Available API methods

• Shotgun()
• find()
• find_one()
• create()
• update()
• delete()
• revive()
• batch()
• upload()
• upload_thumbnail()
• upload_filmstrip_thumbnail()
• download_attachment()
• work_schedule_read()
• work_schedule_update()
• schema_read()
• schema_field_read()
• schema_entity_read()
• schema_field_delete()
• schema_field_update()
• schema_field_create()
• set_session_uuid()

dict Shotgun(string base_url, string script_name, string api_key, string api_ver, boolean convert_datetimes_to_utc, string http_proxy)

Constructor to create a new Shotgun instance.

• string base_url (required)
  This is the url of the Shotgun server. Make sure you include the 'http:' ('https:' if you are using SSL). Do not include the trailing slash. Example: https://example.shotgunstudio.com.
• string script_name (default=None)
  The name of the script as defined on the Scripts page in Shotgun (see [setup](https://shotgunsoftware.zendesk.com/forums/31279/entries/21646 Set up Shotgun for API Access) ).
• string api_key (default=None)
  The api_key this script will use for communicating with the Shotgun server.
• string api_ver (default='api3')
  The API version to use. This is useful for when we upgrade the Shotgun API, you can incrementally update your scripts to take advantage of the new version of the API one by one.
• boolean convert_datetimes_to_utc (default=True)
  Automatically have the API convert datetimes between local time and UTC. Datetimes are stored in the database in UTC. When this parameter is True, it will use local machine settings for timezone and daylight saving time settings in order to convert datetimes to and from UTC. Datetimes that are returned from Shotgun will be converted from UTC to the local time and the datetime object will contain a tzinfo class. Datetimes that are sent to Shotgun will be converted from local time to UTC. If this parameter is False the datetime object returned by Shotgun will be in UTC and will not have a tzinfo class attached. Conversely, datetimes sent to Shotgun will be assumed as UTC and will be stored as such. Make sure the machine the script is running on has the correct timezone and daylight saving time settings.
• string http_proxy (default=None)
  URL of your proxy server, on the forms 123.123.123.123, 123.123.123.123:8888 or user:pass@123.123.123.123:8888.

• dict A Shotgun object
  • api_key: (string) The api_key this script will use for communicating with the Shotgun server.
  • api_url: (string) This is the full url path of the Shotgun server API. Example: https://example.shotgunstudio.com/api3/.
  • api_ver: (string) The API version being used.
  • base_url: (string) This is the root url of the Shotgun server. Example: https://example.shotgunstudio.com.
  • convert_datetimes_to_utc: (boolean) Automatically have the API convert datetimes between local time and UTC. Datetimes are stored in the database in UTC. If this is enabled, it will use local machine settings for timezone and daylight saving time to convert to and from UTC.
  • http_proxy: (string) URL of your proxy server or None
  • local_path_string: (string) Used internally to populate 'local_path' key for local file links
  • platform: (string) Platform current script is running on or None if unsupported. ('windows','linux', or 'mac')
  • script_name: (string) The name of the script calling the API as defined on the Scripts page in Shotgun
  • server_info: (dict) Information about the Shotgun server the script is connecting to. 'server_info': {'version': [2, 4, 0, 'Dev']}
  • sid: (string) Legacy field used internally to store a session id for retrieving files and attachments
  • supports_paging_info: (boolean) Whether or not the current Shotgun server version supports omitting requests for paging information when performing read requests. Omitting paging information from requests that are limited to a single page will speed up performance.

from shotgun import Shotgun 
SERVER_PATH = 'http://shotgun.examplestudio.com' # change this to https if your studio uses SSL
SCRIPT_USER = 'trigger_script'
SCRIPT_KEY = '2350acafb1826c92e4121986fe663043b77bb8da'
sg = Shotgun(SERVER_PATH, SCRIPT_USER, SCRIPT_KEY)

list find(string entity_type, list filters, list fields, array order, string filter_operator, int limit, boolean retired_only, int page)

Find entities

• string entity_type (required)
  The entity type to find (in CamelCase format). Example: MocapTake.
• list filters (required)
  An array of array conditions used to filter the find query. You can find the reference for filter values here.
  • Each condition should be in the format [ column_name, operator, value1(, value2) ] defined as the following:
  • column_name (string): The system name of the column (not the display name) Examples: “code”, “sg_asset_type”.
  • operator (string): the operator as it appears in the query builder. Examples: “is”, “is_not”, "between", “in_last”.
  • value (mixed): The value to compare the column on.
  • value2 (optional for some operators) (int): The second value for column comparison. This value is specified for operators such as ”between”.
• list fields (default="id")
  The column fields to return for the entities.
  • These are the internal codes for the columns like sg_asset_type not ”Asset Type”.
• list order (default=[])
  Order results using the provided column and direction string attributes.
  • The order parameter takes an array of dict objects to allow for multiple sorting rules. Example: [{'field_name':'created_at','direction':'asc'}, {'field_name':'id','direction':'desc'}].
  • The default will return the records in whatever order the database returns them by default.
• string filter_operator (default="all")
  Controls how the filters are matched. There are only two valid options: all and any. You cannot currently combine the two options in the same query.
• int limit (default=0)
  Limit the number of results returned.
  • A value of 0 will not limit the results.
• boolean retired_only (default=False)
  Return only retired entities.
  • By default find() returns ONLY active entities.
  • There is no way to return both active and retired entities in the same query.
• int page (default=0)
  Return a single specified page number of records instead of the entire result set
  • By default find() returns all records. Specifying a value of 0 will have the same effect.
  • Shotgun processes results in pages of 500 records by default. You can use the limit() parameter to set this lower but it cannot be set higher.

• list of dict objects containing key/value pairs for each column specified in the fields parameter. Returns a minimum of the 'id' and 'type' fields representing the entity type and id of the record(s) returned. For fields that represent links to other entities, the value will be a dict object defining the entity with id, name, type, and valid attributes.

# ----------------------------------------------
# Get Character Assets in Sequence 100_FOO
# ----------------------------------------------
fields = ['id', 'code', 'sg_asset_type']
sequence_id = 2 # Sequence 100_FOO
project_id = 4 # Demo Project
filters = [
    ['project','is',{'type':'Project','id':project_id}],
    ['sg_asset_type','is', 'Character'],
    ['sequences', 'is', {'type':'Sequence','id':sequence_id}]
    ]
assets= sg.find("Asset",filters,fields)
if len(assets) < 1:
    print "couldn't find any assets"
    exit(0)
else:
    print "Found "+str(len(assets))+" assets"
    pprint (assets)

example output:

 Found 7 assets  
 [{'code': 'Gopher', 'id': 32, 'sg_asset_type': 'Character', 'type': 'Asset'},  
  {'code': 'Cow', 'id': 33, 'sg_asset_type': 'Character', 'type': 'Asset'},  
  {'code': 'Bird_1', 'id': 35, 'sg_asset_type': 'Character', 'type': 'Asset'},  
  {'code': 'Bird_2', 'id': 36, 'sg_asset_type': 'Character', 'type': 'Asset'},  
  {'code': 'Bird_3', 'id': 37, 'sg_asset_type': 'Character', 'type': 'Asset'},  
  {'code': 'Raccoon', 'id': 45, 'sg_asset_type': 'Character', 'type': 'Asset'},  
  {'code': 'Wet Gopher', 'id': 149, 'sg_asset_type': 'Character', 'type': 'Asset'}]  

list find_one(string entity_type, list filters, [list fields, list order, string filter_operator)

Find one entity. This is a wrapper for find() with a limit=1. This will also speeds the request as no paging information is requested from the server.

• string entity_type (required)
  The entity type to find (in CamelCase format). Example: MocapTake.
• list filters (required)
  An array of array conditions used to filter the find query. You can find the reference for filter values here.
  • Each condition should be in the format [ column_name, operator, value1(, value2) ] defined as the following:
  • column_name (string): The system name of the column (not the display name). Examples: “code”, “sg_asset_type”.
  • operator (string): The operator as it appears in the query builder. Examples: “is”, “is_not”, "between", “in_last”.
  • value (mixed): The value to compare the column on.
  • value2 (optional for some operators) (int): The second value for column comparison. This value is specified for operators such as ”between”.
• list fields (default="id")
  The column fields to return for the entities.
  • These are the internal codes for the columns like sg_asset_type not ”Asset Type”.
• list order (default=[])
  Order results using the provided column and direction string attributes.
  • The order parameter takes an array of dict objects to allow for multiple sorting rules. Example: [{'field_name':'created_at','direction':'asc', {'field_name':'id','direction':'desc'}].
  • The default will return the records in whatever order the database returns them by default.
• string filter_operator (default="all")
  Controls how the filters are matched. There are only two valid options: all and any. You cannot currently combine the two options in the same query.

• dict object containing key/value pairs for each column specified in the fields parameter. Returns a minimum of the 'id' and 'type' fields representing the entity type and id of the record returned. For fields that represent links to other entities, the value will be a dict object defining the entity with id, name, type, and valid attributes. Note that this differs from find() which returns an array of dicts.

# ----------------------------------------------
# Find Character Asset
# ----------------------------------------------
fields = ['id', 'code', 'sg_status_list']
asset_id = 32 # Gopher
project_id = 4 # Demo Project
filters = [
    ['project','is',{'type':'Project','id':project_id}],
    ['id','is',asset_id]
    ]
asset= sg.find_one("Asset",filters,fields)
if not asset:
    print "couldn't find asset"
    exit(0)
else:
    pprint (asset)

example output:

 {'code': 'Gopher', 'id': 32, 'sg_status_list': 'ip', 'type': 'Asset'} 

dict create(string entity_type, dict data)

Create a new entity with the values provided in the data dictionary where keys are the fields to set with their corresponding values.

• string entity_type (required)
  The entity type to create (in CamelCase format). Example: MocapTake
• dict data (required)
  A dict of key/value pairs where key is the column name and value is the value to set for that column. Note that most entities require the project (dict) parameter that designates the project this entity belongs to.
• list return_fields (optional)
  An array of field names to be returned, in addition to ones being sent in the data param.

• dict object containing key/value pairs for each column specified in the fields parameter as well as the id for the created entity and a special type key which holds the entity type to make it easy to pipe this hash into another query. For fields that represent links to other entities, the value will be a dict object defining the entity with id, name, type, and valid attributes. Note that this differs from find() which returns an array of dicts.

# ----------------------------------------------
# Create new Version 
# ----------------------------------------------
project_id = 4 # Demo Project
data = {
    'project': {'type':'Project','id':project_id},
    'code':'JohnnyApple_Design01_FaceFinal',
    'description': 'fixed rig per director final notes',
    'id': 6007
    'sg_status_list':'rev',
    'entity': {'type':'Asset','id':123},
    'type': 'Version',
    'user': {'type':'HumanUser','id':'165'},
    }
version = sg.create("Version",data,return_fields=[''])
pprint(version)

example output:

 {  
    'project': {'type':'Project','id':project_id},  
    'code':'JohnnyApple_Design01_FaceFinal',  
    'description': 'fixed rig per director final notes',  
    'sg_status_`list`':'rev',  
    'entity': {'type':'Asset','id':123},  
    'user': {'type':'HumanUser','id':'165'},   'type': 'Version',  
 }  

dict update(string entity_type, int entity_id, dict data)

Update specified entity columns with paired values.

• string entity_type (required)
  The entity type to update (in CamelCase format). Example: Asset.
• int entity_id (required)
  The specific entity id to update.
• dict data (required)
  key/value pairs where key is the column name and value is the value to set for that column.

• dict entity object with updated values.

# ----------------------------------------------
# Update Asset: link asset to shots and update status
# ----------------------------------------------
asset_id = 55
shots_asset_is_in = [
    {'type':'Shot', 'id':'40435'},
    {'type':'Shot', 'id':'40438'},
    {'type':'Shot', 'id':'40441'}
    ]
data = {
    'shots': shots_asset_is_in, 
    'sg_status_list':'rev' 
    }
asset = sg.update("Asset",asset_id,data)
pprint(asset)

example output:

 {'type': 'Shot',  
  'id': 55,  
  'sg_status_`list`': 'rev',  
  'shots': [{'id': 40435, 'name': '100_010', 'type': 'Shot', 'valid': 'valid'},  
            {'id': 40438, 'name': '100_040', 'type': 'Shot', 'valid': 'valid'},  
            {'id': 40441, 'name': '100_070', 'type': 'Shot', 'valid': 'valid'}]  
 }  

boolean delete(string entity_type, int entity_id)

Retires the entity matching entity_type and entity_id.

• string entity_type (required)
  The type of entity to delete (in CamelCase format). Example: Asset.
• int entity_id (required)
  The id of the specific entity to delete.

• boolean True if entity was deleted successfully.

# ----------------------------------------------
# Delete (retire) Asset
# ----------------------------------------------
result = sg.delete("Asset",23)
pprint(result)

example output:

True

boolean revive(string entity_type, int entity_id)

Revives (un-deletes) the entity matching entity_type and entity_id.

• string entity_type (required)
  The type of entity to revive (in CamelCase format). Example: Asset.
• int entity_id (required)
  The id of the specific entity to revive.

• boolean True if entity was revived successfully. False if the entity was already revived.

# ----------------------------------------------
# Revive (un-retire) Asset
# ----------------------------------------------
result = sg.revive("Asset",23)
pprint(result)

example output:

 True 

list batch(list requests)

Make a batch request of several create, update, and/or delete calls at one time. This is for performance when making large numbers of requests, as it cuts down on the overhead of roundtrips to the server and back. All requests are performed within a transaction, and if any request fails, all of them will be rolled back.

• list requests (required)
  A list of dicts, that are the requests to be batched. The required keys of the `dictionary for each request type are similar to what you pass to the non-batched methods, with the addition of a request_type key to specify which type of request it is.
  • create:
    • string request_type (required)
      The type of request this is. Example: create
    • string entity_type (required)
      The entity type to create (in CamelCase format). Example: MocapTake
    • dict data (required)
      A dict of key/value pairs where key is the column name and value is the value to set for that column. Note that most entities require the project (dict) parameter that designates the project this entity belongs to.
  • update:
    • string request_type (required)
      The type of request this is. Example: update
    • string entity_type (required)
      The entity type to update (in CamelCase format). Example: Asset.
    • int entity_id (required)
      The specific entity id to update.
    • dict data (required)
      A dict of key/value pairs where key is the column name and value is the value to set for that column.
  • delete:
    • string request_type (required)
      The type of request this is. Example: delete
    • string entity_type (required)
      The type of entity to delete (in CamelCase format). Example: Asset.
    • int entity_id (required)
      The id of the specific entity to delete.

• list containing dictionaries, with the results of each batched request in the same order they were passed to the batch method. The return values for each request are the same as for their non-batched methods:
  • create:
    • dict object containing key/value pairs for each column specified in the data parameter.
  • update:
    • dict object containing key/value pairs for each column specified in the data parameter.
  • delete:
    • boolean True if entity was deleted successfully

# ----------------------------------------------
# Make a bunch of shots
# ----------------------------------------------
batch_data = []
for i in range(1,100):
    data = {
        "code":"shot_%04d" % i,
        "project":project
    }
    batch_data.append( {"request_type":"create","entity_type":"Shot","data":data} )
pprint( sg.batch(batch_data) )

example output:

 [{'code': 'shot_0001',  
   'type': 'Shot',  
   'id': 3624,  
   'project': {'id': 4, 'name': 'Demo Project', 'type': 'Project'}},  
 ... and a bunch more ...  
  {'code': 'shot_0099',  
   'type': 'Shot',  
   'id': 3722,  
   'project': {'id': 4, 'name': 'Demo Project', 'type': 'Project'}}]  

# ----------------------------------------------
# All three types of requests in one batch!
# ----------------------------------------------
requests = [
  {"request_type":"create","entity_type":"Shot","data":{"code":"New Shot 1", "project":project}},
  {"request_type":"update","entity_type":"Shot","entity_id":3624,"data":{"code":"Changed 1"}},
  {"request_type":"delete","entity_type":"Shot","entity_id":3624}
]
pprint( sg.batch(requests) )

example output:

 [{'code': 'New Shot 1', 'type': 'Shot', 'id': 3723, 'project': {'id': 4, 'name': 'Demo Project', 'type': 'Project'}},  
  {'code': 'Changed 1', 'type': 'Shot', 'id': 3624},  
  True] 

None upload(string entity_type, int entity_id, string path, [string field_name, string display_name, string tag_list])

Uploads a file from a local directory and links it to a specified entity. Optionally assign the file to a specific field. Optionally create a display name for the label.

• string entity_type (required)
  The entity type to link the uploaded file to (in CamelCase format). Example: MocapTake.
• int entity_id (required)
  The id of the specific entity to link the uploaded file to.
• string path (required)
  The full path to the local file to upload.
• string field_name (default="sg_attachment")
  Optional name of the field within Shotgun to assign the file to. Must be a field of type File/Link.
• string display_name (default=None)
  Optional text to display as the link to the file. The default is the original file name.
• string tag_list (default=None)
  Optional comma separated string of tags to attach to the File entity when it is created in Shotgun.

• int id of the Attachment created by the upload if it was successful. An error is raised if not.

# ----------------------------------------------
# Upload Latest Quicktime
# ----------------------------------------------
quicktime = '/data/show/ne2/100_110/anim/01.mlk-02b.mov'
shot_id = 423
result = sg.upload("Shot",shot_id,quicktime,"sg_latest_quicktime","Latest QT")
print result

example output:

 72 

int upload_thumbnail(string entity_type, int entity_id, string path)

Uploads a file from a local directory and assigns it as the thumbnail for the specified entity. Note: Currently you cannot un-set or clear a thumbnail on an entity. This is a known issue that has an associated bug ticket.

• string entity_type (required)
  The entity type to link the thumbnail to (in CamelCase format). Example: MocapTake.
• int entity_id (required)
  The id of the specific entity to link the thumbnail to.
• string path (required)
  The full path to the local thumbnail file to upload.

• int id of the Attachment entity that was created for the image if thumbnail was uploaded successfully. An error is raised if not.

# ----------------------------------------------
# Upload Thumbnail
# ----------------------------------------------
version_id = 27
thumbnail = '/data/show/ne2/100_110/anim/01.mlk-02b.jpg'
result = sg.upload_thumbnail("Version",version_id,thumbnail)
print result

example output:

 36 

(requires Shotgun server >= v3.1.0 and Python API >= v3.0.9_beta1)

int upload_filmstrip_thumbnail(string entity_type, int entity_id, string path)

Uploads a file from a local directory and assigns it as the filmstrip thumbnail for the specified entity. The image must be a horizontal strip of any number of frames that are exactly 240 pixels wide. So the whole strip must be an exact multiple of 240 pixels in width. The height can be anything (and will depend on the aspect ratio of the frames). Any image filetype that works for thumbnails will work for filmstrip thumbnails.

Filmstrip thumbnails will only be visible in the Thumbnail field on an entity if a regular thumbnail image is also uploaded to the entity. The standard thumbnail is displayed by default as the poster frame. Then, on hover, the filmstrip thumbnail is displayed and updated based on your horizontal cursor position for scrubbing. On mouseout, the default thumbnail is displayed again as the poster frame.

The url for a filmstrip thumbnail on an entity is available by querying for the filmstrip_image field.

• string entity_type (required)
  The entity type to link the filmstrip thumbnail to (in CamelCase format). Example: MocapTake
• int entity_id (required)
  The id of the specific entity to link the filmstrip thumbnail to. Example: 123.
• string path (required)
  The full path to the local filmstrip thumbnail file to upload. Example: /path/to/my/filmstrip/thumb.png

• int id of the Attachment entity that was created for the image if the filmstrip thumbnail was uploaded successfully. An error is raised if not.

# ----------------------------------------------
# Upload Filmstrip Thumbnail
# ----------------------------------------------
version_id = 27
filmstrip_thumbnail = '/data/show/ne2/100_110/anim/01.mlk-02b_filmstrip.jpg'
result = sg.upload_filmstrip_thumbnail("Version", version_id, filmstrip_thumbnail)
print result

example output:

 87 

Binary download_attachment(int entity_id)

Returns binary content of Attachment entity with specified id.

• int entity_id (required)
  The id of the Attachment to download.

• binary content of the Attachment entity.

# ----------------------------------------------
# Download Attachment
# ----------------------------------------------
 attachment_id = 12
 quicktime_file = sg.download_attachment(attachment_id)

example output:

 None 

(requires Shotgun server >= v3.2.0 and Python API >= v3.0.9_beta1)

dict work_schedule_read(string start_date, string end_date[, dict project, dict user])

Get the work day rules for a given date range.

• string start_date (required)
  Start date of date range. Example: 2012-02-01
• string end_date (required)
  End date of date range. Example: 2012-02-03
• dict project Project entity to query WorkDayRules for. Example: {'type':'Project', 'id':3}
• dict user HumanUser entity to query WorkDayRules for. Example: {'type':'HumanUser', 'id':21}

• dict containing key/value pairs for each date between the start_date and end dates. The key is the date. The value is a dict with key/value pairs for each date. These pairs include the keys:
• description: the description entered into the work day rule exception if applicable.
• reason: one of six options:
  • STUDIO_WORK_WEEK: standard studio schedule applies
  • STUDIO_EXCEPTION: studio-wide exception applies
  • PROJECT_WORK_WEEK: standard project schedule applies
  • PROJECT_EXCEPTION: project-specific exception applies
  • USER_WORK_WEEK: standard user work week applies
  • USER_EXCEPTION: user-specific exception applies

# ----------------------------------------------
# Lookup Christmas Work Week for Studio
# ----------------------------------------------
start_date = '2012-12-24'
end_date = '2012-12-28'
result = sg.work_schedule_read(start_date, end_date)
pprint(result)

example output:

 {'2012-12-24': {'description': 'Christmas Eve',
                'reason': 'STUDIO_EXCEPTION',
                'working': False},
 '2012-12-25': {'description': 'Christmas',
                'reason': 'STUDIO_EXCEPTION',
                'working': False},
 '2012-12-26': {'description': None,
                'reason': 'STUDIO_WORK_WEEK',
                'working': True},
 '2012-12-27': {'description': None,
                'reason': 'STUDIO_WORK_WEEK',
                'working': True},
 '2012-12-28': {'description': None,
                'reason': 'STUDIO_WORK_WEEK',
                'working': True}} 

(requires Shotgun server >= v3.2.0 and Python API >= v3.0.9_beta1)

dict work_schedule_update(string date, bool working[, string description, dict project, dict user, string recalculate_field])

Update the work schedule for a given date. If neither project nor user are passed, the studio work schedule will be updated. project and user can only be used separately.

• string date (required)
  Date of WorkDayRule to update.. Example: 2012-12-31
• bool working (required)
  Whether it's a working day or not. Example: False
• string description Reason for time off or on. Example: New Year's Eve
• dict project Project entity to assign the rule to. Cannot be used with user parameter. Example: {'type':'Project', 'id':3}
• dict user HumanUser entity to assign the rule to. Cannot be used with project parameter. Example: {'type':'HumanUser', 'id':21}
• string recalculate_field Choose the schedule field that will be recalculated on Tasks when they are affected by a change in working schedule. Valid options are due_date or duration. Defaults to the setting defined in the Site Preferences. Example: due_date

• dict containing key/value pairs for each value of the work day rule created (date, description, project, user, working).

# ----------------------------------------------
# Add New Year's Eve as a Studio holiday
# ----------------------------------------------
date = '2012-12-31'
working = False
description = "New Year's Eve"
result = sg.work_schedule_update (date, working, description=description, project=None, user=None, recalculate_field=None)
pprint(result)

example output:

{'date': '2012-12-31',
 'description': "New Year's Eve",
 'project': None,
 'user': None,
 'working': False}

list schema_read()

Returns properties for all fields for all entities.

• none

• dict A (nested) dict object containing a key/value pair for all fields of all entity types. Properties that are 'editable': True, can be updated using the schema_field_update method.

# ----------------------------------------------
# Get full Shotgun schema
# ----------------------------------------------
result = sg.schema_read()
pprint(result)

example output (edited for brevity):

 {'ActionMenuItem': {'entity_type': {'data_type': {'editable': False, 'value': 'text'},  
                                      'description': {'editable': True, 'value': ''},  
                                      'editable': {'editable': False, 'value': True},  
                                      'entity_type': {'editable': False, 'value': 'ActionMenuItem'},  
                                      'mandatory': {'editable': False, 'value': False},  
                                      'name': {'editable': True, 'value': 'Entity Type'},  
                                      'properties': {'default_value': {'editable': False, 'value': None},  
                                                     'summary_default': {'editable': False, 'value': 'none'}}},  
                      'id': {'data_type': {'editable': False, 'value': 'number'},  
                             'description': {'editable': True, 'value': ''},  
                             'editable': {'editable': False, 'value': False},  
                             'entity_type': {'editable': False, 'value': 'ActionMenuItem'},  
                             'mandatory': {'editable': False, 'value': False},  
                             'name': {'editable': True, 'value': 'Id'},  
                             'properties': {'default_value': {'editable': False, 'value': None},  
                                            'summary_default': {'editable': False, 'value': 'none'}}},  
  ...  
  ...  
  ...  
  'ApiUser': {'created_at': {'data_type': {'editable': False, 'value': 'date_time'},  
              'description': {'editable': True, 'value': ''},  
              'editable': {'editable': False, 'value': True},  
              'entity_type': {'editable': False, 'value': 'ApiUser'},  
              'mandatory': {'editable': False, 'value': False},  
              'name': {'editable': True, 'value': 'Date Created'},  
              'properties': {'default_value': {'editable': False, 'value': None},  
                             'summary_default': {'editable': True, 'value': 'none'}}},  
 ...  
 ...  
 ...  
 } 

list schema_field_read(string entity_type, string field_name)

Returns properties for a specified field (or all fields if none is specified) for the specified entity.

• string entity_type (required)
  The entity type to find (in CamelCase format). Example: HumanUser.
• string field_name (optional)
  Specifies the field you want. If this parameter is excluded, data structures of *all* fields will be returned.

• dict a (nested) dict object containing a key/value pair for the field_name specified and its properties, or if no field_name is specified, for all the fields of the entity_type. Properties that are 'editable': True, can be updated using the schema_field_update method.

# ----------------------------------------------
# Get schema for the 'shots' field on Asset
# ----------------------------------------------
result = sg.schema_field_read('Asset','shots')
pprint(result)

example output:

 {'shots': {'data_type': {'editable': False, 'value': 'multi_entity'},  
            'description': {'editable': True, 'value': ''},  
            'editable': {'editable': False, 'value': True},  
            'entity_type': {'editable': False, 'value': 'Asset'},  
            'mandatory': {'editable': False, 'value': False},  
            'name': {'editable': True, 'value': 'Shots'},  
            'properties': {'default_value': {'editable': False,  
                                             'value': None},  
                           'summary_default': {'editable': True,  
                                               'value': 'none'},  
                           'valid_types': {'editable': True,  
                                           'value': ['Shot']}}}} 

Unlike how the results of a find() can be pumped into a create() or update(), the results of schema_field_read() are not compatible with the format used for schema_field_create() or schema_field_update(). If you need to pipe the results from schema_field_read() into a schema_field_create() or schema_field_update(), you will need to reformat the data in your script.

list schema_entity_read()

Returns all active entities and their display names.

• dict a (nested) dict object containing key/value containing the names and display names for all active entities.

# ----------------------------------------------
# Get all active entities and their display names
# ----------------------------------------------
result = sg.schema_entity_read()
pprint(result)

example output:

 {'ApiUser': {'name': {'editable': False, 'value': 'Script'}},  
  'Asset': {'name': {'editable': False, 'value': 'Asset'}},  
  'AssetLibrary': {'name': {'editable': False, 'value': 'Asset Library'}},  
  'Camera': {'name': {'editable': False, 'value': 'Camera'}},  
  'Candidate': {'name': {'editable': False, 'value': 'Candidate'}},  
  'CustomEntity01': {'name': {'editable': False, 'value': 'Picture'}},  
  'CustomEntity02': {'name': {'editable': False, 'value': 'Client'}},  
  'CustomEntity05': {'name': {'editable': False, 'value': 'Software'}},  
  'CustomEntity07': {'name': {'editable': False, 'value': 'Hardware'}},  
  'Cut': {'name': {'editable': False, 'value': 'Cut'}},  
  'CutItem': {'name': {'editable': False, 'value': 'Cut Item'}},  
  'DeliveryTarget': {'name': {'editable': False, 'value': 'Delivery Target'}},  
  'Element': {'name': {'editable': False, 'value': 'Element'}},  
  'EventLogEntry': {'name': {'editable': False, 'value': 'Event Log Entry'}},  
  'Group': {'name': {'editable': False, 'value': 'Group'}},  
  'HumanUser': {'name': {'editable': False, 'value': 'Person'}},  
  'Launch': {'name': {'editable': False, 'value': 'Launch'}},  
  'MocapPass': {'name': {'editable': False, 'value': 'Mocap Pass'}},  
  'MocapSetup': {'name': {'editable': False, 'value': 'Mocap Setup'}},  
  'MocapTake': {'name': {'editable': False, 'value': 'Mocap Take'}},  
  'MocapTakeRange': {'name': {'editable': False, 'value': 'Mocap Take Range'}},  
  'Note': {'name': {'editable': False, 'value': 'Note'}},  
  'Performer': {'name': {'editable': False, 'value': 'Performer'}},  
  'PhysicalAsset': {'name': {'editable': False, 'value': 'Physical Asset'}},  
  'Project': {'name': {'editable': False, 'value': 'Project'}},  
  'PublishEvent': {'name': {'editable': False, 'value': 'Publish Event'}},  
  'Release': {'name': {'editable': False, 'value': 'Release'}},  
  'Reply': {'name': {'editable': False, 'value': 'Reply'}},  
  'Review': {'name': {'editable': False, 'value': 'Review'}},  
  'ReviewItem': {'name': {'editable': False, 'value': 'Review Item'}},  
  'Revision': {'name': {'editable': False, 'value': 'Revision'}},  
  'Routine': {'name': {'editable': False, 'value': 'Mocap Routine'}},  
  'Scene': {'name': {'editable': False, 'value': 'Scene'}},  
  'Sequence': {'name': {'editable': False, 'value': 'Sequence'}},  
  'ShootDay': {'name': {'editable': False, 'value': 'Shoot Day'}},  
  'Shot': {'name': {'editable': False, 'value': 'Shot'}},  
  'Slate': {'name': {'editable': False, 'value': 'Slate'}},  
  'Task': {'name': {'editable': False, 'value': 'Task'}},  
  'TaskTemplate': {'name': {'editable': False, 'value': 'Task Template'}},  
  'TemerityNode': {'name': {'editable': False, 'value': 'Temerity Node'}},  
  'Ticket': {'name': {'editable': False, 'value': 'Ticket'}},  
  'TimeLog': {'name': {'editable': False, 'value': 'Time Log'}},  
  'Tool': {'name': {'editable': False, 'value': 'Tool'}},  
  'Version': {'name': {'editable': False, 'value': 'Version'}}}  

boolean schema_field_delete(string entity_type, string field_name)

Will delete the field specified for the entity specified.

• string entity_type (required)
  The entity type to find (in CamelCase format). Example: HumanUser.
• string field_name (required)
  The specific field to be deleted, must be the system name.

• boolean True if successful.

# ----------------------------------------------
# Delete sg_temp_field on Asset
# ----------------------------------------------
result = sg.schema_field_delete("Asset", "sg_temp_field")
pprint(result)

example output:

 True 

boolean schema_field_update(string entity_type, string field_name, dict properties)

Updates the specified properties for the specified field on the specified entity. Note that although the property name may be the key in a nested dictionary, like 'summary_default', it is treated no differently than keys that are up one level, like 'description'. See example output of schema_field_read().

• string entity_type (required)
  The entity type to find (in CamelCase format). Example: HumanUser.
• string field_name (required)
  Specifies the field you want.
• dict properties (required)
  A dictionary with key:value pairs where the key is the property to be updated and the value is the new value.

• boolean True if successful.

# ----------------------------------------------------------
#  Update the display name, summary_defalut, and description
# ----------------------------------------------------------
properties = {"name":"Test Number Field Renamed", "summary_default":"sum", "description":"this is only a test"}
result = sg.schema_field_update("Asset", "sg_test_number", properties)
pprint(result)

example output:

 True 

string schema_field_create(string entity_type, string field_type, string display_name, dict properties)

Create a field of specified type on specified Asset.

• `string` **entity_type** (*required*)
  The entity type (in CamelCase format). Example: HumanUser.
  

• `string` **field_type** (*required*)
  The type of field you want to create.  Valid values are:
    *   checkbox
    *   currency
    *   date
    *   date_time
    *   duration
    *   entity
    *   float
    *   list
    *   number
    *   percent
    *   status_list
    *   text
    *   timecode
    *   url
  

• `string` **display_name** (*required*)
  Specifies the display name of the field you are creating.  The system name will be created from this display name and returned upon successful creation.
  

• `dict` **properties** (*optional*)
  Use this to specify other field properties such as the 'description' or 'summary_default'.
  

• string the Shotgun system name for the new field.

# ------------------------------------------------------------
#  Create a text field through the api
# ------------------------------------------------------------
properties = {"summary_default":"count", "description":"Complexity breakdown of Asset"}
result = sg.schema_field_create("Asset", "text", "Complexity", properties)
pprint(result)

example output:

 'sg_complexity'

None set_session_uuid(string session_uuid)

Sets the browser session_uuid in the current Shotgun API instance. When this is set, any events generated by the API will include the session_uuid value on the corresponding EventLogEntries. If there is a current browser session open with this session_uuid, the browser will display updates for these events.

• string session_uuid (required)
  The uuid of the browser session to be updated. Example: '5a1d49b0-0c69-11e0-a24c-003048d17544'.

• None

# ----------------------------------------------
# Set the browser session_uuid
# ----------------------------------------------
sg.set_session_uuid("5a1d49b0-0c69-11e0-a24c-003048d17544")