argparse-dataclass

What it is and what it does

argparse_dataclass bridges dataclasses and argparse to let you define CLI arguments as typed dataclass fields instead of writing repetitive argparse setup code. When you decorate a dataclass with its ArgumentParser, the library automatically generates argument definitions from field types, defaults, and metadata—booleans become flags, integers and strings become typed options, and Literal types create choice constraints. You call parse_args() as you would with standard argparse, but get back a populated dataclass instance instead of a Namespace object.

The package handles positional arguments, boolean flags, simple scalar types, default values, and choice-based options. It supports custom type converters via field metadata, optional fields, required flags, and parse_known_args() for partial parsing. Subcommands and mutually exclusive groups are not yet implemented. With no runtime dependencies and low install friction, it's a lightweight alternative to heavier CLI frameworks when you want argparse's simplicity with less boilerplate.

Use it for:

• Define a tool's CLI arguments as a single dataclass, reducing argument parser setup code and improving type safety.
• Build scripts that need both positional and optional arguments with clear type hints and default values.
• Create command-line tools where the argument structure is stable and you want a single source of truth for CLI schema.
• Parse CLI arguments into a typed object for easier downstream validation and use in your application logic.
• Migrate existing argparse code to a more declarative style without rewriting the entire parser.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Builds command-line interfaces declaratively by combining Python dataclasses with argparse, eliminating boilerplate argument definition code.

Yes, if you are starting a new CLI project or refactoring an existing one and want to reduce argparse boilerplate. The library is stable, has no dependencies, and works with modern Python versions. However, be aware that maintenance is minimal—the last release was in mid-2023 and the repository shows no recent activity. If you need active support, subcommands, or mutually exclusive groups, consider whether a more actively maintained alternative suits your needs.

Install

argparse-dataclass on PyPI

pip install argparse-dataclass

uv add argparse-dataclass

poetry add argparse-dataclass

Installing argparse-dataclass

Before you install

Low friction: pure Python, no runtime dependencies, and distributed as a wheel. However, the package is aging—last release was 2023-06-11 and no commits since 2025-06-02—so expect limited active maintenance.

License in practice

MIT license (permissive) means you can use, modify, and distribute the package freely in commercial and open-source projects with minimal restrictions.

Quickstart

from dataclasses import dataclass
from argparse_dataclass import ArgumentParser

@dataclass
class Options:
    name: str
    verbose: bool = False

parser = ArgumentParser(Options)
args = parser.parse_args(['--name', 'example', '--verbose'])
print(args)  # Options(name='example', verbose=True)

Requires Python 3.8 or later.

Verify before relying

• Whether subcommands and mutually exclusive groups (marked unimplemented) are planned or abandoned.
• Current maintenance status and likelihood of bug fixes or feature additions post-2023.

Package facts

Evidence: argparse_dataclass-2.0.0-py3-none-any.whl

Tags

More Software Development packages