surfdude 0.1.0__py3-none-any.whl

surfdude/__init__.py

@@ -0,0 +1,20 @@
+"""Public exports for the surfdude package."""
+
+from surfdude.dialects import AgentTraderDialect, SimpleDialect
+from surfdude.surf.retry import RetryAttempt, RetryPolicy, StandardRetry, never
+from surfdude.surf.surfer import Page, Surfer
+from surfdude.surf.wave import Report, Wave, WaveStoppedError
+
+__all__ = [
+    "AgentTraderDialect",
+    "Page",
+    "Report",
+    "RetryAttempt",
+    "RetryPolicy",
+    "SimpleDialect",
+    "StandardRetry",
+    "Surfer",
+    "Wave",
+    "WaveStoppedError",
+    "never",
+]

surfdude/conformance.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from surfdude.dialect import Dialect, HTTPResponse
+from surfdude.hypertext import Control, Resource
+
+
+def run(dialect: Dialect, directory: Path) -> None:
+    """Run every case in directory/cases.json against dialect (call from pytest)."""
+    raw = (directory / "cases.json").read_bytes()
+    spec = json.loads(raw)
+    if spec["dialect"] != dialect.name():
+        raise AssertionError(
+            f'cases.json is for dialect {spec["dialect"]!r} but this is {dialect.name()!r}'
+        )
+    for case in spec["cases"]:
+        _run_case(dialect, directory, case)
+
+
+def _run_case(dialect: Dialect, directory: Path, case: dict[str, Any]) -> None:
+    body = (directory / case["file"]).read_bytes()
+    headers: dict[str, list[str]] = {}
+    for k, v in (case.get("headers") or {}).items():
+        headers[k] = [v]
+    if case.get("contentType"):
+        headers["Content-Type"] = [case["contentType"]]
+    response = HTTPResponse(status_code=case.get("status", 200), headers=headers, body=body)
+    if not dialect.matches(response):
+        raise AssertionError(f"the {dialect.name()} dialect should recognise this response")
+    resource = dialect.read(response)
+    _check(resource, case["expect"])
+
+
+def _check(resource: Resource, want: dict[str, Any]) -> None:
+    if resource.status != want.get("status", resource.status):
+        raise AssertionError(f"status = {resource.status}, want {want.get('status')}")
+    if "notes" in want:
+        n = want["notes"]
+        if n is not None and len(resource.notes) != n:
+            raise AssertionError(f"notes = {len(resource.notes)}, want {n}")
+    if "paging" in want and want["paging"] is not None:
+        got = resource.paging
+        wp = want["paging"]
+        if (
+            got is None
+            or got.skip != wp.get("skip", 0)
+            or got.take != wp.get("take", 0)
+            or got.count != wp.get("count", 0)
+            or got.total != wp.get("total")
+        ):
+            raise AssertionError(f"paging = {got}, want {wp}")
+    if "rels" in want and want["rels"] is not None and resource.rels() != want["rels"]:
+        raise AssertionError(f"rels = {resource.rels()}, want {want['rels']}")
+    for rel, w in (want.get("controls") or {}).items():
+        c = resource.control(rel)
+        if c is None:
+            raise AssertionError(f"missing control {rel!r}")
+        _check_control(rel, c, w)
+    if "items" in want and want["items"] is not None:
+        if len(resource.items) != len(want["items"]):
+            raise AssertionError(f"items = {len(resource.items)}, want {len(want['items'])}")
+        for i, w in enumerate(want["items"]):
+            it = resource.items[i]
+            if w.get("rels") is not None and it.rels() != w["rels"]:
+                raise AssertionError(f"item {i} rels = {it.rels()}, want {w['rels']}")
+            for rel, cw in (w.get("controls") or {}).items():
+                c = it.control(rel)
+                if c is None:
+                    raise AssertionError(f"item {i} is missing control {rel!r}")
+                _check_control(rel, c, cw)
+    if "problems" in want and want["problems"] is not None:
+        if len(resource.problems) != len(want["problems"]):
+            raise AssertionError(
+                f"problems = {len(resource.problems)}, want {len(want['problems'])}"
+            )
+        for i, p in enumerate(want["problems"]):
+            got = resource.problems[i]
+            if got.field != p.get("field") or got.code != p.get("code"):
+                raise AssertionError(f"problem {i} = {got}, want {p}")
+
+
+def _check_control(rel: str, c: Control, w: dict[str, Any]) -> None:
+    if c.form != w.get("form", c.form):
+        raise AssertionError(f"{rel}: form = {c.form}, want {w.get('form')}")
+    if c.http_method() != w.get("method", "GET"):
+        raise AssertionError(f"{rel}: method = {c.http_method()}, want {w.get('method')}")
+    if w.get("inputs") is not None:
+        names = [inp.name for inp in c.inputs]
+        if names != w["inputs"]:
+            raise AssertionError(f"{rel}: inputs = {names}, want {w['inputs']}")
+    if w.get("required") is not None:
+        names = [inp.name for inp in c.inputs if inp.required and inp.value is None]
+        if names != w["required"]:
+            raise AssertionError(f"{rel}: required = {names}, want {w['required']}")
+    if w.get("requires") is not None and c.requires != w["requires"]:
+        raise AssertionError(f"{rel}: requires = {c.requires}, want {w['requires']}")
+    if w.get("ifMatch") is not None and c.if_match != w["ifMatch"]:
+        raise AssertionError(f"{rel}: ifMatch = {c.if_match!r}, want {w['ifMatch']!r}")
+    if w.get("inputValues"):
+        for name, want in w["inputValues"].items():
+            inp = next((i for i in c.inputs if i.name == name), None)
+            if inp is None:
+                raise AssertionError(f"{rel}: input {name!r} not found for inputValues check")
+            if not _input_value_equal(inp.value, want):
+                raise AssertionError(f"{rel}: input {name!r} value = {inp.value!r}, want {want!r}")
+
+
+def _input_value_equal(got: Any, want: Any) -> bool:
+    if got == want:
+        return True
+    return str(got) == str(want)

