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

shotgun_api3/lib/mockgun/_sync_client.py

@@ -0,0 +1,190 @@
+"""Run the real synchronous client against an isolated in-memory site."""
+
+import dataclasses
+from typing import ClassVar, Self
+
+from shotgun_api3 import Shotgun as RealShotgun
+from shotgun_api3 import _crud
+from shotgun_api3._client import ConstructorOptions
+from shotgun_api3._config import RequestContext
+from shotgun_api3._transport import Transport
+
+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 ._transport import InMemoryTransport
+
+
+class Shotgun(RealShotgun):
+    """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_entity_path: ClassVar[str | None] = None
+    _schema_path: ClassVar[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.
+        Default construction performs fake-site readiness; supplying
+        `auth_token` also performs the normal session-token exchange.
+
+        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 perform eager readiness during construction.
+            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, files are missing, or
+                readiness or session behavior is unsupported.
+            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.
+            ShotgunError: If eager readiness or session exchange returns a
+                modeled fault or invalid metadata.
+        """
+        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.get_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,
+        )
+
+    def _find(self, options: _crud.FindOptions) -> list[dict[str, object]]:
+        """Count each query before dispatching through the real client."""
+        self.finds += 1
+        return super()._find(options)
+
+    def _new_transport(self, context: RequestContext) -> Transport:
+        """Bind every operation to this client's in-memory site."""
+        del context
+        return InMemoryTransport(self._server)
+
+    @classmethod
+    def get_schema_paths(cls) -> tuple[str | None, str | None]:
+        """Return field-schema and entity-schema paths, in that order."""
+        return cls._schema_path, cls._schema_entity_path
+
+    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.
+            MockgunError: If eager readiness or session behavior is
+                unsupported.
+            ShotgunError: If eager readiness or session exchange returns a
+                modeled fault or invalid metadata.
+        """
+        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
+    def set_schema_paths(cls, schema_path: str, schema_entity_path: str) -> None:
+        """Configure the trusted schema pickles loaded by future instances.
+
+        Args:
+            schema_path: Path to the field-schema pickle.
+            schema_entity_path: Path to the entity-schema pickle.
+        """
+        cls._schema_path = schema_path
+        cls._schema_entity_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/_threads.py

@@ -0,0 +1,226 @@
+"""Read observed Note threads from the fake site's records."""
+
+from collections.abc import Mapping
+from copy import deepcopy
+from datetime import datetime
+from itertools import pairwise
+from typing import cast
+
+from ._errors import MockgunError, ServerFaultError
+from ._links import named_link
+from ._sessions import RequestContext
+from ._store import FieldValue, Row, Store
+from ._wire import format_wire_datetime
+
+_DEFAULT_FIELDS = {
+    'Attachment': ('type', 'id', 'created_by', 'created_at'),
+    'Note': ('type', 'id', 'content', 'created_at', 'created_by'),
+    'Reply': ('type', 'id', 'content', 'user', 'created_at'),
+}
+
+
+def _field_type(store: Store, kind: str, field: str) -> str:
+    """Reject structurally unsettled selections even without rows."""
+    prefix = f'mockgun cannot note_thread_contents {kind}.{field}'
+    if field == 'updated_by':
+        raise MockgunError(f'{prefix}: the audit link is unsettled')
+    if '.' in field or not store.schema.declares(kind, field):
+        raise MockgunError(f'{prefix}: the field is undeclared or deep')
+    data_type = store.schema.field_type(kind, field)
+    if data_type == 'multi_entity':
+        raise MockgunError(f'{prefix}: multi-entity selection is unsettled')
+    return data_type
+
+
+def _fields(store: Store, params: Mapping[str, object]) -> dict[str, list[str]]:
+    """Validate requested thread selections before reading any row."""
+    extra = set(params) - {'note_id', 'entity_fields'}
+    if extra:
+        raise MockgunError(f'mockgun cannot note_thread_contents parameter {min(extra)}')
+    raw = params.get('entity_fields', {})
+    if not isinstance(raw, dict):
+        raise MockgunError('mockgun cannot note_thread_contents parameter entity_fields')
+    result: dict[str, list[str]] = {}
+    for kind, names in cast('dict[object, object]', raw).items():
+        if (
+            kind not in _DEFAULT_FIELDS
+            or not isinstance(names, list)
+            or not all(isinstance(name, str) for name in cast('list[object]', names))
+        ):
+            raise MockgunError(f'mockgun cannot note_thread_contents entity_fields {kind}')
+        entity_type = cast('str', kind)
+        selected = cast('list[str]', names)
+        for field in selected:
+            if field not in _DEFAULT_FIELDS[entity_type] and not (
+                entity_type == 'Reply' and field == 'created_by'
+            ):
+                _field_type(store, entity_type, field)
+        result[entity_type] = selected
+    return result
+
+
+def _unsettled(row: Row, field: str, reason: str) -> MockgunError:
+    """Name the thread field and record whose value cannot be reproduced."""
+    return MockgunError(
+        f'mockgun cannot note_thread_contents {row["type"]}.{field} '
+        f'on record {row["id"]}: {reason}'
+    )
+
+
+def _known(store: Store, row: Row, field: str, *, membership: bool = False) -> None:
+    """Include the thread RPC in a stored unknown marker's diagnostic."""
+    try:
+        store.check_known(row, field, membership=membership)
+    except MockgunError as exc:
+        raise _unsettled(row, field, str(exc)) from exc
+
+
+def _entries(store: Store, note: Row) -> list[Row]:
+    """Collect active Replies and Note-member Attachments."""
+    identity = note['id']
+    _known(store, note, 'attachments', membership=True)
+    members = cast('list[dict[str, FieldValue]]', note.get('attachments', []))
+    entries: list[Row] = []
+    if store.schema.declares('Reply'):
+        for row in store.rows('Reply', retired=False):
+            _known(store, row, 'entity')
+            if row.get('entity') == {'type': 'Note', 'id': identity}:
+                entries.append(row)
+    if store.schema.declares('Attachment'):
+        for row in store.rows('Attachment', retired=False):
+            _known(store, row, 'attachment_links', membership=True)
+            linked = {'type': 'Note', 'id': identity} in cast(
+                'list[dict[str, FieldValue]]', row.get('attachment_links', [])
+            )
+            member = {'type': 'Attachment', 'id': row['id']} in members
+            if linked and not member:
+                raise _unsettled(row, 'attachment_links', 'the Note does not list this attachment')
+            if member:
+                entries.append(row)
+    return entries
+
+
+def _named(store: Store, row: Row, field: str) -> dict[str, object] | None:
+    """Return an observed named single link in thread key order."""
+    _known(store, row, field)
+    value = row.get(field)
+    if value is None:
+        return None
+    if not isinstance(value, dict):
+        raise _unsettled(row, field, 'the link shape is unsettled')
+    try:
+        link = named_link(store, cast('dict[str, FieldValue]', value))
+    except (MockgunError, ServerFaultError) as exc:
+        raise _unsettled(row, field, str(exc)) from exc
+    if 'name' not in link:
+        raise _unsettled(row, field, 'the linked name is unsettled')
+    return {'id': link['id'], 'name': link['name'], 'type': link['type']}
+
+
+def _ordered(store: Store, entries: list[Row]) -> list[Row]:
+    """Order thread entries while rejecting unobserved timestamp forms."""
+    for row in entries:
+        if not store.schema.declares(cast('str', row['type']), 'created_at') and len(entries) > 1:
+            raise _unsettled(row, 'created_at', 'the timestamp is undeclared')
+        _known(store, row, 'created_at')
+        if not isinstance(row.get('created_at'), datetime):
+            raise _unsettled(row, 'created_at', 'the timestamp is unsettled')
+    entries.sort(key=lambda row: (cast('datetime', row['created_at']), cast('int', row['id'])))
+    for earlier, later in pairwise(entries):
+        if earlier['created_at'] == later['created_at'] and earlier['type'] != later['type']:
+            raise MockgunError(
+                f'mockgun cannot note_thread_contents {earlier["type"]} {earlier["id"]} '
+                f'and {later["type"]} {later["id"]}: mixed-type timestamp tie is unsettled'
+            )
+    return entries
+
+
+def _reply_user(store: Store, row: Row) -> dict[str, object]:
+    """Include the observed null image on a Reply actor link."""
+    link = _named(store, row, 'user')
+    if link is None:
+        raise _unsettled(row, 'user', 'the null actor is unsettled')
+    user_type = cast('str', link['type'])
+    user_id = cast('int', link['id'])
+    user = store.row(user_type, user_id)
+    if user is not None and store.schema.declares(user_type, 'image'):
+        _known(store, user, 'image')
+        if user.get('image') is not None:
+            raise _unsettled(row, 'user', f'{user_type}.image is non-null')
+    return {**link, 'image': None}
+
+
+def _value(store: Store, row: Row, field: str) -> object:
+    """Project one declared thread field without exposing unknown state."""
+    kind = cast('str', row['type'])
+    data_type = _field_type(store, kind, field)
+    if kind == 'Reply' and field == 'user':
+        return _reply_user(store, row)
+    if data_type == 'entity':
+        link = _named(store, row, field)
+        if field == 'created_by' and link is None:
+            raise _unsettled(row, field, 'the null actor is unsettled')
+        return link
+    _known(store, row, field)
+    value = row.get(field)
+    if data_type == 'date_time' and value is not None:
+        if not isinstance(value, datetime):
+            raise _unsettled(row, field, 'the timestamp is unsettled')
+        return format_wire_datetime(value)
+    return deepcopy(value)
+
+
+def _row(store: Store, row: Row, fields: list[str], *, script_reader: bool) -> dict[str, object]:
+    """Build default thread keys followed by requested fields."""
+    kind = cast('str', row['type'])
+    result: dict[str, object] = {}
+    for field in _DEFAULT_FIELDS[kind]:
+        result[field] = row[field] if field in {'type', 'id'} else _value(store, row, field)
+    for field in fields:
+        if field in result or (kind == 'Reply' and field == 'created_by'):
+            continue
+        user = row.get('user')
+        if (
+            kind == 'Reply'
+            and field == 'entity'
+            and script_reader
+            and isinstance(user, dict)
+            and user.get('type') == 'ApiUser'
+        ):
+            continue
+        result[field] = _value(store, row, field)
+    return result
+
+
+def read_thread(
+    store: Store, params: Mapping[str, object], *, context: RequestContext
+) -> list[dict[str, object]]:
+    """Return one Note followed by its active, time-ordered thread entries.
+
+    Args:
+        store: Site records and schema for the current request.
+        params: Wire `note_id` and optional per-type `entity_fields`.
+        context: Request context captured for this RPC.
+
+    Returns:
+        Detached rows in the observed Note thread wire shape.
+
+    Raises:
+        MockgunError: If a requested value or ordering is unsettled.
+        ServerFaultError: If the Note is absent or retired.
+    """
+    script_reader = context.session_kind == 'script'
+    if not store.schema.declares('Note'):
+        raise MockgunError('mockgun cannot note_thread_contents Note: schema is undeclared')
+    identity = params.get('note_id')
+    if not isinstance(identity, int) or isinstance(identity, bool):
+        raise MockgunError('mockgun cannot note_thread_contents parameter note_id')
+    selections = _fields(store, params)
+    note = store.row('Note', identity)
+    if note is None or note['__retired']:
+        raise ServerFaultError(f'Note {identity} not found', error_code=103)
+    entries = _ordered(store, _entries(store, note))
+    return [_row(store, note, selections.get('Note', []), script_reader=script_reader)] + [
+        _row(store, row, selections.get(cast('str', row['type']), []), script_reader=script_reader)
+        for row in entries
+    ]

