panda-cli 0.2.0__tar.gz → 0.3.0__tar.gz

panda_cli-0.3.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.5
+Name: panda-cli
+Version: 0.3.0
+Summary: Declarative CLI framework: commands are Pydantic models, built on Click
+Author-email: meleshuk0804@gmail.com
+Keywords: cli,click,command-line,declarative,pydantic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: click>=8.3.1
+Requires-Dist: pydantic>=2.12.5
+Description-Content-Type: text/markdown
+
+# panda-cli
+
+A lightweight declarative CLI framework built on top of Click and Pydantic.
+
+Define commands as Python classes, describe arguments with type hints,
+and build CLI trees using simple class composition.
+
+---
+
+## Features
+
+- Declarative CLI commands
+- Type-safe arguments
+- Automatic CLI tree generation
+- Built-in validation via Pydantic
+- Validation errors reported in command-line terms (`--port`, not `port`)
+- Minimal boilerplate
+- Nested command groups
+
+---
+
+## Installation
+
+```bash
+pip install panda-cli
+```
+
+
+## Quick Example
+```python
+from panda_cli import BaseCommand, Option, BaseGroup
+from panda_cli import Config
+
+
+class WebCli(BaseCommand): 
+    """ Web server """ # automaticly add to web --help
+    __cli_name__ = "web"
+
+    config=Config(fields_name_to_flag=True)  # if True auto gen flag by field name host -> --host
+
+    host: str = Option(
+        "--host",
+        default="127.0.0.1",
+        description="Host to listen on",
+    )
+
+    port: int = Option(
+        "--port",
+        default=8000,
+    )
+
+    methods: list[str] # --methods GET --methods POST -> ['GET', 'POST']
+
+    map: dict[str, str] # --map key=value --map key2=value2 -> {'key': 'value', 'key2': 'value2'}
+
+    def __exec__(self) -> None:
+        """ Automaticly runs when command is called """
+    
+        print(f"Host: {self.host}")
+        print(f"Port: {self.port}")
+        print(f"Methods: {self.methods}")
+        print(f"Map: {self.map}")
+
+
+class MainCli(BaseGroup):
+    __cli_name__ = "main"
+
+
+    web: WebCli
+
+
+def main():
+    MainCli.run()
+
+
+if __name__ == "__main__":
+    main()
+```
+
+
+## CLI
+```bash
+uv run examples/web.py --help
+
+        Usage: main [OPTIONS] COMMAND [ARGS]...
+
+        Options:
+        --help  Show this message and exit.
+
+        Commands:
+        web  Web server
+```
+
+```bash
+uv run examples/web.py web --help
+
+        Usage: main web [OPTIONS]
+
+        Web server
+
+        Options:
+        --host TEXT                 Host to listen on  [default: 127.0.0.1]
+        --port INTEGER              [default: 8000]
+        --methods Iterable TEXT...  [required]
+        --map TEXT=TEXT             [required]
+        --help                      Show this message and exit.
+```
+
+
+## Validation
+
+Any Pydantic validator works, and failures are shown the way a CLI user
+expects them — not as a traceback:
+
+```python
+from pydantic import Field
+
+class WebCli(BaseCommand):
+    __cli_name__ = "web"
+    port: int = Field(default=8000, ge=1, le=65535)
+
+    def __exec__(self) -> None: ...
+```
+
+```bash
+$ web --port 99999
+
+        Usage: web [OPTIONS]
+        Try 'web --help' for help.
+
+        Error: Invalid value for '--port': Input should be less than or equal to 65535
+```
+
+
+## Environment variables
+
+```python
+host: str = Option("--host", default="127.0.0.1", envvar="APP_HOST")
+```
+
+
+## Embedding into an existing Click app
+
+`run()` is the entry point for `console_scripts`, but the built command is
+also available on its own — useful for mounting a panda-cli tree inside a
+Click application, and for testing:
+
+```python
+import click
+
+cli = click.Group("myapp")
+cli.add_command(MainCli.as_click())
+```
+
+`MainCli.spec()` returns the same tree as backend-independent dataclasses,
+without touching Click at all.
+
+
+## Architecture
+
+```
+declaration   BaseCommand / BaseGroup — what the user writes
+introspect    model -> Spec           — the only module that imports pydantic
+backend       Spec -> click.Command   — the only module that imports click
+runtime       argv -> validate -> __exec__
+```
+
+Subcommands are declared as fields (`web: WebCli`) but are not model fields:
+the metaclass moves them into the command tree before Pydantic sees them, so
+a group stays an ordinary model with its own options.
+
+
+## Development
+
+```bash
+make test        # run the test suite
+make cov         # coverage
+make regression  # tests guarding previously fixed bugs
+make check       # lint + tests
+```

