Packages¶

Module containing the Package abstract class and some classes derived from it: EditPackage, GroupPackage and RootPackage

A package defines the nodes and parameters that will create or edit the locations managed by a PackageSuperToolAPI-based SuperTool. Each package will be associated with one location.

By default, a package will be a creation package, which creates new locations using its internal nodes. A package class derived from EditPackage is an edit package, which can edit existing locations from the incoming scene graph.

Package classes derived from GroupPackage can have child packages: packages that create and manage locations that are children of the parent package’s location.

All packages have a parent package, except the root package, which is implemented by RootPackage. The root package represents the root location of the PackageSuperToolAPI-based node.

A package usually creates and manages a package node, usually of the type Group or GroupStack, that contains all of the nodes the package requires. This node needs to be set with some standard parameters and should create some standard attributes to be consumed internally by the SuperTool framework. These can be automatically created with some helper functions provided by this class, or its abstract children (EditPackage and GroupPackage).

Optionally, a GroupStack node can be added to the Post-Merge area of the SuperTool by this class. These nodes will have access to the incoming scene graph.

Packages¶

class PackageSuperToolAPI.Packages.Package(packageNode)¶

Bases: PackageSuperToolAPI.Packages.Upgradable

Class implementing the base class for all PackageSuperToolAPI packages.

@undocumented: __hash__, __eq__, __ne__

__init__(packageNode)¶

Initializes an instance of the class with the given package node.

Parameters:	packageNode (`NodegraphAPI.Node`) – The package node for which to initialize the new package instance. This is usually a Group or a GroupStack node, but can also be a single node.

adoptPackage(childPackage, peerNames=None)¶

Implements the adoption of a given package as child of this package. To be implemented by child classes that support child packages.

The default implementation does nothing.

Parameters:	childPackage (`Package`) – The package to adopt. peerNames (`list` of `str` or `None`) – An optional list of the names of the existing locations which will be peers of the newly adopted package. If provided, this will be used to make sure that the location for the adopted package is given a unique name.

canAdoptPackage(package)¶

Return type:	`bool`
Parameters:	package (`Package`) – The package to test whether it can be adopted by this package.
Returns:	`True` if the given package can be adopted by this package, otherwise `False`. The default implementation returns `False`.

canBeAdoptedByPackage(package)¶

Return type:	`bool`
Parameters:	package (`Package`) – The package to test whether it can adopt this package.
Returns:	`True` if the given package can adopt this package, otherwise `False`.

classmethod canBeCreatedByPackageClass(packageClass)¶

Determines if the given package class can create a child of this package type.

Return type:	`bool`
Parameters:	packageClass (`type`) – The package class to test whether it can create a child of the type of this package class.
Returns:	`True` if the packages of the given class can create children of the type of this package class, otherwise `False`. The default implementation returns `True`.

canBeDeleted()¶

Return type:	`bool`
Returns:	`True` if the package can be deleted, otherwise `False`.
Note:	A package might not be able to be deleted if the SuperTool’s main node is locked.

canBeDuplicated(parentPackage=None)¶

Parameters:	parentPackage (`Package` or `None`) – The destination package where the new duplicated package would be created. If none is provided, the parent package of the original package would be used.
Return type:	`bool`
Returns:	`True` if the package can be duplicated, otherwise `False`.

canBeRenamed()¶

Return type:	`bool`
Returns:	`True` if the package can be renamed, otherwise `False`.
Note:	A package might not be able to be renamed if the SuperTool’s main node is locked.

classmethod canCreateChildPackage(packageClassOrName, mainNode, locationPath)¶

Return type:	`bool`
Parameters:	packageClassOrName (`type` or `str`) – A package class or package class type. mainNode (`NodegraphAPI.Node`) – The main node of a SuperTool. locationPath (`str`) – The location path for which to test whether a child package can be created by this package.
Returns:	`True` if this package class can create a child package of the given type for the location of the given path, under the given main node, otherwise `False`.

classmethod canCreatePackageClass(packageClass)¶

Determines if this package can create a child of the given package class.

Return type:	`bool`
Parameters:	packageClass (`type`) – The package class to test whether it can be created by this package.
Returns:	`True` if the packages of the given class can be created by this package, otherwise `False`. The default implementation returns `False`.

canDuplicate()¶: @deprecated: This function is deprecated. Please use canBeDuplicated() instead.

canReorderChildPackage(oldIndex, newIndex)¶

Returns a flag indicating if the package at the given index can be reordered to the given new index. To be implemented by child classes that support child packages. The default implementation returns False.

Return type:	`bool`
Parameters:	oldIndex (`int`) – The index position of the child package to reorder. newIndex (`int`) – The index position to which to move the specified child package.
Returns:	`True` if the reorder operation is acceptable, otherwise `False`.

classmethod create(enclosingNode, locationPath)¶

A factory method which should be implemented by derived classes, which should return an instance of the derived class. The responsibilities of this function are to:

Create the package node and its internal node graph network. This should be created using one of the helper functions provided to create package nodes with all the necessary parameters needed internally by the framework (e.g. Package.createPackageGroupNode). The attributes that need to be generated by this node (or by its internal network) to be internally consumed by the framework can be done by adding the nodes returned by Package.createStandardPackageNodes to the internal network of this node. These standard nodes are not more than AttributeSet nodes that set these attributes. The function NodeUtils.WireInlineNodes can also be useful to connect several nodes in one serial sequence.
Add the necessary parameter-driven references to any internal nodes which will need to be accessible via NodeUtils.GetRefNode in other parts of the code.
Instantiate the package object to be returned.
Optionally create a GroupStack node with some internal nodes in the Post-Merge area. This can be created using the helper function Package.createPostMergeStackNode once the Package instance has been created.

Return type:	`Package`
Parameters:	enclosingNode (`NodegraphAPI.Node`) – The parent node within which the new package’s node should be created. locationPath (`str`) – The path to the location to be created/managed by the package.
Returns:	The newly-created package instance.
Raises:	NotImplementedError – If this method has not been implemented by a derived class.

createChildPackage(packageClassOrName, name=None, peerNames=None)¶

Creates and returns a package of the class identified by packageClassOrName as a child of this package. To be implemented by subclasses that support child packages. The default implementation returns None.

Return type:	`Package` or `None`
Parameters:	packageClassOrName (`type` or `str`) – Either the type or the name of the type of child package to create. name (`str` or `None`) – The new name of the package to create. If not specified, a default name will be used. If the name (specified or default) conflicts with an existing package name, it will be modified with a suffixed incrementing number until a unique name is found. peerNames (`iterable` or `None`) – An optional list of names of siblings which is used when performing collision checks for the name of the newly created child package.
Returns:	The newly created child package or `None` if a child package could not be created.

classmethod createPackage(packageNode)¶

Instantiates a package of this class with the given package node.

Return type:	`Package`
Parameters:	packageNode (`NodegraphAPI.Node`) – The package node.
Returns:	An instance of this package class.

classmethod createPackageGroupNode(enclosingNode, locationPath)¶

Helper function to be used in Package.create that creates a Group node to be used as the package node. Tags the node with the necessary parameters used internally by the SuperTool.

Return type:	`GroupNode`
Parameters:	enclosingNode (`NodegraphAPI.Node`) – The enclosing node within which the new Group node should be created. To create the node at root level, the result of `NodegraphAPI.GetRootNode()` should be passed. locationPath (`str`) – The location path created/managed by the package for which the new Group node is being created.
Returns:	The newly-created Group node.

createPostMergeStackNode()¶

Helper function to be used in Package.create that creates a GroupStack node to be used as the package post-merge stack node. Tags the node with the necessary parameters used internally by the SuperTool.

Return type:	`NodegraphAPI.GroupStack`
Returns:	The newly-created `GroupStack` node.

classmethod createStandardPackageNodes(packageNode)¶

Helper function to be used in the create method of a package to create any standard nodes for this package type. These nodes will be created within the given package node, but need to be connected together by the caller.

Return type:	`list` of `NodegraphAPI.Node`
Parameters:	packageNode (`NodegraphAPI.Node`) – The package node for which the standard package nodes should be created (usually a `GroupNode`).
Returns:	The standard nodes to be added to the package node.

delete()¶

Deletes the nodes bound to this package, and rewires any connected nodes.

Adds a "sceneGraph_locationDeleted" event to Katana’s event queue in order to notify others of the deletion.

duplicate(peerNames=None, parentPackage=None)¶

Duplicates a package by creating a copy of all the relevant nodes.

Return type:	`Package`
Parameters:	peerNames (`list` of `str` or `None`) – An optional list of names of siblings which is used when performing collision checks for the name of the newly created child package. parentPackage (`Package` or `None`) – The destination package where the new duplicated package will be created. If none is provided, the parent package of the original package will be used.
Returns:	The new, duplicated package.
Raises:	RuntimeError – If this package cannot be duplicated.

classmethod getAdoptableLocationTypes()¶

Return type:	`set` of `str`
Returns:	A set of names of types of locations that can be adopted by this package class.

getChildPackage(name, includeDummies=False)¶

Return type:	`Package` or `None`
Parameters:	name (`str`) – The name of the package. includeDummies (`bool`) – A flag indicating whether a package of the given name should be returned if it is a dummy group package.
Returns:	The child package of the given name, or `None` if no such package was found.
Raises:	NotImplementedError – If the package does not support child packages.

getChildPackages()¶

Return type:	`list` of `Package`
Returns:	The child packages of this package. The default implementation returns an empty list.

getCreateNode()¶

Return type:	`NodegraphAPI.Node`
Returns:	The node responsible for creating this package’s location. This is usually a node obtained by calling `NodeUtils.GetRefNode("create")`. In order for this to work, the `Package.create` function should create a reference to this node using `NodeUtils.AddNodeRef()`.

classmethod getEditPackageClass()¶

Return type:	`type`
Returns:	The registered edit package class for this class, or `EditPackage` if no edit class has been set for this class.

getExtraNodeDependencies()¶

Return type:	`list` of `NodegraphAPI.Node`
Returns:	A list of the nodes which are dependent on this package.
Note:	This function is used to determine which nodes should be duplicated when a package is duplicated. Package classes which create nodes which are not inside the package node should return these nodes in their implementation of this function.

getLocationPath()¶

Return type:	`str`
Returns:	The path of the location created/edited by this package.
Raises:	ValueError – If a location path could not be determined for this package.

getMainNode()¶

Return type:	`NodegraphAPI.Node`
Returns:	The main node of the SuperTool in which this package exists.

classmethod getMainNodeFromNode(node)¶

Return type:	`NodegraphAPI.Node` or `None`
Parameters:	node (`NodegraphAPI.Node`) – The node within a SuperTool for which to return the main SuperTool node.
Returns:	The main node corresponding to the SuperTool to which the given node belongs, or `None` if no such main node could be found.

getName()¶

Return type:	`str`
Returns:	The name of this package, which matches the name of its location.

getOrCreateNodeByType(nodeType, forceCreate=True)¶

Return type:	`NodegraphAPI.Node` or `None`
Parameters:	nodeType (`str`) – The name of the type of node to get or create for this package. Note that a created node may be of a different type than the `nodeType` passed in. See `isNodeOfType`. forceCreate (`bool`) – A flag indicating whether the node should be created if it doesn’t exist.
Returns:	The node of the given type for this package, optionally creating it if it doesn’t already exist. Returns `None` if the node type was not recognized, or if the node does not exist and `forceCreate` was not set to `True`.

getOverrideNodeAndParameter(attrName)¶

Returns the node and the parameter that drives the value of the attribute of the given name at this package’s location.

This function closes the loop between attributes and parameters. Columns in the SceneGraphView widget created in a PackageSuperTool’s editor are associated with attribute names. This function returns the node and parameter for editing these attributes.

