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

shotgun_api3/lib/mockgun/_async_client.py

@@ -0,0 +1,196 @@
+"""Run the real asynchronous client against an isolated in-memory site."""
+
+import dataclasses
+from typing import ClassVar, Self
+
+from shotgun_api3 import _crud
+from shotgun_api3._async_client import AsyncShotgun as RealAsyncShotgun
+from shotgun_api3._async_transport import AsyncTransport
+from shotgun_api3._client import ConstructorOptions
+from shotgun_api3._config import RequestContext
+
+from ._new_client import (
+    SHARED_SERVER,
+    copy_client_settings,
+    default_credentials,
+    new_client_options,
+)
+from ._schema import load_schema
+from ._server import FakeServer
+from ._site import Site
+from ._sync_client import Shotgun
+from ._transport import AsyncInMemoryTransport
+
+
+class AsyncShotgun(RealAsyncShotgun):
+    """A real client whose transport reaches only its own in-memory fake site.
+
+    Configure schema paths before construction. Direct construction creates
+    independent site state; `new_client()` shares the site with new
+    credentials. Test controls are exposed through `site`.
+
+    Attributes:
+        finds: Number of find operations performed.
+    """
+
+    _in_process: ClassVar[bool] = True
+    _schema_paths: ClassVar[tuple[str, str] | None] = None
+
+    def __init__(
+        self,
+        base_url: str,
+        script_name: str | None = None,
+        api_key: str | None = None,
+        convert_datetimes_to_utc: bool = True,
+        http_proxy: str | None = None,
+        connect: bool = True,
+        ca_certs: str | None = None,
+        login: str | None = None,
+        password: str | None = None,
+        sudo_as_login: str | None = None,
+        session_token: str | None = None,
+        auth_token: str | None = None,
+    ) -> None:
+        """Initialize a fake site before the real client's readiness operation.
+
+        Load the configured schema files synchronously for a new fake site.
+        Readiness and session operations remain deferred to the async client's
+        normal entry points.
+
+        Args:
+            base_url: Flow Production Tracking site URL.
+            script_name: Script name for script authentication.
+            api_key: API key for script authentication.
+            convert_datetimes_to_utc: Whether to convert datetime values to
+                UTC.
+            http_proxy: Optional proxy authority in `[user:pass@]host[:port]`
+                form.
+            connect: Whether to request eager readiness during asynchronous
+                context entry.
+            ca_certs: Optional certificate-authority bundle path.
+            login: Login for human-user authentication.
+            password: Password for human-user authentication.
+            sudo_as_login: Optional user login for sudo impersonation.
+            session_token: Existing session token for authentication.
+            auth_token: Optional two-factor authentication token.
+
+        Raises:
+            MockgunError: If schema paths are unset or files are missing.
+            OSError: If a schema file cannot be opened or read.
+            EOFError: If a schema pickle ends prematurely.
+            pickle.UnpicklingError: If a schema pickle is invalid.
+            ValueError: If a pickle protocol is unsupported, constructor values
+                fail real-client validation, or the retry environment setting
+                is invalid.
+        """
+        options = ConstructorOptions(
+            base_url,
+            script_name,
+            api_key,
+            convert_datetimes_to_utc,
+            http_proxy,
+            connect,
+            ca_certs,
+            login,
+            password,
+            sudo_as_login,
+            session_token,
+            auth_token,
+        )
+        shared = SHARED_SERVER.get()
+        if shared is None:
+            options = default_credentials(options)
+        self._server = (
+            shared
+            if shared is not None
+            else FakeServer(load_schema(*self._configured_schema_paths()))
+        )
+        self._options = options
+        self._site = Site(self._server)
+        if options.login is not None:
+            self._server.admit_login(options.login)
+        self.finds = 0
+        super().__init__(
+            options.base_url,
+            options.script_name,
+            options.api_key,
+            options.convert_datetimes_to_utc,
+            options.http_proxy,
+            options.connect,
+            options.ca_certs,
+            options.login,
+            options.password,
+            options.sudo_as_login,
+            options.session_token,
+            options.auth_token,
+        )
+
+    @classmethod
+    def _configured_schema_paths(cls) -> tuple[str | None, str | None]:
+        """Resolve subclass paths or the base synchronous client's defaults."""
+        return cls._schema_paths if cls._schema_paths is not None else Shotgun.get_schema_paths()
+
+    async def _find(self, options: _crud.FindOptions) -> list[dict[str, object]]:
+        """Count each query before dispatching through the real client."""
+        self.finds += 1
+        return await super()._find(options)
+
+    def _new_transport(self, context: RequestContext) -> AsyncTransport:
+        """Bind every operation to this client's in-memory site."""
+        del context
+        return AsyncInMemoryTransport(self._server)
+
+    @classmethod
+    async def get_schema_paths(cls) -> tuple[str | None, str | None]:
+        """Return field-schema and entity-schema paths, in that order."""
+        return cls._configured_schema_paths()
+
+    def new_client(self, **credentials: object) -> Self:
+        """Create a client with new credentials sharing this client's fake site.
+
+        This is a plain method on both sync and async clients. The returned
+        client has its own readiness and session state. Timeout, retry and
+        user-agent settings are copied; other noncredential options use their
+        original constructor values.
+
+        Args:
+            **credentials: Constructor credential arguments. A lone
+                `sudo_as_login` preserves the original credentials; otherwise
+                only the supplied credentials are used.
+
+        Returns:
+            A new instance of this client's class sharing schema and records.
+
+        Raises:
+            ValueError: If constructor credentials, retained configuration, or
+                the retry environment setting fail validation.
+        """
+        options = new_client_options(self._options, credentials)
+        token = SHARED_SERVER.set(self._server)
+        try:
+            client = type(self)(**dataclasses.asdict(options))
+        finally:
+            SHARED_SERVER.reset(token)
+        copy_client_settings(self.config, client.config)
+        return client
+
+    @classmethod
+    async def set_schema_paths(cls, schema_path: str, schema_entity_path: str) -> None:
+        """Configure the trusted schema pickles loaded by future instances.
+
+        On `AsyncShotgun` itself, these paths are shared with
+        `mockgun.Shotgun`.
+
+        Args:
+            schema_path: Path to the field-schema pickle.
+            schema_entity_path: Path to the entity-schema pickle.
+        """
+        if cls is AsyncShotgun:
+            Shotgun.set_schema_paths(schema_path, schema_entity_path)
+        else:
+            cls._schema_paths = (schema_path, schema_entity_path)
+
+    @property
+    def site(self) -> Site:
+        """The test-control facade for this client's in-memory site."""
+        return self._site

