Skip to content

config module

Utilities for configuration.

unsetkey _unsetkey

When passed as a value, the corresponding key will be unset.

It can still be overridden by another dict.

combine_pathlike_keys function

combine_pathlike_keys(
    k1,
    k2
)

Combine two path-like keys.

convert_to_dict function

convert_to_dict(
    dct,
    nested=True
)

Convert any config to dict.

Set nested to True to convert all child dicts in recursive manner.

If a config is an instance of AtomicConfig, will convert it to atomic_dict.

copy_dict function

copy_dict(
    dct,
    copy_mode='shallow',
    nested=True
)

Copy dict based on a copy mode.

The following modes are supported:

  • 'none': Does not copy
  • 'shallow': Copies keys only
  • 'hybrid': Copies keys and values using copy.copy
  • 'deep': Copies the whole thing using copy.deepcopy

Set nested to True to copy all child dicts in recursive manner.

del_dict_item function

del_dict_item(
    dct,
    k,
    force=False
)

Delete dict item.

If the dict is of the type Config, also passes force keyword to override blocking flags.

get_dict_item function

get_dict_item(
    dct,
    k,
    populate=False
)

Get dict item under the key k.

The key can be nested using the dot notation, pathlib.Path, or a tuple, and must be hashable.

merge_dicts function

merge_dicts(
    *dicts,
    to_dict=True,
    copy_mode='shallow',
    nested=None,
    same_keys=False
)

Merge dicts.

Args

*dicts : dict
Dicts.
to_dict : bool
Whether to call convert_to_dict() on each dict prior to copying.
copy_mode : str
Mode for copy_dict() to copy each dict prior to merging.
nested : bool

Whether to merge all child dicts in recursive manner.

If None, checks whether any dict is nested.

same_keys : bool
Whether to merge on the overlapping keys only.

resolve_dict function

resolve_dict(
    dct,
    i=None
)

Select keyword arguments.

resolve_pathlike_key function

resolve_pathlike_key(
    k
)

Convert a path-like key into a tuple.

set_dict_item function

set_dict_item(
    dct,
    k,
    v,
    force=False
)

Set dict item.

If the dict is of the type Config, also passes force keyword to override blocking flags.

unset_keys function

unset_keys(
    dct,
    nested=True,
    force=False
)

Unset the keys that have the value unsetkey.

update_dict function

update_dict(
    x,
    y,
    nested=True,
    force=False,
    same_keys=False
)

Update dict with keys and values from other dict.

Set nested to True to update all child dicts in recursive manner.

For force, see set_dict_item().

If you want to treat any dict as a single value, wrap it with atomic_dict.

If nested is True, a value in x is an instance of Configured, and the corresponding value in y is a dictionary, calls Configured.replace().

Note

If the child dict is not atomic, it will copy only its values, not its meta.

AtomicConfig class

AtomicConfig(
    *args,
    options_=None,
    **kwargs
)

Config that behaves like a single value when merging.

Superclasses

Inherited members

Config class

Config(
    *args,
    options_=None,
    **kwargs
)

Extends pickleable dict with config features such as nested updates, freezing, and resetting.

Args

*args
Arguments to construct the dict from.
options_ : dict
Config options (see below).
**kwargs
Keyword arguments to construct the dict from.

Options can have the following keys:

Attributes

copy_kwargs : dict

Keyword arguments passed to copy_dict() for copying main dict and reset_dct.

Copy mode defaults to 'none'.

reset_dct : dict

Dict to fall back to in case of resetting.

Defaults to None. If None, copies main dict using reset_dct_copy_kwargs.

Note

Defaults to main dict in case it's None and readonly is True.

reset_dct_copy_kwargs : dict

Keyword arguments that override copy_kwargs for reset_dct.

Copy mode defaults to 'none' if readonly is True, else to 'hybrid'.

pickle_reset_dct : bool
Whether to pickle reset_dct.
frozen_keys : bool

Whether to deny updates to the keys of the config.

Defaults to False.

readonly : bool

Whether to deny updates to the keys and values of the config.

Defaults to False.

nested : bool

