U $FZhj.ã@sâdZddlmZddlmZmZmZmZmZm Z m Z ddl m Z ddl m ZddlmZmZddlmZddlmZmZdd lmZmZdd lmZdd lmZerÈdd lmZdd lm Z ddl!m"Z"Gdd„deej#ƒZ$dS)zHClasses for representing collections for the Google Cloud Firestore API.é)Ú annotations)Ú TYPE_CHECKINGÚAnyÚCallableÚ GeneratorÚOptionalÚTupleÚUnion)Úgapic_v1)Úretry)Ú aggregationÚdocument)Úquery)Ú transactionÚ vector_query)ÚBaseCollectionReferenceÚ_item_to_document_ref)ÚQueryResultsList)ÚWatch)ÚDocumentSnapshot)ÚExplainOptions)ÚStreamGeneratorcseZdZdZddœ‡fdd„ Zddœdd„Zd dœd d „Zd dœd d„Zdej j dfddddddœdd„Z dej j dfdddddœdd„Z ddœdd „Z dej j dfdd!œd"ddd#d$d%œd&d'„Zdej j dfdd!œd(dd)d#d*d%œd+d,„Zd-d.d/œd0d1„Z‡ZS)2ÚCollectionReferencea A reference to a collection in a Firestore database. The collection may already exist or this class can facilitate creation of documents within the collection. Args: path (Tuple[str, ...]): The components in the collection path. This is a series of strings representing each collection and sub-collection ID, as well as the document IDs for any documents that contain a sub-collection. kwargs (dict): The keyword arguments for the constructor. The only supported keyword is ``client`` and it must be a :class:`~google.cloud.firestore_v1.client.Client` if provided. It represents the client that created this collection reference. Raises: ValueError: if * the ``path`` is empty * there are an even number of elements * a collection ID in ``path`` is not a string * a document ID in ``path`` is not a string TypeError: If a keyword other than ``client`` is used. ÚNone)Úreturncstt|ƒj||ŽdS©N)ÚsuperrÚ__init__)ÚselfÚpathÚkwargs©Ú __class__©úk/home/aprabhat/apps/x.techxrdev.in/venv/lib/python3.8/site-packages/google/cloud/firestore_v1/collection.pyrAszCollectionReference.__init__zquery_mod.QuerycCs t |¡S)zeQuery factory. Returns: :class:`~google.cloud.firestore_v1.query.Query` )Ú query_modÚQuery©rr#r#r$Ú_queryDszCollectionReference._queryzaggregation.AggregationQuerycCst | ¡¡S)z‡AggregationQuery factory. Returns: :class:`~google.cloud.firestore_v1.aggregation_query.AggregationQuery` )r ZAggregationQueryr(r'r#r#r$Ú_aggregation_queryLsz&CollectionReference._aggregation_queryzvector_query.VectorQuerycCst | ¡¡S)zxVectorQuery factory. Returns: :class:`~google.cloud.firestore_v1.vector_query.VectorQuery` )rZ VectorQueryr(r'r#r#r$Ú _vector_queryTsz!CollectionReference._vector_queryNÚdictzUnion[str, None]zretries.Retry | object | NonezUnion[float, None]zTuple[Any, Any])Ú document_dataÚ document_idr ÚtimeoutrcCs,| ||||¡\}}|j|f|Ž}|j|fS)aCreate a document in the Firestore database with the provided data. Args: document_data (dict): Property names and values to use for creating the document. document_id (Optional[str]): The document identifier within the current collection. If not provided, an ID will be automatically assigned by the server (the assigned ID will be a random 20 character string composed of digits, uppercase and lowercase letters). 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. Returns: Tuple[:class:`google.protobuf.timestamp_pb2.Timestamp`, :class:`~google.cloud.firestore_v1.document.DocumentReference`]: Pair of * The ``update_time`` when the document was created/overwritten. * A document reference for the created document. Raises: :class:`google.cloud.exceptions.Conflict`: If ``document_id`` is provided and the document already exists. )Z _prep_addÚcreateZ update_time)rr,r-r r.Z document_refr Z write_resultr#r#r$Úadd\s"üzCollectionReference.addzUnion[int, None]zGenerator[Any, Any, None])Ú page_sizer r.rcsBˆ |||¡\}}ˆjjjf|ˆjjdœ|—Ž}‡fdd„|DƒS)a`List all subdocuments of the current collection. Args: page_size (Optional[int]]): The maximum number of documents in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API. 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. Returns: Sequence[:class:`~google.cloud.firestore_v1.collection.DocumentReference`]: iterator of subdocuments of the current collection. If the collection does not exist at the time of `snapshot`, the iterator will be empty )ÚrequestÚmetadatac3s|]}tˆ|ƒVqdSr)r)Ú.0Úir'r#r$Ú ¥sz5CollectionReference.list_documents..)Z_prep_list_documentsZ_clientZ_firestore_apiÚlist_documentsZ _rpc_metadata)rr1r r.r2r Úiteratorr#r'r$r7‡s þýz"CollectionReference.list_documentsÚint)Ú chunk_sizecCs| ¡ |¡Sr)r(Ú _chunkify)rr:r#r#r$r;§szCollectionReference._chunkify)Úexplain_optionsz$Union[transaction.Transaction, None]zOptional[ExplainOptions]z"QueryResultsList[DocumentSnapshot])rr r.r<rcCs4| ||¡\}}|dk r ||d<|jfd|i|—ŽS)aÖRead the documents in this collection. This sends a ``RunQuery`` RPC and returns a list of documents returned in the stream of ``RunQueryResponse`` messages. Args: transaction (Optional[:class:`~google.cloud.firestore_v1.transaction.transaction.Transaction`]): An existing transaction that this query will run 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. explain_options (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator. 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). Returns: QueryResultsList[DocumentSnapshot]: The documents in this collection that match the query. Nr<r)Ú_prep_get_or_streamÚget©rrr r.r<rr r#r#r$r>ªs"zCollectionReference.getz!Optional[transaction.Transaction]zOptional[float]z!StreamGenerator[DocumentSnapshot]cCs0| ||¡\}}|r||d<|jfd|i|—ŽS)a Read the documents in this collection. This sends a ``RunQuery`` RPC and then returns an iterator which consumes each document returned in the stream of ``RunQueryResponse`` messages. .. note:: The underlying stream of responses will time out after the ``max_rpc_timeout_millis`` value set in the GAPIC client configuration for the ``RunQuery`` API. Snapshots not consumed from the iterator before that point will be lost. 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: transaction (Optional[:class:`~google.cloud.firestore_v1.transaction. transaction.Transaction`]): An existing transaction that the query will run in. retry (Optional[google.api_core.retry.Retry]): Designation of what errors, if any, should be retried. Defaults to a system-specified policy. timeout (Optional[float]): The timeout for this request. Defaults to a system-specified value. explain_options (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator. Returns: `StreamGenerator[DocumentSnapshot]`: A generator of the query results. r<r)r=Ústreamr?r#r#r$r@Òs*zCollectionReference.streamrr)ÚcallbackrcCs| ¡}t ||tj¡S)aš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() )r(rZ for_queryr r)rrArr#r#r$Ú on_snapshotszCollectionReference.on_snapshot)Ú__name__Ú __module__Ú __qualname__Ú__doc__rr(r)r*r ÚmethodÚDEFAULTr0r7r;r>r@rBÚ __classcell__r#r#r!r$r's6 û-ü üú*üú0rN)%rFÚ __future__rÚtypingrrrrrrr Zgoogle.api_corer r ÚretriesZgoogle.cloud.firestore_v1r r rr%rrZ)google.cloud.firestore_v1.base_collectionrrZ'google.cloud.firestore_v1.query_resultsrZgoogle.cloud.firestore_v1.watchrZ'google.cloud.firestore_v1.base_documentrZ'google.cloud.firestore_v1.query_profilerZ*google.cloud.firestore_v1.stream_generatorrr&rr#r#r#r$Ús $