Merge branch 'master' into exception-convert

Author: bdbaddog

CHANGES.txt

@@ -66,6 +66,10 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Improved the conversion of a "foreign" exception from an action
       into BuildError by making sure our defaults get applied even in
       corner cases. Fixes #4530.
+    - Restructured API docs build (Sphinx) so main module contents appear
+      on a given page *before* the submodule docs, not after. Also
+      tweaked the Util package doc build so it's structured more like the
+      other packages (a missed part of the transition when it was split).
 
 
 RELEASE 4.7.0 -  Sun, 17 Mar 2024 17:22:20 -0700

RELEASE.txt

@@ -72,6 +72,8 @@ DOCUMENTATION
 - Updated Value Node docs.
 - Update manpage for Tools, and for the TOOL variable.
 - Update manpage and user guide for Variables usage.
+- Restructured API Docs build so main package contents are listed
+  before contents of package submodules.
 
 
 

SCons/Debug.py

@@ -23,10 +23,10 @@
 
 """Code for debugging SCons internal things.
 
-Shouldn't be needed by most users. Quick shortcuts:
+Shouldn't be needed by most users. Quick shortcuts::
 
-from SCons.Debug import caller_trace
-caller_trace()
+    from SCons.Debug import caller_trace
+    caller_trace()
 """
 
 import atexit

SCons/PathList.py

@@ -23,7 +23,7 @@
 
 """Handle lists of directory paths.
 
-These are the path lists that get set as CPPPATH, LIBPATH,
+These are the path lists that get set as ``CPPPATH``, ``LIBPATH``,
 etc.) with as much caching of data and efficiency as we can, while
 still keeping the evaluation delayed so that we Do the Right Thing
 (almost) regardless of how the variable is specified.
@@ -47,10 +47,10 @@ def node_conv(obj):
     """
     This is the "string conversion" routine that we have our substitutions
     use to return Nodes, not strings.  This relies on the fact that an
-    EntryProxy object has a get() method that returns the underlying
-    Node that it wraps, which is a bit of architectural dependence
-    that we might need to break or modify in the future in response to
-    additional requirements.
+    :class:`~SCons.Node.FS.EntryProxy` object has a ``get()`` method that
+    returns the underlying Node that it wraps, which is a bit of
+    architectural dependence that we might need to break or modify in the
+    future in response to additional requirements.
     """
     try:
         get = obj.get
@@ -64,34 +64,35 @@ def node_conv(obj):
     return result
 
 class _PathList:
-    """An actual PathList object."""
+    """An actual PathList object.
 
-    def __init__(self, pathlist, split=True) -> None:
-        """
-        Initializes a PathList object, canonicalizing the input and
-        pre-processing it for quicker substitution later.
+    Initializes a :class:`PathList` object, canonicalizing the input and
+    pre-processing it for quicker substitution later.
 
-        The stored representation of the PathList is a list of tuples
-        containing (type, value), where the "type" is one of the TYPE_*
-        variables defined above.  We distinguish between:
+    The stored representation of the :class:`PathList` is a list of tuples
+    containing (type, value), where the "type" is one of the ``TYPE_*``
+    variables defined above.  We distinguish between:
 
-            strings that contain no '$' and therefore need no
-            delayed-evaluation string substitution (we expect that there
-            will be many of these and that we therefore get a pretty
-            big win from avoiding string substitution)
+    *   Strings that contain no ``$`` and therefore need no
+        delayed-evaluation string substitution (we expect that there
+        will be many of these and that we therefore get a pretty
+        big win from avoiding string substitution)
 
-            strings that contain '$' and therefore need substitution
-            (the hard case is things like '${TARGET.dir}/include',
-            which require re-evaluation for every target + source)
+    *   Strings that contain ``$`` and therefore need substitution
+        (the hard case is things like ``${TARGET.dir}/include``,
+        which require re-evaluation for every target + source)
 
-            other objects (which may be something like an EntryProxy
-            that needs a method called to return a Node)
+    *   Other objects (which may be something like an
+        :class:`~SCons.Node.FS.EntryProxy`
+        that needs a method called to return a Node)
 
-        Pre-identifying the type of each element in the PathList up-front
-        and storing the type in the list of tuples is intended to reduce
-        the amount of calculation when we actually do the substitution
-        over and over for each target.
-        """
+    Pre-identifying the type of each element in the :class:`PathList`
+    up-front and storing the type in the list of tuples is intended to
+    reduce the amount of calculation when we actually do the substitution
+    over and over for each target.
+    """
+
+    def __init__(self, pathlist, split=True) -> None:
         if SCons.Util.is_String(pathlist):
             if split:
                 pathlist = pathlist.split(os.pathsep)
@@ -152,34 +153,33 @@ class PathListCache:
     use the same Memoizer pattern that we use elsewhere to count cache
     hits and misses, which is very valuable.
 
-    Lookup keys in the cache are computed by the _PathList_key() method.
+    Lookup keys in the cache are computed by the :meth:`_PathList_key` method.
     Cache lookup should be quick, so we don't spend cycles canonicalizing
-    all forms of the same lookup key.  For example, 'x:y' and ['x',
-    'y'] logically represent the same list, but we don't bother to
+    all forms of the same lookup key.  For example, ``x:y`` and ``['x', 'y']``
+    logically represent the same list, but we don't bother to
     split string representations and treat those two equivalently.
     (Note, however, that we do, treat lists and tuples the same.)
 
     The main type of duplication we're trying to catch will come from
     looking up the same path list from two different clones of the
-    same construction environment.  That is, given
+    same construction environment.  That is, given::
 
         env2 = env1.Clone()
 
-    both env1 and env2 will have the same CPPPATH value, and we can
-    cheaply avoid re-parsing both values of CPPPATH by using the
+    both ``env1`` and ``env2`` will have the same ``CPPPATH`` value, and we can
+    cheaply avoid re-parsing both values of ``CPPPATH`` by using the
     common value from this cache.
     """
     def __init__(self) -> None:
         self._memo = {}
 
     def _PathList_key(self, pathlist):
