Publish Items

Publish items are the individual UI elements displayed to the user for publishing. These items are created during the collection phase of the publisher. Items can be displayed in a flat list for example when a collection of unrelated files are dragged and dropped into the publisher. Alternatively, items can be displayed in a hierarchy when it is important to show some relationship between them.

class tk_multi_publish2.processing.Item(item_type, display_type, name, parent)[source]

An object representing an scene or file item that should be processed. Items are constructed and returned by the collector hook.

Items should always be created via the Item.create_item() method of an existing item (typically the parent_item supplied to one of the collector’s methods). The constructor should never be used within a collector.

Items are organized as a tree with access to parent and children.

Initialize an item. Should never be called.

Parameters:
  • item_type (str) – Item type, typically following a hierarchical dot notation. For example, ‘file’, ‘file.image’, ‘file.quicktime’ or ‘maya_scene’
  • display_type (str) – Equivalent to the type, but for display purposes.
  • name (str) – The name to represent the item in a UI. This can be a node name in a DCC or a file name.
  • parent (Item) – Parent item.
create_item(item_type, display_type, name)[source]

Factory method for generating new items.

The item_type is a string that represents the type of the item. This can be any string, but is typically defined by studio convention. This value is used by the publish plugins to identify which items to act upon.

The basic Shotgun integrations, for example, use a hierarchical dot notation such as: file.image, file.image.sequence, file.movie, and maya.session.

The current convention used within the shipped integrations is to classify files that exist on disk as file.{type} (file.image or file.video for example). This classification is determined from the mimetype in the base collector. In addition, any sequence-based items are classified as file.{type}.sequence (file.image.sequence for example).

For items defined within a DCC-session that must be save or exported prior to publish, the shipped integrations use the form {dcc}.{type} for the primary session item and {dcc}.{type}.{subtype} for items within the session.

In Maya, for example, the primary session item would be of type maya.session and an item representing all geomtery in the session would be maya.session.geometry.

These are merely conventions used in the shipped integrations and can be altered to meet studio requirements. It is recommended to look at each of the publish plugins shipped with the publisher and housed in each of the toolkit engines to see what item types are supported by default.

The display_type argument corresponds to the item type, but is used for display purposes only.

Examples include: Image File, Movie File, and Maya Scene.

The name argument is the display name for the item instance. This can be the name of a file or a node name in Nuke or Houdini, or a combination of both. This value is displayed to the user and should make it easy for the user to identify what the item represents in terms of the current session or a file on disk.

_images/create_item_args.png

Parameters:
  • item_type (str) – Item type, typically following a hierarchical dot notation.
  • display_type (str) – Equivalent to the type, but for display purposes.
  • name (str) – The name to represent the item in a UI. This can be a node name in a DCC or a file name.
parent

The parent item (read only)

children

List of associated child items (read only)

properties

A free form dictionary-like object where arbitrary data can be stored on the item.

The properties dictionary itself is read only (calling item.properties = my_properties is invalid) but arbitrary key value pairs can be set within the dictionary itself.

This property provides a way to store data that is global across all attached publish plugins. It is also useful for accessing data stored on parent items that may be useful to plugin attached to child items.

For properties that are local to the current plugin, see local_properties.

This property can also be used to store data on an items that may then be accessed by plugins attached to the item’s children.

local_properties

A dictionary-like object that houses item properties local to the current publish plugin instance.

This property behaves like the local storage in python’s threading module, except here, the data is local to the current publish plugin.

You can get and set values for this property using standard dictionary notation or via dot notation.

Attempts to access this property outside of a publish plugin will raise an AttributeError.

It is important to consider when to set a value via Item.properties`() and when to use Item.local_properties(). Setting the values on item.properties is a way to globally share information between publish plugins. Values set via item.local_properties will only be applied during the execution of the current plugin (similar to python’s threading.local storage).

A common scenario to consider is when you have multiple publish plugins acting on the same item. You may, for example, want the publish_name and publish_version to be shared by each plugin, while setting the remaining properties on each plugin instance since they will be specific to that plugin’s output.

Example:

# set shared properties on the item (potentially in the collector or
# the first publish plugin). these values will be available to all
# publish plugins attached to the item.
item.properties.publish_name = "Gorilla"
item.properties.publish_version = "0003"

# set specific properties in subclasses of the base file publish (this
# class). first publish plugin...
item.local_properties.publish_template = "asset_fbx_template"
item.local_properties.publish_type = "FBX File"

# in another publish plugin...
item.local_properties.publish_template = "asset_abc_template"
item.local_properties.publish_type = "Alembic Cache"
get_property(name, default_value=None)[source]

This is a convenience method that will retrieve a property set on the item.

If the property was set via Item.local_properties(), then that will be returned. Otherwise, the value set via Item.properties() will be returned. If the property is not set on the item, then the supplied default_value will be returned (default is None).

Parameters:
  • name – The property to retrieve.
  • default_value – The value to return if the property is not set on the item.
Returns:

The value of the supplied property.
name

The name of the item as a string.

type

The item type as defined when Publish item was created.

See Item.create_item() for more info.

display_type

A human readable type string, suitable for UI and display purposes.

thumbnail_enabled

Flag to indicate that thumbnails can be interacted with.

  • If True, thumbnails will be visible and editable in the publish UI (via screen capture).
  • If False and a thumbnail has been set via the thumbnail() property, the thumbnail will be visible but screen capture will be disabled.
  • If False and no thumbnail has been specified, no thumbnail will appear in the UI.
thumbnail_explicit

Flag to indicate that thumbnail has been explicitly set. When this flag is on, the summary thumbnail should be ignored For this this specific item.

context

The context associated with this item.

If no context has been defined, the parent context will be returned or if that hasn’t been defined, None will be returned.

description

The description for this item that will be displayed to the user and associated with the eventual Publish in Shotgun.

If no description has been set for this item, the parent item’s description will be returned. If no description has been set for the parent, None will be returned.

thumbnail

The associated thumbnail, as a QtGui.QPixmap.

The thumbnail is an image to represent the item visually such as a thumbnail of an image or a screenshot of a scene.

If no thumbnail has been defined for this node, the parent thumbnail is returned, or None if no thumbnail exists.

expanded

Flag to indicate that this item’s children should be expanded.

checked

Flag to indicate that this item should be checked by default.

Please note that the final state of the node is also affected by the child tasks. Below are some examples of how this interaction plays out in practice:

  • If all child tasks/items return checked: False in their accept method, the parent item will be unchecked, regardless of the state of this property.
  • If one or more child tasks return checked: True and the item checked state is False, the item and all its sub-items will be unchecked.
enabled

Flag to indicate that this item and its children should be enabled.

set_thumbnail_from_path(path)[source]

Helper method. Parses the contents of the given file path and tries to convert it into a QPixmap which is then used to set the thumbnail for the item.

Parameters:path (str) – Path to a file on disk
get_thumbnail_as_path()[source]

Helper method. Writes the associated thumbnail to a temp file on disk and returns the path. This path is automatically deleted when the object goes out of scope.

Returns:Path to a file on disk or None if no thumbnail set
icon

The associated icon, as a QPixmap. The icon is a small square image used to represent the item visually

_images/item_icon.png

If no icon has been defined for this node, the parent icon is returned, or a default one if not defined

set_icon_from_path(path)[source]

Helper method. Parses the contents of the given file path and tries to convert it into a QPixmap which is then used to set the icon for the item.

Parameters:path (str) – Path to a file on disk
context_change_allowed

True if item allows context change, False otherwise. Default is True