Return type:	`(NodegraphAPI.Node, NodegraphAPI.Parameter)`
Parameters:	attrName (`str`) – The name of the attribute for which to return the override node and parameter.
Returns:	The node and its parameter responsible for setting/editing the value of the given attribute.

classmethod getPackageClassFromNode(node)¶

Return type:	`Package` or `None`
Parameters:	node (`NodegraphAPI.Node`) – The package node for which to return the package class.
Returns:	The package class of the given node, or `None` if no package class was found for the given node.

classmethod getPackageFromNode(node)¶

Return type:	`Package`
Parameters:	node (`NodegraphAPI.Node`) – The node for which an enclosing package node should be returned.
Returns:	The first enclosing package node for the given node, or `None` if no enclosing package node was found.

getPackageNode()¶

Return type:	`NodegraphAPI.Node`
Returns:	The package node. This is usually a Group or a GroupStack node containing other nodes.

getParentPackage()¶

Return type:	`Package` or `None`
Returns:	The parent package of this package or `None` if a parent package could not be found.

getPostMergePackageStack(create=False)¶

Return type:	`NodegraphAPI.GroupStack` or `None`
Parameters:	create (`bool`) – A flag indicating whether the post-merge package stack node should be created if it doesn’t exist.
Returns:	The post-merge package stack node for this package, or `None` if no such node could be found, and `create` is not set to `True`.

initializeExtraNodeDependencies()¶: Called after copying/importing a hierarchy of packages. Re-wires and initializes the package’s auxiliary nodes.

isNodeOfType(node, nodeType)¶

Return type:	`bool`
Parameters:	node (`NodegraphAPI.Node` or `None`) – The node to check. nodeType (`str`) – The node type to check the given node against.
Returns:	`True` if the given node is of the given node type, otherwise `False`.
Note:	This function can be overridden in derived classes to support the case whereby `getOrCreateNodeByType` doesn’t return a node of the type given to it. The `isNodeOfType` function can be called to check if a given node corresponds to the node type name given to `getOrCreateNodeByType`.

reorderChildPackage(oldIndex, newIndex)¶

Reorders the child package at the given index to a new position. To be implemented by child classes that support child packages. The default implementation does nothing.

Parameters:	oldIndex (`int`) – The index position of the child package to reorder. newIndex (`int`) – The index position to which to move the specified child package.

classmethod setEditPackageClass(editPackageClass)¶

Sets the edit package class for this package class. The edit package class is the class of packages that is able to manage adopted locations created by this package class.

Parameters:	editPackageClass (`type`) – The edit package class, derived from `EditPackage`.

setName(name, queueEvent=False, selectLocation=False, makeUnique=True, replaceSelection=True, **kwargs)¶

Sets the name of the package.

Return type:	`str`
Parameters:	name (`str`) – The new name of the package. queueEvent (`bool`) – Whether or not to add a `"sceneGraph_locationRenamed"` event to Katana’s event queue in order to notify others of the rename. selectLocation (`bool`) – If `queueEvent` is `True`, whether or not the location rename event should automatically select the location. makeUnique (`bool`) – Flag that controls whether to make the resulting package name unique by taking names of peer locations into account (`True`), or to use the given name as-is (`False`). replaceSelection (`bool`) – If both `queueEvent` and `selectLocation` are set to `True`, whether to replace current selection, or to append to current selection.
Returns:	The name of the package after the rename. This may not be the same as the given name, if a package of the given name already exists.

supportsLocking()¶

Return type:	`bool`
Returns:	`True` if this package supports locking in the Viewer tab, otherwise `False`. The default implementation returns `False`.

classmethod walkUpPackageHierarchy(leafPackage, includeLeaf=True)¶

Return type:	`generator`
Parameters:	leafPackage (`Package`) – The `Package` from which to start walking up the hierarchy. includeLeaf (`bool`) – A flag indicating whether to include the given `leafPackage` as the first result when iterating.
Returns:	A generator that yields `Package` instances up through the hierarchy, up to and including the `RootPackage`.

class PackageSuperToolAPI.Packages.EditPackage(packageNode)¶

Bases: PackageSuperToolAPI.Packages.Package

A base class for implementing an edit package. An edit package can “adopt” locations which exist in the incoming scene graph for editing.

canBeAdoptedByPackage(package)¶

Return type:	`bool`
Parameters:	package (`Package`) – The package to test whether it can adopt this package.
Returns:	`True` if the given package can adopt this package, otherwise `False`. The default implementation returns `False`.

classmethod canBeCreatedByPackageClass(packageClass)¶

Determines if the given package class can create a child of this package type.

Return type:	`bool`
Parameters:	packageClass (`type`) – The package class to test whether it can create a child of the type of this package class.
Returns:	`True` if the packages of the given class can create children of the type of this package class, otherwise `False`. The default implementation returns `True`.

canBeRenamed()¶

Return type:	`bool`
Returns:	`True` if the package can be renamed, otherwise `False`. The default implementation returns `False`.
Note:	A package might not be able to be if the SuperTool’s main node is locked.

classmethod canCreatePackageClass(packageClass)¶

Determines if this package can create a child of the given package class.

Return type:	`bool`
Parameters:	packageClass (`type`) – The package class to test whether it can be created by this package.
Returns:	`True` if the packages of the given class can be created by this package, otherwise `False`. The default implementation returns `False`.

classmethod create(enclosingNode, locationPath)¶

Implementation of Package.create(). This should be called by derived classes in their own create() functions.

Return type:	`Package`
Parameters:	enclosingNode (`NodegraphAPI.Node`) – The parent node within which the new package’s node should be created. locationPath (`str`) – The path to the location to be created/managed by the package.
Returns:	The newly-created package instance.

classmethod createPackage(packageNode)¶

Instantiates a package of this class with the given package node.

Return type:	`Package`
Parameters:	packageNode (`NodegraphAPI.Node`) – The package node.
Returns:	An instance of this package class.

classmethod createPackageEditStackNode(enclosingNode, locationPath)¶

Helper function to be used in EditPackage.create that creates a GroupStack node to be used as the package node. Tags the node with the necessary parameters used internally by the SuperTool.

Return type:	`NodegraphAPI.Node`
Parameters:	enclosingNode (`NodegraphAPI.Node`) – The node in which to create the package node. locationPath (`str`) – The location path for this package.
Returns:	The newly created package node.

delete()¶: Deletes the nodes bound to this package, and rewires any connected nodes.

class PackageSuperToolAPI.Packages.GroupPackage(packageNode)¶

Bases: PackageSuperToolAPI.Packages.GroupMixin, PackageSuperToolAPI.Packages.Package

Class that implements a package that can have child packages.

DEFAULT_NAME = 'group'¶

DISPLAY_ICON = 'group'¶

classmethod create(enclosingNode, locationPath)¶

A factory method which returns an instance of the class. This should be called from any child class’ implementation of create().

Return type:	`Package`
Parameters:	enclosingNode (`NodegraphAPI.Node`) – The parent node within which the new group package node should be created. locationPath (`str`) – The path to the location for this group package.
Returns:	The newly-created package instance.

classmethod createStandardPackageNodes(packageNode)¶

Helper function to be used in the create method of a package to create any standard nodes for this package type. These nodes will be created within the given package node, but need to be connected together by the caller.

Return type:	`list` of `NodegraphAPI.Node`
Parameters:	packageNode (`NodegraphAPI.Node`) – The package node for which the standard package nodes should be created (usually a `GroupNode`).
Returns:	The standard nodes to be added to the package node.

getChildPackages()¶

Return type:	`list` of `Package`
Returns:	The child packages of this package.

getExtraNodeDependencies()¶

Called prior to copying/exporting a hierarchy of packages. Packages with additional nodes can return them here.

Return type:	`list` of `NodegraphAPI.Node`
Returns:	A list of the nodes to duplicate. All nodes under the package node of this package will be implicitly duplicated, but additional nodes must be returned, for example, the post merge nodes.

initializeExtraNodeDependencies()¶: Called after copying/importing a hierarchy of packages. Re-wires and initializes the package’s auxiliary nodes.

class PackageSuperToolAPI.Packages.GroupEditPackage(packageNode)¶

Bases: PackageSuperToolAPI.Packages.GroupMixin, PackageSuperToolAPI.Packages.EditPackage

Abstract base class for edit packages that allow editing of a group package.

childRemoved()¶: Called to notify the package of the removal of a child package.

classmethod create(enclosingNode, locationPath)¶

A factory method which returns an instance of the class. This must be implemented by derived classes.

Return type:	`Package`
Parameters:	enclosingNode (`NodegraphAPI.Node`) – The parent node within which the new root package node should be created. locationPath (`str`) – The path to the location for this root package.
Returns:	The newly-created package instance.
Raises:	NotImplementedError – If derived classes have not implemented this method.

getChildPackageCreateNode()¶

Returns the package node to use when creating child packages. This isn’t necessarily the same as the underlying package node for this package (returned by getPackageNode()).

Return type:	`NodegraphAPI.Node`
Returns:	The `Node` to use when creating child packages.

getChildPackages()¶

Return type:	`list` of `Package`
Returns:	The child packages of this package.

class PackageSuperToolAPI.Packages.DummyGroupPackage(packageNode, locationPath=None, mainNode=None)¶

Bases: PackageSuperToolAPI.Packages.GroupPackage

Dummy/stub package that represents an upstream location that doesn’t necessarily have a node structure within this SuperTool instance that represents it. Can be used as a place holder for an upstream location that hasn’t been explicitly adopted by the user. Creation of child packages will lazily create a node hierarchy within the ‘create stack’ of the SuperTool representing the location. Deletion of all children will cause any parent node hierarchy to be cleaned up.

DEFAULT_NAME = 'dummygroup'¶

DISPLAY_ICON = 'dummygroup'¶

__init__(packageNode, locationPath=None, mainNode=None)¶

Parameters:

packageNode (NodegraphAPI.Node or None) – The package node. Can also be None if this dummy is representing a location with no relevant Node within the SuperTool.
locationPath (str or None) – If packageNode is None, locationPath can be used to provide the location that the dummy package represents.
mainNode (NodegraphAPI.Node or None) – If packageNode is None, mainNode can be used to provide the main SuperTool node.

canAdoptPackage(package)¶

Return type:	`bool`
Parameters:	package (`Package`) – The package to test whether it can be adopted by this package.
Returns:	`True` if the given package can be adopted by this package, otherwise `False`.

classmethod canCreateChildPackage(packageClassOrName, mainNode, locationPath)¶

Parameters:	packageClassOrName (`type` or `str`) – A package class or package class type. mainNode (`NodegraphAPI.Node`) – The main node of a SuperTool. locationPath (`str` @rtype `bool`) – The location path for which to test whether a child package can be created by this package.
Returns:	`True` if this package class can create a child package of the given type for the location of the given path, under the given main node, otherwise `False`.

childRemoved()¶: Called to notify the package of the removal of a child package.

classmethod create(enclosingNode, locationPath)¶: Implementation of Package.create(). This should be called from any child class’ implementation of create().

createChildPackage(*args, **kwargs)¶: Creates a child package under this package. Passes all arguments through to GroupPackage.createChildPackage.

classmethod createForLocation(locationPath, mainNode)¶

Creates an instance of DummyGroupPackage without creating any node hierarchy within the SuperTool. The result DummyGroupPackage represents a potential package at the given locationPath under the given mainNode. Any child creation on the resulting DummyGroupPackage will result in a lazily created node hierarchy within the SuperTool node (which will be lazily deleted when all children are removed). If an existing DummyGroupPackage package node hierarchy already exists for the given location, that node hierarchy will be re-used.

Parameters:	locationPath (`str`) – The path to the location to create the `DummyGroupPackage` for. mainNode (`NodegraphAPI.Node`) – The main SuperTool node.

createParentPackageHierarchy()¶: Creates the necessary nodes in the SuperTool node’s ‘create stack’ for the current location. This includes all necessary parent nodes if they don’t already exist. Updates the current package’s package node with the newly created node.

delete()¶: Deletes the nodes bound to this package, and rewires any connected nodes.

getChildPackageCreateNode()¶

Return type:	`NodegraphAPI.Node`
Returns:	The package node to use when creating child packages. This isn’t necessarily the same as the underlying package node for this package (returned by `getPackageNode()`).

getChildPackages()¶

Return type:	`list` of `Package`
Returns:	The child packages of this package.

getLocationPath()¶

Return type:	`str`
Returns:	The path of the location created/edited by this package.

getMainNode()¶

Return type:	`NodegraphAPI.Node`
Returns:	The main node of the SuperTool in which this package exists.

getParentPackage()¶

Return type:	`Package` or `None`
Returns:	The parent package of this package or `None` if a parent package could not be found.

class PackageSuperToolAPI.Packages.RootPackage(packageNode)¶

Bases: PackageSuperToolAPI.Packages.GroupPackage

Class that implements the root package for a PackageSuperToolAPI-based SuperTool.

__init__(packageNode)¶

Initializes an instance of the class with the given package node.

Parameters:	packageNode (`NodegraphAPI.Node`) – The package node for which to initialize the new package instance. This is usually a Group or a GroupStack node, but can also be a single node.

canBeDeleted()¶

Returns a flag indicating whether this package can be deleted. A package might not be able to be deleted if the SuperTool’s main node is locked.

Return type:	`bool`
Returns:	`True` if the package can be deleted, otherwise `False`.

canBeRenamed()¶

Returns a flag indicating whether this package can be renamed. A package might not be able to be if the SuperTool’s main node is locked.

Return type:	`bool`
Returns:	`True` if the package can be renamed, otherwise `False`.

classmethod canCreatePackageClass(packageClass)¶

Determines if this package can create a child of the given package class. Returns True, to indicate that RootPackage can create any type of package.

Return type:	`bool`
Parameters:	packageClass (`type`) – The package class to test whether it can be created by this package.
Returns:	`True` if the packages of the given class can be created by this package, otherwise `False`.

classmethod create(enclosingNode, locationPath)¶

A factory method which returns an instance of the class.

Return type:	`Package`
Parameters:	enclosingNode (`NodegraphAPI.Node`) – The parent node within which the new root package node should be created. locationPath (`str`) – The path to the location for this root package.
Returns:	The newly-created package instance.

delete()¶

Implementation of Package.delete() which raises an exception to indicate that the root package of a SuperTool cannot be deleted.

Raises:	TypeError – Always, to indicate that the root package of a SuperTool cannot be deleted.

setName(name, peerNames=None, queueEvent=False, selectLocation=False, replaceSelection=True)¶

Raises a TypeError to indicate that the root package of a SuperTool cannot be renamed.

Parameters:

name (str) – The new name of the package.
peerNames (list of str or None) – An optional list of the names of the existing locations which will be peers of the newly adopted package. If provided, this will be used to make sure that the location for the adopted package is given a unique name.
queueEvent (bool) – Whether or not to queue a sceneGraph_locationRenamed event to notify others of the rename.
selectLocation (bool) – If queueEvent is True, whether or not the location rename event should automatically select the location.
replaceSelection (bool) – If both queueEvent and selectLocation are set to True, whether to replace current selection, or to append to current selection.

Raises:

TypeError – Always, to indicate that the root package of a SuperTool cannot be renamed.

Mix-ins¶

class PackageSuperToolAPI.Packages.Mixin¶

Bases: PackageSuperToolAPI.Packages.Upgradable

Base class for classes providing mix-in functionality.

class PackageSuperToolAPI.Packages.CallbackMixin¶

Bases: PackageSuperToolAPI.Packages.Mixin

Class providing mix-in functionality related to providing application callbacks for packages.

Variables:

_OnPackageCreatedCallbackID – The ID of an application callback which is registered for derived classes if they define an ON_CREATED_CALLBACK_TYPE class variable giving the name of a callback type. This callback should be triggered by derived classes on package creation, by calling executeCreationCallback, passing the package object.
_OnShaderSelectedCallbackID – The ID of an application callback which is registered to indicate when a light shader has been selected in the UI. This works by responding to onSceneGraphViewShaderSelected callbacks, which are executed by the SceneGraphView widget.

classmethod executeCreationCallback(package)¶

Executes the “on package created” callback for this package class, passing the given package instance. Called after creation of a new package instance.

Parameters:	package (`Package`) – The package instance for which to execute the “on package created” callback.

classmethod onSceneGraphViewShaderSelected(objectHash=None, node=None, parameterPolicy=None)¶

Callback registered for the onSceneGraphViewShaderSelected type, which is executed when a shader is selected in a SceneGraphView widget. Obtains the GafferThree package responsible for the given node or parameter policy, and if a package is available, executes callbacks of the onGafferShaderSelected type, passing that package as an argument to registered callbacks of that callback type.

Parameters:	node (`NodegraphAPI.Node` or `None`) – The node for which a shader has been set, or `None` if no node was provided when executing the callback. parameterPolicy (`BaseParameterPolicy` or `None`) – The parameter policy for which a shader has been set, or `None` if no parameter policy was provided when executing the callback.

classmethod registerCallbacks(packageClass)¶

Register callback types for this package class.

Parameters:	packageClass (`type`) – The package class for which to register callbacks.

class PackageSuperToolAPI.Packages.DisableableMixin¶

Bases: PackageSuperToolAPI.Packages.Mixin

Class providing mix-in functionality related to disabling and enabling packages.

isDisabled()¶

Return type:	`bool`
Returns:	`True` if the `Package` is directly disabled (as opposed to being disabled due to a parent package being disabled), otherwise `False`.

isDisabledByParents()¶

Return type:	`bool`
Returns:	`True` if the package is disabled due to any of its parents being disabled, otherwise `False`.

setDisabled(disabled)¶

Sets the disabled state of the Package.

