{"id":15710155,"url":"https://github.com/omni-us/jsonargparse","last_synced_at":"2025-05-14T10:05:09.742Z","repository":{"id":34851351,"uuid":"184562685","full_name":"omni-us/jsonargparse","owner":"omni-us","description":"Implement minimal boilerplate CLIs derived from type hints and parse from command line, config files and environment variables","archived":false,"fork":false,"pushed_at":"2025-05-08T12:28:49.000Z","size":9966,"stargazers_count":363,"open_issues_count":34,"forks_count":53,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-08T13:31:47.080Z","etag":null,"topics":["argparse","argparse-alternative","argument-parser","cli","configuration-files","dataclasses","environment-variables","json","jsonnet","python","python3","toml","type-hints","yaml"],"latest_commit_sha":null,"homepage":"https://jsonargparse.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/omni-us.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":".github/FUNDING.yaml","license":"LICENSE.rst","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"mauvilsa"}},"created_at":"2019-05-02T10:36:48.000Z","updated_at":"2025-05-08T12:28:51.000Z","dependencies_parsed_at":"2023-01-15T09:34:31.660Z","dependency_job_id":"a284c07e-cc59-403b-b4cf-9b39769c8123","html_url":"https://github.com/omni-us/jsonargparse","commit_stats":{"total_commits":1025,"total_committers":29,"mean_commits":35.3448275862069,"dds":0.2985365853658537,"last_synced_commit":"442f9bf63745cc4dd3f443771bb96a317674f6b0"},"previous_names":[],"tags_count":229,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omni-us%2Fjsonargparse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omni-us%2Fjsonargparse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omni-us%2Fjsonargparse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omni-us%2Fjsonargparse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omni-us","download_url":"https://codeload.github.com/omni-us/jsonargparse/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254119469,"owners_count":22017951,"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":["argparse","argparse-alternative","argument-parser","cli","configuration-files","dataclasses","environment-variables","json","jsonnet","python","python3","toml","type-hints","yaml"],"created_at":"2024-10-03T21:03:59.092Z","updated_at":"2025-05-14T10:05:09.733Z","avatar_url":"https://github.com/omni-us.png","language":"Python","readme":".. image:: https://readthedocs.org/projects/jsonargparse/badge/?version=stable\n    :target: https://readthedocs.org/projects/jsonargparse/\n.. image:: https://github.com/omni-us/jsonargparse/actions/workflows/tests.yaml/badge.svg\n    :target: https://github.com/omni-us/jsonargparse/actions/workflows/tests.yaml\n.. image:: https://codecov.io/gh/omni-us/jsonargparse/branch/main/graph/badge.svg\n    :target: https://codecov.io/gh/omni-us/jsonargparse\n.. image:: https://sonarcloud.io/api/project_badges/measure?project=omni-us_jsonargparse\u0026metric=alert_status\n    :target: https://sonarcloud.io/dashboard?id=omni-us_jsonargparse\n.. image:: https://badge.fury.io/py/jsonargparse.svg\n    :target: https://badge.fury.io/py/jsonargparse\n\n\njsonargparse\n============\n\nDocs: https://jsonargparse.readthedocs.io/ | Source: https://github.com/omni-us/jsonargparse/\n\n``jsonargparse`` is a library for creating command-line interfaces (CLIs) and\nmaking Python apps easily configurable. It is a well-maintained project with\nfrequent releases, adhering to high standards of development: semantic\nversioning, deprecation periods, changelog, automated testing, and full test\ncoverage.\n\nAlthough ``jsonargparse`` might not be widely recognized yet, it already boasts\na `substantial user base\n\u003chttps://github.com/omni-us/jsonargparse/network/dependents\u003e`__. Most notably,\nit serves as the framework behind pytorch-lightning's `LightningCLI\n\u003chttps://lightning.ai/docs/pytorch/stable/cli/lightning_cli.html\u003e`__.\n\nTeaser examples\n---------------\n\nCLI with minimal boilerplate:\n\n.. code-block:: python\n\n    from jsonargparse import auto_cli\n\n    def main_function(...):  # your main parameters and logic here\n        ...\n\n    if __name__ == \"__main__\":\n        auto_cli(main_function)  # parses arguments and runs main_function\n\nMinimal boilerplate but manually parsing:\n\n.. code-block:: python\n\n    from jsonargparse import auto_parser\n\n    ...\n\n    if __name__ == \"__main__\":\n        parser = auto_parser(main_function)\n        cfg = parser.parse_args()\n        ...\n\nPowerful argparse-like low level parsers:\n\n.. code-block:: python\n\n    from typing import Union, Literal\n    from jsonargparse import ArgumentParser\n\n    parser = ArgumentParser()\n    parser.add_argument(\"--config\", action=\"config\")  # support config files\n    parser.add_argument(\"--opt\", type=Union[int, Literal[\"off\"]])  # complex arguments via type hints\n    parser.add_function_arguments(main_function, \"function\")  # add function parameters\n    parser.add_class_arguments(SomeClass, \"class\")  # add class parameters\n    ...\n    cfg = parser.parse_args()\n    init = parser.instantiate_classes(cfg)\n    ...\n\n\nFeatures\n--------\n\n``jsonargparse`` is user-friendly and encourages the development of **clean,\nhigh-quality code**. It encompasses numerous powerful features, some unique to\n``jsonargparse``, while also combining advantages found in similar packages:\n\n- **Automatic** creation of CLIs, like `Fire\n  \u003chttps://pypi.org/project/fire/\u003e`__, `Typer\n  \u003chttps://pypi.org/project/typer/\u003e`__, `Clize\n  \u003chttps://pypi.org/project/clize/\u003e`__ and `Tyro\n  \u003chttps://pypi.org/project/tyro/\u003e`__.\n\n- Use **type hints** for argument validation, like `Typer\n  \u003chttps://pypi.org/project/typer/\u003e`__, `Tap\n  \u003chttps://pypi.org/project/typed-argument-parser/\u003e`__ and `Tyro\n  \u003chttps://pypi.org/project/tyro/\u003e`__.\n\n- Use of **docstrings** for automatic generation of help, like `Tap\n  \u003chttps://pypi.org/project/typed-argument-parser/\u003e`__, `Tyro\n  \u003chttps://pypi.org/project/tyro/\u003e`__ and `SimpleParsing\n  \u003chttps://pypi.org/project/simple-parsing/\u003e`__.\n\n- Parse from **configuration files** and **environment variables**, like\n  `OmegaConf \u003chttps://pypi.org/project/omegaconf/\u003e`__, `dynaconf\n  \u003chttps://pypi.org/project/dynaconf/\u003e`__, `confuse\n  \u003chttps://pypi.org/project/confuse/\u003e`__ and `configargparse\n  \u003chttps://pypi.org/project/ConfigArgParse/\u003e`__.\n\n- **Dataclasses** support, like `SimpleParsing\n  \u003chttps://pypi.org/project/simple-parsing/\u003e`__ and `Tyro\n  \u003chttps://pypi.org/project/tyro/\u003e`__.\n\nOther notable features include:\n\n- **Extensive type hint support:** nested types (union, optional), containers\n  (list, dict, etc.), user-defined generics, restricted types (regex, numbers),\n  paths, URLs, types from stubs (``*.pyi``), future annotations (PEP `563\n  \u003chttps://peps.python.org/pep-0563/\u003e`__), and backports (PEPs `604\n  \u003chttps://peps.python.org/pep-0604\u003e`__/`585\n  \u003chttps://peps.python.org/pep-0585\u003e`__).\n\n- **Keyword arguments introspection:** resolving of parameters used via\n  ``**kwargs``.\n\n- **Dependency injection:** support types that expect a class instance and\n  callables that return a class instance.\n\n- **Structured configs:** parse config files with more understandable non-flat\n  hierarchies.\n\n- **Config file formats:** `json \u003chttps://www.json.org/\u003e`__, `yaml\n  \u003chttps://yaml.org/\u003e`__, `toml \u003chttps://toml.io/\u003e`__, `jsonnet\n  \u003chttps://jsonnet.org/\u003e`__ and extendable to more formats.\n\n- **Relative paths:** within config files and parsing of config paths referenced\n  inside other configs.\n\n- **Argument linking:** directing parsed values to multiple parameters,\n  preventing unnecessary interpolation in configs.\n\n\nDesign principles\n-----------------\n\n- **Non-intrusive/decoupled:**\n\n  There is no requirement for unrelated modifications throughout a codebase,\n  maintaining the `separation of concerns principle\n  \u003chttps://en.wikipedia.org/wiki/Separation_of_concerns\u003e`__. In simpler terms,\n  changes should make sense even without the CLI. No need to inherit from a\n  special class, add decorators, or use CLI-specific type hints.\n\n- **Minimal boilerplate:**\n\n  A recommended practice is to write code with function/class parameters having\n  meaningful names, accurate type hints, and descriptive docstrings. Reuse these\n  wherever they appear to automatically generate the CLI, following the `don't\n  repeat yourself principle\n  \u003chttps://en.wikipedia.org/wiki/Don%27t_repeat_yourself\u003e`__. A notable\n  advantage is that when parameters are added or types changed, the CLI will\n  remain synchronized, avoiding the need to update the CLI's implementation.\n\n- **Dependency injection:**\n\n  Using as type hint a class or a callable that instantiates a class, a practice\n  known as `dependency injection\n  \u003chttps://en.wikipedia.org/wiki/Dependency_injection\u003e`__, is a sound design\n  pattern for developing loosely coupled and highly configurable software. Such\n  type hints should be supported with minimal restrictions.\n\n\n.. _installation:\n\nInstallation\n============\n\nYou can install using `pip \u003chttps://pypi.org/project/jsonargparse/\u003e`__ as:\n\n.. code-block:: bash\n\n    pip install jsonargparse\n\nBy default the only dependency that jsonargparse installs is `PyYAML\n\u003chttps://pypi.org/project/PyYAML/\u003e`__. However, several optional features can be\nenabled by specifying any of the following extras requires: ``signatures``,\n``jsonschema``, ``jsonnet``, ``urls``, ``fsspec``, ``toml``, ``ruyaml``,\n``omegaconf``, ``shtab`` and ``argcomplete``. There is also the ``all`` extras\nrequire to enable all optional features (excluding tab completion ones).\nInstalling jsonargparse with extras require is as follows:\n\n.. code-block:: bash\n\n    pip install \"jsonargparse[signatures,urls]\"  # Enable signatures and URLs features\n    pip install \"jsonargparse[all]\"              # Enable all optional features\n","funding_links":["https://github.com/sponsors/mauvilsa"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomni-us%2Fjsonargparse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomni-us%2Fjsonargparse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomni-us%2Fjsonargparse/lists"}