Core API Reference

Introduction

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

Creating an API Instance

sgtk.sgtk_from_path()

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

Sgtk sgtk.sgtk_from_path( str path )

Parameters & Return Value

str path - A path for which we want to retrieve a suitable Sgtk 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: Sgtk API Object.

sgtk.sgtk_from_entity()

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

Sgtk sgtk.sgtk_from_entity( str entity_type, int entity_id )

Parameters & Return Value

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

Executing tank commands via the API

The tank command offers a variety of system utility commands to handle for example upgrades, administration and maintenance. These commands are also available to use via the API in order to make it easy to integrate toolkit maintenance workflows with other scriped workflows you may have in your studio. The following commands can be used to manage and execute these functions:

sgtk.list_commands()

Lists the global level system commands registered with the system. These global commands can be executed at any point and do not require a project or a configuration to be present. Examples of such commands are the core upgrade check and the setup_project commands.

Commands returned by this method can be used in the sgtk.get_command() method.

list sgtk.list_commands()

Parameters & Return Value

Returns: List of all the global command names.

Example

>>> import sgtk
>>> sgtk.list_commands()
['setup_project', 'core']

sgtk_api_obj.list_commands()

Lists the project level and global level system commands registered with the system. Project level commands are commands which require a project to be active. Since this method is a member of a toolkit API instance, your command will operate on that API instance when they execute. Project level commands include commands for maintenance and admin, app installation, updates, development etc. The global commands (also retrievable via sgtk.list_commands() will also be returned by this command. Commands returned by this method can be used in the sgtk_api_obj.get_command() method.

list sgtk_api_obj.list_commands()

Parameters & Return Value

Returns: List of all global and project level command names.

Example

>>> import sgtk
>>> tk = sgtk.sgtk_from_path("/studio/project_root")
>>> tk.list_commands()
['setup_project', 'core', 'localize', 'validate', 'cache_apps', 'clear_cache',
 'app_info', 'install_app', 'install_engine', 'updates', 'configurations', 'clone_configuration']

sgtk.get_command() / sgtk_api_obj.get_command()

Returns an instance of a command object that can be used to execute a command.

Once you have retrieved the command instance, you can perform introspection to check for example the required parameters for the command, name, description etc. Lastly, you can execute the command by running the execute() method.

Commands retrieved via sgtk.list_commands() can be accessed using the sgtk.get_command() and commands retrieved via the tk API level sgtk_api_obj.list_commands() method can be accessed using the tk API level sgtk_api_obj.get_command() method.

Global variant: SgtkSystemCommand sgtk.get_command( str command_name )

Project specific variant: SgtkSystemCommand sgtk_api_obj.get_command( str command_name )

Parameters & Return Value

str command_name - Name of command to execute. Get a list of all available commands using the sgtk.list_commands() method.
Returns: SgtkSystemCommand object instance.

Example

#############################################
# global commands

>>> import sgtk

>>> sgtk.list_commands()
['setup_project', 'core']

>>> sgtk.get_command("core")
<tank.deploy.tank_command.SgtkSystemCommand object at 0x106d9f090>


#############################################
# project specific commands

>>> import sgtk

>>> tk = sgtk.sgtk_from_path("/studio/project_root")

>>> tk.list_commands()
['setup_project', 'core', 'localize', 'validate', 'cache_apps', 'clear_cache',
 'app_info', 'install_app', 'install_engine', 'updates', 'configurations', 'clone_configuration']

>>> tk.get_command("validate")
<tank.deploy.tank_command.SgtkSystemCommand object at 0x106d9f090>

The `SgtkSystemCommand` class

Commands are managed via the SgtkSystemCommand class which provides methods and accessors for both execution and introspection. The following properties and methods exist:

parameters property

Returns the different parameters that needs to be specified and if a parameter has any default values. For example:

{ "parameter_name": { "description": "Parameter info",
                    "default": None,
                    "type": "str" },

 ...

 "return_value": { "description": "Return value (optional)",
                   "type": "str" }
}

description property

Returns a brief description of this command.

name property

Returns the name of this command.

category property

Returns the category for this command. This is typically a short string like "Admin".

set_logger()

Specify a standard python log instance to send logging output to. If this is not specify, the standard output mechanism will be used.

command_obj.set_logger( logging.Logger log )

Parameters & Return Value

logging.Logger log - Python std logger to use when reporting output.

execute()

Execute this command.

If no changes have been made via the set_logger() method, a standard python logger to stderr will be used for any logging output the command emits. Any parameters required by the command needs to be passed in via the params argument. To see which parameters a particular commands supports, use the parameters property documented above.

If the parameters property dictionary contains a return_value key, this is the type of return value to expect from the execute methods.

command_obj.execute( dict params )

Parameters & Return Value

dict params - Dictionary of parameter values to pass to the command. The dictionary key is the name of the parameter and the value is the value you want to pass. You can query which parameters can be passed in via the parameters property.
Returns: Various data depending on the command.

The Sgtk API Instance Object

The Sgtk object is the main object in the Sgtk API and the starting point for all operations. You don't instantiate it via its constructor, but instead use the sgtk_from_path() factory method to create a Sgtk 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. These items reflect the Local Storages that you have set up in Shotgun. Each project in the Pipeline Toolkit is connected to a number of these storages - these storages define the root points for all the different data locations for your project. So for example, if you have a mount point for textures, one for renders and one for production data such as scene files, you can set up a multi root configuration which uses three Local Storages in Shotgun. This method returns the project storage locations for the current project. The key is the name of the local storage, the way it is defined in Shotgun. The value is the path which is defined in the Shotgun Local storage definition for the current operating system, concatenated with the project folder name.

Example

>>> import sgtk
>>> tk = sgtk.sgtk_from_path("/studio/project_root")
>>> tk.roots
{"primary": "/mnt/projects/my_project", "textures": "/textures/my_project", "renders": "/renders/my_project" }

templates property

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

reload_templates() method

Reloads the template definitions from disk. If the reload fails a TankError will be raised and the previous template definitions will be preserved. This method can be helpful if you are tweaking templates inside of for example maya and want to reload them. You can then access this method from the python console via the current engine handle: sgtk.platform.current_engine().sgtk.reload_templates()

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 Sgtk API instance.

version property

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

documentation_url property

Returns the relevant documentation url for the Core API.

configuration_name property

Returns the name of the Pipeline Configuration associated with this API instance.

template_from_path()

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

Template sgtk_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 sgtk
>>> tk = sgtk.sgtk_from_path("/studio/project_root")
>>> tk.template_from_path("/studio/my_proj/assets/Car/Anim/work")
<Sgtk 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.

Any keys that are required by the template but aren't included in the fields dictionary are always skipped. Any optional keys that aren't included are only skipped if the skip_missing_optional_keys parameter is set to True.

If an optional key is to be skipped, all matching paths that contain a value for that key as well as those that don't will be included in the result.

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

list sgtk_api_obj.paths_from_template( Template template, dict fields, list skip_keys = None, bool skip_missing_optional_keys = False )

Example

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

>>> import sgtk
>>> tk = sgtk.sgtk_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 sgtk
>>> 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.
bool skip_missing_optional_keys - determine if optional keys not included in the fields dictionary should be ignored.
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 sgtk_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 sgtk
>>> tk = sgtk.sgtk_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 sgtk
>>> 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 sgtk_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 sgtk_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

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

context_empty()

Factory method that constructs an empty Context object.

Context sgtk_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 sgtk_api_obj.context_from_path( 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 Sgtk 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 sgtk_api_obj.context_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 Context object.

context_from_entity_dictionary()

Factory method that constructs a Context object from a Shotgun entity dictionary.

Context sgtk_api_obj.context_from_entity_dictionary(dict entity_dictionary)

This method will try to use any linked information available in the supplied entity_dictionary to construct a valid Context. If there isn't enough information then it will fall back to context_from_entity() which may result in a Shotgun or Path Cache query and be considerably slower.

The following values for entity_dictionary will result in a Context being created without falling back to context_from_entity. Each entity in the dictionary (including linked entities) must have the fields type, id and name (or the name equivelent for specific entity types, e.g. content for Step entities, code for Shot entities, etc.).

# Construct a Context containing just a Project
{"type":"Project", "id":123, "name":"My Project"}

# Construct a Context containing an entity (Shot) and Project
{"type":"Shot", "id":456, "code":"Shot 001", 
    "project":{"type":"Project", "id":123, "name":"My Project"}
}

# Construct a Context containing a Task, Step, entity (Shot) and Project
{"type":"Task", "id":789, "name":"Animation",
    "project":{"type":"Project", "id":123, "name":"My Project"}, 
    "entity":{"type":"Shot", "id":456, "name":"Shot 001"},
    "step":{"type":"Step", "id":101112, "name":"Anm"}
    }

The following values for entity_dictionary don't contain enough information to fully form a Context so the code will fall back to context_from_entity() which may then result in a Shotgun or Path Cache query to retrieve the missing information.

# missing project name
{"type":"Project", "id":123}

# missing linked project
{"type":"Shot", "id":456, "code":"Shot 001"}

# missing linked project name and linked step
{"type":"Task", "id":789, "name":"Animation",
  "project":{"type":"Project", "id":123},
  "entity":{"type":"Shot", "id":456, "name":"Shot 001"}
  }

Parameters & Return Value

dict entity_dictionary - A Shotgun entity dictionary containing at least 'type' and 'id'
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 sgtk_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.

Note that this is just a string following a convention - typically, we recommend that an engine name (e.g. 'tk-nuke') is passed in, however all this metod is doing is to relay this string on to the folder creation (schema) setup so that it is compared with any deferred entries there. In case of a match, the folder creation will recurse down into the subtree marked as deferred.

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 sgtk_api_obj.preview_filesystem_structure( str entity_type, int entity_id, str engine = None )

For details, see the create_filesystem_structure() method.

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.

synchronize_filesystem_structure()

Ensures that the filesystem structure on a local machine is in sync with Shotgun.

list sgtk_api_obj.synchronize_filesystem_structure( bool full_sync = False )

Ensures that the filesystem structure on a local machine is in sync with Shotgun. This synchronization is implicitly carried out as part of the normal folder creation process, however sometimes it is useful to be able to call it on its own. Note that this method is equivalent to the synchronize_folders tank command.

Parameters & Return Value

bool full_sync - If set to true, a complete sync will be carried out. By default, the sync is incremental.
Returns: List of folders that were synchronized.

The Context Object

The context method is used to collect a set of key fields describing the current Context. We sometimes refer to the context as the current work area. 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 tk.context_from_entity(), tk.context_from_entity_dictionary() and tk.context_from_path().

sgtk property

Returns the Sgtk 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 sgtk
>>> tk = sgtk.sgtk_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 sgtk
>>> tk = sgtk.sgtk_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 sgtk
>>> tk = sgtk.sgtk_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 sgtk
>>> tk = sgtk.sgtk_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 Sgtk 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 sgtk
>>> tk = sgtk.sgtk_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 sgtk
>>> tk = sgtk.sgtk_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 sgtk
>>> tk = sgtk.sgtk_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 sgtk
>>> tk = sgtk.sgtk_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 Sgtk 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. The validate parameter can be used to ensure that the method returns all required context fields and if it can't then it will raise a TankError.

dict context_obj.as_template_fields( Template template_obj, Bool validate=False )

Parameters & Return Value

Template template_obj - A template for which suitable values should be returned.
Bool validate - If True then the fields found will be checked to ensure that all expected fields for the context were found and if a field is missing then a TankError will be raised. If False (default behaviour) then this validation is skipped and the method may return an incomplete list of fields.
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 sgtk
>>> tk = sgtk.sgtk_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'}

create_copy_for_user()

Provides the ability to create a copy of an existing Context for a specific user. This is useful if you need to determine a user specific version of a path, e.g. when copying files between different user sandboxes.

Context context_obj.create_copy_for_user(dict user)

Parameters & Return Value

dict user - The user entity that should be set on the copied context
Returns: A new Context object representing the same project, entity, task etc. as the original but with the user that was passed in

Example

>>> import sgtk
>>> tk = sgtk.sgtk_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'}
>>>
>>> copied_ctx = tk.create_copy_for_user({'type': 'HumanUser', 'id': 7, 'name': 'John Snow'})
>>> copied_ctx.user
{'type': 'HumanUser', 'id': 23, 'name': 'John Snow'}

Serialization to/from string

The Context object can be serialized to/deserialized from a string. This can be useful if you need to pass a Context between different processes. As an example, the tk-multi-launchapp uses this mechanism to pass the Context from the app to the Application (e.g. Maya) being launched.

The following two methods are made available for this:

sgtk.context.serialize()

str sgtk.context.serialize(Context context)

Parameters & Return Value

Context context - The Context object to be serialized
Returns: A str representing the Context object

sgtk.context.deserialize()

Context sgtk.context.serialize(str context_str)

Parameters & Return Value

str context_str - The str representation of the context to be deserialized
Returns: A new Context object

Example

>>> import sgtk
>>> tk = sgtk.sgtk_from_path("/studio.08/demo_project")
>>> ctx = tk.context_from_path("/studio.08/demo_project/sequences/AAA/ABC/Lighting/dirk.gently/work")
>>> context_str = sgtk.context.serialize(ctx)
>>> new_ctx = sgtk.context.deserialize(context_str)

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 sgtk
>>> tk = sgtk.sgtk_from_path("/studio.08/demo_project")
>>> template_path = tk.templates['maya_shot_publish']
>>> template_path
<Sgtk TemplatePath maya_shot_publish: sequences/{Sequence}/{Shot}/{Step}/publish/{name}.v{version}.ma>

>>> template_str = tk.templates['maya_publish_name']
>>> template_str
<Sgtk 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
<Sgtk TemplatePath maya_shot_publish: sequences/{Sequence}/{Shot}/{Step}/publish/{name}.v{version}.ma>

>>> template_path.parent
<Sgtk 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 TemplateKey objects.

Example

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

>>> template_str.keys
{'name': <Sgtk StringKey name>, 'version': <Sgtk 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_obj.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': <Sgtk StringKey name>, 'version': <Sgtk 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_obj.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
<Sgtk 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_obj.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 Sgtk, 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 Sgtk 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/sgtk/demo_project_1/sequences/seq_1/shot_2/comp/publish/henry.v003.ma'

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

validate_and_get_fields()

The validate_and_get_fields method takes an input string and determines whether it can be mapped to the template pattern. If it can then the list of matching fields is returned.

dict template_obj.validate_and_get_fields( str path, dict required_fields, list skip_keys )

Parameters & Return Value

str path - The path to validate.
dict required_fields - An optional dictionary of key names to key values. If supplied these values will need to be present in the input path and found by the template.
list skip_keys - An optional list of key names whose values do not need to be constrained for the validation.
Returns: Dictionary of key names to key values if the path validates, otherwise None.

Example

>>> good_path = '/studio_root/sgtk/demo_project_1/sequences/seq_1/shot_2/comp/publish/henry.v003.ma'
>>> template_path.validate_and_get_fields(good_path)
{'Sequence': 'seq_1',
 'Shot': 'shot_2',
 'Step': 'comp',
 'name': 'henry',
 'version': 3}

>>> bad_path = '/studio_root/sgtk/demo_project_1/shot_2/comp/publish/henry.v003.ma'
>>> template_path.validate_and_get_fields(bad_path)
None

validate()

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

bool template_obj.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/sgtk/demo_project_1/sequences/seq_1/shot_2/comp/publish/henry.v003.ma'
>>> template_path.validate(good_path)
True

>>> bad_path = '/studio_root/sgtk/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_obj.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/sgtk/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}

The Template Key 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 sgtk
>>> tk = sgtk.sgtk_from_path("/studio.08/demo_project")
>>> template_path = tk.templates['nuke_asset_render']
>>> str_key = template_path.keys['Asset']
>>> str_key
<Sgtk StringKey Asset>

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

>>> seq_key = template_path.keys['frame']
>>> seq_key
<Sgtk 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 template_key_obj.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 template_key_obj.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 template_key_obj.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

The Hook Base Class

Hooks are snippets of code that can be customized as part of the configuration. You can use hooks with the Core API (we call those core hooks) and with apps and engines. Hooks are a central concept in the configuration of Sgtk. A hook is like a configuration setting, but instead of specifying a simple value, a piece of code represents the value. We use hooks whenever there is a need to expose code and allow it to be customized. Examples of when this is useful is Disk I/O, launching of applications and permissions control. You can read more about how to use hooks here:

LINKBOX_DOC:11:Administering the Shotgun Pipeline Toolkit

Hooks are implemented in a python file and they all derive from a Hook base class. They all need to implement an execute() method which Sgtk will call. The execute method needs to match the argument signature required by Sgtk. The example below shows the before register publish hook, which is called just before Sgtk creates a publish in shotgun. The idea with this hook is that you can modify the data that gets created in Shotgun as part of the publish. For example, if you are using custom publish fields, these can be set here. The default implementation is a pass through which just returns the same data dictionary that was passed to the hook:

from sgtk import Hook

class BeforeRegisterPublish(Hook):

    def execute(self, shotgun_data, context, **kwargs):
        """
        Gets executed just before a new publish entity is created in Shotgun.

        :param shotgun_data: All the data which will be passed to the shotgun create call
        :param context: The context of the publish

        :returns: return (potentially) modified data dictionary
        """

        # default implementation is just a pass-through.
        return shotgun_data

Note the **kwargs parameter - this is important for future compatibility! In the future, additional arguments may be passed to the hook and if you don't want your hook to break, make sure that you have a **kwargs parameter to consume such arguments.

parent property

The parent object to the exeucting hook. This varies with the type of hook that is being executed. For a hook that runs inside an app or an engine, the parent object will be the app or engine instance. For core hooks, the parent object will be the API object.

Note that if you need to access Shotgun inside your hook, you can do this by calling self.parent.shotgun since both Apps, Engines and the Core API has a shotgun property.

execute()

Executes the actual hook logic.

hook_obj.execute( ... )

This method will be called by the API when the hook is evaluated. Parameters passed depend on the hook. Return value depends on the hook.

get_publish_path()

Returns the path on disk for a publish entity in Shotgun.

Use this method if you have shotgun publish entity and want to get a local path on disk. This method will ensure that however the publish path is encoding the data describing with the file is located, a local path is returned.

Note: If you have a collection of items, use the get_publish_paths() method instead.

str hook_obj.get_publish_path( dict sg_publish_data )

Parameters & Return Value

dict sg_publish_data - Shotgun dictionary containing information about a publish. Needs to at least contain a type, id and a path key.
Returns: String representing a local path on disk.

get_publish_paths()

Returns several local paths on disk given a list of shotgun data dictionaries representing publishes. See get_publish_path() for details.

list hook_obj.get_publish_paths( list sg_publish_data_list )

Parameters & Return Value

list sg_publish_data_list - List of Shotgun dictionaries containing information publishes. Needs to at least contain a type, id and a path key.
Returns: List of strings representing local paths on disk.

load_framework()

Loads and returns a framework given an environment instance name. Note that this only works for app and engine hooks and not for core hooks.

framework_instance hook_obj.load_framework( str framework_instance_name )

Parameters & Return Value

str framework_instance_name - name of the framework, as defined in an environment config.
Returns: framework instance

If you want to encapsulate functionality in reusable libraries, you can use Frameworks. Frameworks are just like Apps and Engines, but typically don't have a UI or any front facing functionality. Instead, they expose an interface that can be used by apps and engines.

Inside a hook you can use the method Hook.load_framework(), like this:

class SomeHook(Hook):

    def execute(self, **kwargs):

        # first get a framework handle. This object is similar to an app or engine object
        fw = self.load_framework("my-framework_v1.x.x")
        # now just like with an app or an engine, if you want to access code in the python
        # folder, you can do import_plugin
        module = fw.import_module("some_module")

Note that you need to have the framework defined in your environment. The my-framework_v1.x.x parameter passed to the load_framework method is the instance name of the framework in the environment. For example, it could look like this:

engines:
  # all engine and app defs here...

frameworks:
  # define the pxm-framework that we are using in the hook
  my-framework_v1.x.x:
    location: {type: dev, path: /some/path}

Utility Functions

get_current_user()

Retrieves a shotgun user dict for the current user. By default the current user is retrieved from the OS but this behaviour can be overridden by customising the get_current_login core hook. This method connects to shotgun.

dict sgtk.util.get_current_user( Sgtk tk )

Parameters and Return Value

Sgtk tk - Sgtk API Instance.
Returns: Returns None if the user is not found in shotgun, otherwise it returns a dictionary of user data comprising the following fields:
- type
- id
- name
- image (thumbnail url)
- email
- login

Example

>>> sgtk.util.get_current_user(tk)

{'name': 'John Snow',
 'image': 'http://some_url/files/0000/0000/0482/232/image.jpg',
 'email': 'john.snow@shotgunsoftware.com',
 'login': 'jsnow',
 '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 sgtk.util.find_publish( Sgtk tk, list list_of_paths, list filters, list fields )

Parameters and Return Value

Sgtk tk - Sgtk 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'
>>> sgtk.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 sgtk.util.create_event_log_entry( Sgtk tk, Context context, str event_type, str description, dict metadata)

Required Parameters

Sgtk tk - a Sgtk 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

>>> sgtk.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 Published File in Shotgun.

dict sgtk.util.register_publish( Sgtk tk, Context context, str path, str name, int version_number, **kwargs )

Required Parameters

Sgtk tk - a Sgtk 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.
list dependency_ids - a list of Shotgun publish ids (as ints) that should be registered as dependencies.
str published_file_type - a published file type in the form of a string. If the type specified does not already exist in Shotgun, it will be automatically created.
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 upload 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.
dict version_entity - a shotgun entity dictionary with id and type representing a version entity that this published file should be linked to
dict sg_fields - a dictionary of additional Shotgun fields/values to set on the PublishedFile entity. This will not overwrite any field values provided in the default parameters.

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'
>>> sgtk.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': 'primary', '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 Sgtk 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 sgtk.util.get_entity_type_display_name( Sgtk tk, str entity_type_code )

Parameters and Return Value

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

get_published_file_entity_type()

Note: This method is only really relevant for clients who have been using version 0.13 or earlier of the Core API.

In Toolkit Core v0.14, the default Shotgun publish entity that the system is using was switched from TankPublishedFile to PublishedFile. If you are running a Toolkit setup which was originally set up based on v0.13 or earlier, you may still be creating TankPublishedFile entities when publishing to Shotgun, or PublishedFile entities, or even both!

This method returns which Shotgun entity is being used in conjunction with publishing for the current configuration.

str sgtk.util.get_published_file_entity_type( Sgtk tk )

Parameters and Return Value

Sgtk tk - Sgtk API Instance.
Returns: A string. Either PublishedFile or TankPublishedFile

download_url()

Convenience method that downloads a file from a given url. This method will take into account any proxy settings which have been defined in the Shotgun connection parameters.

sgtk.util.download_url( Shotgun sg, str url, str location )

Parameters and Return Value

Shotgun sg - Shotgun API instance
str url - http or https url from which content should be downloaded.
str location - path on disk where the content should be written. If this file already exists, it will be overwritten.
Returns: Nothing

Core API Reference

Introduction

Creating an API Instance

sgtk.sgtk_from_path()

sgtk.sgtk_from_entity()

Executing tank commands via the API

sgtk.list_commands()

sgtk_api_obj.list_commands()

sgtk.get_command() / sgtk_api_obj.get_command()

The SgtkSystemCommand class

parameters property

description property

name property

category property

set_logger()

execute()

The Sgtk API Instance Object

roots property

templates property

reload_templates() method

project_path property

shotgun property

version property

documentation_url property

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

context_from_entity_dictionary()

create_filesystem_structure()

preview_filesystem_structure()

synchronize_filesystem_structure()

The Context Object

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

create_copy_for_user()

Serialization to/from string

sgtk.context.serialize()

sgtk.context.deserialize()

The Template Object

definition property

parent property

keys property

missing_keys()

is_optional()

apply_fields()

validate_and_get_fields()

validate()

get_fields()

The Template Key Object

name property

default property

choices property

is_abstract property

str_from_value()

value_from_str()

validate()

The Hook Base Class

parent property

execute()

get_publish_path()

get_publish_paths()

load_framework()

Utility Functions

get_current_user()

find_publish()

The `SgtkSystemCommand` class