onefig 0.1.0__py3-none-any.whl

onefig/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from onefig._diff import MISSING
+from onefig._format import flatten, format_tree, unflatten
+from onefig.model import ConfigModel
+
+__all__ = ["ConfigModel", "MISSING", "flatten", "format_tree", "unflatten"]
+__version__ = "0.1.0"

onefig/_cli.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def parse_overrides(tokens: list[str]) -> dict[str, Any]:
+    """Parse a list of ``key=value`` tokens into a flat override dict.
+
+    Values are coerced with best-effort JSON parsing (so ``5`` → int, ``5.0``
+    → float, ``true`` / ``false`` → bool, ``null`` → ``None``, ``[1,2]`` →
+    list) and fall back to the raw string. Pydantic re-validates at
+    assignment, so the coercion is a hint, not a contract.
+
+    Args:
+        tokens: List of CLI tokens, each of the form ``key=value``.
+
+    Returns:
+        Flat mapping of keys to coerced values.
+
+    Raises:
+        ValueError: If a token has no ``=``, or has an empty key.
+    """
+    out: dict[str, Any] = {}
+    for tok in tokens:
+        if "=" not in tok:
+            raise ValueError(f"Bad override token {tok!r}: expected key=value.")
+        key, _, raw = tok.partition("=")
+        if not key:
+            raise ValueError(f"Bad override token {tok!r}: empty key.")
+        out[key] = _coerce(raw)
+    return out
+
+
+def _coerce(raw: str) -> Any:
+    if raw == "None":
+        return None
+    try:
+        return json.loads(raw)
+    except (ValueError, json.JSONDecodeError):
+        return raw

