Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings
This repository was archived by the owner on Mar 2, 2026. It is now read-only.

Commit d8e3af1

Browse filesBrowse files
gkevinzhenggcf-owl-bot[bot]daniel-sanche
authored
feat: Added read_time as a parameter to various calls (synchronous/base classes) (#1050)
* feat: Added read_time as a parameter to various calls (synchronous/base classes) * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * fixed tests + added system tests * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * Removed specific system test assertions * added system test with python datetimes * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * revised type hints * linting * feat: Added read_time as a parameter to various calls (async classes) (#1059) * feat: Added read_time as a parameter to various calls (async classes) * used TYPE_CHECKING; fixed unit tests * linting + fixing cover * final linting * TYPE_CHECKING * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * Update client.py fix no cover comment * fixed async system test --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Daniel Sanche <sanche@google.com>
1 parent 437e233 commit d8e3af1
Copy full SHA for d8e3af1

32 files changed

+1,588-168Lines changed: 1588 additions & 168 deletions
Expand file treeCollapse file tree
Open diff view settings
Collapse file

‎google/cloud/firestore_v1/aggregation.py‎

Copy file name to clipboardExpand all lines: google/cloud/firestore_v1/aggregation.py
+26-1Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@
3939
from google.cloud.firestore_v1.query_profile import ExplainMetrics
4040
from google.cloud.firestore_v1.query_profile import ExplainOptions
4141

42+
import datetime
43+
4244

4345
class AggregationQuery(BaseAggregationQuery):
4446
"""Represents an aggregation query to the Firestore API."""
@@ -56,6 +58,7 @@ def get(
5658
timeout: float | None = None,
5759
*,
5860
explain_options: Optional[ExplainOptions] = None,
61+
read_time: Optional[datetime.datetime] = None,
5962
) -> QueryResultsList[AggregationResult]:
6063
"""Runs the aggregation query.
6164
@@ -78,6 +81,10 @@ def get(
7881
(Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
7982
Options to enable query profiling for this query. When set,
8083
explain_metrics will be available on the returned generator.
84+
read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
85+
time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
86+
is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
87+
timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
8188
8289
Returns:
8390
QueryResultsList[AggregationResult]: The aggregation query results.
@@ -90,6 +97,7 @@ def get(
9097
retry=retry,
9198
timeout=timeout,
9299
explain_options=explain_options,
100+
read_time=read_time,
93101
)
94102
result_list = list(result)
95103

@@ -100,13 +108,16 @@ def get(
100108

101109
return QueryResultsList(result_list, explain_options, explain_metrics)
102110

103-
def _get_stream_iterator(self, transaction, retry, timeout, explain_options=None):
111+
def _get_stream_iterator(
112+
self, transaction, retry, timeout, explain_options=None, read_time=None
113+
):
104114
"""Helper method for :meth:`stream`."""
105115
request, kwargs = self._prep_stream(
106116
transaction,
107117
retry,
108118
timeout,
109119
explain_options,
120+
read_time,
110121
)
111122

112123
return self._client._firestore_api.run_aggregation_query(
@@ -132,6 +143,7 @@ def _make_stream(
132143
retry: Union[retries.Retry, None, object] = gapic_v1.method.DEFAULT,
133144
timeout: Optional[float] = None,
134145
explain_options: Optional[ExplainOptions] = None,
146+
read_time: Optional[datetime.datetime] = None,
135147
) -> Generator[List[AggregationResult], Any, Optional[ExplainMetrics]]:
136148
"""Internal method for stream(). Runs the aggregation query.
137149
@@ -155,6 +167,10 @@ def _make_stream(
155167
(Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
156168
Options to enable query profiling for this query. When set,
157169
explain_metrics will be available on the returned generator.
170+
read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
171+
time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
172+
is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
173+
timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
158174
159175
Yields:
160176
List[AggregationResult]:
@@ -172,6 +188,7 @@ def _make_stream(
172188
retry,
173189
timeout,
174190
explain_options,
191+
read_time,
175192
)
176193
while True:
177194
try:
@@ -182,6 +199,8 @@ def _make_stream(
182199
transaction,
183200
retry,
184201
timeout,
202+
explain_options,
203+
read_time,
185204
)
186205
continue
187206
else:
@@ -206,6 +225,7 @@ def stream(
206225
timeout: Optional[float] = None,
207226
*,
208227
explain_options: Optional[ExplainOptions] = None,
228+
read_time: Optional[datetime.datetime] = None,
209229
) -> StreamGenerator[List[AggregationResult]]:
210230
"""Runs the aggregation query.
211231
@@ -229,6 +249,10 @@ def stream(
229249
(Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
230250
Options to enable query profiling for this query. When set,
231251
explain_metrics will be available on the returned generator.
252+
read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
253+
time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
254+
is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
255+
timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
232256
233257
Returns:
234258
`StreamGenerator[List[AggregationResult]]`:
@@ -239,5 +263,6 @@ def stream(
239263
retry=retry,
240264
timeout=timeout,
241265
explain_options=explain_options,
266+
read_time=read_time,
242267
)
243268
return StreamGenerator(inner_generator, explain_options)
Collapse file

‎google/cloud/firestore_v1/async_aggregation.py‎

Copy file name to clipboardExpand all lines: google/cloud/firestore_v1/async_aggregation.py
+19Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@
3737
from google.cloud.firestore_v1.base_aggregation import AggregationResult
3838
from google.cloud.firestore_v1.query_profile import ExplainMetrics, ExplainOptions
3939
import google.cloud.firestore_v1.types.query_profile as query_profile_pb
40+
import datetime
4041

4142

4243
class AsyncAggregationQuery(BaseAggregationQuery):
@@ -55,6 +56,7 @@ async def get(
5556
timeout: float | None = None,
5657
*,
5758
explain_options: Optional[ExplainOptions] = None,
59+
read_time: Optional[datetime.datetime] = None,
5860
) -> QueryResultsList[List[AggregationResult]]:
5961
"""Runs the aggregation query.
6062
@@ -75,6 +77,10 @@ async def get(
7577
(Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
7678
Options to enable query profiling for this query. When set,
7779
explain_metrics will be available on the returned generator.
80+
read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
81+
time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
82+
is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
83+
timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
7884
7985
Returns:
8086
QueryResultsList[List[AggregationResult]]: The aggregation query results.
@@ -87,6 +93,7 @@ async def get(
8793
retry=retry,
8894
timeout=timeout,
8995
explain_options=explain_options,
96+
read_time=read_time,
9097
)
9198
try:
9299
result = [aggregation async for aggregation in stream_result]
@@ -106,6 +113,7 @@ async def _make_stream(
106113
retry: retries.AsyncRetry | object | None = gapic_v1.method.DEFAULT,
107114
timeout: Optional[float] = None,
108115
explain_options: Optional[ExplainOptions] = None,
116+
read_time: Optional[datetime.datetime] = None,
109117
) -> AsyncGenerator[List[AggregationResult] | query_profile_pb.ExplainMetrics, Any]:
110118
"""Internal method for stream(). Runs the aggregation query.
111119
@@ -130,6 +138,10 @@ async def _make_stream(
130138
(Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
131139
Options to enable query profiling for this query. When set,
132140
explain_metrics will be available on the returned generator.
141+
read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
142+
time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
143+
is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
144+
timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
133145
134146
Yields:
135147
List[AggregationResult] | query_profile_pb.ExplainMetrics:
@@ -143,6 +155,7 @@ async def _make_stream(
143155
retry,
144156
timeout,
145157
explain_options,
158+
read_time,
146159
)
147160

148161
response_iterator = await self._client._firestore_api.run_aggregation_query(
@@ -167,6 +180,7 @@ def stream(
167180
timeout: Optional[float] = None,
168181
*,
169182
explain_options: Optional[ExplainOptions] = None,
183+
read_time: Optional[datetime.datetime] = None,
170184
) -> AsyncStreamGenerator[List[AggregationResult]]:
171185
"""Runs the aggregation query.
172186
@@ -190,6 +204,10 @@ def stream(
190204
(Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
191205
Options to enable query profiling for this query. When set,
192206
explain_metrics will be available on the returned generator.
207+
read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
208+
time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
209+
is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
210+
timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
193211
194212
Returns:
195213
`AsyncStreamGenerator[List[AggregationResult]]`:
@@ -201,5 +219,6 @@ def stream(
201219
retry=retry,
202220
timeout=timeout,
203221
explain_options=explain_options,
222+
read_time=read_time,
204223
)
205224
return AsyncStreamGenerator(inner_generator, explain_options)
Collapse file

‎google/cloud/firestore_v1/async_client.py‎

Copy file name to clipboardExpand all lines: google/cloud/firestore_v1/async_client.py
+18-4Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,10 @@
4848
grpc_asyncio as firestore_grpc_transport,
4949
)
5050

51-
if TYPE_CHECKING:
52-
from google.cloud.firestore_v1.bulk_writer import BulkWriter # pragma: NO COVER
51+
if TYPE_CHECKING: # pragma: NO COVER
52+
import datetime
53+
54+
from google.cloud.firestore_v1.bulk_writer import BulkWriter
5355

5456

5557
class AsyncClient(BaseClient):
@@ -227,6 +229,8 @@ async def get_all(
227229
transaction: AsyncTransaction | None = None,
228230
retry: retries.AsyncRetry | object | None = gapic_v1.method.DEFAULT,
229231
timeout: float | None = None,
232+
*,
233+
read_time: datetime.datetime | None = None,
230234
) -> AsyncGenerator[DocumentSnapshot, Any]:
231235
"""Retrieve a batch of documents.
232236
@@ -261,13 +265,17 @@ async def get_all(
261265
should be retried. Defaults to a system-specified policy.
262266
timeout (float): The timeout for this request. Defaults to a
263267
system-specified value.
268+
read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
269+
time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
270+
is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
271+
timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
264272
265273
Yields:
266274
.DocumentSnapshot: The next document snapshot that fulfills the
267275
query, or :data:`None` if the document does not exist.
268276
"""
269277
request, reference_map, kwargs = self._prep_get_all(
270-
references, field_paths, transaction, retry, timeout
278+
references, field_paths, transaction, retry, timeout, read_time
271279
)
272280

273281
response_iterator = await self._firestore_api.batch_get_documents(
@@ -283,6 +291,8 @@ async def collections(
283291
self,
284292
retry: retries.AsyncRetry | object | None = gapic_v1.method.DEFAULT,
285293
timeout: float | None = None,
294+
*,
295+
read_time: datetime.datetime | None = None,
286296
) -> AsyncGenerator[AsyncCollectionReference, Any]:
287297
"""List top-level collections of the client's database.
288298
@@ -291,12 +301,16 @@ async def collections(
291301
should be retried. Defaults to a system-specified policy.
292302
timeout (float): The timeout for this request. Defaults to a
293303
system-specified value.
304+
read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
305+
time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
306+
is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
307+
timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
294308
295309
Returns:
296310
Sequence[:class:`~google.cloud.firestore_v1.async_collection.AsyncCollectionReference`]:
297311
iterator of subcollections of the current document.
298312
"""
299-
request, kwargs = self._prep_collections(retry, timeout)
313+
request, kwargs = self._prep_collections(retry, timeout, read_time)
300314
iterator = await self._firestore_api.list_collection_ids(
301315
request=request,
302316
metadata=self._rpc_metadata,
Collapse file

‎google/cloud/firestore_v1/async_collection.py‎

Copy file name to clipboardExpand all lines: google/cloud/firestore_v1/async_collection.py
+25-1Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@
3434
from google.cloud.firestore_v1.document import DocumentReference
3535

3636
if TYPE_CHECKING: # pragma: NO COVER
37+
import datetime
38+
3739
from google.cloud.firestore_v1.async_stream_generator import AsyncStreamGenerator
3840
from google.cloud.firestore_v1.base_document import DocumentSnapshot
3941
from google.cloud.firestore_v1.query_profile import ExplainOptions
@@ -162,6 +164,8 @@ async def list_documents(
162164
page_size: int | None = None,
163165
retry: retries.AsyncRetry | object | None = gapic_v1.method.DEFAULT,
164166
timeout: float | None = None,
167+
*,
168+
read_time: datetime.datetime | None = None,
165169
) -> AsyncGenerator[DocumentReference, None]:
166170
"""List all subdocuments of the current collection.
167171
@@ -173,14 +177,20 @@ async def list_documents(
173177
should be retried. Defaults to a system-specified policy.
174178
timeout (float): The timeout for this request. Defaults to a
175179
system-specified value.
180+
read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
181+
time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
182+
is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
183+
timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
176184
177185
Returns:
178186
Sequence[:class:`~google.cloud.firestore_v1.collection.DocumentReference`]:
179187
iterator of subdocuments of the current collection. If the
180188
collection does not exist at the time of `snapshot`, the
181189
iterator will be empty
182190
"""
183-
request, kwargs = self._prep_list_documents(page_size, retry, timeout)
191+
request, kwargs = self._prep_list_documents(
192+
page_size, retry, timeout, read_time
193+
)
184194

185195
iterator = await self._client._firestore_api.list_documents(
186196
request=request,
@@ -197,6 +207,7 @@ async def get(
197207
timeout: Optional[float] = None,
198208
*,
199209
explain_options: Optional[ExplainOptions] = None,
210+
read_time: Optional[datetime.datetime] = None,
200211
) -> QueryResultsList[DocumentSnapshot]:
201212
"""Read the documents in this collection.
202213
@@ -216,6 +227,10 @@ async def get(
216227
(Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
217228
Options to enable query profiling for this query. When set,
218229
explain_metrics will be available on the returned generator.
230+
read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
231+
time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
232+
is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
233+
timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
219234
220235
If a ``transaction`` is used and it already has write operations added,
221236
this method cannot be used (i.e. read-after-write is not allowed).
@@ -227,6 +242,8 @@ async def get(
227242
query, kwargs = self._prep_get_or_stream(retry, timeout)
228243
if explain_options is not None:
229244
kwargs["explain_options"] = explain_options
245+
if read_time is not None:
246+
kwargs["read_time"] = read_time
230247

231248
return await query.get(transaction=transaction, **kwargs)
232249

@@ -237,6 +254,7 @@ def stream(
237254
timeout: Optional[float] = None,
238255
*,
239256
explain_options: Optional[ExplainOptions] = None,
257+
read_time: Optional[datetime.datetime] = None,
240258
) -> AsyncStreamGenerator[DocumentSnapshot]:
241259
"""Read the documents in this collection.
242260
@@ -268,6 +286,10 @@ def stream(
268286
(Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
269287
Options to enable query profiling for this query. When set,
270288
explain_metrics will be available on the returned generator.
289+
read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
290+
time. This must be a timestamp within the past one hour, or if Point-in-Time Recovery
291+
is enabled, can additionally be a whole minute timestamp within the past 7 days. If no
292+
timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
271293
272294
Returns:
273295
`AsyncStreamGenerator[DocumentSnapshot]`: A generator of the query
@@ -276,5 +298,7 @@ def stream(
276298
query, kwargs = self._prep_get_or_stream(retry, timeout)
277299
if explain_options:
278300
kwargs["explain_options"] = explain_options
301+
if read_time is not None:
302+
kwargs["read_time"] = read_time
279303

280304
return query.stream(transaction=transaction, **kwargs)

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.