First commit

Author: guludo

.coveragerc

@@ -0,0 +1,3 @@
+[run]
+source=argparse_subdec
+command_line = -m pytest -v

.gitignore

@@ -0,0 +1,3 @@
+*.egg-info
+.coverage
+__pycache__

README.rst

@@ -0,0 +1,82 @@
+python-argparse-subdec
+######################
+
+This is a very simple Python package that allows one to create argparse_'s
+subcommands via function decorators.
+
+Usage
+=====
+
+Create a ``SubDec`` object:
+
+.. code:: python
+
+  import argparse_subdec
+
+  # Create the object to collect subcommands via decorators
+  sd = argparse_subdec.SubDec()
+
+Now, we can define our subcommands. We define a subcommand by decorating a
+function with method calls to ``sd``, like below:
+
+.. code:: python
+
+  @sd.add_argument('--option', default='123')
+  @sd.add_argument('--another')
+  def foo(args):
+      print(f'foo subcommand: --option={args.option!r} and --another={args.another!r}')
+
+You can use any method name that you would use in a subparser. In our example
+above, we used ``add_argument``, probably most commonly used. When creating
+the subparsers, ``sd`` will replay those calls to the created subparser for
+the ``foo`` subcommand.
+
+
+In the example below we define a second subcommand, which will be named
+``foo-bar``:
+
+.. code:: python
+
+  @sd.cmd(prefix_chars=':')
+  @sd.add_argument('positional_arg', type=int)
+  def foo_bar(args):
+      print(f'foo-bar subcommand: {args.positional_arg!r}')
+
+Note that we use a special decorator, ``sd.cmd``, which makes ``sd`` pass all
+of its arguments down to ``add_parser()`` when creating the subparser for
+``foo-bar``.
+
+Once our subcommands are defined, we must call ``sd.create_parsers()`` in
+order to effectively create the subparsers:
+
+.. code:: python
+
+  parser = argparse.ArgumentParser()
+  subparsers = parser.add_subparsers()
+  sd.create_parsers(subparsers)
+
+
+The following is example of how we would call the subcommands:
+
+.. code:: python
+
+    args = parser.parse_args(['foo', '--another', 'hello'])
+    args.fn(args) # The subcommand function is assigned to ``args.fn`` by default
+    # Outputs: foo subcommand: --option='123' and --another='hello'
+
+
+For more details about the API, check out the subdec_ module.
+
+
+Install
+=======
+
+Via ``pip``:
+
+.. code:: bash
+
+   pip install argparse-subdec
+
+
+.. _argparse: https://docs.python.org/3/library/argparse.html
+.. _subdec: argparse_subdec/subdec.py

argparse_subdec/__init__.py

@@ -0,0 +1 @@
+from .subdec import SubDec