-        """
-        Returns the key for memoization of PathLists.
+        """Returns the key for memoization of PathLists.
 
         Note that we want this to be pretty quick, so we don't completely
         canonicalize all forms of the same list.  For example,
-        'dir1:$ROOT/dir2' and ['$ROOT/dir1', 'dir'] may logically
-        represent the same list if you're executing from $ROOT, but
+        ``dir1:$ROOT/dir2`` and ``['$ROOT/dir1', 'dir']`` may logically
+        represent the same list if you're executing from ``$ROOT``, but
         we're not going to bother splitting strings into path elements,
         or massaging strings into Nodes, to identify that equivalence.
         We just want to eliminate obvious redundancy from the normal
@@ -191,9 +191,10 @@ def _PathList_key(self, pathlist):
 
     @SCons.Memoize.CountDictCall(_PathList_key)
     def PathList(self, pathlist, split=True):
-        """
-        Returns the cached _PathList object for the specified pathlist,
-        creating and caching a new object as necessary.
+        """Entry point for getting PathLists.
+
+        Returns the cached :class:`_PathList` object for the specified
+        pathlist, creating and caching a new object as necessary.
         """
         pathlist = self._PathList_key(pathlist)
         try:
@@ -215,7 +216,8 @@ def PathList(self, pathlist, split=True):
 
 PathList = PathListCache().PathList
 
-
+# TODO: removing the class object here means Sphinx doesn't pick up its
+#   docstrings: they're fine for reading here, but are not in API Docs.
 del PathListCache
 
 # Local Variables:

SCons/Variables/ListVariable.py

@@ -21,10 +21,10 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-"""Variable type for list Variables.
+"""Variable type for List Variables.
 
-A 'list' option may either be 'all', 'none' or a list of names
-separated by comma. After the option has been processed, the option
+A list variable may given as 'all', 'none' or a list of names
+separated by comma. After the variable has been processed, the variable
 value holds either the named list elements, all list elements or no
 list elements at all.
 
@@ -41,7 +41,7 @@
             elems=list_of_libs,
         )
     )
-    ...
+    env = Environment(variables=opts)
     for lib in list_of_libs:
         if lib in env['shared']:
             env.SharedObject(...)
@@ -53,14 +53,21 @@
 # since elements can occur twice.
 
 import collections
-from typing import Tuple, Callable
+from typing import Callable, List, Optional, Tuple, Union
 
 import SCons.Util
 
 __all__ = ['ListVariable',]
 
 
 class _ListVariable(collections.UserList):
+    """Internal class holding the data for a List Variable.
+
+    The initializer accepts two arguments, the list of actual values
+    given, and the list of allowable values. Not normally instantiated
+    by hand, but rather by the ListVariable converter function.
+    """
+
     def __init__(self, initlist=None, allowedElems=None) -> None:
         if initlist is None:
             initlist = []
@@ -88,19 +95,18 @@ def __lt__(self, other):
         return NotImplemented
 
     def __str__(self) -> str:
-        if not len(self):
+        if not self.data:
             return 'none'
         self.data.sort()
         if self.data == self.allowedElems:
             return 'all'
-        else:
-            return ','.join(self)
+        return ','.join(self)
 
     def prepare_to_store(self):
-        return self.__str__()
+        return str(self)
 
 def _converter(val, allowedElems, mapdict) -> _ListVariable:
-    """ """
+    """Convert list variables."""
     if val == 'none':
         val = []
     elif val == 'all':
@@ -111,39 +117,57 @@ def _converter(val, allowedElems, mapdict) -> _ListVariable:
         notAllowed = [v for v in val if v not in allowedElems]
         if notAllowed:
             raise ValueError(
-                "Invalid value(s) for option: %s" % ','.join(notAllowed)
+                f"Invalid value(s) for option: {','.join(notAllowed)}"
             )
     return _ListVariable(val, allowedElems)
 
 
 # def _validator(key, val, env) -> None:
 #     """ """
-#     # TODO: write validator for pgk list
+#     # TODO: write validator for list variable
 #     pass
 
 
-def ListVariable(key, help, default, names, map={}) -> Tuple[str, str, str, None, Callable]:
-    """Return a tuple describing a list SCons Variable.
-
-    The input parameters describe a 'list' option. Returns
-    a tuple including the correct converter and validator.
-    The result is usable for input to :meth:`Add`.
-
-    *help* will have text appended indicating the legal values
-    (not including any extra names from *map*).
-
-    *map* can be used to map alternative names to the ones in *names* -
-    that is, a form of alias.
-
-    A 'list' option may either be 'all', 'none' or a list of
-    names (separated by commas).
+# lint: W0622: Redefining built-in 'help' (redefined-builtin)
+# lint: W0622: Redefining built-in 'map' (redefined-builtin)
+def ListVariable(
+    key,
+    help: str,
+    default: Union[str, List[str]],
+    names: List[str],
+    map: Optional[dict] = None,
+) -> Tuple[str, str, str, None, Callable]:
+    """Return a tuple describing a list variable.
+
+    The input parameters describe a list variable, where the values
+    can be one or more from *names* plus the special values ``all``
+    and ``none``.
+
+    Arguments:
+       key: the name of the list variable.
+       help: the basic help message.  Will have text appended indicating
+          the allowable values (not including any extra names from *map*).
+       default: the default value(s) for the list variable. Can be
+          given as string (possibly comma-separated), or as a list of strings.
+          ``all`` or ``none`` are allowed as *default*.
+       names: the allowable values. Must be a list of strings.
+       map: optional dictionary to map alternative names to the ones in
+          *names*, providing a form of alias. The converter will make
+          the replacement, names from *map* are not stored and will
+          not appear in the help message.
+
+    Returns:
+       A tuple including the correct converter and validator.  The
+       result is usable as input to :meth:`~SCons.Variables.Variables.Add`.
     """
-    names_str = 'allowed names: %s' % ' '.join(names)
+    if map is None:
+        map = {}
+    names_str = f"allowed names: {' '.join(names)}"
     if SCons.Util.is_List(default):
         default = ','.join(default)
     help = '\n    '.join(
         (help, '(all|none|comma-separated list of names)', names_str))
-    return (key, help, default, None, lambda val: _converter(val, names, map))
+    return key, help, default, None, lambda val: _converter(val, names, map)
 
 # Local Variables:
 # tab-width:4

SCons/Variables/ListVariableTests.py

@@ -101,12 +101,8 @@ def test_converter(self) -> None:
         x = o.converter('three,ONE,TWO')
         assert str(x) == 'all', x
 
-        caught = None
-        try:
+        with self.assertRaises(ValueError):
             x = o.converter('no_match')
-        except ValueError:
-            caught = 1
-        assert caught, "did not catch expected ValueError"
 
     def test_copy(self) -> None:
         """Test copying a ListVariable like an Environment would"""

doc/sphinx/SCons.Node.rst

@@ -1,6 +1,15 @@
 SCons.Node package
 ==================
 
+Module contents
+---------------
+
+.. automodule:: SCons.Node
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 Submodules
 ----------
 
@@ -27,12 +36,3 @@ SCons.Node.Python module
     :members:
     :undoc-members:
     :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: SCons.Node
-    :members:
-    :undoc-members:
-    :show-inheritance: