Skip to main content

Extension for python argparse with typehints and typechecks.

Project description

typedparser

build 3.7 status build 3.8 status build 3.9 status build 3.10 status build 3.11 status build 3.12 status build 3.7 full status build 3.12 full status coverage version

Typing extension for python argparse using attrs.

Includes typechecking and conversion utilities to parse a dictionary into an attrs instance.

Install

Requires python>=3.7

pip install typedparser

Basic usage

  1. Create an attrs class (decorate with @attr.define). Note that optional arguments must also be typed as optional.
  2. Define and type the fields with typedparser.add_argument - the syntax extends add_argument from argparse.
  3. Parse the args with TypedParser and enjoy args with type hints. Disable typechecking by setting strict=False.
from typing import Optional
from attrs import define
from typedparser import add_argument, TypedParser


@define
class Args:   
    # omit the argument name to have it inferred from the field name
    foo: str = add_argument(positional=True)
    bar: int = add_argument(shortcut="-b", type=int, default=0)
    opt: Optional[str] = add_argument()

    # # in case you prefer the regular argparse syntax:
    # foo: str = add_argument("foo")
    # bar: int = add_argument("-b", "--bar", type=int, default=0)
    # opt: Optional[str] = add_argument("--opt")
    
    

def main():
    parser = TypedParser.create_parser(Args, strict=True)
    args: Args = parser.parse_args()
    print(args)


if __name__ == "__main__":
    main()

Features

  • Create commandline arguments with type hints and checks while staying close to the syntax of the standard library's argparse.
  • Utilities for typechecking and converting nested objects:
    • Nested checking and conversion of python standard types
    • Supports old and new style typing (e.g. typing.List and list)
    • Supports positional and keyword arguments in classes
    • Can also typecheck existing attrs instances
    • Allows custom conversions, by default converts source type str to target type Path and int to float
    • Allows to redefine which objects will be recursed into, by default recurses into standard containers (list, dict, etc.)
    • @definenumpy decorator for equality check if the instances contains numpy arrays
  • Some object utilities in typedparser.objects required for everything else

Advanced usage

  • Use TypedParser.from_parser(parser, Args) to add typing to an existing parser. This is useful to cover usecases like subparsers or argument groups.
  • Snippet for argument lists xarg: List[int] = add_argument(shortcut="-x", type=int, action="append", help="Xarg", default=[]), use as -x 1 -x 2 to get [1, 2] in the args instance.

Usage of attr utilities

Define the class hierarchy and parse the input using attrs_from_dict. Use @define(slots=False) to allow multiple inheritance and setting attributes later.

from attrs import define
from typing import Optional
from typedparser import attrs_from_dict

@define
class Cfg:
    foo: int = 12
    bar: Optional[int] = None

print(attrs_from_dict(Cfg, {"foo": 1, "bar": 2}))
# Cfg(foo=1, bar=2)


@define
class CfgNested:
    sub_cfg: Cfg = None

print(attrs_from_dict(CfgNested, {"sub_cfg": {"foo": 1, "bar": 2}}))
# CfgNested(sub_cfg=Cfg(foo=1, bar=2))

Strict mode (default)

  • Convert everything to the target type, e.g. if the input is a list and the annotation is a tuple, the output will be a tuple
  • Raise errors if types cannot be matched, there are unknown fields in the input or abstract annotation types are used (e.g. Sequence)
  • Set _allow_extra_keys = True in the class definition to allow unknown fields in the input

Non-strict mode

Enabled by calling attrs_from_dict with strict=False

  • No conversion except for creating the attrs instance from the dict
  • Ignore silently if types cannot be matched or abstract annotation types are used
  • Unknown fields in the input will be added to the attrs instance if possible (see the hint below about slots)

Skip unknowns

Set skip_unknowns=True to ignore all unknown input fields.

Hints

The following behaviour stems from the attrs package:

  • New attributes cannot to be added after class definition to an attrs instance, unless it is created with @define(slots=False) Explanation
  • Untyped fields or "ClassVar" typed fields will be ignored by @attrs.define and therefore also by this library.

Install locally and run tests

Clone repository and cd into. Setup python 3.7 or higher. Note: Some tests are skipped for python 3.7.

pip install -e .
pip install pytest pytest-cov pylint
pylint typedparser

# run tests
python -m pytest --cov
pylint tests

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

typedparser-0.20.2.tar.gz (21.9 kB view details)

Uploaded Source

Built Distribution

typedparser-0.20.2-py3-none-any.whl (20.9 kB view details)

Uploaded Python 3

File details

Details for the file typedparser-0.20.2.tar.gz.

File metadata

  • Download URL: typedparser-0.20.2.tar.gz
  • Upload date:
  • Size: 21.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.10.15

File hashes

Hashes for typedparser-0.20.2.tar.gz
Algorithm Hash digest
SHA256 38987877b868f2eedd0e98832a713b408ce2c36498a7df32db65e3a943349d63
MD5 3c0b089c77a2b63e9f91b519ca767f03
BLAKE2b-256 67217bfa8571de58d4decd1f2fc467e9d2ba023821e9d96badc6d26f457cd274

See more details on using hashes here.

File details

Details for the file typedparser-0.20.2-py3-none-any.whl.

File metadata

  • Download URL: typedparser-0.20.2-py3-none-any.whl
  • Upload date:
  • Size: 20.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.10.15

File hashes

Hashes for typedparser-0.20.2-py3-none-any.whl
Algorithm Hash digest
SHA256 8142fc4f5673a45330fb5ece7a8aa613a8f4794553569521006eff6e7ada5020
MD5 0d214dc33809a04ade80c43f1648c346
BLAKE2b-256 d5ca50e74390a364f86e71c0636a4af9bf5829aeb7ca10c1d4172c9e29dd9c1a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page