Tweak around docstring to make prettier sphinx autodocs.

[python_utils.git] / config.py

diff --git a/config.py b/config.py
index 599026c8f95ec4379c22261ed025c9f9a7b5e063..c5813a81145764c05d7af29ce32a07da4ef36ef8 100644 (file)
--- a/config.py
+++ b/config.py
@@ -7,64 +7,64 @@ and saved configuration files.  This works across several modules.
 
 Usage:
 
 
 Usage:
 

-    module.py:
-    ----------
-    import config
-
-    parser = config.add_commandline_args(
-        "Module",
-        "Args related to module doing the thing.",
-    )
-    parser.add_argument(
-        "--module_do_the_thing",
-        type=bool,
-        default=True,
-        help="Should the module do the thing?"
-    )
-
-    main.py:
-    --------
-    import config
-
-    def main() -> None:
+    In your file.py::
+
+        import config
+

         parser = config.add_commandline_args(
         parser = config.add_commandline_args(

-            "Main",
-            "A program that does the thing.",
+            "Module",
+            "Args related to module doing the thing.",

         )
         parser.add_argument(
         )
         parser.add_argument(

-            "--dry_run",
+            "--module_do_the_thing",

             type=bool,
             type=bool,

-            default=False,
-            help="Should we really do the thing?"
+            default=True,
+            help="Should the module do the thing?"

         )
         )

-        config.parse()   # Very important, this must be invoked!
+
+    In your main.py::
+
+        import config
+
+        def main() -> None:
+            parser = config.add_commandline_args(
+                "Main",
+                "A program that does the thing.",
+            )
+            parser.add_argument(
+                "--dry_run",
+                type=bool,
+                default=False,
+                help="Should we really do the thing?"
+            )
+            config.parse()   # Very important, this must be invoked!

 
     If you set this up and remember to invoke config.parse(), all commandline
     arguments will play nicely together.  This is done automatically for you
 
     If you set this up and remember to invoke config.parse(), all commandline
     arguments will play nicely together.  This is done automatically for you

-    if you're using the bootstrap module's initialize wrapper.
+    if you're using the bootstrap module's initialize wrapper.::

 
 

-    % main.py -h
-    usage: main.py [-h]
-                   [--module_do_the_thing MODULE_DO_THE_THING]
-                   [--dry_run DRY_RUN]
+        % main.py -h
+        usage: main.py [-h]
+                       [--module_do_the_thing MODULE_DO_THE_THING]
+                       [--dry_run DRY_RUN]

 
 

-    Module:
-      Args related to module doing the thing.
+        Module:
+          Args related to module doing the thing.

 
 

-      --module_do_the_thing MODULE_DO_THE_THING
-                   Should the module do the thing?
+          --module_do_the_thing MODULE_DO_THE_THING
+                       Should the module do the thing?

 
 

-    Main:
-      A program that does the thing
+        Main:
+          A program that does the thing

 
 

-      --dry_run
-                   Should we really do the thing?
+          --dry_run
+                       Should we really do the thing?

 
     Arguments themselves should be accessed via
 
     Arguments themselves should be accessed via

-    config.config['arg_name'].  e.g.
+    :code:`config.config['arg_name']`.  e.g.::

 
 

-    if not config.config['dry_run']:
-        module.do_the_thing()
+        if not config.config['dry_run']:
+            module.do_the_thing()

 
 """
 
 
 """
 


@@ -92,6 +92,33 @@ class OptionalRawFormatter(argparse.HelpFormatter):
     "RAW|".  In that case, the line breaks are preserved and the text
     is not wrapped.
 
     "RAW|".  In that case, the line breaks are preserved and the text
     is not wrapped.
 

+    Use this, for example, when you need the helptext of an argument
+    to have its spacing preserved exactly, e.g.::
+
+        args.add_argument(
+            '--mode',
+            type=str,
+            default='PLAY',
+            choices=['CHEAT', 'AUTOPLAY', 'SELFTEST', 'PRECOMPUTE', 'PLAY'],
+            metavar='MODE',
+            help='''RAW|Our mode of operation.  One of:
+
+                PLAY = play wordle with me!  Pick a random solution or
+                       specify a solution with --template.
+
+               CHEAT = given a --template and, optionally, --letters_in_word
+                       and/or --letters_to_avoid, return the best guess word;
+
+            AUTOPLAY = given a complete word in --template, guess it step
+                       by step showing work;
+
+            SELFTEST = autoplay every possible solution keeping track of
+                       wins/losses and average number of guesses;
+
+          PRECOMPUTE = populate hash table with optimal guesses.
+            ''',
+        )
+

     """
 
     def _split_lines(self, text, width):
     """
 
     def _split_lines(self, text, width):


@@ -127,8 +154,16 @@ config: Dict[str, Any] = {}
 # It would be really nice if this shit worked from interactive python
 
 
 # It would be really nice if this shit worked from interactive python
 
 

-def add_commandline_args(title: str, description: str = ""):
-    """Create a new context for arguments and return a handle."""
+def add_commandline_args(title: str, description: str = "") -> argparse._ArgumentGroup:
+    """Create a new context for arguments and return a handle.
+
+    Args:
+        title: A title for your module's commandline arguments group.
+        description: A helpful description of your module.
+
+    Returns:
+        An argparse._ArgumentGroup to be populated by the caller.
+    """

     return ARGS.add_argument_group(title, description)
 
 
     return ARGS.add_argument_group(title, description)
 
 


