Tank API Reference

Tank Core API

Welcome to the Core API documentation! This part of the documentation covers the part of the API that deals with the core part of tank, for example file system manipulation, how to identify the key sections in a path and how to access Shotgun.

tank.tank_from_path()

Factory method that constructs and returns a Tank API object from a path on disk.

Tank tank.tank_from_path( str path )

Parameters & Return Value

str path - A path for which we want to retrieve a suitable Tank API object. Typically this is the project path, but it can be also be a path that goes deeper into the file system, alternatively points to an entirely different file tree or drive in the case of multiple roots being associated with the project.
Returns: Tank API Object.

tank.tank_from_entity()

Factory method that constructs and returns a Tank API object from a Shotgun object.

Tank tank.tank_from_path( str entity_type, int entity_id )

Parameters & Return Value

str entity_type - A Shotgun entity type.
int entity_id - A Shotgun entity id.
Returns: Tank API Object.

The Tank Object

The Tank object is the main object in the Tank API and the starting point for all operations. You don't instantiate it via its constructor, but instead use the tank_from_path() factory method to create a Tank object.

roots property

Returns a dictionary of root names to root paths. In the case of a single project root, there will only be one entry.

templates property

Dictionary of all templates in the system, keyed by template name.

project_path property

Path to the primary root directory for a project.

shotgun property

A Shotgun API Handle that is connected to the shotgun server associated with this Tank API instance.

version property

The version of the tank Core API (e.g. 'v0.2.3').

documentation_url property

Return the relevant documentation url for this app. May return None if no documentation exists.

template_from_path()

Attempts to resolve a file system path into a Template object.

Template tank_api_obj.template_from_path( string input_path )

Parameters & Return Value

string input_path -- The file path to try to find a template for.
Returns: a Template Object.
Returns: None if no object could be found.

Example

>>> import tank
>>> tk = tank.tank_from_path("/studio/project_root")    
>>> tk.template_from_path("/studio/my_proj/assets/Car/Anim/work")
<Tank Template maya_asset_project: assets/%(Asset)s/%(Step)s/work>

paths_from_template()

Finds paths that match a template using field values passed. This is useful if you want to get a list of files matching a particular template and set of fields. One common pattern is when you are dealing with versions, and you want to retrieve all the different versions for a file. In that case just resolve all the fields for the file you want to operate on, then pass those in to the paths_from_template() method. By passing version to the skip_keys parameter, the method will return all the versions associated with your original file.

Note: The result is not ordered in any particular way.

list tank_api_obj.paths_from_template(Template template, dict fields, list skip_keys=None)

Example

Imagine you have a template maya_work: sequences/{Sequence}/{Shot}/work/{name}.v{version}.ma

>>> import tank
>>> tk = tank.tank_from_path("/studio/my_proj")    
>>> maya_work = tk.templates["maya_work"]

All fields that you don't specify will be searched for. So if we want to search for all names and versions for a particular sequence and shot, we can do:

>>> import tank
>>> tk.paths_from_template(maya_work, {"Sequence": "AAA", "Shot": "001"})
/studio/my_proj/sequences/AAA/001/work/background.v001.ma
/studio/my_proj/sequences/AAA/001/work/background.v002.ma
/studio/my_proj/sequences/AAA/001/work/background.v003.ma
/studio/my_proj/sequences/AAA/001/work/mainscene.v001.ma
/studio/my_proj/sequences/AAA/001/work/mainscene.v002.ma
/studio/my_proj/sequences/AAA/001/work/mainscene.v003.ma

Parameters & Return Value

Template template -- The template object to look for.
dict fields -- Fields to constrain the search by.
list skip_keys -- keys inside the fields dictionary that you want to ignore.
Returns: a matching list of file paths.

abstract_paths_from_template()

Similar to paths_from_template(), but optimized for abstract fields such as image sequences and stereo patterns.

An abstract fields is for example an image sequence pattern token, such as %04d or @@@@@. This token represents a large collection of files. This method will return abstract fields whenever it can, and it will attempt to optimize the calls based on abstract pattern matching, trying to avoid doing a thousand file lookups for a thousand frames in a sequence.

It works exactly like paths_from_template with the difference that any field marked as abstract in the configuration will use its default value rather than any matched file values. Sequence fields are abstract by default.

Note: The result is not ordered in any particular way.

list tank_api_obj.abstract_paths_from_template(Template template, dict fields, list skip_keys=None)

