Overview

Getting Started

All you must do to start using sgsession is to construct a Session with an existing Shotgun instance:

>>> from shotgun_api3 import Shotgun
>>> from sgsession import Session
>>> session = Session(Shotgun(*shotgun_args))

From then on you can use the session as you would have used the Shotgun instance itself.

The Entity

The primary representation of Shotgun entities is the Entity class, which extends the familiar dictionary with more Shotgun specific methods and a link back to the session for fetching more fields, parents, etc..

Instance Sharing

The same Entity instance will always be returned for the same conceptual instance. E.g.:

>>> a = session.find_one('Task', [('code', 'is', 'AA_001')])
>>> b = session.find_one('Task', [('code', 'is', 'AA_001')])
>>> a is b
True

Caching, Merging, and Backrefs

Entities will be cached for the lifetime of their Session, and any new information about them will be merged in as it is encountered.

For example, fields fetched in subsequent queries to the server will be availible on earlier found entities:

>>> a = session.find_one('Task', [('code', 'is', 'AA_001')])
>>> 'sg_status_list' in a
False
>>> b = session.find_one('Task', [('code', 'is', 'AA_001')], ['sg_status_list'])
>>> a['sg_status_list']
'fin'

Deep-linked fields will also be merged into the main scope of the linked entities for easy referral:

>>> x = session.find_one('Task', [], ['entity.Shot.code'])
>>> x['entity']['code']
'AA_001'

Links to other entities will automatically populate backrefs on the remote side of the link, allowing for entities to easily find there they have been linked from:

>>> task = session.find_one('Task', [], ['entity'])
>>> shot = task['entity']
>>> task in shot.backrefs[('Task', 'entity')]
True

Important Fields

Several fields will always be queried for whenever you operate on entities. These include Shot.code, Task.step, and project on many types. When availible, deep-linked fields will also be fetched, including Task.entity.Shot.code, so even single simple queries will return lots of related data:

>>> x = session.find_one('Task', [])
>>> x.pprint()
Task:456 at 0x101577a20; {
    entity = Shot:234 at 0x101541a80; {
            code = 'AA_001'
            name = 'AA_001'
            project = Project:123 at 0x101561f30; {
                    name = 'Demo Project'
            }
    }
    project = Project:123 at 0x101561f30; ...
    sg_status_list = 'fin'
    step = Step:345 at 0x10155b5e0; {
            code = 'Matchmove'
            entity_type = 'Shot'
            name = 'Matchmove'
            short_name = 'Matchmove'
    }
}

Brace Expansion

During a find or find_one, return fields can be specified with brace expansions to allow for a more compact representation of complex links:

>>> session.find('Task', [], ['entity.{Asset,Shot}.{name,code}'])

Efficient Heirarchies

Ever have a list of tasks that you need to know the full heirarchy for all the way up to the project? With any number of tasks, you can get all of the important fields for the full heirarchy in no more than 3 requests:

>>> tasks = session.find('Task', some_filters)
>>> all_entities = session.fetch_heirarchy(tasks)

all_entities is a list of every entity above those tasks, and every entity has been linked and backreffed to each other.