conclude 1.0.0__py3-none-any.whl

conclude/files.py

@@ -0,0 +1,247 @@
+"""Layer: config file(s).
+
+Supports the pattern of a project-local file (in the current working
+directory) overriding a user-global one (which in turn overrides an
+optional, opt-in system-wide one), any number of sibling
+"auxiliary" files picked up automatically, and a two-level
+``[PARENT]``/``[PARENT.CHILD]`` table selection within each file --
+plus resolving which table a bare positional "shorthand" argument (a
+deck name, a profile name, whatever your app calls it) maps to, by
+peeking at the config files themselves.
+
+None of this cares what your app is called or what its settings are:
+callers pass in the paths, the ``defaults`` dict (used only to know
+which keys are worth pulling out of a TOML table), and the already-
+decided ``table_path``.
+"""
+
+import tomllib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+
+class ConfigFileError(ValueError):
+    """A config file exists but couldn't be parsed."""
+
+
+def load_raw_toml(path: Path | None) -> dict[str, Any]:
+    """The raw, unfiltered TOML content of ``path``, or ``{}`` if
+    ``path`` is ``None`` (that source disabled) or doesn't exist.
+    Raises :class:`ConfigFileError` on a malformed file.
+    """
+    if path is None or not path.is_file():
+        return {}
+    with path.open("rb") as fh:
+        try:
+            return tomllib.load(fh)
+        except tomllib.TOMLDecodeError as exc:
+            raise ConfigFileError(f"{path}: {exc}") from exc
+
+
+def table_exists(raw: Mapping[str, Any], table_path: list[str]) -> bool:
+    """Whether ``raw`` has a table at ``table_path`` (e.g. ``["a", "b"]``
+    for ``[a.b]``) -- as opposed to that path being absent, or present
+    but holding something other than a table (a bare key/value).
+    """
+    node: Any = raw
+    for part in table_path:
+        if not isinstance(node, dict) or part not in node:
+            return False
+        node = node[part]
+    return isinstance(node, dict)
+
+
+def cwd_aux_config_paths(
+    cwd_path: Path | None, pattern: str | None = ".config.*.toml"
+) -> list[Path]:
+    """Any sibling files matching ``pattern`` alongside ``cwd_path``
+    (its own e.g. ``.config.toml``) -- e.g. ``.config.filters.toml`` --
+    sorted by name for a deterministic merge order. This is what lets
+    settings that don't belong in the main config file (a pile of
+    generated, self-contained tables, say) live in a file of their own
+    instead, while still being picked up automatically.
+
+    ``cwd_path=None`` (that source disabled) means no directory to
+    search alongside, and ``pattern=None`` turns the sibling search off
+    while leaving ``cwd_path`` itself alone; either way this returns
+    ``[]``.
+    """
+    if cwd_path is None or pattern is None:
+        return []
+    directory = cwd_path.parent if str(cwd_path.parent) else Path()
+    if not directory.is_dir():
+        return []
+    return sorted(p for p in directory.glob(pattern) if p != cwd_path and p.is_file())
+
+
+def load_config_file(
+    path: Path | None, defaults: Mapping[str, Any], table_path: list[str]
+) -> dict[str, Any]:
+    """Load one config file's settings from the selected TOML table(s).
+
+    With a single-element ``table_path`` (``[PARENT]``), this just
+    reads that top-level table. With a two-element ``[PARENT, CHILD]``
+    ``table_path``, ``[PARENT]`` supplies shared settings and the
+    nested ``[PARENT.CHILD]`` table overrides them -- so several
+    profiles in one config file can share most settings and only
+    override what differs, e.g. ``[japanese]`` holding defaults common
+    to a deck, with ``[japanese.verbs]`` and ``[japanese.vocab]`` each
+    layering their own overrides on top.
+
+    Only keys already present in ``defaults`` are pulled out -- an
+    unrelated key sitting in the same table is ignored here, same as
+    everywhere else in conclude's "only keys a caster/default knows
+    about matter" convention.
+
+    ``path=None`` (that source disabled), a missing file, or a file
+    with no matching table, all simply contribute nothing (same "no
+    opinion" convention as every other layer). Raises
+    :class:`ConfigFileError` on a malformed file.
+    """
+    if path is None or not path.is_file():
+        return {}
+    raw = load_raw_toml(path)
+
+    parent = raw.get(table_path[0], {})
+    if not isinstance(parent, dict):
+        return {}
+    merged = {key: parent[key] for key in defaults if key in parent}
+
+    if len(table_path) == 2:
+        child = parent.get(table_path[1], {})
+        if isinstance(child, dict):
+            merged.update({key: child[key] for key in defaults if key in child})
+
+    return merged
+
+
+def load_config_files(
+    home_path: Path | None,
+    cwd_path: Path | None,
+    defaults: Mapping[str, Any],
+    table_path: list[str],
+    aux_pattern: str | None = ".config.*.toml",
+    *,
+    system_path: Path | None = None,
+) -> dict[str, Any]:
+    """Merge every config-file location, lowest priority first.
+
+    ``system_path`` (the system-wide file, e.g. ``/etc/<app>/config.toml``)
+    is the lowest-priority file of all: ``home_path`` overrides it on
+    any key it sets, and so does everything after that. It is opt-in
+    at this level too -- ``None`` (the default) means no system file is
+    read.
+
+    ``cwd_path`` (project-local) is checked -- and wins on any key it
+    sets -- ahead of ``home_path`` (the user's global config file), so
+    a project directory can override the user's defaults just by
+    having its own local config file. Any files matching
+    ``aux_pattern`` alongside ``cwd_path`` (see
+    :func:`cwd_aux_config_paths`) are merged in last, in sorted-by-name
+    order, each winning over anything before it -- so, on the rare
+    occasion a key is set in more than one of these files, the more
+    specifically-named one wins over the plain project-local one.
+
+    Any path can be ``None`` to disable that one source entirely
+    (dropping it out of the merge, same as it never existing) --
+    ``cwd_path=None`` also disables the aux-file search, since there's
+    no longer a directory to search alongside; ``aux_pattern=None``
+    disables just the aux-file search.
+    """
+    merged: dict[str, Any] = {}
+    merged.update(load_config_file(system_path, defaults, table_path))
+    merged.update(load_config_file(home_path, defaults, table_path))
+    merged.update(load_config_file(cwd_path, defaults, table_path))
+    for aux_path in cwd_aux_config_paths(cwd_path, aux_pattern):
+        merged.update(load_config_file(aux_path, defaults, table_path))
+    return merged
+
+
+def parse_config_table(value: str | None, default_table: str) -> list[str]:
+    """``"PARENT"`` or ``"PARENT.CHILD"`` -> ``["PARENT"]`` or
+    ``["PARENT", "CHILD"]``. ``None``/``""`` (no explicit table
+    selection given at all) means ``[default_table]``.
+
+    A stray extra dot -- ``"a..b"``, ``"a."``, ``".a"`` -- is rejected
+    with ``ValueError`` rather than silently dropped: each of those
+    reads as a plausible typo (a doubled separator, a trailing/leading
+    one) for a table name the person actually meant to type
+    correctly, not as a third way to spell ``"a.b"``/``"a"``/``"a"``.
+    """
+    if not value:
+        return [default_table]
+    parts = value.split(".")
+    if len(parts) > 2 or any(not part for part in parts):
+        raise ValueError(f"config table must be PARENT or PARENT.CHILD, got {value!r}")
+    return parts
+
+
+def _resolve_shorthand_table_path(
+    shorthand: str,
+    default_table: str,
+    home_path: Path | None,
+    cwd_path: Path | None,
+    aux_pattern: str | None,
+    system_path: Path | None = None,
+) -> list[str]:
+    """Figure out which config table a bare positional shorthand value
+    (e.g. a deck name typed as ``myapp CARDS``) maps to, by peeking at
+    the config files themselves: a same-named top-level ``[SHORTHAND]``
+    table takes priority, as if that table had been selected
+    explicitly. Failing that, a nested ``[default_table.SHORTHAND]``
+    (inheriting whatever's shared in ``[default_table]``). Failing that
+    too, just ``[default_table]``, same as no shorthand at all.
+
+    Checked across ``cwd_path``, ``home_path``, ``system_path``, and
+    any auxiliary files alongside ``cwd_path`` as a simple union (any one of them having
+    the table counts) -- the usual value-priority between all of these
+    is unaffected, since that's still handled entirely by
+    :func:`load_config_files` once this returns which table(s) to read.
+    A ``None`` path (that source disabled) simply contributes nothing
+    to the union, same as everywhere else here.
+    """
+    raws = [load_raw_toml(cwd_path), load_raw_toml(home_path), load_raw_toml(system_path)]
+    raws.extend(load_raw_toml(path) for path in cwd_aux_config_paths(cwd_path, aux_pattern))
+    if any(table_exists(raw, [shorthand]) for raw in raws):
+        return [shorthand]
+    if any(table_exists(raw, [default_table, shorthand]) for raw in raws):
+        return [default_table, shorthand]
+    return [default_table]
+
+
+def resolve_config_table(
+    *,
+    config_value: str | None,
+    shorthand_value: str | None,
+    default_table: str,
+    home_path: Path | None,
+    cwd_path: Path | None,
+    aux_pattern: str | None = ".config.*.toml",
+    system_path: Path | None = None,
+) -> list[str]:
+    """Figure out which TOML table(s) to read config files from.
+
+    ``config_value`` -- your app's already-resolved "--config, or its
+    env var" value, CLI winning -- always wins outright when given:
+    this part can't itself be layered through the normal config-file
+    mechanism (a config file can't tell us which table of itself to
+    read).
+
+    Otherwise, ``shorthand_value`` (a bare positional argument like a
+    deck name) picks the table by looking the name up in the config
+    files themselves -- see :func:`_resolve_shorthand_table_path`.
+    Pass ``shorthand_value=None`` if your app has no such shorthand.
+
+    Falls back to ``[default_table]`` when neither is given.
+    ``home_path``/``cwd_path``/``system_path`` can each be ``None`` to
+    disable that source (the shorthand lookup then simply finds
+    nothing there).
+    """
+    if config_value:
+        return parse_config_table(config_value, default_table)
+    if shorthand_value:
+        return _resolve_shorthand_table_path(
+            shorthand_value, default_table, home_path, cwd_path, aux_pattern, system_path
+        )
+    return [default_table]

conclude/formatters.py

@@ -0,0 +1,100 @@
+"""Formatting a resolved value back into a CLI-flag token -- the
+inverse of casting. Used by :meth:`conclude.App.format_invocation` to
+render a standalone command line that reproduces a resolved settings
+dict, with no env vars or config files needed to get back to the same
+result.
+
+Each formatter returns one of three things for a given value:
+
+- a plain string -- the flag's value, already shell-quoted, to render
+  as ``--flag=<string>``
+- ``""`` (the empty string) -- render the flag bare, with no ``=value``
+  at all (used for a boolean that's on)
+- ``None`` -- don't render this flag at all
+"""
+
+import shlex
+from collections.abc import Callable, Mapping
+from typing import Any, TypeAlias
+
+from conclude.infer import Opt
+
+Formatter: TypeAlias = Callable[[Any], str | None]
+"""A function taking a resolved value and returning the CLI-token text
+to render it as (see the module docstring above for the three possible
+shapes) -- what :func:`infer_formatter` picks one of, and what an
+override in ``formatters=``/``overrides=`` is expected to be.
+"""
+
+
+def format_bool(value: bool) -> str | None:
+    """``True`` -> the bare flag; ``False`` -> not rendered at all.
+
+    This matches :meth:`conclude.App.add_arguments`'s inferred
+    ``store_true``-only CLI flags for a bool setting: there's no
+    inferred CLI syntax to explicitly turn a bool back to ``False``,
+    so a setting whose *default* is ``True`` can't be faithfully
+    reproduced this way -- write your own formatter (and, likely, your
+    own CLI flag) for that one instead of relying on inference.
+    """
+    return "" if value else None
+
+
+def format_scalar(value: Any) -> str:
+    """Any other single value -- shell-quoted ``str(value)``."""
+    return shlex.quote(str(value))
+
+
+def format_list(value: list[Any]) -> str:
+    """A list -- shell-quoted, comma-joined, matching the convention
+    :func:`conclude.cast_comma_list` casts back out of.
+    """
+    return shlex.quote(",".join(str(item) for item in value))
+
+
+_FORMATTERS_BY_TYPE: dict[type, Formatter] = {
+    bool: format_bool,
+    int: format_scalar,
+    float: format_scalar,
+    str: format_scalar,
+    list: format_list,
+}
+
+
+def infer_formatter(type_: type) -> Formatter:
+    """The formatter conclude picks for a bare Python ``type_``. Raises
+    ``TypeError`` for anything else -- pass an explicit formatter for
+    that one setting instead.
+    """
+    try:
+        return _FORMATTERS_BY_TYPE[type_]
+    except KeyError as exc:
+        raise TypeError(
+            f"no built-in formatter for type {type_!r} -- pass an explicit "
+            "formatter for this setting instead of relying on inference"
+        ) from exc
+
+
+def infer_formatters(
+    defaults: Mapping[str, Any],
+    overrides: Mapping[str, Formatter] | None = None,
+) -> dict[str, Formatter]:
+    """A formatter for every key in ``defaults`` -- inferred the same
+    way :func:`conclude.infer_casters` infers a caster (from an
+    :class:`conclude.Opt`'s wrapped type, or ``type(default)``), except
+    for a key present in ``overrides``, whose formatter there is used
+    outright. Pair a formatter override with any matching caster
+    override that needs one: a setting whose caster does something
+    beyond a plain type conversion (e.g. decoding backslash escapes)
+    needs a formatter that reverses that same thing, not the type's
+    default one.
+    """
+    overrides = overrides or {}
+    formatters: dict[str, Formatter] = {}
+    for key, default in defaults.items():
+        if key in overrides:
+            formatters[key] = overrides[key]
+            continue
+        type_ = default.type if isinstance(default, Opt) else type(default)
+        formatters[key] = infer_formatter(type_)
+    return formatters

