# arcparse
Declare program arguments in a type-safe way.
This project builds on top of `argparse` by adding type-safety and allowing a more expressive argument parser definition.
## Example usage
```py
from arcparse import arcparser, flag
from pathlib import Path
@arcparser
class Args:
path: Path
recurse: bool = flag("-r")
item_limit: int = 100
output_path: Path | None
args = Args.parse()
print(f"Scanning {args.path}...")
...
```
For more examples see [Examples](examples/).
## Installation
```shell
# Using pip
$ pip install arcparse
```
## Features
- Positional, Option and Flag arguments
- Multiple values per argument
- Name overriding
- Type conversions
- Mutually exclusive groups
- Subparsers
- Parser inheritance
## Credits
This project was inspired by [swansonk14/typed-argument-parser](https://github.com/swansonk14/typed-argument-parser).
## Known issues
### Annotations
`from __future__ import annotations` makes all annotations strings at runtime. This library relies on class variable annotations's types being actual types. `inspect.get_annotations(obj, eval_str=True)` is used to evaluate string annotations to types in order to assign converters. If an argument is annotated with a non-builtin type which is defined outside of the argument-defining class body the type can't be found which results in `NameError`s. This is avoidable either by only using custom types which have been defined in the argument-defining class body (which is restrictive), or alternatively by not using the `annotations` import which should not be necessary from python 3.13 forward thanks to [PEP 649](https://peps.python.org/pep-0649/).
Raw data
{
"_id": null,
"home_page": "https://github.com/Kuba314/arcparse",
"name": "arcparse",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "argparse, declarative, argument, parsing, type-safe",
"author": "Jakub Rozek",
"author_email": "jakub.rozek314@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f5/1c/b01ad2ea6c11ecb344dd40412889193e270248230addecaa6b65c3c2b10a/arcparse-1.1.0.tar.gz",
"platform": null,
"description": "# arcparse\nDeclare program arguments in a type-safe way.\n\nThis project builds on top of `argparse` by adding type-safety and allowing a more expressive argument parser definition.\n\n## Example usage\n```py\nfrom arcparse import arcparser, flag\nfrom pathlib import Path\n\n@arcparser\nclass Args:\n path: Path\n recurse: bool = flag(\"-r\")\n item_limit: int = 100\n output_path: Path | None\n\nargs = Args.parse()\nprint(f\"Scanning {args.path}...\")\n...\n```\n\nFor more examples see [Examples](examples/).\n\n## Installation\n```shell\n# Using pip\n$ pip install arcparse\n```\n\n## Features\n- Positional, Option and Flag arguments\n- Multiple values per argument\n- Name overriding\n- Type conversions\n- Mutually exclusive groups\n- Subparsers\n- Parser inheritance\n\n## Credits\nThis project was inspired by [swansonk14/typed-argument-parser](https://github.com/swansonk14/typed-argument-parser).\n\n## Known issues\n\n### Annotations\n`from __future__ import annotations` makes all annotations strings at runtime. This library relies on class variable annotations's types being actual types. `inspect.get_annotations(obj, eval_str=True)` is used to evaluate string annotations to types in order to assign converters. If an argument is annotated with a non-builtin type which is defined outside of the argument-defining class body the type can't be found which results in `NameError`s. This is avoidable either by only using custom types which have been defined in the argument-defining class body (which is restrictive), or alternatively by not using the `annotations` import which should not be necessary from python 3.13 forward thanks to [PEP 649](https://peps.python.org/pep-0649/).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Declare program arguments in a type-safe way",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/Kuba314/arcparse",
"Repository": "https://github.com/Kuba314/arcparse"
},
"split_keywords": [
"argparse",
" declarative",
" argument",
" parsing",
" type-safe"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c17cb55ecda75497be3d4571055d79e4cc117fd241642f38183562afc977aa26",
"md5": "e83e1f15419ebca296703214243177da",
"sha256": "9fd481e3a83b10cb6df1b2a12a979466edc7c3ca07884327594f8c86659fd48a"
},
"downloads": -1,
"filename": "arcparse-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e83e1f15419ebca296703214243177da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 12750,
"upload_time": "2024-11-23T20:39:12",
"upload_time_iso_8601": "2024-11-23T20:39:12.352699Z",
"url": "https://files.pythonhosted.org/packages/c1/7c/b55ecda75497be3d4571055d79e4cc117fd241642f38183562afc977aa26/arcparse-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f51cb01ad2ea6c11ecb344dd40412889193e270248230addecaa6b65c3c2b10a",
"md5": "bdea266befc0061a7b2c58e8da60190e",
"sha256": "f898b09119375e32fe70ad441f9b32e819555736e8c8741b74cf8374a586659b"
},
"downloads": -1,
"filename": "arcparse-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "bdea266befc0061a7b2c58e8da60190e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 10620,
"upload_time": "2024-11-23T20:39:14",
"upload_time_iso_8601": "2024-11-23T20:39:14.264012Z",
"url": "https://files.pythonhosted.org/packages/f5/1c/b01ad2ea6c11ecb344dd40412889193e270248230addecaa6b65c3c2b10a/arcparse-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-23 20:39:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kuba314",
"github_project": "arcparse",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "arcparse"
}