vcorelib.dict package

vcorelib.dict package#

Submodules#

vcorelib.dict.cache module#

A module implementing a JSON-file database.

class vcorelib.dict.cache.DirectoryCache(pathlike: ~pathlib.Path | str | None, arbiter: ~vcorelib.io.arbiter.DataArbiter = <vcorelib.io.arbiter.DataArbiter object>)[source]#

Bases: JsonCache

A class implementing a JSON cache based on a directory.

context_load(stack: ExitStack, **kwargs) → Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]][source]#: Load the data.

class vcorelib.dict.cache.FileCache(pathlike: ~pathlib.Path | str | None, arbiter: ~vcorelib.io.arbiter.DataArbiter = <vcorelib.io.arbiter.DataArbiter object>)[source]#

Bases: JsonCache

A class implementing a JSON cache based on a file.

context_load(stack: ExitStack, **kwargs) → Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]][source]#: Load the data.

class vcorelib.dict.cache.JsonCache(pathlike: ~pathlib.Path | str | None, arbiter: ~vcorelib.io.arbiter.DataArbiter = <vcorelib.io.arbiter.DataArbiter object>)[source]#

Bases: ABC

A JSON cach interface.

abstract context_load(stack: ExitStack, **kwargs) → Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]][source]#: Load the data.

loaded(**kwargs) → Iterator[Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]]][source]#: Provide loaded data so that the data is written back to disk on completion.

vcorelib.dict.codec module#

A module for implementing classes that can be loaded from dictionaries and exported as dictionaries.

Bases: DictCodec

The simplest possible dictionary codec implementation.

asdict() → Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]][source]#: Obtain a dictionary representing this instance.

init(data: Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]]) → None[source]#: Initialize this instance.

Bases: JsonCodec

A class implementing an interface for objects that can be decoded from disk and encoded back to disk.

classmethod create(data: Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]] = None, schemas: SchemaMap = None, dest_attr: str = 'data', verify: bool = True) → V[source]#: A factory method to create an instance.

default_schemas: SchemaMap | None = None#

abstract init(data: Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]]) → None[source]#: Perform implementation-specific initialization.

class vcorelib.dict.codec.JsonCodec(schemas: SchemaMap, valid_attr: str = 'data')[source]#

Bases: ABC, SchemaMixin

A simple JSON codec interface.

abstract asdict() → Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]][source]#: Obtain a dictionary representing this instance.

abstract classmethod create(data: Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]] = None, schemas: SchemaMap = None, dest_attr: str = 'data', verify: bool = True) → T[source]#: A factory method to create an instance.

classmethod decode(pathlike: ~pathlib.Path | str | None, arbiter: ~vcorelib.io.arbiter.DataArbiter = <vcorelib.io.arbiter.DataArbiter object>, schemas: ~vcorelib.schemas.base.SchemaMap = None, dest_attr: str = 'data', verify: bool = True, require_success: bool = True, default_data: ~typing.Dict[str, str | int | float | bool | None | ~typing.Dict[str, str | int | float | bool | None] | ~typing.List[str | int | float | bool | None]] = None, **kwargs) → T[source]#: Decode an object instance from data loaded from a file.

encode(pathlike: ~pathlib.Path | str | None, arbiter: ~vcorelib.io.arbiter.DataArbiter = <vcorelib.io.arbiter.DataArbiter object>, **kwargs) → Tuple[bool, int][source]#: Encode this object instance to a file.

classmethod file_cache(pathlike: ~pathlib.Path | str | None, arbiter: ~vcorelib.io.arbiter.DataArbiter = <vcorelib.io.arbiter.DataArbiter object>, encode_kwargs: ~typing.Dict[str, ~typing.Any] = None, require_success: bool = False, **kwargs) → Iterator[T][source]#: Manage an instance of this class as a disk-backed file.

classmethod normalize(data: Dict[str, str | int | float | bool | None | Dict[str, str | int | float | bool | None] | List[str | int | float | bool | None]] | T) → T[source]#: Ensure that some object is an instance of this class.

