Shotgun Globals Access

The globals module contains various accessors to Shotgun globals such as the schema, task statuses, etc. The globals are cached locally for fast access and updated in a background worker. Pass a data retriever object to the module in order for it to pull updates from Shotgun. When you shut down your app or tool, make sure you unregister the data retriever.

The sample code below shows how you can use the globals in your Toolkit App Code:

shotgun_globals = sgtk.platform.import_framework("tk-framework-shotgunutils", "shotgun_globals")
task_manager = sgtk.platform.import_framework("tk-framework-shotgunutils", "task_manager")


# typically, in your UI or app constructor, create a
# task manager
task_manager = task_manager.BackgroundTaskManager(self)
task_manager.start_processing()

# register it with the globals module so that it can
# use it to fetch data
shotgun_globals.register_bg_task_manager(task_manager)

# at runtime, access things
shotgun_globals.get_type_display_name("CustomEntity01")

# at shutdown time, unregister
shotgun_globals.unregister_bg_task_manager(task_manager)
task_manager.shut_down()

shotgun_globals.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

shotgun_globals.unregister_bg_task_manager(task_manager)

Unregister a previously registered data retriever with the singleton.

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

shotgun_globals.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

shotgun_globals.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

shotgun_globals.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

shotgun_globals.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

shotgun_globals.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"

shotgun_globals.get_entity_type_icon(entity_type)[source]

Retrieve the icon for the specified entity type if available.

Parameters:: entity_type – The entity type to retrieve the icon for
Returns:: A QIcon if an icon was found for the specified entity type, otherwise None.

shotgun_globals.get_entity_type_icon_url(entity_type)[source]

Retrieve the icon resource path for the specified entity type if available.

This is useful if you want to include an icon in a QLabel using an <img> html tag.

Parameters:: entity_type – The entity type to retrieve the icon for
Returns:: A string url with a qt resource path

shotgun_globals.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.

shotgun_globals.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.

shotgun_globals.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.

shotgun_globals.create_human_readable_date(dt)[source]

Return the date represented by the argument as a string, displaying recent dates as “Yesterday”, “Today”, or “Tomorrow”.

Parameters:: dt (datetime.date or datetime.datetime) – The date convert to a string
Returns:: A String representing date appropriate for display