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

shotgun_api3/_async_driver.py

@@ -15,7 +15,6 @@ from typing import Protocol, TypeVar, cast
 from . import _protocol, _transport
 from ._async_transport import AsyncTransport
 from ._config import (
-    CompatibilityWarningCode,
     EventRoute,
     ObserverCallback,
     Outcome,
@@ -200,14 +199,11 @@ class AsyncExecutionOptions:
     """Control async executor transport choreography.
 
     Attributes:
-        compatibility_warning_codes: Compatibility warnings emitted before
-            attempts.
         logical_method_name: Optional observer-facing operation name.
         redirect_factory: Optional request factory for redirect responses.
         streaming: Whether the response body is consumed as a stream.
     """
 
-    compatibility_warning_codes: tuple[CompatibilityWarningCode, ...] = ()
     logical_method_name: str | None = None
     redirect_factory: Callable[['AsyncLiveResponse'], TransportRequest] | None = None
     streaming: bool = False
@@ -486,10 +482,7 @@ class AsyncDriver:
                 consumption, or cleanup fails.
         """
         execution_options = options or AsyncExecutionOptions()
-        for event in compatibility_warning_events(
-            execution_options.compatibility_warning_codes,
-            context.timeout,
-        ):
+        for event in compatibility_warning_events(context.timeout):
             notify_observer(context.on_compatibility_warning, event)
         route = event_route(operation)
         self._transport.checkout()
@@ -590,7 +583,6 @@ class AsyncDriver:
         params: object,
         context: RequestContext,
         include_auth: bool = True,
-        compatibility_warning_codes: tuple[CompatibilityWarningCode, ...] = (),
         *,
         _logical_method_name: str | None = None,
     ) -> object:
@@ -601,7 +593,6 @@ class AsyncDriver:
             params: Normalized method parameters.
             context: Immutable operation configuration.
             include_auth: Whether to include captured authentication.
-            compatibility_warning_codes: Sanitized compatibility notices.
             _logical_method_name: Optional logical operation name when it
                 differs from the wire method.
 
@@ -615,10 +606,7 @@ class AsyncDriver:
                 consumption, or cleanup fails.
         """
         normalized_params = copy.deepcopy(params)
-        options = AsyncExecutionOptions(
-            compatibility_warning_codes=compatibility_warning_codes,
-            logical_method_name=_logical_method_name,
-        )
+        options = AsyncExecutionOptions(logical_method_name=_logical_method_name)
         return await self._execute_rpc(
             method_name,
             normalized_params,

shotgun_api3/_client.py

@@ -26,7 +26,6 @@ from . import _config as config_module
 from . import _crud, _errors, _files, _methods, _protocol, _transport
 from ._capabilities import ClientCapabilities, ServerCapabilities
 from ._config import (
-    CompatibilityWarningCode,
     Config,
     RequestContext,
     advance_transport_generation,
@@ -137,10 +136,8 @@ _CONSTRUCTOR_PARAMETERS = (
 )
 _UPLOAD_DOCSTRING = """Upload a file or thumbnail and return its Attachment ID.
 
-A successful HTTP response from the legacy form-upload route still
-raises `ShotgunError`; no Attachment ID is established for that
-route. The form request has already been sent when this error is
-raised.
+A server requiring legacy form uploads raises `ShotgunError` before
+any upload request is sent. Server capability reads may occur.
 
 Args:
     entity_type: Entity type receiving the upload.
@@ -157,8 +154,8 @@ Returns:
 Raises:
     TypeError: If arguments do not match the documented signature.
     ShotgunError: If the file or an upload response is invalid, an RPC
-        fault or terminal transport failure occurs, or the legacy
-        form-upload route succeeds.
+        fault or terminal transport failure occurs, or the server
+        requires legacy form uploads.
     ProtocolError: If an upload endpoint returns an HTTP error.
     ValueError: If authenticated HTTP violates the configured origin policy.
 """
@@ -348,7 +345,6 @@ class _InvocationOptions:
     """Collect non-payload controls for one client invocation."""
 
     include_auth: bool = True
-    compatibility_warning_codes: tuple[CompatibilityWarningCode, ...] = ()
     logical_method_name: str | None = None
     auth_spec: _protocol.AuthSpec | None = None
 
@@ -570,7 +566,6 @@ class Shotgun:
             outbound,
             context,
             include_auth=options.include_auth,
-            compatibility_warning_codes=options.compatibility_warning_codes,
             _logical_method_name=options.logical_method_name,
         )
         return _protocol.transform_inbound(result, context.convert_datetimes_to_utc)
@@ -884,28 +879,6 @@ class Shotgun:
             lambda _text, _headers: None,
         )
 
-    @staticmethod
-    def _upload_form(
-        driver: Driver,
-        context: RequestContext,
-        prepared: _files.PreparedUpload,
-    ) -> Never:
-        """Send the observed form request without guessing a success result."""
-        if context.canonical_origin is None:
-            raise ValueError('server parameters must be configured before upload I/O')
-        exchange = _files.build_form_upload_exchange(
-            context.canonical_origin,
-            context.user_agent,
-            prepared,
-            context.auth,
-        )
-
-        def reject_success(_text: str, _headers: Mapping[str, str]) -> Never:
-            raise ShotgunError('form upload success response is not established')
-
-        _execute_upload_exchange(driver, context, exchange, reject_success)
-        raise AssertionError('form upload response parser returned')
-
     @staticmethod
     def _upload_link(
         driver: Driver,
@@ -1002,14 +975,14 @@ class Shotgun:
         """Execute one prepared upload through a captured driver lease."""
         arguments = prepared.options.arguments
         capabilities = self._ensure_readiness(context, driver)
-        upload_path = _files.choose_upload_path(
-            capabilities.server_info,
-            arguments.entity_type,
-            arguments.field_name,
-            prepared.file_size,
+        upload_path = _files.require_supported_upload_path(
+            _files.choose_upload_path(
+                capabilities.server_info,
+                arguments.entity_type,
+                arguments.field_name,
+                prepared.file_size,
+            )
         )
-        if upload_path == 'form':
-            return self._upload_form(driver, context, prepared)
         multipart = upload_path == 'multipart'
         upload_info = self._upload_allocation(driver, context, prepared, multipart)
         if multipart:
@@ -1033,11 +1006,42 @@ class Shotgun:
         prepared: _files.PreparedUpload,
     ) -> int:
         """Execute the exact direct-storage thumbnail workflow."""
-        self._ensure_readiness(context, driver)
+        capabilities = self._ensure_readiness(context, driver)
+        arguments = prepared.options.arguments
+        _files.require_supported_upload_path(
+            _files.choose_upload_path(
+                capabilities.server_info,
+                arguments.entity_type,
+                arguments.field_name,
+                prepared.file_size,
+            )
+        )
         upload_info = self._upload_allocation(driver, context, prepared, multipart=False)
         self._upload_direct(driver, context, prepared, upload_info)
         return self._upload_link(driver, context, prepared, upload_info)
 
+    def _upload_thumbnails_after_write(
+        self,
+        entity_type: str,
+        entity_id: int,
+        thumbnails: dict[str, object],
+        result: dict[str, object],
+    ) -> dict[str, object]:
+        """Upload separated thumbnail paths and merge their current field values."""
+        if not thumbnails:
+            return result
+        for field_name, path in thumbnails.items():
+            upload = (
+                self.upload_filmstrip_thumbnail
+                if field_name == 'filmstrip_image'
+                else self.upload_thumbnail
+            )
+            upload(entity_type, entity_id, cast('str', path))
+        current = self.find_one(entity_type, [['id', 'is', entity_id]], list(thumbnails))
+        if current is not None:
+            result.update({field_name: current.get(field_name) for field_name in thumbnails})
+        return result
+
     @overload
     def activity_stream_read(self, entity_type: Never) -> dict[str, object]: ...
 
@@ -1298,6 +1302,10 @@ class Shotgun:
     ) -> dict[str, object]:
         """Create an entity with the supplied field values.
 
+        Non-empty `image` and `filmstrip_image` values are file paths. They are
+        uploaded as thumbnails after the entity is created, and the result
+        includes their current field values.
+
         Args:
             entity_type: Entity type to create.
             data: Field values for the new entity.
@@ -1308,14 +1316,20 @@ class Shotgun:
 
         Raises:
             ShotgunError: If an RPC fault or terminal transport failure occurs,
-                or if `data`, its field names, `return_fields`, or the server
-                result is invalid.
+                if `data`, its field names, `return_fields`, or the server
+                result is invalid, or if a thumbnail path is not a nonempty
+                file. A thumbnail failure occurs after the entity is created.
             ProtocolError: If a server request returns an HTTP error.
             ValueError: If authenticated HTTP violates the configured origin
                 policy.
         """
-        params = _crud.build_create_params(entity_type, data, return_fields)
-        return _crud.require_dictionary_result(self._call('create', params), 'create')
+        field_data, thumbnails = _files.split_thumbnail_uploads(data, keep_image_none=False)
+        params = _crud.build_create_params(entity_type, field_data, return_fields)
+        result = _crud.require_dictionary_result(self._call('create', params), 'create')
+        if not thumbnails:
+            return result
+        entity_id = _crud.require_entity_id(result.get('id'), 'create did not return an entity id')
+        return self._upload_thumbnails_after_write(entity_type, entity_id, thumbnails, result)
 
     def delete(self, entity_type: str, entity_id: int) -> bool:
         """Retire an entity.
@@ -1422,6 +1436,15 @@ class Shotgun:
         except (TransportError, _errors.ProtocolError, OSError):
             raise _errors.ShotgunFileDownloadError('attachment download failed') from None
 
+    def entity_types(self) -> Never:
+        """Reject the deprecated alias of `schema_entity_read()` without I/O.
+
+        Raises:
+            ShotgunError: Always, naming `schema_entity_read()` as the
+                replacement.
+        """
+        raise _methods.entity_types_alias_error()
+
     @overload
     def export_page(
         self,
@@ -1442,6 +1465,9 @@ class Shotgun:
     def export_page(self, *args: object, **kwargs: object) -> str:
         """Export a page using the documented arguments.
 
+        The Page or its layout must be marked API Exportable in the web UI, or
+        the server rejects the export.
+
         Args:
             *args: Positional values from the documented `export_page`
                 signature.
@@ -1789,7 +1815,11 @@ class Shotgun:
             seed_entity_field,
         )
         return _methods.require_dictionary_list_result(
-            self._call('nav_search_entity', params),
+            self._call(
+                'nav_search',
+                params,
+                invocation_options=_InvocationOptions(logical_method_name='nav_search_entity'),
+            ),
             'nav_search_entity',
         )
 
@@ -1822,7 +1852,11 @@ class Shotgun:
             seed_entity_field,
         )
         return _methods.require_dictionary_list_result(
-            self._call('nav_search_string', params),
+            self._call(
+                'nav_search',
+                params,
+                invocation_options=_InvocationOptions(logical_method_name='nav_search_string'),
+            ),
             'nav_search_string',
         )
 
@@ -1849,7 +1883,11 @@ class Shotgun:
         """
         params = _methods.build_note_thread_read_params(note_id, entity_fields)
         return _methods.require_dictionary_list_result(
-            self._call('note_thread_read', params),
+            self._call(
+                'note_thread_contents',
+                params,
+                invocation_options=_InvocationOptions(logical_method_name='note_thread_read'),
+            ),
             'note_thread_read',
         )
 
@@ -1900,6 +1938,18 @@ class Shotgun:
             'revive',
         )
 
+    def schema(self, entity_type: str) -> Never:
+        """Reject the deprecated alias of `schema_field_read()` without I/O.
+
+        Args:
+            entity_type: Entity type named in the replacement suggestion.
+
+        Raises:
+            ShotgunError: Always, naming the equivalent `schema_field_read()`
+                call.
+        """
+        raise _methods.schema_alias_error(entity_type)
+
     def schema_entity_read(
         self,
         project_entity: dict[str, Any] | None = None,
@@ -1923,33 +1973,10 @@ class Shotgun:
             self._call(
                 'schema_entity_read',
                 _methods.build_schema_entity_read_params(project_entity),
-                _InvocationOptions(
-                    compatibility_warning_codes=_methods.consume_compatibility_warnings(
-                        _methods.SCHEMA_ENTITY_READ_WARNINGS,
-                        self,
-                    ),
-                ),
             ),
             'schema_entity_read',
         )
 
-    def entity_types(self) -> dict[str, object]:
-        """Return entity schema through the deprecated alias.
-
-        Returns:
-            Entity-type schema data returned by the server.
-
-        Raises:
-            ShotgunError: If an RPC fault or terminal transport failure occurs,
-                or if the server result is not a dictionary.
-            ProtocolError: If a server request returns an HTTP error.
-            ValueError: If authenticated HTTP violates the configured origin
-                policy.
-        """
-        _methods.warn_entity_types_alias()
-        with _methods.entity_types_alias(self):
-            return self.schema_entity_read()
-
     def schema_field_create(
         self,
         entity_type: str,
@@ -2042,36 +2069,10 @@ class Shotgun:
                     field_name,
                     project_entity,
                 ),
-                _InvocationOptions(
-                    compatibility_warning_codes=_methods.consume_compatibility_warnings(
-                        _methods.SCHEMA_FIELD_READ_WARNINGS,
-                        self,
-                    ),
-                ),
             ),
             'schema_field_read',
         )
 
-    def schema(self, entity_type: str) -> dict[str, object]:
-        """Return field schema through the deprecated alias.
-
-        Args:
-            entity_type: Entity type whose fields to return.
-
-        Returns:
-            Field schema data returned by the server.
-
-        Raises:
-            ShotgunError: If an RPC fault or terminal transport failure occurs,
-                or if the server result is invalid.
-            ProtocolError: If a server request returns an HTTP error.
-            ValueError: If authenticated HTTP violates the configured origin
-                policy.
-        """
-        _methods.warn_schema_alias()
-        with _methods.schema_alias(self):
-            return self.schema_field_read(entity_type)
-
     def schema_field_update(
         self,
         entity_type: str,
@@ -2184,7 +2185,8 @@ class Shotgun:
 
         Supply exactly one of `thumbnail_path` and `source_entity`. A local
         thumbnail is uploaded to the first target before it is shared with the
-        remaining targets.
+        remaining targets. A local thumbnail is rejected before any upload
+        request if the server requires legacy form uploads.
 
         Args:
             entities: Nonempty list of target entities with `type` and `id`.
@@ -2201,7 +2203,8 @@ class Shotgun:
             TypeError: If forwarded arguments do not match the upload signature
                 or include `field_name`.
             ShotgunError: If an RPC fault or terminal transport failure occurs,
-                or if the source selection, entities, or transport fails.
+                or if the source selection, entities, or transport fails, or a
+                local upload requires the legacy form route.
             ShotgunThumbnailNotReady: If an uploaded source stays transient.
             ProtocolError: If an upload endpoint returns an HTTP error.
             ValueError: If authenticated HTTP violates the configured origin
@@ -2384,6 +2387,12 @@ class Shotgun:
     ) -> dict[str, object]:
         """Update fields on an existing entity.
 
