{"id":19478180,"url":"https://github.com/yuanx749/config-argument-parser","last_synced_at":"2025-04-04T16:09:17.945Z","repository":{"id":54403721,"uuid":"441851688","full_name":"yuanx749/config-argument-parser","owner":"yuanx749","description":"A package to help automatically create command-line interface from configuration or code.","archived":false,"fork":false,"pushed_at":"2024-11-21T09:39:05.000Z","size":43,"stargazers_count":127,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2025-03-28T15:03:47.584Z","etag":null,"topics":["command-line-interface","package","tool"],"latest_commit_sha":null,"homepage":"http://config-argument-parser.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yuanx749.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-26T09:16:28.000Z","updated_at":"2025-03-11T10:54:02.000Z","dependencies_parsed_at":"2024-07-28T12:41:34.168Z","dependency_job_id":"43dbac44-19d7-4029-bead-aa7e150f44a4","html_url":"https://github.com/yuanx749/config-argument-parser","commit_stats":{"total_commits":36,"total_committers":1,"mean_commits":36.0,"dds":0.0,"last_synced_commit":"efad6b9a8ff632c096c454119abba030b976da64"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanx749%2Fconfig-argument-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanx749%2Fconfig-argument-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanx749%2Fconfig-argument-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanx749%2Fconfig-argument-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yuanx749","download_url":"https://codeload.github.com/yuanx749/config-argument-parser/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247208143,"owners_count":20901570,"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":["command-line-interface","package","tool"],"created_at":"2024-11-10T19:47:28.065Z","updated_at":"2025-04-04T16:09:17.919Z","avatar_url":"https://github.com/yuanx749.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# config-argument-parser\r\n\r\n[![PyPI version](https://badge.fury.io/py/config-argument-parser.svg)](https://badge.fury.io/py/config-argument-parser)\r\n[![Downloads](https://static.pepy.tech/badge/config-argument-parser/month)](https://pepy.tech/project/config-argument-parser)\r\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/b15383188a354af684ba9d49b09cc253)](https://app.codacy.com/gh/yuanx749/config-argument-parser/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\r\n[![Maintainability](https://api.codeclimate.com/v1/badges/288bbabbf406afe66e37/maintainability)](https://codeclimate.com/github/yuanx749/config-argument-parser/maintainability)\r\n[![codecov](https://codecov.io/gh/yuanx749/config-argument-parser/branch/dev/graph/badge.svg?token=W34MFRGVMY)](https://codecov.io/gh/yuanx749/config-argument-parser)\r\n[![Documentation Status](https://readthedocs.org/projects/config-argument-parser/badge/?version=latest)](https://config-argument-parser.readthedocs.io/en/latest/?badge=latest)\r\n\r\nA package to help automatically create command-line interface from configuration or code.\r\n\r\nIt contains three modules CAP🧢(`ConfigArgumentParser`), TAP🚰(`TypeArgumentParser`), and GAP🕳️(`GlobalArgumentParser`).\r\n\r\nRead the documentation [here](http://config-argument-parser.readthedocs.io/).\r\n\r\n## Motivation\r\n\r\nConfiguration files are highly readable and useful for specifying options, but sometimes they are not convenient as command-line interface. However, it requires writing a lot of code to produce a CLI. This package automates the building process, by utilizing the Python standard libraries `configparser` and `argparse`.\r\n\r\nThe design is to minimize the changes to your original scripts, so as to facilitate maintenance.\r\n\r\n## Features\r\n\r\n- Only few extra lines are needed to build a CLI from an existing script.\r\n- The comments are parsed as help messages. (Most libraries do not preserve the comments.)\r\n- Consistent format between configuration and script provides ease of use.\r\n\r\n## Usage\r\n\r\n### Case 1: create CLI from an object\r\n\r\nIf you use class to store arguments, such as the script `example.py` below.\r\n\r\n```Python\r\nimport configargparser\r\n\r\nclass Args:\r\n    # Help message of the first argument. Help is optional.\r\n    a_string = \"abc\"\r\n    a_float = 1.23  # inline comments are omitted\r\n    # Help can span multiple lines.\r\n    # This is another line.\r\n    a_boolean = False\r\n    an_integer = 0\r\n\r\nargs = Args()\r\n\r\nparser = configargparser.ConfigArgumentParser()\r\nparser.parse_obj(args, shorts=\"sfb\")\r\n\r\nprint(args.a_string)\r\nprint(args.a_float)\r\nprint(args.a_boolean)\r\nprint(args.an_integer)\r\n```\r\n\r\nIn fact, only the snippet below is added to the original script. Moreover, removing this minimal modification does not affect the original script. `shorts` is optional. If provided, add short options for the first few arguments in order.\r\n\r\n```Python\r\nimport configargparser\r\nparser = configargparser.ConfigArgumentParser()\r\nparser.parse_obj(args)\r\n```\r\n\r\nDefault arguments are defined as class attributes, and parsed arguments are stored as instance attributes. The good is that auto-completion can be triggered in editors.\r\n\r\nShow help, `python example.py -h`:\r\n\r\n```console\r\n$ python example.py -h\r\nusage: example.py [-h] [-s A_STRING] [-f A_FLOAT] [-b] [--an-integer AN_INTEGER]\r\n\r\noptions:\r\n  -h, --help            show this help message and exit\r\n  -s A_STRING, --a-string A_STRING\r\n                        Help message of the first argument. Help is optional. (default: abc)\r\n  -f A_FLOAT, --a-float A_FLOAT\r\n                        a_float (default: 1.23)\r\n  -b, --a-boolean       Help can span multiple lines. This is another line. (default: False)\r\n  --an-integer AN_INTEGER\r\n                        an_integer (default: 0)\r\n```\r\n\r\nRun with options, for example, `python example.py -b -f 1`:\r\n\r\n```console\r\n$ python example.py -b -f 1\r\nabc\r\n1.0\r\nTrue\r\n0\r\n```\r\n\r\nNote that the values are changed.\r\n\r\nFor the best practice, see [Case 4](#case-4-create-cli-from-a-dataclass-object-preferred).\r\n\r\n### Case 2: create CLI from configuration\r\n\r\nIf you use configuration file, create an example script `example.py`:\r\n\r\n```Python\r\nimport configargparser\r\n\r\nparser = configargparser.ConfigArgumentParser()\r\nparser.read(\"config.ini\")\r\nparser.parse_args(shorts=\"sfb\")\r\n\r\nprint(\"Configs:\", parser.defaults)\r\nprint(\"Args:   \", parser.args)\r\n```\r\n\r\nCreate a configuration file `config.ini` in the same directory:\r\n\r\n```ini\r\n[DEFAULT]\r\n# Help message of the first argument. Help is optional.\r\na_string = 'abc'\r\na_float = 1.23  # inline comments are omitted\r\n# Help can span multiple lines.\r\n# This is another line.\r\na_boolean = False\r\nan_integer = 0\r\n```\r\n\r\nRegular run, `python example.py`:\r\n\r\n```console\r\n$ python example.py\r\nConfigs: {'a_string': 'abc', 'a_float': 1.23, 'a_boolean': False, 'an_integer': 0}\r\nArgs:    {'a_string': 'abc', 'a_float': 1.23, 'a_boolean': False, 'an_integer': 0}\r\n```\r\n\r\nRun with options, such as `python example.py -b -f 1`:\r\n\r\n```console\r\n$ python example.py -b -f 1\r\nConfigs: {'a_string': 'abc', 'a_float': 1.23, 'a_boolean': False, 'an_integer': 0}\r\nArgs:    {'a_string': 'abc', 'a_float': 1.0, 'a_boolean': True, 'an_integer': 0}\r\n```\r\n\r\n### Case 3: create CLI from global variables\r\n\r\nIf you use global variables, define the variables at top of file as the script `example.py` below:\r\n\r\n```Python\r\n# [DEFAULT]\r\n# Help message of the first argument. Help is optional.\r\na_string = \"abc\"\r\na_float = 1.23  # inline comments are omitted\r\n# Help can span multiple lines.\r\n# This is another line.\r\na_boolean = False\r\nan_integer = 0\r\n# [END]\r\n\r\nimport configargparser\r\n\r\nparser = configargparser.ConfigArgumentParser()\r\nparser.read_py(\"example.py\")\r\nparser.parse_args(shorts=\"sfb\")\r\n\r\n# update global variables\r\nglobals().update(parser.args)\r\nprint(a_string)\r\nprint(a_float)\r\nprint(a_boolean)\r\nprint(an_integer)\r\n```\r\n\r\nUse it as in case 1. For example, `python example.py -b -f 1`:\r\n\r\n```console\r\n$ python example.py -b -f 1\r\nabc\r\n1.0\r\nTrue\r\n0\r\n```\r\n\r\n### Case 4: create CLI from a dataclass object (preferred)\r\n\r\nSuppose you have a script `example.py` below, which uses a `dataclass` object to store arguments:\r\n\r\n```Python\r\nfrom dataclasses import dataclass\r\n\r\n@dataclass\r\nclass Args:\r\n    # Help message of the first argument. Help is optional.\r\n    a_string: str = \"abc\"\r\n    a_float: float = 1.23  # inline comments are omitted\r\n    # Help can span multiple lines.\r\n    # This is another line.\r\n    a_boolean: bool = False\r\n    an_integer: int = 0\r\n\r\nargs = Args()\r\n```\r\n\r\nAdd these lines to the script to create CLI:\r\n\r\n```Python\r\nimport configargparser\r\nparser = configargparser.TypeArgumentParser()\r\nparser.parse_obj(args, shorts=\"sfb\")\r\n\r\nprint(args)\r\n```\r\n\r\nUse it as in case 1. For example, `python example.py -b -f 1` to change the values:\r\n\r\n```console\r\n$ python example.py -b -f 1\r\nArgs(a_string='abc', a_float=1.0, a_boolean=True, an_integer=0)\r\n```\r\n\r\n### Case 5: create CLI from global variables (without comments)\r\n\r\nThis requires less code than case 3, but the comments are not parsed, as the script `example.py` below:\r\n\r\n```Python\r\na_string = \"abc\"\r\na_float = 1.23\r\na_boolean = False\r\nan_integer = 0\r\n\r\nimport configargparser\r\n\r\nparser = configargparser.GlobalArgumentParser()\r\nparser.parse_globals(shorts=\"sfb\")\r\n\r\nprint(a_string)\r\nprint(a_float)\r\nprint(a_boolean)\r\nprint(an_integer)\r\n```\r\n\r\nUse it as in case 1. For example, `python example.py -b -f 1`:\r\n\r\n```console\r\n$ python example.py -b -f 1\r\nabc\r\n1.0\r\nTrue\r\n0\r\n```\r\n\r\n## Installation\r\n\r\nInstall from PyPI:\r\n\r\n```bash\r\npython -m pip install --upgrade pip\r\npip install config-argument-parser\r\n```\r\n\r\nAlternatively, install from source:\r\n\r\n```bash\r\ngit clone https://github.com/yuanx749/config-argument-parser.git\r\ncd config-argument-parser\r\n```\r\n\r\nthen install in development mode:\r\n\r\n```bash\r\ngit checkout main\r\npython -m pip install --upgrade pip\r\npip install -e .\r\n```\r\n\r\nor:\r\n\r\n```bash\r\ngit checkout dev\r\npython -m pip install --upgrade pip\r\npip install -e .[dev]\r\npre-commit install\r\n```\r\n\r\nUninstall:\r\n\r\n```bash\r\npip uninstall config-argument-parser\r\n```\r\n\r\n## Notes\r\n\r\nThis package uses [Semantic Versioning](https://semver.org/).\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuanx749%2Fconfig-argument-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuanx749%2Fconfig-argument-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuanx749%2Fconfig-argument-parser/lists"}