nk2dl package

Nuke to Deadline Submitter - Core Library

A pure Python library for submitting nukescripts to Thinkbox Deadline.

nk2dl.submit_nuke_script(script_path, **kwargs)

Submit a Nuke script to Deadline render farm.

This is the primary entry point for the nk2dl package. It handles parsing the script, configuring job parameters, and submitting to Deadline.

Parameters:

• script_path (str) – Path to the Nuke script file (.nk)

• **kwargs – Submission parameters

• list (# For full parameter)

• documentation (see the NukeSubmission class)

Returns:

List of dictionaries containing job information:

• job_id (str): The Deadline job ID

• render_order (int): The render order value

• plugin_info (dict): Plugin info used for submission

• job_info (dict): Job info used for submission

• deadline_return (dict): Raw return data from Deadline

Return type:

list

Examples

Basic usage:

from nk2dl import submit_nuke_script
submit_nuke_script("path/to/script.nk")

With specific write nodes:

submit_nuke_script("path/to/script.nk", write_nodes=["Write1", "Write2"])

With job parameters:

submit_nuke_script(
    "path/to/script.nk",
    priority=80,
    pool="nuke",
    chunk_size=10,
    comment="Render {script} on farm"
)

Submit as a Python script job (ScriptJob in Deadline):

submit_nuke_script(
    "path/to/script.nk",
    submission_as_script_job=True
)

Raises:

NK2DLError – For configuration or submission errors

Submodules

nk2dl.config module

Configuration system for nk2dl.

This module handles loading, validating and accessing configuration settings from YAML files and environment variables.

exception nk2dl.config.ConfigError

Bases: Exception

Base exception for configuration related errors.

class nk2dl.config.Config(project_config: str | None = None, user_config: str | None = None)

Bases: object

Configuration manager for nk2dl.

Handles loading and accessing configuration from YAML files and environment variables. Configuration is loaded in the following order (later sources override earlier ones): 1. Default configuration 2. Project configuration file (from NK2DL_CONFIG or config.yaml in nk2dl module root) 3. Environment variables (NK2DL_*) 4. User configuration file (~/.nuke/nk2dl/config.yaml)

USER_CONFIG_PATH = PosixPath('/home/runner/.nuke/nk2dl/config.yaml')

nk2dl = <module 'nk2dl' from '/home/runner/work/nk2dl/nk2dl/src/nk2dl/__init__.py'>

MODULE_DIR = PosixPath('/home/runner/work/nk2dl/nk2dl/src/nk2dl')

GLOBAL_CONFIG_PATH = PosixPath('/home/runner/work/nk2dl/nk2dl/src/nk2dl/config.yaml')

PROJECT_CONFIG_PATH = PosixPath('/home/runner/work/nk2dl/nk2dl/src/nk2dl/config.yaml')

SPECIAL_ENV_VARS = {'NK2DL_CONFIG'}

DEFAULT_CONFIG = {'deadline': {'command_path': None, 'commandline_on_fail': True, 'host': 'localhost', 'port': 8081, 'repository_path': None, 'ssl': False, 'ssl_cert': None, 'timeout': 1, 'use_web_service': False}, 'logging': {'call_level': 'INFO', 'file': None, 'format': '%(asctime)s - %(name)s - %(levelname)s - %(message)s', 'level': 'INFO', 'qt_level': 'INFO'}, 'panel': {}, 'submission': {'batch_mode': True, 'batch_name_template': '{nukescript}', 'build_job_as_auxiliary_file': True, 'build_job_name': None, 'build_job_name_template': '{buildjob} >> {nukescript}', 'build_job_script_path': None, 'chunk_size': 10, 'comment_template': '', 'concurrent_tasks': 1, 'continue_on_error': False, 'copy_script': False, 'copy_script_path': None, 'custom_write_classes': [], 'delete_build_job_script': True, 'department': '', 'enable_auto_timeout': False, 'enforce_render_order': True, 'environment': {}, 'environment_keys': [], 'extra_info': None, 'gpu_override': '', 'group': 'none', 'job_dependencies': None, 'job_name_template': '{batch} / {write} / {file}', 'limit_groups': '', 'limit_worker_tasks': False, 'machine_allow_list': None, 'machine_deny_list': None, 'machine_limit': None, 'omit_environment_keys': [], 'on_job_complete': None, 'performance_profiler': False, 'performance_profiler_path': '', 'pool': 'nuke', 'post_build_job_script': None, 'post_job_script': None, 'post_task_script': None, 'pre_build_job_script': None, 'pre_job_script': None, 'pre_task_script': None, 'priority': 50, 'ram_use': 0, 'reload_plugins': False, 'render_mode': 'full', 'render_order_dependencies': False, 'render_settings_from_metadata': False, 'script_copy_path': '{outdir}/.farm/{nkstem}.nk', 'script_job_script_path': None, 'stack_size': 0, 'submission_is_build_job': False, 'submit_copied_script': False, 'submit_script_as_auxiliary_file': False, 'submit_suspended': False, 'submit_writes_alphabetically': False, 'submit_writes_in_render_order': False, 'threads': 0, 'use_current_environment': False, 'use_gpu': False, 'use_node_frame_list': False, 'use_nuke_x': False, 'use_proxy': False, 'write_nodes_as_separate_jobs': False, 'write_nodes_as_tasks': False}}

__init__(project_config: str | None = None, user_config: str | None = None)

Initialize configuration.

Parameters:

• project_config – Optional path to project configuration file

• user_config – Optional path to user configuration file

load_config() → None

Load configuration from all sources.

get(key: str, default: Any = None) → Any

Get a configuration value by key.

Parameters:

• key – Dot-separated configuration key (e.g. ‘deadline.host’)

• default – Default value if key doesn’t exist

Returns:

Configuration value or default

trigger_debug_if_enabled() → None

Trigger debug output if DEBUG level is configured and hasn’t been shown yet.

debug_config_info() → None

Log detailed configuration debugging information to help troubleshoot config issues.

nk2dl.config.debug_config(force: bool = False) → None

Convenience function to log configuration debugging information.

Outputs detailed configuration information using the logger at DEBUG level.

Parameters:

force – If True, show debug info even if already shown once

Usage:

from nk2dl.config import debug_config debug_config() # Show once debug_config(force=True) # Force show again

nk2dl.connection module

Deadline connection handling.

This module provides a unified interface for connecting to Deadline using either the Web Service API or command-line interface.

class nk2dl.connection.Colors

Bases: object

RED = '\x1b[91m'

GREEN = '\x1b[92m'

YELLOW = '\x1b[93m'

BLUE = '\x1b[94m'

MAGENTA = '\x1b[95m'

CYAN = '\x1b[96m'

RESET = '\x1b[0m'

nk2dl.connection.colored_text(text: str, color_code: str) → str

Add color to text for terminal output.

Parameters:

• text – Text to colorize

• color_code – ANSI color code

Returns:

Colorized text string

class nk2dl.connection.DeadlineConnection

Bases: object

Manages connection to Deadline.

Provides a unified interface regardless of whether using Web Service or command-line interface.

__init__()

Initialize connection based on configuration.

ensure_connected()

Ensure connection is initialized.

get_groups() → List[str]

Get list of Deadline groups.

Returns:

List of group names

get_pools() → List[str]

Get list of Deadline pools.

Returns:

List of pool names

submit_job(job_info: Dict[str, Any], plugin_info: Dict[str, Any], auxiliary_files: List[str] | None = None) → Dict[str, Any]

Submit a job to Deadline.

Parameters:

• job_info – Job information dictionary

• plugin_info – Plugin-specific information dictionary

• auxiliary_files – Optional list of auxiliary files to include with the job

Returns:

• job_id: The Deadline job ID

• raw_response: The raw response from Deadline

• connection_type: Either ‘web’ or ‘command_line’

Return type:

Dictionary containing

Raises:

DeadlineError – If job submission fails

nk2dl.connection.get_connection() → DeadlineConnection

Get the global connection instance, creating it if needed.

nk2dl.errors module

Error handling for nk2dl.

This module defines custom exceptions and error handling utilities.

exception nk2dl.errors.NK2DLError

Bases: Exception

Base exception for all nk2dl errors.

exception nk2dl.errors.ConfigError

Bases: NK2DLError

Configuration related errors.

exception nk2dl.errors.ValidationError

Bases: NK2DLError

Validation related errors.

exception nk2dl.errors.DeadlineError

Bases: NK2DLError

Deadline connection/communication errors.

exception nk2dl.errors.SubmissionError

Bases: NK2DLError

Job submission related errors.

exception nk2dl.errors.NukeError

Bases: NK2DLError

Nuke script/execution related errors.

exception nk2dl.errors.ParserError

Bases: NK2DLError

Parser related errors when parsing Nuke scripts without using Nuke.

nk2dl.errors.handle_error(error: Exception, logger=None) → None

Handle an error by logging it and optionally performing additional actions.

Parameters:

• error – The exception to handle

• logger – Optional logger instance to use

nk2dl.framerange module

class nk2dl.framerange.FrameRange(frame_range_str: str = '')

Bases: object

Class for validating and processing frame range strings with token substitution.

Supports syntax like: - 1-10 (simple range) - 1,3,9 (comma separated list) - 1-90x3 or 1-90/3 (stepped range with x or / syntax) - 9,50,100-200 (mixed comma list and range) - 9-18x2,100 (mixed stepped range and single frames)

Tokens that can be substituted: - f or first = first_frame - m or middle = middle_frame (the average of first and last frame) - l or last = last_frame - i or input = frame range from input of a write node - h or hero = hero_frames (comma separated list of frames)

Usage:

# Create a frame range object fr = FrameRange(“1-10,20,30-40x2”)

# Validate syntax if fr.is_valid_syntax():

# Get expanded list of frames frames = fr.expand_range()

# With token substitution from Nuke fr = FrameRange(“f-l”) fr.substitute_tokens_from_nuke() frames = fr.expand_range()

# With token substitution from a Nuke script file fr = FrameRange(“f,hero”) with open(“my_script.nk”, “r”) as f:

script_content = f.read()

fr.substitute_tokens_from_script(script_content) frames = fr.expand_range()

RANGE_PATTERN = '(\\d+|\\w+)-(\\d+|\\w+)(?:x(\\d+)|/(\\d+))?'

SINGLE_PATTERN = '(\\d+|\\w+)'

FRAME_RANGE_PATTERN = '^((\\d+|\\w+)-(\\d+|\\w+)(?:x(\\d+)|/(\\d+))?|(\\d+|\\w+))(?:,((\\d+|\\w+)-(\\d+|\\w+)(?:x(\\d+)|/(\\d+))?|(\\d+|\\w+)))*$'

TOKEN_PATTERN = '(f|first|m|middle|l|last|i|input|h|hero)\\b'

__init__(frame_range_str: str = '')

Initialize with a frame range string.

Parameters:

frame_range_str – A string representing a frame range

is_valid_syntax() → bool

Check if the frame range string has valid syntax.

Returns:

True if syntax is valid, False otherwise

Return type:

bool

static normalize_hero_frames(hero_frames: str) → str

Normalize hero frames string to comma-separated format without extra spaces. Handles various delimiters (commas, spaces, or mixed).

Parameters:

hero_frames – Hero frames string in any format

Returns:

Normalized comma-separated hero frames

Return type:

str

substitute_tokens(first_frame: int | float | None = None, last_frame: int | float | None = None, hero_frames: str | None = None, input_first_frame: int | None = None, input_last_frame: int | None = None) → str

Substitute tokens in the frame range string with actual values. Only performs substitution if tokens are present.

Parameters:

• first_frame – Value to substitute for ‘f/first’ token

• last_frame – Value to substitute for ‘l/last’ token

• hero_frames – Value to substitute for ‘h/hero’ token

• input_first_frame – Value to substitute for ‘i/input’ token (start frame)

• input_last_frame – Value to substitute for ‘i/input’ token (end frame)

Returns:

Frame range string with tokens substituted

Return type:

str

substitute_tokens_from_nuke(write_node_name: str | None = None) → str

Substitute tokens using values from Nuke environment. Only performs substitution if tokens are present.

Parameters:

write_node_name – Optional name of a write node to get input frame range from

Returns:

Frame range string with tokens substituted

Return type:

str

Raises:

ImportError – If not running in a Nuke environment

substitute_tokens_from_script(script_content: str) → str

Substitute tokens using values extracted from a Nuke script file content. Only performs substitution if tokens are present.

Parameters:

script_content – Content of the Nuke script file

Returns:

Frame range string with tokens substituted

Return type:

str

expand_range() → List[int]

Expand the processed frame range string into a list of frame numbers.

Returns:

List of frame numbers specified by the range

Return type:

List[int]

Raises:

ValueError – If the frame range syntax is invalid or token substitution is needed

__str__() → str

String representation of the frame range.

nk2dl.info module

Version/author information

nk2dl.logging module

Centralized logging configuration for nk2dl.

This module provides logging setup and configuration management, ensuring consistent formatting across all nk2dl modules.

class nk2dl.logging.Nk2dlLogger(name, level=0)

Bases: Logger

Custom logger that automatically adds caller information to DEBUG messages.

debug(message, *args, **kwargs)

Override debug to automatically add caller information when level is at or below configured threshold.

nk2dl.logging.disable_caller_info()

Temporarily disable caller information for debug messages.

nk2dl.logging.enable_caller_info()

Re-enable caller information for debug messages.

nk2dl.logging.get_nk2dl_logger(name: str) → Nk2dlLogger

Get a logger with the custom Nk2dlLogger class, ensuring it’s properly configured.

nk2dl.logging.log_session_start()

Log the session start date if in DEBUG mode and not already logged.

nk2dl.logging.setup_logging(name: str) → Nk2dlLogger

Set up logging configuration for nk2dl modules.

Parameters:

name – The logger name (typically __name__)

Returns:

Configured logger instance

nk2dl.logging.fix_existing_loggers() → None

Fix any existing nk2dl loggers to use consistent formatting.

nk2dl.logging.configure_logging(level: str = None, qt_level=None, call_level=None) → None

Configure logging level dynamically.

Parameters:

• level – Logging level to set (INFO, DEBUG, NOTSET)

• qt_level – Level for Qt debug messages - string (DEBUG, INFO, etc.) or numeric (None to keep current)

• call_level – Level for caller information - string (DEBUG, INFO, etc.) or numeric (None to keep current)

nk2dl.nuke_utils module

Utility functions for working with Nuke.

This module provides utility functions for working with Nuke, including functions to get the Nuke module, get node file paths, and get Nuke version.

nk2dl.nuke_utils.nuke_module()

Get the nuke module, importing it if necessary.

Returns:

The nuke module.

Raises:

SubmissionError – If nuke module is not available.

nk2dl.nuke_utils.parser_module()

Get the parser module, creating it if necessary.

This module is intended to provide a lightweight alternative to the real Nuke module for parsing Nuke scripts without loading Nuke itself.

Returns:

A parser instance that mimics the nuke module interface.

Raises:

SubmissionError – If the parser module is not available or functionality is incomplete.

nk2dl.nuke_utils.node_pretty_path(node) → str

Get a node’s file path while preserving frame number placeholders.

When Nuke evaluates a file path with node[‘file’].evaluate(), it replaces frame number placeholders (e.g., ‘####’, ‘%04d’) with the actual frame number. This function evaluates the path but restores those placeholders.

Parameters:

node – A Nuke node with a ‘file’ knob

Returns:

The evaluated file path with frame number placeholders preserved

nk2dl.nuke_utils.nuke_version(nuke_version: str | int | float | None = None) → str

Get the Nuke version to use for rendering.

Uses the following priority: 1. The nuke_version parameter provided 2. The nuke_version value from config 3. The current Nuke version

Parameters:

nuke_version – Optional Nuke version to use. Can be string, int, or float.

Returns:

Version string in format “MAJOR.MINOR” (e.g. “13.0”)

nk2dl.parser module

Parser for Nuke script files.

This module provides functionality for parsing Nuke script files without requiring the Nuke application. It implements a subset of the Nuke Python API that’s necessary for working with submission tasks.

class nk2dl.parser.NukeKnob(name: str, value: Any)

Bases: object

Class representing a Nuke knob.

__init__(name: str, value: Any)

value()

Get the value of the knob.

evaluate()

Evaluate the value of the knob.

In the actual Nuke API, this would evaluate expressions and return the result. In our implementation, this just returns the value.

class nk2dl.parser.GSVKnob(name: str, values: Dict[str, Any])

Bases: NukeKnob

Class representing a Graph Scope Variables knob.

__init__(name: str, values: Dict[str, Any])

getListOptions(key: str) → List[str]

Get the list of available values for a GSV key.

getGsvValue(var_name: str) → str

Get the value of a GSV variable.

setGsvValue(path: str, value: str) → None

Set the value of a GSV variable at the specified path.

class nk2dl.parser.NukeNode(name: str, node_type: str)

Bases: object

Class representing a node in a Nuke script.

__init__(name: str, node_type: str)

name() → str

Get the name of the node.

Class() → str

Get the class (type) of the node.

knobs() → Dict[str, NukeKnob]

Get all knobs of the node.

__getitem__(key)

Get a knob by name.

firstFrame() → int

Get the first frame of the node’s input.

Raises:

NotImplementedError – This method is not yet implemented.

lastFrame() → int

Get the last frame of the node’s input.

Raises:

NotImplementedError – This method is not yet implemented.

class nk2dl.parser.RootNode

Bases: NukeNode

Class representing the root node of a Nuke script.

__init__()

class nk2dl.parser.WriteNode(name: str)

Bases: NukeNode

Class representing a Write node in a Nuke script.

__init__(name: str)

class nk2dl.parser.NukeParser

Bases: object

Parser for Nuke script files.

__init__()

scriptOpen(filepath: str) → None

Open and parse a Nuke script file.

Parameters:

filepath – Path to the Nuke script file

Raises:

ParserError – If the file cannot be opened or parsed

root() → RootNode

Get the root node of the script.

toNode(name: str) → NukeNode | None

Get a node by name.

Parameters:

name – Name of the node

Returns:

The node if found, None otherwise

allNodes(node_type: str | None = None) → List[NukeNode]

Get all nodes of a specific type.

Parameters:

node_type – Type of nodes to get (e.g., ‘Write’). If None, get all nodes.

Returns:

List of nodes

nk2dl.parser.create_parser() → NukeParser

Create a new NukeParser instance.

Returns:

A new NukeParser instance

nk2dl.submission module

Nuke script submission to Deadline.

This module provides functionality for submitting Nuke scripts to Deadline render farm.

class nk2dl.submission.WriteNode(write_node_input=None)

Bases: object

Handles configuration for a single write node with optional overrides.

This class provides a flexible way to specify write nodes with optional overrides for both job info and plugin info parameters in Deadline submissions.

Supports the following input formats: - Single string: The name of a write node - Dictionary: Write node name as ‘write_node’ key with overrides for submission

The dictionary can contain both direct Deadline job/plugin info keys or nk2dl submission variables that will be translated to the appropriate Deadline keys.

Examples

# Simple write node name WriteNode(‘Write1’)

# Write node with direct Deadline parameter overrides WriteNode({

‘write_node’: ‘Write1’, ‘Priority’: 90, # Direct Deadline job info parameter ‘ChunkSize’: 5, # Direct Deadline job info parameter ‘UseGpu’: ‘1’, # Direct Deadline plugin info parameter ‘RamUse’: ‘16000’ # Direct Deadline plugin info parameter

})

# Write node with nk2dl parameter name overrides (automatically translated) WriteNode({

‘write_node’: ‘Write1’, ‘priority’: 90, # Translated to ‘Priority’ ‘chunk_size’: 5, # Translated to ‘ChunkSize’ ‘use_gpu’: True, # Translated to ‘UseGpu’: ‘1’ ‘ram_use’: 16000 # Translated to ‘RamUse’: ‘16000’

})

# Mixed direct and translated parameters WriteNode({

‘write_node’: ‘Write1’, ‘priority’: 90, # Translated parameter ‘ChunkSize’: 5, # Direct parameter ‘use_gpu’: True, # Translated parameter ‘RamUse’: ‘16000’ # Direct parameter

})

This class handles automatic translation between nk2dl parameters and Deadline job/plugin info keys, type conversions (e.g. boolean to “0”/”1”), and separation of job info vs. plugin info parameters.

NK2DL_TO_DEADLINE = {'batch_mode': 'BatchMode', 'batch_name': 'BatchName', 'chunk_size': 'ChunkSize', 'comment': 'Comment', 'concurrent_tasks': 'ConcurrentTasks', 'continue_on_error': 'ContinueOnError', 'department': 'Department', 'enable_auto_timeout': 'EnableAutoTimeout', 'enforce_render_order': 'EnforceRenderOrder', 'frames': 'Frames', 'gpu_override': 'GpuOverride', 'group': 'Group', 'job_dependencies': 'JobDependency0', 'limit_groups': 'LimitGroups', 'limit_worker_tasks': 'LimitConcurrentTasks', 'nuke_version': 'Version', 'on_job_complete': 'OnJobComplete', 'output_file_path': 'OutputFilePath', 'performance_profiler': 'PerformanceProfiler', 'performance_profiler_path': 'PerformanceProfilerDir', 'pool': 'Pool', 'post_job_script': 'PostJobScript', 'post_task_script': 'PostTaskScript', 'pre_job_script': 'PreJobScript', 'pre_task_script': 'PreTaskScript', 'priority': 'Priority', 'ram_use': 'RamUse', 'reload_plugins': 'ReloadPlugins', 'render_mode': 'RenderMode', 'stack_size': 'StackSize', 'submit_suspended': 'InitialStatus', 'task_timeout': 'TaskTimeoutSeconds', 'threads': 'Threads', 'use_gpu': 'UseGpu', 'use_nuke_x': 'UseNukeX', 'user_name': 'UserName', 'views': 'Views'}

