# argclass

> A Python library for building type-safe command-line interfaces using declarative classes with type hints, configuration files, and environment variables. Zero external dependencies. Requires Python 3.10+.

argclass wraps Python's standard `argparse` module, letting you describe argument parsers as classes with type annotations instead of imperative `add_argument()` calls. It supports INI/JSON/TOML config files, environment variable binding, secret masking, argument groups, and hierarchical subcommands — all with full IDE autocompletion.

Key API classes: `Parser` (main entry point), `Argument`, `Group`, `Secret`, `INIConfig`, `JSONConfig`, `TOMLConfig`, `LogLevel`.

## Quick Examples

### Minimal parser

```python
import argclass

class CLI(argclass.Parser):
    host: str = "localhost"      # --host (default: localhost)
    port: int = 8080             # --port (default: 8080)
    verbose: bool = False        # --verbose flag (store_true)

parser = CLI()
parser.parse_args()
```

### Optional, list, and literal types

```python
from typing import Optional, Literal
import argclass

class CLI(argclass.Parser):
    name: Optional[str] = None               # --name (optional)
    tags: list[str] = argclass.Argument(      # --tags a b c
        nargs=argclass.Nargs.ONE_OR_MORE,
    )
    mode: Literal["fast", "slow"] = "fast"   # --mode {fast,slow}
```

### Argument groups

```python
import argclass

class Database(argclass.Group):
    host: str = "localhost"
    port: int = 5432

class CLI(argclass.Parser):
    debug: bool = False
    db: Database = Database(title="Database options")

parser = CLI()
parser.parse_args()
print(parser.db.host, parser.db.port)
```

### Subcommands

```python
import argclass

class Serve(argclass.Parser):
    port: int = 8080

class Deploy(argclass.Parser):
    target: str = "production"

class CLI(argclass.Parser):
    serve = Serve()
    deploy = Deploy()
```

### Environment variables and secrets

```python
import argclass

class CLI(argclass.Parser):
    db_url: str = argclass.Argument(env_var="DATABASE_URL")
    api_key: str = argclass.Secret()  # masked in repr/logs

# auto_env_var_prefix generates env vars from arg names
parser = CLI(auto_env_var_prefix="APP_")
parser.parse_args()
parser.sanitize_env(only_secrets=True)
```

### Config file support

```python
import argclass

class CLI(argclass.Parser):
    host: str = "localhost"
    port: int = 8080
    config: str = argclass.Config(
        search_paths=["/etc/myapp.ini", "~/.myapp.ini"],
    )
```

## Docs

- [Quick Start](https://docs.argclass.com/_sources/quickstart.md.txt): 5-minute overview of essential concepts
- [Tutorial](https://docs.argclass.com/_sources/tutorial.md.txt): 30-minute guide building a complete CLI application
- [Arguments](https://docs.argclass.com/_sources/arguments.md.txt): Typed arguments, defaults, nargs, enums, boolean flags
- [Groups](https://docs.argclass.com/_sources/groups.md.txt): Reusable argument groups with prefix support
- [Subparsers](https://docs.argclass.com/_sources/subparsers.md.txt): Hierarchical subcommands and nested parsers
- [Config Files](https://docs.argclass.com/_sources/config-files.md.txt): INI, JSON, and TOML configuration file support
- [Environment Variables](https://docs.argclass.com/_sources/environment.md.txt): Automatic env var binding with prefixes
- [Secrets](https://docs.argclass.com/_sources/secrets.md.txt): Secret masking to prevent accidental exposure in logs
- [API Reference](https://docs.argclass.com/api.html): Full API documentation with all classes and functions

## Optional

- [Examples Gallery](https://docs.argclass.com/_sources/examples.md.txt): Ready-to-use patterns from simple CLIs to multi-command tools
- [Error Handling](https://docs.argclass.com/_sources/errors.md.txt): Error types and handling strategies
- [Common Pitfalls](https://docs.argclass.com/_sources/pitfalls.md.txt): Frequent mistakes and how to avoid them
- [Integrations](https://docs.argclass.com/_sources/integrations.md.txt): Using argclass with other tools
- [Security](https://docs.argclass.com/_sources/security.md.txt): Security policy and best practices