corgy

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

Features

Type checking: Corgy instances 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: Corgy instances 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: Corgy class attributes can be added to an ArgumentParser instance, and parsed from the command-line. Help messages can be added to attributes with Annotated, 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 corgy package provides CorgyHelpFormatter, a formatter class for argparse, with support for colorized output. It can also be used independent of Corgy classes.

>>> 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

Sample argparse output with CorgyHelpFormatter

Convenience types: corgy.types provides 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}

Install

corgy is available on PyPI, and can be installed with pip:

pip install corgy

Support 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]

Metadata

Release files for corgy 9.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for corgy 9.3.0
File	Size	Uploaded
corgy-9.3.0.tar.gz	93.5 kB	Mar 8, 2024	Details

Built distribution (wheel)

Table of built distributions (wheels) for corgy 9.3.0
File	Interpreter	ABI	Platform	Reset
corgy-9.3.0-py3-none-any.whl 48.3 kB Mar 8, 2024	Python 3	none	any	Details

Total release size: 141.9 kB

Release files / corgy-9.3.0.tar.gz

Download URL	corgy-9.3.0.tar.gz
Size	93.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`7dea41a4cca02294c8688a1a4d8f223be648b4cd3c4b568205ece7b9c34e6159`
BLAKE2b-256 checksum How to use checksums	`b8af7135bcd9c25e1b88168461499806f222c20689e106b4db4744a57da5cfd4`
Upload date	Mar 8, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.8.2 CPython/3.10.12 Linux/6.5.0-1015-azure`

Release files / corgy-9.3.0-py3-none-any.whl

Download URL	corgy-9.3.0-py3-none-any.whl
Size	48.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`edc61324840efd83be66e1990f5f08bbd11cd5025a65e8e74c01141f92ea9fdd`
BLAKE2b-256 checksum How to use checksums	`eb3ab22553cf6e1785d192b28781b0f9c5fd72c465f29fe7cadf13b1a5fb8381`
Upload date	Mar 8, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.8.2 CPython/3.10.12 Linux/6.5.0-1015-azure`