conclude 1.0.0__py3-none-any.whl

conclude/casters.py

@@ -0,0 +1,262 @@
+"""Reusable casters for the common shapes a CLI config setting takes.
+
+Every caster here follows the same convention the rest of conclude
+relies on: given "no opinion" input (``None``, or ``""`` for the
+string-ish ones), it returns ``None`` rather than raising, so a layer
+that didn't mention a setting merges away cleanly (see
+:func:`conclude.merge.resolve`). A caster is applied uniformly to every
+layer -- CLI string, env var string, TOML-native value -- so e.g. the
+env var string ``"true"`` and a TOML boolean ``true`` normalize to the
+exact same Python value before the merge happens.
+
+These cover the common cases; an application with a setting that needs
+its own bespoke casting (a "STYLE" mini-language, say) just writes its
+own caster function -- :func:`conclude.merge.resolve` takes any
+``dict[str, Callable]``, not specifically these.
+"""
+
+import re
+from typing import Any
+
+_TRUE_STRINGS = frozenset({"1", "true", "yes", "on", "y"})
+_FALSE_STRINGS = frozenset({"0", "false", "no", "off", "n"})
+
+# Matches a bare integer literal with a redundant all-zero decimal
+# tail ("5.0", "5.", "-3.00") -- see _try_parse_exact_int below.
+_TRAILING_ZERO_DECIMAL_RE = re.compile(r"^([+-]?\d+)\.0*$")
+
+# The exact, narrow set of backslash escapes cast_escaped_str (and
+# conclude.env.load_dotenv's double-quoted values) decode -- see
+# decode_backslash_escapes below for why this has to be a manual,
+# character-by-character scan rather than reusing Python's own
+# "unicode_escape" codec.
+_BACKSLASH_ESCAPES = {
+    "n": "\n",
+    "t": "\t",
+    "r": "\r",
+    "\\": "\\",
+    '"': '"',
+}
+
+
+def decode_backslash_escapes(text: str) -> str:
+    """Decode just ``\\n``/``\\t``/``\\r``/``\\\\``/``\\"`` in ``text``,
+    leaving every other character -- including every non-ASCII one --
+    completely untouched, and leaving any *other* backslash sequence
+    (``\\x41``, ``\\u00e9``, an unrecognized ``\\q``, a trailing lone
+    ``\\``) exactly as written rather than guessing at it.
+
+    This is deliberately not ``text.encode("utf-8").decode("unicode_escape")``,
+    which looks like it does the same thing but doesn't: encoding to
+    UTF-8 first turns any non-ASCII character into multiple bytes, and
+    "unicode_escape" then decodes those bytes one at a time as if each
+    were its own Latin-1 character -- so e.g. ``"café"`` silently comes
+    back as ``"café"``, and anything outside Latin-1 (CJK text, emoji,
+    ...) comes back as multi-character garbage. A plain scan for
+    exactly the handful of escapes this is meant to support has no such
+    failure mode, at the cost of not supporting the rest of
+    "unicode_escape"'s much larger grammar (octal/hex/named escapes) --
+    which was never the point here (see :func:`cast_escaped_str`).
+    """
+    result: list[str] = []
+    i = 0
+    length = len(text)
+    while i < length:
+        ch = text[i]
+        if ch == "\\" and i + 1 < length and text[i + 1] in _BACKSLASH_ESCAPES:
+            result.append(_BACKSLASH_ESCAPES[text[i + 1]])
+            i += 2
+        else:
+            result.append(ch)
+            i += 1
+    return "".join(result)
+
+
+def cast_bool(value: Any) -> bool:
+    """Truthy/falsy strings/numbers/bools -> bool.
+
+    Recognizes ``1``/``true``/``yes``/``on``/``y`` (case-insensitive) as
+    true, ``0``/``false``/``no``/``off``/``n`` as false, and an empty
+    string as false (the "not provided, so falsy" case a bool setting's
+    absence normally means). A Python ``bool`` is passed through
+    unchanged, so a TOML-native ``true``/``false`` is unaffected by this
+    string-oriented check.
+
+    Anything else raises ``ValueError`` rather than silently guessing --
+    a typo like ``"tru"`` should be caught, not quietly treated as
+    false just because it isn't in the recognized true set.
+    """
+    if isinstance(value, bool):
+        return value
+    text = str(value).strip().lower()
+    if text == "":
+        return False
+    if text in _TRUE_STRINGS:
+        return True
+    if text in _FALSE_STRINGS:
+        return False
+    raise ValueError(f"expected a boolean (true/false/yes/no/on/off/1/0/y/n), got {value!r}")
+
+
+def _try_parse_exact_int(text: str) -> int | None:
+    """Parse ``text`` as an exact Python ``int`` if it's a clean
+    integer literal -- optionally with a redundant all-zero decimal
+    tail, e.g. ``"5"`` or ``"5.00"`` -- without ever routing it
+    through ``float()``. Returns ``None`` for anything else (a
+    genuinely fractional value like ``"1.9"``, scientific notation,
+    ``"inf"``/``"nan"``, or non-numeric text) -- callers fall back to
+    ``float()`` themselves for those, accepting its limits since
+    there's no way around them for input that isn't a bare integer to
+    begin with.
+
+    The reason this exists at all: a Python ``float`` only has 53 bits
+    of exact integer precision. Routing an already-exact integer (or a
+    numeral string representing one) through ``float()`` first -- the
+    obvious way to also accept ``"5.0"``-style input -- can silently
+    corrupt it once it's larger than that: ``int(float(9007199254740993))``
+    quietly becomes ``9007199254740992``, one off from the real value,
+    with no error raised anywhere. Handling the "already an exact
+    integer, possibly with a pointless trailing ``.0``" shape directly,
+    before ``float()`` ever enters the picture, avoids that entirely.
+    """
+    try:
+        return int(text)
+    except ValueError:
+        pass
+    match = _TRAILING_ZERO_DECIMAL_RE.match(text)
+    return int(match.group(1)) if match else None
+
+
+def cast_int_or_none(value: Any, *, label: str = "a number") -> int | float | None:
+    """A whole or fractional number, or ``None``.
+
+    Returns an ``int`` when the value is a whole number (``"5"``,
+    ``5.0``) and a ``float`` otherwise (``"1.5"``), which is usually
+    what you want for a "seconds" or similar real-valued setting where
+    whole numbers should print/compare cleanly but fractions are still
+    allowed. Raises ``ValueError`` (message customizable via ``label``,
+    e.g. ``"a number of seconds"``) on anything that isn't a number at
+    all.
+
+    An already-``int`` value, or a numeral string like ``"5"`` or
+    ``"9007199254740993"``, is parsed as an exact integer directly --
+    see :func:`_try_parse_exact_int` -- rather than always routing
+    through ``float()`` first, which would silently corrupt a large
+    enough integer.
+    """
+    if value in (None, ""):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value) if value.is_integer() else value
+    exact = _try_parse_exact_int(str(value).strip())
+    if exact is not None:
+        return exact
+    try:
+        as_float = float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"expected {label}, got {value!r}") from exc
+    return int(as_float) if as_float.is_integer() else as_float
+
+
+def cast_positive_int(value: Any, *, label: str = "a positive integer") -> int | None:
+    """A whole number >= 1, or ``None``.
+
+    Raises ``ValueError`` (message customizable via ``label``) on
+    non-numeric input, on a number below 1, and -- unlike a naive
+    ``int(float(value))`` -- on a value that parses as a number but
+    isn't actually a whole one (``1.9``, which ``int()`` would
+    silently truncate to ``1`` rather than reject) or isn't finite
+    (``"inf"``/``"nan"``, which ``int()`` raises ``OverflowError``/
+    another ``ValueError`` internally -- both are normalized to the
+    one documented ``ValueError`` here, same as everything else this
+    rejects).
+
+    Like :func:`cast_int_or_none`, an already-``int`` value or a clean
+    integer-literal string never goes through ``float()`` at all, so a
+    large value (beyond a float's 53 bits of exact integer precision)
+    is never at risk of silently losing precision along the way.
+    """
+    if value in (None, ""):
+        return None
+    if isinstance(value, int):
+        as_int = value
+    elif isinstance(value, float):
+        if not value.is_integer():
+            raise ValueError(f"expected {label} (a whole number), got {value!r}")
+        as_int = int(value)
+    else:
+        exact = _try_parse_exact_int(str(value).strip())
+        if exact is not None:
+            as_int = exact
+        else:
+            try:
+                as_float = float(value)
+            except (TypeError, ValueError) as exc:
+                raise ValueError(f"expected {label}, got {value!r}") from exc
+            if not as_float.is_integer():
+                raise ValueError(f"expected {label} (a whole number), got {value!r}")
+            as_int = int(as_float)
+    if as_int < 1:
+        raise ValueError(f"{label} must be >= 1, got {value!r}")
+    return as_int
+
+
+def cast_float_or_none(value: Any) -> float | None:
+    """A floating-point number, or ``None``. Raises ``ValueError`` on
+    anything that isn't numeric at all. Prefer :func:`cast_int_or_none`
+    for a setting that should print as a whole number when the value
+    given happens to be one (e.g. "5" rather than "5.0") -- this one
+    always returns a ``float``.
+    """
+    if value in (None, ""):
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"expected a number, got {value!r}") from exc
+
+
+def cast_str_or_none(value: Any) -> str | None:
+    """A string, or ``None`` for "not provided" (``None`` or ``""``).
+
+    Use this for settings where an empty string never means anything
+    different from "unset" -- e.g. a filename or column name. For a
+    setting where an explicit empty string IS a meaningful, distinct
+    choice, use :func:`cast_escaped_str` instead.
+    """
+    if value in (None, ""):
+        return None
+    return str(value)
+
+
+def cast_comma_list(value: Any) -> list[str] | None:
+    """Comma-separated string (or an already-a-list TOML value) ->
+    ``list[str]``, or ``None`` for "not provided".
+
+    Each item is stripped of surrounding whitespace; empty items
+    (e.g. from a trailing comma) are dropped.
+    """
+    if value in (None, ""):
+        return None
+    if isinstance(value, list):
+        return [str(v).strip() for v in value if str(v).strip()]
+    return [part.strip() for part in str(value).split(",") if part.strip()]
+
+
+def cast_escaped_str(value: Any) -> str | None:
+    """Like :func:`cast_str_or_none`, but an explicit empty string is a
+    real choice (e.g. "no separator at all"), not "not provided" -- so
+    unlike the other string casters, ``""`` is preserved rather than
+    folded into ``None``. Only an actual ``None`` means "not provided".
+
+    Also decodes backslash escapes -- ``\\n``/``\\t``/``\\r``/``\\\\``/``\\"``
+    -- into their real characters, so a CLI value like
+    ``--separator='\\n\\n'`` behaves the way a user would expect; see
+    :func:`decode_backslash_escapes` for exactly what is and isn't
+    touched (non-ASCII text is always left alone).
+    """
+    if value is None:
+        return None
+    return decode_backslash_escapes(str(value))

