py-arguments 1.0.1__py3-none-any.whl

py_arguments-1.0.1.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: py-arguments
+Version: 1.0.1
+Description-Content-Type: text/markdown
+Provides-Extra: development
+Requires-Dist: pre-commit; extra == "development"
+
+# PyArg
+
+A small layer on top of `argparse` to build CLIs with sub-commands by **reusing parser classes**.
+
+Each parser is a class. You define its arguments in one method, and then plug that class into another parser as a
+command, without rewriting the arguments.
+
+## Installation
+
+```bash
+pip install .
+```
+
+For development (changes apply without reinstalling):
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.10+ and has no dependencies.
+
+## Quick start
+
+Create a class that inherits from `PyArg` and define the arguments in `setup_arguments`:
+
+```python
+from pyarg import PyArg
+
+
+class Login(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--username", "-u")
+        self.add_argument("--password", "-p")
+
+
+parser = Login(name="Login")
+print(parser.get_arguments())
+```
+
+```console
+$ python main.py -u ana -p 123
+{'username': 'ana', 'password': '123'}
+```
+
+Since `PyArg` inherits from `argparse.ArgumentParser`, everything from `argparse` still works
+(`add_argument`, `add_mutually_exclusive_group`, `type`, `nargs`, `choices`, etc.).
+
+## Sub-commands
+
+Use `add_command_parser` to attach parsers to a main one. Each command is named after the parser `name`, converted to
+lowercase with spaces replaced by `-` (`"Make Directory"` becomes `make-directory`).
+
+```python
+from pyarg import PyArg
+
+
+class Login(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--username", "-u")
+        self.add_argument("--password", "-p")
+
+
+class Logout(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--all", action="store_true")
+
+
+class App(PyArg):
+    def setup_arguments(self) -> None:
+        pass  # The main parser can have its own arguments too.
+
+
+app = App(name="My App", description="Demo app.")
+app.add_command_parser(Login(name="Login", description="Sign in."))
+app.add_command_parser(Logout(name="Logout"), description="Sign out.")
+
+print(app.get_arguments())
+```
+
+```console
+$ python main.py login -u ana -p 123
+{'command': 'login', 'username': 'ana', 'password': '123'}
+
+$ python main.py logout --all
+{'command': 'logout', 'all': True}
+
+$ python main.py -h
+usage: My App [-h] {login,logout} ...
+```
+
+The chosen command is available under the `command` key.
+
+## Reusing arguments
+
+Arguments from other parsers can be inherited with `parents`:
+
+```python
+class Common(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--verbose", "-v", action="store_true")
+
+
+class Build(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--target")
+
+
+build = Build(name="Build", parents=[Common(name="Common", add_help=False)])
+```
+
+Use `add_help=False` on the parent parser so the `-h` option is not registered twice.
+
+## API
+
+### `PyArg(name, description=None, parents=[], **kwargs)`
+
+Abstract class. It cannot be instantiated directly, you must inherit from it and implement `setup_arguments`.
+
+- `name`: parser name. Used as `prog` in the help text and to build the command name.
+- `description`: text shown in `-h`.
+- `parents`: other parsers whose arguments are copied into this one.
+- `**kwargs`: forwarded to `argparse.ArgumentParser`. The `prog`, `description`, `parents` and `conflict_handler`
+  keys are ignored, as `conflict_handler` is always `"resolve"`.
+
+### `setup_arguments(self) -> None`
+
+Abstract method. Define all the arguments of the parser here. It runs at the end of `__init__`.
+
+### `command_name`
+
+Read-only property with the command name derived from `name`.
+
+### `add_command_parser(parser, description=None, script_entrypoint=None)`
+
+Adds `parser` as a sub-command. If `description` is not set, the parser's own description is used.
+
+`script_entrypoint` stores a callable on the command, but `get_arguments` does not call it and removes it from the
+result.
+
+### `get_arguments() -> dict[str, Any]`
+
+Parses `sys.argv` and returns the arguments passed by the user as a dictionary.
+
+## Development
+
+See [DEVELOPERS.md](DEVELOPERS.md).

py_arguments-1.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+pyarg/__init__.py,sha256=R5_NfeiJii9p9hunfiYdfcHHXBwk2Dx7MN6K7caYlh8,101
+pyarg/parser.py,sha256=vdtXC5DSymuLuuXUMXKy1S-YMIy-2N3ygdaGX1lMPBA,4175
+py_arguments-1.0.1.dist-info/METADATA,sha256=G3pl3-Ns6cnqQABHR2maN_CQ3Z9_-Nm_eQArh1FfY9w,4141
+py_arguments-1.0.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+py_arguments-1.0.1.dist-info/top_level.txt,sha256=y1U_g5JsWcbFiM6lo3f2O9pIKHiJOErDQLFdHIr4tcs,6
+py_arguments-1.0.1.dist-info/RECORD,,

