Nitpick, docfixes and missing filters [part 1] (#1840)

CHANGELOG.md

@@ -22,22 +22,20 @@ Changes are grouped as follows
 ### Fixed
 - If you derived from `TypedNode` or `TypedEdge`, and then derived the `load` method would not include the parent
   class properties. Same if you used multiple inheritance. This is now fixed.
-
 ### Added
-
-- [Feature Preview - alpha] Core Model, available `cognite.client.data_classes import cdm`. 
+- [Feature Preview - alpha] Core Model, available `cognite.client.data_classes import cdm`.
 
 ## [7.53.1] - 2024-07-02
 ### Fixed
-- In the new `.retrieve_nodes` and `retrieve_edges` methods in the `client.data_modeling.instances` module, if you 
+- In the new `retrieve_nodes` and `retrieve_edges` methods in the `client.data_modeling.instances` module, if you
   give the identifier of a single node or edge, you will now get a single `TypedNode` or `TypedEdge` instance back.
 
 ## [7.53.0] - 2024-07-02
 ### Added
 - New classes `TypedNode` and `TypedEdge` (in addition to `TypedNodeApply` and `TypedEdgeApply`) to be used as
   base classes for user created classes that represent nodes and edges with properties in a specific view. For example,
   is you have a view `Person` with properties `name` and `age`, you can create a class `Person` that inherits from
-  `TypedNode` and add properties `name` and `age` to it. This class can then be used with the 
+  `TypedNode` and add properties `name` and `age` to it. This class can then be used with the
   `client.data_modeling.instances.retrieve(..)`, `.apply(...)`, `.list(...)` and `.search(...)` methods.
 
 ## [7.52.3] - 2024-06-27
@@ -46,20 +44,20 @@ Changes are grouped as follows
 
 ## [7.52.2] - 2024-06-26
 ### Added
-- Alpha feature, in `client.time_series.data` support for `instance_id` in `.insert`, `insert_multiple`,
-  `.delete`, and `.retrieve` methods. This is an experimental feature and may change without warning.
+- Alpha feature: `client.time_series.data` support for `instance_id` in `insert`, `insert_multiple`,
+  `delete`, and `retrieve` methods. This is an experimental feature and may change without warning.
 
 ## [7.52.1] - 2024-06-26
 ### Fixed
--  Calling `.extend` on a `NodeListWithCursor` or `EdgeListWithCursor` would raise a `TypeError`. This is now fixed.
+- Calling `.extend` on a `NodeListWithCursor` or `EdgeListWithCursor` no longer raises a `TypeError`.
 
 ## [7.52.0] - 2024-06-19
 ### Added
 - Support the `immutable` flag on container/view properties
 
 ## [7.51.1] - 2024-06-18
 ### Added
-- Added support for serializing Node/Edge properties of type `list` of `NodeId`and `DirectRelationReference`, 
+- Added support for serializing Node/Edge properties of type `list` of `NodeId` and `DirectRelationReference`,
   `date`, `datetime` and list of `date` and `datetime` to `json` format.
 
 ## [7.51.0] - 2024-06-16

cognite/client/_api/data_modeling/instances.py

@@ -645,7 +645,7 @@ def delete(
                 >>> from cognite.client import CogniteClient
                 >>> from cognite.client.data_classes.data_modeling import NodeId, EdgeId
                 >>> client = CogniteClient()
-                >>> my_view = client.data_modeling.views.retrieve('mySpace', 'myView')
+                >>> my_view = client.data_modeling.views.retrieve(('mySpace', 'myView'))
                 >>> my_nodes = client.data_modeling.instances.list(instance_type='node', sources=my_view, limit=None)
                 >>> client.data_modeling.instances.delete(nodes=my_nodes.as_ids())
         """

cognite/client/_api/datapoints_subscriptions.py

@@ -57,7 +57,7 @@ def __call__(
 
     def __iter__(self) -> Iterator[DatapointSubscription]:
         """Iterate over all datapoint subscriptions."""
-        return self.__call__()
+        return self()
 
     def create(self, subscription: DataPointSubscriptionWrite) -> DatapointSubscription:
         """`Create a subscription <https://api-docs.cognite.com/20230101/tag/Data-point-subscriptions/operation/postSubscriptions>`_

cognite/client/_api/extractionpipelines.py

@@ -76,7 +76,7 @@ def __call__(
 
     def __iter__(self) -> Iterator[ExtractionPipeline]:
         """Iterate over all extraction pipelines"""
-        return self.__call__()
+        return self()
 
     def retrieve(self, id: int | None = None, external_id: str | None = None) -> ExtractionPipeline | None:
         """`Retrieve a single extraction pipeline by id. <https://developer.cognite.com/api#tag/Extraction-Pipelines/operation/showExtPipe>`_

cognite/client/_api/functions.py

@@ -13,7 +13,7 @@
 from numbers import Number
 from pathlib import Path
 from tempfile import TemporaryDirectory
-from typing import TYPE_CHECKING, Any, Callable, Sequence, overload
+from typing import TYPE_CHECKING, Any, Callable, NoReturn, Sequence, overload
 from zipfile import ZipFile
 
 from cognite.client._api_client import APIClient
@@ -33,7 +33,7 @@
     TimestampRange,
 )
 from cognite.client.data_classes.functions import FunctionCallsFilter, FunctionsStatus
-from cognite.client.utils._auxiliary import is_unlimited
+from cognite.client.utils._auxiliary import at_most_one_is_not_none, is_unlimited
 from cognite.client.utils._identifier import Identifier, IdentifierSequence
 from cognite.client.utils._importing import local_import
 from cognite.client.utils._session import create_session_and_return_nonce
@@ -72,8 +72,23 @@ def _get_function_identifier(function_id: int | None, function_external_id: str
     raise ValueError("Exactly one of function_id and function_external_id must be specified")
 
 
+@overload
+def _ensure_at_most_one_id_given(function_id: int, function_external_id: str) -> NoReturn: ...
+
+
+@overload
+def _ensure_at_most_one_id_given(function_id: int | None, function_external_id: str | None) -> None: ...
+
+
+def _ensure_at_most_one_id_given(function_id: int | None, function_external_id: str | None) -> None:
+    if at_most_one_is_not_none(function_id, function_external_id):
+        return
+    raise ValueError("Both 'function_id' and 'function_external_id' were supplied, pass exactly one or neither.")
+
+
 class FunctionsAPI(APIClient):
     _RESOURCE_PATH = "/functions"
+    _RESOURCE_PATH_CALL = "/functions/{}/call"
 
     def __init__(self, config: ClientConfig, api_version: str | None, cognite_client: CogniteClient) -> None:
         super().__init__(config, api_version, cognite_client)
@@ -146,7 +161,7 @@ def __call__(
 
         return self._list_generator(
             method="POST",
-            resource_path="/functions/list",
+            resource_path=self._RESOURCE_PATH + "/list",
             filter=filter_,
             limit=limit,
             chunk_size=chunk_size,
@@ -156,7 +171,7 @@ def __call__(
 
     def __iter__(self) -> Iterator[Function]:
         """Iterate over all functions."""
-        return self.__call__()
+        return self()
 
     def create(
         self,
@@ -476,7 +491,7 @@ def call(
 
         if data is None:
             data = {}
-        url = f"/functions/{id}/call"
+        url = self._RESOURCE_PATH_CALL.format(id)
         res = self._post(url, json={"data": data, "nonce": nonce})
 
         function_call = FunctionCall._load(res.json(), cognite_client=self._cognite_client)
@@ -498,7 +513,7 @@ def limits(self) -> FunctionsLimits:
                 >>> client = CogniteClient()
                 >>> limits = client.functions.limits()
         """
-        res = self._get("/functions/limits")
+        res = self._get(self._RESOURCE_PATH + "/limits")
         return FunctionsLimits.load(res.json())
 
     def _zip_and_upload_folder(
@@ -600,7 +615,7 @@ def activate(self) -> FunctionsStatus:
                 >>> client = CogniteClient()
                 >>> status = client.functions.activate()
         """
-        res = self._post("/functions/status")
+        res = self._post(self._RESOURCE_PATH + "/status")
         return FunctionsStatus.load(res.json())
 
     def status(self) -> FunctionsStatus:
@@ -617,7 +632,7 @@ def status(self) -> FunctionsStatus:
                 >>> client = CogniteClient()
                 >>> status = client.functions.status()
         """
-        res = self._get("/functions/status")
+        res = self._get(self._RESOURCE_PATH + "/status")
         return FunctionsStatus.load(res.json())
 
 
@@ -986,6 +1001,7 @@ def __call__(
         cron_expression: str | None = None,
         limit: int | None = None,
     ) -> Iterator[FunctionSchedule]: ...
+
     @overload
     def __call__(
         self,
@@ -1023,13 +1039,7 @@ def __call__(
             Iterator[FunctionSchedule] | Iterator[FunctionSchedulesList]: yields function schedules.
 
         """
-        if function_id or function_external_id:
-            try:
-                IdentifierSequence.load(ids=function_id, external_ids=function_external_id).assert_singleton()
-            except ValueError:
-                raise ValueError(
-                    "Both 'function_id' and 'function_external_id' were supplied, pass exactly one or neither."
-                ) from None
+        _ensure_at_most_one_id_given(function_id, function_external_id)
 
         filter_ = FunctionSchedulesFilter(
             name=name,
@@ -1038,6 +1048,7 @@ def __call__(
             created_time=created_time,
             cron_expression=cron_expression,
         ).dump(camel_case=True)
+
         return self._list_generator(
             method="POST",
             url_path=f"{self._RESOURCE_PATH}/list",
@@ -1050,7 +1061,7 @@ def __call__(
 
     def __iter__(self) -> Iterator[FunctionSchedule]:
         """Iterate over all function schedules"""
-        return self.__call__()
+        return self()
 
     def retrieve(self, id: int) -> FunctionSchedule | None:
         """`Retrieve a single function schedule by id. <https://developer.cognite.com/api#tag/Function-schedules/operation/byIdsFunctionSchedules>`_
@@ -1113,17 +1124,10 @@ def list(
                 >>> schedules = func.list_schedules(limit=None)
 
         """
-        if function_id or function_external_id:
-            try:
-                IdentifierSequence.load(ids=function_id, external_ids=function_external_id).assert_singleton()
-            except ValueError:
-                raise ValueError(
-                    "Both 'function_id' and 'function_external_id' were supplied, pass exactly one or neither."
-                ) from None
-
         if is_unlimited(limit):
             limit = self._LIST_LIMIT_CEILING
 
+        _ensure_at_most_one_id_given(function_id, function_external_id)
         filter = FunctionSchedulesFilter(
             name=name,
             function_id=function_id,

cognite/client/_api/transformations/__init__.py

@@ -95,8 +95,8 @@ def __call__(
         has_blocked_error: bool | None = None,
         created_time: dict[str, Any] | TimestampRange | None = None,
         last_updated_time: dict[str, Any] | TimestampRange | None = None,
-        data_set_ids: list[int] | None = None,
-        data_set_external_ids: list[str] | None = None,
+        data_set_ids: int | list[int] | None = None,
+        data_set_external_ids: str | list[str] | None = None,
         tags: TagsFilter | None = None,
         limit: int | None = None,
     ) -> Iterator[Transformation] | Iterator[TransformationList]:
@@ -113,21 +113,15 @@ def __call__(
             has_blocked_error (bool | None): Whether only the blocked transformations should be included in the results.
             created_time (dict[str, Any] | TimestampRange | None): Range between two timestamps
             last_updated_time (dict[str, Any] | TimestampRange | None): Range between two timestamps
-            data_set_ids (list[int] | None): Return only transformations in the specified data sets with these ids.
-            data_set_external_ids (list[str] | None): Return only transformations in the specified data sets with these external ids.
+            data_set_ids (int | list[int] | None): Return only transformations in the specified data sets with these id(s).
+            data_set_external_ids (str | list[str] | None): Return only transformations in the specified data sets with these external id(s).
             tags (TagsFilter | None): Return only the resource matching the specified tags constraints. It only supports ContainsAny as of now.
             limit (int | None): Limits the number of results to be returned. Defaults to yielding all transformations.
 
         Returns:
             Iterator[Transformation] | Iterator[TransformationList]: Yields transformations in chunks if chunk_size is specified, otherwise one transformation at a time.
         """
-        ds_ids: list[dict[str, Any]] | None = None
-        if data_set_ids and data_set_external_ids:
-            ds_ids = [*[{"id": i} for i in data_set_ids], *[{"externalId": i} for i in data_set_external_ids]]
-        elif data_set_ids:
-            ds_ids = [{"id": i} for i in data_set_ids]
-        elif data_set_external_ids:
-            ds_ids = [{"externalId": i} for i in data_set_external_ids]
+        ds_ids = IdentifierSequence.load(data_set_ids, data_set_external_ids, id_name="data_set").as_dicts()
 
         filter_ = TransformationFilter(
             include_public=include_public,
@@ -140,7 +134,7 @@ def __call__(
             created_time=created_time,
             last_updated_time=last_updated_time,
             tags=tags,
-            data_set_ids=ds_ids,
+            data_set_ids=ds_ids or None,
         ).dump(camel_case=True)
 
         return self._list_generator(
@@ -299,8 +293,8 @@ def list(
         has_blocked_error: bool | None = None,
         created_time: dict[str, Any] | TimestampRange | None = None,
         last_updated_time: dict[str, Any] | TimestampRange | None = None,
-        data_set_ids: list[int] | None = None,
-        data_set_external_ids: list[str] | None = None,
+        data_set_ids: int | list[int] | None = None,
+        data_set_external_ids: str | list[str] | None = None,
         tags: TagsFilter | None = None,
         limit: int | None = DEFAULT_LIMIT_READ,
     ) -> TransformationList:
@@ -316,8 +310,8 @@ def list(
             has_blocked_error (bool | None): Whether only the blocked transformations should be included in the results.
             created_time (dict[str, Any] | TimestampRange | None): Range between two timestamps
             last_updated_time (dict[str, Any] | TimestampRange | None): Range between two timestamps
-            data_set_ids (list[int] | None): Return only transformations in the specified data sets with these ids.
-            data_set_external_ids (list[str] | None): Return only transformations in the specified data sets with these external ids.
+            data_set_ids (int | list[int] | None): Return only transformations in the specified data sets with these id(s).
+            data_set_external_ids (str | list[str] | None): Return only transformations in the specified data sets with these external id(s).
             tags (TagsFilter | None): Return only the resource matching the specified tags constraints. It only supports ContainsAny as of now.
             limit (int | None): Limits the number of results to be returned. To retrieve all results use limit=-1, default limit is 25.
 
@@ -332,13 +326,7 @@ def list(
                 >>> client = CogniteClient()
                 >>> transformations_list = client.transformations.list()
         """
-        ds_ids: list[dict[str, Any]] | None = None
-        if data_set_ids and data_set_external_ids:
-            ds_ids = [*[{"id": i} for i in data_set_ids], *[{"externalId": i} for i in data_set_external_ids]]
-        elif data_set_ids:
-            ds_ids = [{"id": i} for i in data_set_ids]
-        elif data_set_external_ids:
-            ds_ids = [{"externalId": i} for i in data_set_external_ids]
+        ds_ids = IdentifierSequence.load(data_set_ids, data_set_external_ids, id_name="data_set").as_dicts()
 
         filter = TransformationFilter(
             include_public=include_public,
@@ -351,8 +339,9 @@ def list(
             created_time=created_time,
             last_updated_time=last_updated_time,
             tags=tags,
-            data_set_ids=ds_ids,
+            data_set_ids=ds_ids or None,
         ).dump(camel_case=True)
+
         return self._list(
             list_cls=TransformationList,
             resource_cls=Transformation,

cognite/client/_api/transformations/notifications.py

@@ -59,7 +59,7 @@ def __call__(
             limit (int | None): Limits the number of results to be returned. Defaults to yielding all notifications.
 
         Returns:
-            Iterator[TransformationNotification] | Iterator[TransformationNotificationList]: No description.
+            Iterator[TransformationNotification] | Iterator[TransformationNotificationList]: Yields notifications one by one if chunk_size is None, otherwise yields lists of notifications.
         """
         filter_ = TransformationNotificationFilter(
             transformation_id=transformation_id,
@@ -78,7 +78,7 @@ def __call__(
 
     def __iter__(self) -> Iterator[TransformationNotification]:
         """Iterate over all transformation notifications"""
-        return self.__call__()
+        return self()
 
     @overload
     def create(

cognite/client/_api/transformations/schedules.py

@@ -66,7 +66,7 @@ def __call__(
 
     def __iter__(self) -> Iterator[TransformationSchedule]:
         """Iterate over all transformation schedules"""
-        return self.__call__()
+        return self()
 
     @overload
     def create(self, schedule: TransformationSchedule | TransformationScheduleWrite) -> TransformationSchedule: ...