panda_cli-0.3.0/README.md

@@ -0,0 +1,180 @@
+# panda-cli
+
+A lightweight declarative CLI framework built on top of Click and Pydantic.
+
+Define commands as Python classes, describe arguments with type hints,
+and build CLI trees using simple class composition.
+
+---
+
+## Features
+
+- Declarative CLI commands
+- Type-safe arguments
+- Automatic CLI tree generation
+- Built-in validation via Pydantic
+- Validation errors reported in command-line terms (`--port`, not `port`)
+- Minimal boilerplate
+- Nested command groups
+
+---
+
+## Installation
+
+```bash
+pip install panda-cli
+```
+
+
+## Quick Example
+```python
+from panda_cli import BaseCommand, Option, BaseGroup
+from panda_cli import Config
+
+
+class WebCli(BaseCommand): 
+    """ Web server """ # automaticly add to web --help
+    __cli_name__ = "web"
+
+    config=Config(fields_name_to_flag=True)  # if True auto gen flag by field name host -> --host
+
+    host: str = Option(
+        "--host",
+        default="127.0.0.1",
+        description="Host to listen on",
+    )
+
+    port: int = Option(
+        "--port",
+        default=8000,
+    )
+
+    methods: list[str] # --methods GET --methods POST -> ['GET', 'POST']
+
+    map: dict[str, str] # --map key=value --map key2=value2 -> {'key': 'value', 'key2': 'value2'}
+
+    def __exec__(self) -> None:
+        """ Automaticly runs when command is called """
+    
+        print(f"Host: {self.host}")
+        print(f"Port: {self.port}")
+        print(f"Methods: {self.methods}")
+        print(f"Map: {self.map}")
+
+
+class MainCli(BaseGroup):
+    __cli_name__ = "main"
+
+
+    web: WebCli
+
+
+def main():
+    MainCli.run()
+
+
+if __name__ == "__main__":
+    main()
+```
+
+
+## CLI
+```bash
+uv run examples/web.py --help
+
+        Usage: main [OPTIONS] COMMAND [ARGS]...
+
+        Options:
+        --help  Show this message and exit.
+
+        Commands:
+        web  Web server
+```
+
+```bash
+uv run examples/web.py web --help
+
+        Usage: main web [OPTIONS]
+
+        Web server
+
+        Options:
+        --host TEXT                 Host to listen on  [default: 127.0.0.1]
+        --port INTEGER              [default: 8000]
+        --methods Iterable TEXT...  [required]
+        --map TEXT=TEXT             [required]
+        --help                      Show this message and exit.
+```
+
+
+## Validation
+
+Any Pydantic validator works, and failures are shown the way a CLI user
+expects them — not as a traceback:
+
+```python
+from pydantic import Field
+
+class WebCli(BaseCommand):
+    __cli_name__ = "web"
+    port: int = Field(default=8000, ge=1, le=65535)
+
+    def __exec__(self) -> None: ...
+```
+
+```bash
+$ web --port 99999
+
+        Usage: web [OPTIONS]
+        Try 'web --help' for help.
+
+        Error: Invalid value for '--port': Input should be less than or equal to 65535
+```
+
+
+## Environment variables
+
+```python
+host: str = Option("--host", default="127.0.0.1", envvar="APP_HOST")
+```
+
+
+## Embedding into an existing Click app
+
+`run()` is the entry point for `console_scripts`, but the built command is
+also available on its own — useful for mounting a panda-cli tree inside a
+Click application, and for testing:
+
+```python
+import click
+
+cli = click.Group("myapp")
+cli.add_command(MainCli.as_click())
+```
+
+`MainCli.spec()` returns the same tree as backend-independent dataclasses,
+without touching Click at all.
+
+
+## Architecture
+
+```
+declaration   BaseCommand / BaseGroup — what the user writes
+introspect    model -> Spec           — the only module that imports pydantic
+backend       Spec -> click.Command   — the only module that imports click
+runtime       argv -> validate -> __exec__
+```
+
+Subcommands are declared as fields (`web: WebCli`) but are not model fields:
+the metaclass moves them into the command tree before Pydantic sees them, so
+a group stays an ordinary model with its own options.
+
+
+## Development
+
+```bash
+make test        # run the test suite
+make cov         # coverage
+make regression  # tests guarding previously fixed bugs
+make check       # lint + tests
+```

