surfdude 0.1.0__tar.gz

surfdude-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.3
+Name: surfdude
+Version: 0.1.0
+Summary: Hypermedia API client: drive journeys by rel, not URLs
+Author: Luke Puplett
+Author-email: Luke Puplett <lpuplett@pacificam.co.uk>
+Requires-Dist: httpx>=0.28.1
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/lukepuplett/surfdude-csharp
+Project-URL: Repository, https://github.com/lukepuplett/surfdude-csharp
+Project-URL: Documentation, https://github.com/lukepuplett/surfdude-csharp/blob/master/README.md
+Description-Content-Type: text/markdown
+
+# Surfdude for Python
+
+Hypermedia client: drive an API by `rel` names, not URLs. Register a **dialect** per **media type** (`SimpleDialect`, `AgentTraderDialect`). Same [fixtures](../fixtures/) as Go and C#.
+
+## Toolchain (if you are new to Python here)
+
+| Piece | What we use | Why |
+|-------|-------------|-----|
+| **Python version** | **3.12+** (`requires-python` in `pyproject.toml`) | Modern typing and long support window |
+| **Local pin** | `.python-version` | Tells [uv](https://docs.astral.sh/uv/) which interpreter to install for this folder |
+| **Package manager** | **uv** only | Creates `.venv`, installs deps, runs pytest — no system `pip` needed |
+| **HTTP** | **httpx** | Sync client (async can come later) |
+| **Tests** | **pytest** | Conformance runs every row in `../fixtures/*/cases.json` |
+| **Lint** | **ruff** | Style and import hygiene |
+
+You do not need a global Python install if uv is on your PATH: uv downloads the pinned version on first `sync`.
+
+## Commands
+
+```sh
+cd python
+uv sync --all-groups          # create .venv and install surfdude + dev tools
+uv run pytest                 # conformance + wave journey tests
+uv run ruff check src tests   # lint
+```
+
+## Layout
+
+```text
+src/surfdude/
+  hypertext/     Resource, Control, errors
+  dialect/       registry and HTTPResponse for dialects
+  dialects/      simple, agenttrader
+  surf/          Surfer, Page, Wave
+  conformance.py shared fixture runner (same cases as Go)
+tests/
+```
+
+## Sample ride
+
+```python
+from surfdude import AgentTraderDialect, Surfer
+
+with Surfer.new("http://localhost:8080", AgentTraderDialect()) as s:
+    s.wave().from_root().then_submit(
+        "search-listings", {"make": "MINI"}
+    ).then_item(0).then_submit(
+        "shortlist", {"note": "nice colour"}
+    ).go()
+```
+
+See [../docs/model.md](../docs/model.md) and [../docs/dialects.md](../docs/dialects.md).
+
+## Publishing
+
+PyPI package **`surfdude`**: tag **`vX.Y.Z`** on the repo triggers [Release workflow](../.github/workflows/release.yml) (trusted publisher OIDC). Install: `pip install surfdude==X.Y.Z`. Full process: [../docs/releasing.md](../docs/releasing.md).

surfdude-0.1.0/README.md

@@ -0,0 +1,56 @@
+# Surfdude for Python
+
+Hypermedia client: drive an API by `rel` names, not URLs. Register a **dialect** per **media type** (`SimpleDialect`, `AgentTraderDialect`). Same [fixtures](../fixtures/) as Go and C#.
+
+## Toolchain (if you are new to Python here)
+
+| Piece | What we use | Why |
+|-------|-------------|-----|
+| **Python version** | **3.12+** (`requires-python` in `pyproject.toml`) | Modern typing and long support window |
+| **Local pin** | `.python-version` | Tells [uv](https://docs.astral.sh/uv/) which interpreter to install for this folder |
+| **Package manager** | **uv** only | Creates `.venv`, installs deps, runs pytest — no system `pip` needed |
+| **HTTP** | **httpx** | Sync client (async can come later) |
+| **Tests** | **pytest** | Conformance runs every row in `../fixtures/*/cases.json` |
+| **Lint** | **ruff** | Style and import hygiene |
+
+You do not need a global Python install if uv is on your PATH: uv downloads the pinned version on first `sync`.
+
+## Commands
+
+```sh
+cd python
+uv sync --all-groups          # create .venv and install surfdude + dev tools
+uv run pytest                 # conformance + wave journey tests
+uv run ruff check src tests   # lint
+```
+
+## Layout
+
+```text
+src/surfdude/
+  hypertext/     Resource, Control, errors
+  dialect/       registry and HTTPResponse for dialects
+  dialects/      simple, agenttrader
+  surf/          Surfer, Page, Wave
+  conformance.py shared fixture runner (same cases as Go)
+tests/
+```
+
+## Sample ride
+
+```python
+from surfdude import AgentTraderDialect, Surfer
+
+with Surfer.new("http://localhost:8080", AgentTraderDialect()) as s:
+    s.wave().from_root().then_submit(
+        "search-listings", {"make": "MINI"}
+    ).then_item(0).then_submit(
+        "shortlist", {"note": "nice colour"}
+    ).go()
+```
+
+See [../docs/model.md](../docs/model.md) and [../docs/dialects.md](../docs/dialects.md).
+
+## Publishing
+
+PyPI package **`surfdude`**: tag **`vX.Y.Z`** on the repo triggers [Release workflow](../.github/workflows/release.yml) (trusted publisher OIDC). Install: `pip install surfdude==X.Y.Z`. Full process: [../docs/releasing.md](../docs/releasing.md).

surfdude-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "surfdude"
+version = "0.1.0"
+description = "Hypermedia API client: drive journeys by rel, not URLs"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["httpx>=0.28.1"]
+
+[[project.authors]]
+name = "Luke Puplett"
+email = "lpuplett@pacificam.co.uk"
+
+[project.urls]
+Homepage = "https://github.com/lukepuplett/surfdude-csharp"
+Repository = "https://github.com/lukepuplett/surfdude-csharp"
+Documentation = "https://github.com/lukepuplett/surfdude-csharp/blob/master/README.md"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0",
+    "ruff>=0.17",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"

surfdude-0.1.0/pyproject.toml.orig

@@ -0,0 +1,26 @@
+[project]
+name = "surfdude"
+version = "0.1.0"
+description = "Hypermedia API client: drive journeys by rel, not URLs"
+readme = "README.md"
+authors = [{ name = "Luke Puplett", email = "lpuplett@pacificam.co.uk" }]
+requires-python = ">=3.12"
+dependencies = ["httpx>=0.28.1"]
+
+[project.urls]
+Homepage = "https://github.com/lukepuplett/surfdude-csharp"
+Repository = "https://github.com/lukepuplett/surfdude-csharp"
+Documentation = "https://github.com/lukepuplett/surfdude-csharp/blob/master/README.md"
+
+[dependency-groups]
+dev = ["pytest>=9.0", "ruff>=0.17"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"

surfdude-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/surfdude/dialects/__init__.py

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

surfdude-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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",
+]