o ˷e@H@sdZddlZddlmZddlmZddlmZddlm Z ddlm Z ddlm Z dd lm Z dd lmZmZmZmZmZmZmZGd d d eZGd ddeZdeedefddZde jfddZdede jfddZdS)zFClasses for representing documents for the Google Cloud Firestore API.N)retry)Document)_helpers) field_path)common) firestore)write)AnyDictIterableNoReturnOptionalUnionTuplec @seZdZdZdZd?ddZddZdd Zd d Zd d Z ddZ e ddZ e ddZ e ddZe ddZdedefddZ  d@dedejdedeeeffddZ  d@dedejdedefd d!Z "  dAded#edejdedeeeff d$d%Z "  dAded#edejdedef d&d'Z   dBd(ed)ejdejdedeeeff d*d+Z   dBd(ed)ejdejdedef d,d-Z!   dBd)ejdejdedeeeffd.d/Z"   dBd)ejdejdedefd0d1Z#    dCd2e$edejdedeeeffd3d4Z%    dCd2e$edejdedd5fd6d7Z&   dBd8e'dejdedeeeffd9d:Z(   dBd8e'dejdeddfd;d<Z)d?d=d>Z*dS)DBaseDocumentReferenceaA reference to a document in a Firestore database. The document may already exist or can be created by this class. Args: path (Tuple[str, ...]): The components in the document 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 (as well as the base document). 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`. It represents the client that created this document 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. NreturncOs6tj|dd||_|dd|_|rtd|ddS)NF) is_collectionclientzReceived unexpected argumentszOnly `client` is supported)r verify_path_pathpop_client TypeError)selfpathkwargsr^/var/www/ideatree/venv/lib/python3.10/site-packages/google/cloud/firestore_v1/base_document.py__init__;szBaseDocumentReference.__init__cCs |j|jd|ji}|j|_|S)zShallow copy the instance. We leave the client "as-is" but tuple-unpack the path. Returns: .DocumentReference: A copy of the current document. r) __class__rr_document_path_internal)rresultrrr__copy__DszBaseDocumentReference.__copy__cCs|S)zDeep copy the instance. This isn't a true deep copy, wee leave the client "as-is" but tuple-unpack the path. Returns: .DocumentReference: A copy of the current document. )r")r unused_memorrr __deepcopy__Ps z"BaseDocumentReference.__deepcopy__cCs(t||jr|j|jko|j|jkStS)zEquality check against another instance. Args: other (Any): A value to compare against. Returns: Union[bool, NotImplementedType]: Indicating if the values are equal.  isinstancerrrNotImplementedrotherrrr__eq__[ zBaseDocumentReference.__eq__cCt|jt|jSN)hashrrrrrr__hash__jzBaseDocumentReference.__hash__cCs(t||jr|j|jkp|j|jkStS)zInequality check against another instance. Args: other (Any): A value to compare against. Returns: Union[bool, NotImplementedType]: Indicating if the values are not equal. r%r(rrr__ne__mr+zBaseDocumentReference.__ne__cCs d|jS)znDatabase-relative for this document. Returns: str: The document's relative path. /)joinrr/rrrr|s zBaseDocumentReference.pathcCs2|jdur|jdurtdt|j|j|_|jS)aXCreate and cache the full path for this document. Of the form: ``projects/{project_id}/databases/{database_id}/... documents/{document_path}`` Returns: str: The full document path. Raises: ValueError: If the current document reference has no ``client``. Nz)A document reference requires a `client`.)r r ValueError_get_document_pathrr/rrr_document_paths  z$BaseDocumentReference._document_pathcCs |jdS)z|The document identifier (within its collection). Returns: str: The last component of the path. )rr/rrrids zBaseDocumentReference.idcCs|jdd}|jj|S)zCollection that owns the current document. Returns: :class:`~google.cloud.firestore_v1.collection.CollectionReference`: The parent collection. Nr8rr collection)r parent_pathrrrparents zBaseDocumentReference.parent collection_idcCs|j|f}|jj|S)aJCreate a sub-collection underneath the current document. Args: collection_id (str): The sub-collection identifier (sometimes referred to as the "kind"). Returns: :class:`~google.cloud.firestore_v1.collection.CollectionReference`: The child collection. r:)rr> child_pathrrrr;s z BaseDocumentReference.collection document_datartimeoutcCs*|j}|||t||}||fSr-)rbatchcreatermake_retry_timeout_kwargs)rr@rrArBrrrr _prep_creates   z"BaseDocumentReference._prep_createcCtr-NotImplementedError)rr@rrArrrrCzBaseDocumentReference.createFmergecC.|j}|j|||dt||}||fS)N)rJ)rrBsetrrD)rr@rJrrArBrrrr _prep_set  zBaseDocumentReference._prep_setcCrFr-rG)rr@rJrrArrrrLzBaseDocumentReference.set field_updatesoptioncCrK)N)rQ)rrBupdaterrD)rrPrQrrArBrrrr _prep_updaterNz"BaseDocumentReference._prep_updatecCrFr-rG)rrPrQrrArrrrRrOzBaseDocumentReference.updatecCs4t|j|}|jj|gdd}t||}||fS)z+Shared setup for async/sync :meth:`delete`.N)databasewrites transaction)r pb_for_deleter7r_database_stringrD)rrQrrAwrite_pbrequestrrrr _prep_deletes z"BaseDocumentReference._prep_deletecCrFr-rG)rrQrrArrrdeleterIzBaseDocumentReference.delete field_pathscCs`t|tr td|durtjt|d}nd}|jj|jg|t |d}t ||}||fS)z(Shared setup for async/sync :meth:`get`.z8'field_paths' must be a sequence of paths, not a string.N)r])rT documentsmaskrV) r&strr5r DocumentMasksortedrrXr7rget_transaction_idrD)rr]rVrrAr_rZrrrr_prep_batch_gets  z%BaseDocumentReference._prep_batch_getDocumentSnapshotcCrFr-rG)rr]rVrrArrrget0rOzBaseDocumentReference.get page_sizecCs |j|d}t||}||fS)z0Shared setup for async/sync :meth:`collections`.)r=rg)r7rrD)rrgrrArZrrrr_prep_collections9s  z'BaseDocumentReference._prep_collectionscCrFr-rG)rrgrrArrr collectionsErIz!BaseDocumentReference.collectionscCrFr-rG)rcallbackrrr on_snapshotMsz!BaseDocumentReference.on_snapshotrN)NN)FNN)NNN)NNNN)+__name__ __module__ __qualname____doc__r rr"r$r*r0r2propertyrr7r9r=r`r r;dictretriesRetryfloatrrEr rCboolrMrLr WriteOptionrSrRr[r\r rdrfintrhrirkrrrrr sV                                rc@seZdZdZ  dddZddZdd Zed d Zed d Z eddZ eddZ de de fddZdeee e fdffddZdeefddZdS)reaA snapshot of document data in a Firestore database. This represents data retrieved at a specific time and may not contain all fields stored for the document (i.e. a hand-picked selection of fields may have been retrieved). Instances of this class are not intended to be constructed by hand, rather they'll be returned as responses to various methods, such as :meth:`~google.cloud.DocumentReference.get`. Args: reference (:class:`~google.cloud.firestore_v1.document.DocumentReference`): A document reference corresponding to the document that contains the data in this snapshot. data (Dict[str, Any]): The data retrieved in the snapshot. exists (bool): Indicates if the document existed at the time the snapshot was retrieved. read_time (:class:`proto.datetime_helpers.DatetimeWithNanoseconds`): The time that this snapshot was read from the server. create_time (:class:`proto.datetime_helpers.DatetimeWithNanoseconds`): The time that this document was created. update_time (:class:`proto.datetime_helpers.DatetimeWithNanoseconds`): The time that this document was last updated. rNcCs.||_t||_||_||_||_||_dSr-) _referencecopydeepcopy_data_exists read_time create_time update_time)r referencedataexistsr~rrrrrrms   zDocumentSnapshot.__init__cCs(t||jstS|j|jko|j|jkSr-)r&rr'ryr|r(rrrr*ys zDocumentSnapshot.__eq__cCr,r-)r.ryrr/rrrr0~r1zDocumentSnapshot.__hash__cC|jjS)zThe client that owns the document reference for this snapshot. Returns: :class:`~google.cloud.firestore_v1.client.Client`: The client that owns this document. )ryrr/rrrrszDocumentSnapshot._clientcC|jS)zExistence flag. Indicates if the document existed at the time this snapshot was retrieved. Returns: bool: The existence flag. )r}r/rrrrs zDocumentSnapshot.existscCr)zThe document identifier (within its collection). Returns: str: The last component of the path of the document. )ryr9r/rrrr9szDocumentSnapshot.idcCr)zDocument reference corresponding to document that owns this data. Returns: :class:`~google.cloud.firestore_v1.document.DocumentReference`: A document reference corresponding to this document. )ryr/rrrrszDocumentSnapshot.referencercCs"|jsdSt||j}t|S)aNGet a value from the snapshot data. If the data is nested, for example: .. code-block:: python >>> snapshot.to_dict() { 'top1': { 'middle2': { 'bottom3': 20, 'bottom4': 22, }, 'middle5': True, }, 'top6': b' foo', } a **field path** can be used to access the nested data. For example: .. code-block:: python >>> snapshot.get('top1') { 'middle2': { 'bottom3': 20, 'bottom4': 22, }, 'middle5': True, } >>> snapshot.get('top1.middle2') { 'bottom3': 20, 'bottom4': 22, } >>> snapshot.get('top1.middle2.bottom3') 20 See :meth:`~google.cloud.firestore_v1.client.Client.field_path` for more information on **field paths**. A copy is returned since the data may contain mutable values, but the data stored in the snapshot must remain immutable. Args: field_path (str): A field path (``.``-delimited list of field names). Returns: Any or None: (A copy of) the value stored for the ``field_path`` or None if snapshot document does not exist. Raises: KeyError: If the ``field_path`` does not match nested data in the snapshot. N)r}field_path_moduleget_nested_valuer|rzr{)rr nested_datarrrrfs; zDocumentSnapshot.getcCs|jsdSt|jS)a[Retrieve the data contained in this snapshot. A copy is returned since the data may contain mutable values, but the data stored in the snapshot must remain immutable. Returns: Dict[str, Any] or None: The data in the snapshot. Returns None if reference does not exist. N)r}rzr{r|r/rrrto_dicts  zDocumentSnapshot.to_dictcCs t|Sr-)rdocument_snapshot_to_protobufr/rrr _to_protobufs zDocumentSnapshot._to_protobufrl)rmrnrorprr*r0rqrrr9rr`r rfrr rr rrrrrrreQs$       @rerrcCs|jdf|}tj|S)aConvert a path tuple into a full path string. Of the form: ``projects/{project_id}/databases/{database_id}/... documents/{document_path}`` Args: client (:class:`~google.cloud.firestore_v1.client.Client`): The client that holds configuration details and a GAPIC client object. path (Tuple[str, ...]): The components in a document path. Returns: str: The fully-qualified document path. r^)rXrDOCUMENT_PATH_DELIMITERr4)rrpartsrrrr6s r6cCs(t|}t|dkrtd|d|dS)aBConsume a gRPC stream that should contain a single response. The stream will correspond to a ``BatchGetDocuments`` request made for a single document. Args: response_iterator (~google.cloud.exceptions.GrpcRendezvous): A streaming iterator returned from a ``BatchGetDocuments`` request. Returns: ~google.cloud.proto.firestore.v1. firestore.BatchGetDocumentsResponse: The single "get" response in the batch. Raises: ValueError: If anything other than exactly one response is returned. z4Unexpected response from `BatchGetDocumentsResponse`zExpected only one resultr)listlenr5)response_iterator all_responsesrrr_consume_single_gets r write_resultscCs|std|dS)aGet first write result from list. For cases where ``len(write_results) > 1``, this assumes the writes occurred at the same time (e.g. if an update and transform are sent at the same time). Args: write_results (List[google.cloud.proto.firestore.v1. write.WriteResult, ...]: The write results from a ``CommitResponse``. Returns: google.cloud.firestore_v1.types.WriteResult: The lone write result from ``write_results``. Raises: ValueError: If there are zero write results. This is likely to **never** occur, since the backend should be stable. z"Expected at least one write resultr)r5)rrrr_first_write_result1sr) rprzgoogle.api_corerrsgoogle.cloud.firestore_v1.typesrgoogle.cloud.firestore_v1rrrrrrtypingr r r r r rrobjectrrer`r6BatchGetDocumentsResponserr WriteResultrrrrrs$       $3-