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

shotgun_api3/_connections.py

@@ -0,0 +1,144 @@
+"""Build and apply TCP keepalive socket options."""
+
+from __future__ import annotations
+
+import socket
+from typing import TYPE_CHECKING, Any, cast
+
+import urllib3
+from urllib3.connection import HTTPConnection, HTTPSConnection
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+
+    from urllib3.response import HTTPResponse
+
+SocketOption = tuple[int, int, int]
+
+
+def _keepalive_timings(target: int) -> tuple[int, int, int]:
+    """Map a nominal target to whole-second probe timings."""
+    idle = target // 2
+    interval = -(-(target - idle) // 3)
+    return idle, interval, 3
+
+
+def keepalive_socket_options(target: int | None) -> tuple[SocketOption, ...]:
+    """Return the available options for a nominal keepalive target.
+
+    Args:
+        target: Validated target in seconds, or `None` to disable keepalive.
+
+    Returns:
+        Enablement first, followed by available platform timing options.
+    """
+    if target is None:
+        return ()
+
+    idle, interval, count = _keepalive_timings(target)
+    options: list[SocketOption] = [(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)]
+    idle_option = getattr(socket, 'TCP_KEEPIDLE', None)
+    if idle_option is None:
+        idle_option = getattr(socket, 'TCP_KEEPALIVE', None)
+    if idle_option is not None:
+        options.append((socket.IPPROTO_TCP, idle_option, idle))
+    if hasattr(socket, 'TCP_KEEPINTVL'):
+        options.append((socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, interval))
+    if hasattr(socket, 'TCP_KEEPCNT'):
+        options.append((socket.IPPROTO_TCP, socket.TCP_KEEPCNT, count))
+    return tuple(options)
+
+
+def tune_socket(sock: object, options: Iterable[SocketOption]) -> None:
+    """Apply each supported socket option without failing on OS refusals.
+
+    Args:
+        sock: Socket-like object, which may lack `setsockopt`.
+        options: Options to apply in order.
+    """
+    setsockopt = getattr(sock, 'setsockopt', None)
+    if setsockopt is None:
+        return
+    for level, option, value in options:
+        try:
+            setsockopt(level, option, value)
+        except OSError:
+            continue
+
+
+def connection_pool_classes(
+    idle_limit: float | None,
+    keepalive: tuple[SocketOption, ...],
+    clock: Callable[[], float],
+) -> dict[str, type[urllib3.HTTPConnectionPool]]:
+    """Create isolated HTTP and HTTPS pool classes with one connection policy.
+
+    Args:
+        idle_limit: Validated idle limit in seconds, or `None` to disable
+            expiry.
+        keepalive: Socket options to apply after connection setup.
+        clock: Monotonic clock returning seconds.
+
+    Returns:
+        New pool classes indexed by scheme, with policy-specific connection
+        classes.
+    """
+
+    class _HTTPConnection(HTTPConnection):
+        """Track response arrival and tune each socket after connection setup."""
+
+        _clock = staticmethod(clock)
+        _idle_limit = idle_limit
+        _keepalive = keepalive
+        _response_at: float | None = None
+
+        def connect(self) -> None:
+            """Open the connection and apply best-effort keepalive tuning.
+
+            Raises:
+                OSError: If connection setup fails.
+                urllib3.exceptions.HTTPError: If connection or proxy setup
+                    fails.
+            """
+            self._response_at = None
+            super().connect()
+            tune_socket(self.sock, self._keepalive)
+
+        def getresponse(self) -> HTTPResponse:
+            """Record time after headers and any preloaded body are received.
+
+            Raises:
+                OSError: If receiving the response fails.
+                urllib3.exceptions.HTTPError: If the response cannot be
+                    received.
+            """
+            response = super().getresponse()
+            self._response_at = self._clock()
+            return response
+
+        @property
+        def is_connected(self) -> bool:
+            """Return whether the connection is unexpired and still connected."""
+            if (
+                self._idle_limit is not None
+                and self._response_at is not None
+                and self._clock() - self._response_at > self._idle_limit
+            ):
+                return False
+            return super().is_connected
+
+    class _HTTPSConnection(_HTTPConnection, HTTPSConnection):
+        """Apply the connection policy around HTTPS setup, including proxy tunnels."""
+
+    class _HTTPConnectionPool(urllib3.HTTPConnectionPool):
+        """Pool HTTP connections under this policy."""
+
+        # urllib3's connection protocols reject its concrete classes under strict typing.
+        ConnectionCls = cast('Any', _HTTPConnection)
+
+    class _HTTPSConnectionPool(urllib3.HTTPSConnectionPool):
+        """Pool HTTPS connections under this policy."""
+
+        ConnectionCls = cast('Any', _HTTPSConnection)
+
+    return {'http': _HTTPConnectionPool, 'https': _HTTPSConnectionPool}

shotgun_api3/_crud.py

@@ -2,187 +2,26 @@
 
 import copy
 import dataclasses
-import inspect
-from collections.abc import Callable
 from typing import Any, Literal, cast
 
 from . import _protocol
 from ._errors import ShotgunError
-from ._signatures import bind_arguments, expose_signature
-
-_FIND_DOCSTRING = """Find entities matching the supplied filters.
-
-Args:
-    entity_type: Entity type to find.
-    filters: Filters in list or dict syntax.
-    fields: Optional fields to return; defaults to `id`.
-    order: Optional field and direction sort specifications.
-    filter_operator: `'all'` or `'any'` for list-syntax filters.
-    limit: Maximum entities to return, or `0` for no limit.
-    retired_only: Return retired entities instead of active entities.
-    page: Specific page to return, or `0` to read all pages.
-    include_archived_projects: Include entities from archived projects.
-    additional_filter_presets: Optional server-side filter presets.
-
-Returns:
-    Matching entities in server order.
-
-Raises:
-    TypeError: If arguments do not match the documented signature.
-    ShotgunError: If an RPC fault or terminal transport failure
-        occurs, or if filters, paging, ordering, or a server result is invalid.
-    ProtocolError: If a server request returns an HTTP error.
-    ValueError: If authenticated HTTP violates the configured origin policy.
-"""
-_FIND_ONE_DOCSTRING = """Return the first entity matching the supplied filters.
-
-Args:
-    entity_type: Entity type to find.
-    filters: Filters in list or dict syntax.
-    fields: Optional fields to return; defaults to `id`.
-    order: Optional field and direction sort specifications.
-    filter_operator: `'all'` or `'any'` for list-syntax filters.
-    retired_only: Return a retired entity instead of an active entity.
-    include_archived_projects: Include entities from archived projects.
-    additional_filter_presets: Optional server-side filter presets.
-
-Returns:
-    The first matching entity, or `None` when no entity matches.
-
-Raises:
-    TypeError: If arguments do not match the documented signature.
-    ShotgunError: If an RPC fault or terminal transport failure
-        occurs, or if filters, paging, ordering, or a server result is invalid.
-    ProtocolError: If a server request returns an HTTP error.
-    ValueError: If authenticated HTTP violates the configured origin policy.
-"""
-_FIND_ONE_PARAMETERS = (
-    inspect.Parameter('entity_type', inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=str),
-    inspect.Parameter(
-        'filters',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        annotation=list[Any] | tuple[Any, ...] | dict[str, Any],
-    ),
-    inspect.Parameter(
-        'fields',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=None,
-        annotation=list[str] | None,
-    ),
-    inspect.Parameter(
-        'order',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=None,
-        annotation=list[dict[str, str]] | None,
-    ),
-    inspect.Parameter(
-        'filter_operator',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=None,
-        annotation=str | None,
-    ),
-    inspect.Parameter(
-        'retired_only',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=False,
-        annotation=bool,
-    ),
-    inspect.Parameter(
-        'include_archived_projects',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=True,
-        annotation=bool,
-    ),
-    inspect.Parameter(
-        'additional_filter_presets',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=None,
-        annotation=object,
-    ),
-)
-_FIND_ONE_SIGNATURE = inspect.Signature(
-    _FIND_ONE_PARAMETERS,
-    return_annotation=dict[str, object] | None,
-)
-_FIND_PARAMETERS = (
-    inspect.Parameter('entity_type', inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=str),
-    inspect.Parameter(
-        'filters',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        annotation=list[Any] | tuple[Any, ...] | dict[str, Any],
-    ),
-    inspect.Parameter(
-        'fields',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=None,
-        annotation=list[str] | None,
-    ),
-    inspect.Parameter(
-        'order',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=None,
-        annotation=list[dict[str, str]] | None,
-    ),
-    inspect.Parameter(
-        'filter_operator',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=None,
-        annotation=str | None,
-    ),
-    inspect.Parameter(
-        'limit',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=0,
-        annotation=int,
-    ),
-    inspect.Parameter(
-        'retired_only',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=False,
-        annotation=bool,
-    ),
-    inspect.Parameter(
-        'page',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=0,
-        annotation=int,
-    ),
-    inspect.Parameter(
-        'include_archived_projects',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=True,
-        annotation=bool,
-    ),
-    inspect.Parameter(
-        'additional_filter_presets',
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-        default=None,
-        annotation=object,
-    ),
-)
-_FIND_SIGNATURE = inspect.Signature(
-    _FIND_PARAMETERS,
-    return_annotation=list[dict[str, object]],
-)
-_METHOD_FIND_ONE_SIGNATURE = inspect.Signature(
-    (
-        inspect.Parameter('self', inspect.Parameter.POSITIONAL_OR_KEYWORD),
-        *_FIND_ONE_PARAMETERS,
-    ),
-    return_annotation=dict[str, object] | None,
-)
-_METHOD_FIND_SIGNATURE = inspect.Signature(
-    (
-        inspect.Parameter('self', inspect.Parameter.POSITIONAL_OR_KEYWORD),
-        *_FIND_PARAMETERS,
-    ),
-    return_annotation=list[dict[str, object]],
-)
 
 
 @dataclasses.dataclass(frozen=True)
-class _FindOneOptions:
-    """Collect exact public `find_one` arguments for validation."""
+class FindOneOptions:
+    """Collect exact public `find_one` arguments for validation.
+
+    Attributes:
+        entity_type: Entity type to find.
+        filters: Filters in list or dict syntax.
+        fields: Optional fields to return; defaults to `id`.
+        order: Optional field and direction sort specifications.
+        filter_operator: `'all'` or `'any'` for list-syntax filters.
+        retired_only: Return a retired entity instead of an active entity.
+        include_archived_projects: Include entities from archived projects.
+        additional_filter_presets: Optional server-side filter presets.
+    """
 
     entity_type: str
     filters: list[Any] | tuple[Any, ...] | dict[str, Any]
@@ -196,11 +35,11 @@ class _FindOneOptions:
 
 @dataclasses.dataclass(frozen=True)
 class FindOptions:
-    """Collect the exact public `find` arguments for runtime validation.
+    """Hold the public `find` arguments in a frozen configuration record.
 
     Attributes:
         entity_type: Type of entity to query.
-        filters: Query filters or filter preset structure.
+        filters: Query filters in list, tuple, or dict syntax.
         fields: Optional fields to return.
         order: Optional field ordering directives.
         filter_operator: Optional logical operator joining filters.
@@ -346,54 +185,6 @@ def _validate_nonnegative_integer(value: object, name: str) -> None:
         raise ShotgunError(f'{name} must be a nonnegative integer')
 
 
-def bind_find(
-    args: tuple[object, ...],
-    kwargs: dict[str, object],
-    client_name: str,
-) -> FindOptions:
-    """Bind runtime arguments with client-specific `find` errors.
-
-    Args:
-        args: Positional public arguments.
-        kwargs: Keyword public arguments.
-        client_name: Public client class name for error attribution.
-
-    Returns:
-        Bound find options retaining the supplied argument values without
-        copying mutable containers.
-
-    Raises:
-        TypeError: If the arguments do not match the public signature.
-    """
-    bound = bind_arguments(_FIND_SIGNATURE, args, kwargs, f'{client_name}.find()')
-    options = cast('Callable[..., FindOptions]', FindOptions)
-    return options(**bound.arguments)
-
-
-def bind_find_one(
-    args: tuple[object, ...],
-    kwargs: dict[str, object],
-    client_name: str,
-) -> _FindOneOptions:
-    """Bind runtime arguments with client-specific `find_one` errors.
-
-    Args:
-        args: Positional public arguments.
-        kwargs: Keyword public arguments.
-        client_name: Public client class name for error attribution.
-
-    Returns:
-        Bound find-one options retaining the supplied argument values without
-        copying mutable containers.
-
-    Raises:
-        TypeError: If the arguments do not match the public signature.
-    """
-    bound = bind_arguments(_FIND_ONE_SIGNATURE, args, kwargs, f'{client_name}.find_one()')
-    options = cast('Callable[..., _FindOneOptions]', _FindOneOptions)
-    return options(**bound.arguments)
-
-
 def build_entity_action_params(entity_type: str, entity_id: int) -> dict[str, object]:
     """Build parameters for delete and revive operations.
 
@@ -447,36 +238,18 @@ def build_page_params(plan: _FindPlan, page_number: int, convert_utc: bool) -> o
 
     Returns:
         Detached transformed page parameters.
+
+    Raises:
+        ValueError: If a naive datetime cannot be converted to UTC.
+        OverflowError: If converting an aware datetime to UTC exceeds the
+            supported datetime range.
+        OSError: If the platform cannot resolve a local datetime.
     """
     built = dict(plan.params)
     built['paging'] = {**plan.paging, 'current_page': page_number}
     return _protocol.transform_outbound(built, convert_utc)
 
 
-def expose_find_one_signature(function: Callable[..., object]) -> Callable[..., object]:
-    """Expose the documented `find_one` signature and documentation.
-
-    Args:
-        function: Variadic method implementation.
-
-    Returns:
-        The same function with its public runtime contract attached.
-    """
-    return expose_signature(function, _METHOD_FIND_ONE_SIGNATURE, _FIND_ONE_DOCSTRING)
-
-
-def expose_find_signature(function: Callable[..., object]) -> Callable[..., object]:
-    """Expose the documented `find` signature and documentation.
-
-    Args:
-        function: Variadic method implementation.
-
-    Returns:
-        The same function with its public runtime contract attached.
-    """
-    return expose_signature(function, _METHOD_FIND_SIGNATURE, _FIND_DOCSTRING)
-
-
 def finalize_find(
     records: list[dict[str, object]],
     options: FindOptions,
@@ -499,7 +272,7 @@ def finalize_find(
     return _protocol.inject_local_paths(records, local_path_field)
 
 
-def find_options_from_one(options: _FindOneOptions) -> FindOptions:
+def find_options_from_one(options: FindOneOptions) -> FindOptions:
     """Convert bound find-one arguments into a one-result find plan.
 
     Args:
@@ -544,11 +317,13 @@ def prepare_find(options: FindOptions) -> _PreparedFind:
         Detached inputs ready for server-aware paging.
 
     Raises:
-        ShotgunError: If paging or ordering is invalid.
+        ShotgunError: If fields, paging, or ordering is invalid.
         Fault: If filter syntax is invalid.
     """
     _validate_nonnegative_integer(options.limit, 'limit')
     _validate_nonnegative_integer(options.page, 'page')
+    if isinstance(options.fields, (str, bytes)):
+        raise ShotgunError('find fields must be an iterable of strings or None')
     translated_filters = copy.deepcopy(
         _protocol.translate_filters(
             _protocol.require_filter_container(options.filters, options.filter_operator),