BOOLEAN_PARAMS = {'batch_mode', 'continue_on_error', 'enforce_render_order', 'performance_profiler', 'reload_plugins', 'use_gpu', 'use_nuke_x'}

PLUGIN_INFO_KEYS = {'BatchMode', 'BatchModeIsMovie', 'ContinueOnError', 'EnforceRenderOrder', 'GpuOverride', 'GraphScopeVariables', 'GraphScopeVariablesEnabled', 'OutputFilePath', 'PerformanceProfiler', 'PerformanceProfilerDir', 'RamUse', 'ReloadPlugins', 'RenderMode', 'SceneFile', 'ScriptFilename', 'ScriptJob', 'StackSize', 'Threads', 'UseGpu', 'UseNukeX', 'Version', 'Views', 'WriteNode', 'WriteNodesAsSeparateJobs'}

PLUGIN_INFO_KEY_PREFIXES = {'WriteNode'}

__init__(write_node_input=None)

Initialize from various input formats.

Parameters:

write_node_input – Flexible input format for write node(s)

class nk2dl.submission.WriteNodes(input_value=None)

Bases: object

Collection of WriteNode objects with utility methods.

This class manages a collection of WriteNode objects and provides methods to access their properties and overrides. It supports multiple input formats to make it flexible for various use cases.

Examples

# Single write node as string write_nodes = WriteNodes(“Write1”)

# Multiple write nodes as list of strings write_nodes = WriteNodes([“Write1”, “Write2”, “Write3”])

# Single write node with overrides write_nodes = WriteNodes({

‘write_node’: ‘Write1’, ‘priority’: 90, ‘use_gpu’: True

})

# Multiple write nodes with individual overrides write_nodes = WriteNodes([

{

‘write_node’: ‘Write1’, ‘priority’: 90, ‘chunk_size’: 5

}, {

‘write_node’: ‘Write2’, ‘priority’: 80, ‘use_gpu’: True

}, “Write3” # Mix of dict and string formats is supported

])

The class provides methods to get write node names and retrieve overrides for specific write nodes when submitting to Deadline.

__init__(input_value=None)

get_names()

Get list of all write node names.

get_overrides(write_node_name)

Get overrides for a specific write node.

get_job_info_overrides(write_node_name)

Get job info overrides for a specific write node.

get_plugin_info_overrides(write_node_name)

Get plugin info overrides for a specific write node.

__bool__()

Return True if there are any nodes defined.

__len__()

Return the number of nodes.

class nk2dl.submission.NukeSubmission(script_path: str, script_is_open: bool = False, use_parser_instead_of_nuke: bool = False, submit_writes_alphabetically: bool = False, submit_writes_in_render_order: bool = False, submit_script_as_auxiliary_file: bool | None = None, render_settings_from_metadata: bool = False, submission_is_build_job: bool = False, build_job_name: str | None = None, build_job_script_path: str | None = None, pre_build_job_script: str | List[str] | None = None, post_build_job_script: str | List[str] | None = None, build_job_as_auxiliary_file: bool | None = None, delete_build_job_script: bool | None = None, copy_script: bool | None = None, copy_script_path: str | List[str] | Dict[int, str] | None = None, submit_copied_script: bool | None = None, script_job_script_path: str | None = None, machine_list: List[str] | None = None, machine_list_is_a_deny_list: bool | None = None, machine_allow_list: List[str] | None = None, machine_deny_list: List[str] | None = None, machine_limit: int | None = None, job_name: str | None = None, batch_name: str | None = None, priority: int | None = None, pool: str | None = None, group: str | None = None, chunk_size: int | None = None, department: str | None = None, user_name: str | None = None, comment: str | None = None, concurrent_tasks: int | None = None, extra_info: List[str] | None = None, frames: str = '', job_dependencies: str | None = None, on_job_complete: str | None = None, submit_suspended: bool = False, limit_groups: str | None = None, task_timeout: int | None = None, enable_auto_timeout: bool = False, limit_worker_tasks: bool = False, pre_job_script: str | None = None, post_job_script: str | None = None, pre_task_script: str | None = None, post_task_script: str | None = None, output_file_path: str = '', parse_output_paths_to_deadline: bool = False, nuke_version: str | int | float | None = None, use_nuke_x: bool = False, batch_mode: bool = True, threads: int | None = None, use_gpu: bool = False, gpu_override: str | None = None, ram_use: int | None = None, enforce_render_order: bool = True, stack_size: int | None = None, continue_on_error: bool = False, reload_plugins: bool = False, performance_profiler: bool = False, performance_profiler_path: str | None = None, write_nodes: str | List[str] | Dict[str, Any] | List[Dict[str, Any]] | None = None, render_mode: str = 'full', write_nodes_as_tasks: bool = False, write_nodes_as_separate_jobs: bool = False, render_order_dependencies: bool = False, use_node_frame_list: bool = False, views: List[str] | None = None, proxy_args: Dict[str, Any] | None = None, graph_scope_variables: List[str] | List[List[str]] | None = None, use_current_environment: bool = False, environment_keys: List[str] | None = None, environment: Dict[str, str] | None = None, omit_environment_keys: List[str] | None = None)

