chore: change docstring examples to showcase instance_id first (#2676)

Author: haakonvt

cognite/client/_api/datapoints.py

@@ -45,7 +45,7 @@
     LatestDatapointList,
     LatestDatapointQuery,
 )
-from cognite.client.data_classes.data_modeling.ids import NodeId
+from cognite.client.data_classes.data_modeling import NodeId
 from cognite.client.data_classes.datapoint_aggregates import Aggregate
 from cognite.client.exceptions import CogniteAPIError, CogniteNotFoundError
 from cognite.client.utils import _json_extended as _json
@@ -1029,16 +1029,16 @@ async def retrieve(
         Examples:
 
             You can specify the identifiers of the datapoints you wish to retrieve in a number of ways. In this example
-            we are using the time-ago format, ``"2w-ago"`` to get raw data for the time series with id=42 from 2 weeks ago up until now.
+            we are using the time-ago format, ``"2w-ago"`` to get raw data for a time series from 2 weeks ago up until now.
             You can also use the time-ahead format, like ``"3d-ahead"``, to specify a relative time in the future.
 
                 >>> from cognite.client import CogniteClient, AsyncCogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> client = CogniteClient()
                 >>> # async_client = AsyncCogniteClient()  # another option
-                >>> dps = client.time_series.data.retrieve(id=42, start="2w-ago")
-                >>> # You can also use instance_id:
-                >>> from cognite.client.data_classes.data_modeling import NodeId
-                >>> dps = client.time_series.data.retrieve(instance_id=NodeId("ts-space", "foo"))
+                >>> dps = client.time_series.data.retrieve(
+                ...     instance_id=NodeId("ts-space", "foo"), start="2w-ago"
+                ... )
 
             Although raw datapoints are returned by default, you can also get aggregated values, such as `max` or `average`. You may also fetch more than one time series simultaneously. Here we are
             getting daily averages and maximum values for all of 2018, for two different time series, where we're specifying `start` and `end` as integers
@@ -1396,14 +1396,15 @@ async def retrieve_arrays(
 
         Examples:
 
-            Get weekly ``min`` and ``max`` aggregates for a time series with id=42 since the year 2000, then compute the range of values:
+            Get weekly ``min`` and ``max`` aggregates for a time series using instance_id, then compute the range of values:
 
                 >>> from cognite.client import CogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> from datetime import datetime, timezone
                 >>> client = CogniteClient()
                 >>> # async_client = AsyncCogniteClient()  # another option
                 >>> dps = client.time_series.data.retrieve_arrays(
-                ...     id=42,
+                ...     instance_id=NodeId("my-space", "my-ts-xid"),
                 ...     start=datetime(2020, 1, 1, tzinfo=timezone.utc),
                 ...     aggregates=["min", "max"],
                 ...     granularity="7d",
@@ -1536,14 +1537,15 @@ async def retrieve_dataframe(
 
         Examples:
 
-            Get a pandas dataframe using a single time series external ID, with data from the last two weeks,
+            Get a pandas dataframe using a single time series instance ID, with data from the last two weeks,
             but with no more than 100 datapoints:
 
                 >>> from cognite.client import CogniteClient, AsyncCogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> client = CogniteClient()
                 >>> # async_client = AsyncCogniteClient()  # another option
                 >>> df = client.time_series.data.retrieve_dataframe(
-                ...     external_id="foo", start="2w-ago", end="now", limit=100
+                ...     instance_id=NodeId("my-space", "my-ts-xid"), start="2w-ago", end="now", limit=100
                 ... )
 
             Get the pandas dataframe with a uniform index (fixed spacing between points) of 1 day, for two time series with
@@ -1574,11 +1576,11 @@ async def retrieve_dataframe(
                 ...     include_aggregate_name=False,
                 ... )
 
-            You may also use ``pandas.Timestamp`` to define start and end. Here we fetch using instance_id:
+            You may also use ``pandas.Timestamp`` to define start and end:
 
                 >>> import pandas as pd
                 >>> df = client.time_series.data.retrieve_dataframe(
-                ...     instance_id=NodeId("my-space", "my-ts-xid"),
+                ...     external_id="foo",
                 ...     start=pd.Timestamp("2023-01-01"),
                 ...     end=pd.Timestamp("2023-02-01"),
                 ... )
@@ -1849,18 +1851,18 @@ async def retrieve_latest(
             Getting the latest datapoint in a time series:
 
                 >>> from cognite.client import CogniteClient, AsyncCogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> client = CogniteClient()
                 >>> # async_client = AsyncCogniteClient()  # another option
-                >>> res = client.time_series.data.retrieve_latest(id=1)
+                >>> res = client.time_series.data.retrieve_latest(
+                ...     instance_id=NodeId("my-space", "my-ts-xid")
+                ... )
                 >>> if res:  # Check if datapoint exists
                 ...     print(res.timestamp, res.value)
 
-            You can also use external_id or instance_id; single identifier or list of identifiers:
+            You can also use id or external_id; single identifier or list of identifiers:
 
-                >>> from cognite.client.data_classes.data_modeling import NodeId
-                >>> res = client.time_series.data.retrieve_latest(
-                ...     external_id=["foo", "bar"], instance_id=NodeId("my-space", "my-ts-xid")
-                ... )
+                >>> res = client.time_series.data.retrieve_latest(id=1, external_id=["foo", "bar"])
 
             You can also get the latest datapoint before a specific time:
 
@@ -1978,6 +1980,7 @@ async def insert(
 
                 >>> from cognite.client import CogniteClient
                 >>> from cognite.client.data_classes import StatusCode
+                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> from datetime import datetime, timezone
                 >>> client = CogniteClient()
                 >>> # async_client = AsyncCogniteClient()  # another option
@@ -1987,20 +1990,19 @@ async def insert(
                 ...     (datetime(2018, 1, 3, tzinfo=timezone.utc), 3000, StatusCode.Uncertain),
                 ...     (datetime(2018, 1, 4, tzinfo=timezone.utc), None, StatusCode.Bad),
                 ... ]
-                >>> client.time_series.data.insert(datapoints, id=1)
+                >>> client.time_series.data.insert(
+                ...     datapoints, instance_id=NodeId("my-space", "my-ts-xid")
+                ... )
 
             The timestamp can be given by datetime as above, or in milliseconds since epoch. Status codes can also be
             passed as normal integers; this is necessary if a subcategory or modifier flag is needed, e.g. 3145728: 'GoodClamped':
 
-                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> datapoints = [
                 ...     (150000000000, 1000),
                 ...     (160000000000, 2000, 3145728),
                 ...     (170000000000, 2000, 2147483648),  # Same as StatusCode.Bad
                 ... ]
-                >>> client.time_series.data.insert(
-                ...     datapoints, instance_id=NodeId("my-space", "my-ts-xid")
-                ... )
+                >>> client.time_series.data.insert(datapoints, id=1)
 
             Or they can be a list of dictionaries:
 
@@ -2161,9 +2163,12 @@ async def delete_range(
             Deleting the last week of data from a time series:
 
                 >>> from cognite.client import CogniteClient, AsyncCogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> client = CogniteClient()
                 >>> # async_client = AsyncCogniteClient()  # another option
-                >>> client.time_series.data.delete_range(start="1w-ago", end="now", id=1)
+                >>> client.time_series.data.delete_range(
+                ...     start="1w-ago", end="now", instance_id=NodeId("my-space", "my-ts-xid")
+                ... )
 
             Deleting the data from now until 2 days in the future from a time series containing e.g. forecasted data:
 

cognite/client/_api/files.py

@@ -272,12 +272,13 @@ async def retrieve(
 
         Examples:
 
-            Get file metadata by id:
+            Get file metadata by instance id:
 
                 >>> from cognite.client import CogniteClient, AsyncCogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> client = CogniteClient()
                 >>> # async_client = AsyncCogniteClient()  # another option
-                >>> res = client.files.retrieve(id=1)
+                >>> res = client.files.retrieve(instance_id=NodeId("my-space", "my-file-xid"))
 
             Get file metadata by external id:
 
@@ -308,14 +309,17 @@ async def retrieve_multiple(
 
         Examples:
 
-            Get file metadatas by id:
+            Get file metadatas by instance id:
 
                 >>> from cognite.client import CogniteClient, AsyncCogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> client = CogniteClient()
                 >>> # async_client = AsyncCogniteClient()  # another option
-                >>> res = client.files.retrieve_multiple(ids=[1, 2, 3])
+                >>> res = client.files.retrieve_multiple(
+                ...     instance_ids=[NodeId("my-space", "my-file-xid")]
+                ... )
 
-            Get file_metadatas by external id:
+            Get file metadatas by external id:
 
                 >>> res = client.files.retrieve_multiple(external_ids=["abc", "def"])
         """
@@ -501,8 +505,21 @@ async def upload_content(
             path (Path | str): Local file path.
             external_id (str | None): The external ID provided by the client. Must be unique within the project.
             instance_id (NodeId | tuple[str, str] | None): Instance ID of the file (CogniteFile).
+
         Returns:
             FileMetadata: No description.
+
+        Examples:
+
+            Upload file content using instance_id:
+
+                >>> from cognite.client import CogniteClient, AsyncCogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
+                >>> client = CogniteClient()
+                >>> # async_client = AsyncCogniteClient()  # another option
+                >>> res = client.files.upload_content(
+                ...     "/path/to/file.txt", instance_id=NodeId("my-space", "my-file-xid")
+                ... )
         """
         path = Path(path)
         if path.is_dir():
@@ -735,19 +752,19 @@ async def upload_content_bytes(
 
         Examples:
 
-            Finish a file creation by uploading the content using external_id:
+            Finish a file creation by uploading the content using instance_id:
 
                 >>> from cognite.client import CogniteClient, AsyncCogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> client = CogniteClient()
                 >>> # async_client = AsyncCogniteClient()  # another option
-                >>> res = client.files.upload_content_bytes(b"some content", external_id="my_file_xid")
-
-            ...or by using instance_id:
-
-                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> res = client.files.upload_content_bytes(
                 ...     b"some content", instance_id=NodeId("my-space", "my_file_xid")
                 ... )
+
+            ...or by using external_id:
+
+                >>> res = client.files.upload_content_bytes(b"some content", external_id="my_file_xid")
         """
         identifiers = IdentifierSequence.load(external_ids=external_id, instance_ids=instance_id).as_singleton()
 
@@ -1027,10 +1044,11 @@ async def multipart_upload_content_session(
             Upload binary data in two chunks:
 
                 >>> from cognite.client import CogniteClient, AsyncCogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> client = CogniteClient()
                 >>> # async_client = AsyncCogniteClient()  # another option
                 >>> with client.files.multipart_upload_content_session(
-                ...     external_id="external-id", parts=2
+                ...     instance_id=NodeId("my-space", "my-file-xid"), parts=2
                 ... ) as session:
                 ...     # Note that the minimum chunk size is 5 MiB.
                 ...     session.upload_part(0, "hello" * 1_200_000)
@@ -1159,6 +1177,18 @@ async def retrieve_download_urls(
 
         Returns:
             dict[int, str] | dict[str, str] | dict[NodeId, str] | dict[int | str | NodeId, str]: Dictionary containing download urls.
+
+        Examples:
+
+            Get download URLs by instance id:
+
+                >>> from cognite.client import CogniteClient, AsyncCogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
+                >>> client = CogniteClient()
+                >>> # async_client = AsyncCogniteClient()  # another option
+                >>> urls = client.files.retrieve_download_urls(
+                ...     instance_id=NodeId("my-space", "my-file-xid")
+                ... )
         """
         identifiers = IdentifierSequence.load(ids=id, external_ids=external_id, instance_ids=instance_id)
 
@@ -1251,9 +1281,10 @@ async def download(
                 ...     directory="my_directory", id=[1, 2, 3], external_id=["abc", "def"]
                 ... )
 
-            Download files by id to the current directory:
+            Download files by instance id to the current directory:
 
-                >>> client.files.download(directory=".", id=[1, 2, 3])
+                >>> from cognite.client.data_classes.data_modeling import NodeId
+                >>> client.files.download(directory=".", instance_id=NodeId("my-space", "my-file-xid"))
         """
         identifiers = IdentifierSequence.load(ids=id, external_ids=external_id, instance_ids=instance_id)
 
@@ -1389,11 +1420,14 @@ async def download_to_path(
 
         Examples:
 
-            Download a file by id:
+            Download a file by instance id:
                 >>> from cognite.client import CogniteClient, AsyncCogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> client = CogniteClient()
                 >>> # async_client = AsyncCogniteClient()  # another option
-                >>> client.files.download_to_path("~/mydir/my_downloaded_file.txt", id=123)
+                >>> client.files.download_to_path(
+                ...     "~/mydir/my_downloaded_file.txt", instance_id=NodeId("my-space", "my-file-xid")
+                ... )
         """
         path = Path(path)
         if not path.parent.is_dir():
@@ -1418,9 +1452,12 @@ async def download_bytes(
             Download a file's content into memory:
 
                 >>> from cognite.client import CogniteClient, AsyncCogniteClient
+                >>> from cognite.client.data_classes.data_modeling import NodeId
                 >>> client = CogniteClient()
                 >>> # async_client = AsyncCogniteClient()  # another option
-                >>> file_content = client.files.download_bytes(id=1)
+                >>> file_content = client.files.download_bytes(
+                ...     instance_id=NodeId("my-space", "my-file-xid")
+                ... )
 
         Returns:
             bytes: The file in binary format