diff --git a/cognite/client/_api/assets.py b/cognite/client/_api/assets.py index cec0351f6..6bc314961 100644 --- a/cognite/client/_api/assets.py +++ b/cognite/client/_api/assets.py @@ -248,7 +248,7 @@ def aggregate(self, filter: AssetFilter | dict | None = None) -> list[AssetAggre """`Aggregate assets `_ 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. `_ 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. diff --git a/cognite/client/_api/data_modeling/instances.py b/cognite/client/_api/data_modeling/instances.py index b9ec46634..a3d2e6cd7 100644 --- a/cognite/client/_api/data_modeling/instances.py +++ b/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) diff --git a/cognite/client/_api/datapoints.py b/cognite/client/_api/datapoints.py index 77d703d27..923de9efa 100644 --- a/cognite/client/_api/datapoints.py +++ b/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" ) diff --git a/cognite/client/_api/documents.py b/cognite/client/_api/documents.py index 18b1df625..f58e571ff 100644 --- a/cognite/client/_api/documents.py +++ b/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 diff --git a/cognite/client/_api/files.py b/cognite/client/_api/files.py index 4bb90c596..10b427ea2 100644 --- a/cognite/client/_api/files.py +++ b/cognite/client/_api/files.py @@ -538,6 +538,9 @@ 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:: @@ -545,10 +548,7 @@ def upload_bytes( >>> 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, diff --git a/cognite/client/_api/functions.py b/cognite/client/_api/functions.py index 7bdc3420d..304988cb1 100644 --- a/cognite/client/_api/functions.py +++ b/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 diff --git a/cognite/client/_http_client.py b/cognite/client/_http_client.py index 7b49670d2..b0c83672a 100644 --- a/cognite/client/_http_client.py +++ b/cognite/client/_http_client.py @@ -141,13 +141,7 @@ def _do_request(self, method: str, url: str, **kwargs: Any) -> requests.Response Sometimes the appropriate built-in networking exception is not in the context, sometimes the requests exception is not in the context, so we need to check for the appropriate built-in exceptions, urllib3 exceptions, and requests exceptions. - - Args: - method (str): No description. - url (str): No description. - **kwargs (Any): No description. - Returns: - requests.Response: No description.""" + """ try: res = self.session.request(method=method, url=url, **kwargs) return res diff --git a/cognite/client/data_classes/data_modeling/query.py b/cognite/client/data_classes/data_modeling/query.py index 09865f167..791bc307e 100644 --- a/cognite/client/data_classes/data_modeling/query.py +++ b/cognite/client/data_classes/data_modeling/query.py @@ -71,7 +71,7 @@ class Query: r"""Query allows you to do advanced queries on the data model. Args: - with\_ (dict[str, ResultSetExpression]): No description. + with\_ (dict[str, ResultSetExpression]): A dictionary of result set expressions to use in the query. The keys are used to reference the result set expressions in the select and parameters. select (dict[str, Select]): A dictionary of select expressions to use in the query. The keys must match the keys in the with\_ dictionary. The select expressions define which properties to include in the result set. parameters (dict[str, PropertyValue] | None): Values in filters can be parameterised. Parameters are provided as part of the query object, and referenced in the filter itself. cursors (Mapping[str, str | None] | None): A dictionary of cursors to use in the query. These are for pagination purposes, for example, in the sync endpoint. @@ -84,8 +84,7 @@ def __init__( parameters: dict[str, PropertyValue] | None = None, cursors: Mapping[str, str | None] | None = None, ) -> None: - with_keys = set(with_) - if not_matching := set(select) - with_keys: + if not_matching := set(select) - set(with_): raise ValueError( f"The select keys must match the with keys, the following are not matching: {not_matching}" ) diff --git a/cognite/client/utils/_time.py b/cognite/client/utils/_time.py index 86f933948..6ec57d83e 100644 --- a/cognite/client/utils/_time.py +++ b/cognite/client/utils/_time.py @@ -75,9 +75,8 @@ def datetime_to_ms(dt: datetime) -> int: except OSError as e: # OSError is raised if dt.timestamp() is called before 1970-01-01 on Windows for naive datetime. raise ValueError( - "Failed to convert datetime to epoch. " - "This likely because you are using a naive datetime." - " Try using a timezone aware datetime instead." + "Failed to convert datetime to epoch. This likely because you are using a naive datetime. " + "Try using a timezone aware datetime instead." ) from e diff --git a/tests/tests_unit/test_api/test_datapoints.py b/tests/tests_unit/test_api/test_datapoints.py index c8c315501..7166e3eb3 100644 --- a/tests/tests_unit/test_api/test_datapoints.py +++ b/tests/tests_unit/test_api/test_datapoints.py @@ -820,14 +820,14 @@ class TestRetrieveDataPointsInTz: {"id": 123, "start": datetime(2023, 1, 1), "end": datetime(2023, 1, 2), "aggregates": "average"}, "Europe/Oslo", "Europe/Oslo", - "Got only one of 'aggregates' and 'granularity'.Pass both to get aggregates, or neither to get raw data", + "Got only one of 'aggregates' and 'granularity'. Pass both to get aggregates, or neither to get raw data", id="Missing granularity", ), pytest.param( {"id": 123, "start": datetime(2023, 1, 1), "end": datetime(2023, 1, 2), "granularity": "1year"}, "Europe/Oslo", "Europe/Oslo", - "Got only one of 'aggregates' and 'granularity'.Pass both to get aggregates, or neither to get raw data", + "Got only one of 'aggregates' and 'granularity'. Pass both to get aggregates, or neither to get raw data", id="Missing aggregates", ), ], diff --git a/tests/tests_unit/test_api/test_functions.py b/tests/tests_unit/test_api/test_functions.py index 19754764d..d804cae94 100644 --- a/tests/tests_unit/test_api/test_functions.py +++ b/tests/tests_unit/test_api/test_functions.py @@ -895,7 +895,10 @@ def test_list_schedules_with_limit(self, mock_filter_function_schedules_response def test_list_schedules_with_function_id_and_function_external_id_raises(self, cognite_client): with pytest.raises(AssertionError) as excinfo: cognite_client.functions.schedules.list(function_id=123, function_external_id="my-func") - assert "Only function_id or function_external_id allowed when listing schedules." == excinfo.value.args[0] + assert ( + "Both 'function_id' and 'function_external_id' were supplied, pass exactly one or neither." + == excinfo.value.args[0] + ) def test_create_schedules_with_function_external_id( self, mock_function_schedules_response_xid_not_valid_with_oidc, cognite_client