contree-client 0.2.1.dev0__tar.gz → 0.3.0__tar.gz

{contree_client-0.2.1.dev0 → contree_client-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contree-client
-Version: 0.2.1.dev0
+Version: 0.3.0
 Summary: Python client for the Contree API, generated from the OpenAPI specification
 Author: Dmitry Orlov
 Author-email: Dmitry Orlov <mosquito@nebius.com>

{contree_client-0.2.1.dev0 → contree_client-0.3.0}/contree_client/__init__.py

@@ -25,7 +25,12 @@ from .exceptions import (
     BadRequestError,
     ConflictError,
     ContreeAPIError,
+    ContreeConnectionError,
     ContreeError,
+    ContreeHTTPError,
+    ContreeStreamError,
+    ContreeTimeoutError,
+    ContreeTransportError,
     ForbiddenError,
     GoneError,
     NotFoundError,
@@ -115,8 +120,13 @@ __all__ = [
     "ClosableStreamRepr",
     "ConflictError",
     "ContreeAPIError",
+    "ContreeConnectionError",
     "ContreeError",
+    "ContreeHTTPError",
     "ContreeModel",
+    "ContreeStreamError",
+    "ContreeTimeoutError",
+    "ContreeTransportError",
     "DirectoryList",
     "Error",
     "EventData",

contree_client-0.3.0/contree_client/aiohttp.py

@@ -0,0 +1,190 @@
+"""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 .exceptions import ContreeConnectionError, ContreeStreamError, ContreeTimeoutError
+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 ContreeAiohttpConnectionError(
+    ContreeConnectionError, aiohttp.ClientConnectionError
+):
+    """A `ContreeConnectionError` that is also an `aiohttp.ClientConnectionError`."""
+
+
+class ContreeAiohttpTimeoutError(ContreeTimeoutError, TimeoutError):
+    """A `ContreeTimeoutError` that is also a stdlib `TimeoutError`."""
+
+
+class ContreeAiohttpStreamError(ContreeStreamError, aiohttp.ClientPayloadError):
+    """A `ContreeStreamError` that is also an `aiohttp.ClientPayloadError`."""
+
+
+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,
+        aiohttp.ClientPayloadError,
+    )
+    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)
+        try:
+            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,
+                )
+        except self.nonretryable_errors as exc:
+            raise ContreeAiohttpTimeoutError.wrap(exc) from exc
+        except aiohttp.ClientPayloadError as exc:
+            raise ContreeAiohttpStreamError.wrap(exc) from exc
+        except self.retryable_errors as exc:
+            raise ContreeAiohttpConnectionError.wrap(exc) from exc
+
+    async def stream(
+        self,
+        spec: RequestSpec,
+        auto_decompress: bool = True,
+    ) -> AsyncGenerator[bytes, None]:
+        url = self.build_url(spec)
+        try:
+            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:
+                    try:
+                        body = await response.read()
+                    except self.retryable_errors:
+                        # The status is authoritative even when its optional
+                        # diagnostic body is interrupted.
+                        body = b""
+                    # 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
+        except self.nonretryable_errors as exc:
+            raise ContreeAiohttpTimeoutError.wrap(exc) from exc
+        except aiohttp.ClientPayloadError as exc:
+            raise ContreeAiohttpStreamError.wrap(exc) from exc
+        except self.retryable_errors as exc:
+            raise ContreeAiohttpConnectionError.wrap(exc) from exc
+
+    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-0.2.1.dev0 → contree_client-0.3.0}/contree_client/base.py

@@ -16,9 +16,9 @@ import platform
 import sys
 import time
 from abc import ABC, abstractmethod
-from collections.abc import AsyncGenerator, Iterable, Iterator
+from collections.abc import AsyncGenerator, Iterable, Iterator, Sequence
 from contextlib import aclosing
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from types import EllipsisType, TracebackType
 from typing import IO, Any, Literal, TypeVar
@@ -35,6 +35,7 @@ from .exceptions import (
 from .models import (
     ClosableStreamRepr,
     DirectoryList,
+    EventDataCompletion,
     File,
     FileResponse,
     FilesListResponse,
@@ -55,6 +56,7 @@ from .models import (
 )
 from .profiles import AUTH_TYPE_IAM, Profile, ProfileError, resolve_profile
 from .runtime import (
+    EVENTS_UNAVAILABLE_STATUSES,
     TIGHT_LOOP_FLOOR,
     BodyFormatter,
     HeaderFormatter,
@@ -370,10 +372,13 @@ class ContreeSyncClient(ContreeClientBase, ABC):
         (410/425/5xx) reconnect from the last received event id, so no
         event is delivered twice; before every reconnect the operation
         status is probed and iteration ends if it already became
-        terminal. Other API errors (404, 403, ...) propagate.
+        terminal. A status meaning the events endpoint itself doesn't
+        exist for this operation/server (400/404/405/406) stops
+        reconnecting and instead polls :meth:`get_operation_status`
+        until the operation is terminal. Other API errors propagate.
         Iteration also ends after the ``completion`` event. *timeout*
-        bounds the whole wait; it is enforced between events and
-        reconnect cycles and raises :class:`TimeoutError`.
+        bounds the whole wait; it is enforced between events, reconnect
+        cycles and polling, and raises :class:`TimeoutError`.
         """
         last_id = last_event_id
         delays = retry_generator()
@@ -410,6 +415,55 @@ class ContreeSyncClient(ContreeClientBase, ABC):
                     last_id = exc.last_event_id
                 self.log.warning("stream error (last_id=%s): %s", last_id, exc)
             except ContreeAPIError as exc:
+                if exc.status in EVENTS_UNAVAILABLE_STATUSES:
+                    # the endpoint is gone, not just failing: reconnecting
+                    # the same request will never work, but the operation
+                    # may still finish - stop touching /events and poll
+                    # status instead for the rest of this wait
+                    self.log.warning(
+                        "events endpoint unavailable (%d), falling back to polling",
+                        exc.status,
+                    )
+                    while True:
+                        check_deadline()
+                        try:
+                            response = self.get_operation_status(operation_id)
+                        except (ContreeError, *self.retryable_errors):
+                            response = None
+                        if (
+                            response is not None
+                            and not isinstance(response.status, EllipsisType)
+                            and response.status.is_terminal()
+                        ):
+                            # no event log to relay, but a caller of
+                            # follow_operation_events must still observe a
+                            # terminal completion rather than nothing at all
+                            last_id = 0 if last_id is None else last_id + 1
+                            duration = response.duration
+                            image_size = response.image_size
+                            yield OperationEvent(
+                                id=last_id,
+                                ts=datetime.now(timezone.utc),
+                                type="completion",
+                                data=EventDataCompletion(
+                                    status=response.status,
+                                    duration_ms=round(duration * 1000)
+                                    if isinstance(duration, (int, float))
+                                    else 0,
+                                    result_image_uuid=response.result_image_uuid,
+                                    error=response.error,
+                                    image_size_bytes=(
+                                        image_size
+                                        if isinstance(image_size, int)
+                                        else ...
+                                    ),
+                                ),
+                            )
+                            return
+                        delay = next(delays)
+                        if deadline is not None:
+                            delay = min(delay, max(0.0, deadline - time.monotonic()))
+                        time.sleep(delay)
                 retryable = exc.status in (410, 425) or 500 <= exc.status < 600
                 if not retryable:
                     raise
@@ -925,9 +979,12 @@ class ContreeSyncClient(ContreeClientBase, ABC):
             uid: User ID to run the process as. Example: ``0``.
             gid: Group ID to run the process as. Example: ``0``.
             timeout: Maximum execution time in seconds Example: ``60``.
-            truncate_output_at: Maximum number of bytes to keep from
-                stdout/stderr. Default is ``1048576`` (1 MiB). The maximum
-                value is ``10485760`` (10 MiB). Example: ``65535``.
+            truncate_output_at: Maximum number of bytes to keep per stream
+                (stdout, stderr, and stdin) in the subprocess event log.
+                Does not affect stdin delivery to the child, which always
+                receives the complete stream regardless of this cap. Default
+                is ``1048576`` (1 MiB). The maximum value is ``10485760``
+                (10 MiB). Example: ``65535``.
             files: Map of absolute file paths to file metadata Example:
                 ``{"/root/hello.txt":{"uuid":"a9165a5d-5c86-4bd8-8ee4-ae46c...``.
         """
@@ -1335,9 +1392,11 @@ class ContreeSyncClient(ContreeClientBase, ABC):
                 main process and exec'd subprocesses. With ``close=false``
                 the pipe stays open and more data can be written via
                 ``POST /operations/{operationId}/subprocesses/{spid}/stdin``.
-            truncate_output_at: Maximum number of bytes of stdout / stderr
-                to keep. Defaults to 1 MiB; capped at 10 MiB. Example:
-                ``65535``.
+            truncate_output_at: Maximum number of bytes to keep per stream
+                (stdout, stderr, and stdin) in the subprocess event log.
+                Does not affect delivery to the child — stdin is always
+                delivered in full regardless of this cap. Defaults to 1 MiB;
+                capped at 10 MiB. Example: ``65535``.
         """
         spec = operations.build_operation_subprocess_create(
             operation_id=operation_id,
@@ -1618,10 +1677,10 @@ class ContreeSyncClient(ContreeClientBase, ABC):
     def inspect_image_grep(
         self,
         image_uuid: str,
-        pattern: str,
+        pattern: str | Sequence[str],
         *,
-        path: str | None = None,
-        glob: str | None = None,
+        path: str | Sequence[str] | None = None,
+        glob: str | Sequence[str] | None = None,
         max_count: int | None = None,
         max_total: int | None = None,
         case: Literal["sensitive", "insensitive", "smart"] | None = None,
@@ -1863,10 +1922,13 @@ class ContreeAsyncClient(ContreeClientBase, ABC):
         (410/425/5xx) reconnect from the last received event id, so no
         event is delivered twice; before every reconnect the operation
         status is probed and iteration ends if it already became
-        terminal. Other API errors (404, 403, ...) propagate.
+        terminal. A status meaning the events endpoint itself doesn't
+        exist for this operation/server (400/404/405/406) stops
+        reconnecting and instead polls :meth:`get_operation_status`
+        until the operation is terminal. Other API errors propagate.
         Iteration also ends after the ``completion`` event. *timeout*
-        bounds the whole wait; it is enforced between events and
-        reconnect cycles and raises :class:`TimeoutError`.
+        bounds the whole wait; it is enforced between events, reconnect
+        cycles and polling, and raises :class:`TimeoutError`.
         """
         last_id = last_event_id
         delays = retry_generator()
@@ -1894,6 +1956,24 @@ class ContreeAsyncClient(ContreeClientBase, ABC):
                 check_deadline()
                 raise
 
+        async def operation_status_before_deadline() -> OperationResponse | None:
+            try:
+                if deadline is None:
+                    return await self.get_operation_status(operation_id)
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    check_deadline()
+                try:
+                    return await asyncio.wait_for(
+                        self.get_operation_status(operation_id),
+                        timeout=remaining,
+                    )
+                except asyncio.TimeoutError:
+                    check_deadline()
+                    raise
+            except (ContreeError, *self.retryable_errors):
+                return None
+
         while True:
             check_deadline()
             events_before = last_id
@@ -1923,6 +2003,51 @@ class ContreeAsyncClient(ContreeClientBase, ABC):
                     last_id = exc.last_event_id
                 self.log.warning("stream error (last_id=%s): %s", last_id, exc)
             except ContreeAPIError as exc:
+                if exc.status in EVENTS_UNAVAILABLE_STATUSES:
+                    # the endpoint is gone, not just failing: reconnecting
+                    # the same request will never work, but the operation
+                    # may still finish - stop touching /events and poll
+                    # status instead for the rest of this wait
+                    self.log.warning(
+                        "events endpoint unavailable (%d), falling back to polling",
+                        exc.status,
+                    )
+                    while True:
+                        response = await operation_status_before_deadline()
+                        if (
+                            response is not None
+                            and not isinstance(response.status, EllipsisType)
+                            and response.status.is_terminal()
+                        ):
+                            # no event log to relay, but a caller of
+                            # follow_operation_events must still observe a
+                            # terminal completion rather than nothing at all
+                            last_id = 0 if last_id is None else last_id + 1
+                            duration = response.duration
+                            image_size = response.image_size
+                            yield OperationEvent(
+                                id=last_id,
+                                ts=datetime.now(timezone.utc),
+                                type="completion",
+                                data=EventDataCompletion(
+                                    status=response.status,
+                                    duration_ms=round(duration * 1000)
+                                    if isinstance(duration, (int, float))
+                                    else 0,
+                                    result_image_uuid=response.result_image_uuid,
+                                    error=response.error,
+                                    image_size_bytes=(
+                                        image_size
+                                        if isinstance(image_size, int)
+                                        else ...
+                                    ),
+                                ),
+                            )
+                            return
+                        delay = next(delays)
+                        if deadline is not None:
+                            delay = min(delay, max(0.0, deadline - time.monotonic()))
+                        await asyncio.sleep(delay)
                 retryable = exc.status in (410, 425) or 500 <= exc.status < 600
                 if not retryable:
                     raise
@@ -2450,9 +2575,12 @@ class ContreeAsyncClient(ContreeClientBase, ABC):
             uid: User ID to run the process as. Example: ``0``.
             gid: Group ID to run the process as. Example: ``0``.
             timeout: Maximum execution time in seconds Example: ``60``.
-            truncate_output_at: Maximum number of bytes to keep from
-                stdout/stderr. Default is ``1048576`` (1 MiB). The maximum
-                value is ``10485760`` (10 MiB). Example: ``65535``.
+            truncate_output_at: Maximum number of bytes to keep per stream
+                (stdout, stderr, and stdin) in the subprocess event log.
+                Does not affect stdin delivery to the child, which always
+                receives the complete stream regardless of this cap. Default
+                is ``1048576`` (1 MiB). The maximum value is ``10485760``
+                (10 MiB). Example: ``65535``.
             files: Map of absolute file paths to file metadata Example:
                 ``{"/root/hello.txt":{"uuid":"a9165a5d-5c86-4bd8-8ee4-ae46c...``.
         """
@@ -2861,9 +2989,11 @@ class ContreeAsyncClient(ContreeClientBase, ABC):
                 main process and exec'd subprocesses. With ``close=false``
                 the pipe stays open and more data can be written via
                 ``POST /operations/{operationId}/subprocesses/{spid}/stdin``.
-            truncate_output_at: Maximum number of bytes of stdout / stderr
-                to keep. Defaults to 1 MiB; capped at 10 MiB. Example:
-                ``65535``.
+            truncate_output_at: Maximum number of bytes to keep per stream
+                (stdout, stderr, and stdin) in the subprocess event log.
+                Does not affect delivery to the child — stdin is always
+                delivered in full regardless of this cap. Defaults to 1 MiB;
+                capped at 10 MiB. Example: ``65535``.
         """
         spec = operations.build_operation_subprocess_create(
             operation_id=operation_id,
@@ -3149,10 +3279,10 @@ class ContreeAsyncClient(ContreeClientBase, ABC):
     async def inspect_image_grep(
         self,
         image_uuid: str,
-        pattern: str,
+        pattern: str | Sequence[str],
         *,
-        path: str | None = None,
-        glob: str | None = None,
+        path: str | Sequence[str] | None = None,
+        glob: str | Sequence[str] | None = None,
         max_count: int | None = None,
         max_total: int | None = None,
         case: Literal["sensitive", "insensitive", "smart"] | None = None,

{contree_client-0.2.1.dev0 → contree_client-0.3.0}/contree_client/exceptions.py

@@ -9,11 +9,36 @@ class ContreeError(Exception):
     """Base class for all contree-client errors."""
 
 
-class DecompressionError(ContreeError):
+class ContreeTransportError(ContreeError):
+    """Wire-level error base; each backend's subclass also inherits its
+    matching native exception type. Construct via :meth:`wrap`."""
+
+    @classmethod
+    def wrap(cls, original: BaseException) -> BaseException:
+        """Build an instance from *original*; return it unwrapped on failure."""
+        try:
+            return cls(*original.args)
+        except Exception:
+            return original
+
+
+class ContreeConnectionError(ContreeTransportError):
+    """Failed to establish or maintain the connection."""
+
+
+class ContreeTimeoutError(ContreeTransportError):
+    """A connect, read or overall deadline elapsed."""
+
+
+class ContreeStreamError(ContreeTransportError):
+    """The response body arrived but could not be consumed correctly."""
+
+
+class DecompressionError(ContreeStreamError):
     """The compressed response body ended prematurely or is corrupt."""
 
 
-class SSEStreamError(ContreeError):
+class SSEStreamError(ContreeStreamError):
     """The server terminated an SSE stream with an in-band error frame.
 
     Per the API convention this is the in-band equivalent of a 410:
@@ -31,7 +56,11 @@ class SSEStreamError(ContreeError):
         self.last_event_id = last_event_id
 
 
-class ContreeAPIError(ContreeError):
+class ContreeHTTPError(ContreeTransportError):
+    """A full HTTP response with a status line was received."""
+
+
+class ContreeAPIError(ContreeHTTPError):
     """An HTTP error response returned by the Contree API."""
 
     def __init__(

{contree_client-0.2.1.dev0 → contree_client-0.3.0}/contree_client/http.py

@@ -25,6 +25,7 @@ from collections.abc import Callable, Iterator
 from urllib.parse import urlsplit
 
 from . import base
+from .exceptions import ContreeConnectionError, ContreeTimeoutError
 from .runtime import (
     CHUNK_SIZE,
     RequestSpec,
@@ -38,6 +39,15 @@ from .runtime import (
 from .spec_info import DEFAULT_BASE_URL
 from .types import logger
 
+
+class ContreeHttpConnectionError(ContreeConnectionError, OSError):
+    """A `ContreeConnectionError` that is also an `OSError`."""
+
+
+class ContreeHttpTimeoutError(ContreeTimeoutError, TimeoutError):
+    """A `ContreeTimeoutError` that is also a stdlib `TimeoutError`."""
+
+
 # the reused keepalive connection may have been closed by the server
 # while it sat in the pool; these surface exactly that and warrant one
 # resend on a fresh connection (RemoteDisconnected is a BadStatusLine)
@@ -271,11 +281,19 @@ class ContreeClient(base.ContreeSyncClient):
                     self.log.debug("stale pooled connection, resending: %s", exc)
                     rewind_body(spec, start)
                     continue
+                if isinstance(exc, self.nonretryable_errors):
+                    raise ContreeHttpTimeoutError.wrap(exc) from exc
+                if isinstance(exc, self.retryable_errors):
+                    raise ContreeHttpConnectionError.wrap(exc) from exc
                 raise
         try:
             data = read_response(response)
-        except BaseException:
+        except BaseException as exc:
             self._pool.discard(connection)
+            if isinstance(exc, self.nonretryable_errors):
+                raise ContreeHttpTimeoutError.wrap(exc) from exc
+            if isinstance(exc, self.retryable_errors):
+                raise ContreeHttpConnectionError.wrap(exc) from exc
             raise
         # the body is fully drained: the connection is reusable unless
         # the server asked to close it (`Connection: close` sets
@@ -295,8 +313,12 @@ class ContreeClient(base.ContreeSyncClient):
         connection = self._connect()
         try:
             response = self._send_on(connection, spec)
-        except BaseException:
+        except BaseException as exc:
             connection.close()
+            if isinstance(exc, self.nonretryable_errors):
+                raise ContreeHttpTimeoutError.wrap(exc) from exc
+            if isinstance(exc, self.retryable_errors):
+                raise ContreeHttpConnectionError.wrap(exc) from exc
             raise
         try:
             self.log.debug(
@@ -326,6 +348,12 @@ class ContreeClient(base.ContreeSyncClient):
                 chunk = decoder.decompress(raw)
                 if chunk:
                     yield chunk
+        except BaseException as exc:
+            if isinstance(exc, self.nonretryable_errors):
+                raise ContreeHttpTimeoutError.wrap(exc) from exc
+            if isinstance(exc, self.retryable_errors):
+                raise ContreeHttpConnectionError.wrap(exc) from exc
+            raise
         finally:
             connection.close()