Type Mismatch DocumentSnapshot of AsyncCollectionReference · Issue #15367 · googleapis/google-cloud-python · GitHub

Environment details

OS type and version: MacOS Sequoia 15.6
Python version: 3.13.5
pip version 25.1.1
google-cloud-firestore version: 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 .reference on any object of the query, the IDE will suggest that the return type would be google.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

call .reference on any object of the query, the IDE will suggest that the return type would be google.cloud.firestore_v1.base_document.DocumentSnapshot

Is this supposed to be DocumentReference instead of DocumentSnapshot? 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 more

Assuming 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 functions

Transferring to google-cloud-python as the code for python-firestore will be migrated there in 1-3 weeks.

I opened a PR to address this here: #18587

fix(firestore): add generic typing for DocumentSnapshot (googleapis#1…

Type Mismatch DocumentSnapshot of AsyncCollectionReference · Issue #15367 · googleapis/google-cloud-python · GitHub

Repository navigation

Type Mismatch DocumentSnapshot of AsyncCollectionReference #15367

Environment details

Description

Steps to reproduce

Code example

references

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Type Mismatch DocumentSnapshot of AsyncCollectionReference · Issue #15367 · googleapis/google-cloud-python · GitHub

Repository navigation

Type Mismatch DocumentSnapshot of AsyncCollectionReference #15367

Description

Environment details

Description

Steps to reproduce

Code example

references

Activity

daniel-sanche commented on Oct 31, 2025

parthea commented on Jan 13, 2026

daniel-sanche commented on Oct 7, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions