plesty.lib.utils.settings

Environment-variable loading helper for Plesty device modules.

Credential and connection information belongs in the environment (an .env file); flexible operational tuning is configured separately (e.g. a YAML file). This module provides a small, dependency-free loader that reads environment variables — optionally seeded from a .env file — and exposes typed, validated access.

The loader is intentionally generic: it does not prescribe any variable names. Each device module decides which names and defaults it needs and uses this helper to read them, so the same .env can drive both a standalone server and its tests.

Attributes

T

Classes

EnvSettings

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

Module Contents

plesty.lib.utils.settings.T
class plesty.lib.utils.settings.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