`sgsession.Session`¶

The Session is a wrapper around a Shotgun instance, proxying requests to the server and applying additional logic on top of it. The Session instance is designed to be used for a single task and then discarded, since it makes the assumption that entity relationships do not change.

While not fully documented below, this object will proxy all attributes to the underlying Shotgun instance, so you can treat this as you would a Shotgun instance.

class sgsession.session.Session(shotgun=None, schema=None, *args, **kwargs)¶

Shotgun wrapper.

Parameters:	shotgun – A Shotgun instance to wrap, or the name to be passed to `shotgun_api3_registry.connect()` in order to construct one.

If passed a name, the remaining args and kwargs will also be passed to the api registry connector.

If passed a descendant of shotgun_api3.Shotgun (or one is constructed via the registry), it will be wrapped in a ShotgunPool so that it becomes thread-safe. Any other objects (e.g. mock servers) are used unmodified.

If passed nothing, shotgun_api3_registry.connect will be called the first time shotgun is accessed (which will happen on many operations). To stop this behaviour, pass False.

Entity Control¶

Session.merge(data, over=None, created_at=None, _depth=0, _memo=None)¶

Import data containing raw entities into the session.

This will effectively return a copy of any nested structure of lists, tuples, and dicts, while converting any dicts which look like entities into an Entity. The returned structure is a copy of the original.

Parameters:	data (dict) – The raw fields to convert into an `Entity`. over (bool) – Control for merge behaviour with existing data. `True` results in the new data taking precedence, and `False` the old data. The default of `None` will automatically decide based on the `updated_at` field.
Returns:	The `Entity`. This will not be a new instance if the entity was already in the session, but it will have all the newly merged data in it.

Session.get(*args, **kwargs)¶

Get one entity by type and ID.

Parameters:	type (str) – The entity type to lookup. id (int) – The entity ID to lookup. Accepts `list` or `tuple` of IDs, and returns the same. fetch (bool) – Request this entity from the server if not cached?

Session.filter_exists(entities, *args, **kwargs)¶

Return the subset of given entities which exist (non-retired).

Parameters:	entities (list) – An iterable of entities to check. check (bool) – Should the server be consulted if we don’t already know? force (bool) – Should we always check the server?
Returns set:	The entities which exist, or aren’t sure about.

This will handle multiple entity-types in multiple requests.

Fetching Fields¶

Session.fetch(entities, *args, **kwargs)¶

Fetch the named fields on the given entities.

Parameters:	to_fetch (list) – Entities to fetch fields for. fields (list) – The names of fields to fetch on those entities. force (bool) – Perform a request even if we already have this data?

This will safely handle multiple entitiy types at the same time, and by default will only make requests of the server if some of the data does not already exist.

Note

This does not assert that all “important” fields exist. See fetch_core().

Session.fetch_core(entities, *args, **kwargs)¶

Assert all “important” fields exist, and fetch them if they do not.

Parameters:	to_fetch (list) – The entities to get the core fields on.

This will populate all important fields, and important fields on linked: entities.

Session.fetch_backrefs(entities, *args, **kwargs)¶

Fetch requested backrefs on the given entities.

Parameters:	to_fetch (list) – Entities to get backrefs on. backref_type (str) – The entity type to look for backrefs on. field (str) – The name of the field to look for backrefs in.

# Find all tasks which refer to this shot.
>>> session.fetch_backrefs([shot], 'Task', 'entity')

Session.fetch_heirarchy(entities, *args, **kwargs)¶

Populate the parents as far up as we can go, and return all involved.

With (new-ish) arbitrarily-deep-links on Shotgun, this method could be made quite a bit more effiecient, since it should be able to request the entire heirarchy for any given type at once.

See parent_fields.

Importance Controls¶

These class attributes control which fields are considered “important”, which types are potentially linked to by various fields, and which types are considered the parent of other types.

Session.important_fields_for_all = ['updated_at']¶

Session.important_fields = {'Project': ['name'], 'Step': ['code', 'short_name', 'entity_type'], 'Task': ['step', 'content'], 'Shot': ['code'], 'Asset': ['code', 'sg_asset_type'], 'Sequence': ['code'], 'Version': ['code', 'sg_task'], 'HumanUser': ['firstname', 'lastname', 'email', 'login'], 'PublishEvent': ['code', 'sg_type', 'sg_version']}¶

Session.important_links = {'PublishEvent': {'project': ['Project'], 'sg_link': ['Task']}, 'Task': {'project': ['Project'], 'step': ['Step'], 'entity': ['Asset', 'Shot']}, 'Shot': {'project': ['Project'], 'sg_sequence': ['Sequence']}, 'Asset': {'project': ['Project']}, 'Sequence': {'project': ['Project']}}¶

Session.parent_fields = {'Task': 'entity', 'Shot': 'sg_sequence', 'Sequence': 'project', 'Project': None, 'Version': 'entity', 'Asset': 'project', 'PublishEvent': 'sg_link'}¶