Merge pull request #4670 from bdbaddog/fix_help_local_only

Fix Help()'s local_only arg to match documents.

CHANGES.txt

@@ -92,6 +92,10 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Added TestSCons.NINJA_BINARY to TestSCons to centralize logic to find ninja binary
     - Refactored SCons.Tool.ninja -> SCons.Tool.ninja_tool, and added alias so
       env.Tool('ninja') will still work. This avoids conflicting with the pypi module ninja.
+    - Renamed env.Help() & Help()'s argument `keep_local` to `local_only`, previously the documentation
+      specified `local_only`, but the code and tests were using `keep_local`. The functionality
+      more closely matches local only.  NOTE: It doesn't seem like any code in the wild was using
+      local_only as we'd not received any reports of such until PR #4606 from hedger.
 
   From Alex James:
     - On Darwin, PermissionErrors are now handled while trying to access

RELEASE.txt

@@ -167,10 +167,15 @@ FIXES
 - Minor modernization: make use of stat object's st_mode, st_mtime
   and other attributes rather than indexing into stat return.
 
-- Ninja's TEMPLATE rule pool changed from `local_pool` to `install_pool``
+- Ninja's TEMPLATE rule pool changed from `local_pool` to `install_pool`
   hoping it will fix a race condition that can occurs when Ninja defers
   to SCons to build.
 
+- Renamed env.Help() & Help()'s argument `keep_local` to `local_only`, previously the documentation
+  specified `local_only`, but the code and tests were using `keep_local`. The functionality
+  more closely matches local only.  NOTE: It doesn't seem like any code in the wild was using
+  local_only as we'd not received any reports of such until PR #4606 from hedger.
+
 
 IMPROVEMENTS
 ------------

SCons/Script/SConscript.py

@@ -536,25 +536,27 @@ def GetOption(self, name):
         name = self.subst(name)
         return SCons.Script.Main.GetOption(name)
 
-    def Help(self, text, append: bool = False, keep_local: bool = False) -> None:
+    def Help(self, text, append: bool = False, local_only: bool = False) -> None:
         """Update the help text.
 
         The previous help text has *text* appended to it, except on the
-        first call. On first call, the values of *append* and *keep_local*
+        first call. On first call, the values of *append* and *local_only*
         are considered to determine what is appended to.
 
         Arguments:
            text: string to add to the help text.
            append: on first call, if true, keep the existing help text
               (default False).
-           keep_local: on first call, if true and *append* is also true,
+           local_only: on first call, if true and *append* is also true,
               keep only the help text from AddOption calls.
 
         .. versionchanged:: 4.6.0
            The *keep_local* parameter was added.
+        .. versionchanged:: NEXT_RELEASE
+           The *keep_local* parameter was renamed *local_only* to match manpage
         """
         text = self.subst(text, raw=1)
-        SCons.Script.HelpFunction(text, append=append, keep_local=keep_local)
+        SCons.Script.HelpFunction(text, append=append, local_only=local_only)
 
     def Import(self, *vars):
         try:

SCons/Script/__init__.py

@@ -251,19 +251,21 @@ def _Set_Default_Targets(env, tlist) -> None:
 help_text = None
 
 
-def HelpFunction(text, append: bool = False, keep_local: bool = False) -> None:
+def HelpFunction(text, append: bool = False, local_only: bool = False) -> None:
     """The implementaion of the the ``Help`` method.
 
     See :meth:`~SCons.Script.SConscript.Help`.
 
     .. versionchanged:: 4.6.0
        The *keep_local* parameter was added.
+    .. versionchanged:: NEXT_RELEASE
+       The *keep_local* parameter was renamed *local_only* to match manpage
     """
     global help_text
     if help_text is None:
         if append:
             with StringIO() as s:
-                PrintHelp(s, local_only=keep_local)
+                PrintHelp(s, local_only=local_only)
                 help_text = s.getvalue()
         else:
             help_text = ""

test/Help.py

@@ -81,51 +81,19 @@
 
 test.run(arguments = '-h', stdout = expect)
 
