Teaser examples

CLI with minimal boilerplate:

from jsonargparse import auto_cli

def main_function(...):  # your main parameters with type hints here
    ...  # your main code 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.), protocols, user-defined generics, restricted types (regex, numbers), paths, URLs, types from stubs (*.pyi), future annotations (PEP 563), and backports (PEP 604).

• 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 extensible 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.

• Variable interpolation: powered by OmegaConf.

• Tab completion: powered by shtab or argcomplete.

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.

Writing configuration files

All tools implemented with the auto_cli() function have the --config option to provide settings in a config file (more details in Configuration files). This is particularly useful when there are many configurable parameters. To ease the writing of config files, there is also the option --print_config which prints to standard output all settings that the tool supports with their default values. Users can follow these steps:

# Dump default config to have as reference
python example.py --print_config > config.yaml
# Modify the config as needed (all default settings can be removed)
nano config.yaml
# Run the tool using the adapted config
python example.py --config config.yaml

Comparison to Fire

The auto_cli() feature is similar to and inspired by Fire. However, there are fundamental differences. First, the purpose is not to allow calling any Python object from the command line. It is only intended for running functions and classes specifically written for this purpose. Second, the arguments are expected to have type hints, and the given values will be validated according to these. Third, the return values of the functions are not automatically printed. auto_cli() returns the value and it is up to the developer to decide what to do with it.

Override order

Final parsed values depend on different sources, namely: source code, command line arguments, Configuration files and Environment variables. Values are overridden based on the following precedence:

1. Defaults defined in the source code.

2. Existing default config files in the order defined in default_config_files, e.g. ~/.config/myapp.yaml.

3. Full config environment variable, e.g. APP_CONFIG.

4. Individual key environment variables, e.g. APP_OPT1.

5. Command line arguments in order left to right (might include config files).

Depending on the parse method used (see ArgumentParser) and how the parser was built, some of the options above might not apply. Parsing of environment variables must be explicitly enabled, except if using ArgumentParser.parse_env(). If the parser does not have an action="config" argument, then there is no parsing of a full config environment variable or a way to provide a config file from command line.

Capturing parsers

It can be common practice to have a function that implements an entire CLI or a function that constructs a parser conditionally based on some parameters and then parses. For example, one might have:

from jsonargparse import ArgumentParser


def main_cli():
    parser = ArgumentParser()
    ...
    cfg = parser.parse_args()
    ...


if __name__ == "__main__":
    main_cli()

For some use cases it is necessary to get an instance of the parser object, without doing any parsing. For instance sphinx-argparse can be used to include the help of CLIs in automatically generated documentation of a package. To use sphinx-argparse it is necessary to have a function that returns the parser. This can be easily implemented with capture_parser() as follows:

from jsonargparse import capture_parser


def get_parser():
    return capture_parser(main_cli)

Optionals as positionals

It can sometimes be useful to allow optional arguments to be passed both by name, such as --key=val, and as positional arguments, such as val. This behavior can be enabled by using set_parsing_settings(parse_optionals_as_positionals=True). Key points to note about this feature are:

• Only optional arguments that accept exactly one value can be passed as positional, i.e., when nargs is not specified or is set to nargs=1.

• Optional arguments with subclass types cannot be passed as positional arguments.

• Optionals are treated as positionals only after the standard positionals and in the order they were added to the parser. The usage section in the help displays the optionals that can be passed as positionals and their order.

• Optional arguments in parsers with subcommands cannot be passed as positionals. Only the child subparsers, after specifying the subcommand name(s), support this feature.

For instance, consider a parser defined as follows:

from jsonargparse import set_parsing_settings


set_parsing_settings(parse_optionals_as_positionals=True)

parser.add_argument("p1")
parser.add_argument("--o2")
parser.add_argument("--o3")

The help will display p1 [o2 [o3]] along with a note indicating that this feature is enabled. Name-based parsing, such as --o2=val2 --o3=val3 val1, will work as expected. Additionally, the following cases are also valid: --o3=val3 val1 val2 or val1 val2 val3.

Functions as type

Using a function as a type, like int_or_off below, is supported though discouraged. A basic requirement is that the function be idempotent, i.e., applying the function two or more times should not modify the value. Instead of a function, it is recommended to implement a type, see Creating custom types.

# either int larger than zero or 'off' string
def int_or_off(x):
    return x if x == "off" else int(x)


parser.add_argument("--int_or_off", type=int_or_off)

Always fail arguments

In scenarios where an argument should be included in the parser but should always fail parsing, there is the ActionFail action. For example a use case can be an optional feature that is only accessible if a specific package is installed:

from jsonargparse import ActionFail

if some_package_installed:
    parser.add_argument("--module", type=SomeClass)
else:
    parser.add_argument(
        "--module",
        action=ActionFail(message="install 'package' to enable %(option)s"),
        help="Option unavailable due to missing 'package'",
    )

With this setup, if an argument is provided as --module=... or in a nested form like --module.child=..., the parsing will fail and display the configured error message.

Restricted numbers

It is quite common that when parsing a number, its range should be limited. To ease these cases the module jsonargparse.typing includes some predefined types and a function restricted_number_type() to define new types. The predefined types are: PositiveInt, NonNegativeInt, PositiveFloat, NonNegativeFloat, ClosedUnitInterval and OpenUnitInterval. Examples of usage are:

from jsonargparse.typing import PositiveInt, PositiveFloat, restricted_number_type

# float larger than zero
parser.add_argument("--op1", type=PositiveFloat)
# between 0 and 10
from_0_to_10 = restricted_number_type("from_0_to_10", int, [(">=", 0), ("<=", 10)])
parser.add_argument("--op2", type=from_0_to_10)

Restricted strings

Similar to the restricted numbers, there is a function to create string types that are restricted to match a given regular expression: restricted_string_type(). A predefined type is Email which is restricted so that it follows the normal email pattern. For example to add an argument required to be exactly four uppercase letters:

from jsonargparse.typing import Email, restricted_string_type

CodeType = restricted_string_type("CodeType", "^[A-Z]{4}$")
parser.add_argument("--code", type=CodeType)
parser.add_argument("--email", type=Email)

Parsing paths

For some use cases it is necessary to parse file paths, checking its existence and access permissions, but not necessarily opening the file. Moreover, a file path could be included in a config file as relative with respect to the config file’s location. After parsing it should be easy to access the parsed file path without having to consider the location of the config file. To help in these situations jsonargparse includes a type generator path_type(), some predefined types (e.g. Path_fr).

For example suppose you have a directory with a config file app/config.yaml and some data app/data/info.db. The contents of the YAML file is the following:

# File: config.yaml
databases:
  info: data/info.db

To create a parser that checks that the value of databases.info is a file that exists and is readable, the following could be done:

from jsonargparse import ArgumentParser
from jsonargparse.typing import Path_fr

parser = ArgumentParser()
parser.add_argument("--databases.info", type=Path_fr)
cfg = parser.parse_path("app/config.yaml")

The fr in the type are flags that stand for file and readable. After parsing, the value of databases.info will be an instance of the Path_fr class that allows to get both the original relative path as included in the YAML file, or the corresponding absolute path:

>>> cfg.databases.info.relative
'data/info.db'
>>> cfg.databases.info.absolute
'/.../app/data/info.db'

Likewise directories can be parsed using the Path_dw type, which would require a directory to exist and be writeable. New path types can be created using the path_type() function. For example to create a type for files that must exist and be both readable and writeable, the command would be Path_frw = path_type('frw'). If the file app/config.yaml is not writeable, then using the type to cast Path_frw('app/config.yaml') would raise a TypeError: File is not writeable exception. For more information of all the mode flags supported, refer to the documentation of the Path class.

