Metadata-Version: 2.4
Name: jsonargparse
Version: 4.42.0
Summary: Implement minimal boilerplate CLIs derived from type hints and parse from command line, config files and environment variables.
Author-email: Mauricio Villegas <mauricio@omnius.com>
License-Expression: MIT
Project-URL: Documentation-stable, https://jsonargparse.readthedocs.io/en/stable/
Project-URL: Documentation-latest, https://jsonargparse.readthedocs.io/en/latest/
Project-URL: Changes, https://jsonargparse.readthedocs.io/en/stable/changelog.html
Project-URL: GitHub, https://github.com/omni-us/jsonargparse
Project-URL: PyPI, https://pypi.org/project/jsonargparse
Project-URL: SonarCloud, https://sonarcloud.io/dashboard?id=omni-us_jsonargparse
Project-URL: Codecov, https://codecov.io/gh/omni-us/jsonargparse
Platform: Any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE.rst
Requires-Dist: PyYAML>=3.13
Provides-Extra: all
Requires-Dist: jsonargparse[signatures]; extra == "all"
Requires-Dist: jsonargparse[jsonschema]; extra == "all"
Requires-Dist: jsonargparse[jsonnet]; extra == "all"
Requires-Dist: jsonargparse[toml]; extra == "all"
Requires-Dist: jsonargparse[urls]; extra == "all"
Requires-Dist: jsonargparse[fsspec]; extra == "all"
Requires-Dist: jsonargparse[ruamel]; extra == "all"
Requires-Dist: jsonargparse[omegaconf]; extra == "all"
Requires-Dist: jsonargparse[typing-extensions]; extra == "all"
Requires-Dist: jsonargparse[reconplogger]; extra == "all"
Provides-Extra: signatures
Requires-Dist: jsonargparse[typing-extensions]; extra == "signatures"
Requires-Dist: docstring-parser>=0.17; extra == "signatures"
Requires-Dist: typeshed-client>=2.8.2; extra == "signatures"
Provides-Extra: jsonschema
Requires-Dist: jsonschema>=3.2.0; extra == "jsonschema"
Provides-Extra: jsonnet
Requires-Dist: jsonnet>=0.21.0; extra == "jsonnet"
Provides-Extra: toml
Requires-Dist: toml>=0.10.2; extra == "toml"
Provides-Extra: urls
Requires-Dist: requests>=2.18.4; extra == "urls"
Provides-Extra: fsspec
Requires-Dist: fsspec>=0.8.4; extra == "fsspec"
Provides-Extra: shtab
Requires-Dist: shtab>=1.7.1; extra == "shtab"
Provides-Extra: argcomplete
Requires-Dist: argcomplete>=3.5.1; extra == "argcomplete"
Provides-Extra: ruamel
Requires-Dist: ruamel.yaml>=0.18.15; extra == "ruamel"
Provides-Extra: ruyaml
Requires-Dist: jsonargparse[ruamel]; extra == "ruyaml"
Provides-Extra: omegaconf
Requires-Dist: omegaconf>=2.1.1; extra == "omegaconf"
Provides-Extra: typing-extensions
Requires-Dist: typing-extensions>=3.10.0.0; python_version < "3.10" and extra == "typing-extensions"
Provides-Extra: reconplogger
Requires-Dist: reconplogger>=4.4.0; extra == "reconplogger"
Provides-Extra: test
Requires-Dist: jsonargparse[test-no-urls]; extra == "test"
Requires-Dist: jsonargparse[shtab]; extra == "test"
Requires-Dist: jsonargparse[argcomplete]; extra == "test"
Requires-Dist: types-PyYAML>=6.0.11; extra == "test"
Requires-Dist: types-requests>=2.28.9; extra == "test"
Requires-Dist: responses>=0.12.0; extra == "test"
Requires-Dist: pydantic>=2.3.0; python_version < "3.14" and extra == "test"
Requires-Dist: attrs>=22.2.0; extra == "test"
Provides-Extra: test-no-urls
Requires-Dist: pytest>=6.2.5; extra == "test-no-urls"
Requires-Dist: pytest-subtests>=0.8.0; extra == "test-no-urls"
Provides-Extra: coverage
Requires-Dist: jsonargparse[test-no-urls]; extra == "coverage"
Requires-Dist: pytest-cov>=4.0.0; extra == "coverage"
Provides-Extra: dev
Requires-Dist: jsonargparse[test]; extra == "dev"
Requires-Dist: jsonargparse[coverage]; extra == "dev"
Requires-Dist: jsonargparse[doc]; extra == "dev"
Requires-Dist: pre-commit>=2.19.0; extra == "dev"
Requires-Dist: tox>=3.25.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Provides-Extra: doc
Requires-Dist: Sphinx>=1.7.9; extra == "doc"
Requires-Dist: sphinx-rtd-theme>=1.2.2; extra == "doc"
Requires-Dist: autodocsumm>=0.1.10; extra == "doc"
Requires-Dist: sphinx-autodoc-typehints>=1.19.5; extra == "doc"
Provides-Extra: maintainer
Requires-Dist: bump2version>=0.5.11; extra == "maintainer"
Requires-Dist: twine>=4.0.2; extra == "maintainer"
Dynamic: license-file

.. 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"