vcorelib.dict.config module#

A module for implementing a configuration data manager with a dictionary.

class vcorelib.dict.config.Config(dict=None, /, **kwargs)[source]#

Bases: UserDict, MutableMapping[str, Any]

A dictionary that allows access to data only once via each key.

static from_directory(pathlike: Path | str | None, *args, **kwargs) → Config[source]#: Load a configuration from a directory on disk.

static from_file(pathlike: Path | str | None, *args, **kwargs) → Config[source]#: Load a configuration from a file on disk.

static from_path(pathlike: Path | str | None, *args, **kwargs) → Config[source]#: Load a configuration from an arbitrary path.

get(key, default=None) → Any[source]#: Get data from the configuration but allow a default value.

merge(other: Dict[Any, Any], *args, **kwargs) → None[source]#: Merge another dictionary into this one.

set_if_not(key, value) → Any[source]#: Set this value if a value is not already set.

vcorelib.dict.env module#

Utilities for working with environment-variable data contained inside various data structures.

vcorelib.dict.env.dict_resolve_env_vars(data: Dict[Any, Any], keys: bool = True, values: bool = True, lists: bool = True, env: Mapping[str, str] = None) → Dict[Any, Any][source]#: Recursively resolve dictionary data that may contain strings that should be treated as environment-variable substitutions. The data is updated in-place.

vcorelib.dict.env.list_resolve_env_vars(data: List[Any], keys: bool = True, values: bool = True, lists: bool = True, env: Mapping[str, str] = None) → List[Any][source]#: Recursively resolve list data that may contain strings that should be treated as environment-variable substitutions. The data is updated in-place.

vcorelib.dict.env.str_resolve_env_var(data: str, env: Mapping[str, Any] = None) → str[source]#: Convert string data to a resolved environment variable if the string begins with ‘$’ and is a key in the environment with a non-empty value.

Module contents#

Dictionary manipulation utilities.

class vcorelib.dict.MergeStrategy(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

An enumeration describing strategies for combining various data structures.

RECURSIVE = 1#

UPDATE = 2#

vcorelib.dict.consume(data: Dict[Any, Any], key: Any, default: Any = None) → Any[source]#: Attempt to obtain dictionary data via key, removing the data if it was present.

vcorelib.dict.limited(data: Dict[Any, Any], key: Any, value: Any = None) → Iterator[None][source]#: Ensure that dictionary data is only temporarily added.

vcorelib.dict.merge(dict_a: Dict[Any, Any], dict_b: Dict[Any, Any], path: List[str] = None, expect_overwrite: bool = False, logger: Logger | LoggerAdapter[Any] = None, strategy: MergeStrategy = MergeStrategy.RECURSIVE) → Dict[Any, Any][source]#: Combine two dictionaries based on a provided merge strategy.

vcorelib.dict.merge_dicts(dicts: List[Dict[Any, Any]], expect_overwrite: bool = False, logger: Logger | LoggerAdapter[Any] = None, strategy: MergeStrategy = MergeStrategy.RECURSIVE) → Dict[Any, Any][source]#: Merge a list of dictionary data into a single set (mutates the first element).

vcorelib.dict.merge_recursive(dict_a: Dict[Any, Any], dict_b: Dict[Any, Any], path: List[str] = None, expect_overwrite: bool = False, logger: Logger | LoggerAdapter[Any] = None, strategy: MergeStrategy = MergeStrategy.RECURSIVE) → Dict[Any, Any][source]#: Combine two dictionaries recursively, prefers dict_a in a conflict. For values of the same key that are lists, the lists are combined. Otherwise the resulting dictionary is cleanly merged.

vcorelib.dict.set_if_not(data: Dict[Any, Any], key: Any, value: Any = None) → Any[source]#: Set a value in a dictionary if one wasn’t already set and return the value that ends up at that key.