feat: Added read_time as a parameter to various calls (synchronous/base classes) by gkevinzheng · Pull Request #1013 · googleapis/python-firestore

gkevinzheng · 2025-01-30T19:08:39Z

This PR adds read_time to API calls that map to various Firestore gRPC calls whose request objects contain read_time as a field.

Calls with read_time added:

Client Library Call	gRPC Request in Call
`AggregationQuery.get/stream`	RunAggregationQueryRequest
`Client.get_all`	BatchGetDocumentsRequest
`Client.collections`	ListCollectionIdsRequest
`Collection.list_documents`	ListDocumentsRequest
`Collection.get/stream`	RunQueryRequest
`DocumentReference.get`	BatchGetDocumentsRequest
`DocumentReference.collections`	ListCollectionIdsRequest
`Query.get/stream`	RunQueryRequest
`Query.list_partitions`	PartitionQueryRequest
`Transaction.get_all`	BatchGetDocumentsRequest
`Transaction.get`	BatchGetDocumentsRequest/ RunQueryRequest

Partially fixes#775 for synchronous/base classes, async classes will be in a separate PR.

classes)

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

between sync/async

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

daniel-sanche · 2025-02-03T23:21:46Z

 """
 from __future__ import annotations

+from datetime import datetime


nit: just importing datetime as a module is probably better? This import overrides the "datetime" module name with the class name, which would get a bit weird if we have to use other datetime imports in the future. And it makes some of the type annotations a bit ambiguous
But let me know what you think

daniel-sanche · 2025-02-03T23:28:20Z

+ read_time (Optional[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.


A couple questions:
how are timezones handled? Do you expect "aware" or "naive" datetimes?
I just did a quick search, but it seems like datetime.datetime also has microsecond precision. Do we need to mention the precision here?

daniel-sanche · 2025-02-03T23:32:37Z

- field_paths: Iterable[str] | None = None,
- transaction: Transaction | None = None,
+ field_paths: Iterable[str] = None,
+ transaction: Transaction = None,


why remove None from these? Doesn't that cause a mypy error?

Whoops, my bad. This was most likely from merging a really old branch. I'll revert it.

daniel-sanche · 2025-02-03T23:32:56Z

+ transaction: Transaction = None,
 retry: retries.Retry | object | None = gapic_v1.method.DEFAULT,
- timeout: float | None = None,
+ timeout: float = None,


same comment: isn't this a type violation?

daniel-sanche · 2025-02-03T23:34:59Z

+ 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.


I'm confused by this comment. Why "most accurate results". Wouldn't the wrong timezone give wrong results? How are timezones meant to be used?
Shouldn't this docstring be consistent with others? I don't see UTC note this in the previous files

daniel-sanche · 2025-02-03T23:39:01Z

+ # make sure we didn't skip assertions in inner function
+ assert inner_fn_ran is True
+
+


it would be good to test a read_time that is far in the past, or in the future, to make sure the exception is raised as you expect it to be

daniel-sanche · 2025-02-03T23:41:44Z

-def _collections_helper(page_size=None, retry=None, timeout=None, database=None):
+@pytest.mark.parametrize("database", [None, "somedb"])
+def test_documentreference_get_with_read_time(database):
+ _get_helper(read_time=DatetimeWithNanoseconds.now(), database=database)


Why use from DatetimeWithNanoseconds here instead of the regular datetime?

The _get_helper creates a mock response which requires a Timestamp object for the read time, so I used DatetimeWithNanoseconds to get access to read_time.timestamp_pb() to get that field. I guess I could just use a regular datetime and have it be mocked accordingly.

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

… minutes (#975) * chore: Update gapic-generator-python to v1.19.1 PiperOrigin-RevId: 684571179 Source-Link: googleapis/googleapis@fbdc238 Source-Link: googleapis/googleapis-gen@3a2cdcf Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiM2EyY2RjZmI4MGMyZDBmNWVjMGNjNjYzYzJiYWIwYTk0ODYyMjlkMCJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * chore: Configure Ruby clients for google-ads-ad_manager PiperOrigin-RevId: 689139590 Source-Link: googleapis/googleapis@296f2ac Source-Link: googleapis/googleapis-gen@2692736 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMjY5MjczNjJlMGFhMTI5MzI1OGZjMjNmZTNjZTgzYzVjMjFkNWZiYiJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * chore: remove body selector from http rule PiperOrigin-RevId: 693215877 Source-Link: googleapis/googleapis@bb6b53e Source-Link: googleapis/googleapis-gen@db8b5a9 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiZGI4YjVhOTM0ODRhZDQ0MDU1YjJiYWNjNGM3Y2Y4N2U5NzBmZTBlZCJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * feat: Add support for opt-in debug logging fix: Fix typing issue with gRPC metadata when key ends in -bin chore: Update gapic-generator-python to v1.21.0 PiperOrigin-RevId: 705285820 Source-Link: googleapis/googleapis@f9b8b91 Source-Link: googleapis/googleapis-gen@ca1e0a1 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiY2ExZTBhMWU0NzJkNmU2ZjVkZTg4M2E1Y2I1NDcyNGYxMTJjZTM0OCJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * fix: bump default deadline on CreateDatabase and RestoreDatabase to 2 minutes feat: add filter argument to FirestoreAdmin.ListBackupsRequest PiperOrigin-RevId: 716763143 Source-Link: googleapis/googleapis@3776db1 Source-Link: googleapis/googleapis-gen@10db5ac Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMTBkYjVhYzQ3NmE5NGFhNGM5ZTBhMjQ5NDZkOWZhMWI3ZWE0NTZmNiJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Daniel Sanche <sanche@google.com>

* fix: fix thread cleanup when destroying Watch instance * added test for on_snapshot while closing

Source-Link: googleapis/synthtool@93e1685 Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-python:latest@sha256:631b4a35a4f9dd5e97740a97c4c117646eb85b35e103844dc49d152bd18694cd Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Daniel Sanche <sanche@google.com>

) Source-Link: googleapis/synthtool@aa69fb7 Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-python:latest@sha256:f016446d6e520e5fb552c45b110cba3f217bffdd3d06bdddd076e9e6d13266cf Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Daniel Sanche <sanche@google.com>

* chore: add logging section to readme Source-Link: googleapis/synthtool@d1011bc Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-python:latest@sha256:fdc038572b896f739f95cc90e62f16c06e4f2ef0ef3bea343a358331862ad0f0 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Daniel Sanche <sanche@google.com>

* feat: Add REST Interceptors which support reading metadata feat: Add support for reading selective GAPIC generation methods from service YAML chore: Update gapic-generator-python to v1.22.0 PiperOrigin-RevId: 724026024 Source-Link: googleapis/googleapis@ad99638 Source-Link: googleapis/googleapis-gen@e291c4d Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiZTI5MWM0ZGQxZDY3MGVkYTE5OTk4ZGU3NmY5NjdlMTYwM2E0ODk5MyJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * chore: expose the Firestore.executePipeline API to the preview branch docs: minor documentation updates to `StructuredQuery` docs: minor documentation changes for `distance_threshold` PiperOrigin-RevId: 731306872 Source-Link: googleapis/googleapis@b6d5ae8 Source-Link: googleapis/googleapis-gen@4cb9048 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNGNiOTA0ODg3MWJmNTkwNmIzOTBlOGVhM2Q3YjlmMWVmNmFjMTlkNiJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Daniel Sanche <sanche@google.com>

Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com> Co-authored-by: Daniel Sanche <sanche@google.com>

* chore: Update gapic-generator-python to v1.23.2 PiperOrigin-RevId: 732281673 Source-Link: googleapis/googleapis@2f37e0a Source-Link: googleapis/googleapis-gen@016b753 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMDE2Yjc1MzhiYTVhNzk4ZjJhZTQyM2Q0Y2NkN2Y4MmIwNmNkZjZkMiJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

* chore: remove unused files * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

* chore: Update gapic-generator-python to 1.23.6 PiperOrigin-RevId: 738170370 Source-Link: googleapis/googleapis@3f1e17a Source-Link: googleapis/googleapis-gen@9afd8c3 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiOWFmZDhjMzNkNGNhZTYxMGI3NWZhNDk5OTI2NGVhOGM4YzY2YjlkMiJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

) Co-authored-by: Daniel Sanche <sanche@google.com>

* chore(docs): add BulkWriter to docs * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * removed unintentional files --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Source-Link: googleapis/synthtool@8767740 Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-python:latest@sha256:023a21377a2a00008057f99f0118edadc30a19d1636a3fee47189ebec2f3921c Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

* chore(python): remove .gitignore from templates Source-Link: googleapis/synthtool@419d94c Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-python:latest@sha256:a7aef70df5f13313ddc027409fc8f3151422ec2a57ac8730fce8fa75c060d5bb * Remove replacement in owlbot.py --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Anthonios Partheniou <partheniou@google.com>

* chore(python): remove CONTRIBUTING.rst from templates Source-Link: googleapis/synthtool@c96fb11 Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-python:latest@sha256:710b70faff81151657d89db6e028c23a1051787598c8276bdd8eef25c92da8ab * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * Remove replacement in owlbot.py --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Anthonios Partheniou <partheniou@google.com>

* chore(python): remove noxfile.py from templates Source-Link: googleapis/synthtool@7765802 Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-python:latest@sha256:25de45b58e52021d3a24a6273964371a97a4efeefe6ad3845a64e697c63b6447 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * remove replacements in owlbot.py --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Anthonios Partheniou <partheniou@google.com>

Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>

classes)

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

gkevinzheng · 2025-05-13T18:48:01Z

Closing this PR; #1050 should be the same PR without all the merge conflicts and rebase issues.

gkevinzheng added 2 commits January 30, 2025 17:37

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

Added system test for DocumentReference.collections
0bc5302

gkevinzheng requested review from a teamJanuary 30, 2025 19:08

blunderbuss-gcfBot assigned danieljbruce Jan 30, 2025

product-auto-labelBot added size: l Pull request size is large. api: firestore Issues related to the googleapis/python-firestore API. labels Jan 30, 2025

🦉 Updates from OwlBot post-processor
e9eefd6
See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

gkevinzheng assigned daniel-sanche and unassigned danieljbruce Jan 30, 2025

gkevinzhengand others added 8 commits January 30, 2025 19:49

linting
a1d8030

Conditionally adding read_time to kwargs for cleaner test separation
d551aa2
between sync/async

🦉 Updates from OwlBot post-processor
3151b8b
See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Conditionally adding read_time to kwargs in base_aggregation.py
4e6f95e

More conditionally adding read_time to kwargs
2ed7eb5

🦉 Updates from OwlBot post-processor
402fe49
See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Added tests for collections.get/stream
39ae878

linting
d85f2f0

daniel-sanche reviewed Feb 3, 2025
View reviewed changes

gkevinzhengand others added 10 commits February 14, 2025 18:08

Addressed review feedback
a8ced8f

🦉 Updates from OwlBot post-processor
f19995e
See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

linting
7f99200

chore: update protoplus for python 3.13 (#1009)
6f5b1c4

fix: client-side path validation for batch.update (#1021)
fbd6ab2

fix: Watch thread deadlock on exit (#1014)
33c134b
* fix: fix thread cleanup when destroying Watch instance * added test for on_snapshot while closing

gcf-owl-botBotand others added 15 commits April 30, 2025 13:55

chore(main): release 2.20.1 (#1011)
1fcb218
Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com> Co-authored-by: Daniel Sanche <sanche@google.com>

chore: remove unused files (#1027)
f71aba8
* chore: remove unused files * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

fix: allow Protobuf 6.x (#1028)
17668b7

fix: remove setup.cfg configuration for creating universal wheels (#1030
4061cf7
) Co-authored-by: Daniel Sanche <sanche@google.com>

chore(main): release 2.20.2 (#1031)
d51ac35
Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>

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

Fixed unit tests
6b1bb42

product-auto-labelBot added size: xl Pull request size is extra large. and removed size: l Pull request size is large. labels Apr 30, 2025

🦉 Updates from OwlBot post-processor
e33292c
See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

gkevinzheng mentioned this pull request May 13, 2025
feat: Added read_time as a parameter to various calls (synchronous/base classes) #1050
Merged

gkevinzheng closed this May 13, 2025

Navigation Menu

Uh oh!

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

feat: Added read_time as a parameter to various calls (synchronous/base classes)#1013
gkevinzheng wants to merge 37 commits into
mainfrom
read-time

gkevinzheng commented Jan 30, 2025

Uh oh!

daniel-sancheFeb 3, 2025•
edited
Loading

Uh oh!

daniel-sancheFeb 3, 2025

Uh oh!

daniel-sancheFeb 3, 2025

Uh oh!

gkevinzhengFeb 10, 2025

Uh oh!

daniel-sancheFeb 3, 2025

Uh oh!

daniel-sancheFeb 3, 2025

Uh oh!

daniel-sancheFeb 3, 2025

Uh oh!

daniel-sancheFeb 3, 2025

Uh oh!

gkevinzhengFeb 10, 2025

Uh oh!

gkevinzheng commented May 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		# make sure we didn't skip assertions in inner function
		assert inner_fn_ran is True

Uh oh!

Conversation

gkevinzheng commented Jan 30, 2025

Uh oh!

daniel-sancheFeb 3, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gkevinzheng commented May 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

daniel-sancheFeb 3, 2025•
edited
Loading