Types created with path_type() have as base class Path. This class implements the os.PathLike protocol, using the absolute version as the actual path, thus for the previous example:

>>> os.fspath(cfg.databases.info)
'/.../app/data/info.db'

The content of a file referenced by a Path instance can be read using the Path.get_content() method. For the previous example, this would be info_db = cfg.databases.info.get_content().

An argument with a path type can be given nargs='+' to parse multiple paths. Thus, from command line you could do --files file1 file2, separated by space. It might also be desired to parse a list of paths found in a plain text file or from stdin. For this add the argument with type list[<path_type>] and enable_path=True. To read from stdin give the special string '-'. Example:

from jsonargparse.typing import Path_fr

parser.add_argument("--list", type=list[Path_fr], enable_path=True)
cfg = parser.parse_args(["--list", "paths.lst"])  # File with list of paths
cfg = parser.parse_args(["--list", "-"])  # List of paths from stdin

In this case since there is no nargs, the argument expects a single value. That is why to provide multiple paths directly from command line, a more cumbersome YAML/JSON array syntax is required, i.e. --list "[file1,file2]". However, the simpler syntax described in :ref:`list-append` can also be used, which would be like ``--list+ file1 --list+ file2. Not as simple as with nargs='+' but with tab completion enabled the effort is minimal.

The same list[<path_type>] behavior described here will work for arguments automatically created from type hints in signatures, that is with auto_cli(), ArgumentParser.add_function_arguments(), ArgumentParser.add_class_arguments(), ArgumentParser.add_method_arguments() and ArgumentParser.add_subclass_arguments().

Parsing URLs

The path_type() function also supports URLs which after parsing, the Path.get_content() method can be used to perform a GET request to the corresponding URL and retrieve its content. For this to work the requests Python package is required. Alternatively, path_type() can also be used for fsspec supported file systems. The respective optional package(s) will be installed along with jsonargparse if installed with the urls or fsspec extras as explained in section Installation.

The 'u' flag is used to parse URLs using requests and the flag 's' to parse fsspec file systems. For example if it is desired that an argument can be either a readable file or URL, the type would be created as Path_fur = path_type('fur'). If the value appears to be a URL, a HEAD request would be triggered to check if it is accessible. To get the content of the parsed path, without needing to care if it is a local file or a URL, the Path.get_content() method can be used.

If you import from jsonargparse import set_parsing_settings and then run set_parsing_settings(config_read_mode_urls_enabled=True) or set_parsing_settings(config_read_mode_fsspec_enabled=True), the following functions and classes will also support loading from URLs: ArgumentParser.parse_path(), ArgumentParser.get_defaults() (default_config_files argument), action="config", ActionJsonSchema, ActionJsonnet and ActionParser. This means that a tool that can receive a config file via action="config" is able to get the content from a URL, thus something like the following would work:

my_tool.py --config http://example.com/config.yaml

Booleans

Parsing boolean arguments is very common, however, the original argparse only has a limited support for them, via store_true and store_false. Furthermore unexperienced users might mistakenly use type=bool which would not provide the intended behavior.

With jsonargparse adding an argument with type=bool the intended action is implemented. If given as values {'yes', 'true'} or {'no', 'false'} the corresponding parsed values would be True or False. For example:

>>> parser.add_argument("--op1", type=bool, default=False)
>>> parser.add_argument("--op2", type=bool, default=True)
>>> parser.parse_args(["--op1", "yes", "--op2", "false"])
Namespace(op1=True, op2=False)

Sometimes it is also useful to define two paired options, one to set True and the other to set False. The ActionYesNo class makes this straightforward. A couple of examples would be:

from jsonargparse import ActionYesNo

# --opt1 for true and --no_opt1 for false.
parser.add_argument("--op1", action=ActionYesNo)
# --with-opt2 for true and --without-opt2 for false.
parser.add_argument("--with-op2", action=ActionYesNo(yes_prefix="with-", no_prefix="without-"))

If the ActionYesNo class is used in conjunction with nargs='?' the options can also be set by giving as value any of {'true', 'yes', 'false', 'no'}.

Enum arguments

Another case of restricted values is string choices. In addition to the common choices given as a list of strings, it is also possible to provide as type an Enum class. This has the added benefit that strings are mapped to some desired values. For example:

>>> import enum
>>> class MyEnum(enum.Enum):
...     choice1 = -1
...     choice2 = 0
...     choice3 = 1
...
>>> parser.add_argument("--op", type=MyEnum)
>>> parser.parse_args(["--op=choice1"])
Namespace(op=<MyEnum.choice1: -1>)

List append

As detailed before, arguments with list type are supported. By default when specifying an argument value, the previous value is replaced, and this also holds for lists. Thus, a parse such as parser.parse_args(['--list=[1]', '--list=[2, 3]']) would result in a final value of [2, 3]. However, in some cases it might be decided to append to the list instead of replacing. This can be achieved by adding + as suffix to the argument key, for example:

>>> parser.add_argument("--list", type=list[int])
>>> parser.parse_args(["--list=[1]", "--list+=[2, 3]"])
Namespace(list=[1, 2, 3])
>>> parser.parse_args(["--list=[4]", "--list+=5"])
Namespace(list=[4, 5])

Append is also supported in config files. For instance the following two config files would first assign a list and then append to this list:

# config1.yaml
list:
- 1

# config2.yaml
list+:
- 2
- 3

Appending works for any type for the list elements. Lists with class type elements (see Class type and sub-classes) are also supported. To append to the list, first append a new class by using the + suffix. Then init_args for this class are specified like if the type wasn’t a list, since the arguments are applied to the last class in the list. Take for example that an argument is added to a parser as:

parser.add_argument("--list_of_instances", type=list[MyBaseClass])

Thanks to the short notation, command line arguments don’t require to specify class_path and init_args. Thus, multiple classes can be appended and its arguments set as follows:

python tool.py \
  --list_of_instances+={CLASS_1_PATH} \
  --list_of_instances.{CLASS_1_ARG_1}=... \
  --list_of_instances.{CLASS_1_ARG_2}=... \
  --list_of_instances+={CLASS_2_PATH} \
  --list_of_instances.{CLASS_2_ARG_1}=... \
  ...
  --list_of_instances+={CLASS_N_PATH} \
  --list_of_instances.{CLASS_N_ARG_1}=... \
  ...

Once a new class has been appended to the list, it is not possible to modify the arguments of a previous class. This limitation is intentional since it forces classes and its arguments to be defined in order, making the command line call intuitive to write and understand.

Dict items

When an argument has dict as type, the value can be set using JSON format, e.g.:

>>> parser.add_argument("--dict", type=dict)
>>> parser.parse_args(['--dict={"key1": "val1", "key2": "val2"}'])
Namespace(dict={'key1': 'val1', 'key2': 'val2'})

Similar to lists, providing a second argument with value a JSON dict completely replaces the previous value. Setting individual dict items without replacing can be achieved as follows:

>>> parser.parse_args(["--dict.key1=val1", "--dict.key2=val2"])
Namespace(dict={'key1': 'val1', 'key2': 'val2'})

Dataclass-like classes

In contrast to subclasses, which requires the user to provide a class_path, in some cases it is not expected to have subclasses. In this case the init args are given directly in a dictionary without specifying a class_path. This is the behavior for standard dataclasses, final classes, attrs’ define decorator, and pydantic’s dataclass decorator and BaseModel classes.

As an example, take a class that is decorated with final(), meaning that it shouldn’t be subclassed. The code below would accept the corresponding YAML structure.

from jsonargparse.typing import final


@final
class FinalClass:
    def __init__(self, number: int = 0, accepted: bool = False):
        ...