Bases: object

Handles submission of Nuke scripts to Deadline.

__init__(script_path: str, script_is_open: bool = False, use_parser_instead_of_nuke: bool = False, submit_writes_alphabetically: bool = False, submit_writes_in_render_order: bool = False, submit_script_as_auxiliary_file: bool | None = None, render_settings_from_metadata: bool = False, submission_is_build_job: bool = False, build_job_name: str | None = None, build_job_script_path: str | None = None, pre_build_job_script: str | List[str] | None = None, post_build_job_script: str | List[str] | None = None, build_job_as_auxiliary_file: bool | None = None, delete_build_job_script: bool | None = None, copy_script: bool | None = None, copy_script_path: str | List[str] | Dict[int, str] | None = None, submit_copied_script: bool | None = None, script_job_script_path: str | None = None, machine_list: List[str] | None = None, machine_list_is_a_deny_list: bool | None = None, machine_allow_list: List[str] | None = None, machine_deny_list: List[str] | None = None, machine_limit: int | None = None, job_name: str | None = None, batch_name: str | None = None, priority: int | None = None, pool: str | None = None, group: str | None = None, chunk_size: int | None = None, department: str | None = None, user_name: str | None = None, comment: str | None = None, concurrent_tasks: int | None = None, extra_info: List[str] | None = None, frames: str = '', job_dependencies: str | None = None, on_job_complete: str | None = None, submit_suspended: bool = False, limit_groups: str | None = None, task_timeout: int | None = None, enable_auto_timeout: bool = False, limit_worker_tasks: bool = False, pre_job_script: str | None = None, post_job_script: str | None = None, pre_task_script: str | None = None, post_task_script: str | None = None, output_file_path: str = '', parse_output_paths_to_deadline: bool = False, nuke_version: str | int | float | None = None, use_nuke_x: bool = False, batch_mode: bool = True, threads: int | None = None, use_gpu: bool = False, gpu_override: str | None = None, ram_use: int | None = None, enforce_render_order: bool = True, stack_size: int | None = None, continue_on_error: bool = False, reload_plugins: bool = False, performance_profiler: bool = False, performance_profiler_path: str | None = None, write_nodes: str | List[str] | Dict[str, Any] | List[Dict[str, Any]] | None = None, render_mode: str = 'full', write_nodes_as_tasks: bool = False, write_nodes_as_separate_jobs: bool = False, render_order_dependencies: bool = False, use_node_frame_list: bool = False, views: List[str] | None = None, proxy_args: Dict[str, Any] | None = None, graph_scope_variables: List[str] | List[List[str]] | None = None, use_current_environment: bool = False, environment_keys: List[str] | None = None, environment: Dict[str, str] | None = None, omit_environment_keys: List[str] | None = None)

Initialize a Nuke script submission.

Parameters:

• parameters (# Environment Variables)

• script_path – Path to the Nuke script file

• script_is_open – Whether this script path is already open in the current Nuke session (can also be also true if submitted script mirrors current Nuke session)

• use_parser_instead_of_nuke – Whether to use a parser instead of Nuke for parsing script

• submit_writes_alphabetically – Whether to sort write nodes alphabetically by name

• submit_writes_in_render_order – Whether to sort write nodes by render order

• submit_script_as_auxiliary_file – Whether to submit the script as an auxiliary file

• render_settings_from_metadata – Whether to extract submission settings from write node metadata. Metadata keys starting with ‘input/nk2dl/’ will be used as submission settings. For example, ‘input/nk2dl/priority’ will set the job priority. This is useful for pipeline integrations where artists can set job parameters directly in their Nuke scripts. Only works when write_nodes_as_separate_jobs is True.

• parameters

• submission_is_build_job – Whether to submit as a Python script job that calls submit_nuke_script. A build job script is generated at submission. WARNING: setting submission_is_build_job=True as the default will result in infinite job submissions.

• build_job_script_path – Full path template for the build job script file. Contains both directory and filename with tokens. Supports tokens for both directory and filename parts: - Script directory tokens: {sdir}, {nkdir}, {scriptdir}, {nukescriptdir} - Script stem tokens: {ss}, {basename}, {stem}, {sstem}, {scriptstem} - Script name tokens: {s}, {script}, {scriptname} - Date tokens: {YYYY}, {YY}, {MM}, {DD}, {hh}, {mm}, {ss} Example: “{scriptdir}/build_jobs/{stem}_{YYYY}-{MM}-{DD}.py”

• pre_build_job_script – Path to a script to run before the build job starts, or list [script_path, arg1, arg2, …] where the first item is the script path and remaining items are arguments. Script runs within the generated build job script.

• post_build_job_script – Path to a script to run after the build job completes, or list [script_path, arg1, arg2, …] where the first item is the script path and remaining items are arguments. Script runs within the generated build job script and receives the submission results.

• build_job_as_auxiliary_file – Whether to submit the build job script as an auxiliary file (default: True)

• delete_build_job_script – Whether to delete the build job script after successful submission (default: True)

• parameters

• copy_script – Whether to copy the script before submission

• copy_script_path – Optional file path template(s) for copying the script (includes both directory and filename). Can be: - String: Single file path template (e.g., “{outdir}/.farm/{scriptname}”) - List: Multiple file path templates - Dict: With integer keys for multiple file path templates Supports tokens: {script}, {output}, {basename}, {YYYY}, {MM}, {DD}, etc.

• submit_copied_script – Whether to submit the copied script

• submit_script_as_auxiliary_file – Whether to submit the script as an auxiliary file

• render_settings_from_metadata – Whether to extract submission settings from write node metadata. Metadata keys starting with ‘input/nk2dl/’ will be used as submission settings. For example, ‘input/nk2dl/priority’ will set the job priority. This is useful for pipeline integrations where artists can set job parameters directly in their Nuke scripts. Only works when write_nodes_as_separate_jobs is True.

• parameters

• script_job_script_path – Path to a Python script to submit as a script job. When specified, sets ScriptJob=True and ScriptFilename to the provided path. ScriptJob is built in functionality of the Deadline Nuke plugin. It runs the script as a Python script job in the nuke script editor as a terminal session but cannot take any arguments. Consider using the build job parameters instead as the build job script can use pre and post build job scripts to run the python scripts with arguments.

• parameters

• machine_list – List of machine names to allow or deny

• machine_list_is_a_deny_list – Whether the machine list is a deny list

• machine_allow_list – List of machine names to allow

• machine_deny_list – List of machine names to deny

• machine_limit – Maximum number of machines to use

• parameters

• job_name – Job name template (defaults to config value)

• batch_name – Batch name template (defaults to config value)

• priority – Job priority (defaults to config value)

• pool – Worker pool (defaults to config value)

• group – Worker group (defaults to config value)

• chunk_size – Number of frames per task (defaults to config value)

• department – Department (defaults to config value)

• user_name – User name (defaults to config value)

• comment – Job comment (defaults to config value) Can include tokens like {script}, {ss}, {write}, {file}, etc.

• concurrent_tasks – Number of parallel tasks for the job (defaults to 1)

• extra_info – List of extra info fields with optional tokens for customization Each item supports the same tokens as job_name

• frames – Frame range to render (defaults to Nuke script settings)

• job_dependencies – Comma or space separated list of job IDs

• on_job_complete – Optional job completion script

• submit_suspended – Whether to submit the job suspended

• limit_groups – Optional comma-separated list of group names to limit

• task_timeout – Optional task timeout in seconds

• enable_auto_timeout – Whether to enable auto timeout

• limit_worker_tasks – Whether to limit concurrent tasks

• pre_job_script – Path to a script to run before the job starts. Can include tokens like {script}.

• post_job_script – Path to a script to run after the job completes. Can include tokens like {script}.

• pre_task_script – Path to a script to run before each task starts. Can include tokens like {script}.

• post_task_script – Path to a script to run after each task completes. Can include tokens like {script}.

• parameters

• output_file_path – Output directory for rendered files

• parse_output_paths_to_deadline – Whether to parse output paths to add as OutputFilename entries in job info. Defaults to True if script_is_open is True

• nuke_version – Version of Nuke to use for rendering. Can be: - String: “15.1” - Float: 15.1 (converts to “15.1”) - Int: 15 (converts to “15.0”) If None, uses config or current Nuke version

• use_nuke_x – Whether to use NukeX for rendering

• batch_mode – Whether to use batch mode

• render_threads – Number of render threads

• use_gpu – Whether to use GPU for rendering

• gpu_override – Specific GPU to use

• max_ram_usage – Maximum RAM usage (MB)

• enforce_render_order – Whether to enforce write node render order

• min_stack_size – Minimum stack size (MB)

• continue_on_error – Whether to continue rendering on error

• reload_plugins – Whether to reload plugins between tasks

• use_profiler – Whether to use the performance profiler

• profile_dir – Directory for performance profile files

• use_proxy – Whether to use proxy mode for rendering

• write_nodes –

  Write nodes to render. Can be provided in multiple formats: - Single string: The name of a write node - List of strings: Multiple write node names - Dictionary: Write node name with overrides, must contain ‘write_node’ key - List of dictionaries: Multiple write nodes with their individual overrides

  The dictionary format allows overriding job and plugin info parameters on a per-write-node basis. You can use either direct Deadline parameter names or nk2dl parameter names (which will be translated).

  Examples: ```python # Simple list of write nodes (original format) write_nodes = [‘Write1’, ‘Write2’]

  # Single write node with overrides write_nodes = {

  ’write_node’: ‘Write1’, # Required key ‘priority’: 90, # Override job priority ‘use_gpu’: True # Enable GPU rendering

  }

  # Multiple write nodes with individual settings write_nodes = [

  {

  ‘write_node’: ‘Write1’, ‘priority’: 90, # Higher priority ‘chunk_size’: 5 # Smaller chunks

  }, {

  ’write_node’: ‘Write2’, ‘priority’: 50, # Lower priority ‘ram_use’: 16000, # More RAM ‘threads’: 16 # More threads

  }, ‘Write3’ # Regular write node without overrides

• render_mode – Render mode (full, proxy, both). When set to “both”, two separate submissions are created - one with “full” and one with “proxy”.

• write_nodes_as_tasks – Whether to submit write nodes as 1 task per write node

• write_nodes_as_separate_jobs – Whether to submit write nodes as separate jobs

• render_order_dependencies – Whether to set job dependencies based on render order

• use_nodes_frame_list – Whether to use the frame range defined in write nodes with use_limit enabled

• views – List of view names to render. If None, all views will be rendered.

• parameters

• graph_scope_variables –

  List of graph scope variables to use for rendering. Can be provided in two formats:

  1. Flat list format (all combinations will be generated): [“key1:value1,value2,…”, “key2:valueA,valueB,…”]

  2. Nested list format (specific combinations): [

     [“key1:value1,value2”, “key2:valueA”], # First set of combinations [“key1:value3”, “key2:valueB”] # Second set of combinations

     ]

  If no values are provided for a key (e.g., “key:” or just “key”), all available values for that key will be used.

• parameters

• use_current_environment – Whether to use the current environment variables

• environment_keys – List of environment variables to include. Can use the special token “{config:extend}” as the first item to include config values and then extend them with the rest of the list.

• environment – Dictionary of environment variables to add to jobs. Can use the special key “{config}” with value “extend” to include config values and then extend/override them with the rest of the dictionary.

• omit_environment_keys – List of environment variables to omit from jobs. Can use the special token “{config:extend}” as the first item to include config values and then extend them with the rest of the list.

• proxy_args – Dictionary of arguments to override for the proxy submission when render_mode=”both”. These arguments will be applied only to the proxy submission, allowing different settings for proxy vs full renders. For example: proxy_args={‘priority’: 30, ‘chunk_size’: 20}. Only used when render_mode=”both”, otherwise ignored.

submit() → List[Dict[str, Any]]

Submit the Nuke script to Deadline.

Returns:

• job_id (str): The Deadline job ID

• render_order (int): The render order (0 if not fetched)

• render_mode (str): The render mode extracted from plugin_info (full/proxy)

• plugin_info (dict): The plugin info used for submission

• job_info (dict): The job info used for submission

• deadline_return (Any): The raw return from the Deadline submission

Return type:

List of dictionaries, each containing

Raises:

SubmissionError – If submission fails

submit_as_build_job() → List[Dict[str, Any]]

Create and submit a Python script job that calls submit_nuke_script.

Creates a temporary Python script file that calls submit_nuke_script with all the current instance parameters, then submits it to Deadline as a Nuke python job. This will create a single job regardless of how many write nodes are specified - the actual write node separation will happen when the script executes on the farm.

Returns:

List of dictionaries with job information, matching the format of regular submission.

Raises:

SubmissionError – If script job submission fails

nk2dl.submission.submit_nuke_script(script_path: str, **kwargs) → List[Dict[str, Any]]

Submit a Nuke script to Deadline.

Parameters:

• script_path – Path to the Nuke script file

• **kwargs –

  Additional submission parameters

  # nk2dl specific parameters - script_is_open: Whether this script path is already open in the current Nuke session - use_parser_instead_of_nuke: Whether to use a parser instead of Nuke for parsing script - submit_writes_alphabetically: Whether to sort write nodes alphabetically by name - submit_writes_in_render_order: Whether to sort write nodes by render order - submit_script_as_auxiliary_file: Whether to submit the script as an auxiliary file - render_settings_from_metadata: Whether to extract submission settings from write node metadata

  stored as ‘input/nk2dl/parameter_name’

  • copy_script: Whether to make copies of the script before submission

  • copy_script_path: Optional file path template(s) for copying the script. Can be:

    • String: Single file path template (e.g., “{outdir}/.farm/{nkstem}.nk”)

    • List: Multiple file path templates

    • Dict: With integer keys for multiple file path templates

    Supports tokens: {script}, {output}, {nkstem}, {YYYY}, {MM}, {DD}, etc.

  • submit_copied_script: Whether to use the copied script path in the submission

  • submission_is_build_job: Whether to submit as a Python script job that calls submit_nuke_script

  • build_job_script_path: Full path template for the build job script file.

    Supports tokens for both directory and filename parts: - Script directory tokens: {sdir}, {nkdir}, {scriptdir}, {nukescriptdir} - Script stem tokens: {ss}, {basename}, {stem}, {sstem}, {scriptstem} - Script name tokens: {s}, {script}, {scriptname} - Date tokens: {YYYY}, {YY}, {MM}, {DD}, {hh}, {mm}, {ss} Example: “{scriptdir}/build_jobs/{stem}_{YYYY}-{MM}-{DD}.py”

  • build_job_as_auxiliary_file: Whether to submit the build job script as an auxiliary file (default: True).

    When True, the job can be recovered if it fails since Deadline will re-copy the script to the worker. When False, the job cannot be restarted if the script file is deleted.

  • delete_build_job_script: Whether to automatically delete the build job script after execution (default: True)

  • graph_scope_variables: List of graph scope variables in either flat format: [“key1:value1,value2”, “key2:valueA,valueB”] - generates all combinations Or nested format: [[“key1:value1”, “key2:valueA”], [“key1:value2”, “key2:valueB”]] - specific combinations

  # Job Info parameters - job_name: Job name template (defaults to config value) - batch_name: Batch name template (defaults to config value) - priority: Job priority (defaults to config value) - pool: Worker pool (defaults to config value) - group: Worker group (defaults to config value) - chunk_size: Number of frames per task (defaults to config value) - department: Department (defaults to config value) - user_name: User name (defaults to config value) - comment: Job comment (defaults to config value) - concurrent_tasks: Number of parallel tasks for the job (defaults to 1) - extra_info: List of extra info fields - frames: Frame range to render (defaults to Nuke script settings) - job_dependencies: Comma or space separated list of job IDs - on_job_complete: Optional job completion script - submit_suspended: Whether to submit the job suspended - limit_groups: Optional comma-separated list of group names to limit - task_timeout: Optional task timeout in seconds - enable_auto_timeout: Whether to enable auto timeout - limit_worker_tasks: Whether to limit concurrent tasks - pre_job_script: Path to a script to run before the job starts. Can include tokens like {script}. - post_job_script: Path to a script to run after the job completes. Can include tokens like {script}. - pre_task_script: Path to a script to run before each task starts. Can include tokens like {script}. - post_task_script: Path to a script to run after each task completes. Can include tokens like {script}.

  # Plugin Info parameters - output_file_path: Output directory for rendered files - parse_output_paths_to_deadline: Whether to parse output paths to add as OutputFilename entries in job info.

  Defaults to True if script_is_open is True

  • nuke_version: Version of Nuke to use for rendering. Can be:

    • String: “15.1”

    • Float: 15.1 (converts to “15.1”)

    • Int: 15 (converts to “15.0”)

    If None, uses config or current Nuke version

  • use_nuke_x: Whether to use NukeX for rendering

  • batch_mode: Whether to use batch mode

  • threads: Number of render threads

  • use_gpu: Whether to use GPU for rendering

  • gpu_override: Specific GPU to use

  • ram_use: Maximum RAM usage (MB)

  • enforce_render_order: Whether to enforce write node render order

  • stack_size: Minimum stack size (MB)

  • continue_on_error: Whether to continue rendering on error

  • reload_plugins: Whether to reload plugins between tasks

  • performance_profiler: Whether to use the performance profiler

  • performance_profiler_path: Directory for performance profile files

  • write_nodes: Write nodes to render. Can be provided in multiple formats:

    • Single string: The name of a write node

    • List of strings: Multiple write node names

    • Dictionary: Write node name with overrides, must contain ‘write_node’ key

    • List of dictionaries: Multiple write nodes with their individual overrides

      The dictionary format allows overriding job and plugin info parameters on a per-write-node basis. You can use either direct Deadline parameter names or nk2dl parameter names (which will be translated).

      Examples: ```python # Simple list of write nodes (original format) write_nodes = [‘Write1’, ‘Write2’]

      # Single write node with overrides write_nodes = {

      ’write_node’: ‘Write1’, # Required key ‘priority’: 90, # Override job priority ‘use_gpu’: True # Enable GPU rendering

      }

      # Multiple write nodes with individual settings write_nodes = [

      {

      ‘write_node’: ‘Write1’, ‘priority’: 90, # Higher priority ‘chunk_size’: 5 # Smaller chunks

      }, {

      ’write_node’: ‘Write2’, ‘priority’: 50, # Lower priority ‘ram_use’: 16000, # More RAM ‘threads’: 16 # More threads

      }, ‘Write3’ # Regular write node without overrides

  • render_mode: Render mode (full, proxy, both). When set to “both”, two separate submissions are created - one with “full” and one with “proxy”.

  • proxy_args: Dictionary of arguments to override for the proxy submission when render_mode=”both”.

    These arguments will be applied only to the proxy submission, allowing different settings for proxy vs full renders. For example: proxy_args={‘priority’: 30, ‘chunk_size’: 20}. Only used when render_mode=”both”, otherwise ignored.

  • write_nodes_as_tasks: Whether to submit write nodes as separate tasks

  • write_nodes_as_separate_jobs: Whether to submit write nodes as separate jobs

  • render_order_dependencies: Whether to set job dependencies based on render order

  • use_node_frame_list: Whether to use node-specific frame lists

  • views: List of view names to render. If None, all views will be rendered.

  # Environment Variables parameters - use_current_environment: Whether to use the current environment variables - environment_keys: List of environment variables to include.

  Can use the special token “{config:extend}” as the first item to include config values and then extend them with the rest of the list.

  • environment: Dictionary of environment variables to add to jobs.

    Can use the special key “{config}” with value “extend” to include config values and then extend/override them with the rest of the dictionary.

  • omit_environment_keys: List of environment variables to omit from jobs.

    Can use the special token “{config:extend}” as the first item to include config values and then extend them with the rest of the list.

  # Machine List parameters - machine_list: List of machine names to allow or deny based on machine_list_is_a_deny_list - machine_list_is_a_deny_list: Whether the machine_list is a deny list (default: False, treat as allow list) - machine_allow_list: Alternative to machine_list, explicitly specifies an allow list - machine_deny_list: List of machine names to deny (cannot be used with machine_allow_list/machine_list) - machine_limit: Maximum number of machines that can work on the job simultaneously

