Skip to content
New: Star-import, signal unraveling, Python 3.12 support, and more

# 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

- Comparable
- Config
- Pickleable
- Prettified
- atomic_dict
- `builtins.dict`
- pdict

Inherited members

- Config.clear()
- Config.copy()
- Config.equals()
- Config.get_option()
- Config.load_update()
- Config.make_checkpoint()
- Config.merge_with()
- Config.options_
- Config.pop()
- Config.popitem()
- Config.prettify()
- Config.rec_state
- Config.reset()
- Config.set_option()
- Config.to_dict()
- Config.update()
- Pickleable.decode_config()
- Pickleable.decode_config_node()
- Pickleable.dumps()
- Pickleable.encode_config()
- Pickleable.encode_config_node()
- Pickleable.file_exists()
- Pickleable.getsize()
- Pickleable.load()
- Pickleable.loads()
- Pickleable.modify_state()
- Pickleable.resolve_file_path()
- Pickleable.save()

## 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

- Comparable
- Pickleable
- Prettified
- `builtins.dict`
- pdict

Inherited members

- Pickleable.decode_config()
- Pickleable.decode_config_node()
- Pickleable.dumps()
- Pickleable.encode_config()
- Pickleable.encode_config_node()
- Pickleable.file_exists()
- Pickleable.getsize()
- Pickleable.load()
- Pickleable.loads()
- Pickleable.modify_state()
- Pickleable.resolve_file_path()
- Pickleable.save()
- pdict.equals()
- pdict.load_update()
- pdict.prettify()
- pdict.rec_state

Subclasses

- AtomicConfig
- FrozenConfig
- HybridConfig
- ReadonlyConfig
- SettingsConfig
- flex_cfg
- frozen_cfg

### 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=vectorbtpro.utils.config._DEF,
        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

- Cacheable
- Chainable
- Comparable
- HasSettings
- Pickleable
- Prettified

Inherited members

- Cacheable.get_ca_setup()
- Chainable.pipe()
- HasSettings.get_path_setting()
- HasSettings.get_path_settings()
- HasSettings.get_setting()
- HasSettings.get_settings()
- HasSettings.has_path_setting()
- HasSettings.has_path_settings()
- HasSettings.has_setting()
- HasSettings.has_settings()
- HasSettings.reset_settings()
- HasSettings.resolve_setting()
- HasSettings.resolve_settings_paths()
- HasSettings.set_settings()
- Pickleable.decode_config()
- Pickleable.decode_config_node()
- Pickleable.dumps()
- Pickleable.encode_config()
- Pickleable.encode_config_node()
- Pickleable.file_exists()
- Pickleable.getsize()
- Pickleable.load()
- Pickleable.loads()
- Pickleable.modify_state()
- Pickleable.rec_state
- Pickleable.resolve_file_path()
- Pickleable.save()
- Prettified.prettify()

Subclasses

- ArrayWrapper
- Bar
- BaseIDXAccessor
- BasePreparer
- Box
- Chunker
- DataUpdater
- ExecutionEngine
- Gauge
- Grouper
- Heatmap
- Histogram
- IndicatorFactory
- Jitter
- PFPrepResult
- Parameterizer
- QSAdapter
- Resampler
- Scatter
- TVClient
- TelegramBot
- Volume
- Wrapping

### 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

- Comparable
- Config
- Pickleable
- Prettified
- `builtins.dict`
- pdict

Inherited members

- Config.clear()
- Config.copy()
- Config.equals()
- Config.get_option()
- Config.load_update()
- Config.make_checkpoint()
- Config.merge_with()
- Config.options_
- Config.pop()
- Config.popitem()
- Config.prettify()
- Config.rec_state
- Config.reset()
- Config.set_option()
- Config.to_dict()
- Config.update()
- Pickleable.decode_config()
- Pickleable.decode_config_node()
- Pickleable.dumps()
- Pickleable.encode_config()
- Pickleable.encode_config_node()
- Pickleable.file_exists()
- Pickleable.getsize()
- Pickleable.load()
- Pickleable.loads()
- Pickleable.modify_state()
- Pickleable.resolve_file_path()
- Pickleable.save()

