webfunction 0.1.0__tar.gz

webfunction-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+venv/
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/

webfunction-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

webfunction-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: webfunction
+Version: 0.1.0
+Summary: Reference client library for the Web Function (wfn) protocol
+Project-URL: Homepage, https://webfunction.org
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# webfunction-python
+
+A reference client library for the [Web Function (wfn)](https://webfunction.org) protocol.
+
+Part of the same reference-client suite as the Ruby gem
+(`https://github.com/webfunction-protocol/webfunction-ruby`, the spec author's own implementation),
+`webfunction-go`, `webfunction-java`, and `webfunction-csharp`.
+
+## Install
+
+```bash
+pip install webfunction
+```
+
+The only runtime dependency is [httpx](https://www.python-httpx.org/), which is what
+lets this library offer both a synchronous `Client` and an async `AsyncClient` from a
+single implementation.
+
+## Usage
+
+### Sync
+
+```python
+from webfunction import Client
+
+client = Client.from_package_endpoint("https://api.example.com/package")
+result = client.list_items(email="a@example.com")  # dynamic dispatch, no generated code
+```
+
+### Async
+
+```python
+import asyncio
+from webfunction import AsyncClient
+
+async def main():
+    client = await AsyncClient.from_package_endpoint("https://api.example.com/package")
+    result = await client.list_items(email="a@example.com")
+
+asyncio.run(main())
+```
+
+### Pagination
+
+Endpoints that declare the `paginated` flag return a `Page` (or `AsyncPage`):
+
+```python
+page = client.list_people()
+for person in page:
+    ...
+if page.has_next:
+    page = page.next_page()
+```
+
+### Pipelining
+
+If the package declares a `pipeline_url`, pass `pipelined=True` to batch several
+endpoint invocations into a single request. Calls return a `Promise` instead of
+executing immediately; index into a promise (`promise["id"]`) to build a reference to
+one of its fields before it's resolved.
+
+```python
+client = Client.from_package_endpoint(url, pipelined=True)
+item = client.list_items(email="a@example.com")
+detail = client.get_widget(id=item["id"])  # references item's future "id" field
+results = client.pipeline.execute()
+print(detail.value)
+```
+
+### Errors
+
+All errors are subclasses of `WebFunctionError`, carrying `.code`, `.message`, and
+`.details`: `BadRequestError`, `UnexpectedStatusCodeError`, `JsonParseError`,
+`UnresolvedPromiseError`.
+
+## A note on unknown fields
+
+This library never validates incoming JSON against a strict schema -- model classes
+only read the keys they know about via plain `dict.get()`, so an API that adds an
+undocumented field to its responses (this has happened for real against
+`api.reservepay.com`) won't break parsing the way it did for the Java client, which
+needed an explicit fix to disable strict unknown-field rejection.
+
+## Development
+
+```bash
+pip install -e .
+python -m unittest discover tests
+```

webfunction-0.1.0/README.md

@@ -0,0 +1,89 @@
+# webfunction-python
+
+A reference client library for the [Web Function (wfn)](https://webfunction.org) protocol.
+
+Part of the same reference-client suite as the Ruby gem
+(`https://github.com/webfunction-protocol/webfunction-ruby`, the spec author's own implementation),
+`webfunction-go`, `webfunction-java`, and `webfunction-csharp`.
+
+## Install
+
+```bash
+pip install webfunction
+```
+
+The only runtime dependency is [httpx](https://www.python-httpx.org/), which is what
+lets this library offer both a synchronous `Client` and an async `AsyncClient` from a
+single implementation.
+
+## Usage
+
+### Sync
+
+```python
+from webfunction import Client
+
+client = Client.from_package_endpoint("https://api.example.com/package")
+result = client.list_items(email="a@example.com")  # dynamic dispatch, no generated code
+```
+
+### Async
+
+```python
+import asyncio
+from webfunction import AsyncClient
+
+async def main():
+    client = await AsyncClient.from_package_endpoint("https://api.example.com/package")
+    result = await client.list_items(email="a@example.com")
+
+asyncio.run(main())
+```
+
+### Pagination
+
+Endpoints that declare the `paginated` flag return a `Page` (or `AsyncPage`):
+
+```python
+page = client.list_people()
+for person in page:
+    ...
+if page.has_next:
+    page = page.next_page()
+```
+
+### Pipelining
+
+If the package declares a `pipeline_url`, pass `pipelined=True` to batch several
+endpoint invocations into a single request. Calls return a `Promise` instead of
+executing immediately; index into a promise (`promise["id"]`) to build a reference to
+one of its fields before it's resolved.
+
+```python
+client = Client.from_package_endpoint(url, pipelined=True)
+item = client.list_items(email="a@example.com")
+detail = client.get_widget(id=item["id"])  # references item's future "id" field
+results = client.pipeline.execute()
+print(detail.value)
+```
+
+### Errors
+
+All errors are subclasses of `WebFunctionError`, carrying `.code`, `.message`, and
+`.details`: `BadRequestError`, `UnexpectedStatusCodeError`, `JsonParseError`,
+`UnresolvedPromiseError`.
+
+## A note on unknown fields
+
+This library never validates incoming JSON against a strict schema -- model classes
+only read the keys they know about via plain `dict.get()`, so an API that adds an
+undocumented field to its responses (this has happened for real against
+`api.reservepay.com`) won't break parsing the way it did for the Java client, which
+needed an explicit fix to disable strict unknown-field rejection.
+
+## Development
+
+```bash
+pip install -e .
+python -m unittest discover tests
+```

webfunction-0.1.0/examples/available_api_versions.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Fetches the merchants package from api.reservepay.com and calls its
+"available-api-versions" endpoint.
+
+Requires a bearer token in the RESERVEPAY_BEARER_TOKEN environment variable:
+
+    RESERVEPAY_BEARER_TOKEN=... python examples/available_api_versions.py
+"""
+
+import os
+import sys
+
+from webfunction import Client, WebFunctionError
+
+PACKAGE_URL = "https://api.reservepay.com/merchants"
+
+
+def main() -> int:
+    token = os.environ.get("RESERVEPAY_BEARER_TOKEN")
+    if not token:
+        print("RESERVEPAY_BEARER_TOKEN is not set.", file=sys.stderr)
+        print(f"Usage: RESERVEPAY_BEARER_TOKEN=... python {sys.argv[0]}", file=sys.stderr)
+        return 1
+
+    client = Client.from_package_endpoint(PACKAGE_URL, bearer_auth=token)
+    try:
+        versions = client.available_api_versions()
+        print(versions)
+    except WebFunctionError as e:
+        print(f"{type(e).__name__}: {e.message} (code={e.code}, details={e.details})", file=sys.stderr)
+        return 1
+    finally:
+        client.close()
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

webfunction-0.1.0/examples/available_api_versions_async.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Async equivalent of available_api_versions.py.
+
+    RESERVEPAY_BEARER_TOKEN=... python examples/available_api_versions_async.py
+"""
+
+import asyncio
+import os
+import sys
+
+from webfunction import AsyncClient, WebFunctionError
+
+PACKAGE_URL = "https://api.reservepay.com/merchants"
+
+
+async def run() -> int:
+    token = os.environ.get("RESERVEPAY_BEARER_TOKEN")
+    if not token:
+        print("RESERVEPAY_BEARER_TOKEN is not set.", file=sys.stderr)
+        print(f"Usage: RESERVEPAY_BEARER_TOKEN=... python {sys.argv[0]}", file=sys.stderr)
+        return 1
+
+    client = await AsyncClient.from_package_endpoint(PACKAGE_URL, bearer_auth=token)
+    try:
+        versions = await client.available_api_versions()
+        print(versions)
+    except WebFunctionError as e:
+        print(f"{type(e).__name__}: {e.message} (code={e.code}, details={e.details})", file=sys.stderr)
+        return 1
+    finally:
+        await client.aclose()
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(run()))

webfunction-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "webfunction"
+version = "0.1.0"
+description = "Reference client library for the Web Function (wfn) protocol"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.24",
+]
+
+[project.urls]
+Homepage = "https://webfunction.org"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/webfunction"]

webfunction-0.1.0/src/webfunction/__init__.py

@@ -0,0 +1,44 @@
+"""webfunction -- a reference client library for the Web Function (wfn) protocol.
+
+See https://webfunction.org for the protocol specification.
+"""
+
+from ._version import VERSION
+from .client import AsyncClient, Client
+from .errors import (
+    BadRequestError,
+    JsonParseError,
+    UnexpectedStatusCodeError,
+    UnresolvedPromiseError,
+    WebFunctionError,
+)
+from .models import Argument, Attribute, DocumentedError, Endpoint, ObjectSchema, Package
+from .page import AsyncPage, Page
+from .pipeline import AsyncPipeline, Path, Pipeline, Promise
+from . import wftype
+
+__version__ = VERSION
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "Package",
+    "Endpoint",
+    "Argument",
+    "Attribute",
+    "DocumentedError",
+    "ObjectSchema",
+    "Page",
+    "AsyncPage",
+    "Path",
+    "Promise",
+    "Pipeline",
+    "AsyncPipeline",
+    "WebFunctionError",
+    "BadRequestError",
+    "UnexpectedStatusCodeError",
+    "JsonParseError",
+    "UnresolvedPromiseError",
+    "wftype",
+    "VERSION",
+]

webfunction-0.1.0/src/webfunction/_request.py

@@ -0,0 +1,106 @@
+"""Low-level HTTP request/response handling shared by Client and AsyncClient, ported
+from the Ruby reference gem's request.rb.
+
+Gzip note: the wfn protocol always sends ``Accept-Encoding: gzip`` explicitly. This has
+bitten *every* prior client in the suite -- webfunction-go and webfunction-java both
+independently broke on gzip response bodies because their HTTP libraries disable their
+own automatic decompression once the caller sets ``Accept-Encoding`` itself.
+httpx does NOT have this problem: it decides whether to decompress based on the
+response's ``Content-Encoding`` header, regardless of who set ``Accept-Encoding`` on the
+request (verified directly against a mock gzip-compressing server -- see
+tests/test_client.py::test_gzip_response). So no manual gzip handling is needed here,
+but it's still covered by a real test rather than just assumed.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._version import VERSION
+from .errors import BadRequestError, JsonParseError, UnexpectedStatusCodeError
+from .pipeline import Promise
+
+
+def _json_default(obj: Any) -> Any:
+    if isinstance(obj, Promise):
+        return obj.to_json_value()
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def dumps(obj: Any) -> bytes:
+    return json.dumps(obj, default=_json_default).encode("utf-8")
+
+
+def build_headers(bearer_auth: Optional[str] = None, version: Optional[str] = None) -> Dict[str, str]:
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "User-Agent": f"webfunction/{VERSION}",
+        "Accept-Encoding": "gzip",
+    }
+    if bearer_auth:
+        headers["Authorization"] = f"Bearer {bearer_auth}"
+    if version:
+        headers["Api-Version"] = version
+    return headers
+
+
+def parse_response(status: int, body: bytes) -> Any:
+    """Parses a raw HTTP response per the wfn protocol, raising typed errors as needed.
+    Does not do pagination wrapping -- that needs the endpoint's ``paginated`` flag, which
+    only the caller (Client/AsyncClient) knows about."""
+    if status not in (200, 400):
+        raise UnexpectedStatusCodeError(
+            f"Unexpected status code ({status})",
+            details={"status_code": status, "raw_body": body.decode("utf-8", "replace")},
+        )
+
+    try:
+        result = json.loads(body)
+    except json.JSONDecodeError as e:
+        raise JsonParseError(
+            str(e),
+            details={"status_code": status, "raw_body": body.decode("utf-8", "replace"), "original_exception": e},
+        ) from e
+
+    if status == 400:
+        code, message, details = "WFN_BAD_REQUEST_ERROR", "Bad request", {"body": result}
+        if (
+            isinstance(result, list) and len(result) == 3
+            and isinstance(result[0], str) and isinstance(result[1], str)
+        ):
+            code, message, details = result
+        raise BadRequestError(message, code=code, details=details)
+
+    return result
+
+
+def execute_sync(http: httpx.Client, url: str, *, bearer_auth: Optional[str] = None,
+                  version: Optional[str] = None, args: Any = None) -> Any:
+    headers = build_headers(bearer_auth, version)
+    response = http.post(url, headers=headers, content=dumps(args if args is not None else {}))
+    return parse_response(response.status_code, response.content)
+
+
+async def execute_async(http: httpx.AsyncClient, url: str, *, bearer_auth: Optional[str] = None,
+                         version: Optional[str] = None, args: Any = None) -> Any:
+    headers = build_headers(bearer_auth, version)
+    response = await http.post(url, headers=headers, content=dumps(args if args is not None else {}))
+    return parse_response(response.status_code, response.content)
+
+
+def get_body_sync(http: httpx.Client, url: str, *, extra_query_params: Optional[dict] = None) -> bytes:
+    params = {k: v for k, v in (extra_query_params or {}).items() if v is not None}
+    headers = {"User-Agent": f"webfunction/{VERSION}", "Accept-Encoding": "gzip"}
+    response = http.get(url, headers=headers, params=params)
+    return response.content
+
+
+async def get_body_async(http: httpx.AsyncClient, url: str, *, extra_query_params: Optional[dict] = None) -> bytes:
+    params = {k: v for k, v in (extra_query_params or {}).items() if v is not None}
+    headers = {"User-Agent": f"webfunction/{VERSION}", "Accept-Encoding": "gzip"}
+    response = await http.get(url, headers=headers, params=params)
+    return response.content

webfunction-0.1.0/src/webfunction/_version.py

@@ -0,0 +1 @@
+VERSION = "0.1.0"