conclude/guard.py

@@ -0,0 +1,172 @@
+"""The gitignore guard: a check that a private, local file really is
+private, shared by the developer config file
+(:mod:`conclude.developer`) and, optionally, a ``.env`` file
+(``App(dotenv_require_gitignored=True)``).
+
+A file that beats -- or quietly backstops -- the environment must never
+come from somewhere it shouldn't: a deployed image, a fresh clone, a CI
+checkout. "It is inside a git working tree *and* git is ignoring it" is
+the practical proxy for "this is somebody's private local file", and
+it's checkable without git installed. :func:`check_guard` runs the
+whole sequence and never raises; it reports which check stopped it, so
+the callers can show a reason instead of leaving anyone to wonder why a
+file has no effect.
+
+The ignore check needs the optional ``pathspec`` package
+(``pip install 'conclude[gitignore]'``). A missing ``pathspec`` is
+reported as a *setup error* (:attr:`GuardResult.setup_error`) rather
+than as an ordinary inactive file, so the callers can raise instead of
+skipping the file quietly.
+
+Caveats of the ignore check, all of which fail closed (the file stays
+inactive) except the last: the global ``core.excludesFile`` is not
+consulted; and the check is pattern matching, not git's index, so a
+*tracked* file that matches an ignore pattern (``git add -f``) still
+counts as ignored, even though git itself would not call it so.
+"""
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+_KILL_SWITCH_VALUES = frozenset({"0", "off", "false", "no"})
+
+_PATHSPEC_HINT = (
+    "the 'pathspec' package is required to verify the file is gitignored -- "
+    "pip install 'conclude[gitignore]'"
+)
+
+
+@dataclass(frozen=True)
+class GuardResult:
+    """The outcome of :func:`check_guard`."""
+
+    active: bool
+    """Every check passed: the file exists, is in a git tree, and is
+    ignored by it (and no kill switch is set)."""
+    reason: str | None = None
+    """Why not, in one short phrase, when ``active`` is ``False``."""
+    setup_error: bool = False
+    """``True`` only when ``pathspec`` is missing, so the ignore check
+    couldn't run -- a tooling problem the caller should raise for, not a
+    state to skip quietly."""
+
+
+def check_guard(
+    path: Path,
+    *,
+    kill_switch_var: str | None = None,
+    environ: Mapping[str, str] | None = None,
+    escape_hint: str | None = None,
+) -> GuardResult:
+    """Whether ``path`` may be used: not switched off, existing, inside
+    a git working tree, and ignored by it. Never raises. Checks run in
+    that order and the first failure is the reason returned.
+
+    ``kill_switch_var`` names an environment variable that, set to
+    ``off``/``0``/``false``/``no``, deactivates the 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). It is checked first, so it also
+    avoids the ``pathspec`` requirement. ``escape_hint`` completes the
+    missing-``pathspec`` message with the way out; by default that is
+    the kill switch, if there is one.
+    """
+    environ = os.environ if environ is None else environ
+    if kill_switch_var and environ.get(kill_switch_var, "").strip().lower() in _KILL_SWITCH_VALUES:
+        return GuardResult(
+            False, f"disabled by {kill_switch_var}={environ[kill_switch_var].strip()}"
+        )
+
+    if not path.is_file():
+        return GuardResult(False, "file not found")
+
+    absolute = Path(os.path.abspath(path))
+    root = _find_git_root(absolute.parent)
+    if root is None:
+        return GuardResult(False, "not inside a git working tree")
+
+    try:
+        ignored = matches_git_ignore_rules(root, absolute)
+    except ImportError:
+        if escape_hint is None and kill_switch_var:
+            escape_hint = f"or set {kill_switch_var}=off to skip the file"
+        hint = _PATHSPEC_HINT + (f" ({escape_hint})" if escape_hint else "")
+        return GuardResult(False, hint, setup_error=True)
+    if not ignored:
+        return GuardResult(False, "not covered by .gitignore")
+    return GuardResult(True)
+
+
+def _find_git_root(start: Path) -> Path | None:
+    """The nearest directory at or above ``start`` containing ``.git``
+    (a directory, or a file for a worktree/submodule).
+    """
+    for directory in (start, *start.parents):
+        if (directory / ".git").exists():
+            return directory
+    return None
+
+
+def matches_git_ignore_rules(root: Path, target: Path) -> bool:
+    """Whether the working tree's ignore rules match ``target`` (an
+    absolute path inside the working tree at ``root``).
+
+    Pure Python: it evaluates the rules itself and never runs ``git``,
+    so it answers "would these rules ignore this path?", not "does git
+    say it is ignored?" -- the two can differ (see the module docstring:
+    tracked files, and the global ``core.excludesFile``). The rules are
+    the ``.gitignore`` files from ``root`` down to the target's
+    directory plus ``root/.git/info/exclude``; nearer ``.gitignore``
+    files override farther ones, the last matching pattern in a file
+    wins, and an ignored parent directory ignores everything beneath
+    it, as :manpage:`gitignore(5)` describes. Raises ``ImportError`` if
+    the optional ``pathspec`` package isn't installed.
+    """
+    import pathspec
+
+    parts = target.relative_to(root).parts
+    exclude_lines = _read_lines(root / ".git" / "info" / "exclude")
+    specs: dict[tuple[str, ...], Any] = {}
+
+    def spec_for(directory_parts: tuple[str, ...]) -> Any:
+        if directory_parts not in specs:
+            lines = _read_lines(root.joinpath(*directory_parts, ".gitignore"))
+            specs[directory_parts] = pathspec.GitIgnoreSpec.from_lines(lines) if lines else None
+        return specs[directory_parts]
+
+    exclude_spec = pathspec.GitIgnoreSpec.from_lines(exclude_lines) if exclude_lines else None
+
+    def ignored(path_parts: tuple[str, ...], is_dir: bool) -> bool:
+        # Nearest .gitignore first; the first file with any matching
+        # pattern (ignore *or* negation) decides.
+        for depth in range(len(path_parts) - 1, -1, -1):
+            spec = spec_for(path_parts[:depth])
+            if spec is None:
+                continue
+            relative = "/".join(path_parts[depth:]) + ("/" if is_dir else "")
+            include = spec.check_file(relative).include
+            if include is not None:
+                return bool(include)
+        if exclude_spec is not None:
+            relative = "/".join(path_parts) + ("/" if is_dir else "")
+            include = exclude_spec.check_file(relative).include
+            if include is not None:
+                return bool(include)
+        return False
+
+    # Git never descends into an ignored directory, so nothing inside
+    # one can be re-included: check every ancestor directory first.
+    for depth in range(1, len(parts)):
+        if ignored(parts[:depth], is_dir=True):
+            return True
+    return ignored(parts, is_dir=False)
+
+
+def _read_lines(path: Path) -> list[str]:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return []

