python(feat): add update, archive, and unarchive to Channel

Author: wei-qlu

python/lib/sift_client/_internal/low_level_wrappers/channels.py

@@ -10,11 +10,13 @@
     GetChannelResponse,
     ListChannelsRequest,
     ListChannelsResponse,
+    UpdateChannelRequest,
+    UpdateChannelResponse,
 )
 from sift.channels.v3.channels_pb2_grpc import ChannelServiceStub
 
 from sift_client._internal.low_level_wrappers.base import LowLevelClientBase
-from sift_client.sift_types.channel import Channel
+from sift_client.sift_types.channel import Channel, ChannelUpdate
 from sift_client.transport import WithGrpcClient
 
 if TYPE_CHECKING:
@@ -120,6 +122,21 @@ async def list_all_channels(
             max_results=max_results,
         )
 
+    async def update_channel(self, update: ChannelUpdate) -> Channel:
+        """Update a channel.
+
+        Args:
+            update: The ChannelUpdate to apply.
+
+        Returns:
+            The updated Channel.
+        """
+        grpc_channel, update_mask = update.to_proto_with_mask()
+        request = UpdateChannelRequest(channel=grpc_channel, update_mask=update_mask)
+        response = await self._grpc_client.get_stub(ChannelServiceStub).UpdateChannel(request)
+        updated_grpc_channel = cast("UpdateChannelResponse", response).channel
+        return Channel._from_proto(updated_grpc_channel)
+
     async def batch_archive_channels(self, channel_ids: list[str]) -> None:
         """Batch archive channels by setting active to false.
 

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

@@ -6,7 +6,7 @@
 import pytest
 
 from sift_client.sift_types import Channel
-from sift_client.sift_types.channel import ChannelDataType, ChannelReference
+from sift_client.sift_types.channel import ChannelDataType, ChannelReference, ChannelUpdate
 
 
 @pytest.fixture
@@ -22,6 +22,10 @@ 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),
         modified_date=datetime.now(timezone.utc),
         created_by_user_id="user1",
@@ -215,3 +219,83 @@ def test_data_method_with_minimal_params(self, mock_channel, mock_client):
             limit=None,
         )
         assert result == mock_data
+
+    def test_update_calls_client_and_updates_self(self, mock_channel, mock_client):
+        """Test that update() calls client.channels.update and calls _update."""
+        updated_channel = MagicMock()
+        mock_client.channels.update.return_value = updated_channel
+
+        with MagicMock() as mock_update:
+            mock_channel._update = mock_update
+
+            update = ChannelUpdate(display_description="new description")
+            result = mock_channel.update(update)
+
+            mock_client.channels.update.assert_called_once_with(channel=mock_channel, update=update)
+            mock_update.assert_called_once_with(updated_channel)
+            assert result is mock_channel
+
+    def test_archive_sets_active_false_via_update(self, mock_channel, mock_client):
+        """archive() delegates to update with active=False and updates in place."""
+        updated = MagicMock()
+        mock_client.channels.update.return_value = updated
+
+        with MagicMock() as mock_update:
+            mock_channel._update = mock_update
+            result = mock_channel.archive()
+
+            mock_client.channels.update.assert_called_once_with(
+                channel=mock_channel, update={"active": False}
+            )
+            mock_update.assert_called_once_with(updated)
+            assert result is mock_channel
+
+    def test_unarchive_sets_active_true_via_update(self, mock_channel, mock_client):
+        """unarchive() delegates to update with active=True and updates in place."""
+        updated = MagicMock()
+        mock_client.channels.update.return_value = updated
+
+        with MagicMock() as mock_update:
+            mock_channel._update = mock_update
+            result = mock_channel.unarchive()
+
+            mock_client.channels.update.assert_called_once_with(
+                channel=mock_channel, update={"active": True}
+            )
+            mock_update.assert_called_once_with(updated)
+            assert result is mock_channel
+
+
+class TestChannelUpdate:
+    """Channel-specific field wiring for ChannelUpdate.
+
+    The generic ModelUpdate behavior (field-mask generation, unset/None exclusion,
+    resource-id requirement, the metadata converter and MappingHelper path expansion)
+    is already covered in test_base.py and test_asset.py. These tests only assert the
+    parts unique to ChannelUpdate: which proto fields its fields map onto.
+    """
+
+    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",
+            metadata={"source": "pytest"},
+            active=False,
+        )
+        update.resource_id = "test_channel_id"
+
+        proto, mask = update.to_proto_with_mask()
+
+        assert proto.channel_id == "test_channel_id"
+        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
+        assert set(mask.paths) == {
+            "display_description",
+            "display_unit_id",
+            "metadata",
+            "active",
+        }

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

@@ -372,6 +372,9 @@ 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,
                 created_by_user_id="user1",

python/lib/sift_client/resources/channels.py

@@ -5,6 +5,7 @@
 from sift_client._internal.low_level_wrappers.channels import ChannelsLowLevelClient
 from sift_client.resources._base import ResourceBase
 from sift_client.sift_types.asset import Asset
+from sift_client.sift_types.channel import Channel, ChannelUpdate
 from sift_client.sift_types.run import Run
 from sift_client.util import cel_utils as cel
 
@@ -16,7 +17,6 @@
     import pyarrow as pa
 
     from sift_client.client import SiftClient
-    from sift_client.sift_types.channel import Channel
 
 
 def _channel_ids_from_list(items: list[str | Channel]) -> list[str]:
@@ -191,6 +191,28 @@ async def find(self, **kwargs) -> Channel | None:
             return channels[0]
         return None
 
+    async def update(
+        self,
+        channel: str | Channel,
+        update: ChannelUpdate | dict,
+    ) -> Channel:
+        """Update a Channel.
+
+        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).
+
+        Returns:
+            The updated Channel.
+        """
+        channel_id = channel._id_or_error if isinstance(channel, Channel) else channel
+        if isinstance(update, dict):
+            update = ChannelUpdate.model_validate(update)
+        update.resource_id = channel_id
+        updated_channel = await self._low_level_client.update_channel(update=update)
+        return self._apply_client_to_instance(updated_channel)
+
     async def archive(self, channels: list[str | Channel]) -> None:
         """Batch archive channels by setting active to false.
 

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

