Extension for python argparse with typehints and typechecks.
Project description
typedparser
Typing extension for python argparse using attrs.
Includes typechecking and conversion utilities to parse a dictionary into an attrs instance.
Features
- Create commandline arguments with type hints and checks while staying very 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
andlist
) - Supports positional and keyword arguments in classes
- Can also typecheck existing attrs instances
- Allows custom conversions, by default converts source type
str
to target typePath
andint
tofloat
- 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
Install
Requires python>=3.7
pip install typedparser
Usage of the parser
- Create an attrs class (decorate with
@attr.define
) - Define the fields with
typedparser.add_argument
- the syntax extends add_argument from argparse. - Parse the args with
TypedParser
, now the args are typechecked and there are typehints available.
from typing import Optional
from attrs import define
from typedparser import add_argument, TypedParser
@define
class Args:
foo: int = add_argument("foo", type=int)
bar: int = add_argument("-b", "--bar", type=int, default=0)
# Syntax extensions:
# Omit argument name to create an optional argument --opt
opt: Optional[int] = add_argument(type=int)
# Use shortcut to create an optional argument -s / --short
short: Optional[int] = add_argument(shortcut="-s", type=int)
def main():
parser = TypedParser.create_parser(Args)
args: Args = parser.parse_args()
print(args)
if __name__ == "__main__":
main()
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)
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 pytest-lazy-fixture
pylint typedparser
# run tests
python -m pytest --cov
pylint tests
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for typedparser-0.6.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 07e752a3abe2aac14ba7a4a57331baf12251604483756bac251b1e1215227683 |
|
MD5 | 36aadab6d3d74c013bc4391b546cf921 |
|
BLAKE2b-256 | c8176bee78762b1b466fcc886cc739b8b4450120f9787db05a878fef67100578 |