Available API methods

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

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.

A NOTE ABOUT PROXY CONNECTIONS: If you are using Python <= v2.6.2, HTTPS connections through a proxy server will not work due to a bug in the urllib2.py library (see http://bugs.python.org/issue1424152). This will affect upload and download-related methods in the Shotgun API (eg. upload(), upload_thumbnail(), upload_filmstrip_thumbnail, and download_attachment()). Normal CRUD methods for passing JSON data should still work fine. If you cannot upgrade your Python installation, you can see the patch merged into Python v2.6.3 (http://hg.python.org/cpython/rev/0f57b30a152f/) and try and hack it into your installation but YMMV. For older versions of Python there are other patches that were proposed in the bug report that may help you as well.

• 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 conditions used to filter the find query. You can find the reference for filter values here.
• 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 conditions used to filter the find query. You can find the reference for filter values here.
• 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 summarize(string entity_type, list filters, list summary_fields[, string filter_operator, list grouping)

Summarize column data returned by a query. This provides the same functionality as the summaries in the UI. You can specify one or more fields to summarize, choose the summary type for each, and optionally group the results which will return summary information for each group as well as the total for the query.

• string entity_type (required)
  The entity type to summarize (in CamelCase format). Example: Asset.
• list filters (required)
  An array of conditions used to filter the find query. You can find the reference for filter values here.
• list summary_fields (required)
  A list of dictionaries with the following keys:
  • field: which field you are summarizing
  • type: the type of summary you are performing on the field. Summary types can be any of [record_count, count, sum, maximum, minimum, average, earliest, latest, percentage, status_percentage, status_list, checked, unchecked] depending on the type of field you're summarizing.
• 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.
• list grouping Optional list of dicts with the following keys:
  • field: a string indicating the field on entity_type to group results by
  • type: a string indicating the type of grouping to perform for each group. Valid types depend on the type of field you are grouping on and can be one of [exact, tens, hundreds, thousands, tensofthousands, hundredsofthousands, millions, day, week, month, quarter, year, clustered_date, oneday, fivedays, entitytype, firstletter]
  • direction: a string that sets the order to display the grouped results. Valid direction options are asc (default) and desc.

• dict object containing grouping and summaries keys.
  • grouping: (list) of dictionaries containing grouping information:
    • group_name: (str) human-readable name (aka. display name) of the value that defines the group
    • group_value: data representation of the value that defines the group
    • summaries: (dict) (see summary key)
    • groups: (for nested groups): this structure will be repeated with the same structure as defined in the top-level grouping key.
  • summaries: (dict) of key/value pairs where the key is the field name and the value is the summary value requested for that field.

summaries = sg.summarize(entity_type='Asset', 
                         filters = [['project', 'is', {'type':'Project', 'id':4}]], 
                         summary_fields=[{'field':'id', 'type':'count'}])

Result:

{'groups': [], 'summaries': {'id': 15}}

The total summary for the query is returned via the summaries dict. Each key is the field summarized and the value is the result of the summary operation for the entire result set. Note you cannot perform more than one summary on a field at a time, but you can summarize several different fields in the same call.

summaries = sg.summarize(entity_type='Asset', 
                         filters = [['project', 'is', {'type':'Project', 'id':4}]], 
                         summary_fields=[{'field':'id', 'type':'count'}],
                         grouping=[{'field':'sg_asset_type','type':'exact','direction':'asc'}])

Result:

{'groups': [{'group_name': 'Character',
             'group_value': 'Character',
             'summaries': {'id': 3}},
            {'group_name': 'Environment',
             'group_value': 'Environment',
             'summaries': {'id': 3}},
            {'group_name': 'Matte Painting',
             'group_value': 'Matte Painting',
             'summaries': {'id': 1}},
            {'group_name': 'Prop',
             'group_value': 'Prop',
             'summaries': {'id': 4}},
            {'group_name': 'Vehicle',
             'group_value': 'Vehicle',
             'summaries': {'id': 4}}],
 'summaries': {'id': 15}}

The total summary for the query is returned via the summaries dict. The summary for each group is returned within the groups dict. group_name is the display name for the group which is the human name value of the grouping. group_value is the actual value of the grouping value. This is often the same as group_name but in the case when grouping by entity, the group_name may be PuppyA and the group_value would be {'type':'Asset','id':922,'name':'PuppyA'}. summaries contains the summary calculation dict for each field requested for that group.

summaries = sg.summarize(entity_type='Task', 
                         filters = [
                            ['entity.Shot.sg_sequence', 'is', {'type':'Sequence', 'id':2}],
                            ['sg_status_list', 'is_not', 'na']], 
                         summary_fields=[{'field':'id', 'type':'count'},{'field':'due_date','type':'latest'}])

Result:

{'groups': [], 'summaries': {'due_date': '2013-07-05', 'id': 30}}

This shows that the there are 30 Tasks for Shots in the Sequence and the latest due_date of any Task is 2013-07-05.

summaries = sg.summarize(entity_type='Task', 
                         filters = [
                            ['entity.Shot.sg_sequence', 'is', {'type':'Sequence', 'id':2}],
                            ['sg_status_list', 'is_not', 'na']], 
                         summary_fields=[{'field':'id', 'type':'count'},{'field':'due_date','type':'latest'}],
                         grouping=[{'field':'entity','type':'exact','direction':'asc'}])
                         )

Result:

{'groups': [{'group_name': 'shot_010',
             'group_value': {'id': 2,
                             'name': 'shot_010',
                             'type': 'Shot',
                             'valid': 'valid'},
             'summaries': {'due_date': '2013-06-18', 'id': 10}},
            {'group_name': 'shot_020',
             'group_value': {'id': 3,
                             'name': 'shot_020',
                             'type': 'Shot',
                             'valid': 'valid'},
             'summaries': {'due_date': '2013-06-28', 'id': 10}},
            {'group_name': 'shot_030',
             'group_value': {'id': 4,
                             'name': 'shot_030',
                             'type': 'Shot',
                             'valid': 'valid'},
             'summaries': {'due_date': '2013-07-05', 'id': 10}}],
 'summaries': {'due_date': '2013-07-05', 'id': 30}}

This shows that the there are 30 Tasks for Shots in the Sequence and the latest due_date of any Task is 2013-07-05. Because the summary is grouped by entity, we can also see the summaries for each Shot returned. Each Shot has 10 Tasks and the latest due_date for each Shot. The difference between group_name and group_value is highlighted in this example as the name of the Shot is different from its value.

summaries = sg.summarize(entity_type='Task', 
                         filters = [
                            ['entity.Shot.sg_sequence', 'is', {'type':'Sequence', 'id':2}],
                            ['sg_status_list', 'is_not', 'na']], 
                         summary_fields=[{'field':'id', 'type':'count'},{'field':'due_date','type':'latest'}],
                         grouping=[{'field':'entity','type':'exact','direction':'asc'},{'field':'step','type':'exact','direction':'asc'}])

Result:

{'groups': [{'group_name': 'shot_010',
             'group_value': {'id': 2,
                             'name': 'shot_010',
                             'type': 'Shot',
                             'valid': 'valid'},
             'groups': [{'group_name': 'Client',
                         'group_value': {'id': 1,
                                         'name': 'Client',
                                         'type': 'Step',
                                         'valid': 'valid'},
                         'summaries': {'due_date': '2013-05-04', 'id': 1}},
                        {'group_name': 'Online',
                         'group_value': {'id': 2,
                                         'name': 'Online',
                                         'type': 'Step',
                                         'valid': 'valid'},
                         'summaries': {'due_date': '2013-05-05', 'id': 1}},
                        ...
                        ... truncated for brevity
                        ...
                        {'group_name': 'Comp',
                         'group_value': {'id': 8,
                                         'name': 'Comp',
                                         'type': 'Step',
                                         'valid': 'valid'},
                         'summaries': {'due_date': '2013-06-18', 'id': 1}}],
             'summaries': {'due_date': '2013-06-18', 'id': 10}},
            {'group_name': 'shot_020',
             'group_value': {'id': 3,
                             'name': 'shot_020',
                             'type': 'Shot',
                             'valid': 'valid'},
             'groups': [{'group_name': 'Client',
                         'group_value': {'id': 1,
                                         'name': 'Client',
                                         'type': 'Step',
                                         'valid': 'valid'},
                         'summaries': {'due_date': '2013-05-15', 'id': 1}},
                        {'group_name': 'Online',
                         'group_value': {'id': 2,
                                         'name': 'Online',
                                         'type': 'Step',
                                         'valid': 'valid'},
                         'summaries': {'due_date': '2013-05-16', 'id': 1}},
                        ...
                        ... truncated for brevity
                        ...
                        {'group_name': 'Comp',
                         'group_value': {'id': 8,
                                         'name': 'Comp',
                                         'type': 'Step',
                                         'valid': 'valid'},
                         'summaries': {'due_date': '2013-06-28', 'id': 1}}],
             'summaries': {'due_date': '2013-06-28', 'id': 10}},
            {'group_name': 'shot_030',
             'group_value': {'id': 4,
                             'name': 'shot_030',
                             'type': 'Shot',
                             'valid': 'valid'},
             'groups': [{'group_name': 'Client',
                         'group_value': {'id': 1,
                                         'name': 'Client',
                                         'type': 'Step',
                                         'valid': 'valid'},
                         'summaries': {'due_date': '2013-05-20', 'id': 1}},
                        {'group_name': 'Online',
                         'group_value': {'id': 2,
                                         'name': 'Online',
                                         'type': 'Step',
                                         'valid': 'valid'},
                         'summaries': {'due_date': '2013-05-21', 'id': 1}},
                        ...
                        ... truncated for brevity
                        ...
                        {'group_name': 'Comp',
                         'group_value': {'id': 8,
                                         'name': 'Comp',
                                         'type': 'Step',
                                         'valid': 'valid'},
                         'summaries': {'due_date': '2013-07-05', 'id': 1}}],
             'summaries': {'due_date': '2013-07-05', 'id': 10}}],
 'summaries': {'due_date': '2013-07-05', 'id': 30}}

Note that when grouping my more than one field, the grouping structure is repreated for each sub-group and summary values are returned for each group on each level.

dict create(string entity_type, dict data, list return_fields)

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
  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: You can un-set (aka clear) a thumbnail on an entity using the update() method and setting the 'image' field to None. This will also unset the filmstrip_thumbnail value if it is set.

• 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 

(requires Shotgun server >= v4.0.0 and Python API >= v3.0.9)

int share_thumbnail(list entities, string thumbnail_path, dict source_entity, bool filmstrip_thumbnail)

Share the thumbnail from between entities without requiring uploading the thumbnail file multiple times. You can use this in one of two ways: 1) Upload an image to set as the thumbnail on multiple entities. 2) Update multiple entities to point to an existing entity's thumbnail.

• list entities (required)
  The entities to update to point to the shared thumbnail provided in standard hash (dict) format Example: [{'type': 'Version', 'id': 123}, {'type': 'Version', 'id': 456}]
• string thumbnail_path (required if source_entity is not provided)
  The full path to the local thumbnail file to upload and share
• dict source_entity (required if thumbnail_path is not provided)
  The entity whos thumbnail will be the source for sharing
• bool filmstrip_thumbnail
  If True the filmstrip_thumbnail will be shared. If False (default), the static thumbnail will be shared.

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

thumb = '/data/show/ne2/100_110/anim/01.mlk-02b.jpg'
e = [{'type': 'Version', 'id': 123}, {'type': 'Version', 'id': 456}]
result = sg.share_thumbnail(entities=e, thumbnail_path=thumb)
print result

example output:

 4271 

e = [{'type': 'Version', 'id': 123}, {'type': 'Version', 'id': 456}]
result = sg.share_thumbnail(entities=e, source_entity={'type':'Version', 'id': 789})
print result

example output:

 4271 

updated in v3.0.14

mixed download_attachment(mixed attachment [, str file_path, int attachment_id])

Download the file associated with an Attachment entity. Supports both locally stored files as well as files on S3, or any linked content that is readable.

You must provide at least one of the following or a TypeError will be raised:

