Kliamka

A small Python CLI library that provides Pydantic-based argument parser with type safety.

Features

• Type-safe CLI arguments with Pydantic validation
• Decorator-based design for clean, readable code
• Automatic argument parsing from class definitions
• Modern Python 3.11+ with full type hints

Installation

# Install via pip
pip install kliamka

# Install from source
git clone https://github.com/hotsyk/kliamka.git
cd kliamka
make install

# Or install in development mode
pip install -e .

Quick Start

from kliamka import KliamkaArg, KliamkaArgClass, kliamka_cli

class MyArgs(KliamkaArgClass):
    """My CLI application arguments."""
    verbose: bool | None = KliamkaArg("--verbose", "Enable verbose output")
    count: int | None = KliamkaArg("--count", "Number of iterations", default=1)

@kliamka_cli(MyArgs)
def main(args: MyArgs) -> None:
    """Main application logic."""
    if args.verbose:
        print("Verbose mode enabled")

    for i in range(args.count or 1):
        print(f"Iteration {i + 1}")

if __name__ == "__main__":
    main()

Run your CLI:

python my_app.py --verbose --count 3

API Reference

Core Components

KliamkaArg

Descriptor for defining CLI arguments with automatic type inference.

class KliamkaArg:
    def __init__(self, flag: str, help_text: str = "", default: Any = None)

KliamkaArgClass

Base class for CLI argument definitions using Pydantic models.

class MyArgs(KliamkaArgClass):
    debug: bool | None = KliamkaArg("--debug", "Enable debug mode")
    config: str | None = KliamkaArg("--config", "Configuration file path")

@kliamka_cli

Decorator that automatically parses CLI arguments and injects them as the first parameter.

@kliamka_cli(MyArgs)
def main(args: MyArgs) -> None:
    # args is automatically populated from command line
    pass

Examples

See the examples/ directory for more comprehensive usage examples:

• examples/basic_usage.py - Basic CLI argument handling
• examples/enums.py - Handling of enumerated types

Development

Requirements

• Python 3.11+
• Pydantic 2.0+

Setup

# Clone and setup
git clone https://github.com/hotsyk/kliamka.git
cd kliamka
make install

# Run tests
make test

# Lint and type check
make lint

# Run example
python examples/basic_usage.py --help

Available Make Commands

• make install - Install package in development mode
• make run - Run the CLI application
• make test - Run tests with pytest
• make lint - Run type checking and linting
• make format - Format code with ruff
• make clean - Clean build artifacts

Documentation

• Examples - Usage examples and demos

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run make lint and make test
5. Submit a pull request

License

MIT-NORUS License - see LICENSE file for details.

Author

Volodymyr Hotsyk - https://github.com/hotsyk