4.7.2 pde.tools.config module

Handles configuration variables of the package.

Parameter	Class representing a single parameter.
Config	Class handling general (nested) configurations.
get_package_versions	Tries to load certain python packages and returns their version.
parse_version_str	Helper function converting a version string into a list of integers.
check_package_version	Checks whether a package has a sufficient version.
packages_from_requirements	Read package names from a requirements file.
get_ffmpeg_version	Read version number of ffmpeg program.
is_hpc_environment	Check whether the code is running in a high-performance computing environment.
environment	Obtain information about the compute environment.

exception AccessError

Bases: RuntimeError

Raised when a configuration change violates the active access mode.

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class Config(items: MutableMapping[str, Any] | Config | Sequence[Parameter] | None = None, *, mode: ConfigMode | str = 'update')

Bases: NestedDict[Parameter]

Class handling general (nested) configurations.

Configurations are basically (nested) dictionaries with string keys that hold Parameter values, which contain a value with some extra information. Moreover, configurations have a mode that controls whether the configuration is writeable or not.

Parameters:

• items (dict, optional) – Configuration values that should be added or overwritten to initialize the configuration.

• mode (str) –

  Defines the mode in which the configuration is used. Possible values are

  • insert: any new configuration key can be inserted

  • update: only the values of pre-existing items can be updated

  • locked: no values can be changed

  Note that the items specified by items will always be inserted, independent of the mode.

changed_mode(**kwargs)

Temporarily switch to mode and restore the previous mode afterwards.

Parameters:

**kwargs – Keyword arguments forwarded to ConfigMode._setstate(), such as node, leaf, and delete.

Yields:

ConfigMode – The mode controller with the temporary mode applied.

clear() → None

Removes all top-level entries from the mapping.

copy() → Config

Creates a structural copy with copied nested mappings.

Child dictionaries and child NestedDict instances are copied, while non-mapping leaf values are reused by reference.

Returns:

New instance containing copied nested structure.

Return type:

NestedDict

create_node(key: str) → Self

Create an empty node at the given location.

Creates all necessary parent nodes recursively. Skips nodes that already exist.

Parameters:

key – Key or nested key path identifying the node to create.

Returns:

The leaf node

items(*, flatten: bool = False) → Iterator[tuple[str, TNestedDictValue[TValue]]]

Iterates over key-value pairs, optionally flattening nested paths.

Parameters:

flatten (bool) – If True, yields (path, value) pairs for all descendants. If False, yields only top-level pairs.

Returns:

Iterator over key-value pairs according to flatten.

Return type:

Iterator[tuple[str, Any]]

Raises:

TypeError – If a key used during flattening is not a string.

keys(*, flatten: bool = False) → Iterator[str]

Iterates over keys, optionally returning flattened key paths.

Parameters:

flatten (bool) – If True, yields separator-joined paths for descendant keys. If False, yields only top-level keys.

Returns:

Iterator over keys or flattened key paths.

Return type:

Iterator[str]

Raises:

TypeError – If a key used during flattening is not a string.

property mode: ConfigMode

Current mutable mode descriptor shared across the whole config tree.

pprint(*args: Any, flatten: bool = False, **kwargs: Any) → None

Pretty-prints the current data as nested plain dictionaries.

Parameters:

• *args (Any) – Positional arguments forwarded to pprint.pprint.

• flatten (bool) – If True, returns a flat mapping with separator-joined paths as keys. If False, returns nested dictionaries.

• **kwargs (Any) – Keyword arguments forwarded to pprint.pprint.

replace_recursive(other: MutableMapping[str, Any], delete_extra: bool = False) → None

Recursively replaces data of the current instance by another mapping.

Parameters:

other (MutableMapping[str, Any]) – Mapping whose entries are will end up in this object.

to_dict(flatten: bool = False, values: bool = False) → dict[str, Any]

Convert the configuration to a simple dictionary.

Parameters:

• flatten (bool) – Return flat or nested dictionary.

• values (bool) – Whether to return only values (and not Parameter instances)

Returns:

A representation of the configuration in a normal dict.

Return type:

dict

update(other) → None

Update this mapping from another mapping recursively.

This method implements collections.abc.MutableMapping update semantics for mapping-like inputs and forwards the actual merge to update_recursive().

