Examples

The repository includes runnable examples for each major feature. Run them from a checkout after make install, or use the patterns below in your own project.

Repository examples

File	Demonstrates
examples/basic_usage.py	Basic options and decorator execution
examples/enums.py	String- and integer-valued enums
examples/positional_args.py	Required and optional positionals
examples/list_args.py	Multi-value list options
examples/env_vars.py	CLI/environment/default precedence
examples/subcommands.py	Main options and Git-style subcommands
examples/custom_converters.py	Per-field and globally registered converters

Browse the examples directory on GitHub for current source.

Run examples locally

git clone https://github.com/hotsyk/kliamka.git
cd kliamka
make init-dev

.venv/bin/python examples/basic_usage.py --help
.venv/bin/python examples/enums.py --help
.venv/bin/python examples/positional_args.py --help
.venv/bin/python examples/list_args.py --help
.venv/bin/python examples/env_vars.py --help
.venv/bin/python examples/subcommands.py --help
.venv/bin/python examples/custom_converters.py --help

Each script has its own accepted arguments; inspect --help or its source before running a non-help invocation.

A practical configuration CLI

This example combines positionals, environment fallback, a list, custom conversion, validation, metadata, and explicit entry-point dispatch:

from pathlib import Path
from typing import Self

from pydantic import model_validator

from kliamka import KliamkaArg, KliamkaArgClass, ParserMeta, kliamka_cli


class ExportArgs(KliamkaArgClass):
    """Export records to a directory."""

    parser_meta = ParserMeta(
        prog="records-export",
        version="records-export 1.0.0",
        epilog="Environment values are used only when CLI options are absent.",
    )

    destination: Path = KliamkaArg(
        "destination",
        "Export directory",
        positional=True,
        converter=Path,
    )
    format: str = KliamkaArg(
        "--format",
        "Output format",
        default="json",
        short="-f",
        env="EXPORT_FORMAT",
    )
    tags: list[str] = KliamkaArg(
        "--tags",
        "Only export records carrying these tags",
        env="EXPORT_TAGS",
    )
    overwrite: bool = KliamkaArg(
        "--overwrite",
        "Allow a non-empty destination",
        short="-o",
    )

    @model_validator(mode="after")
    def supported_format(self) -> Self:
        if self.format not in {"json", "csv"}:
            raise ValueError("format must be json or csv")
        return self


@kliamka_cli(ExportArgs)
def main(args: ExportArgs) -> None:
    args.destination.mkdir(parents=True, exist_ok=True)
    print(
        f"Exporting format={args.format}, tags={args.tags}, "
        f"overwrite={args.overwrite} to {args.destination}"
    )


if __name__ == "__main__":
    main()

python export.py ./out --format csv --tags active reviewed
EXPORT_FORMAT=json EXPORT_TAGS=active,reviewed python export.py ./out

Test the example

Create a separate decorated function with deterministic input:

@kliamka_cli(
    ExportArgs,
    argv=["./out", "--format", "csv", "--tags", "active", "reviewed"],
)
def invoke(args: ExportArgs) -> ExportArgs:
    return args


parsed = invoke()
assert parsed.destination == Path("out")
assert parsed.format == "csv"
assert parsed.tags == ["active", "reviewed"]

This tests parser construction, token conversion, fallback resolution, and Pydantic validation together. Test application services separately with ordinary ExportArgs instances where appropriate.