Doc and test tweaks for ENVPath functions

Reword AppendENVPath and PrependENVPath manpage entries.

Add more unit tests for the underlying functions,
SCons.Util.AppendPath and SCons.Util.PrependPath

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

Author: mwichmann

CHANGES.txt

@@ -156,6 +156,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Improve the wording of Configure methods.
     - Add unit test cases for AppendUnique, PrependUnique - verify behavior
       if existing value already contained more than one of added value.
+    - Improve thw wording of AppendENVPath and PrependENVPath in manpage.
+    - Add more unit tets to internal AppendPath, PrependPath functions.
 
 
 RELEASE 4.9.1 -  Thu, 27 Mar 2025 11:40:20 -0700

RELEASE.txt

@@ -126,6 +126,8 @@ DOCUMENTATION
 
 - Improve the wording of Configure methods.
 
+- Improve thw wording of AppendENVPath and PrependENVPath in manpage.
+
 DEVELOPMENT
 -----------
 
@@ -176,6 +178,8 @@ DEVELOPMENT
   iterative speedup test from 200 to 250.  Increasing the workload
   should reduce the likelihood that the ninja tests are slower.
 
+- Add more unit tets to internal AppendPath, PrependPath functions.
+
 Thanks to the following contributors listed below for their contributions to this release.
 ==========================================================================================
 .. code-block:: text

SCons/Environment.xml

@@ -778,26 +778,32 @@ See also &f-link-env-AppendUnique;,
 </arguments>
 <summary>
 <para>
