Improve env.Dump('json') a bit

When doing a Dump in json mode, custom SCons classes are not examined
by default (unlike the standard pprint() Dump), and end up in the
un-serialized bucket.  Mostly, that's fine, but the BUILDERS dictionary
contains valueable information (which builders actually got configured),
as do the CLVar instances - these contain actual cmdline options that will
be issued.  Update the function called when an object looks unserializable
to recognize subclasses of UserDict (which covers BuilderDict) and
UserList (which covers CLVar) and return their .data field.

Also tell the json encoder to sort the keys.

The adjacent function in the source file got a small tweak (non-functional).

Fixes SCons#4493

Signed-off-by: Mats Wichmann <[email protected]>

Author: mwichmann

CHANGES.txt

@@ -12,6 +12,9 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
   From Mats Wichmann:
 
     - Updated Value Node docs and tests.
+    - Dump() with json format selected now recognizes additional compound types
+      (UserDict and UserList), which improves the detail of the display.
+      json output is also sorted, to match the default display.
 
 
 RELEASE 4.7.0 -  Sun, 17 Mar 2024 17:22:20 -0700

RELEASE.txt

@@ -26,8 +26,9 @@ DEPRECATED FUNCTIONALITY
 CHANGED/ENHANCED EXISTING FUNCTIONALITY
 ---------------------------------------
 
-- List modifications to existing features, where the previous behavior
-  wouldn't actually be considered a bug
+- Dump() with json format selected now recognizes additional compound types
+  (UserDict and UserList), which improves the detail of the display.
+  json output is also sorted, to match the default display.
 
 FIXES
 -----

SCons/Environment.py

@@ -35,9 +35,9 @@
 import sys
 import re
 import shlex
-from collections import UserDict, deque
+from collections import UserDict, UserList, deque
 from subprocess import PIPE, DEVNULL
-from typing import Optional
+from typing import Optional, Sequence
 
 import SCons.Action
 import SCons.Builder
@@ -1687,17 +1687,23 @@ def Dictionary(self, *args):
         return dlist
 
 
-    def Dump(self, key=None, format: str='pretty'):
-        """ Return construction variables serialized to a string.
+    def Dump(self, key: Optional[str] = None, format: str = 'pretty') -> str:
+        """ Returns a dump of serialized construction variables.
+
+        The display formats are intended for humaan readers when
+        debugging - none of the supported formats produce a result that
+        SCons itself can directly make use of. Objects that cannot
+        directly be represented get a placeholder like
+        ``<function foo at 0x123456>`` or ``<<non-serializable: function>>``.
 
         Args:
-          key (optional): if None, format the whole dict of variables.
-            Else format the value of `key` (Default value = None)
-          format (str, optional): specify the format to serialize to.
-            `"pretty"` generates a pretty-printed string,
-            `"json"` a JSON-formatted string.
-            (Default value = `"pretty"`)
+           key: if ``None``, format the whole dict of variables,
+              else format just the value of *key*.
+           format: specify the format to serialize to. ``"pretty"`` generates
+             a pretty-printed string, ``"json"`` a JSON-formatted string.
 
+        Raises:
+           ValueError: *format* is not a recognized serialization format.
         """
         if key:
             cvars = self.Dictionary(key)
@@ -1707,9 +1713,9 @@ def Dump(self, key=None, format: str='pretty'):
         fmt = format.lower()
 
         if fmt == 'pretty':
-            import pprint
-            pp = pprint.PrettyPrinter(indent=2)
+            import pprint  # pylint: disable=import-outside-toplevel
 
+            pp = pprint.PrettyPrinter(indent=2)
             # TODO: pprint doesn't do a nice job on path-style values
             # if the paths contain spaces (i.e. Windows), because the
             # algorithm tries to break lines on spaces, while breaking
@@ -1718,26 +1724,33 @@ def Dump(self, key=None, format: str='pretty'):
             return pp.pformat(cvars)
 
         elif fmt == 'json':
-            import json
-            def non_serializable(obj):
-                return '<<non-serializable: %s>>' % type(obj).__qualname__
-            return json.dumps(cvars, indent=4, default=non_serializable)
+            import json  # pylint: disable=import-outside-toplevel
+
+            class DumpEncoder(json.JSONEncoder):
+                """SCons special json Dump formatter."""
+                def default(self, obj):
+                    if isinstance(obj, (UserList, UserDict)):
+                        return obj.data
+                    return f'<<non-serializable: {type(obj).__qualname__}>>'
+
+            return json.dumps(cvars, indent=4, cls=DumpEncoder, sort_keys=True)
         else:
             raise ValueError("Unsupported serialization format: %s." % fmt)
 
 
-    def FindIxes(self, paths, prefix, suffix):
-        """Search a list of paths for something that matches the prefix and suffix.
+    def FindIxes(self, paths: Sequence[str], prefix: str, suffix: str) -> Optional[str]:
+        """Search *paths* for a path that has *prefix* and *suffix*.
 
-        Args:
-          paths: the list of paths or nodes.
-          prefix: construction variable for the prefix.
-          suffix: construction variable for the suffix.
+        Returns on first match.
 
-        Returns: the matched path or None
+        Arguments:
+           paths: the list of paths or nodes.
+           prefix: construction variable for the prefix.
+           suffix: construction variable for the suffix.
 
+        Returns:
+           The matched path or ``None``
         """
-
         suffix = self.subst('$'+suffix)
         prefix = self.subst('$'+prefix)
 

SCons/EnvironmentTests.py

@@ -3182,7 +3182,8 @@ def test_Dump(self) -> None:
         assert len(env.Dump()) > 200, env.Dump()    # no args version
 
         assert env.Dump('FOO', 'json') == '"foo"'    # JSON key version
-        self.assertEqual(env.Dump('FOOFLAGS', 'json'), '"<<non-serializable: CLVar>>"')
+        expect = """[\n    "--bar",\n    "--baz"\n]"""
+        self.assertEqual(env.Dump('FOOFLAGS', 'json'), expect)
         import json
         env_dict = json.loads(env.Dump(format = 'json'))
         assert env_dict['FOO'] == 'foo'    # full JSON version