Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/omni-us/jsonargparse

Implement minimal boilerplate CLIs derived from type hints and parse from command line, config files and environment variables
https://github.com/omni-us/jsonargparse

argparse argparse-alternative argument-parser cli configuration-files dataclasses environment-variables json jsonnet python python3 type-hints yaml

Last synced: 5 days ago
JSON representation

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

Awesome Lists containing this project

README 

        
.. image:: https://readthedocs.org/projects/jsonargparse/badge/?version=stable

    :target: https://readthedocs.org/projects/jsonargparse/

.. image:: https://github.com/omni-us/jsonargparse/actions/workflows/tests.yaml/badge.svg

    :target: https://github.com/omni-us/jsonargparse/actions/workflows/tests.yaml

.. image:: https://codecov.io/gh/omni-us/jsonargparse/branch/main/graph/badge.svg

    :target: https://codecov.io/gh/omni-us/jsonargparse

.. image:: https://sonarcloud.io/api/project_badges/measure?project=omni-us_jsonargparse&metric=alert_status

    :target: https://sonarcloud.io/dashboard?id=omni-us_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/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

  `__, `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:



Installation

============



You can install using `pip `__ as:



.. code-block:: bash



    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:



.. code-block:: bash



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

    pip install "jsonargparse[all]"              # Enable all optional features