shotgun_api3/lib/mockgun/_dates.py

@@ -0,0 +1,164 @@
+"""Validate and evaluate settled relative-date windows in request time."""
+
+from collections.abc import Sequence
+from datetime import datetime, timedelta
+from typing import cast
+
+from ._errors import MockgunError, ServerFaultError
+from ._sessions import RequestContext
+from ._store import FieldValue
+
+_ROLLING_ARITY = 2
+_UNITS = ('HOUR', 'DAY', 'WEEK', 'MONTH', 'YEAR')
+
+
+def _shift(now: datetime, amount: int, unit: str) -> datetime:
+    """Shift by elapsed time or by the same calendar day without clamping."""
+    if unit == 'MONTH':
+        year, month = divmod(now.year * 12 + now.month - 1 + amount, 12)
+        return now.replace(year=year, month=month + 1)
+    if unit == 'YEAR':
+        return now.replace(year=now.year + amount)
+    return now + timedelta(hours=amount * {'HOUR': 1, 'DAY': 24, 'WEEK': 168}[unit])
+
+
+def _valid_operands(field_type: str, relation: str, values: Sequence[object], prefix: str) -> bool:
+    """Distinguish characterized validation faults from unsettled operand forms."""
+    calendar = relation.startswith('in_calendar_')
+    if field_type == 'date_time' and relation == 'in_last':
+        if len(values) != _ROLLING_ARITY:
+            raise ServerFaultError(f'{prefix} expects [amount, unit]', error_code=103)
+        amount, unit = values
+        if type(amount) is not int:
+            raise ServerFaultError(f'{prefix} requires an Integer amount', error_code=103)
+        if amount < 0:
+            raise ServerFaultError(f'{prefix} requires a positive Integer amount', error_code=103)
+        if unit not in _UNITS:
+            raise ServerFaultError(
+                f'{prefix} unit {unit} is not supported. Valid units: {", ".join(_UNITS)}',
+                error_code=103,
+            )
+        valid = amount > 0 or unit == 'DAY'
+    elif field_type == 'date_time' and relation == 'in_calendar_day':
+        if len(values) != 1 or type(values[0]) is not int:
+            raise ServerFaultError(f'{prefix} requires an Integer offset', error_code=103)
+        valid = True
+    elif calendar:
+        valid = len(values) == 1 and type(values[0]) is int
+    else:
+        valid = (
+            len(values) == _ROLLING_ARITY
+            and type(values[0]) is int
+            and values[0] > 0
+            and values[1] in _UNITS
+        )
+    return valid
+
+
+def _window(
+    field_type: str, relation: str, values: Sequence[object], now: datetime
+) -> tuple[datetime, datetime]:
+    """Build rolling or calendar bounds after operand validation."""
+    amount = cast('int', values[0])
+    if relation.startswith('in_calendar_'):
+        unit = relation.removeprefix('in_calendar_').upper()
+        start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        if unit == 'WEEK':
+            start -= timedelta(days=(start.weekday() + 1) % 7)
+        elif unit == 'MONTH':
+            start = start.replace(day=1)
+        elif unit == 'YEAR':
+            start = start.replace(month=1, day=1)
+        lower = amount if amount < 0 else (1 if amount > 0 else 0)
+        upper = 0 if amount < 0 else amount + 1
+        return _shift(start, lower, unit), _shift(start, upper, unit)
+    unit = cast('str', values[1])
+    if field_type == 'date':
+        now = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        if unit == 'HOUR':
+            amount //= 24
+            unit = 'DAY'
+    if relation.endswith('last'):
+        return _shift(now, -amount, unit), now
+    return now, _shift(now, amount, unit)
+
+
+def in_window(
+    field_type: str, relation: str, values: Sequence[object], value: FieldValue, *, now: datetime
+) -> bool:
+    """Match a validated relative filter, rejecting unsettled datetime endpoints.
+
+    Args:
+        field_type: Either `date` or `date_time`.
+        relation: Validated rolling or calendar relation.
+        values: Validated amount and unit, or calendar offset.
+        value: Stored date string, datetime, or null.
+        now: Aware UTC request timestamp.
+
+    Returns:
+        Whether the stored value matches the relation. A null value matches
+        only `not_in_last` and `not_in_next`.
+
+    Raises:
+        MockgunError: A stored date cannot be parsed or a datetime equals a
+            rolling endpoint.
+    """
+    negative = relation in {'not_in_last', 'not_in_next'}
+    if value is None:
+        return negative
+    lower, upper = _window(field_type, relation, values, now)
+    if field_type == 'date':
+        try:
+            actual_date = datetime.fromisoformat(cast('str', value)).date()
+        except ValueError as exc:
+            raise MockgunError(f'stored date cannot be parsed: {value!r}') from exc
+        matches = lower.date() <= actual_date <= upper.date()
+        if relation.startswith('in_calendar_'):
+            matches = lower.date() <= actual_date < upper.date()
+    else:
+        actual = cast('datetime', value)
+        if relation.startswith('in_calendar_'):
+            matches = lower <= actual < upper
+        else:
+            if actual in (lower, upper):
+                raise MockgunError('relative datetime endpoint is not settled')
+            matches = lower < actual < upper
+    return not matches if negative else matches
+
+
+def validate_relative(
+    path: str,
+    field_type: str,
+    relation: str,
+    values: Sequence[object],
+    *,
+    context: RequestContext,
+) -> None:
+    """Validate relative operands and row-independent timezone and shift constraints.
+
+    Args:
+        path: Root entity type and filter path, as `Entity.field`, for
+            qualified errors.
+        field_type: Either `date` or `date_time`.
+        relation: Supported relative relation.
+        values: Amount and unit, or calendar offset.
+        context: Request whose UTC time and session classification apply.
+
+    Raises:
+        ServerFaultError: A characterized invalid operand has fault code 103.
+        MockgunError: Operand, timezone, or calendar shift behavior is
+            unsettled.
+    """
+    prefix = f'API read() {path} {relation}'
+    calendar = relation.startswith('in_calendar_')
+    valid = _valid_operands(field_type, relation, values, prefix)
+    prefix = f'mockgun cannot evaluate {path} {field_type} {relation}'
+    if not valid:
+        raise MockgunError(f'{prefix} operands are not settled: {values!r}')
+    unknown_zone = context.session_kind != 'script'
+    if unknown_zone and (calendar or field_type == 'date' or values[1] in {'MONTH', 'YEAR'}):
+        raise MockgunError(f'{prefix} requires a known session timezone')
+    try:
+        _window(field_type, relation, values, context.now)
+    except (ValueError, OverflowError) as exc:
+        raise MockgunError(f'{prefix} calendar shift is not settled: {exc}') from exc

shotgun_api3/lib/mockgun/_errors.py

@@ -0,0 +1,18 @@
+"""Separate unsupported mockgun behavior from emulated server rejections."""
+
+
+class MockgunError(Exception):
+    """Report mockgun setup failures and behavior the fake site cannot emulate."""
+
+
+class ServerFaultError(Exception):
+    """Represent a server rejection encoded as a JSON-RPC fault.
+
+    Attributes:
+        error_code: Optional server error code accompanying the message.
+    """
+
+    def __init__(self, message: str, error_code: int | None = None) -> None:
+        """Initialize a rejection with its wire message and optional code."""
+        super().__init__(message)
+        self.error_code = error_code