Implement framework for hinting complex types

• Showcase potential with `ExecutorType`

Author: Repiteo

CHANGES.txt

@@ -43,6 +43,10 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       method so that the generated function argument list matches the function's
       prototype when including a header file.
 
+  From Thaddeus Crews:
+    - Implemented SCons.Util.sctyping as a safe means of hinting complex types. Currently
+      only implemented for `Executor` as a proof-of-concept.
+
   From William Deegan:
     - Fix sphinx config to handle SCons versions with post such as: 4.6.0.post1
 
@@ -1402,12 +1406,12 @@ RELEASE 3.1.0 - Mon, 20 Jul 2019 16:59:23 -0700
       scons: rebuilding `file3' because:
            the dependency order changed:
            ->Sources
-           Old:xxx	New:zzz
-           Old:yyy	New:yyy
-           Old:zzz	New:xxx
+           Old:xxx  New:zzz
+           Old:yyy  New:yyy
+           Old:zzz  New:xxx
            ->Depends
            ->Implicit
-           Old:/usr/bin/python	New:/usr/bin/python
+           Old:/usr/bin/python  New:/usr/bin/python
     - Fix Issue #3350 - SCons Exception EnvironmentError is conflicting with Python's EnvironmentError.
     - Fix spurious rebuilds on second build for cases where builder has > 1 target and the source file
       is generated. This was causing the > 1th target to not have it's implicit list cleared when the source

RELEASE.txt

@@ -72,6 +72,8 @@ DEVELOPMENT
 -----------
 
 - Fix sphinx config to handle SCons versions with post such as: 4.6.0.post1
+- Created SCons.Util.sctyping to contain complex type information, allowing
+  for repo-wide type hinting without causing cyclical dependencies.
 
 Thanks to the following contributors listed below for their contributions to this release.
 ==========================================================================================

SCons/Action.py

@@ -109,6 +109,7 @@
 from abc import ABC, abstractmethod
 from collections import OrderedDict
 from subprocess import DEVNULL, PIPE
+from typing import Optional
 
 import SCons.Debug
 import SCons.Errors
@@ -119,6 +120,7 @@
 from SCons.Debug import logInstanceCreation
 from SCons.Subst import SUBST_SIG, SUBST_RAW
 from SCons.Util import is_String, is_List
+from SCons.Util.sctyping import ExecutorType
 
 class _null:
     pass
@@ -530,7 +532,7 @@ def __call__(
         show=_null,
         execute=_null,
         chdir=_null,
-        executor=None,
+        executor: Optional[ExecutorType] = None,
     ):
         raise NotImplementedError
 
@@ -542,15 +544,15 @@ def no_batch_key(self, env, target, source):
 
     batch_key = no_batch_key
 
-    def genstring(self, target, source, env, executor=None) -> str:
+    def genstring(self, target, source, env, executor: Optional[ExecutorType] = None) -> str:
         return str(self)
 
     @abstractmethod
-    def get_presig(self, target, source, env, executor=None):
+    def get_presig(self, target, source, env, executor: Optional[ExecutorType] = None):
         raise NotImplementedError
 
     @abstractmethod
-    def get_implicit_deps(self, target, source, env, executor=None):
+    def get_implicit_deps(self, target, source, env, executor: Optional[ExecutorType] = None):
         raise NotImplementedError
 
     def get_contents(self, target, source, env):
@@ -602,10 +604,10 @@ def presub_lines(self, env):
         self.presub_env = None      # don't need this any more
         return lines
 
-    def get_varlist(self, target, source, env, executor=None):
+    def get_varlist(self, target, source, env, executor: Optional[ExecutorType] = None):
         return self.varlist
 
-    def get_targets(self, env, executor):
+    def get_targets(self, env, executor: Optional[ExecutorType]):
         """
         Returns the type of targets ($TARGETS, $CHANGED_TARGETS) used
         by this action.
@@ -659,7 +661,7 @@ def __call__(self, target, source, env,
                                show=_null,
                                execute=_null,
                                chdir=_null,
-                               executor=None):
+                               executor: Optional[ExecutorType] = None):
         if not is_List(target):
             target = [target]
         if not is_List(source):
@@ -743,10 +745,10 @@ def __call__(self, target, source, env,
     # an ABC like parent ActionBase, but things reach in and use it. It's
     # not just unittests or we could fix it up with a concrete subclass there.
 
-    def get_presig(self, target, source, env, executor=None):
+    def get_presig(self, target, source, env, executor: Optional[ExecutorType] = None):
         raise NotImplementedError
 
-    def get_implicit_deps(self, target, source, env, executor=None):
+    def get_implicit_deps(self, target, source, env, executor: Optional[ExecutorType] = None):
         raise NotImplementedError
 
 
@@ -1010,7 +1012,7 @@ def __str__(self) -> str:
             return ' '.join(map(str, self.cmd_list))
         return str(self.cmd_list)
 
-    def process(self, target, source, env, executor=None, overrides: bool=False):
+    def process(self, target, source, env, executor: Optional[ExecutorType] = None, overrides: bool=False):
         if executor:
             result = env.subst_list(self.cmd_list, 0, executor=executor, overrides=overrides)
         else:
@@ -1031,7 +1033,7 @@ def process(self, target, source, env, executor=None, overrides: bool=False):
             pass
         return result, ignore, silent
 
-    def strfunction(self, target, source, env, executor=None, overrides: bool=False):
+    def strfunction(self, target, source, env, executor: Optional[ExecutorType] = None, overrides: bool=False):
         if self.cmdstr is None:
             return None
         if self.cmdstr is not _null:
@@ -1046,7 +1048,7 @@ def strfunction(self, target, source, env, executor=None, overrides: bool=False)
             return ''
         return _string_from_cmd_list(cmd_list[0])
 
-    def execute(self, target, source, env, executor=None):
+    def execute(self, target, source, env, executor: Optional[ExecutorType] = None):
         """Execute a command action.
 
         This will handle lists of commands as well as individual commands,
@@ -1108,7 +1110,7 @@ def execute(self, target, source, env, executor=None):
                                                command=cmd_line)
         return 0
 
-    def get_presig(self, target, source, env, executor=None):
+    def get_presig(self, target, source, env, executor: Optional[ExecutorType] = None):
         """Return the signature contents of this action's command line.
 
         This strips $(-$) and everything in between the string,
@@ -1123,7 +1125,7 @@ def get_presig(self, target, source, env, executor=None):
             return env.subst_target_source(cmd, SUBST_SIG, executor=executor)
         return env.subst_target_source(cmd, SUBST_SIG, target, source)
 
-    def get_implicit_deps(self, target, source, env, executor=None):
+    def get_implicit_deps(self, target, source, env, executor: Optional[ExecutorType] = None):
         """Return the implicit dependencies of this action's command line."""
         icd = env.get('IMPLICIT_COMMAND_DEPENDENCIES', True)
         if is_String(icd) and icd[:1] == '$':
@@ -1145,7 +1147,7 @@ def get_implicit_deps(self, target, source, env, executor=None):
         # lightweight dependency scanning.
         return self._get_implicit_deps_lightweight(target, source, env, executor)
 
-    def _get_implicit_deps_lightweight(self, target, source, env, executor):
+    def _get_implicit_deps_lightweight(self, target, source, env, executor: Optional[ExecutorType]):
         """
         Lightweight dependency scanning involves only scanning the first entry
         in an action string, even if it contains &&.
@@ -1166,7 +1168,7 @@ def _get_implicit_deps_lightweight(self, target, source, env, executor):
                     res.append(env.fs.File(d))
         return res
 
-    def _get_implicit_deps_heavyweight(self, target, source, env, executor,
+    def _get_implicit_deps_heavyweight(self, target, source, env, executor: Optional[ExecutorType],
                                        icd_int):
         """
         Heavyweight dependency scanning involves scanning more than just the
@@ -1234,7 +1236,7 @@ def __init__(self, generator, kw) -> None:
         self.varlist = kw.get('varlist', ())
         self.targets = kw.get('targets', '$TARGETS')
 
-    def _generate(self, target, source, env, for_signature, executor=None):
+    def _generate(self, target, source, env, for_signature, executor: Optional[ExecutorType] = None):
         # ensure that target is a list, to make it easier to write
         # generator functions:
         if not is_List(target):
@@ -1265,11 +1267,11 @@ def __str__(self) -> str:
     def batch_key(self, env, target, source):
         return self._generate(target, source, env, 1).batch_key(env, target, source)
 
-    def genstring(self, target, source, env, executor=None) -> str:
+    def genstring(self, target, source, env, executor: Optional[ExecutorType] = None) -> str:
         return self._generate(target, source, env, 1, executor).genstring(target, source, env)
 
     def __call__(self, target, source, env, exitstatfunc=_null, presub=_null,
-                 show=_null, execute=_null, chdir=_null, executor=None):
+                 show=_null, execute=_null, chdir=_null, executor: Optional[ExecutorType] = None):
         act = self._generate(target, source, env, 0, executor)
         if act is None:
             raise SCons.Errors.UserError(
@@ -1281,21 +1283,21 @@ def __call__(self, target, source, env, exitstatfunc=_null, presub=_null,
             target, source, env, exitstatfunc, presub, show, execute, chdir, executor
         )
 
-    def get_presig(self, target, source, env, executor=None):
+    def get_presig(self, target, source, env, executor: Optional[ExecutorType] = None):
         """Return the signature contents of this action's command line.
 
         This strips $(-$) and everything in between the string,
         since those parts don't affect signatures.
         """
         return self._generate(target, source, env, 1, executor).get_presig(target, source, env)
 
-    def get_implicit_deps(self, target, source, env, executor=None):
+    def get_implicit_deps(self, target, source, env, executor: Optional[ExecutorType] = None):
         return self._generate(target, source, env, 1, executor).get_implicit_deps(target, source, env)
 
-    def get_varlist(self, target, source, env, executor=None):
+    def get_varlist(self, target, source, env, executor: Optional[ExecutorType] = None):
         return self._generate(target, source, env, 1, executor).get_varlist(target, source, env, executor)
 
-    def get_targets(self, env, executor):
+    def get_targets(self, env, executor: Optional[ExecutorType]):
         return self._generate(None, None, env, 1, executor).get_targets(env, executor)
 
 
@@ -1341,22 +1343,22 @@ def _generate_cache(self, env):
             raise SCons.Errors.UserError("$%s value %s cannot be used to create an Action." % (self.var, repr(c)))
         return gen_cmd
 
-    def _generate(self, target, source, env, for_signature, executor=None):
+    def _generate(self, target, source, env, for_signature, executor: Optional[ExecutorType] = None):
         return self._generate_cache(env)
 
     def __call__(self, target, source, env, *args, **kw):
         c = self.get_parent_class(env)
         return c.__call__(self, target, source, env, *args, **kw)
 
-    def get_presig(self, target, source, env, executor=None):
+    def get_presig(self, target, source, env, executor: Optional[ExecutorType] = None):
         c = self.get_parent_class(env)
         return c.get_presig(self, target, source, env)
 
-    def get_implicit_deps(self, target, source, env, executor=None):
+    def get_implicit_deps(self, target, source, env, executor: Optional[ExecutorType] = None):
         c = self.get_parent_class(env)
         return c.get_implicit_deps(self, target, source, env)
 
-    def get_varlist(self, target, source, env, executor=None):
+    def get_varlist(self, target, source, env, executor: Optional[ExecutorType] = None):
         c = self.get_parent_class(env)
         return c.get_varlist(self, target, source, env, executor)
 
@@ -1389,7 +1391,7 @@ def function_name(self):
             except AttributeError:
                 return "unknown_python_function"
 
-    def strfunction(self, target, source, env, executor=None):
+    def strfunction(self, target, source, env, executor: Optional[ExecutorType] = None):
         if self.cmdstr is None:
             return None
         if self.cmdstr is not _null:
@@ -1430,7 +1432,7 @@ def __str__(self) -> str:
             return str(self.execfunction)
         return "%s(target, source, env)" % name
 
-    def execute(self, target, source, env, executor=None):
+    def execute(self, target, source, env, executor: Optional[ExecutorType] = None):
         exc_info = (None,None,None)
         try:
             if executor:
@@ -1471,14 +1473,14 @@ def execute(self, target, source, env, executor=None):
             # more information about this issue.
             del exc_info
 
-    def get_presig(self, target, source, env, executor=None):
+    def get_presig(self, target, source, env, executor: Optional[ExecutorType] = None):
         """Return the signature contents of this callable action."""
         try:
             return self.gc(target, source, env)
         except AttributeError:
             return self.funccontents
 
-    def get_implicit_deps(self, target, source, env, executor=None):
+    def get_implicit_deps(self, target, source, env, executor: Optional[ExecutorType] = None):
         return []
 
 class ListAction(ActionBase):
@@ -1495,7 +1497,7 @@ def list_of_actions(x):
         self.varlist = ()
         self.targets = '$TARGETS'
 
-    def genstring(self, target, source, env, executor=None) -> str:
+    def genstring(self, target, source, env, executor: Optional[ExecutorType] = None) -> str:
         return '\n'.join([a.genstring(target, source, env) for a in self.list])
 
     def __str__(self) -> str:
@@ -1505,15 +1507,15 @@ def presub_lines(self, env):
         return SCons.Util.flatten_sequence(
             [a.presub_lines(env) for a in self.list])
 
-    def get_presig(self, target, source, env, executor=None):
+    def get_presig(self, target, source, env, executor: Optional[ExecutorType] = None):
         """Return the signature contents of this action list.
 
         Simple concatenation of the signatures of the elements.
         """
         return b"".join([bytes(x.get_contents(target, source, env)) for x in self.list])
 
     def __call__(self, target, source, env, exitstatfunc=_null, presub=_null,
-                 show=_null, execute=_null, chdir=_null, executor=None):
+                 show=_null, execute=_null, chdir=_null, executor: Optional[ExecutorType] = None):
         if executor:
             target = executor.get_all_targets()
             source = executor.get_all_sources()
@@ -1524,13 +1526,13 @@ def __call__(self, target, source, env, exitstatfunc=_null, presub=_null,
                 return stat
         return 0
 
-    def get_implicit_deps(self, target, source, env, executor=None):
+    def get_implicit_deps(self, target, source, env, executor: Optional[ExecutorType] = None):
         result = []
         for act in self.list:
             result.extend(act.get_implicit_deps(target, source, env))
         return result
 
-    def get_varlist(self, target, source, env, executor=None):
+    def get_varlist(self, target, source, env, executor: Optional[ExecutorType] = None):
         result = OrderedDict()
         for act in self.list:
             for var in act.get_varlist(target, source, env, executor):
@@ -1596,7 +1598,7 @@ def subst_kw(self, target, source, env):
             kw[key] = self.subst(self.kw[key], target, source, env)
         return kw
 
-    def __call__(self, target, source, env, executor=None):
+    def __call__(self, target, source, env, executor: Optional[ExecutorType] = None):
         args = self.subst_args(target, source, env)
         kw = self.subst_kw(target, source, env)
         return self.parent.actfunc(*args, **kw)

SCons/ActionTests.py

@@ -43,11 +43,13 @@ def __call__(self) -> None:
 import unittest
 from unittest import mock
 from subprocess import PIPE
+from typing import Optional
 
 import SCons.Action
 import SCons.Environment
 import SCons.Errors
 from SCons.Action import scons_subproc_run
+from SCons.Util.sctyping import ExecutorType
 
 import TestCmd
 
@@ -1699,11 +1701,11 @@ def __call__(self, target, source, env) -> int:
         c = test.read(outfile, 'r')
         assert c == "class1b\n", c
 
-        def build_it(target, source, env, executor=None, self=self) -> int:
+        def build_it(target, source, env, executor: Optional[ExecutorType] = None, self=self) -> int:
             self.build_it = 1
             return 0
 
-        def string_it(target, source, env, executor=None, self=self):
+        def string_it(target, source, env, executor: Optional[ExecutorType] = None, self=self):
             self.string_it = 1
             return None
 

SCons/Builder.py

@@ -102,6 +102,7 @@
 import os
 from collections import UserDict, UserList
 from contextlib import suppress
+from typing import Optional
 
 import SCons.Action
 import SCons.Debug
@@ -111,6 +112,7 @@
 import SCons.Warnings
 from SCons.Debug import logInstanceCreation
 from SCons.Errors import InternalError, UserError
+from SCons.Util.sctyping import ExecutorType
 
 class _Null:
     pass
@@ -589,7 +591,7 @@ def _execute(self, env, target, source, overwarn={}, executor_kw={}):
         # build this particular list of targets from this particular list of
         # sources.
 
-        executor = None
+        executor: Optional[ExecutorType] = None
         key = None
 
         if self.multi: