python.shotgun_model.shotgun_hierarchy_item module

class ShotgunHierarchyItem(*args, **kwargs)

Bases: python.shotgun_model.shotgun_standard_item.ShotgunStandardItem

A subclass of ShotgunStandardItem with access to data provided via the nav_expand() python API calls.

Warning

Do NOT construct instances of this class and then manually them to an existing ShotgunHierarchyModel. Doing so will likely causes memory issues or issues centered around garbage collection as the model class takes a lot of care to know exactly which items exist, when they’re added/removed etc.

SG_PATH_FIELD = 'path'

entity_type()

Returns the entity type of the item.

There are two kinds of items that are associated with entity types.

The first is the actual “entity_type” item. These are typically parent items in the hierarchy like Shots or Assets which have children that correspond to actual entities.

The entity items themselves also have an entity type.

This method will return the entity type for either of these kinds of items. To find out the kind of the item, use the kind() method.

If the item has no associated entity type, None will be returned.

Return type:str or None

has_children()

Returns True if the item has children, False otherwise.

Return type:bool

is_entity_related()

Returns True if the item is entity related, False otherwise.

Being “entity related” means it represents an entity, an entity type, a list of entities, or a generic container for entities.

Some items returned from the SG hierarchy are merely placeholders that tell the user that there are no associated entities. For these items, this method will return False.

Returns:True if entity related, False otherwise. Return type:bool

kind()

Returns the “kind” of the item.

The current “kinds” are:

• “entity”: A concrete entity instance

• “entity_type”: A container for the type of entity (ex: “Asset”, “Shot”,

  etc)

• “list”: A container for other items

• “no_entity”: A container for items with no parent entity (ex: “Shots

  with no Sequence”)

• None: A placeholder that represents no items (ex: “No Shots”)

Return type:str or None

path()

Returns the path for this item in the hierarchy.

May return None if the item has no data or does not have a path.

Most items in the model will store a path which identifies their location in the hierarchy. This is the same value used by nav_expand() in the python-api to query a Shotgun hierarchy.

An example path:

'path': '/Project/65/Asset/sg_asset_type/Character',

target_entities()

Returns the target_entities dict as stored on the item.

May return None if the item has no data or does not have target_entities.

This dictionary stores information that can be used to query the entities targeted when the containing hierarchy model was created. It includes a key called additional_filter_presets with a value that can be provided to the shotgun python-api’s find() call to tell the server exactly which entities exist under this item’s branch in the hierarchy. The value is a list of dictionaries with server-side filter presets for locating the target entities.

The dictionary also stores a type key whose value is the type of entity being targeted.

A common usage of this is to respond to selection-changed signals on a view showing a Shotgun hierarchy. For example, the data returned can be fed to a separate Shotgun model view.

Example usage:

target_entities = selected_item.target_entities()

sg_model.load_data(
    target_entities["type"],
    additional_filter_presets=target_entities.get("additional_filter_presets"),
)