panda_cli-0.3.0/examples/web.py

@@ -0,0 +1,47 @@
+from panda_cli import BaseCommand, Option, BaseGroup
+from panda_cli import Config
+
+
+class WebCli(BaseCommand):
+    """Web server"""  # automaticly add to web --help
+
+    __cli_name__ = "web"
+
+    config = Config(fields_name_to_flag=True)  # if True auto gen flag by field name host -> --host
+
+    host: str = Option(
+        "--host",
+        default="127.0.0.1",
+        description="Host to listen on",
+    )
+
+    port: int = Option(
+        "--port",
+        default=8000,
+    )
+
+    methods: list[str]  # --methods GET --methods POST -> ['GET', 'POST']
+
+    map: dict[str, str]  # --map key=value --map key2=value2 -> {'key': 'value', 'key2': 'value2'}
+
+    def __exec__(self) -> None:
+        """Automaticly runs when command is called"""
+
+        print(f"Host: {self.host}")
+        print(f"Port: {self.port}")
+        print(f"Methods: {self.methods}")
+        print(f"Map: {self.map}")
+
+
+class MainCli(BaseGroup):
+    __cli_name__ = "main"
+
+    web: WebCli
+
+
+def main():
+    MainCli.run()
+
+
+if __name__ == "__main__":
+    main()

{panda_cli-0.2.0 → panda_cli-0.3.0}/makefile

@@ -1,4 +1,4 @@
-.PHONY: major minor patch
+.PHONY: major minor patch test cov regression lint check
 
 PYPROJECT := pyproject.toml
 INIT_FILE := src/panda_cli/__init__.py
@@ -22,4 +22,19 @@ minor:
 	$(call bump,$(MAJOR).$(shell echo $$(($(MINOR)+1))).0)
 
 patch:
-	$(call bump,$(MAJOR).$(MINOR).$(shell echo $$(($(PATCH)+1))))
+	$(call bump,$(MAJOR).$(MINOR).$(shell echo $$(($(PATCH)+1))))
+
+test:
+	uv run pytest
+
+cov:
+	uv run pytest --cov
+
+regression:  # тесты на закрытые баги
+	uv run pytest -m regression -rX
+
+lint:
+	uv run ruff check .
+	uv run ruff format --check .
+
+check: lint test

