ftrack_api.entity.location

class ftrack_api.entity.location.Location(session, data=None, reconstructing=False)[source]

Represent storage for components.

__init__(session, data=None, reconstructing=False)[source]

Initialise entity.

session is an instance of ftrack_api.session.Session that this entity instance is bound to.

data is a mapping of key, value pairs to apply as initial attribute values.

reconstructing indicates whether this entity is being reconstructed, such as from a query, and therefore should not have any special creation logic applied, such as initialising defaults for missing data.

add_component(component, source, recursive=True)[source]

Add component to location.

component should be a single component instance.

source should be an instance of another location that acts as the source.

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

Raise ftrack_api.LocationError if managing data and 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.

Note

A Session.commit may be automatically issued as part of the component registration.

add_components(components, sources, recursive=True, _depth=0)[source]

Add components to location.

components should be a list of component instances.

sources may be either a single source or a list of sources. If a list then each corresponding index in sources will be used for each component. A source should be an instance of another location.

Raise ftrack_api.exception.ComponentInLocationError if any component in components already exists in this location. In this case, no changes will be made and no data transferred.

Raise ftrack_api.exception.LocationError if managing data and 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.

Note

A Session.commit may be automatically issued as part of the components registration.

Important

If this location manages data then the components data is first transferred to the target prescribed by the structure plugin, using the configured accessor. If any component fails to transfer then ftrack_api.exception.LocationError is raised and none of the components are registered with the database. In this case it is left up to the caller to decide and act on manually cleaning up any transferred data using the ‘transferred’ detail in the raised error.

Likewise, after transfer, all components are registered with the database in a batch call. If any component causes an error then all components will remain unregistered and ftrack_api.exception.LocationError will be raised detailing issues and any transferred data under the ‘transferred’ detail key.

remove_component(component, recursive=True)[source]

Remove component from location.

Note

A Session.commit may be automatically issued as part of the component deregistration.

remove_components(components, recursive=True)[source]

Remove components from location.

Note

A Session.commit may be automatically issued as part of the components deregistration.

get_component_availability(component)[source]

Return availability of component in this location as a float.

get_component_availabilities(components)[source]

Return availabilities of components in this location.

Return list of float values corresponding to each component.

get_resource_identifier(component)[source]

Return resource identifier for component.

Raise ftrack_api.exception.ComponentNotInLocationError if the component is not present in this location.

get_resource_identifiers(components)[source]

Return resource identifiers for components.

Raise ftrack_api.exception.ComponentNotInLocationError if any of the components are not present in this location.

get_filesystem_path(component)[source]

Return filesystem path for component.

get_filesystem_paths(components)[source]

Return filesystem paths for components.

get_url(component)[source]

Return url for component.

Raise AccessorFilesystemPathError if URL could not be determined from component or AccessorUnsupportedOperationError if retrieving URL is not supported by the location’s accessor.

attributes = None
clear()

Reset all locally modified attribute values.

default_projections = None
entity_type = 'Entity'
get(k[, d]) D[k] if k in D, else d.  d defaults to None.
items()

Return list of tuples of (key, value) pairs.

Note

Will fetch all values from the server if not already fetched or set locally.

keys() a set-like object providing a view on D's keys
merge(entity, merged=None)

Merge entity attribute values and other data into this entity.

Only merge values from entity that are not ftrack_api.symbol.NOT_SET.

Return a list of changes made with each change being a mapping with the keys:

  • type - Either ‘remote_attribute’, ‘local_attribute’ or ‘property’.

  • name - The name of the attribute / property modified.

  • old_value - The previous value.

  • new_value - The new merged value.

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.

primary_key_attributes = None
setdefault(k[, d]) D.get(k,d), also set D[k]=d if k not in D
update([E, ]**F) None.  Update D from mapping/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, v in F.items(): D[k] = v

values()

Return list of values.

class ftrack_api.entity.location.MemoryLocationMixin[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__()
clear() None.  Remove all items from D.
get(k[, d]) D[k] if k in D, else d.  d defaults to None.
items() a set-like object providing a view on D's items
keys() a set-like object providing a view on 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
update([E, ]**F) None.  Update D from mapping/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, v in F.items(): D[k] = v

values() an object providing a view on D's values
class ftrack_api.entity.location.UnmanagedLocationMixin[source]

Location that does not manage data.

__init__()
clear() None.  Remove all items from D.
get(k[, d]) D[k] if k in D, else d.  d defaults to None.
items() a set-like object providing a view on D's items
keys() a set-like object providing a view on 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
update([E, ]**F) None.  Update D from mapping/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, v in F.items(): D[k] = v

values() an object providing a view on D's values
class ftrack_api.entity.location.OriginLocationMixin[source]

Special origin location that expects sources as filepaths.

__init__()
clear() None.  Remove all items from D.
get(k[, d]) D[k] if k in D, else d.  d defaults to None.
items() a set-like object providing a view on D's items
keys() a set-like object providing a view on 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
update([E, ]**F) None.  Update D from mapping/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, v in F.items(): D[k] = v

values() an object providing a view on D's values
class ftrack_api.entity.location.ServerLocationMixin[source]

Location representing ftrack server.

Adds convenience methods to location, specific to ftrack server.

get_thumbnail_url(component, size=None)[source]

Return thumbnail url for component.

Optionally, specify size to constrain the downscaled image to size x size pixels.

Raise AccessorFilesystemPathError if URL could not be determined from resource_identifier or AccessorUnsupportedOperationError if retrieving URL is not supported by the location’s accessor.

__init__()
clear() None.  Remove all items from D.
get(k[, d]) D[k] if k in D, else d.  d defaults to None.
items() a set-like object providing a view on D's items
keys() a set-like object providing a view on 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
update([E, ]**F) None.  Update D from mapping/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, v in F.items(): D[k] = v

values() an object providing a view on D's values