Metadata-Version: 2.4
Name: pyclifer
Version: 0.4.1
Summary: PYthon Command Line Interface Framework — decorator-driven CLI framework built on click-extra and rich-click
Project-URL: Homepage, https://bahamut45.github.io/pyclifer
Project-URL: Repository, https://github.com/bahamut45/pyclifer
Project-URL: Issues, https://github.com/bahamut45/pyclifer/issues
Project-URL: Documentation, https://bahamut45.github.io/pyclifer
Author-email: Nicolas JOUBERT <njoubert45@gmail.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click-extra<8.0.0,>=7.18.0
Requires-Dist: jinja2<4.0.0,>=3.1.0
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: pyyaml<7.0.0,>=6.0.3
Requires-Dist: rich-click<2.0.0,>=1.9.8
Requires-Dist: rich>=15.0.0
Requires-Dist: xmltodict<2.0.0,>=1.0.0
Provides-Extra: dev
Requires-Dist: git-cliff>=2.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: tox-uv>=1.0; extra == 'dev'
Requires-Dist: tox>=4.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mike>=2.1; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2.0,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/bahamut45/pyclifer/main/docs/assets/logo.png" alt="pyclifer logo" width="200">
</p>

# pyclifer

![version](https://img.shields.io/badge/version-0.4.1-green)
[![PyPI](https://img.shields.io/pypi/v/pyclifer)](https://pypi.org/project/pyclifer/)
[![codecov](https://codecov.io/gh/bahamut45/pyclifer/graph/badge.svg)](https://codecov.io/gh/bahamut45/pyclifer)

**PYthon Command Line Interface Framework** — a decorator-driven CLI framework built on
[click-extra](https://github.com/kdeldycke/click-extra) and [rich-click](https://github.com/ewels/rich-click).

pyclifer provides four decorators (`@app_group`, `@group`, `@command`, `@option`) that give
your CLI applications automatic configuration management, environment variable binding,
Rich-enhanced logging, global option propagation, and standardized output formatting —
with zero boilerplate.

## Installation

```bash
# pip
pip install pyclifer

# uv
uv add pyclifer

# poetry
poetry add pyclifer
```

Requires Python 3.10+.

## Development

Requires [Task](https://taskfile.dev/#/installation).

```bash
task install       # install dev + docs dependencies
pre-commit install # activate git hooks (ruff check + format on every commit)
```

```bash
task check         # lint + test
task test          # run test suite
task tox           # run tests across Python 3.10–3.13
```

```bash
task release:patch # bump patch version, commit, tag and push
task release:minor
task release:major
```

Run `task --list` to see all available tasks.

## Quick Start

```python
"""CLI application using pyclifer."""
from pyclifer import app_group, command, option, Response


@app_group(handle_response=True)
def main():
    """My CLI application."""
    pass


@main.command()
@option("--name", "-n", default="World", help="Your name")
def hello(name: str) -> Response:
    """Say hello."""
    return Response(success=True, message=f"Hello {name}!")


if __name__ == "__main__":
    main()
```

```bash
$ python app.py --help
 Usage: app.py [OPTIONS] COMMAND [ARGS]...

 My CLI application.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│     --version                                    Show the version and exit.  │
│     --log-file       FILE                        Path to the log file (with  │
│                                                  daily automatic rotation).  │
│                                                  [env var: MYAPP_LOG_FILE]   │
│ -v  --verbosity      LEVEL                       Either TRACE, DEBUG, INFO,  │
│                                                  WARNING, ERROR, CRITICAL.   │
│                                                  [env var: MYAPP_VERBOSITY]  │
│                                                  [default: WARNING]          │
│ -C  --config         CONFIG_PATH                 Configuration file          │
│                                                  location. Supports glob     │
│                                                  patterns and remote URLs.   │
│                                                  [env var: MYAPP_CONFIG]     │
│                                                  [default:                   │
│                                                  /etc/myapp/*.{toml,yaml,    │
│                                                  yml,json,ini,xml},          │
│                                                  ~/.config/myapp/*.{toml,    │
│                                                  yaml,yml,json,ini,xml}]     │
│ -o  --output-format  [json|yaml|table|rich|raw]  Specify the output format   │
│                                                  for the command. [env var:  │
│                                                  MYAPP_OUTPUT_FORMAT]        │
│                                                  [default: table]            │
│ -h  --help                                       Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ hello                       Say hello.                                       │
╰──────────────────────────────────────────────────────────────────────────────╯

$ python app.py hello --name Alice
Hello Alice!

$ python app.py hello --help
 Usage: app.py hello [OPTIONS]

 Say hello.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ -n  --name           TEXT                        Your name [env var:         │
│                                                  MYAPP_HELLO_NAME] [default: │
│                                                  World]                      │
│ -v  --verbosity      LEVEL                       Either TRACE, DEBUG, INFO,  │
│                                                  WARNING, ERROR, CRITICAL.   │
│                                                  [env var:                   │
│                                                  MYAPP_HELLO_VERBOSITY]      │
│                                                  [default: WARNING]          │
│ -o  --output-format  [json|yaml|table|rich|raw]  Specify the output format   │
│                                                  for the command. [env var:  │
│                                                  MYAPP_HELLO_OUTPUT_FORMAT]  │
│                                                  [default: table]            │
│ -h  --help                                       Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
```

## Features

- **Decorator-driven** — four decorators cover the full CLI surface
- **Autoconfiguration** — TOML/YAML/JSON config files with Linux path conventions (`/etc/<app>/`, `~/.config/<app>/`)
- **Environment variables** — automatic prefix-based binding for every option
- **Rich logging** — colored output, custom `TRACE` level, secret masking, rotating log files
- **Standardized output** — `Response` dataclass with JSON/YAML/Table/Rich/Raw formatters via `--output-format`
- **Global options** — options marked `is_global=True` propagate automatically to all subcommands
- **Project scaffolding** — `pyclifer project init` generates a ready-to-use project structure

## Documentation

Full documentation at **[bahamut45.github.io/pyclifer](https://bahamut45.github.io/pyclifer/)**.

## License

MIT — see [LICENSE](LICENSE).