plesty.lib.utils.settings
=========================

.. py:module:: plesty.lib.utils.settings

.. autoapi-nested-parse::

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

.. autoapisummary::

   plesty.lib.utils.settings.T


Classes
-------

.. autoapisummary::

   plesty.lib.utils.settings.EnvSettings


Module Contents
---------------

.. py:data:: T

.. 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.