{"id":6789,"library":"pydantic-argparse","title":"Typed Argument Parsing with Pydantic","description":"pydantic-argparse is a Python package that provides declarative typed argument parsing by leveraging Pydantic models. It builds on the standard `argparse` module, offering a simple, opinionated, and type-hinted API for command-line interfaces. The library supports nesting Pydantic models for sub-command functionality and utilizes Pydantic's robust validation system. The current version is 0.10.0, released in February 2025, indicating an active development and release cadence.","status":"active","version":"0.10.0","language":"en","source_language":"en","source_url":"https://github.com/SupImDos/pydantic-argparse","tags":["pydantic","argparse","cli","command-line","typed","validation","settings"],"install":[{"cmd":"pip install pydantic-argparse","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for defining argument models and validation.","package":"pydantic","optional":false}],"imports":[{"symbol":"ArgumentParser","correct":"from pydantic_argparse import ArgumentParser"},{"note":"While pydantic-argparse added initial Pydantic v2 compatibility in v0.9.0, its official quickstart examples still explicitly import `pydantic.v1` for model definition. This suggests that using Pydantic v1 might be more stable or intended with current examples, or that full v2 migration requires careful adaptation of Pydantic models.","wrong":"from pydantic.v1 import BaseModel","symbol":"BaseModel","correct":"from pydantic import BaseModel"}],"quickstart":{"code":"import pydantic.v1 as pydantic\nfrom pydantic import Field\nfrom pydantic_argparse import ArgumentParser\n\nclass Arguments(pydantic.BaseModel):\n    \"\"\"Simple Command-Line Arguments.\"\"\"\n    # Required Args\n    string: str = Field(description=\"a required string\", aliases=[\"-s\"])\n    integer: int = Field(description=\"a required integer\", aliases=[\"-i\"])\n    flag: bool = Field(description=\"a required flag\", aliases=[\"-f\"])\n\n    # Optional Args\n    second_flag: bool = Field(False, description=\"an optional flag\")\n    third_flag: bool = Field(True, description=\"an optional flag\")\n\ndef main() -> None:\n    \"\"\"Simple Main Function.\"\"\"\n    parser = ArgumentParser(\n        model=Arguments,\n        prog=\"Example Program\",\n        description=\"Example Description\",\n        version=\"0.0.1\",\n        epilog=\"Example Epilog\",\n    )\n    args = parser.parse_typed_args()\n    print(args)\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"Define your command-line arguments using a Pydantic `BaseModel`. Then, create an instance of `pydantic_argparse.ArgumentParser` with your model and call `parse_typed_args()` to get a validated Pydantic model instance. This example uses `pydantic.v1` as shown in the official documentation."},"warnings":[{"fix":"For new projects, decide whether to explicitly use `pydantic.v1` for full compatibility with existing `pydantic-argparse` examples, or to adapt your Pydantic models to v2 and test thoroughly. If using Pydantic v2, consult the Pydantic migration guide for changes to `BaseModel` configuration and validators. The library's main `ArgumentParser` import remains consistent.","message":"Pydantic v1 vs v2 Compatibility: While pydantic-argparse v0.9.0 introduced initial compatibility with Pydantic v2, the official quickstart examples (even for v0.10.0) continue to explicitly use `import pydantic.v1 as pydantic`. Pydantic v2 includes significant breaking changes to its API (e.g., `Config` class vs `model_config` dict, `@validator` vs `@field_validator`, behavior of `Optional` fields). Users migrating from Pydantic v1 to v2 should carefully review the Pydantic migration guide and adapt their argument models, as direct compatibility with `pydantic-argparse` may require specific Pydantic v1 imports or adjustments.","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"Update code that inspects `model.__fields_set__` or uses `model.json(exclude_unset=True)` to account for the new behavior where only explicitly provided arguments are marked as 'set'.","message":"Changes to Default Value Handling (v0.6.0): Prior to v0.6.0, `pydantic-argparse` explicitly set default values for arguments not provided by the user via `argparse`. From v0.6.0 onwards, it transitioned to using `argparse.SUPPRESS` and relies on the `pydantic` model's default values for missing arguments. This change impacts how `model.__fields_set__` and `model.json(exclude_unset=True)` behave, as arguments not provided by the user will no longer appear in `__fields_set__`.","severity":"breaking","affected_versions":"<0.6.0"},{"fix":"Always define arguments using `pydantic.Field` with implicit or explicit aliases (flags) for all command-line inputs. Do not attempt to define positional arguments through the Pydantic model.","message":"No Positional Arguments: `pydantic-argparse` has an opinionated design that explicitly does not support positional arguments, only optional and required arguments which are defined with flags. Users accustomed to `argparse`'s positional argument behavior may find this limiting.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult Pydantic's `BaseSettings` documentation for environment variable loading order and precedence when designing your CLI with environment variable support. Clearly document the expected behavior for your users.","message":"Environment Variable Precedence: Version 0.8.0 introduced handling for environment variables, leveraging `pydantic.BaseSettings` for configuration. While a powerful feature, users should be aware of the precedence rules if arguments can be supplied via both command-line flags and environment variables, as the order of overriding might not always be intuitive without consulting Pydantic's settings documentation.","severity":"gotcha","affected_versions":">=0.8.0"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}