panda_cli-0.3.0/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "panda-cli"
+version = "0.3.0"
+description = "Declarative CLI framework: commands are Pydantic models, built on Click"
+readme = "README.md"
+authors = [
+    { email = "meleshuk0804@gmail.com" }
+]
+requires-python = ">=3.12"
+keywords = ["cli", "click", "pydantic", "command-line", "declarative"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "click>=8.3.1",
+    "pydantic>=2.12.5",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/panda_cli"]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.4",
+    "twine>=6.2.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q --strict-markers --strict-config"
+markers = [
+    "regression: тест на конкретный закрытый баг — не удалять при рефакторинге",
+]
+xfail_strict = true
+
+[tool.coverage.run]
+source = ["panda_cli"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = ["pragma: no cover", "raise NotImplementedError", "if t.TYPE_CHECKING:"]
+
+[tool.ruff]
+line-length = 100
+src = [".", "src"]
+exclude = ["_temp", "dist", ".venv"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+ignore = [
+    "RUF003", # кириллица в комментариях
+    "RUF001", # кириллица в строках — здесь это нормально
+    "RUF002", # кириллица в docstring'ах
+    "RUF012", # ClassVar для mutable-атрибутов: ложное срабатывание на полях pydantic
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["panda_cli", "tests"]
+
+[tool.ruff.lint.per-file-ignores]
+# пример повторяет README дословно — форматирование импортов оставлено как в доке
+"examples/*.py" = ["I001"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src/panda_cli", "tests"]

panda_cli-0.3.0/src/panda_cli/__init__.py

@@ -0,0 +1,15 @@
+from .base import BaseCommand, BaseGroup, Config
+from .errors import BindingError, DeclarationError, PandaCLIError
+from .option import Option
+
+__all__ = [
+    "BaseCommand",
+    "BaseGroup",
+    "BindingError",
+    "Config",
+    "DeclarationError",
+    "Option",
+    "PandaCLIError",
+]
+
+__version__ = "0.3.0"

panda_cli-0.3.0/src/panda_cli/annotations.py

@@ -0,0 +1,79 @@
+"""Аннотация Python → описание значения параметра.
+
+Чистый слой: только `typing`, никакого click и никакого pydantic.
+Развёртка `Optional` живёт здесь в единственном экземпляре — раньше она была
+скопирована в четырёх функциях, и в пятом месте про неё забыли.
+"""
+
+from __future__ import annotations
+
+import types
+import typing as t
+from dataclasses import dataclass
+
+from panda_cli.spec import (
+    Arity,
+    ChoiceType,
+    PairType,
+    ScalarType,
+    TypeSpec,
+    UnionType,
+)
+
+_SEQUENCE_ORIGINS: t.Final = (list, tuple, set, frozenset)
+
+
+def unwrap_optional(annotation: t.Any) -> t.Any:
+    """`X | None` → `X`. Всё остальное возвращается как есть."""
+    if t.get_origin(annotation) not in (t.Union, types.UnionType):
+        return annotation
+    args = [a for a in t.get_args(annotation) if a is not type(None)]
+    return args[0] if len(args) == 1 else annotation
+
+
+@dataclass(frozen=True)
+class Shape:
+    """Что аннотация говорит о параметре."""
+
+    type: TypeSpec
+    arity: Arity
+    collect_pairs: bool
+
+
+def describe(annotation: t.Any) -> Shape:
+    """Разобрать аннотацию поля в тип значения и арность."""
+    ann = unwrap_optional(annotation)
+    origin = t.get_origin(ann)
+
+    if origin is t.Literal:
+        choices = tuple(str(c) for c in t.get_args(ann))
+        return Shape(ChoiceType(choices), Arity.SINGLE, False)
+
+    if origin in (t.Union, types.UnionType):
+        members = tuple(_scalar(a) for a in t.get_args(ann) if a is not type(None))
+        return Shape(UnionType(members), Arity.SINGLE, False)
+
+    # Голые `dict` / `list` не имеют __origin__, но означают то же самое.
+    if origin is dict or ann is dict:
+        args = t.get_args(ann)
+        key = _scalar(args[0]) if args else ScalarType(str)
+        value = _scalar(args[1]) if len(args) > 1 else ScalarType(str)
+        return Shape(PairType(key, value), Arity.MULTIPLE, True)
+
+    if origin in _SEQUENCE_ORIGINS or ann in _SEQUENCE_ORIGINS:
+        args = t.get_args(ann)
+        inner = describe(args[0]).type if args else ScalarType(str)
+        return Shape(inner, Arity.MULTIPLE, False)
+
+    if ann is bool:
+        return Shape(ScalarType(bool), Arity.FLAG, False)
+
+    return Shape(_scalar(ann), Arity.SINGLE, False)
+
+
+def _scalar(annotation: t.Any) -> TypeSpec:
+    """Тип одного значения — без учёта контейнера."""
+    ann = unwrap_optional(annotation)
+    if t.get_origin(ann) is t.Literal:
+        return ChoiceType(tuple(str(c) for c in t.get_args(ann)))
+    return ScalarType(ann)

panda_cli-0.3.0/src/panda_cli/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Бэкенды: спецификация → конкретный парсер командной строки."""
+
+from panda_cli.backends.click_backend import build
+
+__all__ = ["build"]