Whether to do operations recursively on each child dict.

Such operations include copy, update, and merge. Disable to treat each child dict as a single value. Defaults to True.

convert_children : bool or type

Whether to convert child dicts of type child_dict to configs with the same configuration.

This will trigger a waterfall reaction across all child dicts. Won't convert dicts that are already configs. Apart from boolean, you can set it to any subclass of Config to use it for construction. Requires nested to be True. Defaults to False.

as_attrs : bool

Whether to enable accessing dict keys via the dot notation.

Enables autocompletion (but only during runtime!). Raises error in case of naming conflicts. Defaults to True if frozen_keys or readonly, otherwise False.

To make nested dictionaries also accessible via the dot notation, wrap them with child_dict and set convert_children and nested to True.

Defaults can be overridden with settings under config.

If another config is passed, its properties are copied over, but they can still be overridden with the arguments passed to the initializer.

Note

All arguments are applied only once during initialization.

Superclasses

Inherited members

Subclasses

clear method

Config.clear(
    force=False
)

Remove all items.

copy method

Config.copy(
    reset_dct_copy_kwargs=None,
    copy_mode=None,
    nested=None
)

Copy the instance.

By default, copies in the same way as during the initialization.

get_option method

Config.get_option(
    k
)

Get an option.

make_checkpoint method

Config.make_checkpoint(
    force=False,
    **reset_dct_copy_kwargs
)

Replace reset_dct by the current state.

reset_dct_copy_kwargs override reset_dct_copy_kwargs.

merge_with method

Config.merge_with(
    other,
    copy_mode=None,
    nested=None,
    **kwargs
)

Merge with another dict into one single dict.

See merge_dicts().

options_ property

Config options.

pop method

Config.pop(
    k,
    v=_Missing.MISSING,
    force=False
)

Remove and return the pair by the key.

popitem method

Config.popitem(
    force=False
)

Remove and return some pair.

reset method

Config.reset(
    force=False,
    **reset_dct_copy_kwargs
)

Clears the config and updates it with the initial config.

reset_dct_copy_kwargs override reset_dct_copy_kwargs.

set_option method

Config.set_option(
    k,
    v
)

Set an option.

to_dict method

Config.to_dict(
    nested=None
)

Convert to dict.

update method

Config.update(
    *args,
    nested=None,
    force=False,
    **kwargs
)

Update the config.

See update_dict().

Configured class

Configured(
    **config
)

Class with an initialization config.

All subclasses of Configured are initialized using Config, which makes it easier to pickle.

Settings are defined under configured.

Warning

If any attribute has been overwritten that isn't listed in Configured._writeable_attrs, or if any Configured argument depends upon global defaults, their values won't be copied over. Make sure to pass them explicitly to make that the saved & loaded / copied instance is resilient to any changes in globals.

Superclasses

Inherited members

Subclasses

config property

Initialization config.

copy method

Configured.copy(
    copy_mode=None,
    nested=None,
    cls=None
)

Create a new instance by copying the config.

See Configured.replace().

equals method

Configured.equals(
    other,
    check_types=True,
    check_attrs=True,
    check_options=False,
    **kwargs
)

Check two objects for equality.

get_writeable_attrs class method

Configured.get_writeable_attrs()

Get set of attributes that are writeable by this class or by any of its base classes.

replace method

Configured.replace(
    copy_mode_=None,
    nested_=None,
    cls_=None,
    copy_writeable_attrs_=None,
    **new_config
)

Create a new instance by copying and (optionally) changing the config.

Warning

This operation won't return a copy of the instance but a new instance initialized with the same config and writeable attributes (or their copy, depending on copy_mode).

resolve_merge_kwargs class method

Configured.resolve_merge_kwargs(
    *configs,
    on_merge_conflict='error',
    **kwargs
)

Resolve keyword arguments for initializing Configured after merging.

update_config method

Configured.update_config(
    *args,
    **kwargs
)

Force-update the config.

FrozenConfig class

FrozenConfig(
    *args,
    **kwargs
)

Config with frozen_keys flag set to True.

Superclasses

Inherited members

