Update v8 with the latest commits from v7

.gemini/config.yaml

@@ -4,7 +4,8 @@ code_review:
   comment_severity_threshold: HIGH
   max_review_comments: -1
   pull_request_opened:
-    help: true
-    summary: false
-    code_review: false
-ignore_patterns: []
+    help: false
+    summary: true
+    code_review: true
+    include_drafts: false
+ignore_patterns: []

cognite/client/_api/synthetic_time_series.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 import asyncio
+import datetime
 import re
 from collections.abc import Mapping, Sequence
-from datetime import datetime
 from typing import TYPE_CHECKING, Any, Literal, Union, cast, overload
+from zoneinfo import ZoneInfo
 
 from cognite.client._api_client import APIClient
 from cognite.client.data_classes import Datapoints, DatapointsList, TimeSeries, TimeSeriesWrite
@@ -13,7 +14,7 @@
 from cognite.client.utils._concurrency import AsyncSDKTask, execute_async_tasks
 from cognite.client.utils._identifier import Identifier, InstanceId
 from cognite.client.utils._importing import local_import
-from cognite.client.utils._time import timestamp_to_ms
+from cognite.client.utils._time import convert_timezone_to_str, timestamp_to_ms
 from cognite.client.utils.useful_types import SequenceNotStr
 
 if TYPE_CHECKING:
@@ -58,54 +59,63 @@ def _get_semaphore(self, operation: Literal["read", "write", "delete"]) -> async
     async def query(
         self,
         expressions: SequenceNotStr[str] | SequenceNotStr[sympy.Basic],
-        start: int | str | datetime,
-        end: int | str | datetime,
+        start: int | str | datetime.datetime,
+        end: int | str | datetime.datetime,
         limit: int | None = None,
         variables: Mapping[str | sympy.Symbol, str | NodeId | TimeSeries | TimeSeriesWrite] | None = None,
         aggregate: str | None = None,
         granularity: str | None = None,
         target_unit: str | None = None,
         target_unit_system: str | None = None,
+        timezone: str | datetime.timezone | ZoneInfo | None = None,
     ) -> DatapointsList: ...
 
     @overload
     async def query(
         self,
         expressions: str | sympy.Basic,
-        start: int | str | datetime,
-        end: int | str | datetime,
+        start: int | str | datetime.datetime,
+        end: int | str | datetime.datetime,
         limit: int | None = None,
         variables: Mapping[str | sympy.Symbol, str | NodeId | TimeSeries | TimeSeriesWrite] | None = None,
         aggregate: str | None = None,
         granularity: str | None = None,
         target_unit: str | None = None,
         target_unit_system: str | None = None,
+        timezone: str | datetime.timezone | ZoneInfo | None = None,
     ) -> Datapoints: ...
 
     async def query(
         self,
         expressions: str | sympy.Basic | Sequence[str] | Sequence[sympy.Basic],
-        start: int | str | datetime,
-        end: int | str | datetime,
+        start: int | str | datetime.datetime,
+        end: int | str | datetime.datetime,
         limit: int | None = None,
         variables: Mapping[str | sympy.Symbol, str | NodeId | TimeSeries | TimeSeriesWrite] | None = None,
         aggregate: str | None = None,
         granularity: str | None = None,
         target_unit: str | None = None,
         target_unit_system: str | None = None,
+        timezone: str | datetime.timezone | ZoneInfo | None = None,
     ) -> Datapoints | DatapointsList:
         """`Calculate the result of a function on time series. <https://developer.cognite.com/api#tag/Synthetic-Time-Series/operation/querySyntheticTimeseries>`_
 
+        Info:
+            You can read the guide to synthetic time series in our `documentation <https://docs.cognite.com/dev/concepts/resource_types/synthetic_timeseries>`_.
+
         Args:
             expressions (str | sympy.Basic | Sequence[str] | Sequence[sympy.Basic]): Functions to be calculated. Supports both strings and sympy expressions. Strings can have either the API `ts{}` syntax, or contain variable names to be replaced using the `variables` parameter.
-            start (int | str | datetime): Inclusive start.
-            end (int | str | datetime): Exclusive end.
+            start (int | str | datetime.datetime): Inclusive start.
+            end (int | str | datetime.datetime): Exclusive end.
             limit (int | None): Number of datapoints per expression to retrieve.
             variables (Mapping[str | sympy.Symbol, str | NodeId | TimeSeries | TimeSeriesWrite] | None): An optional map of symbol replacements.
             aggregate (str | None): use this aggregate when replacing entries from `variables`, does not affect time series given in the `ts{}` syntax.
             granularity (str | None): use this granularity with the aggregate.
             target_unit (str | None): use this target_unit when replacing entries from `variables`, does not affect time series given in the `ts{}` syntax.
             target_unit_system (str | None): Same as target_unit, but with unit system (e.g. SI). Only one of target_unit and target_unit_system can be specified.
+            timezone (str | datetime.timezone | ZoneInfo | None): The timezone to use when aggregating datapoints. For aggregates of granularity 'hour' and longer,
+                which time zone should we align to. Align to the start of the hour, start of the day or start of the month. For time zones of type Region/Location,
+                the aggregate duration can vary, typically due to daylight saving time. For time zones of type UTC+/-HH:MM, use increments of 15 minutes. Default: "UTC" (None)
 
         Returns:
             Datapoints | DatapointsList: A DatapointsList object containing the calculated data.
@@ -152,7 +162,9 @@ async def query(
                 ...     variables={x: "foo", y: "bar"},
                 ...     aggregate="interpolation",
                 ...     granularity="15m",
-                ...     target_unit="temperature:deg_c")
+                ...     target_unit="temperature:deg_c",
+                ...     timezone="Europe/Oslo",  # can also use this format: 'UTC+05:30'
+                ... )
         """
         if is_unlimited(limit):
             limit = cast(int, float("inf"))
