| Name | jsonargparse JSON |
| Version |
4.36.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-01-17 17:55:47 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | The MIT License (MIT) Copyright (c) 2019-present, Mauricio Villegas <mauricio@omnius.com> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| 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>`__.
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.), 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 (PEPs `604
<https://peps.python.org/pep-0604>`__/`585
<https://peps.python.org/pep-0585>`__).
- **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 extendable 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.
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 that jsonargparse installs is `PyYAML
<https://pypi.org/project/PyYAML/>`__. However, several optional features can be
enabled by specifying any of the following extras requires: ``signatures``,
``jsonschema``, ``jsonnet``, ``urls``, ``fsspec``, ``toml``, ``ruyaml``,
``omegaconf``, ``shtab`` and ``argcomplete``. There is also the ``all`` extras
require to enable all optional features (excluding tab completion ones).
Installing jsonargparse with extras require is as follows:
.. code-block:: bash
pip install "jsonargparse[signatures,urls]" # Enable signatures and URLs features
pip install "jsonargparse[all]" # Enable all optional features
Raw data
{
"_id": null,
"home_page": null,
"name": "jsonargparse",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Mauricio Villegas <mauricio@omnius.com>",
"download_url": "https://files.pythonhosted.org/packages/14/de/dd1e113182865f600d8b1f6c90ec5e584114c18e33f0794d1c43815f05f6/jsonargparse-4.36.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\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\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 <https://peps.python.org/pep-0563/>`__), and backports (PEPs `604\n <https://peps.python.org/pep-0604>`__/`585\n <https://peps.python.org/pep-0585>`__).\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 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 <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 that jsonargparse installs is `PyYAML\n<https://pypi.org/project/PyYAML/>`__. 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",
"bugtrack_url": null,
"license": "The MIT License (MIT) Copyright (c) 2019-present, Mauricio Villegas <mauricio@omnius.com> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Implement minimal boilerplate CLIs derived from type hints and parse from command line, config files and environment variables.",
"version": "4.36.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": "",
"digests": {
"blake2b_256": "e5127134b957ca60fb10692c7701d1ed16928b8b2b331eeaa54bedd3a9dabaf3",
"md5": "e988237b7e0e459cc46a2f23b89b86c6",
"sha256": "1140dc766957857282e81efbb88c51605c948aa3c3517ea98f3265d6df2df627"
},
"downloads": -1,
"filename": "jsonargparse-4.36.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e988237b7e0e459cc46a2f23b89b86c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 214471,
"upload_time": "2025-01-17T17:55:42",
"upload_time_iso_8601": "2025-01-17T17:55:42.075314Z",
"url": "https://files.pythonhosted.org/packages/e5/12/7134b957ca60fb10692c7701d1ed16928b8b2b331eeaa54bedd3a9dabaf3/jsonargparse-4.36.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "14dedd1e113182865f600d8b1f6c90ec5e584114c18e33f0794d1c43815f05f6",
"md5": "ae2debd5f0b327fcf1c268e5b92c8184",
"sha256": "95b9a5df843d0224acae1a9bb780745fa8f206784a87b2b30d5b1db11b00c125"
},
"downloads": -1,
"filename": "jsonargparse-4.36.0.tar.gz",
"has_sig": false,
"md5_digest": "ae2debd5f0b327fcf1c268e5b92c8184",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 193845,
"upload_time": "2025-01-17T17:55:47",
"upload_time_iso_8601": "2025-01-17T17:55:47.076995Z",
"url": "https://files.pythonhosted.org/packages/14/de/dd1e113182865f600d8b1f6c90ec5e584114c18e33f0794d1c43815f05f6/jsonargparse-4.36.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-17 17:55:47",
"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"
}