HasSettings class

HasSettings()

Class that has settings in vectorbtpro._settings.

Subclasses

get_path_setting class method

HasSettings.get_path_setting(
    path,
    key,
    default=_Missing.MISSING,
    sub_path=None,
    sub_path_only=False
)

Get a value from the settings under a path.

get_path_settings class method

HasSettings.get_path_settings(
    path,
    sub_path=None,
    sub_path_only=False
)

Get the settings under a path.

get_setting class method

HasSettings.get_setting(
    key,
    default=_Missing.MISSING,
    path_id=None,
    inherit=True,
    sub_path=None,
    sub_path_only=False
)

Get a value under the settings associated with this class and its superclasses (if inherit is True).

get_settings class method

HasSettings.get_settings(
    path_id=None,
    inherit=True,
    sub_path=None,
    sub_path_only=False
)

Get the settings associated with this class and its superclasses (if inherit is True).

has_path_setting class method

HasSettings.has_path_setting(
    path,
    key,
    sub_path=None,
    sub_path_only=False
)

Return whether the setting under a path exists.

has_path_settings class method

HasSettings.has_path_settings(
    path,
    sub_path=None,
    sub_path_only=False
)

Return whether the settings under a path exist.

has_setting class method

HasSettings.has_setting(
    key,
    path_id=None,
    inherit=True,
    sub_path=None,
    sub_path_only=False
)

Return whether the settings associated with this class and its superclasses (if inherit is True) exists.

has_settings class method

HasSettings.has_settings(
    path_id=None,
    inherit=True,
    sub_path=None,
    sub_path_only=False
)

Return whether there the settings associated with this class and its superclasses (if inherit is True) exist.

reset_settings class method

HasSettings.reset_settings(
    path_id=None,
    sub_path=None
)

Reset the settings in vectorbtpro._settings associated with this class.

resolve_setting class method

HasSettings.resolve_setting(
    value,
    key,
    merge=False,
    default=_Missing.MISSING,
    path_id=None,
    inherit=True,
    sub_path=None,
    sub_path_only=False
)

Resolve a value that has a key under the settings in vectorbtpro._settings associated with this class.

If the provided value is None, returns the setting, otherwise the value. If the value is a dict and merge is True, merges it over the corresponding dict in the settings.

If sub_path is provided, appends it to the resolved path and gives it more priority. If only the sub_path should be considered, set sub_path_only to True.

resolve_settings_paths class method

HasSettings.resolve_settings_paths(
    path_id=None,
    inherit=True,
    super_first=True
)

Resolve the settings paths associated with this class and its superclasses (if inherit is True).

set_settings class method

HasSettings.set_settings(
    path_id=None,
    sub_path=None,
    populate_=False,
    **kwargs
)

Set the settings in vectorbtpro._settings associated with this class.

If the settings do not exist yet, pass populate_=True.

HybridConfig class

HybridConfig(
    *args,
    **kwargs
)

Config with copy_kwargs set to copy_mode='hybrid'.

Superclasses

Inherited members

ReadonlyConfig class

ReadonlyConfig(
    *args,
    **kwargs
)

Config with readonly flag set to True.

Superclasses

Inherited members

SettingNotFoundError class

SettingNotFoundError(
    *args,
    **kwargs
)

Gets raised if a setting could not be found.

Superclasses

  • builtins.BaseException
  • builtins.Exception
  • builtins.KeyError
  • builtins.LookupError

SettingsNotFoundError class

SettingsNotFoundError(
    *args,
    **kwargs
)

Gets raised if settings could not be found.

Superclasses

  • builtins.BaseException
  • builtins.Exception
  • builtins.KeyError
  • builtins.LookupError

atomic_dict class

atomic_dict(
    *args,
    **kwargs
)

Dict that behaves like a single value when merging.

Superclasses

Inherited members

Subclasses

child_dict class

child_dict(
    *args,
    **kwargs
)

Subclass of dict acting as a child dict.

Superclasses

Inherited members

hdict class

hdict(
    *args,
    **kwargs
)

Hashable dict.

Superclasses

  • builtins.dict