Development API

This page is generally for the developers of sgcache itself, as it does not yet have any Python API’s designed for public consumption.

Cache Data Models

class sgcache.entity.EntityType(cache, name, schema)

Largely a mapping of fields, but also responsible for entity-level caching mechanisms, including columns (on table.c):

• _active: Is the entity not “retired”?
• _cache_created_at: When was this entity first cached?
• _cache_updated_at: When was this entity last updated in the cache?
• _last_log_event_id: What was the last LogEventEntry id to affect this entity?

type_name = None

The name of this entity type, e.g.: Task.

table_name = None

The name of the SQLAlchemy table, usually the lower-cased type_name; see Schema Rules.

table = None

The SQLAlchemy table itself.

schema = None

The EntitySchema for this entity type.

Schema

class sgcache.schema.Schema

A mapping of entity type names to EntitySchema.

classmethod from_yaml(cls, file)

Load the full schema from the given YAML file. This schema is assumed to be:

• a mapping of entity names to entity schemas, which are:
• a mapping of field names to field schemas, which are:
• either a string representing the data type, or a mapping including a data_type, and any other info as required by the field.

class sgcache.schema.EntitySchema(name)

A mapping of field names to FieldSchema.

class sgcache.schema.FieldSchema(name)

The schema of a single field.

data_type = None

The Shotgun data type, e.g. entity or checkbox.

entity_types = ()

The allowable entity types for entity and multi_entity fields.

Field Paths

class sgcache.path.FieldPath(input_, root_type=None)

A path in an API3 filter or return field; a sequence of FieldPathSegment objects.

Parameters:

• input – A list of FieldPathSegment, or a string.
• root_type – The entity type this field starts at; required if the input is a string.

>>> path = FieldPath('entity.Shot.sg_sequence.Sequence.code', root_type='Task')

>>> str(path)
'entity.Shot.sg_sequence.Sequence.code'

>>> str(path[:1])
'entity'

>>> str(path[1:])
'sg_sequence.Sequence.code'

format(head=False, tail=True, _cached=True)

Stringify this path.

Parameters:

• head (bool) – Include the root entity type?
• tail (bool) – Include the final field name?

>>> path = FieldPath('entity.Shot.code', root_type='Task')

>>> path.format()
'entity.Shot.code'

>>> path.format(head=True)
'Task.entity.Shot.code'

>>> path.format(tail=False)
'entity.Shot'

class sgcache.path.FieldPathSegment

One segment of a FieldPath.

type

The entity type of this segment.

field

The field name of this segment.

API3 Operations

class sgcache.api3.create.Api3CreateOperation(request, create_with_id=False, source_event=None)

Operation to process an API3-style “create” request, which look like:

{
    "fields": [
        {
            "field_name": "key", 
            "value": "value"
        }
    ], 
    "return_fields": [
        "id"
    ], 
    "type": "Test"
}

Parameters:

• request (dict) – The request with fields, return_fields, and type.
• create_with_id (bool) – If an ID is provided, and the entity does not exist, are we permitted to create that specific entity?

Raises:

ValueError – if an ID is given but create_with_id is not true.

entity_exists = None

Did the entity exist? Set to True once run if an ID was provided and that entity did exist.

before_query = None

List of functions to call with the transaction before the primary query is executed; generally appended to by the multi_entity Base.

after_query = None

List of functions to call with the transaction after the primary query is executed; generally appended to by the multi_entity Base.

source_event = None

The Event that triggered this query.

run(cache, con=None, extra=None)

Run the create operation.

Parameters:

• cache – The Cache.
• con – A SQLA connection; we will create one if not passed.
• extra (dict) – Extra data to insert/update in the entity; used for entity-level caching mechanisms.

class sgcache.api3.read.Api3ReadOperation(request)

Operation to process an API3-style “read” request.

Parameters:request (dict) –

The request itself with:

• type
• filters
• return_fields
• paging.entities_per_page
• paging.current_page
• sorts
• return_only

run(cache)

Run the operation.

Parameters:cache – The Cache. Returns:API3 compatible results.