|On this page
This node creates work items that run a Python script (in-process or as a scheduled job) during the work item generation phase. You can configure this behavior with the Evaluate Script During menu.
If the script is configured to run during the generation step, then the code is evaluated immediately after the work item is created. No additional work is done while the work item is cooking. You can use this mode to create attributes programmatically instead of using the Attribute Create node.
If you select one of the other evaluation modes, then the work item evaluates the script code when it cooks. In-process scripts can access a larger amount of information about the PDG graph as well as other objects and settings within the current Houdini session. If you run the script out-of-process, then the script is limited to accessing the attributes of the work item it is associated with and anything the script can import.
The node will always create exactly one work item per upstream item, with the contents of the Python Code field as the work to be done for that item. To generate a custom work item configuration, you should use the Python Processor node instead.
$HH/help/files/pdg_examples/top_pythonscript example shows how you can use this node to interact with both in-process and out-of-process work items.
Determines when this node will generate work items. You should generally leave this set to “Automatic” unless you know the node requires a specific generation mode, or that the work items need to be generated dynamically.
All Upstream Items are Generated
This node will generate work items once all of the input nodes have generated their work items.
All Upstream Items are Cooked
This node will generate work items once all of the input nodes have cooked their work items.
Each Upstream Item is Cooked
This node will generate work items each time a work item in an input node is cooked.
The generation mode is selected based on the generation mode of the input nodes. If any of the input nodes are generating work items when their inputs cook, this node will be set to Each Upstream Item is Cooked. Otherwise, it will be set to All Upstream Items are Generated.
Evaluate Script During
Determines when the script code stored on this node is evaluated.
Runs the script when the work item is generating.
Runs the script during the cook stage in the same process as the Houdini session.
A scheduler runs the script out-of-process during the cook stage.
A service runs the script during the cook stage.
Run on Service Block
Determines whether or not work items in this node should run on the parent service block, if one exists.
Always run work items on the block’s service, regardless of any other service settings on this node.
Only run work items on the block’s service if Service Name matches the service name that’s used by the block.
Never run work items on the block’s service.
When Cook Type is set to the Service, this parameter is used to specify the name of the service. For more information on using services, see the PDG Service Manager documentation.
The following parameters configure which Python executable to use to run the script code and what arguments to pass to the executable.
These parameters are only available when the node is configured to run out-of-process by the Cook (Out-of-Process) option in the Evaluate Script During menu.
Determines which Python executable to use to run the script.
hython to run the script.
Use PDG Python to run the script.
Use a custom Python executable to run the script.
Run the script on the Python interepter associated with a virtual environment.
Custom Python Bin
Determines the path to the Python executable.
This parameter is only available when Python Bin is set to Custom.
When Python Bin is set to Virtual Environment, this parameter specifies the path to the virtual environment to use when running the script.
Specifies the extra arguments to pass to the Python executable itself to configure the behavior of the interpreter.
By default, the node includes
-u as an argument for out-of-process Python tasks which disables standard output buffering.
Specifies the arguments to pass to the Python script. These values are accessible in the script through
Reset Python Path Variables
When on, resets the
PYTHONPATH variables that are defined by Houdini in the external Python process. This is necessary when using a Python version that is incompatible with the one that is built into Houdini.
Load as Native Work Item
By default, PDG loads work items as a
pdgjson.WorkItem object which mimics the in-process Python API using a thin Python wrapper around the work item’s JSON data. This type of work item can be loaded in any Python interpreter, not just a Houdini-based one. When cooking Out-of-Process using
hython as the interepter, however, you can enable this toggle to tell PDG to load a full in-process work item for the duration of the job.
Determines whether or not batching should be enabled, and what type of batch the node should create.
Work items in the node cook normally, and are not batched.
A batch with a fixed size determined by the Batch Size parameter, is created each time this node generates tasks.
A batch with an unspecified size is created each time this node generates tasks. The script code itself will determine how big the batch is, by adding sub items to the batch as the script executes.
Run Script Code
Determines whether the Python Code should be run once per sub item in the batch, with PDG managing the batch’s life time, or if the code manually manages the batch sub items.
When Batch Type is set to Fixed, this parameter determines the number of sub items in the batch.
When Run Script Code is set to Once per Sub Item, this parameter can be used to specify a block of Python code that runs once, before the batching itself begins processing.
Expand Variables in Script
By default, PDG evaluates the script parameter as a raw string. This means that any
$variables or expressions in back ticks are preserved and included as part of the script. When this parameter is turned on, PDG applies variable/expression expansion immediately when it evaluates the script. Variables or expressions enclosed in back ticks are replaced with their evaluated values in the final script.
Expand Variables in String Attributes
When on, PDG will expand
$variables in the string attributes when loading work items into the standalone Python process. Variable expansion includes any environment variable, as well as PDG-specific tokens like
This parameter is only available when Evaluate Script During is set to Cook (Out-of-Process).
The Python code that is run for each work item.
When running out-of-process, the Python interpreter specified by Python Bin or Custom Python Bin saves the code to disk and executes it. The script has access to the
work_item variable which provides an API to access the name, index, frame, and attributes of the work item associated with the script. Additionally, you can use the
strData helper functions to query attributes on the work item.
The script also has access to the
graph variable, which can be used to look up global attributes. For out-of-process work items the
graph object only has methods for querying attribute data, but for in-process work item the variable is set to the pdg.Graph that the work item belongs to.
When running in-process or during the generation stage, the Python interpreter embedded in Houdini runs the code. In addition to the
work_item variable, the
parent_item variables are also available. The
self variable is a reference to the node that owns the work item and the
parent_item variable is a reference to the parent or
Caching and Output Files
Determines how the processor node handles work items that report expected file results.
If the expected result file exists on disk, the work item is marked as cooked without being scheduled. If the file does not exist on disk, the work item is scheduled as normal. If upstream work item dependencies write out new files during a cook, the cache files on work items in this node will also be marked as out-of-date.
Automatic (Ignore Upstream)
The same as Automatic, except upstream file writes do not invalidate cache files on work items in this node and this node will only check output files for its own work items.
If the expected result file exists on disk, the work item is marked as cooked without being scheduled. Otherwise the work item is marked as failed.
Work items are always scheduled and the expected result file is ignored even if it exists on disk.
Copy Inputs to Outputs
Determines whether or not work items in this node should copy input files to their output file list.
Never copy inputs files the output file list.
Always copy inputs files the output file list.
If Script Doesn’t Add Outputs
By default, input files are only copied if the Python Script does not add any new output files on its own.
Expected Outputs From
Determines how expected output files should be specified.
Specifies the name of the attribute that contains the file paths(s).
This parameter is only available when Expected Outputs From is set to Attribute Name,
Custom File Tag
When on, the custom tag value will be assigned to all output files. Otherwise, PDG will use the existing tag for the file if one has been set, or pick one automatically based on the file extension if a tag does not exist.
Determines the number of file list entries.
This parameter is only available when Expected Outputs From is set to File List.
Specifies the path to the file.
TOP Scheduler Override
This parameter overrides the TOP scheduler for this node.
When enabled, this parameter can be used to specify an expression that determines which work items from the node should be scheduled. If the expression returns zero for a given work item, that work item will immediately be marked as cooked instead of being queued with a scheduler. If the expression returns a non-zero value, the work item is scheduled normally.
Work Item Label
Determines how the node should label its work items. This parameter allows you to assign non-unique label strings to your work items which are then used to identify the work items in the attribute panel, task bar, and scheduler job names.
Use Default Label
The work items in this node will use the default label from the TOP network, or have no label if the default is unset.
Inherit From Upstream Item
The work items inherit their labels from their parent work items.
The work item label is set to the Label Expression custom expression which is evaluated for each item.
Node Defines Label
The work item label is defined in the node’s internal logic.
When on, this parameter specifies a custom label for work items created by this node. The parameter can be an expression that includes references to work item attributes or built-in properties. For example,
$OS: @pdg_frame will set the label of each work item based on its frame value.
Work Item Priority
This parameter determines how the current scheduler prioritizes the work items in this node.
Inherit From Upstream Item
The work items inherit their priority from their parent items. If a work item has no parent, its priority is set to 0.
The work item priority is set to the value of Priority Expression.
Node Defines Priority
This parameter specifies an expression for work item priority. The expression is evaluated for each work item in the node.
This parameter is only available when Work Item Priority is set to Custom Expression.
This example file demonstrates creates work item attributes using a Python Script node.