added read_time option

Author: daniel-sanche

google/cloud/firestore_v1/async_pipeline.py

@@ -18,6 +18,7 @@
 from google.cloud.firestore_v1.base_pipeline import _BasePipeline
 
 if TYPE_CHECKING:  # pragma: NO COVER
+    import datetime
     from google.cloud.firestore_v1.async_client import AsyncClient
     from google.cloud.firestore_v1.pipeline_result import PipelineResult
     from google.cloud.firestore_v1.async_transaction import AsyncTransaction
@@ -59,6 +60,7 @@ def __init__(self, client: AsyncClient, *stages: stages.Stage):
     async def execute(
         self,
         transaction: "AsyncTransaction" | None = None,
+        read_time: datetime.datetime | None = None,
     ) -> list[PipelineResult]:
         """
         Executes this pipeline and returns results as a list
@@ -70,12 +72,17 @@ async def execute(
                 If a ``transaction`` is used and it already has write operations
                 added, this method cannot be used (i.e. read-after-write is not
                 allowed).
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a microsecond precision 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. For the most accurate results, use UTC timezone.
         """
-        return [result async for result in self.stream(transaction=transaction)]
+        return [result async for result in self.stream(transaction=transaction, read_time=read_time)]
 
     async def stream(
         self,
         transaction: "AsyncTransaction" | None = None,
+        read_time: datetime.datetime | None = None,
     ) -> AsyncIterable[PipelineResult]:
         """
         Process this pipeline as a stream, providing results through an Iterable
@@ -87,8 +94,12 @@ async def stream(
                 If a ``transaction`` is used and it already has write operations
                 added, this method cannot be used (i.e. read-after-write is not
                 allowed).
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a microsecond precision 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. For the most accurate results, use UTC timezone.
         """
-        request = self._prep_execute_request(transaction)
+        request = self._prep_execute_request(transaction, read_time)
         async for response in await self._client._firestore_api.execute_pipeline(
             request
         ):

google/cloud/firestore_v1/base_pipeline.py

@@ -33,6 +33,7 @@
 from google.cloud.firestore_v1 import _helpers
 
 if TYPE_CHECKING:  # pragma: NO COVER
+    import datetime
     from google.cloud.firestore_v1.client import Client
     from google.cloud.firestore_v1.async_client import AsyncClient
     from google.cloud.firestore_v1.types.firestore import ExecutePipelineResponse
@@ -99,7 +100,9 @@ def _append(self, new_stage):
         return self.__class__._create_with_stages(self._client, *self.stages, new_stage)
 
     def _prep_execute_request(
-        self, transaction: BaseTransaction | None
+        self,
+        transaction: BaseTransaction | None,
+        read_time: datetime.datetime | None,
     ) -> ExecutePipelineRequest:
         """
         shared logic for creating an ExecutePipelineRequest
@@ -116,6 +119,7 @@ def _prep_execute_request(
             database=database_name,
             transaction=transaction_id,
             structured_pipeline=self._to_pb(),
+            read_time=read_time,
         )
         return request
 

google/cloud/firestore_v1/pipeline.py

@@ -18,6 +18,7 @@
 from google.cloud.firestore_v1.base_pipeline import _BasePipeline
 
 if TYPE_CHECKING:  # pragma: NO COVER
+    import datetime
     from google.cloud.firestore_v1.client import Client
     from google.cloud.firestore_v1.pipeline_result import PipelineResult
     from google.cloud.firestore_v1.transaction import Transaction
@@ -56,6 +57,7 @@ def __init__(self, client: Client, *stages: stages.Stage):
     def execute(
         self,
         transaction: "Transaction" | None = None,
+        read_time: datetime.datetime | None = None,
     ) -> list[PipelineResult]:
         """
         Executes this pipeline and returns results as a list
@@ -67,12 +69,17 @@ def execute(
                 If a ``transaction`` is used and it already has write operations
                 added, this method cannot be used (i.e. read-after-write is not
                 allowed).
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a microsecond precision 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. For the most accurate results, use UTC timezone.
         """
-        return [result for result in self.stream(transaction=transaction)]
+        return [result for result in self.stream(transaction=transaction, read_time=read_time)]
 
     def stream(
         self,
         transaction: "Transaction" | None = None,
+        read_time: datetime.datetime | None = None,
     ) -> Iterable[PipelineResult]:
         """
         Process this pipeline as a stream, providing results through an Iterable
@@ -84,7 +91,11 @@ def stream(
                 If a ``transaction`` is used and it already has write operations
                 added, this method cannot be used (i.e. read-after-write is not
                 allowed).
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a microsecond precision 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. For the most accurate results, use UTC timezone.
         """
-        request = self._prep_execute_request(transaction)
+        request = self._prep_execute_request(transaction, read_time)
         for response in self._client._firestore_api.execute_pipeline(request):
             yield from self._execute_response_helper(response)