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

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`.

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`
 ---------------------------------------------------------------------

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`
+     - | ``<protocol>://<domain>/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`
+     - | ``<signed URL for S3 object>`` -
+       | 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:
 
 ***********

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 
+            <interpreting_image_field_strings>`, 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 ""))