dirigent-client 0.9.0__tar.gz

dirigent_client-0.9.0/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 Morten Olav Hansen <morten@winterop.com>. All rights reserved.
+
+This source code and accompanying documentation are the property of
+Morten Olav Hansen. No license, express or implied, is granted to use, copy,
+modify, merge, publish, distribute, sublicense, or sell copies of this
+software or its derivatives.
+
+The source is published for reference only. Any use beyond reading
+requires written permission from the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES,
+OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.
+
+Third-party components redistributed with this software, and the licences they
+carry, are listed in THIRD_PARTY_NOTICES.md.

dirigent_client-0.9.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: dirigent-client
+Version: 0.9.0
+Summary: The dirigent API contract: typed wire schemas and an async Python client.
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Requires-Dist: dirigent-common
+Requires-Dist: httpx2>=2.12.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# dirigent-client
+
+The dirigent API contract: typed wire schemas and an async Python client.
+
+```python
+from datetime import timedelta
+
+from dirigent_client import Dirigent
+
+async with Dirigent(url="https://dirigent.example.org", token=token) as dg:
+    plan = await dg.pipelines.apply("pipelines/daily-climate-load.yaml", dry_run=True)
+    run = await dg.pipelines.run("daily-climate-load", params={"day": "2026-08-29"})
+    final = await dg.runs.wait(run.run_id, timeout=timedelta(hours=2))
+    async for entry in dg.runs.follow_logs(run.run_id):
+        print(entry.message)
+```
+
+The package holds the pydantic schemas for every request and response the REST API speaks,
+and `dirigent-server` imports them, so the client and the server can never disagree about a
+shape. It depends on `dirigent-common`, `httpx2`, `pydantic`, and `pyyaml`, and on nothing else in the
+workspace.
+
+`docs/python.md` has the worked examples, and `examples/python/` has six runnable scripts.

dirigent_client-0.9.0/README.md

@@ -0,0 +1,23 @@
+# dirigent-client
+
+The dirigent API contract: typed wire schemas and an async Python client.
+
+```python
+from datetime import timedelta
+
+from dirigent_client import Dirigent
+
+async with Dirigent(url="https://dirigent.example.org", token=token) as dg:
+    plan = await dg.pipelines.apply("pipelines/daily-climate-load.yaml", dry_run=True)
+    run = await dg.pipelines.run("daily-climate-load", params={"day": "2026-08-29"})
+    final = await dg.runs.wait(run.run_id, timeout=timedelta(hours=2))
+    async for entry in dg.runs.follow_logs(run.run_id):
+        print(entry.message)
+```
+
+The package holds the pydantic schemas for every request and response the REST API speaks,
+and `dirigent-server` imports them, so the client and the server can never disagree about a
+shape. It depends on `dirigent-common`, `httpx2`, `pydantic`, and `pyyaml`, and on nothing else in the
+workspace.
+
+`docs/python.md` has the worked examples, and `examples/python/` has six runnable scripts.

dirigent_client-0.9.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "dirigent-client"
+version = "0.9.0"
+description = "The dirigent API contract: typed wire schemas and an async Python client."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+dependencies = [
+    "dirigent-common",
+    "httpx2>=2.12.0",
+    "pydantic>=2.13.5",
+    "pyyaml>=6.0.3",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]

dirigent_client-0.9.0/pyproject.toml.orig

@@ -0,0 +1,20 @@
+[project]
+name = "dirigent-client"
+version = "0.9.0"
+description = "The dirigent API contract: typed wire schemas and an async Python client."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+dependencies = [
+    "dirigent-common",
+    "httpx2>=2.12.0",
+    "pydantic>=2.13.5",
+    "pyyaml>=6.0.3",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]

dirigent_client-0.9.0/src/dirigent_client/__init__.py

@@ -0,0 +1,219 @@
+"""The dirigent API contract: typed wire schemas, and an async client over them."""
+
+from dirigent_client.client import BlockingDirigent, Dirigent
+from dirigent_client.enums import (
+    AlertEvent,
+    AlertScope,
+    AttemptKind,
+    AttemptStatus,
+    DocumentKind,
+    FiringOutcome,
+    LogLevel,
+    NotificationStatus,
+    ProvenanceSource,
+    RunItemStatus,
+    RunPriority,
+    RunStatus,
+    ScheduleKind,
+    TokenKind,
+    TriggerKind,
+    UserRole,
+    WebhookOutcome,
+    WorkerStatus,
+)
+from dirigent_client.errors import (
+    VERSION_HEADER,
+    Conflict,
+    DirigentError,
+    Forbidden,
+    NotDirigent,
+    NotFound,
+    RateLimited,
+    ServerError,
+    TransportError,
+    Unauthorized,
+    ValidationFailed,
+    WaitTimeout,
+)
+from dirigent_client.schemas import (
+    TERMINAL_RUN_STATUSES,
+    AlertRuleIn,
+    AlertRuleOut,
+    ApplyRequest,
+    ApplyResult,
+    AttemptEvent,
+    AttemptOut,
+    BackfillAccepted,
+    BackfilledRun,
+    BackfillRequest,
+    BlockEntry,
+    BlockKind,
+    Catalog,
+    CheckResult,
+    CheckStatus,
+    ConnectionHealth,
+    ConnectionIn,
+    ConnectionOut,
+    ConnectionUpdate,
+    DagNode,
+    DagView,
+    DeliveryOut,
+    DiffSummary,
+    FiringOut,
+    Health,
+    HookAccepted,
+    Identity,
+    IssuedTokenOut,
+    ItemOut,
+    JsonList,
+    JsonMap,
+    LogEntryOut,
+    LoginRequest,
+    Materialized,
+    NotificationOut,
+    Page,
+    PipelineDetail,
+    PipelineOut,
+    PipelinePlan,
+    PipelineVersionOut,
+    PlanAction,
+    Problem,
+    Readiness,
+    RunAccepted,
+    RunDetail,
+    RunOut,
+    RunReport,
+    RunRequest,
+    ScheduleIn,
+    ScheduleOut,
+    SchedulePreview,
+    SchedulePreviewRequest,
+    SchemaIn,
+    SchemaOut,
+    SchemaUpdate,
+    StepReport,
+    SurfaceEntry,
+    SystemInfo,
+    TestQueued,
+    TestRequest,
+    TokenOut,
+    TokenRequest,
+    TriggerDocumentDetail,
+    TriggerDocumentOut,
+    UserIn,
+    UserOut,
+    ValidationIssue,
+    WebhookIn,
+    WebhookOut,
+    WebhookTokenOut,
+    WorkerOut,
+)
+from dirigent_client.transport import API_PREFIX, Transport
+
+__all__ = [
+    "API_PREFIX",
+    "TERMINAL_RUN_STATUSES",
+    "VERSION_HEADER",
+    "AlertEvent",
+    "AlertRuleIn",
+    "AlertRuleOut",
+    "AlertScope",
+    "ApplyRequest",
+    "ApplyResult",
+    "BackfillAccepted",
+    "BackfillRequest",
+    "BackfilledRun",
+    "AttemptKind",
+    "AttemptEvent",
+    "AttemptOut",
+    "AttemptStatus",
+    "BlockEntry",
+    "BlockKind",
+    "BlockingDirigent",
+    "Catalog",
+    "CheckResult",
+    "CheckStatus",
+    "Conflict",
+    "ConnectionHealth",
+    "ConnectionIn",
+    "ConnectionOut",
+    "ConnectionUpdate",
+    "SchemaIn",
+    "SchemaOut",
+    "SchemaUpdate",
+    "DagNode",
+    "DagView",
+    "DocumentKind",
+    "DeliveryOut",
+    "DiffSummary",
+    "Dirigent",
+    "DirigentError",
+    "FiringOut",
+    "FiringOutcome",
+    "Forbidden",
+    "Health",
+    "HookAccepted",
+    "Identity",
+    "IssuedTokenOut",
+    "ItemOut",
+    "JsonList",
+    "JsonMap",
+    "LogEntryOut",
+    "LogLevel",
+    "LoginRequest",
+    "Materialized",
+    "NotDirigent",
+    "NotFound",
+    "NotificationOut",
+    "NotificationStatus",
+    "Page",
+    "PipelineDetail",
+    "PipelineOut",
+    "PipelinePlan",
+    "PipelineVersionOut",
+    "PlanAction",
+    "Problem",
+    "ProvenanceSource",
+    "RateLimited",
+    "Readiness",
+    "RunAccepted",
+    "RunDetail",
+    "RunItemStatus",
+    "RunOut",
+    "RunPriority",
+    "RunReport",
+    "RunRequest",
+    "RunStatus",
+    "ScheduleIn",
+    "ScheduleKind",
+    "ScheduleOut",
+    "SchedulePreview",
+    "SchedulePreviewRequest",
+    "ServerError",
+    "StepReport",
+    "SurfaceEntry",
+    "SystemInfo",
+    "TestQueued",
+    "TestRequest",
+    "TokenKind",
+    "TokenOut",
+    "TokenRequest",
+    "TriggerDocumentDetail",
+    "TriggerDocumentOut",
+    "Transport",
+    "TransportError",
+    "TriggerKind",
+    "Unauthorized",
+    "UserIn",
+    "UserOut",
+    "UserRole",
+    "ValidationFailed",
+    "ValidationIssue",
+    "WaitTimeout",
+    "WebhookIn",
+    "WebhookOut",
+    "WebhookOutcome",
+    "WebhookTokenOut",
+    "WorkerOut",
+    "WorkerStatus",
+]

dirigent_client-0.9.0/src/dirigent_client/client.py

@@ -0,0 +1,143 @@
+"""The client itself: one connection, and one namespaced accessor per API resource."""
+
+import asyncio
+import threading
+from collections.abc import AsyncIterator, Awaitable, Iterator, Mapping
+from typing import Any, Self
+
+import httpx2
+
+from dirigent_client.resources.alerts import Alerts
+from dirigent_client.resources.auth import Admin, Auth
+from dirigent_client.resources.blocks import Blocks
+from dirigent_client.resources.connections import Connections
+from dirigent_client.resources.pipelines import Pipelines
+from dirigent_client.resources.runs import Runs
+from dirigent_client.resources.schedules import Schedules
+from dirigent_client.resources.schemas import Schemas
+from dirigent_client.resources.system import System, Workers
+from dirigent_client.resources.trigger_documents import TriggerDocuments
+from dirigent_client.resources.webhooks import Webhooks
+from dirigent_client.transport import API_PREFIX, DEFAULT_RETRIES, DEFAULT_TIMEOUT, Transport
+
+SHUTDOWN_SECONDS = 5.0
+
+
+class Dirigent:
+    """An authenticated connection to one dirigent instance."""
+
+    def __init__(
+        self,
+        *,
+        url: str,
+        token: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+        headers: Mapping[str, str] | None = None,
+        http_transport: httpx2.AsyncBaseTransport | None = None,
+        api_prefix: str = API_PREFIX,
+    ) -> None:
+        """Open a connection to an instance, with a bearer token when one is needed."""
+        self.transport = Transport(
+            url=url,
+            api_prefix=api_prefix,
+            token=token,
+            timeout=timeout,
+            retries=retries,
+            headers=headers,
+            http_transport=http_transport,
+        )
+        self.pipelines = Pipelines(self.transport)
+        self.runs = Runs(self.transport)
+        self.connections = Connections(self.transport)
+        self.schemas = Schemas(self.transport)
+        self.blocks = Blocks(self.transport)
+        self.schedules = Schedules(self.transport)
+        self.webhooks = Webhooks(self.transport)
+        self.trigger_documents = TriggerDocuments(self.transport)
+        self.alerts = Alerts(self.transport)
+        self.system = System(self.transport)
+        self.workers = Workers(self.transport)
+        self.auth = Auth(self.transport)
+        self.admin = Admin(self.transport)
+
+    @property
+    def url(self) -> str:
+        """Name the instance this client is bound to."""
+        return self.transport.url
+
+    async def __aenter__(self) -> Self:
+        """Enter the client's context."""
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        """Close the underlying connection pool."""
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying connection pool."""
+        await self.transport.aclose()
+
+
+class BlockingDirigent:
+    """The same client, driven from synchronous code."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Open a connection and the loop its calls run on; the arguments are Dirigent's."""
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._loop.run_forever, name="dirigent-client", daemon=True)
+        self._thread.start()
+        self.client = Dirigent(**kwargs)
+        self.url = self.client.url
+        self.pipelines = self.client.pipelines
+        self.runs = self.client.runs
+        self.connections = self.client.connections
+        self.schemas = self.client.schemas
+        self.blocks = self.client.blocks
+        self.schedules = self.client.schedules
+        self.webhooks = self.client.webhooks
+        self.trigger_documents = self.client.trigger_documents
+        self.alerts = self.client.alerts
+        self.system = self.client.system
+        self.workers = self.client.workers
+        self.auth = self.client.auth
+        self.admin = self.client.admin
+
+    def __enter__(self) -> Self:
+        """Enter the client's context."""
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        """Close the connection pool and stop the loop."""
+        self.close()
+
+    def call[T](self, awaitable: Awaitable[T]) -> T:
+        """Run one of the client's coroutines to completion and return what it produced."""
+        return asyncio.run_coroutine_threadsafe(_awaited(awaitable), self._loop).result()
+
+    def iterate[T](self, source: AsyncIterator[T]) -> Iterator[T]:
+        """Read an async iterator, such as a log tail, as an ordinary one."""
+        while True:
+            try:
+                yield self.call(anext(source))
+            except StopAsyncIteration:
+                return
+
+    def close(self) -> None:
+        """Close the connection pool and stop the loop it was running on.
+
+        The asynchronous generators must be shut down before the loop is: a generator
+        finalised after its loop has closed raises where nobody is listening.
+        """
+        try:
+            self.call(self.client.aclose())
+            self.call(self._loop.shutdown_asyncgens())
+        finally:
+            self._loop.call_soon_threadsafe(self._loop.stop)
+            self._thread.join(timeout=SHUTDOWN_SECONDS)
+            self._loop.close()
+
+
+async def _awaited[T](awaitable: Awaitable[T]) -> T:
+    """Wrap an awaitable as the coroutine ``run_coroutine_threadsafe`` requires."""
+    return await awaitable

dirigent_client-0.9.0/src/dirigent_client/enums.py

@@ -0,0 +1,215 @@
+"""The closed vocabularies the engine's state machines are built from."""
+
+from enum import StrEnum
+
+
+class RunStatus(StrEnum):
+    """Where a run is."""
+
+    QUEUED = "queued"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    COMPLETED_WITH_ERRORS = "completed_with_errors"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class AttemptStatus(StrEnum):
+    """The step-attempt state machine."""
+
+    PENDING = "pending"
+    """Waiting on its depends_on edges; not yet claimable."""
+
+    QUEUED = "queued"
+    """Claimable once available_at has passed."""
+
+    RUNNING = "running"
+    """Claimed by a worker, holding a lease."""
+
+    WAITING = "waiting"
+    """Not on a worker: parked with a remote handle or a pending poke, re-examined when
+    next_poll_at is due."""
+
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+    CANCELLED = "cancelled"
+
+
+class AttemptKind(StrEnum):
+    """Whether the engine created an attempt or an operator asked for it."""
+
+    AUTOMATIC = "automatic"
+    MANUAL = "manual"
+
+
+class RunItemStatus(StrEnum):
+    """Per-item status of a fan-out step."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+class RunPriority(StrEnum):
+    """How far ahead of the other runs a run's attempts are claimed."""
+
+    LOW = "low"
+    """Claimed after everything else, which is where a bulk job belongs."""
+
+    NORMAL = "normal"
+
+    HIGH = "high"
+    """Claimed before any other run's attempts, the moment a slot frees."""
+
+
+#: What each priority is worth to the claim's sort, highest first.
+PRIORITY_RANK: dict[RunPriority, int] = {RunPriority.LOW: 0, RunPriority.NORMAL: 1, RunPriority.HIGH: 2}
+
+
+class TriggerKind(StrEnum):
+    """What started a run."""
+
+    ADHOC = "adhoc"
+    SCHEDULE = "schedule"
+    WEBHOOK = "webhook"
+    API_TOKEN = "api_token"
+    USER = "user"
+    PIPELINE = "pipeline"
+    """A step of another run started this one, and ``triggered_by_id`` names that run."""
+
+    BACKFILL = "backfill"
+    """A backfill over past windows created this one, and ``triggered_by_id`` names the schedule."""
+
+
+class ScheduleKind(StrEnum):
+    """How a schedule computes its next firing."""
+
+    CRON = "cron"
+    INTERVAL = "interval"
+    ONE_TIME = "one_time"
+
+
+class AlertEvent(StrEnum):
+    """The run-level events an alert rule may bind to."""
+
+    RUN_FAILED = "run_failed"
+    RUN_COMPLETED_WITH_ERRORS = "run_completed_with_errors"
+    RUN_SUCCEEDED = "run_succeeded"
+    RUN_STUCK = "run_stuck"
+
+
+class AlertScope(StrEnum):
+    """Whether an alert rule watches everything or one pipeline."""
+
+    GLOBAL = "global"
+    PIPELINE = "pipeline"
+
+
+class NotificationStatus(StrEnum):
+    """Where one queued alert delivery is."""
+
+    PENDING = "pending"
+    """Queued and claimable once available_at has passed."""
+
+    SENDING = "sending"
+    """Claimed by a worker, holding a lease."""
+
+    SENT = "sent"
+    """The notifier accepted it."""
+
+    FAILED = "failed"
+    """Terminally undeliverable: the retry budget is gone, and the error is on the row."""
+
+
+class FiringOutcome(StrEnum):
+    """What one scheduler tick decided about one due schedule."""
+
+    FIRED = "fired"
+    """A run was created and is executing."""
+
+    QUEUED = "queued"
+    """A run was created but is held behind the one already in flight."""
+
+    REPLACED = "replaced"
+    """The run in flight was cancelled and a new one took its place."""
+
+    SKIPPED = "skipped"
+    """The concurrency policy dropped this firing; the run in flight is enough."""
+
+    FAILED = "failed"
+    """The run could not be created at all, and the reason is on the row."""
+
+
+class WebhookOutcome(StrEnum):
+    """What the intake endpoint did with one delivery."""
+
+    ACCEPTED = "accepted"
+    """The payload mapped, validated, and started a run."""
+
+    SKIPPED = "skipped"
+    """The payload was good, but the pipeline's concurrency policy dropped the run."""
+
+    REJECTED = "rejected"
+    """The delivery was refused, and the reason is on the row."""
+
+
+class LogLevel(StrEnum):
+    """Severity of a product log entry, which is separate from process logging."""
+
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class DocumentKind(StrEnum):
+    """Which kind of ``dirigent/v1`` document an apply carried."""
+
+    PIPELINE = "pipeline"
+    TRIGGERS = "triggers"
+    """Clocks and webhooks for a pipeline defined somewhere else."""
+
+
+class ProvenanceSource(StrEnum):
+    """Where a pipeline version came from, recorded when it is applied."""
+
+    UI = "ui"
+    FILE = "file"
+    URL = "url"
+    API = "api"
+    DIRECTORY = "directory"
+
+
+class UserRole(StrEnum):
+    """What an account may do."""
+
+    ADMIN = "admin"
+    """Full access: definitions, connections, runs, users, and tokens."""
+
+    OPERATOR = "operator"
+    """Define, apply, run, cancel and schedule, but not manage accounts, tokens or connections."""
+
+    VIEWER = "viewer"
+    """Read-only: every listing, run, log and report, and nothing that writes."""
+
+
+class TokenKind(StrEnum):
+    """Whether a stored credential is an automation token or a browser session."""
+
+    API = "api"
+    """A bearer token an operator created for a script or a CI job."""
+
+    SESSION = "session"
+    """A cookie-borne session minted by a login, expiring on its own."""
+
+
+class WorkerStatus(StrEnum):
+    """What the worker registry last heard from a node."""
+
+    STARTING = "starting"
+    RUNNING = "running"
+    DRAINING = "draining"
+    STOPPED = "stopped"