• attachment: (dict) representing an Attachment entity
• attachment: (deprecated) (int) representing the id of and Attachment entity
• attachment_id: via keyword argument (deprecated) (int) representing the id of and Attachment entity

• mixed attachment (default=False) A dict representing an Attachment entity. For backwards compatibility, this will also accept an integer which is presumed to be the id of an Attachment entity to download.
• str file_path (default=None) The complete local path to write the file to. When this is provided, the file will be written directly to disk rather than loaded into memory. This saves memory especially for large files, and is likely what you want to do anyway.
• int attachment_id (default=None) For backwards compatibility only. The id of the Attachment to download. Since we have changed the primary (first) parameter name, we include this option only for legacy scripts that may be specifying keyword args when calling this method.

• mixed If file_path is not provided, returns binary content of Attachment entity. If file_path is provided, returns file_path on success. Raises ShotgunFileDownloadError exception on failure.

# ----------------------------------------------
# Download Attachment
# ----------------------------------------------
 path = "/studio/path/to/some/file.mov
 version = sg.find_one('Version', [['id', 'is', 123]], ['sg_uploaded_movie'])
 attachment = sg.download_attachment(attachment=version['sg_uploaded_movie'], file_path=path)

(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}

dict or None authenticate_human_user(string user_login, string user_password)

Authenticate a Shotgun HumanUser. The HumanUser must be an active account.

• string user_login (required)
  The login of an active HumanUser in Shotgun.
• string user_password (required)
  The password that should correspond to the previously supplied login.

• dict or None The HumanUser object including the ID if the authentication succeeded or None if unauthorized.

# ----------------------------------------------
# Authenticate a user
# ----------------------------------------------
result = sg.authenticate_human_user('testUser', 'testPassword')
pprint.pprint(result)

example output:

{'id': 354, 'login': 'testUser', 'type': 'HumanUser'}

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")

(requires Python API >= v3.0.10)

None add_user_agent(string agent_string)

Add agent_string to the user-agent reported to the shotgun server for this connection. The default user-agent reports on the version of the api in use, but this allows tracking of additional strings in the web logs.

• string agent_string (required)
  The addtional string to be tracked. Example: 'MyApp v1.0'.

• None

# ----------------------------------------------
# Add a string to the user-agent
# ----------------------------------------------
sg.add_user_agent("MyApp v1.0")

(requires Python API >= v3.0.10)

None reset_user_agent()

Add agent_string to the user-agent reported to the shotgun server for this connection. The default user-agent reports on the version of the api in use, but this allows tracking of additional strings in the web logs.

• none

• None

# ----------------------------------------------
# Reset the user-agent to the default
# ----------------------------------------------
sg.reset_user_agent()