# corgy
Corgy is a Python library that allows you to create feature rich data
classes using intuitive type annotations.
```pycon
>>> 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.
```pycon
>>> 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.
```pycon
>>> 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.
```pycon
>>> 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.
```pycon
>>> 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.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.
```pycon
>>> 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:
```bash
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:
```bash
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:
```bash
pip install corgy[toml]
```
Raw data
{
"_id": null,
"home_page": "https://github.com/jayanthkoushik/corgy",
"name": "corgy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "data classes,argparse,argument parsing,command line parsing,cli",
"author": "Jayanth Koushik",
"author_email": "mail@jkoushik.me",
"download_url": "https://files.pythonhosted.org/packages/b8/af/7135bcd9c25e1b88168461499806f222c20689e106b4db4744a57da5cfd4/corgy-9.3.0.tar.gz",
"platform": null,
"description": "# corgy\n\nCorgy is a Python library that allows you to create feature rich data\nclasses using intuitive type annotations.\n\n```pycon\n>>> from typing import List\n>>> from typing_extensions import Literal\n>>> from corgy import Corgy\n>>> from corgy.types import KeyValuePairs\n\n>>> class G(Corgy):\n... x: int\n... y: Literal[\"y1\", \"y2\", \"y3\"]\n\n>>> class C(Corgy):\n... x: List[float] = [1.0, 2.0]\n... y: KeyValuePairs[str, int]\n... g: G\n\n```\n\n## Features\n\n* **Type checking**: `Corgy` instances are type-checked, and support a\n number of type modifiers.\n\n```pycon\n>>> from typing import Tuple\n\n>>> class C(Corgy):\n... x: int\n... y: Tuple[int, int]\n\n>>> C(x=\"1\")\nTraceback (most recent call last):\n ...\nValueError: error setting `x`: invalid value for type '<class 'int'>': '1'\n\n>>> C(y=(1, 2, 3))\nTraceback (most recent call last):\n ...\nValueError: error setting `y`: invalid value for type 'typing.Tuple[int, int]': (1, 2, 3): expected exactly '2' elements\n\n```\n\n* **Dictionary interface**: `Corgy` instances can be converted to/from\n dictionaries.\n\n```pycon\n>>> class G(Corgy):\n... x: int\n\n>>> class C(Corgy):\n... x: int\n... g: G\n\n>>> g = G.from_dict({\"x\": 1})\n>>> g\nG(x=1)\n\n>>> c = C(x=2, g=g)\n>>> c.as_dict()\n{'x': 2, 'g': {'x': 1}}\n\n```\n\n* **Command-line parsing**: `Corgy` class attributes can be added to an\n `ArgumentParser` instance, and parsed from the command-line. Help\n messages can be added to attributes with `Annotated`, and will be\n passed to the command line parser.\n\n```pycon\n>>> from argparse import ArgumentParser\n>>> from typing import Optional\n>>> from typing_extensions import Annotated\n\n>>> class ArgGroup(Corgy):\n... arg1: Annotated[Optional[int], \"optional number\"]\n... arg2: Annotated[bool, \"a boolean\"]\n\n>>> class MyArgs(Corgy):\n... arg1: Annotated[int, \"a number\"] = 1\n... arg2: Annotated[Tuple[float, ...], \"at least one float\"]\n... grp1: Annotated[ArgGroup, \"group 1\"]\n\n>>> parser = ArgumentParser(usage=\"\")\n>>> MyArgs.add_args_to_parser(parser)\n>>> parser.print_help() # doctest: +SKIP\nusage:\n\noptional arguments:\n -h, --help show this help message and exit\n --arg1 ARG1 a number\n --arg2 ARG2 [ARG2 ...]\n at least one float\n\ngrp1:\n group 1\n\n --grp1:arg1 [GRP1:ARG1]\n optional number\n --grp1:arg2, --no-grp1:arg2\n a boolean\n\n```\n\n* **Enhanced argparse formatting**: The `corgy` package provides\n `CorgyHelpFormatter`, a formatter class for `argparse`, with support\n for colorized output. It can also be used independent of `Corgy`\n classes.\n\n```pycon\n>>> from corgy import CorgyHelpFormatter\n\n>>> # `ArgGroup` and `MyArgs` as defined above\n>>> parser = ArgumentParser(usage=\"\", formatter_class=CorgyHelpFormatter)\n>>> MyArgs.add_args_to_parser(parser)\n>>> parser.print_help() # doctest: +SKIP\n```\n\n \n\n* **Convenience types**: `corgy.types` provides a number of types for\n converting strings into objects like paths, dictionaries, classes,\n etc. These can be used standalone, but are especially useful for\n parsing from command line arguments. Refer to the docs for details on\n all available types. A small example is shown below.\n\n```pycon\n>>> T = KeyValuePairs[str, int]\n>>> m = T(\"x=1,y=2\")\n>>> print(m)\n{'x': 1, 'y': 2}\n\n```\n\n## Install\n`corgy` is available on PyPI, and can be installed with pip:\n\n```bash\npip install corgy\n```\n\nSupport for colorized output requires the `crayons` package, also\navailable on PyPI. You can pull it as a dependency for `corgy` by\ninstalling with the `colors` extra:\n\n```bash\npip install corgy[colors]\n```\n\nParsing `Corgy` objects from `toml` files requires the `tomli` package\non Python versions below 3.11. This can be installed automatically with\nthe `toml` extra:\n\n```bash\npip install corgy[toml]\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Elegant data classes",
"version": "9.3.0",
"project_urls": {
"Homepage": "https://github.com/jayanthkoushik/corgy",
"Repository": "https://github.com/jayanthkoushik/corgy"
},
"split_keywords": [
"data classes",
"argparse",
"argument parsing",
"command line parsing",
"cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eb3ab22553cf6e1785d192b28781b0f9c5fd72c465f29fe7cadf13b1a5fb8381",
"md5": "63622c9e429cb83b6e3c2ececde7f913",
"sha256": "edc61324840efd83be66e1990f5f08bbd11cd5025a65e8e74c01141f92ea9fdd"
},
"downloads": -1,
"filename": "corgy-9.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "63622c9e429cb83b6e3c2ececde7f913",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 48340,
"upload_time": "2024-03-08T16:53:57",
"upload_time_iso_8601": "2024-03-08T16:53:57.710521Z",
"url": "https://files.pythonhosted.org/packages/eb/3a/b22553cf6e1785d192b28781b0f9c5fd72c465f29fe7cadf13b1a5fb8381/corgy-9.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b8af7135bcd9c25e1b88168461499806f222c20689e106b4db4744a57da5cfd4",
"md5": "0d0eefa7b78c179e45570460529fdb27",
"sha256": "7dea41a4cca02294c8688a1a4d8f223be648b4cd3c4b568205ece7b9c34e6159"
},
"downloads": -1,
"filename": "corgy-9.3.0.tar.gz",
"has_sig": false,
"md5_digest": "0d0eefa7b78c179e45570460529fdb27",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 93540,
"upload_time": "2024-03-08T16:53:59",
"upload_time_iso_8601": "2024-03-08T16:53:59.699456Z",
"url": "https://files.pythonhosted.org/packages/b8/af/7135bcd9c25e1b88168461499806f222c20689e106b4db4744a57da5cfd4/corgy-9.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-08 16:53:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jayanthkoushik",
"github_project": "corgy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "corgy"
}
JSON
