qca 0.0.1.dev1__py3-none-any.whl

qca/common/_models.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel as PydanticBaseModel
+from pydantic import ConfigDict, PrivateAttr, TypeAdapter, ValidationError
+
+from ._exceptions import APIResponseValidationError
+
+
+class BaseModel(PydanticBaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True, protected_namespaces=(), defer_build=True)
+    _request_id: str | None = PrivateAttr(default=None)
+
+    def to_dict(
+        self, *, mode: str = "python", use_api_names: bool = True, exclude_unset: bool = True
+    ) -> dict[str, Any]:
+        return self.model_dump(mode=mode, by_alias=use_api_names, exclude_unset=exclude_unset)
+
+    def to_json(self, *, indent: int | None = 2, use_api_names: bool = True, exclude_unset: bool = True) -> str:
+        return self.model_dump_json(indent=indent, by_alias=use_api_names, exclude_unset=exclude_unset)
+
+
+def parse_response(cast_to: Any, data: Any, response: Any) -> Any:
+    if cast_to is None or cast_to is type(None):
+        return None
+    try:
+        result = TypeAdapter(cast_to).validate_python(data)
+    except (ValidationError, ValueError) as exc:
+        raise APIResponseValidationError(response=response, body=data) from exc
+    if isinstance(result, BaseModel):
+        result._request_id = response.headers.get("x-request-id") or response.headers.get("request-id")
+    return result

qca/common/_resource.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+from ._response import RawResponseResource
+
+if TYPE_CHECKING:
+    from ._base_client import AsyncAPIClient, SyncAPIClient
+
+
+class SyncAPIResource:
+    def __init__(self, client: SyncAPIClient) -> None:
+        self._client = client
+
+    @cached_property
+    def with_raw_response(self) -> RawResponseResource:
+        return RawResponseResource(self)
+
+    @cached_property
+    def with_streaming_response(self) -> RawResponseResource:
+        return RawResponseResource(self, streaming=True)
+
+
+class AsyncAPIResource:
+    def __init__(self, client: AsyncAPIClient) -> None:
+        self._client = client
+
+    @cached_property
+    def with_raw_response(self) -> RawResponseResource:
+        return RawResponseResource(self)
+
+    @cached_property
+    def with_streaming_response(self) -> RawResponseResource:
+        return RawResponseResource(self, streaming=True)