@@ -166,6 +178,10 @@ async def query(
                 user_expr, variables, aggregate, granularity, target_unit, target_unit_system
             )
             query = {"expression": expression, "start": timestamp_to_ms(start), "end": timestamp_to_ms(end)}
+            if timezone is not None:
+                if isinstance(timezone, (ZoneInfo, datetime.timezone)):
+                    timezone = convert_timezone_to_str(timezone)
+                query["timeZone"] = timezone
             tasks.append(AsyncSDKTask(self._fetch_datapoints, query, limit, short_expression))
 
         datapoints_summary = await execute_async_tasks(tasks)

cognite/client/_sync_api/synthetic_time_series.py

@@ -1,15 +1,16 @@
 """
 ===============================================================================
-ba420a10cb3584372ce6ee71cc57255c
+c30ea9cd2b7de10dc2a40c7c1065ef4a
 This file is auto-generated from the Async API modules, - do not edit manually!
 ===============================================================================
 """
 
 from __future__ import annotations
 
+import datetime
 from collections.abc import Mapping, Sequence
-from datetime import datetime
 from typing import TYPE_CHECKING, overload
+from zoneinfo import ZoneInfo
 
 from cognite.client import AsyncCogniteClient
 from cognite.client._sync_api_client import SyncAPIClient
