paramspecli 0.2.1__tar.gz → 0.3.0__tar.gz

{paramspecli-0.2.1 → paramspecli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramspecli
-Version: 0.2.1
+Version: 0.3.0
 Summary: Type-safe facade for the venerable argparse
 Author: jkmnt
 Requires-Python: >=3.12
@@ -78,7 +78,7 @@ pip install paramspecli
 - Commands match handler functions parameters with arguments and options.
 - Arguments are bound to the handler's positional parameters.
 - Options are bound to the handler's keyword parameters.
-- Groups organize the commands. Groups may be nested. They could act like like an intermediate commands, i.e. have own handlers, options and arguments.
+- Groups organize the commands. Groups may be nested. They could act like an intermediate commands, i.e. have own handlers, options and arguments.
 - CLI 'compiles' to the `argparse`, runs it, then outputs the parse result.
 - Parse result is a callable. Calling it invokes handlers along the route.
 

{paramspecli-0.2.1 → paramspecli-0.3.0}/README.md

@@ -64,7 +64,7 @@ pip install paramspecli
 - Commands match handler functions parameters with arguments and options.
 - Arguments are bound to the handler's positional parameters.
 - Options are bound to the handler's keyword parameters.
-- Groups organize the commands. Groups may be nested. They could act like like an intermediate commands, i.e. have own handlers, options and arguments.
+- Groups organize the commands. Groups may be nested. They could act like an intermediate commands, i.e. have own handlers, options and arguments.
 - CLI 'compiles' to the `argparse`, runs it, then outputs the parse result.
 - Parse result is a callable. Calling it invokes handlers along the route.
 

{paramspecli-0.2.1 → paramspecli-0.3.0}/pyproject.toml

@@ -64,6 +64,7 @@ ignore = [
 ]
 
 [tool.pyright]
+include = ["src", "tests"]
 # typeCheckingMode = "strict"
 typeCheckingMode = "standard"
 useLibraryCodeForTypes = true

{paramspecli-0.2.1 → paramspecli-0.3.0}/src/paramspecli/__init__.py

@@ -1,20 +1,23 @@
 """Type-safe facade for the venerable argparse"""
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 
 
+from .acts import custom_action as custom_action
+from .acts import version_action as version_action
 from .args import argument as argument
-from .cli import Action as Action
+from .cli import MISSING as MISSING
 from .cli import CallableGroup as CallableGroup
 from .cli import Command as Command
 from .cli import Config as Config
 from .cli import Group as Group
 from .cli import Handler as Handler
+from .cli import Missing as Missing
 from .cli import Route as Route
 from .cli import help_action as help_action
-from .cli import version_action as version_action
+from .const import const as const
 from .conv import PathConv as PathConv
-from .fake import Const as Const
+from .exc import ParseAgain as ParseAgain
 from .fake import Context as Context
 from .fake import deprecated as deprecated
 from .fake import required as required
@@ -25,3 +28,6 @@ from .flags import repeated_flag as repeated_flag
 from .flags import switch as switch
 from .opts import option as option
 from .opts import repeated_option as repeated_option
+
+# compat
+Const = const

paramspecli-0.3.0/src/paramspecli/acts.py

@@ -0,0 +1,159 @@
+import argparse
+from typing import Any, Iterable, Literal, NoReturn, overload
+
+from . import util
+from .apstub import TypeConverter
+from .cli import MISSING, Action, ActionHandler, Markup, Missing
+
+
+@overload
+def custom_action(
+    *names: str,
+    handler: ActionHandler[str],
+    default: Any = None,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[Any] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = False,
+) -> Action[str]: ...
+
+
+# nargs=0
+@overload
+def custom_action(
+    *names: str,
+    handler: ActionHandler[None],
+    nargs: Literal[0],
+    default: Any = None,
+    #
+    help: str | bool | Markup | None = None,
+    show_default: bool | str | None = False,
+) -> Action[None]: ...
+
+
+# nargs
+@overload
+def custom_action(
+    *names: str,
+    handler: ActionHandler[list[str]],
+    nargs: int | Literal["+", "*"],
+    default: Any = None,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[Any] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = False,
+) -> Action[list[str]]: ...
+
+
+# optional
+@overload
+def custom_action(
+    *names: str,
+    handler: ActionHandler[str],
+    nargs: Literal["?"],
+    default: Any = None,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[Any] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = False,
+) -> Action[str | Missing]: ...
+
+
+# T
+@overload
+def custom_action[T](
+    *names: str,
+    handler: ActionHandler[T],
+    type: TypeConverter[T],
+    default: Any = None,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[Any] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = False,
+) -> Action[T]: ...
+
+
+# T, nargs
+@overload
+def custom_action[T](
+    *names: str,
+    handler: ActionHandler[list[T]],
+    type: TypeConverter[T],
+    nargs: int | Literal["+", "*"],
+    default: Any = None,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[Any] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = False,
+) -> Action[list[T]]: ...
+
+
+# T, optional
+@overload
+def custom_action[T](
+    *names: str,
+    handler: ActionHandler[T | Missing],
+    type: TypeConverter[T],
+    nargs: Literal["?"],
+    default: Any = None,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[Any] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = False,
+) -> Action[T | Missing]: ...
+
+
+def custom_action(
+    *names: str,
+    handler: ActionHandler[Any],
+    type: TypeConverter[Any] | None = None,
+    nargs: int | Literal["+", "*", "?"] | None = None,
+    default: Any = None,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[Any] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = False,
+) -> Action[Any]:
+    """Custom action calling the `handler` upon the option match"""
+    if metavar is None and choices is None and nargs != 0:
+        metavar = names[0].lstrip("-").upper()
+
+    return Action(
+        names,
+        handler=handler,
+        help=help,
+        conv=type,
+        nargs=nargs,
+        default=default,
+        const=MISSING if nargs == "?" else None,
+        choices=choices,
+        metavar=metavar,
+        #
+        hard_show_default=show_default,
+        soft_show_default=default is not None and default != [],
+    )
+
+
+class _VersionPrinter:
+    def __init__(self, version: str):
+        self.version = version
+
+    def __call__(self, *, parser: argparse.ArgumentParser, **kwargs: Any) -> NoReturn:
+        util.echo(self.version)
+        parser.exit(0)
+
+
+def version_action(
+    version: str,
+    *,
+    help: str | Markup | bool = "Show program's version number and exit",
+    names: tuple[str, ...] = ("--version",),
+) -> Action[None]:
+    return Action(names, help=help, nargs=0, handler=_VersionPrinter(version))

{paramspecli-0.2.1 → paramspecli-0.3.0}/src/paramspecli/apstub.py

@@ -81,4 +81,4 @@ class ArgumentParserLike(
     def exit(self, status: int = ..., message: str | None = ...) -> NoReturn: ...
 
 
-class ArgumentGroupLike(SupportsAddArgument, SupportsAddOneofGroup, Protocol): ...
+class ArgumentGroupLike(SupportsAddArgument, SupportsAddOneofGroup, SupportsSetDefaults, Protocol): ...

paramspecli-0.3.0/src/paramspecli/args.py

@@ -0,0 +1,164 @@
+from typing import Any, Iterable, Literal, overload
+
+from .apstub import TypeConverter
+from .cli import Markup
+from .fake import Argument
+
+
+# 1.
+# {'type': 'None', 'nargs': 'None'}
+@overload
+def argument(
+    metavar: str,
+    *,
+    #
+    type: None = None,
+    nargs: None = None,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[str] | None = None,
+) -> Argument[str, str]: ...
+
+
+# 2.
+# {'type': 'None', 'nargs': 'int | Literal["*", "+"]'}
+@overload
+def argument(
+    metavar: str,
+    *,
+    #
+    type: None = None,
+    nargs: int | Literal["*", "+"],
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[str] | None = None,
+) -> Argument[list[str], list[str]]: ...
+
+
+# 3.
+# {'type': 'None', 'nargs': 'Literal["?"]', 'default': 'None'}
+@overload
+def argument(
+    metavar: str,
+    *,
+    #
+    type: None = None,
+    nargs: Literal["?"],
+    default: None = None,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[str] | None = None,
+) -> Argument[str, None]: ...
+
+
+# 4.
+# {'type': 'None', 'nargs': 'Literal["?"]', 'default': 'D'}
+@overload
+def argument[D](
+    metavar: str,
+    *,
+    #
+    type: None = None,
+    nargs: Literal["?"],
+    default: D,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[str] | None = None,
+) -> Argument[str, D]: ...
+
+
+# 5.
+# {'type': 'TypeConverter[T]', 'nargs': 'None'}
+@overload
+def argument[T](
+    metavar: str,
+    *,
+    #
+    type: TypeConverter[T],
+    nargs: None = None,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[T] | None = None,
+) -> Argument[T, T]: ...
+
+
+# 6.
+# {'type': 'TypeConverter[T]', 'nargs': 'int | Literal["*", "+"]'}
+@overload
+def argument[T](
+    metavar: str,
+    *,
+    #
+    type: TypeConverter[T],
+    nargs: int | Literal["*", "+"],
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[T] | None = None,
+) -> Argument[list[T], list[T]]: ...
+
+
+# 7.
+# {'type': 'TypeConverter[T]', 'nargs': 'Literal["?"', 'default': 'None'}
+@overload
+def argument[T](
+    metavar: str,
+    *,
+    #
+    type: TypeConverter[T],
+    nargs: Literal["?"],
+    default: None = None,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[T] | None = None,
+) -> Argument[T, None]: ...
+
+
+# 8.
+# {'type': 'TypeConverter[T]', 'nargs': 'Literal["?"', 'default': 'str'}
+@overload
+def argument[T, D](
+    metavar: str,
+    *,
+    #
+    type: TypeConverter[T],
+    nargs: Literal["?"],
+    default: str,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[T] | None = None,
+) -> Argument[T, T]: ...
+
+
+# 8.
+# {'type': 'TypeConverter[T]', 'nargs': 'Literal["?"', 'default': 'D'}
+@overload
+def argument[T, D](
+    metavar: str,
+    *,
+    #
+    type: TypeConverter[T],
+    nargs: Literal["?"],
+    default: D,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[T] | None = None,
+) -> Argument[T, D]: ...
+
+
+def argument(
+    metavar: str,
+    *,
+    #
+    type: TypeConverter[Any] | None = None,
+    nargs: int | Literal["*", "+", "?"] | None = None,
+    default: Any | None = None,
+    #
+    help: str | bool | Markup | None = None,
+    choices: Iterable[Any] | None = None,
+) -> Argument[Any, Any]:
+    """Positional argument. Always required, unless made optional via `nargs="?"`."""
+
+    if isinstance(nargs, int) and nargs <= 0:
+        raise ValueError("Arguments could not have nargs == 0")
+
+    return Argument(metavar, help=help, conv=type, choices=choices, nargs=nargs, default=default)