Returns:

• job_id (str): The Deadline job ID

• render_order (int): The render order (0 if not fetched)

• render_mode (str): The render mode extracted from plugin_info (full/proxy)

• plugin_info (dict): The plugin info used for submission

• job_info (dict): The job info used for submission

• deadline_return (Any): The raw return from the Deadline submission

Return type:

List of dictionaries, each containing

nk2dl.subprocess module

Module for handling Nuke script submission through subprocesses.

This module provides functionality for submitting Nuke scripts through external processes when direct parsing of the script in the current Nuke session is not possible.

nk2dl.subprocess.serialize_kwargs(kwargs: Dict[str, Any]) → str

Serialize kwargs to a JSON string that can be safely included in Python code.

nk2dl.subprocess.submit_script_via_subprocess(script_path: str, use_parser_instead_of_nuke: bool = False, **kwargs) → Dict[int, List[str]]

Submit a Nuke script via subprocess to ensure proper script parsing.

Parameters:

• script_path – Path to the Nuke script

• use_parser_instead_of_nuke – Whether to use Python parser instead of Nuke

• **kwargs – Additional arguments to pass to submit_nuke_script

Returns:

Dictionary mapping render orders to job IDs

nk2dl.subprocess.create_submission_script(script_path: str, kwargs: Dict[str, Any]) → str

Create a temporary Python script for submission.

nk2dl.subprocess.execute_submission_script(script_path: str, use_parser_instead_of_nuke: bool) → Dict[int, List[str]]

Execute the submission script in a subprocess.

nk2dl.subprocess.script_parsing_required(**kwargs) → bool

Determine whether we need to parse the script based on kwargs.

Parameters:

**kwargs – Submission keyword arguments

Returns:

True if script parsing is required, False otherwise

Return type:

bool