zuke 1.0.0__py3-none-any.whl

zuke/__init__.py

@@ -0,0 +1,76 @@
+# Copyright (c) 2026 the Zuke contributors
+# SPDX-License-Identifier: MIT
+"""Zuke for Python: author your build as typed Python, run it on the Zuke engine.
+
+A build is a class extending :class:`Build` whose fields are targets made with
+:func:`target`, services made with :func:`service`, parameters made with
+:func:`parameter`, groups made with :func:`group` and CI files made with
+:func:`ci`; the file ends with :func:`run`. The engine starts the file as a
+worker, asks it for the graph, and runs each target's body when its turn comes.
+"""
+
+from zuke._build import Build
+from zuke._ci import Ci, ci, invoke
+from zuke._context import (
+    CommandError,
+    Context,
+    ExecResult,
+    Outcome,
+    Plan,
+    ServiceContext,
+    StateHandle,
+)
+from zuke._dsl import (
+    BooleanParameter,
+    Group,
+    NumberListParameter,
+    NumberParameter,
+    Parameter,
+    Service,
+    StringListParameter,
+    StringParameter,
+    Target,
+    group,
+    parameter,
+    service,
+    target,
+)
+from zuke._duration import Duration
+from zuke._run import run
+from zuke._settings import LockSettings, ValidateDuringSettings, WaitSettings
+
+__version__ = "1.0.0"  # x-release-please-version
+"""The package version; release-please bumps it alongside pyproject.toml."""
+
+__all__ = [
+    "BooleanParameter",
+    "Build",
+    "Ci",
+    "CommandError",
+    "Context",
+    "Duration",
+    "ExecResult",
+    "Group",
+    "LockSettings",
+    "NumberListParameter",
+    "NumberParameter",
+    "Outcome",
+    "Parameter",
+    "Plan",
+    "Service",
+    "ServiceContext",
+    "StateHandle",
+    "StringListParameter",
+    "StringParameter",
+    "Target",
+    "ValidateDuringSettings",
+    "WaitSettings",
+    "__version__",
+    "ci",
+    "group",
+    "invoke",
+    "parameter",
+    "run",
+    "service",
+    "target",
+]

zuke/_awaited.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2026 the Zuke contributors
+# SPDX-License-Identifier: MIT
+"""Settle what a user's function returned: awaited when it chose to be async."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable
+
+
+async def awaited[T](value: T | Awaitable[T]) -> T:
+    """``value`` itself, or its result when it is awaitable."""
+    if inspect.isawaitable(value):
+        return await value
+    return value

zuke/_build.py

@@ -0,0 +1,169 @@
+# Copyright (c) 2026 the Zuke contributors
+# SPDX-License-Identifier: MIT
+"""The build class: its fields are its targets, parameters, groups and CI files.
+
+A subclass is read when it is created: every field holding one of those is
+named after its attribute, in declaration order, and every target a field
+names must be a field of the same build, or the class fails to be made with
+the offending field named. The instance is what the worker hosts; the hooks
+a subclass overrides are the ones the manifest flags and the engine calls.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Mapping
+from typing import ClassVar
+
+from zuke._ci import Ci
+from zuke._dsl import Group, Parameter, Service, Target
+from zuke._duration import Duration
+from zuke._field import Field
+from zuke._guard import ProtocolError
+
+
+class Build:
+    """Extend this with targets as fields; see :func:`~zuke.target`."""
+
+    deadline: ClassVar[Duration | None] = None
+    """How long the whole run may take, as a duration or milliseconds."""
+    unforceable: ClassVar[tuple[Target, ...]] = ()
+    """Targets ``--force`` may never re-run."""
+
+    targets_: ClassVar[dict[str, Target]] = {}
+    """The targets by name, in declaration order; set when the subclass is made."""
+    parameters_: ClassVar[dict[str, Parameter]] = {}
+    """The parameters by name, in declaration order; set when the subclass is made."""
+    groups_: ClassVar[dict[str, Group]] = {}
+    """The groups by name, in declaration order; set when the subclass is made."""
+    ci_: ClassVar[dict[str, Ci]] = {}
+    """The CI files by name, in declaration order; set when the subclass is made."""
+
+    def __init_subclass__(cls) -> None:
+        """Discover and name the fields, then check every reference between them."""
+        super().__init_subclass__()
+        cls.targets_, cls.parameters_, cls.groups_, cls.ci_ = {}, {}, {}, {}
+        for klass in reversed(cls.__mro__):
+            if klass is Build or klass is object:
+                continue
+            for name, value in vars(klass).items():
+                if isinstance(value, Target):
+                    cls.targets_[name] = value
+                elif isinstance(value, Parameter):
+                    cls.parameters_[name] = value
+                elif isinstance(value, Group):
+                    cls.groups_[name] = value
+                elif isinstance(value, Ci):
+                    cls.ci_[name] = value
+                else:
+                    continue
+                value.name_ = name
+        cls._check_references()
+
+    @classmethod
+    def _check_references(cls) -> None:
+        targets = list(cls.targets_.values())
+        for name, t in cls.targets_.items():
+            for setter, reference in t.references():
+                cls._check(name, setter, reference, targets)
+            for p in t.parameters():
+                if p not in cls.parameters_.values():
+                    cls._refuse(
+                        name,
+                        "requires",
+                        "a parameter that is not a field of this build",
+                    )
+        for name, g in cls.groups_.items():
+            for member in g.members_:
+                cls._check(name, "group", member, targets)
+        for name, c in cls.ci_.items():
+            for reference in c.references():
+                cls._check(name, "invokes", reference, targets)
+        for t in cls.unforceable:
+            cls._check("unforceable", "unforceable", t, targets)
+
+    @classmethod
+    def _check(
+        cls, field: str, setter: str, reference: Field | str, targets: list[Target]
+    ) -> None:
+        if isinstance(reference, str):
+            if reference not in cls.targets_:
+                cls._refuse(field, setter, f'no target named "{reference}"')
+        elif reference not in targets:
+            cls._refuse(field, setter, "a target that is not a field of this build")
+
+    @classmethod
+    def _refuse(cls, field: str, setter: str, what: str) -> None:
+        raise TypeError(f"{cls.__name__}.{field}: {setter} names {what}")
+
+    def on_start(self) -> Awaitable[None] | None:
+        """Override to run before the first target; sync or async."""
+        return None
+
+    def on_target_start(self, target: str) -> Awaitable[None] | None:
+        """Override to run before each target; sync or async."""
+        return None
+
+    def on_target_end(self, target: str, status: str) -> Awaitable[None] | None:
+        """Override to run after each target settles, with its status; sync or async."""
+        return None
+
+    def on_finish(self, ok: bool) -> Awaitable[None] | None:
+        """Override to run when the build is done, told whether it succeeded."""
+        return None
+
+    def hooks_(self) -> dict[str, bool]:
+        """Which hooks this build overrides: the ones the engine will call."""
+        cls = type(self)
+        flagged = {
+            "onStart": cls.on_start is not Build.on_start,
+            "onTargetStart": cls.on_target_start is not Build.on_target_start,
+            "onTargetEnd": cls.on_target_end is not Build.on_target_end,
+            "onFinish": cls.on_finish is not Build.on_finish,
+        }
+        return {name: True for name, overridden in flagged.items() if overridden}
+
+    def describe(self) -> dict[str, object]:
+        """The manifest: what ``build.describe`` answers."""
+        m: dict[str, object] = {
+            "name": type(self).__name__,
+            "targets": [t.manifest() for t in self.targets_.values()],
+        }
+        for key, fields in (
+            ("parameters", self.parameters_),
+            ("groups", self.groups_),
+            ("ci", self.ci_),
+        ):
+            if fields:
+                m[key] = [f.manifest() for f in fields.values()]
+        hooks = self.hooks_()
+        if hooks:
+            m["hooks"] = hooks
+        config: dict[str, object] = {}
+        if self.deadline is not None:
+            config["deadline"] = self.deadline
+        if self.unforceable:
+            config["unforceable"] = [t.name for t in self.unforceable]
+        if config:
+            m["config"] = config
+        return m
+
+    def configure(self, parameters: Mapping[str, str | None]) -> None:
+        """Take the resolved parameters from ``build.configure``."""
+        for name, p in self.parameters_.items():
+            p.resolve(parameters.get(name))
+
+    def target_(self, name: str, method: str) -> Target:
+        """The target ``method`` asks about, or a :class:`ProtocolError` naming it."""
+        t = self.targets_.get(name)
+        if t is None:
+            raise ProtocolError(
+                f'{method}: {type(self).__name__} has no target "{name}"'
+            )
+        return t
+
+    def service_(self, name: str, method: str) -> Service:
+        """The service ``method`` asks about, or a :class:`ProtocolError` naming it."""
+        t = self.target_(name, method)
+        if not isinstance(t, Service):
+            raise ProtocolError(f'{method}: "{name}" is not a service')
+        return t

zuke/_ci.py

@@ -0,0 +1,141 @@
+# Copyright (c) 2026 the Zuke contributors
+# SPDX-License-Identifier: MIT
+"""CI files a build declares, which ``zuke generate-ci`` renders from the manifest.
+
+A CI file is a build field like a target, named after its attribute, which
+names its default path: ``releaseWorkflow`` writes
+``.github/workflows/release.yml``. The engine renders it from the manifest
+exactly as it renders a TypeScript build's.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Literal, Self
+
+from zuke._field import Field, name_of
+from zuke._guard import is_list
+
+Provider = Literal["github", "gitlab", "azure", "bitbucket"]
+"""A CI provider the engine renders for."""
+
+# shortcut: the pipeline, the invocation adjustments, the fan-out options and
+# the pins are mappings passed through as given, which the engine validates
+# field by field and refuses by name; typed builders for them arrive with the
+# facade generator, which can emit them from core's own CI types.
+
+
+class Ci(Field):
+    """One CI file. Start one with :func:`ci`."""
+
+    def __init__(self) -> None:
+        """A CI file with nothing declared yet."""
+        super().__init__()
+        self._provider: Provider | None = None
+        self._path: str | None = None
+        self._pipeline: dict[str, object] | None = None
+        self._invokes: list[Field | str | dict[str, object]] = []
+        self._fan_out: bool | dict[str, object] | None = None
+        self._pins: dict[str, object] | None = None
+
+    def provider(self, provider: Provider) -> Self:
+        """The provider to render for; GitHub when not set."""
+        self._provider = provider
+        return self
+
+    def path(self, path: str) -> Self:
+        """The output path, overriding the one the field name implies."""
+        self._path = path
+        return self
+
+    def pipeline(self, fields: Mapping[str, object]) -> Self:
+        """The pipeline fields, and the jobs unless ``invokes`` or ``fan_out`` do."""
+        self._pipeline = dict(fields)
+        return self
+
+    def invokes(self, *entries: Field | str | Mapping[str, object]) -> Self:
+        """The targets to run as jobs: bare, or through :func:`invoke` to adjust."""
+        self._invokes.extend(
+            dict(entry) if isinstance(entry, Mapping) else entry for entry in entries
+        )
+        return self
+
+    def fan_out(self, options: bool | Mapping[str, object] = True) -> Self:
+        """One job per target in the graph, with the fan-out options."""
+        self._fan_out = dict(options) if isinstance(options, Mapping) else options
+        return self
+
+    def pins(self, pins: Mapping[str, object]) -> Self:
+        """Pinned action references by action name."""
+        self._pins = dict(pins)
+        return self
+
+    def references(self) -> list[Field | str]:
+        """Every target the file invokes, for the build to check."""
+        named: list[Field | str] = []
+        for entry in self._invokes:
+            if isinstance(entry, dict):
+                target = entry.get("target")
+                if isinstance(target, (Field, str)):
+                    named.append(target)
+                after = entry.get("after")
+                if is_list(after):
+                    named.extend(
+                        item for item in after if isinstance(item, (Field, str))
+                    )
+            else:
+                named.append(entry)
+        return named
+
+    def manifest(self) -> dict[str, object]:
+        """The file as the manifest's ``ci`` list carries it."""
+        m: dict[str, object] = {"name": self.name}
+        for key, value in (
+            ("provider", self._provider),
+            ("path", self._path),
+            ("pipeline", self._pipeline),
+        ):
+            if value is not None:
+                m[key] = value
+        if self._invokes:
+            m["invokes"] = [_invocation(entry) for entry in self._invokes]
+        if self._fan_out is not None:
+            m["fanOut"] = self._fan_out
+        if self._pins is not None:
+            m["pins"] = self._pins
+        return m
+
+
+def _invocation(entry: Field | str | dict[str, object]) -> object:
+    if not isinstance(entry, dict):
+        return name_of(entry)
+    resolved = dict(entry)
+    target = resolved.get("target")
+    if isinstance(target, (Field, str)):
+        resolved["target"] = name_of(target)
+    after = resolved.get("after")
+    if is_list(after):
+        resolved["after"] = [
+            name_of(item) if isinstance(item, (Field, str)) else item for item in after
+        ]
+    return resolved
+
+
+def ci() -> Ci:
+    """A new CI file, to configure fluently and assign to a build field."""
+    return Ci()
+
+
+def invoke(
+    target: Field | str, *, after: Sequence[Field | str] = (), **adjustments: object
+) -> dict[str, object]:
+    """An invoked target with the runner's adjustments, for :meth:`Ci.invokes`.
+
+    ``after`` adds ``needs:`` edges; the other keywords, such as ``matrix``, are
+    the invocation's fields as the engine names them.
+    """
+    entry: dict[str, object] = {"target": target}
+    if after:
+        entry["after"] = list(after)
+    entry.update(adjustments)
+    return entry

