Metadata-Version: 2.4
Name: argclz
Version: 1.0.0
Summary: Create commandline interface via dataclass-like class
Author-email: Yu-Ting Wei <ytsimon2004@gmail.com>, Ta-Shun Su <antoniost29@gmail.com>
License: BSD 3-Clause License
        
        Copyright (c) 2025, Yu-Ting Wei
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/ytsimon2004/argclz
Project-URL: Documentation, https://argclz.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/ytsimon2004/argclz
Project-URL: Issues, https://github.com/ytsimon2004/argclz/issues
Keywords: commandline
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typing_extensions
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: doc
Requires-Dist: sphinx; extra == "doc"
Requires-Dist: pydata-sphinx-theme; extra == "doc"
Requires-Dist: sphinx_prompt; extra == "doc"
Requires-Dist: sphinx_copybutton; extra == "doc"
Dynamic: license-file

# argclz

[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/argclz)](https://pypi.org/project/argclz/)
[![PyPI version](https://badge.fury.io/py/argclz.svg)](https://badge.fury.io/py/argclz)

[![Documentation Status](https://readthedocs.org/projects/argp/badge/?version=latest)](https://argp.readthedocs.io/en/latest/)
[![codecov](https://codecov.io/gh/ytsimon2004/argclz/branch/main/graph/badge.svg?token=HfO5frntJe)](https://codecov.io/gh/ytsimon2004/argclz)

Class-based command-line argument parsing for Python that combines the power of `argparse` with class definitions and
type annotations.

## Features

- **Type-safe arguments** - Automatically infer type conversion from Python type annotations
- **Clean syntax** - Define arguments as class attributes with straightforward decorators
- **Composable** - Easily reuse and extend argument definitions through inheritance
- **Validation** - Built-in validation system with chainable API
- **Subcommands** - Support for command hierarchies with minimal boilerplate
- **Organized help** - Group arguments into logical sections for better documentation

## Installation

```bash
pip install argclz
```

## [See Documentation](https://argp.readthedocs.io/en/latest/)

## Quick Start

```python
from argclz import *


class MyArgs(AbstractParser):
    verbose: bool = argument('--verbose', help='Enable verbose output')
    name: str = argument('-n', '--name', required=True, help='Name of the user')
    count: int = argument('--count', default=1, help='Number of times to greet')

    def run(self):
        for _ in range(self.count):
            if self.verbose:
                print(f"Greeting with enthusiasm: Hello, {self.name}!")
            else:
                print(f"Hello, {self.name}!")


if __name__ == '__main__':
    MyArgs().main()
```

Show help:

```bash
python my_script.py -h
```

Expected output:

```text
usage: my_script.py [-h] [--verbose] -n NAME [--count COUNT]

options:
  -h, --help            show this help message and exit
  --verbose             Enable verbose output
  -n NAME, --name NAME  Name of the user
  --count COUNT         Number of times to greet
```

Run with:

```bash
python my_script.py --name Alice --count 3 --verbose
```

## Core Features

### Argument Types

```python
# Regular argument
name: str = argument('-n', '--name', help='Name of the user')

# Boolean flag
verbose: bool = argument('--verbose', help='Enable verbose output')

# Positional argument
filename: str = pos_argument('FILENAME', help='Input file to process')

# Variable-length argument
items: list[str] = var_argument('ITEMS', help='Items to process')
```

### Type Parsers

```python
# Comma-separated values to a tuple of floats
coords: tuple[float, ...] = argument('--coords', type=float_tuple_type)

# Value range (min:max)
ranging: tuple[int, int] = argument('--range', type=int_tuple_type)
```

### Argument Organization

```python
# Grouped arguments
verbose: bool = argument('--verbose', group='general')
output_dir: str = argument('--output', group='output')

# Mutually exclusive arguments
output_json: bool = argument('--json', ex_group='output')
output_yaml: bool = argument('--yaml', ex_group='output')
```

### Validators

```python
# Range validator
age: int = argument('--age', validator.int.in_range(18, 99))

# Path validator
path: Path = argument('--path', validator.path.is_dir().is_exists())
```

### Subcommands

```python
class InitCmd(AbstractParser):
    name: str = argument('--name', required=True)

    def run(self):
        print(f"Initializing project: {self.name}")


class BuildCmd(AbstractParser):
    release: bool = argument('--release')

    def run(self):
        print("Building in release mode" if self.release else "Building in debug mode")


# Entry point
from argclz.commands import parse_command_args

if __name__ == '__main__':
    parse_command_args({
        'init': InitCmd,
        'build': BuildCmd
    })
```

### Reusable Option Classes

```python
class IOOptions:
    input_path: str = argument('--input', help='Input file')
    output_path: str = argument('--output', help='Output file')


class LoggingOptions:
    verbose: bool = argument('--verbose', help='Enable verbose logging')


class MyOptions(IOOptions, LoggingOptions):
    # Override an inherited argument
    input_path = as_argument(IOOptions.input_path).with_options(required=True)
```

## License

[BSD 3-Clause License](LICENSE)