onefig/_cli_entry.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from onefig._completion import python_completion_script, shell_script
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="onefig",
+        description=(
+            "onefig command-line utilities. The library's primary API is the "
+            "Python ConfigModel; this CLI exposes a small number of install "
+            "helpers for shell tab completion."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    p_install = sub.add_parser(
+        "install-completion",
+        help=(
+            "Print a shell-completion install snippet bound to a specific "
+            "script command name."
+        ),
+        description=(
+            "Print a shell-completion install snippet for a script. Source "
+            "the output (or append it to your shell rc file) to enable TAB "
+            "completion for the named command."
+        ),
+    )
+    p_install.add_argument(
+        "shell",
+        choices=("bash", "zsh", "fish"),
+        help="Target shell.",
+    )
+    p_install.add_argument(
+        "--prog",
+        required=True,
+        metavar="NAME",
+        help="Command name the user types to invoke the script.",
+    )
+
+    p_py = sub.add_parser(
+        "install-python-completion",
+        help=(
+            "Print a generic shell snippet that enables tab completion for "
+            "every onefig script invoked via `python <script>.py`."
+        ),
+        description=(
+            "Print a generic shell snippet that hooks tab completion onto "
+            "`python` and `python3`. After installing it once, every "
+            "onefig-based script invoked via `python script.py` gets "
+            "completion automatically."
+        ),
+    )
+    p_py.add_argument(
+        "shell",
+        choices=("bash", "zsh", "fish"),
+        help="Target shell.",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``onefig`` console script.
+
+    Args:
+        argv: CLI arguments. Defaults to ``sys.argv[1:]``.
+
+    Returns:
+        Process exit code (``0`` on success).
+    """
+    args = build_parser().parse_args(argv)
+    if args.command == "install-completion":
+        print(shell_script(args.shell, prog=args.prog))
+    elif args.command == "install-python-completion":
+        print(python_completion_script(args.shell))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

onefig/_completion.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import shlex
+
+from pydantic import BaseModel
+
+from onefig._overrides import _resolve_keys
+
+_SPECIAL_FLAGS = ("--show", "--help", "-h")
+
+
+def completion_candidates(model: BaseModel) -> list[str]:
+    """Return every override-key candidate the shell should offer.
+
+    Each scalar field contributes its full dotted path suffixed with ``=``
+    (e.g. ``"optimizer.lr="``). When the leaf name resolves uniquely it is
+    also offered as a shorthand (``"lr="``); ambiguous leaves are omitted
+    so users aren't shown a shortcut the override engine would refuse.
+
+    Special flags (``--show``, ``--help``, ``-h``) round out the list.
+
+    Args:
+        model: A Pydantic model instance to introspect.
+
+    Returns:
+        A flat list of completion strings, in stable insertion order.
+    """
+    candidates = _resolve_keys(model)
+    seen: set[str] = set()
+    out: list[str] = []
+    for key, paths in candidates.items():
+        if len(paths) != 1:
+            # Ambiguous leaf — skip; the full-path form will appear separately.
+            continue
+        token = f"{key}="
+        if token not in seen:
+            seen.add(token)
+            out.append(token)
+    out.extend(_SPECIAL_FLAGS)
+    return out
+
+
+def shell_script(shell: str, *, prog: str) -> str:
+    """Render a shell-completion install snippet for ``prog``.
+
+    The generated script binds tab-completion of ``prog`` to a callback
+    that invokes ``prog --onefig-completions <prefix>`` and uses the
+    output as the candidate list. Source the snippet in your shell rc to
+    install (or eval it inline for one-shot use).
+
+    Args:
+        shell: One of ``"bash"``, ``"zsh"``, ``"fish"``.
+        prog: The command name the user types to invoke the script (used
+            both as the completion target and as the callback command).
+
+    Returns:
+        A shell snippet ready to write to a file or eval.
+
+    Raises:
+        ValueError: If ``shell`` isn't one of the supported shells.
+    """
+    if shell == "bash":
+        return _bash_script(prog)
+    if shell == "zsh":
+        return _zsh_script(prog)
+    if shell == "fish":
+        return _fish_script(prog)
+    raise ValueError(f"Unsupported shell {shell!r}; expected one of: bash, zsh, fish.")
+
+
+def _safe_func_suffix(prog: str) -> str:
+    """Turn ``prog`` into an identifier-safe suffix for the completion function."""
+    out = []
+    for ch in prog:
+        if ch.isalnum() or ch == "_":
+            out.append(ch)
+        else:
+            out.append("_")
+    return "".join(out) or "onefig"
+
+
+_BANNER_OPEN = "# ========== onefig: tab completion =========="
+_BANNER_CLOSE = "# ============================================"
+_PY_BANNER_OPEN = "# ====== onefig: python tab completion ======="
+_PY_BANNER_CLOSE = "# ============================================"
+
+
+def _bash_script(prog: str) -> str:
+    func = f"_onefig_complete_{_safe_func_suffix(prog)}"
+    qprog = shlex.quote(prog)
+    return f"""\
+{_BANNER_OPEN}
+{func}() {{
+    local cur
+    cur="${{COMP_WORDS[COMP_CWORD]}}"
+    local IFS=$'\\n'
+    local candidates
+    candidates=$({qprog} --onefig-completions "$cur" 2>/dev/null)
+    COMPREPLY=( $(compgen -W "$candidates" -- "$cur") )
+}}
+complete -o nospace -F {func} {qprog}
+{_BANNER_CLOSE}
+"""
+
+
+def _zsh_script(prog: str) -> str:
+    func = f"_onefig_complete_{_safe_func_suffix(prog)}"
+    qprog = shlex.quote(prog)
+    return f"""\
+{_BANNER_OPEN}
+{func}() {{
+    local -a candidates
+    candidates=("${{(@f)$({qprog} --onefig-completions \"$PREFIX\" 2>/dev/null)}}")
+    [[ ${{#candidates[@]}} -gt 0 ]] && compadd -S '' -- $candidates
+}}
+if (( ! ${{+functions[compdef]}} )); then
+    autoload -Uz compinit 2>/dev/null && compinit -u 2>/dev/null
+fi
+(( ${{+functions[compdef]}} )) && compdef {func} {prog}
+{_BANNER_CLOSE}
+"""
+
+
+def _fish_script(prog: str) -> str:
+    func = f"__onefig_complete_{_safe_func_suffix(prog)}"
+    qprog = shlex.quote(prog)
+    return f"""\
+{_BANNER_OPEN}
+function {func}
+    set -l cur (commandline -t)
+    {qprog} --onefig-completions "$cur" 2>/dev/null
+end
+complete -c {prog} -f -a '({func})'
+{_BANNER_CLOSE}
+"""
+
+
+def python_completion_script(shell: str) -> str:
+    """Render an install snippet for ``python <script>.py`` tab completion.
+
+    Bound to ``python`` / ``python3`` (and friends), the generated function
+    walks the current command line to find the script arg. Before
+    invoking the script it greps for the literal word ``onefig`` in the
+    file; if not found, the wrapper returns immediately without running
+    the script. This keeps TAB safe for arbitrary Python scripts that
+    have side effects at import time. Onefig scripts (anything that
+    ``import``s or references ``onefig``) match the grep and are invoked
+    with ``--onefig-completions <prefix>``; the printed candidates are
+    used as the completion list.
+
+    Falls back to file completion while the user is still typing the
+    script path.
+
+    One-time install. Sourcing the snippet enables completion for every
+    onefig-based script invoked via ``python``, regardless of whether the
+    script is on ``$PATH`` or directly executable.
+
+    Args:
+        shell: One of ``"bash"``, ``"zsh"``, ``"fish"``.
+
+    Returns:
+        A shell snippet ready to write to a file or eval.
+
+    Raises:
+        ValueError: If ``shell`` isn't one of the supported shells.
+    """
+    if shell == "bash":
+        return _python_bash_script()
+    if shell == "zsh":
+        return _python_zsh_script()
+    if shell == "fish":
+        return _python_fish_script()
+    raise ValueError(f"Unsupported shell {shell!r}; expected one of: bash, zsh, fish.")
+
+
+_PYTHON_NAMES = (
+    "python",
+    "python3",
+    "python3.9",
+    "python3.10",
+    "python3.11",
+    "python3.12",
+    "python3.13",
+)
+
+
+def _python_bash_script() -> str:
+    targets = " ".join(_PYTHON_NAMES)
+    return f"""\
+{_PY_BANNER_OPEN}
+_onefig_python_complete() {{
+    local cur script i
+    cur="${{COMP_WORDS[COMP_CWORD]}}"
+    script=""
+    for ((i=1; i<COMP_CWORD; i++)); do
+        case "${{COMP_WORDS[i]}}" in
+            -*) ;;
+            *.py)
+                if [[ -f "${{COMP_WORDS[i]}}" ]]; then
+                    script="${{COMP_WORDS[i]}}"
+                    break
+                fi
+                ;;
+        esac
+    done
+    if [[ -z "$script" ]]; then
+        COMPREPLY=( $(compgen -f -- "$cur") )
+        return
+    fi
+    # Skip non-onefig scripts to avoid running their side effects on TAB.
+    grep -qw onefig "$script" 2>/dev/null || return
+    local IFS=$'\\n'
+    local candidates
+    candidates=$("${{COMP_WORDS[0]}}" "$script" --onefig-completions "$cur" 2>/dev/null)
+    if [[ -z "$candidates" ]]; then
+        return
+    fi
+    COMPREPLY=( $(compgen -W "$candidates" -- "$cur") )
+}}
+complete -o nospace -F _onefig_python_complete {targets}
+{_PY_BANNER_CLOSE}
+"""
+
+
+def _python_zsh_script() -> str:
+    targets = " ".join(_PYTHON_NAMES)
+    cand_expr = (
+        '("${(@f)$($python_cmd "$script" '
+        '--onefig-completions "$PREFIX" 2>/dev/null)}")'
+    )
+    return f"""\
+{_PY_BANNER_OPEN}
+_onefig_python_complete() {{
+    local script python_cmd i
+    python_cmd="${{words[1]}}"
+    script=""
+    for ((i=2; i<CURRENT; i++)); do
+        case "${{words[i]}}" in
+            -*) ;;
+            *.py)
+                if [[ -f "${{words[i]}}" ]]; then
+                    script="${{words[i]}}"
+                    break
+                fi
+                ;;
+        esac
+    done
+    if [[ -z "$script" ]]; then
+        _files
+        return
+    fi
+    # Skip non-onefig scripts to avoid running their side effects on TAB.
+    grep -qw onefig "$script" 2>/dev/null || return
+    local -a candidates
+    candidates={cand_expr}
+    [[ ${{#candidates[@]}} -gt 0 ]] && compadd -S '' -- $candidates
+}}
+if (( ! ${{+functions[compdef]}} )); then
+    autoload -Uz compinit 2>/dev/null && compinit -u 2>/dev/null
+fi
+(( ${{+functions[compdef]}} )) && compdef _onefig_python_complete {targets}
+{_PY_BANNER_CLOSE}
+"""
+
+
+def _python_fish_script() -> str:
+    cmds = " ".join(f"-c {n}" for n in _PYTHON_NAMES)
+    return f"""\
+{_PY_BANNER_OPEN}
+function __onefig_python_complete
+    set -l tokens (commandline -opc)
+    set -l cur (commandline -t)
+    set -l script ""
+    for tok in $tokens[2..]
+        if string match -q -- '-*' $tok
+            continue
+        end
+        if string match -q -- '*.py' $tok; and test -f "$tok"
+            set script $tok
+            break
+        end
+    end
+    if test -z "$script"
+        __fish_complete_path "$cur"
+        return
+    end
+    # Skip non-onefig scripts to avoid running their side effects on TAB.
+    if not grep -qw onefig "$script" 2>/dev/null
+        return
+    end
+    $tokens[1] "$script" --onefig-completions "$cur" 2>/dev/null
+end
+complete {cmds} -f -a '(__onefig_python_complete)'
+{_PY_BANNER_CLOSE}
+"""

onefig/_diff.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+_RED = "\033[31m"
+_GREEN = "\033[32m"
+_DIM = "\033[2m"
+_RESET = "\033[0m"
+
+
+class _MissingType:
+    """Singleton sentinel for keys that are absent from one side of a diff."""
+
+    _instance: _MissingType | None = None
+
+    def __new__(cls) -> _MissingType:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "<MISSING>"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+MISSING: Any = _MissingType()
+
+
+def compute_diff(
+    a: dict[str, Any], b: dict[str, Any]
+) -> dict[str, tuple[Any, Any]]:
+    """Diff two flat dotted-key dicts.
+
+    Returns ``{path: (old, new)}`` for every key whose value differs.
+    Keys present in only one side use the :data:`MISSING` sentinel for
+    the absent side.
+
+    The returned dict is ordered: keys present in ``a`` come first (in
+    ``a``'s order), then keys only present in ``b`` (in ``b``'s order).
+    Makes diff output stable and easy to scan.
+    """
+    out: dict[str, tuple[Any, Any]] = {}
+    for k, va in a.items():
+        vb = b.get(k, MISSING)
+        if va != vb:
+            out[k] = (va, vb)
+    for k, vb in b.items():
+        if k in a:
+            continue
+        out[k] = (MISSING, vb)
+    return out
+
+
+def format_diff(
+    diff: dict[str, tuple[Any, Any]],
+    *,
+    color: bool | None = None,
+    empty_message: str = "(no changes)",
+) -> str:
+    """Render a diff dict as an aligned ``old → new`` table.
+
+    Every row uses the side-by-side ``key  old  →  new`` layout, with
+    ANSI red on the old side, green on the new side, and dimmed
+    ``<MISSING>`` for any side without a value (cross-schema diffs
+    against partial dicts).
+
+    Args:
+        diff: Mapping from dotted path to ``(old, new)`` tuple (the
+            output of :func:`compute_diff` / :meth:`ConfigModel.diff`).
+        color: ``True`` / ``False`` to force ANSI on or off. ``None``
+            (default) auto-detects via ``sys.stdout.isatty()``.
+        empty_message: Text to return when ``diff`` is empty.
+
+    Returns:
+        A multi-line string ready to print.
+    """
+    if not diff:
+        return empty_message
+
+    use_color = sys.stdout.isatty() if color is None else color
+
+    raw_olds = [_format_value(old) for old, _ in diff.values()]
+    raw_news = [_format_value(new) for _, new in diff.values()]
+
+    key_width = max(len(k) for k in diff)
+    old_width = max(len(s) for s in raw_olds)
+
+    lines: list[str] = []
+    for (key, (old, new)), old_str, new_str in zip(
+        diff.items(), raw_olds, raw_news
+    ):
+        old_padded = old_str.ljust(old_width)
+        old_styled = _style_value(old_padded, old, _RED, enabled=use_color)
+        new_styled = _style_value(new_str, new, _GREEN, enabled=use_color)
+        lines.append(f"  {key.ljust(key_width)}  {old_styled}  →  {new_styled}")
+    return "\n".join(lines)
+
+
+def format_against_defaults(
+    current: dict[str, Any],
+    defaults: dict[str, Any],
+    *,
+    color: bool | None = None,
+    empty_message: str = "(empty config)",
+) -> str:
+    """Render a config's full state with override highlights.
+
+    Walks every key in ``current``. For fields that match ``defaults``,
+    the value renders alone in green (it's the active value, untouched).
+    For fields that diverge, the row renders as ``default → current``
+    with the default in red and the current in green.
+
+    Useful as a "what does this run actually look like, and where did I
+    deviate from defaults?" snapshot.
+
+    Args:
+        current: Flat dotted-key dict of the config's current values.
+        defaults: Flat dotted-key dict of the schema's default values.
+        color: ``True`` / ``False`` to force ANSI on or off. ``None``
+            (default) auto-detects via ``sys.stdout.isatty()``.
+        empty_message: Text to return when ``current`` is empty.
+
+    Returns:
+        A multi-line string ready to print.
+    """
+    if not current:
+        return empty_message
+
+    use_color = sys.stdout.isatty() if color is None else color
+
+    keys = list(current.keys())
+    key_width = max(len(k) for k in keys)
+
+    overridden_olds = [
+        repr(defaults[k])
+        for k in keys
+        if k in defaults and defaults[k] != current[k]
+    ]
+    old_width = max((len(s) for s in overridden_olds), default=0)
+
+    lines: list[str] = []
+    for key in keys:
+        key_col = key.ljust(key_width)
+        cur_val = current[key]
+        cur_repr = repr(cur_val)
+        if key in defaults and defaults[key] == cur_val:
+            # Unchanged — single green value, no arrow.
+            value_styled = _style(cur_repr, _GREEN, enabled=use_color)
+            lines.append(f"  {key_col}  {value_styled}")
+        else:
+            # Overridden — default in red, current in green.
+            default_repr = (
+                repr(defaults[key]) if key in defaults else "<MISSING>"
+            )
+            old_padded = default_repr.ljust(old_width)
+            old_styled = _style(old_padded, _RED, enabled=use_color)
+            new_styled = _style(cur_repr, _GREEN, enabled=use_color)
+            lines.append(f"  {key_col}  {old_styled}  →  {new_styled}")
+    return "\n".join(lines)
+
+
+def _format_value(value: Any) -> str:
+    if value is MISSING:
+        return "<MISSING>"
+    return repr(value)
+
+
+def _style_value(
+    text: str, value: Any, color_code: str, *, enabled: bool
+) -> str:
+    """Style a value's rendered text. MISSING dims; everything else uses
+    its side's color."""
+    if not enabled:
+        return text
+    code = _DIM if value is MISSING else color_code
+    return f"{code}{text}{_RESET}"
+
+
+def _style(text: str, color_code: str, *, enabled: bool) -> str:
+    if not enabled:
+        return text
+    return f"{color_code}{text}{_RESET}"

onefig/_env.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from onefig._cli import _coerce
+
+
+def parse_env(
+    environ: Mapping[str, str],
+    *,
+    prefix: str,
+    delimiter: str = "__",
+    case_sensitive: bool = False,
+) -> dict[str, Any]:
+    """Parse environment variables into a flat override dict.
+
+    Keys that don't start with ``prefix`` are ignored. For matching keys,
+    the prefix is stripped, ``delimiter`` is replaced with ``.`` (so a
+    POSIX-legal name can address nested fields), and the result is
+    lowercased unless ``case_sensitive`` is set. Values are coerced with
+    best-effort JSON parsing (same rules as the CLI parser).
+
+    Args:
+        environ: Mapping of env var names to string values (typically
+            ``os.environ``).
+        prefix: Required prefix to scope which env vars are consumed.
+            Pass ``""`` to read every variable (rarely what you want).
+        delimiter: Substring that separates nested-field segments inside
+            an env var name. Defaults to ``"__"``, matching the
+            pydantic-settings convention.
+        case_sensitive: If ``False`` (default), keys are lowercased after
+            stripping the prefix. Set ``True`` for schemas with mixed-case
+            field names.
+
+    Returns:
+        Flat mapping of override keys (e.g. ``"model.lr"``) to coerced
+        values, ready to hand to ``apply_overrides``.
+
+    Raises:
+        ValueError: If a matching env var, after stripping the prefix and
+            splitting on the delimiter, contains an empty segment.
+    """
+    out: dict[str, Any] = {}
+    for raw_name, raw_value in environ.items():
+        if not raw_name.startswith(prefix):
+            continue
+        tail = raw_name[len(prefix) :]
+        if not tail:
+            # Var name equals the prefix exactly; nothing to address.
+            continue
+        segments = tail.split(delimiter)
+        if any(seg == "" for seg in segments):
+            raise ValueError(
+                f"Env var {raw_name!r} produces an empty key segment "
+                f"after stripping prefix {prefix!r} and splitting on "
+                f"{delimiter!r}."
+            )
+        key = ".".join(segments)
+        if not case_sensitive:
+            key = key.lower()
+        out[key] = _coerce(raw_value)
+    return out