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: 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: 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: GroupMixin, 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: GroupMixin, 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: 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)
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.

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:
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: 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: Upgradable

Base class for classes providing mix-in functionality.

class PackageSuperToolAPI.Packages.CallbackMixin

Bases: 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 (UI4.FormMaster.BaseParameterPolicy.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: 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: 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: 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: 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: 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: 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: 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: 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.