map channel description to display field

Author: wei-qlu

python/lib/sift_client/_tests/sift_types/test_channel.py

@@ -22,8 +22,6 @@ def mock_channel(mock_client):
         bit_field_elements=[],
         enum_types={},
         asset_id="test_asset_id",
-        display_description="display description",
-        display_unit="m/s",
         metadata={},
         active=True,
         created_date=datetime.now(timezone.utc),
@@ -228,7 +226,7 @@ def test_update_calls_client_and_updates_self(self, mock_channel, mock_client):
         with MagicMock() as mock_update:
             mock_channel._update = mock_update
 
-            update = ChannelUpdate(display_description="new description")
+            update = ChannelUpdate(description="new description")
             result = mock_channel.update(update)
 
             mock_client.channels.update.assert_called_once_with(channel=mock_channel, update=update)
@@ -278,8 +276,8 @@ class TestChannelUpdate:
     def test_fields_map_to_correct_proto_fields(self):
         """Each ChannelUpdate field targets its matching Channel proto field and mask path."""
         update = ChannelUpdate(
-            display_description="new description",
-            display_unit="volts",
+            description="new description",
+            unit="volts",
             metadata={"source": "pytest"},
             active=False,
         )
@@ -288,14 +286,17 @@ def test_fields_map_to_correct_proto_fields(self):
         proto, mask = update.to_proto_with_mask()
 
         assert proto.channel_id == "test_channel_id"
+        # description/unit write the display override fields, the only ones the
+        # server allows UpdateChannel to mutate.
         assert proto.display_description == "new description"
-        # display_unit is renamed onto the proto's display_unit_id field.
         assert proto.display_unit_id == "volts"
         assert {md.key.name: md.string_value for md in proto.metadata} == {"source": "pytest"}
         assert proto.active is False
+        # The server's update mask accepts "display_units" (not "display_unit_id")
+        # for the unit; see channel_service.go UpdateChannel.
         assert set(mask.paths) == {
             "display_description",
-            "display_unit_id",
+            "display_units",
             "metadata",
             "active",
         }

python/lib/sift_client/_tests/sift_types/test_results.py

@@ -372,8 +372,6 @@ def _channel(name: str) -> Channel:
                 bit_field_elements=[],
                 enum_types={},
                 asset_id="asset_1",
-                display_description="",
-                display_unit="",
                 active=True,
                 created_date=now,
                 modified_date=now,

python/lib/sift_client/resources/channels.py

@@ -201,7 +201,7 @@ async def update(
         Args:
             channel: The Channel or channel ID to update.
             update: Updates to apply to the Channel. See ChannelUpdate for the updatable fields
-                (display description, display unit, metadata, and active status).
+                (description, unit, metadata, and active status).
 
         Returns:
             The updated Channel.

python/lib/sift_client/resources/sync_stubs/__init__.pyi

@@ -564,7 +564,7 @@ class ChannelsAPI:
         Args:
             channel: The Channel or channel ID to update.
             update: Updates to apply to the Channel. See ChannelUpdate for the updatable fields
-                (display description, display unit, metadata, and active status).
+                (description, unit, metadata, and active status).
 
         Returns:
             The updated Channel.

python/lib/sift_client/sift_types/channel.py

@@ -254,8 +254,6 @@ class Channel(BaseType[ChannelProto, "Channel"]):
     bit_field_elements: list[ChannelBitFieldElement] = Field(default_factory=list)
     enum_types: dict[str, int] = Field(default_factory=dict)
     asset_id: str
-    display_description: str
-    display_unit: str
     metadata: dict[str, str | float | bool] = Field(default_factory=dict)
     active: bool
     created_date: datetime
@@ -284,15 +282,16 @@ def _from_proto(cls, proto: ChannelProto, sift_client: SiftClient | None = None)
             id_=proto.channel_id,
             name=proto.name,
             data_type=ChannelDataType(proto.data_type),
-            description=proto.description,
-            unit=proto.unit_id,
+            # Prefer the user-set display override, falling back to the canonical
+            # value set at channel creation. This mirrors how the Sift app resolves
+            # these (displayDescription || description, displayUnit || unit).
+            description=proto.display_description or proto.description,
+            unit=proto.display_unit_id or proto.unit_id,
             bit_field_elements=[
                 ChannelBitFieldElement._from_proto(el) for el in proto.bit_field_elements
             ],
             enum_types=cls._enum_types_from_proto_list(proto.enum_types),  # type: ignore
             asset_id=proto.asset_id,
-            display_description=proto.display_description,
-            display_unit=proto.display_unit_id,
             metadata=metadata_proto_to_dict(proto.metadata),  # type: ignore
             active=proto.active,
             created_date=proto.created_date.ToDatetime(tzinfo=timezone.utc),
@@ -383,17 +382,27 @@ def runs(self) -> list[Run]:
 
 
 class ChannelUpdate(ModelUpdate[ChannelProto]):
-    """Model of the Channel fields that can be updated."""
+    """Model of the Channel fields that can be updated.
 
-    display_description: str | None = None
-    display_unit: str | None = None
+    A channel's canonical description and unit are set at creation and are immutable
+    afterward. Updating ``description`` or ``unit`` writes the channel's display
+    override (``display_description`` / ``display_unit_id``), which is the value the
+    Sift app shows in place of the canonical one.
+    """
+
+    description: str | None = None
+    unit: str | None = None
     metadata: dict[str, str | float | bool] | None = None
     active: bool | None = None
 
     _to_proto_helpers: ClassVar[dict[str, MappingHelper]] = {
-        "display_unit": MappingHelper(
+        "description": MappingHelper(
+            proto_attr_path="display_description",
+            update_field="display_description",
+        ),
+        "unit": MappingHelper(
             proto_attr_path="display_unit_id",
-            update_field="display_unit_id",
+            update_field="display_units",
         ),
         "metadata": MappingHelper(
             proto_attr_path="metadata",