Implement `GetSConsVersion` static method

9 files changed, 93 insertions, 5 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index e938a74..ee2657b 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -9,6 +9,10 @@ NOTE: 4.3.0 now requires Python 3.6.0 and above. Python 3.5.x is no longer suppo
 
 RELEASE  VERSION/DATE TO BE FILLED IN LATER
 
+  From Thaddeus Crews:
+    - GetSConsVersion() to grab the latest SCons version without needing to
+      dig into private functions.
+
   From Raymond Li:
     - Fix issue #3935: OSErrors are now no longer hidden during execution of
       Actions. All exceptions during the execution of an Action are now
diff --git a/RELEASE.txt b/RELEASE.txt
index 12d4b07..6502880 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -16,7 +16,7 @@ Here is a summary of the changes since 4.7.0:
 NEW FUNCTIONALITY
 -----------------
 
-- List new features (presumably why a checkpoint is being released)
+- GetSConsVersion() to grab the current SCons version from an exposed api.
 
 DEPRECATED FUNCTIONALITY
 ------------------------
diff --git a/SCons/Script/SConscript.py b/SCons/Script/SConscript.py
index 85070ab..a2ef3b9 100644
--- a/SCons/Script/SConscript.py
+++ b/SCons/Script/SConscript.py
@@ -45,6 +45,7 @@ import re
 import sys
 import traceback
 import time
+from typing import Tuple
 
 class SConscriptReturn(Exception):
     pass
@@ -385,7 +386,7 @@ class SConsEnvironment(SCons.Environment.Base):
     # Private methods of an SConsEnvironment.
     #
     @staticmethod
-    def _get_major_minor_revision(version_string):
+    def _get_major_minor_revision(version_string: str) -> Tuple[int, int, int]:
         """Split a version string into major, minor and (optionally)
         revision parts.
 
@@ -484,15 +485,22 @@ class SConsEnvironment(SCons.Environment.Base):
         SCons.Script._Set_Default_Targets(self, targets)
 
     @staticmethod
-    def EnsureSConsVersion(major, minor, revision: int=0) -> None:
+    def GetSConsVersion() -> Tuple[int, int, int]:
+        """Return the current SCons version.
+
+        .. versionadded:: 4.8.0
+        """
+        return SConsEnvironment._get_major_minor_revision(SCons.__version__)
+
+    @staticmethod
+    def EnsureSConsVersion(major: int, minor: int, revision: int = 0) -> None:
         """Exit abnormally if the SCons version is not late enough."""
         # split string to avoid replacement during build process
         if SCons.__version__ == '__' + 'VERSION__':
             SCons.Warnings.warn(SCons.Warnings.DevelopmentVersionWarning,
                 "EnsureSConsVersion is ignored for development version")
             return
-        scons_ver = SConsEnvironment._get_major_minor_revision(SCons.__version__)
-        if scons_ver < (major, minor, revision):
+        if SConsEnvironment.GetSConsVersion() < (major, minor, revision):
             if revision:
                 scons_ver_string = '%d.%d.%d' % (major, minor, revision)
             else:
diff --git a/SCons/Script/SConscript.xml b/SCons/Script/SConscript.xml
index 3c72994..2298490 100644
--- a/SCons/Script/SConscript.xml
+++ b/SCons/Script/SConscript.xml
@@ -136,6 +136,18 @@ EnsureSConsVersion(0,96,90)
 </summary>
 </scons_function>
 
+<scons_function name="GetSConsVersion">
+<arguments signature="global">
+()
+</arguments>
+<summary>
+<para>
+Returns the current SCons version in the form of a Tuple[int, int, int],
+representing the major, minor, and revision values respectively.
+</para>
+</summary>
+</scons_function>
+
 <scons_function name="Exit">
 <arguments signature="global">
 ([value])
diff --git a/SCons/Script/__init__.py b/SCons/Script/__init__.py
index a62650f..ce01055 100644
--- a/SCons/Script/__init__.py
+++ b/SCons/Script/__init__.py
@@ -297,6 +297,7 @@ def Variables(files=None, args=ARGUMENTS):
 #
 # Static functions that do not trigger initialization of
 # DefaultEnvironment() and don't use its state.
+GetSConsVersion = _SConscript.SConsEnvironment.GetSConsVersion
 EnsureSConsVersion = _SConscript.SConsEnvironment.EnsureSConsVersion
 EnsurePythonVersion = _SConscript.SConsEnvironment.EnsurePythonVersion
 Exit = _SConscript.SConsEnvironment.Exit
diff --git a/doc/generated/functions.mod b/doc/generated/functions.mod
index 7273aab..0fb4a35 100644
--- a/doc/generated/functions.mod
+++ b/doc/generated/functions.mod
@@ -50,6 +50,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY f-GetBuildPath "<function xmlns='http://www.scons.org/dbxsd/v1.0'>GetBuildPath</function>">
 <!ENTITY f-GetLaunchDir "<function xmlns='http://www.scons.org/dbxsd/v1.0'>GetLaunchDir</function>">
 <!ENTITY f-GetOption "<function xmlns='http://www.scons.org/dbxsd/v1.0'>GetOption</function>">
+<!ENTITY f-GetSConsVersion "<function xmlns='http://www.scons.org/dbxsd/v1.0'>GetSConsVersion</function>">
 <!ENTITY f-Glob "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Glob</function>">
 <!ENTITY f-Help "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Help</function>">
 <!ENTITY f-Ignore "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Ignore</function>">
@@ -132,6 +133,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY f-env-GetBuildPath "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.GetBuildPath</function>">
 <!ENTITY f-env-GetLaunchDir "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.GetLaunchDir</function>">
 <!ENTITY f-env-GetOption "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.GetOption</function>">
+<!ENTITY f-env-GetSConsVersion "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.GetSConsVersion</function>">
 <!ENTITY f-env-Glob "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Glob</function>">
 <!ENTITY f-env-Help "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Help</function>">
 <!ENTITY f-env-Ignore "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Ignore</function>">
@@ -220,6 +222,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY f-link-GetBuildPath "<link linkend='f-GetBuildPath' xmlns='http://www.scons.org/dbxsd/v1.0'><function>GetBuildPath</function></link>">
 <!ENTITY f-link-GetLaunchDir "<link linkend='f-GetLaunchDir' xmlns='http://www.scons.org/dbxsd/v1.0'><function>GetLaunchDir</function></link>">
 <!ENTITY f-link-GetOption "<link linkend='f-GetOption' xmlns='http://www.scons.org/dbxsd/v1.0'><function>GetOption</function></link>">
+<!ENTITY f-link-GetSConsVersion "<link linkend='f-GetSConsVersion' xmlns='http://www.scons.org/dbxsd/v1.0'><function>GetSConsVersion</function></link>">
 <!ENTITY f-link-Glob "<link linkend='f-Glob' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Glob</function></link>">
 <!ENTITY f-link-Help "<link linkend='f-Help' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Help</function></link>">
 <!ENTITY f-link-Ignore "<link linkend='f-Ignore' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Ignore</function></link>">
@@ -302,6 +305,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY f-link-env-GetBuildPath "<link linkend='f-GetBuildPath' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.GetBuildPath</function></link>">
 <!ENTITY f-link-env-GetLaunchDir "<link linkend='f-GetLaunchDir' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.GetLaunchDir</function></link>">
 <!ENTITY f-link-env-GetOption "<link linkend='f-GetOption' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.GetOption</function></link>">
+<!ENTITY f-link-env-GetSConsVersion "<link linkend='f-GetSConsVersion' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.GetSConsVersion</function></link>">
 <!ENTITY f-link-env-Glob "<link linkend='f-Glob' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Glob</function></link>">
 <!ENTITY f-link-env-Help "<link linkend='f-Help' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Help</function></link>">
 <!ENTITY f-link-env-Ignore "<link linkend='f-Ignore' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Ignore</function></link>">
diff --git a/doc/scons.mod b/doc/scons.mod
index 2288879..fc96aec 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -214,6 +214,7 @@
 <!ENTITY EnumVariable "<function xmlns='http://www.scons.org/dbxsd/v1.0'>EnumVariable</function>">
 <!ENTITY EnsurePythonVersion "<function xmlns='http://www.scons.org/dbxsd/v1.0'>EnsurePythonVersion</function>">
 <!ENTITY EnsureSConsVersion "<function xmlns='http://www.scons.org/dbxsd/v1.0'>EnsureSConsVersion</function>">
+<!ENTITY GetSConsVersion "<function xmlns='http://www.scons.org/dbxsd/v1.0'>GetSConsVersion</function>">
 <!ENTITY Environment "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Environment</function>">
 <!ENTITY Execute "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Execute</function>">
 <!ENTITY Exit "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Exit</function>">
diff --git a/doc/user/misc.xml b/doc/user/misc.xml
index ef2e4ca..33c0157 100644
--- a/doc/user/misc.xml
+++ b/doc/user/misc.xml
@@ -178,6 +178,33 @@ SCons 1.0 or greater required, but you have SCons 0.98.5
   </section>
 
   <section>
+  <title>Grabbing the current SCons Version:  the &GetSConsVersion; Function</title>
+
+    <para>
+
+    While &EnsureSConsVersion; is acceptable for most cases, there
+    are times where the user will want to support multiple SCons versions
+    simultaneously. In this scenario, it's beneficial to retrieve version
+    information of the currently executing SCons directly. This was previously
+    only possible by accessing private class methods, which made the
+    process cumbersome and unintuitive. From 4.8 onwards, it's now possible
+    to instead call &GetSConsVersion; to recieve a tuple containing the
+    major, minor, and revision values of the current version.
+
+    </para>
+
+    <screen>
+if GetSConsVersion() &gt;= (4, 9):
+    # Some function got a new argument in 4.9 that we want to take advantage of
+    SomeFunc(arg1, arg2, arg3)
+else:
+    # Can't use the extended syntax, but it doesn't warrant exiting prematurely
+    SomeFunc(arg1, arg2)
+    </screen>
+
+  </section>
+
+  <section>
   <title>Explicitly Terminating &SCons; While Reading &SConscript; Files:  the &Exit; Function</title>
 
     <para>
diff --git a/test/EnsureSConsVersion.py b/test/EnsureSConsVersion.py
index 7eae2ad..efdc17f 100644
--- a/test/EnsureSConsVersion.py
+++ b/test/EnsureSConsVersion.py
@@ -63,6 +63,23 @@ Exit(0)
 
     test.run(status=2)
 
+    test.write('SConstruct', """\
+env = Environment()
+env.EnsureSConsVersion(*env.GetSConsVersion())
+Exit(0)
+""")
+
+    test.run()
+
+    test.write('SConstruct', """\
+env = Environment()
+ver = env.GetSConsVersion()
+env.EnsureSConsVersion(ver[0], ver[1], ver[2])
+Exit(0)
+""")
+
+    test.run()
+
 
 
 test.write('SConstruct', """\
@@ -121,6 +138,20 @@ EnsureSConsVersion(1,0)
 
 test.run(status=2)
 
+test.write('SConstruct', """\
+import SCons
+EnsureSConsVersion(*GetSConsVersion())
+""")
+
+test.run()
+
+test.write('SConstruct', """\
+import SCons
+ver = GetSConsVersion()
+EnsureSConsVersion(ver[0], ver[1], ver[2])
+""")
+
+test.run()
 
 
 test.pass_test()