python-api

TD Python API Discipline

Core rule

Never guess a TouchDesigner Python API signature. Treat every method name, attribute name, and parameter name on a td class as unverified until it has been looked up or probed in the live session. Do not pattern-match from general Python knowledge, from other creative-coding frameworks, or from a plausible-sounding name.

This rule exists for a concrete reason: the td module is large (hundreds of operator classes, each with its own methods and parameters), it changes across TouchDesigner versions (a method present in one build can be renamed, removed, or gain new required arguments in another), and it is thinly and unevenly represented in general-purpose training data compared to mainstream libraries. A guess that "looks right" is exactly the failure mode to guard against, because it will often be subtly wrong — a slightly incorrect parameter name, a method that exists on OP but not on the specific operator subclass in question, or a signature from a different TD version. Verify before writing any non-trivial script, and especially before writing anything that mutates the project (creating nodes, changing parameters, deleting nodes, running exports).

Trivial, well-established usage (see "Safe core APIs" below) does not need a fresh lookup every time. Everything else does.

The lookup ladder

Work through these steps in order, stopping as soon as the needed information is confirmed. Do not skip straight to writing a full script when the API surface involved is unfamiliar.

1. Find the class. Use get_td_classes to search the catalogue of TouchDesigner Python classes and modules. Use this when the exact class name is unknown — for example, unsure whether the relevant class is textTOP, topOP, or something else entirely.
2. Inspect the class. Use get_td_class_details with the resolved class name to retrieve its methods and members. Read the returned signatures carefully — argument names, defaults, and return types matter. This is the step that catches "that method doesn't take a path argument" or "this is a read-only property, not a callable."
3. Read module-level docs. Use get_td_module_help to pull the Python help() text for a module or class when behavior, not just signature, is in question — for example, how a family of related methods interact, or what a parameter's accepted value range is.
4. Probe interactively. Before committing to a full script, run a tiny snippet through execute_python_script to check reality directly against a live node: print(dir(op('/project1/text1'))) to list everything available, print(type(op('/project1/text1'))) to confirm the resolved class, or print(repr(op('/project1/text1').par.text.eval())) to inspect an actual value. This step catches version drift and instance-specific quirks that static docs cannot.