contree-client 0.1.0__py3-none-any.whl

contree_client/__init__.py

@@ -0,0 +1,174 @@
+"""Contree API client, generated from the OpenAPI specification.
+
+Pick a backend module and import its ``ContreeClient``::
+
+    from contree_client.requests import ContreeClient
+
+Synchronous backends export ``ContreeClient``, asynchronous ones
+export ``ContreeAsyncClient``: ``contree_client.http`` (stdlib
+http.client, no extra dependencies), ``contree_client.urllib3`` and
+``contree_client.requests`` (sync), ``contree_client.httpx`` (both)
+and ``contree_client.aiohttp`` (async).  All of them share the
+interface of :class:`contree_client.types.ContreeSyncClient` or
+:class:`contree_client.types.ContreeAsyncClient` - annotate against
+those base classes to stay backend-agnostic.
+
+When any installed backend will do, let the package pick one::
+
+    from contree_client.sync import ContreeClient
+    from contree_client.asyncio import ContreeAsyncClient
+
+Generated by codegen from the OpenAPI spec - do not edit.
+"""
+
+from .exceptions import (
+    BadRequestError,
+    ConflictError,
+    ContreeAPIError,
+    ContreeError,
+    ForbiddenError,
+    GoneError,
+    NotFoundError,
+    ServerError,
+    SSEStreamError,
+    TooEarlyError,
+    UnauthorizedError,
+    UnprocessableEntityError,
+)
+from .models import (
+    ACTIVE_STATUSES,
+    TERMINAL_STATUSES,
+    ContreeModel,
+    DirectoryList,
+    Error,
+    EventData,
+    EventDataCompletion,
+    EventDataExit,
+    EventDataInit,
+    EventDataNetwork,
+    EventDataNetworkConfigured,
+    EventDataShutdown,
+    EventDataSizeCap,
+    EventDataSpawn,
+    EventDataStream,
+    EventDataTruncated,
+    EventResources,
+    File,
+    FileItem,
+    FileResponse,
+    FilesListResponse,
+    FileSpec,
+    Image,
+    ImageImportMetadata,
+    ImageImportMetadataRegistry,
+    ImageImportMetadataRegistryCredentials,
+    ImageImportRegistry,
+    ImageImportRegistryCredentials,
+    ImageImportRequest,
+    ImageListResponse,
+    InstanceResourcesLimits,
+    InstanceResult,
+    InstanceResultResources,
+    InstanceResultState,
+    InstanceSpawnRequest,
+    InstanceSpawnResponse,
+    NetworkInterface,
+    OperationEvent,
+    OperationEventType,
+    OperationInstanceMetadata,
+    OperationResponse,
+    OperationResult,
+    OperationStatus,
+    OperationSummary,
+    StreamRepr,
+    WhoAmIResponse,
+    decode_chunk,
+    decode_stream,
+    parse_datetime,
+)
+from .profiles import (
+    Profile,
+    ProfileError,
+    load_profiles,
+    resolve_profile,
+)
+from .runtime import (
+    RequestSpec,
+    ResponseData,
+    RetryPolicy,
+)
+from .spec_info import (
+    DEFAULT_BASE_URL,
+)
+
+__all__ = [
+    "ACTIVE_STATUSES",
+    "DEFAULT_BASE_URL",
+    "TERMINAL_STATUSES",
+    "BadRequestError",
+    "ConflictError",
+    "ContreeAPIError",
+    "ContreeError",
+    "ContreeModel",
+    "DirectoryList",
+    "Error",
+    "EventData",
+    "EventDataCompletion",
+    "EventDataExit",
+    "EventDataInit",
+    "EventDataNetwork",
+    "EventDataNetworkConfigured",
+    "EventDataShutdown",
+    "EventDataSizeCap",
+    "EventDataSpawn",
+    "EventDataStream",
+    "EventDataTruncated",
+    "EventResources",
+    "File",
+    "FileItem",
+    "FileResponse",
+    "FileSpec",
+    "FilesListResponse",
+    "ForbiddenError",
+    "GoneError",
+    "Image",
+    "ImageImportMetadata",
+    "ImageImportMetadataRegistry",
+    "ImageImportMetadataRegistryCredentials",
+    "ImageImportRegistry",
+    "ImageImportRegistryCredentials",
+    "ImageImportRequest",
+    "ImageListResponse",
+    "InstanceResourcesLimits",
+    "InstanceResult",
+    "InstanceResultResources",
+    "InstanceResultState",
+    "InstanceSpawnRequest",
+    "InstanceSpawnResponse",
+    "NetworkInterface",
+    "NotFoundError",
+    "OperationEvent",
+    "OperationEventType",
+    "OperationInstanceMetadata",
+    "OperationResponse",
+    "OperationResult",
+    "OperationStatus",
+    "OperationSummary",
+    "Profile",
+    "ProfileError",
+    "RequestSpec",
+    "ResponseData",
+    "RetryPolicy",
+    "SSEStreamError",
+    "ServerError",
+    "StreamRepr",
+    "TooEarlyError",
+    "UnauthorizedError",
+    "UnprocessableEntityError",
+    "WhoAmIResponse",
+    "decode_chunk",
+    "decode_stream",
+    "load_profiles",
+    "parse_datetime",
+    "resolve_profile",
+]

contree_client/aiohttp.py

@@ -0,0 +1,153 @@
+"""Contree API client backed by aiohttp."""
+
+from __future__ import annotations
+
+import asyncio
+import gzip
+import ssl
+from collections.abc import AsyncGenerator
+from contextlib import suppress
+
+import aiohttp
+
+from . import base
+from .runtime import (
+    CHUNK_SIZE,
+    RequestSpec,
+    ResponseData,
+    RetryPolicy,
+    error_for_response,
+    library_version,
+)
+from .spec_info import DEFAULT_BASE_URL
+from .types import logger
+
+
+class ContreeAsyncClient(base.ContreeAsyncClient):
+    """Asynchronous Contree API client on top of `aiohttp.ClientSession`.
+
+    The session is created lazily on the first request so the client
+    may be constructed outside of a running event loop.
+    """
+
+    log = logger.getChild("aiohttp")
+    UA_TRANSPORT_LIBRARY = library_version(aiohttp)
+    retryable_errors = (
+        aiohttp.ClientConnectionError,
+        aiohttp.ServerConnectionError,
+    )
+    nonretryable_errors = (TimeoutError, asyncio.TimeoutError)
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        project: str | None = None,
+        timeout: float | None = 300.0,
+        retry: RetryPolicy | None = None,
+        identity: str | None = None,
+        ssl_context: ssl.SSLContext | None = None,
+        # adapter-specific, prefixed by adapter name
+        aiohttp_session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        super().__init__(
+            token,
+            base_url=base_url,
+            project=project,
+            timeout=timeout,
+            retry=retry,
+            identity=identity,
+        )
+        if aiohttp_session is not None and ssl_context is not None:
+            raise ValueError(
+                "ssl_context cannot be combined with aiohttp_session;"
+                " configure TLS on the session connector itself"
+            )
+        self.__owns_session = aiohttp_session is None
+        self._session = aiohttp_session
+        self._ssl_context = ssl_context
+
+    def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            connector = (
+                aiohttp.TCPConnector(ssl=self._ssl_context)
+                if self._ssl_context is not None
+                else None
+            )
+            self._session = aiohttp.ClientSession(connector=connector)
+        return self._session
+
+    async def open(self) -> None:
+        """Create the session eagerly (`async with client:` path)."""
+        self._get_session()
+
+    async def request(self, spec: RequestSpec) -> ResponseData:
+        url = self.build_url(spec)
+        async with self._get_session().request(
+            spec.method,
+            url,
+            data=spec.body,
+            headers=self.build_headers(spec),
+            allow_redirects=False,
+            timeout=aiohttp.ClientTimeout(total=self.timeout),
+        ) as response:
+            body = await response.read()
+            return ResponseData(
+                status=response.status,
+                headers={k.lower(): v for k, v in response.headers.items()},
+                body=body,
+            )
+
+    async def stream(
+        self,
+        spec: RequestSpec,
+        auto_decompress: bool = True,
+    ) -> AsyncGenerator[bytes, None]:
+        url = self.build_url(spec)
+        async with self._get_session().request(
+            spec.method,
+            url,
+            data=spec.body,
+            headers=self.build_headers(spec),
+            allow_redirects=False,
+            auto_decompress=auto_decompress,
+            timeout=aiohttp.ClientTimeout(
+                total=None,
+                sock_connect=self.timeout,
+                # only SSE may idle (bounded by spec.read_timeout
+                # when a deadline is set); downloads must time out
+                sock_read=(
+                    spec.read_timeout
+                    if spec.accept == "text/event-stream"
+                    else self.timeout
+                ),
+            ),
+        ) as response:
+            self.log.debug("%s %s -> %d (stream)", spec.method, url, response.status)
+            if not 200 <= response.status < 300:
+                body = await response.read()
+                # auto_decompress=False applies to the payload only:
+                # the error body must still be decoded, or the parsed
+                # server message is lost
+                encoding = (response.headers.get("Content-Encoding") or "").lower()
+                if not auto_decompress and encoding == "gzip":
+                    with suppress(gzip.BadGzipFile, OSError):
+                        body = gzip.decompress(body)
+                raise error_for_response(
+                    ResponseData(
+                        status=response.status,
+                        headers={k.lower(): v for k, v in response.headers.items()},
+                        body=body,
+                    )
+                )
+            async for chunk in response.content.iter_chunked(CHUNK_SIZE):
+                yield chunk
+
+    async def close(self) -> None:
+        if (
+            self.__owns_session
+            and self._session is not None
+            and not self._session.closed
+        ):
+            await self._session.close()

contree_client/asyncio.py

@@ -0,0 +1,48 @@
+"""Autodetected asynchronous client.
+
+Tries the installed backends in priority order and exposes the first
+importable one as ``ContreeAsyncClient``::
+
+    from contree_client.asyncio import ContreeAsyncClient
+
+Raises an ImportError with an installation suggestion when neither
+aiohttp nor httpx is available.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+
+from . import base
+from .types import logger
+
+log = logger.getChild("asyncio")
+
+# Ordered by ecosystem popularity - PyPI download totals per ClickPy
+# (https://clickpy.clickhouse.com): aiohttp ~10B, httpx ~7.6B.
+BACKEND_PRIORITY = ("aiohttp", "httpx")
+
+
+def detect_backend() -> tuple[str, type[base.ContreeAsyncClient]]:
+    for name in BACKEND_PRIORITY:
+        try:
+            module = import_module(f"contree_client.{name}")
+        except ModuleNotFoundError as exc:
+            # only the backend's own missing dependency (or a wholly
+            # absent backend module) means "not installed"; anything
+            # else is a real error to surface
+            if exc.name not in (name, f"contree_client.{name}"):
+                raise
+            continue
+        client_class: type[base.ContreeAsyncClient] = module.ContreeAsyncClient
+        log.debug("autodetected backend: %s", name)
+        return name, client_class
+    raise ImportError(
+        "no asynchronous contree-client backend could be imported;"
+        " install one of:\n"
+        "  pip install contree-client[aiohttp]\n"
+        "  pip install contree-client[httpx]"
+    )
+
+
+BACKEND, ContreeAsyncClient = detect_backend()