Improved example handling for parser help

Author: dhondta

.github/workflows/pypi-publish.yml

@@ -79,3 +79,33 @@ jobs:
       with:
         github_token: ${{ secrets.github_token }}
         branch: ${{ github.ref }}
+  deploy:
+    runs-on: ubuntu-latest
+    needs: coverage
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+    - name: Check for version change
+      uses: dorny/paths-filter@v2
+      id: filter
+      with:
+        filters: |
+          version:
+            - '**/VERSION.txt'
+    - if: steps.filter.outputs.version == 'true'
+      name: Cleanup README
+      run: |
+        sed -ri 's/^(##*)\s*:.*:\s*/\1 /g' README.md
+        awk '{if (match($0,"## Supporters")) exit; print}' README.md > README
+        mv -f README README.md
+    - if: steps.filter.outputs.version == 'true'
+      name: Build ${{ env.package }} package
+      run: python3 -m pip install --upgrade build && python3 -m build
+    - if: steps.filter.outputs.version == 'true'
+      name: Upload ${{ env.package }} to PyPi
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.PYPI_API_TOKEN }}
+        verbose: true
+        verify_metadata: false

.github/workflows/python-package.yml

@@ -1 +1 @@
-1.30.18
+1.30.19

src/tinyscript/VERSION.txt

@@ -35,12 +35,9 @@
                 '__source__', '__training__']
 DUNDERS = BASE_DUNDERS + [
     '__date__', '__details__', '__description__', '__doc__', '__docformat__', '__email__', '__examples__',
-    '__functions__', '__maximum_python_version__', '__minimum_python_version__', '__priority__', '__product__',
-    '__script__', '__status__', '__version__',
+    '__example_limit__', '__functions__', '__maximum_python_version__', '__minimum_python_version__', '__priority__',
+    '__product__', '__requires__', '__script__', '__status__', '__version__',
 ]
-if sys.version_info >= (3, 8):
-    DUNDERS.append('__requires__')
-
 DEFAULT_MAX_LEN     = 20
 DEFAULT_LST_MAX_LEN = 10
 
@@ -158,14 +155,14 @@ def add_parser(self, name, **kwargs):
             choice_action.category = category
             self._choices_actions.append(choice_action)
         # create the parser, but with another formatter and separating the help into an argument group
+        kwargs.update(name=name, parent_action=self)
         parser = self._parser_class(add_help=False, **kwargs)
-        parser.name = name
         # add default extra arguments group
         i = parser.add_argument_group("extra arguments")
         i.add_argument("-h", action="usage", prefix="show", help=gt("show usage message and exit"))
         i.add_argument("--help", action="help", prefix="show", help=gt("show this help message and exit"))
         # add it to the map
-        self._name_parser_map[name] = parser
+        self._name_parser_map[parser.name] = parser
         # make parser available under aliases also
         for alias in aliases:
             self._name_parser_map[alias] = parser
@@ -316,13 +313,16 @@ def __init__(self, *args, **kwargs):
         if not hasattr(ArgumentParser, "_globals_dict"):
             ArgumentParser._globals_dict = get_tool_globals()
         gd = ArgumentParser._globals_dict
-        if sys.version_info >= (3, 8):
-            self._check_requirements(gd.get('__requires__'))
+        self._check_requirements(gd.get('__requires__'))
         configure_docformat(gd)
         self._config_parsed = False
         self._docfmt = gd.get('__docformat__')
+        self._parent_action = kwargs.pop('parent_action', None)
+        self._parent = self._parent_action._parent if self._parent_action else None
         self._reparse_args = {'pos': [], 'opt': [], 'sub': []}
+        self.name = kwargs.pop('name', self.__class__.name)
         self.examples = gd.get('__examples__', [])
+        self.example_limit = gd.get('__example_limit__', {})
         script = basename(self.tokens[0])
         _stem = lambda p: splitext(p)[0]
         if gd.get('__script__') is None:
@@ -344,6 +344,19 @@ def __init__(self, *args, **kwargs):
             l = ["{} {}".format(ArgumentParser.prog, e) for e in self.examples]
             l = list(filter(lambda x: x.startswith(kwargs['prog']), l))
             if len(l) > 0:
