| Name | jsonargparse JSON |
| Version |
4.41.0
JSON |
| download |
| home_page | None |
| Summary | Implement minimal boilerplate CLIs derived from type hints and parse from command line, config files and environment variables. |
| upload_time | 2025-09-04 03:46:34 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. image:: https://readthedocs.org/projects/jsonargparse/badge/?version=stable
:target: https://readthedocs.org/projects/jsonargparse/
.. image:: https://github.com/omni-us/jsonargparse/actions/workflows/tests.yaml/badge.svg
:target: https://github.com/omni-us/jsonargparse/actions/workflows/tests.yaml
.. image:: https://codecov.io/gh/omni-us/jsonargparse/branch/main/graph/badge.svg
:target: https://codecov.io/gh/omni-us/jsonargparse
.. image:: https://sonarcloud.io/api/project_badges/measure?project=omni-us_jsonargparse&metric=alert_status
:target: https://sonarcloud.io/dashboard?id=omni-us_jsonargparse
.. image:: https://badge.fury.io/py/jsonargparse.svg
:target: https://badge.fury.io/py/jsonargparse
jsonargparse
============
Docs: https://jsonargparse.readthedocs.io/ | Source: https://github.com/omni-us/jsonargparse/
``jsonargparse`` is a library for creating command-line interfaces (CLIs) and
making Python apps easily configurable. It is a well-maintained project with
frequent releases, adhering to high standards of development: semantic
versioning, deprecation periods, changelog, automated testing, and full test
coverage.
Although ``jsonargparse`` might not be widely recognized yet, it already boasts
a `substantial user base
<https://github.com/omni-us/jsonargparse/network/dependents>`__. Most notably,
it serves as the framework behind pytorch-lightning's `LightningCLI
<https://lightning.ai/docs/pytorch/stable/cli/lightning_cli.html>`__.
Teaser examples
---------------
CLI with minimal boilerplate:
.. code-block:: python
from jsonargparse import auto_cli
def main_function(...): # your main parameters and logic here
...
if __name__ == "__main__":
auto_cli(main_function) # parses arguments and runs main_function
Minimal boilerplate but manually parsing:
.. code-block:: python
from jsonargparse import auto_parser
parser = auto_parser(main_function)
cfg = parser.parse_args()
...
Powerful argparse-like low level parsers:
.. code-block:: python
from jsonargparse import ArgumentParser
parser = ArgumentParser()
parser.add_argument("--config", action="config") # support config files
parser.add_argument("--opt", type=Union[int, Literal["off"]]) # complex arguments via type hints
parser.add_function_arguments(main_function, "function") # add function parameters
parser.add_class_arguments(SomeClass, "class") # add class parameters
...
cfg = parser.parse_args()
init = parser.instantiate_classes(cfg)
...
Features
--------
``jsonargparse`` is user-friendly and encourages the development of **clean,
high-quality code**. It encompasses numerous powerful features, some unique to
``jsonargparse``, while also combining advantages found in similar packages:
- **Automatic** creation of CLIs, like `Fire
<https://pypi.org/project/fire/>`__, `Typer
<https://pypi.org/project/typer/>`__, `Clize
<https://pypi.org/project/clize/>`__ and `Tyro
<https://pypi.org/project/tyro/>`__.
- Use **type hints** for argument validation, like `Typer
<https://pypi.org/project/typer/>`__, `Tap
<https://pypi.org/project/typed-argument-parser/>`__ and `Tyro
<https://pypi.org/project/tyro/>`__.
- Use of **docstrings** for automatic generation of help, like `Tap
<https://pypi.org/project/typed-argument-parser/>`__, `Tyro
<https://pypi.org/project/tyro/>`__ and `SimpleParsing
<https://pypi.org/project/simple-parsing/>`__.
- Parse from **configuration files** and **environment variables**, like
`OmegaConf <https://pypi.org/project/omegaconf/>`__, `dynaconf
<https://pypi.org/project/dynaconf/>`__, `confuse
<https://pypi.org/project/confuse/>`__ and `configargparse
<https://pypi.org/project/ConfigArgParse/>`__.
- **Dataclasses** support, like `SimpleParsing
<https://pypi.org/project/simple-parsing/>`__ and `Tyro
<https://pypi.org/project/tyro/>`__.
Other notable features include:
- **Extensive type hint support:** nested types (union, optional), containers
(list, dict, etc.), protocols, user-defined generics, restricted types (regex,
numbers), paths, URLs, types from stubs (``*.pyi``), future annotations (PEP
`563 <https://peps.python.org/pep-0563/>`__), and backports (PEP `604
<https://peps.python.org/pep-0604>`__).
- **Keyword arguments introspection:** resolving of parameters used via
``**kwargs``.
- **Dependency injection:** support types that expect a class instance and
callables that return a class instance.
- **Structured configs:** parse config files with more understandable non-flat
hierarchies.
- **Config file formats:** `json <https://www.json.org/>`__, `yaml
<https://yaml.org/>`__, `toml <https://toml.io/>`__, `jsonnet
<https://jsonnet.org/>`__ and extensible to more formats.
- **Relative paths:** within config files and parsing of config paths referenced
inside other configs.
- **Argument linking:** directing parsed values to multiple parameters,
preventing unnecessary interpolation in configs.
- **Variable interpolation:** powered by `OmegaConf
<https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation>`__.
- **Tab completion:** powered by `shtab
<https://pypi.org/project/shtab/>`__ or `argcomplete
<https://pypi.org/project/argcomplete/>`__.
Design principles
-----------------
- **Non-intrusive/decoupled:**
There is no requirement for unrelated modifications throughout a codebase,
maintaining the `separation of concerns principle
<https://en.wikipedia.org/wiki/Separation_of_concerns>`__. In simpler terms,
changes should make sense even without the CLI. No need to inherit from a
special class, add decorators, or use CLI-specific type hints.
- **Minimal boilerplate:**
A recommended practice is to write code with function/class parameters having
meaningful names, accurate type hints, and descriptive docstrings. Reuse these
wherever they appear to automatically generate the CLI, following the `don't
repeat yourself principle
<https://en.wikipedia.org/wiki/Don%27t_repeat_yourself>`__. A notable
advantage is that when parameters are added or types changed, the CLI will
remain synchronized, avoiding the need to update the CLI's implementation.
- **Dependency injection:**
Using as type hint a class or a callable that instantiates a class, a practice
known as `dependency injection
<https://en.wikipedia.org/wiki/Dependency_injection>`__, is a sound design
pattern for developing loosely coupled and highly configurable software. Such
type hints should be supported with minimal restrictions.
.. _installation:
Installation
============
You can install using `pip <https://pypi.org/project/jsonargparse/>`__ as:
.. code-block:: bash
pip install jsonargparse
By default, the only dependency installed with ``jsonargparse`` is `PyYAML
<https://pypi.org/project/PyYAML/>`__. However, several optional features can be
enabled by specifying one or more of the following extras (optional
dependencies): ``signatures``, ``jsonschema``, ``jsonnet``, ``urls``,
``fsspec``, ``toml``, ``ruamel``, ``omegaconf``, ``shtab``, and ``argcomplete``.
Additionally, the ``all`` extras can be used to enable all optional features
(excluding tab completion ones). To install ``jsonargparse`` with extras, use
the following syntax:
.. code-block:: bash
pip install "jsonargparse[signatures,urls]" # Enable signatures and URLs features
pip install "jsonargparse[all]" # Enable all optional features
To install the latest development version, use the following command:
.. code-block:: bash
pip install "jsonargparse[signatures] @ git+https://github.com/omni-us/jsonargparse.git@main"
Raw data
{
"_id": null,
"home_page": null,
"name": "jsonargparse",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Mauricio Villegas <mauricio@omnius.com>",
"download_url": "https://files.pythonhosted.org/packages/44/86/60032fb5623df8d938d31f733e4b3385c40791d85d0fae3dfb4e3be10c42/jsonargparse-4.41.0.tar.gz",
"platform": "Any",
"description": ".. 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&metric=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<https://github.com/omni-us/jsonargparse/network/dependents>`__. Most notably,\nit serves as the framework behind pytorch-lightning's `LightningCLI\n<https://lightning.ai/docs/pytorch/stable/cli/lightning_cli.html>`__.\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 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 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 <https://pypi.org/project/fire/>`__, `Typer\n <https://pypi.org/project/typer/>`__, `Clize\n <https://pypi.org/project/clize/>`__ and `Tyro\n <https://pypi.org/project/tyro/>`__.\n\n- Use **type hints** for argument validation, like `Typer\n <https://pypi.org/project/typer/>`__, `Tap\n <https://pypi.org/project/typed-argument-parser/>`__ and `Tyro\n <https://pypi.org/project/tyro/>`__.\n\n- Use of **docstrings** for automatic generation of help, like `Tap\n <https://pypi.org/project/typed-argument-parser/>`__, `Tyro\n <https://pypi.org/project/tyro/>`__ and `SimpleParsing\n <https://pypi.org/project/simple-parsing/>`__.\n\n- Parse from **configuration files** and **environment variables**, like\n `OmegaConf <https://pypi.org/project/omegaconf/>`__, `dynaconf\n <https://pypi.org/project/dynaconf/>`__, `confuse\n <https://pypi.org/project/confuse/>`__ and `configargparse\n <https://pypi.org/project/ConfigArgParse/>`__.\n\n- **Dataclasses** support, like `SimpleParsing\n <https://pypi.org/project/simple-parsing/>`__ and `Tyro\n <https://pypi.org/project/tyro/>`__.\n\n\nOther notable features include:\n\n- **Extensive type hint support:** nested types (union, optional), containers\n (list, dict, etc.), protocols, user-defined generics, restricted types (regex,\n numbers), paths, URLs, types from stubs (``*.pyi``), future annotations (PEP\n `563 <https://peps.python.org/pep-0563/>`__), and backports (PEP `604\n <https://peps.python.org/pep-0604>`__).\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 <https://www.json.org/>`__, `yaml\n <https://yaml.org/>`__, `toml <https://toml.io/>`__, `jsonnet\n <https://jsonnet.org/>`__ and extensible 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- **Variable interpolation:** powered by `OmegaConf\n <https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation>`__.\n\n- **Tab completion:** powered by `shtab\n <https://pypi.org/project/shtab/>`__ or `argcomplete\n <https://pypi.org/project/argcomplete/>`__.\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 <https://en.wikipedia.org/wiki/Separation_of_concerns>`__. 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 <https://en.wikipedia.org/wiki/Don%27t_repeat_yourself>`__. 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 <https://en.wikipedia.org/wiki/Dependency_injection>`__, 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 <https://pypi.org/project/jsonargparse/>`__ as:\n\n.. code-block:: bash\n\n pip install jsonargparse\n\nBy default, the only dependency installed with ``jsonargparse`` is `PyYAML\n<https://pypi.org/project/PyYAML/>`__. However, several optional features can be\nenabled by specifying one or more of the following extras (optional\ndependencies): ``signatures``, ``jsonschema``, ``jsonnet``, ``urls``,\n``fsspec``, ``toml``, ``ruamel``, ``omegaconf``, ``shtab``, and ``argcomplete``.\nAdditionally, the ``all`` extras can be used to enable all optional features\n(excluding tab completion ones). To install ``jsonargparse`` with extras, use\nthe following syntax:\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\nTo install the latest development version, use the following command:\n\n.. code-block:: bash\n\n pip install \"jsonargparse[signatures] @ git+https://github.com/omni-us/jsonargparse.git@main\"\n",
"bugtrack_url": null,
"license": null,
"summary": "Implement minimal boilerplate CLIs derived from type hints and parse from command line, config files and environment variables.",
"version": "4.41.0",
"project_urls": {
"Changes": "https://jsonargparse.readthedocs.io/en/stable/changelog.html",
"Codecov": "https://codecov.io/gh/omni-us/jsonargparse",
"Documentation-latest": "https://jsonargparse.readthedocs.io/en/latest/",
"Documentation-stable": "https://jsonargparse.readthedocs.io/en/stable/",
"GitHub": "https://github.com/omni-us/jsonargparse",
"PyPI": "https://pypi.org/project/jsonargparse",
"SonarCloud": "https://sonarcloud.io/dashboard?id=omni-us_jsonargparse"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "62fc6ac1943f22f3d2e14703335d64a7d68496f0480c82a3077cde44b2c55ef5",
"md5": "c6628f54886782a8791d044a0fd59f9a",
"sha256": "cd49b6a2fea723ee4d80f9df034f51af226128a7f166be8755d6acdeb3e077a7"
},
"downloads": -1,
"filename": "jsonargparse-4.41.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c6628f54886782a8791d044a0fd59f9a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 228528,
"upload_time": "2025-09-04T03:46:32",
"upload_time_iso_8601": "2025-09-04T03:46:32.668031Z",
"url": "https://files.pythonhosted.org/packages/62/fc/6ac1943f22f3d2e14703335d64a7d68496f0480c82a3077cde44b2c55ef5/jsonargparse-4.41.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "448660032fb5623df8d938d31f733e4b3385c40791d85d0fae3dfb4e3be10c42",
"md5": "571f398069a0efee6151ffb7512c22d6",
"sha256": "ba1806bf0ed0ad1975e403dffb18b3a755fee3bfe4e7b36d8cce2f297b552b5f"
},
"downloads": -1,
"filename": "jsonargparse-4.41.0.tar.gz",
"has_sig": false,
"md5_digest": "571f398069a0efee6151ffb7512c22d6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 206634,
"upload_time": "2025-09-04T03:46:34",
"upload_time_iso_8601": "2025-09-04T03:46:34.715252Z",
"url": "https://files.pythonhosted.org/packages/44/86/60032fb5623df8d938d31f733e4b3385c40791d85d0fae3dfb4e3be10c42/jsonargparse-4.41.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 03:46:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "omni-us",
"github_project": "jsonargparse",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jsonargparse"
}
