python.external_config.external_command module

class ExternalCommand(callback_name, display_name, tooltip, group, is_group_default, plugin_id, interpreter, engine_name, descriptor_uri, pipeline_config_id, entity_type, entity_id, pipeline_config_name, sg_deny_permissions, sg_supports_multiple_selection, icon)

Bases: object

Represents an external Toolkit command (e.g. menu option).

These objects are emitted by ExternalConfiguration and are independent, decoupled, light weight objects that can be serialized and brought back easily.

A command is executed via its execute() method, which will launch it in the given engine.

classmethod create(external_configuration, data, entity_id)

Creates a new ExternalCommand instance based on the data in data. This data is generated by external_command_utils.serialize_command().

Parameters:

• external_configuration – associated ExternalConfiguration instance.
• data (dict) – Serialized data to be turned into an instance
• entity_id (int) – The data is cached in a general form, suitable for all entities. This means that the entity_id cached as part of the data parameter reflects the entity for which the caching process was executed and not necessarily the one we are after. This parameter indicates the actual entity id for which we want the commands to be assoiated.

Returns:

ExternalCommand instance.

classmethod deserialize(data)

Creates a ExternalCommand instance given some serialized data.

Parameters:data (str) – Data created by serialize() Returns:External Command instance. Return type:ExternalCommand Raises:RuntimeError if data is not valid

display_name

Display name, suitable for display in a menu.

engine_name

The name of the engine associated with the command

excluded_permission_groups_hint

Legacy option used by some older Shotgun toolkit apps. Apps may hint a list of permission groups for which the app command should not be displayed.

Returns a list of Shotgun permission groups (as strings) where this command is not appropriate.

execute(pre_cache=False)

Executes the external command in a separate process.

Note

The process will be launched in an synchronous way. It is recommended that this command is executed in a worker thread:

# execute external command in a thread to not block
# main thread execution
worker = threading.Thread(target=action.execute)
# if the python environment shuts down, no need
# to wait for this thread
worker.daemon = True
# launch external process
worker.start()

Parameters:pre_cache (bool) – If set to True, starting up the command will also include a full caching of all necessary dependencies for all contexts and engines. If set to False, caching will only be carried as needed in order to run the given command. This is an advanced setting that can be useful to set to true when launching older engines which don’t launch via a bootstrap process. In that case, the engine simply assumes that all necessary app dependencies already exists in the bundle cache search path and without a pre-cache, apps may not initialize correctly. Raises:RuntimeError on execution failure. Returns:Output from execution session.

execute_on_multiple_entities(pre_cache=False, entity_ids=None)

Executes the external command in a separate process. This method provides support for executing commands that support being run on multiple entities as part of a single execution.

Parameters:

• pre_cache (bool) – If set to True, starting up the command will also include a full caching of all necessary dependencies for all contexts and engines. If set to False, caching will only be carried as needed in order to run the given command. This is an advanced setting that can be useful to set to true when launching older engines which don’t launch via a bootstrap process. In that case, the engine simply assumes that all necessary app dependencies already exists in the bundle cache search path and without a pre-cache, apps may not initialize correctly.
• entity_ids (list) – A list of entity ids to use when executing the command. This is only required when running legacy commands that support being run on multiple entities at the same time. If not given, a list will be built on the fly containing only the entity id associated with this command.

Raises:

RuntimeError on execution failure.

Returns:

Output from execution session.

group

Group command belongs to or None if not defined.

This is used in conjunction with the group() property and is a hint to engines how commands should be grouped together.

Engines which implement support for grouping will group commands which share the same group() name into a group of associated items (typically as a submenu). The group_default() boolean property is used to indicate which item in the group should be considered the default one to represent the group as a whole.

icon

The path to a square png icon file representing this item

classmethod is_compatible(data)

Determines if the given data is compatible.

Parameters:data (dict) – Serialized data Returns:True if the given data can be loaded, False if not.

is_group_default

True if this command is a default action for a group.

This is used in conjunction with the group() property and is a hint to engines how commands should be grouped together.

Engines which implement support for grouping will group commands which share the same group() name into a group of associated items (typically as a submenu). The group_default() boolean property is used to indicate which item in the group should be considered the default one to represent the group as a whole.

pipeline_configuration_name

The name of the Shotgun pipeline configuration this command is associated with, or None if no association exists.

serialize()

Serializes the current object into a string.

For use with deserialize().

Returns:String representing the current instance. Return type:str

support_shotgun_multiple_selection

Legacy flag indicated by some older Toolkit apps, indicating that the app can accept a list of entity ids to operate on rather than a single item.

system_name

The system name for the command

tooltip

Associated help text tooltip.