+        Non-empty `image` and `filmstrip_image` values are file paths. They are
+        uploaded as thumbnails after the other fields are updated, and the
+        result includes their current field values. An `image` of `None` clears
+        both thumbnails. When no other fields remain, no update request is sent
+        and the result contains only `id` and `type`.
+
         Args:
             entity_type: Entity type to update.
             entity_id: Numeric entity identifier.
@@ -2395,19 +2404,27 @@ class Shotgun:
 
         Raises:
             ShotgunError: If an RPC fault or terminal transport failure occurs,
-                or if `data`, its field names, `multi_entity_update_modes`, or
-                the server result is invalid.
+                if `data`, its field names, `multi_entity_update_modes`, or the
+                server result is invalid, or if a thumbnail path is not a
+                nonempty file. A thumbnail failure occurs after the update.
             ProtocolError: If a server request returns an HTTP error.
             ValueError: If authenticated HTTP violates the configured origin
                 policy.
         """
+        field_data, thumbnails = _files.split_thumbnail_uploads(data, keep_image_none=True)
         params = _crud.build_update_params(
             entity_type,
             entity_id,
-            data,
+            field_data,
             multi_entity_update_modes,
         )
-        return _crud.require_dictionary_result(self._call('update', params), 'update')
+        result: dict[str, object] = {'id': entity_id, 'type': entity_type}
+        if params['fields']:
+            result = _crud.require_dictionary_result(
+                self._call('update', params),
+                'update',
+            )
+        return self._upload_thumbnails_after_write(entity_type, entity_id, thumbnails, result)
 
     def update_project_last_accessed(
         self,
@@ -2453,9 +2470,8 @@ class Shotgun:
     def upload(self, *args: object, **kwargs: object) -> int:
         """Upload a file or thumbnail and return its Attachment ID.
 
