.. image:: https://readthedocs.org/projects/jsonargparse/badge/?version=stable :target: https://readthedocs.org/projects/jsonargparse/ .. image:: https://github.com/mauvilsa/jsonargparse/actions/workflows/tests.yaml/badge.svg :target: https://github.com/mauvilsa/jsonargparse/actions/workflows/tests.yaml .. image:: https://codecov.io/gh/mauvilsa/jsonargparse/branch/main/graph/badge.svg :target: https://codecov.io/gh/mauvilsa/jsonargparse .. image:: https://sonarcloud.io/api/project_badges/measure?project=mauvilsa_jsonargparse&metric=alert_status&token=74f3ff0af709f6caa0544dfbcf823c49fb68cb46 :target: https://sonarcloud.io/dashboard?id=mauvilsa_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/mauvilsa/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
__. Most notably,
it serves as the framework behind pytorch-lightning's LightningCLI
__.
The documentation is a reference that describes each feature in isolation, which
is not always the best way to learn. If you would rather see the why behind
the features and complete use cases built end to end, have a look at the talks
and articles __
page, which collects presentations, blog posts and example projects.
Teaser examples ---------------
CLI with minimal boilerplate:
.. code-block:: python
from jsonargparse import auto_cli
def main_function(...): # your main parameters with type hints here ... # your main code 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=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(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
__, Typer
__, Clize
__ and Tyro
__.
- Use type hints for argument validation, like
Typer __, Tap
__ and Tyro
__.
- Use of docstrings for automatic generation of help, like
Tap __, Tyro
__ and SimpleParsing
__.
- Parse from configuration files and environment variables, like
OmegaConf __, dynaconf
__, confuse
__ and configargparse
__.
- Dataclasses support, like
SimpleParsing __ and 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 __), and backports (PEP 604
__).
- 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 __, yaml __, toml __, jsonnet
__ 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 __.
- Tab completion: powered by
shtab __ or argcomplete
__.
Design principles
-----------------
- Non-intrusive/decoupled:
There is no requirement for unrelated modifications throughout a codebase,
maintaining the separation of concerns principle
__. 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
__. 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
__, 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 __ as:
.. code-block:: bash
pip install jsonargparse
jsonargparse has no required dependencies. Optional features are enabled by
specifying one or more of the following extras (optional dependencies):
signatures, docstrings, typeshed, yaml, jsonschema,
jsonnet, urls, fsspec, toml, ruamel, omegaconf,
shtab, and argcomplete. The yaml extra installs PyYAML
__, without which config files are parsed
only as JSON. The signatures extra includes docstrings and
typeshed, which can also be installed individually. 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] @ https://github.com/mauvilsa/jsonargparse/zipball/main"