{"id":15450757,"url":"https://github.com/suned/main-dec","last_synced_at":"2025-04-04T17:48:18.590Z","repository":{"id":57439297,"uuid":"193973942","full_name":"suned/main-dec","owner":"suned","description":"A tiny library for creating CLIs in Python","archived":false,"fork":false,"pushed_at":"2019-06-26T20:43:37.000Z","size":10,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-10T09:08:08.180Z","etag":null,"topics":["argument-checks","argument-parser","argument-parsers","argument-parsing","arguments","cli","command-line","command-line-tool","commandline","decorated-functions","decorator","decorators","main","python-3","python3","script","scripting","scripts"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/suned.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-26T20:34:52.000Z","updated_at":"2022-09-09T14:32:21.000Z","dependencies_parsed_at":"2022-09-26T17:20:27.207Z","dependency_job_id":null,"html_url":"https://github.com/suned/main-dec","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suned%2Fmain-dec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suned%2Fmain-dec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suned%2Fmain-dec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suned%2Fmain-dec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/suned","download_url":"https://codeload.github.com/suned/main-dec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247226195,"owners_count":20904464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["argument-checks","argument-parser","argument-parsers","argument-parsing","arguments","cli","command-line","command-line-tool","commandline","decorated-functions","decorator","decorators","main","python-3","python3","script","scripting","scripts"],"created_at":"2024-10-01T21:18:57.505Z","updated_at":"2025-04-04T17:48:18.565Z","avatar_url":"https://github.com/suned.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `main_dec`\n\nA small library for painless commandline argument parsing in python.\n## Install\n\n`\u003e pip install main-dec`\n\n## Quickstart\n```python\n# my_cli.py\n\nfrom typing import Tuple\n\nfrom main_dec import main\n\n\n@main\ndef run(required_str: str, optional_int=1, optional_tuple: Tuple[int, ...]=()):\n    \"\"\"\n    A small example cli\n    \n    :param required_str: a required str\n    :param optional_int: an optional int\n    :param optional_tuple: an optional tuple\n    \"\"\"\n    print('required_str', required_str)\n    print('optional_int', optional_int)\n    print('optional_tuple', optional_tuple)\n```\n\n```console\n\u003e python -m my_cli -h\nusage: my_cli [-h] [--optional-tuple OPTIONAL_TUPLE [OPTIONAL_TUPLE ...]] [--optional-int OPTIONAL_INT] required_str\n\nA small example cli\n\npositional arguments:\n  required_str          a required str\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --optional-tuple OPTIONAL_TUPLE [OPTIONAL_TUPLE ...]\n                        an optional tuple\n  --optional-int OPTIONAL_INT\n                        an optional int\n\n\u003e python -m my_cli arg --optional-int 2 --optional-tuple 1 2 3\nrequired_str arg\noptional_int 2\noptional_tuple (1, 2, 3)\n```\n\n## Required and optional arguments\n\nPositional arguments to your function will be parsed as required arguments to your cli.\nOptional arguments to your function will be parsed as optional arguments.\n```python\n# my_cli.py\n\nfrom main_dec import main\n\n\n@main\ndef run(required_arg: str, optional_arg=''):\n    pass\n```\n\n```console\n\u003e python -m my_cli -h\nusage: my_cli [-h] [--optional-arg OPTIONAL_ARG] required_arg\n\npositional arguments:\n  required_arg\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --optional-arg\n```\n\n## Flags\nOptional `bool` arguments are parsed as flags, such that passing them\non the commandline \"flips\" their\ntruthiness.\n\n```python\n# my_cli.py\n\nfrom main_dec import main\n\n@main\ndef run(positive_flag=False, negative_flag=True):\n    print('positive_flag', positive_flag)\n    print('negative_flag', negative_flag)\n```\n```console\n\u003e python -m my_cli --postive-flag --negative-flag\npositive_flag True\nnegative_flag False\n```\n## Type conversions\nPEP484 annotated arguments and arguments with default values will have their\ntypes converted before they are passed to your function.\n```python\n# my_cli.py\n\nfrom typing import Tuple \n\nfrom main_dec import main\n\n\n@main\ndef run(required_float: float, optional_tuple: Tuple[float, ...] = ()):\n    print('required_float', required_float)\n    print('optional_tuple', optional_tuple)\n```\n```console\n\u003e python -m my_cli 1 --optional-tuple 2 3 4\nrequired_float 1.0\noptional_tuple (2.0, 3.0, 4.0)\n```\nCurrently supported types are `str`, `bytes`, `int`, `float`, `list` (including `typing.List`), `tuple` \n(including `typing.Tuple`) and `Enum`. `str` is the default type\nfor arguments that are not annotated and do not have a default value.\n## Tuple arguments\nTuple arguments can either be parsed as varied length tuples, or fixed length tuples.\n\nFixed length tuples are arguments that are annotated without `...` as a type variable,\nor arguments with default values with mixed types\n\n```python\n# my_cli.py\n\nfrom typing import Tuple\n\nfrom main_dec import main\n\n\n@main\ndef run(fixed_length_tuple1: Tuple[int, int], fixed_length_tuple2=(1, 'arg')):\n    pass\n```\n\n```console\n\u003e python -m my_cli -h\nusage: my_cli [-h] [--fixed-length-tuple2 FIXED_LENGTH_TUPLE2 FIXED_LENGTH_TUPLE2] fixed_length_tuple1 fixed_length_tuple1\n\npositional arguments:\n  fixed_length_tuple1\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --fixed-length-tuple2 FIXED_LENGTH_TUPLE2 FIXED_LENGTH_TUPLE2\n```\n\nVaried length tuples are arguments that\n\n- Are annotated with `...` as a type variable (e.g `Tuple[int, ...]`)\n- Are annotated simply with `Tuple` or `tuple`\n- Have a tuple as a default value with homogeneous types (e.g `(1, 2)`)\n## Enum arguments\nArguments annotated with`Enum`, or with a default `Enum` type, can be used\nto enforce that an argument must have certain values.\n\n```python\n# my_cli.py\n\nfrom enum import Enum\n\nfrom main_dec import main\n\nclass Choice(Enum):\n    first = 1\n    second = 2\n\n@main\ndef run(argument_with_choices: Choice):\n    print('argument_with_choices', argument_with_choices)\n```\n```console\n\u003e python -b my_cli -h\nusage: my_cli [-h] {first,second}\n\npositional arguments:\n  {first,second}\n\noptional arguments:\n  -h, --help      show this help message and exit\n \n\u003e python -m my_cli second\nargument_with_choices Choice.second\n```\n\nThis can be combined with generic types such as `typing.Tuple` and `typing.List`, as well\nas arguments with default arguments that are `tuple` or `list` types with `Enum` elements. \n\n## CLI Documentation\nDoc strings in ReST or Google style are parsed and used to create usage\nand help messages\n```python\n# my_cli.py\n\nfrom main_dec import main\n\n@main\ndef run(arg: str):\n    \"\"\"\n    An example cli\n    \n    :param arg: A required argument\n    \"\"\"\n```\n\n```console\n\u003e python -m my_cli -h\nusage: my_cli [-h] arg\n\nAn example cli\n\npositional arguments:\n  arg         A required argument\n\noptional arguments:\n  -h, --help  show this help message and exit\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuned%2Fmain-dec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuned%2Fmain-dec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuned%2Fmain-dec/lists"}