feat: Added read_time as a parameter to various calls (synchronous/base classes)

google/cloud/firestore_v1/aggregation.py

@@ -20,6 +20,8 @@
 """
 from __future__ import annotations
 
+import datetime
+
 from typing import TYPE_CHECKING, Any, Generator, List, Optional, Union
 
 from google.api_core import exceptions, gapic_v1
@@ -56,6 +58,7 @@ def get(
         timeout: float | None = None,
         *,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> QueryResultsList[AggregationResult]:
         """Runs the aggregation query.
 
@@ -78,6 +81,10 @@ def get(
                 (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned generator.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
+                is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Returns:
             QueryResultsList[AggregationResult]: The aggregation query results.
@@ -90,6 +97,7 @@ def get(
             retry=retry,
             timeout=timeout,
             explain_options=explain_options,
+            read_time=read_time,
         )
         result_list = list(result)
 
@@ -100,13 +108,16 @@ def get(
 
         return QueryResultsList(result_list, explain_options, explain_metrics)
 
-    def _get_stream_iterator(self, transaction, retry, timeout, explain_options=None):
+    def _get_stream_iterator(
+        self, transaction, retry, timeout, explain_options=None, read_time=None
+    ):
         """Helper method for :meth:`stream`."""
         request, kwargs = self._prep_stream(
             transaction,
             retry,
             timeout,
             explain_options,
+            read_time,
         )
 
         return self._client._firestore_api.run_aggregation_query(
@@ -132,6 +143,7 @@ def _make_stream(
         retry: Union[retries.Retry, None, object] = gapic_v1.method.DEFAULT,
         timeout: Optional[float] = None,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> Generator[List[AggregationResult], Any, Optional[ExplainMetrics]]:
         """Internal method for stream(). Runs the aggregation query.
 
@@ -155,6 +167,10 @@ def _make_stream(
                 (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned generator.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
+                is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Yields:
             List[AggregationResult]:
@@ -172,6 +188,7 @@ def _make_stream(
             retry,
             timeout,
             explain_options,
+            read_time,
         )
         while True:
             try:
@@ -182,6 +199,8 @@ def _make_stream(
                         transaction,
                         retry,
                         timeout,
+                        explain_options,
+                        read_time,
                     )
                     continue
                 else:
@@ -206,6 +225,7 @@ def stream(
         timeout: Optional[float] = None,
         *,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> StreamGenerator[List[AggregationResult]]:
         """Runs the aggregation query.
 
@@ -229,6 +249,10 @@ def stream(
                 (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned generator.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
+                is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Returns:
             `StreamGenerator[List[AggregationResult]]`:
@@ -239,5 +263,6 @@ def stream(
             retry=retry,
             timeout=timeout,
             explain_options=explain_options,
+            read_time=read_time,
         )
         return StreamGenerator(inner_generator, explain_options)

google/cloud/firestore_v1/base_aggregation.py

@@ -21,6 +21,8 @@
 from __future__ import annotations
 
 import abc
+import datetime
+
 from abc import ABC
 from typing import TYPE_CHECKING, Any, Coroutine, List, Optional, Tuple, Union
 
@@ -205,6 +207,7 @@ def _prep_stream(
         retry: Union[retries.Retry, retries.AsyncRetry, None, object] = None,
         timeout: float | None = None,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> Tuple[dict, dict]:
         parent_path, expected_prefix = self._collection_ref._parent_info()
         request = {
@@ -214,6 +217,8 @@ def _prep_stream(
         }
         if explain_options:
             request["explain_options"] = explain_options._to_dict()
+        if read_time is not None:
+            request["read_time"] = read_time
         kwargs = _helpers.make_retry_timeout_kwargs(retry, timeout)
 
         return request, kwargs
@@ -228,6 +233,7 @@ def get(
         timeout: float | None = None,
         *,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> (
         QueryResultsList[AggregationResult]
         | Coroutine[Any, Any, List[List[AggregationResult]]]
@@ -253,6 +259,10 @@ def get(
                 (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned generator.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
+                is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Returns:
             (QueryResultsList[List[AggregationResult]] | Coroutine[Any, Any, List[List[AggregationResult]]]):
@@ -270,6 +280,7 @@ def stream(
         timeout: Optional[float] = None,
         *,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> (
         StreamGenerator[List[AggregationResult]]
         | AsyncStreamGenerator[List[AggregationResult]]
@@ -291,6 +302,10 @@ def stream(
                 (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned generator.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
+                is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Returns:
             StreamGenerator[List[AggregationResult]] | AsyncStreamGenerator[List[AggregationResult]]:

google/cloud/firestore_v1/base_client.py

@@ -25,6 +25,7 @@
 """
 from __future__ import annotations
 
+import datetime
 import os
 from typing import (
     Any,
@@ -437,6 +438,7 @@ def _prep_get_all(
         transaction: BaseTransaction | None = None,
         retry: retries.Retry | retries.AsyncRetry | object | None = None,
         timeout: float | None = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> Tuple[dict, dict, dict]:
         """Shared setup for async/sync :meth:`get_all`."""
         document_paths, reference_map = _reference_info(references)
@@ -447,6 +449,8 @@ def _prep_get_all(
             "mask": mask,
             "transaction": _helpers.get_transaction_id(transaction),
         }
+        if read_time is not None:
+            request["read_time"] = read_time
         kwargs = _helpers.make_retry_timeout_kwargs(retry, timeout)
 
         return request, reference_map, kwargs
@@ -458,6 +462,8 @@ def get_all(
         transaction=None,
         retry: retries.Retry | retries.AsyncRetry | object | None = None,
         timeout: float | None = None,
+        *,
+        read_time: Optional[datetime.datetime] = None,
     ) -> Union[
         AsyncGenerator[DocumentSnapshot, Any], Generator[DocumentSnapshot, Any, Any]
     ]:
@@ -467,9 +473,14 @@ def _prep_collections(
         self,
         retry: retries.Retry | retries.AsyncRetry | object | None = None,
         timeout: float | None = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> Tuple[dict, dict]:
         """Shared setup for async/sync :meth:`collections`."""
-        request = {"parent": "{}/documents".format(self._database_string)}
+        request = {
+            "parent": "{}/documents".format(self._database_string),
+        }
+        if read_time is not None:
+            request["read_time"] = read_time
         kwargs = _helpers.make_retry_timeout_kwargs(retry, timeout)
 
         return request, kwargs
@@ -478,6 +489,8 @@ def collections(
         self,
         retry: retries.Retry | retries.AsyncRetry | object | None = None,
         timeout: float | None = None,
+        *,
+        read_time: Optional[datetime.datetime] = None,
     ):
         raise NotImplementedError
 

google/cloud/firestore_v1/base_collection.py

@@ -15,7 +15,9 @@
 """Classes for representing collections for the Google Cloud Firestore API."""
 from __future__ import annotations
 
+import datetime
 import random
+
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -202,6 +204,7 @@ def _prep_list_documents(
         page_size: Optional[int] = None,
         retry: retries.Retry | retries.AsyncRetry | object | None = None,
         timeout: Optional[float] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> Tuple[dict, dict]:
         """Shared setup for async / sync :method:`list_documents`"""
         parent, _ = self._parent_info()
@@ -215,6 +218,8 @@ def _prep_list_documents(
             # to include no fields
             "mask": {"field_paths": None},
         }
+        if read_time is not None:
+            request["read_time"] = read_time
         kwargs = _helpers.make_retry_timeout_kwargs(retry, timeout)
 
         return request, kwargs
@@ -224,6 +229,8 @@ def list_documents(
         page_size: Optional[int] = None,
         retry: retries.Retry | retries.AsyncRetry | object | None = None,
         timeout: Optional[float] = None,
+        *,
+        read_time: Optional[datetime.datetime] = None,
     ) -> Union[
         Generator[DocumentReference, Any, Any], AsyncGenerator[DocumentReference, Any]
     ]:
@@ -497,6 +504,7 @@ def get(
         timeout: Optional[float] = None,
         *,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> (
         QueryResultsList[DocumentSnapshot]
         | Coroutine[Any, Any, QueryResultsList[DocumentSnapshot]]
@@ -510,6 +518,7 @@ def stream(
         timeout: Optional[float] = None,
         *,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> StreamGenerator[DocumentSnapshot] | AsyncIterator[DocumentSnapshot]:
         raise NotImplementedError
 

google/cloud/firestore_v1/base_document.py

@@ -16,6 +16,8 @@
 from __future__ import annotations
 
 import copy
+import datetime
+
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -290,6 +292,7 @@ def _prep_batch_get(
         transaction=None,
         retry: retries.Retry | retries.AsyncRetry | None | object = None,
         timeout: float | None = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> Tuple[dict, dict]:
         """Shared setup for async/sync :meth:`get`."""
         if isinstance(field_paths, str):
@@ -306,6 +309,8 @@ def _prep_batch_get(
             "mask": mask,
             "transaction": _helpers.get_transaction_id(transaction),
         }
+        if read_time is not None:
+            request["read_time"] = read_time
         kwargs = _helpers.make_retry_timeout_kwargs(retry, timeout)
 
         return request, kwargs
@@ -316,6 +321,8 @@ def get(
         transaction=None,
         retry: retries.Retry | retries.AsyncRetry | None | object = None,
         timeout: float | None = None,
+        *,
+        read_time: Optional[datetime.datetime] = None,
     ) -> "DocumentSnapshot" | Awaitable["DocumentSnapshot"]:
         raise NotImplementedError
 
@@ -324,9 +331,15 @@ def _prep_collections(
         page_size: int | None = None,
         retry: retries.Retry | retries.AsyncRetry | None | object = None,
         timeout: float | None = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> Tuple[dict, dict]:
         """Shared setup for async/sync :meth:`collections`."""
-        request = {"parent": self._document_path, "page_size": page_size}
+        request = {
+            "parent": self._document_path,
+            "page_size": page_size,
+        }
+        if read_time is not None:
+            request["read_time"] = read_time
         kwargs = _helpers.make_retry_timeout_kwargs(retry, timeout)
 
         return request, kwargs
@@ -336,6 +349,8 @@ def collections(
         page_size: int | None = None,
         retry: retries.Retry | retries.AsyncRetry | None | object = None,
         timeout: float | None = None,
+        *,
+        read_time: Optional[datetime.datetime] = None,
     ):
         raise NotImplementedError