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

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for mauvilsa from gravatar.com mauvilsa

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (The MIT License (MIT))
  • Author: Mauricio Villegas
  • Requires: Python >=3.8
  • Provides-Extra: all, signatures, jsonschema, jsonnet, toml, urls, fsspec, shtab, argcomplete, ruyaml, omegaconf, typing-extensions, reconplogger, test, test-no-urls, coverage, dev, doc, maintainer
Classifiers
Report project as malware

Project description

https://readthedocs.org/projects/jsonargparse/badge/?version=stable https://github.com/omni-us/jsonargparse/actions/workflows/tests.yaml/badge.svg https://codecov.io/gh/omni-us/jsonargparse/branch/main/graph/badge.svg https://sonarcloud.io/api/project_badges/measure?project=omni-us_jsonargparse&metric=alert_status https://badge.fury.io/py/jsonargparse.svg

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:

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

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for mauvilsa from gravatar.com mauvilsa

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (The MIT License (MIT))
  • Author: Mauricio Villegas
  • Requires: Python >=3.8
  • Provides-Extra: all, signatures, jsonschema, jsonnet, toml, urls, fsspec, shtab, argcomplete, ruyaml, omegaconf, typing-extensions, reconplogger, test, test-no-urls, coverage, dev, doc, maintainer
Classifiers

Release history Release notifications | RSS feed

This version

4.40.0

4.39.0

4.38.0

4.37.0

4.36.0

4.35.0

4.34.1

4.34.0

4.33.2

4.33.1

4.32.1

4.32.0

4.31.0

4.30.0

4.29.0

4.28.0

4.27.7

4.27.6

4.27.5

4.27.4

4.27.3

4.27.2

4.27.1

4.27.0

4.26.2

4.26.1

4.26.0

4.25.0

4.24.1

4.24.0

4.23.1

4.23.0

4.22.1

4.22.0

4.21.2

4.21.1

4.21.0

4.20.1

4.20.0

4.19.0

4.18.0

4.17.0

4.16.0

4.15.2

4.15.1

4.15.0

4.14.1

4.14.0

4.13.3

4.13.2

4.13.1

4.13.0

4.12.0

4.11.0

4.10.2

4.10.1

4.10.0

4.10.0.dev2 pre-release

4.10.0.dev1 pre-release

4.9.0

4.8.0

4.8.0.dev2 pre-release

4.8.0.dev1 pre-release

4.7.3

4.7.2

4.7.1

4.7.0

4.6.0

4.6.0.dev3 pre-release

4.6.0.dev1 pre-release

4.5.0

4.4.0

4.3.1

4.3.0

4.2.0

4.1.4

4.1.3

4.1.2

4.1.1

4.1.0

4.0.4

4.0.3

4.0.2

4.0.1 yanked

Reason this release was yanked:

automatic push failed and there was a mistake in the manual push

4.0.0

4.0.0rc1 pre-release

4.0.0.dev1 pre-release

3.19.4

3.19.3

3.19.2

3.19.1

3.19.0

3.18.0

3.17.0

3.16.1

3.16.0

3.15.0

3.14.0

3.13.1

3.13.0

3.12.1

3.12.0

3.11.2

3.11.1

3.11.0

3.10.1

3.10.0

3.9.0

3.8.1

3.8.0

3.7.0

3.6.0

3.5.1

3.5.0

3.4.1

3.4.0

3.3.2

3.3.1

3.3.0

3.2.1

3.1.0

3.0.1

3.0.0

3.0.0rc4 pre-release

3.0.0rc3 pre-release

3.0.0rc2 pre-release

3.0.0rc1 pre-release

3.0.0.dev5 pre-release

3.0.0.dev4 pre-release

3.0.0.dev3 pre-release

3.0.0.dev2 pre-release

3.0.0.dev1 pre-release

2.32.2

2.32.1

2.32.0

2.31.2

2.31.1

2.31.0

2.30.2

2.30.0

2.29.0

2.28.0

2.27.0

2.26.1

2.26.0

2.25.4

2.25.3

2.25.2

2.25.1

2.25.0

2.24.1

2.24.0

2.23.5

2.23.4

2.23.3

2.23.2

2.23.1

2.23.0

2.22.2

2.22.1

2.22.0

2.21.0

2.20.0

2.19.0

2.18.0

2.17.0

2.16.0

2.15.0

2.14.3

2.14.2

2.14.1

2.14.0

2.13.1

2.13.0

2.12.0

2.11.0

2.10.1

2.9.0

2.8.0

2.7.0

2.6.1

2.6.0

2.5.0

2.4.1

2.4.0

2.3.0

2.2.1

2.1.1

2.1.0

2.0.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jsonargparse-4.40.0.tar.gz (203.1 kB view details)

Uploaded Source

Built Distribution

jsonargparse-4.40.0-py3-none-any.whl (224.3 kB view details)

Uploaded Python 3

File details

Details for the file jsonargparse-4.40.0.tar.gz.

File metadata

  • Download URL: jsonargparse-4.40.0.tar.gz
  • Upload date:
  • Size: 203.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for jsonargparse-4.40.0.tar.gz
Algorithm Hash digest
SHA256 fa6d748b48e36c0dadadc744c9d7bab3812785e7f4cee27fb0239b8301c808a1
MD5 00752e4f5f6ca8558dc76fc9744ddfe6
BLAKE2b-256 ece66a296858db86228a7484753fb7d79d92ba29820acfc7d8bff05ab13e8f1b

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonargparse-4.40.0.tar.gz:

Publisher: tests.yaml on omni-us/jsonargparse

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file jsonargparse-4.40.0-py3-none-any.whl.

File metadata

File hashes

Hashes for jsonargparse-4.40.0-py3-none-any.whl
Algorithm Hash digest
SHA256 5822a84efa7d10d2a5aacc3fc6c6414ea2919419a398c06d9e8ac79a420365af
MD5 6ee26be34b4101db72edfb73d3607fcf
BLAKE2b-256 ccb71cd333988594bf4b2cf6aa92073ebb57e7db15bcd6ef8ef45b6e68caeb9c

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonargparse-4.40.0-py3-none-any.whl:

Publisher: tests.yaml on omni-us/jsonargparse

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page