+                dest = self._parent_action.dest if getattr(self, "_parent_action", None) else None
+                if (n := self.example_limit if isinstance(self.example_limit, int) else \
+                         self.example_limit.get(self.name, self.example_limit.get(dest, 0))):
+                    from random import shuffle
+                    from shlex import split
+                    shuffle(l)
+                    _tmp, new_l = set(), []
+                    for example in l:
+                        token = split(example)[self.depth+1]
+                        if token not in _tmp:
+                            new_l.append(example)
+                            _tmp.add(token)
+                    l = sorted(new_l)
                 kwargs['epilog'] = txt2title(gt("Usage example{}".format(["", "s"][len(l) > 1])) + ":")
                 e = '\n'.join(["\n", "  "][self._docfmt is None] + txt2paragraph(e) for e in l)
                 kwargs['epilog'] += "\n" + e
@@ -603,6 +616,11 @@ def _sorted_actions(self):
         for a in filter(lambda _: self.is_action(_, 'parsers'), self._actions):
             yield a
 
+    def add_subparsers(self, **kwargs):
+        action = super(ArgumentParser, self).add_subparsers(**kwargs)
+        action._parent = self
+        return action
+    
     def config_args(self, section="main"):
         """ Additional method for feeding input arguments from a config file. """
         if self._config_parsed:
@@ -730,19 +748,26 @@ def print_usage(self, file=None):
         self._print_message(txt_terminal_render(self.format_usage()), file or sys.stdout)
 
     @property
-    def tokens(self):
+    def depth(self):
+        p, d = self, 0
+        while (p := getattr(p, "_parent", None)):
+            d += 1
+        return d
+    
+    @property
+    def root(self):
         p = self
-        while hasattr(p, "_parent") and p._parent is not None:
+        while getattr(p, "_parent", None):
             p = p._parent
-        if hasattr(p, "_tokens"):
-            return p._tokens
+        return p
+    
+    @property
+    def tokens(self):
+        return getattr(self.root, "_tokens", None)
 
     @tokens.setter
     def tokens(self, command):
-        p = self
-        while hasattr(p, "_parent") and p._parent is not None:
-            p = p._parent
-        if hasattr(p, "_tokens"):
+        if hasattr(p := self.root, "_tokens"):
             return
         p._tokens = sys.argv if command is None else command
         if isinstance(p._tokens, str):

src/tinyscript/argreparse.py

@@ -12,8 +12,9 @@
 
 
 def get_parser(tool, logger=None, **kwargs):
-    return [p for p in get_parsers(tool, logger=logger, **kwargs).values() if isinstance(p, ArgumentParser) and \
-                                                                              not hasattr(p, "_parent")][0]
+    for p in get_parsers(tool, logger=logger, **kwargs).values():
+        if p.name == ArgumentParser.name:
+            return p
 
 
 def get_parsers(tool, logger=None, **kwargs):

src/tinyscript/helpers/parser.py

@@ -25,21 +25,22 @@
 
 
 FIXTURES = ArgumentParser._globals_dict = {
-    '__author__':       "John Doe",
-    '__contributors__': [
+    '__author__':        "John Doe",
+    '__contributors__':  [
         {'author': "James McAdams", 'email': "j.mcadams@hotmail.com"},
         {'author': "h4x0r1234", 'reason': "for his kind testing"},
         {'reason': "won't be displayed (no author and no email specified)"},
     ],
-    '__copyright__':    "test",
-    '__credits__':      "Thanks to Bob for his contribution",
-    '__doc__':          "test tool",
-    '__details__':      "some more information",
-    '__email__':        "john.doe@example.com",
-    '__examples__':     ["-v"],
-    '__license__':      "agpl-v3.0",
-    '__status__':       "beta",
-    '__version__':      "1.2.3",
+    '__copyright__':     "test",
+    '__credits__':       "Thanks to Bob for his contribution",
+    '__doc__':           "test tool",
+    '__details__':       "some more information",
+    '__email__':         "john.doe@example.com",
+    '__examples__':      ["-v"],
+    '__example_limit__': {'main': 1},
+    '__license__':       "agpl-v3.0",
+    '__status__':        "beta",
+    '__version__':       "1.2.3",
 }