qca/common/_response.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+from pathlib import Path
+from typing import Any, Callable, Generic, TypeVar
+
+import anyio
+import httpx
+
+from ._exceptions import APIConnectionError, APITimeoutError
+
+T = TypeVar("T")
+
+
+def read_response(response: httpx.Response) -> bytes:
+    try:
+        return response.read()
+    except httpx.TimeoutException as exc:
+        raise APITimeoutError(request=response.request) from exc
+    except httpx.TransportError as exc:
+        raise APIConnectionError(request=response.request) from exc
+
+
+async def aread_response(response: httpx.Response) -> bytes:
+    try:
+        return await response.aread()
+    except httpx.TimeoutException as exc:
+        raise APITimeoutError(request=response.request) from exc
+    except httpx.TransportError as exc:
+        raise APIConnectionError(request=response.request) from exc
+
+
+class APIResponse(Generic[T]):
+    def __init__(self, response: httpx.Response, parse: Callable[[], T]) -> None:
+        self.http_response = response
+        self._parse = parse
+
+    @property
+    def headers(self) -> httpx.Headers:
+        return self.http_response.headers
+
+    @property
+    def status_code(self) -> int:
+        return self.http_response.status_code
+
+    def parse(self) -> T:
+        self.read()
+        return self._parse()
+
+    def read(self) -> bytes:
+        return read_response(self.http_response)
+
+    def iter_bytes(self, chunk_size: int | None = None) -> Iterator[bytes]:
+        return self.http_response.iter_bytes(chunk_size)
+
+    def iter_lines(self) -> Iterator[str]:
+        return self.http_response.iter_lines()
+
+    def close(self) -> None:
+        self.http_response.close()
+
+
+class AsyncAPIResponse(Generic[T]):
+    def __init__(self, response: httpx.Response, parse: Callable[[], T]) -> None:
+        self.http_response = response
+        self._parse = parse
+
+    @property
+    def headers(self) -> httpx.Headers:
+        return self.http_response.headers
+
+    @property
+    def status_code(self) -> int:
+        return self.http_response.status_code
+
+    async def parse(self) -> T:
+        await self.read()
+        return self._parse()
+
+    async def read(self) -> bytes:
+        return await aread_response(self.http_response)
+
+    async def iter_bytes(self, chunk_size: int | None = None) -> AsyncIterator[bytes]:
+        async for chunk in self.http_response.aiter_bytes(chunk_size):
+            yield chunk
+
+    async def iter_lines(self) -> AsyncIterator[str]:
+        async for line in self.http_response.aiter_lines():
+            yield line
+
+    async def close(self) -> None:
+        await self.http_response.aclose()
+
+
+class BinaryAPIResponse:
+    """A streaming download. Close it explicitly or use a context manager."""
+
+    def __init__(self, response: httpx.Response) -> None:
+        self.http_response = response
+
+    @property
+    def headers(self) -> httpx.Headers:
+        return self.http_response.headers
+
+    @property
+    def status_code(self) -> int:
+        return self.http_response.status_code
+
+    def read(self) -> bytes:
+        return read_response(self.http_response)
+
+    def iter_bytes(self, chunk_size: int | None = None) -> Iterator[bytes]:
+        return self.http_response.iter_bytes(chunk_size)
+
+    def write_to_file(self, path: str | Path) -> None:
+        try:
+            with Path(path).open("wb") as output:
+                for chunk in self.iter_bytes():
+                    output.write(chunk)
+        finally:
+            self.close()
+
+    def close(self) -> None:
+        self.http_response.close()
+
+    def __enter__(self) -> BinaryAPIResponse:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncBinaryAPIResponse:
+    def __init__(self, response: httpx.Response) -> None:
+        self.http_response = response
+
+    @property
+    def headers(self) -> httpx.Headers:
+        return self.http_response.headers
+
+    @property
+    def status_code(self) -> int:
+        return self.http_response.status_code
+
+    async def read(self) -> bytes:
+        return await aread_response(self.http_response)
+
+    async def iter_bytes(self, chunk_size: int | None = None) -> AsyncIterator[bytes]:
+        async for chunk in self.http_response.aiter_bytes(chunk_size):
+            yield chunk
+
+    async def write_to_file(self, path: str | Path) -> None:
+        try:
+            async with await anyio.open_file(path, "wb") as output:
+                async for chunk in self.iter_bytes():
+                    await output.write(chunk)
+        finally:
+            await self.close()
+
+    async def close(self) -> None:
+        await self.http_response.aclose()
+
+    async def __aenter__(self) -> AsyncBinaryAPIResponse:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+
+class RawResponseResource:
+    def __init__(self, resource: Any, *, streaming: bool = False) -> None:
+        self._resource = resource
+        self._streaming = streaming
+
+    def __getattr__(self, name: str) -> Any:
+        resource = self._resource
+        attr = getattr(resource, name)
+        if not callable(attr):
+            return RawResponseResource(attr, streaming=self._streaming)
+
+        def wrapped(*args: Any, **kwargs: Any) -> Any:
+            # A separate view carries the response mode, avoiding shared mutable
+            # flags when the same client is used concurrently.
+            view = type(resource)(resource._client._raw_response_view(streaming=self._streaming))
+
+            def call() -> Any:
+                return getattr(view, name)(*args, **kwargs)
+
+            if self._streaming:
+                manager = AsyncResponseContextManager if resource._client._is_async else ResponseContextManager
+                return manager(call)
+            return call()
+
+        return wrapped
+
+
+class ResponseContextManager:
+    def __init__(self, request: Callable[[], Any]) -> None:
+        self._request = request
+        self.response: Any = None
+
+    def __enter__(self) -> Any:
+        self.response = self._request()
+        return self.response
+
+    def __exit__(self, *_: object) -> None:
+        self.response.close()
+
+
+class AsyncResponseContextManager:
+    def __init__(self, request: Callable[[], Any]) -> None:
+        self._request = request
+        self.response: Any = None
+
+    async def __aenter__(self) -> Any:
+        self.response = await self._request()
+        return self.response
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.response.close()

