def document(self, *document_path: Tuple[str]) -> DocumentReference:
"""Get a reference to a document in a collection.
For a top-level document:
.. code-block:: python
>>> client.document('collek/shun')
>>> # is the same as
>>> client.document('collek', 'shun')
For a document in a sub-collection:
.. code-block:: python
>>> client.document('mydocs/doc/subcol/child')
>>> # is the same as
>>> client.document('mydocs', 'doc', 'subcol', 'child')
Documents in sub-collections can be nested deeper in a similar fashion.
Args:
document_path (Tuple[str, ...]): Can either be
* A single ``/``-delimited path to a document
* A tuple of document path segments
Returns:
:class:`~google.cloud.firestore_v1.document.DocumentReference`:
A reference to a document in a collection.
"""
return DocumentReference(*self._document_path_helper(*document_path),
client=self)
def test_get_document_ref(self):
from google.cloud.firestore_v1.document import DocumentReference
client = mock.Mock(spec=["get_all"])
transaction = self._make_one(client)
ref = DocumentReference("documents", "doc-id")
result = transaction.get(ref)
client.get_all.assert_called_once_with([ref], transaction=transaction.id)
self.assertIs(result, client.get_all.return_value)
def test_clean_dict(document):
doc_dict = document.to_dict()
doc_dict.update({
'ref': DocumentReference('collection', 'doc'),
'nan_value': np.nan
})
result_dict = clean_dict(doc_dict)
assert result_dict.get('ref') is None
assert result_dict.get('nan_value') is None
def test_missing(self):
from google.cloud.firestore_v1.document import DocumentReference
ref_string = self._dummy_ref_string()
response_pb = _make_batch_response(missing=ref_string)
document = DocumentReference("fizz", "bazz", client=mock.sentinel.client)
reference_map = {ref_string: document}
snapshot = self._call_fut(response_pb, reference_map)
self.assertFalse(snapshot.exists)
self.assertEqual(snapshot.id, "bazz")
self.assertIsNone(snapshot._data)
def test__parse_batch_get_missing():
from google.cloud.firestore_v1.document import DocumentReference
from google.cloud.firestore_v1.base_client import _parse_batch_get
ref_string = _dummy_ref_string()
response_pb = _make_batch_response(missing=ref_string)
document = DocumentReference("fizz", "bazz", client=mock.sentinel.client)
reference_map = {ref_string: document}
snapshot = _parse_batch_get(response_pb, reference_map,
mock.sentinel.client)
assert not snapshot.exists
assert snapshot.id == "bazz"
assert snapshot._data is None
def _transaction_get_w_document_ref_helper(retry=None, timeout=None):
from google.cloud.firestore_v1.document import DocumentReference
from google.cloud.firestore_v1 import _helpers
client = mock.Mock(spec=["get_all"])
transaction = _make_transaction(client)
ref = DocumentReference("documents", "doc-id")
kwargs = _helpers.make_retry_timeout_kwargs(retry, timeout)
result = transaction.get(ref, **kwargs)
assert result is client.get_all.return_value
client.get_all.assert_called_once_with([ref],
transaction=transaction,
**kwargs)
def _add_bundle_element(self, bundle_element: BundleElement, *,
client: BaseClient, type: str): # type: ignore
"""Applies BundleElements to this FirestoreBundle instance as a part of
deserializing a FirestoreBundle string.
"""
from google.cloud.firestore_v1.types.document import Document
if getattr(self, "_doc_metadata_map", None) is None:
self._doc_metadata_map = {}
if type == "metadata":
self._deserialized_metadata = bundle_element.metadata # type: ignore
elif type == "namedQuery":
self.named_queries[
bundle_element.named_query.
name] = bundle_element.named_query # type: ignore
elif type == "documentMetadata":
self._doc_metadata_map[bundle_element.document_metadata.
name] = bundle_element.document_metadata
elif type == "document":
doc_ref_value = _helpers.DocumentReferenceValue(
bundle_element.document.name)
snapshot = DocumentSnapshot(
data=_helpers.decode_dict(
Document(mapping=bundle_element.document).fields, client),
exists=True,
reference=DocumentReference(
doc_ref_value.collection_name,
doc_ref_value.document_id,
client=client,
),
read_time=self._doc_metadata_map[
bundle_element.document.name].read_time,
create_time=bundle_element.document.
create_time, # type: ignore
update_time=bundle_element.document.
update_time, # type: ignore
)
self.add_document(snapshot)
bundled_document = self.documents.get(
snapshot.reference._document_path)
for query_name in self._doc_metadata_map[
bundle_element.document.name].queries:
bundled_document.metadata.queries.append(
query_name) # type: ignore
else:
raise ValueError(f"Unexpected type of BundleElement: {type}")
def document(self, *document_path):
"""Get a reference to a document in a collection.
For a top-level document:
.. code-block:: python
>>> client.document('collek/shun')
>>> # is the same as
>>> client.document('collek', 'shun')
For a document in a sub-collection:
.. code-block:: python
>>> client.document('mydocs/doc/subcol/child')
>>> # is the same as
>>> client.document('mydocs', 'doc', 'subcol', 'child')
Documents in sub-collections can be nested deeper in a similar fashion.
Args:
document_path (Tuple[str, ...]): Can either be
* A single ``/``-delimited path to a document
* A tuple of document path segments
Returns:
~.firestore_v1.document.DocumentReference: A reference
to a document in a collection.
"""
if len(document_path) == 1:
path = document_path[0].split(_helpers.DOCUMENT_PATH_DELIMITER)
else:
path = document_path
# DocumentReference takes a relative path. Strip the database string if present.
base_path = self._database_string + "/documents/"
joined_path = _helpers.DOCUMENT_PATH_DELIMITER.join(path)
if joined_path.startswith(base_path):
joined_path = joined_path[len(base_path) :]
path = joined_path.split(_helpers.DOCUMENT_PATH_DELIMITER)
return DocumentReference(*path, client=self)
def build_document_snapshot(
*,
collection_name: str = "col",
document_id: str = "doc",
client: typing.Optional[BaseClient] = None,
data: typing.Optional[typing.Dict] = None,
exists: bool = True,
create_time: typing.Optional[Timestamp] = None,
read_time: typing.Optional[Timestamp] = None,
update_time: typing.Optional[Timestamp] = None,
) -> DocumentSnapshot:
return DocumentSnapshot(
DocumentReference(collection_name, document_id, client=client),
data or {"hello", "world"},
exists=exists,
read_time=read_time or build_timestamp(),
create_time=create_time or build_timestamp(),
update_time=update_time or build_timestamp(),
)
def _make_document_reference(*args, **kwargs):
from google.cloud.firestore_v1.document import DocumentReference
return DocumentReference(*args, **kwargs)