@@ -23,7 +23,7 @@ if TYPE_CHECKING:
         CalculatedChannelCreate,
         CalculatedChannelUpdate,
     )
-    from sift_client.sift_types.channel import Channel
+    from sift_client.sift_types.channel import Channel, ChannelUpdate
     from sift_client.sift_types.data_import import (
         DataTypeKey,
         ImportConfig,
@@ -558,6 +558,19 @@ class ChannelsAPI:
         """
         ...
 
+    def update(self, channel: str | Channel, update: ChannelUpdate | dict) -> Channel:
+        """Update a Channel.
+
+        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).
+
+        Returns:
+            The updated Channel.
+        """
+        ...
+
 class DataExportAPI:
     """Sync counterpart to `DataExportAPIAsync`.
 

python/lib/sift_client/sift_types/__init__.py

@@ -142,6 +142,7 @@
     ChannelBitFieldElement,
     ChannelDataType,
     ChannelReference,
+    ChannelUpdate,
 )
 from sift_client.sift_types.ingestion import (
     ChannelConfig,
@@ -215,6 +216,7 @@
     "ChannelConfig",
     "ChannelDataType",
     "ChannelReference",
+    "ChannelUpdate",
     "DataExportDetails",
     "DataExportStatusDetails",
     "DataImportDetails",

python/lib/sift_client/sift_types/channel.py

@@ -2,7 +2,7 @@
 
 from datetime import datetime, timezone
 from enum import Enum
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, ClassVar
 
 import sift.common.type.v1.channel_data_type_pb2 as channel_pb
 from pydantic import BaseModel, Field, model_validator
@@ -25,7 +25,8 @@
     Uint64Values,
 )
 
-from sift_client.sift_types._base import BaseType
+from sift_client.sift_types._base import BaseType, MappingHelper, ModelUpdate
+from sift_client.util.metadata import metadata_dict_to_proto, metadata_proto_to_dict
 
 if TYPE_CHECKING:
     from sift_stream_bindings import ChannelBitFieldElementPy, ChannelDataTypePy
@@ -253,6 +254,10 @@ 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
     modified_date: datetime
     created_by_user_id: str
@@ -286,6 +291,10 @@ def _from_proto(cls, proto: ChannelProto, sift_client: SiftClient | None = None)
             ],
             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),
             modified_date=proto.modified_date.ToDatetime(tzinfo=timezone.utc),
             created_by_user_id=proto.created_by_user_id,
@@ -332,6 +341,35 @@ def data(
             )
         return data
 
+    def update(self, update: ChannelUpdate | dict) -> Channel:
+        """Update the Channel.
+
+        Args:
+            update: Either a ChannelUpdate instance or a dictionary of fields to update.
+
+        Returns:
+            The updated Channel.
+        """
+        updated_channel = self.client.channels.update(channel=self, update=update)
+        self._update(updated_channel)
+        return self
+
+    def archive(self) -> Channel:
+        """Archive the channel by setting it inactive.
+
+        Returns:
+            The archived Channel.
+        """
+        return self.update({"active": False})
+
+    def unarchive(self) -> Channel:
+        """Unarchive the channel by setting it active.
+
+        Returns:
+            The unarchived Channel.
+        """
+        return self.update({"active": True})
+
     @property
     def asset(self) -> Asset:
         """Get the asset that this channel belongs to."""
@@ -344,6 +382,35 @@ def runs(self) -> list[Run]:
         return self.asset.runs
 
 
+class ChannelUpdate(ModelUpdate[ChannelProto]):
+    """Model of the Channel fields that can be updated."""
+
+    display_description: str | None = None
+    display_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(
+            proto_attr_path="display_unit_id",
+            update_field="display_unit_id",
+        ),
+        "metadata": MappingHelper(
+            proto_attr_path="metadata",
+            update_field="metadata",
+            converter=metadata_dict_to_proto,
+        ),
+    }
+
+    def _get_proto_class(self) -> type[ChannelProto]:
+        return ChannelProto
+
+    def _add_resource_id_to_proto(self, proto_msg: ChannelProto):
+        if self._resource_id is None:
+            raise ValueError("Resource ID must be set before adding to proto")
+        proto_msg.channel_id = self._resource_id
+
+
 class ChannelReference(BaseModel):
     """Channel reference for a calculated channel or rule expression.