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.

class Config(items=None, *, mode='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.

copy()

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

property mode: ConfigMode

Current mutable mode descriptor shared across the whole config tree.

replace_recursive(other, delete_extra=False)

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.

• delete_extra (bool)

Return type:

None

to_dict(flatten=False, values=False)

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

class ConfigMode(node=Modes.UPDATE, leaf=Modes.INSERT, delete=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.

• node (Modes)

• leaf (Modes)

• delete (bool)

delete: bool = False

classmethod from_str(value)

Create a mode descriptor from a textual mode name.

Parameters:

value (str) – 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(value)

Bases: Enum

Access modes controlling how configuration entries can be modified.

INSERT = 'insert'

READONLY = 'readonly'

UPDATE = 'update'

class Parameter(value, *, default_value=<_OMITTED_TYPE object>, cls=<_OMITTED_TYPE object>, description='', hidden=False, extra=None)

Bases: object

Class representing a single parameter.

Parameters:

• value (str | float | int | bool | None) – The current value of the parameter.

• default_value (str | float | int | bool | None | _OMITTED_TYPE) – The fallback value used when the parameter is reset. If omitted, the current value is used.

• cls (object | _OMITTED_TYPE) – Type used to convert assigned values.

• description (str) – Human-readable explanation of the parameter.

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

• extra (dict[str, Any] | None) – Optional metadata stored alongside the parameter.

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

convert(value=<_OMITTED_TYPE object>)

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 (str | float | int | bool | None | _OMITTED_TYPE) – The value to convert

Returns:

The converted value, which is of type self.cls

Return type:

str | float | int | bool | None

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

description: str = ''

extra: dict[str, Any] | None = None

hidden: bool = False

reset()

Reset parameter to default value.

Return type:

None

value: str | float | int | bool | None

check_package_version(package_name, min_version)

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()

Obtain information about the compute environment.

Returns:

information about the python installation and packages

Return type:

dict

get_ffmpeg_version()

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, *, na_str='not available')

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()

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)

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

Return type:

list[str]

parse_version_str(ver_str)

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]