Metadata-Version: 2.3
Name: mrjk.clak
Version: 0.6.1
Summary: Command Line avec Klass
License: GPL-3.0-only
Author: mrjk
Author-email: mrjk.78@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Shells
Provides-Extra: colors
Provides-Extra: config
Provides-Extra: markdown
Provides-Extra: rst
Requires-Dist: argcomplete (>=3.6.2,<4.0.0)
Requires-Dist: coloredlogs (>=15.0.1,<16.0.0) ; extra == "colors"
Requires-Dist: docutils (>=0.21.0,<1.0.0) ; extra == "rst"
Requires-Dist: prettytable (>=3.16.0,<4.0.0)
Requires-Dist: pyyaml (>=6.0,<7.0) ; extra == "config"
Requires-Dist: rich (>=14.0.0,<15.0.0) ; extra == "markdown"
Project-URL: Documentation, https://mrjk.github.io/python-clak/
Project-URL: Homepage, https://github.com/mrjk/python-clak
Project-URL: Issues, https://github.com/mrjk/python-clak/issues
Project-URL: Repository, https://github.com/mrjk/python-clak
Description-Content-Type: text/markdown

# Clak

<p align='center'>
<img src="logo/logo.svg" alt="Clak Logo" width="128">
</p>

<p align='center'>
<img src="https://img.shields.io/badge/python-3.10%E2%80%933.14-blue" alt="Python Version">
<img src="https://img.shields.io/badge/license-GPL%20v3-blue" alt="License">
<img src="https://img.shields.io/pypi/v/mrjk.clak.svg" alt="PyPI">
</p>

Clak (*Command Line avec Klass*) is a Python library for building command-line
interfaces with a **class-based** API on top of standard `argparse`. Nested
commands, arguments, and optional batteries (views, logging, config, completion)
stay close to what you already know from the stdlib.

Full docs: [mrjk.github.io/python-clak](https://mrjk.github.io/python-clak/) ·
PyPI: [mrjk.clak](https://pypi.org/project/mrjk.clak/)

## Features

- **Class-based CLI** — define apps with `Parser`, `Argument`, and `Command`; no new DSL
- **Argparse-native** — same argument syntax as `add_argument()` / subparsers
- **Nested commands** — git-like trees with inheritance and a command overview in `--help`
- **Optional components** — views, logging, XDG config, shell-completion script generation
- Light core; extras only when you need them (`colors`, `config`, `markdown`, `rst`)

## Requirements

- **Python 3.10–3.14** (declared `>=3.10,<4.0`; CI and local matrix cover 3.10–3.14)
- `argparse` (stdlib)

Developer setup and the version matrix: [Development setup](https://mrjk.github.io/python-clak/project/setup/).

## Install

```bash
pip install mrjk.clak

# Or with your project manager
poetry add mrjk.clak
pdm add mrjk.clak
uv add mrjk.clak
```

Optional:

```bash
pip install 'mrjk.clak[colors]'   # coloredlogs for LoggingOptMixin
pip install 'mrjk.clak[config]'   # PyYAML for YAML config / --format yaml
pip install 'mrjk.clak[markdown]' # rich for MarkdownView and colored --help
pip install 'mrjk.clak[rst]'      # docutils for RstView
```

## Quick start

```python
from clak import Argument, Command, Parser


class ShowCommand(Parser):
    """Show something."""

    target = Argument("--target", "-t", help="Target to show")
    format = Argument(
        "--format", choices=["json", "text"], help="Output format"
    )

    def cli_run(self, target=None, format=None, **_):
        print(f"show target={target} format={format}")


class MainApp(Parser):
    """Demo application."""

    debug = Argument("--debug", action="store_true", help="Enable debug mode")
    config = Argument("--config", "-c", help="Config file path")

    show = Command(ShowCommand, help="Show something")


# Instantiating the root parser parses argv and runs the matching command.
if __name__ == "__main__":
    MainApp()
```

```bash
$ python demo.py --help
usage: demo.py [-h] [--debug] [--config CONFIG] {show} ...
```

## Key concepts

### Arguments

```python
class MyCommand(Parser):
    verbose = Argument("-v", "--verbose", action="store_true", help="Verbose")
```

### Nested commands

`Command` binds a child `Parser` (aliases: `SubParser`, `SubCommand`, `Cmd`):

```python
class MainApp(Parser):
    status = Command(StatusCommand, help="Show status")
```

### Optional components

| Component | Mixin / class | Docs |
| --- | --- | --- |
| Tables / structured output | `ListViewMixin`, `ShowViewMixin`, `PprintViewMixin` | [Views](https://mrjk.github.io/python-clak/docs/views/) |
| Colored `--help` | default (Rich extra, TTY) | [Colored help](https://mrjk.github.io/python-clak/docs/help/) |
| Logging + `-v` | `LoggingOptMixin` | [Logging](https://mrjk.github.io/python-clak/docs/logging/) |
| XDG paths + config file | `XDGConfigMixin` | [Config](https://mrjk.github.io/python-clak/docs/config/) |
| Shell completion scripts | `CompCmdRender` | [Completion](https://mrjk.github.io/python-clak/docs/completion/) |

## Learn more

- [Installation](https://mrjk.github.io/python-clak/quickstart/install/) and [Quickstart](https://mrjk.github.io/python-clak/quickstart/quickstart/)
- Guides under `docs/` / the site **Guides** tab
- Pasteable AI context: [primer](https://mrjk.github.io/python-clak/ai/primer/) · [reference](https://mrjk.github.io/python-clak/ai/reference/)
- Runnable examples in [`examples/`](examples/)
- Planned work: [Roadmap](https://mrjk.github.io/python-clak/project/roadmap/)

## Contributing

Bug reports, questions, and PRs are welcome. See the contribution guidelines
in the documentation (or `CONTRIBUTING.md`).

## License

GPL v3.