## HasSettings class

    HasSettings()

Class that has settings in vectorbtpro._settings.

Subclasses

- Configured

### get_path_setting class method

    HasSettings.get_path_setting(
        path,
        key,
        default=vectorbtpro.utils.config._DEF,
        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=vectorbtpro.utils.config._DEF,
        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=vectorbtpro.utils.config._DEF,
        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

- Comparable
- Config
- Pickleable
- Prettified
- `builtins.dict`
- pdict

Inherited members

- Config.clear()
- Config.copy()
- Config.equals()
- Config.get_option()
- Config.load_update()
- Config.make_checkpoint()
- Config.merge_with()
- Config.options_
- Config.pop()
- Config.popitem()
- Config.prettify()
- Config.rec_state
- Config.reset()
- Config.set_option()
- Config.to_dict()
- Config.update()
- Pickleable.decode_config()
- Pickleable.decode_config_node()
- Pickleable.dumps()
- Pickleable.encode_config()
- Pickleable.encode_config_node()
- Pickleable.file_exists()
- Pickleable.getsize()
- Pickleable.load()
- Pickleable.loads()
- Pickleable.modify_state()
- Pickleable.resolve_file_path()
- Pickleable.save()

## ReadonlyConfig class

    ReadonlyConfig(
        *args,
        **kwargs
    )

Config with `readonly` flag set to True.

Superclasses

- Comparable
- Config
- Pickleable
- Prettified
- `builtins.dict`
- pdict

Inherited members

- Config.clear()
- Config.copy()
- Config.equals()
- Config.get_option()
- Config.load_update()
- Config.make_checkpoint()
- Config.merge_with()
- Config.options_
- Config.pop()
- Config.popitem()
- Config.prettify()
- Config.rec_state
- Config.reset()
- Config.set_option()
- Config.to_dict()
- Config.update()
- Pickleable.decode_config()
- Pickleable.decode_config_node()
- Pickleable.dumps()
- Pickleable.encode_config()
- Pickleable.encode_config_node()
- Pickleable.file_exists()
- Pickleable.getsize()
- Pickleable.load()
- Pickleable.loads()
- Pickleable.modify_state()
- Pickleable.resolve_file_path()
- Pickleable.save()

## 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

- Comparable
- Pickleable
- Prettified
- `builtins.dict`
- pdict

Inherited members

- Pickleable.decode_config()
- Pickleable.decode_config_node()
- Pickleable.dumps()
- Pickleable.encode_config()
- Pickleable.encode_config_node()
- Pickleable.file_exists()
- Pickleable.getsize()
- Pickleable.load()
- Pickleable.loads()
- Pickleable.modify_state()
- Pickleable.resolve_file_path()
- Pickleable.save()
- pdict.equals()
- pdict.load_update()
- pdict.prettify()
- pdict.rec_state

Subclasses

- AtomicConfig

## child_dict class

    child_dict(
        *args,
        **kwargs
    )

Subclass of `dict` acting as a child dict.

Superclasses

- Comparable
- Pickleable
- Prettified
- `builtins.dict`
- pdict

Inherited members

- Pickleable.decode_config()
- Pickleable.decode_config_node()
- Pickleable.dumps()
- Pickleable.encode_config()
- Pickleable.encode_config_node()
- Pickleable.file_exists()
- Pickleable.getsize()
- Pickleable.load()
- Pickleable.loads()
- Pickleable.modify_state()
- Pickleable.resolve_file_path()
- Pickleable.save()
- pdict.equals()
- pdict.load_update()
- pdict.prettify()
- pdict.rec_state

## hdict class

    hdict(
        *args,
        **kwargs
    )

Hashable dict.

Superclasses

- `builtins.dict`

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings