narwhalapi 0.1.0__py3-none-any.whl

narwhalapi/__init__.py

@@ -0,0 +1,17 @@
+"""Typed clients for the Narwhal API."""
+
+from . import codes, errors, models
+from ._client import AsyncNarwhal, Narwhal
+from ._meta import RateLimit, ResponseMeta
+from ._version import __version__
+
+__all__ = [
+    "AsyncNarwhal",
+    "Narwhal",
+    "RateLimit",
+    "ResponseMeta",
+    "__version__",
+    "codes",
+    "errors",
+    "models",
+]

narwhalapi/_client.py

@@ -0,0 +1,122 @@
+"""Connection-owning synchronous and asynchronous clients."""
+
+import asyncio
+import random
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from types import TracebackType
+from typing import TypeVar
+
+import httpx
+
+from ._generated.operations import (
+    LIVE_SPEC_SHA,
+    AsyncStableOperations,
+    StableOperations,
+)
+from ._transport import AsyncTransport, Settings, SyncTransport
+
+SyncClient = TypeVar("SyncClient", bound="Narwhal")
+AsyncClient = TypeVar("AsyncClient", bound="AsyncNarwhal")
+
+
+class Narwhal(StableOperations):
+    """Share one client across threads and close it when finished."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        proxy: str | None = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+        max_retry_wait: float = 30,
+        extra_headers: Mapping[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        clock: Callable[[], float] = time.monotonic,
+        random_fraction: Callable[[], float] = random.random,
+    ) -> None:
+        settings = Settings(
+            api_key=api_key,
+            base_url=base_url,
+            proxy=proxy,
+            timeout=timeout,
+            max_retries=max_retries,
+            max_retry_wait=max_retry_wait,
+            extra_headers=extra_headers,
+            clock=clock,
+            random_fraction=random_fraction,
+            spec_sha=LIVE_SPEC_SHA,
+        )
+        self._transport = SyncTransport(settings, transport=transport, sleep=sleep)
+        super().__init__(self._transport)
+
+    def __repr__(self) -> str:
+        return "Narwhal(api_key=<redacted>)"
+
+    def close(self) -> None:
+        self._transport.http.close()
+
+    def __enter__(self: SyncClient) -> SyncClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncNarwhal(AsyncStableOperations):
+    """Use one client per event loop and close it with async with."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        proxy: str | None = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+        max_retry_wait: float = 30,
+        extra_headers: Mapping[str, str] | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+        clock: Callable[[], float] = time.monotonic,
+        random_fraction: Callable[[], float] = random.random,
+    ) -> None:
+        settings = Settings(
+            api_key=api_key,
+            base_url=base_url,
+            proxy=proxy,
+            timeout=timeout,
+            max_retries=max_retries,
+            max_retry_wait=max_retry_wait,
+            extra_headers=extra_headers,
+            clock=clock,
+            random_fraction=random_fraction,
+            spec_sha=LIVE_SPEC_SHA,
+        )
+        self._transport = AsyncTransport(settings, transport=transport, sleep=sleep)
+        super().__init__(self._transport)
+
+    def __repr__(self) -> str:
+        return "AsyncNarwhal(api_key=<redacted>)"
+
+    async def aclose(self) -> None:
+        await self._transport.http.aclose()
+
+    async def __aenter__(self: AsyncClient) -> AsyncClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()

narwhalapi/_deadline.py