parser = ArgumentParser()
parser.add_argument("--data", type=FinalClass)
cfg = parser.parse_path("config.yaml")

data:
  number: 8
  accepted: true

Generic types

Classes that inherit from typing.Generic, also known as user-defined generic types, are supported. Take for example a point in 2D:

from typing import Generic, TypeVar

Number = TypeVar("Number", float, complex)

@dataclass
class Point2d(Generic[Number]):
    x: Number = 0.0
    y: Number = 0.0

Parsing complex-valued points would be:

>>> parser.add_argument("--point", type=Point2d[complex])
>>> parser.parse_args(["--point.x=(1+2j)"]).point
Namespace(x=(1+2j), y=0.0)

Callable type

When using Callable as type, the parser accepts several options. The first option is the import path of a callable object, for example:

parser.add_argument("--callable", type=Callable)
parser.parse_args(["--callable=time.sleep"])

A second option is a class that once instantiated becomes callable:

class OffsetSum:
    def __init__(self, offset: int):
        self.offset = offset

    def __call__(self, value: int):
        return self.offset + value

>>> value = {
...     "class_path": "__main__.OffsetSum",
...     "init_args": {
...         "offset": 3,
...     },
... }

>>> cfg = parser.parse_args(["--callable", str(value)])
>>> cfg.callable
Namespace(class_path='__main__.OffsetSum', init_args=Namespace(offset=3))
>>> init = parser.instantiate_classes(cfg)
>>> init.callable(5)
8

The third option is only applicable when the type is a callable that returns class instances. This is a form of Dependency injection, so this third case is explained in section Instance factories.

Registering types

With the register_type() function it is possible to register additional types for use in jsonargparse parsers. If the type class can be instantiated with a string representation and casting the instance to str gives back the string representation, then only the type class is given to register_type(). For example in the jsonargparse.typing package this is how complex numbers are registered: register_type(complex). For other type classes that don’t have these properties, to register it might be necessary to provide a serializer and/or deserializer function. Including the serializer and deserializer functions, the registration of the complex numbers example is equivalent to register_type(complex, serializer=str, deserializer=complex).

A more useful example could be registering the datetime class. This case requires to give both a serializer and a deserializer as seen below.

from datetime import datetime
from jsonargparse import ArgumentParser
from jsonargparse.typing import register_type


def serializer(v):
    return v.isoformat()


def deserializer(v):
    return datetime.strptime(v, "%Y-%m-%dT%H:%M:%S")


register_type(datetime, serializer, deserializer)

parser = ArgumentParser()
parser.add_argument("--datetime", type=datetime)
parser.parse_args(["--datetime=2008-09-03T20:56:35"])

Creating custom types

It is possible to create new types and use them for parsing. Even though types can be created for specific CLI behaviors, it is recommended to create them such that they make sense independent of parsing. This is so that they can be used as type hints in functions and classes in order to improve the code in a more general sense. An alternative to creating types, can be to use pydantic types.

There are a few ways for creating types, the most simple being to implement a class. When creating a type, take as reference how basic types work, e.g. int. Properties of basic types are:

• Casting a string creates an instance of the type, if the value is valid, e.g. int("1").

• Casting a string raises a ValueError, if the value is not valid, e.g. int("a").

• Casting an instance of the type to string gives back the string representation of the value, e.g. str(1) == "1".

• Types are idempotent, i.e. casting an instance of the type to the type gives back the same value, e.g. int(1) == int(int(1)).

Once a type is created, it can be registered with register_type(). If the type follows the properties above, then there is no need to provide more parameters, just do register_type(MyType).

The extend_base_type() function can be useful for creating and registering new types in a single call. For example, creating a type for even integers could be done as:

from jsonargparse.typing import extend_base_type

def is_even(type_class, value):
    if int(value) % 2 != 0:
        raise ValueError(f"{value} is not even")

EvenInt = extend_base_type("EvenInt", int, is_even)

Then this type can be used in a parser as:

>>> parser = ArgumentParser()
>>> parser.add_argument("--even_int", type=EvenInt)
>>> parser.parse_args(["--even_int=2"])
Namespace(even_int=2)

When using custom types as a type hint, defaults must be casted so that static type checkers don’t complain. For example:

def fn(value: EvenInt = EvenInt(2)):
    ...

Serialization

Parsers that have an action="config" argument also include a --print_config option. This is useful particularly for command line tools with a large set of options to create an initial config file including all default values. If the ruamel.yaml package is installed, the config can be printed having the help descriptions content as YAML comments by using --print_config=comments. Another option is --print_config=skip_null which skips entries whose value is null.

From within Python it is also possible to serialize a config object by using either the ArgumentParser.dump() or ArgumentParser.save() methods. Several formats with a particular style are supported: yaml, toml, json_compact and json_indented. It is possible to add more dumping formats by using the set_dumper() function. For example to allow dumping using PyYAML’s default_flow_style do the following:

import yaml
from jsonargparse import set_dumper


def custom_yaml_dump(data):
    return yaml.safe_dump(data, default_flow_style=True)


set_dumper("yaml_custom", custom_yaml_dump)

Custom loaders

The yaml parser mode (see ArgumentParser.__init__()) uses for loading a subclass of yaml.SafeLoader with two modifications. First, it supports float’s scientific notation, e.g. '1e-3' => 0.001 (unlike default PyYAML which considers '1e-3' a string). Second, text within curly braces is considered a string, e.g. '{text}' (unlike default PyYAML which parses this as ``{'text': None}).

It is possible to replace the yaml loader or add a loader as a new parser mode via the set_loader() function. For example if you need a custom PyYAML loader it can be registered and used as follows:

import yaml
from jsonargparse import ArgumentParser, set_loader


class CustomLoader(yaml.SafeLoader):
    ...


def custom_yaml_load(stream):
    return yaml.load(stream, Loader=CustomLoader)


set_loader("yaml_custom", custom_yaml_load)

parser = ArgumentParser(parser_mode="yaml_custom")

When setting a loader based on a library different from PyYAML, the exceptions that it raises when there are failures should be given to set_loader().

Docstring parsing

To get parameter docstrings in the parser help, the docstring-parser package is required. This package is included when installing jsonargparse with the signatures extra as explained in section Installation.

A couple of options can be configured, both related to docstring parsing speed. By default docstrings are parsed used with docstring_parser.DocstringStyle.AUTO, which means that it is attempted to parse docstrings with all supported styles. If the relevant codebase uses a single style, this is inefficient. A single style can be configured as follows:

from docstring_parser import DocstringStyle
from jsonargparse import set_parsing_settings

set_parsing_settings(docstring_parse_style=DocstringStyle.REST)

The second option that can be configured is the support for attribute docstrings (i.e. literal strings in the line after an attribute is defined). By default this feature is disabled and enabling it makes the parsing slower even for classes that don’t have attribute docstrings. To enable, do as follows:

from dataclasses import dataclass
from jsonargparse import set_parsing_settings

set_parsing_settings(docstring_parse_attribute_docstrings=True)


@dataclass
class Options:
    """Options for a competition winner."""

    name: str
    """Name of winner."""
    prize: int = 100
    """Amount won."""

Customization of arguments

Since the arguments are added automatically based on the function signatures, the developer has limited control over their behavior. To customize some of the arguments, you can create a subclass and override the ArgumentParser.add_argument() method. For example, by default, bool arguments require a true|false value from the command line. To change this behavior and use ActionYesNo instead, through a CLI based on auto_cli(), you can:

from jsonargparse import ArgumentParser, auto_cli

class CustomArgumentParser(ArgumentParser):
    def add_argument(self, *args, **kwargs):
        if "type" in kwargs and kwargs["type"] == bool:
            kwargs.pop("type")
            kwargs["action"] = ActionYesNo
        return super().add_argument(*args, **kwargs)

def main_function(flag: bool = False):
    ...

if __name__ == "__main__":
    auto_cli(main_function, parser_class=CustomArgumentParser)

Classes from functions

In some cases there are functions which return an instance of a class. To add this to a parser such that ArgumentParser.instantiate_classes() calls this function, the example above would change to:

from jsonargparse import ArgumentParser, class_from_function

parser = ArgumentParser()
dynamic_class = class_from_function(instantiate_myclass)
parser.add_class_arguments(dynamic_class, "myclass.init")

Classes created with class_from_function() can be selected using class_path for Class type and sub-classes. For example, if class_from_function() is run in a module my_module as:

class_from_function(instantiate_myclass, name="MyClass")

Then the class_path for the created class would be my_module.MyClass.

Parameter resolvers

Three techniques are implemented for resolving signature parameters. One makes use of Python’s Abstract Syntax Trees (AST) library and the second is based on assumptions of class inheritance. The AST resolver is used first and only when AST fails, the assumptions resolver is run as fallback. The third resolver uses stub files *.pyi and is applied on top of both the AST and assumptions resolvers.

from jsonargparse import ArgumentParser

parser = ArgumentParser()
parser.add_argument("--myclass", type=MyClass)
cfg = parser.parse_args()
cfg_init = parser.instantiate_classes(cfg)

class_path: MyClass
init_args:
  foo: 1
dict_kwargs:
  bar: 2

def calls_a_function(*args, **kwargs):
    a_function(*args, **kwargs)


def calls_a_method(*args, **kwargs):
    an_instance = SomeClass()
    an_instance.a_method(*args, **kwargs)


def calls_a_static_method(*args, **kwargs):
    an_instance = SomeClass()
    an_instance.a_static_method(*args, **kwargs)


def calls_a_class_method(*args, **kwargs):
    SomeClass.a_class_method(*args, **kwargs)


def calls_local_import(**kwargs):
    import some_module
    some_module.a_callable(**kwargs)


def pops_from_kwargs(**kwargs):
    val = kwargs.pop("name", "default")


def gets_from_kwargs(**kwargs):
    val = kwargs.get("name", "default")


def constant_conditional(**kwargs):
    if global_boolean_1:
        first_function(**kwargs)
    elif not global_boolean_2:
        second_function(**kwargs)
    else:
        third_function(**kwargs)

class PassThrough(BaseClass):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)


class CallMethod:
    def __init__(self, *args, **kwargs):
        self.a_method(*args, **kwargs)


class AttributeUseInMethod:
    def __init__(self, **kwargs):
        self._kwargs = kwargs

    def a_method(self):
        a_callable(**self._kwargs)


class AttributeUseInProperty:
    def __init__(self, **kwargs):
        self._kwargs = kwargs

    @property
    def a_property(self):
        return a_callable(**self._kwargs)


class DictUpdateUseInMethod:
    def __init__(self, **kwargs):
        self._kwargs = dict(p1=1)  # Can also be: self._kwargs = {'p1': 1}
        self._kwargs.update(**kwargs)  # Can also be: self._kwargs = dict(p1=1, **kwargs)

    def a_method(self):
        a_callable(**self._kwargs)


class InstanceInClassmethod:
    @classmethod
    def get_instance(cls, **kwargs):
        return cls(**kwargs)


class NonImmediateSuper(BaseClass):
    def __init__(self, *args, **kwargs):
        super(BaseClass, self).__init__(*args, **kwargs)

# Class instance: only keyword arguments with ``ast.Constant`` value
class_instance: SomeClass = SomeClass(param=1)

# Lambda returning class instance: only keyword arguments with ``ast.Constant`` value
class_instance: Callable[[type], BaseClass] = lambda a: ChildClass(a, param=2.3)

def calls_a_function(*args, **kwargs):
    a_function(*args, param=1, **kwargs)

def conditional_calls(**kwargs):
    if condition_1:
        first_function(**kwargs)
    elif condition_2:
        second_function(**kwargs)
    else:
        third_function(**kwargs)

>>> from random import uniform

>>> parser = ArgumentParser()
>>> parser.add_function_arguments(uniform, "uniform")
>>> parser.parse_args(["--uniform.a=0.7", "--uniform.b=3.4"])
Namespace(uniform=Namespace(a=0.7, b=3.4))

Class type and sub-classes

When a class is used as a type hint, jsonargparse expects in config files a dictionary with a class_path entry indicating the dot notation expression to import the class, and optionally some init_args that would be used to instantiate it. When parsing, it will be checked that the class can be imported, that it is a subclass of the given type and that init_args values correspond to valid arguments to instantiate it. After parsing, the config object will include the class_path and init_args entries. To get a config object with all nested sub-classes instantiated, the ArgumentParser.instantiate_classes() method is used.

Additional to using a class as type hint in signatures, for low level construction of parsers, there are also the methods SignatureArguments.add_class_arguments() and SignatureArguments.add_subclass_arguments(). These methods accept a skip argument that can be used to exclude parameters within subclasses. This is done by giving its relative destination key, i.e. as param.init_args.subparam. An individual argument can also be added having as type a class, i.e. parser.add_argument("--module", type=ModuleBase).

A simple example with a top-level class to instantiate, with a parameter that expects an injected class instance, would be having some config file config.yaml as:

myclass:
  calendar:
    class_path: calendar.Calendar
    init_args:
      firstweekday: 1

Then in Python:

>>> from calendar import Calendar

>>> class MyClass:
...     def __init__(self, calendar: Calendar):
...         self.calendar = calendar
...

>>> parser = ArgumentParser()
>>> parser.add_class_arguments(MyClass, "myclass")

>>> cfg = parser.parse_path("config.yaml")
>>> cfg.myclass.calendar.as_dict()
{'class_path': 'calendar.Calendar', 'init_args': {'firstweekday': 1}}

>>> cfg = parser.instantiate_classes(cfg)
>>> isinstance(cfg.myclass, MyClass)
True
>>> isinstance(cfg.myclass.calendar, Calendar)
True
>>> cfg.myclass.calendar.getfirstweekday()
1

In this example the class_path points to the same class used for the type. But a subclass of Calendar with an extended set of init parameters would also work.

If the previous example were changed to use SignatureArguments.add_subclass_arguments() instead of SignatureArguments.add_class_arguments(), then subclasses MyClass would also be accepted. In this case the config would be like:

myclass:
  class_path: my_module.MyClass
  init_args:
    calendar:
      class_path: calendar.TextCalendar
      init_args:
        firstweekday: 1

Instance factories

As explained at the beginning of section Dependency injection, callables that return instances of classes, referred to as instance factories, represent an alternative approach to dependency injection. This is useful to support dependency injection of classes that require parameters that are only available after injection. For this case, when ArgumentParser.instantiate_classes() is run, a partial function is provided, which might accept parameters and returns the instance of the class. Two options are possible, either using Callable or Protocol. First to illustrate the Callable option, take for example the classes:

class Optimizer:
    def __init__(self, params: Iterable):
        self.params = params


class SGD(Optimizer):
    def __init__(self, params: Iterable, lr: float):
        super().__init__(params)
        self.lr = lr

A possible parser and callable behavior would be:

>>> value = {
...     "class_path": "SGD",
...     "init_args": {
...         "lr": 0.01,
...     },
... }