shotgun_api3/lib/mockgun/_thumbnails.py

@@ -0,0 +1,146 @@
+"""Apply observed thumbnail identities, sharing and owner side effects."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+from urllib.parse import urlsplit
+
+from ._activity import taint_activity
+from ._errors import MockgunError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from ._server import FakeServer
+    from ._sessions import RequestContext
+    from ._storage import Allocation
+    from ._store import Row
+
+
+def _owner(server: FakeServer, kind: str, identity: int, field: str, route: str) -> Row:
+    """Require an active writable owner with the selected image declaration."""
+    row = server.store.row(kind, identity) if server.schema.declares(kind) else None
+    if row is None or row['__retired'] or not server.schema.declares(kind, field):
+        raise MockgunError(
+            f'mockgun POST {route} {kind} {identity} field {field}: '
+            'missing or retired owner or image declaration is unsettled'
+        )
+    server.store.check_writable(row)
+    return row
+
+
+def _reference(server: FakeServer, value: str) -> Row:
+    """Resolve a share form reference to an active image owner."""
+    kind, identity = value.rsplit('_', 1)
+    return _owner(server, kind, int(identity), 'image', '/upload/share_thumbnail')
+
+
+def _set_image(server: FakeServer, row: Row, field: str, key: str | None, route: str) -> None:
+    """Replace an image while invalidating its previous identity and side effects."""
+    store = server.store
+    kind, identity = cast('str', row['type']), cast('int', row['id'])
+    store.remember(row)
+    row[field] = server.storage.image_url(key) if key is not None else None
+    store.forget_unknown(row, field)
+    store.side_set('image_identity', (kind, identity, field), None)
+    reason = (
+        f'POST {route} {kind} {identity} field {field}: audit, events and activity are unsettled'
+    )
+    for name in ('updated_at', 'updated_by'):
+        if server.schema.declares(kind, name):
+            store.mark_unknown(row, name, reason)
+    store.taint_events(reason)
+    taint_activity(store, [row], reason)
+
+
+def link_thumbnail(
+    server: FakeServer, allocation: Allocation, form: Mapping[str, str], context: RequestContext
+) -> str:
+    """Link uploaded thumbnail bytes using an unreadable Attachment identity.
+
+    Args:
+        server: Site whose storage allocation and record are being linked.
+        allocation: Issued Thumbnail allocation with completed bytes.
+        form: Link form identifying an owner and optional filmstrip selection.
+        context: Authenticated request actor and instant.
+
+    Returns:
+        The client's successful link grammar containing the reserved identity.
+
+    Raises:
+        MockgunError: If owner, field or optional metadata behavior is
+            unsettled.
+    """
+    del context
+    route = '/upload/api_link_file'
+    kind, identity = form['entity_type'], int(form['entity_id'])
+    if form.keys() - {'entity_type', 'entity_id', 'filmstrip', 'upload_link_info'} or (
+        'filmstrip' in form and form['filmstrip'] != 'true'
+    ):
+        raise MockgunError(
+            f'mockgun POST {route} {kind} {identity} thumbnail fields: metadata is unsettled'
+        )
+    field = 'filmstrip_image' if form.get('filmstrip') == 'true' else 'image'
+    row = _owner(server, kind, identity, field, route)
+    if not server.schema.declares('Attachment'):
+        raise MockgunError(
+            f'mockgun POST {route} {kind} {identity} field {field}: Attachment schema is missing'
+        )
+    # C6/C7 P4-14: the shared counter advances without creating an Attachment row.
+    with server.store.transaction():
+        thumbnail_id = server.store.reserve_id('Attachment')
+        _set_image(server, row, field, allocation.key, route)
+        server.store.side_set('image_identity', (kind, identity, field), thumbnail_id)
+    return f'1:{thumbnail_id}'
+
+
+def share_thumbnail(server: FakeServer, form: Mapping[str, str], context: RequestContext) -> str:
+    """Share an uploaded source image and return its stable thumbnail identity.
+
+    Args:
+        server: Site containing source and target owners and stored bytes.
+        form: Entity references and filmstrip flag from the source-share route.
+        context: Authenticated request actor and instant.
+
+    Returns:
+        Success with the source identity, or the observed null-source failure.
+
+    Raises:
+        MockgunError: If filmstrip, owner or source identity behavior is
+            unsettled.
+    """
+    del context
+    route = '/upload/share_thumbnail'
+    if form['filmstrip_thumbnail'] != 'False':
+        raise MockgunError(
+            f'mockgun POST {route} {form["source_entity"]} filmstrip_thumbnail: '
+            'share identity is unsettled'
+        )
+    source = _reference(server, form['source_entity'])
+    targets = [_reference(server, value) for value in form['entities'].split(',')]
+    server.store.check_known(source, 'image')
+    kind, identity = cast('str', source['type']), cast('int', source['id'])
+    image = source.get('image')
+    # C8 Q4: the empty Asset source clears one populated, non-filmstrip Asset.
+    if image is None:
+        if (
+            kind == 'Asset'
+            and len(targets) == 1
+            and targets[0]['type'] == 'Asset'
+            and isinstance(targets[0].get('image'), str)
+            and targets[0].get('filmstrip_image') is None
+        ):
+            with server.store.transaction():
+                _set_image(server, targets[0], 'image', None, route)
+        return f'0:mockgun share failed: {kind} {identity} has no thumbnail'
+    thumbnail_id = server.store.side_get('image_identity', (kind, identity, 'image'))
+    if not isinstance(thumbnail_id, int) or not isinstance(image, str):
+        raise MockgunError(
+            f'mockgun POST {route} {kind} {identity} image: source identity is unsettled'
+        )
+    key = urlsplit(image).path.lstrip('/')
+    # C7 P4-19: every share retains the path and source ID, with fresh URL tokens.
+    with server.store.transaction():
+        for target in targets:
+            _set_image(server, target, 'image', key, route)
+    return f'1:{thumbnail_id}'