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

panda_cli-0.3.0/.gitignore

@@ -0,0 +1,162 @@
+*.log
+*.pot
+*.pyc
+__pycache__/
+__pycache__
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+media
+.env
+*.py[cod]
+*$py.class
+
+*.so
+.idea/
+.DS_Store
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+
+*.manifest
+*.spec
+
+
+pip-log.txt
+pip-delete-this-directory.txt
+
+
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+
+*.mo
+
+
+
+instance/
+.webassets-cache
+
+
+.scrapy
+
+
+docs/_build/
+
+
+.pybuilder/
+target/
+
+
+.ipynb_checkpoints
+
+
+profile_default/
+ipython_config.py
+
+
+.pdm.toml
+
+
+__pypackages__/
+
+
+celerybeat-schedule
+celerybeat.pid
+
+
+*.sage.py
+
+
+
+.venv
+venv/
+env.bak/
+venv.bak/
+
+.spyderproject
+.spyproject
+
+
+.ropeproject
+
+
+/site
+
+
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+
+.pyre/
+
+
+.pytype/
+
+
+cython_debug/
+
+
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+.idea
+.DS_Store
+
+
+.idea/**/aws.xml
+
+
+.idea/**/contentModel.xml
+
+
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+
+.idea/**/gradle.xml
+.idea/**/libraries
+
+
+cmake-build-*/
+.stignore
+
+
+_temp
+dist
+tests

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.3.0/makefile

@@ -0,0 +1,40 @@
+.PHONY: major minor patch test cov regression lint check
+
+PYPROJECT := pyproject.toml
+INIT_FILE := src/panda_cli/__init__.py
+
+# Читаем текущую версию из pyproject.toml
+CURRENT := $(shell grep '^version = ' $(PYPROJECT) | sed 's/version = "\(.*\)"/\1/')
+MAJOR   := $(shell echo $(CURRENT) | cut -d. -f1)
+MINOR   := $(shell echo $(CURRENT) | cut -d. -f2)
+PATCH   := $(shell echo $(CURRENT) | cut -d. -f3)
+
+define bump
+	@echo UPDATED "$(CURRENT) → $(1)"
+	@sed -i 's/^version = ".*"/version = "$(1)"/' $(PYPROJECT)
+	@sed -i 's/^__version__ = ".*"/__version__ = "$(1)"/' $(INIT_FILE)
+endef
+
+major:
+	$(call bump,$(shell echo $$(($(MAJOR)+1))).0.0)
+
+minor:
+	$(call bump,$(MAJOR).$(shell echo $$(($(MINOR)+1))).0)
+
+patch:
+	$(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"]