| On this page | |
| Since | 17.5 |
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.
Tip
The $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.
Parameters ¶
Script ¶
Generate When
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.
Automatic
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.
Generate
Runs the script when the work item is generating.
Cook (In-Process)
Runs the script during the cook stage in the same process as the Houdini session.
Cook (Out-of-Process)
A scheduler runs the script out-of-process during the cook stage.
Cook (Service)
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
Always run work items on the block’s service, regardless of any other service settings on this node.
Match
Only run work items on the block’s service if Service Name matches the service name that’s used by the block.
Never
Never run work items on the block’s service.
Service Name
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.
Python Bin
Determines which Python executable to use to run the script.
Hython
Use hython to run the script.
PDG Python
Use PDG Python to run the script.
Custom
Use a custom Python executable to run the script.
Virtual Environment
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.
Venv Path
When Python Bin is set to Virtual Environment, this parameter specifies the path to the virtual environment to use when running the script.
Python Arguments
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.
Script Arguments
Specifies the arguments to pass to the Python script. These values are accessible in the script through sys.argv[1:].
Reset Python Path Variables
When on, resets the PYTHONHOME and 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.
Batch Type
Determines whether or not batching should be enabled, and what type of batch the node should create.
None
Work items in the node cook normally, and are not batched.
Fixed
A batch with a fixed size determined by the Batch Size parameter, is created each time this node generates tasks.
Dynamic
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.
Batch Size
When Batch Type is set to Fixed, this parameter determines the number of sub items in the batch.
Setup Script
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 PDG_DIR or PDG_TEMP.
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 intData, floatData, and 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 self and 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 None.
Caching and Output Files ¶
Cache Mode
Determines how the processor node handles work items that report expected file results.
Automatic
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.
Read Files
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.
Write Files
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
Never copy inputs files the output file list.
Always
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.
Attribute Name
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.
Expected Outputs
Determines the number of file list entries.
This parameter is only available when Expected Outputs From is set to File List.
Output File
Specifies the path to the file.
Schedulers ¶
TOP Scheduler Override
This parameter overrides the TOP scheduler for this node.
Schedule When
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.
Custom Expression
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.
Label Expression
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.
Custom Expression
The work item priority is set to the value of Priority Expression.
Node Defines Priority
The work item priority is set based on the node’s own internal priority calculations.
This option is only available on the Python Processor TOP, 
ROP Fetch TOP, and ROP Output TOP nodes. These nodes define their own prioritization schemes that are implemented in their node logic.
Priority Expression
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.
Examples ¶
CreateAttributes Example for Python Script TOP node
This example file demonstrates creates work item attributes using a Python Script node.
PythonScript Example for Python Script TOP node
This example demonstrates how the Python Script node can be used to run Python code in process or out of process.
| See also |
