jacinle.config.environ_v2

This file defines a global variable configs, which can be used as a (nested) dictionary to store configuration values. There are three modes of using this variable:

Definition mode: enabled by jacinle.def_configs(). In this mode, you can access the configs variable to define keys and their default values. For example:

>>> from jacinle.config.environ_v2 import def_configs, configs
>>> with def_configs():
...     configs.model.name = 'resnet18'

In this case, the key model.name will be defined with the default value 'resnet18'.

Setting mode: enabled by jacinle.set_configs(). In this mode, you can access the configs variable to set values. For example:

>>> from jacinle.config.environ_v2 import set_configs, configs
>>> with set_configs():
...     configs.model.name = 'resnet50'

In this case, the key model.name will be set to 'resnet50'.

Reading mode: this is the default mode. In this mode, you can access the configs variable to read values. For example:

>>> from jacinle.config.environ_v2 import configs
>> print(configs.model.name)

Here is a more complete example:

>>> from jacinle.config.environ_v2 import def_configs, set_configs, configs
>>> with def_configs():
...     configs.model.name = 'resnet18'
...     configs.model.num_classes = 1000
...     configs.model.num_layers = 18

>>> with set_configs():
...     configs.model.name = 'resnet50'
...     configs.model.num_layers = 50
...     configs.model.num_filters = 64

>>> print(configs.model.name)  # 'resnet50'
>>> print('Undefined keys:', configs.find_undefined_values())  # ['model.num_filters']

Note that, we have also provided a helper function configs.find_undefined_values to find all undefined keys in the configs variables (i.e., those keys used in set_configs but not defined in def_configs). This can be used as a sanity check to make sure that all keys are defined.

Note that, a definition of a key in def_configs can be later than its usage in set_configs. This allows you to have a global configuration file that sets all keys, while the definition of each key is in the corresponding module (data, model, etc.)

When a key has not been defined or set, reading it will raise an error.

Module attributes

configs

The global configuration dictionary.

Classes

StrictG

A strictly-managed dictionary that supports three-mode access (define, set, read).

Functions

def_configs()	A context manager to enable configuration definition mode.
def_configs_func(func)	A decorator to enable configuration definition mode when calling a function.
set_configs()	A context manager to enable configuration setting mode.
set_configs_func(func)	A decorator to enable configuration setting mode when calling a function.

Class StrictG

class StrictG

Bases: dict

A strictly-managed dictionary that supports three-mode access (define, set, read).

__init__(*args, **kwargs)

def_(name, type=None, choices=None, default=None, help=None)

Define a key. If the key has already been defined, raise an error. This function is more flexible than __setattr__ because it allows you to specify the type, choices, and default value of the key. It also allows you to specify a help message for the key.

find_undefined_values(global_prefix='configs')

Find all undefined keys in the dictionary. This function is used to check whether all keys have been defined.

Parameters:

global_prefix (str) – the prefix of the global configuration dictionary when printing the undefined keys.

format(sep=': ', end='\n')

Format the dictionary into a string.

print(sep=': ', end='\n', file=None)

Print the dictionary.

validate(name)

Validate the value of a key based on the type, choices, and default value specified.

Functions

def_configs()

A context manager to enable configuration definition mode. See the module docstring jacinle.configs.environ_v2 for more details.

def_configs_func(func)

A decorator to enable configuration definition mode when calling a function. See the module docstring jacinle.configs.environ_v2 for more details.

set_configs()

A context manager to enable configuration setting mode. See the module docstring jacinle.configs.environ_v2 for more details.

set_configs_func(func)

A decorator to enable configuration setting mode when calling a function. See the module docstring jacinle.configs.environ_v2 for more details.