utilities

Note

See the Glossary for the meaning of the acronyms used in this guide.

contexts

plugin_dirs(dirs: Iterable[str] = ('.',)) → Iterator[None]

redirect_print(new_target: Optional[IO] = None) → Iterator[None]

sys_path_dirs(dirs: Iterable[str] = ('.',)) → Iterator[None]

env_vars(env_updates: dict[str, str]) → Iterator[None]

Create a context for temporarily updating environment variables.

Parameters

env_updates – A dictionary that maps the environment variables (keys) to a new value. Both the keys and values must be strings.

Examples

The example below shows how to use env_vars to set/update the value of the environment variable __A within a context block. First, import the os module and check the current value of __A (we provide a a default value because this environment variable should not exist).

>>> import os
>>> print(os.getenv("__A", "default value of __A"))
default value of __A

Next, set up a with statement using env_vars to set a new value for __A confirm that the update worked.

>>> with env_vars({"__A": "new value of __A"}):
...     print(os.getenv("__A", "default value of A"))
new value of __A

Finally, confirm that __A has been restored to its default value after exiting the with statement.

>>> print(os.getenv("__A", "default value of __A"))
default value of __A

Note

This code is adapted from https://stackoverflow.com/a/34333710.

decorators

require_package(name: str, exc_message: typing.Optional[str] = None, exc_type: typing.Type[dioptra.sdk.exceptions.base.BaseOptionalDependencyError] = <class 'dioptra.sdk.exceptions.base.BaseOptionalDependencyError'>) → Callable[[dioptra.sdk.utilities.decorators._require_package.T], dioptra.sdk.utilities.decorators._require_package.T]

logging

attach_stdout_stream_handler(as_json: bool, logger: Optional[logging.Logger] = None) → None

clear_logger_handlers(logger: Optional[logging.Logger]) → None

configure_structlog() → None

set_logging_level(level: str, logger: Optional[logging.Logger] = None) → None

class StderrLogStream(as_json: bool)

Bases: dioptra.sdk.utilities.logging.log_stream.LogStream

close()

flush()

class StdoutLogStream(as_json: bool)

Bases: dioptra.sdk.utilities.logging.log_stream.LogStream

close()

flush()

paths

set_path_ext(filepath: Union[str, pathlib.Path], ext: str) → pathlib.Path

clear_directory(dir_: Union[str, pathlib.Path])

Remove all subdirectories and files from the given directory.

Parameters

dir – A string or Path object referring to a directory

set_cwd(temp_cwd: Union[str, pathlib.Path]) → Iterator[None]

A convenient way to temporarily set the current working directory to a particular directory, while executing a particular block of code. Just place the code into a with-statement which uses this function as a contextmanager.

Parameters

temp_cwd – The directory to temporarily set as current