Example

Imagine you have a template render: sequences/{Sequence}/{Shot}/images/{eye}/{name}.{SEQ}.exr

>>> import tank
>>> tk = tank.tank_from_path("/studio/my_proj")    
>>> render = tk.templates["render"]

All fields that you don't specify will be searched for. So if we want to search for all names and versions for a particular sequence and shot, we can do:

>>> import tank
>>> tk.abstract_paths_from_template(maya_work, {"Sequence": "AAA", "Shot": "001"})
/studio/my_proj/sequences/AAA/001/images/%V/render_1.%04d.exr
/studio/my_proj/sequences/AAA/001/images/%V/render_2.%04d.exr
/studio/my_proj/sequences/AAA/001/images/%V/render_3.%04d.exr

Parameters & Return Value

Template template -- The template object to look for.
dict fields -- Fields to constrain the search by. You can only specify real values here, not abstract fields such as %04d or %v.
list skip_keys -- keys inside the fields dictionary that you want to ignore.
Returns: a matching list of abstract file paths.

paths_from_entity()

Finds paths associated with a Shotgun entity.

list tank_api_obj.paths_from_entity(str entity_type, int entity_id)

Parameters & Return Value

str entity_type -- The Shotgun Entity type to look for.
int entity_id -- The Shotgun Entity id to look for.
Returns: a matching list of paths.

entity_from_path()

Returns the Shotgun entity associated with a path.

list tank_api_obj.entity_from_path(str path)

Parameters & Return Value

str path -- A path on disk
Returns: A Shotgun dictionary containing the keys type, name and id. None if no Shotgun Entity was associated.

Example

>>> tank_object.entity_from_path("/studio/demo_project")
{'type': 'Project', 'id': 4, 'name': 'Demo Project'}

context_empty()

Factory method that constructs an empty Context object.

Context tank_api_obj.context_empty()

Parameters & Return Value

Returns: a Context object.

context_from_path()

Factory method that constructs a context object from a path on disk.

Context tank_api_obj.context_empty(str path, Context previous_context=None)

Parameters & Return Value

str path -- Path to a file or a folder for which we want to create a Context.
Context previous_context (Optional) -- You can pass in a previous context object to this method, in which case Tank will try to populate the new context both based on the path and on the previous context -- if, for example, the previous context contains a Task and the specified path maps to the same entity as the previous context, the task will automatically be carried across from the previous context to the new one.
Returns: a Context object

context_from_entity()

Factory method that constructs a context object from a Shotgun entity.

Context tank_api_obj.context_empty(str entity_type, int entity_id)

Parameters & Return Value

str entity_type -- The Shotgun Entity type to look for.
int entity_id -- The Shotgun Entity id to look for.
Returns: a Context object

create_filesystem_structure()

Create folders and associated data on disk to reflect branches in the project tree related to a specific entity.

int tank_api_obj.create_filesystem_structure(str entity_type, int entity_id, str engine = None)

It is possible to set up folder creation so that it happens in two passes - a primary pass and a deferred pass. Typically, the primary pass is used to create the high level folder structure and the deferred is executed just before launching an application environment. It can be used to create application specific folders or to create a user workspace based on the user launching the application. By setting the optional engine parameter to a string value (typically the engine name, for example tk-maya) you can indicate to the system that it should trigger the deferred pass and recurse down in the part of the configuration that has been marked as being deferred in the configuration.

Parameters & Return Value

str entity_type -- The Shotgun Entity type to create folders for.
int entity_id -- The Shotgun Entity id to create folders for, alternatively a list of ids if you want to create folders for multiple items.
str engine -- Indicates that a second folder creation pass should be executed for a particular engine.
Returns: a the number of folders processed.

preview_filesystem_structure()

Preview what folders the folder creation method would create on disk.

int tank_api_obj.preview_filesystem_structure(str entity_type, int entity_id, str engine = None)

Parameters & Return Value

str entity_type -- The Shotgun Entity type to create folders for.
int entity_id -- The Shotgun Entity id to create folders for, alternatively a list of ids if you want to create folders for multiple items.
str engine -- Indicates that a second folder creation pass should be executed for a particular engine. For more information about this, see the create_filesystem_structure() documentation.
Returns: a list of folders and files that would be processed if the create_filesystem_strcture() method was to be executed.

The Context Object

The context method is used to collect a set of key fields describing the current Context. Typically this would be the current shot or asset that someone is working on.

