-
Notifications
You must be signed in to change notification settings - Fork 114
Core API Reference
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.
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.
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.
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:
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']
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']
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 thesgtk.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>
Commands are managed via the SgtkSystemCommand
class which provides methods
and accessors for both execution and introspection. The following properties
and methods exist:
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" }
}
Returns a brief description of this command.
Returns the name of this command.
Returns the category for this command. This is typically a short string like "Admin".
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 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 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.
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" }
Dictionary of all templates in the system, keyed by template name.
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()
Path to the primary root directory for a project.
A Shotgun API Handle that is connected to the shotgun server associated with this Sgtk API instance.
The version of the Sgtk Core API (e.g. 'v0.2.3').
Returns the relevant documentation url for the Core API.
Returns the name of the Pipeline Configuration associated with this API instance.
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>
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.
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.
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.
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'}
Factory method that constructs an empty Context object.
Context
sgtk_api_obj.context_empty()
Parameters & Return Value
- Returns: a Context object.
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.
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.
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 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 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 thecreate_filesystem_structure()
documentation. -
Returns: a list of folders and files that would be processed if the create_filesystem_strcture() method was to be executed.
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 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()
.
Returns the Sgtk API object associated with this Context object.
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'}
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'}
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'}
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'}
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'}
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.
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']
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']
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'
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.
dict
context_obj.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 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'}
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'}
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:
str
sgtk.context.serialize(Context
context)
Parameters & Return Value
-
Context
context - The Context object to be serialized -
Returns: A
str
representing the Context object
Context
sgtk.context.serialize(str
context_str)
Parameters & Return Value
-
str
context_str - Thestr
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)
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}>
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}'
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
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>}
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']
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
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'
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
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
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}
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>
The name that the template will use to refer to the key.
The value this key will use if no value is provided.
A list of values that this key may use. Any value not in this list will be considered invalid.
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.
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'
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
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
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.
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.
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.
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.
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.
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}
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)
- 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}
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'}}
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 formCompany_Item_Action
. Examples include:Shotgun_Asset_New
,Shotgun_Asset_Change
andShotgun_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'
}
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
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.
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
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
orTankPublishedFile
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