o ,= j4@sdZddlmZddlmZmZmZmZmZm Z m Z ddl m Z ddl m ZddlmZmZmZmZddlmZddlmZmZdd lmZdd lmZerddd lZdd lmZdd l m!Z!ddl"m#Z#Gdddeej$Z%d S)zHClasses for representing collections for the Google Cloud Firestore API.) annotations) TYPE_CHECKINGAnyCallable GeneratorOptionalTupleUnion)gapic_v1)retry) aggregationdocument transaction vector_query)query)BaseCollectionReference_item_to_document_ref)QueryResultsList)WatchN)DocumentSnapshot)ExplainOptions)StreamGeneratorcseZdZdZd9fdd Zd:ddZd;d d Zdd!d"Z d?d%d&Z dej j dfddd'd@d-d.Zdej j dfddd'dAd2d3ZdBd7d8ZZS)CCollectionReferencea 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. returnNonecstt|j|i|dSN)superr__init__)selfpathkwargs __class__nC:\Users\psant\Downloads\Anu Raj Backend\school\venv\Lib\site-packages\google/cloud/firestore_v1/collection.pyrCszCollectionReference.__init__query_mod.QuerycCs t|S)zeQuery factory. Returns: :class:`~google.cloud.firestore_v1.query.Query` N) query_modQueryrr#r#r$_queryFs zCollectionReference._queryaggregation.AggregationQuerycCt|S)zAggregationQuery factory. Returns: :class:`~google.cloud.firestore_v1.aggregation_query.AggregationQuery` N)r ZAggregationQueryr)r(r#r#r$_aggregation_queryNz&CollectionReference._aggregation_queryvector_query.VectorQuerycCr+)zxVectorQuery factory. Returns: :class:`~google.cloud.firestore_v1.vector_query.VectorQuery` N)rZ VectorQueryr)r(r#r#r$ _vector_queryVr-z!CollectionReference._vector_queryN document_datadict document_idUnion[str, None]r retries.Retry | object | NonetimeoutUnion[float, None]Tuple[Any, Any]cCs0|||||\}}|j|fi|}|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. N)Z _prep_addcreateZ update_time)rr0r2r r5Z document_refr Z write_resultr#r#r$add^s" zCollectionReference.add) read_time page_sizeUnion[int, None]r:Optional[datetime.datetime]Generator[Any, Any, None]csD||||\}}jjjd|jjd|}fdd|DS)aList 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. 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.DocumentReference`]: iterator of subdocuments of the current collection. If the collection does not exist at the time of `snapshot`, the iterator will be empty )requestmetadatac3s|]}t|VqdSr)r).0ir(r#r$ sz5CollectionReference.list_documents..Nr#)Z_prep_list_documentsZ_clientZ_firestore_apilist_documentsZ _rpc_metadata)rr;r r5r:r?r iteratorr#r(r$rDs z"CollectionReference.list_documents chunk_sizeintcCs||Sr)r) _chunkify)rrFr#r#r$rHszCollectionReference._chunkify)explain_optionsr:r$Union[transaction.Transaction, None]rIOptional[ExplainOptions]"QueryResultsList[DocumentSnapshot]cCsD|||\}}|dur||d<|dur||d<|jdd|i|S)asRead 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. 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. 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. NrIr:rr#)_prep_get_or_streamgetrrr r5rIr:rr r#r#r$rNs 'zCollectionReference.get!Optional[transaction.Transaction]Optional[float]!StreamGenerator[DocumentSnapshot]cCs@|||\}}|r||d<|dur||d<|jdd|i|S)aRead 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. 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: `StreamGenerator[DocumentSnapshot]`: A generator of the query results. rINr:rr#)rMstreamrOr#r#r$rSs /zCollectionReference.streamcallbackrrcCs|}t||tjS)aMonitor 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() N)r)rZ for_queryr r)rrTrr#r#r$ on_snapshotszCollectionReference.on_snapshot)rr)rr%)rr*)rr.) r0r1r2r3r r4r5r6rr7) r;r<r r4r5r6r:r=rr>)rFrG) rrJr r4r5r6rIrKr:r=rrL) rrPr r4r5rQrIrKr:r=rrR)rTrrr)__name__ __module__ __qualname____doc__rr)r,r/r methodDEFAULTr9rDrHrNrSrU __classcell__r#r#r!r$r)s@     - (17r)&rY __future__rtypingrrrrrrr Zgoogle.api_corer r retriesZgoogle.cloud.firestore_v1r r rrrr&Z)google.cloud.firestore_v1.base_collectionrrZ'google.cloud.firestore_v1.query_resultsrZgoogle.cloud.firestore_v1.watchrdatetimeZ'google.cloud.firestore_v1.base_documentrZ'google.cloud.firestore_v1.query_profilerZ*google.cloud.firestore_v1.stream_generatorrr'rr#r#r#r$s  $