python.shotgun_globals.cached_schema module

class CachedShotgunSchema

Bases: sphinx.ext.autodoc.importer._MockObject

Wraps around the shotgun schema and caches it for fast lookups.

Singleton-style setup, so all access method happen via class methods:

• get_type_display_name - Display name for entity type
• get_field_display_name - Display name for field
• get_empty_phrase - String to denote ‘no value’ for item
• get_status_display_name - Display name for status code

This caches the shotgun schema to disk once and doesn’t check for further updates. If the cache fails to find a value, the technical name rather than the display name is returned, so there is graceful fallback.

Signal schema_loaded:  Fires when the schema has been loaded Signal status_loaded:  Fires when the status list has been loaded

classmethod clear_cached_data(project_id=None)

Remove both the schema and status cache files from disk for the specified project_id. If no project_id is specified, then use the current context project.

Parameters:project_id – The id of the project entity to remove schema and status cache files for. If None, the current context’s project will be used.

classmethod field_is_editable(sg_entity_type, field_name, project_id=None)

Returns a boolean identifying the editability of the entity’s field.

Parameters:

• sg_entity_type (str) – the entity type
• field_name (str) – the field name to check editibility
• project_id – The project Entity id. If None, the current context’s project will be used, or the “site” cache location will be returned if the current context does not have an associated project.

The field_name may be in “bubble” notation. This method will account for it and return the editability setting for the evaluated entity type and field defined in the bubble noation. For example, if the field is defined as “sg_sequence.Sequence.code”, this method will return the editability of the code field on the Sequence entity.

Returns:True if the field is ediable, False otherwise.

classmethod field_is_visible(sg_entity_type, field_name, project_id=None)

Returns a boolean identifying the visibility of the entity’s field.

Parameters:

• sg_entity_type – the entity type
• field_name – the field name to check visibility
• project_id – The project Entity id. If None, the current context’s project will be used, or the “site” cache location will be returned if the current context does not have an associated project.

The field_name may be in “bubble” notation. This method will account for it and return the visibility setting for the evaluated entity type and field defined in the bubble noation. For example, if the field is defined as “sg_sequence.Sequence.code”, this method will return the visibility of the code field on the Sequence entity.

Returns:True if the field is visible, False otherwise.

classmethod get_data_type(sg_entity_type, field_name, project_id=None)

Return the data type for the given Shotgun field.

Parameters:

• sg_entity_type – Shotgun entity type
• field_name – Shotgun field name
• project_id – The id of the project entity to get a type from. If None, the current context’s project will be used.

Returns:

Data type string

classmethod get_empty_phrase(sg_entity_type, field_name, project_id=None)

Get an appropriate phrase to describe the fact that a given Shotgun field is empty. The phrase will differ depending on the data type of the field.

Parameters:

• sg_entity_type – Shotgun entity type
• field_name – Shotgun field name
• project_id – The id of the project entity to get a phrase from. If None, the current context’s project will be used.

Returns:

Empty phrase string

classmethod get_entity_fields(sg_entity_type, project_id=None)

Returns the fields for a Shotgun entity type.

Parameters:

• sg_entity_type – Shotgun entity type
• project_id – The id of the project entity to get fields from. If None, the current context’s project will be used.

Returns:

List of field names

classmethod get_field_display_name(sg_entity_type, field_name, project_id=None)

Returns the display name for a given Shotgun field. If the field cannot be found or the value is not yet cached, the system name for the field is returned.

If the data is not present locally, a cache reload will be triggered, meaning that subsequent cache requests may return valid data.

Parameters:

• sg_entity_type – Shotgun entity type
• field_name – Shotgun field name
• project_id – The id of the project entity to get a name from. If None, the current context’s project will be used.

Returns:

Field display name

classmethod get_ordered_status_list(display_names=False, project_id=None)

Returns a list of statuses in their order as defined by the Shotgun site preferences.

If the data is not present locally, a cache reload will be triggered, meaning that subsequent cache requests may return valid data.

Parameters:

• display_names – If True, returns status display names. If False, status codes are returned. Default is False.
• project_id – The id of the project entity to get statuses from. If None, the current context’s project will be used.

Returns:

list of string display names in order

classmethod get_status_color(status_code, project_id=None)

Returns the color for a given status code. If the status code cannot be found or haven’t been loaded, None is returned.

If the data is not present locally, a cache reload will be triggered, meaning that subsequent cache requests may return valid data.

Parameters:

• status_code – Status short code (e.g ‘ip’)
• project_id – The id of the project entity to get a color from. If None, the current context’s project will be used.

Returns:

string with r,g,b values, e.g. "123,255,10"

classmethod get_status_display_name(status_code, project_id=None)

Returns the display name for a given status code. If the status code cannot be found or haven’t been loaded, the status code is returned back.

If the data is not present locally, a cache reload will be triggered, meaning that subsequent cache requests may return valid data.

Parameters:

• status_code – Status short code (e.g ‘ip’)
• project_id – The id of the project entity to get a name from. If None, the current context’s project will be used.

Returns:

string with descriptive status name

classmethod get_type_display_name(sg_entity_type, project_id=None)

Returns the display name for a Shotgun entity type. If no display name is known for this object, the system name is returned, e.g. the same that’s being passed in via the sg_entity_type parameter.

If the data is not present locally, a cache reload will be triggered, meaning that subsequent cache requests may return valid data.

Parameters:

• sg_entity_type – Shotgun entity type
• project_id – The id of the project entity to get a name from. If None, the current context’s project will be used.

Returns:

Entity type display name

classmethod get_valid_types(sg_entity_type, field_name, project_id=None)

Return the valid entity types that the given Shotgun field can link to.

Parameters:

• sg_entity_type – Shotgun entity type
• field_name – Shotgun field name
• project_id – The id of the project entity to get types from. If None, the current context’s project will be used.

Returns:

List of entity types

classmethod get_valid_values(sg_entity_type, field_name, project_id=None)

Returns valid values for fields with a list of choices.

Parameters:

• sg_entity_type (str) – The entity type.
• field_name (str) – The name of the field on the entity
• project_id – The id of the project entity to get a name from. If None, the current context’s project will be used.

Returns:

A list of valid values defined by the schema

Raises:

ValueError if the field has no valid values.

classmethod register_bg_task_manager(task_manager)

Register a background task manager with the singleton. Once a background task manager has been registered, the schema singleton can refresh its cache.

Parameters:task_manager (BackgroundTaskManager) – Background task manager to use

classmethod run_on_schema_loaded(callback, project_id=None)

Run the given callback once the schema is loaded.

Parameters:

• callback – Method with no argument to run when the schema is loaded
• project_id – The id of the project entity to load the schema for. If None, the current context’s project will be used.

schema_loaded

Used by autodoc_mock_imports.

status_loaded

Used by autodoc_mock_imports.

classmethod unregister_bg_task_manager(task_manager)

Unregister a previously registered data retriever with the singleton.

Parameters:task_manager (BackgroundTaskManager) – Background task manager to use