Property

This module defines the properties of a Task. Property is a task data one can edit directly using a text editor, e.g. a string, a number or a combination of strings and numbers etc.

Data type

Property can have different data type:

• PropertyFloat

• PropertyInt

• PropertyBool

• PropertyString

• PropertyEnum

• PropertyFloatVector

• PropertyIntVector

• PropertyBoolVector

One can extend the property type by designing a custom property. Please read custom_property page for how to create a custom property type.

Use

One can set the value of a property by:

float1 = ng.add_task("node_graph.test_float")
# set the value for Float property
float1.properties["Float"].value = 2.0
# or by
float1.set_inputs({"Float": 2.0})

Validation and wrapped values

Each property type declares allowed_types and values are validated when assigned.

In some runtimes, you may store values using wrapper objects (for example an ORM data node that exposes a Python value via .value). To support this without hardcoding third-party dependencies, TaskProperty.validate accepts a value if any of these match allowed_types:

• the value itself

• value.__wrapped__ (if present)

• value.value (if present)

• values returned by any registered validation adapters

External packages (e.g. an engine) can register adapters globally:

from node_graph.property import TaskProperty

def unwrap_custom(value):
    if hasattr(value, "get_list") and callable(value.get_list):
        return value.get_list()
    return TaskProperty.NOT_ADAPTED

TaskProperty.register_validation_adapter(unwrap_custom)

Create properties for a new Task

def create_properties(self):
   self.add_property("node_graph.float_vector", "x", size=3, default=[0, 0, 0])

Add properties to a input socket

def update_spec(self):
   inp = self.add_input("node_graph.any", "x")
   inp.add_property("node_graph.float_vector", size=3, default=[0, 0, 0])

Assigning to Existing Task

task1 = ng.add_task(Task, "pow")
task1.add_property("node_graph.float", "x")

Update Example

Support adding an update callback function when updating a property.

It can be useful to create a dynamic socket based on a property’s value.

# the item of the Enum options are [name, content, description]
self.add_property("node_graph.enum",
                     "function",
                     default="cos",
                     options=[["cos", "cos", "cos function"],
                              ["sin", "sin", "sin function"],
                              ["pow", "pow", "pow function"]],
                     update=self.update_spec,
                     )

List of all Methods

class node_graph.property.TaskProperty(name: str, description: str = '', default: Any = None, update: Callable[[], None] | None = None, arg_type: str | None = 'kwargs', value: Any = None, **kwargs)

Base class for Task properties.

A property holds data that can be displayed or modified in a GUI, with an optional update callback.

copy() → TaskProperty

Create a shallow copy of the property.

classmethod from_dict(data: Dict[str, Any]) → TaskProperty

Create a TaskProperty from a serialized dictionary.

get_metadata() → Dict[str, Any]

Return metadata related to this property.

classmethod new(identifier: str | type, name: str = None, PropertyPool: Dict[str, TaskProperty] = None, **kwargs) → TaskProperty

Create a new property from an identifier.

classmethod register_validation_adapter(adapter: Callable[[Any], Any]) → None

Register a validation adapter used when allowed_types checks fail.

The adapter is called as adapter(value) and should return either: - TaskProperty.NOT_ADAPTED if it cannot adapt the value - an adapted value that can be validated against allowed_types

set_value(value: Any) → None

Set the value and invoke the update callback if present.

to_dict() → Dict[str, Any]

Serialize the property to a dictionary for database storage.

classmethod unregister_validation_adapter(adapter: Callable[[Any], Any]) → None

Unregister a previously registered validation adapter.

update_from_dict(data: Dict[str, Any]) → None

Update the property from a dictionary.

validate(value: Any) → None

Validate the given value based on allowed types.

class node_graph.properties.builtins.MatrixProperty(name, description='', size=[3, 3], default=None, update=None)

node_graph Matrix property

copy()

Create a shallow copy of the property.

validate(value: Any) → None

Validate the given value based on allowed types.

validate_item(value: Any) → None

Validate the given value based on allowed types.

class node_graph.properties.builtins.PropertyAny(name: str, description: str = '', default: Any = None, update: Callable[[], None] | None = None, arg_type: str | None = 'kwargs', value: Any = None, **kwargs)

A new class for Any type.

class node_graph.properties.builtins.PropertyBaseDict(name, description='', default={}, update=None)

node_graph BaseDict property. All the elements should be a base type (int, float, string, bool).

set_value(value)

Set the value and invoke the update callback if present.

class node_graph.properties.builtins.PropertyBaseList(name, description='', default=None, update=None)

node_graph BaseList property. All the elements should be a base type (int, float, string, bool).

set_value(value)

Set the value and invoke the update callback if present.

class node_graph.properties.builtins.PropertyBool(name: str, description: str = '', default: Any = None, update: Callable[[], None] | None = None, arg_type: str | None = 'kwargs', value: Any = None, **kwargs)

A new class for bool type.

class node_graph.properties.builtins.PropertyBoolVector(name, description='', size=3, default=None, update=None)

A new class for bool vector type.

class node_graph.properties.builtins.PropertyEnum(name, options=[], description='', default=None, update=None)

A new class for enumeration type.

Each option has:

• identifier: identifier of the this option.

• content: The true content of the this option.

• description: Used for documentation and tooltips.

>>> from node_graph.properties.built_in import PropertyEnum
>>> enum = PropertyEnum("node_graph.enum",
                options=[["add", "test_add", "add function"],
                        "sqrt", "test_sqrt", "sqrt function"],
                        "power", "test_power", "power function"]],
                update=callback
            )
>>> enum = "sqrt"
>>> asset enum.value == "test_sqrt"

copy()

Create a shallow copy of the property.

get_metadata()

Return metadata related to this property.

set_value(value)

Set the value and invoke the update callback if present.

class node_graph.properties.builtins.PropertyFloat(name: str, description: str = '', default: Any = None, update: Callable[[], None] | None = None, arg_type: str | None = 'kwargs', value: Any = None, **kwargs)

A new class for float type.

class node_graph.properties.builtins.PropertyFloatMatrix(name, description='', size=[3, 3], default=None, update=None)

A new class for float matrix type.

class node_graph.properties.builtins.PropertyFloatVector(name, description='', size=3, default=None, update=None)

A new class for float vector type.

class node_graph.properties.builtins.PropertyInt(name: str, description: str = '', default: Any = None, update: Callable[[], None] | None = None, arg_type: str | None = 'kwargs', value: Any = None, **kwargs)

A new class for integer type.

class node_graph.properties.builtins.PropertyIntVector(name, description='', size=3, default=None, update=None)

A new class for integer vector type.

class node_graph.properties.builtins.PropertyString(name: str, description: str = '', default: Any = None, update: Callable[[], None] | None = None, arg_type: str | None = 'kwargs', value: Any = None, **kwargs)

A new class for string type.

class node_graph.properties.builtins.PropertyVector(name, description='', size=3, default=None, update=None)

node_graph Vector property

copy()

Create a shallow copy of the property.

get_metadata()

Return metadata related to this property.

set_value(value: Any) → None

Set the value and invoke the update callback if present.

validate(value: Any) → None

Validate the given value based on allowed types.

validate_item(value: Any) → None

Validate the given value based on allowed types.