qca/common/_streaming.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Iterator
+from typing import Any, Generic, TypeVar
+
+import httpx
+
+from ._exceptions import APIConnectionError, APIError, APIResponseValidationError, APITimeoutError
+from ._models import parse_response
+
+T = TypeVar("T")
+
+
+class SSEDecoder:
+    def __init__(self) -> None:
+        self.last_event_id: str | None = None
+        self.event: str | None = None
+        self.data: list[str] = []
+
+    def decode(self, line: str) -> tuple[str | None, str] | None:
+        if not line:
+            result = (self.event, "\n".join(self.data)) if self.data else None
+            self.event = None
+            self.data = []
+            return result
+        if line.startswith(":"):
+            return None
+        field, _, value = line.partition(":")
+        if value.startswith(" "):
+            value = value[1:]
+        if field == "data":
+            self.data.append(value)
+        elif field == "event":
+            self.event = value
+        elif field == "id" and "\x00" not in value:
+            self.last_event_id = value
+        return None
+
+
+class BaseStream(Generic[T]):
+    def __init__(self, response: httpx.Response, cast_to: Any) -> None:
+        self.response = response
+        self._cast_to = cast_to
+        self._decoder = SSEDecoder()
+        self._last_event_id: str | None = None
+
+    @property
+    def last_event_id(self) -> str | None:
+        return self._last_event_id
+
+    def _parse(self, frame: tuple[str | None, str]) -> T:
+        event_type, text = frame
+        try:
+            data = json.loads(text)
+        except ValueError as exc:
+            raise APIResponseValidationError(response=self.response, body=text) from exc
+        if event_type == "error" or (isinstance(data, dict) and data.get("type") == "error"):
+            error = data.get("error", data) if isinstance(data, dict) else data
+            message = error.get("message", str(error)) if isinstance(error, dict) else str(error)
+            raise APIError(message, request=self.response.request, body=data)
+        if isinstance(data, dict):
+            data = dict(data)
+            if event_type:
+                data.setdefault("type", event_type)
+            if self._decoder.last_event_id:
+                data.setdefault("id", self._decoder.last_event_id)
+        result = parse_response(self._cast_to, data, self.response)
+        # Checkpoint only after a complete frame is parsed, never on a partial ID.
+        self._last_event_id = self._decoder.last_event_id
+        return result
+
+
+class Stream(BaseStream[T], Iterator[T]):
+    def __init__(self, response: httpx.Response, cast_to: Any) -> None:
+        super().__init__(response, cast_to)
+        self._iterator = self._iter_events()
+
+    def __next__(self) -> T:
+        return next(self._iterator)
+
+    def _iter_events(self) -> Iterator[T]:
+        try:
+            for line in self.response.iter_lines():
+                frame = self._decoder.decode(line)
+                if frame is None:
+                    continue
+                if frame[0] == "ping":
+                    continue
+                if frame[1] == "[DONE]":
+                    return
+                yield self._parse(frame)
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(request=self.response.request) from exc
+        except httpx.TransportError as exc:
+            raise APIConnectionError(request=self.response.request) from exc
+        finally:
+            self.close()
+
+    def close(self) -> None:
+        self.response.close()
+
+    def __enter__(self) -> Stream[T]:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncStream(BaseStream[T], AsyncIterator[T]):
+    def __init__(self, response: httpx.Response, cast_to: Any) -> None:
+        super().__init__(response, cast_to)
+        self._iterator = self._iter_events()
+
+    async def __anext__(self) -> T:
+        return await self._iterator.__anext__()
+
+    async def _iter_events(self) -> AsyncIterator[T]:
+        try:
+            async for line in self.response.aiter_lines():
+                frame = self._decoder.decode(line)
+                if frame is None:
+                    continue
+                if frame[0] == "ping":
+                    continue
+                if frame[1] == "[DONE]":
+                    return
+                yield self._parse(frame)
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(request=self.response.request) from exc
+        except httpx.TransportError as exc:
+            raise APIConnectionError(request=self.response.request) from exc
+        finally:
+            await self.close()
+
+    async def close(self) -> None:
+        await self.response.aclose()
+
+    async def __aenter__(self) -> AsyncStream[T]:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()

