nodebpy 520.40.0__tar.gz → 520.41.0__tar.gz

{nodebpy-520.40.0 → nodebpy-520.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nodebpy
-Version: 520.40.0
+Version: 520.41.0
 Summary: Build nodes trees in Blender more elegantly with code
 Keywords: blender,bpy,nodes,geometry-nodes,shader,compositor,procedural
 Author: Brady Johnston

{nodebpy-520.40.0 → nodebpy-520.41.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nodebpy"
-version = "520.40.0"
+version = "520.41.0"
 description = "Build nodes trees in Blender more elegantly with code"
 readme = "README.md"
 authors = [

{nodebpy-520.40.0 → nodebpy-520.41.0}/src/nodebpy/builder/items.py

@@ -246,6 +246,10 @@ class Item(Generic[_InT, _OutT]):
     def name(self) -> str:
         return self._item.name
 
+    @name.setter
+    def name(self, value: str) -> None:
+        self._item.name = value
+
     @property
     def socket_type(self) -> str:
         # some collections (capture_items, grid_items) call this data_type

{nodebpy-520.40.0 → nodebpy-520.41.0}/src/nodebpy/builder/mixins.py

@@ -346,6 +346,11 @@ class LinkingMixin:
                 (i for i in inputs if i.identifier.startswith("__extend__")), None
             )
             if extend is not None and outputs:
+                # a node with several (For Each's main and generation items)
+                # picks the one the source's type belongs to
+                pick = getattr(target, "_extend_input", None)
+                if pick is not None:
+                    extend = pick(outputs[0])
                 return extend, outputs[0]
             return None
 

{nodebpy-520.40.0 → nodebpy-520.41.0}/src/nodebpy/export/codegen.py

@@ -35,7 +35,15 @@ from types import ModuleType
 from typing import TYPE_CHECKING, Any, Literal, NamedTuple
 
 import numpy as np
-from bpy.types import ID, FunctionNodeCompare, Node, NodeSocket, NodeTree
+from bpy.types import (
+    ID,
+    FunctionNodeCompare,
+    Material,
+    Node,
+    NodeSocket,
+    NodeTree,
+    World,
+)
 
 from ..types import Default
 from ._floats import (
@@ -4141,7 +4149,7 @@ def _format_with_ruff(code: str) -> str:
 
 
 def to_python(
-    tree: NodeTree | TreeBuilder[Any],
+    tree: NodeTree | TreeBuilder[Any] | Material | World,
     min_chain_length: int = 3,
     strict: bool = True,
     max_inline_width: int | None = 88,
@@ -4163,8 +4171,10 @@ def to_python(
 
     Parameters
     ----------
-    tree: TreeBuilder[Any] | bpy.types.NodeTree
-        The node tree to export.
+    tree: TreeBuilder[Any] | bpy.types.NodeTree | bpy.types.Material | bpy.types.World
+        The node tree to export. With ``top_level="with"``, a material or
+        world (or its node tree) is rebuilt with ``s.material(...)`` /
+        ``s.world(...)``.
     min_chain_length: int
         Minimum number of items (including interface endpoints) for a linear
         pipeline to be expressed with ``>>`` syntax; shorter runs are emitted
@@ -4267,7 +4277,18 @@ def to_python(
     str
         Python source code as a string.
     """
+    owner: Material | World | None = None
+    if isinstance(tree, (Material, World)):
+        owner = tree
+        tree = tree.node_tree  # ty: ignore[invalid-assignment]
     node_tree: NodeTree = tree.tree if hasattr(tree, "tree") else tree  # ty: ignore[invalid-assignment]
+    if not isinstance(node_tree, NodeTree):
+        raise TypeError(
+            "to_python() takes a node tree, TreeBuilder, material or world, "
+            f"not {type(tree).__name__}"
+        )
+    if owner is None and node_tree.is_embedded_data:
+        owner = _embedded_tree_owner(node_tree)
 
     class_names = dict(group_class_names or {})
     externals = set(external_groups or ())
@@ -4328,6 +4349,8 @@ def to_python(
     else:
         emission = _emit_tree(node_tree, collector)
         used_aliases = emission.used_aliases | collector.used_aliases
+        if owner is not None:
+            used_aliases.add("s")
 
     # 5. Assemble the module: imports, group classes, then the tree block (only
     #    in "with" mode), each top-level block separated by two blank lines.
@@ -4371,6 +4394,9 @@ def to_python(
 
         constructor = _TREE_CONSTRUCTORS.get(node_tree.bl_idname, "TreeBuilder")
         ctor_args = [_fmt(node_tree.name)]
+        if owner is not None:
+            constructor = "s.material" if isinstance(owner, Material) else "s.world"
+            ctor_args = [_fmt(owner.name)]
         # Auto-layout dissolves reroutes and overwrites locations, so disable it
         # for either option.
         if snapshot_positions or keep_reroutes:
@@ -5032,6 +5058,16 @@ def _render_group_class(
     return "\n".join(header + body)
 
 
+def _embedded_tree_owner(node_tree: NodeTree) -> Material | World | None:
+    """The material or world whose node tree ``node_tree`` is, if any."""
+    import bpy
+
+    for owner in (*bpy.data.materials, *bpy.data.worlds):
+        if owner.node_tree == node_tree:
+            return owner
+    return None
+
+
 def _emit_tree(node_tree, collector: _GroupCollector) -> _TreeEmission:
     """Generate the interface/body/output lines for one tree. Nested group
     nodes register their classes on ``collector`` as a side effect."""
@@ -6557,17 +6593,6 @@ def _emit_foreach_input(node, ctx: EmitContext) -> _Val:
         f"    {zone_ref.name} = {Call(ctor, kwargs=kwargs).render()}"
     )
 
-    generation_items = list(out_node.generation_items)
-    if (
-        not generation_items
-        or generation_items[0].socket_type != "GEOMETRY"
-        or generation_items[0].name != "Geometry"
-    ):
-        raise CodegenError(
-            f"foreach zone '{node.name}': the first generation item is not "
-            "the default Geometry item, which the zone wrapper cannot rebuild"
-        )
-
     plans: list[_ZoneItemPlan] = []
     in_inputs = _prefixed_sockets(node, "Input_")
     in_outputs = _prefixed_sockets(node, "Input_", output=True)
@@ -6603,9 +6628,7 @@ def _emit_foreach_input(node, ctx: EmitContext) -> _Val:
         )
     gen_inputs = _prefixed_sockets(out_node, "Generation_")
     gen_outputs = _prefixed_sockets(out_node, "Generation_", output=True)
-    for i, item in enumerate(generation_items):
-        if i == 0:
-            continue  # the wrapper creates the default Geometry item itself
+    for i, item in enumerate(out_node.generation_items):
         extra: dict[str, Expr] = {}
         if item.domain != "POINT":
             extra["domain"] = Lit(item.domain)
@@ -6628,8 +6651,6 @@ def _emit_foreach_input(node, ctx: EmitContext) -> _Val:
     )
     current_map["Index"] = Attr(zone_ref, "index")
     current_map["Element"] = Attr(zone_ref, "input.o.element")
-    targets[gen_inputs[0].identifier] = Attr(zone_ref, "generation.input")
-    outputs[gen_outputs[0].identifier] = Attr(zone_ref, "generation.output")
     outputs["Geometry"] = Attr(zone_ref, "output")
 
     ctx.zones[out_node.name] = _ZoneState(targets, outputs)

{nodebpy-520.40.0 → nodebpy-520.41.0}/src/nodebpy/nodes/compositor/distort.py

@@ -616,21 +616,43 @@ class MovieDistortion(BaseNode):
         self,
         image: InputColor = (0.8, 0.8, 0.8, 1.0),
         type: InputMenu | Literal["Undistort", "Distort"] = "Undistort",
+        *,
+        clip: bpy.types.MovieClip | None = None,
     ):
         super().__init__()
         key_args = {"Image": image, "Type": type}
 
         self._establish_links(**key_args)
+        if clip is not None:
+            self.clip = clip
 
     @classmethod
-    def undistort(cls, image: InputColor = (0.8, 0.8, 0.8, 1.0)) -> "MovieDistortion":
+    def undistort(
+        cls,
+        image: InputColor = (0.8, 0.8, 0.8, 1.0),
+        *,
+        clip: bpy.types.MovieClip | None = None,
+    ) -> "MovieDistortion":
         """Create Movie Distortion node with type 'Undistort'."""
-        return cls(image=image, type="Undistort")
+        return cls(image=image, clip=clip, type="Undistort")
 
     @classmethod
-    def distort(cls, image: InputColor = (0.8, 0.8, 0.8, 1.0)) -> "MovieDistortion":
+    def distort(
+        cls,
+        image: InputColor = (0.8, 0.8, 0.8, 1.0),
+        *,
+        clip: bpy.types.MovieClip | None = None,
+    ) -> "MovieDistortion":
         """Create Movie Distortion node with type 'Distort'."""
-        return cls(image=image, type="Distort")
+        return cls(image=image, clip=clip, type="Distort")
+
+    @property
+    def clip(self) -> bpy.types.MovieClip | None:
+        return self.node.clip
+
+    @clip.setter
+    def clip(self, value: bpy.types.MovieClip | None) -> None:
+        self.node.clip = value
 
 
 class PlaneTrackDeform(BaseNode):
@@ -703,6 +725,7 @@ class PlaneTrackDeform(BaseNode):
         samples: InputInteger = 16,
         shutter: InputFloat = 0.5,
         *,
+        clip: bpy.types.MovieClip | None = None,
         tracking_object: str = "",
         plane_track_name: str = "",
     ):
@@ -716,6 +739,16 @@ class PlaneTrackDeform(BaseNode):
         self.tracking_object = tracking_object
         self.plane_track_name = plane_track_name
         self._establish_links(**key_args)
+        if clip is not None:
+            self.clip = clip
+
+    @property
+    def clip(self) -> bpy.types.MovieClip | None:
+        return self.node.clip
+
+    @clip.setter
+    def clip(self, value: bpy.types.MovieClip | None) -> None:
+        self.node.clip = value
 
     @property
     def tracking_object(self) -> str:
@@ -1084,6 +1117,8 @@ class Stabilize2D(BaseNode):
         | Literal["Nearest", "Bilinear", "Bicubic", "Anisotropic"] = "Bilinear",
         extension_x: InputMenu | Literal["Clip", "Extend", "Repeat"] = "Clip",
         extension_y: InputMenu | Literal["Clip", "Extend", "Repeat"] = "Clip",
+        *,
+        clip: bpy.types.MovieClip | None = None,
     ):
         super().__init__()
         key_args = {
@@ -1096,6 +1131,16 @@ class Stabilize2D(BaseNode):
         }
 
         self._establish_links(**key_args)
+        if clip is not None:
+            self.clip = clip
+
+    @property
+    def clip(self) -> bpy.types.MovieClip | None:
+        return self.node.clip
+
+    @clip.setter
+    def clip(self, value: bpy.types.MovieClip | None) -> None:
+        self.node.clip = value
 
 
 class Transform(BaseNode):

{nodebpy-520.40.0 → nodebpy-520.41.0}/src/nodebpy/nodes/compositor/filter.py

@@ -612,6 +612,7 @@ class Defocus(BaseNode):
         image: InputColor = (1.0, 1.0, 1.0, 1.0),
         z: InputFloat = 1.0,
         *,
+        scene: bpy.types.Scene | None = None,
         bokeh: Literal[
             "OCTAGON", "HEPTAGON", "HEXAGON", "PENTAGON", "SQUARE", "TRIANGLE", "CIRCLE"
         ] = "CIRCLE",
@@ -630,6 +631,16 @@ class Defocus(BaseNode):
         self.use_zbuffer = use_zbuffer
         self.z_scale = z_scale
         self._establish_links(**key_args)
+        if scene is not None:
+            self.scene = scene
+
+    @property
+    def scene(self) -> bpy.types.Scene | None:
+        return self.node.scene
+
+    @scene.setter
+    def scene(self, value: bpy.types.Scene | None) -> None:
+        self.node.scene = value
 
     @property
     def bokeh(

{nodebpy-520.40.0 → nodebpy-520.41.0}/src/nodebpy/nodes/compositor/input.py

@@ -399,6 +399,8 @@ class Mask(BaseNode):
         motion_blur: InputBoolean = False,
         samples: InputInteger = 16,
         shutter: InputFloat = 0.5,
+        *,
+        mask: bpy.types.Mask | None = None,
     ):
         super().__init__()
         key_args = {
@@ -412,6 +414,16 @@ class Mask(BaseNode):
         }
 
         self._establish_links(**key_args)
+        if mask is not None:
+            self.mask = mask
+
+    @property
+    def mask(self) -> bpy.types.Mask | None:
+        return self.node.mask
+
+    @mask.setter
+    def mask(self, value: bpy.types.Mask | None) -> None:
+        self.node.mask = value
 
 
 class MovieClip(BaseNode):
@@ -461,11 +473,21 @@ class MovieClip(BaseNode):
         @property
         def o(self) -> _Outputs: ...
 
-    def __init__(self) -> None:
+    def __init__(self, clip: bpy.types.MovieClip | None = None):
         super().__init__()
         key_args = {}
 
         self._establish_links(**key_args)
+        if clip is not None:
+            self.clip = clip
+
+    @property
+    def clip(self) -> bpy.types.MovieClip | None:
+        return self.node.clip
+
+    @clip.setter
+    def clip(self, value: bpy.types.MovieClip | None) -> None:
+        self.node.clip = value
 
 
 class Normal(BaseNode):
@@ -533,11 +555,25 @@ class RenderLayers(BaseNode):
         @property
         def o(self) -> _Outputs: ...
 
-    def __init__(self, layer: str = "ViewLayer"):
+    def __init__(
+        self,
+        scene: bpy.types.Scene | None = None,
+        layer: str = "ViewLayer",
+    ):
         super().__init__()
         key_args = {}
         self.layer = layer
         self._establish_links(**key_args)
+        if scene is not None:
+            self.scene = scene
+
+    @property
+    def scene(self) -> bpy.types.Scene | None:
+        return self.node.scene
+
+    @scene.setter
+    def scene(self, value: bpy.types.Scene | None) -> None:
+        self.node.scene = value
 
     @property
     def layer(self) -> str:
@@ -855,6 +891,7 @@ class TrackPosition(BaseNode):
         ] = "Absolute",
         frame: InputInteger = 0,
         *,
+        clip: bpy.types.MovieClip | None = None,
         tracking_object: str = "",
         track_name: str = "",
     ):
@@ -863,6 +900,16 @@ class TrackPosition(BaseNode):
         self.tracking_object = tracking_object
         self.track_name = track_name
         self._establish_links(**key_args)
+        if clip is not None:
+            self.clip = clip
+
+    @property
+    def clip(self) -> bpy.types.MovieClip | None:
+        return self.node.clip
+
+    @clip.setter
+    def clip(self, value: bpy.types.MovieClip | None) -> None:
+        self.node.clip = value
 
     @property
     def tracking_object(self) -> str:

{nodebpy-520.40.0 → nodebpy-520.41.0}/src/nodebpy/nodes/compositor/matte.py

@@ -1105,12 +1105,23 @@ class KeyingScreen(BaseNode):
         self,
         smoothness: InputFloat = 0.0,
         *,
+        clip: bpy.types.MovieClip | None = None,
         tracking_object: str = "",
     ):
         super().__init__()
         key_args = {"Smoothness": smoothness}
         self.tracking_object = tracking_object
         self._establish_links(**key_args)
+        if clip is not None:
+            self.clip = clip
+
+    @property
+    def clip(self) -> bpy.types.MovieClip | None:
+        return self.node.clip
+
+    @clip.setter
+    def clip(self, value: bpy.types.MovieClip | None) -> None:
+        self.node.clip = value
 
     @property
     def tracking_object(self) -> str:

{nodebpy-520.40.0 → nodebpy-520.41.0}/src/nodebpy/nodes/geometry/input.py

@@ -1562,11 +1562,21 @@ class Font(BaseNode):
         @property
         def o(self) -> _Outputs: ...
 
-    def __init__(self) -> None:
+    def __init__(self, font: bpy.types.VectorFont | None = None):
         super().__init__()
         key_args = {}
 
         self._establish_links(**key_args)
+        if font is not None:
+            self.font = font
+
+    @property
+    def font(self) -> bpy.types.VectorFont | None:
+        return self.node.font
+
+    @font.setter
+    def font(self, value: bpy.types.VectorFont | None) -> None:
+        self.node.font = value
 
 
 class HandleTypeSelection(_HandleModeMixin, BaseNode):
@@ -1697,11 +1707,21 @@ class Image(BaseNode):
         @property
         def o(self) -> _Outputs: ...
 
-    def __init__(self) -> None:
+    def __init__(self, image: bpy.types.Image | None = None):
         super().__init__()
         key_args = {}
 
         self._establish_links(**key_args)
+        if image is not None:
+            self.image = image
+
+    @property
+    def image(self) -> bpy.types.Image | None:
+        return self.node.image
+
+    @image.setter
+    def image(self, value: bpy.types.Image | None) -> None:
+        self.node.image = value
 
 
 class ImageInfo(BaseNode):

{nodebpy-520.40.0 → nodebpy-520.41.0}/src/nodebpy/nodes/geometry/zone.py

@@ -637,6 +637,9 @@ class ForEachGeometryElementZone(_ZonePair):
         self.input = ForEachGeometryElementInput()
         self.output = ForEachGeometryElementOutput()
         self._pair()
+        # Like the other zones, start without Blender's default Geometry item;
+        # declare generated geometry with ``generated_items.geometry()``.
+        self.output.node.generation_items.clear()
         self.output.domain = domain
         self.input._establish_links(Geometry=geometry, Selection=selection)
 
@@ -664,12 +667,18 @@ class ForEachGeometryElementZone(_ZonePair):
         """The current element as geometry, read inside the zone body."""
         return self.input.o.element
 
+    # -- deprecated entry points, removed in 530 --
+
     @property
     def generation(self) -> "Item[GeometrySocket]":
-        """Handle for the default generation item (the generated geometry)."""
-        return cast("Item[GeometrySocket]", self.generated_items[0])
-
-    # -- deprecated entry points, removed in 530 --
+        """The ``Geometry`` generation item, added when the zone has none."""
+        _deprecated(
+            "zone.generation", 'zone.generated_items.geometry(value, "Geometry")'
+        )
+        for item in self.generated_items:
+            if item.name == "Geometry" and item.socket_type == "GEOMETRY":
+                return cast("Item[GeometrySocket]", item)
+        return self.generated_items.geometry(name="Geometry")
 
     @property
     def inputs(self) -> _ForEachItems:
@@ -777,21 +786,12 @@ class ForEachGeometryElementOutput(BaseZoneOutput):
     _bl_idname = "GeometryNodeForeachGeometryElementOutput"
     node: bpy.types.GeometryNodeForeachGeometryElementOutput
 
-    class _Inputs(SocketAccessor):
-        generation_0: GeometrySocket
-        """The geometry to generate elements from."""
-
     class _Outputs(SocketAccessor):
         geometry: GeometrySocket
         """The output geometry after processing all elements."""
-        generation_0: GeometrySocket
-        """The generated geometry output."""
 
     if TYPE_CHECKING:
 
-        @property
-        def i(self) -> _Inputs: ...
-
         @property
         def o(self) -> _Outputs: ...
 
@@ -806,6 +806,13 @@ class ForEachGeometryElementOutput(BaseZoneOutput):
         self.domain = domain
         self._establish_links(**key_args)
 
+    def _extend_input(self, source: bpy.types.NodeSocket) -> bpy.types.NodeSocket:
+        # Main items can't hold geometry: geometry linked into the output is
+        # added as a generation item.
+        kind = "generation" if source.type == "GEOMETRY" else "main"
+        assert self.node.inputs is not None
+        return next(s for s in self.node.inputs if s.identifier == f"__extend__{kind}")
+
     @property
     def items_generated(
         self,

{nodebpy-520.40.0 → nodebpy-520.41.0}/src/nodebpy/nodes/shader/input.py

@@ -1086,11 +1086,25 @@ class TextureCoordinate(BaseNode):
         @property
         def o(self) -> _Outputs: ...
 
-    def __init__(self, from_instancer: bool = False):
+    def __init__(
+        self,
+        object: bpy.types.Object | None = None,
+        from_instancer: bool = False,
+    ):
         super().__init__()
         key_args = {}
         self.from_instancer = from_instancer
         self._establish_links(**key_args)
+        if object is not None:
+            self.object = object
+
+    @property
+    def object(self) -> bpy.types.Object | None:
+        return self.node.object
+
+    @object.setter
+    def object(self, value: bpy.types.Object | None) -> None:
+        self.node.object = value
 
     @property
     def from_instancer(self) -> bool: