Warning! This documentation is outdated. Visit help center for the latest documentation.

API reference

Discover the Python API for ftrack.

ftrack

class ftrack.ABCMeta[source]

Metaclass for defining Abstract Base Classes (ABCs).

Use this metaclass to create an ABC. An ABC can be subclassed directly, and then acts as a mix-in class. You can also register unrelated concrete classes (even built-in classes) and unrelated ABCs as ‘virtual subclasses’ – these and their descendants will be considered subclasses of the registering ABC by the built-in issubclass() function, but the registering ABC won’t show up in their MRO (Method Resolution Order) nor will method implementations defined by the registering ABC be callable (not even via super()).

__init__

x.__init__(...) initializes x; see help(type(x)) for signature

mro() → list

return a type’s method resolution order

register(subclass)[source]

Register a virtual subclass of an ABC.

class ftrack.Accessor[source]

Provide data access to a location.

A location represents a specific storage, but access to that storage may vary. For example, both local filesystem and FTP access may be possible for the same storage. An accessor implements these different ways of accessing the same data location.

As different accessors may access the same location, only part of a data path that is commonly understood may be stored in the database. The format of this path should be a contract between the accessors that require access to the same location and is left as an implementation detail. As such, this system provides no guarantee that two different accessors can provide access to the same location, though this is a clear goal. The path stored centrally is referred to as the resource identifier and should be used when calling any of the accessor methods that accept a resourceIdentifier argument.

__init__()[source]

Initialise location accessor.

exists(resourceIdentifier)[source]

Return if resourceIdentifier is valid and exists in location.

getContainer(resourceIdentifier)[source]

Return resourceIdentifier of container for resourceIdentifier.

Raise AccessorParentResourceNotFoundError if container of resourceIdentifier could not be determined.

getFilesystemPath(resourceIdentifier)[source]

Return filesystem path for resourceIdentifier.

Raise AccessorFilesystemPathError if filesystem path could not be determined from resourceIdentifier or AccessorUnsupportedOperationError if retrieving filesystem paths is not supported by this accessor.

getUrl(resourceIdentifier)[source]

Return URL for resourceIdentifier.

Raise ftrack.AccessorUrlError if URL could not be determined from resourceIdentifier* or ftrack.AccessorUnsupportedOperationError if retrieving URL’s is not supported by this accessor.

isContainer(resourceIdentifier)[source]

Return whether resourceIdentifier refers to a container.

isFile(resourceIdentifier)[source]

Return whether resourceIdentifier refers to a file.

isSequence(resourceIdentifier)[source]

Return whether resourceIdentifier refers to a file sequence.

list(resourceIdentifier)[source]

Return list of entries in resourceIdentifier container.

Each entry in the returned list should be a valid resource identifier.

Raise AccessorResourceNotFoundError if resourceIdentifier does not exist or AccessorResourceInvalidError if resourceIdentifier is not a container.

makeContainer(resourceIdentifier, recursive=True)[source]

Make a container at resourceIdentifier.

If recursive is True, also make any intermediate containers.

Should silently ignore existing containers and not recreate them.

open(resourceIdentifier, mode='rb')[source]

Return Data for resourceIdentifier.

remove(resourceIdentifier)[source]

Remove resourceIdentifier.

Raise AccessorResourceNotFoundError if resourceIdentifier does not exist.

removeContainer(resourceIdentifier)[source]

Remove container at resourceIdentifier.

exception ftrack.AccessorContainerNotEmptyError(resourceIdentifier, **kw)[source]

Raise when container is not empty.

__init__(resourceIdentifier, **kw)
args
defaultMessage = 'Container is not empty: {resourceIdentifier}'
message
exception ftrack.AccessorError(message=None, details=None, **kw)[source]

Base for errors associated with accessors.

__init__(message=None, details=None, **kw)

Initialise exception with message.

If message is None, the class ‘defaultMessage’ will be used.

args
defaultMessage = 'Unspecified accessor error'
message
exception ftrack.AccessorFilesystemPathError(resourceIdentifier, **kw)[source]

Raise when a error related to an accessor filesystem path occurs.

__init__(resourceIdentifier, **kw)
args
defaultMessage = 'Could not determine filesystem path from resource identifier: {resourceIdentifier}.'
message
exception ftrack.AccessorOperationFailedError(operation='', resourceIdentifier=None, **kw)[source]

Base for failed operations on accessors.

__init__(operation='', resourceIdentifier=None, **kw)[source]
args
defaultMessage = 'Operation {operation} failed: {details}'
message
exception ftrack.AccessorParentResourceNotFoundError(resourceIdentifier, **kw)[source]

Raise when a parent resource (such as directory) is not found.

__init__(resourceIdentifier, **kw)
args
defaultMessage = 'Parent resource is missing: {resourceIdentifier}'
message
exception ftrack.AccessorPermissionDeniedError(operation='', resourceIdentifier=None, **kw)[source]

Raise when permission denied.

__init__(operation='', resourceIdentifier=None, **kw)
args
defaultMessage = 'Cannot {operation} {resourceIdentifier}. Permission denied.'
message
exception ftrack.AccessorResourceError(resourceIdentifier, **kw)[source]

Base for errors associated with specific resource.

__init__(resourceIdentifier, **kw)[source]
args
defaultMessage = 'Unspecified resource error: {resourceIdentifier}'
message
exception ftrack.AccessorResourceIdentifierError(resourceIdentifier, **kw)[source]

Raise when a error related to a resourceIdentifier occurs.

__init__(resourceIdentifier, **kw)[source]
args
defaultMessage = 'Resource identifier is invalid: {resourceIdentifier}.'
message
exception ftrack.AccessorResourceInvalidError(resourceIdentifier, **kw)[source]

Raise when a resource is not the right type.

__init__(resourceIdentifier, **kw)
args
defaultMessage = 'Resource invalid: {resourceIdentifier}'
message
exception ftrack.AccessorResourceNotFoundError(resourceIdentifier, **kw)[source]

Raise when a required resource is not found.

__init__(resourceIdentifier, **kw)
args
defaultMessage = 'Resource not found: {resourceIdentifier}'
message
exception ftrack.AccessorUnsupportedOperationError(operation='', resourceIdentifier=None, **kw)[source]

Raise when operation is unsupported.

__init__(operation='', resourceIdentifier=None, **kw)
args
defaultMessage = 'Operation {operation} unsupported.'
message
class ftrack.Action[source]

Action base class.

__init__()[source]

Initialise action handler.

description = None
discover(event)[source]

Return action config.

icon = None
identifier = None
label = None
launch(event)[source]

Callback method for custom action.

register()[source]

Register action.

variant = None
class ftrack.ActivityEvent(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getData()[source]
getEntity()[source]
getEntityRef()
getId()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.Asset(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
createVersion(comment='', taskid=None)[source]

Create an AssetVersion for publishing

Parameters:
  • comment – ‘this is a comment’
  • taskid – ‘id-of-a-task’
Return type:

AssetVersion

delete()
get(key)
getEntityRef()
getId()[source]
getMeta(key=None)

Get metadata from an object. This method can be used to retrive meta data from an object. The data is stored in key/value pairs where key and value are strings.

This method can also be used without any arguments to retrive a dict with all metadata key/value pairs attached to this object.

Parameters:key – A string representing the key or None to retrive all key/value pairs on this object.
Return type:string or dict
getName()[source]
getParent()

Get parent object from this object

Return type:FTObject of that type
getParents()

Get parent object from this object

Return type:list owith items of that type
getType()[source]
getVersions(*args, **argv)[source]

Get AssetVersions

Parameters:componentNames – A list with names of components that the versions must have at least one of
Return type:FTList of AssetVersions
keys()

Return keys accessible using get/set methods.

metaKeys()

Return keys accessible using getMeta/setMeta methods.

publish()[source]

Publish the asset together with its new version and components

Return type:bool
set(key, value=None)
setMeta(key, value=None)

Set metadata on an object. This method can be used to store arbitrary data on an object. The data is stored in key/value pairs where key and value are strings.

This method also accepts a dict with key/value pairs

Parameters:
  • key – A string representing the key or a dict with key/value pairs.
  • value – A string representing the value or None if key is a dict.
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.AssetType(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()[source]
getName()[source]
getShort()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.AssetVersion(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
addUsesVersions(versions)[source]

Add links to versions to inform that they are used by this version

Parameters:versions (list) – A list with AssetVersion that should be linked to this version.
createComponent(name='main', path='', systemType=None, file=None, location='auto', manageData=None, size=None)[source]

Create a Component with name.

The name property defaults to ‘main’ and needs to be unique for each version. Will raise ftrack.FTrackError if the name already exists.

path can be a string representing a filesystem path to the data to use for the component. The path can also be specified as a sequence string, in which case a sequence component with child components for each item in the sequence will be created automatically. The accepted format for a sequence is ‘{head}{padding}{tail} [{ranges}]’. For example:

'/path/to/file.%04d.ext [1-5, 7, 8, 10-20]'

If location is specified, then the created component will be automatically added to that location. The returned component will also be configured with that location set as its current location. It should be an instance of ftrack.Location, the string ‘auto’ (default) or None.

Note

If path is not specified the location property will be ignored.

If location is set to ‘auto’ the most suitable location will be selected and used. If no suitable location is found the component will be created without being added to a location.

If name is set to be ‘ftrackreview-mp4’, ‘ftrackreview-webm’ or ‘ftrackreview-image’ when ‘auto’ is specified the review location will be used.

If the specified location is of type ftrack.Location, it needs to be configured with a location plugin that is loaded in the current session. If the component fails to be added to the specified location, it will be removed and the underlying exception will be raised.

Note

If a location is not specified at component creation time then no path data will be stored in ftrack and the data not moved in any way. Instead, the returned component will be configured with a special ‘origin’ location allowing the component to be added to other locations manually using ftrack.Location.addComponent().

If manageData is True then manage transfer of data to the location. If False, assume the data has been managed externally and just record the component as present in that location. If manageData is None, let the location decide if data should be managed.

Note

If no location is specified, manageData will be ignored.

An optional versionId can be passed to specify the version entity that this component should be linked to.

Warning

A component cannot currently be attached to a version after creation.

If systemType is not specified it will be inferred from the path. If no path set it will default to ‘file’.

size is the size of the component in bytes. size will be calculated automatically from the path if not specified. If size is specified for a sequence it will be stored for the sequence and for child components as size / number of child components.

file is a deprecated synonym for path. Please update code to use path in future.

createNote(note, category='auto', recipients=None)

Create note with text note.

Optional category can be specified to set the note category of the note. Can be either NoteCategory or category id. If set to auto the default note category setting will be used.

Recipients can be specified by setting recipients to be a list of User or user ids.

createTake(name='main', path='', systemType=None, file=None, location='auto', manageData=None, size=None)

Create a Component with name.

The name property defaults to ‘main’ and needs to be unique for each version. Will raise ftrack.FTrackError if the name already exists.

path can be a string representing a filesystem path to the data to use for the component. The path can also be specified as a sequence string, in which case a sequence component with child components for each item in the sequence will be created automatically. The accepted format for a sequence is ‘{head}{padding}{tail} [{ranges}]’. For example:

'/path/to/file.%04d.ext [1-5, 7, 8, 10-20]'

If location is specified, then the created component will be automatically added to that location. The returned component will also be configured with that location set as its current location. It should be an instance of ftrack.Location, the string ‘auto’ (default) or None.

Note

If path is not specified the location property will be ignored.

If location is set to ‘auto’ the most suitable location will be selected and used. If no suitable location is found the component will be created without being added to a location.

If name is set to be ‘ftrackreview-mp4’, ‘ftrackreview-webm’ or ‘ftrackreview-image’ when ‘auto’ is specified the review location will be used.

If the specified location is of type ftrack.Location, it needs to be configured with a location plugin that is loaded in the current session. If the component fails to be added to the specified location, it will be removed and the underlying exception will be raised.

Note

If a location is not specified at component creation time then no path data will be stored in ftrack and the data not moved in any way. Instead, the returned component will be configured with a special ‘origin’ location allowing the component to be added to other locations manually using ftrack.Location.addComponent().

If manageData is True then manage transfer of data to the location. If False, assume the data has been managed externally and just record the component as present in that location. If manageData is None, let the location decide if data should be managed.

Note

If no location is specified, manageData will be ignored.

An optional versionId can be passed to specify the version entity that this component should be linked to.

Warning

A component cannot currently be attached to a version after creation.

If systemType is not specified it will be inferred from the path. If no path set it will default to ‘file’.

size is the size of the component in bytes. size will be calculated automatically from the path if not specified. If size is specified for a sequence it will be stored for the sequence and for child components as size / number of child components.

file is a deprecated synonym for path. Please update code to use path in future.

createThumbnail(file, fileName='image.jpg')

Create thumbnail from file.

delete()
get(key)
getAsset()[source]

Get the asset that this version belongs to

Return type:Asset
getComment()[source]
getComponent(name='main', location='auto')[source]

Return component with name.

location can be set to specify the initial location the retrieved component should be switched to. See :py:class:`~ftrack.Component` for more information on supported values for *location.

getComponents(location='auto')[source]

Return list of components attached to this asset version.

location can be set to specify the initial location the retrieved component should be switched to. See :py:class:`~ftrack.Component` for more information on supported values for *location.

getDate()[source]
getDefaultRecipients()

Get default recipients for an object

Return type:list with User objects
getEntityRef()
getId()[source]
getMeta(key=None)

Get metadata from an object. This method can be used to retrive meta data from an object. The data is stored in key/value pairs where key and value are strings.

This method can also be used without any arguments to retrive a dict with all metadata key/value pairs attached to this object.

Parameters:key – A string representing the key or None to retrive all key/value pairs on this object.
Return type:string or dict
getNotes()

Fetch notes from an entity, this will include replies.

getOwner()[source]
getParent()

Get parent object from this object

Return type:FTObject of that type
getParents()

Get parent object from this object

Return type:list owith items of that type
getStatus()

Return the status of the object or None if it has no status.

getTake(name='main', location='auto')

Return component with name.

location can be set to specify the initial location the retrieved component should be switched to. See :py:class:`~ftrack.Component` for more information on supported values for *location.

getTakes(location='auto')

Return list of components attached to this asset version.

location can be set to specify the initial location the retrieved component should be switched to. See :py:class:`~ftrack.Component` for more information on supported values for *location.

getTask()[source]

Get the task this version is connected to

Return type:Task
getThumbnail()

Get a url to the thumbnail.

getURL()

Return url that can be used to view this entity in a browser.

getUser()[source]

Get the user that published this version

Return type:User
getVersion()[source]
getWebWidgetUrl(name, theme='dark')

Return url that can be used is a qt webwidget.

name should be the name of the ftrack panel. theme is optional.

keys()

Return keys accessible using get/set methods.

metaKeys()

Return keys accessible using getMeta/setMeta methods.

newComponents = None
publish()[source]
removeUsesVersions(versions)[source]

Remove versions that are used in this version

Parameters:versions (list) – A list with AssetVersion that should be un-linked from this version.
set(key, value=None)
setMeta(key, value=None)

Set metadata on an object. This method can be used to store arbitrary data on an object. The data is stored in key/value pairs where key and value are strings.

This method also accepts a dict with key/value pairs

Parameters:
  • key – A string representing the key or a dict with key/value pairs.
  • value – A string representing the value or None if key is a dict.
setStatus(status)

Set status of the object

Parameters:statusStatus the status object that should be set
setThumbnail(component)

Set component as thumbnail.

usedInVersions()[source]

Returns versions this version is used in

Return type:list with AssetVersion
usesVersions()[source]

Returns versions used in this version

Return type:list with AssetVersion
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.Assetable[source]

Mixin to make a class assetable.

__init__

x.__init__(...) initializes x; see help(type(x)) for signature

createAsset(name, assetType, task=None)[source]

Create a new asset or return existing.

name is the name of the asset and assetType is the type of the asset defined by its short name. A task or task id can also be passed in which will be used as the default task when versions are created on this asset.

createAttachment(file, fileName=None, isThumb=False)[source]

Legacy method to attach files to objects.

class ftrack.BaseObject[source]

Mixin representing a context.

__init__

x.__init__(...) initializes x; see help(type(x)) for signature

create(objectType, name, statusId=None, typeId=None, priorityId=None)[source]

Create a context from objectType with name.

createEpisode(name)[source]

Create an episode from name.

createSequence(name)[source]

Create a sequence from name.

createShot(name)[source]

Create a shot from name.

createTask(name, taskType=None, taskStatus=None)[source]

Create a task from name, taskType and taskStatus.

getChildren(objectType=None, depth=1)[source]

Get attached Children (not tasks)

Return type:FTList of Children
getEpisodes()[source]
getSequences()[source]

Get attached Sequences

Return type:FTList of Sequence
getShots()[source]
getTasks(*args, **argv)[source]

Get attached Tasks

Parameters:
  • userslist with usernames like [‘username1’,’username2’] to filter out tasks
  • taskTypeslist representing task types. Can be TaskType objects, their IDs or their names.
  • taskStatuseslist representing task statuses. Can be TaskStatus objects, their IDs or their names.
  • stateslist with states. Possible states are NOT_STARTED, IN_PROGRESS, DONE, BLOCKED which are availible from the ftrack module
  • activeProjectsOnlybool Default to True. specifying if only to query active projects.
  • includeChildrenbool Default to False. childrens tasks should be included.
  • includePathbool Default to False. specifying if the path should be added to each task. Much faster than useing getParents on each task afterwards.
Return type:

FTList with Task

class ftrack.Booking(id=None, dict=None, eagerload=None)[source]
PROJECT = 'project'
VACATION = 'vacation'
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()
getMeta(key=None)

Get metadata from an object. This method can be used to retrive meta data from an object. The data is stored in key/value pairs where key and value are strings.

This method can also be used without any arguments to retrive a dict with all metadata key/value pairs attached to this object.

Parameters:key – A string representing the key or None to retrive all key/value pairs on this object.
Return type:string or dict
getParent()

Get parent object from this object

Return type:FTObject of that type
getParents()

Get parent object from this object

Return type:list owith items of that type
getProject()[source]

Return the project for this booking

getUser()[source]

Return the user for this booking

keys()

Return keys accessible using get/set methods.

metaKeys()

Return keys accessible using getMeta/setMeta methods.

set(key, value=None)
setMeta(key, value=None)

Set metadata on an object. This method can be used to store arbitrary data on an object. The data is stored in key/value pairs where key and value are strings.

This method also accepts a dict with key/value pairs

Parameters:
  • key – A string representing the key or a dict with key/value pairs.
  • value – A string representing the value or None if key is a dict.
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.ClassicStructure(fieldSeparator='_', *args, **kwargs)[source]

Classic structure supporting Components only.

Components will be examined and paths generated to support a typical studio structure.

TODO:Give examples!
__init__(fieldSeparator='_', *args, **kwargs)[source]

Initialise structure.

fieldSeparator will be used to join fields in filenames.

getResourceIdentifier(entity)[source]

Return a resourceIdentifier for supplied entity.

class ftrack.Component(id=None, dict=None, eagerload=None, location='auto', resourceIdentifier=None)[source]
CONTAINER_TYPES = ['container', 'sequence']
__init__(id=None, dict=None, eagerload=None, location='auto', resourceIdentifier=None)[source]

Initialise Component with either id or dict.

Optional parameter resourceIdentifier will be set on the Component if specified.

location can be set to specify the initial location this component should be switched to. It should be an instance of ftrack.Location, the string ‘auto’ (default) or None.

If a specific location instance is specified, but the component does not exist in that location then ftrack.LocationError will be raised.

If ‘auto’ is specified then the most suitable location will be used. If no suitable location is found then the location property will be set to None and no location based information available.

Use None for location to manage the switching manually later on.

See ftrack.Component.switchLocation() for more information.

Note

If both location and resourceIdentifier are set then no location switching will occur and instead the passed values will just be set directly. It is the callers responsibility to ensure the values are appropriate.

addMember(component)[source]

Add a component as a member of this container.

delete()
get(key)
getAvailability(locationIds=None)[source]

Return availability in locations with locationIds.

If locationIds is None, all known locations will be checked.

Return a dictionary of {locationId:percentage_availability}

getContainer(location='auto')[source]

Return the Container of this component.

location can be set to specify the initial location to switch to on the retrieved container.

It should be an instance of ftrack.Location, the string ‘auto’ (default) or None.

If a specific location instance is specified, but the container does not exist in that location then ftrack.LocationError will be raised.

If ‘auto’ is specified then will attempt to use the current location of this child component. If the container does not exist in that location then it will have no location set.

Use None for location to manage the switching manually later on.

getEntityRef()
getFile()[source]

Return internal resourceIdentifier.

Deprecated since version 2.0: Use getResourceIdentifier() instead.

getFileType()[source]

Return component file type.

getFilesystemPath()[source]

Return filesystem path.

Return the filesystem path for the component in currently active location. Will return None if no path can be calculated.

getId()[source]

Return component id.

getImportPath()[source]

Return accessible component path.

Deprecated since version 2.0: Use getFilesystemPath() instead.

getLocation()[source]

Return current location.

getMembers(location='auto')[source]

Return contained members.

location can be set to specify the initial location to switch to for each member.

It should be an instance of ftrack.Location, the string ‘auto’ (default) or None.

If a specific location instance is specified, but a member does not exist in that location then ftrack.LocationError will be raised.

If ‘auto’ is specified then will attempt to use the current location of this container component. If the member does not exist in that location then it will have no location set.

Use None for location to manage the switching manually later on.

Raise TypeError if not a container.

getMeta(key=None)

Get metadata from an object. This method can be used to retrive meta data from an object. The data is stored in key/value pairs where key and value are strings.

This method can also be used without any arguments to retrive a dict with all metadata key/value pairs attached to this object.

Parameters:key – A string representing the key or None to retrive all key/value pairs on this object.
Return type:string or dict
getName()[source]

Return component name.

getPadding()[source]

Return padding value for sequence.

getParent()

Get parent object from this object

Return type:FTObject of that type
getParents()

Get parent object from this object

Return type:list owith items of that type
getResourceIdentifier()[source]

Return component resource identifier.

getSize()[source]

Return size of component in bytes.

getSystemType()[source]

Return component system type.

getUrl()[source]

Return URL.

Return the URL for the component in currently active location. Will return None if no path can be calculated.

getVersion()[source]

Return the AssetVersion this component belongs to.

If no version is associated with this component then return None.

isContainer()[source]

Return whether this component is a container for others.

isSequence()[source]

Return whether component is a sequence.

keys()

Return keys accessible using get/set methods.

metaKeys()

Return keys accessible using getMeta/setMeta methods.

removeMember(component)[source]

Remove component from being a member of this container.

set(key, value=None)
setMeta(key, value=None)

Set metadata on an object. This method can be used to store arbitrary data on an object. The data is stored in key/value pairs where key and value are strings.

This method also accepts a dict with key/value pairs

Parameters:
  • key – A string representing the key or a dict with key/value pairs.
  • value – A string representing the value or None if key is a dict.
setPadding(padding)[source]

Set padding value for sequence.

padding should be an integer representing the width of indexes in the sequence, with 0 representing no padding. For example, ‘0001’ would be represented as padding=4 whilst ‘1’ would be padding=0.

Note

Will not affect any calculated paths stored in the database.

setResourceIdentifier(resourceIdentifier)[source]

Set component resource identifier to resourceIdentifier.

setSize(size)[source]

Set the size of a component in bytes.

switchLocation(location)[source]

Update the current location of the component.

location should be a ftrack.Location instance, the string ‘auto’ or None.

Will update the resourceIdentifier property of the component to reflect the specified location.

If a specific location instance is specified, but the component does not exist in that location then ftrack.LocationError will be raised.

If ‘auto’ is specified then the most suitable location will be used. If no suitable location is found then ftrack.ComponentNotInAnyLocationError will be raised.

If location is specified as None then any location relevant properties will be reset to None and the component will no longer reflect the component in a specific location.

xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
exception ftrack.ComponentInLocationError(componentId, locationId, **kw)[source]

Raise when component already exists in location.

__init__(componentId, locationId, **kw)[source]

Initialise with componentId and locationId.

args
defaultMessage = 'Component "{componentId}" already exists in location "{locationId}".'
message
exception ftrack.ComponentNotInAnyLocationError(message=None, details=None, **kw)[source]

Raise when component not available in any location.

__init__(message=None, details=None, **kw)

Initialise exception with message.

If message is None, the class ‘defaultMessage’ will be used.

args
defaultMessage = 'Component not available in any location.'
message
exception ftrack.ComponentNotInLocationError(componentIds, locationId, **kw)[source]

Raise when component(s) not in location.

__init__(componentIds, locationId, **kw)[source]

Initialise with componentIds and locationId.

args
defaultMessage = 'Component(s) {componentIds} not found in location "{locationId}".'
getMissingIds()[source]

Return a list of components missing in the location.

message
class ftrack.ConnectStructure(prefix='')[source]

Connect structure supporting directory generation for connect.

__init__(prefix='')

Initialise structure.

getResourceIdentifier(entity)[source]

Return a resourceIdentifier for supplied entity.

Construct the returned resourceIdentifier by examining the hierarchy of entities for the supplied entity and using the names of those to build a corresponding directory structure hierarchy. Then append any existing resource identifier of entity to that structure.

The following is the pattern used for the hierarchy:

/{disk}/{projectFolder}/{assetPathPrefix}/ {sequenceName|’assetb’}/{shotName|assetBuildName}/{assetType}/{assetName}/{versionNumber}/ {projectName}_{sequenceName|’assetb’}_{shotName|assetBuildName}_{assetType}_{assetName}_{versionNumber}_{componentName}.{frame|range}.{extension}

Example of a resulting resourceIdentifier for a shot render:

/demo/test/ftrack/assets/sc010/010/img/spacestationLights/v001/ test_sc010_010_img_spacestationLights_v001_main.%04d.exr

Example of a resulting resourceIdentifier for an asset build:

/demo/test/ftrack/assets/assetb/spacestation/geo/model/v001/ test_assetb_spacestation_geo_model_v001_main.mb

Note

The returned resourceIdentifier is always an absolute path.

Note

If entity is a member of a container then the container will be used to determine the directory structure for the component. This ensures that all members of a container end up in the same parent directory structure.

class ftrack.Data[source]

File-like object for manipulating data.

__init__()[source]

Initialise data access.

close()[source]

Flush buffers and prevent further access.

flush()[source]

Flush buffers ensuring data written.

read(limit=None)[source]

Return content from current position up to limit.

seek(offset, whence=0)[source]

Move internal pointer by offset.

The whence argument is optional and defaults to os.SEEK_SET or 0 (absolute file positioning); other values are os.SEEK_CUR or 1 (seek relative to the current position) and os.SEEK_END or 2 (seek relative to the file’s end).

tell()[source]

Return current position of internal pointer.

write(content)[source]

Write content at current position.

class ftrack.Dependable[source]
__init__

x.__init__(...) initializes x; see help(type(x)) for signature

addPredecessor(task)[source]

Add a dependency from another task to this task

Parameters:task – The predecessor task
addSuccessor(task)[source]

Add a dependency from this task to another task

Parameters:task – The successor task
getPredecessors()[source]

Returns a list of items that this item depends on

Return type:list
getSuccessors()[source]

Returns a list of items that depend on this object

Return type:list
removePredecessor(task)[source]

remove a dependency another task to this task

Parameters:task – The predecessor task
removeSuccessor(task)[source]

remove a dependency from this task to another task

Parameters:task – The successor task
class ftrack.Disk(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()[source]
getName()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.DiskAccessor(prefix, **kw)[source]

Provide disk access to a location.

Expect resource identifiers to refer to relative filesystem paths.

__init__(prefix, **kw)[source]

Initialise location accessor.

prefix specifies the base folder for the disk based structure and will be prepended to any path. It should be specified in the syntax of the current OS.

exists(resourceIdentifier)[source]

Return if resourceIdentifier is valid and exists in location.

getContainer(resourceIdentifier)[source]

Return resourceIdentifier of container for resourceIdentifier.

Raise AccessorParentResourceNotFoundError if container of resourceIdentifier could not be determined.

getFilesystemPath(resourceIdentifier)[source]

Return filesystem path for resourceIdentifier.

For example:

>>> accessor = DiskAccessor('my.location', '/mountpoint')
>>> print accessor.getFilesystemPath('test.txt')
/mountpoint/test.txt
>>> print accessor.getFilesystemPath('/mountpoint/test.txt')
/mountpoint/test.txt

Raise AccessorFilesystemPathError if filesystem path could not be determined from resourceIdentifier.

getUrl(resourceIdentifier)

Return URL for resourceIdentifier.

Raise ftrack.AccessorUrlError if URL could not be determined from resourceIdentifier* or ftrack.AccessorUnsupportedOperationError if retrieving URL’s is not supported by this accessor.

isContainer(resourceIdentifier)[source]

Return whether resourceIdentifier refers to a container.

isFile(resourceIdentifier)[source]

Return whether resourceIdentifier refers to a file.

isSequence(resourceIdentifier)[source]

Return whether resourceIdentifier refers to a file sequence.

list(resourceIdentifier)[source]

Return list of entries in resourceIdentifier container.

Each entry in the returned list should be a valid resource identifier.

Raise AccessorResourceNotFoundError if resourceIdentifier does not exist or AccessorResourceInvalidError if resourceIdentifier is not a container.

makeContainer(resourceIdentifier, recursive=True)[source]

Make a container at resourceIdentifier.

If recursive is True, also make any intermediate containers.

open(resourceIdentifier, mode='rb')[source]

Return Data for resourceIdentifier.

remove(resourceIdentifier)[source]

Remove resourceIdentifier.

Raise AccessorResourceNotFoundError if resourceIdentifier does not exist.

removeContainer(resourceIdentifier)

Remove container at resourceIdentifier.

class ftrack.EntityIdStructure(prefix='')[source]

Id pass-through structure.

__init__(prefix='')

Initialise structure.

getResourceIdentifier(entity)[source]

Return a resourceIdentifier for supplied entity.

class ftrack.Event(topic, id=None, data=None, sent=None, source=None, target='', inReplyToEvent=None)[source]

Represent a single event.

__init__(topic, id=None, data=None, sent=None, source=None, target='', inReplyToEvent=None)[source]

Initialise event.

topic is the required topic for the event. It can use a dotted notation to demarcate groupings. For example, ‘ftrack.update’.

id is the unique id for this event instance. It is primarily used when replying to an event. If not supplied a default uuid based value will be used.

data refers to event specific data. It should be a mapping structure and defaults to an empty dictionary if not supplied.

sent is the timestamp the event is sent. It will be set automatically as send time unless specified here.

source is information about where the event originated. It should be a mapping and include at least a unique id value under an ‘id’ key. If not specified, senders usually populate the value automatically at publish time.

target can be an expression that targets this event. For example, a reply event would target the event to the sender of the source event. The expression will be tested against subscriber information only.

inReplyToEvent is used when replying to an event and should contain the unique id of the event being replied to.

clear() → None. Remove all items from D.
copy() → a shallow copy of D
fromkeys(S[, v]) → New dict with keys from S and values equal to v.

v defaults to None.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.
has_key(k) → True if D has a key k, else False
isStopped()[source]

Return whether event has been stopped.

items() → list of D's (key, value) pairs, as 2-tuples
iteritems() → an iterator over the (key, value) items of D
iterkeys() → an iterator over the keys of D
itervalues() → an iterator over the values of D
keys() → list of D's keys
pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
stop()[source]

Stop further processing of this event.

update([E, ]**F) → None. Update D from dict/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → list of D's values
viewitems() → a set-like object providing a view on D's items
viewkeys() → a set-like object providing a view on D's keys
viewvalues() → an object providing a view on D's values
class ftrack.EventHub(server=None)[source]

Manage routing of events.

__init__(server=None)[source]

Initialise hub, connecting to ftrack server.

connect()[source]

Initialise connection to server.

Raise ftrack.EventHubConnectionError if already connected or connection fails.

connected

Return if connected.

disconnect(unsubscribe=True)[source]

Disconnect from server.

Raise ftrack.EventHubConnectionError if not currently connected.

If unsubscribe is True then unsubscribe all current subscribers automatically before disconnecting.

getHostname()[source]

Return hostname with port.

getServerUrl()[source]

Return URL to server.

getSubscriberByIdentifier(identifier)[source]

Return subscriber with matching identifier.

Return None if no subscriber with identifier found.

publish(event, synchronous=False, onReply=None)[source]

Publish event.

If synchronous is specified as True then this method will wait and return a list of results from any called callbacks.

Note

Currently, if synchronous is True then only locally registered callbacks will be called and no event will be sent to the server. This may change in future.

onReply is an optional callable to call with any reply event that is received in response to the published event.

Note

Will not be called when synchronous is True.

publishReply(sourceEvent, data, source=None)[source]

Publish a reply event to sourceEvent with supplied data.

If source is specified it will be used for the source value of the sent event.

reconnect(attempts=10, delay=5)[source]

Reconnect to server.

Make attempts number of attempts with delay in seconds between each attempt.

Note

All current subscribers will be automatically resubscribed after successful reconnection.

Raise ftrack.EventHubConnectionError if fail to reconnect.

secure

Return whether secure connection used.

subscribe(subscription, callback, subscriber=None, priority=100)[source]

Register callback for subscription.

A subscription is a string that can specify in detail which events the callback should receive. The filtering is applied against each event object. Nested references are supported using ‘.’ separators. For example, ‘topic=foo and data.eventType=Shot’ would match the following event:

<Event {'topic': 'foo', 'data': {'eventType': 'Shot'}}>

The callback should accept an instance of Event as its sole argument.

Callbacks are called in order of priority. The lower the priority number the sooner it will be called, with 0 being the first. The default priority is 100. Note that priority only applies against other callbacks registered with this hub and not as a global priority.

An earlier callback can prevent processing of subsequent callbacks by calling Event.stop() on the passed event before returning.

Warning

Handlers block processing of other received events. For long running callbacks it is advisable to delegate the main work to another process or thread.

A callback can be attached to subscriber information that details the subscriber context. A subscriber context will be generated automatically if not supplied.

Note

The subscription will be stored locally, but until the server receives notification of the subscription it is possible the callback will not be called.

Return subscriber identifier.

Raise ftrack.NotUniqueError if a subscriber with the same identifier already exists.

subscription(subscription, callback, subscriber=None, priority=100)[source]

Return context manager with callback subscribed to subscription.

The subscribed callback will be automatically unsubscribed on exit of the context manager.

unsubscribe(subscriberIdentifier)[source]

Unsubscribe subscriber with subscriberIdentifier.

Note

If the server is not reachable then it won’t be notified of the unsubscription. However, the subscriber will be removed locally regardless.

wait(duration=None)[source]

Wait for events and handle as they arrive.

If duration is specified, then only process events until duration is reached. duration is in seconds though float values can be used for smaller values.

exception ftrack.EventHubConnectionError(message=None, details=None, **kw)[source]

Raise when event hub encounters connection problem.

__init__(message=None, details=None, **kw)

Initialise exception with message.

If message is None, the class ‘defaultMessage’ will be used.

args
defaultMessage = 'Event hub is not connected.'
message
exception ftrack.EventHubError(message=None, details=None, **kw)[source]

Raise when issues related to event hub occur.

__init__(message=None, details=None, **kw)

Initialise exception with message.

If message is None, the class ‘defaultMessage’ will be used.

args
defaultMessage = 'Event hub error occurred.'
message
exception ftrack.EventHubPacketError(message=None, details=None, **kw)[source]

Raise when event hub encounters an issue with a packet.

__init__(message=None, details=None, **kw)

Initialise exception with message.

If message is None, the class ‘defaultMessage’ will be used.

args
defaultMessage = 'Invalid packet.'
message
class ftrack.FTList(objectType=None, objects=None)[source]

Extended list

__init__(objectType=None, objects=None)[source]
append()

L.append(object) – append object to end

count(value) → integer -- return number of occurrences of value
extend()

L.extend(iterable) – extend list by appending elements from the iterable

find(key, value)[source]

Find @param key used to fetch a value from objects in list @param value the value we are looking for

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

insert()

L.insert(index, object) – insert object before index

pop([index]) → item -- remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()

L.reverse() – reverse IN PLACE

sort(how='asc', onWhat='name')[source]

Sort @param how asc or desc @param onWhat Sorting parameter

class ftrack.FTObject(id=None, dict=None, eagerload=None)[source]

Base object, should never be used directly

__init__(id=None, dict=None, eagerload=None)[source]
delete()[source]
get(key)[source]
getEntityRef()[source]
getId()[source]
keys()[source]

Return keys accessible using get/set methods.

set(key, value=None)[source]
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
exception ftrack.FTrackError(message=None, details=None, **kw)[source]

Base for FTrack specific errors.

__init__(message=None, details=None, **kw)[source]

Initialise exception with message.

If message is None, the class ‘defaultMessage’ will be used.

args
defaultMessage = 'Unspecified error'
message
class ftrack.File(path, mode='rb')[source]

Data wrapper accepting filepath.

__init__(path, mode='rb')[source]

Open file at path with mode.

close()

Flush buffers and prevent further access.

flush()

Flush buffers ensuring data written.

read(limit=None)

Return content from current position up to limit.

seek(offset, whence=0)

Move internal pointer by offset.

tell()

Return current position of internal pointer.

write(content)

Write content at current position.

class ftrack.FileWrapper(wrapped_file)[source]

Data wrapper for Python file objects.

__init__(wrapped_file)[source]

Initialise access to wrapped_file.

close()[source]

Flush buffers and prevent further access.

flush()[source]

Flush buffers ensuring data written.

read(limit=None)[source]

Return content from current position up to limit.

seek(offset, whence=0)[source]

Move internal pointer by offset.

tell()[source]

Return current position of internal pointer.

write(content)[source]

Write content at current position.

class ftrack.Group(id=None, dict=None, eagerload=None)[source]

Represent a group.

__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()
getMembers()[source]

Return list of users in the group.

getSubgroups()[source]

Return list of subgroups.

keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.HasManagers[source]

Mixin for creating and retrieving managers.

__init__

x.__init__(...) initializes x; see help(type(x)) for signature

createManager(user, managerType)[source]

Create a manager from user and managerType for this entity.

user should be a User instance.

managerType should be a ManagerType instance.

getManagers()[source]

Return all managers assigned to this entity.

class ftrack.IdStructure(prefix='')[source]

Id based structure supporting Components only.

A components unique id will be used to form a path to store the data at. To avoid millions of entries in one directory each id is chunked into four prefix directories with the remainder used to name the file:

/prefix/1/2/3/4/56789

If the component has a defined filetype it will be added to the path:

/prefix/1/2/3/4/56789.exr

Components that are children of container components will be placed inside the id structure of their parent:

/prefix/1/2/3/4/56789/355827648d.exr
/prefix/1/2/3/4/56789/ajf24215b5.exr

However, sequence children will be named using their label as an index and a common prefix of ‘file.’:

/prefix/1/2/3/4/56789/file.0001.exr
/prefix/1/2/3/4/56789/file.0002.exr
__init__(prefix='')

Initialise structure.

getResourceIdentifier(entity)[source]

Return a resourceIdentifier for supplied entity.

class ftrack.InternalResourceIdentifierTransformer(platform=None, *args, **kwargs)[source]

Transform resource identifier to support ftrack legacy disk locations.

Historically, a concept of disks have been used in ftrack to manage different OS prefixes for paths tracked in ftrack. In addition, it was possible to configure a project folder attribute and, behind the scenes, an asset prefix that would both be used to calculate the resulting path to display in the UI and also when retrieved through the API.

To provide backwards compatibility with these disks, this transformer will adapt relevant resource identifiers when reading them back from the database (see decode()).

__init__(platform=None, *args, **kwargs)[source]

Initialise internal resource identifier transformer.

platform will override the current platform. Acceptable arguments are ‘Linux’, ‘Windows’ or ‘Darwin’. This will change the disk prefix prepended to paths.

decode(resourceIdentifier, context=None)[source]

Return decoded resourceIdentifier based on context.

Assumes that resourceIdentifier is a path to a resource on disk. The path can be relative or absolute.

context must be a collections.Mapping that contains a ‘component’ key referring to a valid Component instance. The component will be used to look up the relevant information including any configured disk prefix, project folder or asset path prefix.

If the path is absolute, any matching disk prefix will be changed to match the prefix of the target platform.

For example, if the project’s Unix disk prefix is set to ‘/mnt/demo’ and its Window prefix set to ‘d:demo’, then for a Windows target platform:

'/mnt/demo/path/to/file' -> 'd:\demo\path/to/file'

For a Linux target platform the same path is left untouched:

'/mnt/demo/path/to/file' -> '/mnt/demo/path/to/file'

However, a matching Windows prefix would be transformed:

'd:\demo\path       o

ile’ -> ‘/mnt/demo/path o ile’

If the path does not match, it is returned as is:

'/mymount/path/to/file' -> '/mymount/path/to/file'

If the path is relative then it will be prepended to start with any disk prefix, project folder and asset path prefix configured for the relevant component.

For example, if the current platform is Linux and the Unix disk prefix is ‘/mnt/demo’, project folder is ‘/jobs/test’ and the asset path prefix is ‘ftrack/assets’:

'path/to/file' -> '/mnt/demo/jobs/test/ftrack/assets/path/to/file'

Note

The resulting path is not normalised in any way so a mixture of path separator styles may be present.

encode(resourceIdentifier, context=None)

Return encoded resourceIdentifier for storing centrally.

A mapping of context values may be supplied to guide the transformation.

platform

Return platform name.

class ftrack.Job(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
createAttachment(file, fileName=None)[source]

Create an attachment on this job from file.

delete()
get(key)
getAttachments()[source]

Return attachments on this job.

getEntityRef()
getId()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
setDescription(description)[source]

Sets the description of the job

Parameters:descriptionstr description of the job.
setStatus(status)[source]

Sets the status of the job

Parameters:statusstr status of the job. Possible statuses are queued, running, done, failed.
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.List(*args, **argv)[source]

Used to group objects (shots,tasks,versions) together. Can for example be used as a review list.

Param:id listid
__init__(*args, **argv)[source]
append(item)[source]

Add item to this list

Parameters:item – The object to be added to the list
close()[source]

Close this list to make sure nothing else can be added

delete()
extend(items)[source]

Add multiple items to this list

Parameters:items – The objects to be added to the list
get(key)
getEntityRef()
getId()[source]
getLinked()[source]

Used to return all tasks that this list was linked to

getName()[source]
getObjects()[source]

Get all obejcts in this list

getValue(fromObject, key)[source]
isOpen()[source]

Return True or False if the list is open or not

keys()

Return keys accessible using get/set methods.

Used to link a list to a task

Parameters:item – The task that the list should be linked to
open()[source]

Open this list

remove(items)[source]

Remove items from this list

Parameters:items – The entities to be remove from the list
set(key, value=None)
setValue(fromObject, key, value)[source]

Used to unlink a list from a task

Parameters:item – The task that the list should be un-linked from
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.ListCategory(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()[source]
getName()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.ListObject(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.Location(id=None, dict=None, eagerload=None, accessor=None, structure=None, resourceIdentifierTransformer=None, priority=50)[source]

Represent storage for components.

__init__(id=None, dict=None, eagerload=None, accessor=None, structure=None, resourceIdentifierTransformer=None, priority=50)[source]

Initialise location with either id or dict.

accessor can be an instance of ftrack.Accessor and will manage access to data in this location for this instance.

structure can be an instance of ftrack.Structure and will be used to provide structure hints when adding components.

resourceIdentifierTransformer can be an instance of ftrack.ResourceIdentifierTransformer and, if set, will be called to encode resource identifiers before storing them centrally or to decode centrally retrieved identifiers before setting on a component.

priority is a basic hint for the priority of the location versus others in this session. The lower the number the higher the priority with zero considered highest priority.

addComponent(*args, **kw)[source]

Add component to this location transferring relevant data.

If component is a container and recursive is True then also add each member of the container to this location.

If manageData is True then manage transfer of data to the location ( an accessor must be set for this location and the location of the component). If False assume data has been managed externally.

Note

Externally managed data must still match the path generated by this location’s structure interface. No existence check is currently performed.

Raise ftrack.ComponentInLocationError if the component already exists in this location.

Raise ftrack.LocationError if the generated target structure for the component already exists according to the accessor. This helps prevent potential data loss by avoiding overwriting existing data. Note that there is a race condition between the check and the write so if another process creates data at the same target during that period it will be overwritten.

Return component in this location.

adoptComponent(component)[source]

Adopt and return component.

Set location on component to this location, as well as retrieving and setting appropriate resource identifier.

Raise ftrack.ComponentNotInLocationError if component not found in this location.

Note that this compliments getComponent() rather than addComponent().

See also

getComponent().

adoptComponents(*args, **kw)[source]

Adopt and return components.

For each component in components, set location to this location, as well as retrieving and setting appropriate resource identifier.

Raise ftrack.ComponentNotInLocationError if any of the components are not found in this location.

See also

getComponents().

delete()
get(key)
getAccessor()[source]

Return current accessor for this location.

getComponent(componentId)[source]

Retrieve component with componentId from this location.

Raise ftrack.ComponentNotInLocationError if component not found in this location.

Note

If an accessor is available for this location then the access path will also be set on the returned component.

See also

adoptComponent().

getComponentAvailabilities(componentIds)[source]

Return list of availabilities for components in this location.

getComponentAvailability(componentId)[source]

Return availability as percentage of component in this location.

getComponents(*args, **kw)[source]

Retrieve components with componentIds from this location.

Raise ftrack.ComponentNotInLocationError if any of the specified components are not found in this location.

If componentIds is not specified (or None) then retrieve ALL components currently in this location.

Note

If an accessor is available for this location then the access path will also be set on the returned component.

See also

adoptComponents().

getEntityRef()
getId()[source]

Return id.

getName()[source]

Return name.

getPriority()[source]

Return priority.

getResourceIdentifierTransformer()[source]

Return current resource identifier transformer for this location.

getStructure()[source]

Return current structure for this location.

keys()

Return keys accessible using get/set methods.

removeComponent(componentId, recursive=True, manageData=True)[source]

Remove component with componentId from this location.

If component is a container and recursive is True then also remove each member of the container from this location.

If manageData is True then manage removal of data from this location ( an accessor must be set for this location). If False assume data has been managed externally.

set(key, value=None)
setAccessor(accessor)[source]

Set current accessor for this location.

setPriority(priority)[source]

Set priority.

setResourceIdentifierTransformer(resourceIdentifierTransformer)[source]

Set current resourceIdentifierTransformer for this location.

setStructure(structure)[source]

Set current structure for this location.

xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
exception ftrack.LocationError(message=None, details=None, **kw)[source]

Base for errors associated with locations.

__init__(message=None, details=None, **kw)

Initialise exception with message.

If message is None, the class ‘defaultMessage’ will be used.

args
defaultMessage = 'Unspecified location error'
message
class ftrack.Manager(id=None, dict=None, eagerload=None)[source]

Represent managers for projects and entities.

A manager is a User associated with a ManagerType. The manager is connected to an entity such as a project or sequence.

__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()
getType()[source]

Return the type for this manager.

getUser()[source]

Return the user for this manager.

keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.ManagerType(id=None, dict=None, eagerload=None)[source]

Represent the type of a Manager.

Manager types can be created in Settings ‣ Manager types. A manager type has a name that can be used to fetch that type by passing it to the constructor. Examples of manager types are “supervisor” or “producer”.

__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()
getName()[source]

Return name of the manager type.

keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.MemoryLocation(*args, **kw)[source]

Represent storage for components.

Unlike a standard location, only store metadata for components in this location in memory rather than persisting to the database.

__init__(*args, **kw)[source]

Initialise location.

addComponent(*args, **kw)

Add component to this location transferring relevant data.

If component is a container and recursive is True then also add each member of the container to this location.

If manageData is True then manage transfer of data to the location ( an accessor must be set for this location and the location of the component). If False assume data has been managed externally.

Note

Externally managed data must still match the path generated by this location’s structure interface. No existence check is currently performed.

Raise ftrack.ComponentInLocationError if the component already exists in this location.

Raise ftrack.LocationError if the generated target structure for the component already exists according to the accessor. This helps prevent potential data loss by avoiding overwriting existing data. Note that there is a race condition between the check and the write so if another process creates data at the same target during that period it will be overwritten.

Return component in this location.

adoptComponent(component)

Adopt and return component.

Set location on component to this location, as well as retrieving and setting appropriate resource identifier.

Raise ftrack.ComponentNotInLocationError if component not found in this location.

Note that this compliments getComponent() rather than addComponent().

See also

getComponent().

adoptComponents(*args, **kw)

Adopt and return components.

For each component in components, set location to this location, as well as retrieving and setting appropriate resource identifier.

Raise ftrack.ComponentNotInLocationError if any of the components are not found in this location.

See also

getComponents().

delete()
get(key)
getAccessor()

Return current accessor for this location.

getComponent(componentId)

Retrieve component with componentId from this location.

Raise ftrack.ComponentNotInLocationError if component not found in this location.

Note

If an accessor is available for this location then the access path will also be set on the returned component.

See also

adoptComponent().

getComponentAvailabilities(componentIds)[source]

Return list of availabilities for components in this location.

getComponentAvailability(componentId)[source]

Return availability as percentage of component in this location.

getComponents(*args, **kw)

Retrieve components with componentIds from this location.

Raise ftrack.ComponentNotInLocationError if any of the specified components are not found in this location.

If componentIds is not specified (or None) then retrieve ALL components currently in this location.

Note

If an accessor is available for this location then the access path will also be set on the returned component.

See also

adoptComponents().

getEntityRef()
getId()

Return id.

getName()

Return name.

getPriority()

Return priority.

getResourceIdentifierTransformer()

Return current resource identifier transformer for this location.

getStructure()

Return current structure for this location.

keys()

Return keys accessible using get/set methods.

removeComponent(componentId, recursive=True, manageData=True)

Remove component with componentId from this location.

If component is a container and recursive is True then also remove each member of the container from this location.

If manageData is True then manage removal of data from this location ( an accessor must be set for this location). If False assume data has been managed externally.

set(key, value=None)
setAccessor(accessor)

Set current accessor for this location.

setPriority(priority)

Set priority.

setResourceIdentifierTransformer(resourceIdentifierTransformer)

Set current resourceIdentifierTransformer for this location.

setStructure(structure)

Set current structure for this location.

xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.Metable[source]

Abstract class inherited by objects to enable meta functionality.

__init__

x.__init__(...) initializes x; see help(type(x)) for signature

getMeta(key=None)[source]

Get metadata from an object. This method can be used to retrive meta data from an object. The data is stored in key/value pairs where key and value are strings.

This method can also be used without any arguments to retrive a dict with all metadata key/value pairs attached to this object.

Parameters:key – A string representing the key or None to retrive all key/value pairs on this object.
Return type:string or dict
metaKeys()[source]

Return keys accessible using getMeta/setMeta methods.

setMeta(key, value=None)[source]

Set metadata on an object. This method can be used to store arbitrary data on an object. The data is stored in key/value pairs where key and value are strings.

This method also accepts a dict with key/value pairs

Parameters:
  • key – A string representing the key or a dict with key/value pairs.
  • value – A string representing the value or None if key is a dict.
exception ftrack.NotFoundError(message=None, details=None, **kw)[source]

Raise when something that should exist is not found.

__init__(message=None, details=None, **kw)

Initialise exception with message.

If message is None, the class ‘defaultMessage’ will be used.

args
defaultMessage = 'Not found.'
message
exception ftrack.NotUniqueError(message=None, details=None, **kw)[source]

Raise when something that should be unique is not.

__init__(message=None, details=None, **kw)

Initialise exception with message.

If message is None, the class ‘defaultMessage’ will be used.

args
defaultMessage = 'Not unique.'
message
class ftrack.Note(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
createAttachment(file, fileName=None)[source]

Create an attachment from file.

createNote(note, category='auto', recipients=None)

Create note with text note.

Optional category can be specified to set the note category of the note. Can be either NoteCategory or category id. If set to auto the default note category setting will be used.

Recipients can be specified by setting recipients to be a list of User or user ids.

createReply(*args, **argv)[source]

Used to add a note on a note

Parameters:
  • note – the note text as a string
  • categoryNoteCategory (optional)
delete()
get(key)
getAttachments()[source]

Return attachments.

getCategory()[source]
getDate()[source]
getDefaultRecipients()

Get default recipients for an object

Return type:list with User objects
getEntityRef()
getId()[source]
getMeta(key=None)

Get metadata from an object. This method can be used to retrive meta data from an object. The data is stored in key/value pairs where key and value are strings.

This method can also be used without any arguments to retrive a dict with all metadata key/value pairs attached to this object.

Parameters:key – A string representing the key or None to retrive all key/value pairs on this object.
Return type:string or dict
getNotes()

Fetch notes from an entity, this will include replies.

getRecipients()[source]

Get recipients for this note. Recipients are users that were notified when it was created.

getText()[source]
getUser()[source]
isReply()[source]
keys()

Return keys accessible using get/set methods.

metaKeys()

Return keys accessible using getMeta/setMeta methods.

set(key, value=None)
setMeta(key, value=None)

Set metadata on an object. This method can be used to store arbitrary data on an object. The data is stored in key/value pairs where key and value are strings.

This method also accepts a dict with key/value pairs

Parameters:
  • key – A string representing the key or a dict with key/value pairs.
  • value – A string representing the value or None if key is a dict.
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.NoteCategory(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getColor()[source]
getEntityRef()
getId()[source]
getName()[source]
getSort()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.Noteable[source]
__init__

x.__init__(...) initializes x; see help(type(x)) for signature

createNote(note, category='auto', recipients=None)[source]

Create note with text note.

Optional category can be specified to set the note category of the note. Can be either NoteCategory or category id. If set to auto the default note category setting will be used.

Recipients can be specified by setting recipients to be a list of User or user ids.

getDefaultRecipients()[source]

Get default recipients for an object

Return type:list with User objects
getNotes()[source]

Fetch notes from an entity, this will include replies.

class ftrack.OriginStructure(prefix='')[source]

Origin structure supporting Components only.

Will maintain original internal component path.

__init__(prefix='')

Initialise structure.

getResourceIdentifier(entity)[source]

Return a resourceIdentifier for supplied entity.

class ftrack.Parentable[source]
__init__

x.__init__(...) initializes x; see help(type(x)) for signature

getParent()[source]

Get parent object from this object

Return type:FTObject of that type
getParents()[source]

Get parent object from this object

Return type:list owith items of that type
exception ftrack.PermissionDeniedError(message=None, details=None, **kw)[source]

Raise when permission is denied.

__init__(message=None, details=None, **kw)

Initialise exception with message.

If message is None, the class ‘defaultMessage’ will be used.

args
defaultMessage = 'Permission denied.'
message
class ftrack.Phase(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
addTaskType(taskType)[source]

Add taskType to the phase.

assignUser(user)[source]

Assign a user to this phase

Parameters:user – A User to assign to this phase
delete()
get(key)
getEntityRef()
getId()
getMeta(key=None)

Get metadata from an object. This method can be used to retrive meta data from an object. The data is stored in key/value pairs where key and value are strings.

This method can also be used without any arguments to retrive a dict with all metadata key/value pairs attached to this object.

Parameters:key – A string representing the key or None to retrive all key/value pairs on this object.
Return type:string or dict
getParent()

Get parent object from this object

Return type:FTObject of that type
getParents()

Get parent object from this object

Return type:list owith items of that type
getTaskTypes()[source]

Return task types for phase.

getUsers()[source]

Return all users assigned to this phase

keys()

Return keys accessible using get/set methods.

metaKeys()

Return keys accessible using getMeta/setMeta methods.

removeTaskType(taskType)[source]

Remove taskType from the phase.

set(key, value=None)
setMeta(key, value=None)

Set metadata on an object. This method can be used to store arbitrary data on an object. The data is stored in key/value pairs where key and value are strings.

This method also accepts a dict with key/value pairs

Parameters:
  • key – A string representing the key or a dict with key/value pairs.
  • value – A string representing the value or None if key is a dict.
unAssignUser(user)[source]

Un-assign a user to this phase

Parameters:user – Un-assign a User from this phase
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.Priority(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getColor()[source]
getEntityRef()
getId()[source]
getName()[source]
getSort()[source]
getValue()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.Project(id=None, dict=None, eagerload=None)[source]

Used to get data from a project or its children @param id show id

__init__(id=None, dict=None, eagerload=None)
create(objectType, name, statusId=None, typeId=None, priorityId=None)

Create a context from objectType with name.

createAsset(name, assetType, task=None)

Create a new asset or return existing.

name is the name of the asset and assetType is the type of the asset defined by its short name. A task or task id can also be passed in which will be used as the default task when versions are created on this asset.

createAssetBuild(name, typeid=None)[source]

Create an asset build from name and typeid.

createAttachment(file, fileName=None, isThumb=False)

Legacy method to attach files to objects.

createEpisode(name)

Create an episode from name.

createList(name, category, objectType=None)[source]

Creates a list for this project

Parameters:
  • name – A str with the name of the list
  • category – A ListCategory object that defines the category for this list
  • objectType – A ListCategory object that defines what this list should contain. This should be AssetVersion or None
Return type:

List

createManager(user, managerType)

Create a manager from user and managerType for this entity.

user should be a User instance.

managerType should be a ManagerType instance.

createNote(note, category='auto', recipients=None)

Create note with text note.

Optional category can be specified to set the note category of the note. Can be either NoteCategory or category id. If set to auto the default note category setting will be used.

Recipients can be specified by setting recipients to be a list of User or user ids.

createPhase(description, startdate, enddate, color=None)[source]

Create a phase for this project

Parameters:
  • description – A str with the description of this phase
  • startdate – A datetime with the start date of this phase
  • enddate – A datetime with the end date of this phase
  • color – A str with the color of this phase
createReviewSession(name, description)[source]

Create a new review session with name and description.

createSequence(name)

Create a sequence from name.

createShot(name)

Create a shot from name.

createTask(name, taskType=None, taskStatus=None)

Create a task from name, taskType and taskStatus.

createThumbnail(file, fileName='image.jpg')

Create thumbnail from file.

delete()
get(key)
getAllocatedGroups()[source]

Return groups allocated on the project.

getAllocatedUsers()[source]

Return users allocated on the project.

getAssetBuildTypes()[source]

Return the asset build types valid for this project.

getAssetBuilds()[source]
getAssets(assetTypes=None, includeChildren=False, componentNames=None, excludeWithTasks=False)[source]

Get attached Assets

Parameters:
  • names – A list with names of the assets
  • assetTypes – A list with names of the asset types or short names of the asset types or asset type ids
  • componentNames – A list with names of components that the versions must have at least one of
  • excludeWithTasks – A bool which defaults to False, can be used to get assets with versions that are not connected to any tasks
Return type:

FTList of Asset

getBookings()[source]

Return all bookings for this project

getChildren(objectType=None, depth=1)

Get attached Children (not tasks)

Return type:FTList of Children
getDefaultRecipients()

Get default recipients for an object

Return type:list with User objects
getEntityRef()
getEpisodes()
getFPS()[source]
getFullName()[source]
getId()[source]
getList(name)[source]

Returns a list by name

Parameters:name – Name of the list on this project.
Return type:List
getLists(name=None, categories=None)[source]

Returns all lists for this project

Parameters:
  • name – Used to match the names.
  • categories – list of ListCategory to use as filter.
Return type:

list

getManagers()

Return all managers assigned to this entity.

getMeta(key=None)

Get metadata from an object. This method can be used to retrive meta data from an object. The data is stored in key/value pairs where key and value are strings.

This method can also be used without any arguments to retrive a dict with all metadata key/value pairs attached to this object.

Parameters:key – A string representing the key or None to retrive all key/value pairs on this object.
Return type:string or dict
getName()[source]
getNotes()

Fetch notes from an entity, this will include replies.

getPath(full=False)[source]

Get OS specific path to project folder

Parameters:fullbool Include asset prefix setting at end of path
Return type:A string with the file path to the project
getPhases()[source]

Return all phases for this project

getReviewSessions()[source]

Return all review sessions on project.

getRoot()[source]
getSequences()

Get attached Sequences

Return type:FTList of Sequence
getShots()
getStatuses(name)[source]

Return valid statuses for object of type name.

getTaskStatuses(typeid=None)[source]

Get TaskStatus that are defined by this projects workflow schema.

Parameters:typeid – Defaults to None. The id or TaskType object. This should always be used since it makes sure the correct statuses are returned if there is an override in place for this type.
Return type:FTList of TaskStatus
getTaskTypes()[source]

Get TaskStatus

Return type:FTList of TaskTypes
getTasks(*args, **argv)

Get attached Tasks

Parameters:
  • userslist with usernames like [‘username1’,’username2’] to filter out tasks
  • taskTypeslist representing task types. Can be TaskType objects, their IDs or their names.
  • taskStatuseslist representing task statuses. Can be TaskStatus objects, their IDs or their names.
  • stateslist with states. Possible states are NOT_STARTED, IN_PROGRESS, DONE, BLOCKED which are availible from the ftrack module
  • activeProjectsOnlybool Default to True. specifying if only to query active projects.
  • includeChildrenbool Default to False. childrens tasks should be included.
  • includePathbool Default to False. specifying if the path should be added to each task. Much faster than useing getParents on each task afterwards.
Return type:

FTList with Task

getThumbnail()

Get a url to the thumbnail.

getTimelogs(start=None, end=None, includeChildren=False)

Return timelogs between start and end dates.

If includeChildren is set, also return timelogs on descendants.

getURL()

Return url that can be used to view this entity in a browser.

getUsers()[source]
getVersionStatuses()[source]

Get version statuses from project workflow scheme used by this project

Return type:FTList of VersionStatus
getWebWidgetUrl(name, theme='dark')

Return url that can be used is a qt webwidget.

name should be the name of the ftrack panel. theme is optional.

keys()

Return keys accessible using get/set methods.

metaKeys()

Return keys accessible using getMeta/setMeta methods.

set(key, value=None)
setMeta(key, value=None)

Set metadata on an object. This method can be used to store arbitrary data on an object. The data is stored in key/value pairs where key and value are strings.

This method also accepts a dict with key/value pairs

Parameters:
  • key – A string representing the key or a dict with key/value pairs.
  • value – A string representing the value or None if key is a dict.
setThumbnail(component)

Set component as thumbnail.

xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.ProjectScheme(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.Registry(paths=None)[source]

Registry for plugins.

__init__(paths=None)[source]

Initialise plugin registry.

add(plugin)[source]

Add plugin.

clear()

This is slow (creates N new iterators!) but effective.

discard(plugin)[source]

Remove plugin.

discover(**kw)[source]

Find and load plugins in search paths.

Each discovered module should implement a register function that accepts this registry and additional kw. The function should add appropriate instances to the registry:

def register(registry, **kw):
    plugin = MyPlugin(name='plugin.name')
    registry.add(plugin)

Note

Each instance must have a ‘getName’ method that will identify the plugin.

get(name)[source]

Retrieve a discovered plugin by name.

Return None if no matching plugin found.

isdisjoint(other)

Return True if two sets have a null intersection.

pop()

Return the popped value. Raise KeyError if empty.

remove(value)

Remove an element. If not a member, raise a KeyError.

class ftrack.ResourceIdentifierTransformer[source]

Transform resource identifiers.

Provide ability to modify resource identifier before it is stored centrally (encode()), or after it has been retrieved, but before it is used locally (decode()).

For example, you might want to decompose paths into a set of key, value pairs to store centrally and then compose a path from those values when reading back.

Note

This is separate from any transformations an ftrack.Accessor may perform and is targeted towards common transformations.

__init__

x.__init__(...) initializes x; see help(type(x)) for signature

decode(resourceIdentifier, context=None)[source]

Return decoded resourceIdentifier for use locally.

A mapping of context values may be supplied to guide the transformation.

encode(resourceIdentifier, context=None)[source]

Return encoded resourceIdentifier for storing centrally.

A mapping of context values may be supplied to guide the transformation.

class ftrack.Review[source]

A utility class that contains functions used by ftrackreview.

Example of adding reviewable components to a version:

import ftrack

# Get a shot and a task on the shot
shot = ftrack.getShot(['project', 'seq', 'shot'])
task = shot.getTasks().pop()

# Create an asset to publish a new reviewable version
asset = shot.createAsset(
    name='compositing', assetType='comp', task=task
)

# Create a new version
version = asset.createVersion(comment='Made som changes to the helmet')

# Set the path to the file that should be attached to the version
filePath = '/Users/carlclaesson/Documents/data/helmet.mov'

# Make the version reviewable by using the util function
# ftrack.Review.makeReviewable(). This will create an original
# component and move it to the ``ftrack.server`` location and trigger
# encoding.
ftrack.Review.makeReviewable(version, filePath)

version.publish()
__init__

x.__init__(...) initializes x; see help(type(x)) for signature

static encodeComponent(component)[source]

Create reviewable components from a given component. The component file needs to be a valid s3 key.

Parameters:componentComponent to convert
static makeReviewable(version=None, filePath=None)[source]

Add web reviewable compoment to version based on filePath.

class ftrack.ReviewSession(id=None, dict=None, eagerload=None)[source]

Represent review session.

__init__(id=None, dict=None, eagerload=None)
createInvitee(email, name)[source]

Create a new invitee with email and name on review session.

createObject(assetVersion, name='', description='', version='', syncAssetVersionData=False)[source]

Create a new review session object on review session.

assetVersion should be an instance of ftrack.AssetVersion.

Optionally specify a name, description, version number which will be visible when viewing the review session in the web interface.

If syncAssetVersionData is set to True the name, description and version will be set based on the assetVersion.

delete()
get(key)
getEntityRef()
getId()
getInvitees()[source]

Return all invitees on review session.

getObjects()[source]

Return a ftrack.FTList of ftrack.ReviewSessionObject.

keys()

Return keys accessible using get/set methods.

reviewSessionObjects()[source]

Return a ftrack.FTList of ftrack.ReviewSessionObject.

Warning

Deprecated method, use ftrack.ReviewSession.getObjects().

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.ReviewSessionInvitee(id=None, dict=None, eagerload=None)[source]

Represent review session invitee.

__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.ReviewSessionObject(id=None, dict=None, eagerload=None)[source]

Represent review session object.

__init__(id=None, dict=None, eagerload=None)
createNote(note, category='auto', recipients=None)

Create note with text note.

Optional category can be specified to set the note category of the note. Can be either NoteCategory or category id. If set to auto the default note category setting will be used.

Recipients can be specified by setting recipients to be a list of User or user ids.

delete()
get(key)
getDefaultRecipients()

Get default recipients for an object

Return type:list with User objects
getEntityRef()
getId()
getNotes()

Fetch notes from an entity, this will include replies.

getStatuses()[source]

Return list of ftrack.ReviewSessionObjectStatus.

If the list is empty no invitees has voted.

keys()

Return keys accessible using get/set methods.

set(key, value=None)
setStatus(status, invitee)[source]

Set status on object for invitee.

invitee should be of type ftrack.ReviewSessionInvitee.

xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.ReviewSessionObjectStatus(id=None, dict=None, eagerload=None)[source]

Represent review session invitee.

__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.Role(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()[source]
getName()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.S3Accessor(bucketName, accessKey, secretKey)[source]

Provide Amazon S3 location access.

To use, please first install the Boto package.

__init__(bucketName, accessKey, secretKey)[source]

Initialise location accessor.

bucketName is the name of the bucket to provide access to using accessKey and secretKey credentials.

bucket

Return bucket.

connection

Return S3 connection.

exists(resourceIdentifier)[source]

Return if resourceIdentifier is valid and exists in location.

getContainer(resourceIdentifier)[source]

Return resourceIdentifier of container for resourceIdentifier.

Raise AccessorParentResourceNotFoundError if container of resourceIdentifier could not be determined.

getFilesystemPath(resourceIdentifier)

Return filesystem path for resourceIdentifier.

Raise AccessorFilesystemPathError if filesystem path could not be determined from resourceIdentifier or AccessorUnsupportedOperationError if retrieving filesystem paths is not supported by this accessor.

getUrl(resourceIdentifier)

Return URL for resourceIdentifier.

Raise ftrack.AccessorUrlError if URL could not be determined from resourceIdentifier* or ftrack.AccessorUnsupportedOperationError if retrieving URL’s is not supported by this accessor.

isContainer(resourceIdentifier)[source]

Return whether resourceIdentifier refers to a container.

isFile(resourceIdentifier)[source]

Return whether resourceIdentifier refers to a file.

isSequence(resourceIdentifier)[source]

Return whether resourceIdentifier refers to a file sequence.

list(resourceIdentifier)[source]

Return list of entries in resourceIdentifier container.

Each entry in the returned list should be a valid resource identifier.

Raise AccessorResourceNotFoundError if resourceIdentifier does not exist or AccessorResourceInvalidError if resourceIdentifier is not a container.

makeContainer(resourceIdentifier, recursive=True)[source]

Make a container at resourceIdentifier.

If recursive is True, also make any intermediate containers.

open(resourceIdentifier, mode='rb')[source]

Return Data for resourceIdentifier.

remove(resourceIdentifier)[source]

Remove resourceIdentifier.

Raise AccessorResourceNotFoundError if resourceIdentifier does not exist.

removeContainer(resourceIdentifier)

Remove container at resourceIdentifier.

class ftrack.Sequence(id=None, dict=None, eagerload=None)[source]

DEPRECATED CLASS

__init__(id=None, dict=None, eagerload=None)
addPredecessor(task)

Add a dependency from another task to this task

Parameters:task – The predecessor task
addSuccessor(task)

Add a dependency from this task to another task

Parameters:task – The successor task
assignUser(user)

Assigns a user to a task

Parameters:user – A User object representing the user that should be assigned to the task.
create(objectType, name, statusId=None, typeId=None, priorityId=None)

Create a context from objectType with name.

createAsset(name, assetType, task=None)

Create a new asset or return existing.

name is the name of the asset and assetType is the type of the asset defined by its short name. A task or task id can also be passed in which will be used as the default task when versions are created on this asset.

createAttachment(file, fileName=None, isThumb=False)

Legacy method to attach files to objects.

createEpisode(name)

Create an episode from name.

createManager(user, managerType)

Create a manager from user and managerType for this entity.

user should be a User instance.

managerType should be a ManagerType instance.

createNote(note, category='auto', recipients=None)

Create note with text note.

Optional category can be specified to set the note category of the note. Can be either NoteCategory or category id. If set to auto the default note category setting will be used.

Recipients can be specified by setting recipients to be a list of User or user ids.

createSequence(name)

Create a sequence from name.

createShot(name)

Create a shot from name.

createTask(name, taskType=None, taskStatus=None)

Create a task from name, taskType and taskStatus.

createThumbnail(file, fileName='image.jpg')

Create thumbnail from file.

delete()
get(key)
getAsset(name, assetType)

Get an Asset

Parameters:
  • namestr with the name of the asset
  • assetType – a string with the asset type like ‘geo’
Return type:

Asset

getAssetVersions()

Get AssetVersions

Return type:list of AssetVersions
getAssets(assetTypes=None, names=None, includeChildren=False, componentNames=None, excludeWithTasks=False)

Get Assets

Parameters:
  • names – A list with names of the assets
  • assetTypes – A list with names of the asset types or short names of the asset types or asset type ids
  • componentNames – A list with names of components that the versions must have at least one of
  • excludeWithTasks – A bool which defaults to False, can be used to get assets with versions that are not connected to any tasks
Return type:

FTList of Assets

getBid()
getChildren(objectType=None, depth=1)

Get attached Children (not tasks)

Return type:FTList of Children
getDefaultRecipients()

Get default recipients for an object

Return type:list with User objects
getDescription()
getEndDate()
getEntityRef()
getEpisodes()
getFPS()
getFrameEnd()
getFrameStart()
getId()
getLists()

Returns the lists that have been linked/associated with this task. NOTE: There is a difference between a task being added to a list and lists linked to a task

Return type:list
getManagers()

Return all managers assigned to this entity.

getMeta(key=None)

Get metadata from an object. This method can be used to retrive meta data from an object. The data is stored in key/value pairs where key and value are strings.

This method can also be used without any arguments to retrive a dict with all metadata key/value pairs attached to this object.

Parameters:key – A string representing the key or None to retrive all key/value pairs on this object.
Return type:string or dict
getName()
getNotes()

Fetch notes from an entity, this will include replies.

getObjectType()
getParent()

Get parent object from this object

Return type:FTObject of that type
getParents()

Get parent object from this object

Return type:list owith items of that type
getPredecessors()

Returns a list of items that this item depends on

Return type:list
getPriority()

Return the priority of the object or None if it has no priority.

getProject()

Get project this object belongs to

Return type:Project
getSequence()

@deprecated Use getParent instead

getSequences()

Get attached Sequences

Return type:FTList of Sequence
getShots()

Get attached Shots

Return type:FTList of Shot
getShow()

@deprecated Use getParent instead

getStartDate()
getStatus()

Return the status of the object or None if it has no status.

getSuccessors()

Returns a list of items that depend on this object

Return type:list
getTasks(*args, **argv)

Get attached Tasks

Parameters:
  • userslist with usernames like [‘username1’,’username2’] to filter out tasks
  • taskTypeslist representing task types. Can be TaskType objects, their IDs or their names.
  • taskStatuseslist representing task statuses. Can be TaskStatus objects, their IDs or their names.
  • stateslist with states. Possible states are NOT_STARTED, IN_PROGRESS, DONE, BLOCKED which are availible from the ftrack module
  • activeProjectsOnlybool Default to True. specifying if only to query active projects.
  • includeChildrenbool Default to False. childrens tasks should be included.
  • includePathbool Default to False. specifying if the path should be added to each task. Much faster than useing getParents on each task afterwards.
Return type:

FTList with Task

getThumbnail()

Get a url to the thumbnail.

getTimelogs(start=None, end=None, includeChildren=False)

Return timelogs between start and end dates.

If includeChildren is set, also return timelogs on descendants.

getType()

Return the type of the object or None if it has no type.

getURL()

Return url that can be used to view this entity in a browser.

getUsers()

Get Users assigned to this Task

Return type:FTList of User
getWebWidgetUrl(name, theme='dark')

Return url that can be used is a qt webwidget.

name should be the name of the ftrack panel. theme is optional.

keys()

Return keys accessible using get/set methods.

metaKeys()

Return keys accessible using getMeta/setMeta methods.

removePredecessor(task)

remove a dependency another task to this task

Parameters:task – The predecessor task
removeSuccessor(task)

remove a dependency from this task to another task

Parameters:task – The successor task
set(key, value=None)
setEndDate(theDate)
setMeta(key, value=None)

Set metadata on an object. This method can be used to store arbitrary data on an object. The data is stored in key/value pairs where key and value are strings.

This method also accepts a dict with key/value pairs

Parameters:
  • key – A string representing the key or a dict with key/value pairs.
  • value – A string representing the value or None if key is a dict.
setPriority(priority)
setStartDate(theDate)
setStatus(status)

Set status of the object

Parameters:statusStatus the status object that should be set
setThumbnail(component)

Set component as thumbnail.

unAssignUser(user)

Unassigns a user from a task

Parameters:user – A User object representing the user that should be unassigned from the task.
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.SequenceLegacy[source]
__init__

x.__init__(...) initializes x; see help(type(x)) for signature

getShots()[source]

Get attached Shots

Return type:FTList of Shot
getShow()[source]

@deprecated Use getParent instead

class ftrack.ServerAccessor(**kw)[source]

Provide server location access.

__init__(**kw)[source]

Initialise location accessor.

exists(resourceIdentifier)[source]

Return if resourceIdentifier is valid and exists in location.

getContainer(resourceIdentifier)[source]

Return resourceIdentifier of container for resourceIdentifier.

getFilesystemPath(resourceIdentifier)

Return filesystem path for resourceIdentifier.

Raise AccessorFilesystemPathError if filesystem path could not be determined from resourceIdentifier or AccessorUnsupportedOperationError if retrieving filesystem paths is not supported by this accessor.

getUrl(resourceIdentifier)[source]

Return url for resourceIdentifier.

isContainer(resourceIdentifier)[source]

Return whether resourceIdentifier refers to a container.

isFile(resourceIdentifier)[source]

Return whether resourceIdentifier refers to a file.

isSequence(resourceIdentifier)[source]

Return whether resourceIdentifier refers to a file sequence.

list(resourceIdentifier)[source]

Return list of entries in resourceIdentifier container.

makeContainer(resourceIdentifier, recursive=True)[source]

Make a container at resourceIdentifier.

open(resourceIdentifier, mode='rb')[source]

Return Data for resourceIdentifier.

remove(resourceIdentifier)[source]

Remove resourceIdentifier.

removeContainer(resourceIdentifier)

Remove container at resourceIdentifier.

class ftrack.Shot(id=None, dict=None, eagerload=None)[source]

DEPRECATED CLASS

__init__(id=None, dict=None, eagerload=None)
addPredecessor(task)

Add a dependency from another task to this task

Parameters:task – The predecessor task
addSuccessor(task)

Add a dependency from this task to another task

Parameters:task – The successor task
assignUser(user)

Assigns a user to a task

Parameters:user – A User object representing the user that should be assigned to the task.
create(objectType, name, statusId=None, typeId=None, priorityId=None)

Create a context from objectType with name.

createAsset(name, assetType, task=None)

Create a new asset or return existing.

name is the name of the asset and assetType is the type of the asset defined by its short name. A task or task id can also be passed in which will be used as the default task when versions are created on this asset.

createAttachment(file, fileName=None, isThumb=False)

Legacy method to attach files to objects.

createEpisode(name)

Create an episode from name.

createManager(user, managerType)

Create a manager from user and managerType for this entity.

user should be a User instance.

managerType should be a ManagerType instance.

createNote(note, category='auto', recipients=None)

Create note with text note.

Optional category can be specified to set the note category of the note. Can be either NoteCategory or category id. If set to auto the default note category setting will be used.

Recipients can be specified by setting recipients to be a list of User or user ids.

createSequence(name)

Create a sequence from name.

createShot(name)

Create a shot from name.

createTask(name, taskType=None, taskStatus=None)

Create a task from name, taskType and taskStatus.

createThumbnail(file, fileName='image.jpg')

Create thumbnail from file.

delete()
get(key)
getAsset(name, assetType)

Get an Asset

Parameters:
  • namestr with the name of the asset
  • assetType – a string with the asset type like ‘geo’
Return type:

Asset

getAssetVersions()

Get AssetVersions

Return type:list of AssetVersions
getAssets(assetTypes=None, names=None, includeChildren=False, componentNames=None, excludeWithTasks=False)

Get Assets

Parameters:
  • names – A list with names of the assets
  • assetTypes – A list with names of the asset types or short names of the asset types or asset type ids
  • componentNames – A list with names of components that the versions must have at least one of
  • excludeWithTasks – A bool which defaults to False, can be used to get assets with versions that are not connected to any tasks
Return type:

FTList of Assets

getBid()
getChildren(objectType=None, depth=1)

Get attached Children (not tasks)

Return type:FTList of Children
getDefaultRecipients()

Get default recipients for an object

Return type:list with User objects
getDescription()
getEndDate()
getEntityRef()
getEpisodes()
getFPS()
getFrameEnd()
getFrameStart()
getId()
getLists()

Returns the lists that have been linked/associated with this task. NOTE: There is a difference between a task being added to a list and lists linked to a task

Return type:list
getManagers()

Return all managers assigned to this entity.

getMeta(key=None)

Get metadata from an object. This method can be used to retrive meta data from an object. The data is stored in key/value pairs where key and value are strings.

This method can also be used without any arguments to retrive a dict with all metadata key/value pairs attached to this object.

Parameters:key – A string representing the key or None to retrive all key/value pairs on this object.
Return type:string or dict
getName()
getNotes()

Fetch notes from an entity, this will include replies.

getObjectType()
getParent()

Get parent object from this object

Return type:FTObject of that type
getParents()

Get parent object from this object

Return type:list owith items of that type
getPredecessors()

Returns a list of items that this item depends on

Return type:list
getPriority()

Return the priority of the object or None if it has no priority.

getProject()

Get project this object belongs to

Return type:Project
getSequence()

@deprecated Use getParent instead

getSequences()

Get attached Sequences

Return type:FTList of Sequence
getShots()

Get attached Shots

Return type:FTList of Shot
getShow()

@deprecated Use getParent instead

getStartDate()
getStatus()

Return the status of the object or None if it has no status.

getSuccessors()

Returns a list of items that depend on this object

Return type:list
getTasks(*args, **argv)

Get attached Tasks

Parameters:
  • userslist with usernames like [‘username1’,’username2’] to filter out tasks
  • taskTypeslist representing task types. Can be TaskType objects, their IDs or their names.
  • taskStatuseslist representing task statuses. Can be TaskStatus objects, their IDs or their names.
  • stateslist with states. Possible states are NOT_STARTED, IN_PROGRESS, DONE, BLOCKED which are availible from the ftrack module
  • activeProjectsOnlybool Default to True. specifying if only to query active projects.
  • includeChildrenbool Default to False. childrens tasks should be included.
  • includePathbool Default to False. specifying if the path should be added to each task. Much faster than useing getParents on each task afterwards.
Return type:

FTList with Task

getThumbnail()

Get a url to the thumbnail.

getTimelogs(start=None, end=None, includeChildren=False)

Return timelogs between start and end dates.

If includeChildren is set, also return timelogs on descendants.

getType()

Return the type of the object or None if it has no type.

getURL()

Return url that can be used to view this entity in a browser.

getUsers()

Get Users assigned to this Task

Return type:FTList of User
getWebWidgetUrl(name, theme='dark')

Return url that can be used is a qt webwidget.

name should be the name of the ftrack panel. theme is optional.

keys()

Return keys accessible using get/set methods.

metaKeys()

Return keys accessible using getMeta/setMeta methods.

removePredecessor(task)

remove a dependency another task to this task

Parameters:task – The predecessor task
removeSuccessor(task)

remove a dependency from this task to another task

Parameters:task – The successor task
set(key, value=None)
setEndDate(theDate)
setMeta(key, value=None)

Set metadata on an object. This method can be used to store arbitrary data on an object. The data is stored in key/value pairs where key and value are strings.

This method also accepts a dict with key/value pairs

Parameters:
  • key – A string representing the key or a dict with key/value pairs.
  • value – A string representing the value or None if key is a dict.
setPriority(priority)
setStartDate(theDate)
setStatus(status)

Set status of the object

Parameters:statusStatus the status object that should be set
setThumbnail(component)

Set component as thumbnail.

unAssignUser(user)

Unassigns a user from a task

Parameters:user – A User object representing the user that should be unassigned from the task.
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.ShotLegacy[source]
__init__

x.__init__(...) initializes x; see help(type(x)) for signature

getFPS()[source]
getFrameEnd()[source]
getFrameStart()[source]
getSequence()[source]

@deprecated Use getParent instead

class ftrack.ShotStatus(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()[source]
getName()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
ftrack.Show

alias of Project

class ftrack.StandardStructure(projectVersionsPrefix=None, illegalCharacterSubstitute='_')[source]

Project hierarchy based structure that only supports Components.

The resource identifier is generated from the project code, the name of objects in the project structure, asset name and version number:

my_project/folder_a/folder_b/asset_name/v003

If the component is a file component then the name of the component and the file type are used as filename in the resource identifier:

my_project/folder_a/folder_b/asset_name/v003/foo.jpg

If the component is a sequence component then a sequence expression, %04d, is used. E.g. a component with the name foo yields:

my_project/folder_a/folder_b/asset_name/v003/foo.%04d.jpg

For the member components their index in the sequence is used:

my_project/folder_a/folder_b/asset_name/v003/foo.0042.jpg

The name of the component is added to the resource identifier if the component is a container. E.g. a container component with the name bar yields:

my_project/folder_a/folder_b/asset_name/v003/bar

For a member of that container the file name is based on the component name and file type:

my_project/folder_a/folder_b/asset_name/v003/bar/baz.pdf
__init__(projectVersionsPrefix=None, illegalCharacterSubstitute='_')[source]

Initialise structure.

If projectVersionsPrefix is defined, insert after the project code for versions published directly under the project:

my_project/<projectVersionsPrefix>/v001/foo.jpg

Replace illegal characters with illegalCharacterSubstitute if defined.

Note

Nested component containers/sequences are not supported.

getResourceIdentifier(entity, context=None)[source]

Return a resource identifier for supplied entity.

context can be a mapping that supplies additional information, but is unused in this implementation.

sanitiseForFilesystem(value)[source]

‘Return value with illegal filesystem characters replaced.

An illegal character is one that is not typically valid for filesystem usage, such as non ascii characters, or can be awkward to use in a filesystem, such as spaces. Replace these characters with the character specified by illegalCharacterSubstitute on initialisation. If no character was specified as substitute then return value unmodified.

class ftrack.Status(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()[source]
getName()[source]
getState()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.Statusable[source]
__init__

x.__init__(...) initializes x; see help(type(x)) for signature

getStatus()[source]

Return the status of the object or None if it has no status.

setStatus(status)[source]

Set status of the object

Parameters:statusStatus the status object that should be set
class ftrack.String(content=None)[source]

Data wrapper using StringIO instance.

__init__(content=None)[source]

Initialise data with content.

close()

Flush buffers and prevent further access.

flush()

Flush buffers ensuring data written.

read(limit=None)

Return content from current position up to limit.

seek(offset, whence=0)

Move internal pointer by offset.

tell()

Return current position of internal pointer.

write(content)

Write content at current position.

ftrack.StringIO()

StringIO([s]) – Return a StringIO-like stream for reading or writing

class ftrack.Structure(prefix='')[source]

Structure plugin interface.

A structure plugin should compute appropriate paths for data.

__init__(prefix='')[source]

Initialise structure.

getResourceIdentifier(entity)[source]

Return a resourceIdentifier for supplied entity.

class ftrack.Task(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
addPredecessor(task)

Add a dependency from another task to this task

Parameters:task – The predecessor task
addSuccessor(task)

Add a dependency from this task to another task

Parameters:task – The successor task
assignUser(user)[source]

Assigns a user to a task

Parameters:user – A User object representing the user that should be assigned to the task.
create(objectType, name, statusId=None, typeId=None, priorityId=None)

Create a context from objectType with name.

createAsset(name, assetType, task=None)

Create a new asset or return existing.

name is the name of the asset and assetType is the type of the asset defined by its short name. A task or task id can also be passed in which will be used as the default task when versions are created on this asset.

createAttachment(file, fileName=None, isThumb=False)

Legacy method to attach files to objects.

createEpisode(name)

Create an episode from name.

createManager(user, managerType)

Create a manager from user and managerType for this entity.

user should be a User instance.

managerType should be a ManagerType instance.

createNote(note, category='auto', recipients=None)

Create note with text note.

Optional category can be specified to set the note category of the note. Can be either NoteCategory or category id. If set to auto the default note category setting will be used.

Recipients can be specified by setting recipients to be a list of User or user ids.

createSequence(name)

Create a sequence from name.

createShot(name)

Create a shot from name.

createTask(name, taskType=None, taskStatus=None)

Create a task from name, taskType and taskStatus.

createThumbnail(file, fileName='image.jpg')

Create thumbnail from file.

delete()
get(key)
getAsset(name, assetType)[source]

Get an Asset

Parameters:
  • namestr with the name of the asset
  • assetType – a string with the asset type like ‘geo’
Return type:

Asset

getAssetVersions()[source]

Get AssetVersions

Return type:list of AssetVersions
getAssets(assetTypes=None, names=None, includeChildren=False, componentNames=None, excludeWithTasks=False)[source]

Get Assets

Parameters:
  • names – A list with names of the assets
  • assetTypes – A list with names of the asset types or short names of the asset types or asset type ids
  • componentNames – A list with names of components that the versions must have at least one of
  • excludeWithTasks – A bool which defaults to False, can be used to get assets with versions that are not connected to any tasks
Return type:

FTList of Assets

getBid()[source]
getChildren(objectType=None, depth=1)

Get attached Children (not tasks)

Return type:FTList of Children
getDefaultRecipients()

Get default recipients for an object

Return type:list with User objects
getDescription()[source]
getEndDate()[source]
getEntityRef()
getEpisodes()
getFPS()
getFrameEnd()
getFrameStart()
getId()[source]
getLists()[source]

Returns the lists that have been linked/associated with this task. NOTE: There is a difference between a task being added to a list and lists linked to a task

Return type:list
getManagers()

Return all managers assigned to this entity.

getMeta(key=None)

Get metadata from an object. This method can be used to retrive meta data from an object. The data is stored in key/value pairs where key and value are strings.

This method can also be used without any arguments to retrive a dict with all metadata key/value pairs attached to this object.

Parameters:key – A string representing the key or None to retrive all key/value pairs on this object.
Return type:string or dict
getName()[source]
getNotes()

Fetch notes from an entity, this will include replies.

getObjectType()[source]
getParent()

Get parent object from this object

Return type:FTObject of that type
getParents()

Get parent object from this object

Return type:list owith items of that type
getPredecessors()

Returns a list of items that this item depends on

Return type:list
getPriority()[source]

Return the priority of the object or None if it has no priority.

getProject()[source]

Get project this object belongs to

Return type:Project
getSequence()

@deprecated Use getParent instead

getSequences()

Get attached Sequences

Return type:FTList of Sequence
getShots()

Get attached Shots

Return type:FTList of Shot
getShow()

@deprecated Use getParent instead

getStartDate()[source]
getStatus()

Return the status of the object or None if it has no status.

getSuccessors()

Returns a list of items that depend on this object

Return type:list
getTasks(*args, **argv)

Get attached Tasks

Parameters:
  • userslist with usernames like [‘username1’,’username2’] to filter out tasks
  • taskTypeslist representing task types. Can be TaskType objects, their IDs or their names.
  • taskStatuseslist representing task statuses. Can be TaskStatus objects, their IDs or their names.
  • stateslist with states. Possible states are NOT_STARTED, IN_PROGRESS, DONE, BLOCKED which are availible from the ftrack module
  • activeProjectsOnlybool Default to True. specifying if only to query active projects.
  • includeChildrenbool Default to False. childrens tasks should be included.
  • includePathbool Default to False. specifying if the path should be added to each task. Much faster than useing getParents on each task afterwards.
Return type:

FTList with Task

getThumbnail()

Get a url to the thumbnail.

getTimelogs(start=None, end=None, includeChildren=False)

Return timelogs between start and end dates.

If includeChildren is set, also return timelogs on descendants.

getType()[source]

Return the type of the object or None if it has no type.

getURL()

Return url that can be used to view this entity in a browser.

getUsers()[source]

Get Users assigned to this Task

Return type:FTList of User
getWebWidgetUrl(name, theme='dark')

Return url that can be used is a qt webwidget.

name should be the name of the ftrack panel. theme is optional.

keys()

Return keys accessible using get/set methods.

metaKeys()

Return keys accessible using getMeta/setMeta methods.

removePredecessor(task)

remove a dependency another task to this task

Parameters:task – The predecessor task
removeSuccessor(task)

remove a dependency from this task to another task

Parameters:task – The successor task
set(key, value=None)
setEndDate(theDate)[source]
setMeta(key, value=None)

Set metadata on an object. This method can be used to store arbitrary data on an object. The data is stored in key/value pairs where key and value are strings.

This method also accepts a dict with key/value pairs

Parameters:
  • key – A string representing the key or a dict with key/value pairs.
  • value – A string representing the value or None if key is a dict.
setPriority(priority)[source]
setStartDate(theDate)[source]
setStatus(status)

Set status of the object

Parameters:statusStatus the status object that should be set
setThumbnail(component)

Set component as thumbnail.

unAssignUser(user)[source]

Unassigns a user from a task

Parameters:user – A User object representing the user that should be unassigned from the task.
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
ftrack.TaskStatus

alias of Status

class ftrack.TaskType(id=None, dict=None, eagerload=None)[source]
__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()[source]
getName()[source]
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.TempData(id=None, dict=None, eagerload=None)[source]

Represent a temp object.

__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()
keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.Thumbnailable[source]

Mixin to add support for thumbnails.

__init__

x.__init__(...) initializes x; see help(type(x)) for signature

createThumbnail(file, fileName='image.jpg')[source]

Create thumbnail from file.

getThumbnail()[source]

Get a url to the thumbnail.

setThumbnail(component)[source]

Set component as thumbnail.

class ftrack.Timelog(id=None, dict=None, eagerload=None)[source]

Represent a timelog.

__init__(id=None, dict=None, eagerload=None)
delete()
get(key)
getEntityRef()
getId()
getUser()[source]

Return timelog user.

keys()

Return keys accessible using get/set methods.

set(key, value=None)
xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.Timereportable[source]

Mixin for timelogging.

__init__

x.__init__(...) initializes x; see help(type(x)) for signature

getTimelogs(start=None, end=None, includeChildren=False)[source]

Return timelogs between start and end dates.

If includeChildren is set, also return timelogs on descendants.

class ftrack.UnmanagedLocation(id=None, dict=None, eagerload=None, accessor=None, structure=None, resourceIdentifierTransformer=None, priority=50)[source]

Represent location for un-managed components.

An un-managed component is one that is only tracked by the system without taking any ownership of the data or its structure. This is similar to the previous behaviour when handling data.

May also prove useful for those who want to manage data themselves and ensure that users of the API cannot accidentally manage the data through the system.

__init__(id=None, dict=None, eagerload=None, accessor=None, structure=None, resourceIdentifierTransformer=None, priority=50)

Initialise location with either id or dict.

accessor can be an instance of ftrack.Accessor and will manage access to data in this location for this instance.

structure can be an instance of ftrack.Structure and will be used to provide structure hints when adding components.

resourceIdentifierTransformer can be an instance of ftrack.ResourceIdentifierTransformer and, if set, will be called to encode resource identifiers before storing them centrally or to decode centrally retrieved identifiers before setting on a component.

priority is a basic hint for the priority of the location versus others in this session. The lower the number the higher the priority with zero considered highest priority.

addComponent(component, recursive=True, manageData=False)[source]

Add component to this location.

If component is a container and recursive is True then also add each member of the container to this location.

Note

manageData must be False as this type of location guarantees to never attempt management of data. Will raise ftrack.LocationError if a non false value is passed in.

Note

Externally managed data must still match the path generated by this location’s structure interface. No existence check is currently performed.

Return component in this location.

adoptComponent(component)

Adopt and return component.

Set location on component to this location, as well as retrieving and setting appropriate resource identifier.

Raise ftrack.ComponentNotInLocationError if component not found in this location.

Note that this compliments getComponent() rather than addComponent().

See also

getComponent().

adoptComponents(*args, **kw)

Adopt and return components.

For each component in components, set location to this location, as well as retrieving and setting appropriate resource identifier.

Raise ftrack.ComponentNotInLocationError if any of the components are not found in this location.

See also

getComponents().

delete()
get(key)
getAccessor()

Return current accessor for this location.

getComponent(componentId)

Retrieve component with componentId from this location.

Raise ftrack.ComponentNotInLocationError if component not found in this location.

Note

If an accessor is available for this location then the access path will also be set on the returned component.

See also

adoptComponent().

getComponentAvailabilities(componentIds)

Return list of availabilities for components in this location.

getComponentAvailability(componentId)

Return availability as percentage of component in this location.

getComponents(*args, **kw)

Retrieve components with componentIds from this location.

Raise ftrack.ComponentNotInLocationError if any of the specified components are not found in this location.

If componentIds is not specified (or None) then retrieve ALL components currently in this location.

Note

If an accessor is available for this location then the access path will also be set on the returned component.

See also

adoptComponents().

getEntityRef()
getId()

Return id.

getName()

Return name.

getPriority()

Return priority.

getResourceIdentifierTransformer()

Return current resource identifier transformer for this location.

getStructure()

Return current structure for this location.

keys()

Return keys accessible using get/set methods.

removeComponent(componentId, recursive=True, manageData=False)[source]

Remove component with componentId from this location.

If component is a container and recursive is True then also remove each member of the container from this location.

Note

manageData must be False as this type of location guarantees to never attempt management of data. Will raise ftrack.LocationError if a non false value is passed in.

set(key, value=None)
setAccessor(accessor)

Set current accessor for this location.

setPriority(priority)

Set priority.

setResourceIdentifierTransformer(resourceIdentifierTransformer)

Set current resourceIdentifierTransformer for this location.

setStructure(structure)

Set current structure for this location.

xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.UnmanagedMemoryLocation(*args, **kw)[source]

Represent memory based location for un-managed components.

__init__(*args, **kw)

Initialise location.

addComponent(component, recursive=True, manageData=False)

Add component to this location.

If component is a container and recursive is True then also add each member of the container to this location.

Note

manageData must be False as this type of location guarantees to never attempt management of data. Will raise ftrack.LocationError if a non false value is passed in.

Note

Externally managed data must still match the path generated by this location’s structure interface. No existence check is currently performed.

Return component in this location.

adoptComponent(component)

Adopt and return component.

Set location on component to this location, as well as retrieving and setting appropriate resource identifier.

Raise ftrack.ComponentNotInLocationError if component not found in this location.

Note that this compliments getComponent() rather than addComponent().

See also

getComponent().

adoptComponents(*args, **kw)

Adopt and return components.

For each component in components, set location to this location, as well as retrieving and setting appropriate resource identifier.

Raise ftrack.ComponentNotInLocationError if any of the components are not found in this location.

See also

getComponents().

delete()
get(key)
getAccessor()

Return current accessor for this location.

getComponent(componentId)

Retrieve component with componentId from this location.

Raise ftrack.ComponentNotInLocationError if component not found in this location.

Note

If an accessor is available for this location then the access path will also be set on the returned component.

See also

adoptComponent().

getComponentAvailabilities(componentIds)

Return list of availabilities for components in this location.

getComponentAvailability(componentId)

Return availability as percentage of component in this location.

getComponents(*args, **kw)

Retrieve components with componentIds from this location.

Raise ftrack.ComponentNotInLocationError if any of the specified components are not found in this location.

If componentIds is not specified (or None) then retrieve ALL components currently in this location.

Note

If an accessor is available for this location then the access path will also be set on the returned component.

See also

adoptComponents().

getEntityRef()
getId()

Return id.

getName()

Return name.

getPriority()

Return priority.

getResourceIdentifierTransformer()

Return current resource identifier transformer for this location.

getStructure()

Return current structure for this location.

keys()

Return keys accessible using get/set methods.

removeComponent(componentId, recursive=True, manageData=False)

Remove component with componentId from this location.

If component is a container and recursive is True then also remove each member of the container from this location.

Note

manageData must be False as this type of location guarantees to never attempt management of data. Will raise ftrack.LocationError if a non false value is passed in.

set(key, value=None)
setAccessor(accessor)

Set current accessor for this location.

setPriority(priority)

Set priority.

setResourceIdentifierTransformer(resourceIdentifierTransformer)

Set current resourceIdentifierTransformer for this location.

setStructure(structure)

Set current structure for this location.

xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
class ftrack.User(id=None, dict=None, eagerload=None)[source]

Username can be supplied to constructor to fetch a user

Parameters:username – A string with the username of the user
__init__(id=None, dict=None, eagerload=None)
addRole(role, project=None)[source]

Add role to this user. If project is None the role will be added to all projects.

createBooking(description, startdate, enddate, project=None, bookingType=None)[source]

Create a booking for this project

Parameters:
  • description – A str with the description of this booking
  • startdate – A datetime with the start date of this booking
  • enddate – A datetime with the end date of this booking
  • user – A Project to book on (optional)
  • bookingType – A str Booking type. Use Booking.VACATION

or Booking.PROJECT. If project param is used, the bookingType must be Booking.PROJECT.

createThumbnail(file, fileName='image.jpg')

Create thumbnail from file.

delete()
get(key)
getApiKey()[source]

Get the api that can be used for this user. Will raise error if you dont have the correct permission to do this. :rtype: str

getBookings()[source]

Return all bookings for this project

getEmail()[source]
getEntityRef()
getId()[source]
getMeta(key=None)

Get metadata from an object. This method can be used to retrive meta data from an object. The data is stored in key/value pairs where key and value are strings.

This method can also be used without any arguments to retrive a dict with all metadata key/value pairs attached to this object.

Parameters:key – A string representing the key or None to retrive all key/value pairs on this object.
Return type:string or dict
getName()[source]
getRoleProjects(role)[source]

Return active projects a role is valid for.

getRoles()[source]

Get Roles that belong to this user :rtype: FTList with Role

getTasks(*args, **argv)[source]

Get Tasks assigned to this User

Parameters:
  • taskTypeslist representing task types. Can be TaskType objects, their IDs or their names.
  • taskStatuseslist representing task statuses. Can be TaskStatus objects, their IDs or their names.
  • stateslist with states. Possible states are NOT_STARTED, IN_PROGRESS, DONE, BLOCKED which are availible from the ftrack module
  • activeProjectsOnlybool Default to True. specifying if only to query active projects.
  • projectslist representing Projects. Can be Project objects or their IDs.
  • includePathbool Default to False. specifying if the path should be added to each task. Much faster than useing getParents on each task afterwards.
Return type:

FTList with Task

getThumbnail()

Get a url to the thumbnail.

getTimelogs(start=None, end=None, includeChildren=False)

Return timelogs between start and end dates.

If includeChildren is set, also return timelogs on descendants.

getUsername()[source]
keys()

Return keys accessible using get/set methods.

metaKeys()

Return keys accessible using getMeta/setMeta methods.

removeRole(role, project=None)[source]

Remove role from project.

If project is None the role will be removed from all projects.

resetApiKey()[source]

Reset the user api key. Will raise error if you dont have the correct permission to do this. :rtype: str

set(key, value=None)
setMeta(key, value=None)

Set metadata on an object. This method can be used to store arbitrary data on an object. The data is stored in key/value pairs where key and value are strings.

This method also accepts a dict with key/value pairs

Parameters:
  • key – A string representing the key or a dict with key/value pairs.
  • value – A string representing the value or None if key is a dict.
setThumbnail(component)

Set component as thumbnail.

xmlServer = <FTrackCore.api.xmlserver.XMLServer instance at 0x34cfea8>
ftrack.VersionStatus

alias of Status

class ftrack.WebWidgetable[source]
__init__

x.__init__(...) initializes x; see help(type(x)) for signature

getURL()[source]

Return url that can be used to view this entity in a browser.

getWebWidgetUrl(name, theme='dark')[source]

Return url that can be used is a qt webwidget.

name should be the name of the ftrack panel. theme is optional.

class ftrack.XMLServer(url, verbose=False, allow_none=True)[source]
__init__(url, verbose=False, allow_none=True)[source]
action(_action, data)[source]
addTempObject(item)[source]
clearGetCache()[source]

Clear any data stored in get cache.

disableGetCache()[source]

Disable caching of get calls.

Also, remove any stored values for cached get calls.

enableGetCache()[source]

Enable caching of get calls.

endBatch()[source]
getOS()[source]
getStatistics()[source]

Return current statistics.

getTotalRequests()[source]
getTotalTime()[source]
handleServerErrors(error)[source]
resetDebug()[source]
resetStatistics()[source]

Reset statistics.

startBatch()[source]
ftrack.abstractmethod(funcobj)[source]

A decorator indicating abstract methods.

Requires that the metaclass is ABCMeta or derived from it. A class that has a metaclass derived from ABCMeta cannot be instantiated unless all of its abstract methods are overridden. The abstract methods can be called using any of the normal ‘super’ call mechanisms.

Usage:

class C:

__metaclass__ = ABCMeta @abstractmethod def my_abstract_method(self, ...):

...
ftrack.asc(on)[source]
ftrack.clearGetCache()[source]

Clear any data stored in ‘get’ cache.

ftrack.createAssetType(name, short)[source]

Create an asset type :param name: str the nice name for this type :param short: str the shot name that will be used in scripts

ftrack.createComponent(*args, **kw)[source]

Create a component with name.

path can be a string representing a filesystem path to the data to use for the component. The path can also be specified as a sequence string, in which case a sequence component with child components for each item in the sequence will be created automatically. The accepted format for a sequence is ‘{head}{padding}{tail} [{ranges}]’. For example:

'/path/to/file.%04d.ext [1-5, 7, 8, 10-20]'

If location is specified, then the created component will be automatically added to that location. The returned component will also be configured with that location set as its current location. It should be an instance of ftrack.Location, the string ‘auto’ (default) or None.

Note

If path is not specified the location property will be ignored.

If location is set to ‘auto’ the most suitable location will be selected and used. If no suitable location is found the component will be created without being added to a location.

If name is set to be ‘ftrackreview-mp4’, ‘ftrackreview-webm’ or ‘ftrackreview-image’ when ‘auto’ is specified the review location will be used.

If the specified location is of type ftrack.Location, it needs to be configured with a location plugin that is loaded in the current session. If the component fails to be added to the specified location, it will be removed and the underlying exception will be raised.

Note

If a location is not specified at component creation time then no path data will be stored in ftrack and the data not moved in any way. Instead, the returned component will be configured with a special ‘origin’ location allowing the component to be added to other locations manually using ftrack.Location.addComponent().

If manageData is True then manage transfer of data to the location. If False, assume the data has been managed externally and just record the component as present in that location. If manageData is None, let the location decide if data should be managed.

Note

If no location is specified, manageData will be ignored.

An optional versionId can be passed to specify the version entity that this component should be linked to.

Warning

A component cannot currently be attached to a version after creation.

If systemType is not specified it will be inferred from the path. If no path set it will default to ‘file’.

size is the size of the component in bytes. size will be calculated automatically from the path if not specified. If size is specified for a sequence it will be stored for the sequence and for child components as size / number of child components.

padding refers to the padding value for a sequence. It makes no sense for other component types and an FTrackError will be raised if padding is attempted to be set on non-sequence components. If not set and a path is used to determine the sequence, then the value will be calculated automatically.

file is a deprecated synonym for path. Please update code to use path in future.

An optional containerId can be passed to specify the container component that this component should be added to. The id must refer to an existing container component.

ftrack.createJob(description, status, user=None)[source]

Create a api job visible in ftrack

Parameters:
  • descriptionstr a description of the job
  • statusstr status of the job. Possible statuses are queued, running, done, failed
  • userUser set the user the job belongs to
Return type:

Job

ftrack.createLocation(name)[source]

Create and return a new Location with name.

ftrack.createProject(fullname, name, workflow)[source]

Create a project

Parameters:
  • fullnamestr the long name of the project
  • namestr the shot name that will be used in scripts
  • workflowProjectScheme the project scheme that should be used in this project. Defines types and statuses.
Return type:

Project

ftrack.createReviewSession(name, description, projectId)[source]

Create review session on projectId with name and description.

ftrack.createShow(fullname, name, workflow)

Create a project

Parameters:
  • fullnamestr the long name of the project
  • namestr the shot name that will be used in scripts
  • workflowProjectScheme the project scheme that should be used in this project. Defines types and statuses.
Return type:

Project

ftrack.createTempData(data, expiry=None)[source]

Create a ftrack.TempData with data.

expiry is optional and should be a datetime object. If no expiry is specified it will default to 1 hour from now.

ftrack.createTimelog(duration, start=None, userId=None, contextId=None, name=None, comment=None, timeZoneOffset=None)[source]

Create a timelog with duration in seconds.

start is the datetime for the timelog and will default to now.

userId will default to the current user but can be overriden.

contextId is an id of a task or project this timelog should be created for.

name is optional but should be included if this timelog does not have a context or a ValueError will be raised.

comment is optional.

timeZoneOffset is optional and only recommended if time zone support is enabled on the server. It can be used to manually set the offset from UTC. If not set the offset will be automatically calculated based on the API user.

ftrack.desc(on)[source]
ftrack.disableGetCache()[source]

Disable caching of ‘get’ calls.

ftrack.enableGetCache()[source]

Enable caching of ‘get’ calls.

ftrack.ensureLocation(name)[source]

Return location with name, creating if necessary.

ftrack.filter_by(arg=None, **args)[source]
ftrack.getActivityEvents(projectId=None, fromEventId=0, fromDate=None, actions=None, preloadObjects=False, limit=100)[source]

Get ActivityEvents :param projectId: str id of the project :param fromEventId: str incremental id of the events :param fromDate: datetime id of the project :param actions: str id of the project :param preloadObjects: bool include object in each event. Defaults to False, if False objects are fetched on request, if True objects and included in event query to minimize number of total requests. :param limit: int limit number of events, default is 100 :rtype: list of Events

ftrack.getAssetPathPrefix(*args, **kw)[source]

Return asset path prefix.

ftrack.getAssetTypes()[source]

Get AssetTypes

Return type:FTList of AssetTypes
ftrack.getComponentAvailabilities(componentIds, locationIds=None)[source]

Return availability of each component in componentIds.

Use locationIds to specify a list of locations by id that should be checked. If not specified then all known locations will be checked.

Return a list of dictionaries, {locationId:percentage_availability}, that can be mapped against the list of componentIds.

ftrack.getComponentAvailability(componentId, locationIds=None)[source]

Return component with componentId availability in locations.

Use locationIds to specify a list of locations by id that should be checked. If not specified then all known locations will be checked.

Return a dictionary of {locationId:percentage_availability}

ftrack.getDiagnostics()[source]
ftrack.getDisks()[source]

Get Disks

Return type:FTList of Disk
ftrack.getFromPath(path)[source]
ftrack.getGroups()[source]

Return all top level groups.

ftrack.getJobs(status=None)[source]

Get Events :param status: str status of the jobs :rtype: list of Jobs

ftrack.getListCategories()[source]

Get ListCategories

Return type:FTList of ListCategory
ftrack.getLocations(includeHidden=False, excludeInaccessible=False)[source]

Return FTList of all Locations.

If includeHidden is True then hidden locations typically used for internal purposes will also be returned.

If excludeInaccessible is True then only locations that currently have a valid accessor will be returned.

ftrack.getManagerTypes()[source]

Return a list of all manager types.

ftrack.getNoteCategories()[source]

Get NoteCategories

Return type:FTList of NoteCategory
ftrack.getNumMessages()[source]
ftrack.getPriorities()[source]

Get Priority

Return type:FTList of Priority
ftrack.getProject(path)[source]

Get a Project` from a path

Parameters:path (list) – A list with strings representing the path to the Project.
Return type:Project
ftrack.getProjectSchemes()[source]

Get all project schemas. Project schemas define types and statuses that should be used

Return type:list with ProjectScheme
ftrack.getProjects(includeHidden=False)[source]

Get all projects

Return type:list with Project
ftrack.getReviewSessions(projectId)[source]

Return all review sessions on projectId.

ftrack.getSequence(path)[source]

Get a Sequence` from a path

Parameters:path (list) – A list with strings representing the path to the Sequence.
Return type:Sequence
ftrack.getSequenceFromPath(path)[source]
ftrack.getShot(path)[source]

Get a shot from a path

Parameters:path (list) – A list with strings representing the path to the Shot.
Return type:Shot
ftrack.getShotFromPath(path)[source]
ftrack.getShow(path)

Get a Project` from a path

Parameters:path (list) – A list with strings representing the path to the Project.
Return type:Project
ftrack.getShowFromPath(path)[source]
ftrack.getShows(includeHidden=False)

Get all projects

Return type:list with Project
ftrack.getTaskStatuses()[source]

Get TaskStatus

Return type:FTList of TaskStatus
ftrack.getTaskTypes()[source]

Get TaskTypes

Return type:FTList of TaskTypes
ftrack.getUUID()[source]

Retrived a unique id from the server. Same type of id as is used for objects (uuid)

Return type:str
ftrack.getUser(username)[source]

Get a user :param username: str the username of the user :rtype: User

ftrack.getUsers()[source]

Get all users

Return type:list with User
ftrack.getWebWidgetUrl(name, theme='dark', entityId=None, entityType=None)[source]

Return URL to web widget with name for entityId and entityType

theme is optional and can be specifed to set which theme the widget should use.

ftrack.limit(limit)[source]
ftrack.order_by(*args)[source]
ftrack.pickLocation(componentId=None, includeHidden=False)[source]

Return an appropriate location to use.

If componentId is None return highest priority location that is accessible. If componentId is not None return highest priority accessible location that has the component matching that id.

If includeHidden is True then hidden locations typically used for internal purposes only will also be considered.

Return None if no suitable location could be picked.

ftrack.pickLocations(componentIds, includeHidden=False)[source]

Return appropriate locations to use for componentIds.

Return list of highest priority locations that can be mapped against each component referenced in componentIds.

If includeHidden is True then hidden locations, typically used for internal purposes, will also be considered.

If no suitable location could be picked for a component then its location entry will be None.

ftrack.printDebug()[source]

Print debug information for this ftrack session. Includes number of requests and time spent during requests.

ftrack.resetDebug()[source]

Reset the debug data

ftrack.resumeCreate()[source]
ftrack.safeURL(url)[source]

Converts a string to one that is safe to use in a filename

Parameters:url – A str.
Return type:string
ftrack.setup(actions=True)[source]

Helper function to setup FTrack.

ftrack.suspendCreate()[source]
ftrack.syncUsers()[source]

Sync users from external service such as ldap

ftrack.withGetCache(function)[source]

Decorate function to use xmlserver get cache for duration of call.