Some doc improvements. Fix broken code examples in `InstancesAPI.[que…

…ry/sync]` (#1377)

cognite/client/_api/assets.py

@@ -248,7 +248,7 @@ def aggregate(self, filter: AssetFilter | dict | None = None) -> list[AssetAggre
         """`Aggregate assets <https://developer.cognite.com/api#tag/Assets/operation/aggregateAssets>`_
 
         Args:
-            filter (AssetFilter | dict | None): Filter on assets filter with exact match
+            filter (AssetFilter | dict | None): Filter on assets with strict matching.
 
         Returns:
             list[AssetAggregate]: List of asset aggregates
@@ -270,7 +270,7 @@ def aggregate_metadata_keys(self, filter: AssetFilter | dict | None = None) -> S
             In the case of text fields, the values are aggregated in a case-insensitive manner
 
         Args:
-            filter (AssetFilter | dict | None): Filter on assets filter with exact match
+            filter (AssetFilter | dict | None): Filter on assets with strict matching.
 
         Returns:
             Sequence[AggregateBucketResult]: List of asset aggregates
@@ -298,7 +298,7 @@ def aggregate_metadata_values(
 
         Args:
             keys (Sequence[str]): Metadata key(s) to apply the aggregation on. Currently supports exactly one key per request.
-            filter (AssetFilter | dict | None): Filter on assets filter with exact match
+            filter (AssetFilter | dict | None): Filter on assets with strict matching.
 
         Returns:
             Sequence[AggregateBucketResult]: List of asset aggregates
@@ -329,8 +329,8 @@ def aggregate_count(
 
         Args:
             property (AssetPropertyLike | None): If specified, get an approximate number of asset with a specific property (property is not null) and matching the filters.
-            advanced_filter (Filter | dict | None): The filter to narrow down the asset to count.
-            filter (AssetFilter | dict | None): The filter to narrow down asset to count requirering exact match.
+            advanced_filter (Filter | dict | None): The advaned filter to narrow down the assets to count.
+            filter (AssetFilter | dict | None): The filter to narrow down the assets to count (strict matching).
 
         Returns:
             int: The number of assets matching the specified filters.
@@ -372,9 +372,9 @@ def aggregate_cardinality_values(
 
         Args:
             property (AssetPropertyLike): The property to count the cardinality of.
-            advanced_filter (Filter | dict | None): The filter to narrow down the assets to count cardinality.
+            advanced_filter (Filter | dict | None): The advanced filter to narrow down assets.
             aggregate_filter (AggregationFilter | dict | None): The filter to apply to the resulting buckets.
-            filter (AssetFilter | dict | None): The filter to narrow down the assets to count requirering exact match.
+            filter (AssetFilter | dict | None): The filter to narrow down assets (strict matching).
         Returns:
             int: The number of properties matching the specified filters and search.
 
@@ -415,11 +415,11 @@ def aggregate_cardinality_properties(
         """`Find approximate paths count for assets.  <https://developer.cognite.com/api#tag/Assets/operation/aggregateAssets>`_
 
         Args:
-            path (AssetPropertyLike): The scope in every document to aggregate properties.  The only value allowed now is ["metadata"].
+            path (AssetPropertyLike): The scope in every document to aggregate properties. The only value allowed now is ["metadata"].
                 It means to aggregate only metadata properties (aka keys).
-            advanced_filter (Filter | dict | None): The filter to narrow down the assets to count cardinality.
+            advanced_filter (Filter | dict | None): The advanced filter to narrow down assets.
             aggregate_filter (AggregationFilter | dict | None): The filter to apply to the resulting buckets.
-            filter (AssetFilter | dict | None): The filter to narrow down the assets to count requirering exact match.
+            filter (AssetFilter | dict | None): The filter to narrow down assets (strict matching).
         Returns:
             int: The number of properties matching the specified filters.
 
@@ -452,9 +452,9 @@ def aggregate_unique_values(
 
         Args:
             property (AssetPropertyLike): The property to group by.
-            advanced_filter (Filter | dict | None): The filter to narrow down the assets to count cardinality.
+            advanced_filter (Filter | dict | None): The advanced filter to narrow down assets.
             aggregate_filter (AggregationFilter | dict | None): The filter to apply to the resulting buckets.
-            filter (AssetFilter | dict | None): The filter to narrow down the assets to count requirering exact match.
+            filter (AssetFilter | dict | None): The filter to narrow down assets (strict matching).
 
         Returns:
             UniqueResultList: List of unique values of assets matching the specified filters and search.
@@ -515,9 +515,9 @@ def aggregate_unique_properties(
         Args:
             path (AssetPropertyLike): The scope in every document to aggregate properties.  The only value allowed now is ["metadata"].
                 It means to aggregate only metadata properties (aka keys).
-            advanced_filter (Filter | dict | None): The filter to narrow down the assets to count cardinality.
+            advanced_filter (Filter | dict | None): The advanced filter to narrow down assets.
             aggregate_filter (AggregationFilter | dict | None): The filter to apply to the resulting buckets.
-            filter (AssetFilter | dict | None): The filter to narrow down the assets to count requirering exact match.
+            filter (AssetFilter | dict | None): The filter to narrow down assets (strict matching).
 
         Returns:
             UniqueResultList: List of unique values of assets matching the specified filters and search.

cognite/client/_api/data_modeling/instances.py

@@ -905,7 +905,7 @@ def query(self, query: Query) -> QueryResult:
                 ...     },
                 ...     select = {
                 ...         "actors": Select(
-                ...             [SourceSelector(actor_id, ["name"])], sort=[actor_id.as_property_ref("name")]),
+                ...             [SourceSelector(actor_id, ["name"])], sort=[InstanceSort(actor_id.as_property_ref("name"))]),
                 ...     },
                 ... )
                 >>> res = c.data_modeling.instances.query(query)
@@ -928,6 +928,7 @@ def sync(self, query: Query) -> QueryResult:
             Find actors in movies released before 2000 sorted by actor name:
 
                 >>> from cognite.client import CogniteClient
+                >>> from cognite.client.data_classes.data_modeling.instances import InstanceSort
                 >>> from cognite.client.data_classes.data_modeling.query import Query, Select, NodeResultSetExpression, EdgeResultSetExpression, SourceSelector
                 >>> from cognite.client.data_classes.filters import Range, Equals
                 >>> from cognite.client.data_classes.data_modeling.ids import ViewId
@@ -942,7 +943,7 @@ def sync(self, query: Query) -> QueryResult:
                 ...     },
                 ...     select = {
                 ...         "actors": Select(
-                ...             [SourceSelector(actor_id, ["name"])], sort=[actor_id.as_property_ref("name")]),
+                ...             [SourceSelector(actor_id, ["name"])], sort=[InstanceSort(actor_id.as_property_ref("name"))]),
                 ...     },
                 ... )
                 >>> res = c.data_modeling.instances.sync(query)

