diff --git a/google/cloud/firestore_v1/query.py b/google/cloud/firestore_v1/query.py index 09e8c8f29..1b729a208 100644 --- a/google/cloud/firestore_v1/query.py +++ b/google/cloud/firestore_v1/query.py @@ -439,7 +439,7 @@ def offset(self, num_to_skip): all_descendants=self._all_descendants, ) - def _check_snapshot(self, document_fields): + def _check_snapshot(self, document_snapshot): """Validate local snapshots for non-collection-group queries. Raises: @@ -449,26 +449,26 @@ def _check_snapshot(self, document_fields): if self._all_descendants: return - if document_fields.reference._path[:-1] != self._parent._path: + if document_snapshot.reference._path[:-1] != self._parent._path: raise ValueError("Cannot use snapshot from another collection as a cursor.") - def _cursor_helper(self, document_fields, before, start): + def _cursor_helper(self, document_fields_or_snapshot, before, start): """Set values to be used for a ``start_at`` or ``end_at`` cursor. The values will later be used in a query protobuf. - When the query is sent to the server, the ``document_fields`` will + When the query is sent to the server, the ``document_fields_or_snapshot`` will be used in the order given by fields set by :meth:`~google.cloud.firestore_v1.query.Query.order_by`. Args: - document_fields + document_fields_or_snapshot (Union[:class:`~google.cloud.firestore_v1.document.DocumentSnapshot`, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. before (bool): Flag indicating if the document in - ``document_fields`` should (:data:`False`) or + ``document_fields_or_snapshot`` should (:data:`False`) or shouldn't (:data:`True`) be included in the result set. start (Optional[bool]): determines if the cursor is a ``start_at`` cursor (:data:`True`) or an ``end_at`` cursor (:data:`False`). @@ -478,15 +478,15 @@ def _cursor_helper(self, document_fields, before, start): A query with cursor. Acts as a copy of the current query, modified with the newly added "start at" cursor. """ - if isinstance(document_fields, tuple): - document_fields = list(document_fields) - elif isinstance(document_fields, document.DocumentSnapshot): - self._check_snapshot(document_fields) + if isinstance(document_fields_or_snapshot, tuple): + document_fields_or_snapshot = list(document_fields_or_snapshot) + elif isinstance(document_fields_or_snapshot, document.DocumentSnapshot): + self._check_snapshot(document_fields_or_snapshot) else: # NOTE: We copy so that the caller can't modify after calling. - document_fields = copy.deepcopy(document_fields) + document_fields_or_snapshot = copy.deepcopy(document_fields_or_snapshot) - cursor_pair = document_fields, before + cursor_pair = document_fields_or_snapshot, before query_kwargs = { "projection": self._projection, "field_filters": self._field_filters, @@ -504,23 +504,23 @@ def _cursor_helper(self, document_fields, before, start): return self.__class__(self._parent, **query_kwargs) - def start_at(self, document_fields): + def start_at(self, document_fields_or_snapshot): """Start query results at a particular document value. The result set will **include** the document specified by - ``document_fields``. + ``document_fields_or_snapshot``. If the current query already has specified a start cursor -- either via this method or :meth:`~google.cloud.firestore_v1.query.Query.start_after` -- this will overwrite it. - When the query is sent to the server, the ``document_fields`` will + When the query is sent to the server, the ``document_fields_or_snapshot`` will be used in the order given by fields set by :meth:`~google.cloud.firestore_v1.query.Query.order_by`. Args: - document_fields + document_fields_or_snapshot (Union[:class:`~google.cloud.firestore_v1.document.DocumentSnapshot`, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection @@ -532,25 +532,25 @@ def start_at(self, document_fields): a copy of the current query, modified with the newly added "start at" cursor. """ - return self._cursor_helper(document_fields, before=True, start=True) + return self._cursor_helper(document_fields_or_snapshot, before=True, start=True) - def start_after(self, document_fields): + def start_after(self, document_fields_or_snapshot): """Start query results after a particular document value. The result set will **exclude** the document specified by - ``document_fields``. + ``document_fields_or_snapshot``. If the current query already has specified a start cursor -- either via this method or :meth:`~google.cloud.firestore_v1.query.Query.start_at` -- this will overwrite it. - When the query is sent to the server, the ``document_fields`` will + When the query is sent to the server, the ``document_fields_or_snapshot`` will be used in the order given by fields set by :meth:`~google.cloud.firestore_v1.query.Query.order_by`. Args: - document_fields + document_fields_or_snapshot (Union[:class:`~google.cloud.firestore_v1.document.DocumentSnapshot`, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection @@ -561,25 +561,27 @@ def start_after(self, document_fields): A query with cursor. Acts as a copy of the current query, modified with the newly added "start after" cursor. """ - return self._cursor_helper(document_fields, before=False, start=True) + return self._cursor_helper( + document_fields_or_snapshot, before=False, start=True + ) - def end_before(self, document_fields): + def end_before(self, document_fields_or_snapshot): """End query results before a particular document value. The result set will **exclude** the document specified by - ``document_fields``. + ``document_fields_or_snapshot``. If the current query already has specified an end cursor -- either via this method or :meth:`~google.cloud.firestore_v1.query.Query.end_at` -- this will overwrite it. - When the query is sent to the server, the ``document_fields`` will + When the query is sent to the server, the ``document_fields_or_snapshot`` will be used in the order given by fields set by :meth:`~google.cloud.firestore_v1.query.Query.order_by`. Args: - document_fields + document_fields_or_snapshot (Union[:class:`~google.cloud.firestore_v1.document.DocumentSnapshot`, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection @@ -590,25 +592,27 @@ def end_before(self, document_fields): A query with cursor. Acts as a copy of the current query, modified with the newly added "end before" cursor. """ - return self._cursor_helper(document_fields, before=True, start=False) + return self._cursor_helper( + document_fields_or_snapshot, before=True, start=False + ) - def end_at(self, document_fields): + def end_at(self, document_fields_or_snapshot): """End query results at a particular document value. The result set will **include** the document specified by - ``document_fields``. + ``document_fields_or_snapshot``. If the current query already has specified an end cursor -- either via this method or :meth:`~google.cloud.firestore_v1.query.Query.end_before` -- this will overwrite it. - When the query is sent to the server, the ``document_fields`` will + When the query is sent to the server, the ``document_fields_or_snapshot`` will be used in the order given by fields set by :meth:`~google.cloud.firestore_v1.query.Query.order_by`. Args: - document_fields + document_fields_or_snapshot (Union[:class:`~google.cloud.firestore_v1.document.DocumentSnapshot`, dict, list, tuple]): a document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection @@ -619,7 +623,9 @@ def end_at(self, document_fields): A query with cursor. Acts as a copy of the current query, modified with the newly added "end at" cursor. """ - return self._cursor_helper(document_fields, before=False, start=False) + return self._cursor_helper( + document_fields_or_snapshot, before=False, start=False + ) def _filters_pb(self): """Convert all the filters into a single generic Filter protobuf.