Skip to content

Reference: Methods

Jump to bottom
Samuel Waugh edited this page Jun 8, 2016 · 91 revisions

Available API methods

Shotgun()

Description

dict Shotgun(string base_url, string script_name, string api_key, bool convert_datetimes_to_utc, string http_proxy, bool ensure_ascii, bool connect, string ca_certs, string login, string password, string sudo_as_login, string session_token, string auth_token )

Constructor to create a new Shotgun instance.

Parameters

  • 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 ).
  • string api_key (default=None)
    The api_key this script will use for communicating with the Shotgun server.
  • 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:[email protected]:8888.
  • bool connect (default=True)
    If True, connect to the server. Only used for testing.
  • string ca_certs (default=None)
    Optional path to an external SSL certificates file. By default, the Shotgun API will use its own built-in certificates file which stores root certificates for the most common Certificate Authorities (CAs). If you are using a corporate or internal CA, or are packaging an application into an executable, it may be necessary to point to your own certificates file. You can do this by passing in the full path to the file via this parameter or by setting the environment variable SHOTGUN_API_CACERTS. In the case both are set, this parameter will take precedence.
  • string login (default=None)
    The login to use to authenticate to the server. If login is provided, then password must be as well and neither script_name nor api_key can be provided.
  • string password (default=None)
    The password for the login to use to authenticate to the server. If password is provided, then login must be as well and neither script_name nor api_key can be provided.
  • string sudo_as_login (default=None)
    A user login string for the user whose permissions will be applied to all actions and who will be logged as the user performing all actions. Note that logged events will have an additional extra meta-data parameter 'sudo_actual_user' indicating the script or user that actually authenticated.
  • string session_token (default=None)
    A session token to use to authenticate to the server. If session_token is provided, neither login/ password nor script_name/api_key should be provided. Session tokens can be generated via the get_session_token() method. Session based authentication requires Shotgun server version 5.3.0 or above.
  • string auth_token (default=None)
    Authentication token required to authenticate to a server with two-factor authentication turned on. If auth_token is provided, then login and password must be as well and neither script_name nor api_key can be provided. Note that these tokens can be short lived so a session is established right away if an auth_token is provided. A MissingTwoFactorAuthenticationFault will be raised if the auth_token is invalid.
    2FA support is currently in beta and requires Shotgun server version v6.1.0+. [Contact support](mailto://[email protected]?subject="Inquiry about 2FA support in Shotgun") for more info.

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.

Usage Example

from shotgun import Shotgun
SERVER_PATH = 'https://example.shotgunstudio.com' # change this to http if you have a local install not using HTTPS
SCRIPT_USER = 'trigger_script'
SCRIPT_KEY = '2350acafb1826c92e4121986fe663043b77bb8da'
sg = Shotgun(SERVER_PATH, SCRIPT_USER, SCRIPT_KEY)

find()

Description

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

Find entities

Parameters

  • 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.
  • 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.
  • boolean include_archived_projects (default=True) Return entities whose projects have been retired.
    • By default find() does not exclude entities whose projects are retired.

Returns

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

Usage Example #1

# ----------------------------------------------
# Find 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"
else:
    print "Found %d Assets" % (len(assets))
    print 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'}]

Usage Example #2: deep linking

You can drill through single entity links to filter on fields or display linked fields. This is often called "deep linking" or using "dot syntax".
See these docs for more info

# ----------------------------------------------
# Find all Versions linked to the Animation pipeline step
# ----------------------------------------------

fields = ['id', 'code']
pipeline_step_id = 2 # Animation Step ID
project_id = 4 # Demo Project

# you can drill through single-entity link fields
filters = [
    ['project','is', {'type': 'Project','id': project_id}],
    ['sg_task.Task.step.Step.id', 'is', pipeline_step_id]
    ]

versions = sg.find("Version", filters, fields)

if len(versions) < 1:
    print "couldn't find any Versions"
else:
    print "Found %d Versions" % (len(versions))
    print versions

example output:

 Found 4 Versions  
 [{'code': 'scene_010_anim_v001', 'id': 42, 'type': 'Version'},  
  {'code': 'scene_010_anim_v002', 'id': 134, 'type': 'Version'},  
  {'code': 'bird_v001', 'id': 137, 'type': 'Version'},  
  {'code': 'birdAltBlue_v002', 'id': 236, 'type': 'Version'}]

find_one()

Description

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

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.

Parameters

  • 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.
  • boolean include_archived_projects (default=True) Return entities whose projects have been retired.
    • By default find_one() does not exclude entities whose projects are retired.

Returns

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

Usage Example

# ----------------------------------------------
# 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'}

summarize()

Description

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.

Parameters

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

Returns

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

Usage Example: Count all Assets for a Project

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.

Usage Example: Count all Assets for a Project, grouped by sg_asset_type

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.

Usage Example: Count all Tasks for a Sequence and find the latest due_date.

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.

Usage Example: Count all Tasks for a Sequence, find the latest due_date and group by Shot.

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.

Usage Example: Count all Tasks for a Sequence, find the latest due_date, group by Shot and Pipeline Step.

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.

text_search()

Description

dict text_search(str text, dict entity_types, list project_ids=None, int limit=None)

Searches across the specified entity types for the given text.

This method can be used to implement auto completion or a Shotgun global search. The method requires a text input phrase that is at least three characters long, or an exception will be raised.

Several ways to limit the results of the query are available:

  • Using the project_ids parameter, you can provide a list of project ids to search across. Leaving this at its default value of None will search across all Shotgun data.

  • You need to define which subset of entity types to search using the entity_types parameter. Each of these entity types can be associated with a filter query to further reduce the list of matches. The filter list is using the standard filter syntax used by for example the find() method. For example - to constrain the search to all shots but character assets only:

{ "Asset": [["sg_asset_type", "is", "character"]],
  "Shot":  []  
}

Parameters

  • str text (required) Text to search for. This must be at least three characters long, or an exception will be raised.
  • dict entity_types (required) Dictionary to specify which entity types to search. See above for usage examples.
  • list project_ids (optional) List of projects to search. By default, all projects will be searched.
  • int limit (optional) Specify the maximum number of matches to return.

Returns

A dictionary with keys terms and matches will be returned:

{'matches': [{'id': 734,
              'type': 'Asset',
              'name': 'Bunny',
              'project_id': 65,                      
              'image': 'https://...',
              'links': ['', ''],
              'status': 'fin'},

              {'id': 558,
               'type': 'Task'
               'name': 'FX',
               'project_id': 65,
               'image': 'https://...',
               'links': ['Shot', 'bunny_010_0010'],
               'status': 'fin'}],
    'terms': ['bunny']}

The links field will contain information about any linked entity. This is useful when for example presenting tasks and you want to display what shot or asset the task is associated with.

activity_stream_read()

Description

dict activity_stream_read(str entity_type, int entity_id, dict entity_fields=None, int min_id=None, int max_id=None, int limit=None)

Retrieves activity stream data from Shotgun. This data corresponds to the data that is displayed in the Activity tab for an entity in the Shotgun Web UI.

By using the entity_fields parameter, you can extend the returned data to include additional fields. If for example you wanted to return the asset type for all assets and the linked sequence for all Shots, pass the following entity_fields:

{"Shot": ["sg_sequence"], "Asset": ["sg_asset_type"]}

Deep queries can be used in this syntax if you want to traverse into connected data.

Parameters

  • str entity_type (required) Entity type to retrieve activity stream for.
  • int entity_id (required) Entity id to retrieve activity stream for.
  • list entity_fields (optional) List of additional fields to include. See above for details
  • int max_id (optional) Do not retrieve ids greater than this id. This is useful when implementing paging.
  • int min_id (optional) Do not retrieve ids lesser than this id. This is useful when implementing caching of the event stream data and you want to "top up" an existing cache.
  • int limit (optional) Specify the maximum number of matches to return. If not specified, the system default will be used.

Returns

A complex data structure on the following form will be returned from Shotgun:

{'earliest_update_id': 50,
 'entity_id': 65,
 'entity_type': 'Project',
 'latest_update_id': 79,
 'updates': [{'created_at': '2015-07-15 11:06:55 UTC',
              'created_by': {'id': 38,
                             'image': '6641',
                             'name': 'John Smith',
                             'status': 'act',
                             'type': 'HumanUser'},
              'id': 79,
              'meta': {'entity_id': 6004,
                       'entity_type': 'Version',
                       'type': 'new_entity'},
              'primary_entity': {'id': 6004,
                                 'name': 'Review_turntable_v2',
                                 'status': 'rev',
                                 'type': 'Version'},
              'read': False,
              'update_type': 'create'},        
]}

The main payload of the return data can be found inside the updates key, containing a list of dictionaries. This list is always returned in descending date order. Each item may contain different fields depending on their update type. The primary_entity key represents the main Shotgun entity that is associated with the update. By default, this entity is returned with a set of standard fields but this list can be extended using the entity_fields parameter.

note_thread_read()

Description

list note_thread_read(int note_id, dict entity_fields=None)

Returns the full conversation for a given note, including replies and attachments.

If you wish to include additional fields beyond the ones that are returned by default, you can specify these in an entity_fields dictionary. This dictonary should be keyed by entity type and each key should contain a list of fields to retrieve, for example:

{ "Note":       ["created_by.HumanUser.image",
                 "addressings_to",
                 "playlist",
                 "user" ],
  "Reply":      ["content"],
  "Attachment": ["filmstrip_image",
                "local_storage",
                "this_file",
                "image"]
}

Parameters

  • int note_id (required) The id for the note to be retrieved
  • list entity_fields (optional) Additional fields to retrieve as part of the request. See above for details.

Returns

Returns a complex data structure on the following form:

[{'content': 'Please add more awesomeness to the color grading.',
  'created_at': '2015-07-14 21:33:28 UTC',
  'created_by': {'id': 38,
                 'name': 'John Pink',
                 'status': 'act',
                 'type': 'HumanUser',
                 'valid': 'valid'},
  'id': 6013,
  'type': 'Note'},
 {'created_at': '2015-07-14 21:33:32 UTC',
  'created_by': {'id': 38,
                 'name': 'John Pink',
                 'status': 'act',
                 'type': 'HumanUser',
                 'valid': 'valid'},
  'id': 159,
  'type': 'Attachment'},
 {'content': 'More awesomeness added',
  'created_at': '2015-07-14 21:54:51 UTC',
  'id': 5,
  'type': 'Reply',
  'user': {'id': 38,
           'name': 'David Blue',
           'status': 'act',
           'type': 'HumanUser',
           'valid': 'valid'}}]

The list is returned in descending chronological order.

follow()

Description

dict follow(dict user, dict entity)

Adds the entity to the user's followed entities (or does nothing if the user is already following the entity)

Parameters

  • dict user (required) User entity to follow the entity
  • dict entity (required) Entity to be followed

Returns

  • dict with 'followed'=true, and dicts for the 'user' and 'entity' that were passed in

Usage Example

# ----------------------------------------------
# Have user follow a shot
# ----------------------------------------------
human = {'id': 32, 'type': 'HumanUser'}
shot = {'id': 860, 'type': 'Shot'}
sg.follow(human, shot)

example output:

{'entity': {'id': 860, 'type': 'Shot'},'followed': True, 'user': {'id': 32, 'type': 'HumanUser'}}
# followers()

Description

list followers(dict entity)

Gets all followers of the entity.

Parameters

  • dict entity (required) Find all followers of this entity

Returns

  • list of dicts for all the users following the entity

Usage Example

# ----------------------------------------------
# Find followers for a shot
# ----------------------------------------------
shot = {'id': 860, 'type': 'Shot'}
sg.followers(shot)

example output:

[{'id': 32,
  'name': 'Admin 2',
  'status': 'act',
  'type': 'HumanUser',
  'uuid': '9b31b966-0302-11df-b8e3-00304898dbee',
  'valid': 'valid'}]

unfollow()

Description

dict unfollow(dict user, dict entity)

Removes entity from the user's followed entities (or does nothing if the user is not following the entity)

Parameters

  • dict user (required) User entity to unfollow the entity
  • dict entity (required) Entity to be unfollowed

Returns

  • dict with 'unfollowed'=true, and dicts for the 'user' and 'entity' that were passed in

Usage Example

# ----------------------------------------------
# Unfollow shot
# ----------------------------------------------
shot = {'id': 860, 'type': 'Shot'}
human = {'id':32, 'type': 'HumanUser'}
sg.unfollow(human, shot)

example output:

{'entity': {'id': 860, 'type': 'Shot'},
 'unfollowed': True,
 'user': {'id': 32, 'type': 'HumanUser'}}

create()

Description

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.

Parameters

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

Returns

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

Usage Example

# ----------------------------------------------
# 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',
    'sg_status_list':'rev',
    'entity': {'type':'Asset','id':123},
    'user': {'type':'HumanUser','id':'165'},
    }
version = sg.create("Version",data)
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',  
 }

update()

Description

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

Update specified entity columns with paired values.

Parameters

  • 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. This method does not restrict the updating of fields hidden by the Web UI via the Project Tracking Settings panel.
  • dict multi_entity_update_modes (optional)
    Dictionary of what update mode to use when updating a multi-entity link field. The keys in the dict are the fields to set the mode for and the values from the dict are one of set, add, or remove. The default behaviour if mode is not specified for a field is set. For example, on the Sequence entity, to append to the shots field and remove from the assets field, you would specify:
    • multi_entity_update_modes={"shots":"add", "assets":"remove"}

Returns

  • dict entity object with updated values.

Usage Example

# ----------------------------------------------
# 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'}]  
 }

delete()

Description

boolean delete(string entity_type, int entity_id)

Retires the entity matching entity_type and entity_id.

Parameters

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

Returns

  • boolean True if entity was deleted successfully.

Usage Example

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

example output:

True

revive()

Description

boolean revive(string entity_type, int entity_id)

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

Parameters

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

Returns

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

Usage Example

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

example output:

 True

batch()

Description

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.

Parameters

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

Returns

  • 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

Usage Examples

# ----------------------------------------------
# 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]

upload()

Description

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.

Parameters

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

Returns

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

Usage Example

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

upload_thumbnail()

Description

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.

Supported image file types include .jpg and .png (preferred).

Thumbnail fields will also accept .gif, .tif, .tiff, .bmp, .exr, .dpx, and .tga.

Parameters

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

Returns

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

Usage Example

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

upload_filmstrip_thumbnail()

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

Description

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.

Parameters

  • 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

Returns

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

Usage Example

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

share_thumbnail()

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

Description

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.

Please note that when sharing a filmstrip thumbnail it is required to have a static thumbnail in place before the filmstrip will be displayed in the Shotgun web UI.

Parameters

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

Returns

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

Usage Example: Upload and share thumbnail

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

Usage Example: Share thumbnail from existing entity

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

download_attachment()

updated in v3.0.14

Description

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 an Attachment entity

Parameters

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

Returns

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

Usage Example

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

work_schedule_read()

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

Description

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

Get the work day rules for a given date range.

Parameters

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

Returns

  • 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

Usage Example

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

work_schedule_update()

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

Description

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.

Parameters

  • 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

Returns

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

Usage Example

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

authenticate_human_user()

Description

dict or None authenticate_human_user(string user_login, string user_password)

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

Parameters

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

Returns

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

Usage Example

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

example output:

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

update_project_last_accessed()

Description

None update_project_last_accessed(dict project[, dict user])

Update a Project's last_accessed_by_current_user field.

Parameters

  • dict project (required)
    Project entity to update the last_accessed_by_current_user field for.
  • dict user
    HumanUser entity to update the field for. This field is optional if using the sudo_as_login or login and password parameters when instantiating the Shotgun() object. In these cases, if user is not provided, the sudo_as_login value or login value from the current instance will be used instead.

Returns

  • None

Usage Example

# ----------------------------------------------
# Update Project's last accessed by user value
# ----------------------------------------------
my_project = {'type': 'Project', 'id': 123}
jimmy_rock = {'type': 'HumanUser', 'id': 42}
result = sg.last_accessed_by_current_user(project=my_project, user=jimmy_rock)
pprint.pprint(result)

example output:

None

schema_read()

Description

list schema_read(dict project_entity)

Returns properties for all fields for all entities.

Parameters

  • dict project_entity (optional) Project entity specifying which project to return the listing for. If omitted or set to None, per-project visibility settings are not taken into consideration and the global list is returned. Example: {'type': 'Project', 'id': 3}.

Returns

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

Notes

  • Without a specified project, everything is reported as visible.

Usage Example

With no project specified

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

example output:

 {'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'}},  
                                      ‘visible’: {'editable': False, 'value': True}},
                      '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'}}},  
                             ‘visible’: {'editable': False, 'value': True}},
  ...  
  ...  
  ...  
  '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'}},  
              ‘visible’: {'editable': False, 'value': True}},
 ...  
 ...  
 ...  
 }

With a project specified

# -------------------------------------------------------------------------
# Get full Shotgun schema
#
# This example assumes that Asset is hidden in the project while Version is
# visible.
# -------------------------------------------------------------------------
result = sg.schema_read({'type': 'Project', 'id': 3})
pprint(result)

