Corgy is a Python library that allows you to create feature rich data classes using intuitive type annotations.
>>> from typing import List
>>> from typing_extensions import Literal
>>> from corgy import Corgy
>>> from corgy.types import KeyValuePairs
>>> class G(Corgy):
... x: int
... y: Literal["y1", "y2", "y3"]
>>> class C(Corgy):
... x: List[float] = [1.0, 2.0]
... y: KeyValuePairs[str, int]
... g: G
- Type checking:
Corgyinstances are type-checked, and support a number of type modifiers.
>>> from typing import Tuple
>>> class C(Corgy):
... x: int
... y: Tuple[int, int]
>>> C(x="1")
Traceback (most recent call last):
...
ValueError: error setting `x`: invalid value for type '<class 'int'>': '1'
>>> C(y=(1, 2, 3))
Traceback (most recent call last):
...
ValueError: error setting `y`: invalid value for type 'typing.Tuple[int, int]': (1, 2, 3): expected exactly '2' elements
- Dictionary interface:
Corgyinstances can be converted to/from dictionaries.
>>> class G(Corgy):
... x: int
>>> class C(Corgy):
... x: int
... g: G
>>> g = G.from_dict({"x": 1})
>>> g
G(x=1)
>>> c = C(x=2, g=g)
>>> c.as_dict()
{'x': 2, 'g': {'x': 1}}
- Command-line parsing:
Corgyclass attributes can be added to anArgumentParserinstance, and parsed from the command-line. Help messages can be added to attributes withAnnotated, and will be passed to the command line parser.
>>> from argparse import ArgumentParser
>>> from typing import Optional
>>> from typing_extensions import Annotated
>>> class ArgGroup(Corgy):
... arg1: Annotated[Optional[int], "optional number"]
... arg2: Annotated[bool, "a boolean"]
>>> class MyArgs(Corgy):
... arg1: Annotated[int, "a number"] = 1
... arg2: Annotated[Tuple[float, ...], "at least one float"]
... grp1: Annotated[ArgGroup, "group 1"]
>>> parser = ArgumentParser(usage="")
>>> MyArgs.add_args_to_parser(parser)
>>> parser.print_help() # doctest: +SKIP
usage:
optional arguments:
-h, --help show this help message and exit
--arg1 ARG1 a number
--arg2 ARG2 [ARG2 ...]
at least one float
grp1:
group 1
--grp1:arg1 [GRP1:ARG1]
optional number
--grp1:arg2, --no-grp1:arg2
a boolean
- Enhanced argparse formatting: The
corgypackage providesCorgyHelpFormatter, a formatter class forargparse, with support for colorized output. It can also be used independent ofCorgyclasses.
>>> from corgy import CorgyHelpFormatter
>>> # `ArgGroup` and `MyArgs` as defined above
>>> parser = ArgumentParser(usage="", formatter_class=CorgyHelpFormatter)
>>> MyArgs.add_args_to_parser(parser)
>>> parser.print_help() # doctest: +SKIP
- Convenience types:
corgy.typesprovides a number of types for converting strings into objects like paths, dictionaries, classes, etc. These can be used standalone, but are especially useful for parsing from command line arguments. Refer to the docs for details on all available types. A small example is shown below.
>>> T = KeyValuePairs[str, int]
>>> m = T("x=1,y=2")
>>> print(m)
{'x': 1, 'y': 2}
corgy is available on PyPI, and can be installed with pip:
pip install corgySupport for colorized output requires the crayons package, also
available on PyPI. You can pull it as a dependency for corgy by
installing with the colors extra:
pip install corgy[colors]Parsing Corgy objects from toml files requires the tomli package
on Python versions below 3.11. This can be installed automatically with
the toml extra:
pip install corgy[toml]