Merge branch 'main' into enable_mypy

Author: daniel-sanche

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "2.20.2"
+    ".": "2.21.0"
 }

CHANGELOG.md

@@ -5,6 +5,18 @@
 [1]: https://pypi.org/project/google-cloud-firestore/#history
 
 
+## [2.21.0](https://github.com/googleapis/python-firestore/compare/v2.20.2...v2.21.0) (2025-05-23)
+
+
+### Features
+
+* Support Sequence[float] as query_vector in FindNearest ([#908](https://github.com/googleapis/python-firestore/issues/908)) ([6c81626](https://github.com/googleapis/python-firestore/commit/6c8162685eb82fc6f814f69741a2a51ddda4c2fa))
+
+
+### Bug Fixes
+
+* Add missing DocumentReference return value to .document ([#1053](https://github.com/googleapis/python-firestore/issues/1053)) ([043d9ef](https://github.com/googleapis/python-firestore/commit/043d9ef59627e5ed7f1acb5ab0c9d47dfd2178c1))
+
 ## [2.20.2](https://github.com/googleapis/python-firestore/compare/v2.20.1...v2.20.2) (2025-04-14)
 
 

google/cloud/firestore/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "2.20.2"  # {x-release-please-version}
+__version__ = "2.21.0"  # {x-release-please-version}

google/cloud/firestore_admin_v1/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "2.20.2"  # {x-release-please-version}
+__version__ = "2.21.0"  # {x-release-please-version}

google/cloud/firestore_bundle/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "2.20.2"  # {x-release-please-version}
+__version__ = "2.21.0"  # {x-release-please-version}

google/cloud/firestore_v1/aggregation.py

@@ -39,6 +39,8 @@
     from google.cloud.firestore_v1.query_profile import ExplainMetrics
     from google.cloud.firestore_v1.query_profile import ExplainOptions
 
+    import datetime
+
 
 class AggregationQuery(BaseAggregationQuery):
     """Represents an aggregation query to the Firestore API."""
@@ -56,6 +58,7 @@ def get(
         timeout: float | None = None,
         *,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> QueryResultsList[AggregationResult]:
         """Runs the aggregation query.
 
@@ -78,6 +81,10 @@ def get(
                 (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned generator.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a 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. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Returns:
             QueryResultsList[AggregationResult]: The aggregation query results.
@@ -90,6 +97,7 @@ def get(
             retry=retry,
             timeout=timeout,
             explain_options=explain_options,
+            read_time=read_time,
         )
         result_list = list(result)
 
@@ -100,13 +108,16 @@ def get(
 
         return QueryResultsList(result_list, explain_options, explain_metrics)
 
-    def _get_stream_iterator(self, transaction, retry, timeout, explain_options=None):
+    def _get_stream_iterator(
+        self, transaction, retry, timeout, explain_options=None, read_time=None
+    ):
         """Helper method for :meth:`stream`."""
         request, kwargs = self._prep_stream(
             transaction,
             retry,
             timeout,
             explain_options,
+            read_time,
         )
 
         return self._client._firestore_api.run_aggregation_query(
@@ -132,6 +143,7 @@ def _make_stream(
         retry: Union[retries.Retry, None, object] = gapic_v1.method.DEFAULT,
         timeout: Optional[float] = None,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> Generator[List[AggregationResult], Any, Optional[ExplainMetrics]]:
         """Internal method for stream(). Runs the aggregation query.
 
@@ -155,6 +167,10 @@ def _make_stream(
                 (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned generator.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a 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. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Yields:
             List[AggregationResult]:
@@ -172,6 +188,7 @@ def _make_stream(
             retry,
             timeout,
             explain_options,
+            read_time,
         )
         while True:
             try:
@@ -182,6 +199,8 @@ def _make_stream(
                         transaction,
                         retry,
                         timeout,
+                        explain_options,
+                        read_time,
                     )
                     continue
                 else:
@@ -206,6 +225,7 @@ def stream(
         timeout: Optional[float] = None,
         *,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> StreamGenerator[List[AggregationResult]]:
         """Runs the aggregation query.
 
@@ -229,6 +249,10 @@ def stream(
                 (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned generator.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a 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. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Returns:
             `StreamGenerator[List[AggregationResult]]`:
@@ -239,5 +263,6 @@ def stream(
             retry=retry,
             timeout=timeout,
             explain_options=explain_options,
+            read_time=read_time,
         )
         return StreamGenerator(inner_generator, explain_options)

google/cloud/firestore_v1/async_aggregation.py

@@ -37,6 +37,7 @@
     from google.cloud.firestore_v1.base_aggregation import AggregationResult
     from google.cloud.firestore_v1.query_profile import ExplainMetrics, ExplainOptions
     import google.cloud.firestore_v1.types.query_profile as query_profile_pb
+    import datetime
 
 
 class AsyncAggregationQuery(BaseAggregationQuery):
@@ -55,6 +56,7 @@ async def get(
         timeout: float | None = None,
         *,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> QueryResultsList[List[AggregationResult]]:
         """Runs the aggregation query.
 
@@ -75,6 +77,10 @@ async def get(
                 (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned generator.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a 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. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Returns:
             QueryResultsList[List[AggregationResult]]: The aggregation query results.
@@ -87,6 +93,7 @@ async def get(
             retry=retry,
             timeout=timeout,
             explain_options=explain_options,
+            read_time=read_time,
         )
         try:
             result = [aggregation async for aggregation in stream_result]
@@ -106,6 +113,7 @@ async def _make_stream(
         retry: retries.AsyncRetry | object | None = gapic_v1.method.DEFAULT,
         timeout: Optional[float] = None,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> AsyncGenerator[List[AggregationResult] | query_profile_pb.ExplainMetrics, Any]:
         """Internal method for stream(). Runs the aggregation query.
 
@@ -130,6 +138,10 @@ async def _make_stream(
                 (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned generator.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a 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. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Yields:
             List[AggregationResult] | query_profile_pb.ExplainMetrics:
@@ -143,6 +155,7 @@ async def _make_stream(
             retry,
             timeout,
             explain_options,
+            read_time,
         )
 
         response_iterator = await self._client._firestore_api.run_aggregation_query(
@@ -167,6 +180,7 @@ def stream(
         timeout: Optional[float] = None,
         *,
         explain_options: Optional[ExplainOptions] = None,
+        read_time: Optional[datetime.datetime] = None,
     ) -> AsyncStreamGenerator[List[AggregationResult]]:
         """Runs the aggregation query.
 
@@ -190,6 +204,10 @@ def stream(
                 (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned generator.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a 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. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Returns:
             `AsyncStreamGenerator[List[AggregationResult]]`:
@@ -201,5 +219,6 @@ def stream(
             retry=retry,
             timeout=timeout,
             explain_options=explain_options,
+            read_time=read_time,
         )
         return AsyncStreamGenerator(inner_generator, explain_options)

google/cloud/firestore_v1/async_client.py

@@ -48,8 +48,10 @@
     grpc_asyncio as firestore_grpc_transport,
 )
 
-if TYPE_CHECKING:
-    from google.cloud.firestore_v1.bulk_writer import BulkWriter  # pragma: NO COVER
+if TYPE_CHECKING:  # pragma: NO COVER
+    import datetime
+
+    from google.cloud.firestore_v1.bulk_writer import BulkWriter
 
 
 class AsyncClient(BaseClient):
@@ -227,6 +229,8 @@ async def get_all(
         transaction: AsyncTransaction | None = None,
         retry: retries.AsyncRetry | object | None = gapic_v1.method.DEFAULT,
         timeout: float | None = None,
+        *,
+        read_time: datetime.datetime | None = None,
     ) -> AsyncGenerator[DocumentSnapshot, Any]:
         """Retrieve a batch of documents.
 
@@ -261,13 +265,17 @@ async def get_all(
                 should be retried.  Defaults to a system-specified policy.
             timeout (float): The timeout for this request.  Defaults to a
                 system-specified value.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a 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. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Yields:
             .DocumentSnapshot: The next document snapshot that fulfills the
             query, or :data:`None` if the document does not exist.
         """
         request, reference_map, kwargs = self._prep_get_all(
-            references, field_paths, transaction, retry, timeout
+            references, field_paths, transaction, retry, timeout, read_time
         )
 
         response_iterator = await self._firestore_api.batch_get_documents(
@@ -283,6 +291,8 @@ async def collections(
         self,
         retry: retries.AsyncRetry | object | None = gapic_v1.method.DEFAULT,
         timeout: float | None = None,
+        *,
+        read_time: datetime.datetime | None = None,
     ) -> AsyncGenerator[AsyncCollectionReference, Any]:
         """List top-level collections of the client's database.
 
@@ -291,12 +301,16 @@ async def collections(
                 should be retried.  Defaults to a system-specified policy.
             timeout (float): The timeout for this request.  Defaults to a
                 system-specified value.
+            read_time (Optional[datetime.datetime]): If set, reads documents as they were at the given
+                time. This must be a 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. If no
+                timezone is specified in the :class:`datetime.datetime` object, it is assumed to be UTC.
 
         Returns:
             Sequence[:class:`~google.cloud.firestore_v1.async_collection.AsyncCollectionReference`]:
                 iterator of subcollections of the current document.
         """
-        request, kwargs = self._prep_collections(retry, timeout)
+        request, kwargs = self._prep_collections(retry, timeout, read_time)
         iterator = await self._firestore_api.list_collection_ids(
             request=request,
             metadata=self._rpc_metadata,