-Append path elements specified by <parameter>newpath</parameter>
-to the given search path string or list <parameter>name</parameter>
-in mapping <parameter>envname</parameter> in the &consenv;.
-Supplying <parameter>envname</parameter> is optional:
-the default is the execution environment &cv-link-ENV;.
-Optional <parameter>sep</parameter> is used as the search path separator,
-the default is the platform's separator (<systemitem>os.pathsep</systemitem>).
-A path element will only appear once.
-Any duplicates in <parameter>newpath</parameter> are dropped,
-keeping the last appearing (to preserve path order).
-If <parameter>delete_existing</parameter>
-is <constant>False</constant> (the default)
-any addition duplicating an existing path element is ignored;
-if <parameter>delete_existing</parameter>
-is <constant>True</constant> the existing value will
-be dropped and the path element will be added at the end.
-To help maintain uniqueness all paths are normalized (using
-<systemitem>os.path.normpath</systemitem>
-and
-<systemitem>os.path.normcase</systemitem>).
+Append one or more path prefixes to an entry in a dictionary-valued
+&consvar; in <parameter>env</parameter>.
+The &consvar; to update is <literal>"ENV"</literal>,
+unless <parameter>envname</parameter> is specified.
+The required <parameter>name</parameter> parameter
+gives the dictionary entry to update.
+The prefix(es) in <parameter>newpath</parameter>
+may be specified as a string,
+a directory node, or a list of strings.
+If a string, it may contain multiple prefixes separated
+by the system path separator
+(<systemitem>os.pathsep</systemitem>),
+or, if specified, by the value of <parameter>sep</parameter>.
+Top-relative path strings (starting with <literal>#</literal>) are recognized.
+</para>
+<para>
+Path prefixes will only appear once.
+Duplicate prefixes in <parameter>newpath</parameter> are removed,
+preserving the last occurrence to maintain path order.
+If <parameter>delete_existing</parameter> is true,
+existing duplicates are removed before appending;
+otherwise, new duplicates are skipped
+(the default is false).
+Prefixes are normalized for comparisons to avoid problems of
+"same path, spelled differently",
+but retain their original form in the result.
 </para>
 
 <para>
@@ -1119,8 +1125,8 @@ env4 = env.Clone(tools=['msvc', MyTool])
 The
 <parameter>parse_flags</parameter>
 keyword argument is also recognized, to allow merging command-line
-style arguments into the appropriate construction
-variables (see &f-link-env-MergeFlags;).
+style arguments into the appropriate &consvars;
+(see &f-link-env-MergeFlags;).
 </para>
 
 <example_commands>
@@ -2863,26 +2869,32 @@ and &f-link-env-PrependUnique;.
 </arguments>
 <summary>
 <para>
-Prepend path elements specified by <parameter>newpath</parameter>
-to the given search path string or list <parameter>name</parameter>
-in mapping <parameter>envname</parameter> in the &consenv;.
-Supplying <parameter>envname</parameter> is optional:
-the default is the execution environment &cv-link-ENV;.
-Optional <parameter>sep</parameter> is used as the search path separator,
-the default is the platform's separator (<systemitem>os.pathsep</systemitem>).
-A path element will only appear once.
-Any duplicates in <parameter>newpath</parameter> are dropped,
-keeping the first appearing (to preserve path order).
-If <parameter>delete_existing</parameter>
-is <constant>False</constant>
-any addition duplicating an existing path element is ignored;
-if <parameter>delete_existing</parameter>
-is <constant>True</constant> (the default) the existing value will
-be dropped and the path element will be inserted at the beginning.
-To help maintain uniqueness all paths are normalized (using
-<systemitem>os.path.normpath</systemitem>
-and
-<systemitem>os.path.normcase</systemitem>).
+Prepend one or more path prefixes to an entry in a dictionary-valued
+&consvar; in <parameter>env</parameter>.
+The &consvar; to update is <literal>"ENV"</literal>,
+unless <parameter>envname</parameter> is specified.
+The required <parameter>name</parameter> parameter
+gives the dictionary entry to update.
+The prefix(es) in <parameter>newpath</parameter>
+may be specified as a string,
+a directory node, or a list of strings.
+If a string, it may contain multiple prefixes separated
+by the system path separator
+(<systemitem>os.pathsep</systemitem>),
+or, if specified, by the value of <parameter>sep</parameter>.
+Top-relative path strings (starting with <literal>#</literal>) are recognized.
+</para>
+<para>
+Path prefixes will only appear once.
+Duplicate prefixes in <parameter>newpath</parameter> are removed,
+preserving the last occurrence to maintain path order.
+If <parameter>delete_existing</parameter> is true,
+existing duplicates are removed before prepending;
+otherwise, new duplicates are skipped
+(the default is false).
+Prefixes are normalized for comparisons to avoid problems of
+"same path, spelled differently",
+but retain their original form in the result.
 </para>
 
 <para>

SCons/Util/UtilTests.py

@@ -545,55 +545,95 @@ def test_get_native_path(self) -> None:
 
     def test_PrependPath(self) -> None:
         """Test prepending to a path"""
-        p1: list | str = r'C:\dir\num\one;C:\dir\num\two'
-        p2: list | str = r'C:\mydir\num\one;C:\mydir\num\two'
-        # have to include the pathsep here so that the test will work on UNIX too.
-        p1 = PrependPath(p1, r'C:\dir\num\two', sep=';')
-        p1 = PrependPath(p1, r'C:\dir\num\three', sep=';')
-        assert p1 == r'C:\dir\num\three;C:\dir\num\two;C:\dir\num\one', p1
-
-        p2 = PrependPath(p2, r'C:\mydir\num\three', sep=';')
-        p2 = PrependPath(p2, r'C:\mydir\num\one', sep=';')
-        assert p2 == r'C:\mydir\num\one;C:\mydir\num\three;C:\mydir\num\two', p2
-
-        # check (only) first one is kept if there are dupes in new
-        p3: list | str = r'C:\dir\num\one'
-        p3 = PrependPath(p3, r'C:\dir\num\two;C:\dir\num\three;C:\dir\num\two', sep=';')
-        assert p3 == r'C:\dir\num\two;C:\dir\num\three;C:\dir\num\one', p3
+        # have to specify the pathsep when adding so it's cross-platform
+        # new duplicates existing - "moves to front"
+        with self.subTest():
+            p1: list | str = r'C:\dir\num\one;C:\dir\num\two'
+            p1 = PrependPath(p1, r'C:\dir\num\two', sep=';')
+            p1 = PrependPath(p1, r'C:\dir\num\three', sep=';')
+            self.assertEqual(p1, r'C:\dir\num\three;C:\dir\num\two;C:\dir\num\one')
+
+        # ... except with delete_existing false
+        with self.subTest():
+            p2: list | str = r'C:\dir\num\one;C:\dir\num\two'
+            p2 = PrependPath(p2, r'C:\dir\num\two', sep=';', delete_existing=False)
+            p2 = PrependPath(p2, r'C:\dir\num\three', sep=';', delete_existing=False)
+            self.assertEqual(p2, r'C:\dir\num\three;C:\dir\num\one;C:\dir\num\two')
+
+        # only last one is kept if there are dupes in new
+        with self.subTest():
+            p3: list | str = r'C:\dir\num\one'
+            p3 = PrependPath(p3, r'C:\dir\num\two;C:\dir\num\three;C:\dir\num\two', sep=';')
+            self.assertEqual(p3, r'C:\dir\num\two;C:\dir\num\three;C:\dir\num\one')
+
+        # try prepending a Dir Node
+        with self.subTest():
+            p4: list | str = r'C:\dir\num\one'
+            test = TestCmd.TestCmd(workdir='')
+            test.subdir('sub')
+            subdir = test.workpath('sub')
+            p4 = PrependPath(p4, subdir, sep=';')
+            self.assertEqual(p4, rf'{subdir};C:\dir\num\one')
+
+        # try with initial list, adding string (result stays a list)
+        with self.subTest():
+            p5: list = [r'C:\dir\num\one', r'C:\dir\num\two']
+            p5 = PrependPath(p5, r'C:\dir\num\two', sep=';')
+            self.assertEqual(p5, [r'C:\dir\num\two', r'C:\dir\num\one'])
+            p5 = PrependPath(p5, r'C:\dir\num\three', sep=';')
+            self.assertEqual(p5, [r'C:\dir\num\three', r'C:\dir\num\two', r'C:\dir\num\one'])
+
+        # try with initial string, adding list (result stays a string)
+        with self.subTest():
+            p6: list | str = r'C:\dir\num\one;C:\dir\num\two'
+            p6 = PrependPath(p6, [r'C:\dir\num\two', r'C:\dir\num\three'], sep=';')
+            self.assertEqual(p6, r'C:\dir\num\two;C:\dir\num\three;C:\dir\num\one')
+
 
     def test_AppendPath(self) -> None:
         """Test appending to a path."""
-        p1: list | str = r'C:\dir\num\one;C:\dir\num\two'
-        p2: list | str = r'C:\mydir\num\one;C:\mydir\num\two'
-        # have to include the pathsep here so that the test will work on UNIX too.
-        p1 = AppendPath(p1, r'C:\dir\num\two', sep=';')
-        p1 = AppendPath(p1, r'C:\dir\num\three', sep=';')
-        assert p1 == r'C:\dir\num\one;C:\dir\num\two;C:\dir\num\three', p1
-
-        p2 = AppendPath(p2, r'C:\mydir\num\three', sep=';')
-        p2 = AppendPath(p2, r'C:\mydir\num\one', sep=';')
-        assert p2 == r'C:\mydir\num\two;C:\mydir\num\three;C:\mydir\num\one', p2
-
-        # check (only) last one is kept if there are dupes in new
-        p3: list | str = r'C:\dir\num\one'
-        p3 = AppendPath(p3, r'C:\dir\num\two;C:\dir\num\three;C:\dir\num\two', sep=';')
-        assert p3 == r'C:\dir\num\one;C:\dir\num\three;C:\dir\num\two', p3
-
-    def test_PrependPathPreserveOld(self) -> None:
-        """Test prepending to a path while preserving old paths"""
-        p1: list | str = r'C:\dir\num\one;C:\dir\num\two'
-        # have to include the pathsep here so that the test will work on UNIX too.
-        p1 = PrependPath(p1, r'C:\dir\num\two', sep=';', delete_existing=False)
-        p1 = PrependPath(p1, r'C:\dir\num\three', sep=';')
-        assert p1 == r'C:\dir\num\three;C:\dir\num\one;C:\dir\num\two', p1
-
-    def test_AppendPathPreserveOld(self) -> None:
-        """Test appending to a path while preserving old paths"""
-        p1: list | str = r'C:\dir\num\one;C:\dir\num\two'
-        # have to include the pathsep here so that the test will work on UNIX too.
-        p1 = AppendPath(p1, r'C:\dir\num\one', sep=';', delete_existing=False)
-        p1 = AppendPath(p1, r'C:\dir\num\three', sep=';')
-        assert p1 == r'C:\dir\num\one;C:\dir\num\two;C:\dir\num\three', p1
+        # have to specify the pathsep when adding so it's cross-platform
+        # new duplicates existing - "moves to end"
+        with self.subTest():
+            p1: list | str = r'C:\dir\num\one;C:\dir\num\two'
+            p1 = AppendPath(p1, r'C:\dir\num\two', sep=';')
+            p1 = AppendPath(p1, r'C:\dir\num\three', sep=';')
+            self.assertEqual(p1, r'C:\dir\num\one;C:\dir\num\two;C:\dir\num\three')
+
+        # ... except with delete_existing false
+        with self.subTest():
+            p2: list | str = r'C:\dir\num\one;C:\dir\num\two'
+            p2 = AppendPath(p1, r'C:\dir\num\one', sep=';', delete_existing=False)
+            p2 = AppendPath(p1, r'C:\dir\num\three', sep=';')
+            self.assertEqual(p2, r'C:\dir\num\one;C:\dir\num\two;C:\dir\num\three')
+
+        # only last one is kept if there are dupes in new
+        with self.subTest():
+            p3: list | str = r'C:\dir\num\one'
+            p3 = AppendPath(p3, r'C:\dir\num\two;C:\dir\num\three;C:\dir\num\two', sep=';')
+            self.assertEqual(p3, r'C:\dir\num\one;C:\dir\num\three;C:\dir\num\two')
+
+        # try appending a Dir Node
+        with self.subTest():
+            p4: list | str = r'C:\dir\num\one'
+            test = TestCmd.TestCmd(workdir='')
+            test.subdir('sub')
+            subdir = test.workpath('sub')
+            p4 = AppendPath(p4, subdir, sep=';')
+            self.assertEqual(p4, rf'C:\dir\num\one;{subdir}')
+
+        # try with initial list, adding string (result stays a list)
+        with self.subTest():
+            p5: list = [r'C:\dir\num\one', r'C:\dir\num\two']
+            p5 = AppendPath(p5, r'C:\dir\num\two', sep=';')
+            p5 = AppendPath(p5, r'C:\dir\num\three', sep=';')
+            self.assertEqual(p5, [r'C:\dir\num\one', r'C:\dir\num\two', r'C:\dir\num\three'])
+
+        # try with initia string, adding list (result stays a string)
+        with self.subTest():
+            p6: list | str = r'C:\dir\num\one;C:\dir\num\two'
+            p6 = AppendPath(p6, [r'C:\dir\num\two', r'C:\dir\num\three'], sep=';')
+            self.assertEqual(p6, r'C:\dir\num\one;C:\dir\num\two;C:\dir\num\three')
 
     def test_addPathIfNotExists(self) -> None:
         """Test the AddPathIfNotExists() function"""