example output:

 {
  (... snipped for brevity...)
  'Asset': {'created_at': {'data_type': {'editable': False, 'value': 'date_time'}},
              'description': {'editable': True, 'value': ''},
              'editable': {'editable': False, 'value': True},
              'entity_type': {'editable': False, 'value': 'Asset'},
              'mandatory': {'editable': False, 'value': False},
              'name': {'editable': True, 'value': 'Date Created'},
              'properties': {'default_value': {'editable': False, 'value': None},
                             'summary_default': {'editable': True, 'value': 'none'}},
              ‘visible’: {'editable': False, 'value': False}},
 (... snipped for brevity...)
 }

schema_field_read()

Description

list schema_field_read(string entity_type, string field_name, dict project_entity)

Returns properties for a specified field (or all fields if none is specified) for the specified entity. If the project is not specified, all fields are reported as visible.

Parameters

  • 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 project_entity (optional) Project entity specifying which project to return the listing for. If omitted or set to None, per-project visibility settings are not taken into consideration and the global list is returned. Example: {'type': 'Project', 'id': 3}.

Returns

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

Notes

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

  • Without a specified project, everything is reported as visible.

Usage Examples

With no project specified

# ----------------------------------------------
# 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']}},
            'visible': {'editable': false, 'value': True}}}

With a project specified

# ----------------------------------------------
# Get schema for the 'shots' field on Asset for
# given project.
#
# Assuming shots field is hidden for the project
# Notice
# ----------------------------------------------
result = sg.schema_field_read('Asset','shots',{'type': 'Project', 'id': 3})
pprint(result)

example output:

 {'shots': {'data_type': {'editable': False, 'value': 'multi_entity'},
            (...output snipped for brevity...)
            'visible': {'editable': false, 'value': False}}
 }

schema_entity_read()

Description

list schema_entity_read( dict project_entity )

Returns all active entity types, their display names and their visibility. If the project parameter is specified, the schema visibility for the given project is being returned. If the project parameter is omitted or set to None, a full listing is returned where per project entity type visibility settings are not considered.

Parameters

  • dict project_entity (optional) Project entity specifying which project to return the listing for. If omitted or set to None, per-project visibility settings are not taken into consideration and the global list is returned. Example: {'type': 'Project', 'id': 3}.

Returns

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

Notes

  • Without a specified project, everything is reported as visible.

Usage Examples

With no project specified

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

example output:

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

With a project specified

# ----------------------------------------------------------------------------
# Get all active entities, their display names and their visibility for given
# project.
#
# This example assumes that Asset is hidden in the project while Version is
# visible.
# ----------------------------------------------------------------------------
result = sg.schema_entity_read({'type': 'Project', 'id': 3})
pprint(result)

example output:

 {
  (...output snipped for brevity...)
  'Asset': {'name': {'editable': False, 'value': 'Asset'}, {'visible': {'editable': False, 'value': False}}},
  'Version': {'name': {'editable': False, 'value': 'Version'}, {'visible': {'editable': False, 'value': True}}}
  (...output snipped for brevity...)
 }

schema_field_delete()

Description

boolean schema_field_delete(string entity_type, string field_name)

Will delete the field specified for the entity specified.

Parameters

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

Returns

  • boolean True if successful.

Usage Example

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

example output:

 True

schema_field_update()

Description

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().

Parameters

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

Returns

  • boolean True if successful.

Usage Example

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

schema_field_create()

Description

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

Create a field of specified type on specified Asset.

Parameters

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

Returns

  • string the Shotgun system name for the new field.

Usage Example

# ------------------------------------------------------------
#  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'

set_session_uuid()

Description

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.

Parameters

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

Returns

  • None

Usage Example

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

add_user_agent()

(requires Python API >= v3.0.10)

Description

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.

Parameters

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

Returns

  • None

Usage Example

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

reset_user_agent()

(requires Python API >= v3.0.10)

Description

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.

Parameters

  • none

Returns

  • None

Usage Example

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

get_session_token()

(requires Python API >= v3.0.19)

Description

str get_session_token()

Returns the session token associated with this API session. The session token identifies a particular user and can be used to instantiate new instances of the Shotgun API via the session_token constructor parameter.

Parameters

  • none

Returns

  • str containing a session token

Usage Example

p = sg.get_session_token()
print p

example output:

3de782b3f0ba03da2d68fa7ba39ca2dd
Clone this wiki locally