Merge branch 'master' into jbrill-msvc-detect

Manually resolve conflicts:
* RELEASE.txt

Author: jcbrill

CHANGES.txt

@@ -118,6 +118,13 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       old Python 2-only code block in a test.
     - scons-time tests now supply a "filter" argument to tarfile.extract
       to quiet a warning which was added in Python 3.13 beta 1.
+    - 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

@@ -58,6 +58,9 @@ FIXES
 -----
 
 - OSErrors are now no longer hidden during the execution of Actions.
+- Improved the conversion of a "foreign" exception from an action
+  into BuildError by making sure our defaults get applied even in
+  corner cases. Fixes Issue #4530
 - MSVC: Visual Studio 2010 (10.0) could be inadvertently detected due to an
   sdk-only install of Windows SDK 7.1.  An sdk-only install of Visual Studio
   2010 is ignored as the msvc batch files will fail. The installed files are
@@ -118,6 +121,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/Errors.py

@@ -177,8 +177,12 @@ def convert_to_BuildError(status, exc_info=None):
         # (for example, failure to create the directory in which the
         # target file will appear).
         filename = getattr(status, 'filename', None)
-        strerror = getattr(status, 'strerror', str(status))
-        errno = getattr(status, 'errno', 2)
+        strerror = getattr(status, 'strerror', None)
+        if strerror is None:
+            strerror = str(status)
+        errno = getattr(status, 'errno', None)
+        if errno is None:
+            errno = 2
 
         buildError = BuildError(
             errstr=strerror,

SCons/ErrorsTests.py

@@ -46,7 +46,7 @@ def test_BuildError(self):
             assert e.command == "c"
 
         try:
-            raise SCons.Errors.BuildError("n", "foo", 57, 3, "file", 
+            raise SCons.Errors.BuildError("n", "foo", 57, 3, "file",
                                           "e", "a", "c", (1,2,3))
         except SCons.Errors.BuildError as e:
             assert e.errstr == "foo", e.errstr
@@ -96,26 +96,48 @@ def test_ExplicitExit(self):
             assert e.node == "node"
 
     def test_convert_EnvironmentError_to_BuildError(self) -> None:
-        """Test the convert_to_BuildError function on SConsEnvironmentError
-        exceptions.
-        """
+        """Test convert_to_BuildError on SConsEnvironmentError."""
         ee = SCons.Errors.SConsEnvironmentError("test env error")
         be = SCons.Errors.convert_to_BuildError(ee)
-        assert be.errstr == "test env error"
-        assert be.status == 2
-        assert be.exitstatus == 2
-        assert be.filename is None
+        with self.subTest():
+            self.assertEqual(be.errstr, "test env error")
+        with self.subTest():
+            self.assertEqual(be.status, 2)
+        with self.subTest():
+            self.assertEqual(be.exitstatus, 2)
+        with self.subTest():
+            self.assertIsNone(be.filename)
 
     def test_convert_OSError_to_BuildError(self) -> None:
-        """Test the convert_to_BuildError function on OSError
-        exceptions.
-        """
+        """Test convert_to_BuildError on OSError."""
         ose = OSError(7, 'test oserror')
         be = SCons.Errors.convert_to_BuildError(ose)
-        assert be.errstr == 'test oserror'
-        assert be.status == 7
-        assert be.exitstatus == 2
-        assert be.filename is None
+        with self.subTest():
+            self.assertEqual(be.errstr, 'test oserror')
+        with self.subTest():
+            self.assertEqual(be.status, 7)
+        with self.subTest():
+            self.assertEqual(be.exitstatus, 2)
+        with self.subTest():
+            self.assertIsNone(be.filename)
+
+    def test_convert_phony_OSError_to_BuildError(self) -> None:
+        """Test convert_to_BuildError on OSError with defaults."""
+        class PhonyException(OSError):
+            def __init__(self, name):
+                OSError.__init__(self, name)  # most fields will default to None
+                self.name = name
+
+        ose = PhonyException("test oserror")
+        be = SCons.Errors.convert_to_BuildError(ose)
+        with self.subTest():
+            self.assertEqual(be.errstr, 'test oserror')
+        with self.subTest():
+            self.assertEqual(be.status, 2)
+        with self.subTest():
+            self.assertEqual(be.exitstatus, 2)
+        with self.subTest():
+            self.assertIsNone(be.filename)
 
 
 if __name__ == "__main__":

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: