printobserver-sdk 0.2.0__py3-none-any.whl

printobserver_sdk/__init__.py

@@ -0,0 +1,54 @@
+"""The typed Python client of the printobserver server's HTTP surface.
+
+One method per public operation the server declares, generated from the same
+checked-in schemas the server's own routes are folded out of — so this client
+and the command-line program expose the same normalized surface because they
+come from one description rather than because somebody kept two lists aligned.
+
+`printobserver_sdk.contract` carries the request and response types those
+methods take and answer, and is generated. Nothing in it is written by hand,
+and `just check-generated` refuses a tree in which it differs from what the
+generator writes.
+
+A refused action is an answer rather than a failure of transport: it arrives as
+`RejectedError`, carrying the reason, the value asked for and the range allowed, so
+a caller can ask again for something inside the range.
+
+Images are a path, never bytes. No method here answers image bytes or an
+encoding of them; the server answers an absolute path on **its own** filesystem
+and this client hands that path back exactly as it was answered.
+
+    from printobserver_sdk import Client
+
+    client = Client("http://127.0.0.1:8420", "operator")
+    status = client.status("0198f0a1-2b3c-7d4e-8f90-123456789abc")
+"""
+
+from __future__ import annotations
+
+from printobserver_sdk._client import Client
+from printobserver_sdk._surface import (
+    ClientError,
+    NoReasonError,
+    PrinterRefusedError,
+    RefusedError,
+    RejectedError,
+    UnreachableError,
+    UnreadableError,
+    reason_given,
+)
+from printobserver_sdk.contract import CONTRACT_VERSION, OPERATION_NAMES
+
+__all__ = [
+    "CONTRACT_VERSION",
+    "OPERATION_NAMES",
+    "Client",
+    "ClientError",
+    "NoReasonError",
+    "PrinterRefusedError",
+    "RefusedError",
+    "RejectedError",
+    "UnreachableError",
+    "UnreadableError",
+    "reason_given",
+]

printobserver_sdk/_client.py

@@ -0,0 +1,189 @@
+"""The client every generated method is a method of.
+
+It carries three things and no more: where the supervisor is, what
+authenticates to it, and who this client acts as. The third is why no generated
+method takes an actor: a call cannot act as somebody the client is not.
+
+The one request this makes is written with the standard library's own HTTP
+client rather than with a dependency. This client speaks to a supervisor over a
+loopback or a local network — the supervisor is the thing beside the printer —
+and a package a supervision tool takes as a dependency is better without a
+transport stack of its own.
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+from typing import cast
+from urllib.parse import quote, urlsplit
+
+from printobserver_sdk._surface import (
+    NoReasonError,
+    PrinterRefusedError,
+    RefusedError,
+    RejectedError,
+    UnreachableError,
+    UnreadableError,
+)
+from printobserver_sdk.contract import (
+    ActionAnswer,
+    Actor,
+    GeneratedClient,
+    Range,
+    RejectionReasonOutOfBoundsPayload,
+)
+
+#: The status a rejected action is answered under.
+REJECTED_STATUS = 409
+
+#: The status an action the machine itself refused is answered under.
+MACHINE_REFUSED_STATUS = 502
+
+#: The status a read or a write that was carried out is answered under.
+SUCCESS_STATUS = 200
+
+#: The media type every operation takes a body in and answers in.
+MEDIA_TYPE = "application/json"
+
+#: How long one request waits, in seconds.
+TIMEOUT_SECONDS = 30.0
+
+
+class Client(GeneratedClient):
+    """A typed client of one printobserver supervisor.
+
+    One method per public operation that supervisor serves, each generated from
+    the same checked-in description the server's own routes are folded out of.
+    """
+
+    def __init__(self, server: str, actor: Actor, credential: str | None = None) -> None:
+        """Point this client at one supervisor, acting as one actor.
+
+        Args:
+            server: Where the supervisor answers, as its own configuration
+                writes it — `http://127.0.0.1:8420` — or as a bare `host:port`.
+            actor: Who this client acts as.
+            credential: What authenticates to it. This server requires none of
+                its API callers; a credential is for a deployment that has put
+                something in front of it that does.
+        """
+        self.address = _address(server)
+        self.actor = actor
+        self.credential = credential
+
+    def call(
+        self,
+        method: str,
+        target: str,
+        asked: list[tuple[str, str]],
+        sending: dict[str, object] | None,
+    ) -> object:
+        """Make one call and answer the document that came back.
+
+        Returns:
+            The document the supervisor answered, parsed.
+
+        Raises:
+            UnreachableError: If nothing answered at the configured address.
+            UnreadableError: If the answer is not a document this client can read.
+            RefusedError: If the supervisor will not do what it was asked.
+            PrinterRefusedError: If the policy accepted the action and the machine
+                refused it.
+            RejectedError: If the policy refused the action.
+        """
+        headers = {"Accept": MEDIA_TYPE}
+        body = None
+        if sending is not None:
+            body = json.dumps(sending)
+            headers["Content-Type"] = MEDIA_TYPE
+        if self.credential is not None:
+            headers["Authorization"] = f"Bearer {self.credential}"
+
+        connection = http.client.HTTPConnection(self.address, timeout=TIMEOUT_SECONDS)
+        try:
+            connection.request(method, _target(target, asked), body=body, headers=headers)
+            answered = connection.getresponse()
+            status = answered.status
+            said = answered.read().decode("utf-8", errors="replace")
+        except OSError as unreachable:
+            raise UnreachableError(self.address, str(unreachable)) from unreachable
+        finally:
+            connection.close()
+
+        if status == SUCCESS_STATUS:
+            return _document(status, said)
+        if status == REJECTED_STATUS:
+            raise _rejection(status, said)
+        if status == MACHINE_REFUSED_STATUS:
+            raise _machine_refusal(status, said)
+        raise RefusedError(status, _said(said))
+
+
+def _address(server: str) -> str:
+    """One supervisor's address, as its own configuration writes it."""
+    trimmed = server.strip().rstrip("/")
+    split = urlsplit(trimmed)
+    return split.netloc if split.netloc else trimmed
+
+
+def _target(path: str, asked: list[tuple[str, str]]) -> str:
+    """The request target one call is made to, with what it asks for."""
+    if not asked:
+        return path
+    written = "&".join(f"{quote(name, safe='')}={quote(value, safe='')}" for name, value in asked)
+    return f"{path}?{written}"
+
+
+def _document(status: int, said: str) -> object:
+    """One answer, parsed.
+
+    Raises:
+        UnreadableError: If it is not a document this client can read.
+    """
+    try:
+        return json.loads(said)
+    except ValueError as unreadable:
+        raise UnreadableError(status, str(unreadable)) from unreadable
+
+
+def _said(said: str) -> str:
+    """What the supervisor said about a request it will not act on."""
+    try:
+        answer = json.loads(said)
+    except ValueError:
+        return "it said nothing this client can read"
+    if isinstance(answer, dict) and isinstance(answer.get("error"), str):
+        return answer["error"]
+    return "it said nothing this client can read"
+
+
+def _rejection(status: int, said: str) -> Exception:
+    """The policy's own refusal, as the answer to it carries it."""
+    answer = cast(ActionAnswer, _document(status, said))
+    decision = answer["record"]["decision"]
+    if not isinstance(decision, dict) or "rejected" not in decision:
+        return UnreadableError(
+            status,
+            "the supervisor refused this action and answered a record whose decision "
+            "is not a refusal",
+        )
+    reason = decision["rejected"]
+    requested: float | None = None
+    allowed: Range | None = None
+    if isinstance(reason, dict) and "out_of_bounds" in reason:
+        bounds = cast(RejectionReasonOutOfBoundsPayload, reason["out_of_bounds"])
+        requested = bounds["requested"]
+        allowed = bounds["allowed"]
+    return RejectedError(reason, requested, allowed, answer)
+
+
+def _machine_refusal(status: int, said: str) -> Exception:
+    """The machine's own refusal of an action the policy accepted."""
+    answer = cast(ActionAnswer, _document(status, said))
+    return PrinterRefusedError(
+        answer.get("printer_refusal") or "it said nothing this client can read", answer
+    )
+
+
+__all__ = ["Client", "NoReasonError"]

printobserver_sdk/_surface.py

@@ -0,0 +1,150 @@
+"""What every generated method is written against, and every way a call can end.
+
+The generated module carries one method per operation the server declares.
+This is what those methods stand on: the two things a call needs from the
+client — who it acts as, and how to make a request — and the closed set of
+failures a caller distinguishes.
+
+Nothing here imports the generated module at run time. The type names below are
+that module's, brought in for the type checker alone, so that the two files can
+name each other's shapes without either being unimportable.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover - imported for annotations alone
+    from printobserver_sdk.contract import ActionAnswer, Actor, Range, RejectionReason
+
+
+class ClientError(Exception):
+    """Why a call did not answer what it asked for."""
+
+
+class UnreachableError(ClientError):
+    """Nothing answered at the configured address."""
+
+    def __init__(self, address: str, detail: str) -> None:
+        """Record where this client looked and what happened there."""
+        super().__init__(
+            f"nothing answered at {address}: {detail}. Start the supervisor there, or "
+            f"point this client at the address it is answering on"
+        )
+        self.address = address
+        self.detail = detail
+
+
+class NoReasonError(ClientError):
+    """This client would not send the request, because it carried no reason.
+
+    Every mutating operation carries a reason, and a call whose reason is empty
+    is refused here rather than at the server: nothing reaches the policy, the
+    printer or the record.
+    """
+
+    def __init__(self) -> None:
+        """Say what every mutating call owes."""
+        super().__init__("every mutating call carries a reason, and this one carries none")
+
+
+class UnreadableError(ClientError):
+    """The supervisor answered something this client cannot read."""
+
+    def __init__(self, status: int, detail: str) -> None:
+        """Record the status it answered under and what could not be read."""
+        super().__init__(
+            f"the supervisor answered {status} with something this client cannot read: {detail}"
+        )
+        self.status = status
+        self.detail = detail
+
+
+class RefusedError(ClientError):
+    """The supervisor will not do what it was asked, and said why."""
+
+    def __init__(self, status: int, detail: str) -> None:
+        """Record the status it answered under and what it said."""
+        super().__init__(f"the supervisor answered {status}: {detail}")
+        self.status = status
+        self.detail = detail
+
+
+class PrinterRefusedError(ClientError):
+    """The policy accepted the action and the machine refused it."""
+
+    def __init__(self, detail: str, answer: ActionAnswer) -> None:
+        """Record what the printer said and the record the request left."""
+        super().__init__(
+            f"the policy accepted this action and the machine refused it: {detail}. "
+            f"Look at the printer, then ask again"
+        )
+        self.detail = detail
+        self.answer = answer
+
+
+class RejectedError(ClientError):
+    """The policy refused the action, and the refusal is the answer.
+
+    `reason` is the refusal itself, matched rather than read; `requested` and
+    `allowed` are the value that was asked for and the range that is allowed,
+    which the policy states when it ruled on a value and which are `None` when
+    it ruled on something else.
+    """
+
+    def __init__(
+        self,
+        reason: RejectionReason,
+        requested: float | None,
+        allowed: Range | None,
+        answer: ActionAnswer,
+    ) -> None:
+        """Record the reason, the value asked for and the range allowed."""
+        said = f"the supervisor's policy refused this action: {reason!r}"
+        if requested is not None and allowed is not None:
+            said += (
+                f". It was asked for {requested}, and what is allowed is "
+                f"{allowed['min']} to {allowed['max']}"
+            )
+        super().__init__(said)
+        self.reason = reason
+        self.requested = requested
+        self.allowed = allowed
+        self.answer = answer
+
+
+def reason_given(reason: str) -> None:
+    """Refuse a mutating call that carries no reason, before it is made.
+
+    Raises:
+        NoReasonError: If the reason is absent or is nothing but whitespace.
+    """
+    if not reason or not reason.strip():
+        raise NoReasonError
+
+
+class GeneratedSurface:
+    """The two things every generated method needs from the client it is on.
+
+    A surface on its own makes no request: `Client` is what implements `call`,
+    and the generated methods are written against this so that the transport
+    and the operation list stay separable.
+    """
+
+    #: Who this client acts as, which every mutating call carries.
+    actor: Actor
+
+    def call(
+        self,
+        method: str,
+        target: str,
+        asked: list[tuple[str, str]],
+        sending: dict[str, object] | None,
+    ) -> object:
+        """Make one call and answer the document that came back.
+
+        Raises:
+            NotImplementedError: Always. `Client` is what makes a request; a
+                surface that answered one would be a second transport.
+        """
+        raise NotImplementedError