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. Most notably, it serves as the framework behind pytorch-lightning's LightningCLI.

Teaser examples

CLI with minimal boilerplate:

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:

from jsonargparse import auto_parser

parser = auto_parser(main_function)
cfg = parser.parse_args()
...

Powerful argparse-like low level parsers:

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, 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.), user-defined generics, restricted types (regex, numbers), paths, URLs, types from stubs (*.pyi), future annotations (PEP 563), and backports (PEPs 604/585).
• 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 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. 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

You can install using pip as:

pip install jsonargparse

By default the only dependency that jsonargparse installs is 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:

pip install "jsonargparse[signatures,urls]"  # Enable signatures and URLs features
pip install "jsonargparse[all]"              # Enable all optional features