sg-python-api 0.1.2__py3-none-any.whl → 0.2.1__py3-none-any.whl

shotgun_api3/_async_driver.py

@@ -13,7 +13,7 @@ from io import BytesIO
 from typing import Protocol, TypeVar, cast
 
 from . import _protocol, _transport
-from ._async_transport import AsyncTransport
+from ._async_transport import AsyncTransport, AsyncUploadObserver
 from ._config import (
     EventRoute,
     ObserverCallback,
@@ -37,7 +37,6 @@ from ._execution import (
     build_rpc_request,
 )
 from ._transport import (
-    ReadTimeoutError,
     SendError,
     TransportError,
     TransportRequest,
@@ -51,23 +50,15 @@ _HTTP_REDIRECT = 302
 
 @dataclasses.dataclass(frozen=True)
 class AsyncAttemptControl:
-    """Consume async attempt bytes under deadline and progress control."""
+    """Consume async attempt bytes with progress reporting."""
 
     _attempt: int
-    _clock: Callable[[], float]
-    _deadline: float | None
     _observer: ObserverCallback | None
     _operation: _protocol.OperationCategory
     _route: EventRoute
 
-    def _check_deadline(self) -> None:
-        """Raise when cumulative monotonic attempt time exceeds its limit."""
-        if self._deadline is not None and self._clock() > self._deadline:
-            raise ReadTimeoutError('total attempt timeout exceeded')
-
-    async def _consume_buffered(self, body: bytes, total_bytes: int | None = None) -> bytes:
+    async def consume_buffered(self, body: bytes, total_bytes: int | None = None) -> bytes:
         """Observe a received buffered body without rebuilding it."""
-        self._check_deadline()
         if body:
             notify_observer(
                 self._observer,
@@ -81,22 +72,13 @@ class AsyncAttemptControl:
             )
         return body
 
-    def _remaining_timeout(self) -> float | None:
-        """Return the remaining cumulative attempt timeout."""
-        if self._deadline is None:
-            return None
-        remaining = self._deadline - self._clock()
-        if remaining < 0:
-            raise ReadTimeoutError('total attempt timeout exceeded')
-        return remaining
-
     async def consume_into(
         self,
         chunks: AsyncIterator[bytes],
         sink: Callable[[bytes], object | Awaitable[object]],
         total_bytes: int | None = None,
     ) -> None:
-        """Write async chunks under deadline and progress control.
+        """Write async chunks with progress reporting.
 
         Args:
             chunks: Fresh response-body chunks for this attempt.
@@ -104,8 +86,7 @@ class AsyncAttemptControl:
             total_bytes: Known complete body size, when available.
 
         Raises:
-            ReadTimeoutError: If cumulative attempt time exceeds the total
-                limit.
+            Exception: If reading a chunk or invoking the sink fails.
         """
         transferred = 0
         async for chunk in chunks:
@@ -113,7 +94,6 @@ class AsyncAttemptControl:
             if inspect.isawaitable(sink_result):
                 await sink_result
             transferred += len(chunk)
-            self._check_deadline()
             if chunk:
                 notify_observer(
                     self._observer,
@@ -131,7 +111,7 @@ class AsyncAttemptControl:
         chunks: AsyncIterator[bytes],
         total_bytes: int | None = None,
     ) -> bytes:
-        """Collect async chunks while enforcing the attempt deadline.
+        """Collect async chunks while reporting progress.
 
         Args:
             chunks: Fresh response-body chunks for this attempt.
@@ -141,8 +121,7 @@ class AsyncAttemptControl:
             Concatenated response bytes.
 
         Raises:
-            ReadTimeoutError: If cumulative attempt time exceeds the total
-                limit.
+            Exception: If reading a chunk fails.
         """
         body = BytesIO()
         await self.consume_into(chunks, body.write, total_bytes=total_bytes)
@@ -239,11 +218,8 @@ class AsyncDriver:
     ) -> AttemptState[AsyncAttemptControl]:
         """Build immutable timing and observer state for one fresh attempt."""
         started = self._clock()
-        deadline = None if context.timeout.total is None else started + context.timeout.total
         control = AsyncAttemptControl(
             _attempt=attempt,
-            _clock=self._clock,
-            _deadline=deadline,
             _observer=context.on_progress,
             _operation=operation.category,
             _route=route,
@@ -296,7 +272,6 @@ class AsyncDriver:
                 response_status = response.status
                 response_headers = response.headers
                 correlation_id = response_correlation_id(response_headers)
-                state.control._check_deadline()  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
                 failure = _protocol.classify_http_failure(
                     response_status,
                     response_headers,
@@ -416,7 +391,6 @@ class AsyncDriver:
         request: TransportRequest,
         state: AttemptState[AsyncAttemptControl],
         *,
-        redirected: bool,
         streaming: bool,
     ) -> AsyncLiveResponse | AttemptRetry:
         """Send once and close the request body under response ownership."""
@@ -425,8 +399,6 @@ class AsyncDriver:
         response_status: int | None = None
         try:
             try:
-                if redirected:
-                    request = _request_with_remaining_timeout(request, state.control)
                 if streaming:
                     response = await self._transport.send_streaming(request)
                 else:
@@ -496,7 +468,6 @@ class AsyncDriver:
                     sent = await self._send_request(
                         request,
                         state,
-                        redirected=redirected,
                         streaming=execution_options.streaming,
                     )
                     if isinstance(sent, AttemptRetry):
@@ -561,7 +532,7 @@ class AsyncDriver:
                 buffered.headers,
                 buffered.content,
             )
-            body = await control._consume_buffered(  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
+            body = await control.consume_buffered(
                 buffered.content,
                 total_bytes=len(buffered.content),
             )
@@ -636,6 +607,11 @@ class AsyncDriver:
 
         Yields:
             Decoded RPC results in page order.
+
+        Raises:
+            TransportError: If a page exhausts its transport attempts.
+            Exception: If building, validating, decoding, or cleaning up a page
+                operation fails.
         """
         if context.page_prefetch <= 0:
             page = first_page
@@ -686,6 +662,7 @@ class AsyncDriver:
         Raises:
             ValueError: If `attempts` is not positive or `interval` is
                 negative.
+            Exception: If the predicate or configured sleep fails.
         """
         if attempts <= 0:
             raise ValueError('poll attempts must be positive')
@@ -721,7 +698,7 @@ class _AsyncBufferedResponse(AsyncLiveResponse, Protocol):
         ...
 
 
-class _ObservedRequestBody(Iterator[bytes]):
+class _ObservedRequestBody(Iterator[bytes], AsyncUploadObserver):
     """Publish progress while owning exact-once request-body cleanup."""
 
     def __init__(
@@ -753,7 +730,13 @@ class _ObservedRequestBody(Iterator[bytes]):
         return chunk
 
     def close(self) -> None:
-        """Close the source iterator exactly once."""
+        """Close the source iterator at most once.
+
+        Later calls do not repeat cleanup even when the first close fails.
+
+        Raises:
+            Exception: If the source iterator's cleanup fails.
+        """
         with self._condition:
             if self._closed:
                 return
@@ -781,15 +764,10 @@ class _ObservedRequestBody(Iterator[bytes]):
 
         Args:
             chunk: Chunk pulled from the source iterator.
-
-        Raises:
-            ReadTimeoutError: If the attempt deadline passed before the chunk
-                could be returned.
         """
         self._transferred += len(chunk)
         if not chunk:
             return
-        self._state.control._check_deadline()  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
         notify_observer(
             self._state.context.on_progress,
             ProgressEvent(
@@ -807,6 +785,9 @@ class _ObservedRequestBody(Iterator[bytes]):
         Returns:
             The next chunk, or `None` when the source is exhausted or the body
             is closing or closed.
+
+        Raises:
+            Exception: If the source iterator fails.
         """
         with self._condition:
             chunks = self._chunks
@@ -890,17 +871,6 @@ def _request_with_progress(
     )
 
 
-def _request_with_remaining_timeout(
-    request: TransportRequest,
-    control: AsyncAttemptControl,
-) -> TransportRequest:
-    """Restrict a redirect hop to its remaining cumulative attempt timeout."""
-    return _transport.narrow_total_timeout(
-        request,
-        control._remaining_timeout(),  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
-    )
-
-
 def _retain_detached_cleanup(task: asyncio.Task[None]) -> None:
     """Retain a detached cleanup task until its completion is observed."""
     _DETACHED_CLEANUP_TASKS.add(task)

shotgun_api3/_async_httpx2.py

@@ -3,14 +3,15 @@
 import asyncio
 import dataclasses
 import ssl
-from collections.abc import AsyncIterator, Callable, Iterator
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping
 from contextlib import suppress
 from http.cookiejar import CookieJar, DefaultCookiePolicy
-from typing import Self, cast
+from typing import Self, TypedDict, cast
 
 import httpx2
 
-from ._async_transport import AsyncStreamingResponse
+from ._async_transport import AsyncStreamingResponse, AsyncUploadObserver
+from ._connections import SocketOption, keepalive_socket_options, tune_socket
 from ._transport import (
     CaseInsensitiveHeaders,
     ConnectError,
@@ -37,12 +38,15 @@ class Httpx2Transport:
     closes the transport.
     """
 
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
         ca_certs: str | None = None,
         proxy_url: str | None = None,
         proxy_headers: dict[str, str] | None = None,
         pool_maxsize: int = 10,
+        *,
+        max_connection_idle_secs: float | None = 60.0,
+        tcp_keepalive_timeout_secs: int | None = 60,
     ) -> None:
         """Initialize one shared async HTTP transport.
 
@@ -51,6 +55,14 @@ class Httpx2Transport:
             proxy_url: Optional proxy URL.
             proxy_headers: Optional headers sent to the proxy.
             pool_maxsize: Maximum concurrent and keep-alive connections.
+            max_connection_idle_secs: Validated idle limit in seconds, or
+                `None` to disable expiry.
+            tcp_keepalive_timeout_secs: Validated nominal keepalive target in
+                seconds, or `None` to leave sockets untuned.
+
+        Raises:
+            OSError: If the certificate-authority bundle cannot be read or
+                loaded into the SSL context.
         """
         verify: ssl.SSLContext | bool = True
         if ca_certs is not None:
@@ -66,9 +78,14 @@ class Httpx2Transport:
             limits=httpx2.Limits(
                 max_connections=pool_maxsize,
                 max_keepalive_connections=pool_maxsize,
+                keepalive_expiry=max_connection_idle_secs,
             ),
             timeout=None,
         )
+        self._request_options: _TraceRequestOptions = {}
+        if tcp_keepalive_timeout_secs is not None:
+            options = keepalive_socket_options(tcp_keepalive_timeout_secs)
+            self._request_options['extensions'] = {'trace': _keepalive_trace(options)}
         self._active = 0
         self._body_cleanup_tasks: set[asyncio.Task[None]] = set()
         self._closed = False
@@ -121,18 +138,12 @@ class Httpx2Transport:
     async def _open_stream(
         self,
         request: httpx2.Request,
-        deadline: float | None,
     ) -> httpx2.Response:
-        """Send through the response-header phase under the total deadline."""
+        """Send through the response-header phase and map backend errors."""
         try:
-            if deadline is None:
-                return await self._client.send(request, stream=True)
-            async with asyncio.timeout_at(deadline):
-                return await self._client.send(request, stream=True)
+            return await self._client.send(request, stream=True)
         except TimeoutError as error:
-            if deadline is None:
-                raise SendError(str(error)) from error
-            raise ReadTimeoutError('total timeout exceeded before response body') from error
+            raise SendError(str(error)) from error
         except (httpx2.HTTPError, httpx2.StreamError) as error:
             raise _map_httpx2_error(error) from error
 
@@ -219,6 +230,7 @@ class Httpx2Transport:
                 headers=request.headers,
                 content=body,
                 timeout=_to_httpx2_timeout(request.timeout),
+                **self._request_options,
             )
         except BaseException:
             self._retain_body_cleanup(body)
@@ -258,7 +270,8 @@ class Httpx2Transport:
 
         Raises:
             TransportError: If the current task owns a lease whose release
-                would depend on this call returning.
+                would depend on this call returning, or backend pool cleanup
+                fails.
         """
         owner = _current_task()
         if self._has_lease(owner) or self._stream_owners.get(owner, 0) > 0:
@@ -295,22 +308,13 @@ class Httpx2Transport:
             TransportError: If httpx2 cannot complete the request.
         """
         self._require_send_available(_current_task())
-        total = request.timeout.total
-        if total is None:
-            try:
-                return await self._send_once(request)
-            except (httpx2.HTTPError, httpx2.StreamError) as error:
-                raise _map_httpx2_error(error) from error
         try:
-            async with asyncio.timeout(request.timeout.total):
-                return await self._send_once(request)
-        except TimeoutError as error:
-            raise ReadTimeoutError('total timeout exceeded') from error
+            return await self._send_once(request)
         except (httpx2.HTTPError, httpx2.StreamError) as error:
             raise _map_httpx2_error(error) from error
 
     async def send_streaming(self, request: TransportRequest) -> AsyncStreamingResponse:
-        """Send one request and stream its body under one total deadline.
+        """Send one request and stream its body.
 
         Args:
             request: Request expressed in shared transport types.
@@ -319,13 +323,10 @@ class Httpx2Transport:
             A single-use streaming response in shared transport types.
 
         Raises:
-            TransportError: If the request, response, or total deadline fails.
+            TransportError: If the request or response fails.
         """
         current_task = _current_task()
         self._require_send_available(current_task)
-        deadline = None
-        if request.timeout.total is not None:
-            deadline = asyncio.get_running_loop().time() + request.timeout.total
         body = _adapt_body(request.body)
         try:
             outgoing = self._client.build_request(
@@ -334,6 +335,7 @@ class Httpx2Transport:
                 headers=request.headers,
                 content=body,
                 timeout=_to_httpx2_timeout(request.timeout),
+                **self._request_options,
             )
         except (httpx2.HTTPError, httpx2.StreamError) as error:
             self._retain_body_cleanup(body)
@@ -344,7 +346,7 @@ class Httpx2Transport:
 
         owner = self._begin_stream()
         try:
-            response = await self._open_stream(outgoing, deadline)
+            response = await self._open_stream(outgoing)
         except BaseException:
             self._retain_body_cleanup(body)
             self._release_stream(owner)
@@ -359,7 +361,6 @@ class Httpx2Transport:
 
         body_owner = _ResponseBody(
             response,
-            deadline,
             lambda: self._release_stream(owner),
             lambda task: self._reserve_stream_task(task, owner),
         )
@@ -387,12 +388,10 @@ class _ResponseBody:
     def __init__(
         self,
         response: httpx2.Response,
-        deadline: float | None,
         release: Callable[[], None],
         reserve: Callable[[asyncio.Task[object]], None],
     ) -> None:
-        """Initialize one deadline-aware async response body."""
-        self._deadline = deadline
+        """Initialize one async response body."""
         self._pending: asyncio.Task[bytes] | None = None
         self._release = release
         self._reserve = reserve
@@ -429,7 +428,7 @@ class _ResponseBody:
         """Run one retained response pull behind a shielded consumer wait."""
         if self._pending is not None:
             raise TransportError('async response already has an active pull')
-        pull = asyncio.create_task(_next_response_chunk(iterator, self._deadline))
+        pull = asyncio.create_task(_next_response_chunk(iterator))
         self._pending = pull
         try:
             self._reserve(pull)
@@ -452,7 +451,14 @@ class _ResponseBody:
                 self._pending = None
 
     async def close(self) -> None:
-        """Wait for cleanup unless the calling task is cancelling."""
+        """Wait for cleanup unless the calling task is cancelling.
+
+        An already-cancelling caller leaves the retained cleanup task running
+        without waiting for it.
+
+        Raises:
+            TransportError: If awaited backend response cleanup fails.
+        """
         cleanup = self._start()
         current = asyncio.current_task()
         if current is not None and current.cancelling():
@@ -460,7 +466,7 @@ class _ResponseBody:
         await asyncio.shield(cleanup)
 
     async def stream(self, size: int) -> AsyncIterator[bytes]:
-        """Yield mapped, deadline-aware response chunks.
+        """Yield response chunks with mapped backend errors.
 
         Args:
             size: Maximum preferred chunk size in bytes.
@@ -469,7 +475,7 @@ class _ResponseBody:
             Response body chunks.
 
         Raises:
-            TransportError: If reading the response stream fails.
+            TransportError: If reading or closing the response stream fails.
         """
         try:
             iterator = self._response.aiter_bytes(size)
@@ -505,7 +511,7 @@ class _ThreadedBody(AsyncIterator[bytes]):
             try:
                 pulled = await asyncio.shield(pull)
             except asyncio.CancelledError:
-                self._start_close()
+                self.start_close()
                 raise
             except Exception as error:
                 raise SendError(str(error)) from error
@@ -528,7 +534,7 @@ class _ThreadedBody(AsyncIterator[bytes]):
                 await asyncio.shield(pending)
         await _close_body(self._chunks)
 
-    def _start_close(self) -> asyncio.Task[None]:
+    def start_close(self) -> asyncio.Task[None]:
         """Start idempotent cleanup and retain its task."""
         if self._close_task is None:
             self._close_task = asyncio.create_task(self._finish_close())
@@ -536,14 +542,27 @@ class _ThreadedBody(AsyncIterator[bytes]):
         return self._close_task
 
     async def aclose(self) -> None:
-        """Close the underlying iterator exactly once and off-loop."""
-        close_task = self._start_close()
+        """Close the underlying iterator exactly once and off-loop.
+
+        An already-cancelling caller leaves the retained cleanup task running
+        without waiting for it.
+
+        Raises:
+            SendError: If awaited iterator cleanup fails.
+        """
+        close_task = self.start_close()
         current = asyncio.current_task()
         if current is not None and current.cancelling():
             return
         await asyncio.shield(close_task)
 
 
+class _TraceRequestOptions(TypedDict, total=False):
+    """Omit the trace extension entirely when socket tuning is disabled."""
+
+    extensions: dict[str, Callable[[str, Mapping[str, object]], Awaitable[None]]]
+
+
 def _adapt_body(
     body: bytes | Iterator[bytes] | None,
 ) -> bytes | _ThreadedBody | None:
@@ -595,6 +614,24 @@ def _is_tls_failure(error: BaseException) -> bool:
     return False
 
 
+def _keepalive_trace(
+    options: tuple[SocketOption, ...],
+) -> Callable[[str, Mapping[str, object]], Awaitable[None]]:
+    """Tune the socket exposed by each completed TCP connection trace event."""
+
+    async def trace(event: str, info: Mapping[str, object]) -> None:
+        if event != 'connection.connect_tcp.complete':
+            return
+        get_extra_info = getattr(info['return_value'], 'get_extra_info', None)
+        if get_extra_info is None:
+            return
+        sock = get_extra_info('socket')
+        if sock is not None:
+            tune_socket(sock, options)
+
+    return trace
+
+
 def _map_httpx2_error(error: httpx2.HTTPError | httpx2.StreamError) -> TransportError:
     """Map an httpx2 failure into the shared transport vocabulary."""
     if isinstance(error, httpx2.ProxyError):
@@ -604,38 +641,34 @@ def _map_httpx2_error(error: httpx2.HTTPError | httpx2.StreamError) -> Transport
             return TLSError(str(error))
         return ConnectError(str(error))
     if isinstance(error, httpx2.PoolTimeout):
-        return ConnectError(str(error))
+        return ConnectError(str(error) or 'timed out waiting for a connection from the pool')
     if isinstance(error, httpx2.ReadTimeout):
         return ReadTimeoutError(str(error))
     return SendError(str(error))
 
 
 def _next_chunk(chunks: Iterator[bytes]) -> _PulledChunk:
-    """Pull one chunk and capture an exact-name loop observer when supported."""
-    pull_for_async = getattr(chunks, 'pull_for_async', None)
-    observe_async_chunk = getattr(chunks, 'observe_async_chunk', None)
-    if callable(pull_for_async) and callable(observe_async_chunk):
+    """Pull one chunk and capture its event-loop observer when supported."""
+    if (
+        isinstance(chunks, AsyncUploadObserver)
+        and callable(chunks.pull_for_async)
+        and callable(chunks.observe_async_chunk)
+    ):
         return _PulledChunk(
-            chunk=cast('Callable[[], bytes | None]', pull_for_async)(),
-            observe=cast('Callable[[bytes], None]', observe_async_chunk),
+            chunk=chunks.pull_for_async(),
+            observe=chunks.observe_async_chunk,
         )
     return _PulledChunk(chunk=next(chunks, None), observe=None)
 
 
 async def _next_response_chunk(
     iterator: AsyncIterator[bytes],
-    deadline: float | None,
 ) -> bytes:
-    """Read one response chunk against the remaining total budget."""
+    """Read one response chunk and map backend errors."""
     try:
-        if deadline is None:
-            return await anext(iterator)
-        async with asyncio.timeout_at(deadline):
-            return await anext(iterator)
+        return await anext(iterator)
     except TimeoutError as error:
-        if deadline is None:
-            raise SendError(str(error)) from error
-        raise ReadTimeoutError('total timeout exceeded during response body') from error
+        raise SendError(str(error)) from error
     except (httpx2.HTTPError, httpx2.StreamError) as error:
         current = asyncio.current_task()
         if current is not None and current.cancelling():
@@ -648,7 +681,7 @@ def _start_adapted_body_cleanup(
 ) -> asyncio.Task[None] | None:
     """Start and return request-body cleanup without delaying an error path."""
     if isinstance(body, _ThreadedBody):
-        return body._start_close()  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
+        return body.start_close()
     return None
 
 

shotgun_api3/_async_transport.py

@@ -1,9 +1,10 @@
 """Async transport vocabulary and streaming response handling."""
 
 import asyncio
+from abc import abstractmethod
 from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import suppress
-from typing import Protocol
+from typing import Protocol, runtime_checkable
 
 from ._transport import (
     CaseInsensitiveHeaders,
@@ -57,7 +58,14 @@ class AsyncStreamingResponse:
             raise TransportError('streaming response is closed')
 
     async def close(self) -> None:
-        """Release resources associated with the streaming response."""
+        """Run the response cleanup callback at most once.
+
+        The callback is cleared before invocation, so a failed cleanup is not
+        retried by later calls.
+
+        Raises:
+            Exception: If the supplied cleanup callback fails.
+        """
         close_fn = self._close_fn
         self._close_fn = None
         if close_fn is not None:
@@ -98,10 +106,37 @@ class AsyncStreamingResponse:
         return self._iterate(size)
 
 
+@runtime_checkable
+class AsyncUploadObserver(Protocol):
+    """Separate worker-thread upload reads from event-loop progress callbacks.
+
+    Implementations pull chunks without observing them. The async transport
+    invokes the observer on its event loop after each worker-thread pull.
+    """
+
+    @abstractmethod
+    def observe_async_chunk(self, chunk: bytes) -> None:
+        """Account for one uploaded chunk on the event loop.
+
+        Args:
+            chunk: Chunk returned by `pull_for_async()`.
+        """
+        ...
+
+    @abstractmethod
+    def pull_for_async(self) -> bytes | None:
+        """Pull a chunk without invoking its progress observer.
+
+        Returns:
+            The next chunk, or `None` when no more chunks are available.
+        """
+        ...
+
+
 class AsyncTransport(Protocol):
     """HTTP backend operations required by the async driver.
 
-    Task cancellation replaces the sync transport's `abort` operation. The
+    Task cancellation interrupts asynchronous transport operations. The
     synchronous lease pair brackets one complete logical RPC so draining close
     operations cannot interrupt a retry loop between attempts.
     """

shotgun_api3/_capabilities.py

@@ -18,10 +18,11 @@ class ClientCapabilities:
     """Represent local platform details used by compatibility helpers.
 
     Attributes:
-        platform: Operating-system name.
-        py_version: Python version.
+        platform: `linux`, `mac`, or `windows`, or `None` on other platforms.
+        py_version: Python version as a `major.minor` string.
         ssl_version: SSL library version.
-        local_path_field: Platform-specific local-file field name.
+        local_path_field: `local_path_<platform>`, or `None` when the platform
+            has no supported local-file field.
     """
 
     def __init__(self) -> None: