jsonargparse 4.34.0

Implement minimal boilerplate CLIs derived from type hints and parse from command line, config files and environment variables.

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.

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, jsonnet 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. 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, 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