diff --git a/docs/cookbook/attachments.rst b/docs/cookbook/attachments.rst index 5988e904..59bffb40 100644 --- a/docs/cookbook/attachments.rst +++ b/docs/cookbook/attachments.rst @@ -76,12 +76,17 @@ descriptions of each field. - **image** (:obj:`str`): The url location of the thumbnail image assigned to this Attachment. For uploads, Shotgun - automatically tries to create a thumbnail from the file. Alternatively, you can assign your + automatically tries to create a thumbnail from the file. + See :ref:`interpreting_image_field_strings`. Alternatively, you can assign your own thumbnail to an Attachment using the :meth:`~shotgun_api3.Shotgun.upload_thumbnail` method. - **sg_type** (:obj:`str`): An optional field for designating different types of Attachments +- **processing_status** (:obj:`str`): + Reflects the status of the attachment (File entity). + When processing the thumbnail, this field is set to ‘Thumbnail Pending’. + File type structures (``this_file``) ==================================== @@ -157,6 +162,10 @@ Uploads Uploads cannot be created directly on Attachments. Instead, you need to use the :meth:`~shotgun_api3.Shotgun.upload` method. +Make sure to have retries for file uploads. Failures when uploading will occasionally happen. When +it does, immediately retrying to upload usually works. + + Local Files =========== See :ref:`creating_local_files`. diff --git a/docs/cookbook/examples/basic_upload_thumbnail_version.rst b/docs/cookbook/examples/basic_upload_thumbnail_version.rst index 62713aa9..c2f221e1 100644 --- a/docs/cookbook/examples/basic_upload_thumbnail_version.rst +++ b/docs/cookbook/examples/basic_upload_thumbnail_version.rst @@ -8,9 +8,8 @@ you've just created your Version in Shotgun, you know its ``id`` is **214**. .. note:: If you upload a movie file or image to the ``sg_uploaded_movie`` field and you have transcoding enabled on your server (the default for hosted sites), a thumbnail will be - generated automatically as well as a filmstrip thumbnail (if possible). But this example is - provided just to show the basic process of uploading a thumbnail manually where is may be - necessary. + generated automatically as well as a filmstrip thumbnail (if possible). + This is a basic example of how to manually provide or replace a thumbnail image. Upload the Image using :meth:`~shotgun_api3.Shotgun.upload_thumbnail` --------------------------------------------------------------------- diff --git a/docs/reference.rst b/docs/reference.rst index d5f68d99..4fb6748e 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -671,6 +671,9 @@ image (read-only) :value: :obj:`str` | :obj:`None` + .. note:: + Refer to :ref:`interpreting_image_field_strings`. + list ==== @@ -788,6 +791,36 @@ Additional keys exist for local file links 'content_type': "string" } +.. _interpreting_image_field_strings: + +******************************** +Interpreting Image Field Strings +******************************** + +There are three possible states for values returned by an ``image`` field: + +.. list-table:: + :header-rows: 1 + + * - Type + - Value - Description + * - :obj:`None` + - No thumbnail image uploaded, or thumbnail generation failed. + * - :obj:`str` + - | ``:///images/status/transient/thumbnail_pending.png`` - + | URLs of this form indicate a transient placeholder icon. + | Returned if image requested between upload & availability from media storage. + | Constant string per site. + * - :obj:`str` + - | ```` - + | Access to final thumbnail. + +.. note:: + Other upcoming features are likely to require the use of other transient thumbnails. + For this reason, it is highly recommended to use the prefix part of the placeholder path + (e.g. https://yoursubdomain.shotgunstudio.com/images/status/transient/) + to detect any transient URLs rather than use the full path of the thumbnail. + .. _event_types: *********** diff --git a/shotgun_api3/shotgun.py b/shotgun_api3/shotgun.py old mode 100755 new mode 100644 index 1da09cca..bb686ffb --- a/shotgun_api3/shotgun.py +++ b/shotgun_api3/shotgun.py @@ -2192,6 +2192,10 @@ def share_thumbnail(self, entities, thumbnail_path=None, source_entity=None, .. note:: When sharing a filmstrip thumbnail, it is required to have a static thumbnail in place before the filmstrip will be displayed in the Shotgun web UI. + If the :ref:`thumbnail is still processing and is using a placeholder + `, this method will error. + + Simple use case: >>> thumb = '/data/show/ne2/100_110/anim/01.mlk-02b.jpg' >>> e = [{'type': 'Version', 'id': 123}, {'type': 'Version', 'id': 456}] @@ -2215,6 +2219,8 @@ def share_thumbnail(self, entities, thumbnail_path=None, source_entity=None, share the static thumbnail. Defaults to ``False``. :returns: ``id`` of the Attachment entity representing the source thumbnail that is shared. :rtype: int + :raises: :class:`ShotgunError` if not supported by server version or improperly called, + or :class:`ShotgunThumbnailNotReady` if thumbnail is still pending. """ if not self.server_caps.version or self.server_caps.version < (4, 0, 0): raise ShotgunError("Thumbnail sharing support requires server " @@ -2373,6 +2379,10 @@ def upload(self, entity_type, entity_id, path, field_name=None, display_name=Non You can optionally store the file in a field on the entity, change the display name, and assign tags to the Attachment. + .. note:: + Make sure to have retries for file uploads. Failures when uploading will occasionally happen. + When it does, immediately retrying to upload usually works + >>> mov_file = '/data/show/ne2/100_110/anim/01.mlk-02b.mov' >>> sg.upload("Shot", 423, mov_file, field_name="sg_latest_quicktime", ... display_name="Latest QT") @@ -2387,6 +2397,7 @@ def upload(self, entity_type, entity_id, path, field_name=None, display_name=Non :param str tag_list: comma-separated string of tags to assign to the file. :returns: Id of the Attachment entity that was created for the image. :rtype: int + :raises: :class:`ShotgunError` on upload failure. """ # Basic validations of the file to upload. path = os.path.abspath(os.path.expanduser(path or ""))