-        A successful HTTP response from the legacy form-upload route still
-        raises `ShotgunError`; no Attachment ID is established for that route.
-        The form request has already been sent when this error is raised.
+        A server requiring legacy form uploads raises `ShotgunError` before any
+        upload request is sent. Server capability reads may occur.
 
         Args:
             *args: Positional arguments from the documented upload signature;
@@ -2468,8 +2484,8 @@ class Shotgun:
         Raises:
             TypeError: If arguments do not match the documented signature.
             ShotgunError: If the file or an upload response is invalid, an RPC
-                fault or terminal transport failure occurs, or the legacy
-                form-upload route succeeds.
+                fault or terminal transport failure occurs, or the server
+                requires legacy form uploads.
             ProtocolError: If an upload endpoint returns an HTTP error.
             ValueError: If authenticated HTTP violates the configured origin
                 policy.
@@ -2501,6 +2517,9 @@ class Shotgun:
     ) -> int:
         """Upload a filmstrip thumbnail through `upload`.
 
+        Servers requiring legacy form uploads are rejected before any upload
+        request is sent.
+
         Args:
             entity_type: Entity type receiving the thumbnail.
             entity_id: Numeric identifier of the receiving entity.
@@ -2513,7 +2532,8 @@ class Shotgun:
         Raises:
             TypeError: If forwarded arguments do not match `upload`.
             ShotgunError: If an RPC fault or terminal transport failure occurs,
-                or if the file, upload response, or transport fails.
+                or if the file, upload response, or transport fails, or the
+                server requires legacy form uploads.
             ProtocolError: If an upload endpoint returns an HTTP error.
             ValueError: If authenticated HTTP violates the configured origin
                 policy.
@@ -2535,6 +2555,9 @@ class Shotgun:
     ) -> int:
         """Upload a static thumbnail through `upload`.
 
