| Inheritence |
|
This class exposes ways to access information about a work item in PDG.
You can look up work items by name with the pdg.Graph.workItemByName method or by ID using the pdg.Graph.workItemById method.
pdg.Node objects also provide methods to access the work items owned by that node.
Methods
addAttrib(name, type:
pdg.attribType, overwrite=
pdg.attribOverwrite.Match, error_level=
pdg.attribErrorLevel.Error)
→ pdg.AttributeFile or pdg.AttributeFloat or pdg.AttributeInt or pdg.AttributePyObject or pdg.AttributeString
Adds an attribute with the specified name and type.
The optional overwrite argument can be set to a value from the pdg.attribOverwrite enum to control what happens when the work item already has an attribute with the same name. By default, if the attribute already exists and has the same type, then the existing attribute is returned. If the attribute exists with a different type, then an exception is thrown. If overwrite is set to pdg.attribOverwrite.Always the existing attribute will be removed and replace by one with the new type.
The optional error_level argument can be used to control how PDG handles failures. By default an exception is thrown with a message that describes the source of the failure. If the pdg.attribErrorLevel.Warn enum value is passed instead, the error message will instead be added as a warning to the node that owns the work item. Finally, passing in pdg.attribErrorLevel.Quiet will suppress all error reporting. When the error level is set to a value other than Error, the method will return None if the attribute cannot be added.
addEnvironmentVar(str)
Adds an environment variable to the work item’s environment.
This method is deprecated. Instead, you can add an attribute using pdg.WorkItem.addAttrib and set the pdg.attribFlag.EnvExport flag on the attribute.
addError(error_message, fail_task=False)
Adds an error message to the work item’s internal, in-process log. If the work item is running in a Python Script or Python Processor and fail_tasks is True, execution of the work item will also be interrupted.
addEventHandler(handler, filter:
pdg.EventType, pass_handler=False)
→ pdg.EventHandler
Adds an event handler to the work item with a value of the type of event to receive. The handler should be a callable that accepts one argument of type pdg.Event.
If pass_handler is True, then the handler itself is passed as the first argument to the function. If pass_handler is False, then only the event object is passed to the function.
addEventHandler(handle, event_types:
pdg.EventType, pass_handler=False)
→ pdg.EventHandler
Adds an event handler to the work item with a list of the types of events to receive. The handler should be a callable that accepts one argument of type pdg.Event.
If pass_handler is True, then the handler itself is passed as the first argument to the function. If pass_handler is False, then only the event object is passed to the function.
addExpectedResultData(result, tag, own=True)
Adds an expected result file to the work item with the specified file tag. result is the string path to the file that the work item will produce when it cooks.
The optional own parameter indicates whether the work item owns the file. PDG uses this parm when it deletes output files from disk.
addMessage(log_message)
Adds a message to the work item’s internal, in-process log.
addResultData(result, tag="", checksum=0, own=True)
Adds a result file to the work item with the specified file tag and checksum value. result is the string path to the file on disk.
The optional own parameter indicates whether the work item owns the file. PDG uses this parm when it deletes output files from disk.
addLog(log_type, message)
Adds a log message of the specified pdg.workItemLogType to the work item’s internal, in process-log. This is the generic version of the specialized log methods, like addError or addMessage.
addWarning(warning_message)
Adds a warning message to the work item’s internal, in-process log.
attrib(name)
→ pdg.AttributeFile or pdg.AttributeFloat or pdg.AttributeInt or pdg.AttributePyObject or pdg.AttributeString
Returns the work item attribute with the specified name, or None if no such attribute exists.
The attribute is one of the supported attribute types listed in pdg.attribType. You can also write the attribute as work_item.attrib[name].
attrib(name, type)
→ pdg.AttributeFile or pdg.AttributeFloat or pdg.AttributeInt or pdg.AttributePyObject or pdg.AttributeString
Returns the work item attribute with the specified name and type, or None if no such attribute exists.
attribArray(name)
→ list
of int
, float
, str
or pdg.File
Returns the array stored on an attribute.
attribHash(include_internal=True, include_unowned=True, only_static=False)
→ int
Returns a hash value calculated based on work item attribute values. This can be useful to identify work items between cooks.
The include_internal argument determines whether or not the hashing operation should include internal attributes defined by PDG itself, like work item input/output files or the the command string.
When the include_unowned argument is False the hashing operation will only consider attributes that were modified or added by the node that owns the work item. Otherwise, all attributes are considered.
When the only_static argument is True the hashing operation will only consider attributes created when the work item was generated. Any attribute additions or modifications made while the work item was scheduled or cooked are not included in the hash.
attribHash(filter, include_internal=True, include_unowned=True, only_static=False)
→ int
Performs the same operation as above, but filters the attributes before hashing them using the list of attribute names passed in via the filter argument.
attribMatch(pattern)
→ list
of str
Returns the list of attribute names from the work item that match the specified pdg.AttributePattern instance.
attribNames()
→ list
of str
Returns the list of attribute names currently stored on the work item.
attribNames(type)
→ list
of str
Returns the list of attribute names currently stored on the work item with the specified type.
attribValue(name, index=0)
→ int
, float
, str
or pdg.File
Returns the value of an attribute at the specified index. You can also write the attribute as work_item[name][index].
attribValues()
→ dict
of list
of int
, float
, and str
Returns the map of all attribute names to values on the work item.
attribValues(type)
→ dict
of list
of int
, float
, or str
Returns the map of all attribute names to values on the work item of the specified pdg.attribType.
attribType(name)
→ pdg.attribType
Returns the type of attribute with the specified name, or pdg.attribType.Undefined if no attribute with that name exists.
cancel()
Cancels the cook of the work item, if it has already been scheduled by a scheduler. If the item has not been scheduled yet, it will eventually canceled when it gets processed by the scheduler associated with it.
clearAttribs()
Clears all attributes on the work item.
clearAttribs(type)
Clears all attributes on the work item of the specified type.
clearEnvironment()
Clears the work item’s environment and stops it from inheriting variables from the parent work item.
This method is deprecated. Instead, remove attributes that have the pdg.attribFlag.EnvExport flag set.
clearExpectedOutputs()
Clears any expected output files from the work item.
clearResultData()
Clears all result files on the work item.
cookSubItem(state, duration=0)
If the work item is in a batch that is cooking in process, this method can be used to indicate to PDG that the item has completed. Doing so allows downstream tasks that depend on the work item to begin processing. The state argument should be one of the completed states from the pdg.workItemState enum, and duration is an optional cook duration for the work item in seconds.
Calling this method on a work item that is not cooking in process or is not in a batch will cause an exception to be thrown.
cookWarning(message)
Adds a warning message to the node which owns this work item.
dirty(delete, remove_outputs)
Dirties the work item. If delete is set to True, then it deletes the work item. If remove_outputs is True, then it also deletes the file results on disk generated by this work item.
Work items cannot be dirtied from Python if they're actively evaluating or if they're not owned by the node that’s calling the Python code. For example, it’s invalid to try to dirty an upstream work item in a Python Processor TOP or a work item that’s evaluating in a Python Script TOP.
envLookup(key)
→ int
, float
, or str
Returns the value of an environment variable on the work item.
This method is deprecated. Instead, you can look up the attribute with pdg.WorkItem.attrib and check for the pdg.attribType.EnvExport flag.
eraseAttrib(name)
Erases an attribute with the specified name.
fileAttribArray(name)
→ list
of pdg.File
Returns the file attribute array.
fileAttribValue(name, index=0)
→ pdg.File
Returns the file attribute value at the specified index.
floatAttribArray(name)
→ list
of float
Returns the floating point attribute array.
floatAttribValue(name, index=0)
→ float
Returns the floating point attribute value at the specified index.
firstResultDataForTag(tag)
→ str
Returns the file path to the result for the specified tag.
hasAttrib(name)
→ bool
If the work item has the specified attribute, then it returns True.
hasEnvironmentVar(name)
→ bool
If the work item has the specified environment variable defined, then this returns True . Else False.
This function is deprecated as environment variables are now implemented as attributes. Instead, you can check for an environment variable by looking up an attribute and checking if it has the pdg.attribFlag.EnvExport flag set.
hasDependency(work_item)
→ bool
If this work item depends on another work item, then this returns True .
invalidateCache()
Invalidates the file cache of this work item and any downstream dependents.
This causes work items in nodes with the cache mode set to Automatic to recook, even if their cache files are found on disk.
intAttribArray(name)
→ list
of int
Returns the integer attribute array.
intAttribValue(name, index=0)
→ int
Returns the integer attribute value at the specified index.
loadJSONFile(file_path)
→ pdg.WorkItem
Static method
Loads a work item from the specified JSON file path.
loadJSONString(json_string)
→ pdg.WorkItem
Static method
Loads a work item from the specified JSON string data
lockAttributes()
→ pdg.LockAttributesBlock
Locks this work item’s attributes using a context manager. For the duration of the context manager, it is safe to modify attributes on the work item.
For example:
with item.lockAttributes(): item.setIntAttrib("example", 10)
Note
You should not call this method from within a PDG node callback, such as onGenerate or onPartition. The node already ensures that the callback can safely access all of the work items.
loopBegin(int)
→ pdg.WorkItem
Returns the loop begin parent item at the given loop depth. If this item is not in a loop or the depth is out of bounds, then it returns None.
makeActive()
→ pdg.ActiveItemBlock
Makes this work item active for parameter evaluation using a Python context manager.
All parameters evaluated during the lifetime of the context manager block will use this work item when computing @attribute or pdgattribute function values.
For example:
with item.makeActive(): val = item.node["parm"].evaluateString()
memoryUsage()
→ pdg.MemoryInfo
Queries memory usage of the work item.
numericAttribute(str)
→ int
or float
Returns a attribute value for a given attribute string. This can be either an attribute name like foo, or a name and a component suffix like foo.x or foo.2.
This method is deprecated. Instead, you can look up the attribute using item.attrib(name) and call attrib.asString().
pyObjectAttribValue(name)
→ object
Returns the Python object stored on the specified attribute.
removeEventHandler(handler)
Removes an event handler from the work item.
removeAllEventHandlers()
Removes all event handlers from the work item.
renameAttrib(src_name, dst_name, overwrite_existing=False)
→ bool
Renames the attribute with src_name to dst_name.
resultDataForTag(tag)
→ array
of pdg.File
Returns the result data entries for a specified tag. The results are returned as a pdg.File objects.
saveJSONFile(file_path, pretty_print=False)
→ bool
Saves the work item to a JSON file and returns True on success.
saveJSONString(pretty_print=False)
→ str
Saves the work item to JSON and returns it as a string.
serializeData()
→ str
Serializes the work item’s data to a string.
serializeDataToFile(filepath)
Serializes the work item’s data to a file.
setAttribFlag(name, flag, set)
Sets or clears the pdg.attribFlag on the specified attribute.
setCommand(command, shell=False)
Sets the work item’s command value to specified command string. Setting shell is set to True indicates to the scheduler that the work item should be run in the system shell if possible. For example, if the work item is executed using a 
Local Scheduler the scheduler will pass the shell=True argument when spawning a worker process for the work item. Since the command string is run in the system shell, it is possible to use environment variables and syntax features supported by that shell. However, relying on shell features will likely mean that the work item’s command string will not work across multiple platforms.
setFileAttrib(name, value, index=0, overwrite=
pdg.attribOverwrite.Match)
Sets a file attribute value at the specified index. If the attribute does not exist, then it is created.
The optional overwrite argument determines what happens if an attribute already exists with the same name, but a different type. See pdg.WorkItem.addAttrib for details.
setFileAttrib(name, array, overwrite=
pdg.attribOverwrite.Match)
Sets a file attribute array. If the attribute does not exist, then it is created.
The optional overwrite argument determines what happens if an attribute already exists with the same name, but a different type. See pdg.WorkItem.addAttrib for details.
setFloatAttrib(name, value, index=0, overwrite=
pdg.attribOverwrite.Match)
Sets an float attribute value at the specified index. If the attribute does not exist, then it is created.
The optional overwrite argument determines what happens if an attribute already exists with the same name, but a different type. See pdg.WorkItem.addAttrib for details.
setFloatAttrib(name, array, overwrite=
pdg.attribOverwrite.Match)
Sets a float attribute array. If the attribute does not exist, then it is created.
The optional overwrite argument determines what happens if an attribute already exists with the same name, but a different type. See pdg.WorkItem.addAttrib for details.
setFrame(frame, step=1.0)
Sets the frame and optionally the frame step size for the work item.
setIntAttrib(name, value, index=0, overwrite=
pdg.attribOverwrite.Match)
Sets an integer attribute value at the specified index. If the attribute does not exist, then it is created.
The optional overwrite argument determines what happens if an attribute already exists with the same name, but a different type. See pdg.WorkItem.addAttrib for details.
setIntAttrib(name, array, overwrite=
pdg.attribOverwrite.Match)
Sets an integer attribute array. If the attribute does not exist, then it will be created.
setIsPostCook(is_postcook)
Sets whether or not this work item needs to run the onPostCookTask callback when it completes cooking. The callback is only run if the node that owns the work item has an onPostCookTask implementation defined.
setLabel(label)
Sets the descriptive label for the work item. The label string does not have to be unique, and can contain spaces or other special characters.
setLoopInfo(loop_iteration, loop_number, loop_size)
Sets the loop iteration, number and size for the work item. Only safe to call inside of a feedback begin node.
setPyObjectAttrib(name, value, overwrite=
pdg.attribOverwrite.Match)
Sets a Python object attribute value. The attribute will increment the ref count on the object to ensure that it exists for the duration of the attribute itself.
The optional overwrite argument determines what happens if an attribute already exists with the same name, but a different type. See pdg.WorkItem.addAttrib for details.
setStringAttrib(name, value, index=0, overwrite=
pdg.attribOverwrite.Match)
Sets a string attribute value at the specified index. If the attribute does not exist, then it is created.
The optional overwrite argument determines what happens if an attribute already exists with the same name, but a different type. See pdg.WorkItem.addAttrib for details.
setStringAttrib(name, array, overwrite=
pdg.attribOverwrite.Match)
Sets a stringattribute array. If the attribute does not exist, then it is created.
The optional overwrite argument determines what happens if an attribute already exists with the same name, but a different type. See pdg.WorkItem.addAttrib for details.
startSubItem(wait=True)
If the work item is a batch sub item that is cooking in process, this method will update the subitem to be in the cooking state. By default it will also wait for the subitem’s dependencies to be cooked, which is necessary for batches that are configured to start immediately instead of waiting on all input items.
Calling this method on a work item that is not cooking in process or is not in a batch will cause an exception to be thrown.
stats()
→ pdg.WorkItemStats
Returns the cook time stats for the work item.
stringAttribute(name)
→ str
Looks up a string attribute value on the work item. This can be either a plain attribute name like foo, or a name and component suffix like foo.x.
This method is deprecated. Instead, you can look up the attribute using item.attrib(name) and call attrib.asString().
stringAttribArray(name)
→ list
of str
Returns the string attribute array.
stringAttribValue(name, index=0)
→ str
Returns the string attribute value at the specified index.
timeDependentAttribs()
→ list
of str
Returns the list of attributes that are time dependent, if this work item is in a batch with shared attributes on the batch parent.
transferFiles()
→ bool
Manually runs file transfer logic for any work item files attributes that have the pdg.attribFlag.Transfer attribute flag set to True. Files are copied using custom file transfer handlers if any have been registered, otherwise the files are copied to the working directory using the default scheduler logic. The function returns True if all files are copied successfully, or False if one or more errors occurred.
updateResultData(index, file, tag, checksum, own)
Updates the result data a given index.
batchIndex
: int
Property
If the work item is in a batch, then this property contains the item’s index within that batch.
batchParent
: pdg.BatchWorkItem
Property
If this work item is in a batch, then returns the batch parent. If this work item is not in a batch, then returns None.
command
: str
Property
The command string for the work item.
cookDuration
: int
Property
If the the work item has cooked, then returns the cook duration performance stat for the work item.
data
: pdg.WorkItemData
Property
The data object for the work item which contains its attribute values.
dependencies
: list
of pdg.WorkItem
Property
The list of work items that this work item depends on.
dependents
: list
of pdg.WorkItem
Property
The list of work items that depend on this work item.
dependencyState
: pdg.workItemState
Property
The worst cooked dependency state.
If all dependencies were cooked successfully, then the property is set to pdg.workItemState.CookedSuccess.
If any dependencies were canceled, then the dependencyState is set to pdg.workItemState.CookedCancel.
If the dependency failed, then the state is set to pdg.workItemState.CookedFail.
environment
: dict
of int
, float
, and str
Property
A dictionary mapping variable names to values in the work item’s environment.
executionType
: pdg.workItemExecutionType
Property
The work item execution type, e.g. if it’s a regular work item or a long running process like a simulation tracker.
expectedInputResultData
: list
of pdg.File
Property
The list of all inputs, including expected files. The inputs are stored as pdg.File objects.
expectedResultData
: list
of pdg.File
Property
The list of expected results for the work item. The results are stored as pdg.File objects.
frame
: float
Property
The frame value associated with the work item.
frameStep
: float
Property
The frame step size associated with the work item.
hasFrame
: bool
Property
If the work item has a frame, then this is set to True. Else False.
hasLabel
: bool
Property
If the work item has a custom label, then this property is set to True. Otherwise the property will be False.
id
: int
Property
The ID of the work item, unique within the pdg.GraphContext that contains the item.
index
: index
Property
The sort/ordering index for the work item.
inputResultData
: list
of pdg.File
Property
The list of input results for this work item. For example, the output files collected from all dependencies.
isInProcess
: bool
Property
If this work item cooks in process instead of spawning a child process using the active scheduler, then this is set to True. Else False.
isNoGenerate
: bool
Property
If this work item does not generate child items in downstream nodes, then this is set to True.
isOutOfProcess
: bool
Property
If this work item cooks out of process, then this is set to True.
Note
It is possible for an item to return False for both isInProcess and isOutOfProcess when that work item does not cook at all. For example, a work item in an 
Attribute Create TOP node
does not cook, and will therefore return False for both.
isPartition
: bool
Property
If this work item is a Static or Dynamic partition, then this is set to True.
isPostCook
: bool
Property
If this work item runs the post cook hook after the being marked as completed, then this is set to True. Else False.
isStatic
: bool
Property
If the work item is a static, regular work item, then this is set to True.
isSuccessful
: bool
Property
If the work item is in a successful cooked state, either
pdg.workItemState.CookedSuccess or pdg.workItemState.CookedCache, then this is set to True.
isUnsuccessful
: bool
Property
If the work item in a unsuccessful cooked state, either
pdg.workItemState.CookedCancel or pdg.workItemState.CookedFail, then this is set to True.
label
: str
Property
Returns the label for the work item. If the item has no label, this property returns the name value instead.
loopDepth
: int
Property
The nested loop depth for the work item, if it is part of a loop block, starting at 0. If the work item is not inside of a loop this property will be set to -1.
loopIteration
: int
Property
The iteration number for the work item, if it is part of a loop block. If the work item is not inside of a loop this property will be set to -1.
loopNumber
: int
Property
The loop number for the work item, if it is part of a loop block. Feedback loop blocks can contain multiple independent groups of work items, each of which will have its own loop number. Work items within the same numbered loop will have unique iteration numbers from 0 to the size of the loop. If the work item is not inside of a loop this property will be set to -1.
loopSize
: int
Property
The size of the loop that contains the work item, or -1 if the work item is not inside of a loop block.
logMessages
: str
Property
The raw string data for the work item’s in-process log, which contains any messages add by the calling the pdg.WorkItem.addMessage.
name
: str
Property
The unique name for the work item. Only unique within the pdg.GraphContext.
parent
: pdg.WorkItem
Property
The upstream work item from which this work item was generated.
partitionItems
: list
of pdg.WorkItem
Property
If the work item is a partition, then this list contains the work items that the partition depends on. Otherwise, the list is empty.
priority
: int
Property
The priority of the work item. 0 is the highest priority.
resultData
: list
of pdg.File
Property
The list of result data for the work item containing tuples of the form.
shouldRunInShell
: bool
Property
Whether or not the work item command should run in the system shell when it gets executed by the scheduler. This is currently only supported by the Local Scheduler.
state
: pdg.workItemState
Property
The current state of the work item.
type
: pdg.workItemType
Property
The type object that constructed the work item.