>>> parser.add_argument("--optimizer", type=Callable[[Iterable], Optimizer])
>>> cfg = parser.parse_args(["--optimizer", str(value)])
>>> cfg.optimizer
Namespace(class_path='__main__.SGD', init_args=Namespace(lr=0.01))
>>> init = parser.instantiate_classes(cfg)
>>> optimizer = init.optimizer([1, 2, 3])
>>> isinstance(optimizer, SGD)
True
>>> optimizer.params, optimizer.lr
([1, 2, 3], 0.01)

If the same type above is used as type hint of a parameter of another class, a default can be set using a lambda, for example:

class Model:
    def __init__(
        self,
        optimizer: Callable[[Iterable], Optimizer] = lambda p: SGD(p, lr=0.05),
    ):
        self.optimizer = optimizer

Then a parser and behavior could be:

>>> parser.add_class_arguments(Model, 'model')
>>> cfg = parser.get_defaults()
>>> cfg.model.optimizer
Namespace(class_path='__main__.SGD', init_args=Namespace(lr=0.05))
>>> init = parser.instantiate_classes(cfg)
>>> optimizer = init.model.optimizer([1, 2, 3])
>>> optimizer.params, optimizer.lr
([1, 2, 3], 0.05)

See AST resolver for limitations of lambda defaults in signatures. Providing a lambda default to ActionsContainer.add_argument() does not work since there is no AST resolving. In this case, a dict with class_path and init_args can be used as default.

Multiple arguments required after injection is also supported and can be specified the same way with a Callable. For example, for two Iterable arguments, you can use the syntax: Callable[[Iterable, Iterable], Type]. Similarly, for a callable that accepts zero arguments, the syntax would be Callable[[], Type].

Note the big limitation that Callable has. It is only possible to specify positional and unnamed parameters. To overcome this limitation, the second option, a callable Protocol can be used instead. Building up from the same example, an OptimizerFactory protocol can be defined as:

class OptimizerFactory(Protocol):
    def __call__(self, params: Iterable) -> Optimizer: ...

Then a parser and protocol behavior would be:

>>> value = {
...     "class_path": "SGD",
...     "init_args": {
...         "lr": 0.02,
...     },
... }

>>> parser.add_argument("--optimizer", type=OptimizerFactory)
>>> cfg = parser.parse_args(["--optimizer", str(value)])
>>> cfg.optimizer
Namespace(class_path='__main__.SGD', init_args=Namespace(lr=0.02))
>>> init = parser.instantiate_classes(cfg)
>>> optimizer = init.optimizer(params=[6, 5])
>>> optimizer.params, optimizer.lr
([6, 5], 0.02)

The key difference with respect to the Callable is being able to call init.optimizer() with keyword arguments params=[6, 5].

Command line

The help of the parser does not show accepted parameters of a class since this depends on the chosen subclass. To get details for a particular subclass there is a help option that receives the import path. Take for example a parser defined as:

from calendar import Calendar
from jsonargparse import ArgumentParser

parser = ArgumentParser()
parser.add_argument("--calendar", type=Calendar)

The help for a corresponding subclass could be printed as:

python tool.py --calendar.help calendar.TextCalendar

In the command line, a subclass can be specified through multiple command line arguments:

python tool.py \
  --calendar.class_path calendar.TextCalendar \
  --calendar.init_args.firstweekday 1

For convenience, the arguments can be somewhat shorter by omitting .class_path and .init_args and only specifying the name of the subclass instead of the full import path.

python tool.py --calendar TextCalendar --calendar.firstweekday 1

Specifying the name of the subclass works for subclasses in modules that have been imported before parsing. Abstract classes and private classes (module or name starting with '_') are not considered. All the subclasses resolvable by its name can be seen in the general help python tool.py --help.

When the base class is not abstract, the class_path can be omitted, by giving directly init_args, for example:

python tool.py --calendar.firstweekday 2

would implicitly use calendar.Calendar as the class path.

Default values

For a parameter that has a class as type, it might also be wanted to set a default value for it. Special care must be taken when doing this, could be considered bad practice and be a good idea to avoid in most cases. The issue is that classes are normally mutable. Depending on how the parameter value is used, its default class instance in the signature could be changed. This goes against what a default value is expected to be and lead to bugs which are difficult to debug.

Since there are some legitimate use cases for class instances in defaults, they are supported with a particular behavior and recommendations. An example is:

class MyClass:
    def __init__(
        self,
        calendar: Calendar = Calendar(firstweekday=1),
    ):
        self.calendar = calendar

Adding this class to a parser will work without issues. The AST resolver in limited cases determines how to instantiate the original default. The parsing methods would provide a dict with class_path and init_args instead of the class instance. Furthermore, if ArgumentParser.instantiate_classes() is used, a new instance of the class is created, thereby avoiding issues related to the mutability of the default.

Since the AST resolver only supports limited cases, or when the source code is not available, a second approach is to use the special function lazy_instance() to instantiate the default. Continuing with the same example above, this would be:

from jsonargparse import lazy_instance


class MyClass:
    def __init__(
        self,
        calendar: Calendar = lazy_instance(Calendar, firstweekday=1),
    ):
        self.calendar = calendar

Like this, the parsed default will be a dict with class_path and init_args, again avoiding the risk of mutability.

The use of lazy_instance() is somewhat discouraged. A function that delays the initialization of instances, and works for all possible cases out there, is challenging. The current implementation is known to have some problems. Instead of using lazy_instance(), you could consider switching to Instance factories.

Applied on parse

For parsing links, source keys can be individual arguments or nested groups. The target key has to be a single argument. The keys can be inside init_args of a subclass. The compute function should accept as many positional arguments as there are sources and return a value of type compatible with the target. An example would be the following:

class Model:
    def __init__(self, batch_size: int):
        self.batch_size = batch_size


class Data:
    def __init__(self, batch_size: int = 5):
        self.batch_size = batch_size


parser = ArgumentParser()
parser.add_class_arguments(Model, "model")
parser.add_class_arguments(Data, "data")
parser.link_arguments("data.batch_size", "model.batch_size", apply_on="parse")

As argument and in config files only data.batch_size should be specified. Then whatever value it has will be propagated to model.batch_size.

An example of a target being in a subclass is:

class Logger:
    def __init__(self, save_dir: Optional[str] = None):
        self.save_dir = save_dir

class Trainer:
    def __init__(
        self,
        save_dir: Optional[str] = None,
        logger: Union[bool, Logger, list[Logger]] = False,
    ):
        self.logger = logger

parser = ArgumentParser()
parser.add_class_arguments(Trainer, "trainer")
parser.link_arguments("trainer.save_dir", "trainer.logger.init_args.save_dir")

The link gets applied to the logger parameter when it is a single subclass and applied to all elements of a list of subclasses. If a subclass does not define the targeted init_args parameter, the link is ignored.

Applied on instantiate

For instantiation links, sources can be class groups (added with SignatureArguments.add_class_arguments()) or subclass arguments (see Class type and sub-classes). The source key can be the entire instantiated object or an attribute of the object. The target key has to be a single argument and can be inside init_args of a subclass. The order of instantiation used by ArgumentParser.instantiate_classes() is automatically determined based on the links. The set of all instantiation links must be a directed acyclic graph. An example would be the following:

class Model:
    def __init__(self, num_classes: int):
        self.num_classes = num_classes


class Data:
    def __init__(self):
        self.num_classes = get_num_classes()


parser = ArgumentParser()
parser.add_class_arguments(Model, "model")
parser.add_class_arguments(Data, "data")
parser.link_arguments("data.num_classes", "model.num_classes", apply_on="instantiate")

This link would imply that ArgumentParser.instantiate_classes() instantiates Data first, then use the num_classes attribute to instantiate Model.

Experimental omegaconf+ mode

An experimental omegaconf+ parser mode is available, which addresses the limitations of the omegaconf mode mentioned earlier. Instead of applying OmegaConf resolvers to each YAML config individually, the resolving is performed once at the end of the parsing process. As a result, in nested sub-configs, references to nodes must be either relative or parser-level absolute to function correctly. Alternatively, you can set_parsing_settings(omegaconf_absolute_to_relative_paths=True) to enable automatic conversion of absolute paths to relative ones during parsing. Be aware that this automatic conversion does not work for every possible case.

Based on community feedback, this mode may become the default omegaconf mode in version 5.0.0. This change would introduce a breaking modification, as absolute node references would no longer work in nested sub-configs.

shtab

For shtab to work, there is no need to set complete/choices to the parser actions, and no need to call shtab.add_argument_to(). This is done automatically by ArgumentParser.parse_args(). The only requirement is to install shtab either directly or by installing jsonargparse with the shtab extra as explained in section Installation.

Once shtab is installed, parsers will automatically have the --print_shtab option that can be used to print the completion script for the supported shells. For example in linux to enable bash completions for all users, as root it would be used as:

# example.py --print_shtab=bash > /etc/bash_completion.d/example

Without installing, completion scripts can be tested by sourcing or evaluating them, for instance:

$ eval "$(example.py --print_shtab=bash)"

The scripts work both to complete when there are choices, but also gives instructions to the user for guidance. Take for example the parser:

#!/usr/bin/env python3

from typing import Optional
from jsonargparse import ArgumentParser

parser = ArgumentParser()
parser.add_argument("--bool", type=Optional[bool])

parser.parse_args()

The completions print the type of the argument, how many options are matched, and afterward the list of choices matched up to that point. If only one option matches, then the value is completed without printing guidance. For example:

$ example.py --bool <TAB><TAB>
Expected type: Optional[bool]; 3/3 matched choices
true  false  null
$ example.py --bool f<TAB>
$ example.py --bool false

For the case of subclass types, the import class paths for known subclasses are completed, both for the switch to select the class and for the corresponding --*.help switch. The init_args for known subclasses are also completed, giving as guidance which of the subclasses accepts it. An example would be:

$ example.py --cls <TAB><TAB>
Expected type: BaseClass; 3/3 matched choices
some.module.BaseClass     other.module.SubclassA
other.module.SubclassB
$ example.py --cls other.module.SubclassA --cls.<TAB><TAB>
--cls.param1    --cls.param2
$ example.py --cls other.module.SubclassA --cls.param2 <TAB><TAB>
Expected type: int; Accepted by subclasses: SubclassA

argcomplete

For argcompete to work, there is no need to implement completer functions or to call argcomplete.autocomplete() since this is done automatically by ArgumentParser.parse_args(). The only requirement to enable tab completion is to install argcomplete either directly or by installing jsonargparse with the argcomplete extra as explained in section Installation.

The tab completion can be enabled globally for all argcomplete compatible tools or for each individual tool.

Using the same bool example as shown above, activate tab completion and use it as follows:

$ eval "$(register-python-argcomplete example.py)"

$ example.py --bool <TAB><TAB>
false  null   true
$ example.py --bool f<TAB>
$ example.py --bool false

Development environment

If you intend to work with the source code, note that this project does not include any requirements.txt file. This is by intention. To make it very clear what are the requirements for different use cases, all the requirements of the project are stored in the file pyproject.toml. The basic runtime requirements are defined in dependencies. Requirements for optional features are stored in [project.optional-dependencies]. Also in the same section there are requirements for testing, development and documentation building: test, dev and doc.

The recommended way to work with the source code is the following. First clone the repository, then create a virtual environment, activate it and finally install the development requirements. More precisely the steps are:

git clone https://github.com/omni-us/jsonargparse.git
cd jsonargparse
python -m venv venv
. venv/bin/activate

The crucial step is installing the requirements which would be done by running:

pip install -e ".[dev,all]"

pre-commit

Please also install the pre-commit git hooks so that unit tests and code checks are automatically run locally. This is done as follows:

pre-commit install

The pre-push stage runs several hooks, including tests, doctests, mypy, and coverage. These hooks are designed to inform developers of issues that must be resolved before a pull request can be merged. Note that these hooks may take some time to complete. If you wish to push without running these hooks, use the command git push --no-verify.

Formatting of the code is done automatically by pre-commit. If some pre-commit hooks fail and you decide to skip them, formatting will be automatically applied by a GitHub action in pull requests.

Documentation

To build the documentation run:

sphinx-build sphinx sphinx/_build sphinx/*.rst

To view the built documentation, open the file sphinx/_build/index.html in a browser.

Tests

Running the unit tests can be done either using pytest or tox. The tests are also installed with the package and can be run in a non-development environment. Also pre-commit runs some additional tests.

tox                                      # Run tests using tox on available python versions
pytest                                   # Run tests using pytest on the python of the environment
pytest --cov                             # Run tests and generate coverage report
python -m jsonargparse_tests             # Run tests on installed package (requires pytest and pytest-subtests)
pre-commit run -a --hook-stage pre-push  # Run pre-push git hooks (tests, doctests, mypy, coverage)

Coverage

For a nice html test coverage report, run:

pytest --cov --cov-report=html

Then open the file htmlcov/index.html in a browser.

To get a full coverage report, you need to install all supported python versions, and then:

rm -fr jsonargparse_tests/.coverage jsonargparse_tests/htmlcov
tox -- --cov=../jsonargparse --cov-append
cd jsonargparse_tests
coverage html

Then open the file jsonargparse_tests/htmlcov/index.html in a browser.

Pull requests

When creating a pull request, it is recommended that you create a specific branch in your fork for the changes you want to contribute, instead of using the main branch.

The required tasks to do for a pull request, are listed in PULL_REQUEST_TEMPLATE.md.

One of the tasks is adding a changelog entry. For this, note that this project uses semantic versioning. Depending on whether the contribution is a bug fix or a new feature, the changelog entry would go in a patch or minor release. The changelog section for the next release does not have a definite date, for example:

v4.28.0 (unreleased)
--------------------

Added
^^^^^
-

If no such section exists, just add it with “(unreleased)” instead of a date. Have a look at previous releases to decide under which subsection the new entry should go. If you are unsure, ask in the pull request.

Please don’t open pull requests with breaking changes unless this has been discussed and agreed upon in an issue.

jsonargparse

Exceptions:

Functions:

Classes:

exception jsonargparse.ArgumentError(argument, message)

Bases: Exception

An error from creating or using an argument (optional or positional).

The string value of this exception is the message, augmented with information about the argument that caused it.

Methods:

__init__(argument, message)

__init__(argument, message)

jsonargparse.CLI(*args, **kwargs)

Alias of auto_cli().

jsonargparse.auto_cli(components=None, args=None, config_help='Path to a configuration file.', set_defaults=None, as_positional=True, fail_untyped=True, parser_class=<class 'jsonargparse._core.ArgumentParser'>, **kwargs)

Simple creation of command line interfaces.

Previously CLI, renamed to follow the standard of functions in lowercase.

Creates an argument parser from one or more functions/classes, parses arguments and runs one of the functions or class methods depending on what was parsed. If the ‘components’ parameter is not given, then the components will be all the locals in the context and defined in the same module as from where auto_cli is called.

Parameters:

• components (Union[Callable, type, list[Union[Callable, type]], dict[str, Union[Callable, type, dict[str, Union[Callable, type, DictComponentsType]]]], None]) – One or more functions/classes to include in the command line interface.

• args (Optional[list[str]]) – List of arguments to parse or None to use sys.argv.

• config_help (str) – Help string for config file option in help.

• set_defaults (Optional[dict[str, Any]]) – Dictionary of values to override components defaults.

• as_positional (bool) – Whether to add required parameters as positional arguments.

• fail_untyped (bool) – Whether to raise exception if a required parameter does not have a type.

• parser_class (type[ArgumentParser]) – The ArgumentParser class to use.

• **kwargs – Used to instantiate ArgumentParser.

Returns:

The value returned by the executed function or class method.

jsonargparse.auto_parser(*args, **kwargs)

Same as auto_cli, but returns the parser, so doesn’t parse arguments or run.

This is a shorthand for capture_parser(lambda: auto_cli(*args, **kwargs)).

Return type:

ArgumentParser

class jsonargparse.ActionsContainer(*args, **kwargs)

Bases: SignatureArguments, _ActionsContainer

Extension of argparse._ActionsContainer to support additional functionalities.

Methods:

__init__(*args, **kwargs)	Initializer for LoggerProperty class.
add_argument(*args[, enable_path])	Adds an argument to the parser or argument group.
add_argument_group(*args[, name])	Adds a group to the parser.
set_defaults(*args, **kwargs)	Sets default values from dictionary or keyword arguments.

__init__(*args, **kwargs)

Initializer for LoggerProperty class.

add_argument(*args, enable_path=False, **kwargs)

Adds an argument to the parser or argument group.

All the arguments from argparse.ArgumentParser.add_argument are supported. Additionally it accepts:

Parameters:

enable_path (bool) – Whether to try parsing path/subconfig when argument is a complex type.

add_argument_group(*args, name=None, **kwargs)

Adds a group to the parser.

All the arguments from argparse.ArgumentParser.add_argument_group are supported. Additionally it accepts:

Parameters:

name (Optional[str]) – Name of the group. If set, the group object will be included in the parser.groups dict.

Return type:

ArgumentGroup

Returns:

The group object.

Raises:

ValueError – If group with the same name already exists.

set_defaults(*args, **kwargs)

Sets default values from dictionary or keyword arguments.

Parameters:

• *args (dict[str, Any]) – Dictionary defining the default values to set.

• **kwargs (Any) – Sets default values based on keyword arguments.

Raises:

KeyError – If key not defined in the parser.

Return type:

None

class jsonargparse.ArgumentParser(*args, env_prefix=True, formatter_class=<class 'jsonargparse._formatters.DefaultHelpFormatter'>, exit_on_error=True, logger=False, version=None, print_config='--print_config', parser_mode='yaml', dump_header=None, default_config_files=None, default_env=False, **kwargs)

Bases: ParserDeprecations, ActionsContainer, ArgumentLinking, LoggerProperty, ArgumentParser

Parser for command line, configuration files and environment variables.

Methods:

__init__(*args[, env_prefix, ...])	Initializer for ArgumentParser instance.
parse_known_args([args, namespace])	Raises NotImplementedError to dissuade its use, since typos in configs would go unnoticed.
parse_args([args, namespace, env, defaults])	Parses command line argument strings.
parse_object(cfg_obj[, cfg_base, env, defaults])	Parses configuration given as an object.
parse_env([env, defaults])	Parses environment variables.
parse_path(cfg_path[, ext_vars, env, defaults])	Parses a configuration file given its path.
parse_string(cfg_str[, cfg_path, ext_vars, ...])	Parses configuration given as a string.
add_subparsers(**kwargs)	Raises a NotImplementedError since jsonargparse uses add_subcommands.
add_subcommands([required, dest])	Adds sub-command parsers to the ArgumentParser.
dump(cfg[, format, skip_none, skip_default, ...])	Generates a yaml or json string for the given configuration object.
save(cfg, path[, format, skip_none, ...])	Writes to file(s) the yaml or json for the given configuration object.
get_default(dest)	Gets a single default value for the given destination key.
get_defaults([skip_validation])	Returns a namespace with all default values.
error(message[, ex])	Logs error message if a logger is set and exits or raises an ArgumentError.
validate(cfg[, skip_none, skip_required, branch])	Checks that the content of a given configuration object conforms with the parser.
add_instantiator(instantiator, class_type[, ...])	Adds a custom instantiator for a class type.
instantiate_classes(cfg[, instantiate_groups])	Recursively instantiates all subclasses defined by 'class_path' and 'init_args' and class groups.
strip_unknown(cfg)	Removes all unknown keys from a configuration object.
get_config_files(cfg)	Returns a list of loaded config file paths.
merge_config(cfg_from, cfg_to)	Merges the first configuration into the second configuration.

Attributes:

default_config_files	Default config file locations.
default_env	Whether by default environment variables parsing is enabled.
env_prefix	The environment variables prefix property.
parser_mode	'yaml', 'jsonnet' or ones added via set_loader().
dump_header	Header to include as comment when dumping a config object.

__init__(*args, env_prefix=True, formatter_class=<class 'jsonargparse._formatters.DefaultHelpFormatter'>, exit_on_error=True, logger=False, version=None, print_config='--print_config', parser_mode='yaml', dump_header=None, default_config_files=None, default_env=False, **kwargs)

Initializer for ArgumentParser instance.

All the arguments from the initializer of argparse.ArgumentParser are supported. Additionally it accepts:

Parameters:

• env_prefix (Union[bool, str]) – Prefix for environment variables. True to derive from prog.

• formatter_class (type[DefaultHelpFormatter]) – Class for printing help messages.

• logger (Union[bool, str, dict, Logger]) – Logger to use or configuration for logger.

• version (Optional[str]) – Program version which will be printed by the –version argument.

• print_config (Optional[str]) – Name for print config argument, %s is replaced by config dest, set None to disable.

• parser_mode (str) – Mode for parsing values: yaml, json, jsonnet or added via set_loader().

• dump_header (Optional[list[str]]) – Header to include as comment when dumping a config object.

• default_config_files (Optional[list[Union[str, PathLike]]]) – Default config file locations, e.g. ['~/.config/myapp/*.yaml'].

• default_env (bool) – Set the default value on whether to parse environment variables.

parse_known_args(args=None, namespace=None)

Raises NotImplementedError to dissuade its use, since typos in configs would go unnoticed.

parse_args(args=None, namespace=None, env=None, defaults=True, **kwargs)

Parses command line argument strings.

All the arguments from argparse.ArgumentParser.parse_args are supported. Additionally it accepts:

Parameters:

• args (Optional[Sequence[str]]) – List of arguments to parse or None to use sys.argv.

• env (Optional[bool]) – Whether to merge with the parsed environment, None to use parser’s default.

• defaults (bool) – Whether to merge with the parser’s defaults.

Return type:

Namespace

Returns:

A config object with all parsed values.

Raises:

ArgumentError – If the parsing fails error and exit_on_error=True.

parse_object(cfg_obj, cfg_base=None, env=None, defaults=True, **kwargs)

Parses configuration given as an object.

Parameters:

• cfg_obj (Union[Namespace, dict[str, Any]]) – The configuration object.

• env (Optional[bool]) – Whether to merge with the parsed environment, None to use parser’s default.

• defaults (bool) – Whether to merge with the parser’s defaults.

Return type:

Namespace

Returns:

A config object with all parsed values.

Raises:

ArgumentError – If the parsing fails error and exit_on_error=True.

parse_env(env=None, defaults=True, **kwargs)

Parses environment variables.

Parameters:

• env (Optional[dict[str, str]]) – The environment object to use, if None os.environ is used.

• defaults (bool) – Whether to merge with the parser’s defaults.

Return type:

Namespace

Returns:

A config object with all parsed values.

Raises:

ArgumentError – If the parsing fails error and exit_on_error=True.

parse_path(cfg_path, ext_vars=None, env=None, defaults=True, **kwargs)

Parses a configuration file given its path.

Parameters:

• cfg_path (Union[str, PathLike]) – Path to the configuration file to parse.

• ext_vars (Optional[dict]) – Optional external variables used for parsing jsonnet.

• env (Optional[bool]) – Whether to merge with the parsed environment, None to use parser’s default.

• defaults (bool) – Whether to merge with the parser’s defaults.

Return type:

Namespace

Returns:

A config object with all parsed values.

Raises:

ArgumentError – If the parsing fails error and exit_on_error=True.

parse_string(cfg_str, cfg_path='', ext_vars=None, env=None, defaults=True, **kwargs)

Parses configuration given as a string.

Parameters:

• cfg_str (str) – The configuration content.

• cfg_path (Union[str, PathLike]) – Optional path to original config path, just for error printing.

• ext_vars (Optional[dict]) – Optional external variables used for parsing jsonnet.

• env (Optional[bool]) – Whether to merge with the parsed environment, None to use parser’s default.

• defaults (bool) – Whether to merge with the parser’s defaults.

Return type:

Namespace

Returns:

A config object with all parsed values.

Raises:

ArgumentError – If the parsing fails error and exit_on_error=True.

add_subparsers(**kwargs)

Raises a NotImplementedError since jsonargparse uses add_subcommands.

Return type:

NoReturn

add_subcommands(required=True, dest='subcommand', **kwargs)

Adds sub-command parsers to the ArgumentParser.

The aim is the same as argparse.ArgumentParser.add_subparsers the difference being that dest by default is ‘subcommand’ and the parsed values of the sub-command are stored in a nested namespace using the sub-command’s name as base key.

Parameters:

• required (bool) – Whether the subcommand must be provided.

• dest (str) – Destination key where the chosen subcommand name is stored.

• **kwargs – All options that argparse.ArgumentParser.add_subparsers accepts.

Return type:

_ActionSubCommands

dump(cfg, format='parser_mode', skip_none=True, skip_default=False, skip_validation=False, with_comments=False, skip_link_targets=True, **kwargs)

Generates a yaml or json string for the given configuration object.

Parameters:

• cfg (Namespace) – The configuration object to dump.

• format (str) – The output format: 'yaml', 'json', 'json_indented', 'toml', 'parser_mode' or ones added via set_dumper().

• skip_none (bool) – Whether to exclude entries whose value is None.

• skip_default (bool) – Whether to exclude entries whose value is the same as the default.

• skip_validation (bool) – Whether to skip parser checking.

• with_comments (bool) – Whether to add help content as comments. Currently only supported for format='yaml'.

• skip_link_targets (bool) – Whether to exclude link targets.

Return type:

str

Returns:

The configuration in yaml or json format.

Raises:

TypeError – If any of the values of cfg is invalid according to the parser.

save(cfg, path, format='parser_mode', skip_none=True, skip_validation=False, overwrite=False, multifile=True, branch=None, **kwargs)

Writes to file(s) the yaml or json for the given configuration object.

Parameters:

• cfg (Namespace) – The configuration object to save.

• path (Union[str, PathLike]) – Path to the location where to save config.

• format (str) – The output format: 'yaml', 'json', 'json_indented', 'parser_mode' or ones added via set_dumper().

• skip_none (bool) – Whether to exclude entries whose value is None.

• skip_validation (bool) – Whether to skip parser checking.

• overwrite (bool) – Whether to overwrite existing files.

• multifile (bool) – Whether to save multiple config files by using the __path__ metas.

Raises:

TypeError – If any of the values of cfg is invalid according to the parser.

Return type:

None

get_default(dest)

Gets a single default value for the given destination key.

Parameters:

dest (str) – Destination key from which to get the default.

Raises:

KeyError – If key or its default not defined in the parser.

Return type:

Any

get_defaults(skip_validation=False, **kwargs)

Returns a namespace with all default values.

Parameters:

skip_validation (bool) – Whether to skip validation of defaults.

Return type:

Namespace

Returns:

An object with all default values as attributes.

error(message, ex=None)

Logs error message if a logger is set and exits or raises an ArgumentError.

Return type:

NoReturn

validate(cfg, skip_none=True, skip_required=False, branch=None, **kwargs)

Checks that the content of a given configuration object conforms with the parser.

Parameters:

• cfg (Namespace) – The configuration object to check.

• skip_none (bool) – Whether to skip checking of values that are None.

• skip_required (bool) – Whether to skip checking required arguments.

• branch (Optional[str]) – Base key in case cfg corresponds only to a branch.

Raises:

• TypeError – If any of the values are not valid.

• KeyError – If a key in cfg is not defined in the parser.

Return type:

None

add_instantiator(instantiator, class_type, subclasses=True, prepend=False)

Adds a custom instantiator for a class type. Used by instantiate_classes.

Instantiator functions are expected to have as signature (class_type: Type[ClassType], *args, **kwargs) -> ClassType.

For reference, the default instantiator is return class_type(*args, **kwargs).

In some use cases, the instantiator function might need access to values applied by instantiation links. For this, the instantiator function can have an additional keyword parameter applied_instantiation_links: dict. This parameter will be populated with a dictionary having as keys the targets of the instantiation links and corresponding values that were applied.

Parameters:

• instantiator (InstantiatorCallable) – Function that instantiates a class.

• class_type (type[TypeVar(ClassType)]) – The class type to instantiate.

• subclasses (bool) – Whether to instantiate subclasses of class_type.

• prepend (bool) – Whether to prepend the instantiator to the existing instantiators.

Return type:

None

instantiate_classes(cfg, instantiate_groups=True)

Recursively instantiates all subclasses defined by ‘class_path’ and ‘init_args’ and class groups.

Parameters:

• cfg (Namespace) – The configuration object to use.

• instantiate_groups (bool) – Whether class groups should be instantiated.

Return type:

Namespace

Returns:

A configuration object with all subclasses and class groups instantiated.

strip_unknown(cfg)

Removes all unknown keys from a configuration object.

Parameters:

cfg (Namespace) – The configuration object to strip.

Return type:

Namespace

Returns:

The stripped configuration object.

get_config_files(cfg)

Returns a list of loaded config file paths.

Parameters:

cfg (Namespace) – The configuration object.

Return type:

list[str]

Returns:

Paths to loaded config files.

merge_config(cfg_from, cfg_to)

Merges the first configuration into the second configuration.

Parameters:

• cfg_from (Namespace) – The configuration from which to merge.

• cfg_to (Namespace) – The configuration into which to merge.

Return type:

Namespace

Returns:

A new object with the merged configuration.

property default_config_files: list[str]

Default config file locations.

Getter:

Returns the current default config file locations.

Setter:

Sets new default config file locations, e.g. ['~/.config/myapp/*.yaml'].

Raises:

ValueError – If an invalid value is given.

property default_env: bool

Whether by default environment variables parsing is enabled.

If the JSONARGPARSE_DEFAULT_ENV environment variable is set to true or false, that value will take precedence.

Getter:

Returns the current default environment variables parsing setting.

Setter:

Sets the default environment variables parsing setting.

Raises:

ValueError – If an invalid value is given.

property env_prefix: bool | str

The environment variables prefix property.

Getter:

Returns the current environment variables prefix.

Setter:

Sets the environment variables prefix.

Raises:

ValueError – If an invalid value is given.

property parser_mode: str

'yaml', 'jsonnet' or ones added via set_loader().

Getter:

Returns the current parser mode.

Setter:

Sets the parser mode.

Raises:

ValueError – If an invalid value is given.

Type:

Mode for parsing configuration files

property dump_header: list[str] | None

Header to include as comment when dumping a config object.

Getter:

Returns the current dump header.

Setter:

Sets the dump header.

Raises:

ValueError – If an invalid value is given.