+        Servers requiring legacy form uploads are rejected before any upload
+        request is sent.
+
         Args:
             entity_type: Entity type receiving the thumbnail.
             entity_id: Numeric identifier of the receiving entity.
@@ -2547,7 +2570,8 @@ class Shotgun:
         Raises:
             TypeError: If forwarded arguments do not match `upload`.
             ShotgunError: If an RPC fault or terminal transport failure occurs,
-                or if the file, upload response, or transport fails.
+                or if the file, upload response, or transport fails, or the
+                server requires legacy form uploads.
             ProtocolError: If an upload endpoint returns an HTTP error.
             ValueError: If authenticated HTTP violates the configured origin
                 policy.
@@ -2563,44 +2587,53 @@ class Shotgun:
     def user_subscriptions_create(self, users: list[dict[str, Any]]) -> bool:
         """Assign subscriptions to users.
 
+        The server accepts this call from scripts and from human users with
+        permission to manage subscriptions, such as members of the Admin
+        permission group. It refuses other human users.
+
         Args:
-            users: Subscription dictionaries that each contain a `user_id` key.
+            users: Subscription dictionaries with a string or integer
+                `humanUserId`; integers become decimal string keys and booleans
+                are not accepted. Each user may appear only once.
+                `subscription` is `None`, a string, or a list of strings.
+                Lists are copied in order. Other entry keys are ignored.
 
         Returns:
-            Whether the server created the subscriptions.
+            `True` when every per-user report is `None`, meaning the server
+            reported no problem; `False` when any user has a non-`None` report.
 
         Raises:
             ShotgunError: If an RPC fault or terminal transport failure occurs,
-                or if `users` is not a list of dictionaries that each contain a
-                `user_id` key, or the server result is not a boolean.
+                or if `users` contains invalid or duplicate entries, or the
+                server result is not a mapping with string keys.
             ProtocolError: If a server request returns an HTTP error.
             ValueError: If authenticated HTTP violates the configured origin
                 policy.
         """
-        return _crud.require_boolean_result(
+        return _methods.require_user_subscriptions_create_result(
             self._call(
                 'user_subscriptions_create',
                 _methods.build_user_subscriptions_create_params(users),
             ),
-            'user_subscriptions_create',
         )
 
     def user_subscriptions_read(self) -> list[dict[str, object]]:
-        """List the current user's subscriptions.
+        """List user subscriptions in server order.
 
         Returns:
-            User subscription dictionaries returned by the server.
+            Subscription entries in server order, each with an unchanged string
+            `humanUserId` and a `subscription` of `None`, a string, or a copied
+            list of strings.
 
         Raises:
             ShotgunError: If an RPC fault or terminal transport failure occurs,
-                or if the server result is not a list of dictionaries.
+                or if the server result is invalid.
             ProtocolError: If a server request returns an HTTP error.
             ValueError: If authenticated HTTP violates the configured origin
                 policy.
         """
-        return _methods.require_dictionary_list_result(
+        return _methods.require_user_subscriptions_result(
             self._call('user_subscriptions_read', None),
-            'user_subscriptions_read',
         )
 
     def work_schedule_read(

shotgun_api3/_config.py

@@ -21,11 +21,7 @@ from ._sentinel import Unset as _Unset
 from ._transport import TimeoutConfig
 from ._version import PACKAGE_VERSION
 
-CompatibilityWarningCode: TypeAlias = Literal[
-    'deprecated-entity-types-alias',
-    'deprecated-schema-alias',
-    'legacy-infinite-timeout',
-]
+CompatibilityWarningCode: TypeAlias = Literal['legacy-infinite-timeout']
 EventRoute: TypeAlias = Literal[
     'allocation',
     'download',
@@ -85,8 +81,6 @@ _ORIGIN_FIELDS = frozenset({'api_path', 'scheme', 'server'})
 _ORIGIN_STRING_FIELDS = frozenset({'scheme', 'server'})
 _UNSET: Final = _Unset()
 _WARNING_MESSAGES: Mapping[CompatibilityWarningCode, str] = {
-    'deprecated-entity-types-alias': 'The entity_types alias is deprecated.',
-    'deprecated-schema-alias': 'The schema alias is deprecated.',
     'legacy-infinite-timeout': 'Explicit None timeout enables legacy infinite waits.',
 }
 _PUBLIC_FIELDS = frozenset(
@@ -1021,19 +1015,17 @@ def auth_spec(config: Config) -> _protocol.AuthSpec:
 
 
 def compatibility_warning_events(
-    warning_codes: tuple[CompatibilityWarningCode, ...],
     timeout: TimeoutConfig,
 ) -> tuple[CompatibilityWarningEvent, ...]:
     """Build fixed-message compatibility warnings for one operation.
 
     Args:
-        warning_codes: Sanitized compatibility notices from the client.
         timeout: Captured operation timeout semantics.
 
     Returns:
         Immutable compatibility-warning events in publication order.
     """
-    codes = list(warning_codes)
+    codes: list[CompatibilityWarningCode] = []
     if timeout.connect is None and timeout.read is None:
         codes.append('legacy-infinite-timeout')
     return tuple(