surfdude/dialect/__init__.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from surfdude.hypertext import Resource, UnsupportedMediaTypeError
+
+
+@dataclass
+class HTTPResponse:
+    """Minimal response shape for dialect matching and reading."""
+
+    status_code: int
+    headers: dict[str, list[str]]
+    body: bytes
+
+    def header_get(self, name: str) -> str:
+        for k, values in self.headers.items():
+            if k.lower() == name.lower() and values:
+                return values[0]
+        return ""
+
+    def header_values(self, name: str) -> list[str]:
+        for k, values in self.headers.items():
+            if k.lower() == name.lower():
+                return values
+        return []
+
+
+class Dialect(Protocol):
+    def name(self) -> str: ...
+
+    def accept(self) -> str: ...
+
+    def body_type(self) -> str: ...
+
+    def matches(self, response: HTTPResponse) -> bool: ...
+
+    def read(self, response: HTTPResponse) -> Resource: ...
+
+
+@dataclass
+class Registry:
+    dialects: list[Dialect] = field(default_factory=list)
+
+    def names(self) -> list[str]:
+        return [d.name() for d in self.dialects]
+
+    def accept(self) -> str:
+        seen: set[str] = set()
+        parts: list[str] = []
+        for d in self.dialects:
+            a = d.accept()
+            if a and a not in seen:
+                seen.add(a)
+                parts.append(a)
+        return ", ".join(parts)
+
+    def choose(self, response: HTTPResponse) -> Dialect | None:
+        for d in self.dialects:
+            if d.matches(response):
+                return d
+        return None
+
+    def first(self) -> Dialect | None:
+        return self.dialects[0] if self.dialects else None
+
+    def unsupported(self, response: HTTPResponse) -> UnsupportedMediaTypeError:
+        return UnsupportedMediaTypeError(
+            content_type=response.header_get("Content-Type"),
+            tried=self.names(),
+        )

surfdude/dialects/__init__.py

@@ -0,0 +1,4 @@
+from surfdude.dialects.agenttrader import AgentTraderDialect
+from surfdude.dialects.simple import SimpleDialect
+
+__all__ = ["AgentTraderDialect", "SimpleDialect"]