Parameters:	disabled (`bool`) – A flag indicating whether the package should be disabled.

class PackageSuperToolAPI.Packages.GroupMixin¶

Bases: PackageSuperToolAPI.Packages.Mixin

Class providing mix-in functionality related to group packages.

Subclasses must implement getChildPackages().

adoptPackage(childPackage, peerNames=None)¶

Adopts the given package as child of this package.

Parameters:	childPackage (`Package`) – The package to adopt. peerNames (`list` of `str` or `None`) – An optional list of the names of the existing locations which will be peers of the newly adopted package. If provided, this will be used to make sure that the location for the adopted package is given a unique name.
Raises:	RuntimeError – If the given package cannot be adopted by this package.

canAdoptPackage(package)¶

Return type:	`bool`
Parameters:	package (`Package`) – The package to test whether it can be adopted by this package.
Returns:	`True` if the given package can be adopted by this package, otherwise `False`.

classmethod canCreateChildPackage(packageClassOrName, mainNode, locationPath)¶

Return type:	`bool`
Parameters:	packageClassOrName (`type` or `str`) – A package class or package class type. mainNode (`NodegraphAPI.Node`) – The main node of a SuperTool. locationPath (`str`) – The location path for which to test whether a child package can be created by this package.
Returns:	`True` if this package class can create a child package of the given type for the location of the given path, under the given main node, otherwise `False`.

canReorderChildPackage(oldIndex, newIndex)¶

Return type:	`bool`
Parameters:	oldIndex (`int`) – The index position of the child package to reorder. newIndex (`int`) – The index position to which to move the specified child package.
Returns:	`True` if the package at the given index can be reordered to the given new index, otherwise `False`.

childRemoved()¶: Called to notify the GroupMixin of the removal of a child package. Can be overridden by subclasses to, for example, clean up lazily-created parent locations. The default implementation does nothing.

createChildPackage(packageClassOrName, name=None, peerNames=None)¶

Creates a child package under this package.

Return type:	`Package` or `None`
Parameters:	packageClassOrName (`type` or `str`) – Either the type or the name of the type of child package to create. name (`str` or `None`) – The new name of the package to create. If not specified, a default name will be used. If the name (specified or default) conflicts with an existing package name, it will be modified with a suffixed incrementing number until a unique name is found. peerNames (`iterable` or `None`) – An optional list of names of siblings which is used when performing collision checks for the name of the newly created child package.
Returns:	The newly created child package or `None` if a child package could not be created.
Raises:	TypeError – If packages of the given type cannot be created as child packages. ValueError – If this package cannot create a child package of the given type.

getChildPackage(name, includeDummies=False)¶

Return type:	`Package` or `None`
Parameters:	name (`str`) – The name of the package. includeDummies (`bool`) – A flag indicating whether a package of the given name should be returned if it is a dummy group package.
Returns:	The child package of the given name, or `None` if no such package was found.

getChildPackageCreateNode()¶

Return type:	`NodegraphAPI.Node`
Returns:	The package node to use when creating child packages. This isn’t necessarily the same as the underlying package node for this package (returned by `getPackageNode()`).

getChildPackages()¶

Return type:	`list` of `Package`
Returns:	The child packages of this package.
Raises:	NotImplementedError – If the subclass has not implemented this method.

classmethod getLocationTypes()¶

Return type:	`list` of `str`
Returns:	A list of location types that packages of this type can represent. The default implementation returns a list containing the single value `'group'`.

reorderChildPackage(oldIndex, newIndex)¶

Reorders the child package at the given index to a new position.

Parameters:	oldIndex (`int`) – The index position of the child package to reorder. newIndex (`int`) – The index position to which to move the specified child package.
Raises:	RuntimeError – If the child package at the given index cannot be reordered to the given new index.

class PackageSuperToolAPI.Packages.LinkingMixin¶

Bases: PackageSuperToolAPI.Packages.Mixin

Class providing mix-in functionality related to light linking for PackageSuperToolAPI packages.

LINKING_ILLUMINATION_EFFECT = 'illumination'¶

LINKING_ILLUMINATION_NODE_NAME = 'LightLinkSetup_illumination'¶

LINKING_ILLUMINATION_NODE_REF = 'lightLink_illumination'¶

LINKING_SHADOW_EFFECT = 'shadow visibility'¶

LINKING_SHADOW_NODE_NAME = 'LightLinkSetup_shadow'¶

LINKING_SHADOW_NODE_REF = 'lightLink_shadow'¶

classmethod getIlluminationLinkingNode(packageNode, create=False)¶

Return type:	`NodegraphAPI.Node` or `None`
Parameters:	packageNode (`NodegraphAPI.Node`) – The package node for which the linking node should be returned. create (`bool`) – A flag indicating whether the node should be created if it doesn’t exist.
Returns:	The illumination linking node for this package, or `None` if the node does not exist and `create` is not set to `True`.

classmethod getLinkingNodes(packageNode, create=False)¶

Return type:	`(NodegraphAPI.Node, NodegraphAPI.Node)` or `(None, None)`
Parameters:	packageNode (`NodegraphAPI.Node`) – The package node for which the linking nodes should be returned. create (`bool`) – A flag indicating whether the nodes should be created if they don’t exist.
Returns:	A tuple containing either the light linking nodes for this package, or two `None` values if the nodes do not exist and `create` is not set to `True`.

classmethod getShadowLinkingNode(packageNode, create=False)¶

Return type:	`NodegraphAPI.Node` or `None`
Parameters:	packageNode (`NodegraphAPI.Node`) – The package node for which the linking node should be returned. create (`bool`) – A flag indicating whether the node should be created if it doesn’t exist.
Returns:	The shadow linking node for this package, or `None` if the node does not exist and `create` is not set to `True`.

class PackageSuperToolAPI.Packages.LockingMixin¶

Bases: PackageSuperToolAPI.Packages.Mixin

Class providing mix-in functionality related to locking for PackageSuperToolAPI packages.

isLocked()¶

