paramspecli 0.2.2__tar.gz → 0.3.1__tar.gz

{paramspecli-0.2.2 → paramspecli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramspecli
-Version: 0.2.2
+Version: 0.3.1
 Summary: Type-safe facade for the venerable argparse
 Author: jkmnt
 Requires-Python: >=3.12

{paramspecli-0.2.2 → paramspecli-0.3.1}/pyproject.toml

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

{paramspecli-0.2.2 → paramspecli-0.3.1}/src/paramspecli/__init__.py

@@ -1,11 +1,12 @@
 """Type-safe facade for the venerable argparse"""
 
-__version__ = "0.2.2"
+__version__ = "0.3.1"
 
 
+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 MISSING as MISSING
-from .cli import Action as Action
 from .cli import CallableGroup as CallableGroup
 from .cli import Command as Command
 from .cli import Config as Config
@@ -14,9 +15,9 @@ 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 .consts 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
@@ -27,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.1/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.2 → paramspecli-0.3.1}/src/paramspecli/args.py

@@ -1,110 +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,
     *,
-    help: str | Literal[False] | None = None,
+    #
+    type: None = None,
+    nargs: None = None,
+    #
+    help: str | bool | Markup | None = None,
     choices: Iterable[str] | None = None,
 ) -> Argument[str, str]: ...
 
 
-## nargs
+# 2.
+# {'type': 'None', 'nargs': 'int | Literal["*", "+"]'}
 @overload
 def argument(
     metavar: str,
     *,
+    #
+    type: None = None,
     nargs: int | Literal["*", "+"],
-    help: str | Literal[False] | None = None,
+    #
+    help: str | bool | Markup | None = None,
     choices: Iterable[str] | None = None,
 ) -> Argument[list[str], list[str]]: ...
 
 
-## optional
+# 3.
+# {'type': 'None', 'nargs': 'Literal["?"]', 'default': 'None'}
 @overload
 def argument(
     metavar: str,
     *,
+    #
+    type: None = None,
     nargs: Literal["?"],
-    help: str | Literal[False] | None = None,
+    default: None = None,
+    #
+    help: str | bool | Markup | None = None,
     choices: Iterable[str] | None = None,
 ) -> Argument[str, None]: ...
 
 
-## optional, default: D
+# 4.
+# {'type': 'None', 'nargs': 'Literal["?"]', 'default': 'D'}
 @overload
 def argument[D](
     metavar: str,
     *,
+    #
+    type: None = None,
     nargs: Literal["?"],
     default: D,
-    help: str | Literal[False] | None = None,
+    #
+    help: str | bool | Markup | None = None,
     choices: Iterable[str] | None = None,
 ) -> Argument[str, D]: ...
 
 
-##  type: T
+# 5.
+# {'type': 'TypeConverter[T]', 'nargs': 'None'}
 @overload
 def argument[T](
     metavar: str,
     *,
+    #
     type: TypeConverter[T],
-    help: str | Literal[False] | None = None,
+    nargs: None = None,
+    #
+    help: str | bool | Markup | None = None,
     choices: Iterable[T] | None = None,
 ) -> Argument[T, T]: ...
 
 
-##  type: T, nargs
+# 6.
+# {'type': 'TypeConverter[T]', 'nargs': 'int | Literal["*", "+"]'}
 @overload
 def argument[T](
     metavar: str,
     *,
+    #
     type: TypeConverter[T],
     nargs: int | Literal["*", "+"],
-    help: str | Literal[False] | None = None,
+    #
+    help: str | bool | Markup | None = None,
     choices: Iterable[T] | None = None,
 ) -> Argument[list[T], list[T]]: ...
 
 
-## type: T, optional
+# 7.
+# {'type': 'TypeConverter[T]', 'nargs': 'Literal["?"', 'default': 'None'}
 @overload
 def argument[T](
     metavar: str,
     *,
+    #
     type: TypeConverter[T],
     nargs: Literal["?"],
-    help: str | Literal[False] | None = None,
+    default: None = None,
+    #
+    help: str | bool | Markup | None = None,
     choices: Iterable[T] | None = None,
 ) -> Argument[T, None]: ...
 
 
-## type: T, optional, default: str | D
-# default is parsed if string
+# 8.
+# {'type': 'TypeConverter[T]', 'nargs': 'Literal["?"', 'default': 'str'}
 @overload
 def argument[T, D](
     metavar: str,
     *,
+    #
     type: TypeConverter[T],
     nargs: Literal["?"],
-    help: str | Literal[False] | None = None,
-    default: str | D,
+    default: str,
+    #
+    help: str | bool | Markup | None = None,
     choices: Iterable[T] | None = None,
-) -> Argument[T, T | D]: ...
+) -> 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,
-    help: str | Literal[False] | 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)