def on_snapshot(self, callback: Callable) -> Watch:
"""Monitor the documents in this collection that match this query.
This starts a watch on this query using a background thread. The
provided callback is run on the snapshot of the documents.
Args:
callback(Callable[[:class:`~google.cloud.firestore.query.QuerySnapshot`], NoneType]):
a callback to run when a change occurs.
Example:
.. code-block:: python
from google.cloud import firestore_v1
db = firestore_v1.Client()
query_ref = db.collection(u'users').where("user", "==", u'Ada')
def on_snapshot(docs, changes, read_time):
for doc in docs:
print(u'{} => {}'.format(doc.id, doc.to_dict()))
# Watch this query
query_watch = query_ref.on_snapshot(on_snapshot)
# Terminate this watch
query_watch.unsubscribe()
"""
return Watch.for_query(self, callback, document.DocumentSnapshot,
document.DocumentReference)
def on_snapshot(self, callback):
"""Watch this document.
This starts a watch on this document using a background thread. The
provided callback is run on the snapshot.
Args:
callback(Callable[[:class:`~google.cloud.firestore.document.DocumentSnapshot`], NoneType]):
a callback to run when a change occurs
Example:
.. code-block:: python
from google.cloud import firestore_v1
db = firestore_v1.Client()
collection_ref = db.collection(u'users')
def on_snapshot(document_snapshot):
doc = document_snapshot
print(u'{} => {}'.format(doc.id, doc.to_dict()))
doc_ref = db.collection(u'users').document(
u'alovelace' + unique_resource_id())
# Watch this document
doc_watch = doc_ref.on_snapshot(on_snapshot)
# Terminate this watch
doc_watch.unsubscribe()
"""
return Watch.for_document(self, callback, DocumentSnapshot, DocumentReference)
def test_for_query_nested(self):
from google.cloud.firestore_v1.watch import Watch
snapshot_callback = self._snapshot_callback
snapshot_class_instance = DummyDocumentSnapshot
document_reference_class_instance = DummyDocumentReference
client = DummyFirestore()
root = DummyCollection(client)
grandparent = DummyDocument("document", parent=root)
parent = DummyCollection(client, parent=grandparent)
modulename = "google.cloud.firestore_v1.watch"
pb2 = DummyPb2()
with mock.patch("%s.firestore" % modulename, pb2):
with mock.patch("%s.Watch.ResumableBidiRpc" % modulename,
DummyRpc):
with mock.patch("%s.Watch.BackgroundConsumer" % modulename,
DummyBackgroundConsumer):
query = DummyQuery(parent=parent)
inst = Watch.for_query(
query,
snapshot_callback,
snapshot_class_instance,
document_reference_class_instance,
)
self.assertTrue(inst._consumer.started)
self.assertTrue(inst._rpc.callbacks, [inst._on_rpc_done])
self.assertEqual(inst._targets["query"], "dummy query target")
def on_snapshot(self, callback):
"""Monitor the documents in this collection.
This starts a watch on this collection using a background thread. The
provided callback is run on the snapshot of the documents.
Args:
callback (Callable[[:class:`~google.cloud.firestore.collection.CollectionSnapshot`], NoneType]):
a callback to run when a change occurs.
Example:
from google.cloud import firestore_v1
db = firestore_v1.Client()
collection_ref = db.collection(u'users')
def on_snapshot(collection_snapshot, changes, read_time):
for doc in collection_snapshot.documents:
print(u'{} => {}'.format(doc.id, doc.to_dict()))
# Watch this collection
collection_watch = collection_ref.on_snapshot(on_snapshot)
# Terminate this watch
collection_watch.unsubscribe()
"""
return Watch.for_query(
query_mod.Query(self),
callback,
document.DocumentSnapshot,
document.DocumentReference,
)
def on_snapshot(self, callback):
"""Monitor the documents in this collection.
This starts a watch on this collection using a background thread. The
provided callback is run on the snapshot of the documents.
Args:
callback (Callable[[:class:`~google.cloud.firestore.collection.CollectionSnapshot`], NoneType]):
a callback to run when a change occurs.
Example:
from google.cloud import firestore_v1
db = firestore_v1.Client()
collection_ref = db.collection(u'users')
def on_snapshot(collection_snapshot):
for doc in collection_snapshot.documents:
print(u'{} => {}'.format(doc.id, doc.to_dict()))
# Watch this collection
collection_watch = collection_ref.on_snapshot(on_snapshot)
# Terminate this watch
collection_watch.unsubscribe()
"""
return Watch.for_query(
query_mod.Query(self),
callback,
document.DocumentSnapshot,
document.DocumentReference,
)
def on_snapshot(self, callback):
"""Monitor the documents in this collection that match this query.
This starts a watch on this query using a background thread. The
provided callback is run on the snapshot of the documents.
Args:
callback(Callable[[:class:`~google.cloud.firestore.query.QuerySnapshot`], NoneType]):
a callback to run when a change occurs.
Example:
.. code-block:: python
from google.cloud import firestore_v1
db = firestore_v1.Client()
query_ref = db.collection(u'users').where("user", "==", u'Ada')
def on_snapshot(docs, changes, read_time):
for doc in docs:
print(u'{} => {}'.format(doc.id, doc.to_dict()))
# Watch this query
query_watch = query_ref.on_snapshot(on_snapshot)
# Terminate this watch
query_watch.unsubscribe()
"""
return Watch.for_query(
self, callback, document.DocumentSnapshot, document.DocumentReference
)
def test_for_query_nested(self):
from google.cloud.firestore_v1.watch import Watch
snapshot_callback = self._snapshot_callback
snapshot_class_instance = DummyDocumentSnapshot
document_reference_class_instance = DummyDocumentReference
client = DummyFirestore()
root = DummyCollection(client)
grandparent = DummyDocument("document", parent=root)
parent = DummyCollection(client, parent=grandparent)
modulename = "google.cloud.firestore_v1.watch"
pb2 = DummyPb2()
with mock.patch("%s.firestore_pb2" % modulename, pb2):
with mock.patch("%s.Watch.ResumableBidiRpc" % modulename, DummyRpc):
with mock.patch(
"%s.Watch.BackgroundConsumer" % modulename, DummyBackgroundConsumer
):
query = DummyQuery(parent=parent)
inst = Watch.for_query(
query,
snapshot_callback,
snapshot_class_instance,
document_reference_class_instance,
)
self.assertTrue(inst._consumer.started)
self.assertTrue(inst._rpc.callbacks, [inst._on_rpc_done])
self.assertEqual(inst._targets["query"], "dummy query target")
def test_watch_for_query_nested(snapshots):
from google.cloud.firestore_v1.watch import Watch
def snapshot_callback(*args): # pragma: NO COVER
snapshots.append(args)
client = DummyFirestore()
root = DummyCollection(client)
grandparent = DummyDocument("document", parent=root)
parent = DummyCollection(client, parent=grandparent)
query = DummyQuery(parent=parent)
with mock.patch("google.cloud.firestore_v1.watch.ResumableBidiRpc"):
with mock.patch("google.cloud.firestore_v1.watch.BackgroundConsumer"):
with mock.patch(
"google.cloud.firestore_v1.watch.Target") as target:
inst = Watch.for_query(
query,
snapshot_callback,
document_snapshot_cls=DummyDocumentSnapshot,
)
inst._consumer.start.assert_called_once_with()
inst._rpc.add_done_callback.assert_called_once_with(inst._on_rpc_done)
query_target = target.QueryTarget.return_value
parent_path, _ = parent._parent_info()
target.QueryTarget.assert_called_once_with(
parent=parent_path,
structured_query=query._to_protobuf(),
)
query_target = target.QueryTarget.return_value
assert inst._targets["query"] is query_target._pb
def on_snapshot(self, callback) -> Watch:
"""Watch this document.
This starts a watch on this document using a background thread. The
provided callback is run on the snapshot.
Args:
callback(Callable[[:class:`~google.cloud.firestore.document.DocumentSnapshot`], NoneType]):
a callback to run when a change occurs
Example:
.. code-block:: python
from google.cloud import firestore_v1
db = firestore_v1.Client()
collection_ref = db.collection(u'users')
def on_snapshot(document_snapshot, changes, read_time):
doc = document_snapshot
print(u'{} => {}'.format(doc.id, doc.to_dict()))
doc_ref = db.collection(u'users').document(
u'alovelace' + unique_resource_id())
# Watch this document
doc_watch = doc_ref.on_snapshot(on_snapshot)
# Terminate this watch
doc_watch.unsubscribe()
"""
return Watch.for_document(self, callback, DocumentSnapshot, DocumentReference)
def test_watch_for_document(snapshots):
from google.cloud.firestore_v1.watch import Watch
def snapshot_callback(*args): # pragma: NO COVER
snapshots.append(args)
docref = DummyDocumentReference()
with mock.patch("google.cloud.firestore_v1.watch.ResumableBidiRpc"):
with mock.patch("google.cloud.firestore_v1.watch.BackgroundConsumer"):
inst = Watch.for_document(
docref,
snapshot_callback,
document_snapshot_cls=DummyDocumentSnapshot,
)
inst._consumer.start.assert_called_once_with()
inst._rpc.add_done_callback.assert_called_once_with(inst._on_rpc_done)
def _makeOne(
self,
document_reference=None,
firestore=None,
target=None,
comparator=None,
snapshot_callback=None,
snapshot_class=None,
reference_class=None,
): # pragma: NO COVER
from google.cloud.firestore_v1.watch import Watch
if document_reference is None:
document_reference = DummyDocumentReference()
if firestore is None:
firestore = DummyFirestore()
if target is None:
WATCH_TARGET_ID = 0x5079 # "Py"
target = {
"documents": {
"documents": ["/"]
},
"target_id": WATCH_TARGET_ID
}
if comparator is None:
comparator = self._document_watch_comparator
if snapshot_callback is None:
snapshot_callback = self._snapshot_callback
if snapshot_class is None:
snapshot_class = DummyDocumentSnapshot
if reference_class is None:
reference_class = DummyDocumentReference
inst = Watch(
document_reference,
firestore,
target,
comparator,
snapshot_callback,
snapshot_class,
reference_class,
BackgroundConsumer=DummyBackgroundConsumer,
ResumableBidiRpc=DummyRpc,
)
return inst
def test_for_document(self):
from google.cloud.firestore_v1.watch import Watch
docref = DummyDocumentReference()
snapshot_callback = self._snapshot_callback
snapshot_class_instance = DummyDocumentSnapshot
document_reference_class_instance = DummyDocumentReference
modulename = "google.cloud.firestore_v1.watch"
with mock.patch("%s.Watch.ResumableBidiRpc" % modulename, DummyRpc):
with mock.patch("%s.Watch.BackgroundConsumer" % modulename,
DummyBackgroundConsumer):
inst = Watch.for_document(
docref,
snapshot_callback,
snapshot_class_instance,
document_reference_class_instance,
)
self.assertTrue(inst._consumer.started)
self.assertTrue(inst._rpc.callbacks, [inst._on_rpc_done])
def test_for_document(self):
from google.cloud.firestore_v1.watch import Watch
docref = DummyDocumentReference()
snapshot_callback = self._snapshot_callback
snapshot_class_instance = DummyDocumentSnapshot
document_reference_class_instance = DummyDocumentReference
modulename = "google.cloud.firestore_v1.watch"
with mock.patch("%s.Watch.ResumableBidiRpc" % modulename, DummyRpc):
with mock.patch(
"%s.Watch.BackgroundConsumer" % modulename, DummyBackgroundConsumer
):
inst = Watch.for_document(
docref,
snapshot_callback,
snapshot_class_instance,
document_reference_class_instance,
)
self.assertTrue(inst._consumer.started)
self.assertTrue(inst._rpc.callbacks, [inst._on_rpc_done])
def _make_watch_no_mocks(
snapshots=None,
comparator=_document_watch_comparator,
):
from google.cloud.firestore_v1.watch import Watch
WATCH_TARGET_ID = 0x5079 # "Py"
target = {"documents": {"documents": ["/"]}, "target_id": WATCH_TARGET_ID}
if snapshots is None:
snapshots = []
def snapshot_callback(*args):
snapshots.append(args)
return Watch(
document_reference=DummyDocumentReference(),
firestore=DummyFirestore(),
target=target,
comparator=comparator,
snapshot_callback=snapshot_callback,
document_snapshot_cls=DummyDocumentSnapshot,
)