cmdargparse 0.1.0__py3-none-any.whl

cmdargparse/namespace.py

@@ -0,0 +1,37 @@
+import argparse
+
+import cmd2
+
+
+# ################################ NAMESPACE ###################################
+
+
+class Namespace(argparse.Namespace):
+
+    def pfields(self, cmd: cmd2.Cmd, /) -> None:
+        """Prints all fields using the feedback output function."""
+
+        fields = tuple(
+            attr
+            for attr in self.__dict__
+            if (
+                # Skip all internalized attributes.
+                not attr.startswith("_")
+                # Skip all cmd2-related attributes.
+                and not attr.startswith("cmd2")
+            )
+        )
+
+        maxlen = max(
+            len(attr)
+            for attr in fields
+            # <format-break>
+        )
+
+        cmd.pfeedback("[Namespace]")
+        for name in fields:
+            cmd.pfeedback(
+                f"  {str.ljust(name, maxlen)!s} :  {self.__dict__[name]!r}"
+            )
+        if not fields:
+            cmd.pfeedback("  (no fields)")

cmdargparse/parser.py

@@ -0,0 +1,40 @@
+from typing import Annotated, Any
+
+import cmd2
+
+
+# ################################ PARSER ######################################
+
+
+class ArgumentParser(cmd2.Cmd2ArgumentParser):
+
+    # Registers a custom argparse argument parameter.
+    #   https://cmd2.readthedocs.io/en/stable/api/argparse_custom/#cmd2.argparse_custom.register_argparse_argument_parameter
+    #   ```
+    #     def register_argparse_argument_parameter(
+    #         param_name: str,
+    #         param_type: Optional[Type[Any]],
+    #     ) -> None: ...
+    #   ```
+
+    def __init__(
+        self,
+        *args: Annotated[Any, "passthrough"],
+        **kwargs: Annotated[Any, "passthrough"],
+    ) -> None:
+        super(cmd2.Cmd2ArgumentParser, self).__init__(*args, **kwargs)
+
+        from .actions import StoreAction
+
+        self.register("action", None, StoreAction)
+        self.register("action", "store", StoreAction)
+        # self.register('action', 'store_const', _StoreConstAction)
+        # self.register('action', 'store_true', _StoreTrueAction)
+        # self.register('action', 'store_false', _StoreFalseAction)
+        # self.register('action', 'append', _AppendAction)
+        # self.register('action', 'append_const', _AppendConstAction)
+        # self.register('action', 'count', _CountAction)
+        # self.register('action', 'help', _HelpAction)
+        # self.register('action', 'version', _VersionAction)
+        # self.register('action', 'parsers', _SubParsersAction)
+        # self.register('action', 'extend', _ExtendAction)

cmdargparse/unset.py

@@ -0,0 +1,79 @@
+from typing import Any, Final, TypeAlias, TypeIs, TypeVar
+
+
+# ################################ PACKAGE #####################################
+
+
+__sname__ = "unset"
+__version__ = "1.3"
+__description__ = ...
+
+__requires__ = ()
+
+
+__all__ = (
+    # fmt: off
+    "UnsetType", "UNSET", "Unset",
+    "isunset", "on_unset",
+    # fmt: on
+)
+
+
+# ################################ TYPING ######################################
+
+
+T = TypeVar("T")
+
+TONCE: TypeAlias = Any
+
+
+# ################################ UNSET #######################################
+
+
+class _UnsetType(type):
+
+    def __invert__(self) -> "UnsetType":
+        """Returns the unset value."""
+        global UNSET
+        return UNSET
+
+
+class UnsetType(object, metaclass=_UnsetType):
+    """Type of the unset value."""
+
+    pass
+
+
+UNSET: Final = UnsetType()
+"""Value to use if unset."""
+
+
+# ###################### CONVENIENCE #######################
+
+
+Unset: TypeAlias = UnsetType
+"""
+The `Unset` attribute is a convenience alias to simplify the usage of the
+`UnsetType` and `UNSET` attributes.
+
+It can be used as follows:
+```
+def function(arg: Type | Unset = ~Unset):
+    arg = arg if not isunset(arg) else VALUE
+    arg = on_unset(arg, VALUE)
+```
+"""
+
+
+# ################################ FUNCTIONS ###################################
+
+
+def isunset(obj: Any, /) -> TypeIs[UnsetType]:
+    """Returns true if the object is unset."""
+    return obj is UNSET
+
+
+def on_unset(obj: T | Unset, value: TONCE, /) -> T | TONCE:
+    """Returns either the object itself or the specified value if the object is
+    unset."""
+    return value if obj is UNSET else obj

cmdargparse-0.1.0.dist-info/METADATA

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: cmdargparse
+Version: 0.1.0
+Summary: A declarative way to define `cmd2` argument parsers.
+Home-page: https://github.com/krnd/cmdargparse
+Author: Kilian Kaiping (krnd)
+License: MIT
+Keywords: CLI,cmd,command,interactive,prompt,Python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Plugins
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cmd2~=2.7
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# cmdargparse
+
+[![pypi](https://img.shields.io/pypi/v/cmdargparse?style=for-the-badge)](https://pypi.org/project/cmdargparse)
+[![license](https://img.shields.io/pypi/l/cmdargparse?style=for-the-badge)](https://github.com/krnd/cmdargparse/blob/main/LICENSE)
+
+The package provides a declarative way to define `cmd2` argument parsers.
+
+
+## Usage
+<!----------------------------------------------------------------------------->
+
+The core functionality is driven by three components:
+* `cmdargument` for defining an argument parser
+* `cmdfield` for declaring the arguments
+* `cmdcommand` for attatching an argument parser to a command
+
+```py
+
+class MyApplication(cmd2.Cmd):
+
+    @cmdargument
+    class _MyCommandArgs(cmdargument):
+        my_argument: str = cmdfield.argument(...)
+        my_option: str = cmdfield.option(...)
+        my_flag: str = cmdfield.flag(...)
+
+    @cmdcommand(_MyCommandArgs)
+    def do_mycommand(self, args: _MyCommandArgs) -> None:
+        args.pfields(self)
+
+```
+
+*[Example Application](./launch/__main__.py)*
+
+
+### Arguments (positional)
+
+* `choices` <br/>
+    The restricted set of values allowed for the argument.
+* `choicesmap` <br/>
+    Additional values allowed for the argument that each map to the
+    specified value in the restricted set of values.
+* `default` <br/>
+    The arguments default value if not specified.
+    <br/> (Providing a default value makes the argument optional.)
+* `type` <br/>
+    Explicitly specifies the `type` to be used by `argparse`.
+    <br/> https://docs.python.org/3/library/argparse.html#type
+* `help` <br/>
+    Brief description of the argument.
+* `helpvar` <br/>
+    Reference name of the argument value in the help message.
+
+#### Examples
+```py
+arg: str | None = cmdfield.argument(
+    ("alpha", "beta"),
+    {
+        "a": "alpha",
+        "b": "beta",
+    },
+    default=None,
+)
+```
+
+
+### Options (non-positional, value-bound)
+
+* `decl` <br/>
+    Specifies the primary option declaration.
+* `altdecl` <br/>
+    Specifies the alternative option declaration.
+* `choices` <br/>
+    The restricted set of values allowed for the option.
+* `choicesmap` <br/>
+    Additional values allowed for the option that each map to the
+    specified value in the restricted set of values.
+* `default` <br/>
+    The options default value if not specified.
+* `form` <br/>
+    Specifies the default form of the option declaration.
+* `decls` <br/>
+    Explicitly specifies all option declarations.
+* `more_decls` <br/>
+    Specifies additional option declarations.
+* `type` <br/>
+    Explicitly specifies the `type` to be used by `argparse`.
+    <br/> https://docs.python.org/3/library/argparse.html#type
+* `required` <br/>
+    Marks the option as required.
+* `help` <br/>
+    Brief description of the option.
+* `helpvar` <br/>
+    Reference name of the option value in the help message.
+
+#### Examples
+```py
+xx: str | None = cmdfield.option()
+yy: int | None = cmdfield.option([1, 2, 3])
+zz: str = cmdfield.option(required=True)
+```
+
+#### Declarations
+```py
+aa: str | None = cmdfield.option()                       # -aa  OR  --aa
+bb: str | None = cmdfield.option("--cc")                 # -bb, --cc  OR  --cc
+dd: str | None = cmdfield.option("-ee")                  # -ee  OR  --dd, -ee
+ff: str | None = cmdfield.option("--gg", "-ii")          # --gg, -ii
+jj: str | None = cmdfield.option(form="--")              # --jj
+kk: str | None = cmdfield.option(form="-")               # -kk
+mm: str | None = cmdfield.option(decls="--mm")           # --mm
+nn: str | None = cmdfield.option(decls="-oo")            # -oo
+pp: str | None = cmdfield.option(decls=("--rr", "-ss"))  # --rr, -ss
+tt: str | None = cmdfield.option(more_decls="-uu")       # -tt, -uu
+```
+
+
+### Flags (non-positional, non-value)
+
+* `decl` <br/>
+    Specifies the primary flag declaration.
+* `altdecl` <br/>
+    Specifies the alternative flag declaration.
+* `invert` <br/>
+    Sets the value `False` instead of `True` if the flag is specified.
+* `const` <br/>
+    The value to set if the flag is specified.
+* `form` <br/>
+    Specifies the default form of the flag declaration.
+* `decls` <br/>
+    Explicitly specifies all flag declarations.
+* `more_decls` <br/>
+    Specifies additional flag declarations.
+* `type` <br/>
+    Explicitly specifies the type to be used by argparse.
+    <br/> https://docs.python.org/3/library/argparse.html#type
+* `help` <br/>
+    Brief description of the flag.
+
+#### Examples
+```py
+vv: bool = cmdfield.flag()
+ww: bool = cmdfield.flag(invert=True)
+xx: float | None = cmdfield.flag(const=1.23)
+yy: str | None = cmdfield.flag(const="text")
+zz: Literal["ltr"] | None = cmdfield.flag(const="ltr")
+```
+
+#### Declarations
+```py
+aa: bool = cmdfield.flag()                       # -aa  OR  --aa
+bb: bool = cmdfield.flag("--cc")                 # -bb, --cc  OR  --cc
+dd: bool = cmdfield.flag("-ee")                  # -ee  OR  --dd, -ee
+ff: bool = cmdfield.flag("--gg", "-ii")          # --gg, -ii
+jj: bool = cmdfield.flag(form="--")              # --jj
+kk: bool = cmdfield.flag(form="-")               # -kk
+mm: bool = cmdfield.flag(decls="--mm")           # --mm
+nn: bool = cmdfield.flag(decls="-oo")            # -oo
+pp: bool = cmdfield.flag(decls=("--rr", "-ss"))  # --rr, -ss
+tt: bool = cmdfield.flag(more_decls="-uu")       # -tt, -uu
+```
+
+
+## Q&A
+<!----------------------------------------------------------------------------->
+
+
+#### Changing the default declaration form
+
+The `cmdargument` decorator accepts a `form` argument to select the default
+declaration form for an argument parser, which can be either *-name* (default)
+or *--name*.
+
+It is also possible to change the global default declaration form by using the
+`cmdargument.default_form` function.

cmdargparse-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+cmdargparse/__init__.py,sha256=weTQyPCVDyw9PWtStk9-nwvgO6qJinGC2dX2aXjlHUs,251
+cmdargparse/argument.py,sha256=vx658i7Qgb6m_JhMddNeIuH47xe8OyfGiyGxziWDn_0,2294
+cmdargparse/command.py,sha256=RhSla4WddgfGXhy50CfYVu_ic-rkji7cZOk2EaO800Y,5926
+cmdargparse/custom.py,sha256=3uJ5mdsJGhkmsOU1IYO69h4sEHgyhDh40lYm_EdqSus,3124
+cmdargparse/field.py,sha256=SMcPRYZ3XJeHCT-LPQF8P4G91fMPXldm2_Hb0irpkG8,21203
+cmdargparse/namespace.py,sha256=SLeaH-49fm3qv8MNZo0HzjFHnr1SsRzLk_00pPn5PXo,984
+cmdargparse/parser.py,sha256=UYFHXrQcOokuqxRnoP5iVvwbE6pMQQVIcGXRLInNrgg,1567
+cmdargparse/unset.py,sha256=QWNkd6t7c3-8K7EPnZJIt0QAPcVKg4rRqiNVPjVCdB8,1687
+cmdargparse-0.1.0.dist-info/licenses/LICENSE,sha256=ZbjvSbpbnaBM1xeQH0Ox4GsHxGMA7KhWUVsO3owGe94,1099
+cmdargparse-0.1.0.dist-info/METADATA,sha256=ebZ06w12jHGyyAWOsKm4yXH-IN_pPkQM0KGiLXXn_GY,7002
+cmdargparse-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cmdargparse-0.1.0.dist-info/top_level.txt,sha256=afbiyImfO4prsVte-5tYouF4u6dLVAfj7W-JfDtsz7E,12
+cmdargparse-0.1.0.dist-info/RECORD,,

cmdargparse-0.1.0.dist-info/WHEEL

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

cmdargparse-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kilian Kaiping (krnd)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cmdargparse-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cmdargparse