@@ -0,0 +1,180 @@
+"""Per-attempt synchronous I/O deadlines, without threads or event loops."""
+
+from collections.abc import Callable, Iterable
+from contextvars import ContextVar
+from ssl import SSLContext
+from typing import Protocol, cast
+
+import httpx
+
+RESPONSE_STARTED = "narwhal.response_started"
+SocketOption = tuple[int, int, int | bytes] | tuple[int, int, None, int]
+
+
+class Deadline:
+    def __init__(self, timeout: float, clock: Callable[[], float]) -> None:
+        self.clock = clock
+        self.expires = clock() + timeout
+
+    def remaining(self) -> float:
+        return max(0.0, self.expires - self.clock())
+
+
+active_deadline: ContextVar[Deadline | None] = ContextVar(
+    "narwhal_deadline", default=None
+)
+
+
+def io_timeout(timeout: float | None) -> float | None:
+    deadline = active_deadline.get()
+    if deadline is None:
+        return timeout
+    remaining = deadline.remaining()
+    if remaining <= 0:
+        raise httpx.ReadTimeout("Attempt deadline exceeded")
+    return remaining if timeout is None else min(timeout, remaining)
+
+
+class NetworkStream(Protocol):
+    def read(self, max_bytes: int, timeout: float | None = None) -> bytes: ...
+    def write(self, buffer: bytes, timeout: float | None = None) -> None: ...
+    def close(self) -> None: ...
+    def start_tls(
+        self,
+        ssl_context: SSLContext,
+        server_hostname: str | None = None,
+        timeout: float | None = None,
+    ) -> "NetworkStream": ...
+    def get_extra_info(self, info: str) -> object: ...
+
+
+class NetworkBackend(Protocol):
+    def connect_tcp(
+        self,
+        host: str,
+        port: int,
+        timeout: float | None = None,
+        local_address: str | None = None,
+        socket_options: Iterable[SocketOption] | None = None,
+    ) -> NetworkStream: ...
+    def connect_unix_socket(
+        self,
+        path: str,
+        timeout: float | None = None,
+        socket_options: Iterable[SocketOption] | None = None,
+    ) -> NetworkStream: ...
+    def sleep(self, seconds: float) -> None: ...
+
+
+class _Stream:
+    def __init__(self, inner: NetworkStream) -> None:
+        self.inner = inner
+
+    def read(self, max_bytes: int, timeout: float | None = None) -> bytes:
+        return self.inner.read(max_bytes, timeout=io_timeout(timeout))
+
+    def write(self, buffer: bytes, timeout: float | None = None) -> None:
+        self.inner.write(buffer, timeout=io_timeout(timeout))
+
+    def close(self) -> None:
+        self.inner.close()
+
+    def start_tls(
+        self,
+        ssl_context: SSLContext,
+        server_hostname: str | None = None,
+        timeout: float | None = None,
+    ) -> "_Stream":
+        return _Stream(
+            self.inner.start_tls(
+                ssl_context,
+                server_hostname=server_hostname,
+                timeout=io_timeout(timeout),
+            )
+        )
+
+    def get_extra_info(self, info: str) -> object:
+        return self.inner.get_extra_info(info)
+
+
+class _Backend:
+    def __init__(self, inner: NetworkBackend) -> None:
+        self.inner = inner
+
+    def connect_tcp(
+        self,
+        host: str,
+        port: int,
+        timeout: float | None = None,
+        local_address: str | None = None,
+        socket_options: Iterable[SocketOption] | None = None,
+    ) -> NetworkStream:
+        return _Stream(
+            self.inner.connect_tcp(
+                host,
+                port,
+                timeout=io_timeout(timeout),
+                local_address=local_address,
+                socket_options=socket_options,
+            )
+        )
+
+    def connect_unix_socket(
+        self,
+        path: str,
+        timeout: float | None = None,
+        socket_options: Iterable[SocketOption] | None = None,
+    ) -> NetworkStream:
+        return _Stream(
+            self.inner.connect_unix_socket(
+                path, timeout=io_timeout(timeout), socket_options=socket_options
+            )
+        )
+
+    def sleep(self, seconds: float) -> None:
+        self.inner.sleep(seconds)
+
+
+class _Pool(Protocol):
+    _network_backend: NetworkBackend
+
+
+class _ClientTransports(Protocol):
+    _transport: httpx.BaseTransport
+    _mounts: dict[object, httpx.BaseTransport | None]
+
+
+def install_deadlines(client: httpx.Client) -> None:
+    """Adapt native pools, including environment and explicit proxy pools.
+
+    This is the sole boundary using transport internals. The underlying HTTP codec
+    caches the body timeout, so mutating the request timeout between chunks alone
+    does not bound slow responses. Native-codec tests verify this adapter against
+    the locked dependency. Injected transports can read request timeout extensions.
+    """
+    transports = cast(_ClientTransports, client)
+    for transport in (transports._transport, *transports._mounts.values()):
+        if isinstance(transport, httpx.HTTPTransport):
+            pool = cast(_Pool, transport._pool)
+            if not isinstance(pool._network_backend, _Backend):
+                pool._network_backend = _Backend(pool._network_backend)
+
+
+def read_response(
+    response: httpx.Response, request: httpx.Request, deadline: Deadline
+) -> httpx.Response:
+    if response.is_stream_consumed:
+        return response
+    timeouts = cast(dict[str, float | None], request.extensions["timeout"])
+    chunks = []
+    for chunk in response.iter_raw():
+        chunks.append(chunk)
+        # Do not raise after a received chunk: it may be the last one. A next
+        # network read is where expiry becomes a transport failure.
+        timeouts["read"] = deadline.remaining()
+    return httpx.Response(
+        response.status_code,
+        headers=response.headers,
+        content=b"".join(chunks),
+        request=request,
+    )

narwhalapi/_decode.py

@@ -0,0 +1,67 @@
+"""Strict wire primitives used by generated decoders."""
+
+import json
+import re
+from decimal import Decimal
+from typing import cast
+
+
+def read_object(value: object) -> dict[str, object]:
+    if not isinstance(value, dict) or any(not isinstance(k, str) for k in value):
+        raise ValueError("expected an object")
+    return cast(dict[str, object], value)
+
+
+def read_list(value: object) -> list[object]:
+    if not isinstance(value, list):
+        raise TypeError("expected an array")
+    return cast(list[object], value)
+
+
+def read_str(value: object) -> str:
+    if not isinstance(value, str):
+        raise TypeError("expected a string")
+    return value
+
+
+def read_int(value: object) -> int:
+    if type(value) is not int:
+        raise ValueError("expected an integer")
+    return value
+
+
+def read_bool(value: object) -> bool:
+    if not isinstance(value, bool):
+        raise TypeError("expected a boolean")
+    return value
+
+
+def read_decimal(value: object) -> Decimal:
+    text = read_str(value)
+    if re.fullmatch(r"-?\d+(\.\d+)?", text, re.ASCII) is None:
+        raise ValueError("expected a decimal wire string")
+    return Decimal(text)
+
+
+def read_decimal_number(value: object) -> Decimal:
+    """A decimal sent as a JSON number; `read_json` keeps its literal as a Decimal."""
+    if isinstance(value, bool) or not isinstance(value, (int, Decimal)):
+        raise TypeError("expected a JSON number")
+    if isinstance(value, Decimal) and not value.is_finite():
+        raise ValueError("expected a finite JSON number")
+    return Decimal(value)
+
+
+def reject_number(value: str) -> object:
+    raise ValueError("unexpected non-finite JSON number")
+
+
+def read_json(raw: bytes) -> object:
+    return json.loads(raw, parse_float=Decimal, parse_constant=reject_number)
+
+
+def read_cursor(value: object) -> str:
+    cursor = read_str(value)
+    if not cursor:
+        raise ValueError("next_cursor must not be empty")
+    return cursor

narwhalapi/_generated/__init__.py

@@ -0,0 +1,3 @@
+# Generated from spec/live/openapi.json sha256 b60f17d48a2e406d95b34c274a80961d2a3de2b5e7b056a082d0ded894340420. Do not edit.
+# Generated from spec/next/openapi.json sha256 b60f17d48a2e406d95b34c274a80961d2a3de2b5e7b056a082d0ded894340420. Do not edit.
+"""Generated contract surface."""