dirigent-cli 0.9.0__py3-none-any.whl

dirigent_cli/context.py

@@ -0,0 +1,136 @@
+"""The state every server-talking command shares: which server, and with what token."""
+
+import logging
+import os
+from collections.abc import Awaitable
+from functools import cached_property
+
+import typer
+from pydantic import BaseModel, ConfigDict
+
+from dirigent_cli.output import (
+    FULL_VERBOSITY,
+    Detail,
+    configure,
+    refuse,
+    write_refusal,
+)
+from dirigent_cli.profiles import Endpoint, ProfileError, resolve_endpoint
+from dirigent_cli.stream import ansi
+from dirigent_client import BlockingDirigent, DirigentError
+from dirigent_core.logging import NOISY_LOGGERS, configure_logging
+from dirigent_core.protocol import Format
+
+VERBOSITY: dict[int, str] = {0: "WARNING", 1: "INFO"}
+
+LOG_LEVEL_ENV = "DIRIGENT_LOG_LEVEL"
+
+
+class CliState(BaseModel):
+    """The addressing flags, how loud to be, and the endpoint they resolve to."""
+
+    model_config = ConfigDict(frozen=True, ignored_types=(cached_property,))
+
+    url: str | None = None
+    token: str | None = None
+    profile: str | None = None
+    verbose: int = 0
+    debug: bool = False
+    debug_all: bool = False
+    output: Format = "json"
+
+    chosen: bool = False
+    """Whether a flag or the environment named the output, rather than it being the default.
+
+    A command run once by a person -- ``dg init`` -- renders unless it was asked for records,
+    and it can only tell the difference if the default is distinguishable from a choice.
+    """
+
+    @property
+    def json_output(self) -> bool:
+        """Report whether this invocation writes records rather than a rendering."""
+        return self.output != "console"
+
+    @property
+    def detail(self) -> Detail:
+        """Resolve how much this invocation emits, and how much of a value it shows.
+
+        Verbosity decides it, and the output does not: the same flags produce the same
+        records whether they are written as NDJSON or rendered, which is what makes
+        ``dg run | dg format`` the same thing as ``dg run -o console``.
+        """
+        if self.debug or self.debug_all or self.verbose >= FULL_VERBOSITY:
+            return Detail.FULL
+        return Detail.VALUES if self.verbose else Detail.SUMMARY
+
+    @property
+    def level(self) -> str:
+        """Resolve how loud to be: the flags first, then the environment, then quiet.
+
+        ``--debug-all`` names a level as well as a cap: a flag that only lifted the caps
+        would print nothing at all on its own.
+        """
+        if self.debug or self.debug_all:
+            return "DEBUG"
+        if self.verbose:
+            return VERBOSITY.get(self.verbose, "DEBUG")
+        return os.environ.get(LOG_LEVEL_ENV, VERBOSITY[0]).upper()
+
+    @property
+    def floors(self) -> dict[str, int]:
+        """Cap the libraries whose debug output would drown dirigent's own."""
+        if self.debug_all:
+            return {}
+        if self.level == "DEBUG":
+            return dict.fromkeys(NOISY_LOGGERS, logging.WARNING)
+        return dict(NOISY_LOGGERS)
+
+    def configure_output(self) -> None:
+        """Point process logging at the level this invocation asked for, and pick the medium."""
+        configure(output=self.output, detail=self.detail)
+        configure_logging(
+            self.level,
+            "console",
+            floors=self.floors,
+            cap_foreign=not self.debug_all,
+            paint=ansi,
+        )
+
+    @cached_property
+    def resolved(self) -> Endpoint:
+        """Resolve the endpoint once: flags first, then DG_*, then the selected profile."""
+        return self.endpoint()
+
+    def endpoint(self, *, needs_token: bool = True) -> Endpoint:
+        """Resolve the endpoint, refusing a profile without a token unless told not to."""
+        try:
+            return resolve_endpoint(url=self.url, token=self.token, profile=self.profile, needs_token=needs_token)
+        except ProfileError as error:
+            raise typer.BadParameter(str(error)) from error
+
+
+def state_of(ctx: typer.Context) -> CliState:
+    """Read the shared state off the Typer context, defaulting when there is none."""
+    found = ctx.find_object(CliState)
+    return found if found is not None else CliState()
+
+
+class Session(BlockingDirigent):
+    """The SDK, driven from the CLI's synchronous commands."""
+
+    def call[T](self, awaitable: Awaitable[T]) -> T:
+        """Run one API call, turning a refusal into a printed error and a non-zero exit."""
+        try:
+            return super().call(awaitable)
+        except DirigentError as error:
+            if error.problem is not None:
+                write_refusal(error.problem)
+            else:
+                refuse(error.message, status=error.status or 1)
+            raise typer.Exit(code=1) from error
+
+
+def client_for(state: CliState, *, needs_token: bool = True) -> Session:
+    """Build the API client for a resolved endpoint."""
+    endpoint = state.endpoint(needs_token=needs_token)
+    return Session(url=endpoint.url, token=endpoint.token, api_prefix=endpoint.api_prefix)

dirigent_cli/formatters.py

@@ -0,0 +1,158 @@
+"""The formatters ``dg format`` dispatches on: a name, a version, and one render method.
+
+The registry holds the built-ins and whatever a plugin in the ``dirigent.formatters`` entry
+point group contributes, so a third party ships a formatter without touching the CLI. A
+formatter renders a record kind it has never heard of rather than failing, because a record
+from a newer dirigent or from a plugin's own event still has to read.
+"""
+
+import re
+from collections.abc import Iterable, Iterator, Mapping
+from typing import Final, cast
+
+from pluginkit import PluginManager
+from rich.console import Group, RenderableType
+
+from dirigent_cli import summaries
+from dirigent_cli.stream import paint, shorten, use_scratch_prefix
+from dirigent_common import Formatter
+from dirigent_core.protocol import Record, console, parse
+from dirigent_plugin import PROJECT_NAME, markers
+
+#: Where a third party registers a formatter of its own.
+ENTRY_POINT_GROUP: Final = "dirigent.formatters"
+
+#: The formatter an omitted positional means.
+DEFAULT: Final = "console"
+
+#: The owner recorded for the built-in names, which a plugin may not claim either.
+BUILT_IN: Final = "dirigent-cli"
+
+
+class DuplicateFormatter(Exception):
+    """Two plugins claimed the same formatter name."""
+
+    def __init__(self, name: str, first: str, second: str) -> None:
+        """Name the formatter and both plugins."""
+        super().__init__(
+            f"formatter {name!r} is contributed by both {first!r} and {second!r}, and a formatter name is "
+            f"what `dg format` dispatches on, so one of the two packages must be uninstalled or renamed."
+        )
+        self.name = name
+        self.plugins = (first, second)
+
+
+class Console:
+    """The fixed-grammar rendering: padded columns, then every field the record carries.
+
+    Columns are padded and never cut, so a value wider than its column pushes the line out
+    rather than losing the half that says which one it is.
+    """
+
+    name = "console"
+    version = "1"
+
+    def render(self, record: Record) -> RenderableType:
+        """Render one record as a padded line, plus whatever its kind renders beneath."""
+        return _with_summary(record, console(shorten(summaries.line(record)), paint=paint))
+
+
+class Compact:
+    """The same grammar with no column padding.
+
+    Every field still goes out whole: this trades the columns a wide terminal can afford,
+    not any of the record's content.
+    """
+
+    name = "compact"
+    version = "1"
+
+    def render(self, record: Record) -> str:
+        """Render one record as an unpadded line, whole.
+
+        What ``console`` renders as a table beneath a line stays on the line here: a table
+        is column padding, and this formatter spends none. One record is still one line.
+        """
+        return console(shorten(record), paint=paint, pad=False)
+
+
+def _with_summary(record: Record, line: str) -> RenderableType:
+    """Put a kind's own rendering under its line, where the kind has one.
+
+    The line keeps the whole-line spelling it has on its own: a record's line is not cut or
+    folded to a terminal's width, whatever is rendered beneath it.
+    """
+    beneath = summaries.beneath(record)
+    return line if beneath is None else Group(line, beneath)
+
+
+#: What a template looks like, so the habit `docker --format` teaches gets a real answer.
+TEMPLATE = re.compile(r"\{\{.*\}\}")
+
+
+def looks_like_a_template(named: str) -> bool:
+    """Report whether this argument is a template rather than a formatter's name."""
+    return bool(TEMPLATE.search(named))
+
+
+def registry(
+    *,
+    group: str = ENTRY_POINT_GROUP,
+    extra: Mapping[str, object] | None = None,
+) -> dict[str, Formatter]:
+    """Build the registry: the built-ins, then whatever an installed plugin contributes.
+
+    ``extra`` registers plugin objects that are not installed as distributions.
+    """
+    found: dict[str, Formatter] = {}
+    origins: dict[str, str] = {}
+    for built_in in (Console(), Compact()):
+        found[built_in.name] = built_in
+        origins[built_in.name] = BUILT_IN
+    manager = PluginManager(PROJECT_NAME)
+    manager.add_extension_points(markers)
+    manager.load_entrypoints(group)
+    for name, plugin in (extra or {}).items():
+        manager.register(plugin, name=name)
+    # The hook's return annotation is a declaration, not an enforcement: a plugin may answer
+    # with anything, and anything that is not a formatter is not registered.
+    for plugin_name, contributed in manager.caller(markers.formatters).collect_with_plugins():
+        for formatter in contributed:
+            if not isinstance(formatter, Formatter):  # pyright: ignore[reportUnnecessaryIsInstance]
+                continue
+            owner = origins.get(formatter.name)
+            if owner is not None:
+                raise DuplicateFormatter(formatter.name, owner, plugin_name)
+            origins[formatter.name] = plugin_name
+            found[formatter.name] = formatter
+    return found
+
+
+def names() -> tuple[str, ...]:
+    """List the registered formatter names, the default first."""
+    registered = registry()
+    rest = sorted(name for name in registered if name != DEFAULT)
+    return (DEFAULT, *rest) if DEFAULT in registered else tuple(rest)
+
+
+def rendered(lines: Iterable[str], formatter: Formatter) -> Iterator[RenderableType]:
+    """Render a stored stream, passing through anything that is not a record."""
+    for line in lines:
+        text = line.rstrip("\n")
+        record = parse(text)
+        if record is None:
+            yield text
+            continue
+        _adopt_scratch(record)
+        # The protocol leaves the answer open; what this prints it with is rich's console.
+        yield cast("RenderableType", formatter.render(record))
+
+
+def _adopt_scratch(record: Record) -> None:
+    """Take the prefix a run's URIs share off the run's own opening record.
+
+    The live rendering is told the prefix by the run; a stream read back has only what the
+    stream says, and the run states it once so that the shorter spelling round-trips.
+    """
+    if record.get("kind") == "run" and isinstance(record.get("scratch"), str):
+        use_scratch_prefix(str(record["scratch"]))

dirigent_cli/graph.py

@@ -0,0 +1,109 @@
+"""A pipeline's shape as an indented tree: what runs first, and what waits for what."""
+
+from collections.abc import Mapping, Sequence
+from typing import Any, NamedTuple, cast
+
+#: The rule a step has unless it says otherwise, and so the one not worth printing.
+DEFAULT_RULE = "all_success"
+
+INDENT = "  "
+
+
+class GraphStep(NamedTuple):
+    """One step as the tree draws it."""
+
+    name: str
+    block: str
+    depends_on: tuple[str, ...] = ()
+    rule: str = DEFAULT_RULE
+
+
+def steps_of_document(document: Mapping[str, Any]) -> list[GraphStep]:
+    """Read the steps out of a ``dirigent/v1`` document, in the order it wrote them."""
+    steps = document.get("steps")
+    if not isinstance(steps, dict):
+        return []
+    read: list[GraphStep] = []
+    for name, body in cast("dict[str, Any]", steps).items():
+        held = cast("dict[str, Any]", body) if isinstance(body, dict) else {}
+        depends = held.get("depends_on")
+        read.append(
+            GraphStep(
+                name=str(name),
+                block=str(held.get("block", "-")),
+                depends_on=tuple(str(item) for item in cast("list[Any]", depends or ())),
+                rule=str(held.get("rule", DEFAULT_RULE)),
+            )
+        )
+    return read
+
+
+def render_graph(steps: Sequence[GraphStep]) -> list[str]:
+    """Draw the graph as indented lines, each step under the last step it waits for.
+
+    A step with several dependencies is drawn once, under the last of them, and names the
+    others rather than appearing twice: one step is one line, whatever its in-degree.
+    """
+    ordered = _in_order(steps)
+    position = {step.name: index for index, step in enumerate(ordered)}
+    known = set(position)
+    parents = {step.name: _parent(step, position) for step in ordered}
+    children: dict[str | None, list[GraphStep]] = {}
+    for step in ordered:
+        children.setdefault(parents[step.name], []).append(step)
+
+    lines: list[str] = []
+    drawn: set[str] = set()
+
+    def draw(step: GraphStep, depth: int) -> None:
+        """Write one step's line, then the steps that wait on it."""
+        if step.name in drawn:
+            return
+        drawn.add(step.name)
+        lines.append(INDENT * depth + _line(step, parents[step.name], known))
+        for child in children.get(step.name, []):
+            draw(child, depth + 1)
+
+    for root in children.get(None, []):
+        draw(root, 0)
+    # A cycle has no root to reach it from, and a step left undrawn is worse than one drawn
+    # at the margin.
+    for step in ordered:
+        draw(step, 0)
+    return lines
+
+
+def _line(step: GraphStep, parent: str | None, known: set[str]) -> str:
+    """Render one step: its name, its block, and whatever the tree cannot show."""
+    rendered = f"{step.name}  ({step.block})"
+    others = [name for name in step.depends_on if name != parent and name in known]
+    if others:
+        rendered += f"  also after {', '.join(others)}"
+    if step.rule != DEFAULT_RULE:
+        rendered += f"  when {step.rule}"
+    return rendered
+
+
+def _parent(step: GraphStep, position: Mapping[str, int]) -> str | None:
+    """The dependency a step is drawn under: the last one to run, or nothing for a root."""
+    known = [name for name in step.depends_on if name in position]
+    return max(known, key=lambda name: position[name]) if known else None
+
+
+def _in_order(steps: Sequence[GraphStep]) -> list[GraphStep]:
+    """Sort the steps so nothing precedes what it waits for, keeping the written order otherwise."""
+    known = {step.name for step in steps}
+    waiting = list(steps)
+    placed: list[GraphStep] = []
+    settled: set[str] = set()
+    while waiting:
+        ready = [step for step in waiting if all(name in settled or name not in known for name in step.depends_on)]
+        if not ready:
+            # A cycle, which validation refuses: draw the rest as written rather than hiding it.
+            placed.extend(waiting)
+            break
+        placed.extend(ready)
+        settled.update(step.name for step in ready)
+        names = {step.name for step in ready}
+        waiting = [step for step in waiting if step.name not in names]
+    return placed