| Inheritance |
|
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 ¶
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, timestamp=True)
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.
If timestamp is True, the log message will be prefixed with the current timestamp.
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(path, tag="", own=True)
This method is deprecated. Use pdg.WorkItem.addExpectedOutputFile instead.
addExpectedOutputFile(path, tag="", own=True)
Adds an expected output file to the work item with the specified file tag. path 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, timestamp=True)
Adds a message to the work item’s internal, in-process log.
If timestamp is True, the log message will be prefixed with the current timestamp.
addOutputFile(path, tag="", checksum=0, own=True)
Adds an output file to the work item with the specified file tag and checksum value. path 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.
addResultData(path, tag="", checksum=0, own=True)
This method is deprecated. Use pdg.WorkItem.addOutputFile instead.
addLog(log_type, message, stamp=True)
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, timestam=True)
Adds a warning message to the work item’s internal, in-process log.
If timestamp is True, the log message will be prefixed with the current timestamp.
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.
checkSubItem()
→ bool
Returns True if the work item is ready to cook, False if it’s not, and throws an exception if the item has a failed dependency. This method is only valid for work items that are part of a batch.
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.
clearExpectedOutputFiles()
Clears any expected output files from the work item.
clearExpectedOutputs()
This method is deprecated. Use pdg.WorkItem.clearExpectedOutputFiles instead.
clearOutputFiles()
Clears all output files on the work item.
clearResultData()
This method is deprecated. Use pdg.WorkItem.clearOutputFiles instead.
cookSubItem(state=pdg.workItemState.CookedSuccess, 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.
createJSONPatch(pretty_print=False)
→ str
Creates a JSON object that contains attributes and outputs that were added to the work item, for reporting outputs during an out of process cook. The JSON data is returned as a string.
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 output files 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.
firstOutputFileForTag(tag)
→ str
Returns the file path to the first output with the specified tag.
firstResultDataForTag(tag)
→ str
This method is deprecated. Use pdg.WorkItem.firstOutputFileForTag instead.
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.
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 .
inputFilesForTag(tag)
→ list
of pdg.File
Returns the list of input files that have the specified tag.
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.
localizePath(file_path)
→ str
Localizes an arbitrary file path using the scheduler associated with the work item.
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
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().
outputFilesForTag(tag)
→ list
of pdg.File
Returns the output file entries for a specified tag. The output files are returned as a pdg.File objects.
prepareDirty(should_delete)
→ pdg.WorkItemDirty
Prepars a dirty of the work item and its dependents, but does not apply the operation to the graph. Instead, the dirty operation is stored to a pdg.WorkItemDirty instance so that it can be applied to the graph at a later point.
removeEventHandler(handler)
Removes an event handler from the work item.
removeAllEventHandlers()
Removes all event handlers from the work item.
resultDataForTag(tag)
→ list
of pdg.File
This method is deprecated. Use pdg.WorkItem.outputFilesForTag instead.
saveArrayJSONFile(file_path, work_items, pretty_print=False, global_attributes=False)
→ bool
Static method
Saves the list of work item to a JSON file and returns True on success.
This method will atttempt to create intermediate directories in the file_path, if they don’t already exist. Failure to create directories, e.g. because of a permission issue or an inaccessible drive, will cause the method to return False immediately.
saveArrayJSONString(work_items, pretty_print=False, global_attributes=False)
→ str
Static method
Saves the list of work item to JSON and returns it as a string.
saveJSONFile(file_path, pretty_print=False, global_attributes=False)
→ bool
Saves the work item to a JSON file and returns True on success.
This method will atttempt to create intermediate directories in the file_path, if they don’t already exist. Failure to create directories, e.g. because of a permission issue or an inaccessible drive, will cause the method to return False immediately.
saveJSONString(pretty_print=False, global_attributes=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.
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.
setCustomState(custom_state)
Sets a custom state string on the work item, which will be displayed after the normal state in the work item attribute panel. Custom states are cleared any time the cook state of the work item changes, e.g. because it was dirtied or finished cooking.
setFrame(frame, step=1.0)
Sets the frame and optionally the frame step size for the work item.
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.
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 will also call pdg.BatchWorkItem.setActiveBatchIndex on the batch parent automatically, once the work item is ready to cook.
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().
transferFiles(update_cache=True)
→ 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.
If update_cache is True, then any file attributes with the pdg.attribFlag.InputFile will be checked when transfering files. Input file attributes will be added to a table on the containing Node and tracked during future cooks. If an input file is was modified between cooks, then the output cache of this work item will also be invalidated. If update_cache is False then the work item’s cache will not be invalidated, even if the file on disk was updated.
updateOutputFile(index, file, tag, checksum, own)
Updates the output file at the specified index.
updateResultData(index, file, tag, checksum, own)
This method is deprecated. Use pdg.WorkItem.updateOutputFile instead.
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.
context
: pdg.GraphContext
Property
The graph context with the work item is associated with.
cookType
: pdg.workItemCookType
Property
The work item’s cook type, which determines whether it runs in process or out of process.
cookDuration
: int
Property
If the the work item has cooked, then returns the cook duration performance stat for the work item.
customState
: str
Property
The custom state of the work item, set using pdg.WorkItem.setCustomState.
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.
expectedInputFiles
: list
of pdg.File
Property
The list of all inputs, including expected files. The inputs are stored as pdg.File objects.
expectedOutputFiles
: list
of pdg.File
Property
The list of expected output files for the work item. The files are stored as pdg.File objects.
expectedInputResultData
: list
of pdg.File
Property
This property is deprecated. Use pdg.WorkItem.expectedInputFiles instead.
expectedResultData
: list
of pdg.File
Property
This property is deprecated. Use pdg.WorkItem.expectedOutputFiles instead.
frame
: float
Property
The frame value associated with the work item.
frameStep
: float
Property
The frame step size associated with the work item.
graph
: pdg.Graph
Property
The graph the work item is associated with.
hasCustomState
: bool
Property
If the work item has a custom state, then this property is set to True. Otherwise the property will be False.
hasFrame
: bool
Property
If the work item has a frame, then this is set to True. Else False.
hasWarnings
: bool
Property
If the work item has at least one warning message in it’s internal log buffer, then this property 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.
inputFiles
: list
of pdg.File
Property
The list of input files for this work item. For example, the output files collected from all dependencies.
inputResultData
: list
of pdg.File
Property
This property is deprecated. Use pdg.WorkItem.inputFiles insead.
isBatch
: bool
Property
If the work items is a pdg.BatchWorkItem this propety is set to True. Else False.
isCooked
: bool
Property
Set to True if the work item is in a Cooked state, else False.
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. The cookType property on the work item returns a pdg.workItemCookType enum entry that describes exactly how the work item will cook.
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.
outputFiles
: list
of pdg.File
Property
The list of output files for the work item.
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
This property is deprecated. Use pdg.WorkItem.outputFiles instead.
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.
tempDir
: str
Property
The temporary file directory associated with the scheduler assigned to the node that owns this work item.
type
: pdg.workItemType
Property
The type object that constructed the work item.
Methods from pdg.AttributeOwner ¶
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 objectm 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 and this object is a work item, 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.
attrib(name)
→ pdg.AttributeFile or pdg.AttributeFloat or pdg.AttributeInt or pdg.AttributePyObject or pdg.AttributeString
Returns the 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 attrib_owner.attrib[name].
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 all of attribute values. This can be useful to identify objects between cooks.
The include_internal argument determines whether or not the hashing operation should include internal attributes defined by PDG itself, like item input/output files or the the command string.
If this is a work item, 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.
If this is a work item, 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.
attribMatch(pattern)
→ list
of str
Returns the list of attribute names from the that match the specified pdg.AttributePattern instance.
attribNames(type=pdg.attribType.Undefined)
→ list
of str
Returns the list of names for all attributes if type is set to pdg.attribType.Undefined, otherwise returns the list of attribute names 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 attrib_owner[name][index].
attribValues(type=pdg.attribType.Undefined)
→ dict
of list
of int
, float
, and str
Returns a map of all attribute names to values if type is set to pdg.attribType.Undefined, otherwise returns a map of names to values for all attributes of the specified type.
attribType(name)
→ pdg.attribType
Returns the type of attribute with the specified name, or pdg.attribType.Undefined if no attribute with that name exists.
clearAttribs()
Clears and deletes all attributes.
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.
hasAttrib(name)
→ bool
Returns True if this object has an attribute with the specified name.
intAttribArray(name)
→ list
of int
Returns the integer attribute array.
intAttribValue(name, index=0)
→ int
Returns the integer attribute value at the specified index.
loadAttributes(file_path, collision_strategy)
→ bool
Loads the attribute data from the specified JSON file into this object. The collision_strategy should be one of the enum values from pdg.attribCollisionStrategy.
lockAttributes()
→ pdg.LockAttributesBlock
Locks this attributes using a context manager. For the duration of the context manager, it is safe to modify attributes without worry about other threads modifying them.
For example:
with attrib_owner.lockAttributes(): attrib_owner.setIntAttrib("example", 10)
Note
You should not call this method on work items 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.
numAttribs(type=pdg.attribType.Undefined)
→ int
Returns the total number of attributes in the map if type is set to pdg.attribType.Undefined, otherwise returns the number of attributes of the specified type.
pyObjectAttribValue(name)
→ object
Returns the Python object stored on the specified attribute.
renameAttrib(src_name, dst_name, overwrite_existing=False)
→ bool
Renames the attribute with src_name to dst_name.
saveAttributes(file_path)
→ bool
Saves the attribute data stored on this object to the specified file path as JSON. If the file path ends in .gz the file will be compressed using GZip, otherwise the file is saved as plain text JSON.
setAttribFlag(name, flag, value=True)
Sets or clears the pdg.attribFlag on the specified attribute.
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.AttributeOwner.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.AttributeOwner.addAttrib for details.
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.AttributeOwner.addAttrib for details.
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.AttributeOwner.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.AttributeOwner.addAttrib for details.
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. This method is primarily used for work item that are in a batch with shared attributes on the batch parent.