Parameters:

other – Mapping containing keys and values to merge into this instance.

Raises:

TypeError – If other is not a mutable mapping.

update_recursive(other: MutableMapping[str, Any]) → None

Recursively merges another mapping into this instance.

Parameters:

other (MutableMapping[str, Any]) – Mapping whose entries are merged into this object. If both sides contain nested mappings at a key, values are merged recursively.

values(*, flatten: bool = False) → Iterator[TNestedDictValue[TValue]]

Iterates over values, optionally recursing into nested children.

Parameters:

flatten (bool) – If True, yields values from all descendant NestedDict instances. If False, yields only top-level values.

Returns:

Iterator over values according to flatten.

Return type:

Iterator[Any]

class ConfigMode(node: Modes = Modes.UPDATE, leaf: Modes = Modes.INSERT, delete: bool = False)

Bases: object

Mutable object storing the current configuration mode.

Parameters:

mode – Initial mode controlling whether items can be inserted, updated, or modified at all.

classmethod from_str(value: str)

Create a mode descriptor from a textual mode name.

Parameters:

value – Mode name. Supported values are "insert", "update", and "locked".

Returns:

Newly created mode descriptor.

Return type:

ConfigMode

Raises:

ValueError – If value is not one of the supported mode names.

leaf: Modes = 'insert'

node: Modes = 'update'

class Modes(*values)

Bases: Enum

Access modes controlling how configuration entries can be modified.

INSERT = 'insert'

READONLY = 'readonly'

UPDATE = 'update'

class Parameter(value: str | float | int | bool | None, *, default_value: str | float | int | bool | None | _OMITTED_TYPE = <_OMITTED_TYPE object>, cls: object | _OMITTED_TYPE = <_OMITTED_TYPE object>, description: str = '', hidden: bool = False, extra: dict[str, ~Any] | None=None)

Bases: object

Class representing a single parameter.

Parameters:

• value – The current value of the parameter.

• default_value – The fallback value used when the parameter is reset. If omitted, the current value is used.

• cls – Type used to convert assigned values.

• description – Human-readable explanation of the parameter.

• hidden – Flag indicating whether the parameter should be hidden in summaries.

• extra – Optional metadata stored alongside the parameter.

cls: object | _OMITTED_TYPE = <pde.tools.config._OMITTED_TYPE object>

convert(value: str | float | int | bool | None | _OMITTED_TYPE = <_OMITTED_TYPE object>) → str | float | int | bool | None

Converts a value into the correct type for this parameter. If value is not given, the current value is converted.

Note that this does not make a copy of the values, which could lead to unexpected effects where the default value is changed by an instance.

Parameters:

value – The value to convert

Returns:

The converted value, which is of type self.cls

default_value: str | float | int | bool | None | _OMITTED_TYPE = <pde.tools.config._OMITTED_TYPE object>

reset() → None

Reset parameter to default value.

check_package_version(package_name: str, min_version: str)

Checks whether a package has a sufficient version.

Parameters:

• package_name (str) – The name of the package to check

• min_version (str) – The minimum required version

Returns:

The function only emits warnings and does not return a value.

Return type:

None

environment() → dict[str, Any]

Obtain information about the compute environment.

Returns:

information about the python installation and packages

Return type:

dict

get_ffmpeg_version() → str | None

Read version number of ffmpeg program.

Returns:

Detected version string, or None if ffmpeg is unavailable or the version could not be parsed.

Return type:

str | None

get_package_versions(packages: list[str], *, na_str='not available') → dict[str, str]

Tries to load certain python packages and returns their version.

Parameters:

• packages (list) – The names of all packages

• na_str (str) – Text to return if package is not available

Returns:

Dictionary with version for each package name

Return type:

dict

is_hpc_environment() → bool

Check whether the code is running in a high-performance computing environment.

Returns:

True if running in an HPC environment, False otherwise.

Return type:

bool

packages_from_requirements(requirements_file: Path | str) → list[str]

Read package names from a requirements file.

Parameters:

requirements_file (str or Path) – The file from which everything is read

Returns:

list of package names

parse_version_str(ver_str: str) → list[int]

Helper function converting a version string into a list of integers.

Parameters:

ver_str (str) – The version string to parse

Returns:

List of version numbers as integers

Return type:

list[int]