Repository navigation
Type Mismatch DocumentSnapshot of AsyncCollectionReference #15367
Description
Environment details
- OS type and version: MacOS Sequoia 15.6
- Python version: 3.13.5
- pip version 25.1.1
google-cloud-firestoreversion: 2.21.0
Description
There's a type inconsistency between the IDE's type hints and the actual returned types when working with Firestore's AsyncClient.
Steps to reproduce
- Initialize async client
- Make a query on a collection
- fetch query data using
await query.get() - the IDE suggest the return type of
google.cloud.firestore_v1.query_results.QueryResultsList[DocumentSnapshot] - call
.referenceon any object of the query, the IDE will suggest that the return type would begoogle.cloud.firestore_v1.base_document.DocumentSnapshot - in reality the document returned is
google.cloud.firestore_v1.async_document.AsyncDocumentReference
Code example
import firebase_admin
firebase_admin.initialize_app()
aclient = firestore_async.firestore.AsyncClient(database="(default)")
users = await aclient.collection("users").get()
print(type(users[0]))
# <class 'google.cloud.firestore_v1.base_document.DocumentSnapshot'>
print(type(users[0].reference)) # Mismatch between type hint and actual type. see the references
# <class 'google.cloud.firestore_v1.async_document.AsyncDocumentReference'>references
https://github.com/googleapis/python-firestore/blob/49836391dc712bd482781a26ccd3c8a8408c473b/google/cloud/firestore_v1/async_collection.py#L199-L244
https://github.com/googleapis/python-firestore/blob/49836391dc712bd482781a26ccd3c8a8408c473b/google/cloud/firestore_v1/async_collection.py#L72-L78
https://github.com/googleapis/python-firestore/blob/49836391dc712bd482781a26ccd3c8a8408c473b/google/cloud/firestore_v1/async_collection.py#L199-L244
https://github.com/googleapis/python-firestore/blob/49836391dc712bd482781a26ccd3c8a8408c473b/google/cloud/firestore_v1/async_query.py#L189-L263
https://github.com/googleapis/python-firestore/blob/49836391dc712bd482781a26ccd3c8a8408c473b/google/cloud/firestore_v1/base_document.py#L441-L449
https://github.com/googleapis/python-firestore/blob/49836391dc712bd482781a26ccd3c8a8408c473b/google/cloud/firestore_v1/async_collection.py#L246-L254
Activity
daniel-sanche commentedon Oct 31, 2025
Is this supposed to be
DocumentReferenceinstead ofDocumentSnapshot? You're calling .reference on a snapshot instance, so I wouldn't expect it to return another snapshot. If your IDE is inferring a snapshot there, that would be unexpected, and worth looking into moreAssuming you mean
DocumentReference, I think you're right that the there's an inconsistency here. We don't provide any type annotations in snapshot.reference, but the docstring does suggest it returns a DocumentReference, even though it can also be an AsyncDocumentReference. Maybe your IDE falls back to those docstrings for untyped functionsparthea commentedon Jan 13, 2026
Transferring to google-cloud-python as the code for python-firestore will be migrated there in 1-3 weeks.
daniel-sanche commentedon Oct 7, 2026
I opened a PR to address this here: #18587
fix(firestore): add generic typing for DocumentSnapshot (googleapis#1…