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

{sg_python_api-0.1.1.dist-info → sg_python_api-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sg-python-api
-Version: 0.1.1
+Version: 0.1.2
 Summary: Python client for Autodesk Flow Production Tracking
 Project-URL: Documentation, https://github.com/dactylo/sg-python-api/tree/main/docs
 Project-URL: Homepage, https://github.com/dactylo/sg-python-api
@@ -44,9 +44,9 @@ This documentation uses SG for Flow Production Tracking, formerly named Shotgun
   for application tests.
 
 sg-python-api is an independent implementation of the documented API of Autodesk's Python client
-`3.10.2`. Some behavior differs on purpose, so validate your application's workflows against a test
-site before replacing its production client. The [migration guide](https://github.com/dactylo/sg-python-api/blob/v0.1.1/docs/migration-guide.md) walks
-through the switch, and the [compatibility reference](https://github.com/dactylo/sg-python-api/blob/v0.1.1/COMPATIBILITY.md) lists the differences.
+`3.10.3`. Some behavior differs on purpose, so validate your application's workflows against a test
+site before replacing its production client. The [migration guide](https://github.com/dactylo/sg-python-api/blob/v0.1.2/docs/migration-guide.md) walks
+through the switch, and the [compatibility reference](https://github.com/dactylo/sg-python-api/blob/v0.1.2/COMPATIBILITY.md) lists the differences.
 
 ## Installation
 
@@ -55,7 +55,7 @@ requests to a remote site require HTTPS.
 
 `sg-python-api` and Autodesk's `shotgun-api3` both install the `shotgun_api3` package, so install
 exactly one of them in a Python environment. If the official client is already installed, follow
-the [migration steps](https://github.com/dactylo/sg-python-api/blob/v0.1.1/docs/migration-guide.md#install-the-replacement) to replace it.
+the [migration steps](https://github.com/dactylo/sg-python-api/blob/v0.1.2/docs/migration-guide.md#install-the-replacement) to replace it.
 
 From a checkout, install into the Python environment that runs your application:
 
@@ -130,23 +130,23 @@ operation fails. Without the `async` extra, importing `AsyncShotgun` raises `Imp
 
 Share an `AsyncShotgun` only among tasks on one event loop, and cancel its work by cancelling the
 task. A cancelled write may already have reached the server, so check its outcome before repeating
-it. The [async reference](https://github.com/dactylo/sg-python-api/blob/v0.1.1/COMPATIBILITY.md#async-extension-surfaces) covers shutdown and
+it. The [async reference](https://github.com/dactylo/sg-python-api/blob/v0.1.2/COMPATIBILITY.md#async-extension-surfaces) covers shutdown and
 cancellation in detail.
 
 ## Documentation
 
 | If you want to...                                     | Read                                                                               |
 | ----------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| Replace Autodesk's client in an existing application  | [Migration guide](https://github.com/dactylo/sg-python-api/blob/v0.1.1/docs/migration-guide.md)                                         |
-| Check what behaves differently from Autodesk's client | [Compatibility](https://github.com/dactylo/sg-python-api/blob/v0.1.1/COMPATIBILITY.md)                                                  |
-| Tune pooling and page prefetch, or observe requests   | [Configuration extensions](https://github.com/dactylo/sg-python-api/blob/v0.1.1/COMPATIBILITY.md#configuration-and-observer-extensions) |
-| Confirm which client loads and run a smoke test       | [Testing an installation](https://github.com/dactylo/sg-python-api/blob/v0.1.1/docs/testing.md)                                         |
-| Compare measured latency and transfer memory          | [Benchmarks](https://github.com/dactylo/sg-python-api/blob/v0.1.1/docs/benchmarks.md)                                                   |
-| See changes by version                                | [Changelog](https://github.com/dactylo/sg-python-api/blob/v0.1.1/CHANGELOG.md)                                                          |
+| Replace Autodesk's client in an existing application  | [Migration guide](https://github.com/dactylo/sg-python-api/blob/v0.1.2/docs/migration-guide.md)                                         |
+| Check what behaves differently from Autodesk's client | [Compatibility](https://github.com/dactylo/sg-python-api/blob/v0.1.2/COMPATIBILITY.md)                                                  |
+| Tune pooling and page prefetch, or observe requests   | [Configuration extensions](https://github.com/dactylo/sg-python-api/blob/v0.1.2/COMPATIBILITY.md#configuration-and-observer-extensions) |
+| Confirm which client loads and run a smoke test       | [Testing an installation](https://github.com/dactylo/sg-python-api/blob/v0.1.2/docs/testing.md)                                         |
+| Compare measured latency and transfer memory          | [Benchmarks](https://github.com/dactylo/sg-python-api/blob/v0.1.2/docs/benchmarks.md)                                                   |
+| See changes by version                                | [Changelog](https://github.com/dactylo/sg-python-api/blob/v0.1.2/CHANGELOG.md)                                                          |
 
 ## Development
 
-See the [development guide](https://github.com/dactylo/sg-python-api/blob/v0.1.1/docs/development.md) for the required tools, CI, and dependency locks.
+See the [development guide](https://github.com/dactylo/sg-python-api/blob/v0.1.2/docs/development.md) for the required tools, CI, and dependency locks.
 With those tools installed, run:
 
 ```sh
@@ -159,6 +159,6 @@ make check
 
 ## License
 
-sg-python-api is available under the [MIT License](https://github.com/dactylo/sg-python-api/blob/v0.1.1/LICENSE). It is an independent project and is
+sg-python-api is available under the [MIT License](https://github.com/dactylo/sg-python-api/blob/v0.1.2/LICENSE). It is an independent project and is
 not affiliated with or endorsed by Autodesk. Flow Production Tracking is a product of Autodesk,
 Inc.

{sg_python_api-0.1.1.dist-info → sg_python_api-0.1.2.dist-info}/RECORD

@@ -1,23 +1,23 @@
 shotgun_api3/__init__.py,sha256=fviJGOi_Gb9jHi5Q9ty5tIbeIvxMtLNrKx_4HJVgemI,2011
-shotgun_api3/_async_client.py,sha256=I5_4t_WwJNc-3hkDrAVnbofqw4Nil07Jcxfr2CSb18A,112160
+shotgun_api3/_async_client.py,sha256=UYVk_IGzMcUguJ4oCV-Nof4mL2kvzYYGuiYvW4gHeMs,113167
 shotgun_api3/_async_driver.py,sha256=NnuMmQP5KrAoANBvWIhcIUe_ljD62pK_7xSIoEIltXw,32308
 shotgun_api3/_async_httpx2.py,sha256=3pjeFsb5racGArvlR50c3w0XtrttXuRU_6E9Y-cBU3c,24387
 shotgun_api3/_async_transport.py,sha256=8iAcoFafEHKRBirBkqdIqMFgqLs1YTgtzgACudD0kM4,4928
 shotgun_api3/_capabilities.py,sha256=RrStvExVC3TAADhfbY2JpYZUXmvE63vXIJy1R-nkEII,5527
-shotgun_api3/_client.py,sha256=7ICzGJGKKI-OzuKoCTfqhumrvRaNybN98-br7CJnB9Y,101143
+shotgun_api3/_client.py,sha256=jtemxhdhFr1gwE7qB6K-62Sohb2C_S4dEO7uKpVh2Uo,102109
 shotgun_api3/_config.py,sha256=fALxy5xGI3A0nECsRDyls_9A8tvjB0DNSpTu1agNEHw,54931
 shotgun_api3/_crud.py,sha256=Ax36jA2E-lauRf2D-2rmRDj61SilOygtkjKgs5XDCUs,30319
 shotgun_api3/_driver.py,sha256=DAtnZW044TWiqscs0G1uwTiluAFtCoR2wKTbJYJHT2g,29498
 shotgun_api3/_errors.py,sha256=fk7v3XbmZK63M272r5wDwF_GgI-4RynPfAWv1P-J-GI,1480
 shotgun_api3/_execution.py,sha256=Kn2Yd9sXIA975stnof7MeuA8bT3dyOuWDIqQnP65LO0,8235
-shotgun_api3/_files.py,sha256=7onuC_ODjGtgysIy3YUpeHKtmUpBHQpYln6XtNe3NK4,36770
-shotgun_api3/_methods.py,sha256=yGyQv7tKpHX3e3nGIVHEbuTNzjsAxQdJVXpmlXXStsw,34184
-shotgun_api3/_protocol.py,sha256=dKr1XqB6Xo56QloZ2MAyN4ulqYkTjw8VYeJRd5QHufQ,45286
+shotgun_api3/_files.py,sha256=-eXHyG0U9mEAdYTthgVEhlzBKYUOt4g-3k9D522L3zM,33900
+shotgun_api3/_methods.py,sha256=pYzx2pN0nus6vPWf-Gl8Zz4MgRf8R4b7kvxN8lhoXgc,37685
+shotgun_api3/_protocol.py,sha256=0ccL65aIm3v2w6dOtNnZuFrKQncA8WO4yadtxRP55-w,42194
 shotgun_api3/_sentinel.py,sha256=KAQzQjJVhTTZPLFY1f88-_vP7U06i2g6ZS7KJcn4vIA,116
 shotgun_api3/_sg_timezone.py,sha256=yr7Wdln9fwfTVGMQSFsgO-eduuTHQ5EbSY5xEVQ2tYw,115
 shotgun_api3/_signatures.py,sha256=_yhNnbkVF-0opaBfg9H6SauBN2RT4hJsHGa3ZO3Ug4s,1622
 shotgun_api3/_transport.py,sha256=LmQ0e2VvAKwFdNy4SyfRHwgKC6GWnwkIN5Wa2fin3AM,30047
-shotgun_api3/_version.py,sha256=LnmGg2me6J0MbE65mSg2nIknHNNg0Etx_3Jkh_k9BWc,102
+shotgun_api3/_version.py,sha256=0NYED9oy2nGCvTERMwWJvajshS5qzH_v4w7QUAGAivY,102
 shotgun_api3/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 shotgun_api3/shotgun.py,sha256=X7PLlCC-gR8dJgY_uLYXw_LWN8mz5MsQsSYJldtavTk,1706
 shotgun_api3/lib/__init__.py,sha256=4WGYod6xHcj23rapx5bTDGdjT52H1CAQNMz4BmzNmn0,55
@@ -25,7 +25,7 @@ shotgun_api3/lib/sgtimezone.py,sha256=nYSaCsIeq_SJh7YgL4yWN7dTVVz9lAfx-G3mzsHb8i
 shotgun_api3/lib/mockgun/__init__.py,sha256=2mHjMJAV4mZ8JvnP8WHn6tkdMJoB7UQtNSs99YzNW30,703
 shotgun_api3/lib/mockgun/_async.py,sha256=7bTZFdlSzeoGq9fRbPBAf-X08qDmrkzV9rxskx5AGX8,10812
 shotgun_api3/lib/mockgun/_mockgun.py,sha256=k2cqLMCKpU5oIbUGiYulf1aIU0HLrMB6DQQ3KrCy7WQ,65093
-sg_python_api-0.1.1.dist-info/METADATA,sha256=bwDwuEXYzQ-8J-igveXXMna_Ulemsdz9xwNLVhdW3mI,7587
-sg_python_api-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-sg_python_api-0.1.1.dist-info/licenses/LICENSE,sha256=V3moMsQxKDchTd3mtXl5J-ODaNBDvFrapOf1DK7Nx_U,1082
-sg_python_api-0.1.1.dist-info/RECORD,,
+sg_python_api-0.1.2.dist-info/METADATA,sha256=2Zv6g9pJZ28QttHMO6Q1yYWvyczPypCHc-QCAYbjIaQ,7587
+sg_python_api-0.1.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+sg_python_api-0.1.2.dist-info/licenses/LICENSE,sha256=V3moMsQxKDchTd3mtXl5J-ODaNBDvFrapOf1DK7Nx_U,1082
+sg_python_api-0.1.2.dist-info/RECORD,,

shotgun_api3/_async_client.py

@@ -59,7 +59,6 @@ from ._config import (
     server_host,
     server_page_limit,
 )
-from ._errors import ShotgunError
 from ._execution import SuppressedExceptionCapture, release_lease, retire_transport
 from ._signatures import bind_arguments, expose_signature
 from ._transport import (
@@ -1037,29 +1036,6 @@ class AsyncShotgun:
             lambda _text, _headers: None,
         )
 
-    @staticmethod
-    async def _upload_form(
-        driver: AsyncDriver,
-        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,
-            chunk_size=_ASYNC_FILE_BATCH_SIZE,
-        )
-
-        def reject_success(_text: str, _headers: Mapping[str, str]) -> Never:
-            raise ShotgunError('form upload success response is not established')
-
-        await _execute_upload_exchange(driver, context, exchange, reject_success)
-        raise AssertionError('form upload response parser returned')
-
     @staticmethod
     async def _upload_link(
         driver: AsyncDriver,
@@ -1162,14 +1138,14 @@ class AsyncShotgun:
         arguments = prepared.options.arguments
         capabilities = await self._ensure_readiness(context, driver)
         operation_context = await self._authenticated_context(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 await self._upload_form(driver, operation_context, prepared)
         multipart = upload_path == 'multipart'
         upload_info = await self._upload_allocation(
             driver,
@@ -1208,6 +1184,16 @@ class AsyncShotgun:
         prepared: _files.PreparedUpload,
     ) -> int:
         """Execute the exact direct-storage thumbnail workflow."""
+        capabilities = await 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 = await self._upload_allocation(
             driver,
             context,
@@ -1702,6 +1688,9 @@ class AsyncShotgun:
     async 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.
@@ -2022,7 +2011,11 @@ class AsyncShotgun:
             entity,
             seed_entity_field,
         )
-        result = await self._call('nav_search_entity', params)
+        result = await self._call(
+            'nav_search',
+            params,
+            _InvocationOptions(logical_method_name='nav_search_entity'),
+        )
         return _methods.require_dictionary_list_result(result, 'nav_search_entity')
 
     async def nav_search_string(
@@ -2053,7 +2046,11 @@ class AsyncShotgun:
             search_string,
             seed_entity_field,
         )
-        result = await self._call('nav_search_string', params)
+        result = await self._call(
+            'nav_search',
+            params,
+            _InvocationOptions(logical_method_name='nav_search_string'),
+        )
         return _methods.require_dictionary_list_result(result, 'nav_search_string')
 
     async def note_thread_read(
@@ -2078,7 +2075,11 @@ class AsyncShotgun:
                 policy.
         """
         params = _methods.build_note_thread_read_params(note_id, entity_fields)
-        result = await self._call('note_thread_read', params)
+        result = await self._call(
+            'note_thread_contents',
+            params,
+            _InvocationOptions(logical_method_name='note_thread_read'),
+        )
         return _methods.require_dictionary_list_result(result, 'note_thread_read')
 
     async def preferences_read(self, prefs: list[str] | None = None) -> dict[str, object]:
@@ -2357,7 +2358,8 @@ class AsyncShotgun:
 
         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`.
@@ -2374,7 +2376,8 @@ class AsyncShotgun:
             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
@@ -2647,9 +2650,8 @@ class AsyncShotgun:
     async 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.
@@ -2661,8 +2663,8 @@ class AsyncShotgun:
         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.
@@ -2694,6 +2696,9 @@ class AsyncShotgun:
     ) -> 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.
@@ -2706,7 +2711,8 @@ class AsyncShotgun:
         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.
@@ -2728,6 +2734,9 @@ class AsyncShotgun:
     ) -> 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.
@@ -2740,7 +2749,8 @@ class AsyncShotgun:
         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.
@@ -2756,28 +2766,40 @@ class AsyncShotgun:
     async 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 containing `user_id` keys.
+            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 arguments or the server result are invalid.
+                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.
         """
         params = _methods.build_user_subscriptions_create_params(users)
         result = await self._call('user_subscriptions_create', params)
-        return _crud.require_boolean_result(result, 'user_subscriptions_create')
+        return _methods.require_user_subscriptions_create_result(result)
 
     async 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,
@@ -2787,7 +2809,7 @@ class AsyncShotgun:
                 policy.
         """
         result = await self._call('user_subscriptions_read', None)
-        return _methods.require_dictionary_list_result(result, 'user_subscriptions_read')
+        return _methods.require_user_subscriptions_result(result)
 
     async def work_schedule_read(
         self,

shotgun_api3/_client.py

@@ -136,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.
@@ -156,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.
 """
@@ -881,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,
@@ -999,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:
@@ -1030,7 +1006,16 @@ 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)
@@ -1480,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.
@@ -1827,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',
         )
 
@@ -1860,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',
         )
 
@@ -1887,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',
         )
 
@@ -2185,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`.
@@ -2202,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
@@ -2468,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;
@@ -2483,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.
@@ -2516,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.
@@ -2528,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.
@@ -2550,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.
@@ -2562,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.
@@ -2578,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/_files.py

@@ -10,7 +10,7 @@ import urllib.parse
 import urllib.request
 import uuid
 from collections.abc import Callable, Generator, Iterator, Mapping, Sequence
-from contextlib import ExitStack, contextmanager
+from contextlib import contextmanager
 from pathlib import Path
 from typing import BinaryIO, Literal, TypeAlias, TypedDict, cast
 
@@ -35,7 +35,6 @@ _MULTIPART_CHUNK_SIZE = 20_000_000
 _Origin: TypeAlias = tuple[str, str, int]
 _PART_LINK_FIELD_COUNT = 2
 _THUMBNAIL_UPLOAD_FIELDS = ('image', 'filmstrip_image')
-_UPLOAD_FILE = '/upload/upload_file'
 
 
 @dataclasses.dataclass(frozen=True)
@@ -246,17 +245,6 @@ class _ExactOriginCookiePolicy(http.cookiejar.DefaultCookiePolicy):
         )
 
 
-def _build_form_upload_fields(prepared: PreparedUpload) -> dict[str, str]:
-    """Build the non-authenticated legacy form-upload fields."""
-    arguments = prepared.options.arguments
-    return {
-        'entity_type': arguments.entity_type,
-        'entity_id': str(arguments.entity_id),
-        'field_name': arguments.field_name or '',
-        'display_name': arguments.display_name or prepared.filename,
-    }
-
-
 def _entity_reference(entity: Mapping[str, object]) -> str:
     """Serialize one entity as the upload endpoint reference grammar."""
     entity_type = entity.get('type')
@@ -295,48 +283,6 @@ def _iter_file(
                 remaining -= len(chunk)
 
 
-def _multipart_content_length(
-    plan: _protocol.MultipartPlan,
-    file_sizes: Mapping[str, int],
-) -> int:
-    """Return the exact byte length of a multipart plan."""
-    return sum(
-        file_sizes[segment.name] if isinstance(segment, _protocol.FileSlot) else len(segment)
-        for segment in plan.segments
-    )
-
-
-def _pump_multipart(
-    plan: _protocol.MultipartPlan,
-    opened: Mapping[str, BinaryIO],
-    chunk_size: int = 65536,
-) -> Generator[bytes, None, None]:
-    """Yield multipart framing while reading file slots incrementally."""
-    if chunk_size <= 0:
-        raise ValueError('multipart chunk size must be positive')
-    for segment in plan.segments:
-        if isinstance(segment, _protocol.FileSlot):
-            handle = opened[segment.name]
-            while chunk := handle.read(chunk_size):
-                yield chunk
-        else:
-            yield segment
-
-
-def _pump_multipart_from_disk(
-    plan: _protocol.MultipartPlan,
-    paths: Mapping[str, str],
-    chunk_size: int = 65536,
-) -> Generator[bytes, None, None]:
-    """Pump multipart framing through lazily opened disk files."""
-    with ExitStack() as stack:
-        opened: dict[str, BinaryIO] = {}
-        for segment in plan.segments:
-            if isinstance(segment, _protocol.FileSlot) and segment.name not in opened:
-                opened[segment.name] = stack.enter_context(Path(paths[segment.name]).open('rb'))
-        yield from _pump_multipart(plan, opened, chunk_size)
-
-
 def _requires_direct_upload(
     server_info: Mapping[str, object],
     entity_type: str,
@@ -694,53 +640,6 @@ def build_download_redirect(
     return build_download_request(context, location, {'user-agent': context.user_agent})
 
 
-def build_form_upload_exchange(
-    canonical_origin: str,
-    user_agent: str,
-    prepared: PreparedUpload,
-    auth: Mapping[str, object],
-    chunk_size: int = 65536,
-) -> UploadExchange:
-    """Plan one restartable legacy multipart form upload.
-
-    The body can be rebuilt, but the operation is not replay-safe after
-    transmission.
-
-    Args:
-        canonical_origin: Captured site origin.
-        user_agent: Captured user-agent header value.
-        prepared: Validated upload metadata and arguments.
-        auth: Captured authentication form fields.
-        chunk_size: Maximum file bytes read per iteration.
-
-    Returns:
-        Complete restartable form-upload exchange.
-    """
-    fields = add_auth_fields(_build_form_upload_fields(prepared), auth)
-    slot = _protocol.FileSlot(
-        name='file',
-        filename=prepared.filename,
-        content_type='application/octet-stream',
-    )
-    plan = _protocol.build_multipart_plan(fields, [slot])
-    path = prepared.options.arguments.path
-    return UploadExchange(
-        body_factory=lambda: _pump_multipart_from_disk(
-            plan,
-            {'file': path},
-            chunk_size,
-        ),
-        headers={
-            'content-length': str(_multipart_content_length(plan, {'file': prepared.file_size})),
-            'content-type': plan.content_type,
-            'user-agent': user_agent,
-        },
-        method='POST',
-        operation=SHARE_THUMBNAIL_OPERATION,
-        url=f'{canonical_origin}{_UPLOAD_FILE}',
-    )
-
-
 def build_upload_endpoint_exchange(
     canonical_origin: str | None,
     user_agent: str,
@@ -1018,6 +917,27 @@ def prepare_upload(options: UploadOptions) -> PreparedUpload:
     return PreparedUpload(filename=path.name, file_size=file_size, options=options)
 
 
+def require_supported_upload_path(
+    upload_path: Literal['form', 'direct', 'multipart'],
+) -> Literal['direct', 'multipart']:
+    """Reject the unsupported legacy form route before upload I/O.
+
+    Args:
+        upload_path: Route selected from server capabilities.
+
+    Returns:
+        The selected supported route.
+
+    Raises:
+        ShotgunError: If the server requires legacy form uploads.
+    """
+    if upload_path == 'form':
+        raise ShotgunError(
+            'server requires legacy form uploads, which this client does not support'
+        )
+    return upload_path
+
+
 def resolve_attachment_url(attachment: object, base_url: str) -> str | None:
     """Resolve a supported attachment reference to its download URL.
 

shotgun_api3/_methods.py

@@ -3,7 +3,7 @@
 import dataclasses
 import datetime
 import inspect
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from typing import Any, NotRequired, TypedDict, cast
 
 from . import _crud, _protocol
@@ -64,6 +64,9 @@ _ACTIVITY_STREAM_READ_SIGNATURE = inspect.Signature(
 )
 _EXPORT_PAGE_DOCSTRING = """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:
     page_id: Numeric page identifier.
     format: Required nonempty export format name.
@@ -328,6 +331,18 @@ def _entity(value: object) -> object:
     return _protocol.optimize_entity(value)
 
 
+def _is_subscription_value(value: object) -> bool:
+    """Check the supported subscription value forms."""
+    return (
+        value is None
+        or isinstance(value, str)
+        or (
+            isinstance(value, list)
+            and all(isinstance(item, str) for item in cast('list[object]', value))
+        )
+    )
+
+
 def _project_entity(value: object) -> object:
     """Optimize an optional project entity."""
     return None if value is None else _entity(value)
@@ -920,11 +935,38 @@ def build_user_subscriptions_create_params(users: object) -> dict[str, object]:
         users,
         'user_subscriptions_create users must be a list',
     )
-    message = 'user_subscriptions_create users must contain dictionaries with a user_id key'
+    entry_message = (
+        'user_subscriptions_create users must contain dictionaries with '
+        'humanUserId and subscription keys'
+    )
+    params: dict[str, object] = {}
     for member in validated:
-        if not isinstance(member, dict) or 'user_id' not in member:
-            raise ShotgunError(message)
-    return {'users': cast('list[dict[str, object]]', validated)}
+        if not isinstance(member, dict):
+            raise ShotgunError(entry_message)
+        entry = cast('dict[str, object]', member)
+        if 'humanUserId' not in entry or 'subscription' not in entry:
+            raise ShotgunError(entry_message)
+        user_id = entry['humanUserId']
+        if isinstance(user_id, bool) or not isinstance(user_id, (str, int)):
+            raise ShotgunError(
+                'user_subscriptions_create users must contain string or integer humanUserId values'
+            )
+        if not _is_subscription_value(entry['subscription']):
+            raise ShotgunError(
+                'user_subscriptions_create users must contain valid subscription values'
+            )
+        key = str(user_id)
+        if key in params:
+            raise ShotgunError(
+                'user_subscriptions_create users must not contain duplicate user IDs'
+            )
+        subscription = entry['subscription']
+        params[key] = (
+            cast('list[str]', subscription).copy()
+            if isinstance(subscription, list)
+            else subscription
+        )
+    return params
 
 
 def build_work_schedule_read_params(
@@ -1124,6 +1166,57 @@ def require_string_result(value: object, method_name: str) -> str:
     return value
 
 
+def require_user_subscriptions_create_result(value: object) -> bool:
+    """Interpret a mapping of per-user subscription assignment reports.
+
+    Args:
+        value: Raw result returned by the server.
+
+    Returns:
+        `True` if every report is `None`, otherwise `False`.
+
+    Raises:
+        ShotgunError: If the result is not a mapping with string keys.
+    """
+    message = 'user_subscriptions_create returned an invalid result mapping'
+    if not isinstance(value, Mapping):
+        raise ShotgunError(message)
+    reports = cast('Mapping[object, object]', value)
+    if any(not isinstance(key, str) for key in reports):
+        raise ShotgunError(message)
+    return all(report is None for report in reports.values())
+
+
+def require_user_subscriptions_result(value: object) -> list[dict[str, object]]:
+    """Convert a subscription mapping to ordered public entries.
+
+    Args:
+        value: Raw subscription mapping returned by the server.
+
+    Returns:
+        Entries with unchanged string `humanUserId` and `subscription` values
+        of `None`, string, or list of strings. Lists are copied.
+
+    Raises:
+        ShotgunError: If the result is not a valid subscription mapping.
+    """
+    if not isinstance(value, Mapping):
+        raise ShotgunError('user_subscriptions_read did not return a dictionary')
+    subscriptions: list[dict[str, object]] = []
+    for user_id, subscription in cast('Mapping[object, object]', value).items():
+        if not isinstance(user_id, str) or not user_id:
+            raise ShotgunError('user_subscriptions_read returned an invalid user ID')
+        if not _is_subscription_value(subscription):
+            raise ShotgunError('user_subscriptions_read returned an invalid subscription')
+        public_subscription = (
+            cast('list[str]', subscription).copy()
+            if isinstance(subscription, list)
+            else subscription
+        )
+        subscriptions.append({'humanUserId': user_id, 'subscription': public_subscription})
+    return subscriptions
+
+
 def schema_alias_error(entity_type: object) -> ShotgunError:
     """Build the error raised by the deprecated `schema` alias.
 

shotgun_api3/_protocol.py

@@ -7,7 +7,6 @@ import json
 import math
 import re
 import sys
-import uuid as _uuid
 from collections.abc import Callable, Mapping, Sequence
 from datetime import UTC
 from email.utils import parsedate_to_datetime
@@ -107,7 +106,6 @@ _IMF_FIXDATE_PATTERN = re.compile(
 _JITTER_BYTES = 8
 _JITTER_RANGE = 1 << (_JITTER_BYTES * 8)
 _MIN_CONDITION_PARTS = 2
-_MULTIPART_BOUNDARY_PATTERN = re.compile(r"[A-Za-z0-9'+._-]{1,70}")
 _OPTIMIZABLE_RELATIONS = frozenset({'is', 'is_not', 'in', 'not_in'})
 _RETRYABLE_STATUSES = frozenset({502, 503, 504})
 _RETRY_AFTER_TOO_LARGE: Final = 'too-large'
@@ -209,34 +207,6 @@ class Failure:
     retry_after: _RetryAfter
 
 
-@dataclasses.dataclass(frozen=True)
-class FileSlot:
-    """Placeholder for file bytes inside a multipart plan.
-
-    Attributes:
-        name: Multipart form field name.
-        filename: Filename exposed in the multipart part.
-        content_type: Media type exposed in the multipart part.
-    """
-
-    name: str
-    filename: str
-    content_type: str
-
-
-@dataclasses.dataclass(frozen=True)
-class MultipartPlan:
-    """Byte segments and file slots forming a multipart/form-data body.
-
-    Attributes:
-        content_type: Multipart content type including its boundary.
-        segments: Ordered encoded segments and file placeholders.
-    """
-
-    content_type: str
-    segments: list[bytes | FileSlot]
-
-
 @dataclasses.dataclass(frozen=True)
 class OperationDescriptor:
     """Describe the replay properties of one logical operation.
@@ -365,11 +335,6 @@ def _entity_optimization_disabled() -> bool:
     return cast('bool', module.SHOTGUN_API_DISABLE_ENTITY_OPTIMIZATION)
 
 
-def _escape_disposition(value: str) -> str:
-    """Make a value safe inside a Content-Disposition quoted-string."""
-    return value.replace('\\', '\\\\').replace('"', '%22').replace('\r', '').replace('\n', '')
-
-
 def _explicit_delay_is_safe(delay: float) -> bool:
     """Return whether a delay stays within the bounded retry policy."""
     return math.isfinite(delay) and 0 <= delay <= _BACKOFF_CAP
@@ -491,13 +456,6 @@ def _parse_retry_after(headers: Mapping[str, str], now: float) -> _RetryAfter:
     return delay
 
 
-def _validate_multipart_boundary(boundary: str) -> str:
-    """Return a boundary safe for multipart framing and an unquoted header."""
-    if not _MULTIPART_BOUNDARY_PATTERN.fullmatch(boundary):
-        raise ValueError('multipart boundary must be 1 to 70 safe ASCII characters')
-    return boundary
-
-
 def _validated_nonnegative_integer(value: object, name: str) -> int:
     """Return a non-boolean, nonnegative integer paging value."""
     if not isinstance(value, int) or isinstance(value, bool) or value < 0:
@@ -615,57 +573,6 @@ def classify_endpoint(
     )
 
 
-def build_multipart_plan(
-    fields: dict[str, str],
-    files: list[FileSlot],
-    boundary: str | None = None,
-) -> MultipartPlan:
-    """Build a pure multipart/form-data framing plan.
-
-    Args:
-        fields: Text form fields in multipart emission order.
-        files: File placeholders in multipart emission order.
-        boundary: Explicit boundary of 1-70 ASCII letters, digits, apostrophes,
-            plus signs, periods, underscores, or hyphens; `None` generates one.
-
-    Returns:
-        A content type and ordered framing segments for the multipart body.
-
-    Raises:
-        ValueError: If an explicit boundary is empty or unsafe for unquoted
-            use.
-    """
-    multipart_boundary = (
-        _uuid.uuid4().hex if boundary is None else _validate_multipart_boundary(boundary)
-    )
-    segments: list[bytes | FileSlot] = []
-    for name, value in fields.items():
-        segments.append(
-            (
-                f'--{multipart_boundary}\r\nContent-Disposition: form-data; '
-                f'name="{_escape_disposition(name)}"'
-                f'\r\n\r\n{value}\r\n'
-            ).encode()
-        )
-    for slot in files:
-        segments.append(
-            (
-                f'--{multipart_boundary}\r\nContent-Disposition: form-data; '
-                f'name="{_escape_disposition(slot.name)}"; '
-                f'filename="{_escape_disposition(slot.filename)}"'
-                f'\r\nContent-Type: {slot.content_type}'
-                '\r\n\r\n'
-            ).encode()
-        )
-        segments.append(slot)
-        segments.append(b'\r\n')
-    segments.append(f'--{multipart_boundary}--\r\n'.encode())
-    return MultipartPlan(
-        content_type=f'multipart/form-data; boundary={multipart_boundary}',
-        segments=segments,
-    )
-
-
 def classify(
     method_name: str,
     normalized_params: object,

shotgun_api3/_version.py

@@ -1,3 +1,3 @@
 """Package version shared by public exports and compatibility metadata."""
 
-PACKAGE_VERSION = '0.1.1'
+PACKAGE_VERSION = '0.1.2'