API Reference
shotgun
Module Attributes
The shotgun
module is a container for the Shotgun
class. There are a couple of useful attributes to note.
- shotgun_api3.shotgun.LOG = <Logger shotgun_api3 (WARNING)>
Logging instance for shotgun_api3
Provides a logging instance where log messages are sent during execution. This instance has no handler associated with it.
See also
- shotgun_api3.shotgun.NO_SSL_VALIDATION = False
Turns off hostname matching validation for SSL certificates
Sometimes there are cases where certificate validation should be disabled. For example, if you have a self-signed internal certificate that isn’t included in our certificate bundle, you may not require the added security provided by enforcing this.
Shotgun()
- class shotgun_api3.shotgun.Shotgun(base_url, script_name=None, api_key=None, convert_datetimes_to_utc=True, http_proxy=None, ensure_ascii=True, connect=True, ca_certs=None, login=None, password=None, sudo_as_login=None, session_token=None, auth_token=None)[source]
Bases:
object
Shotgun Client connection.
Initializes a new instance of the Shotgun client.
- Parameters:
base_url (str) –
http or https url of the Shotgun server. Do not include the trailing slash:
https://example.shotgunstudio.com
script_name (str) –
name of the Script entity used to authenticate to the server. If provided, then
api_key
must be as well, and neitherlogin
norpassword
can be provided.See also
api_key (str) –
API key for the provided
script_name
. Used to authenticate to the server. If provided, thenscript_name
must be as well, and neitherlogin
norpassword
can be provided.See also
convert_datetimes_to_utc (bool) – (optional) When
True
, datetime values are converted from local time to UTC time before being sent to the server. Datetimes received from the server are then converted back to local time. WhenFalse
the client should use UTC date time values. Default isTrue
.http_proxy (str) –
(optional) URL for a proxy server to use for all connections. The expected str format is
[username:password@]111.222.333.444[:8080]
. Examples:192.168.0.1 192.168.0.1:8888 joe:user@192.168.0.1:8888
connect (bool) – (optional) When
True
, as soon as theShotgun
instance is created, a connection will be made to the Shotgun server to determine the server capabilities and confirm this version of the client is compatible with the server version. This is mostly used for testing. Default isTrue
.ca_certs (str) – (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.login (str) –
The user login str to use to authenticate to the server when using user-based authentication. If provided, then
password
must be as well, and neitherscript_name
norapi_key
can be provided.See also
password (str) –
The password str to use to authenticate to the server when using user-based authentication. If provided, then
login
must be as well and neitherscript_name
norapi_key
can be provided.See Authentication for more info.
sudo_as_login (str) – A user login string for the user whose permissions will be applied to all actions. Event log entries will be generated showing this user performing all actions with an additional extra meta-data parameter
sudo_actual_user
indicating the script or user that is actually authenticated.session_token (str) –
The session token to use to authenticate to the server. This can be used as an alternative to authenticating with a script user or regular user. You can retrieve the session token by running the
get_session_token()
method.auth_token (str) –
The authentication token required to authenticate to a server with two-factor authentication turned on. If provided, then
login
andpassword
must be provided as well, and neitherscript_name
norapi_key
can be provided.Note
These tokens can be short lived so a session is established right away if an
auth_token
is provided. AMissingTwoFactorAuthenticationFault
will be raised if theauth_token
is invalid.
Note
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
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()
,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.
Shotgun Methods
The majority of functionality is contained within the Shotgun
class.
The documentation for all of the methods you’ll need in your scripts lives in here.
Connection & Authentication
Connect client to the server if it is not already connected. |
|
Close the current connection to the server. |
|
Authenticate Shotgun HumanUser. |
|
Get the session token associated with the current session. |
|
Add agent to the user-agent header. |
|
Reset user agent to the default value. |
|
Set the browser session_uuid in the current Shotgun API instance. |
|
Get API-related metadata from the Shotgun server. |
CRUD Methods
Create a new entity of the specified |
|
Find entities matching the given filters. |
|
Shortcut for |
|
Update the specified entity with the supplied data. |
|
Retire the specified entity. |
|
Revive an entity that has previously been deleted. |
|
Make a batch request of several |
|
Summarize field data returned by a query. |
|
Return the full conversation for a given note, including Replies and Attachments. |
|
Search across the specified entity types for the given text. |
|
Update a Project's |
|
Return the work day rules for a given date range. |
|
Update the work schedule for a given date. |
|
Get a subset of the site preferences. |
Working With Files
Upload a file to the specified entity. |
|
Upload a file from a local path and assign it as the thumbnail for the specified entity. |
|
Upload filmstrip thumbnail to specified entity. |
|
Download the file associated with a Shotgun Attachment. |
|
Return the URL for downloading provided Attachment. |
|
Associate a thumbnail with more than one Shotgun entity. |
Activity Stream
Retrieve activity stream data from Shotgun. |
|
Add the entity to the user's followed entities. |
|
Remove entity from the user's followed entities. |
|
Return all followers for an entity. |
|
Return all entity instances a user is following. |
Working with the Shotgun Schema and Preferences
Return all active entity types, their display names, and their visibility. |
|
Get schema for all fields on the specified entity type or just the field name specified if provided. |
|
Create a field for the specified entity type. |
|
Update the properties for the specified field on an entity. |
|
Delete the specified field from the entity type. |
|
Get the schema for all fields on all entities. |
|
Deprecated since version 3.0.0. |
|
Deprecated since version 3.0.0. |
Connection & Authentication
These methods are used for connecting and authenticating with your Flow Production Tracking server. Most of this is done automatically when you instantiate your instance. But if you need finer-grain control, these methods are available.
- Shotgun.connect()[source]
Connect client to the server if it is not already connected.
Note
The client will automatically connect to the server on demand. You only need to call this function if you wish to confirm the client can connect.
- Shotgun.close()[source]
Close the current connection to the server.
If the client needs to connect again it will do so automatically.
- Shotgun.authenticate_human_user(user_login, user_password, auth_token=None)[source]
Authenticate Shotgun HumanUser.
Authenticates a user given the login, password, and optionally, one-time auth token (when two-factor authentication is required). The user must be a
HumanUser
entity and the account must be active.>>> sg.authenticate_human_user("rhendriks", "c0mPre$Hi0n", None) {"type": "HumanUser", "id": 123, "name": "Richard Hendriks"}
- Parameters:
- Returns:
Standard Shotgun dictionary representing the HumanUser if authentication succeeded.
None
if authentication failed for any reason.- Return type:
- Shotgun.get_session_token()[source]
Get the session token associated with the current session.
If a session token has already been established, this is returned, otherwise a new one is generated on the server and returned.
>>> sg.get_session_token() dd638be7d07c39fa73d935a775558a50
- Returns:
String containing a session token.
- Return type:
- Shotgun.get_auth_cookie_handler()[source]
Return an urllib cookie handler containing a cookie for FPTR authentication.
Looks up session token and sets that in a cookie in the
urllib2
handler. This is used internally for downloading attachments from FPTR.
- Shotgun.add_user_agent(agent)[source]
Add agent to the user-agent header.
Appends agent to the user-agent string sent with every API request.
>>> sg.add_user_agent("my_tool 1.0")
- Parameters:
agent (str) – string to append to user-agent.
- Shotgun.reset_user_agent()[source]
Reset user agent to the default value.
Example default user-agent:
shotgun-json (3.0.17); Python 2.6 (Mac); ssl OpenSSL 1.0.2d 9 Jul 2015 (validate)
- Shotgun.set_session_uuid(session_uuid)[source]
Set 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 thissession_uuid
, the browser will display updates for these events.>>> sg.set_session_uuid("5a1d49b0-0c69-11e0-a24c-003048d17544")
- Parameters:
session_uuid (str) – The uuid of the browser session to be updated.
- Shotgun.info()[source]
Get API-related metadata from the Shotgun server.
>>> sg.info() {'full_version': [8, 2, 1, 0], 'version': [8, 2, 1], 'user_authentication_method': 'default', ...}
Token Value -------- --------- full_version An ordered array of the full Shotgun version. [major, minor, patch, hotfix] version An ordered array of the Shotgun version. [major, minor, patch] user_authentication_method Indicates the authentication method used by Shotgun. Will be one of the following values: default: regular username/password. ldap: username/password from the company's LDAP. saml2: SSO used, over SAML2.
Note
Beyond the documented tokens, you should expect the other values to be unsupported and for internal use only.
- Returns:
dict of the server metadata.
- Return type:
Subscription Management
These methods are used for reading and assigning user subscriptions.
- Shotgun.user_subscriptions_read()[source]
Get the list of user subscriptions.
- Returns:
A list of user subscriptions where each subscription is a dictionary containing the
humanUserId
andsubscription
fields.- Return type:
- Shotgun.user_subscriptions_create(users)[source]
Assign subscriptions to users.
- Parameters:
users (list) – list of user subscriptions to assign. Each subscription must be a dictionary with the
humanUserId
andsubscription
fields. Thesubscription
is eitherNone
, a single string, or an array of strings with subscription information.- Returns:
True
if the request succedeed,False
if otherwise.- Return type:
CRUD Methods
These are the main methods for creating, reading, updating, and deleting information. There are also some specialized convenience methods for accessing particular types of information.
- Shotgun.create(entity_type, data, return_fields=None)[source]
Create a new entity of the specified
entity_type
.>>> data = { ... "project": {"type": "Project", "id": 161}, ... "sg_sequence": {"type": "Sequence", "id": 109}, ... "code": "001_100", ... 'sg_status_list': "ip" ... } >>> sg.create('Shot', data) {'code': '001_100', 'id': 2557, 'project': {'id': 161, 'name': 'Pied Piper', 'type': 'Project'}, 'sg_sequence': {'id': 109, 'name': 'Sequence 001', 'type': 'Sequence'}, 'sg_status_list': 'ip', 'type': 'Shot'}
- Parameters:
entity_type (str) – Shotgun entity type to create.
data (dict) – Dictionary of fields and corresponding values to set on the new entity. If
image
orfilmstrip_image
fields are provided, the file path will be uploaded to the server automatically.return_fields (list) –
Optional list of additional field values to return from the new entity. Defaults to
id
field.See also
- Returns:
Shotgun entity dictionary containing the field/value pairs of all of the fields set from the
data
parameter as well as the defaultstype
andid
. If any additional fields were provided using thereturn_fields
parameter, these would be included as well.See also
- Return type:
- Shotgun.find(entity_type, filters, fields=None, order=None, filter_operator=None, limit=0, retired_only=False, page=0, include_archived_projects=True, additional_filter_presets=None)[source]
Find entities matching the given filters.
>>> # 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) [{'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'}]
You can drill through single entity links to filter on fields or display linked fields. This is often called “deep linking” or using “dot notation”.
See also
>>> # Find Versions created by Tasks in 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] >>> ] >>> sg.find("Version", filters, fields) [{'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'}]
- Parameters:
entity_type (str) – Shotgun entity type to find.
filters (list) –
list of filters to apply to the query.
See also
fields (list) –
Optional list of fields to include in each entity record returned. Defaults to
["id"]
.See also
order (list) –
Optional list of dictionaries defining how to order the results of the query. Each dictionary contains the
field_name
to order by and thedirection
to sort:[ {'field_name':'foo', 'direction':'asc'}, {'field_name':'bar', 'direction':'desc'} ]
Defaults to sorting by
id
in ascending order.filter_operator (str) – Operator to apply to the filters. Supported values are
"all"
and"any"
. These are just another way of defining if the query is an AND or OR query. Defaults to"all"
.limit (int) – Optional limit to the number of entities to return. Defaults to
0
which returns all entities that match.page (int) – Optional page of results to return. Use this together with the
limit
parameter to control how your query results are paged. Defaults to0
which returns all entities that match.retired_only (bool) – Optional boolean when
True
will return only entities that have been retired. Defaults toFalse
which returns only entities which have not been retired. There is no option to return both retired and non-retired entities in the same query.include_archived_projects (bool) – Optional boolean flag to include entities whose projects have been archived. Defaults to
True
.additional_filter_presets –
Optional list of presets to further filter the result set, list has the form:
[{ "preset_name": <preset_name>, <optional_param1>: <optional_value1>, ... }]
Note that these filters are ANDed together and ANDed with the ‘filter’ argument.
For details on supported presets and the format of this parameter see Additional Filter Presets
- Returns:
list of dictionaries representing each entity with the requested fields, and the defaults
"id"
and"type"
which are always included.See also
- Return type:
- Shotgun.find_one(entity_type, filters, fields=None, order=None, filter_operator=None, retired_only=False, include_archived_projects=True, additional_filter_presets=None)[source]
Shortcut for
find()
withlimit=1
so it returns a single result.>>> sg.find_one("Asset", [["id", "is", 32]], ["id", "code", "sg_status_list"]) {'code': 'Gopher', 'id': 32, 'sg_status_list': 'ip', 'type': 'Asset'}
- Parameters:
entity_type (str) – Shotgun entity type as a string to find.
filters (list) –
list of filters to apply to the query.
See also
fields (list) – Optional list of fields to include in each entity record returned. Defaults to
["id"]
.order (int) –
Optional list of fields to order the results by. List has the format:
[ {'field_name':'foo', 'direction':'asc'}, {'field_name':'bar', 'direction':'desc'} ]
Defaults to sorting by
id
in ascending order.filter_operator (str) – Operator to apply to the filters. Supported values are
"all"
and"any"
. These are just another way of defining if the query is an AND or OR query. Defaults to"all"
.retired_only (bool) – Optional boolean when
True
will return only entities that have been retired. Defaults toFalse
which returns only entities which have not been retired. There is no option to return both retired and non-retired entities in the same query.include_archived_projects (bool) – Optional boolean flag to include entities whose projects have been archived. Defaults to
True
.additional_filter_presets –
Optional list of presets to further filter the result set, list has the form:
[{ "preset_name": <preset_name>, <optional_param1>: <optional_value1>, ... }]
Note that these filters are ANDed together and ANDed with the ‘filter’ argument.
For details on supported presets and the format of this parameter see Additional Filter Presets
- Returns:
Dictionary representing a single matching entity with the requested fields, and the defaults
"id"
and"type"
which are always included.See also
- Return type:
- Shotgun.update(entity_type, entity_id, data, multi_entity_update_modes=None)[source]
Update the specified entity with the supplied data.
>>> shots = [ ... {'type':'Shot', 'id':'40435'}, ... {'type':'Shot', 'id':'40438'}, ... {'type':'Shot', 'id':'40441'}] >>> data = { ... 'shots': shots_asset_is_in, ... 'sg_status_list':'rev'} >>> sg.update("Asset", 55, data) {'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'}] }
- Parameters:
entity_type (str) – Entity type to update.
entity_id (id) – id of the entity to update.
data (dict) – key/value pairs where key is the field name and value is the value to set for that field. This method does not restrict the updating of fields hidden in the web UI via the Project Tracking Settings panel.
multi_entity_update_modes (dict) –
Optional dict indicating 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
, orremove
. Defaults toset
.multi_entity_update_modes={"shots": "add", "assets": "remove"}
- Returns:
Dictionary of the fields updated, with the default keys type and id added as well.
- Return type:
- Shotgun.delete(entity_type, entity_id)[source]
Retire the specified entity.
Entities in Shotgun are not “deleted” destructively, they are instead, “retired”. This means they are placed in the trash where they are no longer accessible to users.
The entity can be brought back to life using
revive()
.>>> sg.delete("Shot", 2557) True
- Shotgun.revive(entity_type, entity_id)[source]
Revive an entity that has previously been deleted.
>>> sg.revive("Shot", 860) True
- Shotgun.batch(requests)[source]
Make a batch request of several
create()
,update()
, anddelete()
calls.All requests are performed within a transaction, so either all will complete or none will.
Ex. 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}) 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'}}]
Ex. All three types of requests in one batch:
batch_data = [ {"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} ] sg.batch(batch_data)
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]
- Parameters:
requests (list) –
A list of dict’s of the form which have a request_type key and also specifies:
create:
entity_type
, data dict of fields to set- update:
entity_type
,entity_id
, data dict of fields to set, and optionally
multi_entity_update_modes
- update:
delete:
entity_type
and entity_id
- Returns:
A list of values for each operation. Create and update requests return a dict of the fields updated. Delete requests return
True
if the entity was deleted.- Return type:
- Shotgun.summarize(entity_type, filters, summary_fields, filter_operator=None, grouping=None, include_archived_projects=True)[source]
Summarize field 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.
Example: Count all Assets for a Project
>>> sg.summarize(entity_type='Asset', ... filters = [['project', 'is', {'type':'Project', 'id':4}]], ... summary_fields=[{'field':'id', 'type':'count'}]) {'groups': [], 'summaries': {'id': 15}}
summaries
contains the total summary for the query. 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.
Example: Count all Assets for a Project, grouped by sg_asset_type
>>> 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'}]) {'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}}
summaries
contains the total summary for the query.groups
contains the summary for each group.group_name
is the display name for the group.group_value
is the actual value of the grouping value. This is often the same asgroup_name
but in the case when grouping by entity, thegroup_name
may bePuppyA
and the group_value would be{'type':'Asset','id':922,'name':'PuppyA'}
.summaries
contains the summary calculation dict for each field requested.
Example: Count all Tasks for a Sequence and find the latest due_date
>>> 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'}]) {'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 is2013-07-05
.Example: Count all Tasks for a Sequence, find the latest due_date and group by Shot
>>> 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'}])) {'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 is2013-07-05
. Because the summary is grouped byentity
, we can also see the summaries for each Shot returned. Each Shot has 10 Tasks and the latestdue_date
for each Shot. The difference betweengroup_name
andgroup_value
is highlighted in this example as the name of the Shot is different from its value.Example: Count all Tasks for a Sequence, find the latest due_date, group by Shot and Pipeline Step
>>> 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'}]) {'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}}
When grouping my more than one field, the grouping structure is repeated for each sub-group and summary values are returned for each group on each level.
- Parameters:
entity_type (str) – The entity type to summarize
filters (list) – A list of conditions used to filter the find query. Uses the same syntax as
find()
method.summary_fields (list) –
A list of dictionaries with the following keys:
- field:
The internal Shotgun field name 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.
filter_operator (str) – Operator to apply to the filters. Supported values are
"all"
and"any"
. These are just another way of defining if the query is an AND or OR query. Defaults to"all"
.grouping (list) –
Optional list of dicts with the following keys:
- field:
a string indicating the internal Shotgun field name 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 options are
asc
anddesc
. Defaults toasc
.
- Returns:
dictionary containing grouping and summaries keys.
- Return type:
- Shotgun.note_thread_read(note_id, entity_fields=None)[source]
Return the full conversation for a given note, including Replies and Attachments.
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.
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 dictionary 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"] }
- Shotgun.text_search(text, entity_types, project_ids=None, limit=None)[source]
Search 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 ofNone
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 thefind()
method.
Example: Constrain the search to all Tasks but Character Assets only
>>> entity_types = { ... "Asset": [["sg_asset_type", "is", "Character"]], ... "Task": [] ... } >>> sg.text_search("bunny", entity_types) {'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.
- Parameters:
text (str) – Text to search for. This must be at least three characters long, or an exception will be raised.
entity_types (dict) – Dictionary to specify which entity types to search across. See above for usage examples.
project_ids (list) – List of Projects to search. By default, all projects will be searched.
limit (int) – Specify the maximum number of matches to return.
- Returns:
A complex dictionary structure, see above for example.
- Return type:
- Shotgun.update_project_last_accessed(project, user=None)[source]
Update a Project’s
last_accessed_by_current_user
field to the current timestamp.This helps keep track of the recent Projects each user has worked on and enables scripts and apps to use this information to display “Recent Projects” for users as a convenience.
New in version Requires: Shotgun v5.3.20+
>>> sg.update_project_last_accessed({"type": "Project", "id": 66}, ... {"type": "HumanUser", "id": 43})
- Parameters:
project (dict) – Standard Project entity dictionary
user (dict) – Standard user entity dictionary. This is optional if the current API instance is using user-based authenitcation, or has specified
sudo_as_login
. In these cases, ifuser
is not provided, thesudo_as_login
value orlogin
value from the current instance will be used instead.
- Shotgun.work_schedule_read(start_date, end_date, project=None, user=None)[source]
Return the work day rules for a given date range.
New in version 3.0.9: Requires Shotgun server v3.2.0+
This returns the defined WorkDayRules between the
start_date
andend_date
inclusive as a dict where the key is the date and the value is another dict describing the rule for that date.Rules are represented by a dict with the following 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
- Working:
boolean indicating whether it is a “working” day or not.
>>> sg.work_schedule_read("2015-12-21", "2015-12-25") {'2015-12-21': {'description': None, 'reason': 'STUDIO_WORK_WEEK', 'working': True}, '2015-12-22': {'description': None, 'reason': 'STUDIO_WORK_WEEK', 'working': True}, '2015-12-23': {'description': None, 'reason': 'STUDIO_WORK_WEEK', 'working': True}, '2015-12-24': {'description': 'Closed for Christmas Eve', 'reason': 'STUDIO_EXCEPTION', 'working': False}, '2015-12-25': {'description': 'Closed for Christmas', 'reason': 'STUDIO_EXCEPTION', 'working': False}}
- Parameters:
- Returns:
Complex dict containing each date and the WorkDayRule defined for that date between the
start_date
andend date
inclusive. See above for details.- Return type:
- Shotgun.work_schedule_update(date, working, description=None, project=None, user=None, recalculate_field=None)[source]
Update the work schedule for a given date.
New in version 3.0.9: Requires Shotgun server v3.2.0+
If neither
project
noruser
are passed in, the studio work schedule will be updated.project
anduser
can only be used exclusively of each other.>>> sg.work_schedule_update ("2015-12-31", working=False, ... description="Studio closed for New Years Eve", project=None, ... user=None, recalculate_field=None) {'date': '2015-12-31', 'description': "Studio closed for New Years Eve", 'project': None, 'user': None, 'working': False}
- Parameters:
date (str) – Date of WorkDayRule to update.
YYY-MM-DD
working (bool) – Indicates whether the day is a working day or not.
description (str) – Optional reason for time off.
project (dict) – Optional Project entity to assign the rule to. Cannot be used with the
user
param.user (dict) – Optional HumanUser entity to assign the rule to. Cannot be used with the
project
param.recalculate_field (str) – Optional schedule field that will be recalculated on Tasks when they are affected by a change in working schedule. Options are
due_date
orduration
. Defaults to the value set in the Shotgun web application’s Site Preferences.
- Returns:
dict containing key/value pairs for each value of the work day rule updated.
- Return type:
Working With Files
Methods that handle uploading and downloading files including thumbnails.
See also
- Shotgun.upload(entity_type, entity_id, path, field_name=None, display_name=None, tag_list=None)[source]
Upload a file to the specified entity.
Creates an Attachment entity for the file in Shotgun and links it to the specified entity. You can optionally store the file in a field on the entity, change the display name, and assign tags to the Attachment.
Note
Make sure to have retries for file uploads. Failures when uploading will occasionally happen. When it does, immediately retrying to upload usually works
>>> mov_file = '/data/show/ne2/100_110/anim/01.mlk-02b.mov' >>> sg.upload("Shot", 423, mov_file, field_name="sg_latest_quicktime", ... display_name="Latest QT") 72
- Parameters:
entity_type (str) – Entity type to link the upload to.
entity_id (int) – Id of the entity to link the upload to.
path (str) – Full path to an existing non-empty file on disk to upload.
field_name (str) – The internal Shotgun field name on the entity to store the file in. This field must be a File/Link field type.
display_name (str) – The display name to use for the file. Defaults to the file name.
tag_list (str) – comma-separated string of tags to assign to the file.
- Returns:
Id of the Attachment entity that was created for the image.
- Return type:
- Raises:
ShotgunError
on upload failure.
- Shotgun.upload_thumbnail(entity_type, entity_id, path, **kwargs)[source]
Upload a file from a local path and assign it as the thumbnail for the specified entity.
Note
Images will automatically be re-sized on the server to generate a size-appropriate image file. However, the original file is retained as well and is accessible when you click on the thumbnail image in the web UI. If you are using a local install of Shotgun and have not enabled S3, this can eat up disk space if you’re uploading really large source images for your thumbnails.
You can un-set (aka clear) a thumbnail on an entity using the
update()
method and setting the image field toNone
. This will also unset thefilmstrip_thumbnail
field if it is set.Supported image file types include
.jpg` and ``.png
(preferred) but will also accept..gif`
,.tif
,.tiff
,.bmp
,.exr
,.dpx
, and.tga
.This method wraps over
upload()
. Additional keyword arguments passed to this method will be forwarded to theupload()
method.
- Shotgun.upload_filmstrip_thumbnail(entity_type, entity_id, path, **kwargs)[source]
Upload filmstrip thumbnail to specified entity.
New in version 3.0.9: Requires Shotgun server v3.1.0+
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. Therefore 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 file type 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
.You can un-set (aka clear) a thumbnail on an entity using the
update()
method and setting the image field toNone
. This will also unset thefilmstrip_thumbnail
field if it is set.This method wraps over
upload()
. Additional keyword arguments passed to this method will be forwarded to theupload()
method.>>> filmstrip_thumbnail = '/data/show/ne2/100_110/anim/01.mlk-02b_filmstrip.jpg' >>> sg.upload_filmstrip_thumbnail("Version", 27, filmstrip_thumbnail) 87
- Parameters:
- Returns:
Id of the new Attachment entity created for the filmstrip thumbnail
- Return type:
- Shotgun.download_attachment(attachment=False, file_path=None, attachment_id=None)[source]
Download the file associated with a Shotgun Attachment.
>>> version = sg.find_one("Version", [["id", "is", 7115]], ["sg_uploaded_movie"]) >>> local_file_path = "/var/tmp/%s" % version["sg_uploaded_movie"]["name"] >>> sg.download_attachment(version["sg_uploaded_movie"], file_path=local_file_path) /var/tmp/100b_scene_output_v032.mov
Warning
On older (< v5.1.0) Shotgun versions, non-downloadable files on Shotgun don’t raise exceptions, they cause a server error which returns a 200 with the page content.
- Parameters:
attachment (dict) –
Usually a dictionary representing an Attachment entity. The dictionary should have a
url
key that specifies the download url. Optionally, the dictionary can be a standard entity hash format withid
andtype
keys as long as"type"=="Attachment"
. This is only supported for backwards compatibility (#22150).If an int value is passed in, the Attachment entity with the matching id will be downloaded from the Shotgun server.
file_path (str) – Optional file path to write the data directly to local disk. This avoids loading all of the data in memory and saves the file locally at the given path.
attachment_id (id) –
(deprecated) Optional
id
of the Attachment entity in Shotgun to download.
- Returns:
If
file_path
is provided, returns the path to the file on disk. Iffile_path
isNone
, returns the actual data of the file, as str in Python 2 or bytes in Python 3.- Return type:
- Shotgun.get_attachment_download_url(attachment)[source]
Return the URL for downloading provided Attachment.
- Parameters:
attachment (mixed) –
Usually a dict representing An Attachment entity in Shotgun to return the download url for. If the
url
key is present, it will be used as-is for the download url. If theurl
key is not present, a url will be constructed pointing at the current Shotgun server for downloading the Attachment entity using theid
.If
None
is passed in, it is silently ignored in order to avoid raising an error when results from afind()
are passed off todownload_attachment()
Note
Support for passing in an int representing the Attachment
id
is deprecated- Returns:
the download URL for the Attachment or
None
ifNone
was passed toattachment
parameter.- Return type:
Associate a thumbnail with more than one Shotgun entity.
New in version 3.0.9: Requires Shotgun server v4.0.0+
Share the thumbnail from between entities without requiring uploading the thumbnail file multiple times. You can use this in two ways:
Upload an image to set as the thumbnail on multiple entities.
Update multiple entities to point to an existing entity’s thumbnail.
Note
When sharing a filmstrip thumbnail, it is required to have a static thumbnail in place before the filmstrip will be displayed in the Shotgun web UI. If the thumbnail is still processing and is using a placeholder, this method will error.
Simple use case:
>>> thumb = '/data/show/ne2/100_110/anim/01.mlk-02b.jpg' >>> e = [{'type': 'Version', 'id': 123}, {'type': 'Version', 'id': 456}] >>> sg.share_thumbnail(entities=e, thumbnail_path=thumb) 4271
>>> e = [{'type': 'Version', 'id': 123}, {'type': 'Version', 'id': 456}] >>> sg.share_thumbnail(entities=e, source_entity={'type':'Version', 'id': 789}) 4271
- Parameters:
entities (list) –
The entities to update to point to the shared thumbnail provided in standard entity dict format:
[{'type': 'Version', 'id': 123}, {'type': 'Version', 'id': 456}]
thumbnail_path (str) – The full path to the local thumbnail file to upload and share. Required if
source_entity
is not provided.source_entity (dict) – The entity whos thumbnail will be the source for sharing. Required if
source_entity
is not provided.filmstrip_thumbnail (bool) –
True
to share the filmstrip thumbnail.False
to share the static thumbnail. Defaults toFalse
.
- Returns:
id
of the Attachment entity representing the source thumbnail that is shared.- Return type:
- Raises:
ShotgunError
if not supported by server version or improperly called, orShotgunThumbnailNotReady
if thumbnail is still pending.
Activity Stream
Methods that relate to the activity stream and following of entities in Flow Production Tracking.
- Shotgun.activity_stream_read(entity_type, entity_id, entity_fields=None, min_id=None, max_id=None, limit=None)[source]
Retrieve 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.
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. 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:
entity_type (str) – Entity type to retrieve activity stream for
entity_id (int) – Entity id to retrieve activity stream for
entity_fields (list) – List of additional fields to include. See above for details
max_id (int) – Do not retrieve ids greater than this id. This is useful when implementing paging.
min_id (int) – 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.
limit (int) – Limit the number of returned records. If not specified, the system default will be used.
- Returns:
A complex activity stream data structure. See above for details.
- Return type:
- Shotgun.follow(user, entity)[source]
Add the entity to the user’s followed entities.
If the user is already following the entity, the method will succeed but nothing will be changed on the server-side.
>>> sg.follow({"type": "HumanUser", "id": 42}, {"type": "Shot", "id": 2050}) {'followed': True, 'user': {'type': 'HumanUser', 'id': 42}, 'entity': {'type': 'Shot', 'id': 2050}}
- Shotgun.unfollow(user, entity)[source]
Remove entity from the user’s followed entities.
This does nothing if the user is not following the entity.
>>> sg.unfollow({"type": "HumanUser", "id": 42}, {"type": "Shot", "id": 2050}) {'entity': {'type': 'Shot', 'id': 2050}, 'user': {'type': 'HumanUser', 'id': 42}, 'unfollowed': True}
- Shotgun.followers(entity)[source]
Return all followers for an entity.
>>> sg.followers({"type": "Shot", "id": 2050}) [{'status': 'act', 'valid': 'valid', 'type': 'HumanUser', 'name': 'Richard Hendriks', 'id': 42}, {'status': 'act', 'valid': 'valid', 'type': 'HumanUser', 'name': 'Bertram Gilfoyle', 'id': 33}, {'status': 'act', 'valid': 'valid', 'type': 'HumanUser', 'name': 'Dinesh Chugtai', 'id': 57}]
- Shotgun.following(user, project=None, entity_type=None)[source]
Return all entity instances a user is following.
Optionally, a project and/or entity_type can be supplied to restrict returned results.
>>> user = {"type": "HumanUser", "id": 1234} >>> project = {"type": "Project", "id": 1234} >>> entity_type = "Task" >>> sg.following(user, project=project, entity_type=entity_type) [{"type":"Task", "id":1}, {"type":"Task", "id":2}, {"type":"Task", "id":3}]
- Parameters:
- Returns:
list of dictionaries, each containing entity type & id’s being followed.
- Return type:
Working with the Shotgun Schema
Methods allow you to introspect and modify the Shotgun schema.
- Shotgun.schema_entity_read(project_entity=None)[source]
Return 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.>>> sg.schema_entity_read() {'ActionMenuItem': {'name': {'editable': False, 'value': 'Action Menu Item'}, 'visible': {'editable': False, 'value': True}}, 'ApiUser': {'name': {'editable': False, 'value': 'Script'}, 'visible': {'editable': False, 'value': True}}, 'AppWelcomeUserConnection': {'name': {'editable': False, 'value': 'App Welcome User Connection'}, 'visible': {'editable': False, 'value': True}}, 'Asset': {'name': {'editable': False, 'value': 'Asset'}, 'visible': {'editable': False, 'value': True}}, 'AssetAssetConnection': {'name': {'editable': False, 'value': 'Asset Asset Connection'}, 'visible': {'editable': False, 'value': True}}, '...' }
- Parameters:
project_entity (dict) – 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 of Entity Type to dict containing the display name.
- Return type:
Note
The returned display names for this method will be localized when the
localize
Shotgun config property is set toTrue
. See Localization for more information.
- Shotgun.schema_field_read(entity_type, field_name=None, project_entity=None)[source]
Get schema for all fields on the specified entity type or just the field name specified if provided.
Note
Unlike how the results of a
find()
can be pumped into acreate()
orupdate()
, the results ofschema_field_read()
are not compatible with the format used forschema_field_create()
orschema_field_update()
. If you need to pipe the results fromschema_field_read()
into aschema_field_create()
orschema_field_update()
, you will need to reformat the data in your script.Note
If you don’t specify a
project_entity
, everything is reported as visible.Note
The returned display names for this method will be localized when the
localize
Shotgun config property is set toTrue
. See Localization for more information.>>> sg.schema_field_read('Asset', 'shots') {'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']}}, 'unique': {'editable': False, 'value': False}, 'visible': {'editable': False, 'value': True}}}
- Parameters:
entity_type (str) – Entity type to get the schema for.
field_name (str) – Optional internal Shotgun name of the field to get the schema definition for. If this parameter is excluded or set to
None
, data structures of all fields will be returned. Defaults toNone
. Example:sg_temp_field
.project_entity (dict) – 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:
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 theentity_type
. Properties that are'editable': True
, can be updated using theschema_field_update()
method.- Return type:
- Shotgun.schema_field_create(entity_type, data_type, display_name, properties=None)[source]
Create a field for the specified entity type.
Note
If the internal Shotgun field name computed from the provided
display_name
already exists, the internal Shotgun field name will automatically be appended with_1
in order to create a unique name. The integer suffix will be incremented by 1 until a unique name is found.>>> properties = {"summary_default": "count", "description": "Complexity breakdown of Asset"} >>> sg.schema_field_create("Asset", "text", "Complexity", properties) 'sg_complexity'
- Parameters:
entity_type (str) – Entity type to add the field to.
data_type (str) – Shotgun data type for the new field.
display_name (str) – 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.
properties (dict) – Dict of valid properties for the new field. Use this to specify other field properties such as the ‘description’ or ‘summary_default’.
- Returns:
The internal Shotgun name for the new field, this is different to the
display_name
parameter passed in.- Return type:
- Shotgun.schema_field_update(entity_type, field_name, properties, project_entity=None)[source]
Update the properties for the specified field on an entity.
Note
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’.
>>> properties = {"name": "Test Number Field Renamed", "summary_default": "sum", ... "description": "this is only a test"} >>> sg.schema_field_update("Asset", "sg_test_number", properties) True
- Parameters:
entity_type – Entity type of field to update.
field_name – Internal Shotgun name of the field to update.
properties – Dictionary with key/value pairs where the key is the property to be updated and the value is the new value.
project_entity (dict) – Optional Project entity specifying which project to modify the
visible
property for. Ifvisible
is present inproperties
andproject_entity
is not set, an exception will be raised. Example:{'type': 'Project', 'id': 3}
- Returns:
True
if the field was updated.
Note
The
project_entity
parameter can only affect the state of thevisible
property and has no impact on other properties.- Return type:
- Shotgun.schema_field_delete(entity_type, field_name)[source]
Delete the specified field from the entity type.
>>> sg.schema_field_delete("Asset", "sg_temp_field") True
- Shotgun.schema_read(project_entity=None)[source]
Get the schema for all fields on all entities.
Note
If
project_entity
is not specified, everything is reported as visible.>>> sg.schema_read() {'ActionMenuItem': {'created_at': {'data_type': {'editable': False, 'value': 'date_time'}, 'description': {'editable': True, 'value': ''}, 'editable': {'editable': False, 'value': False}, 'entity_type': {'editable': False, 'value': 'ActionMenuItem'}, 'mandatory': {'editable': False, 'value': False}, 'name': {'editable': True, 'value': 'Date Created'}, 'properties': {'default_value': {'editable': False, 'value': None}, 'summary_default': {'editable': True, 'value': 'none'}}, 'unique': {'editable': False, 'value': False}, 'visible': {'editable': False, 'value': True}}, 'created_by': {'data_type': {'editable': False,'value': 'entity'}, 'description': {'editable': True,'value': ''}, 'editable': {'editable': False,'value': False}, 'entity_type': {'editable': False,'value': 'ActionMenuItem'}, 'mandatory': {'editable': False,'value': False}, 'name': {'editable': True,'value': 'Created by'}, 'properties': {'default_value': {'editable': False,'value': None}, 'summary_default': {'editable': True,'value': 'none'}, 'valid_types': {'editable': True,'value': ['HumanUser','ApiUser']}}, 'unique': {'editable': False,'value': False}, 'visible': {'editable': False,'value': True}}, ... ... ... ... 'Version': {'client_approved': {'data_type': {'editable': False,'value': 'checkbox'}, 'description': {'editable': True,'value': ''}, 'editable': {'editable': False,'value': True}, 'entity_type': {'editable': False,'value': 'Version'}, 'mandatory': {'editable': False,'value': False}, 'name': {'editable': True,'value': 'Client Approved'}, 'properties': {'default_value': {'editable': False,'value': False}, 'summary_default': {'editable': False,'value': 'none'}}, 'unique': {'editable': False,'value': False}, 'visible': {'editable': False,'value': True}}, ... ... ... ... }
- Parameters:
project_entity (dict) – 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}
. Defaults toNone
.- Returns:
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 theschema_field_update()
method.- Return type:
Note
The returned display names for this method will be localized when the
localize
Shotgun config property is set toTrue
. See Localization for more information.
Exceptions
These are the various exceptions that the Flow Production Tracking API will raise.
- class shotgun_api3.ShotgunError[source]
Bases:
Exception
Base for all Shotgun API Errors.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- class shotgun_api3.ShotgunFileDownloadError[source]
Bases:
ShotgunError
Exception for file download-related errors.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- class shotgun_api3.Fault[source]
Bases:
ShotgunError
Exception when server-side exception detected.
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
Filter Syntax
Basic Filters
Filters are represented as a list of conditions that will be combined using the supplied
filter_operator (any
or all
). Each condition follows the basic simple form:
[<field>, <relation>, <value(s)>]
Basic Example
Using the default filter_operator "all"
, the following filters will return all Shots whose status
is “ip” AND is linked to Asset #9:
filters = [
["sg_status_list", "is", "ip"],
["assets", "is", {"type": "Asset", "id": 9}]
]
result = sg.find("Shot", filters)
Complex Filters
Complex filters can be a dictionary that represents a complex sub-condition of the form:
{"filter_operator": "any", "filters": [<list of conditions>]}
Complex Example
Using the default filter_operator "all"
, the following filters will return all Shots whose status
is “ip” AND is linked to either Asset #9 OR Asset #23:
filters = [
["sg_status_list", "is", "ip"],
{
"filter_operator": "any",
"filters": [
["assets", "is", {"type": "Asset", "id": 9}],
["assets", "is", {"type": "Asset", "id": 23}]
]
}
]
result = sg.find("Shot", filters)
Operators and Arguments
Operator Arguments
-------- ---------
'is' [field_value] | None
'is_not' [field_value] | None
'less_than' [field_value] | None
'greater_than' [field_value] | None
'contains' [field_value] | None
'not_contains' [field_value] | None
'starts_with' [string]
'ends_with' [string]
'between' [[field_value] | None, [field_value] | None]
'not_between' [[field_value] | None, [field_value] | None]
'in_last' [[int], 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'YEAR']
# note that brackets are not literal (eg. ['start_date', 'in_last', 1, 'DAY'])
'in_next' [[int], 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'YEAR']
# note that brackets are not literal (eg. ['start_date', 'in_next', 1, 'DAY'])
'in' [[field_value], ...] # Array of field values
'type_is' [string] | None # Shotgun entity type
'type_is_not' [string] | None # Shotgun entity type
'in_calendar_day' [int] # Offset (e.g. 0 = today, 1 = tomorrow,
# -1 = yesterday)
'in_calendar_week' [int] # Offset (e.g. 0 = this week, 1 = next week,
# -1 = last week)
'in_calendar_month' [int] # Offset (e.g. 0 = this month, 1 = next month,
# -1 = last month)
'name_contains' [string]
'name_not_contains' [string]
'name_starts_with' [string]
'name_ends_with' [string]
Valid Operators By Data Type
addressing 'is'
'is_not'
'contains'
'not_contains'
'in'
'type_is'
'type_is_not'
'name_contains'
'name_not_contains'
'name_starts_with'
'name_ends_with'
checkbox 'is'
'is_not'
currency 'is'
'is_not'
'less_than'
'greater_than'
'between'
'not_between'
'in'
'not_in'
date 'is'
'is_not'
'greater_than'
'less_than'
'in_last'
'not_in_last'
'in_next'
'not_in_next'
'in_calendar_day'
'in_calendar_week'
'in_calendar_month'
'in_calendar_year'
'between'
'in'
'not_in'
date_time 'is'
'is_not'
'greater_than'
'less_than'
'in_last'
'not_in_last'
'in_next'
'not_in_next'
'in_calendar_day'
'in_calendar_week'
'in_calendar_month'
'in_calendar_year'
'between'
'in'
'not_in'
duration 'is'
'is_not'
'greater_than'
'less_than'
'between'
'in'
'not_in'
entity 'is'
'is_not'
'type_is'
'type_is_not'
'name_contains'
'name_not_contains'
'name_is'
'in'
'not_in'
float 'is'
'is_not'
'greater_than'
'less_than'
'between'
'in'
'not_in'
image 'is' ** Note: For both 'is' and 'is_not', the only supported value is None,
'is_not' ** which supports detecting the presence or lack of a thumbnail.
list 'is'
'is_not'
'in'
'not_in'
multi_entity 'is' ** Note: when used on multi_entity, this functions as
you would expect 'contains' to function
'is_not'
'type_is'
'type_is_not'
'name_contains'
'name_not_contains'
'in'
'not_in'
number 'is'
'is_not'
'less_than'
'greater_than'
'between'
'not_between'
'in'
'not_in'
password ** Filtering by this data type field not supported
percent 'is'
'is_not'
'greater_than'
'less_than'
'between'
'in'
'not_in'
serializable ** Filtering by this data type field not supported
status_list 'is'
'is_not'
'in'
'not_in'
summary ** Filtering by this data type field not supported
tag_list 'is' ** Note: when used on tag_list, this functions as
you would expect 'contains' to function
'is_not'
'name_contains'
'name_not_contains'
'name_id'
text 'is'
'is_not'
'contains'
'not_contains'
'starts_with'
'ends_with'
'in'
'not_in'
timecode 'is'
'is_not'
'greater_than'
'less_than'
'between'
'in'
'not_in'
url ** Filtering by this data type field is not supported
Additional Filter Presets
As of Flow Production Tracking version 7.0 it is possible to also use filter presets. These presets provide a simple way to specify powerful query filters that would otherwise be costly and difficult to craft using traditional filters.
Multiple presets can be specified in cases where it makes sense.
Also, these presets can be used alongside normal filters. The result returned is an AND operation between the specified filters.
Example Uses
The following query will return the Version with the name ‘ABC’ that is linked to the latest entity created:
additional_filter_presets = [
{
"preset_name": "LATEST",
"latest_by": "ENTITIES_CREATED_AT"
}
]
filters = [['code', 'is', 'ABC']]
result = sg.find('Version', filters = filters, additional_filter_presets = additional_filter_presets)
The following query will find all CutItems associated to Cut #1 and return all Versions associated to the Shot linked to each of these CutItems:
additional_filter_presets = [
{
"preset_name": "CUT_SHOT_VERSIONS",
"cut_id": 1
}
]
result = sg.find('Version', additional_filter_presets = additional_filter_presets)
Available Filter Presets by Entity Type
Allowed filter presets (and preset parameter values) depend on the entity type being searched.
The table bellow gives the details about which filter preset can be used on each entity type and with which parameters.
Entity Type Preset Name Preset Parameters Allowed Preset Parameter Values
----------- ----------- ----------------- -------------------------------
Cut LATEST [string] latest_by 'REVISION_NUMBER':
Returns the cuts that have the
highest revision number.
This is typically used with a query
filter that returns cuts with the
same value for a given field
(e.g. code field). This preset
therefore allows to get
the Cut of that set that has
the highest revision_number value.
Version CUT_SHOT_VERSIONS [int] cut_id Valid Cut entity id.
Returns all Version entities
associated to the Shot entity
associated to the CutItems
of the given Cut.
This basically allows to find all
Versions associated to the given
Cut, via its CutItems.
LATEST [string] latest_by 'ENTITIES_CREATED_AT':
When dealing with multiple
Versions associated to a group
of entities, this will return
only the last Version created
for each entity.
For example, when dealing with a
set of Shots, this preset allows
to find the latest Version created
for each of these Shots.
'BY_PIPELINE_STEP_NUMBER_AND_ENTITIES_CREATED_AT':
When dealing with multiple versions
associated to the same entity *and*
to Tasks, returns the Version
associated to the Task with highest
step.list_order.
If multiple Versions are found for
that step.list_order, only the
latest Version is returned.
This allows to isolate the Version
entity that is the farthest along
in the pipeline for a given entity.
For example, when dealing with a Shot
with multiple Versions, this preset
will return the Version associated
to the Task with the highest
step.list_order value.
Published LATEST [string] latest_by 'ENTITIES_CREATED_AT':
Files When dealing with multiple
PublishedFiles associated to a
group of entities, this will return
only the last PublishedFiles created
for each entity.
For example, when dealing with a
set of Versions, this preset allows
you to find the latest PublishedFile
created for each of these Versions.
'VERSION_NUMBER':
When dealing with multiple
PublishedFiles associated with a
group of entities, this returns only
the PublishedFile with the highest
version_number.
Data Types
addressing
- value:
List of dicts:
[
{
'type': 'HumanUser' | 'Group',
'id': int,
...
},
...
]
checkbox
- value:
bool
(True
|False
)
color
- value:
- example:
255,0,0
|pipeline_step
pipeline_step
indicates the Task color inherits from the Pipeline Step color.
currency
date
date_time
duration
Length of time, in minutes
entity
{
'type': "string",
'id': int,
...
}
float
footage
image (read-only)
- value:
-
Note
Refer to Interpreting Image Field Strings.
list
multi_entity
- value:
List of dicts
[
{
'type': "string",
'id': int,
...
},
...
]
number
- value:
int
|None
- range:
-2147483648
,2147483647
password
- value:
string
|None
Returned values of password fields are replaced with *******
for security
percent
- value:
int
|None
- range:
-2147483648
,2147483647
serializable
- value:
dict
|None
status_list
- value:
str
|None
system_task_type (deprecated)
- value:
str
|None
tag_list
- value:
text
- value:
str
|None
timecode
- value:
int
|None
- range:
-2147483648
,2147483647
Length of time, in milliseconds (1000 = 1 second)
url (file/link field)
- value:
dict
|None
{
'content_type': "string",
'link_type': "local" | "url" | "upload",
'name': "string",
'url': "string"
}
Local File Links
Additional keys exist for local file links
- value:
dict
|None
{
'content_type': "string",
'link_type': "local",
'local_path': "string" | None,
'local_path_linux': "string" | None,
'local_path_mac': "string" | None,
'local_path_windows': "string" | None,
'local_storage': {dictionary},
'name': "string",
'url': "string",
}
API versions < v3.0.3:
{
'url': "string",
'name': "string",
'content_type': "string"
}
Interpreting Image Field Strings
There are three possible states for values returned by an image
field:
Type |
Value - Description |
---|---|
No thumbnail image uploaded, or thumbnail generation failed. |
|
<protocol>://<domain>/images/status/transient/thumbnail_pending.png -URLs of this form indicate a transient placeholder icon.
Returned if image requested between upload & availability from media storage.
Constant string per site.
|
|
<signed URL for S3 object> -Access to final thumbnail.
|
Note
Other upcoming features are likely to require the use of other transient thumbnails. For this reason, it is highly recommended to use the prefix part of the placeholder path (e.g. https://my-site.shotgrid.autodesk.com/images/status/transient/) to detect any transient URLs rather than use the full path of the thumbnail.
Event Types
Whenever a user makes a change to any data in Flow Production Tracking, an event log entry record is created, capturing the value before and after. Flow Production Tracking also logs some additional useful events that help keep track of various activity on your Flow Production Tracking instance.
Event-based Triggers
Events are particularlly useful when used in conjunction with a trigger framework like the Flow Production Tracking Event Daemon. This allows you to write plug-ins that watch for certain types of events and then run code when they occur.
Structure of Event Types
The basic structure of event types is broken into 3 parts:
Application_EntityType_Action
Application
: Is always “Shotgun” for events automatically created by the Flow Production Tracking server. Other Flow Production Tracking products may use their name in here, for example, Toolkit has its own events that it logs and the application portion is identified by “Toolkit”. If you decide to use the EventLogEntry entity to log events for your scripts or tools, you would use your tool name here.EntityType
: This is the entity type in Flow Production Tracking that was acted upon (eg. Shot, Asset, etc.)Action
: The general action that was taken. (eg. New, Change, Retirement, Revival)
Standard Event Types
Each entity type has a standard set of events associated with it when it’s created, updated, deleted, and revived. They follow this pattern:
Shotgun_EntityType_New
: a new entity was created. Example:Shotgun_Task_New
Shotgun_EntityType_Change
: an entity was modified. Example:Shotgun_HumanUser_Change
Shotgun_EntityType_Retirement
: an entity was deleted. Example:Shotgun_Ticket_Retirement
Shotgun_EntityType_Revival
: an entity was revived. Example:Shotgun_CustomEntity03_Revival
Additional Event Types
These are _some_ of the additional event types that are logged by Flow Production Tracking:
Shotgun_Attachment_View
: an Attachment (file) was viewed by a user.Shotgun_Reading_Change
: a threaded entity has been marked read or unread. For example, a Note was read by a user. The readings are unique to the entity<->user connection so when a Note is read by user “joe” it may still be unread by user “jane”.Shotgun_User_Login
: a user logged in to Flow Production Tracking.Shotgun_User_Logout
: a user logged out of Flow Production Tracking.
Custom Event Types
Since EventLogEntries
are entities themselves, you can create them using the API just like any
other entity type. As mentioned previously, if you’d like to have your scripts or tools log to
the Flow Production Tracking event log, simply devise a thoughtful naming structure for your event types and
create the EventLogEntry as needed following the usual methods for creating entities via the API.
Again, other Flow Production Tracking products like Toolkit use event logs this way.
Note
EventLogEntries cannot be updated or deleted (that would defeat the purpose of course).
Performance
Event log database tables can get large very quickly. While Flow Production Tracking does very well with event logs that get into the millions of records, there’s an inevitable degradation of performance for pages that display them in the web application as well as any API queries for events when they get too big. This volume of events is not the norm, but can be reached if your server expereinces high usage.
This does not mean your Flow Production Tracking server performance will suffer in general, just any pages that are specifically displaying EventLogEntries in the web application, or API queries on the event log that are run. We are always looking for ways to improve this in the future. If you have any immediate concerns, please reach out to our support team
Environment Variables
SHOTGUN_API_CACERTS
Used to specify a path to an external SSL certificates file. This environment variable can be used in place of the ca_certs
keyword argument to the Shotgun
constructor. In the case that both this environment variable is set and the keyword argument is provided, the value from the keyword argument will be used.
SHOTGUN_API_RETRY_INTERVAL
Stores the number of milliseconds to wait between request retries. By default, a value of 3000 milliseconds is used. You can override the default either by setting this environment variable, or by setting the rpc_attempt_interval
property on the config like so:
sg = Shotgun(site_name, script_name, script_key)
sg.config.rpc_attempt_interval = 1000 # adjusting default interval
In the case that both this environment variable and the config’s rpc_attempt_interval
property are set, the value in rpc_attempt_interal
will be used.
SHOTGUN_API_ENABLE_ENTITY_OPTIMIZATION
Note
(v3.7.0) This is an experimental feature. Feel free to disable this feature if you are experiencing any issues.
When set to 1
, this environment variable will enable the entity optimization feature.
This feature is disabled by default and is used to reduce the payload size made to the server when retrieving entities
improving overall performance by decreasing network latency and server processing.
For example, a find
call like this:
sg.find('Asset', [['project', 'is', {
'created_at': datetime.datetime(2015, 12, 16, 11, 2, 10, tzinfo),
'id': 9999,
'name': 'Demo: Game',
'type': 'Project',
# More entity attributes
}]])
Will internally be transformed as if you invoked something like this:
sg.find('Asset', [['project', 'is', {'id': 999, 'type': 'Project'}]])
Localization
The Flow Production Tracking API offers the ability to return localized display names in the current user’s language. Requests made from script/API users are localized in the site settings.
This functionality is currently supported by the methods Shotgun.schema_entity_read
, Shotgun.schema_field_read
, and Shotgun.schema_read
.
Localization is disabled by default. To enable localization, set the localized
property to True
.
Example for a user whose language preference is set to Japanese:
>>> sg = Shotgun(site_name, script_name, script_key)
>>> sg.config.localized # checking that localization is disabled
False
>>> sg.schema_field_read('Shot')
{
'sg_vendor_groups': {
'mandatory': {'editable': False, 'value': False},
# the value field (display name) is not localized
'name': {'editable': True, 'value': 'Vendor Groups'},
...
},
...
}
>>> sg.config.localized = True # enabling the localization
>>> sg.schema_field_read('Shot')
{
'sg_vendor_groups': {
'mandatory': {'editable': False, 'value': False},
# the value field (display name) is localized
'name': {'editable': True, 'value': '\xe3\x83\x99\xe3\x83\xb3\xe3\x83\x80\xe3\x83\xbc \xe3\x82\xb0\xe3\x83\xab\xe3\x83\xbc\xe3\x83\x97'},
...
},
...
}
Note
If needed, the encoding of the returned localized string can be ensured regardless the Python version using shotgun_api3.lib.six.ensure_text().