webfunction 0.1.0__py3-none-any.whl

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/_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/_version.py

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

webfunction/client.py

@@ -0,0 +1,296 @@
+"""Client and AsyncClient, ported from the Ruby reference gem's client.rb.
+
+Dynamic dispatch (``client.list_items(a="b")`` working without any generated code) is
+implemented via ``__getattr__``, the same trick Ruby/JS/PHP use via method_missing /
+Proxy / __call -- confirmed as the right default for Python too, matching the majority
+of the reference-client suite.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from . import _request
+from .models import Package
+from .page import AsyncPage, Page
+from .pipeline import AsyncPipeline, Pipeline
+
+
+def _join_url(base_url: str, endpoint_name: str) -> str:
+    # Plain string-level normalization per
+    # https://webfunction.org/package#url-composition: append endpoint_name
+    # directly if base_url ends in "/", otherwise insert a single "/".
+    #
+    # This deliberately does NOT use urljoin/RFC 3986 relative-reference
+    # resolution, despite the comment that used to be here claiming urljoin
+    # "already does the right thing to match Ruby's URI.join semantics".
+    # That was wrong: RFC 3986 resolution treats a base_url path segment as
+    # replaceable when base_url doesn't end in "/" -- e.g. resolving
+    # "list-people" against "https://api.example.com/v1" (no trailing
+    # slash) silently drops "v1" and produces
+    # "https://api.example.com/list-people" instead of
+    # "https://api.example.com/v1/list-people". The spec's own composition
+    # rule has no such failure mode: it works correctly for a base_url with
+    # or without a trailing slash. (Ruby's URI.join has the identical bug,
+    # confirmed directly -- so "matching Ruby" was never actually a safe
+    # bar to aim for here; webfunction-go had the same bug for the same
+    # reason and has since been fixed the same way.)
+    if base_url.endswith("/"):
+        return base_url + endpoint_name
+    return base_url + "/" + endpoint_name
+
+
+class Client:
+    """A synchronous wrapper around a Web Function Package that provides a convenient
+    interface for invoking endpoints.
+
+    Example::
+
+        client = Client.from_package_endpoint("https://api.example.com/package")
+        client.list_items(a="b")  # => {"c": "d"}
+    """
+
+    def __init__(self, *, base_url: str, endpoints: Optional[List[str]] = None,
+                 package: Optional[Package] = None, bearer_auth: Optional[str] = None,
+                 version: Optional[str] = None, pipeline: Optional[Pipeline] = None,
+                 http_client: Optional[httpx.Client] = None):
+        self._package = package
+        self._base_url = base_url
+        self._endpoints: Dict[str, str] = {e.replace("-", "_"): e for e in (endpoints or [])}
+        self.bearer_auth = bearer_auth
+        self.version = version
+        self.pipeline = pipeline
+        self._http = http_client if http_client is not None else httpx.Client()
+        self._owns_http = http_client is None
+
+    # -- construction -----------------------------------------------------------------
+
+    @classmethod
+    def from_package_endpoint(cls, url: str, *, bearer_auth: Optional[str] = None,
+                               version: Optional[str] = None, pipelined: bool = False,
+                               http_client: Optional[httpx.Client] = None) -> "Client":
+        http = http_client if http_client is not None else httpx.Client()
+        response = _request.execute_sync(http, url, bearer_auth=bearer_auth, version=version, args={})
+        package = Package.from_dict(response)
+        return cls.from_package(package, bearer_auth=bearer_auth, version=version,
+                                 pipelined=pipelined, http_client=http)
+
+    @classmethod
+    def from_url(cls, url: str, *, bearer_auth: Optional[str] = None, version: Optional[str] = None,
+                 pipelined: bool = False, http_client: Optional[httpx.Client] = None) -> "Client":
+        http = http_client if http_client is not None else httpx.Client()
+        body = _request.get_body_sync(http, url, extra_query_params={"api_version": version})
+        package = Package.from_dict(json.loads(body))
+        return cls.from_package(package, bearer_auth=bearer_auth, version=version,
+                                 pipelined=pipelined, http_client=http)
+
+    @classmethod
+    def from_package(cls, package: Package, *, bearer_auth: Optional[str] = None,
+                      version: Optional[str] = None, pipelined: bool = False,
+                      http_client: Optional[httpx.Client] = None) -> "Client":
+        http = http_client if http_client is not None else httpx.Client()
+        pipeline = None
+        if pipelined and package.pipeline_url:
+            pipeline = Pipeline(
+                package.pipeline_url,
+                lambda url, args: _request.execute_sync(http, url, bearer_auth=bearer_auth, version=version, args=args),
+            )
+
+        client = cls(
+            package=package,
+            base_url=package.base_url,
+            endpoints=[e.name for e in package.endpoints],
+            bearer_auth=bearer_auth,
+            version=version,
+            pipeline=pipeline,
+            http_client=http,
+        )
+
+        for endpoint in package.endpoints:
+            endpoint.client = client
+
+        return client
+
+    # -- invocation ---------------------------------------------------------------------
+
+    def call(self, endpoint_name: str, args: Optional[dict] = None) -> Any:
+        """Calls an endpoint by name with the given arguments. Paginated responses are
+        wrapped in a :class:`Page`. When the client is pipelined, returns a
+        :class:`~webfunction.pipeline.Promise` instead of executing immediately."""
+        args = args or {}
+        url = _join_url(self._base_url, endpoint_name)
+
+        if self.pipeline is not None:
+            step = {"url": url, "headers": _request.build_headers(self.bearer_auth, self.version), "body": args}
+            return self.pipeline.add_step(step)
+
+        return self._execute_and_wrap(url, args, endpoint_name)
+
+    def _execute_and_wrap(self, url: str, args: dict, endpoint_name: str) -> Any:
+        response = _request.execute_sync(self._http, url, bearer_auth=self.bearer_auth, version=self.version, args=args)
+        endpoint = self._package.endpoint(endpoint_name) if self._package else None
+        paginated = bool(endpoint and endpoint.paginated)
+        return Page.wrap(response, paginated=paginated, fetch=lambda body: self._execute_and_wrap(url, body, endpoint_name))
+
+    @property
+    def package(self) -> Optional[Package]:
+        return self._package
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # -- dynamic dispatch -----------------------------------------------------------------
+
+    def __getattr__(self, name: str):
+        # Only reached when normal attribute lookup fails.
+        endpoints = self.__dict__.get("_endpoints", {})
+        endpoint_name = endpoints.get(name)
+        if endpoint_name is None:
+            raise AttributeError(f"{type(self).__name__!r} object has no attribute or endpoint {name!r}")
+
+        def _invoke(**kwargs):
+            return self.call(endpoint_name, kwargs)
+
+        return _invoke
+
+    def __dir__(self):
+        return list(super().__dir__()) + list(self.__dict__.get("_endpoints", {}).keys())
+
+    def __repr__(self) -> str:
+        return f"Client(base_url={self._base_url!r})"
+
+
+class AsyncClient:
+    """Async equivalent of :class:`Client`. All I/O methods (including dynamic-dispatch
+    endpoint calls) return awaitables.
+
+    Example::
+
+        client = await AsyncClient.from_package_endpoint("https://api.example.com/package")
+        await client.list_items(a="b")  # => {"c": "d"}
+    """
+
+    def __init__(self, *, base_url: str, endpoints: Optional[List[str]] = None,
+                 package: Optional[Package] = None, bearer_auth: Optional[str] = None,
+                 version: Optional[str] = None, pipeline: Optional[AsyncPipeline] = None,
+                 http_client: Optional[httpx.AsyncClient] = None):
+        self._package = package
+        self._base_url = base_url
+        self._endpoints: Dict[str, str] = {e.replace("-", "_"): e for e in (endpoints or [])}
+        self.bearer_auth = bearer_auth
+        self.version = version
+        self.pipeline = pipeline
+        self._http = http_client if http_client is not None else httpx.AsyncClient()
+        self._owns_http = http_client is None
+
+    # -- construction -----------------------------------------------------------------
+
+    @classmethod
+    async def from_package_endpoint(cls, url: str, *, bearer_auth: Optional[str] = None,
+                                     version: Optional[str] = None, pipelined: bool = False,
+                                     http_client: Optional[httpx.AsyncClient] = None) -> "AsyncClient":
+        http = http_client if http_client is not None else httpx.AsyncClient()
+        response = await _request.execute_async(http, url, bearer_auth=bearer_auth, version=version, args={})
+        package = Package.from_dict(response)
+        return await cls.from_package(package, bearer_auth=bearer_auth, version=version,
+                                       pipelined=pipelined, http_client=http)
+
+    @classmethod
+    async def from_url(cls, url: str, *, bearer_auth: Optional[str] = None, version: Optional[str] = None,
+                        pipelined: bool = False, http_client: Optional[httpx.AsyncClient] = None) -> "AsyncClient":
+        http = http_client if http_client is not None else httpx.AsyncClient()
+        body = await _request.get_body_async(http, url, extra_query_params={"api_version": version})
+        package = Package.from_dict(json.loads(body))
+        return await cls.from_package(package, bearer_auth=bearer_auth, version=version,
+                                       pipelined=pipelined, http_client=http)
+
+    @classmethod
+    async def from_package(cls, package: Package, *, bearer_auth: Optional[str] = None,
+                            version: Optional[str] = None, pipelined: bool = False,
+                            http_client: Optional[httpx.AsyncClient] = None) -> "AsyncClient":
+        http = http_client if http_client is not None else httpx.AsyncClient()
+        pipeline = None
+        if pipelined and package.pipeline_url:
+            async def _exec(url, args):
+                return await _request.execute_async(http, url, bearer_auth=bearer_auth, version=version, args=args)
+            pipeline = AsyncPipeline(package.pipeline_url, _exec)
+
+        client = cls(
+            package=package,
+            base_url=package.base_url,
+            endpoints=[e.name for e in package.endpoints],
+            bearer_auth=bearer_auth,
+            version=version,
+            pipeline=pipeline,
+            http_client=http,
+        )
+
+        for endpoint in package.endpoints:
+            endpoint.client = client
+
+        return client
+
+    # -- invocation ---------------------------------------------------------------------
+
+    async def call(self, endpoint_name: str, args: Optional[dict] = None) -> Any:
+        args = args or {}
+        url = _join_url(self._base_url, endpoint_name)
+
+        if self.pipeline is not None:
+            step = {"url": url, "headers": _request.build_headers(self.bearer_auth, self.version), "body": args}
+            return self.pipeline.add_step(step)
+
+        return await self._execute_and_wrap(url, args, endpoint_name)
+
+    async def _execute_and_wrap(self, url: str, args: dict, endpoint_name: str) -> Any:
+        response = await _request.execute_async(self._http, url, bearer_auth=self.bearer_auth, version=self.version, args=args)
+        endpoint = self._package.endpoint(endpoint_name) if self._package else None
+        paginated = bool(endpoint and endpoint.paginated)
+
+        async def _fetch(body):
+            return await self._execute_and_wrap(url, body, endpoint_name)
+
+        return AsyncPage.wrap(response, paginated=paginated, fetch=_fetch)
+
+    @property
+    def package(self) -> Optional[Package]:
+        return self._package
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.aclose()
+
+    # -- dynamic dispatch -----------------------------------------------------------------
+
+    def __getattr__(self, name: str):
+        endpoints = self.__dict__.get("_endpoints", {})
+        endpoint_name = endpoints.get(name)
+        if endpoint_name is None:
+            raise AttributeError(f"{type(self).__name__!r} object has no attribute or endpoint {name!r}")
+
+        async def _invoke(**kwargs):
+            return await self.call(endpoint_name, kwargs)
+
+        return _invoke
+
+    def __dir__(self):
+        return list(super().__dir__()) + list(self.__dict__.get("_endpoints", {}).keys())
+
+    def __repr__(self) -> str:
+        return f"AsyncClient(base_url={self._base_url!r})"

webfunction/errors.py

@@ -0,0 +1,54 @@
+"""Exception hierarchy for the Web Function client.
+
+A single base exception carries ``code``/``message``/``details``, with four
+named subtypes -- matching the same four errors used by every other client
+in the reference-client suite (Ruby, JS, PHP, Go, Java, C#).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+_CAMEL_RE = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+class WebFunctionError(Exception):
+    """Base exception for all Web Function client errors.
+
+    ``code`` defaults to a mechanically-derived string from the class name
+    (e.g. ``BadRequestError`` -> ``WFN_BAD_REQUEST_ERROR``) when none is given
+    explicitly, matching the Ruby reference gem's behavior.
+    """
+
+    def __init__(self, message: str, *, code: Optional[str] = None, details: Any = None):
+        super().__init__(message)
+        self.message = message
+        self.code = code or self._default_code()
+        self.details = details
+
+    def _default_code(self) -> str:
+        name = _CAMEL_RE.sub("_", type(self).__name__).upper()
+        return f"WFN_{name}"
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.message!r}, code={self.code!r}, details={self.details!r})"
+
+
+class BadRequestError(WebFunctionError):
+    """Raised when the server returns a 400 response."""
+
+
+class UnexpectedStatusCodeError(WebFunctionError):
+    """Raised when the server returns a status code other than 200 or 400."""
+
+
+class JsonParseError(WebFunctionError):
+    """Raised when the response body is not valid JSON."""
+
+
+class UnresolvedPromiseError(WebFunctionError):
+    """Raised when a Promise's value is accessed before it has been resolved."""
+
+    def __init__(self, message: str = "Promise is not yet resolved", *, code: Optional[str] = None, details: Any = None):
+        super().__init__(message, code=code, details=details)