eksp 0.9.0__py3-none-any.whl

eksp/__init__.py

@@ -0,0 +1,61 @@
+"""eksp - resolve Jinja-style ``{{ ... }}`` references in JSON configurations.
+
+Public API:
+
+- :func:`eksp.resolver.resolve` - recursive fixed-point Jinja rendering and
+  ``$include`` / ``$include.*`` / ``$src`` / ``$src.*`` handling (optional ``debug=True`` for
+  ``//$include*`` and ``//$src*`` diagnostics).
+- :func:`eksp.namespaces.build_namespaces` - build the lookup namespaces from
+  ``--src``, ``--ctxt``, ``--srcvar``, ``--var`` inputs, and the process environment.
+- :func:`eksp.namespaces.parse_ctxt_arg` - parse one ``--ctxt`` path (same rules as ``--src``).
+- :func:`eksp.namespaces.parse_srcvar_arg` - parse one ``--srcvar`` key (path into ``SRC``).
+- :func:`eksp.namespaces.parse_var_arg` - parse one ``--var`` key (path into ``CTXT``).
+- :func:`eksp.namespaces.parse_path_prefix` - parse ``--srcvar-root`` / ``--var-root``.
+- :func:`eksp.cli.main` - the ``eksp`` console script entry point.
+- :func:`eksp.api.resolve_cli` - parse CLI-style ``argv``; return
+  ``(resolved, namespaces)`` tuple.
+- :func:`eksp.pipeline.build_and_resolve` - same pipeline as the CLI without
+  parsing flags or serializing JSON.
+"""
+
+from .api import resolve_cli
+from .namespaces import (
+    RESERVED_LABELS,
+    build_namespaces,
+    parse_ctxt_arg,
+    parse_path_prefix,
+    parse_src_arg,
+    parse_srcvar_arg,
+    parse_var_arg,
+    prepend_path_root,
+)
+from .pipeline import build_and_resolve
+from .resolver import (
+    INCLUDE_KEY,
+    MAX_ITERATIONS,
+    SRC_KEY,
+    ResolutionError,
+    make_native_environment,
+    resolve,
+)
+
+__all__ = [
+    "INCLUDE_KEY",
+    "MAX_ITERATIONS",
+    "RESERVED_LABELS",
+    "SRC_KEY",
+    "ResolutionError",
+    "build_and_resolve",
+    "build_namespaces",
+    "make_native_environment",
+    "parse_ctxt_arg",
+    "parse_path_prefix",
+    "parse_src_arg",
+    "parse_srcvar_arg",
+    "parse_var_arg",
+    "prepend_path_root",
+    "resolve",
+    "resolve_cli",
+]
+
+__version__ = "0.9.0"

eksp/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the package via ``python -m eksp``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

eksp/api.py

@@ -0,0 +1,92 @@
+"""Programmatic entry points that mirror the ``eksp`` CLI."""
+
+from __future__ import annotations
+
+import shlex
+import sys
+import warnings
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from .pipeline import build_and_resolve
+
+
+def resolve_cli(
+    argv: str | Sequence[str] | None = None,
+    *,
+    environ: Mapping[str, str] | None = None,
+) -> tuple[Any, dict[str, Any]]:
+    """Parse CLI-style arguments and return ``(resolved, namespaces)``.
+
+    Parameters
+    ----------
+    argv:
+        Arguments as for :func:`subprocess.run`: a single string (split with
+        :func:`shlex.split`), a sequence of tokens, or ``None`` to use
+        ``sys.argv[1:]``. Do not include the program name.
+    environ:
+        Optional environment mapping for the ``ENV`` namespace. Defaults to
+        ``os.environ`` when building namespaces.
+
+    Returns
+    -------
+    tuple[Any, dict[str, Any]]
+        The resolved merged ``SRC`` document and the full namespace mapping from
+        :func:`eksp.namespaces.build_namespaces`.
+
+    Warnings
+    --------
+    Emits :class:`UserWarning` if ``--output``, ``--compact``, or ``--sort-keys``
+        are present; those flags only affect JSON serialization in the CLI.
+
+    Raises
+    ------
+    click.exceptions.ClickException
+        On invalid CLI usage (including ``--help`` / ``--version``, which exit
+        via Click as in the terminal).
+    NamespaceError
+        Invalid ``--src``, ``--ctxt``, ``--srcvar``, or ``--var`` arguments.
+    ResolutionError
+        Template or resolution failure while rendering.
+    """
+    if argv is None:
+        args = sys.argv[1:]
+    elif isinstance(argv, str):
+        args = shlex.split(argv)
+    else:
+        args = list(argv)
+
+    from .cli import main
+
+    ctx = main.make_context("eksp", args)
+    params = ctx.params
+
+    if params.get("output") is not None:
+        warnings.warn(
+            "--output is ignored by resolve_cli (the result is returned, not written to a file)",
+            UserWarning,
+            stacklevel=2,
+        )
+    if params.get("compact"):
+        warnings.warn(
+            "--compact is ignored by resolve_cli",
+            UserWarning,
+            stacklevel=2,
+        )
+    if params.get("sort_keys"):
+        warnings.warn(
+            "--sort-keys is ignored by resolve_cli",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    return build_and_resolve(
+        src_args=params["src_args"],
+        ctxt_args=params["ctxt_args"],
+        srcvar_args=params["srcvar_args"],
+        var_args=params["var_args"],
+        srcvar_root=params.get("srcvar_root"),
+        var_root=params.get("var_root"),
+        debug=params["debug"],
+        environ=environ,
+    )

eksp/cli.py

@@ -0,0 +1,180 @@
+"""``eksp`` command-line entry point.
+
+Run ``eksp --help`` for the full reference. The CLI's job is to translate
+``--src``, ``--ctxt``, ``--srcvar``, and ``--var`` arguments into namespaces,
+resolve the merged ``SRC`` document, and serialize the result back to JSON.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .json_format import format_json
+from .namespaces import NamespaceError
+from .pipeline import build_and_resolve
+from .resolver import ResolutionError
+
+
+@click.command(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    epilog=(
+        "Examples:\n"
+        "\n"
+        "  eksp --src cfg1.json --src cfg2.json \\\n"
+        "       --var name1=abc --var name2=def\n"
+        "\n"
+        "  eksp --src cfg.json --var solo=pat\n"
+        "       (patches merged CTXT, e.g. {{ CTXT.solo }})\n"
+        "  eksp --src R1=cfg1.json --src R2=cfg2.json \\\n"
+        "       --var name1=abc\n"
+        "\n"
+        "Variables are referenced with Jinja's {{ NAMESPACE.path }} syntax, e.g.\n"
+        "{{ ENV.HOME }}, {{ SRC.db.host }}, {{ CTXT1.fragment }}, {{ CTXT.solo }}.\n"
+    ),
+)
+@click.option(
+    "--src",
+    "src_args",
+    metavar="[LABEL=]PATH",
+    multiple=True,
+    help=(
+        "Load JSON from PATH. With LABEL=, expose as namespace LABEL (repeat LABEL "
+        "to shallow-merge several files into that label) and as SRC# for this line. "
+        "With PATH only, expose only as SRC#. Every file is shallow-merged into SRC "
+        "(later files win at the top level). Repeatable."
+    ),
+)
+@click.option(
+    "--ctxt",
+    "ctxt_args",
+    metavar="[LABEL=]PATH",
+    multiple=True,
+    help=(
+        "Load JSON like --src; shallow-merge into CTXT and expose as CTXT1, "
+        "CTXT2, … (repeat LABEL to merge into that label). Not merged into SRC or "
+        "printed output. Repeatable."
+    ),
+)
+@click.option(
+    "--srcvar",
+    "srcvar_args",
+    metavar="PATH.TO.KEY=VALUE",
+    multiple=True,
+    help=(
+        "Set a string on the merged SRC document: Jinja-style path (.a, ['b']) "
+        "before the first =; value is the rest (may contain =). Repeatable."
+    ),
+)
+@click.option(
+    "--srcvar-root",
+    "srcvar_root",
+    metavar="PATH",
+    default=None,
+    help=(
+        "Prepend PATH. to every --srcvar key (dot-separated Jinja-style path, "
+        "same rules as --srcvar keys without =)."
+    ),
+)
+@click.option(
+    "--var",
+    "var_args",
+    metavar="PATH.TO.KEY=VALUE",
+    multiple=True,
+    help=(
+        "Patch a string into the merged CTXT document: Jinja-style path (.a, ['b']) "
+        "before the first =; value is the rest (may contain =). Not merged into "
+        "printed SRC. Repeatable."
+    ),
+)
+@click.option(
+    "--var-root",
+    "var_root",
+    metavar="PATH",
+    default=None,
+    help=(
+        "Prepend PATH. to every --var key (dot-separated Jinja-style path, same "
+        "rules as --var keys without =)."
+    ),
+)
+@click.option(
+    "--output",
+    "-o",
+    "output",
+    type=click.Path(dir_okay=False, writable=True, path_type=Path),
+    default=None,
+    help="Write the resolved JSON to PATH instead of stdout.",
+)
+@click.option(
+    "--compact",
+    is_flag=True,
+    default=False,
+    help="Emit compact JSON (one line, no extra whitespace).",
+)
+@click.option(
+    "--sort-keys",
+    is_flag=True,
+    default=False,
+    help="Sort object keys in JSON output (default preserves source key order).",
+)
+@click.option(
+    "--debug",
+    is_flag=True,
+    default=False,
+    help=(
+        "Keep $include / $include.* source values under //$include / //$include.* "
+        "and src diagnostics under //$src, //$src.*, and //$ctxt.*."
+    ),
+)
+@click.version_option(__version__, prog_name="eksp")
+def main(
+    src_args: tuple[str, ...],
+    ctxt_args: tuple[str, ...],
+    srcvar_args: tuple[str, ...],
+    srcvar_root: str | None,
+    var_args: tuple[str, ...],
+    var_root: str | None,
+    output: Path | None,
+    compact: bool,
+    sort_keys: bool,
+    debug: bool,
+) -> None:
+    """Resolve Jinja-style ``{{ ... }}`` references in JSON configurations.
+
+    eksp loads zero or more JSON files via ``--src`` (``PATH`` or ``LABEL=PATH``)
+    and zero or more via ``--ctxt`` (same shape, exposed as ``CTXT1``, ``CTXT2``,
+    … without merging into ``SRC``). ``--srcvar`` patches string values into the
+    merged ``SRC`` object; ``--var`` patches the merged ``CTXT`` namespace for templates.
+    The ``SRC`` namespace is then rendered recursively until every string stops
+    changing (and ``$include`` / ``$include.*`` keys are expanded). The result is
+    printed as JSON.
+    """
+    try:
+        resolved, _namespaces = build_and_resolve(
+            src_args,
+            ctxt_args,
+            srcvar_args,
+            var_args,
+            srcvar_root=srcvar_root,
+            var_root=var_root,
+            debug=debug,
+        )
+    except NamespaceError as exc:
+        raise click.UsageError(str(exc)) from exc
+    except ResolutionError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    text = format_json(resolved, compact=compact, sort_keys=sort_keys)
+
+    if output is None:
+        click.echo(text)
+    else:
+        output.write_text(text + ("" if text.endswith("\n") else "\n"), encoding="utf-8")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main(prog_name="eksp")
+    sys.exit(0)

eksp/json_format.py

@@ -0,0 +1,18 @@
+"""Serialize resolved values as JSON for the CLI."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def format_json(value: Any, *, compact: bool = False, sort_keys: bool = False) -> str:
+    """Return ``value`` as JSON text.
+
+    By default, object keys keep their insertion order (Python 3.7+ dicts).
+    Set ``sort_keys`` to emit keys in sorted order at every object level.
+    """
+    kwargs: dict[str, Any] = {"ensure_ascii": False, "sort_keys": sort_keys}
+    if compact:
+        return json.dumps(value, separators=(",", ":"), **kwargs)
+    return json.dumps(value, indent=2, **kwargs)