py_arguments-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_arguments-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyarg

pyarg/__init__.py

@@ -0,0 +1,5 @@
+"""Entrypoint module file for pyarg library."""
+
+from pyarg.parser import PyArg
+
+__all__ = ["PyArg"]

pyarg/parser.py

@@ -0,0 +1,118 @@
+import argparse
+import re
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterable
+from typing import Any
+
+
+# Classes.
+class PyArg(ABC, argparse.ArgumentParser):
+    """
+    **PyArg** is an abstract class that uses `argparse.ArgumentParser` class that allows you to set up easily sub
+    parsers/commands from a parent parser.
+
+    Creates a class inhenrance from **PyArg**, set up all arguments in `setup_arguments` method, and then, you can
+    re-use the same parser definition to build your complex structure of parser arguments and CLI commands.
+
+    Usage:
+    ```
+    class Forms(PyArg):
+        def setup_arguments(self):
+            self.add_argument("--username", "-u")
+            self.add_argument("--password", "-p")
+
+    parser = Forms(name="Forms")
+    arguments = parser.get_arguments()
+    ```
+
+    Extra commands that trigger a function:
+    ```
+    class Application(PyArg):
+        def setup_arguments(self):
+            ...
+
+    class MakeDir(PyArg):
+        @staticmethod
+        def create_directory(location, name_list):
+            for name in name_list:
+                os.makedirs(os.path.join(location, name))
+
+        def setup_arguments(self):
+            self.add_argument("--location", "-l")
+            self.add_argument("--name", "-n", type=str, nargs="+")
+
+    class DeleteDir(PyArg):
+        @staticmethod
+        def delete_directory(path):
+            shutil.rmtree(path)
+
+        def setup_arguments(self):
+            self.add_argument("--path", "-p")
+
+    make_dir_parser = MakeDir(name="Make Directory")
+    delete_dir_parser = DeleteDir(name="Delete Directory")
+
+    app = Application(name="Directory Manager")
+    app.add_command_parser(parser=make_dir_parser, script_entrypoint=MakeDir.create_directory)
+    app.add_command_parser(parser=delete_dir_parser, script_entrypoint=DeleteDir.delete_directory)
+    app.get_arguments()
+    ```
+    """
+
+    # Special methods.
+    def __init__(
+        self, name: str, description: str | None = None, parents: Iterable["PyArg"] | None = None, **kwargs: Any
+    ) -> None:
+        # Remove parameters.
+        for to_remove in ("prog", "description", "parents", "conflict_handler"):
+            kwargs.pop(to_remove, None)
+        parents = [] if parents is None else parents
+        super().__init__(prog=name, description=description, parents=parents, conflict_handler="resolve", **kwargs)
+
+        # Attributes.
+        self.__command_name: str = self.__get_program_name(name=name)
+
+        # Set up extra sub parsers.
+        self.__subparser: None | argparse._SubParsersAction[argparse.ArgumentParser] = None
+
+        # Set up arguments.
+        self.setup_arguments()
+
+    # Properties.
+    @property
+    def command_name(self) -> str:
+        return self.__command_name
+
+    # Abstract methods.
+    @abstractmethod
+    def setup_arguments(self) -> None:
+        """Main method used to define all parameters of the parser."""
+
+    # Private methods.
+    def __get_program_name(self, name: str) -> str:
+        """Convert the parser name to a CLI command name."""
+        name = name.lower()
+        name = re.sub(pattern=r"\s+", repl="-", string=name.strip())
+        return name
+
+    # Methods.
+    def add_command_parser(
+        self, parser: "PyArg", description: str | None = None, script_entrypoint: Callable[..., Any] | None = None
+    ) -> None:
+        """Add an extra parser to a parent **PyArg** class to be called by `name`."""
+        if self.__subparser is None:
+            self.__subparser = self.add_subparsers(
+                dest="command", parser_class=argparse.ArgumentParser, help="Available commands."
+            )
+        subparser: argparse.ArgumentParser = self.__subparser.add_parser(
+            parents=[parser], name=parser.command_name, description=description or parser.description, add_help=False
+        )
+        # Add script.
+        if script_entrypoint:
+            subparser.set_defaults(_entrypoint=script_entrypoint)
+
+    def get_arguments(self) -> dict[str, Any]:
+        """Get the CLI arguments."""
+        args: dict[str, Any] = vars(self.parse_args())
+        args.pop("_entrypoint", None)
+        return args