argparse_subdec/subdec.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import argparse
+import collections.abc as C
+import typing as T
+
+
+class SubDec:
+    """
+    This class provides a way to decorate functions as subcommands for
+    argparse.
+
+    It provides an implementation of `__getattr__` that allows one to annotate
+    a function (which represents a subcommand) multiple times as if calling
+    methods on a sub-parser for that command.
+
+    The example below creates two subcommands::
+
+    >>> sd = SubDec()
+
+    >>> @sd.add_argument('--option', default='123')
+    ... @sd.add_argument('--another')
+    ... def foo(args):
+    ...     print(f'foo subcommand: --option={args.option!r} and --another={args.another!r}')
+
+    >>> @sd.cmd(prefix_chars=':')
+    ... @sd.add_argument('positional_arg', type=int)
+    ... def foo_bar(args):
+    ...     print(f'foo-bar subcommand: {args.positional_arg!r}')
+
+    Note that the second command uses a special decorator ``cmd()``, which
+    passes all of its arguments down to ``add_parser()`` when creating the
+    sub-parser.
+
+    In order to create the sub-parsers, you must call ``sd.create_parsers()``
+    passing a ``subparsers`` object as argument::
+
+    >>> parser = argparse.ArgumentParser()
+    >>> subparsers = parser.add_subparsers()
+    >>> sd.create_parsers(subparsers)
+
+    >>> args = parser.parse_args(['foo', '--another', 'hello'])
+
+    By default, the subcommand function is assigned to ``args.fn``::
+
+    >>> args.fn(args)
+    foo subcommand: --option='123' and --another='hello'
+
+    Calling the second command::
+
+    >>> args = parser.parse_args(['foo-bar', '42'])
+    >>> args.fn(args)
+    foo-bar subcommand: 42
+    """
+
+    def __init__(self,
+        name_prefix: str = '',
+        fn_dest: str = 'fn',
+        sep: str = '-',
+    ):
+        """
+        Initialize this object.
+
+        If ``name_prefix`` is not empty, that prefix is removed from the
+        function name when defining the name of that function's subparser.
+
+        The parameter ``fn_dest`` (default: "fn") defines the name of the
+        attribute in the object returned by ``parse_args()`` the decorated
+        function will be assigned to.
+
+        The parameter ``sep`` (default: "-") defines the string that will
+        replace the underscore character ("_") when converting the name of the
+        decorated function to a subcommand name.
+        """
+        self.__decorators_cache = {}
+        self.__commands = {}
+        self.__name_prefix = name_prefix
+        self.__fn_dest = fn_dest
+        self.__sep = sep
+
+    def create_parsers(self, subparsers):
+        """
+        Create subparsers by calling ``subparsers.add_parser()`` for each
+        decorated function.
+        """
+        for cmd in self.__commands.values():
+            self.__create_parser(cmd, subparsers)
+
+    def cmd(self, *k, **kw):
+        """
+        Special decorator to register arguments to be passed do
+        ``add_parser()``.
+        """
+        def decorator(fn):
+            cmd = self.__get_command(fn)
+            cmd['add_parser_args'] = (k, kw)
+            return fn
+        return decorator
+
+    def __getattr__(self, name: str):
+        if name in self.__decorators_cache:
+            return self.__decorators_cache[name]
+
+        def decorator_wrapper(*k, **kw):
+            def decorator(fn):
+                cmd = self.__get_command(fn)
+                cmd['subparser_call_stack'].append({
+                    'method_name': name,
+                    'args': k,
+                    'kwargs': kw,
+                })
+                return fn
+            return decorator
+
+        self.__decorators_cache[name] = decorator_wrapper
+        return decorator_wrapper
+
+    def __get_command(self, fn: T.Callable):
+        if fn not in self.__commands:
+            self.__commands[fn] = {
+                'name': None,
+                'fn': fn,
+                'subparser_call_stack': [],
+                'add_parser_args': None,
+            }
+        return self.__commands[fn]
+
+    def __create_parser(self, cmd: dict, subparsers: T.Any):
+        name = cmd['name']
+        if not name:
+            name = cmd['fn'].__name__
+            if name.startswith(self.__name_prefix):
+                name = name[len(self.__name_prefix):]
+            if self.__sep is not None:
+                name = name.replace('_', self.__sep)
+
+        if cmd['add_parser_args']:
+            add_parser_args, add_parser_kwargs = cmd['add_parser_args']
+            if not add_parser_args:
+                add_parser_args = (name,)
+        else:
+            add_parser_args = (name,)
+            add_parser_kwargs = {}
+
+        parser = subparsers.add_parser(*add_parser_args, **add_parser_kwargs)
+        parser.set_defaults(**{self.__fn_dest: cmd['fn']})
+
+        for call_data in reversed(cmd['subparser_call_stack']):
+            method = getattr(parser, call_data['method_name'])
+            method(*call_data['args'], **call_data['kwargs'])

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"

pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+addopts =
+    --doctest-modules --doctest-ignore-import-errors

setup.py

@@ -0,0 +1,13 @@
+import setuptools
+
+setuptools.setup(
+    name='argparse-subdec',
+    version='0.0.0',
+    packages=['argparse_subdec'],
+    extras_require={
+        'tests': [
+            'pytest~=6.2',
+            'coverage~=5.5',
+        ],
+    },
+)

tests/test_subdec.py

@@ -0,0 +1,69 @@
+import argparse
+
+import argparse_subdec
+
+
+def test_command_decorator():
+    sd = argparse_subdec.SubDec()
+
+    @sd.cmd()
+    def foo():
+        pass
+
+    @sd.cmd()
+    def two_words():
+        pass
+
+    @sd.add_argument('--option-for-bar')
+    @sd.add_argument('--another-option-for-bar')
+    def bar():
+        pass
+
+    @sd.cmd('changed-name')
+    @sd.add_argument('--option')
+    def original_name():
+        pass
+
+    # Test changing order of decorators
+    @sd.add_argument('--option')
+    @sd.cmd('changed-name-2')
+    def another_original_name():
+        pass
+
+    parser = argparse.ArgumentParser()
+    subparsers = parser.add_subparsers()
+    sd.create_parsers(subparsers)
+
+    args = parser.parse_args(['foo'])
+    expected_args = argparse.Namespace(
+        fn=foo,
+    )
+    assert args == expected_args
+
+    args = parser.parse_args(['two-words'])
+    expected_args = argparse.Namespace(
+        fn=two_words,
+    )
+    assert args == expected_args
+
+    args = parser.parse_args(['bar', '--option-for-bar', 'hello'])
+    expected_args = argparse.Namespace(
+        fn=bar,
+        option_for_bar='hello',
+        another_option_for_bar=None,
+    )
+    assert args == expected_args
+
+    args = parser.parse_args(['changed-name', '--option', 'hello'])
+    expected_args = argparse.Namespace(
+        fn=original_name,
+        option='hello',
+    )
+    assert args == expected_args
+
+    args = parser.parse_args(['changed-name-2'])
+    expected_args = argparse.Namespace(
+        fn=another_original_name,
+        option=None,
+    )
+    assert args == expected_args