qca/common/_types.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from os import PathLike
+from typing import IO, Any, Mapping, Union
+
+
+class NotGiven:
+    """A missing argument, distinct from an explicitly supplied None."""
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_GIVEN = NotGiven()
+FileContent = Union[bytes, IO[bytes], PathLike[str]]
+FileTypes = Union[
+    FileContent,
+    tuple[str, FileContent],
+    tuple[str, FileContent, str],
+    tuple[str, FileContent, str, Mapping[str, str]],
+]
+Body = Mapping[str, Any]

qca/common/_utils.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any, Mapping
+from urllib.parse import quote
+
+from pydantic import BaseModel
+
+from ._types import NOT_GIVEN, NotGiven
+
+
+def strip_not_given(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        value = value.model_dump(mode="json", by_alias=True, exclude_unset=True)
+    if isinstance(value, Mapping):
+        return {k: strip_not_given(v) for k, v in value.items() if not isinstance(v, NotGiven)}
+    if isinstance(value, (list, tuple)):
+        return [strip_not_given(v) for v in value if not isinstance(v, NotGiven)]
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    return value
+
+
+def path_template(path: str, **params: str) -> str:
+    for name, value in params.items():
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"Expected a non-empty string for {name}")
+        if value in (".", ".."):
+            raise ValueError(f"Invalid path segment for {name}")
+        path = path.replace("{" + name + "}", quote(value, safe=""))
+    return path
+
+
+def make_request_options(
+    *,
+    body: Mapping[str, Any],
+    query: Mapping[str, Any],
+    headers: Mapping[str, Any],
+    extra_headers: Mapping[str, str] | None,
+    extra_query: Mapping[str, Any] | None,
+    extra_body: Mapping[str, Any] | None,
+    timeout: Any = NOT_GIVEN,
+) -> dict[str, Any]:
+    # Preserve tuples and file objects until multipart encoding.
+    return {
+        "body": {**{k: v for k, v in body.items() if not isinstance(v, NotGiven)}, **(extra_body or {})},
+        "query": strip_not_given({**query, **(extra_query or {})}),
+        "headers": {
+            **{k: v for k, v in headers.items() if not isinstance(v, NotGiven) and v is not None},
+            **(extra_headers or {}),
+        },
+        "timeout": timeout,
+    }
+
+
+def query_pairs(query: Mapping[str, Any]) -> list[tuple[str, str]]:
+    pairs: list[tuple[str, str]] = []
+
+    def add(key: str, value: Any) -> None:
+        if value is None or isinstance(value, NotGiven):
+            return
+        if isinstance(value, Mapping):
+            for child, item in value.items():
+                add(f"{key}[{child}]", item)
+        elif isinstance(value, (list, tuple)):
+            for item in value:
+                add(key, item)
+        else:
+            pairs.append((key, str(value).lower() if isinstance(value, bool) else str(value)))
+
+    for key, value in query.items():
+        add(key, value)
+    return pairs

qca/common/credentials.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class Credential(Protocol):
+    def get_token(self) -> str:
+        """Return the current access token. Called for each HTTP attempt."""
+        ...
+
+
+class AsyncCredential(Protocol):
+    async def get_token(self) -> str: ...

qca/common/pagination.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from typing import Any, Generic, TypeVar
+
+from pydantic import Field, PrivateAttr
+
+from ._models import BaseModel
+
+T = TypeVar("T")
+
+
+class BasePage(BaseModel, Generic[T]):
+    data: list[T] = Field(default_factory=list)
+    has_more: bool | None = None
+    first_id: str | None = None
+    last_id: str | None = None
+    next_page: str | None = None
+    _query: dict[str, Any] = PrivateAttr(default_factory=dict)
+    _style: str = PrivateAttr(default="Page")
+    _fetch: Any = PrivateAttr(default=None)
+
+    def _next_query(self) -> dict[str, Any] | None:
+        if self.has_more is False:
+            return None
+        query = dict(self._query)
+        if self._style in ("PageCursor", "BidirectionalPageCursor", "TokenPage"):
+            key = "page_token" if self._style == "TokenPage" else "page"
+            cursor = self.next_page
+        else:
+            if not self.data:
+                return None
+            key = "before_id" if query.get("before_id") else "after_id"
+            cursor = self.first_id if key == "before_id" else self.last_id
+        if not cursor:
+            return None
+        if query.get(key) == cursor:
+            raise RuntimeError("Pagination cursor did not advance")
+        for other in ("after_id", "before_id", "page", "page_token"):
+            if other != key:
+                query[other] = None
+        query[key] = cursor
+        return query
+
+    def has_next_page(self) -> bool:
+        return self._next_query() is not None
+
+
+class SyncPage(BasePage[T]):
+    def get_next_page(self) -> SyncPage[T]:
+        query = self._next_query()
+        if query is None:
+            raise RuntimeError("No more pages")
+        if self._fetch is None:
+            raise RuntimeError("Page is not attached to a client request")
+        return self._fetch(query)
+
+    def iter_pages(self) -> Iterator[SyncPage[T]]:
+        page = self
+        seen: set[str] = set()
+        while True:
+            yield page
+            query = page._next_query()
+            if query is None:
+                break
+            fingerprint = repr(query)
+            if fingerprint in seen:
+                raise RuntimeError("Pagination cursor cycle detected")
+            seen.add(fingerprint)
+            page = page.get_next_page()
+
+    def __iter__(self) -> Iterator[T]:  # type: ignore[override]
+        for page in self.iter_pages():
+            yield from page.data
+
+
+class AsyncPage(BasePage[T]):
+    async def get_next_page(self) -> AsyncPage[T]:
+        query = self._next_query()
+        if query is None:
+            raise RuntimeError("No more pages")
+        if self._fetch is None:
+            raise RuntimeError("Page is not attached to a client request")
+        return await self._fetch(query)
+
+    async def iter_pages(self) -> AsyncIterator[AsyncPage[T]]:
+        page = self
+        seen: set[str] = set()
+        while True:
+            yield page
+            query = page._next_query()
+            if query is None:
+                break
+            fingerprint = repr(query)
+            if fingerprint in seen:
+                raise RuntimeError("Pagination cursor cycle detected")
+            seen.add(fingerprint)
+            page = await page.get_next_page()
+
+    async def __aiter__(self) -> AsyncIterator[T]:
+        async for page in self.iter_pages():
+            for item in page.data:
+                yield item
+
+
+class AsyncPaginator(Generic[T]):
+    """Await the first page, or iterate items directly with async for."""
+
+    def __init__(self, fetch: Callable[[], Awaitable[AsyncPage[T]]]) -> None:
+        self._fetch = fetch
+
+    def __await__(self) -> Any:
+        return self._fetch().__await__()
+
+    async def __aiter__(self) -> AsyncIterator[T]:
+        page = await self._fetch()
+        async for item in page:
+            yield item

qca/forward/__init__.py

@@ -0,0 +1,7 @@
+from ._client import AsyncForward as AsyncForward
+from ._client import Forward as Forward
+
+Client = Forward
+AsyncClient = AsyncForward
+ForwardClient = Forward
+AsyncForwardClient = AsyncForward