U >i~4@sdZddlmZddlmZmZmZmZmZm Z ddl m Z m Z ddl m ZddlmZmZddlmZddlmZdd lmZmZmZmZmZmZmZmZerdd lm Z dd l!m"Z"dd l#m$Z$Gd ddej%eZ&GdddeZ'dddddZ(dS)zEHelpers for applying Google Cloud Firestore changes in a transaction.) annotations) TYPE_CHECKINGAnyAsyncGeneratorCallable CoroutineOptional) exceptionsgapic_v1) retry_async)_helpers async_batch)AsyncDocumentReference) AsyncQuery) _CANT_BEGIN _CANT_COMMIT_CANT_ROLLBACK_EXCEED_ATTEMPTS_TEMPLATE_WRITE_READ_ONLY MAX_ATTEMPTSBaseTransaction_BaseTransactional)AsyncStreamGenerator)DocumentSnapshot)ExplainOptionscseZdZdZedfddfdd Zdddfd d Zd"d dd ddZddddZddddZ e j j d fdddddddZ e j j d fd dddddddd d!ZZS)#AsyncTransactionaOAccumulate read-and-write operations to be sent in a transaction. Args: client (:class:`~google.cloud.firestore_v1.async_client.AsyncClient`): The client that created this transaction. max_attempts (Optional[int]): The maximum number of attempts for the transaction (i.e. allowing retries). Defaults to :attr:`~google.cloud.firestore_v1.transaction.MAX_ATTEMPTS`. read_only (Optional[bool]): Flag indicating if the transaction should be read-only or should allow writes. Defaults to :data:`False`. FNonereturncs"tt||t|||dSN)superr__init__r)selfclientZ max_attemptsZ read_only __class__O/tmp/pip-unpacked-wheel-599y42ri/google/cloud/firestore_v1/async_transaction.pyr!:szAsyncTransaction.__init__list) write_pbsrcs"|jrtttt||dS)a Add `Write`` protobufs to this transaction. Args: write_pbs (List[google.cloud.firestore_v1. write.Write]): A list of write protobufs to be added. Raises: ValueError: If this transaction is read-only. N) _read_only ValueErrorrr r_add_write_pbs)r"r)r$r&r'r,>s zAsyncTransaction._add_write_pbsNz bytes | None)retry_idrcsR|jrt|j}t||jjj|jj| |d|jj dIdH}|j |_dS)zBegin the transaction. Args: retry_id (Optional[bytes]): Transaction ID of a transaction to be retried. Raises: ValueError: If the current transaction has already begun. )databaseoptionsrequestmetadataN) in_progressrformat_idr+_client_firestore_apiZbegin_transaction_database_stringZ_options_protobuf _rpc_metadata transaction)r"r-msgZtransaction_responser&r&r'_beginMs   zAsyncTransaction._begincsJ|jsttz,|jjj|jj|jd|jj dIdHW5|XdS)zRoll back the transaction. Raises: ValueError: If no transaction is in progress. google.api_core.exceptions.GoogleAPICallError: If the rollback fails. )r.r:r0N) r3r+r _clean_upr6r7rollbackr8r5r9)r"r&r&r' _rollbackds zAsyncTransaction._rollbackcs\|jstt|jjj|jj|j|jd|jj dIdH}| t |j |_ |j |_ |j S)aTransactionally commit the changes accumulated. Returns: List[:class:`google.cloud.firestore_v1.write.WriteResult`, ...]: The write results corresponding to the changes committed, returned in the same order as the changes were applied to this transaction. A write result contains an ``update_time`` field. Raises: ValueError: If no transaction is in progress. )r.Zwritesr:r0N)r3r+rr6r7commitr8Z _write_pbsr5r9r=r(Z write_resultsZ commit_time)r"Zcommit_responser&r&r'_commit{s   zAsyncTransaction._commitz"retries.AsyncRetry | object | Nonez float | Nonez%AsyncGenerator[DocumentSnapshot, Any]) referencesretrytimeoutrcs*t||}|jj|fd|i|IdHS)atRetrieves multiple documents from Firestore. Args: references (List[.AsyncDocumentReference, ...]): Iterable of document references to be retrieved. 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. Yields: .DocumentSnapshot: The next document snapshot that fulfills the query, or :data:`None` if the document does not exist. r:N)r make_retry_timeout_kwargsr6get_all)r"rBrCrDkwargsr&r&r'rFs zAsyncTransaction.get_all)explain_optionsz#AsyncDocumentReference | AsyncQueryzOptional[float]zOptional[ExplainOptions]zNAsyncGenerator[DocumentSnapshot, Any] | AsyncStreamGenerator[DocumentSnapshot]) ref_or_queryrCrDrHrcst||}t|trF|dk r&td|jj|gfd|i|IdHSt|trt|dk r`||d<|jfd|i|StddS)a Retrieve a document or a query result from the database. Args: ref_or_query (AsyncDocumentReference | AsyncQuery): The document references or query object to return. 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. Can only be used when running a query, not a document reference. Yields: DocumentSnapshot: The next document snapshot that fulfills the query, or :data:`None` if the document does not exist. Raises: ValueError: if `ref_or_query` is not one of the supported types, or explain_options is provided when `ref_or_query` is a document reference. Nz^When type of `ref_or_query` is `AsyncDocumentReference`, `explain_options` cannot be provided.r:rHzSValue for argument "ref_or_query" must be a AsyncDocumentReference or a AsyncQuery.) r rE isinstancerr+r6rFrstream)r"rIrCrDrHrGr&r&r'gets(!    zAsyncTransaction.get)N)__name__ __module__ __qualname____doc__rr!r,r<r?rAr methodDEFAULTrFrL __classcell__r&r&r$r'r,s  rcs>eZdZdZddfdd Zdddd d Zd d ZZS) _AsyncTransactionalalProvide a callable object to use as a transactional decorater. This is surfaced via :func:`~google.cloud.firestore_v1.async_transaction.transactional`. Args: to_wrap (Coroutine[[:class:`~google.cloud.firestore_v1.async_transaction.AsyncTransaction`, ...], Any]): A coroutine that should be run (and retried) in a transaction. rrcstt||dSr)r rTr!)r"to_wrapr$r&r'r!sz_AsyncTransactional.__init__rr)r:rcsN||j|jdIdH|j|_|jdkr6|j|_|j|f||IdHS)a}Begin transaction and call the wrapped coroutine. Args: transaction (:class:`~google.cloud.firestore_v1.async_transaction.AsyncTransaction`): A transaction to execute the coroutine within. args (Tuple[Any, ...]): The extra positional arguments to pass along to the wrapped coroutine. kwargs (Dict[str, Any]): The extra keyword arguments to pass along to the wrapped coroutine. Returns: Any: result of the wrapped coroutine. Raises: Exception: Any failure caused by ``to_wrap``. )r-N)r=r<r-r5Z current_idrU)r"r:argsrGr&r&r' _pre_commits  z_AsyncTransactional._pre_commitc s||jstjnd}d}zt|jD]^}|j|f||IdH}z|IdH|WWS|k r}z|}W5d}~XYq(Xq(t |j} t | |Wn$t k r| IdHYnXdS)aExecute the wrapped callable within a transaction. Args: transaction (:class:`~google.cloud.firestore_v1.transaction.Transaction`): A transaction to execute the callable within. args (Tuple[Any, ...]): The extra positional arguments to pass along to the wrapped callable. kwargs (Dict[str, Any]): The extra keyword arguments to pass along to the wrapped callable. Returns: Any: The result of the wrapped callable. Raises: ValueError: If the transaction does not succeed in ``max_attempts``. r&N) Z_resetr*r ZAbortedrangeZ _max_attemptsrWrArr4r+ BaseExceptionr?) r"r:rVrGZretryable_exceptionslast_excattemptresultexcr;r&r&r'__call__s"  z_AsyncTransactional.__call__)rMrNrOrPr!rWr^rSr&r&r$r'rTs rTz!Callable[[AsyncTransaction], Any])rUrcCst|S)aDecorate a callable so that it runs in a transaction. Args: to_wrap (Callable[[:class:`~google.cloud.firestore_v1.transaction.Transaction`, ...], Any]): A callable that should be run (and retried) in a transaction. Returns: Callable[[:class:`~google.cloud.firestore_v1.transaction.Transaction`, ...], Any]: the wrapped callable. )rT)rUr&r&r'async_transactionalCsr_N))rP __future__rtypingrrrrrrZgoogle.api_corer r r retriesZgoogle.cloud.firestore_v1r r Z(google.cloud.firestore_v1.async_documentrZ%google.cloud.firestore_v1.async_queryrZ*google.cloud.firestore_v1.base_transactionrrrrrrrrZ0google.cloud.firestore_v1.async_stream_generatorrZ'google.cloud.firestore_v1.base_documentrZ'google.cloud.firestore_v1.query_profilerZAsyncWriteBatchrrTr_r&r&r&r's      (    9_