Migrate a specklepy script to 2026.9

​

What changes for a script

​

Update specklepy first

pip install "specklepy[bundle]==2026.9.0b3"

​

Load a model

version = client.version.get(version_id, project_id)
root = operations.receive(version.referenced_object, remote_transport=transport)

with operations.receive3(account, project_id, model_id, version_id) as model:
    print(len(model.objects))

​

Count and filter objects

from specklepy.objects.data_objects import DataObject

def iter_elements(obj):
    yield obj
    for child in getattr(obj, "elements", None) or []:
        yield from iter_elements(child)


counts = {}
for obj in iter_elements(root):
    if not isinstance(obj, DataObject):
        continue
    key = (obj.properties or {}).get("category") or "Unknown"
    counts[key] = counts.get(key, 0) + 1

by_level = {}
for obj in iter_elements(root):
    if not isinstance(obj, DataObject):
        continue
    key = (obj.properties or {}).get("level") or "Unknown"
    by_level.setdefault(key, []).append(obj)

walls = [
    o
    for o in iter_elements(root)
    if isinstance(o, DataObject) and (o.properties or {}).get("category") == "Walls"
]

counts = {}
for obj in model.objects:
    key = obj.get_string("category") or obj.name or "Unknown"
    counts[key] = counts.get(key, 0) + 1

by_level = {}
for obj in model.objects:
    key = obj.level.name if obj.level else "Unknown"
    by_level.setdefault(key, []).append(obj)

walls = [o for o in model.objects_with("category") if o.get_string("category") == "Walls"]

​

Replace property walks

• get_string / get_double / get_bool: typed lookup. None if the path is missing or the value is another type. Instance properties first, then type properties, then root scalars.
• Indexer (obj["path"]): untyped lookup, same order.
• properties.under("Constraints"): the subtree under that prefix, with the prefix stripped.
• to_nested(): the old nested-dictionary tree. Allocates. Use it only when a caller still needs that shape.

groups = (wall.properties or {}).get("parameters") or {}
x = groups.get("x") or {}
y = x.get("y")

y = wall.get_string("parameters.x.y")
offset = wall.get_double("Constraints.Base Offset")

constraints = wall.properties.under("Constraints")
for key, value in constraints.items():
    print(f"{key}: {value}")

​

Replace proxy walks

by_level = {}
for obj in model.objects:
    key = obj.level.name if obj.level else "Unknown"
    by_level.setdefault(key, []).append(obj)

hosted = [o for o in model.objects if o.host is not None]

​

Read versions published before 2026.9

• Versions published before 2026.9: pass referenced_object as a content hash and get the object graph back.
• Versions published by a 2026.9 connector: referenced_object is a bundle reference (bundle.<projectId>.<modelId>.<versionId>). A 2026.9 specklepy recognizes the prefix and returns a best-effort Base tree (Model.to_base(), DataObject idiom, version = 4 on the root). That projection does not scale to the model sizes the bundle format is built for, and it is not a lossless round trip. It needs an authenticated ServerTransport for the reference’s project. Do not build new work on it.
• Older specklepy: fetching a bundle reference from the objects API returns 404 with upgrade guidance. Upgrade specklepy rather than parsing the 404 body.

​

Publish from a script

from specklepy.api import operations
from specklepy.bundle import BundleBuilder, Producer
from specklepy.objects.geometry import Mesh

builder = BundleBuilder(Producer("my-script", "1.0.0"), "m")
walls = builder.get_or_add_container_path(["Walls"])
wall = builder.get_or_add_object("wall-1").set_properties({"Mark": "W-01"}, name="Basic Wall")
wall.collection = walls
wall.add_geometry(Mesh(vertices=[0, 0, 0, 1, 0, 0, 0, 1, 0], faces=[3, 0, 1, 2], units="m"))

sent = operations.send3(account, project_id, model_id, builder)
print(f"Reserved version {sent.version_id}")

​

FAQ