Metadata-Version: 2.3
Name: mrjk.clak
Version: 0.5.0
Summary: Command Line avec Klass
License: GPLv3
Author: mrjk
Author-email: mrjk.78@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: License :: Other/Proprietary License
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
Provides-Extra: colors
Provides-Extra: config
Requires-Dist: argcomplete (>=3.6.2,<4.0.0)
Requires-Dist: coloredlogs (>=15.0.1,<16.0.0) ; extra == "colors"
Requires-Dist: prettytable (>=3.16.0,<4.0.0)
Requires-Dist: pyyaml (>=6.0,<7.0) ; extra == "config"
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`)

## 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
```

## 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/) |
| 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.

