Source code for osprey_connectors.dotenv

"""The deployment's env chain: which files it is, and how they are read.

A tiny dependency-free parser (no ``python-dotenv`` import) and the chain it
reads — ``.env.shared`` then ``.env`` at the repo root, later file wins. Every
OSPREY process loads that chain on start-up
(:func:`osprey_connectors.config.load_project_dotenv`), so the reading half
lives here. Writing the files is the framework's deployment layer's
(``osprey.deployment.dotenv``).
"""

from __future__ import annotations

from pathlib import Path

__all__ = [
    "ENV_CHAIN_APPLIED_ENV",
    "ENV_CHAIN_FILENAMES",
    "ENV_LOCAL_FILENAME",
    "ENV_SHARED_FILENAME",
    "chain_files",
    "merge_chain",
    "parse_dotenv_file",
    "parse_dotenv_text",
]


[docs] def parse_dotenv_file(path: Path) -> dict[str, str]: """Parse a ``.env`` file into a dict of environment variables. Handles ``KEY=VALUE`` lines, ``#`` comments, blank lines, an optional ``export`` prefix, and quoted values (single or double quotes stripped from the value boundaries). """ return parse_dotenv_text(path.read_text(encoding="utf-8"))
[docs] def parse_dotenv_text(text: str) -> dict[str, str]: """Parse ``.env`` *text* into a dict of environment variables. The in-memory half of :func:`parse_dotenv_file`, for callers holding the file's contents already (a locked read-modify-write, a rendered template). """ env: dict[str, str] = {} for line in text.splitlines(): line = line.strip() if not line or line.startswith("#"): continue # Skip lines without = if "=" not in line: continue # Skip `export` prefix (common in .env files) line = line.removeprefix("export ") key, _, value = line.partition("=") key = key.strip() if not key: continue value = value.strip() # Strip matching surrounding quotes if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"): value = value[1:-1] env[key] = value return env
#: The committed, non-secret defaults half of the env chain, at the repo root. ENV_SHARED_FILENAME = ".env.shared" #: The host-local half of the env chain, at the repo root: the deployment's one #: secret store, hand-edited and written back to by ``osprey up``. ENV_LOCAL_FILENAME = ".env" #: The env chain in ASCENDING precedence order: every mechanism that delivers #: these files must end up with ``.env`` winning over ``.env.shared`` on a key #: both set. Spelled here, once, because the mechanics of "later wins" differ #: per delivery path — a compose ``env_file:`` list is read in this order, an #: ``override=True`` loader loads in this order, and an ``override=False`` #: (first-loaded-wins) loader must load it REVERSED to reach the same answer. #: Membership is fixed: a chain member is a file the deployment knows by name, #: not a directory scan. ENV_CHAIN_FILENAMES: tuple[str, ...] = (ENV_SHARED_FILENAME, ENV_LOCAL_FILENAME) #: Set by a parent that already applied the env chain and hands its child a #: resolved environment it chose. A process that carries it does not load the #: chain again: reloading would put back what the parent withheld. ENV_CHAIN_APPLIED_ENV = "OSPREY_ENV_CHAIN_APPLIED"
[docs] def chain_files(repo_root: Path) -> list[Path]: """The env-chain files that exist under ``repo_root``, ascending precedence. Returns the existing members of :data:`ENV_CHAIN_FILENAMES` in that order — ``.env.shared`` before ``.env`` — so a caller can hand the list straight to whatever consumes it (a compose ``env_file:`` list, an ``override=True`` loader, a ``$``-scan) and get local-over-shared precedence from the order alone. Missing members are skipped rather than reported: a project with neither file, only defaults, or only local settings are all valid shapes, and the list is empty/short accordingly. :param repo_root: Directory the chain lives in (the deployment repo root). :return: Existing chain files, lowest precedence first. """ root = Path(repo_root) return [path for path in (root / name for name in ENV_CHAIN_FILENAMES) if path.is_file()]
[docs] def merge_chain(repo_root: Path) -> dict[str, str]: """Parse the env chain under ``repo_root`` into one dict; later file wins. The chain is read in :func:`chain_files` order, each file's entries laid over the previous file's, so a key set in both ``.env.shared`` and ``.env`` ends up with the ``.env`` value — the single in-process answer to "what does this deployment's env chain say?". Key order in the result is first-seen: the shared defaults in file order, then keys only the local file introduces. A key both files set keeps its shared-file position and takes the local value, so the merged view reads like the defaults file with the local overrides applied in place. Nothing is written to :data:`os.environ` here — the caller decides whether these values overlay a subprocess environment, a compose file, or nothing at all. :param repo_root: Directory the chain lives in (the deployment repo root). :return: Merged ``KEY=VALUE`` pairs; empty when no chain file exists. """ merged: dict[str, str] = {} for path in chain_files(repo_root): merged.update(parse_dotenv_file(path)) return merged