Group

Bases: Node

Source code in core/nodeclass.py

class Group(Node):

    def __init__(self, group_name: str, named_sockets: dict = {}, **sockets):
        """ Node Group

        > Node Group

        Create a node 'Group' with the tree provided with 'group_name' argument.

        The sockets can be initialized either using the sockets dictionary or using they snake_case name
        as kwargs arguments.

        ``` python
        # Create a utility group
        with GeoNodes("Add two values", is_group=True):

            a = Float(0, "a")
            b = Float(0, "b")

            (a + b).out("Sum")

        # A node calling the utility group
        with GeoNodes("Call a group"):

            Geometry().out()

            c = Group("Add two values", {'a': Float(10, 'a'), 'b': Float(10, 'b')}).sum
            node = Group("Add two values")

            node.a = 100
            node.b = 200

            c.out("c")
            node._out.out("d")
        ```

        Parameters
        ----------
        group_name : str
            name of the group to use

        named_sockets : dict
            sockets initialization values

        **sockets : dict, default={}
            sockets  initialization with their snake_case name

        Returns
        -------
        Node Group
        """

        tree = Tree.current_tree()

        # ----------------------------------------------------------------------------------------------------
        # Get the node group by its name
        # ----------------------------------------------------------------------------------------------------

        spec = utils.get_available_groups(tree._btree.bl_idname).get(group_name, {})
        node_tree = blender.load_node_group(spec)
        if node_tree is None:
            raise NodeError(f"Impossible to find the group named '{group_name}'")

        # ----------------------------------------------------------------------------------------------------
        # Super init
        # ----------------------------------------------------------------------------------------------------

        super().__init__('Group', named_sockets=named_sockets, node_tree=node_tree, **sockets)

    # ----------------------------------------------------------------------------------------------------
    # Prefixed instantiation
    # ----------------------------------------------------------------------------------------------------

    @classmethod
    def Prefix(cls, prefix, group_name, named_sockets={}, **sockets):
        """ Call a Group with a prefixed named.

        > Node Group

        Using a prefix for groups of the same type can be usefull in big projects with
        a lot of groups.

        ``` python
        # Prefix used to identifiy utility groups
        UTIL = "UTIL"

        # Create a group utility
        with GeoNodes("Add two values", prefix=UTIL, is_group=True):

            a = Float(0, "a")
            b = Float(0, "b")

            (a + b).out("Sum")

        with GeoNodes("Call a group"):

            Geometry().out()

            # Call the the prefixed utility
            c = Group.Prefix(UTIL, "Add two values", {'a': Float(10, 'a'), 'b': Float(10, 'b')}).sum

            # Call the the prefixed utility
            node = Group.Prefix(UTIL, "Add two values")

            node.a = 100
            node.b = 200

            c.out("c")
            node._out.out("d")
        ```

        Parameters
        ----------
        prefix : str
            prefix

        group_name : str
            name of the group to use

        sockets : dict
            sockets initialization values

        **sockets : dict, default={}
            sockets  initialization with their snake_case name

        Returns
        -------
        Node Group
        """
        return cls(f"{str(prefix)} {group_name}", named_sockets=named_sockets, **sockets)

    # ====================================================================================================
    # Add a group as a class method
    # ====================================================================================================

    @staticmethod
    def add_method(
        group_name      : str, 
        target_class    : type, 
        *,
        func_name       : str = None,
        self_attr       : str = None,
        ret_class       : type = None, 
        prefix          : str = "",
        **fixed):
        """ Add a method calling the Group.

        The argument self_attr is the attribute to use to plug the node socket used as self:
        - None : the method is implemented as static method
        - "" : self is used directly
        - other = getattr(self, self_name) is plugged

        Parameters
        ----------
        group_name : str
            name of the Group

        target_class : type
            class to add the method to

        func_name : str, optional
            name of the method to create (snae case version of group name if None) default=None.

        self_attr : str, optional
            self name attribute name default=None.

        ret_class : type, optional
            class to use to transtype the output socket default=None.

        prefix : str, optional
            group prefix default="".

        self_attr : Any, optional
            which attr default=None.

        fixed : dict
            fixed values for sockets        

        """

        # ---------------------------------------------------------------------------
        # Get the node tree
        # ---------------------------------------------------------------------------

        if isinstance(group_name, bpy.types.NodeTree):
            btree = group_name
            group_name = btree.name
            full_name = btree.name

        else:
            pref = str(prefix)
            if pref != "":
                pref = pref + " "
            full_name = pref + group_name
            btree = bpy.data.node_groups.get(full_name)
            if btree is None:
                raise NodeError(f"Impossible to find the Group named '{full_name}'")

        # ---------------------------------------------------------------------------
        # The 3 possible calls
        # ---------------------------------------------------------------------------

        def self_method(self_, *args, **kwargs):
            node = Group(btree.name)
            return node.method_call(self_, *args, ret_class=ret_class, **kwargs, **fixed)

        def attr_method(self_, *args, **kwargs):
            node = Group(btree.name)
            return node.method_call(getattr(self_, self_attr), *args, ret_class=ret_class, **kwargs, **fixed)

        def static(*args, **kwargs):
            node = Group(btree.name)
            return node.method_call(*args, ret_class=ret_class, **kwargs, **fixed)

        # ---------------------------------------------------------------------------
        # Add the method to the class
        # ---------------------------------------------------------------------------

        if func_name is None:
            func_name = utils.snake_case(group_name)

        if func_name in dir(target_class):
            #raise NodeError(f"Impossible to add Node method '{func_name}'. This function already exists in class {target_class}.")
            print(f"CAUTION: the method '{func_name}' (implementing group '{full_name}') already exists in class {target_class}.")

        if self_attr is None:            
            setattr(target_class, func_name, staticmethod(static))

        elif self_attr.lower() in ["", "self"]:
            setattr(target_class, func_name, self_method)

        else:
            setattr(target_class, func_name, attr_method)

_out property

Returns the first enabled output socket.

Returns:

Type	Description
Socket	first enabled output socket

Prefix(prefix, group_name, named_sockets={}, **sockets) classmethod

Call a Group with a prefixed named.

Node Group

Using a prefix for groups of the same type can be usefull in big projects with a lot of groups.

# Prefix used to identifiy utility groups
UTIL = "UTIL"

# Create a group utility
with GeoNodes("Add two values", prefix=UTIL, is_group=True):

    a = Float(0, "a")
    b = Float(0, "b")

    (a + b).out("Sum")

with GeoNodes("Call a group"):

    Geometry().out()

    # Call the the prefixed utility
    c = Group.Prefix(UTIL, "Add two values", {'a': Float(10, 'a'), 'b': Float(10, 'b')}).sum

    # Call the the prefixed utility
    node = Group.Prefix(UTIL, "Add two values")

    node.a = 100
    node.b = 200

    c.out("c")
    node._out.out("d")

Parameters:

Name	Type	Description	Default
prefix	str	prefix	required
group_name	str	name of the group to use	required
sockets	dict	sockets initialization values	{}
**sockets	dict	sockets initialization with their snake_case name	{}

Returns:

Type	Description
Node Group

Source code in core/nodeclass.py

@classmethod
def Prefix(cls, prefix, group_name, named_sockets={}, **sockets):
    """ Call a Group with a prefixed named.

    > Node Group

    Using a prefix for groups of the same type can be usefull in big projects with
    a lot of groups.

    ``` python
    # Prefix used to identifiy utility groups
    UTIL = "UTIL"

    # Create a group utility
    with GeoNodes("Add two values", prefix=UTIL, is_group=True):

        a = Float(0, "a")
        b = Float(0, "b")

        (a + b).out("Sum")

    with GeoNodes("Call a group"):

        Geometry().out()

        # Call the the prefixed utility
        c = Group.Prefix(UTIL, "Add two values", {'a': Float(10, 'a'), 'b': Float(10, 'b')}).sum

        # Call the the prefixed utility
        node = Group.Prefix(UTIL, "Add two values")

        node.a = 100
        node.b = 200

        c.out("c")
        node._out.out("d")
    ```

    Parameters
    ----------
    prefix : str
        prefix

    group_name : str
        name of the group to use

    sockets : dict
        sockets initialization values

    **sockets : dict, default={}
        sockets  initialization with their snake_case name

    Returns
    -------
    Node Group
    """
    return cls(f"{str(prefix)} {group_name}", named_sockets=named_sockets, **sockets)

__init__(group_name, named_sockets={}, **sockets)

Node Group

Node Group

Create a node 'Group' with the tree provided with 'group_name' argument.

The sockets can be initialized either using the sockets dictionary or using they snake_case name as kwargs arguments.

# Create a utility group
with GeoNodes("Add two values", is_group=True):

    a = Float(0, "a")
    b = Float(0, "b")

    (a + b).out("Sum")

# A node calling the utility group
with GeoNodes("Call a group"):

    Geometry().out()

    c = Group("Add two values", {'a': Float(10, 'a'), 'b': Float(10, 'b')}).sum
    node = Group("Add two values")

    node.a = 100
    node.b = 200

    c.out("c")
    node._out.out("d")

Parameters:

Name	Type	Description	Default
group_name	str	name of the group to use	required
named_sockets	dict	sockets initialization values	{}
**sockets	dict	sockets initialization with their snake_case name	{}

Returns:

Type	Description
Node Group

Source code in core/nodeclass.py

def __init__(self, group_name: str, named_sockets: dict = {}, **sockets):
    """ Node Group

    > Node Group

    Create a node 'Group' with the tree provided with 'group_name' argument.

    The sockets can be initialized either using the sockets dictionary or using they snake_case name
    as kwargs arguments.

    ``` python
    # Create a utility group
    with GeoNodes("Add two values", is_group=True):

        a = Float(0, "a")
        b = Float(0, "b")

        (a + b).out("Sum")

    # A node calling the utility group
    with GeoNodes("Call a group"):

        Geometry().out()

        c = Group("Add two values", {'a': Float(10, 'a'), 'b': Float(10, 'b')}).sum
        node = Group("Add two values")

        node.a = 100
        node.b = 200

        c.out("c")
        node._out.out("d")
    ```

    Parameters
    ----------
    group_name : str
        name of the group to use

    named_sockets : dict
        sockets initialization values

    **sockets : dict, default={}
        sockets  initialization with their snake_case name

    Returns
    -------
    Node Group
    """

    tree = Tree.current_tree()

    # ----------------------------------------------------------------------------------------------------
    # Get the node group by its name
    # ----------------------------------------------------------------------------------------------------

    spec = utils.get_available_groups(tree._btree.bl_idname).get(group_name, {})
    node_tree = blender.load_node_group(spec)
    if node_tree is None:
        raise NodeError(f"Impossible to find the group named '{group_name}'")

    # ----------------------------------------------------------------------------------------------------
    # Super init
    # ----------------------------------------------------------------------------------------------------

    super().__init__('Group', named_sockets=named_sockets, node_tree=node_tree, **sockets)

_lc(label=None, color=None)

Set node label and color.

This method returns self to be chained:

Parameters:

Name	Type	Description	Default
label	str	node label default=None.	None
color	color	node color default=None.	None

Returns:

Type	Description
self

Source code in core/nodeclass.py

def _lc(self, label=None, color=None):
    """ Set node label and color.

    This method returns self to be chained:

    Parameters
    ----------
    label : str, optional
        node label default=None.

    color : color, optional
        node color default=None.


    Returns
    -------
    self
    """
    self._label = label
    self._color = color
    return self    

_list_to_inputs(*names, socket_list=None)

Feed node inputs with successive items from a list socket.

When names is empty, all inputs whose type matches the list item type are used. Otherwise, only the named inputs are used. Inputs keep their order on the node.

Parameters:

Name	Type	Description	Default
names	str	Optional names of the inputs to feed.	()
socket_list	Socket	List whose successive items are connected to the selected inputs.	None

Returns:

Type	Description
Node	This node.

Source code in core/nodeclass.py

def _list_to_inputs(self, *names, socket_list=None):
    """Feed node inputs with successive items from a list socket.

    When ``names`` is empty, all inputs whose type matches the list item
    type are used. Otherwise, only the named inputs are used. Inputs keep
    their order on the node.

    Parameters
    ----------
    names : str
        Optional names of the inputs to feed.

    socket_list : Socket
        List whose successive items are connected to the selected inputs.

    Returns
    -------
    Node
        This node.
    """
    socket_type = SocketType(socket_list).type

    input_sockets = []
    all_socks = []
    for bsock in self._bnode.inputs:

        all_socks.append(bsock.name)

        if bsock.type != socket_type:
            continue

        if len(names) and bsock.name not in names:
            continue

        input_sockets.append(bsock)

    if not len(input_sockets):
        raise NodeError(f"Impossible to feed inputs of type '{socket_type}' on Node {self}.\n" +
                        f"- names args : {names}\n" +
                        f"- sockets : {all_socks}")

    for index, bsock in enumerate(input_sockets):
        self._tree.link(socket_list[index], bsock)

    return self

_outputs_to_list(*names, data_type='Float', return_names=False)

Collect node outputs into a list.

The selected outputs are stored in the order in which they appear on the node. When names is empty, all outputs matching data_type are collected.

separate = Node('Separate XYZ', vector=vector)

# List containing X, Y and Z
components = separate._outputs_to_list(data_type='Float')

# List containing X and Z, plus their names
components, names = separate._outputs_to_list(
    'X', 'Z',
    data_type='Float',
    return_names=True,
)

Parameters:

Name	Type	Description	Default
names	str	Optional names of the outputs to collect.	()
data_type	str	Type of the outputs to collect.	'Float'
return_names	bool	Also return a String list containing the selected socket names.	False

Returns:

Type	Description
Socket or tuple(Socket, String)	List of output values, optionally followed by the list of their names.

Raises:

Type	Description
NodeError	If the node has no output matching both names and data_type.

Source code in core/nodeclass.py

def _outputs_to_list(self, *names, data_type='Float', return_names=False):
    """Collect node outputs into a list.

    The selected outputs are stored in the order in which they appear on
    the node. When ``names`` is empty, all outputs matching ``data_type``
    are collected.

    ``` python
    separate = Node('Separate XYZ', vector=vector)

    # List containing X, Y and Z
    components = separate._outputs_to_list(data_type='Float')

    # List containing X and Z, plus their names
    components, names = separate._outputs_to_list(
        'X', 'Z',
        data_type='Float',
        return_names=True,
    )
    ```

    Parameters
    ----------
    names : str
        Optional names of the outputs to collect.

    data_type : str, default='Float'
        Type of the outputs to collect.

    return_names : bool, default=False
        Also return a String list containing the selected socket names.

    Returns
    -------
    Socket or tuple(Socket, String)
        List of output values, optionally followed by the list of their
        names.

    Raises
    ------
    NodeError
        If the node has no output matching both ``names`` and
        ``data_type``.
    """

    from .sockettype import SocketType
    from .sock_string import String

    socket_type = SocketType.from_type(data_type).type

    sock_values = []
    sock_names = []
    all_socks = []
    for bsock in self._bnode.outputs:

        all_socks.append(bsock.name)

        if bsock.type != socket_type:
            continue

        if len(names) and bsock.name not in names:
            continue

        sock_values.append(self._to_socket(bsock))
        sock_names.append(bsock.name)

    if not len(sock_values):
        raise NodeError(f"Impossible to build a list of '{socket_type}' from Node {self} outputs.\n" +
                        f"- names args : {names}\n" +
                        f"- sockets : {all_socks}")

    val_list = sock_values[0].List(*sock_values)
    if return_names:
        name_list = String.List(*sock_names)
        return val_list, name_list
    else:
        return val_list

_socket_created(socket, value=None)

Socket creation call back

Source code in core/nodeclass.py

def _socket_created(self, socket, value=None):
    """ Socket creation call back
    """

    from .geometry_class import Geometry

    # Store created sockets

    bsocket = utils.get_bsocket(socket)
    inout = 'OUTPUT' if bsocket.is_output else 'INPUT'

    d = self._created_sockets.get(inout, {})
    d[bsocket.name] = socket
    self._created_sockets[inout] = d

    # Geometry class

    if inout == 'INPUT' and SocketType(value).is_geometry:
        if value is None or isinstance(value, SocketType):
            self._geo_classes[bsocket.name] = Geometry
        else:
            self._geo_classes[bsocket.name] = type(value)

_to_socket(socket)

Wrap a Blender socket with the dynamic geometry class when known.

Source code in core/nodeclass.py

def _to_socket(self, socket):
    """Wrap a Blender socket with the dynamic geometry class when known.
    """
    bsocket = utils.get_bsocket(socket)

    geo_classes = self._geo_classes
    if self._is_paired_output and self._paired_input_node is not None:
        geo_classes = self._paired_input_node._geo_classes

    geo_class = geo_classes.get(bsocket.name) or self._geo_classes.get(bsocket.name)

    if geo_class is not None:
        return geo_class(bsocket)

    return utils.to_socket(bsocket)

add_method(group_name, target_class, *, func_name=None, self_attr=None, ret_class=None, prefix='', **fixed) staticmethod

Add a method calling the Group.

The argument self_attr is the attribute to use to plug the node socket used as self: - None : the method is implemented as static method - "" : self is used directly - other = getattr(self, self_name) is plugged

Parameters:

Name	Type	Description	Default
group_name	str	name of the Group	required
target_class	type	class to add the method to	required
func_name	str	name of the method to create (snae case version of group name if None) default=None.	None
self_attr	str	self name attribute name default=None.	None
ret_class	type	class to use to transtype the output socket default=None.	None
prefix	str	group prefix default="".	''
self_attr	Any	which attr default=None.	None
fixed	dict	fixed values for sockets	{}

Source code in core/nodeclass.py

@staticmethod
def add_method(
    group_name      : str, 
    target_class    : type, 
    *,
    func_name       : str = None,
    self_attr       : str = None,
    ret_class       : type = None, 
    prefix          : str = "",
    **fixed):
    """ Add a method calling the Group.

    The argument self_attr is the attribute to use to plug the node socket used as self:
    - None : the method is implemented as static method
    - "" : self is used directly
    - other = getattr(self, self_name) is plugged

    Parameters
    ----------
    group_name : str
        name of the Group

    target_class : type
        class to add the method to

    func_name : str, optional
        name of the method to create (snae case version of group name if None) default=None.

    self_attr : str, optional
        self name attribute name default=None.

    ret_class : type, optional
        class to use to transtype the output socket default=None.

    prefix : str, optional
        group prefix default="".

    self_attr : Any, optional
        which attr default=None.

    fixed : dict
        fixed values for sockets        

    """

    # ---------------------------------------------------------------------------
    # Get the node tree
    # ---------------------------------------------------------------------------

    if isinstance(group_name, bpy.types.NodeTree):
        btree = group_name
        group_name = btree.name
        full_name = btree.name

    else:
        pref = str(prefix)
        if pref != "":
            pref = pref + " "
        full_name = pref + group_name
        btree = bpy.data.node_groups.get(full_name)
        if btree is None:
            raise NodeError(f"Impossible to find the Group named '{full_name}'")

    # ---------------------------------------------------------------------------
    # The 3 possible calls
    # ---------------------------------------------------------------------------

    def self_method(self_, *args, **kwargs):
        node = Group(btree.name)
        return node.method_call(self_, *args, ret_class=ret_class, **kwargs, **fixed)

    def attr_method(self_, *args, **kwargs):
        node = Group(btree.name)
        return node.method_call(getattr(self_, self_attr), *args, ret_class=ret_class, **kwargs, **fixed)

    def static(*args, **kwargs):
        node = Group(btree.name)
        return node.method_call(*args, ret_class=ret_class, **kwargs, **fixed)

    # ---------------------------------------------------------------------------
    # Add the method to the class
    # ---------------------------------------------------------------------------

    if func_name is None:
        func_name = utils.snake_case(group_name)

    if func_name in dir(target_class):
        #raise NodeError(f"Impossible to add Node method '{func_name}'. This function already exists in class {target_class}.")
        print(f"CAUTION: the method '{func_name}' (implementing group '{full_name}') already exists in class {target_class}.")

    if self_attr is None:            
        setattr(target_class, func_name, staticmethod(static))

    elif self_attr.lower() in ["", "self"]:
        setattr(target_class, func_name, self_method)

    else:
        setattr(target_class, func_name, attr_method)

as_tuple()

Returns the output sockets as a tuple

Used in nodes such a separate_xyz to get the 3 components in a tuple

v = Vector()

# Split without node label
x, y, z = v.xyz

# Split with label
x, y, z = v.separate_xyz()._lc("Size").as_tuple()

Returns:

Type	Description
tuple	tuple of enabled sockets

Source code in core/nodeclass.py

def as_tuple(self):
    """ Returns the output sockets as a tuple

    Used in nodes such a separate_xyz to get the 3 components in a tuple

    ``` python
    v = Vector()

    # Split without node label
    x, y, z = v.xyz

    # Split with label
    x, y, z = v.separate_xyz()._lc("Size").as_tuple()
    ```

    Returns
    -------
    tuple
        tuple of enabled sockets

    """
    return tuple([socket for _, socket in self.get_sockets('OUTPUT')])

create_from_socket(in_out, socket, name=None, panel='', **props)

Create a new socket from a socket and link them

Parameters:

Name	Type	Description	Default
in_out	(INPUT, OUPUT)	input or output socket	'INPUT'
socket	Socket | NodeSocket	socket to create from	required
panel	str	creation panel default="".	''
props	dict	additional properties	{}

Raises:

Type	Description
- NodeError if impossible to create the socket

Returns:

Type	Description
Socket	the created socket

Source code in core/nodeclass.py

def create_from_socket(self,
        in_out  : IN_OUT, 
        socket  : Socket,
        name    : str = None, 
        panel   : str="", **props) -> Socket:
    """ Create a new socket from a socket and link them

    Parameters
    ----------
    in_out : {'INPUT', 'OUPUT'}
        input or output socket

    socket : Socket | bpy.types.NodeSocket
        socket to create from

    panel : str, optional
        creation panel default="".

    props : dict
        additional properties


    Raises
    ------
    - NodeError if impossible to create the socket

    Returns
    -------
    Socket
        the created socket

    """

    # ---------------------------------------------------------------------------
    # Creation must be possible
    # ---------------------------------------------------------------------------

    assert in_out in ('INPUT', 'OUTPUT')

    if (in_out == 'INPUT' and not self._has_dyn_in) or (in_out == 'OUTPUT' and not self._has_dyn_out):
        raise NodeError(f"Impossible to create a {in_out} socket for node {self} (name '{name}').")

    bsocket = SocketType.get_bsocket(socket)
    if bsocket is None:
        raise NodeError(f"Invalid socket: {socket}.")

    if name is None:
        name = utils.get_default_name(socket)

    # ---------------------------------------------------------------------------
    # Tree interface
    # ---------------------------------------------------------------------------

    if self._use_interface:

        intf_in_out = self._interface_in_out[in_out]
        if intf_in_out is None:
            assert False, f"Shouldn't happen"

        isock = self._interface.create_socket(intf_in_out, name, socket_type=None, parent=self._tree.get_panel(panel), from_socket=bsocket, **props)
        if isock is None:
            raise NodeError(f"Impossible to create the {intf_in_out} socket named in Node {self}", name=name, **props)

        created = self.socket_by_identifier(in_out, isock.identifier)        

    # ---------------------------------------------------------------------------
    # Items
    # ---------------------------------------------------------------------------

    else:
        full_name = (ItemPath(panel) + name).long_name
        items_type = SocketType(bsocket).items_type

        # No arguments
        if self._bnode.bl_idname in ['GeometryNodeIndexSwitch']:
            self._items[in_out].new()

        # Name only
        elif self._bnode.bl_idname in ['GeometryNodeMenuSwitch']:
            self._items[in_out].new(full_name)

        # For each
        elif self._bnode.bl_idname == 'GeometryNodeForeachGeometryElementOutput':
            if utils.snake_case(panel) == "main":
                items = self._bnode.main_items
            else:
                items = self._bnode.generation_items
            items.new(items_type, full_name)

        # Name and data type
        else:
            try:
                self._items[in_out].new(items_type, full_name)
            except Exception as e:
                raise NodeError(f"Impossible to create the item '{full_name}' in Node ({self._bnode.bl_idname}), Socket type: '{items_type}': {str(e)}")

        sockets = self._bnode.inputs if in_out == 'INPUT' else self._bnode.outputs
        created = sockets[-2]

    # ---------------------------------------------------------------------------
    # Link and return
    # ---------------------------------------------------------------------------

    if bsocket.is_output:
        self._tree.link(bsocket, created)
    else:
        self._tree.link(created, bsocket)

    self._socket_created(created, value=socket)

    return created

create_socket(in_out, socket_type, name, panel='', **props)

Create a new socket.

Parameters:

Name	Type	Description	Default
in_out	(INPUT, OUPUT)	input or output socket	'INPUT'
socket_type	str | Socket	type of socket to create	required
panel	str	creation panel default="".	''
props	dict	additional properties	{}

Raises:

Type	Description
- NodeError if impossible to create the socket

Returns:

Type	Description
Socket (output) or bpy.types.NodeSocket (input) : the created socket

Source code in core/nodeclass.py

def create_socket(self, 
        in_out      : IN_OUT, 
        socket_type : str | SocketType, 
        name        : str, 
        panel       : str="",
        **props) -> Socket:
    """ Create a new socket.

    Parameters
    ----------
    in_out : {'INPUT', 'OUPUT'}
        input or output socket

    socket_type : str | Socket
        type of socket to create

    panel : str, optional
        creation panel default="".

    props : dict
        additional properties


    Raises
    ------
    - NodeError if impossible to create the socket

    Returns
    -------
    Socket (output) or bpy.types.NodeSocket (input) : the created socket
    """

    # ---------------------------------------------------------------------------
    # Creation must be possible
    # ---------------------------------------------------------------------------

    assert in_out in ('INPUT', 'OUTPUT')
    if socket_type is None:
        assert self._bnode.bl_idname in constants.AUTO_INPUT_TYPE_NODES
        socket_type = SocketType.from_type(self._bnode.data_type)

    if (in_out == 'INPUT' and not self._has_dyn_in) or (in_out == 'OUTPUT' and not self._has_dyn_out):            
        raise NodeError(f"Impossible to create a {in_out} socket for node {self} (name '{name}').")

    # ---------------------------------------------------------------------------
    # Socket type and sub type
    # ---------------------------------------------------------------------------

    socket_type = SocketType.from_type(socket_type)
    creation_props = socket_type.set_props({**props})

    # ---------------------------------------------------------------------------
    # Tree interface
    # ---------------------------------------------------------------------------

    if self._use_interface:

        intf_in_out = self._interface_in_out[in_out]
        if intf_in_out is None:
            assert False, f"Shouldn't happen"

        isock = self._interface.create_socket(intf_in_out, name, socket_type, parent=self._tree.get_panel(panel), **creation_props)
        if isock is None:
            raise NodeError(f"Impossible to create the {intf_in_out} socket named in Node {self}", name=name, stype=str(socket_type), **creation_props)

        socket = self.socket_by_identifier(in_out, isock.identifier)

    # ---------------------------------------------------------------------------
    # Items
    # ---------------------------------------------------------------------------

    else:

        # For each
        if self._bnode.bl_idname == 'GeometryNodeForeachGeometryElementOutput':
            if utils.snake_case(panel) == "main":
                items = self._bnode.main_items
            else:
                items = self._bnode.generation_items
        else:
            items = self._items[in_out]

        full_name = (ItemPath(panel) + name).long_name
        # No argument
        if self._bnode.bl_idname in ['GeometryNodeIndexSwitch']:
            items.new()

        # One argument
        elif self._bnode.bl_idname in ['GeometryNodeMenuSwitch']:
            items.new(full_name)

        # Two arguments
        else:
            try:
                items.new(socket_type.items_type, full_name)
            except Exception as e:
                raise NodeError(
                    f"Impossible to create the socket '{full_name}' of type '{socket_type.items_type} "
                    f" in node [{self._bnode.bl_idname}].\n{str(e)}")

        io_socks = self._bnode.inputs if in_out == 'INPUT' else self._bnode.outputs
        socket = io_socks[-2]

        # Default on input socket for paired input nodes
        if in_out == 'OUTPUT' and self._is_paired_input:
            def_val = props.get('default', props.get('default_value', None))
            if def_val is not None:
                try:
                    self._inputs.by_name(full_name).default_value = def_val
                except Exception as e:
                    pass
                    #raise RuntimeError(f"Erreor setting default val <{def_val}>, Node {self}, {name=}, {full_name=}: {str(e)}")


    self._socket_created(socket, value=socket_type)

    return socket

data_type_from_value(value, param_name='data_type', on_error='DEFAULT')

Get the data_type from the value to plug on socket

Parameters:

Name	Type	Description	Default
value		the value to set on the socket	required
param_name	(data_type, input_type)	param name	'data_type'
on_error	(HALT, NONE, DEFAULT)	what to do if not found	'HALT'

Returns:

Type	Description
data_type	a valid data type

Source code in core/nodeclass.py

def data_type_from_value(self, value, param_name: str = 'data_type', on_error: str = 'DEFAULT'):
    """ Get the data_type from the value to plug on socket

    Parameters
    ----------
    value
        the value to set on the socket

    param_name : {'data_type', 'input_type'}
        param name

    on_error : {'HALT', 'NONE', 'DEFAULT'}
        what to do if not found


    Returns
    -------
    data_type
        a valid data type

    """
    return SocketType.get_data_type_for_node(value, self._bnode.bl_idname, param_name, on_error='DEFAULT')

get_signature(include=None, exclude=[], enabled_only=False, free_only=False, with_sockets=False)

Build the signature of the node.

Parameters:

Name	Type	Description	Default
include	list	sockets to include default=None.	None
exclude	list	sockets to exclude default=[].	[]
enabled_only	bool	(bool = True) : ignore disabled sockets	False
free_only	bool	ignore linked sockets	False
with_sockets	bool	include sockets default=False.	False

Returns:

Type	Description
Signature

Source code in core/nodeclass.py

def get_signature(self, 
        include      : list = None, 
        exclude      : list = [], 
        enabled_only : bool = False, 
        free_only    : bool = False,
        with_sockets : bool = False) -> Signature:
    """ Build the signature of the node.

    Parameters
    ----------
    include : list, optional
        sockets to include default=None.

    exclude : list, optional
        sockets to exclude default=[].

    enabled_only
        (bool = True) : ignore disabled sockets

    free_only : bool, default=False
        ignore linked sockets

    with_sockets : bool, optional
        include sockets default=False.


    Returns
    -------
    Signature
    """

    sigs = []
    for in_out in ('INPUT', 'OUTPUT'):

        node_sockets = self.get_sockets(
            in_out, 
            include         = include, 
            exclude         = exclude, 
            enabled_only    = enabled_only, 
            free_only       = free_only)

        sig = {}
        #for name, socket in node_sockets.items():
        for name, socket in node_sockets:

            bsocket = utils.get_bsocket(socket)

            sig[name] = {
                'socket_type' : SocketType(bsocket),
                'identifier'  : bsocket.identifier,
            }

            if with_sockets:
                sig[name]['socket'] = socket

        sigs.append(sig)

    return Signature(*sigs)

get_socket(in_out, name, socket_type, enabled_only=True, free_only=False, halt=True)

Get a socket by a reference

Parameters:

Name	Type	Description	Default
in_out	(INPUT, OUTPUT)	input or output sockets	'INPUT'
name	str | int | Socket	socket index, name, identifier or the socket itself	required
socket_type	str	socket type	required
enabled_only	bool	ignore disabled sockets default=True	True
free_only	bool	ignore linked sockets default=False.	False
halt	bool	raises an error if not found default=True.	True

Returns:

Type	Description
Socket if found

Source code in core/nodeclass.py

def get_socket(self, 
        in_out       : IN_OUT, 
        name         : str | int | Socket, 
        socket_type  : str,
        enabled_only : bool = True, 
        free_only    : bool = False, 
        halt         : bool = True) -> Socket:
    """ Get a socket by a reference

    Parameters
    ----------
    in_out : {'INPUT', 'OUTPUT'}
        input or output sockets

    name : str | int | Socket
        socket index, name, identifier or the socket itself

    socket_type : str
        socket type

    enabled_only : bool
        ignore disabled sockets default=True

    free_only : bool, optional
        ignore linked sockets default=False.

    halt : bool, optional
        raises an error if not found default=True.


    Returns
    -------
    Socket if found
    """

    # The result is provided
    socket = utils.get_bsocket(name)
    if socket is not None:
        return socket

    # By its index
    if isinstance(name, int):
        return self.socket_by_index(in_out, name, enabled_only=enabled_only)

    # Let's try the identifier
    socket = self.socket_by_identifier(in_out, name, halt=False)
    if socket is not None:
        return socket

    # Utltimately : the socket name
    return self.socket_by_name(in_out, name, socket_type, enabled_only=enabled_only, free_only=free_only, halt = halt)

get_socket_default_name(in_out, value)

Get the socket default name from a value

Parameters:

Name	Type	Description	Default
in_out	(INPUT, OUTPUT)	for input or output socket	'INPUT'
value	Any	the value to name	required

Source code in core/nodeclass.py

def get_socket_default_name(self, in_out: IN_OUT, value) -> str:
    """ Get the socket default name from a value

    Parameters
    ----------
    in_out : {'INPUT', 'OUTPUT'}
        for input or output socket

    value : Any
        the value to name

    """
    if SocketType(value).type == 'GEOMETRY':
        if in_out == 'OUTPUT' and self._bnode.bl_idname == "GeometryNodeForeachGeometryElementOutput":
            return "Geometry"

        return type(value).__name__

    return utils.get_default_name(value)

get_sockets(in_out, include=None, exclude=[], enabled_only=True, free_only=False, panel='')

Build a list of sockets.

Parameters:

Name	Type	Description	Default
in_out	(INPUT, OUTPUT)	input or output sockets	'INPUT'
include	list	sockets to include default=None.	None
exclude	list	sockets to exclude default=[].	[]
enabled_only	bool	(bool = True) : ignore disabled sockets	True
free_only	bool	(bool = False) : ignore linked sockets	False

Returns:

Type	Description
list of sockets

Source code in core/nodeclass.py

def get_sockets(self, 
        in_out       : IN_OUT, 
        include      : list = None,
        exclude      : list = [],
        enabled_only : bool = True,
        free_only    : bool = False,
        panel        : str = "") -> list[(str, Socket)]:
    """ Build a list of sockets.

    Parameters
    ----------
    in_out : {'INPUT', 'OUTPUT'}
        input or output sockets

    include : list, optional
        sockets to include default=None.

    exclude : list, optional
        sockets to exclude default=[].

    enabled_only
        (bool = True) : ignore disabled sockets

    free_only
        (bool = False) : ignore linked sockets


    Returns
    -------
    list of sockets
    """

    assert(in_out in ('INPUT', 'OUTPUT'))

    # ====================================================================================================
    # Get from tree interface
    # ====================================================================================================

    if self._use_interface:

        intf_in_out = self._interface_in_out[in_out]
        if intf_in_out is None:
            return []

        isocks = self._interface.get_sockets(
            intf_in_out, 
            include      = include,
            exclude      = exclude,
            enabled_only = enabled_only,
            parent       = panel,
        )

        sockets = []
        for isock in isocks:
            path = ItemPath(isock) - ItemPath(panel)
            if in_out == 'INPUT':
                socket = self._bnode.inputs[isock.identifier]

                if free_only and not utils.is_free(socket):
                    continue

            else:
                socket = self._to_socket(self._bnode.outputs[isock.identifier])

            sockets.append((path.path, socket))

        return sockets

    # ====================================================================================================
    # No tree interface
    # ====================================================================================================

    sockets = []

    socks = self._inputs if in_out == 'INPUT' else self._outputs

    panel_path = ItemPath(panel).ranked_long_name

    for name, socket in socks:

        if in_out == 'INPUT' and free_only and not utils.is_free(socket):
            continue

        if panel_path != "" and not name.startswith(panel_path):
            continue

        names = (name, utils.snake_case(name))
        if include is not None:
            ok = False
            for iname in include:
                if iname in names:
                    ok = True
                    break
            if not ok:
                continue

        ok = True
        for iname in exclude:
            if iname in names:
                ok = False
                break
        if not ok:
            continue

        sockets.append((name, socket))

    return sockets

link_inputs(from_node=None, from_panel='', *, include=None, exclude=[], panel='')

Link input sockets from another node

If from_node is None, the current input node is taken.

Sockets which has been set at initialization time and sockets already linked are ignored.

If from node is able to create output sockets, they are created, otherwise only the sockets with matching names and types are linked.

Parameters:

Name	Type	Description	Default
from_node	Node	node to get output sockets from	None
from_panel	str	the panel to use in from_node	""
include	list	sockets to include	None
exclude	list	sockets to exclude	[]
panel	str	panel to select input socket	""

Returns:

Type	Description
self

Source code in core/nodeclass.py

def link_inputs(self,
    from_node   : Node = None,
    from_panel  : str = "",
    *,
    include     : list =  None,
    exclude     : list  = [],
    panel       : str = "",
    ):
    """ Link input sockets from another node

    If from_node is None, the current input node is taken.

    Sockets which has been set at initialization time and sockets already linked are ignored.

    If from node is able to create output sockets, they are created, otherwise only the sockets
    with matching names and types are linked.

    Parameters
    ----------
    from_node : Node, default=None
        node to get output sockets from

    from_panel : str, default=""
        the panel to use in from_node

    include : list, default=None
        sockets to include

    exclude : list, default=[]
        sockets to exclude

    panel : str, default=""
        panel to select input socket

    Returns
    -------
    self
    """

    # ---------------------------------------------------------------------------
    # The list of input sockets to link
    # ---------------------------------------------------------------------------

    if from_node is None:
        from_node = self._tree.get_input_node()
    elif from_node in ['GROUP', 'TREE']:
        from_node = self._tree.input_node

    in_sockets = self.get_sockets(
        'INPUT',
        include      = include,
        exclude      = exclude + self._link_ignore,
        enabled_only = True,
        free_only    = True,
        panel        = panel,
        )

    # ---------------------------------------------------------------------------
    # Create the links
    # ---------------------------------------------------------------------------

    for name, in_socket in in_sockets:

        path = ItemPath(from_panel) + name
        copy_interface_properties = False

        out_socket = from_node.socket_by_name('OUTPUT', path, SocketType(in_socket).type, halt=False)

        if out_socket is None:
            if from_node._has_dyn_out:
                out_socket = from_node.create_from_socket('OUTPUT', in_socket, name=path)

                # Copy the properties when both nodes have interface
                if self._use_interface and from_node._use_interface:
                    copy_interface_properties = True

        if out_socket is not None:
            self._tree.link(out_socket, in_socket)
            # Menu items are inferred from the link; their defaults cannot
            # be assigned until the new interface socket is connected.
            if copy_interface_properties:
                self._interface.copy_properties(
                    from_node._interface.by_identifier(out_socket._bsocket.identifier),
                    self._interface.by_identifier(in_socket.identifier)
                )

    return self

link_outputs(to_node=None, to_panel='', *, include=None, exclude=[], panel='')

Link output socket to another node

if to_node is None, the current output node is taken.

If from node is able to create output sockets, they are created, otherwise only the sockets with matchin names and types are linked.

Parameters:

Name	Type	Description	Default
to_node	Node	node to plug into	None
to_panel	str	the panel to use in to_node	""
include	list	sockets to include	None
exclude	list	sockets to exclude	[]]
panel	str	panel to select input socket in	""

Source code in core/nodeclass.py

def link_outputs(self,
    to_node     : Node = None,
    to_panel    : str = "",
    *,
    include     : list =  None,
    exclude     : list  = [],
    panel       : str = "",
    ):
    """ Link output socket to another node

    if to_node is None, the current output node is taken.

    If from node is able to create output sockets, they are created, otherwise only the sockets
    with matchin names and types are linked.

    Parameters
    ----------
    to_node : Node, default=None
        node to plug into

    to_panel : str, default=""
        the panel to use in to_node

    include : list, default=None
        sockets to include

    exclude : list, default=[]]
        sockets to exclude

    panel : str, default=""
        panel to select input socket in

    """

    # ---------------------------------------------------------------------------
    # The list of output sockets to link
    # ---------------------------------------------------------------------------

    if to_node is None:
        to_node = self._tree.get_output_node()

    out_sockets = self.get_sockets(
        'OUTPUT',
        include      = include,
        exclude      = exclude,
        enabled_only = True,
        panel        = panel,
        )

    # ---------------------------------------------------------------------------
    # Create the links
    # ---------------------------------------------------------------------------

    links = []

    for name, out_socket in out_sockets:

        path = (ItemPath(to_panel) + name).path

        in_socket = to_node.socket_by_name('INPUT', path, SocketType(out_socket).type, halt=False)

        if in_socket is None:
            if to_node._has_dyn_in:
                in_socket = to_node.create_from_socket('INPUT', out_socket, name=path)

        if in_socket is not None:
            self._tree.link(out_socket, in_socket)
            links.append((out_socket, in_socket))

    return links

link_panel(panel, from_node=None)

Link panel input sockets from another node

If from_node is None, the current input node is taken.

see ink_inputs

Call:

    return self.link_inputs(from_node=from_node, from_panel=panel, panel=panel)

Parameters:

Name	Type	Description	Default
panel	str	the panel to use in from_node and to select input sockets	required
from_node	Node	node to get output sockets from	None

Returns:

Type	Description
self

Source code in core/nodeclass.py

def link_panel(self, panel: str, from_node : Node = None):
    """ Link panel input sockets from another node

    If from_node is None, the current input node is taken.

    see `link_inputs``

    Call:

    ```python
        return self.link_inputs(from_node=from_node, from_panel=panel, panel=panel)
    ```

    Parameters
    ----------
    panel : str
        the panel to use in from_node and to select input sockets

    from_node : Node, default=None
        node to get output sockets from

    Returns
    -------
    self
    """
    if isinstance(panel, str):
        return self.link_inputs(from_node=from_node, from_panel=panel, panel=panel)

    for s in panel:
        self.link_panel(s, from_node=from_node)

    return self

method_call(*args, ret_class=None, **kwargs)

Link the input sockets with method arguments

Parameters:

Name	Type	Description	Default
args	tuple	values of the first sockets (but self_ if not None)	()
ret_class	type	output class	None
kwargs	dict	named sockets	{}

Returns:

Type	Description
Socket	node._out

Source code in core/nodeclass.py

def method_call(self, *args, ret_class = None, **kwargs):
    """ Link the input sockets with method arguments

    Parameters
    ----------
    args : tuple
        values of the first sockets (but self_ if not None)

    ret_class : type
        output class

    kwargs : dict
        named sockets


    Returns
    -------
    Socket
        node._out

    """

    # ------------------------------------------------------------
    # Get the valid input sockets
    # ------------------------------------------------------------

    sockets = self.get_sockets('INPUT', enabled_only = False, free_only = False)

    # For error message
    sig = self.get_signature()
    ssocks = []
    for index, d in enumerate(sig.inputs):
        s = f"{utils.snake_case(d['name']):15s} : {SocketType.from_type(d['socket_type']).class_name}"
        if index < len(args):
            s += " (arg)"
        ssocks.append(s)
    valids = "\n- " + "\n- ".join(ssocks)

    # The number of arguments must not exceed the number of valid sockets
    n = len(args) + len(kwargs)
    if n > len(sockets):
        raise NodeError(
            f"Error when calling {self}: too many arguments.\n"
            f"The node has only {len(sockets)} input sockets but {n} arguments are provided.\n"
            f"Valid sockets are: {valids}\n")

    # ------------------------------------------------------------
    # Sockets set by arguments
    # ------------------------------------------------------------

    n = len(args)        
    arg_sockets = list(sockets[:n])
    remain      = list(sockets[n:])

    dones = []

    for (name, socket), arg in zip(arg_sockets, args):

        dones.append(f"{socket.name} <- <{arg}> (arg)")

        try:
            self.set_input_socket_value(socket, arg)

        except Exception as e:

            sdones = "\n - " + "\n - ".join(dones)

            raise NodeError(
                f"Error when calling '{self}': impossible to set the socket '{socket.name}' with value <{arg}>.\n"
                f"Valid sockets are: {valids}\n"
                f"Sockets successfully set:{sdones}")

    # ------------------------------------------------------------
    # Sockets set by key word arguments
    # ------------------------------------------------------------

    for name, value in kwargs.items():
        self.set_input_socket(name, value)

    # ------------------------------------------------------------
    # Done
    # ------------------------------------------------------------

    if ret_class is None:
        return self._out
    else:
        return ret_class(self._out)

out(panel='')

Plug the output sockets to the current tree output.

Parameters:

Name	Type	Description	Default
panel	str	panel to create the output sockets into	""

Source code in core/nodeclass.py

def out(self, panel: str = ""):
    """ Plug the output sockets to the current tree output.

    Parameters
    ----------
    panel : str, default=""
        panel to create the output sockets into

    """
    self.link_outputs(None, to_panel=panel)

set_input_socket(name, value, create=True, panel='', python_name=False, **props)

Set a value to an input socket.

If name is None (for instance when called by Socket.out()): - The first free input socket of the proper type is chosen - If not found, a socket is created when possible

Parameters:

Name	Type	Description	Default
name	Socket | str | int | None	socket name of socket index	required
value	Socket or any value	value to set to the socket	required
create	bool	create the value (only for node with dynamic input sockets) default=True.	True
panel	str	creation panel default="".	''
python_name	bool	Whether name comes from a Python keyword. Underscores are replaced by spaces only when a dynamic socket is created.	False
props	dict	additional properties (ignored)	{}

Raises:

Type	Description
- AttributeError or IndexError if not found

Returns:

Type	Description
The input socket

Source code in core/nodeclass.py

def set_input_socket(self, 
        name    : str | int, 
        value   : Any, 
        create  : bool = True, 
        panel   : str="",
        python_name : bool = False,
        **props):
    """ Set a value to an input socket.

    If name is None (for instance when called by Socket.out()):
    - The first free input socket of the proper type is chosen
    - If not found, a socket is created when possible

    Parameters
    ----------
    name : Socket | str | int | None
        socket name of socket index

    value : Socket or any value
        value to set to the socket

    create : bool, optional
        create the value (only for node with dynamic input sockets) default=True.

    panel : str, optional
        creation panel default="".

    python_name : bool, optional
        Whether ``name`` comes from a Python keyword. Underscores are
        replaced by spaces only when a dynamic socket is created.

    props : dict
        additional properties (ignored)


    Raises
    ------
    - AttributeError or IndexError if not found

    Returns
    -------
    The input socket
    """

    # ====================================================================================================
    # Multi input socket set with a list of value
    # ====================================================================================================

    is_multi = name in self._inputs._multi_names
    if is_multi and isinstance(value, list):
        sockets = []
        # Reversed for join strings !
        for v in reversed(value):
            sockets.append(self.set_input_socket(
                name, v, create=False, panel=panel, python_name=python_name))
        return sockets

    # ====================================================================================================
    # The socket is set, it can ignored in a further link_inputs
    # ====================================================================================================

    if value is not None:
        self._link_ignore.append(name)

    # ====================================================================================================
    # No value: nothing to do, otherwise let's read the socket type
    # ====================================================================================================

    # If Value is None, the type is Geometry
    # We don't exit at this stage because it could be a request to create an input socket

    value_socket_type = SocketType(value)

    # ----------------------------------------------------------------------------------------------------
    # Special naming
    # ----------------------------------------------------------------------------------------------------

    # Name can be the socket index or its identifier

    found_socket = None
    if not self._has_dyn_in and name is not None:
        if isinstance(name, int):
            found_socket = self._bnode.inputs[name]
        else:
            for s in self._bnode.inputs:
                if s.identifier == name:
                    found_socket = s
                    break

    # ----------------------------------------------------------------------------------------------------
    # Virtual socket : the input socket must exist (or auto data type)
    # ----------------------------------------------------------------------------------------------------

    if value_socket_type.is_virtual:

        auto = self._bnode.bl_idname in constants.AUTO_INPUT_TYPE_NODES
        halt = name is not None and not auto

        if name is None:
            full_name = None
        else:
            full_name = (ItemPath(panel) + name).path

        # The socket must exist
        if found_socket is None:
            in_socket = self.get_socket('INPUT', full_name, value_socket_type, free_only=True, halt=halt)
        else:
            in_socket = found_socket

        # However, if auto data type we can create it
        if in_socket is None and auto:
            in_socket = self.create_socket('INPUT', None, name=name, panel=panel, **props)

        # Error
        if in_socket is None:
            raise NodeError(
                "Impossible plug an new Input to a new Output socket.\n"
                "You tried to create a new input socket named '{name}' in node {self}. "
                "But you used the virtual socket Input which has not type. "
                "It is impossible to identify the type of socket you want to create.\n"
                f"Use Float(name='{name}') rather than Input('{name}') to create a Float socket for instance."
                )

        # Create / link the output socket
        value.node.create_from_socket('OUTPUT', in_socket, name=value.name, panel=value.panel, **value.props)

        return in_socket

    # ===========================================================================
    # Name is None: value must be a socket
    # ===========================================================================

    if name is None:
        # Specific case: index switch doesn't need a name to create a new socket
        if self._bnode.bl_idname == 'GeometryNodeIndexSwitch':
            name = str(len(self._bnode.index_switch_items) + 1)

    if name is None:

        # ----- First free input socket

        for _, socket in self.get_sockets('INPUT', free_only=True, panel=panel):

            if socket.type == value_socket_type.type:
                self._tree.link(value, socket)
                return socket

        # ----- Not found : we should be able to create it

        if not (create and self._has_dyn_in):
            raise NodeError(f"Error when setting an input socket to node {self}: no free input socket found for socket {value} of type: {value_socket_type.type}.")

        name = self.get_socket_default_name('OUTPUT', value)

    # ===========================================================================
    # Name is not None
    # ===========================================================================

    # ---------------------------------------------------------------------------
    # Get the input socket by its name
    # ---------------------------------------------------------------------------

    create_socket = create and self._has_dyn_in
    if found_socket is None:
        full_name = (ItemPath(panel) + name).path
        socket = self.get_socket('INPUT', full_name, value_socket_type, free_only=True, halt=not create_socket)
    else:
        socket = found_socket

    # ---------------------------------------------------------------------------
    # Create the dynamic socket
    # ---------------------------------------------------------------------------

    if socket is None:

        if python_name and isinstance(name, str):
            name = name.replace('_', ' ')

        if utils.get_bsocket(value) is not None and SocketType(value) == SocketType(utils.get_bsocket(value)):
            return self.create_from_socket('INPUT', value, name=name, panel=panel, **props)

        socket_type = SocketType(value)
        socket = self.create_socket('INPUT', socket_type, name=name, panel=panel, **props)

        # Menus
        if self._is_menu_switch:
            if self._default_menu == "":
                self._default_menu = name


    # ===========================================================================
    # Set a value to the socket
    # ===========================================================================

    return self.set_input_socket_value(socket, value)

set_input_socket_value(socket, value)

Set a value to an input socket

Parameters:

Name	Type	Description	Default
socket	Socket	the input socket	required
value	Any	the value to set	required

Returns:

Type	Description
socket

Source code in core/nodeclass.py

def set_input_socket_value(self, socket, value):
    """ Set a value to an input socket

    Parameters
    ----------
    socket : Socket
        the input socket

    value : Any
        the value to set


    Returns
    -------
    socket
    """

    if value is None:
        return socket

    # ---------------------------------------------------------------------------
    # We take default value from empty socket
    # ---------------------------------------------------------------------------

    if utils.is_empty_socket(value):
        value = value._bsocket

    # ---------------------------------------------------------------------------
    # If the value is a Node, we take its default output socket
    # ---------------------------------------------------------------------------

    if '_bnode' in dir(value):
        value = value._out

    # ---------------------------------------------------------------------------
    # If the value is a domain, we take its geometry
    # ---------------------------------------------------------------------------

    if '_geo' in dir(value):
        value = value._geo

    # ---------------------------------------------------------------------------
    # We directly have a socket
    # ---------------------------------------------------------------------------

    out_socket = utils.get_bsocket(value)
    if out_socket is not None:
        return self._tree.link(out_socket, socket)

    # ---------------------------------------------------------------------------
    # We need to create a node if:
    # - in_socket.hide_value is True
    # - the value is an array containing sockets : vector((0, a, 1))
    # ---------------------------------------------------------------------------

    socket_type = SocketType(socket)
    if socket.hide_value:
        self._tree.link(utils.to_socket(value)._bsocket, socket)
        return socket

    # ---------------------------------------------------------------------------
    # Setting according to the socket type
    # ---------------------------------------------------------------------------

    if socket_type.type in constants.ARRAY_TYPES:

        if not hasattr(socket, 'default_value'):
            raise NodeError(f"Impossible to set the input socket {self}.'{socket.name}' with the value: <{value}>.")

        if socket_type.type == 'RGBA':
            a = SysColor(value).rgba

        else:
            spec = constants.ARRAY_TYPES[socket_type.type]
            a = utils.value_to_array(value, spec['shape'])

        # There is a bsocket in the array
        if utils.has_bsocket(a):
            v = utils.get_socket_class(socket_type)(a)
            self._tree.link(v, socket)

        else:
            try:
                socket.default_value = list(a)
            except Exception as e:
                raise NodeError(f"Impossible to set input socket [{socket.node.name}].{socket.name} with value <{value}>. {str(e)}")

    elif socket_type.class_name in ['Boolean', 'Integer', 'Float', 'String']:
        try:
            socket.default_value = value
        except Exception as e:
            raise NodeError(f"Impossible to set input socket [{socket.node.name}].{socket.name} with value <{value}>. {str(e)}")

    elif socket.type in ['OBJECT', 'COLLECTION', 'IMAGE', 'MATERIAL']:

        bobj = blender.get_resource(socket.type, value)

        if bobj is not None:
            socket.default_value = bobj

    elif socket.type == 'FONT':
        socket.default_value = blender.get_font(value)

    elif socket.type == 'MENU':

        try:    
            socket.default_value = str(value)

        except TypeError as te:
            s = str(te)
            nfi = "not found in "
            p = s.find(nfi)
            valids = eval(s[p + len(nfi):])

            ok = False
            sval = str(value).lower()
            for itm in valids:
                if itm.lower() == sval:
                    socket.default_value = itm
                    ok = True
                    break

            if not ok:
                raise NodeError(f"Impossible to set menu [{socket.node.name}]{socket.name} with value <{value}>. {str(te)}")

        except Exception as e:
            raise NodeError(f"Impossible to set menu [{socket.node.name}]{socket.name} with value <{value}>. {str(e)}")


    else:
        raise TypeError(f"Impossible to set input socket [{socket.node.name}].{socket.name} with value <{value}>. Unsupported socket type '{socket.type}'.")


    return socket

set_parameter(name, value, halt=True)

Set a node parameter

Arguments name : str parameter name

value : any parameter value

halt : bool, optional raise an error if name is not a parameter default=True.

Returns:

Type	Description
str	parameter name if properly set, None otherwise

Source code in core/nodeclass.py

def set_parameter(self, name: str, value, halt: bool = True):
    """ Set a node parameter

    Arguments
    name : str
        parameter name

    value : any
        parameter value

    halt : bool, optional
        raise an error if name is not a parameter default=True.


    Returns
    -------
    str
        parameter name if properly set, None otherwise

    """
    from .constants import NODE_INFO

    node_info = NODE_INFO[self._bnode.bl_idname]
    params = node_info['params']

    param_name = name

    prop = self._bnode.bl_rna.properties.get(param_name)
    if prop is None:
        if halt:
            raise NodeError(
                f"Node {self} doesn't have a parameter named '{name}'. "
                f"Valid parameters are: {list(params.keys())}.")
        else:
            return None

    if value is None:
        return param_name

    # ---------------------------------------------------------------------------
    # Enum validation
    # ---------------------------------------------------------------------------

    # Alternate value
    alt_value = None

    if prop.type == 'ENUM':

        if param_name in ['data_type', 'input_type']:
            param_value = value
            alt_value = SocketType.convert_type_for_node(value, self._bnode.bl_idname, param_name, on_error='HALT' if halt else 'DEFAULT')

        # Font
        elif param_name == 'font' and isinstance(value, str):
            param_value = blender.get_font(value)

        else:
            param_value = value

        if prop.is_enum_flag:

            if isinstance(param_value, str):
                param_value = set(param_value)

            values = set()
            for v in param_value:
                lvalue = v.lower()

                ok = False
                for enum_item in prop.enum_items:
                    if lvalue in (enum_item.name.lower(), enum_item.identifier.lower()):
                        values.add(enum_item.identifier)
                        ok = True
                        break

                if not ok:
                    raise NodeError(f"Value '{v}' is not valid for node parameter [{self._bnode.name}].{name}.\n"
                        f"Valid values are {[enum_item.name for enum_item in prop.enum_items]}.")

            setattr(self._bnode, param_name, values)

        else:
            lvalue = param_value.lower()

            for enum_item in prop.enum_items:
                if lvalue in (enum_item.name.lower(), enum_item.identifier.lower()):
                    setattr(self._bnode, param_name, enum_item.identifier)
                    return param_name

            if alt_value is not None:
                setattr(self._bnode, param_name, alt_value)
                return param_name

            raise NodeError(f"Value '{param_value}' is not valid for node parameter [{self._bnode.name}].{name}.\n"
                f"Valid values are {[enum_item.name for enum_item in prop.enum_items]},\n"
                f"or {[enum_item.identifier for enum_item in prop.enum_items]},"
                )

    # ---------------------------------------------------------------------------
    # Not enum
    # ---------------------------------------------------------------------------

    else:
        setattr(self._bnode, param_name, value)

    return param_name

set_signature(in_out, signature, panel='')

Set the signature .

Parameters:

Name	Type	Description	Default
in_out	'INPUT, 'OUTPUT', 'BOTH'	input or output sockets or both	'INPUT
signature	Signature	the signature to apply	required
panel	str	the panel where to create the sockets default="".	''

Returns:

Type	Description
dict of created sockets

Source code in core/nodeclass.py

def set_signature(self, 
    in_out      : Literal['INPUT', 'OUTPUT', 'BOTH'],
    signature   : Signature,
    panel       : str = ""):
    """ Set the signature .

    Parameters
    ----------
    in_out : {'INPUT, 'OUTPUT', 'BOTH'}
        input or output sockets or both

    signature : Signature
        the signature to apply

    panel : str, optional
        the panel where to create the sockets default="".


    Returns
    -------
    dict of created sockets
    """

    signature = Signature(signature)

    sigs = {}
    if in_out == 'INPUT':
        sigs['INPUT'] = signature.sockets
    elif in_out == 'OUTPUT':
        sigs['OUTPUT'] = signature.sockets
    else:
        sigs['INPUT'] = signature.inputs
        sigs['OUTPUT'] = signature.outputs

    created = {}

    for io, sockets in sigs.items():

        created[io] = {}

        for spec in sockets: #.items():
            name = spec['name']
            socket = spec.get('socket')

            if socket is None:
                stype = spec.get('bl_idname', spec.get('socket_type', 'VALUE'))
                created[io][name] = self.create_socket(io, stype, name=name, panel=panel)
            else:
                created[io][name] = self.create_from_socket(io, socket, name=name, panel=panel)

    return created

socket_by_index(in_out, index, enabled_only=True)

Get a socket by its index

Parameters:

Name	Type	Description	Default
in_out	(INPUT, OUTPUT)	input or output sockets	'INPUT'
index	int	socket index	required
enabled_only	bool	(bool = True) : ignore disabled sockets	True

Raises:

Type	Description
- IndexError if index is incorrect

Returns:

Type	Description
Socket

Source code in core/nodeclass.py

def socket_by_index(self, 
        in_out       : IN_OUT, 
        index        : int, 
        enabled_only : bool = True) -> Socket:
    """ Get a socket by its index

    Parameters
    ----------
    in_out : {'INPUT', 'OUTPUT'}
        input or output sockets

    index : int
        socket index

    enabled_only
        (bool = True) : ignore disabled sockets


    Raises
    ------
    - IndexError if index is incorrect

    Returns
    -------
    Socket
    """
    sockets = self.get_sockets(in_out, enabled_only=enabled_only)
    return sockets[index][1]

socket_by_name(in_out, name, socket_type, enabled_only=True, free_only=False, halt=True)

Get a socket by its name

Get a socket by its name. Valid names are: - The socket name possibly suffixed by its rank (e.g. value_1 for second socket named Value) - The python version

Parameters:

Name	Type	Description	Default
in_out	(INPUT, OUTPUT)	input or output sockets	'INPUT'
name	str	socket name	required
socket_type	str	socket_type	required
enabled_only	bool	ignore disabled sockets default=True	True
free_only	bool	ignore linked sockets default=False.	False
halt	bool	raises an error if not found default=True.	True

Raises:

Type	Description
- AttributeError if name not found

Returns:

Type	Description
Socket

Source code in core/nodeclass.py

def socket_by_name(self, 
        in_out       : IN_OUT, 
        name         : str, 
        socket_type  : str, 
        enabled_only : bool = True, 
        free_only    : bool = False, 
        halt         : bool = True) -> Socket:
    """ Get a socket by its name

    Get a socket by its name. Valid names are:
    - The socket name possibly suffixed by its rank (e.g. `value_1` for second socket named Value)
    - The python version

    Parameters
    ----------
    in_out : {'INPUT', 'OUTPUT'}
        input or output sockets

    name : str
        socket name

    socket_type : str
        socket_type

    enabled_only : bool
        ignore disabled sockets default=True

    free_only : bool, optional
        ignore linked sockets default=False.

    halt : bool, optional
        raises an error if not found default=True.


    Raises
    ------
    - AttributeError if name not found

    Returns
    -------
    Socket
    """

    # ====================================================================================================
    # Get from tree interface
    # ====================================================================================================

    if self._use_interface:

        intf_in_out = self._interface_in_out[in_out]
        if intf_in_out is not None:

            # All the interface socket matching the provided name
            # First With type

            isocks = self._interface.get_socket_by_python_name(
                intf_in_out, name, socket_type, parent=self._tree.get_panel(), return_all=True)

            #print("DEBUG NODE 0", name, socket_type, '-->', isocks)

            # Second without type
            if not len(isocks):
                isocks = self._interface.get_socket_by_python_name(
                    intf_in_out, name, None, parent=self._tree.get_panel(), return_all=True)

            #print("DEBUG NODE 1", name, '-->', isocks)

            # Look for the first one matching the conditions
            for isock in isocks:
                socket = self.socket_by_identifier(in_out, isock.identifier)
                bsocket = utils.get_bsocket(socket)

                if enabled_only and not bsocket.enabled:
                    continue

                if in_out == 'INPUT' and free_only and not utils.is_free(socket):
                    continue

                return socket

        if halt:
            if intf_in_out is None:
                valids = []
            else:
                valids = [s.name for s in self._interface.get_sockets(intf_in_out)]

            raise NodeError(f"Node {self} doesn't own an {intf_in_out} socket named '{name}'.\nValids are {valids}")

        return None

    # ====================================================================================================
    # No tree interface
    # ====================================================================================================

    path = ItemPath(name).ranked_long_name

    socks = self._inputs if in_out == 'INPUT' else self._outputs
    socket = socks.by_name(path)

    if socket is None:
        if halt:
            raise NodeError(f"Node {self} doesn't own an {in_out} socket named '{name}'. Valid names are {socks.names}")

    return socket