dirigent-client 0.9.0__py3-none-any.whl

dirigent_client/schemas/triggers.py

@@ -0,0 +1,208 @@
+"""A pipeline's persisted triggers: its schedules and its inbound webhooks."""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, Field, SecretStr, field_validator
+
+from dirigent_client.enums import (
+    FiringOutcome,
+    LogLevel,
+    ProvenanceSource,
+    RunPriority,
+    ScheduleKind,
+    WebhookOutcome,
+)
+from dirigent_client.schemas.common import WireModel
+from dirigent_common import EntityName, JsonMap
+from dirigent_common.durations import Duration
+
+
+class ScheduleIn(BaseModel):
+    """A schedule as a caller declares it: exactly one clock, in its own timezone."""
+
+    code: EntityName
+    name: str | None = None
+    description: str | None = None
+    cron: str | None = None
+    interval: Duration | None = None
+    at: datetime | None = None
+    timezone: str = "UTC"
+    params: JsonMap = Field(default_factory=dict)
+    connection_pins: JsonMap = Field(default_factory=dict)
+    log_levels: dict[str, LogLevel] | None = Field(
+        default=None,
+        description=(
+            "The log-level map every fired run carries, as block-id patterns; the most "
+            "specific pattern wins. Omitted keeps info and up."
+        ),
+    )
+    priority: RunPriority | None = Field(
+        default=None,
+        description="The priority every fired run carries. Omitted takes the pipeline's own.",
+    )
+
+    @field_validator("log_levels")
+    @classmethod
+    def _a_pattern_names_something(cls, value: dict[str, LogLevel] | None) -> dict[str, LogLevel] | None:
+        """Refuse an empty pattern, which would match nothing and say nothing."""
+        if value is not None and any(not pattern for pattern in value):
+            raise ValueError("log_levels: a pattern may not be empty")
+        return value
+
+
+class SchedulePreviewRequest(BaseModel):
+    """A clock as it is being written, for reading back what it would fire.
+
+    The three expressions are text rather than parsed values: a clock is previewed while it is
+    being typed, so a half-written interval is an answer saying what is wrong with it rather
+    than a request the server refuses to read.
+    """
+
+    cron: str | None = None
+    interval: str | None = None
+    at: str | None = None
+    timezone: str = "UTC"
+
+
+class SchedulePreview(WireModel):
+    """The next firings of a clock nothing has declared yet, oldest first."""
+
+    firings: list[datetime]
+
+
+class ScheduleOut(WireModel):
+    """A schedule as a listing shows it."""
+
+    id: UUID
+    code: str
+    name: str | None = None
+    description: str | None = None
+    kind: ScheduleKind
+    cron: str | None = None
+    interval: str | None = None
+    at: datetime | None = None
+    timezone: str
+    params: JsonMap = Field(default_factory=dict)
+    log_levels: dict[str, LogLevel] | None = None
+    priority: RunPriority | None = None
+    """The priority every fired run carries, or null when it takes the pipeline's own."""
+    paused: bool
+    managed: bool
+    trigger_document: str | None = None
+    """The triggers document that declares this row, or null when the pipeline's own does."""
+
+    next_fire_at: datetime | None = None
+    last_fired_at: datetime | None = None
+    created_at: datetime
+
+
+class FiringOut(WireModel):
+    """One recorded firing: what it was due for, and what came of it."""
+
+    id: int
+    scheduled_for: datetime
+    created_at: datetime
+    outcome: FiringOutcome
+    misfired: bool
+    run_id: UUID | None = None
+    detail: str | None = None
+
+
+class WebhookIn(BaseModel):
+    """A webhook as a caller declares it; the token is never supplied, only minted."""
+
+    code: EntityName
+    name: str | None = None
+    description: str | None = None
+    params_from_payload: dict[str, str] = Field(default_factory=dict[str, str])
+    hmac_secret: SecretStr | None = Field(default=None, min_length=1)
+    """The signing secret, or null for an unsigned webhook; an empty string is neither."""
+
+    rate_limit_per_minute: int = Field(default=60, ge=1)
+    priority: RunPriority | None = Field(
+        default=None,
+        description="The priority every accepted delivery's run carries. Omitted takes the pipeline's own.",
+    )
+
+
+class WebhookOut(WireModel):
+    """A webhook as a listing shows it: everything about it except the token."""
+
+    id: UUID
+    code: str
+    name: str | None = None
+    description: str | None = None
+    token_prefix: str
+    params_from_payload: dict[str, str] = Field(default_factory=dict[str, str])
+    signed: bool
+    """Whether this webhook requires an HMAC signature; the secret itself never leaves."""
+
+    active: bool
+    managed: bool
+    trigger_document: str | None = None
+    """The triggers document that declares this row, or null when the pipeline's own does."""
+
+    rate_limit_per_minute: int
+    priority: RunPriority | None = None
+    """The priority every accepted delivery's run carries, or null when it takes the pipeline's own."""
+
+    last_delivery_at: datetime | None = None
+    created_at: datetime
+
+
+class TriggerDocumentOut(WireModel):
+    """A ``kind: triggers`` document as a listing shows it."""
+
+    id: UUID
+    code: str
+    name: str | None = None
+    description: str | None = None
+    pipeline: str
+    """The code of the pipeline these triggers fire."""
+
+    digest: str
+    provenance_source: ProvenanceSource
+    provenance_ref: str | None = None
+    applied_by: str | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class TriggerDocumentDetail(TriggerDocumentOut):
+    """The document itself, and the rows it owns on the pipeline it names."""
+
+    document: JsonMap
+    schedules: list[str] = Field(default_factory=list[str])
+    webhooks: list[str] = Field(default_factory=list[str])
+
+
+class WebhookTokenOut(WireModel):
+    """A freshly minted webhook token, returned once and never readable again."""
+
+    webhook_id: UUID
+    code: str
+    token: str
+    prefix: str
+    url_path: str
+    """Where to POST, so a caller can be configured without assembling the path by hand."""
+
+
+class HookAccepted(WireModel):
+    """What an accepted delivery answers with: the run it started, or why it started none."""
+
+    run_id: UUID | None = None
+    outcome: WebhookOutcome
+    detail: str | None = None
+
+
+class DeliveryOut(WireModel):
+    """One inbound delivery, and what came of it."""
+
+    id: int
+    created_at: datetime
+    outcome: WebhookOutcome
+    run_id: UUID | None = None
+    reason: str | None = None
+    mapped_params: JsonMap | None = None
+    source: str | None = None