conclude/developer.py

@@ -0,0 +1,215 @@
+"""Layer: the developer config file -- a private, project-local TOML
+file that sits *above* the environment in the precedence chain::
+
+    defaults < system < user < project < env < developer < CLI
+
+The motivation is a local ``DATABASE_URL`` (or any other setting a
+developer wants pinned while working on one project): environment
+variables are process-wide and can leak between projects through a
+long-lived shell, while a file whose location the *project* decides is
+scoped to exactly the project it belongs to -- so it wins over ambient
+environment state. Use the CLI for a one-off override.
+
+Where the file lives is declared in the project's ``pyproject.toml``::
+
+    [tool.conclude.developer]
+    config = ".conclude.local.toml"
+
+(relative to the directory containing that ``pyproject.toml``). The
+file's format follows its name: a ``.toml`` file uses the same ``[app]``
+table layout as every other config file, and anything else -- say
+``.env.local`` -- is dotenv, keyed by the app's environment variable
+names, so the one private file can also serve docker compose, direnv or
+an IDE run configuration. It is deliberately hard to activate by accident, because a file
+that beats the environment must never come from somewhere it shouldn't
+-- a deployed image, a fresh clone, a CI checkout. It only applies when
+*all* of these hold, and otherwise it is skipped quietly -- no error, no
+warning, though :meth:`conclude.App.describe_sources` always says which
+case it is:
+
+1. the app opted in (``App(pyproject_path=AUTO)``),
+2. ``pyproject.toml`` sets ``tool.conclude.developer.config``,
+3. the ``<APP>_DEVELOPER_CONFIG`` kill switch is not set to ``off``,
+4. the file exists,
+5. it is inside a git working tree, and
+6. it is covered by that tree's ignore rules (``.gitignore`` files and
+   ``.git/info/exclude``) -- i.e. private by construction. Checks 3-6
+   are the shared :mod:`conclude.guard`, which needs the optional
+   ``pathspec`` package (``pip install 'conclude[gitignore]'``).
+
+Two things are deliberately *not* quiet, because they are setup errors
+rather than ordinary states, and hiding them would leave a developer
+wondering why their file has no effect: a missing ``pathspec`` when the
+ignore check is actually needed raises ``ImportError`` (the kill switch,
+checked first, avoids it), and an active file that isn't valid TOML
+raises :class:`conclude.ConfigFileError`. :func:`developer_status` and
+``describe_sources()`` never raise; they just report.
+
+The ignore check's caveats (the global ``core.excludesFile`` isn't
+consulted; pattern matching, not git's index) are in
+:mod:`conclude.guard`.
+"""
+
+import enum
+import tomllib
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from conclude.env import load_env
+from conclude.files import ConfigFileError, load_config_file
+from conclude.guard import check_guard
+
+
+class DeveloperState(enum.Enum):
+    """Where the developer config layer stands -- the four cases
+    :meth:`conclude.App.describe_sources` tells apart.
+    """
+
+    NOT_OPTED_IN = "not opted in"
+    """The app never asked for a developer layer at all."""
+
+    NOT_CONFIGURED = "not configured"
+    """Opted in, but the project's ``pyproject.toml`` names no file."""
+
+    INACTIVE = "configured, inactive"
+    """A file is named, but a safety condition isn't met (see
+    :attr:`DeveloperStatus.reason`); the layer contributes nothing."""
+
+    ACTIVE = "configured, active"
+    """The file is named, exists, and is gitignored; it is read."""
+
+
+@dataclass(frozen=True)
+class DeveloperStatus:
+    """The state of the developer layer, and -- for any state but
+    ``NOT_OPTED_IN`` -- why. Never raised or logged: it's information
+    for :meth:`conclude.App.describe_sources` and for an app's own
+    diagnostics (e.g. a ``--diagnose`` flag).
+    """
+
+    state: DeveloperState
+    path: Path | None = None
+    """The developer file's path, once ``pyproject.toml`` names one."""
+    reason: str | None = None
+    """Why ``NOT_CONFIGURED``/``INACTIVE``, in one short phrase."""
+    setup_error: bool = False
+    """``True`` only for a setup error rather than a normal state -- the
+    ``pathspec`` package is missing, so the ignore check can't run.
+    :func:`load_developer_config` raises for it instead of quietly
+    skipping the file, since silently ignoring a *tooling* problem
+    would leave a developer wondering why their file has no effect."""
+
+    @property
+    def active(self) -> bool:
+        return self.state is DeveloperState.ACTIVE
+
+    @property
+    def format(self) -> Literal["toml", "dotenv"] | None:
+        """How the file is parsed, decided by its name alone: ``"toml"``
+        for a name ending in ``.toml`` (any case), ``"dotenv"`` for
+        anything else (``.env.local``, ``.env``, no extension at all),
+        and ``None`` until ``pyproject.toml`` names a file.
+        """
+        if self.path is None:
+            return None
+        return "toml" if self.path.name.lower().endswith(".toml") else "dotenv"
+
+    def __str__(self) -> str:
+        if self.state is DeveloperState.NOT_OPTED_IN:
+            return str(self.state.value)
+        if self.state is DeveloperState.NOT_CONFIGURED:
+            return f"{self.state.value} ({self.reason})" if self.reason else str(self.state.value)
+        detail = f" ({self.reason})" if self.state is DeveloperState.INACTIVE else ""
+        return f"{self.path} -- {self.state.value}{detail}"
+
+
+def developer_status(
+    pyproject_path: Path | None,
+    *,
+    kill_switch_var: str | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> DeveloperStatus:
+    """Work out the state of the developer layer. Never raises.
+
+    ``pyproject_path`` is the ``pyproject.toml`` to read
+    ``tool.conclude.developer.config`` from, or ``None`` if the app
+    didn't opt in. ``kill_switch_var`` names an environment variable
+    that, set to ``off``/``0``/``false``/``no``, deactivates a
+    configured file (read from ``environ``, default ``os.environ``,
+    and only ever from the real environment -- it is a control knob, not
+    a setting, so no ``.env`` file or config layer can carry it).
+    """
+    if pyproject_path is None:
+        return DeveloperStatus(DeveloperState.NOT_OPTED_IN)
+
+    configured = _read_configured_path(pyproject_path)
+    if isinstance(configured, str):
+        return DeveloperStatus(DeveloperState.NOT_CONFIGURED, reason=configured)
+    path = configured
+
+    result = check_guard(path, kill_switch_var=kill_switch_var, environ=environ)
+    state = DeveloperState.ACTIVE if result.active else DeveloperState.INACTIVE
+    return DeveloperStatus(state, path, result.reason, setup_error=result.setup_error)
+
+
+def load_developer_config(
+    status: DeveloperStatus,
+    defaults: Mapping[str, Any],
+    table_path: list[str],
+    env_vars: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    """The developer layer's settings from the file ``status`` says is
+    active, or ``{}`` for any state but ``ACTIVE``.
+
+    A ``.toml`` file is read like any config file: the selected TOML
+    table(s), only keys in ``defaults`` (see
+    :func:`conclude.load_config_file`), and an active file that isn't
+    valid TOML raises :class:`conclude.ConfigFileError` (a developer
+    editing their own file should be told). Any other file is dotenv
+    (see :func:`conclude.load_dotenv`): ``env_vars`` -- your
+    ``{setting: ENV_VAR_NAME}`` mapping, required for this format --
+    says which variables in it are settings, and ``table_path`` is
+    ignored because dotenv has no tables; the values are raw strings,
+    cast later like any other layer. Either way, ``ImportError`` is
+    raised if ``pathspec`` is missing (see
+    :attr:`DeveloperStatus.setup_error`).
+    """
+    if status.setup_error:
+        raise ImportError(f"developer config file {status.path}: {status.reason}")
+    if not status.active:
+        return {}
+    if status.format == "dotenv":
+        if env_vars is None:
+            raise ValueError(
+                f"developer config file {status.path} is dotenv (only .toml files are "
+                "TOML), so reading it needs env_vars= to map its variables to settings"
+            )
+        return load_env(env_vars, {}, dotenv_path=status.path)
+    try:
+        return load_config_file(status.path, defaults, table_path)
+    except ConfigFileError as exc:
+        raise ConfigFileError(f"developer config file {exc}") from exc
+
+
+def _read_configured_path(pyproject_path: Path) -> Path | str:
+    """The developer file path named by ``pyproject_path`` (relative
+    to its directory), or a short reason string if none is.
+    """
+    try:
+        data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return f"no {pyproject_path}"
+    except (OSError, UnicodeDecodeError, tomllib.TOMLDecodeError):
+        return f"{pyproject_path} is not readable TOML"
+
+    node: Any = data
+    for part in ("tool", "conclude", "developer"):
+        node = node.get(part) if isinstance(node, dict) else None
+    value = node.get("config") if isinstance(node, dict) else None
+    if value is None:
+        return f"no tool.conclude.developer.config in {pyproject_path}"
+    if not isinstance(value, str) or not value.strip():
+        return "tool.conclude.developer.config must be a non-empty string"
+    return pyproject_path.parent / value.strip()

conclude/env.py

@@ -0,0 +1,176 @@
+"""Layer: environment variables -- the real process environment, with
+an optional ``.env`` file as a fallback for anything not actually set
+there.
+
+By default a ``.env`` file is read as-is, so one can be committed with
+non-secret local defaults. When it holds private values instead, pass
+``require_gitignored=True`` (``App(dotenv_require_gitignored=True)``):
+the file is then read only if it passes the same gitignore guard as the
+developer config file -- exists, inside a git working tree, and ignored
+by it (see :mod:`conclude.guard`) -- and is otherwise skipped quietly,
+with :func:`dotenv_status` saying why. A missing ``pathspec`` (the
+optional ``conclude[gitignore]`` extra the check needs) is the one
+loud case: it raises ``ImportError``.
+"""
+
+import enum
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from conclude.casters import decode_backslash_escapes
+from conclude.guard import check_guard
+
+
+class DotenvState(enum.Enum):
+    """Where the ``.env`` fallback stands."""
+
+    DISABLED = "disabled"
+    """No ``.env`` path at all (the default)."""
+
+    ACTIVE = "active"
+    """The file will be read (if it exists) -- and, when a gitignore
+    guard was requested, it passed."""
+
+    INACTIVE = "inactive"
+    """A guard was requested and the file failed it (see
+    :attr:`DotenvStatus.reason`); nothing is read from it."""
+
+
+@dataclass(frozen=True)
+class DotenvStatus:
+    """The state of the ``.env`` fallback, and why. Never raised or
+    logged: information for :meth:`conclude.App.describe_sources` and
+    an app's own diagnostics.
+    """
+
+    state: DotenvState
+    path: Path | None = None
+    reason: str | None = None
+    """Why ``INACTIVE``, in one short phrase."""
+    guarded: bool = False
+    """Whether a gitignore guard was requested."""
+    setup_error: bool = False
+    """``True`` only when the guard needed ``pathspec`` and it is
+    missing: :func:`load_env` raises ``ImportError`` for it instead of
+    quietly skipping the file."""
+
+    @property
+    def active(self) -> bool:
+        return self.state is DotenvState.ACTIVE
+
+    def __str__(self) -> str:
+        if self.state is DotenvState.DISABLED:
+            return "disabled"
+        if self.state is DotenvState.ACTIVE:
+            return f"{self.path} -- active (gitignored)" if self.guarded else str(self.path)
+        return f"{self.path} -- inactive ({self.reason})"
+
+
+def dotenv_status(dotenv_path: Path | None, *, require_gitignored: bool = False) -> DotenvStatus:
+    """Work out the state of the ``.env`` fallback. Never raises.
+
+    ``dotenv_path=None`` is ``DISABLED``. Otherwise, without
+    ``require_gitignored`` the file is ``ACTIVE`` whether or not it
+    exists yet (exactly the pre-guard behavior); with it, the file must
+    also pass :func:`conclude.guard.check_guard`.
+    """
+    if dotenv_path is None:
+        return DotenvStatus(DotenvState.DISABLED)
+    if not require_gitignored:
+        return DotenvStatus(DotenvState.ACTIVE, dotenv_path)
+    result = check_guard(dotenv_path, escape_hint="or stop requiring it to be gitignored")
+    state = DotenvState.ACTIVE if result.active else DotenvState.INACTIVE
+    return DotenvStatus(
+        state, dotenv_path, result.reason, guarded=True, setup_error=result.setup_error
+    )
+
+
+def load_dotenv(path: Path) -> dict[str, str]:
+    """Parse a ``.env``-style file into a plain ``{NAME: value}`` dict
+    of strings, or ``{}`` if ``path`` doesn't exist.
+
+    Supported syntax, one variable per line: ``NAME=value``, an
+    optional leading ``export `` (ignored), blank lines and lines
+    starting with ``#`` skipped, and a value optionally wrapped in
+    matching quotes -- single-quoted is taken completely literally;
+    double-quoted additionally decodes backslash escapes (``\\n``,
+    ``\\t``, ``\\r``, ``\\\\``, ``\\"`` -- see
+    :func:`conclude.casters.decode_backslash_escapes`, which non-ASCII
+    characters pass through unchanged), matching common ``.env``
+    convention.
+
+    Deliberately not supported: multi-line values, inline comments
+    after a value on the same line, and ``${OTHER_VAR}``-style
+    interpolation -- keeping the parser small and its behavior easy to
+    predict beats covering every corner of every ``.env`` dialect in
+    the wild. Write a fuller ``.env`` parser yourself and pass its
+    result as ``environ``/merge it in ahead of time if you need one of
+    these.
+    """
+    if not path.is_file():
+        return {}
+    result: dict[str, str] = {}
+    for raw_line in path.read_text().splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        line = line.removeprefix("export ").strip()
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            quote, value = value[0], value[1:-1]
+            if quote == '"':
+                value = decode_backslash_escapes(value)
+        result[key] = value
+    return result
+
+
+def load_env(
+    env_vars: Mapping[str, str],
+    environ: Mapping[str, str] | None = None,
+    *,
+    dotenv_path: Path | None = None,
+    require_gitignored: bool = False,
+) -> dict[str, Any]:
+    """Read the environment-variable layer.
+
+    ``env_vars`` maps your setting name -> the environment variable
+    name that carries it (e.g. ``{"filename": "FLASHCARDS_FILENAME"}``).
+    Only variables actually present end up in the result, same "no
+    opinion" convention every other layer follows.
+
+    ``environ`` (default: ``os.environ``) is always checked first and
+    always wins: pass ``dotenv_path`` to also fall back to a ``.env``
+    file (see :func:`load_dotenv`) for any variable ``environ`` itself
+    doesn't already set -- a real, actually-exported environment
+    variable overriding a stale ``.env`` file is the conventional
+    behavior every dotenv-style tool follows, and it's what lets a
+    ``.env`` file be safely committed for local development without
+    silently overriding whatever a deployment environment injects for
+    real.
+
+    With ``require_gitignored=True`` the ``.env`` file is only used if
+    it passes the gitignore guard (see :func:`dotenv_status`), and a
+    missing ``pathspec`` raises ``ImportError`` rather than quietly
+    dropping the file.
+    """
+    environ = os.environ if environ is None else environ
+    merged: dict[str, str] = {}
+    if dotenv_path is not None:
+        status = dotenv_status(dotenv_path, require_gitignored=require_gitignored)
+        if status.setup_error:
+            raise ImportError(f".env file {status.path}: {status.reason}")
+        if status.active:
+            merged = load_dotenv(dotenv_path)
+    merged.update(environ)
+    result: dict[str, Any] = {}
+    for key, var_name in env_vars.items():
+        if var_name in merged:
+            result[key] = merged[var_name]
+    return result