def stream(
collection_ref: CollectionReference, *args, **kwargs
) -> Iterator[DocumentSnapshot]:
"""Returns a Firestore stream for a specified collection or query.
Args:
collection_ref: Firestore reference to a collection.
Raises:
FirestoreConnectorError: if an arbitrary exception occurred after retrying.
Caught by decorator to return error code.
Returns:
yields document snapshots or -1 exception (error after retrying a second
time - from decorator).
"""
try:
return collection_ref.stream(*args, **kwargs)
except Exception:
__log_exception(1, collection_ref)
sleep(EXCEPTION_SLEEP_TIME)
try:
# Retry
return collection_ref.stream(*args, **kwargs)
except Exception as exc:
__log_exception(1, collection_ref, True)
raise FirestoreConnectorError("stream", exc)
def collection(self, *collection_path):
"""Get a reference to a collection.
For a top-level collection:
.. code-block:: python
>>> client.collection('top')
For a sub-collection:
.. code-block:: python
>>> client.collection('mydocs/doc/subcol')
>>> # is the same as
>>> client.collection('mydocs', 'doc', 'subcol')
Sub-collections can be nested deeper in a similar fashion.
Args:
collection_path (Tuple[str, ...]): Can either be
* A single ``/``-delimited path to a collection
* A tuple of collection path segments
Returns:
~.firestore_v1.collection.CollectionReference: A reference
to a collection in the Firestore database.
"""
if len(collection_path) == 1:
path = collection_path[0].split(_helpers.DOCUMENT_PATH_DELIMITER)
else:
path = collection_path
return CollectionReference(*path, client=self)
def collection(self, *collection_path: Tuple[str]) -> CollectionReference:
"""Get a reference to a collection.
For a top-level collection:
.. code-block:: python
>>> client.collection('top')
For a sub-collection:
.. code-block:: python
>>> client.collection('mydocs/doc/subcol')
>>> # is the same as
>>> client.collection('mydocs', 'doc', 'subcol')
Sub-collections can be nested deeper in a similar fashion.
Args:
collection_path (Tuple[str, ...]): Can either be
* A single ``/``-delimited path to a collection
* A tuple of collection path segments
Returns:
:class:`~google.cloud.firestore_v1.collection.CollectionReference`:
A reference to a collection in the Firestore database.
"""
return CollectionReference(*_path_helper(collection_path), client=self)
def _filtered_stream(
collection_ref: CollectionReference, field_path: str, op_string: str, value: Any
) -> List[DocumentSnapshot]:
"""Like stream, but with filters."""
query = collection_ref.where(field_path, op_string, value)
docs = stream(query)
if docs == StatusCode.ERROR:
raise FirestoreConnectorError("filtered_stream", error_code=StatusCode.ERROR)
return [doc for doc in docs]
def collection_exists(collection_ref: CollectionReference) -> bool:
"""A helper method to check whether a collection exists
Args:
collection_ref: The reference object to check if exists.
Returns:
bool: True if it exists, False otherwise.
Examples:
>>> db = new_connection(project=FIRESTORE_PROJECT_ID)
>>> col_ref = db.collection("MY_COLLECTION")
>>> print(fc.collection_exists(col_ref))
False
"""
docs = get(collection_ref.limit(1))
if docs == -1:
logging.error(
"Couldn't get collection_ref. Please check the logs above for possible errors."
)
return False
return len(docs) > 0
def _make_collection_reference(*args, **kwargs):
from google.cloud.firestore_v1.collection import CollectionReference
return CollectionReference(*args, **kwargs)