plesty.lib.utils

Utility functions and helpers for Plesty.

Submodules

• plesty.lib.utils.config
• plesty.lib.utils.dll_utils
• plesty.lib.utils.error_utils
• plesty.lib.utils.logger
• plesty.lib.utils.registry
• plesty.lib.utils.settings

Attributes

DEFAULT_CONFIG_FILE

Classes

EnvSettings

Typed accessor over environment variables, optionally seeded from .env.

Functions

load_yaml(→ Any)	Parse a YAML file.
module_config(→ Any)	Return the configuration a module ships, or one section of it.
module_config_path(→ pathlib.Path)	Return the path of the configuration file packaged with module.

Package Contents

plesty.lib.utils.DEFAULT_CONFIG_FILE = 'config.yaml'

plesty.lib.utils.load_yaml(path: str | pathlib.Path, default: Any = _REQUIRED) → Any

Parse a YAML file.

Parameters:

• path (str | pathlib.Path) – The file to read.

• default (Any) – Returned when the file does not exist. Without it a missing file raises — a run configured from a path that is not there is a mistake worth naming, not an empty configuration to proceed with.

Returns:

The parsed document, or default when the file is absent.

Raises:

• FileNotFoundError – If the file is missing and no default was given.

• ValueError – If the file is not valid YAML.

Return type:

Any

plesty.lib.utils.module_config(module: str | types.ModuleType, *keys: str, filename: str = DEFAULT_CONFIG_FILE) → Any

Return the configuration a module ships, or one section of it.

Parameters:

• module (str | types.ModuleType) – The module, or its importable name ("plesty.qd_fss").

• *keys (str) – Path into the document, e.g. "constants", "hwp". Without keys the whole document is returned.

• filename (str) – Configuration file name beside the module’s __init__.

Returns:

The document, or the addressed section.

Raises:

• FileNotFoundError – If the module ships no such configuration file — an absent packaged config is a broken install, not a default.

• KeyError – If a key is missing, naming the full path so the error says which constant the module forgot to declare.

• ValueError – If the file is not valid YAML.

Return type:

Any

plesty.lib.utils.module_config_path(module: str | types.ModuleType, filename: str = DEFAULT_CONFIG_FILE) → pathlib.Path

Return the path of the configuration file packaged with module.

Parameters:

• module (str | types.ModuleType) – The module, or its importable name ("plesty.qd_fss").

• filename (str) – Configuration file name beside the module’s __init__.

Returns:

The path, whether or not the file exists.

Raises:

• ModuleNotFoundError – If module names something that cannot be imported.

• ValueError – If the module has no location on disk.

Return type:

pathlib.Path

class plesty.lib.utils.EnvSettings(values: dict[str, str])

Typed accessor over environment variables, optionally seeded from .env.

Process environment variables take precedence over entries read from the .env file, matching the conventional dotenv behaviour.

Store the resolved variable mapping (see load()).

Parameters:

values (dict[str, str])

_values

classmethod load(dotenv_path: str | os.PathLike[str] | None = '.env', export: bool = True) → EnvSettings

Load variables from dotenv_path (if present) and the process env.

Parameters:

• dotenv_path (str | os.PathLike[str] | None) – Path to a .env file to seed values from, or None to read the process environment only. A missing file is ignored.

• export (bool) – When True (default), values parsed from the .env file are registered into os.environ without overriding existing process variables, matching conventional dotenv behaviour. This makes them visible to os.getenv, child processes, and any code reading the environment directly. Set False for a side-effect-free load that keeps the values local to this instance.

Returns:

An EnvSettings wrapping the merged mapping (process env wins).

Return type:

EnvSettings

static _parse_dotenv(path: str) → dict[str, str]

Parse a minimal KEY=value .env file, ignoring blanks and comments.

Parameters:

path (str)

Return type:

dict[str, str]

get(name: str, default: T | None = None, cast: Callable[[str], T] | None = None, override: T | None = None) → T | str | None

Return variable name following override > env > default.

Parameters:

• name (str) – Environment variable name.

• default (T | None) – Value returned when the variable is absent or empty.

• cast (Callable[[str], T] | None) – Optional converter applied to the raw string (int, float, bool, …). bool accepts 1/true/yes/on case-insensitively.

• override (T | None) – An explicit value (e.g. a parsed CLI argument) that wins over both the environment and default when it is not None. It is assumed to already have the right type and is returned as-is.

Returns:

The override if set, else the converted env value, else default.

Return type:

T | str | None

require(name: str, cast: Callable[[str], T] | None = None, override: T | None = None) → T | str

Return override if set, else variable name; raise if neither is set.

Use for credentials that must never be hard-coded: the value comes from an explicit override (e.g. a CLI argument) or the environment, and a clean KeyError is raised when both are absent.

Parameters:

• name (str) – Environment variable name.

• cast (Callable[[str], T] | None) – Optional converter applied to the raw string.

• override (T | None) – An explicit value that wins over the environment when not None; returned as-is.

Raises:

KeyError – If override is None and the variable is missing or empty.

Return type:

T | str

static _coerce(value: str, cast: Callable[[str], Any]) → Any

Apply cast to value, with sensible boolean parsing.

Parameters:

• value (str)

• cast (Callable[[str], Any])

Return type:

Any

__contains__(name: str) → bool

Return whether name resolved to a non-empty value.

Parameters:

name (str)

Return type:

bool