Metadata-Version: 2.1
Name: jsonargparse
Version: 4.28.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: 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.
        
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: CircleCI, https://circleci.com/gh/omni-us/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.7
Classifier: Programming Language :: Python :: 3.8
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: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.7
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[urls]; extra == "all"
Requires-Dist: jsonargparse[fsspec]; extra == "all"
Requires-Dist: jsonargparse[argcomplete]; extra == "all"
Requires-Dist: jsonargparse[ruyaml]; 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.15; extra == "signatures"
Requires-Dist: typeshed-client>=2.1.0; extra == "signatures"
Provides-Extra: jsonschema
Requires-Dist: jsonschema>=3.2.0; extra == "jsonschema"
Provides-Extra: jsonnet
Requires-Dist: jsonnet>=0.13.0; os_name == "posix" and extra == "jsonnet"
Requires-Dist: jsonnet-binary>=0.17.0; os_name != "posix" and extra == "jsonnet"
Provides-Extra: urls
Requires-Dist: requests>=2.18.4; extra == "urls"
Provides-Extra: fsspec
Requires-Dist: fsspec>=0.8.4; extra == "fsspec"
Provides-Extra: argcomplete
Requires-Dist: argcomplete>=2.0.0; python_version < "3.8" and extra == "argcomplete"
Requires-Dist: argcomplete>=3.3.0; python_version >= "3.8" and extra == "argcomplete"
Provides-Extra: ruyaml
Requires-Dist: ruyaml>=0.20.0; 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: 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; 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: jsonargparse[mypy]; 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"

.. 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.yml/badge.svg
    :target: https://github.com/omni-us/jsonargparse/actions/workflows/tests.yml
.. 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/>`__, `jsonnet <https://jsonnet.org/>`__ and extendible 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``, ``ruyaml``, ``omegaconf`` and
``argcomplete``. There is also the ``all`` extras require to enable all optional
features. 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