dirigent_client/transport.py

@@ -0,0 +1,191 @@
+"""The one place a request is made, authenticated, retried, and turned into an exception."""
+
+import asyncio
+from collections.abc import AsyncGenerator, Mapping
+from contextlib import asynccontextmanager
+from typing import Any, Final, Self
+
+import httpx2
+
+from dirigent_client.errors import (
+    VERSION_HEADER,
+    DirigentError,
+    NotDirigent,
+    TransportError,
+    error_for,
+    parse_problem,
+)
+
+#: Where the API is unless an instance says otherwise. A server that sets ``api_prefix``
+#: serves it somewhere else, and a connection has to be told the same thing.
+API_PREFIX: Final = "/api/v1"
+
+
+def _normalise_prefix(prefix: str) -> str:
+    """Spell a prefix the one way the server spells it: a leading slash, no trailing one.
+
+    The server normalises its own setting the same way, so a connection configured by hand
+    with "api/v1" or "/api/v1/" addresses the same instance as one configured with neither.
+    """
+    trimmed = prefix.strip().strip("/")
+    return f"/{trimmed}" if trimmed else ""
+
+
+DEFAULT_TIMEOUT: Final = 30.0
+DEFAULT_RETRIES: Final = 2
+BACKOFF_SECONDS: Final = 0.25
+BACKOFF_MAX_SECONDS: Final = 4.0
+
+#: A POST or a PATCH can have taken effect before the connection broke, so repeating one
+#: risks a second run, a second token, a second account.
+IDEMPOTENT_METHODS: Final = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
+
+
+def backoff_for(attempt: int) -> float:
+    """Say how long to wait before the given retry."""
+    return min(BACKOFF_SECONDS * 2.0**attempt, BACKOFF_MAX_SECONDS)
+
+
+def _retry_after(response: httpx2.Response) -> float | None:
+    """Read a Retry-After header as seconds, ignoring the HTTP-date spelling of it."""
+    raw: str | None = response.headers.get("retry-after")
+    if raw is None:
+        return None
+    try:
+        return float(raw)
+    except ValueError:
+        return None
+
+
+class Transport:
+    """An authenticated connection to one 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 pool bound to one base URL and one credential."""
+        self.url = url.rstrip("/")
+        self.api_prefix = _normalise_prefix(api_prefix)
+        self.retries = retries
+        sent = {**(headers or {})}
+        if token:
+            sent["Authorization"] = f"Bearer {token}"
+        self._client = httpx2.AsyncClient(
+            base_url=self.url,
+            headers=sent,
+            timeout=timeout,
+            transport=http_transport,
+        )
+
+    def session_cookie(self, name: str) -> str | None:
+        """Read a cookie the instance set on this connection, or report that it set none."""
+        return self._client.cookies.get(name)
+
+    def present(self, secret: str) -> None:
+        """Present this credential on every later request of this connection.
+
+        A session arrives as a cookie, and a cookie the instance marked ``Secure`` is never
+        sent back over plain HTTP -- so a client that relied on the jar could log in and then
+        be refused by the next call. A client is not a browser: it holds the credential
+        either way, and presenting it as a bearer token is what makes a session usable
+        wherever a token is.
+        """
+        self._client.headers["Authorization"] = f"Bearer {secret}"
+
+    async def __aenter__(self) -> Self:
+        """Enter the connection'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._client.aclose()
+
+    def endpoint(self, path: str, *, prefixed: bool = True) -> str:
+        """Render one API path as the absolute URL it is fetched from."""
+        return f"{self.url}{self.api_prefix if prefixed else ''}{path}"
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        timeout: float | None = None,
+        prefixed: bool = True,
+        accept: tuple[int, ...] = (),
+        **kwargs: Any,
+    ) -> httpx2.Response:
+        """Make one authenticated request, retrying what is safe and raising what is not."""
+        target = f"{self.api_prefix if prefixed else ''}{path}"
+        sent: dict[str, Any] = dict(kwargs)
+        if timeout is not None:
+            sent["timeout"] = timeout
+        retryable = method.upper() in IDEMPOTENT_METHODS
+        attempts = self.retries + 1 if retryable else 1
+        for attempt in range(attempts):
+            last = attempt == attempts - 1
+            try:
+                response = await self._client.request(method, target, **sent)
+            except httpx2.HTTPError as error:
+                if last:
+                    raise TransportError(self.url, error) from error
+                await asyncio.sleep(backoff_for(attempt))
+                continue
+            if response.status_code in accept:
+                return response
+            if response.status_code >= 500 and not last:
+                await response.aclose()
+                await asyncio.sleep(backoff_for(attempt))
+                continue
+            if response.status_code >= 400:
+                raise self._refusal(response, target)
+            return response
+        raise DirigentError("the request was never made", url=self.endpoint(path))  # pragma: no cover
+
+    def _refusal(self, response: httpx2.Response, target: str) -> DirigentError:
+        """Turn an error response into the exception its status and body deserve."""
+        if VERSION_HEADER not in response.headers:
+            return NotDirigent(self.url, target, response.headers.get("content-type", ""))
+        try:
+            payload: object = response.json()
+        except ValueError:
+            payload = None
+        return error_for(
+            response.status_code,
+            f"{self.url}{target}",
+            parse_problem(payload),
+            retry_after=_retry_after(response),
+        )
+
+    async def json(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Make one request and return its parsed body, or nothing when it answered 204."""
+        response = await self.request(method, path, **kwargs)
+        return None if response.status_code == 204 else response.json()
+
+    async def text(self, path: str, **kwargs: Any) -> str:
+        """GET a path that answers with text rather than JSON, such as an export."""
+        return (await self.request("GET", path, **kwargs)).text
+
+    @asynccontextmanager
+    async def stream(self, path: str, **kwargs: Any) -> AsyncGenerator[httpx2.Response]:
+        """Open a streaming GET, held open for as long as the caller reads it."""
+        target = f"{self.api_prefix}{path}"
+        try:
+            async with self._client.stream("GET", target, timeout=None, **kwargs) as response:
+                if response.status_code >= 400:
+                    await response.aread()
+                    raise self._refusal(response, target)
+                yield response
+        except httpx2.HTTPError as error:
+            raise TransportError(self.url, error) from error

dirigent_client-0.9.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,34 @@
+dirigent_client/__init__.py,sha256=HEhLHTVb0awp1PfJiJBwnJecSDVAQaXSv4bgW9tuICs,4114
+dirigent_client/client.py,sha256=XXPH8Th6aHWqR40cvVWvUPz81WnJVmm8OcRxIf89LPU,5408
+dirigent_client/enums.py,sha256=54XXZvmMx9ejXzXF_mxpp6HILmecCon2Ib5WgYR0Ql0,5543
+dirigent_client/errors.py,sha256=gf3EFi7DeB9ZYYLJUsKRaackbQHn0WWim2XmipkrL9U,5112
+dirigent_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dirigent_client/resources/__init__.py,sha256=Ju5AWYzraLSqLbvOR2QKUBB71FWtW6C0VbejPONUs94,85
+dirigent_client/resources/alerts.py,sha256=UJSbygTMZYWmBjvuuKp_vZqfFe8ccw8guQHUzarVouU,3889
+dirigent_client/resources/auth.py,sha256=upCTGhpf5eHqsyKQgN9YXvnCfvfx2iEVNZ5dQ3v7bP0,6582
+dirigent_client/resources/base.py,sha256=OV-5_7VKaGg_sRqhpSvggvtW6MJNcVqubzLhXkFsVz4,2319
+dirigent_client/resources/blocks.py,sha256=D1V-AMSKICGaSiykALMjCXe6Drpo_rw7O5V4aUJxZGc,824
+dirigent_client/resources/connections.py,sha256=pNWd-XT6EexSNHwtLfTvx5ICjhzjWdi2dyAyzbN8LjI,2326
+dirigent_client/resources/pipelines.py,sha256=V3ny5VMR0_PkR0SPl6WLX8Cu0mLjyPzr1XM7PbAnGMk,8467
+dirigent_client/resources/runs.py,sha256=OmdX9sqGM4ljl4y__MZpn73PvPWTQoQvVlitnFH3huo,9937
+dirigent_client/resources/schedules.py,sha256=LS8mEayld3oWN__YnjuF-X5fZb3Xtr4B9vEjGVLAAWc,4955
+dirigent_client/resources/schemas.py,sha256=x4as80oc5N2MijjqHAkSHjZvabrmyVUPIo9kRaQmBuA,1854
+dirigent_client/resources/system.py,sha256=WrcwNVjXmX_iaoHNVrawUmpoUjzOFozw9VTyHgBkfP8,1574
+dirigent_client/resources/trigger_documents.py,sha256=fnEooykY36R-vSUWeC01HoBKpso5RzK6L2ayBQYI9Dw,1071
+dirigent_client/resources/webhooks.py,sha256=LAZ6wbx6MjrJmhvdStohuQazynIzYup1h68bdxLzmkk,3548
+dirigent_client/schemas/__init__.py,sha256=PW_EXk2_1jEL1KiniS_MCK_74WAPQcHdEeTgOdQ5maQ,3412
+dirigent_client/schemas/alerts.py,sha256=Oxy0DpxRYPZ1UfR7hLiLCegnui5-FYJlSTED8NQnURg,2468
+dirigent_client/schemas/auth.py,sha256=4oQtgrwXCLL0uW77Dn29frAl9S3WqA3HGm2gR5jtdxM,3171
+dirigent_client/schemas/catalog.py,sha256=KGCBeOKUcZ6moSiPGym3N_qhOZoZryI75lFmtwfPHOA,2328
+dirigent_client/schemas/common.py,sha256=Zbdr9BOCA2fYjTMey7vA3k2vhuT9BDJp1CRCl3gWht8,1171
+dirigent_client/schemas/connections.py,sha256=2CBN2VkMvdJ6R0L4pMg983P9bvIDqbb9oPhAx1cWsvs,1895
+dirigent_client/schemas/pipelines.py,sha256=aekxsXFzKgGf25TMppqzCkKLLGM98LAlNfk43rAGTn4,11768
+dirigent_client/schemas/runs.py,sha256=_g62IK_g0LNLy6j67SFjkBH67DYQboBc8pLgio62wsE,6017
+dirigent_client/schemas/schemas.py,sha256=m5MFJxFTMzBubpNfnDkeTOwG6Q4ZS-qGIVSRUsRSL1s,1908
+dirigent_client/schemas/system.py,sha256=iLUxsq8XoYrqgj-UN4q5fNAUkSECJLLpYHFuvgla5k4,2823
+dirigent_client/schemas/triggers.py,sha256=nS7c-xFpL7kHDFR7JpmdFt7vcRaGWMpcgfWqAX--xVM,6489
+dirigent_client/transport.py,sha256=E1jxuqoiwVoRoDE2rJF8eiRYNe2rk7gVoIMUp4i7_zw,7397
+dirigent_client-0.9.0.dist-info/licenses/LICENSE,sha256=LKBm7Cx-WBc1zca4DjGxq99VEpAiWGnZDxIKmntn1hQ,910
+dirigent_client-0.9.0.dist-info/WHEEL,sha256=mru_b36sH6joUMnwf7IlFCun3RoDjrNg9RcfBmEcqsE,81
+dirigent_client-0.9.0.dist-info/METADATA,sha256=T4GYrcnOOtFmWGzdIqyBg99whB0v4fySng5VVW-XU8o,1366
+dirigent_client-0.9.0.dist-info/RECORD,,

dirigent_client-0.9.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.11
+Root-Is-Purelib: true
+Tag: py3-none-any

dirigent_client-0.9.0.dist-info/licenses/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.