plesty.lib.utils ================ .. py:module:: plesty.lib.utils .. autoapi-nested-parse:: Utility functions and helpers for Plesty. Submodules ---------- .. toctree:: :maxdepth: 1 /reference/plesty/lib/utils/config/index /reference/plesty/lib/utils/dll_utils/index /reference/plesty/lib/utils/error_utils/index /reference/plesty/lib/utils/logger/index /reference/plesty/lib/utils/registry/index /reference/plesty/lib/utils/settings/index Attributes ---------- .. autoapisummary:: plesty.lib.utils.DEFAULT_CONFIG_FILE Classes ------- .. autoapisummary:: plesty.lib.utils.EnvSettings Functions --------- .. autoapisummary:: plesty.lib.utils.load_yaml plesty.lib.utils.module_config plesty.lib.utils.module_config_path Package Contents ---------------- .. py:data:: DEFAULT_CONFIG_FILE :value: 'config.yaml' .. py:function:: load_yaml(path: str | pathlib.Path, default: Any = _REQUIRED) -> Any Parse a YAML file. :param path: The file to read. :param default: 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. :raises ValueError: If the file is not valid YAML. .. py:function:: 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. :param module: The module, or its importable name (``"plesty.qd_fss"``). :param \*keys: Path into the document, e.g. ``"constants", "hwp"``. Without keys the whole document is returned. :param filename: 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. :raises KeyError: If a key is missing, naming the full path so the error says which constant the module forgot to declare. :raises ValueError: If the file is not valid YAML. .. py:function:: module_config_path(module: str | types.ModuleType, filename: str = DEFAULT_CONFIG_FILE) -> pathlib.Path Return the path of the configuration file packaged with *module*. :param module: The module, or its importable name (``"plesty.qd_fss"``). :param filename: 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. :raises ValueError: If the module has no location on disk. .. py:class:: 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 :meth:`load`). .. py:attribute:: _values .. py:method:: load(dotenv_path: str | os.PathLike[str] | None = '.env', export: bool = True) -> EnvSettings :classmethod: Load variables from ``dotenv_path`` (if present) and the process env. :param dotenv_path: Path to a ``.env`` file to seed values from, or ``None`` to read the process environment only. A missing file is ignored. :param export: 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 :class:`EnvSettings` wrapping the merged mapping (process env wins). .. py:method:: _parse_dotenv(path: str) -> dict[str, str] :staticmethod: Parse a minimal ``KEY=value`` ``.env`` file, ignoring blanks and comments. .. py:method:: 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``. :param name: Environment variable name. :param default: Value returned when the variable is absent or empty. :param cast: Optional converter applied to the raw string (``int``, ``float``, ``bool``, …). ``bool`` accepts ``1/true/yes/on`` case-insensitively. :param override: 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``. .. py:method:: 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. :param name: Environment variable name. :param cast: Optional converter applied to the raw string. :param override: 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. .. py:method:: _coerce(value: str, cast: Callable[[str], Any]) -> Any :staticmethod: Apply ``cast`` to ``value``, with sensible boolean parsing. .. py:method:: __contains__(name: str) -> bool Return whether ``name`` resolved to a non-empty value.