surfdude/dialects/agenttrader.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import json
+from email.message import Message
+
+from surfdude.dialect import HTTPResponse
+from surfdude.hypertext import Control, Input, Item, Paging, Price, Problem, Resource
+
+PROFILE_URI = "https://agenttrader.net/profiles/envelope/v1"
+
+
+class AgentTraderDialect:
+    def name(self) -> str:
+        return "agenttrader"
+
+    def accept(self) -> str:
+        return "application/json"
+
+    def body_type(self) -> str:
+        return "application/json"
+
+    def matches(self, response: HTTPResponse) -> bool:
+        mt = _parse_media_type(response.header_get("Content-Type"))
+        if not (mt == "application/json" or mt.endswith("+json")):
+            return False
+        for link in response.header_values("Link"):
+            if f"<{PROFILE_URI}>" in link and 'rel="profile"' in link:
+                return True
+        try:
+            probe = json.loads(response.body)
+        except json.JSONDecodeError:
+            return False
+        return isinstance(probe.get("status"), int) and isinstance(probe.get("data"), list)
+
+    def read(self, response: HTTPResponse) -> Resource:
+        env = json.loads(response.body)
+        res = Resource(
+            status=env.get("status") or response.status_code,
+            message=env.get("message", ""),
+            notes=list(env.get("notes") or []),
+            controls=_to_controls(env.get("_links") or [], env.get("_actions") or []),
+            body=response.body,
+        )
+        paging = env.get("paging")
+        if paging:
+            res.paging = Paging(
+                skip=paging.get("skip", 0),
+                take=paging.get("take", 0),
+                count=paging.get("count", 0),
+                total=paging.get("total"),
+            )
+        for raw in env.get("data") or []:
+            if isinstance(raw, dict):
+                item_raw = json.dumps(raw).encode()
+                res.items.append(
+                    Item(
+                        controls=_to_controls(raw.get("_links") or [], raw.get("_actions") or []),
+                        notes=list(raw.get("notes") or []),
+                        data=item_raw,
+                    )
+                )
+            else:
+                res.items.append(Item(data=json.dumps(raw).encode()))
+        if res.status >= 400:
+            for raw in env.get("data") or []:
+                if not isinstance(raw, dict):
+                    continue
+                if raw.get("message"):
+                    res.problems.append(
+                        Problem(
+                            field=raw.get("field", ""),
+                            code=raw.get("code", ""),
+                            message=raw.get("message", ""),
+                        )
+                    )
+        return res
+
+
+def _parse_media_type(value: str) -> str:
+    if not value:
+        return ""
+    msg = Message()
+    msg["content-type"] = value
+    return msg.get_content_type()
+
+
+def _to_controls(links: list, actions: list) -> list[Control]:
+    out: list[Control] = []
+    for link in links:
+        out.append(
+            Control(
+                rel=link.get("rel", ""),
+                title=link.get("title", ""),
+                href=link.get("href", ""),
+                method=link.get("method", ""),
+                type=link.get("type", ""),
+                requires=list(link.get("requires") or []),
+            )
+        )
+    for action in actions:
+        c = Control(
+            rel=action.get("rel", ""),
+            title=action.get("title", ""),
+            href=action.get("action", ""),
+            method=action.get("method", ""),
+            enctype=action.get("enctype", ""),
+            form=True,
+            requires=list(action.get("requires") or []),
+            if_match=action.get("ifMatch", ""),
+        )
+        price = action.get("price")
+        if price:
+            c.price = Price(
+                amount=price.get("amount", ""),
+                currency=price.get("currency", ""),
+                note=price.get("note", ""),
+            )
+        for field in action.get("fields") or []:
+            c.inputs.append(
+                Input(
+                    name=field.get("name", ""),
+                    required=field.get("required", False),
+                    value=field.get("value"),
+                    schema=dict(field.get("schema") or {}),
+                )
+            )
+        out.append(c)
+    return out