conclude/infer.py

@@ -0,0 +1,116 @@
+"""Inferring a caster -- and, for a setting whose default is ``None``,
+the real type a provided value should become -- from a defaults dict
+alone, so a setting only has to be written once (as its default
+value) rather than also needing a matching entry in some separate
+casters dict.
+
+A default that's already a concrete ``bool``/``int``/``float``/``str``/
+``list`` value carries its own type directly (``type(default)``). A
+default of plain ``None`` doesn't -- and "optional, unset by default"
+is the single most common shape a setting takes -- so wrap it with
+:func:`opt` instead of writing a bare ``None``: ``opt(str)`` still
+*is* ``None`` at runtime (as the actual default, and as the "not
+provided in this layer" sentinel every other layer already follows),
+it just also remembers what type a provided value should cast to.
+"""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, TypeAlias
+
+from conclude.casters import (
+    cast_bool,
+    cast_comma_list,
+    cast_float_or_none,
+    cast_int_or_none,
+    cast_str_or_none,
+)
+
+Caster: TypeAlias = Callable[[Any], Any]
+"""A function taking a raw value from any layer (a CLI string, an env
+var string, a TOML-native value, ...) and returning the properly-typed
+Python value it represents -- what :func:`infer_caster` picks one of,
+and what an override in ``casters=``/``overrides=`` is expected to be.
+"""
+
+_CASTERS_BY_TYPE: dict[type, Caster] = {
+    bool: cast_bool,
+    int: cast_int_or_none,
+    float: cast_float_or_none,
+    str: cast_str_or_none,
+    list: cast_comma_list,
+}
+
+
+@dataclass(frozen=True)
+class Opt:
+    """A typed placeholder for "no default value, but here's the type
+    a provided value should cast to" -- see :func:`opt`. Not meant to
+    be constructed directly; use ``opt(type_)``.
+    """
+
+    type: type
+
+    def __repr__(self) -> str:
+        return f"opt({self.type.__name__})"
+
+
+def opt(type_: type) -> Opt:
+    """The default to write for an optional setting of type ``type_``
+    -- e.g. ``opt(str)`` for a setting that starts out unset but,
+    once a value reaches it from any layer, should be a string; or
+    ``opt(list)`` for one that becomes a comma-separated list. Behaves
+    as plain ``None`` everywhere a default is actually *used* (the
+    defaults layer itself, and the "not provided" check every other
+    layer follows) -- this wrapper only exists so caster inference has
+    a type to work from.
+    """
+    return Opt(type_)
+
+
+def infer_caster(type_: type) -> Caster:
+    """The caster conclude picks for a bare Python ``type_``
+    (``bool``/``int``/``float``/``str``/``list``). Raises ``TypeError``
+    for anything else -- write your own caster and pass it via an
+    ``overrides``/``casters`` mapping for that one setting instead of
+    relying on inference.
+    """
+    try:
+        return _CASTERS_BY_TYPE[type_]
+    except KeyError as exc:
+        raise TypeError(
+            f"no built-in caster for type {type_!r} -- pass an explicit "
+            "caster for this setting instead of relying on inference"
+        ) from exc
+
+
+def effective_defaults(defaults: Mapping[str, Any]) -> dict[str, Any]:
+    """``defaults``, with every :class:`Opt` placeholder unwrapped to
+    the ``None`` it actually stands for -- this is what the defaults
+    *layer* of the merge should use as real values.
+    """
+    return {key: (None if isinstance(value, Opt) else value) for key, value in defaults.items()}
+
+
+def infer_casters(
+    defaults: Mapping[str, Any],
+    overrides: Mapping[str, Caster] | None = None,
+) -> dict[str, Caster]:
+    """A caster for every key in ``defaults``: inferred from each
+    default's type (:class:`Opt`'s wrapped type, or ``type(default)``
+    for anything else) -- except for a key present in ``overrides``,
+    whose caster there is used outright instead. Reach for an override
+    when inference alone isn't enough for that one setting: a caster
+    that needs custom error-message wording, or a string setting (like
+    a separator) where an explicit empty value is meaningfully
+    different from "not provided" (see :func:`conclude.cast_escaped_str`).
+    """
+    overrides = overrides or {}
+    casters: dict[str, Caster] = {}
+    for key, default in defaults.items():
+        if key in overrides:
+            casters[key] = overrides[key]
+            continue
+        type_ = default.type if isinstance(default, Opt) else type(default)
+        casters[key] = infer_caster(type_)
+    return casters