Support Labels Retrieve (#1795)

CHANGELOG.md

@@ -17,6 +17,10 @@ Changes are grouped as follows
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+## [7.47.0] - 2024-06-04
+### Added
+- Support for retrieving `Labels`, `client.labels.retrieve`. 
+
 ## [7.46.2] - 2024-06-03
 ### Added
 - Added option for silencing `FeaturePreviewWarnings` in the `cognite.client.global_config`. 

cognite/client/_api/labels.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Iterator, Sequence, cast, overload
+from typing import Iterator, Literal, Sequence, cast, overload
 
 from cognite.client._api_client import APIClient
 from cognite.client._constants import DEFAULT_LIMIT_READ
@@ -52,6 +52,49 @@ def __call__(
             chunk_size=chunk_size,
         )
 
+    @overload
+    def retrieve(self, external_id: str, ignore_unknown_ids: Literal[True]) -> LabelDefinition | None: ...
+
+    @overload
+    def retrieve(self, external_id: str, ignore_unknown_ids: Literal[False] = False) -> LabelDefinition: ...
+
+    @overload
+    def retrieve(self, external_id: SequenceNotStr[str], ignore_unknown_ids: bool = False) -> LabelDefinitionList: ...
+
+    def retrieve(
+        self, external_id: str | SequenceNotStr[str], ignore_unknown_ids: bool = False
+    ) -> LabelDefinition | LabelDefinitionList | None:
+        """`Retrieve one or more label definitions by external id. <https://developer.cognite.com/api#tag/Labels/operation/byIdsLabels>`_
+
+        Args:
+            external_id (str | SequenceNotStr[str]): External ID or list of external ids
+            ignore_unknown_ids (bool): If True, ignore IDs and external IDs that are not found rather than throw an exception.
+
+        Returns:
+            LabelDefinition | LabelDefinitionList | None: The requested label definition(s)
+
+        Examples:
+
+            Get label by external id::
+
+                >>> from cognite.client import CogniteClient
+                >>> client = CogniteClient()
+                >>> res = client.labels.retrieve(external_id="my_label", ignore_unknown_ids=True)
+
+        """
+        is_single = isinstance(external_id, str)
+        external_ids = [external_id] if is_single else external_id
+        identifiers = IdentifierSequence.load(external_ids=external_ids)  # type: ignore[arg-type]
+        result = self._retrieve_multiple(
+            list_cls=LabelDefinitionList,
+            resource_cls=LabelDefinition,
+            identifiers=identifiers,
+            ignore_unknown_ids=ignore_unknown_ids,
+        )
+        if is_single:
+            return result[0] if result else None
+        return result
+
     def list(
         self,
         name: str | None = None,

cognite/client/_version.py

@@ -1,4 +1,4 @@
 from __future__ import annotations
 
-__version__ = "7.46.2"
+__version__ = "7.47.0"
 __api_subversion__ = "20230101"

docs/source/data_organization.rst

@@ -81,6 +81,10 @@ List labels
 ^^^^^^^^^^^
 .. automethod:: cognite.client._api.labels.LabelsAPI.list
 
+Retrieve labels
+^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.labels.LabelsAPI.retrieve
+
 Create a label
 ^^^^^^^^^^^^^^
 .. automethod:: cognite.client._api.labels.LabelsAPI.create

pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "cognite-sdk"
 
-version = "7.46.2"
+version = "7.47.0"
 description = "Cognite Python SDK"
 readme = "README.md"
 documentation = "https://cognite-sdk-python.readthedocs-hosted.com"

tests/tests_integration/test_api/test_labels.py

@@ -2,7 +2,9 @@
 
 import pytest
 
-from cognite.client.data_classes import Asset, AssetUpdate, Label, LabelDefinition
+from cognite.client import CogniteClient
+from cognite.client.data_classes import Asset, AssetUpdate, Label, LabelDefinition, LabelDefinitionList
+from cognite.client.exceptions import CogniteNotFoundError
 from cognite.client.utils._text import random_string
 
 
@@ -25,6 +27,32 @@ def test_list(self, cognite_client, new_label, post_spy):
         assert 0 < len(res) <= 100
         assert 1 == cognite_client.labels._post.call_count
 
+    def test_retrieve_existing_labels(self, cognite_client: CogniteClient, new_label: LabelDefinition) -> None:
+        res = cognite_client.labels.retrieve(external_id=new_label.external_id)
+        assert isinstance(res, LabelDefinition)
+        assert res.external_id == new_label.external_id
+        assert res.name == new_label.name
+
+    def test_retrieve_label_list(self, cognite_client: CogniteClient, new_label: LabelDefinition) -> None:
+        res = cognite_client.labels.retrieve(external_id=[new_label.external_id])
+        assert isinstance(res, LabelDefinitionList)
+        assert len(res) == 1
+        assert res[0].external_id == new_label.external_id
+        assert res[0].name == new_label.name
+
+    def test_retrieve_non_existing_labels(self, cognite_client: CogniteClient) -> None:
+        with pytest.raises(CogniteNotFoundError) as e:
+            cognite_client.labels.retrieve(external_id="this does not exist")
+        assert e.value.failed[0]["externalId"] == "this does not exist"
+
+    def test_retrieve_non_existing_label_list(self, cognite_client: CogniteClient) -> None:
+        label_list = cognite_client.labels.retrieve(external_id=["this does not exist"], ignore_unknown_ids=True)
+        assert len(label_list) == 0
+
+    def test_retrieve_none_existing_labels_ignore_unknown(self, cognite_client: CogniteClient) -> None:
+        res = cognite_client.labels.retrieve(external_id="this does not exist", ignore_unknown_ids=True)
+        assert res is None
+
     def test_create_asset_with_label(self, cognite_client, new_label):
         ac = cognite_client.assets.create(Asset(name="any", labels=[Label(external_id=new_label.external_id)]))
         assert isinstance(ac, Asset)