@@ -168,18 +203,33 @@ group.add_argument(
 
 
 def overwrite_argparse_epilog(msg: str) -> None:
 
 
 def overwrite_argparse_epilog(msg: str) -> None:

+    """Allows your code to override the default epilog created by
+    argparse.
+
+    Args:
+        msg: The epilog message to substitute for the default.
+    """

     ARGS.epilog = msg
 
 
     ARGS.epilog = msg
 
 

-def is_flag_already_in_argv(var: str):
-    """Is a particular flag passed on the commandline?"""
+def is_flag_already_in_argv(var: str) -> bool:
+    """Returns true if a particular flag is passed on the commandline?
+
+    Args:
+        var: The flag to search for.
+    """

     for _ in sys.argv:
         if var in _:
             return True
     return False
 
 
     for _ in sys.argv:
         if var in _:
             return True
     return False
 
 

-def reorder_arg_action_groups_before_help(entry_module: Optional[str]):
+def _reorder_arg_action_groups_before_help(entry_module: Optional[str]):
+    """Internal.  Used to reorder the arguments before dumping out a
+    generated help string such that the main program's arguments come
+    last.
+
+    """

     reordered_action_groups = []
     for grp in ARGS._action_groups:
         if entry_module is not None and entry_module in grp.title:  # type: ignore
     reordered_action_groups = []
     for grp in ARGS._action_groups:
         if entry_module is not None and entry_module in grp.title:  # type: ignore


@@ -191,7 +241,21 @@ def reorder_arg_action_groups_before_help(entry_module: Optional[str]):
     return reordered_action_groups
 
 
     return reordered_action_groups
 
 

-def augment_sys_argv_from_environment_variables():
+def _augment_sys_argv_from_environment_variables():
+    """Internal.  Look at the system environment for variables that match
+    arg names.  This is done via some munging such that:
+
+    :code:`--argument_to_match`
+
+    ...is matched by:
+
+    :code:`ARGUMENT_TO_MATCH`
+
+    This allows programmers to set args via shell environment variables
+    in lieu of passing them on the cmdline.
+
+    """
+

     usage_message = ARGS.format_usage()
     optional = False
     var = ''
     usage_message = ARGS.format_usage()
     optional = False
     var = ''


@@ -227,7 +291,9 @@ def augment_sys_argv_from_environment_variables():
                 env = ''
 
 
                 env = ''
 
 

-def augment_sys_argv_from_loadfile():
+def _augment_sys_argv_from_loadfile():
+    """Internal.  Augment with arguments persisted in a saved file."""
+

     loadfile = None
     saw_other_args = False
     grab_next_arg = False
     loadfile = None
     saw_other_args = False
     grab_next_arg = False


@@ -263,7 +329,8 @@ def augment_sys_argv_from_loadfile():
 
 def parse(entry_module: Optional[str]) -> Dict[str, Any]:
     """Main program should call this early in main().  Note that the
 
 def parse(entry_module: Optional[str]) -> Dict[str, Any]:
     """Main program should call this early in main().  Note that the

-    bootstrap.initialize wrapper takes care of this automatically.
+    :code:`bootstrap.initialize` wrapper takes care of this automatically.
+    This should only be called once per program invocation.

 
     """
     global CONFIG_PARSE_CALLED
 
     """
     global CONFIG_PARSE_CALLED


@@ -278,17 +345,17 @@ def parse(entry_module: Optional[str]) -> Dict[str, Any]:
         if arg in ('--help', '-h'):
             if entry_module is not None:
                 entry_module = os.path.basename(entry_module)
         if arg in ('--help', '-h'):
             if entry_module is not None:
                 entry_module = os.path.basename(entry_module)

-            ARGS._action_groups = reorder_arg_action_groups_before_help(entry_module)
+            ARGS._action_groups = _reorder_arg_action_groups_before_help(entry_module)

 
     # Examine the environment for variables that match known flags.
     # For a flag called --example_flag the corresponding environment
     # variable would be called EXAMPLE_FLAG.  If found, hackily add
     # these into sys.argv to be parsed.
 
     # Examine the environment for variables that match known flags.
     # For a flag called --example_flag the corresponding environment
     # variable would be called EXAMPLE_FLAG.  If found, hackily add
     # these into sys.argv to be parsed.

-    augment_sys_argv_from_environment_variables()
+    _augment_sys_argv_from_environment_variables()

 
     # Look for loadfile and read/parse it if present.  This also
     # works by jamming these values onto sys.argv.
 
     # Look for loadfile and read/parse it if present.  This also
     # works by jamming these values onto sys.argv.

-    augment_sys_argv_from_loadfile()
+    _augment_sys_argv_from_loadfile()

 
     # Parse (possibly augmented, possibly completely overwritten)
     # commandline args with argparse normally and populate config.
 
     # Parse (possibly augmented, possibly completely overwritten)
     # commandline args with argparse normally and populate config.


@@ -322,7 +389,7 @@ def parse(entry_module: Optional[str]) -> Dict[str, Any]:
 
 
 def has_been_parsed() -> bool:
 
 
 def has_been_parsed() -> bool:

-    """Has the global config been parsed yet?"""
+    """Returns True iff the global config has already been parsed"""

     return CONFIG_PARSE_CALLED
 
 
     return CONFIG_PARSE_CALLED