Declare program arguments in a type-safe way.

This project builds on top of argparse by adding type-safety and allowing a more expressive argument parser definition.

from arcparse import arcparser, flag, positional from pathlib import Path @arcparser class Args: path: Path = positional() recurse: bool = flag("-r") item_limit: int = 100 output_path: Path | None args = Args.parse() print(f"Scanning {args.path}...") ...

usage: program.py [-h] [-r] [--item-limit ITEM_LIMIT] [--output-path OUTPUT_PATH] path positional arguments: path options: -h, --help show this help message and exit -r, --recurse --item-limit ITEM_LIMIT --output-path OUTPUT_PATH 

For more examples see Examples.

# Using pip $ pip install arcparse

• Positional, Option and Flag arguments
• Name overriding
• Multiple values per argument
• Type conversions
• Mutually exclusive groups
• Subparsers
• Parser inheritance (with overriding)
• Presence validation

This project was inspired by swansonk14/typed-argument-parser.

from __future__ import annotations makes all annotations strings at runtime. This library relies on class variable annotations's types being actual types. inspect.get_annotations(obj, eval_str=True) is used to evaluate string annotations to types in order to assign converters. If an argument is annotated with a non-builtin type which is defined outside of the argument-defining class body the type can't be found which results in NameErrors. This is avoidable either by only using custom types which have been defined in the argument-defining class body (which is restrictive), or alternatively by not using the annotations import which should not be necessary from python 3.14 forward thanks to PEP 649.