Context objects are not constructed by hand but are fabricated by the methods tank_obj.context_from_entity() and tank_obj.context_from_path().

tank property

Returns the tank API object associated with this Context object.

project property

A property which holds the project associated with this context. If the context is incomplete, it is possible that the property is None.

>>> import tank
>>> tk = tank.tank_from_path("/studio.08/demo_project")
>>> ctx = tk.context_from_path("/studio.08/demo_project/sequences/AAA/ABC/Lighting/work")
>>> ctx.project
{'type': 'Project', 'id': 4, 'name': 'demo_project'}

entity property

A property which holds the entity associated with this context. If the context is incomplete, it is possible that the property is None.

>>> import tank
>>> tk = tank.tank_from_path("/studio.08/demo_project")
>>> ctx = tk.context_from_path("/studio.08/demo_project/sequences/AAA/ABC/Lighting/work")
>>> ctx.entity
{'type': 'Shot', 'id': 2, 'name': 'shot_010'}

step property

A property which holds the step associated with this context. If the context is incomplete, it is possible that the property is None.

>>> import tank
>>> tk = tank.tank_from_path("/studio.08/demo_project")
>>> ctx = tk.context_from_path("/studio.08/demo_project/sequences/AAA/ABC/Lighting/work")
>>> ctx.step
{'type': 'Step', 'id': 1, 'name': 'Client'}

task property

A property which holds the task associated with this context. If the context is incomplete, it is possible that the property is None.

>>> import tank
>>> tk = tank.tank_from_path("/studio.08/demo_project")
>>> ctx = tk.context_from_path("/studio.08/demo_project/sequences/AAA/ABC/Lighting/first_pass_lgt/work")
>>> ctx.task
{'type': 'Task', 'id': 212, 'name': 'first_pass_lgt'}

user property

A property which holds the user associated with this context. If the context is incomplete, it is possible that the property is None.

The user property is a bit special -- either it represents a user value that was baked into a template path upon folder creation, or it represents the current user. The current user will only be correctly resolved if Tank is able to match the user's login against a login record in Shotgun. If the match fails, the user is set to None.

>>> import tank
>>> tk = tank.tank_from_path("/studio.08/demo_project")
>>> ctx = tk.context_from_path("/studio.08/demo_project/sequences/AAA/ABC/Lighting/dirk.gently/work")
>>> ctx.user
{'type': 'HumanUser', 'id': 23, 'name': 'Dirk Gently'}

additional_entities property

List of entities that are required to provide a full context in non-standard configurations. The "context_additional_entities" core hook gives the context construction code hints about how this data should be populated.

Returns a list of std shotgun link dictionaries. Will be an empty list in most cases.

entity_locations property

A property which holds a list of paths on disk which correspond to the entity which this context represents. If no folders have been created for this context yet, the value of this property will be an empty list.

>>> import tank
>>> tk = tank.tank_from_path("/studio.08/demo_project")
>>> ctx = tk.context_from_entity("Task", 8)
>>> ctx.entity_locations
['/studio.08/demo_project/sequences/AAA/ABC']

filesystem_locations property

A property which holds a list of paths on disk which correspond to this context. If no folders have been created for this context yet, the value of this property will be an empty list.

>>> import tank
>>> tk = tank.tank_from_path("/studio.08/demo_project")
>>> ctx = tk.context_from_entity("Task", 8)
>>> ctx.filesystem_locations
['/studio.08/demo_project/sequences/AAA/ABC']

shotgun_url property

A property which holds the url that best correspond to this context. If the context is completely empty, the base url of the associated shotgun installation will be returned.

>>> import tank
>>> tk = tank.tank_from_path("/studio.08/demo_project")
>>> ctx = tk.context_from_entity("Task", 8)
>>> ctx.shotgun_url
'https://mystudio.shotgunstudio.com/detail/Task/8'

as_template_fields()

Returns the context object as a dictionary of template fields. This is useful if you want to use a Context object as part of a call to the Tank API. In order for the system to pass suitable values, you need to pass the template you intend to use the data with as a parameter to this method. The values are derived from existing paths on disk, or in the case of keys with shotgun_entity_type and shotgun_entity_field settings, direct queries to the Shotgun server.

dict as_template_fields( Template template_obj )

Parameters & Return Value

Template template_obj - A template for which suitable values should be returned.
Returns: Dictionary of template files representing the context. The dictionary is matched to the specified template and can be used for example as an input to the apply_fields() method.

Example

>>> import tank
>>> tk = tank.tank_from_path("/studio.08/demo_project")
>>> ctx = tk.context_from_path("/studio.08/demo_project/sequences/AAA/ABC/Lighting/work")
>>> 
>>> templ = tk.templates["maya_publish_file"]
>>>
>>> fields = ctx.as_template_fields(templ)
>>> fields
{'Step': 'Lighting', 'Shot': 'ABC', 'Sequence': 'AAA'}

The Template Object

Template objects represent patterns that can be used to move between field value pairs and resolved strings (usually project related paths). These patterns come in two flavors, those resolving to paths and those resolving to non-path strings and are defined in the template configuration file Configuration Documentation.

Example

>>> import tank
>>> tk = tank.tank_from_path("/studio.08/demo_project")
>>> template_path = tk.templates['maya_shot_publish']
>>> template_path
<Tank TemplatePath maya_shot_publish: sequences/{Sequence}/{Shot}/{Step}/publish/{name}.v{version}.ma>

>>> template_str = tk.templates['maya_publish_name']
>>> template_str
<Tank TemplateString maya_publish_name: Maya Scene {name}, v{version}>

definition property

The definition is the pattern on which the template is based. It will match the definition as seen in the template configuration file with any aliased key names replacing their original names.

Example

>>> template_path.definition
'sequences/{Sequence}/{Shot}/{Step}/publish/{name}.v{version}.ma'

>>> template_str.definition
'Maya Scene {name}, v{version}'

parent property

The parent property returns a template representing the parent path of the current template. This is equivalent to creating a template on the fly from the parent directory path of the current template. This template is unnamed and may represent a pattern not directly defined for the project. Template strings do not represent paths and as such will always return None as a parent.

Example

>>> template_path
<Tank TemplatePath maya_shot_publish: sequences/{Sequence}/{Shot}/{Step}/publish/{name}.v{version}.ma>

>>> template_path.parent
<Tank TemplatePath sequences/{Sequence}/{Shot}/{Step}/publish>

>>> template_str.parent

keys property

The keys property returns the keys used in this templates definition. It is in the form of a mapping of key names to key objects.

Example

>>> template_path
>>> template_path.keys
{'Sequence': <Tank StringKey Sequence>,
 'Shot': <Tank StringKey Shot>,
 'Step': <Tank StringKey Step>,
 'name': <Tank StringKey name>,
 'version': <Tank IntegerKey version>}

>>> template_str.keys
{'name': <Tank StringKey name>, 'version': <Tank IntegerKey version>}

missing_keys()

The missing keys method return a list of key names of keys required by the template minus those passed to the method.

list Template.missing_keys( dict fields )

Parameters & Return Value

dict fields -- A dictionary of key names to key values.
Returns: A list of key names which are required by the template but missing as keys in the fields parameter.

Example

>>> template_str.keys
{'name': <Tank StringKey name>, 'version': <Tank IntegerKey version>}

>>> fields = {"Shot":"shot 1", "name": "henry"}

>>> template_path.missing_keys(fields)
['Step', 'version', 'Sequence']

>>> template_str.missing_keys(fields)
['version']

is_optional()

Returns true if the given parameter is an optional part of the given template.

bool Template.is_optional( str key_name )

Parameters & Return Value

str key_name -- Template key to check
Returns: True if the specified key is optional, False if it is required.

Example

>>> template
<Tank TemplatePath max_asset_work: assets/{sg_asset_type}/{Asset}/{Step}/work/3dsmax/[{name}].v{version}.max>

>>> template.is_optional("name")
True

>>> template.is_optional("version")
False

apply_fields()

The apply fields method takes a dictionary of fields (key value pairs) and returns a value based on those values in conjunction with the template pattern.

str Template.apply_fields( dict fields )

Parameters & Return Value

dict fields -- A dictionary of key names to key values.
Returns: a string representation of the template pattern using the field values.

Special formatting for sequence fields

If a field is of type SequenceKey, special formatting options are available.

With image sequences, there are many ways of representing a set of images. Different applications use different representations, so it is often necessary to be able to extract image sequences on a particular format so that it works with a particular application environment.

