luminarycloud 0.20.0__py3-none-any.whl → 0.21.0__py3-none-any.whl

luminarycloud/geometry.py

@@ -29,7 +29,7 @@ from .named_variable_set import NamedVariableSet, get_named_variable_set
 
 if TYPE_CHECKING:
     from .project import Project
-    from .geometry_version import GeometryVersion
+    from .geometry_version import GeometryVersion, GeometryVersionIterator
 
 
 @ProtoWrapper(geometrypb.Geometry)
@@ -292,6 +292,46 @@ class Geometry(ProtoWrapperBase):
             )
         )
 
+    def versions(self, unfiltered: bool = False, page_size: int = 50) -> "GeometryVersionIterator":
+        """
+        List the geometry versions for this geometry in chronological order, oldest first.
+
+        By default, this only returns versions that are named OR have an associated Mesh OR are the
+        latest version of the geometry. If `unfiltered` is true, this returns all versions.
+
+        The geometry versions are fetched lazily in batches using pagination to optimize memory
+        usage and API calls.
+
+        Parameters
+        ----------
+        unfiltered : bool, optional
+            If True, returns all versions. If False, returns only versions that are named OR have an
+            associated Mesh OR are the latest version of the geometry. Defaults to False.
+        page_size : int, optional
+            Number of geometry versions to fetch per page. Defaults to 50, max is 500.
+
+        Returns
+        -------
+        GeometryVersionIterator
+            An iterator that yields GeometryVersion objects one at a time.
+
+        Examples
+        --------
+        Fetch the versions of this geometry with default filtering applied.
+        >>> for version in geometry.versions():
+        ...     print(version.id, version.name)
+
+        Fetch all versions of the geometry.
+        >>> for version in geometry.versions(unfiltered=True):
+        ...     print(version.id, version.name)
+
+        Build a list of versions of this geometry that have the name "So Important".
+        >>> important_versions = [ver for ver in geometry.versions() if ver.name == "So Important"]
+        """
+        from .geometry_version import GeometryVersionIterator
+
+        return GeometryVersionIterator(self.id, unfiltered, page_size)
+
     def latest_version(self) -> GeometryVersion:
         """
         Get the latest version of the geometry.

luminarycloud/geometry_version.py

@@ -3,6 +3,7 @@ from datetime import datetime
 
 from ._client import get_default_client
 from ._helpers._timestamp_to_datetime import timestamp_to_datetime
+from ._helpers.pagination import PaginationIterator
 from ._proto.api.v0.luminarycloud.geometry import geometry_pb2 as geometrypb
 from ._proto.geometry import geometry_pb2 as gpb
 from ._wrapper import ProtoWrapper, ProtoWrapperBase
@@ -87,7 +88,7 @@ class GeometryVersion(ProtoWrapperBase):
         ]
         return surfaces, volumes
 
-    def copy_to_new_geometry(self, name: str = "") -> Geometry:
+    def copy_to_new_geometry(self, name: str = "", request_id: str = "") -> Geometry:
         """
         Copy this GeometryVersion and create a new Geometry containing only that newly copied version.
 
@@ -95,6 +96,11 @@ class GeometryVersion(ProtoWrapperBase):
         ----------
         name : str, optional
             The name of the new Geometry. If not provided, a default name will be used.
+        request_id : str, optional
+            A deduplication key, useful for idempotency. The first time copy_to_new_geometry() is
+            called with a given request_id, a new geometry will be created. Subsequent calls with
+            the same request_id will return the same geometry. If not provided, no deduplication is
+            done. Max length: 256 characters.
 
         Returns
         -------
@@ -104,6 +110,7 @@ class GeometryVersion(ProtoWrapperBase):
         req = geometrypb.CopyGeometryFromVersionRequest(
             geometry_version_id=self.id,
             name=name,
+            request_id=request_id,
         )
         res: geometrypb.CopyGeometryFromVersionResponse = (
             get_default_client().CopyGeometryFromVersion(req)
@@ -173,14 +180,39 @@ class GeometryVersion(ProtoWrapperBase):
         return res.sdk_code
 
 
+class GeometryVersionIterator(PaginationIterator[GeometryVersion]):
+    """Iterator class for geometry versions that provides length hint."""
+
+    def __init__(self, geometry_id: str, unfiltered: bool, page_size: int):
+        super().__init__(page_size)
+        self._geometry_id: str = geometry_id
+        self._unfiltered: bool = unfiltered
+
+    def _fetch_page(
+        self, page_size: int, page_token: str
+    ) -> tuple[list[GeometryVersion], str, int]:
+        req = geometrypb.ListGeometryVersionsRequest(
+            page_size=page_size,
+            page_token=page_token,
+            geometry_id=self._geometry_id,
+            unfiltered=self._unfiltered,
+        )
+        res = self._client.ListGeometryVersions(req)
+        return (
+            [GeometryVersion(gv) for gv in res.geometry_versions],
+            res.next_page_token,
+            res.total_count,
+        )
+
+
 def get_geometry_version(id: str) -> GeometryVersion:
     """
-    Get a specific geometry version with the given ID.
+    Get a geometry version by its ID.
 
     Parameters
     ----------
     id : str
-        Geometry version ID.
+        ID of the geometry version to get.
 
     Returns
     -------
@@ -191,3 +223,25 @@ def get_geometry_version(id: str) -> GeometryVersion:
     req = geometrypb.GetGeometryVersionRequest(geometry_version_id=id)
     res: geometrypb.GetGeometryVersionResponse = get_default_client().GetGeometryVersion(req)
     return GeometryVersion(res.geometry_version)
+
+
+def update_geometry_version(id: str, name: str) -> GeometryVersion:
+    """
+    Update a geometry version.
+
+    Parameters
+    ----------
+    id : str
+        ID of the geometry version to update.
+    name : str
+        The new name for the geometry version. Pass an empty string to clear the name.
+
+    Returns
+    -------
+    GeometryVersion
+        The updated GeometryVersion.
+    """
+
+    req = geometrypb.UpdateGeometryVersionRequest(geometry_version_id=id, name=name)
+    res: geometrypb.UpdateGeometryVersionResponse = get_default_client().UpdateGeometryVersion(req)
+    return GeometryVersion(res.geometry_version)