Changelog

0.9.0 (unreleased)

A full static-typing pass over the package and test suite. The code base now passes ty with zero errors and zero suppression comments (every # type: ignore has been removed), and ty runs in CI alongside ruff. Blender API values that are typed as Something | None or as wide data-block unions are now handled through small helpers that check at runtime and narrow the type, instead of being ignored.

Added

  • Typed narrowing helpers, exported from the top-level databpy namespace:
    • require() — return a value, raising ValueError if it is None
    • require_data(), mesh_data(), curves_data(), pointcloud_data(), volume_data() — return Object.data checked to be the expected data-block type, raising TypeError otherwise
    • active_scene() and active_object() — non-optional accessors for bpy.context.scene / bpy.context.active_object
  • Node helpers in databpy.nodes for the optional-heavy node APIs: tree_interface(), new_socket(), input_socket(), output_socket(), socket_value() and set_socket_value().
  • databpy.object.get_uuid() / set_uuid() for the dynamically registered uuid property on bpy.types.Object.
  • Type checking with ty in CI (new typecheck job in the lint workflow), with ty and ruff added as locked dev dependencies.
  • API documentation sections for the new utility and node helpers.

Changed

  • Breaking: invalid-type errors now consistently raise TypeError (some previously raised ValueError or AttributeError): utils.path_resolve(), attribute.guess_atype_from_array(), BlenderObject.__getitem__() with a non-string key, assigning a non-Object to BlenderObjectBase.object, and the deprecated vertices / edges properties on non-mesh objects.
  • Object creation functions (create_object(), create_mesh_object(), create_curves_object(), create_pointcloud_object(), create_bob() and the BlenderObject.from_*() classmethods) are now typed to accept any array-like (lists and tuples always worked at runtime).
  • utils.lerp() accepts scalars and array-likes, converting to numpy arrays internally (the documented list example now actually works).
  • Attribute() accepts any bpy.types.Attribute and validates it against the supported concrete attribute types, raising NamedAttributeError for unsupported ones.
  • nodes.new_tree() is typed as returning a GeometryNodeTree and raises NodeGroupCreationError if an existing node group with the requested name is not a geometry node tree.
  • nodes.MaintainConnections and nodes.swap_tree() raise TypeError when given a node that is not a GeometryNodeGroup.
  • custom_string_iswitch() catches specific exception types during node group creation (rather than a blind except Exception) and chains the original error onto the raised NodeGroupCreationError.

Fixed

  • from databpy import utils was shadowed by databpy.nodes.utils in the package namespace, so static analysis (and potentially import order) resolved databpy.utils to the wrong module.
  • Docs builds failed with the latest griffe (quartodoc 0.11.1 is incompatible with griffe 2.x); griffe is now pinned to <2 in the dev dependencies.

0.8.0 (2026-07-21)

Support for the new attribute types introduced in Blender 5.2, alongside a cleanup of the attribute typing system. Requires bpy >= 5.2.

Added

  • Support for the new Blender 5.2 attribute types:
    • FLOAT4 — 4D float vectors (Float4Attribute)
    • INT16_2D — 2D 16-bit signed integer vectors (Short2Attribute)
    • STRING — text strings (StringAttribute). String support is experimental and raises a warning when used: string attributes are accessible through the Python API but are not yet properly supported within Geometry Nodes. Values are read and written per-element (as unicode numpy arrays) since Blender’s foreach_get/foreach_set do not support string properties.
  • GeometrySet, for accessing all components of an object’s evaluated geometry — including multi-component Geometry Nodes outputs (mesh, point cloud, curves and instances) that a normally evaluated object doesn’t expose. Provides named_attribute() / list_attributes() across components and an informative repr() suited to snapshot testing.
  • Attribute.storage_type, exposing Blender 5.2’s new attribute storage types ("ARRAY" or "SINGLE"). SINGLE-storage attributes (produced by Geometry Nodes for constant values) read transparently as full arrays.
  • named_attribute(evaluate=True) and evaluate_object() now work for Curves and PointCloud objects, not just meshes.
  • BlenderObject.store_named_attribute() now returns the created or modified attribute (previously returned None).

Changed

  • Results of AttributeArray operations (e.g. pos + 1, comparisons) are now plain numpy.ndarrays, and copies (pos.copy(), boolean-mask indexing) are detached from Blender — neither syncs back on modification. True views (slices, column access) remain connected and continue to auto-sync.
  • Data is cast to the attribute’s storage dtype before writing, letting Blender’s foreach_set use its fast buffer path instead of per-element iteration (a significant speedup for the common case of passing float64 arrays).
  • Breaking: attribute type guessing for (n, 4) float arrays now maps to the generic FLOAT4 type instead of FLOAT_COLOR. To store colors or quaternions, explicitly request them with e.g. store_named_attribute(..., atype="FLOAT_COLOR"). (n, 4) uint8 arrays still map to BYTE_COLOR.
  • Attribute type guessing for (n, 2) int16 / uint16 arrays now maps to INT16_2D (other integer widths still map to INT32_2D), and string arrays map to STRING.
  • Requires bpy >= 5.2 (previously >= 5.1).
  • Improved type hints throughout the attribute module: precise Literal types for attribute type and domain names, tuple[int, ...] shapes, and an immutable AttributeType dataclass.

Fixed

  • Setting an existing attribute with dictionary syntax (bob["color"] = data) no longer performs a second, redundant write with a re-guessed attribute type, which could raise a type mismatch error for color and quaternion attributes.
  • Attribute.from_array() now triggers the same object-data refresh workaround as store_named_attribute(), so writes through the low-level interface update reliably in the viewport.
  • repr() of an AttributeArray that has lost its attribute reference no longer raises an error.

Removed

  • Breaking: removed the unused legacy AttributeTypeInfo and AttributeDomain classes from the public API. Use the AttributeTypes and AttributeDomains enums instead.

0.7.0 (2026-03-05)

  • Updated dependencies for Blender 5.1 (#69).

0.6.2 (2026-03-05)

  • Improved typing for the attribute module (#67).
  • Added move_to_collection() for moving objects from one collection into another (#62, thanks @kolibril13).

0.6.0 (2025-11-25)

  • Refactored object classes around a more minimal BlenderObjectBase (#61, #63).

0.5.1 (2025-11-06)

  • General cleanup (#58).
  • Improved deduplication method (#60).

0.5.0 (2025-10-25)

  • Better point cloud and curves support (#57).
  • Requires Blender >= 4.5 for compatibility with point cloud support.

0.4.2 (2025-10-24)

  • Internal improvements and cleanup (#56).
  • Deprecated Attribute.n_values in favor of Attribute.size.

0.4.1 (2025-10-21)

  • Fixed AttributeArray.__str__ (#55).

0.4.0 (2025-10-21)

  • Fixed integer attribute returns to be int32 (#54).

For older releases, see the GitHub releases page.