Return type:	`bool`
Returns:	The current lock state of this package.

setLocked(state)¶

Sets the lock state of the particular package.

Parameters:	state (`bool`) – The lock state to set for the package.

class PackageSuperToolAPI.Packages.LookFileReferenceEditMixin¶

Bases: PackageSuperToolAPI.Packages.Mixin

Class providing mix-in functionality related to editing of Look File references for PackageSuperToolAPI packages.

Derived classes are expected to define a pseudo-protected instance function with the following name to specify the name of the node type that stores Look File reference information: _getLookFileReferenceNodeTypeName

getLookFileMaterial()¶

Return type:	2-`tuple` of `str` or `None`
Returns:	A tuple containing the asset and material path for this edit package’s Look File Material. Both can be `None` to indicate that asset and/or material path are not overridden by this edit package.

isLookFileMaterialActive()¶

Return type:	`bool`
Returns:	`True` if the asset and/or material path for a Look File Material on this edit package are potentially overridden by this edit package, otherwise `False`.

setLookFileMaterial(asset, materialPath, assetAsExpression=False, materialPathAsExpression=False)¶

Sets overrides for the asset and/or material path of the material that is sourced from a Look File for this edit package.

Makes the Look File Material active if either an asset or a material path are given, so that values from the incoming scene can be overridden.

The Look File asset and the path to the material can both optionally be specified as expressions.

Parameters:

asset (str or None) – The Look File asset from which to load the material, or None to disable that override, while leaving its current value intact, and to pick up the incoming value.
materialPath (str or None) – The path of the material in the Look File, or None to disable that override, while leaving its current value intact, and to pick up the incoming value.
assetAsExpression (bool) – A flag indicating whether the given asset is supplied as an expression.
materialPathAsExpression (bool) – A flag indicating whether the given material path is supplied as an expression.

Note:

The overrides for the Look File Material from which to take shaders can be turned on or off using setLookFileMaterialActive.

setLookFileMaterialActive(lookFileMaterialActive)¶

Sets whether the asset and/or material path for a Look File Material on this edit package are potentially overridden by this edit package

Parameters:	lookFileMaterialActive (`bool`) – Flag that controls whether the asset and/or material path for a Look File Material on this edit package are potentially overridden by this edit package.
Note:	The Look File Material to take shaders from can be set using `setLookFileMaterial`.

class PackageSuperToolAPI.Packages.MaterialMixin¶

Bases: PackageSuperToolAPI.Packages.Mixin

Class providing mix-in functionality related to materials for PackageSuperToolAPI packages.

getLookFileMaterial()¶

Return type:	`tuple` of (`str`, `str`) or (`None`, `None`)
Returns:	A tuple containing the asset and material path for this package’s Look File material, or (`None`, `None`) if no such Look File material was found.

getShader(shaderType)¶

Return type:	`str` or `None`
Parameters:	shaderType (`str`) – The name of the type of shader whose name to return. Is expected to include a renderer name prefix, for example `"arnoldLight"` or `"prmanSurface"`.
Returns:	The name of the shader of the given shader type that is locally set for the package, or `None` if no shader of the given type is locally set for the package.

isLookFileMaterialActive()¶

Return type:	`bool`
Returns:	`True` if the shaders for this package are taken from a Look File Material, otherwise `False`.

isUsingLookFileMaterial()¶: @deprecated: This function is deprecated. Please use isLookFileMaterialActive() instead.

setIsUsingLookFileMaterial(newValue)¶: @deprecated: This function is deprecated. Please use setLookFileMaterialActive() instead.

setLookFileMaterial(asset, materialPath, assetAsExpression=False, materialPathAsExpression=False)¶

Sets the material node to point at a material baked into a Look File. The Look File asset and and the path to the material can both optionally be specified as expressions.

Parameters:

asset (str or None) – The asset for the Look File Material, or None to deactivate the Look File Material.
materialPath (str) – The path to the Look File Material.
assetAsExpression (bool) – A flag indicating whether the given asset is supplied as an expression.
materialPathAsExpression (bool) – A flag indicating whether the given material path is supplied as an expression.

Note:

The Look File Material from which to take shaders can be turned on or off using setLookFileMaterialActive.

setLookFileMaterialActive(lookFileMaterialActive)¶

Sets whether the shaders for this package are taken from a Look File Material.

Parameters:	lookFileMaterialActive (`bool`) – Flag that controls whether shaders for this package are taken from a Look File Material.
Note:	The Look File Material to take shaders from can be set using `setLookFileMaterial`.

setShader(shaderType, shaderName, asExpression=False)¶

Sets or resets the shader of the given shader type. Adds a shader of the given shader type if the parameter for the shader type doesn’t exist yet.

Parameters:

shaderType (str) – The name of the type of shader to set to the given shader name. Is expected to include a renderer name prefix, for example "arnoldLight" or "prmanSurface".
shaderName (str or None) – The name or expression to set for the shader with the given shader type. If an empty string or None is passed, the name or expression is reset/cleared.
asExpression (bool) – Flag that controls whether to set or reset the shader of the given shader type as an expression rather than a constant value.

class PackageSuperToolAPI.Packages.MuteAndSoloMixin¶

Bases: PackageSuperToolAPI.Packages.Mixin

Class providing mix-in functionality related to muting and soloing of lights for PackageSuperToolAPI packages.

MUTEANDSOLO_NODE_REFERENCE = 'muteAndSolo'¶

NODE_NAME = 'MuteAndSolo'¶

SOLOLISTEDIT_NODE_REFERENCE = 'soloEdit'¶

delete(edit=False)¶

Performs the cleanup necessary for removing a package that supports Mute and Solo.

Parameters:	edit (`bool`) – `True` the package is an edit package, `False` it is a create package.

getExtraNodeDependencies()¶

Called prior to copying/exporting a hierarchy of packages. Packages with additional nodes can return them here.

Return type:	`list` of `NodegraphAPI.Node`
Returns:	A list of the nodes to duplicate. All nodes under the package node of this package will be implicitly duplicated, but additional nodes must be returned, for example, the post merge nodes.

getMuteSoloAndSoloListEditNode(create=False)¶

getOverrideNodeAndParameter(attributeName)¶

Returns the node and the parameter that drives the value of the attribute of the given name at this package’s location.

This function closes the loop between attributes and parameters. Columns in the SceneGraphView widget created in a PackageSuperTool’s editor are associated with attribute names. This function returns the node and parameter for editing these attributes.

Return type:	`(NodegraphAPI.Node, NodegraphAPI.Parameter)` or `(None, None)`
Parameters:	attributeName (`str`) – The name of the attribute for which to return the override node and parameter.
Returns:	The node and its parameter responsible for setting/editing the value of the given attribute, or `(None, None)` if no such node and parameter could be found.

initializeExtraNodeDependencies()¶: Called after copying/importing a hierarchy of packages. Re-wires and initializes the package’s auxiliary nodes.

isMuteOverrideEnabled()¶

Determines whether the package’s mute state is overridden or not.

Return type:	`bool`
Returns:	`True` if the package’s mute state is overridden, otherwise `False`.

isMuted()¶

Determines whether the package is muted or not.

Return type:	`bool`
Returns:	`True` if the package is muted, otherwise `False`.

isSoloOverrideEnabled()¶

Determines whether the package’s solo state is overridden or not.

Return type:	`bool`
Returns:	`True` if the package’s solo state is overridden, otherwise `False`.

isSoloed()¶

Determines whether the package is soloed or not.

Return type:	`bool`
Returns:	`True` if the package is soloed, otherwise `False`.

setMuted(muted, edit=False)¶

Sets the mute state of the package.

Parameters:	muted (`bool`) – `True` to mute the package, `False` to unmute it. edit (`bool`) – `True` if the package is an edit package, `False` if it is a create package.

setSoloed(soloed, edit=False)¶

Sets the solo state of the package.

Parameters:	soloed (`bool`) – `True` to solo the package, `False` to unsolo it. edit (`bool`) – `True` the package is an edit package, `False` it is a create package.

class PackageSuperToolAPI.Packages.MuteAndSoloEditMixin¶

Bases: PackageSuperToolAPI.Packages.MuteAndSoloMixin

Class providing mix-in functionality related to editing of mute and solo states of lights for PackageSuperToolAPI packages.

delete()¶: Performs the cleanup necessary for removing a package that supports Mute and Solo.

setMuted(muted)¶

Sets the mute state of the package.

Parameters:	muted (`bool`) – `True` to mute the package, `False` to unmute it.

setSoloed(soloed)¶

Sets the solo state of the package.

Parameters:	soloed (`bool`) – `True` to solo the package, `False` to unsolo it.

Module Functions¶

PackageSuperToolAPI.Packages.GetPackageClass(superToolName, packageClassName)¶

Return type:	`Package` or `None`
Parameters:	superToolName (`str` or `None`) – The name of the SuperTool for which the package class was registered of `None` if the package is generic. packageClassName (`str`) – The package class name.
Returns:	The package class with the given name, registered for the given SuperTool if one was provided. Returns `None` if no such package class could be found.

PackageSuperToolAPI.Packages.GetPackageClassAndPackageName(superToolName, packageClassOrName)¶

Return type:	`(type, str)` or `(None, None)`
Parameters:	superToolName (`str`) – The name of the SuperTool. packageClassOrName (`type` or `str`) – A package class or package class type.
Returns:	A tuple of the form `(packageClass, packageName)` containing the class and name for the given package class, or `None` if no such registered package class could be found for the given SuperTool.

PackageSuperToolAPI.Packages.GetPackageClassForGroupLocationType(superToolName, groupLocationType)¶

Return type:	`Package` or `None`
Parameters:	superToolName (`str` or `None`) – The name of the SuperTool for which to return the registered package class for the given group location type, or `None` to return the registered generic package class for the given location type. groupLocationType (`str`) – The group location type for which to return the registered package class for the SuperTool of the given name.
Returns:	The registered package class for the SuperTool of the given name which is registered for the given group location type (i.e. types of location which can contain child locations, like `'group'`).

PackageSuperToolAPI.Packages.GetRegisteredDisplayPackageClasses(superToolName)¶

Return type:	`list` of `Package`
Parameters:	superToolName (`str` or `None`) – The name of the SuperTool for which the registered display package classes should be returned, or `None` to return the registered generic display package classes.
Returns:	A list of the registered display packages for the given SuperTool.

PackageSuperToolAPI.Packages.GetRegisteredPackageClasses(superToolName)¶

Return type:	`list` of `(str, type)`
Parameters:	superToolName (`str` or `None`) – The name of the SuperTool for which the registered package classes should be returned, or `None` to return the registered generic package classes.
Returns:	A list of (name, class) tuples for the registered package classes for the given SuperTool, or a list of generic packages if the given SuperTool name is `None`. The `name` element is the name of the package class. To access the display name (if the package class supports it), query the `DISPLAY_NAME` attribute (if it exists) on the class.

PackageSuperToolAPI.Packages.IsLocationTypeAdoptable(superToolName, locationType)¶

Return type:	`bool`
Parameters:	superToolName (`str` or `None`) – The name of the SuperTool for which to check whether locations of the given type can be adopted. locationType (`str`) – The name of the location type to check.
Returns:	`True` if locations of the given type can be adopted by the SuperTool of the given name, otherwise `False`.

PackageSuperToolAPI.Packages.RegisterPackage(superToolName, packageClass)¶: @deprecated: This function is deprecated. Please use RegisterPackageClass() instead.

PackageSuperToolAPI.Packages.RegisterPackageClass(superToolName, packageClass)¶

Registers a new package class for the given SuperTool, or registers it as a generic package class if the given SuperTool name is None.

Parameters:	superToolName (`str` or `None`) – The name of the SuperTool for which the package class will be registered, or `None` to register a generic package class. packageClass (`type`) – The package class to be registered.