paramspecli 0.2.1__tar.gz

paramspecli-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jkmnt
+
+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.

paramspecli-0.2.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: paramspecli
+Version: 0.2.1
+Summary: Type-safe facade for the venerable argparse
+Author: jkmnt
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+License-File: LICENSE
+Project-URL: Documentation, https://jkmnt.github.io/paramspecli
+Project-URL: Source, https://github.com/jkmnt/paramspecli
+
+# paramspecli
+
+**paramspecli** is a facade for the venerable [argparse](https://docs.python.org/3/library/argparse.html).
+It's simple, composable, and fun. But, most important, it's type-safe thanks to the [ParamSpec](https://docs.python.org/3/library/typing.html#typing.ParamSpec) magic.
+
+## Quick start
+
+```python
+from paramspecli import Command, argument, option, flag
+
+
+def ping(addr: str, *, until_stopped: bool, count: int | None):
+    print(f"Pinging {addr} ...")
+
+
+cli = Command(ping, prog="ping")
+cli.bind(
+    -argument("IP"),
+    until_stopped=-flag("-t"),
+    count=-option("-n", type=int),
+)
+
+result = cli.parse()
+result()
+```
+
+Running it:
+
+```
+$ python ping.py -t -n 10 127.0.0.1
+Pinging 127.0.0.1 ...
+```
+
+Type checker catches common errors:
+
+```python
+cli.bind(
+    # "bool" is not assignable to "str"
+    -argument("IP", type=bool),
+    # Type "bool | None" is not assignable to type "bool"
+    until_stopped=-flag("-t", default=None),
+    #
+    # Argument missing for parameter "count"
+)
+```
+
+IDE suggestions work too:
+
+<pre>
+cli.bind(⏎
+    <small>(<strong>addr: str</strong>, *, until_stopped: bool, count: int | None) -> None</small>
+</pre>
+
+## Installation
+
+```shell
+pip install paramspecli
+```
+
+## Key points
+
+**paramspecli** builds hierarchical CLIs with groups and commands.
+
+- 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.
+- 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** supports several advanced `argparse` features: help sections, mutually exclusive
+options, options with the same destination. And adds a few own, like const options and passing contexts. It also includes a markdown documentation generator.
+
+[Read the documentation](https://jkmnt.github.io/paramspecli)

paramspecli-0.2.1/README.md

@@ -0,0 +1,74 @@
+# paramspecli
+
+**paramspecli** is a facade for the venerable [argparse](https://docs.python.org/3/library/argparse.html).
+It's simple, composable, and fun. But, most important, it's type-safe thanks to the [ParamSpec](https://docs.python.org/3/library/typing.html#typing.ParamSpec) magic.
+
+## Quick start
+
+```python
+from paramspecli import Command, argument, option, flag
+
+
+def ping(addr: str, *, until_stopped: bool, count: int | None):
+    print(f"Pinging {addr} ...")
+
+
+cli = Command(ping, prog="ping")
+cli.bind(
+    -argument("IP"),
+    until_stopped=-flag("-t"),
+    count=-option("-n", type=int),
+)
+
+result = cli.parse()
+result()
+```
+
+Running it:
+
+```
+$ python ping.py -t -n 10 127.0.0.1
+Pinging 127.0.0.1 ...
+```
+
+Type checker catches common errors:
+
+```python
+cli.bind(
+    # "bool" is not assignable to "str"
+    -argument("IP", type=bool),
+    # Type "bool | None" is not assignable to type "bool"
+    until_stopped=-flag("-t", default=None),
+    #
+    # Argument missing for parameter "count"
+)
+```
+
+IDE suggestions work too:
+
+<pre>
+cli.bind(⏎
+    <small>(<strong>addr: str</strong>, *, until_stopped: bool, count: int | None) -> None</small>
+</pre>
+
+## Installation
+
+```shell
+pip install paramspecli
+```
+
+## Key points
+
+**paramspecli** builds hierarchical CLIs with groups and commands.
+
+- 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.
+- 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** supports several advanced `argparse` features: help sections, mutually exclusive
+options, options with the same destination. And adds a few own, like const options and passing contexts. It also includes a markdown documentation generator.
+
+[Read the documentation](https://jkmnt.github.io/paramspecli)

paramspecli-0.2.1/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "paramspecli"
+authors = [{ name = "jkmnt" }]
+readme = "README.md"
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dynamic = ["version", "description"]
+
+[project.urls]
+Source = "https://github.com/jkmnt/paramspecli"
+Documentation = "https://jkmnt.github.io/paramspecli"
+
+[tool.flit.sdist]
+exclude = ["tests/"]
+
+
+[tool.ruff]
+line-length = 120
+
+[tool.black]
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "UP",
+    "B",
+    "ANN0",
+    "I",
+    "SLOT",
+    "ICN",
+    "FBT",
+    "C4",
+    "LOG",
+    "RET",
+    "INT",
+    "RUF",
+    "PLE",
+    "T20",
+    "PT",
+]
+
+ignore = [
+    "SIM108",
+    "FBT003",
+    "RET504",
+    "RET505",
+    "E501",
+    "RUF015",
+    "UP035",
+    "C408",
+    "B009",
+    "B010",
+]
+
+[tool.pyright]
+# typeCheckingMode = "strict"
+typeCheckingMode = "standard"
+useLibraryCodeForTypes = true
+strictListInference = true
+strictSetInference = true
+strictDictionaryInference = true
+reportMissingImports = "error"
+# reportMissingTypeStubs = "none"
+reportMissingParameterType = "warning"
+reportUnnecessaryComparison = "information"
+reportUnnecessaryContains = "information"
+reportPrivateUsage = false
+
+[tool.ty.analysis]
+respect-type-ignore-comments = false
+
+[tool.ty.rules]
+assert-type-unspellable-subtype = "ignore"
+# ty type assertions are not compatible with mypy/pyright
+type-assertion-failure = "ignore"
+# fails to find pytest
+unresolved-import = "ignore"

paramspecli-0.2.1/src/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-0.2.1/src/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-0.2.1/src/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)