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.
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.
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.
You can install using pip as:
pip install jsonargparseBy 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