cognite/client/_api/datapoints.py

@@ -1099,7 +1099,7 @@ def retrieve_dataframe_in_tz(
 
         if exactly_one_is_not_none(aggregates, granularity):
             raise ValueError(
-                "Got only one of 'aggregates' and 'granularity'."
+                "Got only one of 'aggregates' and 'granularity'. "
                 "Pass both to get aggregates, or neither to get raw data"
             )
 

cognite/client/_api/documents.py

@@ -61,18 +61,17 @@ def download_page_as_png_bytes(self, id: int, page_number: int = 1) -> bytes:
 
         Examples:
 
-        Download image preview of page 5 of file with id 123:
+            Download image preview of page 5 of file with id 123:
 
-            >>> from cognite.client import CogniteClient
-            >>> c = CogniteClient()
-            >>> content = c.documents.previews.download_page_as_png_bytes(id=123, page_number=5)
-
-        Download an image preview and display using IPython.display.Image (for example in a Jupyter Notebook):
+                >>> from cognite.client import CogniteClient
+                >>> c = CogniteClient()
+                >>> content = c.documents.previews.download_page_as_png_bytes(id=123, page_number=5)
 
-            >>> from IPython.display import Image
-            >>> binary_png = c.documents.previews.download_page_as_png_bytes(id=123, page_number=5)
-            >>> Image(binary_png)
+            Download an image preview and display using IPython.display.Image (for example in a Jupyter Notebook):
 
+                >>> from IPython.display import Image
+                >>> binary_png = c.documents.previews.download_page_as_png_bytes(id=123, page_number=5)
+                >>> Image(binary_png)
         """
         res = self._do_request(
             "GET", f"{self._RESOURCE_PATH}/{id}/preview/image/pages/{page_number}", accept="image/png"
@@ -127,11 +126,11 @@ def download_document_as_pdf_bytes(self, id: int) -> bytes:
 
         Examples:
 
-        Download PDF preview of file with id 123:
+            Download PDF preview of file with id 123:
 
-            >>> from cognite.client import CogniteClient
-            >>> c = CogniteClient()
-            >>> content = c.documents.previews.download_document_as_pdf_bytes(id=123)
+                >>> from cognite.client import CogniteClient
+                >>> c = CogniteClient()
+                >>> content = c.documents.previews.download_document_as_pdf_bytes(id=123)
         """
         res = self._do_request("GET", f"{self._RESOURCE_PATH}/{id}/preview/pdf", accept="application/pdf")
         return res.content
@@ -181,11 +180,11 @@ def retrieve_pdf_link(self, id: int) -> TemporaryLink:
 
         Examples:
 
-        Retrieve the PDF preview download link for document with id 123:
+            Retrieve the PDF preview download link for document with id 123:
 
-            >>> from cognite.client import CogniteClient
-            >>> c = CogniteClient()
-            >>> link = c.documents.previews.retrieve_pdf_link(id=123)
+                >>> from cognite.client import CogniteClient
+                >>> c = CogniteClient()
+                >>> link = c.documents.previews.retrieve_pdf_link(id=123)
         """
         res = self._get(f"{self._RESOURCE_PATH}/{id}/preview/pdf/temporarylink")
         return TemporaryLink.load(res.json())
@@ -271,21 +270,20 @@ def aggregate_count(self, query: str | None = None, filter: Filter | dict | None
 
         Examples:
 
-        Count the number of documents in your CDF project:
-
-            >>> from cognite.client import CogniteClient
-            >>> c = CogniteClient()
-            >>> count = c.documents.aggregate_count()
+            Count the number of documents in your CDF project:
 
-        Count the number of PDF documents in your CDF project:
+                >>> from cognite.client import CogniteClient
+                >>> c = CogniteClient()
+                >>> count = c.documents.aggregate_count()
 
-            >>> from cognite.client import CogniteClient
-            >>> from cognite.client.data_classes import filters
-            >>> from cognite.client.data_classes.documents import DocumentProperty
-            >>> c = CogniteClient()
-            >>> is_pdf = filters.Equals(DocumentProperty.mime_type, "application/pdf")
-            >>> pdf_count = c.documents.aggregate_count(filter=is_pdf)
+            Count the number of PDF documents in your CDF project:
 
+                >>> from cognite.client import CogniteClient
+                >>> from cognite.client.data_classes import filters
+                >>> from cognite.client.data_classes.documents import DocumentProperty
+                >>> c = CogniteClient()
+                >>> is_pdf = filters.Equals(DocumentProperty.mime_type, "application/pdf")
+                >>> pdf_count = c.documents.aggregate_count(filter=is_pdf)
         """
         self._validate_filter(filter)
         return self._advanced_aggregate(
@@ -368,13 +366,12 @@ def aggregate_cardinality_properties(
 
         Examples:
 
-        Count the number metadata keys for documents in your CDF project:
-
-            >>> from cognite.client import CogniteClient
-            >>> from cognite.client.data_classes.documents import SourceFileProperty
-            >>> c = CogniteClient()
-            >>> count = c.documents.aggregate_cardinality_properties(SourceFileProperty.metadata)
+            Count the number metadata keys for documents in your CDF project:
 
+                >>> from cognite.client import CogniteClient
+                >>> from cognite.client.data_classes.documents import SourceFileProperty
+                >>> c = CogniteClient()
+                >>> count = c.documents.aggregate_cardinality_properties(SourceFileProperty.metadata)
         """
         self._validate_filter(filter)
 
@@ -408,35 +405,34 @@ def aggregate_unique_values(
 
         Examples:
 
-        Get the unique types with count of documents in your CDF project:
-
-            >>> from cognite.client import CogniteClient
-            >>> from cognite.client.data_classes.documents import DocumentProperty
-            >>> c = CogniteClient()
-            >>> result = c.documents.aggregate_unique_values(DocumentProperty.mime_type)
-            >>> unique_types = result.unique
+            Get the unique types with count of documents in your CDF project:
 
-        Get the different languages with count for documents with external id prefix "abc":
+                >>> from cognite.client import CogniteClient
+                >>> from cognite.client.data_classes.documents import DocumentProperty
+                >>> c = CogniteClient()
+                >>> result = c.documents.aggregate_unique_values(DocumentProperty.mime_type)
+                >>> unique_types = result.unique
 
-            >>> from cognite.client import CogniteClient
-            >>> from cognite.client.data_classes import filters
-            >>> from cognite.client.data_classes.documents import DocumentProperty
-            >>> c = CogniteClient()
-            >>> is_abc = filters.Prefix(DocumentProperty.external_id, "abc")
-            >>> result = c.documents.aggregate_unique_values(DocumentProperty.language, filter=is_abc)
-            >>> unique_languages = result.unique
+            Get the different languages with count for documents with external id prefix "abc":
 
-        Get the unique mime types with count of documents, but exclude mime types that start with text:
+                >>> from cognite.client import CogniteClient
+                >>> from cognite.client.data_classes import filters
+                >>> from cognite.client.data_classes.documents import DocumentProperty
+                >>> c = CogniteClient()
+                >>> is_abc = filters.Prefix(DocumentProperty.external_id, "abc")
+                >>> result = c.documents.aggregate_unique_values(DocumentProperty.language, filter=is_abc)
+                >>> unique_languages = result.unique
 
-            >>> from cognite.client import CogniteClient
-            >>> from cognite.client.data_classes.documents import DocumentProperty
-            >>> from cognite.client.data_classes import aggregations
-            >>> c = CogniteClient()
-            >>> agg = aggregations
-            >>> is_not_text = agg.Not(agg.Prefix("text"))
-            >>> result = c.documents.aggregate_unique_values(DocumentProperty.mime_type, aggregate_filter=is_not_text)
-            >>> unique_mime_types = result.unique
+            Get the unique mime types with count of documents, but exclude mime types that start with text:
 
+                >>> from cognite.client import CogniteClient
+                >>> from cognite.client.data_classes.documents import DocumentProperty
+                >>> from cognite.client.data_classes import aggregations
+                >>> c = CogniteClient()
+                >>> agg = aggregations
+                >>> is_not_text = agg.Not(agg.Prefix("text"))
+                >>> result = c.documents.aggregate_unique_values(DocumentProperty.mime_type, aggregate_filter=is_not_text)
+                >>> unique_mime_types = result.unique
         """
         self._validate_filter(filter)
         return self._advanced_aggregate(
@@ -470,13 +466,12 @@ def aggregate_unique_properties(
 
         Examples:
 
-        Get the unique metadata keys with count of documents in your CDF project:
-
-            >>> from cognite.client import CogniteClient
-            >>> from cognite.client.data_classes.documents import SourceFileProperty
-            >>> c = CogniteClient()
-            >>> result = c.documents.aggregate_unique_values(SourceFileProperty.metadata)
+            Get the unique metadata keys with count of documents in your CDF project:
 
+                >>> from cognite.client import CogniteClient
+                >>> from cognite.client.data_classes.documents import SourceFileProperty
+                >>> c = CogniteClient()
+                >>> result = c.documents.aggregate_unique_values(SourceFileProperty.metadata)
         """
         self._validate_filter(filter)
 
@@ -510,12 +505,11 @@ def retrieve_content(self, id: int) -> bytes:
 
         Examples:
 
-        Retrieve the content of a document with id 123:
-
-            >>> from cognite.client import CogniteClient
-            >>> c = CogniteClient()
-            >>> content = c.documents.retrieve_content(id=123)
+            Retrieve the content of a document with id 123:
 
+                >>> from cognite.client import CogniteClient
+                >>> c = CogniteClient()
+                >>> content = c.documents.retrieve_content(id=123)
         """
         response = self._do_request("GET", f"{self._RESOURCE_PATH}/{id}/content", accept="text/plain")
         return response.content

cognite/client/_api/files.py

@@ -538,17 +538,17 @@ def upload_bytes(
             security_categories (Sequence[int] | None): Security categories to attach to this file.
             overwrite (bool): If 'overwrite' is set to true, and the POST body content specifies a 'externalId' field, fields for the file found for externalId can be overwritten. The default setting is false. If metadata is included in the request body, all of the original metadata will be overwritten. The actual file will be overwritten after successful upload. If there is no successful upload, the current file contents will be kept. File-Asset mappings only change if explicitly stated in the assetIds field of the POST json body. Do not set assetIds in request body if you want to keep the current file-asset mappings.
 
+        Returns:
+            FileMetadata: No description.
+
         Examples:
 
             Upload a file from memory::
 
                 >>> from cognite.client import CogniteClient
                 >>> c = CogniteClient()
                 >>> res = c.files.upload_bytes(b"some content", name="my_file", asset_ids=[1,2,3])
-
-
-        Returns:
-            FileMetadata: No description."""
+        """
         file_metadata = FileMetadata(
             name=name,
             external_id=external_id,

cognite/client/_api/functions.py

@@ -959,7 +959,9 @@ def list(
             try:
                 IdentifierSequence.load(ids=function_id, external_ids=function_external_id).assert_singleton()
             except ValueError:
-                raise AssertionError("Only function_id or function_external_id allowed when listing schedules.")
+                raise AssertionError(
+                    "Both 'function_id' and 'function_external_id' were supplied, pass exactly one or neither."
+                )
 
         if is_unlimited(limit):
             limit = self._LIST_LIMIT_CEILING