zuke/_context.py

@@ -0,0 +1,214 @@
+# Copyright (c) 2026 the Zuke contributors
+# SPDX-License-Identifier: MIT
+"""The contexts a body and a service phase are handed, every call served by the engine.
+
+A body never spawns a process or touches the run's state itself. Each method
+here is a request the engine serves inside the caller's own scope, so its
+dry-run echo, redaction and cancellation apply, and each is named as the
+engine's protocol names it. A service phase gets the smaller context, since
+the engine serves it no body-only call. The engine's answers are untrusted
+and narrowed field by field.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from zuke._guard import boolean, integer, record, string, string_or_none, strings
+from zuke._rpc import CANCELLED, Peer, RpcError
+
+
+@dataclass(frozen=True)
+class ExecResult:
+    """What a command the engine ran for the body came back with."""
+
+    code: int
+    """The exit code."""
+    stdout: str
+    """What it printed to stdout."""
+    stderr: str
+    """What it printed to stderr."""
+
+
+def exec_result_of(answer: object, method: str) -> ExecResult:
+    """The :class:`ExecResult` an answer of ``method`` carries, each field guarded."""
+    return ExecResult(
+        code=integer(answer, "code", method),
+        stdout=string(answer, "stdout", method),
+        stderr=string(answer, "stderr", method),
+    )
+
+
+class CommandError(Exception):
+    """A command :meth:`ServiceContext.sh` ran exited with a code other than zero."""
+
+    def __init__(self, argv: tuple[str, ...], result: ExecResult) -> None:
+        """Name the command and its code."""
+        super().__init__(f"`{' '.join(argv)}` exited with code {result.code}")
+        self.argv = argv
+        """The command, as discrete arguments."""
+        self.result = result
+        """Its exit code and output."""
+
+
+@dataclass(frozen=True)
+class Outcome:
+    """What another target in this run did, as :meth:`Context.outcome_of` tells."""
+
+    status: str
+    """The record's status: ``succeeded``, ``failed``, ``skipped``, ``waiting``, …"""
+    error: str | None
+    """The failure's message, when it failed."""
+    started_at: str | None
+    """When it started, ISO-8601, if it did."""
+    ended_at: str | None
+    """When it settled, ISO-8601, if it has."""
+
+
+@dataclass(frozen=True)
+class Plan:
+    """The run's plan, as :meth:`Context.plan` reports it."""
+
+    targets: list[str]
+    """The planned targets, in order."""
+    dependencies: dict[str, list[str]]
+    """Each planned target's dependencies."""
+
+
+class StateHandle:
+    """Durable state of one target, kept by the engine across runs and resumes."""
+
+    def __init__(self, ctx: Context, of: str | None) -> None:
+        """State of ``of``, or of the body's own target when ``None``."""
+        self._ctx = ctx
+        self._of = {} if of is None else {"of": of}
+
+    async def get(self) -> dict[str, object]:
+        """The state as last written."""
+        return record(
+            await self._ctx.call_("state.get", **self._of), "state.get: the answer"
+        )
+
+    async def set(self, patch: Mapping[str, object]) -> None:
+        """Merge ``patch`` into the state."""
+        await self._ctx.call_("state.set", patch=dict(patch), **self._of)
+
+    async def try_set(self, patch: Mapping[str, object]) -> bool:
+        """Merge ``patch`` if the engine will record it now; whether it did."""
+        answer = await self._ctx.call_("state.trySet", patch=dict(patch), **self._of)
+        return boolean(answer, "recorded", "state.trySet")
+
+
+class ServiceContext:
+    """What a service phase is handed: the engine's services a phase may use."""
+
+    def __init__(self, engine: Peer, target: str) -> None:
+        """A context for a phase of ``target``."""
+        self._engine = engine
+        self.target = target
+        """The target whose phase or body this is."""
+
+    async def call_(self, method: str, **params: object) -> object:
+        """Ask the engine as this target; an engine-side cancel unwinds the caller."""
+        try:
+            return await self._engine.request(method, {"target": self.target, **params})
+        except RpcError as error:
+            if error.code == CANCELLED:
+                raise asyncio.CancelledError(str(error)) from None
+            raise
+
+    async def sh(
+        self,
+        *argv: str,
+        cwd: str | None = None,
+        env: Mapping[str, str] | None = None,
+        stdin: str | None = None,
+        check: bool = True,
+    ) -> ExecResult:
+        """Run ``argv`` through the engine, in the worker's directory and environment.
+
+        ``cwd`` and ``env`` adjust those for this command; ``stdin`` is fed to it.
+        Raises :class:`CommandError` on a non-zero code unless ``check`` is off.
+        """
+        params: dict[str, object] = {"argv": list(argv)}
+        if cwd is not None:
+            params["cwd"] = cwd
+        if env is not None:
+            params["env"] = dict(env)
+        if stdin is not None:
+            params["stdin"] = stdin
+        result = exec_result_of(await self.call_("exec", **params), "exec")
+        if check and result.code != 0:
+            raise CommandError(argv, result)
+        return result
+
+    async def secret(self, value: str) -> None:
+        """Redact ``value`` from everything the run prints or records from now on."""
+        await self.call_("secret.register", value=value)
+
+    async def log(self, line: str) -> None:
+        """Log a line attributed to this target."""
+        await self.call_("log", line=line)
+
+
+class Context(ServiceContext):
+    """What a body is handed: the run it is part of, and all the engine serves it."""
+
+    def __init__(self, engine: Peer, target: str, run_id: str, dry_run: bool) -> None:
+        """A context for ``target``'s body in the run ``run_id``."""
+        super().__init__(engine, target)
+        self.run_id = run_id
+        """The run's id, as the run record and ``zuke resume`` name it."""
+        self.dry_run = dry_run
+        """Whether the run is a ``--dry-run``."""
+
+    @property
+    def state(self) -> StateHandle:
+        """This target's durable state."""
+        return StateHandle(self, None)
+
+    def state_of(self, target: str) -> StateHandle:
+        """Another target's durable state."""
+        return StateHandle(self, target)
+
+    async def outcome_of(self, target: str) -> Outcome | None:
+        """What ``target`` did in this run, or ``None`` if it has not run."""
+        answer = await self.call_("outcome.of", of=target)
+        return None if answer is None else _outcome(answer, "outcome.of")
+
+    async def outcomes(self) -> dict[str, Outcome]:
+        """What every settled target did in this run, by name."""
+        answer = record(await self.call_("outcomes"), "outcomes: the answer")
+        return {
+            name: _outcome(view, f"outcomes: {name}") for name, view in answer.items()
+        }
+
+    async def summary(self, pairs: Mapping[str, str | float]) -> None:
+        """Report notes into this target's row of the build summary."""
+        await self.call_("summary.report", pairs=dict(pairs))
+
+    async def plan(self) -> Plan:
+        """The run's plan: the planned targets and each one's dependencies."""
+        answer = record(await self.call_("plan"), "plan: the answer")
+        dependencies = record(answer.get("dependencies"), 'plan: "dependencies"')
+        return Plan(
+            targets=strings(answer, "targets", "plan"),
+            dependencies={
+                name: strings(dependencies, name, "plan") for name in dependencies
+            },
+        )
+
+    async def signals(self) -> dict[str, object]:
+        """The external signals this run has received, by name."""
+        return record(await self.call_("signals"), "signals: the answer")
+
+
+def _outcome(value: object, what: str) -> Outcome:
+    return Outcome(
+        status=string(value, "status", what),
+        error=string_or_none(value, "error", what),
+        started_at=string_or_none(value, "startedAt", what),
+        ended_at=string_or_none(value, "endedAt", what),
+    )