-# Bug #2831 - append flag to Help doesn't wipe out addoptions and variables used together
-test.write('SConstruct', r"""
+# Use fixturized SConstruct_HELP_AddOption.py for the remaining tests
+# All of which add help with AddOption() and then call Help() various ways
+# to test how the help from the option contributes to the Help()'s output
 
-AddOption(
-    '--debugging',
-    dest='debugging',
-    action='store_true',
-    default=False,
-    metavar='BDEBUGGING',
-    help='Compile with debugging symbols',
-)
-
-vars = Variables()
-vars.Add(ListVariable('buildmod', 'List of modules to build', 'none', ['python']))
-DefaultEnvironment(tools=[])
-env = Environment()
-Help(vars.GenerateHelpText(env), append=True)
-""")
+test.file_fixture('SConstruct_HELP_AddOption.py', 'SConstruct')
 
+# Bug #2831 - append flag to Help doesn't wipe out addoptions and variables used together
 expect = ".*--debugging.*Compile with debugging symbols.*buildmod: List of modules to build.*"
 test.run(arguments = '-h', stdout = expect, match=TestSCons.match_re_dotall)
 
 # Bug 2831
 # This test checks to verify that append=False doesn't include anything
 # but the expected help for the specified Variable()
-
-test.write('SConstruct', r"""
-AddOption(
-    '--debugging',
-    dest='debugging',
-    action='store_true',
-    default=False,
-    metavar='BDEBUGGING',
-    help='Compile with debugging symbols',
-)
-
-vars = Variables()
-vars.Add(ListVariable('buildmod', 'List of modules to build', 'none', ['python']))
-
-DefaultEnvironment(tools=[])
-env = Environment()
-
-Help(vars.GenerateHelpText(env), append=False)
-""")
-
 expect = """\
 scons: Reading SConscript files ...
 scons: done reading SConscript files.
@@ -139,29 +107,10 @@
 Use scons -H for help about SCons built-in command-line options.
 """
 
-test.run(arguments='-h', stdout=expect)
+test.run(arguments='-h NO_APPEND=1', stdout=expect)
 
-# Enhancement: keep_local flag saves the AddOption help,
+# Enhancement: local_only flag saves the AddOption help,
 # but not SCons' own help.
-test.write('SConstruct', r"""
-AddOption(
-    '--debugging',
-    dest='debugging',
-    action='store_true',
-    default=False,
-    metavar='BDEBUGGING',
-    help='Compile with debugging symbols',
-)
-
-vars = Variables()
-vars.Add(ListVariable('buildmod', 'List of modules to build', 'none', ['python']))
-
-DefaultEnvironment(tools=[])
-env = Environment()
-
-Help(vars.GenerateHelpText(env), append=True, keep_local=True)
-""")
-
 expect = """\
 scons: Reading SConscript files ...
 scons: done reading SConscript files.
@@ -177,7 +126,7 @@
 Use scons -H for help about SCons built-in command-line options.
 """
 
-test.run(arguments='-h', stdout=expect)
+test.run(arguments='-h LOCAL_ONLY=1', stdout=expect)
 
 
 test.pass_test()

test/fixture/SConstruct_HELP_AddOption.py

@@ -0,0 +1,22 @@
+
+AddOption(
+    '--debugging',
+    dest='debugging',
+    action='store_true',
+    default=False,
+    metavar='BDEBUGGING',
+    help='Compile with debugging symbols',
+)
+
+vars = Variables()
+vars.Add(ListVariable('buildmod', 'List of modules to build', 'none', ['python']))
+DefaultEnvironment(tools=[])
+env = Environment()
+
+if ARGUMENTS.get('NO_APPEND',False):
+    Help(vars.GenerateHelpText(env), append=False)
+elif ARGUMENTS.get('LOCAL_ONLY',False):
+    Help(vars.GenerateHelpText(env), append=True, local_only=True)
+else:
+    Help(vars.GenerateHelpText(env), append=True)
+