@@ -32,55 +33,64 @@ def __init__(self, async_client: AsyncCogniteClient) -> None:
     def query(
         self,
         expressions: SequenceNotStr[str] | SequenceNotStr[sympy.Basic],
-        start: int | str | datetime,
-        end: int | str | datetime,
+        start: int | str | datetime.datetime,
+        end: int | str | datetime.datetime,
         limit: int | None = None,
         variables: Mapping[str | sympy.Symbol, str | NodeId | TimeSeries | TimeSeriesWrite] | None = None,
         aggregate: str | None = None,
         granularity: str | None = None,
         target_unit: str | None = None,
         target_unit_system: str | None = None,
+        timezone: str | datetime.timezone | ZoneInfo | None = None,
     ) -> DatapointsList: ...
 
     @overload
     def query(
         self,
         expressions: str | sympy.Basic,
-        start: int | str | datetime,
-        end: int | str | datetime,
+        start: int | str | datetime.datetime,
+        end: int | str | datetime.datetime,
         limit: int | None = None,
         variables: Mapping[str | sympy.Symbol, str | NodeId | TimeSeries | TimeSeriesWrite] | None = None,
         aggregate: str | None = None,
         granularity: str | None = None,
         target_unit: str | None = None,
         target_unit_system: str | None = None,
+        timezone: str | datetime.timezone | ZoneInfo | None = None,
     ) -> Datapoints: ...
 
     def query(
         self,
         expressions: str | sympy.Basic | Sequence[str] | Sequence[sympy.Basic],
-        start: int | str | datetime,
-        end: int | str | datetime,
+        start: int | str | datetime.datetime,
+        end: int | str | datetime.datetime,
         limit: int | None = None,
         variables: Mapping[str | sympy.Symbol, str | NodeId | TimeSeries | TimeSeriesWrite] | None = None,
         aggregate: str | None = None,
         granularity: str | None = None,
         target_unit: str | None = None,
         target_unit_system: str | None = None,
+        timezone: str | datetime.timezone | ZoneInfo | None = None,
     ) -> Datapoints | DatapointsList:
         """
         `Calculate the result of a function on time series. <https://developer.cognite.com/api#tag/Synthetic-Time-Series/operation/querySyntheticTimeseries>`_
 
+        Info:
+            You can read the guide to synthetic time series in our `documentation <https://docs.cognite.com/dev/concepts/resource_types/synthetic_timeseries>`_.
+
         Args:
             expressions (str | sympy.Basic | Sequence[str] | Sequence[sympy.Basic]): Functions to be calculated. Supports both strings and sympy expressions. Strings can have either the API `ts{}` syntax, or contain variable names to be replaced using the `variables` parameter.
-            start (int | str | datetime): Inclusive start.
-            end (int | str | datetime): Exclusive end.
+            start (int | str | datetime.datetime): Inclusive start.
+            end (int | str | datetime.datetime): Exclusive end.
             limit (int | None): Number of datapoints per expression to retrieve.
             variables (Mapping[str | sympy.Symbol, str | NodeId | TimeSeries | TimeSeriesWrite] | None): An optional map of symbol replacements.
             aggregate (str | None): use this aggregate when replacing entries from `variables`, does not affect time series given in the `ts{}` syntax.
             granularity (str | None): use this granularity with the aggregate.
             target_unit (str | None): use this target_unit when replacing entries from `variables`, does not affect time series given in the `ts{}` syntax.
             target_unit_system (str | None): Same as target_unit, but with unit system (e.g. SI). Only one of target_unit and target_unit_system can be specified.
+            timezone (str | datetime.timezone | ZoneInfo | None): The timezone to use when aggregating datapoints. For aggregates of granularity 'hour' and longer,
+                which time zone should we align to. Align to the start of the hour, start of the day or start of the month. For time zones of type Region/Location,
+                the aggregate duration can vary, typically due to daylight saving time. For time zones of type UTC+/-HH:MM, use increments of 15 minutes. Default: "UTC" (None)
 
         Returns:
             Datapoints | DatapointsList: A DatapointsList object containing the calculated data.
@@ -127,7 +137,9 @@ def query(
                 ...     variables={x: "foo", y: "bar"},
                 ...     aggregate="interpolation",
                 ...     granularity="15m",
-                ...     target_unit="temperature:deg_c")
+                ...     target_unit="temperature:deg_c",
+                ...     timezone="Europe/Oslo",  # can also use this format: 'UTC+05:30'
+                ... )
         """
         return run_sync(
             self.__async_client.time_series.data.synthetic.query(
@@ -140,5 +152,6 @@ def query(
                 granularity=granularity,
                 target_unit=target_unit,
                 target_unit_system=target_unit_system,
+                timezone=timezone,
             )
         )

docs/source/_static/css/custom.css

@@ -0,0 +1,21 @@
+/* Source: https://github.com/readthedocs/sphinx_rtd_theme/issues/1529#issuecomment-1918561608*/
+
+/* Take out pointless vertical whitespace in the signatures. */
+.rst-content dl .sig dl,
+.rst-content dl .sig dd {
+  margin-bottom: 0;
+}
+
+/* Make signature boxes full-width, with view-source and header links right-aligned. */
+.rst-content dl .sig {
+  width: -webkit-fill-available;
+}
+.rst-content .viewcode-link {
+  display: inline-flex;
+  float: inline-end;
+  margin-right: 1.5em;
+}
+.rst-content .headerlink {
+  position: absolute;
+  right: 0.5em;
+}

docs/source/conf.py

@@ -23,7 +23,7 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+needs_sphinx = "7.2"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -93,7 +93,8 @@
 # Add any paths that contain custom _static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin _static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path = ["_static"]
+html_css_files = ["css/custom.css"]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -159,3 +160,22 @@
         "Miscellaneous",
     )
 ]
+
+python_maximum_signature_line_length = 80
+
+# Patch Sphinx to hide @overload signatures in docs
+# Sphinx's autodoc uses ModuleAnalyzer.overloads via the parser
+# We patch the analyze method to clear overloads after parsing
+# To see why, check out https://github.com/cognitedata/cognite-sdk-python/pull/2460
+from sphinx.pycode import ModuleAnalyzer  # noqa: E402
+
+analyze_fn = ModuleAnalyzer.analyze
+
+
+def analyze_but_skip_overloads(self):
+    result = analyze_fn(self)
+    self.overloads = {}  # Clear overloads after analysis
+    return result
+
+
+ModuleAnalyzer.analyze = analyze_but_skip_overloads

docs/source/data_modeling.rst

@@ -380,3 +380,9 @@ Extractor Extensions
 .. automodule:: cognite.client.data_classes.data_modeling.extractor_extensions.v1
     :members:
     :show-inheritance:
+
+Debugging Data Classes
+----------------------
+.. automodule:: cognite.client.data_classes.data_modeling.debug
+    :members:
+    :show-inheritance: