Skip to content

Commit cc3e080

Browse files
authored
SG-12960 doc edits and additions for direct upload to s3 (#201)
* SG-12960 doc edits and additions for direct upload to s3 * add new 'Interpreting Image field strings' section and cross-references to it within attachments and thumbnail-handling docs
1 parent 1cf6c3b commit cc3e080

File tree

4 files changed

+56
-4
lines changed

4 files changed

+56
-4
lines changed

docs/cookbook/attachments.rst

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,12 +76,17 @@ descriptions of each field.
7676

7777
- **image** (:obj:`str`):
7878
The url location of the thumbnail image assigned to this Attachment. For uploads, Shotgun
79-
automatically tries to create a thumbnail from the file. Alternatively, you can assign your
79+
automatically tries to create a thumbnail from the file.
80+
See :ref:`interpreting_image_field_strings`. Alternatively, you can assign your
8081
own thumbnail to an Attachment using the :meth:`~shotgun_api3.Shotgun.upload_thumbnail` method.
8182

8283
- **sg_type** (:obj:`str`):
8384
An optional field for designating different types of Attachments
8485

86+
- **processing_status** (:obj:`str`):
87+
Reflects the status of the attachment (File entity).
88+
When processing the thumbnail, this field is set to ‘Thumbnail Pending’.
89+
8590

8691
File type structures (``this_file``)
8792
====================================
@@ -157,6 +162,10 @@ Uploads
157162
Uploads cannot be created directly on Attachments. Instead, you need to use the
158163
:meth:`~shotgun_api3.Shotgun.upload` method.
159164

165+
Make sure to have retries for file uploads. Failures when uploading will occasionally happen. When
166+
it does, immediately retrying to upload usually works.
167+
168+
160169
Local Files
161170
===========
162171
See :ref:`creating_local_files`.

docs/cookbook/examples/basic_upload_thumbnail_version.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,8 @@ you've just created your Version in Shotgun, you know its ``id`` is **214**.
88

99
.. note:: If you upload a movie file or image to the ``sg_uploaded_movie`` field and you have
1010
transcoding enabled on your server (the default for hosted sites), a thumbnail will be
11-
generated automatically as well as a filmstrip thumbnail (if possible). But this example is
12-
provided just to show the basic process of uploading a thumbnail manually where is may be
13-
necessary.
11+
generated automatically as well as a filmstrip thumbnail (if possible).
12+
This is a basic example of how to manually provide or replace a thumbnail image.
1413

1514
Upload the Image using :meth:`~shotgun_api3.Shotgun.upload_thumbnail`
1615
---------------------------------------------------------------------

docs/reference.rst

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -671,6 +671,9 @@ image (read-only)
671671

672672
:value: :obj:`str` | :obj:`None`
673673

674+
.. note::
675+
Refer to :ref:`interpreting_image_field_strings`.
676+
674677
list
675678
====
676679

@@ -788,6 +791,36 @@ Additional keys exist for local file links
788791
'content_type': "string"
789792
}
790793

794+
.. _interpreting_image_field_strings:
795+
796+
********************************
797+
Interpreting Image Field Strings
798+
********************************
799+
800+
There are three possible states for values returned by an ``image`` field:
801+
802+
.. list-table::
803+
:header-rows: 1
804+
805+
* - Type
806+
- Value - Description
807+
* - :obj:`None`
808+
- No thumbnail image uploaded, or thumbnail generation failed.
809+
* - :obj:`str`
810+
- | ``<protocol>://<domain>/images/status/transient/thumbnail_pending.png`` -
811+
| URLs of this form indicate a transient placeholder icon.
812+
| Returned if image requested between upload & availability from media storage.
813+
| Constant string per site.
814+
* - :obj:`str`
815+
- | ``<signed URL for S3 object>`` -
816+
| Access to final thumbnail.
817+
818+
.. note::
819+
Other upcoming features are likely to require the use of other transient thumbnails.
820+
For this reason, it is highly recommended to use the prefix part of the placeholder path
821+
(e.g. https://yoursubdomain.shotgunstudio.com/images/status/transient/)
822+
to detect any transient URLs rather than use the full path of the thumbnail.
823+
791824
.. _event_types:
792825

793826
***********

shotgun_api3/shotgun.py

100755100644
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2192,6 +2192,10 @@ def share_thumbnail(self, entities, thumbnail_path=None, source_entity=None,
21922192
.. note::
21932193
When sharing a filmstrip thumbnail, it is required to have a static thumbnail in
21942194
place before the filmstrip will be displayed in the Shotgun web UI.
2195+
If the :ref:`thumbnail is still processing and is using a placeholder
2196+
<interpreting_image_field_strings>`, this method will error.
2197+
2198+
Simple use case:
21952199
21962200
>>> thumb = '/data/show/ne2/100_110/anim/01.mlk-02b.jpg'
21972201
>>> e = [{'type': 'Version', 'id': 123}, {'type': 'Version', 'id': 456}]
@@ -2215,6 +2219,8 @@ def share_thumbnail(self, entities, thumbnail_path=None, source_entity=None,
22152219
share the static thumbnail. Defaults to ``False``.
22162220
:returns: ``id`` of the Attachment entity representing the source thumbnail that is shared.
22172221
:rtype: int
2222+
:raises: :class:`ShotgunError` if not supported by server version or improperly called,
2223+
or :class:`ShotgunThumbnailNotReady` if thumbnail is still pending.
22182224
"""
22192225
if not self.server_caps.version or self.server_caps.version < (4, 0, 0):
22202226
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
23732379
You can optionally store the file in a field on the entity, change the display name, and
23742380
assign tags to the Attachment.
23752381
2382+
.. note::
2383+
Make sure to have retries for file uploads. Failures when uploading will occasionally happen.
2384+
When it does, immediately retrying to upload usually works
2385+
23762386
>>> mov_file = '/data/show/ne2/100_110/anim/01.mlk-02b.mov'
23772387
>>> sg.upload("Shot", 423, mov_file, field_name="sg_latest_quicktime",
23782388
... display_name="Latest QT")
@@ -2387,6 +2397,7 @@ def upload(self, entity_type, entity_id, path, field_name=None, display_name=Non
23872397
:param str tag_list: comma-separated string of tags to assign to the file.
23882398
:returns: Id of the Attachment entity that was created for the image.
23892399
:rtype: int
2400+
:raises: :class:`ShotgunError` on upload failure.
23902401
"""
23912402
# Basic validations of the file to upload.
23922403
path = os.path.abspath(os.path.expanduser(path or ""))

0 commit comments

Comments
 (0)