surfdude/dialects/simple.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import json
+from email.message import Message
+from http import HTTPStatus
+
+from surfdude.dialect import HTTPResponse
+from surfdude.hypertext import Control, Input, Item, Resource, Schema
+
+MEDIA_TYPE = "application/simple-hypertext+json"
+
+
+class SimpleDialect:
+    def name(self) -> str:
+        return "simple"
+
+    def accept(self) -> str:
+        return MEDIA_TYPE
+
+    def body_type(self) -> str:
+        return "application/json"
+
+    def matches(self, response: HTTPResponse) -> bool:
+        mt = _parse_media_type(response.header_get("Content-Type"))
+        return mt == MEDIA_TYPE
+
+    def read(self, response: HTTPResponse) -> Resource:
+        doc = json.loads(response.body)
+        links = doc.get("links") or []
+        res = Resource(
+            status=response.status_code,
+            message=HTTPStatus(response.status_code).phrase,
+            controls=_controls(links),
+            body=response.body,
+        )
+        for item in doc.get("items") or []:
+            raw = json.dumps(item).encode()
+            res.items.append(
+                Item(controls=_controls(item.get("links") or []), data=raw)
+            )
+        return res
+
+
+def _parse_media_type(value: str) -> str:
+    if not value:
+        return ""
+    msg = Message()
+    msg["content-type"] = value
+    return msg.get_content_type()
+
+
+def _controls(links: list) -> list[Control]:
+    out: list[Control] = []
+    for link in links:
+        form = link.get("form") or []
+        c = Control(
+            rel=link.get("rel", ""),
+            title=link.get("description", ""),
+            href=link.get("href", ""),
+            method=link.get("method", ""),
+            if_match=link.get("ifMatch", ""),
+            form=len(form) > 0,
+        )
+        for inp in form:
+            hin = Input(
+                name=inp.get("name", ""),
+                required=not inp.get("isOptional", False),
+                value=inp.get("value"),
+            )
+            schema: Schema = {}
+            if inp.get("label"):
+                schema["description"] = inp["label"]
+            opts = inp.get("options")
+            if opts:
+                schema["enum"] = list(opts)
+            if schema:
+                hin.schema = schema
+            c.inputs.append(hin)
+        out.append(c)
+    return out

surfdude/hypertext/__init__.py

@@ -0,0 +1,32 @@
+from surfdude.hypertext.errors import (
+    InvalidInputError,
+    MissingInputError,
+    MultiItemReadError,
+    NoDataError,
+    RelNotFoundError,
+    RequestFailedError,
+    UnexpectedInputError,
+    UnexpectedStatusError,
+    UnsupportedMediaTypeError,
+)
+from surfdude.hypertext.model import Control, Input, Item, Paging, Price, Problem, Resource, Schema
+
+__all__ = [
+    "Control",
+    "Input",
+    "InvalidInputError",
+    "Item",
+    "MissingInputError",
+    "MultiItemReadError",
+    "NoDataError",
+    "Paging",
+    "Price",
+    "Problem",
+    "RelNotFoundError",
+    "RequestFailedError",
+    "Resource",
+    "Schema",
+    "UnexpectedInputError",
+    "UnexpectedStatusError",
+    "UnsupportedMediaTypeError",
+]

surfdude/hypertext/errors.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from surfdude.hypertext.model import Input, Resource
+
+
+@dataclass
+class RelNotFoundError(Exception):
+    rel: str
+    where: str
+    offered: list[str]
+
+    def __str__(self) -> str:
+        offered = ", ".join(self.offered) if self.offered else "nothing"
+        return (
+            f'Unable to follow "{self.rel}". {self.where} has no control with that rel. '
+            f"It offers: {offered}."
+        )
+
+
+@dataclass
+class MissingInputError(Exception):
+    rel: str
+    missing: list[Input]
+
+    def __str__(self) -> str:
+        parts: list[str] = []
+        for inp in self.missing:
+            label = inp.name
+            desc = inp.schema.get("description") if inp.schema else None
+            if isinstance(desc, str) and desc:
+                label = f"{inp.name} ({desc})"
+            parts.append(label)
+        return f'Unable to submit "{self.rel}". It needs: {", ".join(parts)}.'
+
+
+@dataclass
+class InvalidInputError(Exception):
+    rel: str
+    name: str
+    reason: str
+
+    def __str__(self) -> str:
+        return (
+            f'Unable to submit "{self.rel}". The value for {self.name} is not allowed: {self.reason}.'
+        )
+
+
+@dataclass
+class UnexpectedInputError(Exception):
+    rel: str
+    name: str
+    allowed: list[str]
+
+    def __str__(self) -> str:
+        return (
+            f'Unable to submit "{self.rel}". It has no input called {self.name}. '
+            f"Its inputs are: {', '.join(self.allowed)}."
+        )
+
+
+@dataclass
+class UnsupportedMediaTypeError(Exception):
+    content_type: str
+    tried: list[str]
+
+    def __str__(self) -> str:
+        return (
+            f'Unable to read the response. No dialect understands "{self.content_type}". '
+            f"Dialects tried: {', '.join(self.tried)}."
+        )
+
+
+@dataclass
+class UnexpectedStatusError(Exception):
+    step: str
+    status: int
+    message: str = ""
+    resource: Resource | None = None
+    attempts: int = 1
+    """How many times the request was sent. More than 1 only when a retry policy tried again."""
+    url: str = ""
+
+    def __str__(self) -> str:
+        text = f"Unable to {self.step}. The server answered {self.status}"
+        if self.message:
+            text += f": {self.message}"
+        if self.resource and self.resource.problems:
+            ps = [f"{p.field} {p.message}".strip() for p in self.resource.problems]
+            text += f" ({'; '.join(ps)})"
+        text += "."
+        if self.attempts > 1:
+            text += f" It was tried {self.attempts} times."
+        return text
+
+
+@dataclass
+class RequestFailedError(Exception):
+    """The request never got an answer, for example the connection failed or timed out."""
+
+    step: str
+    cause: Exception
+    attempts: int = 1
+
+    def __str__(self) -> str:
+        tried = f" after {self.attempts} attempts" if self.attempts > 1 else ""
+        return f"Unable to {self.step}. The request failed{tried}: {self.cause}"
+
+
+@dataclass
+class NoDataError(Exception):
+    def __str__(self) -> str:
+        return "Unable to read data. The response carried none."
+
+
+class MultiItemReadError(Exception):
+    def __init__(self, count: int) -> None:
+        self.count = count
+        super().__init__(
+            f"Unable to read data. This page has {count} items; select one with Item(i)."
+        )

