paramspecli 0.2.1__py3-none-any.whl

paramspecli/__init__.py

@@ -0,0 +1,27 @@
+"""Type-safe facade for the venerable argparse"""
+
+__version__ = "0.2.1"
+
+
+from .args import argument as argument
+from .cli import Action as Action
+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 Route as Route
+from .cli import help_action as help_action
+from .cli import version_action as version_action
+from .conv import PathConv as PathConv
+from .fake import Const as Const
+from .fake import Context as Context
+from .fake import deprecated as deprecated
+from .fake import required as required
+from .fake import t as t
+from .flags import count as count
+from .flags import flag as flag
+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

paramspecli/apstub.py

@@ -0,0 +1,84 @@
+# Protocols are used since some of the needed argparse classes are internal, e.g. _SubParsersAction
+# Based on a typeshed with a small changes and omissions.
+import argparse
+from typing import Any, Callable, Iterable, NoReturn, Protocol
+
+type TypeConverter[T] = Callable[[str], T]
+
+
+class SupportsAddArgument(Protocol):
+    def add_argument(
+        self,
+        *names: str,
+        nargs: int | str | None = ...,
+        const: Any = ...,
+        default: Any = ...,
+        type: TypeConverter[Any] = ...,
+        choices: Iterable[Any] | None = ...,
+        action: str | type[argparse.Action] = ...,
+        required: bool = ...,
+        help: str | None = ...,
+        metavar: str | tuple[str, ...] | None = ...,
+        dest: str | None = ...,
+        version: str = ...,
+        **kwargs: Any,
+    ) -> argparse.Action: ...
+
+
+class SupportsSetDefaults(Protocol):
+    def set_defaults(self, **kwargs: Any) -> None: ...
+
+
+class SupportsAddOneofGroup(Protocol):
+    def add_mutually_exclusive_group(self, *, required: bool = ...) -> SupportsAddArgument: ...
+
+
+class SupportsAddParser(Protocol):
+    def add_parser(
+        self,
+        name: str,
+        *,
+        # own
+        help: str | None = ...,
+        aliases: tuple[str, ...] = ...,
+        # of ArgumentParser
+        usage: str | None = ...,
+        description: str | None = ...,
+        epilog: str | None = ...,
+        formatter_class: type[argparse.HelpFormatter] = ...,
+        allow_abbrev: bool = ...,
+        # NOTE: exit_on_error is broken in argparse. in same cases it's exit anyway
+        exit_on_error: bool = ...,
+        prog: str | None = ...,
+        add_help: bool = ...,
+        # untyped rest
+        **kwargs: Any,
+    ) -> "ArgumentParserLike": ...
+
+
+class SupportsAddArgumentGroup(Protocol):
+    def add_argument_group(self, title: str | None = ..., description: str | None = ...) -> "ArgumentGroupLike": ...
+
+
+class ArgumentParserLike(
+    SupportsAddArgument, SupportsAddArgumentGroup, SupportsAddOneofGroup, SupportsSetDefaults, Protocol
+):
+    def add_subparsers(
+        self,
+        *,
+        title: str = ...,
+        prog: str | None = ...,
+        # parser_class: type[argparse.ArgumentParser],
+        parser_class: type[Any],
+        required: bool = ...,
+        help: str | None = ...,
+        metavar: str | None = ...,
+        description: str | None = ...,
+        dest: str | None = None,
+    ) -> SupportsAddParser: ...
+
+    def print_help(self) -> None: ...
+    def exit(self, status: int = ..., message: str | None = ...) -> NoReturn: ...
+
+
+class ArgumentGroupLike(SupportsAddArgument, SupportsAddOneofGroup, Protocol): ...

paramspecli/args.py

@@ -0,0 +1,110 @@
+from typing import Any, Iterable, Literal, overload
+
+from .apstub import TypeConverter
+from .fake import Argument
+
+
+##
+@overload
+def argument(
+    metavar: str,
+    *,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+) -> Argument[str, str]: ...
+
+
+## nargs
+@overload
+def argument(
+    metavar: str,
+    *,
+    nargs: int | Literal["*", "+"],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+) -> Argument[list[str], list[str]]: ...
+
+
+## optional
+@overload
+def argument(
+    metavar: str,
+    *,
+    nargs: Literal["?"],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+) -> Argument[str, None]: ...
+
+
+## optional, default: D
+@overload
+def argument[D](
+    metavar: str,
+    *,
+    nargs: Literal["?"],
+    default: D,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+) -> Argument[str, D]: ...
+
+
+##  type: T
+@overload
+def argument[T](
+    metavar: str,
+    *,
+    type: TypeConverter[T],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+) -> Argument[T, T]: ...
+
+
+##  type: T, nargs
+@overload
+def argument[T](
+    metavar: str,
+    *,
+    type: TypeConverter[T],
+    nargs: int | Literal["*", "+"],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+) -> Argument[list[T], list[T]]: ...
+
+
+## type: T, optional
+@overload
+def argument[T](
+    metavar: str,
+    *,
+    type: TypeConverter[T],
+    nargs: Literal["?"],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+) -> Argument[T, None]: ...
+
+
+## type: T, optional, default: str | D
+# default is parsed if string
+@overload
+def argument[T, D](
+    metavar: str,
+    *,
+    type: TypeConverter[T],
+    nargs: Literal["?"],
+    help: str | Literal[False] | None = None,
+    default: str | D,
+    choices: Iterable[T] | None = None,
+) -> Argument[T, 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,
+    choices: Iterable[Any] | None = None,
+) -> Argument[Any, Any]:
+    """Positional argument. Always required, unless made optional via `nargs="?"`."""
+    return Argument(metavar, help=help, type=type, choices=choices, nargs=nargs, default=default)