o ,= j=@s dZddlmZddlmZmZmZmZmZm Z m Z ddl m Z ddl m ZddlmZmZmZmZddlmZddlmZdd lmZdd lmZdd lmZdd lmZdd l m!Z!ddl"m#Z#ddl$m%Z%ddl&m'Z(ddl)m*Z+ddl,m-Z-erddl.Z.ddl/m0Z0GdddeZ1dS)aClient for interacting with the Google Cloud Firestore API. This is the base from which all interactions with the API occur. In the hierarchy of API concepts * a :class:`~google.cloud.firestore_v1.client.Client` owns a :class:`~google.cloud.firestore_v1.collection.CollectionReference` * a :class:`~google.cloud.firestore_v1.client.Client` owns a :class:`~google.cloud.firestore_v1.document.DocumentReference` ) annotations) TYPE_CHECKINGAny GeneratorIterableListOptionalUnion)gapic_v1)retry) _CLIENT_INFO BaseClient_parse_batch_get _path_helper)DocumentSnapshot) MAX_ATTEMPTS WriteBatch)CollectionReference)DocumentReference) FieldPathPipelinePipelineSource)CollectionGroup)client)grpc TransactionN) BulkWritercseZdZdZdddedfdHfdd ZeddZdId d ZdJddZ dKddZ dde j j dfdddLd$d%Ze j j dfdddMd'd(Zdd)d*dNd1d2Zd)d3d4dOd7d8ZdPd:d;Zed>> 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: 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. rN)rr)r+r4r.r.r/ collectionwszClient.collection collection_idrcCst||S)a Creates and returns a new Query that includes all documents in the database that are contained in a collection or subcollection with the given collection_id. .. code-block:: python >>> query = client.collection_group('mygroup') Args: collection_id (str) Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. Returns: :class:`~google.cloud.firestore_v1.query.CollectionGroup`: The created Query. N)rZ_get_collection_reference)r+r7r.r.r/collection_groupszClient.collection_group document_pathrcGst|j|d|iS)a}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): 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. rN)rZ_document_path_helper)r+r9r.r.r/documents zClient.document) read_time referenceslist field_pathsIterable[str] | None transactionTransaction | Noner retries.Retry | object | Nonetimeout float | Noner;datetime.datetime | None&Generator[DocumentSnapshot, Any, None]c csR|||||||\}}} |jjd||jd| } | D] } t| ||VqdS)a7Retrieve a batch of documents. .. note:: Documents returned by this method are not guaranteed to be returned in the same order that they are given in ``references``. .. note:: If multiple ``references`` refer to the same document, the server will only return one result. See :meth:`~google.cloud.firestore_v1.client.Client.field_path` for more information on **field paths**. If a ``transaction`` is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed). Args: references (List[.DocumentReference, ...]): Iterable of document references to be retrieved. field_paths (Optional[Iterable[str, ...]]): An iterable of field paths (``.``-delimited list of field names) to use as a projection of document fields in the returned results. If no value is provided, all fields will be returned. transaction (Optional[:class:`~google.cloud.firestore_v1.transaction.Transaction`]): An existing transaction that these ``references`` will be retrieved in. retry (google.api_core.retry.Retry): Designation of what errors, if any, 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. requestmetadataNr.)Z _prep_get_allr3Zbatch_get_documents _rpc_metadatar) r+r<r>r@r rCr;rHZ reference_mapkwargsZresponse_iteratorZget_doc_responser.r.r/get_alls4  zClient.get_allGenerator[Any, Any, None]ccsH||||\}}|jjd||jd|}|D]}||VqdS)aList top-level collections of the client's database. Args: retry (google.api_core.retry.Retry): Designation of what errors, if any, 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.collection.CollectionReference`]: iterator of subcollections of the current document. rGNr.)Z_prep_collectionsr3Zlist_collection_idsrJr6)r+r rCr;rHrKiteratorr7r.r.r/ collectionsszClient.collectionsi) bulk_writer chunk_size reference-Union[CollectionReference, DocumentReference]rPOptional['BulkWriter']rQintcCs |dur|}|j|||dS)aUDeletes documents and their subcollections, regardless of collection name. Passing a CollectionReference leads to each document in the collection getting deleted, as well as all of their descendents. Passing a DocumentReference deletes that one document and all of its descendents. Args: reference (Union[ :class:`@google.cloud.firestore_v1.collection.CollectionReference`, :class:`@google.cloud.firestore_v1.document.DocumentReference`, ]) The reference to be deleted. bulk_writer (Optional[:class:`@google.cloud.firestore_v1.bulk_writer.BulkWriter`]) The BulkWriter used to delete all matching documents. Supply this if you want to override the default throttling behavior. N)rQ)rP_recursive_delete)r+rRrPrQr.r.r/recursive_delete2szClient.recursive_deleterrQdepth 'BulkWriter'rYc Csd}t|tr&|tg|D]=}|D] }|d7}||jqqt|t rI| D]}||j ||||dd7}q/|d7}||n t d|j j|dkrZ||S)z'Recursion helper for `recursive_delete.rrXzUnexpected type for reference: N) isinstancer recursiveselectrZ document_idZ _chunkifydeleterRrrOrV TypeErrorr-__name__close) r+rRrPrQrYZ num_deletedchunkZdoc_snapZcol_refr.r.r/rVWs4       zClient._recursive_deletercCt|S)zGet a batch instance from this client. Returns: :class:`~google.cloud.firestore_v1.batch.WriteBatch`: A "write" batch to be used for accumulating document changes and sending the changes all at once. Nrr2r.r.r/batchsz Client.batchF max_attempts read_onlyboolrcCst|||dS)aDGet a transaction that uses this client. See :class:`~google.cloud.firestore_v1.transaction.Transaction` for more information on transactions and the constructor arguments. Args: kwargs (Dict[str, Any]): The keyword arguments (other than ``client``) to pass along to the :class:`~google.cloud.firestore_v1.transaction.Transaction` constructor. Returns: :class:`~google.cloud.firestore_v1.transaction.Transaction`: A transaction attached to this client. )rfrgNr)r+rfrgr.r.r/r@szClient.transactioncCstSNrr2r.r.r/ _pipeline_clsszClient._pipeline_clsrcCrdrirr2r.r.r/pipelineszClient.pipeline)r"r#)r4r5r"r)r7r5r"r)r9r5r"r)r<r=r>r?r@rAr rBrCrDr;rEr"rF)r rBrCrDr;rEr"rM)rRrSrPrTrQrUr"rU) rRrSrPrZrQrUrYrUr"rU)r"r)rfrUrgrhr"r)r"r)ra __module__ __qualname____doc__r r*propertyr3r6r8r:r methodDEFAULTrLrOrWrVrerr@rjrk __classcell__r.r.r,r/r!?sJ   &C&* .  r!)2rn __future__rtypingrrrrrrr Zgoogle.api_corer r retriesZ%google.cloud.firestore_v1.base_clientr r rrZ'google.cloud.firestore_v1.base_documentrZ*google.cloud.firestore_v1.base_transactionrZgoogle.cloud.firestore_v1.batchrZ$google.cloud.firestore_v1.collectionrZ"google.cloud.firestore_v1.documentrZ$google.cloud.firestore_v1.field_pathrZ"google.cloud.firestore_v1.pipelinerZ)google.cloud.firestore_v1.pipeline_sourcerZgoogle.cloud.firestore_v1.queryrZ,google.cloud.firestore_v1.services.firestorerr1Z7google.cloud.firestore_v1.services.firestore.transportsrr0Z%google.cloud.firestore_v1.transactionrdatetimeZ%google.cloud.firestore_v1.bulk_writerr r!r.r.r.r/s, $