surfdude/hypertext/model.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+Schema = dict[str, Any]
+
+
+@dataclass
+class Input:
+    name: str
+    required: bool = False
+    value: Any = None
+    schema: Schema = field(default_factory=dict)
+
+
+@dataclass
+class Price:
+    amount: str = ""
+    currency: str = ""
+    note: str = ""
+
+
+@dataclass
+class Control:
+    rel: str
+    title: str = ""
+    href: str = ""
+    method: str = ""
+    enctype: str = ""
+    type: str = ""
+    form: bool = False
+    inputs: list[Input] = field(default_factory=list)
+    requires: list[str] = field(default_factory=list)
+    if_match: str = ""
+    price: Price | None = None
+
+    def http_method(self) -> str:
+        return (self.method or "GET").upper()
+
+
+@dataclass
+class Paging:
+    skip: int = 0
+    take: int = 0
+    count: int = 0
+    total: int | None = None
+
+
+@dataclass
+class Problem:
+    field: str = ""
+    code: str = ""
+    message: str = ""
+
+
+@dataclass
+class Item:
+    controls: list[Control] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+    data: bytes = b""
+
+    def control(self, rel: str) -> Control | None:
+        return _find(self.controls, rel)
+
+    def rels(self) -> list[str]:
+        return [c.rel for c in self.controls]
+
+    def decode(self, into: Any) -> None:
+        parsed = json.loads(self.data)
+        if isinstance(into, dict) and isinstance(parsed, dict):
+            into.clear()
+            into.update(parsed)
+            return
+        if isinstance(parsed, dict):
+            for k, v in parsed.items():
+                if hasattr(into, k):
+                    setattr(into, k, v)
+
+
+@dataclass
+class Resource:
+    status: int = 0
+    message: str = ""
+    notes: list[str] = field(default_factory=list)
+    paging: Paging | None = None
+    controls: list[Control] = field(default_factory=list)
+    items: list[Item] = field(default_factory=list)
+    problems: list[Problem] = field(default_factory=list)
+    body: bytes = b""
+
+    def control(self, rel: str) -> Control | None:
+        return _find(self.controls, rel)
+
+    def rels(self) -> list[str]:
+        return [c.rel for c in self.controls]
+
+    def duplicate_rels(self) -> list[str]:
+        counts: dict[str, int] = {}
+        for c in self.controls:
+            if c.rel:
+                counts[c.rel] = counts.get(c.rel, 0) + 1
+        return sorted(rel for rel, n in counts.items() if n > 1)
+
+    def decode(self, into: Any) -> None:
+        if self.problems:
+            from surfdude.hypertext.errors import NoDataError
+
+            raise NoDataError()
+        if not self.items:
+            from surfdude.hypertext.errors import NoDataError
+
+            raise NoDataError()
+        self.items[0].decode(into)
+
+
+def _find(controls: list[Control], rel: str) -> Control | None:
+    for c in controls:
+        if c.rel == rel:
+            return c
+    return None