In Tank, this can be done using a special FORMAT directive. This format directive only works with abstract image sequence fields and supports a number of different formats. For example, an app may need to reconstruct a path, but the app doesn't know if the user has configured the input paths to use eight zero padded paths or four zero padded paths. However, the app runs in Nuke, so it needs path on the form %04d (for four zero padded paths). In order to get the correct padding, pass FORMAT: %d and Tank will format this with the correct padding.

The following conversions are supported for sequence keys:

FORMAT: %d - Turns format_spec 04 into %04d and a non-zero padded format_spec into %d
FORMAT: @ - Turns format_spec 04 into @@@@ and a non-zero padded format_spec into @
FORMAT: # - Turns format_spec 04 into #### and a non-zero padded format_spec into #
FORMAT: $F - Turns format_spec 04 into $F4 and a non-zero padded format_spec into $F

Example

>>> fields = {"Sequence":"seq_1", "Shot":"shot_2", "Step":"comp", "name":"henry", "version":3}

>>> template_path.apply_fields(fields)
'/studio_root/tank/demo_project_1/sequences/seq_1/shot_2/comp/publish/henry.v003.ma'

>>> template_str.apply_fields(fields)
'Maya Scene henry, v003'

validate()

The validate method take an input string and determines whether it can be mapped to the template pattern.

bool Template.validate( str path, dict fields, list skip_keys )

Parameters & Return Value

str path -- The string to validate.
dict fields -- An optional dictionary of key names to key values. If supplied these values will need to be present in the input path.
list skip_keys -- An optional list of key names whose values do not need to be constrained for the validation.
Returns: bool

Example

>>> good_path = '/studio_root/tank/demo_project_1/sequences/seq_1/shot_2/comp/publish/henry.v003.ma'
>>> template_path.validate(good_path)
True

>>> bad_path = '/studio_root/tank/demo_project_1/shot_2/comp/publish/henry.v003.ma'
>>> template_path.validate(bad_path)
False

get_fields()

The get_fields method returns a mapping of fields to values based on an input string.

dict Template.get_fields( str input_path, list skip_keys )

Parameters & Return Value

str input_path -- The path from which to extract field values.
list skip_keys -- An optional list of key names whose values do not need to be constrained for the validation (they will be treated as strings).
Returns: dictionary of key names to values.

Example

>>> input_path = '/studio_root/tank/demo_project_1/sequences/seq_1/shot_2/comp/publish/henry.v003.ma'
>>> template_path.get_fields(input_path)

{'Sequence': 'seq_1',
 'Shot': 'shot_2',
 'Step': 'comp',
 'name': 'henry',
 'version': 3}

TemplateKey Object

TemplateKeys are used by Template object to move between key values and resolved strings. The template keys handle the manner in which this conversion should occur. Template keys come in three flavors: string, integer, and sequence.

Example

>>> import tank
>>> tk = tank.tank_from_path("/studio.08/demo_project")
>>> template_path = tk.templates['nuke_asset_render']
>>> str_key = template_path.keys['Asset']
>>> str_key
<Tank StringKey Asset>

>>> int_key = template_path.keys['height']
>>> int_key
<Tank IntegerKey height>

>>> seq_key = template_path.keys['frame']
>>> seq_key
<Tank SequenceKey frame>

name property

The name that the template will use to refer to the key.

default property

The value this key will use if no value is provided.

choices property

A list of values that this key may use. Any value not in this list will be considered invalid.

is_abstract property

A boolean value indicating if this key is abstract. Abstract keys are typically used in conjunction with path elements which represent clusters of files, for example when you want to represent a sequence of frames using a %04d syntax or a left and right eye using a %v syntax.

str_from_value()

Returns a string version of a value as appropriate for the key's type and settings.

str TemplateKey.str_from_value( str value, ignore_type bool )

Parameters and Return Value

value -- The value to turn into a string. If not supplied the key's default value will be used.
bool ignore_type -- If true, will just cast the value to a string.
Returns: A string version of the value formatted as specified by the key.

Example

>>> str_key.str_from_value('henry')
'henry'

>>> int_key.str_from_value(4)
'4'

>>> seq_key.str_from_value(4)
'0004'

value_from_str()

Validates and translates a string into an appropriate value for this key.

key type TemplateKey.value_from_str( str str_value )

Parameters and Return Value

str str_value -- The string to translate.
Returns: The translated value.

Example

>>> str_key.value_from_str('henry')
'henry'

>>> int_key.value_from_str('4')
4

>>> seq_key.value_from_str('0004')
4

validate()

Test if a value is valid for this key.

bool TemplateKey.validate( value, list messages )

Parameters and Return Value

value -- Value to test.
list messages -- (Optional) A list to which error messages will be appended.
Returns: Bool

Example

>>> str_key.validate('henry')
True

>>> int_key.validate(2)
True

>>> int_key.validate('henry')
False

>>> seq_key.validate(3)
True

>>> seq_key.validate('henry')
False

Utility Functions

get_current_user()

Retrieves a shotgun user dict for the current user. Returns None if the user is not found in shotgun. This method connects to shotgun.

Returns the following fields:

type
id
name
image (thumbnail url)
email
login

dict tank.util.get_current_user(Tank tk )

Parameters and Return Value

Tank tk -- Tank API Instance.
Returns: Dictionary of user data.

Example

>>> tank.util.get_current_user(tk)

{'name': 'Tank Platform', 
 'image': 'http://some_url/files/0000/0000/0482/232/image.jpg', 
 'email': 'tank.platform@shotgunsoftware.com', 
 'login': 'tank', 
 'type': 'HumanUser', 
 'id': 39}

find_publish()

Finds publishes in Shotgun given paths on disk. This method is similar to the find method in the Shotgun API, except that instead of an Entity type, a list of files is passed into the function.

In addition to a list of files, shotgun filters can also be specified. This may be useful if for example all publishes with a certain status should be retrieved.

By default, the shotgun id is returned for each successfully identified path. If you want to retrieve additional fields, you can specify these using the fields parameter.

The method will return a dictionary, keyed by path. The value will be a standard shotgun query result dictionary, for example:

{
    "/foo/bar" : { "id": 234, "code": "some data" },
    "/foo/baz" : { "id": 23,  "code": "some more data" }
}

Fields that are not found, or filtered out by the filters parameter, is not returned in the dictionary.

dict tank.util.find_publish( Tank tk, list list_of_paths, list filters, list fields )

Parameters and Return Value

Tank tk -- Tank API Instance
list list_of_paths -- List of full paths for which information should be retrieved
list filters -- Optional list of shotgun filters to apply.
list fields -- Optional list of fields from the matched entities to return. Defaults to id.
Returns: dictionary keyed by path

Example

>>> pub_path = '/studio_root/demo_project/sequences/Sequence-1/shot_010/Anm/publish/henry.v001.ma'
>>> tank.util.find_publish(tk, [pub_path])
{'/studio_root/demo_project/sequences/Sequence-1/shot_010/Anm/publish/henry.v001.ma': {'id': 1, 'type': 'TankPublishedFile'}}

create_event_log_entry()

Creates an event log entry in Shotgun.

dict tank.util.create_event_log_entry( Tank tk, Context context, str event_type, str description, dict metadata)

Required Parameters

Tank tk -- a Tank API instance
Context context -- the context we want to associate with the event log entry
str event_type -- String which defines the event type. The Shotgun standard suggests that this should be on the form Company_Item_Action. Examples include: Shotgun_Asset_New, Shotgun_Asset_Change and Shotgun_User_Login.
str description -- Verbose description of the event log entry.

Optional Parameters

dict metadata -- A dictionary containing arbitrary metadata. You can only use simple types such as strings and its in this dictionary.

Return Value

Returns: Dictionary with event log information.

Example

>>> tank.util.create_event_log_entry(tk, ctx, "MyStudio_Maya_Startup, "Maya was launched from Shotgun.")
{   'description': 'Maya was launched from Shotgun.', 
    'entity': None,
    'project': {'type': 'Project', 'id': 69, 'name': 'test'}, 
    'user': {'type': 'HumanUser', 'id': 39, 'name': 'Manne Ohrstrom'}, 
    'type': 'EventLogEntry', 
    'id': 47501, 
    'event_type': 'MyStudio_Maya_Startup'
    }

register_publish()

Creates a Tank Published File in Shotgun.

dict tank.util.register_publish( Tank tk, Context context, str path, str name, int version_number, kwargs )

Required Parameters

Tank tk -- a Tank API instance
Context context -- the context we want to associate with the publish
str path -- the path to the file or sequence we want to publish
str name -- a name, without version number, which helps distinguish this publish from other publishes. This is typically used for grouping inside of Shotgun so that all the versions of the same "file" can be grouped into a cluster. For example, for a maya publish, where we track only the scene name, the name would simply be that: the scene name. For something like a render, it could be the scene name, the name of the AOV and the name of the render layer.
int version_number -- the verison numnber of the item we are publishing.

Optional Parameters

dict task -- a shotgun entity dictionary with id and type (which should always be Task). if no value is specified, the task will be grabbed from the context object.
str comment -- a string containing a description of the comment
str thumbnail_path -- a path to a thumbnail (png or jpeg) which will be uploaded to shotgun and associated with the publish.
list dependency_paths -- a list of file system paths that should be attempted to be registered as dependencies. Files in this listing that do not appear as publishes in shotgun will be ignored.
str tank_type -- a tank type in the form of a string which should match a tank type that is registered in Shotgun.
bool update_entity_thumbnail -- if a thumbnail has been provided, try to upload it to the associated entity (e.g. the associated Shot or Asset).
bool update_task_thumbnail -- if a thumbnail has been provided, try to uploade it to the associated task.
dict created_by -- a shotgun entity dictionary with id and type (which should always be a HumanUser or an ApiUser). If no value is specified then the current user will be used.
datetime created_at -- a datetime representing the date and time the publish was created at. If no value is specified then the current date and time will be used.

Return Value

Returns: Dictionary with PublishedFile entity information.

Example

>>> version_number = 1
>>> file_path = '/studio/demo_project/sequences/Sequence-1/shot_010/Anm/publish/henry.v001.ma'
>>> name = 'henry'
>>> tank.util.register_publish(tk, ctx, file_path, name, version_number)
{'code': 'henry.v001.ma',
 'created_by': {'id': 40, 'name': 'kennedy behrman', 'type': 'HumanUser'},
 'description': None,
 'entity': {'id': 2, 'name': 'shot_010', 'type': 'Shot'},
 'id': 2,
 'name': 'henry',
 'path': {'content_type': None,
  'link_type': 'local',
  'local_path': '/studio/demo_project/sequences/Sequence-1/shot_010/Anm/publish/henry.v001.ma',
  'local_path_linux': '/studio/demo_project/sequences/Sequence-1/shot_010/Anm/publish/henry.v001.ma',
  'local_path_mac': '/studio/demo_project/sequences/Sequence-1/shot_010/Anm/publish/henry.v001.ma',
  'local_path_windows': 'c:\\studio\\demo_project\\sequences\\Sequence-1\\shot_010\\Anm\\publish\\henry.v001.ma',
  'local_storage': {'id': 1, 'name': 'Tank', 'type': 'LocalStorage'},
  'name': 'henry.v001.ma',
  'url': 'file:///studio/demo_project/sequences/Sequence-1/shot_010/Anm/publish/henry.v001.ma'},
 'path_cache': 'demo_project/sequences/Sequence-1/shot_010/Anm/publish/henry.v001.ma',
 'project': {'id': 4, 'name': 'Demo Project', 'type': 'Project'},
 'task': None,
 'type': 'TankPublishedFile',
 'version_number': 1}

The above example shows a basic publish. In addition to the required parameters, it is also common to supply at least a description and a Tank Type.

get_entity_type_display_name()

Returns the display name for an entity type given its type name. For example, if a custom entity is named "Workspace" in the Shotgun preferences, but is addressed as CustomEntity03 in the Shotgun API, this method will resolve CustomEntity03 -> Workspace.

str tank.util.get_entity_type_display_name(Tank tk, str entity_type_code )

Parameters and Return Value

Tank tk -- Tank API Instance.
str entity_type_code -- Name of entity type
Returns: Display name string

Tank API Reference

Tank Core API

tank.tank_from_path()

tank.tank_from_entity()

The Tank Object

roots property

templates property

project_path property

shotgun property

version property

documentation_url property

template_from_path()

paths_from_template()

abstract_paths_from_template()

paths_from_entity()

entity_from_path()

context_empty()

context_from_path()

context_from_entity()

create_filesystem_structure()

preview_filesystem_structure()

The Context Object

tank property

project property

entity property

step property

task property

user property

additional_entities property

entity_locations property

filesystem_locations property

shotgun_url property

as_template_fields()

The Template Object

definition property

parent property

keys property

missing_keys()

is_optional()

apply_fields()

validate()

get_fields()

TemplateKey Object

name property

default property

choices property

is_abstract property

str_from_value()

value_from_str()

validate()

Utility Functions

get_current_user()

find_publish()

create_event_log_entry()

register_publish()

get_entity_type_display_name()

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally