Houdini 20.5 Nodes TOP nodes

Python Script TOP node

Creates work items that run a Python script.

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.

Python Executable

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.

Batching

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.

Variable Expansion

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).

Python Code

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

TOP nodes