Python: updated partial APIs naming (#8826)

* `update_fields(clear: bool, ...)` -> `from_fields(clear_unset: bool,
...)`
* `clear_fields()` -> `cleared()`
* `cleared()` is not implemented by forwarding to
`from_fields(clear_unset=True)`

This does not cover implementing the constructors in terms of
`from_fields()`. If that happens at all, this will be in one or more
follow-ups.

---

* Part of #8822

Author: teh-cmc

crates/build/re_types_builder/src/codegen/python/mod.rs

@@ -2537,7 +2537,7 @@ fn quote_partial_update_methods(reporter: &Reporter, obj: &Object, objects: &Obj
         doc_string_lines.push("\n".to_owned());
         doc_string_lines.push("Parameters".to_owned());
         doc_string_lines.push("----------".to_owned());
-        doc_string_lines.push("clear:".to_owned());
+        doc_string_lines.push("clear_unset:".to_owned());
         doc_string_lines
             .push("    If true, all unspecified fields will be explicitly cleared.".to_owned());
         for doc in parameter_docs {
@@ -2546,24 +2546,13 @@ fn quote_partial_update_methods(reporter: &Reporter, obj: &Object, objects: &Obj
     };
     let doc_block = indent::indent_by(12, quote_doc_lines(doc_string_lines));
 
-    let field_clears = obj
-        .fields
-        .iter()
-        .map(|field| {
-            let field_name = field.snake_case_name();
-            format!("{field_name}=[],")
-        })
-        .collect_vec()
-        .join("\n");
-    let field_clears = indent::indent_by(12, field_clears);
-
     unindent(&format!(
         r#"
         @classmethod
-        def update_fields(
+        def from_fields(
             cls,
             *,
-            clear: bool = False,
+            clear_unset: bool = False,
             {parameters},
         ) -> {name}:
             {doc_block}
@@ -2573,7 +2562,7 @@ fn quote_partial_update_methods(reporter: &Reporter, obj: &Object, objects: &Obj
                     {kwargs},
                 }}
 
-                if clear:
+                if clear_unset:
                     kwargs = {{k: v if v is not None else [] for k, v in kwargs.items()}}  # type: ignore[misc]
 
                 inst.__attrs_init__(**kwargs)
@@ -2583,13 +2572,9 @@ fn quote_partial_update_methods(reporter: &Reporter, obj: &Object, objects: &Obj
             return inst
 
         @classmethod
-        def clear_fields(cls) -> {name}:
+        def cleared(cls) -> {name}:
             """Clear all the fields of a `{name}`."""
-            inst = cls.__new__(cls)
-            inst.__attrs_init__(
-                {field_clears}
-            )
-            return inst
+            return cls.from_fields(clear_unset=True)
         "#
     ))
 }

docs/snippets/all/archetypes/mesh3d_partial_updates.py

@@ -22,4 +22,4 @@
 factors = np.abs(np.sin(np.arange(1, 300, dtype=np.float32) * 0.04))
 for i, factor in enumerate(factors):
     rr.set_time_sequence("frame", i)
-    rr.log("triangle", rr.Mesh3D.update_fields(vertex_positions=vertex_positions * factor))
+    rr.log("triangle", rr.Mesh3D.from_fields(vertex_positions=vertex_positions * factor))

docs/snippets/all/archetypes/points3d_partial_updates.py

@@ -14,7 +14,7 @@
     radii = [0.6 if n < i else 0.2 for n in range(0, 10)]
 
     rr.set_time_sequence("frame", i)
-    rr.log("points", rr.Points3D.update_fields(radii=radii, colors=colors))
+    rr.log("points", rr.Points3D.from_fields(radii=radii, colors=colors))
 
 rr.set_time_sequence("frame", 20)
-rr.log("points", rr.Points3D.update_fields(clear=True, positions=positions, radii=0.3))
+rr.log("points", rr.Points3D.from_fields(clear_unset=True, positions=positions, radii=0.3))

docs/snippets/all/archetypes/transform3d_partial_updates.py

@@ -23,7 +23,7 @@ def truncated_radians(deg: float) -> float:
     rad = truncated_radians(deg * 4)
     rr.log(
         "box",
-        rr.Transform3D.update_fields(
+        rr.Transform3D.from_fields(
             # TODO(cmc): we should have access to all the fields of the extended constructor too.
             rotation_axis_angle=rr.RotationAxisAngle(axis=[0.0, 1.0, 0.0], radians=rad),
         ),
@@ -33,15 +33,15 @@ def truncated_radians(deg: float) -> float:
 for t in range(51):
     rr.log(
         "box",
-        rr.Transform3D.update_fields(translation=[0, 0, t / 10.0]),
+        rr.Transform3D.from_fields(translation=[0, 0, t / 10.0]),
     )
 
 # Update only the rotation of the box.
 for deg in range(46):
     rad = truncated_radians((deg + 45) * 4)
     rr.log(
         "box",
-        rr.Transform3D.update_fields(
+        rr.Transform3D.from_fields(
             # TODO(cmc): we should have access to all the fields of the extended constructor too.
             rotation_axis_angle=rr.RotationAxisAngle(axis=[0.0, 1.0, 0.0], radians=rad),
         ),
@@ -50,5 +50,5 @@ def truncated_radians(deg: float) -> float:
 # Clear all of the box's attributes, and reset its axis length.
 rr.log(
     "box",
-    rr.Transform3D.update_fields(clear=True, axis_length=15),
+    rr.Transform3D.from_fields(clear_unset=True, axis_length=15),
 )

docs/snippets/all/tutorials/data_out.py

@@ -38,7 +38,7 @@
 
 # log a `Label` component to the face bounding box entity
 target_entity = "/video/detector/faces/0/bbox"
-rr.log(target_entity, rr.Boxes2D.update_fields(show_labels=True), static=True)
+rr.log(target_entity, rr.Boxes2D.from_fields(show_labels=True), static=True)
 rr.send_columns(
     target_entity,
     indexes=[rr.TimeSequenceColumn("frame_nr", df["frame_nr"])],

examples/python/air_traffic_data/air_traffic_data.py

@@ -318,12 +318,12 @@ def log_position_and_altitude(self, df: polars.DataFrame, icao_id: str) -> None:
             color = rr.components.Color.from_string(entity_path)
             rr.log(
                 entity_path,
-                rr.Points3D.update_fields(colors=color),
+                rr.Points3D.from_fields(colors=color),
                 # TODO(cmc): That would be UB right now (and doesn't matter as long as we are on the untagged index).
-                # rr.GeoPoints.update_fields(colors=color),
+                # rr.GeoPoints.from_fields(colors=color),
                 static=True,
             )
-            rr.log(entity_path + "/barometric_altitude", rr.SeriesLine.update_fields(color=color), static=True)
+            rr.log(entity_path + "/barometric_altitude", rr.SeriesLine.from_fields(color=color), static=True)
             self._position_indicators.add(icao_id)
 
         timestamps = rr.TimeSecondsColumn("unix_time", df["timestamp"].to_numpy())

examples/python/detect_and_track_objects/detect_and_track_objects.py

@@ -213,7 +213,7 @@ def log_tracked(self) -> None:
                 ),
             )
         else:
-            rr.log(f"video/tracked/{self.tracking_id}", rr.Boxes2D.clear_fields())
+            rr.log(f"video/tracked/{self.tracking_id}", rr.Boxes2D.cleared())
 
     def update_with_detection(self, detection: Detection, bgr: cv2.typing.MatLike) -> None:
         self.num_recent_undetected_frames = 0

examples/python/drone_lidar/drone_lidar.py

@@ -119,7 +119,7 @@ def log_lidar_data() -> None:
     rr.log(
         "/lidar",
         # negative radii are interpreted in UI units (instead of scene units)
-        rr.Points3D.update_fields(colors=(128, 128, 255), radii=-0.1),
+        rr.Points3D.from_fields(colors=(128, 128, 255), radii=-0.1),
         static=True,
     )
 
@@ -137,7 +137,7 @@ def log_drone_trajectory() -> None:
 
     rr.log(
         "/drone",
-        rr.Points3D.update_fields(colors=(255, 0, 0), radii=0.5),
+        rr.Points3D.from_fields(colors=(255, 0, 0), radii=0.5),
         static=True,
     )
 

examples/python/incremental_logging/incremental_logging.py

@@ -23,7 +23,7 @@
 # Only log colors and radii once.
 # Logging as static would also work (i.e. `static=True`).
 rr.set_time_sequence("frame_nr", 0)
-rr.log("points", rr.Points3D.update_fields(colors=0xFF0000FF, radii=0.1))
+rr.log("points", rr.Points3D.from_fields(colors=0xFF0000FF, radii=0.1))
 
 rng = default_rng(12345)
 
@@ -32,7 +32,7 @@
 # They will automatically re-use the colors and radii logged at the beginning.
 for i in range(10):
     rr.set_time_sequence("frame_nr", i)
-    rr.log("points", rr.Points3D.update_fields(positions=rng.uniform(-5, 5, size=[10, 3])))
+    rr.log("points", rr.Points3D.from_fields(positions=rng.uniform(-5, 5, size=[10, 3])))
 ```
 
 Move the time cursor around, and notice how the colors and radii from frame 0 are still picked up by later frames, while the points themselves keep changing every frame.
@@ -47,7 +47,7 @@
 # Only log colors and radii once.
 # Logging as static would also work (i.e. `static=True`).
 rr.set_time_sequence("frame_nr", 0)
-rr.log("points", rr.Points3D.update_fields(colors=0xFF0000FF, radii=0.1))
+rr.log("points", rr.Points3D.from_fields(colors=0xFF0000FF, radii=0.1))
 
 rng = default_rng(12345)
 
@@ -56,6 +56,6 @@
 # They will automatically re-use the colors and radii logged at the beginning.
 for i in range(10):
     rr.set_time_sequence("frame_nr", i)
-    rr.log("points", rr.Points3D.update_fields(positions=rng.uniform(-5, 5, size=[10, 3])))
+    rr.log("points", rr.Points3D.from_fields(positions=rng.uniform(-5, 5, size=[10, 3])))
 
 rr.script_teardown(args)