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

google/cloud/firestore_v1/aggregation.py

 """
 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

google/cloud/firestore_v1/aggregation.py

+            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

google/cloud/firestore_v1/client.py

-        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

google/cloud/firestore_v1/client.py

+        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

google/cloud/firestore_v1/client.py

+            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

tests/system/test_system.py

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

tests/unit/v1/test_document.py

-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 team as code owners January 30, 2025 19:08

gkevinzheng requested a review from a team January 30, 2025 19:08

blunderbuss-gcf bot assigned danieljbruce Jan 30, 2025

product-auto-label bot 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

gkevinzheng and 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

gkevinzheng and 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-bot bot and 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-label bot 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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 intomainfrom
read-time

gkevinzheng commented Jan 30, 2025

Uh oh!

daniel-sanche Feb 3, 2025 •

edited

Loading

Uh oh!

daniel-sanche Feb 3, 2025

Uh oh!

daniel-sanche Feb 3, 2025

Uh oh!

gkevinzheng Feb 10, 2025

Uh oh!

daniel-sanche Feb 3, 2025

Uh oh!

daniel-sanche Feb 3, 2025

Uh oh!

daniel-sanche Feb 3, 2025

Uh oh!

daniel-sanche Feb 3, 2025

Uh oh!

gkevinzheng Feb 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

Conversation

gkevinzheng commented Jan 30, 2025

Uh oh!

daniel-sanche Feb 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-sanche Feb 3, 2025 •

edited

Loading