Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/google/cloud/firestore_v1/services/firestore/async

1# -*- coding: utf-8 -*-

4# Licensed under the Apache License, Version 2.0 (the "License");

5# you may not use this file except in compliance with the License.

6# You may obtain a copy of the License at

8# http://www.apache.org/licenses/LICENSE-2.0

10# Unless required by applicable law or agreed to in writing, software

11# distributed under the License is distributed on an "AS IS" BASIS,

12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

13# See the License for the specific language governing permissions and

14# limitations under the License.

15#

16import logging as std_logging

17from collections import OrderedDict

18import re

19from typing import (

20 Dict,

21 Callable,

22 Mapping,

23 MutableMapping,

24 MutableSequence,

25 Optional,

26 AsyncIterable,

27 Awaitable,

28 AsyncIterator,

29 Sequence,

30 Tuple,

31 Type,

32 Union,

33)

35from google.cloud.firestore_v1 import gapic_version as package_version

37from google.api_core.client_options import ClientOptions

38from google.api_core import exceptions as core_exceptions

39from google.api_core import gapic_v1

40from google.api_core import retry_async as retries

41from google.auth import credentials as ga_credentials # type: ignore

42from google.oauth2 import service_account # type: ignore

43import google.protobuf

46try:

47 OptionalRetry = Union[retries.AsyncRetry, gapic_v1.method._MethodDefault, None]

48except AttributeError: # pragma: NO COVER

49 OptionalRetry = Union[retries.AsyncRetry, object, None] # type: ignore

51from google.cloud.firestore_v1.services.firestore import pagers

52from google.cloud.firestore_v1.types import aggregation_result

53from google.cloud.firestore_v1.types import common

54from google.cloud.firestore_v1.types import document

55from google.cloud.firestore_v1.types import document as gf_document

56from google.cloud.firestore_v1.types import firestore

57from google.cloud.firestore_v1.types import query

58from google.cloud.firestore_v1.types import query_profile

59from google.cloud.firestore_v1.types import write as gf_write

60from google.cloud.location import locations_pb2 # type: ignore

61from google.longrunning import operations_pb2 # type: ignore

62from google.protobuf import timestamp_pb2 # type: ignore

63from google.rpc import status_pb2 # type: ignore

64from .transports.base import FirestoreTransport, DEFAULT_CLIENT_INFO

65from .transports.grpc_asyncio import FirestoreGrpcAsyncIOTransport

66from .client import FirestoreClient

68try:

69 from google.api_core import client_logging # type: ignore

71 CLIENT_LOGGING_SUPPORTED = True # pragma: NO COVER

72except ImportError: # pragma: NO COVER

73 CLIENT_LOGGING_SUPPORTED = False

75_LOGGER = std_logging.getLogger(__name__)

78class FirestoreAsyncClient:

79 """The Cloud Firestore service.

81 Cloud Firestore is a fast, fully managed, serverless,

82 cloud-native NoSQL document database that simplifies storing,

83 syncing, and querying data for your mobile, web, and IoT apps at

84 global scale. Its client libraries provide live synchronization

85 and offline support, while its security features and

86 integrations with Firebase and Google Cloud Platform accelerate

87 building truly serverless apps.

88 """

90 _client: FirestoreClient

92 # Copy defaults from the synchronous client for use here.

93 # Note: DEFAULT_ENDPOINT is deprecated. Use _DEFAULT_ENDPOINT_TEMPLATE instead.

94 DEFAULT_ENDPOINT = FirestoreClient.DEFAULT_ENDPOINT

95 DEFAULT_MTLS_ENDPOINT = FirestoreClient.DEFAULT_MTLS_ENDPOINT

96 _DEFAULT_ENDPOINT_TEMPLATE = FirestoreClient._DEFAULT_ENDPOINT_TEMPLATE

97 _DEFAULT_UNIVERSE = FirestoreClient._DEFAULT_UNIVERSE

99 common_billing_account_path = staticmethod(

100 FirestoreClient.common_billing_account_path

101 )

102 parse_common_billing_account_path = staticmethod(

103 FirestoreClient.parse_common_billing_account_path

104 )

105 common_folder_path = staticmethod(FirestoreClient.common_folder_path)

106 parse_common_folder_path = staticmethod(FirestoreClient.parse_common_folder_path)

107 common_organization_path = staticmethod(FirestoreClient.common_organization_path)

108 parse_common_organization_path = staticmethod(

109 FirestoreClient.parse_common_organization_path

110 )

111 common_project_path = staticmethod(FirestoreClient.common_project_path)

112 parse_common_project_path = staticmethod(FirestoreClient.parse_common_project_path)

113 common_location_path = staticmethod(FirestoreClient.common_location_path)

114 parse_common_location_path = staticmethod(

115 FirestoreClient.parse_common_location_path

116 )

117

118 @classmethod

119 def from_service_account_info(cls, info: dict, *args, **kwargs):

120 """Creates an instance of this client using the provided credentials

121 info.

122

123 Args:

124 info (dict): The service account private key info.

125 args: Additional arguments to pass to the constructor.

126 kwargs: Additional arguments to pass to the constructor.

127

128 Returns:

129 FirestoreAsyncClient: The constructed client.

130 """

131 return FirestoreClient.from_service_account_info.__func__(FirestoreAsyncClient, info, *args, **kwargs) # type: ignore

132

133 @classmethod

134 def from_service_account_file(cls, filename: str, *args, **kwargs):

135 """Creates an instance of this client using the provided credentials

136 file.

137

138 Args:

139 filename (str): The path to the service account private key json

140 file.

141 args: Additional arguments to pass to the constructor.

142 kwargs: Additional arguments to pass to the constructor.

143

144 Returns:

145 FirestoreAsyncClient: The constructed client.

146 """

147 return FirestoreClient.from_service_account_file.__func__(FirestoreAsyncClient, filename, *args, **kwargs) # type: ignore

148

149 from_service_account_json = from_service_account_file

150

151 @classmethod

152 def get_mtls_endpoint_and_cert_source(

153 cls, client_options: Optional[ClientOptions] = None

154 ):

155 """Return the API endpoint and client cert source for mutual TLS.

156

157 The client cert source is determined in the following order:

158 (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the

159 client cert source is None.

160 (2) if `client_options.client_cert_source` is provided, use the provided one; if the

161 default client cert source exists, use the default one; otherwise the client cert

162 source is None.

163

164 The API endpoint is determined in the following order:

165 (1) if `client_options.api_endpoint` if provided, use the provided one.

166 (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the

167 default mTLS endpoint; if the environment variable is "never", use the default API

168 endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise

169 use the default API endpoint.

170

171 More details can be found at https://google.aip.dev/auth/4114.

172

173 Args:

174 client_options (google.api_core.client_options.ClientOptions): Custom options for the

175 client. Only the `api_endpoint` and `client_cert_source` properties may be used

176 in this method.

177

178 Returns:

179 Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the

180 client cert source to use.

181

182 Raises:

183 google.auth.exceptions.MutualTLSChannelError: If any errors happen.

184 """

185 return FirestoreClient.get_mtls_endpoint_and_cert_source(client_options) # type: ignore

186

187 @property

188 def transport(self) -> FirestoreTransport:

189 """Returns the transport used by the client instance.

190

191 Returns:

192 FirestoreTransport: The transport used by the client instance.

193 """

194 return self._client.transport

195

196 @property

197 def api_endpoint(self):

198 """Return the API endpoint used by the client instance.

199

200 Returns:

201 str: The API endpoint used by the client instance.

202 """

203 return self._client._api_endpoint

204

205 @property

206 def universe_domain(self) -> str:

207 """Return the universe domain used by the client instance.

208

209 Returns:

210 str: The universe domain used

211 by the client instance.

212 """

213 return self._client._universe_domain

214

215 get_transport_class = FirestoreClient.get_transport_class

216

217 def __init__(

218 self,

219 *,

220 credentials: Optional[ga_credentials.Credentials] = None,

221 transport: Optional[

222 Union[str, FirestoreTransport, Callable[..., FirestoreTransport]]

223 ] = "grpc_asyncio",

224 client_options: Optional[ClientOptions] = None,

225 client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,

226 ) -> None:

227 """Instantiates the firestore async client.

228

229 Args:

230 credentials (Optional[google.auth.credentials.Credentials]): The

231 authorization credentials to attach to requests. These

232 credentials identify the application to the service; if none

233 are specified, the client will attempt to ascertain the

234 credentials from the environment.

235 transport (Optional[Union[str,FirestoreTransport,Callable[..., FirestoreTransport]]]):

236 The transport to use, or a Callable that constructs and returns a new transport to use.

237 If a Callable is given, it will be called with the same set of initialization

238 arguments as used in the FirestoreTransport constructor.

239 If set to None, a transport is chosen automatically.

240 client_options (Optional[Union[google.api_core.client_options.ClientOptions, dict]]):

241 Custom options for the client.

242

243 1. The ``api_endpoint`` property can be used to override the

244 default endpoint provided by the client when ``transport`` is

245 not explicitly provided. Only if this property is not set and

246 ``transport`` was not explicitly provided, the endpoint is

247 determined by the GOOGLE_API_USE_MTLS_ENDPOINT environment

248 variable, which have one of the following values:

249 "always" (always use the default mTLS endpoint), "never" (always

250 use the default regular endpoint) and "auto" (auto-switch to the

251 default mTLS endpoint if client certificate is present; this is

252 the default value).

253

254 2. If the GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable

255 is "true", then the ``client_cert_source`` property can be used

256 to provide a client certificate for mTLS transport. If

257 not provided, the default SSL client certificate will be used if

258 present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not

259 set, no client certificate will be used.

260

261 3. The ``universe_domain`` property can be used to override the

262 default "googleapis.com" universe. Note that ``api_endpoint``

263 property still takes precedence; and ``universe_domain`` is

264 currently not supported for mTLS.

265

266 client_info (google.api_core.gapic_v1.client_info.ClientInfo):

267 The client info used to send a user-agent string along with

268 API requests. If ``None``, then default info will be used.

269 Generally, you only need to set this if you're developing

270 your own client library.

271

272 Raises:

273 google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport

274 creation failed for any reason.

275 """

276 self._client = FirestoreClient(

277 credentials=credentials,

278 transport=transport,

279 client_options=client_options,

280 client_info=client_info,

281 )

282

283 if CLIENT_LOGGING_SUPPORTED and _LOGGER.isEnabledFor(

284 std_logging.DEBUG

285 ): # pragma: NO COVER

286 _LOGGER.debug(

287 "Created client `google.firestore_v1.FirestoreAsyncClient`.",

288 extra={

289 "serviceName": "google.firestore.v1.Firestore",

290 "universeDomain": getattr(

291 self._client._transport._credentials, "universe_domain", ""

292 ),

293 "credentialsType": f"{type(self._client._transport._credentials).__module__}.{type(self._client._transport._credentials).__qualname__}",

294 "credentialsInfo": getattr(

295 self.transport._credentials, "get_cred_info", lambda: None

296 )(),

297 }

298 if hasattr(self._client._transport, "_credentials")

299 else {

300 "serviceName": "google.firestore.v1.Firestore",

301 "credentialsType": None,

302 },

303 )

304

305 async def get_document(

306 self,

307 request: Optional[Union[firestore.GetDocumentRequest, dict]] = None,

308 *,

309 retry: OptionalRetry = gapic_v1.method.DEFAULT,

310 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

311 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

312 ) -> document.Document:

313 r"""Gets a single document.

314

315 .. code-block:: python

316

317 # This snippet has been automatically generated and should be regarded as a

318 # code template only.

319 # It will require modifications to work:

320 # - It may require correct/in-range values for request initialization.

321 # - It may require specifying regional endpoints when creating the service

322 # client as shown in:

323 # https://googleapis.dev/python/google-api-core/latest/client_options.html

324 from google.cloud import firestore_v1

325

326 async def sample_get_document():

327 # Create a client

328 client = firestore_v1.FirestoreAsyncClient()

329

330 # Initialize request argument(s)

331 request = firestore_v1.GetDocumentRequest(

332 transaction=b'transaction_blob',

333 name="name_value",

334 )

335

336 # Make the request

337 response = await client.get_document(request=request)

338

339 # Handle the response

340 print(response)

341

342 Args:

343 request (Optional[Union[google.cloud.firestore_v1.types.GetDocumentRequest, dict]]):

344 The request object. The request for

345 [Firestore.GetDocument][google.firestore.v1.Firestore.GetDocument].

346 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

347 should be retried.

348 timeout (float): The timeout for this request.

349 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

350 sent along with the request as metadata. Normally, each value must be of type `str`,

351 but for metadata keys ending with the suffix `-bin`, the corresponding values must

352 be of type `bytes`.

353

354 Returns:

355 google.cloud.firestore_v1.types.Document:

356 A Firestore document.

357

358 Must not exceed 1 MiB - 4 bytes.

359

360 """

361 # Create or coerce a protobuf request object.

362 # - Use the request object if provided (there's no risk of modifying the input as

363 # there are no flattened fields), or create one.

364 if not isinstance(request, firestore.GetDocumentRequest):

365 request = firestore.GetDocumentRequest(request)

366

367 # Wrap the RPC method; this adds retry and timeout information,

368 # and friendly error handling.

369 rpc = self._client._transport._wrapped_methods[

370 self._client._transport.get_document

371 ]

372

373 # Certain fields should be provided within the metadata header;

374 # add these here.

375 metadata = tuple(metadata) + (

376 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),

377 )

378

379 # Validate the universe domain.

380 self._client._validate_universe_domain()

381

382 # Send the request.

383 response = await rpc(

384 request,

385 retry=retry,

386 timeout=timeout,

387 metadata=metadata,

388 )

389

390 # Done; return the response.

391 return response

392

393 async def list_documents(

394 self,

395 request: Optional[Union[firestore.ListDocumentsRequest, dict]] = None,

396 *,

397 retry: OptionalRetry = gapic_v1.method.DEFAULT,

398 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

399 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

400 ) -> pagers.ListDocumentsAsyncPager:

401 r"""Lists documents.

402

403 .. code-block:: python

404

405 # This snippet has been automatically generated and should be regarded as a

406 # code template only.

407 # It will require modifications to work:

408 # - It may require correct/in-range values for request initialization.

409 # - It may require specifying regional endpoints when creating the service

410 # client as shown in:

411 # https://googleapis.dev/python/google-api-core/latest/client_options.html

412 from google.cloud import firestore_v1

413

414 async def sample_list_documents():

415 # Create a client

416 client = firestore_v1.FirestoreAsyncClient()

417

418 # Initialize request argument(s)

419 request = firestore_v1.ListDocumentsRequest(

420 transaction=b'transaction_blob',

421 parent="parent_value",

422 )

423

424 # Make the request

425 page_result = client.list_documents(request=request)

426

427 # Handle the response

428 async for response in page_result:

429 print(response)

430

431 Args:

432 request (Optional[Union[google.cloud.firestore_v1.types.ListDocumentsRequest, dict]]):

433 The request object. The request for

434 [Firestore.ListDocuments][google.firestore.v1.Firestore.ListDocuments].

435 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

436 should be retried.

437 timeout (float): The timeout for this request.

438 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

439 sent along with the request as metadata. Normally, each value must be of type `str`,

440 but for metadata keys ending with the suffix `-bin`, the corresponding values must

441 be of type `bytes`.

442

443 Returns:

444 google.cloud.firestore_v1.services.firestore.pagers.ListDocumentsAsyncPager:

445 The response for

446 [Firestore.ListDocuments][google.firestore.v1.Firestore.ListDocuments].

447

448 Iterating over this object will yield results and

449 resolve additional pages automatically.

450

451 """

452 # Create or coerce a protobuf request object.

453 # - Use the request object if provided (there's no risk of modifying the input as

454 # there are no flattened fields), or create one.

455 if not isinstance(request, firestore.ListDocumentsRequest):

456 request = firestore.ListDocumentsRequest(request)

457

458 # Wrap the RPC method; this adds retry and timeout information,

459 # and friendly error handling.

460 rpc = self._client._transport._wrapped_methods[

461 self._client._transport.list_documents

462 ]

463

464 # Certain fields should be provided within the metadata header;

465 # add these here.

466 metadata = tuple(metadata) + (

467 gapic_v1.routing_header.to_grpc_metadata(

468 (

469 ("parent", request.parent),

470 ("collection_id", request.collection_id),

471 )

472 ),

473 )

474

475 # Validate the universe domain.

476 self._client._validate_universe_domain()

477

478 # Send the request.

479 response = await rpc(

480 request,

481 retry=retry,

482 timeout=timeout,

483 metadata=metadata,

484 )

485

486 # This method is paged; wrap the response in a pager, which provides

487 # an `__aiter__` convenience method.

488 response = pagers.ListDocumentsAsyncPager(

489 method=rpc,

490 request=request,

491 response=response,

492 retry=retry,

493 timeout=timeout,

494 metadata=metadata,

495 )

496

497 # Done; return the response.

498 return response

499

500 async def update_document(

501 self,

502 request: Optional[Union[firestore.UpdateDocumentRequest, dict]] = None,

503 *,

504 document: Optional[gf_document.Document] = None,

505 update_mask: Optional[common.DocumentMask] = None,

506 retry: OptionalRetry = gapic_v1.method.DEFAULT,

507 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

508 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

509 ) -> gf_document.Document:

510 r"""Updates or inserts a document.

511

512 .. code-block:: python

513

514 # This snippet has been automatically generated and should be regarded as a

515 # code template only.

516 # It will require modifications to work:

517 # - It may require correct/in-range values for request initialization.

518 # - It may require specifying regional endpoints when creating the service

519 # client as shown in:

520 # https://googleapis.dev/python/google-api-core/latest/client_options.html

521 from google.cloud import firestore_v1

522

523 async def sample_update_document():

524 # Create a client

525 client = firestore_v1.FirestoreAsyncClient()

526

527 # Initialize request argument(s)

528 request = firestore_v1.UpdateDocumentRequest(

529 )

530

531 # Make the request

532 response = await client.update_document(request=request)

533

534 # Handle the response

535 print(response)

536

537 Args:

538 request (Optional[Union[google.cloud.firestore_v1.types.UpdateDocumentRequest, dict]]):

539 The request object. The request for

540 [Firestore.UpdateDocument][google.firestore.v1.Firestore.UpdateDocument].

541 document (:class:`google.cloud.firestore_v1.types.Document`):

542 Required. The updated document.

543 Creates the document if it does not

544 already exist.

545

546 This corresponds to the ``document`` field

547 on the ``request`` instance; if ``request`` is provided, this

548 should not be set.

549 update_mask (:class:`google.cloud.firestore_v1.types.DocumentMask`):

550 The fields to update.

551 None of the field paths in the mask may

552 contain a reserved name.

553

554 If the document exists on the server and

555 has fields not referenced in the mask,

556 they are left unchanged.

557 Fields referenced in the mask, but not

558 present in the input document, are

559 deleted from the document on the server.

560

561 This corresponds to the ``update_mask`` field

562 on the ``request`` instance; if ``request`` is provided, this

563 should not be set.

564 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

565 should be retried.

566 timeout (float): The timeout for this request.

567 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

568 sent along with the request as metadata. Normally, each value must be of type `str`,

569 but for metadata keys ending with the suffix `-bin`, the corresponding values must

570 be of type `bytes`.

571

572 Returns:

573 google.cloud.firestore_v1.types.Document:

574 A Firestore document.

575

576 Must not exceed 1 MiB - 4 bytes.

577

578 """

579 # Create or coerce a protobuf request object.

580 # - Quick check: If we got a request object, we should *not* have

581 # gotten any keyword arguments that map to the request.

582 flattened_params = [document, update_mask]

583 has_flattened_params = (

584 len([param for param in flattened_params if param is not None]) > 0

585 )

586 if request is not None and has_flattened_params:

587 raise ValueError(

588 "If the `request` argument is set, then none of "

589 "the individual field arguments should be set."

590 )

591

592 # - Use the request object if provided (there's no risk of modifying the input as

593 # there are no flattened fields), or create one.

594 if not isinstance(request, firestore.UpdateDocumentRequest):

595 request = firestore.UpdateDocumentRequest(request)

596

597 # If we have keyword arguments corresponding to fields on the

598 # request, apply these.

599 if document is not None:

600 request.document = document

601 if update_mask is not None:

602 request.update_mask = update_mask

603

604 # Wrap the RPC method; this adds retry and timeout information,

605 # and friendly error handling.

606 rpc = self._client._transport._wrapped_methods[

607 self._client._transport.update_document

608 ]

609

610 # Certain fields should be provided within the metadata header;

611 # add these here.

612 metadata = tuple(metadata) + (

613 gapic_v1.routing_header.to_grpc_metadata(

614 (("document.name", request.document.name),)

615 ),

616 )

617

618 # Validate the universe domain.

619 self._client._validate_universe_domain()

620

621 # Send the request.

622 response = await rpc(

623 request,

624 retry=retry,

625 timeout=timeout,

626 metadata=metadata,

627 )

628

629 # Done; return the response.

630 return response

631

632 async def delete_document(

633 self,

634 request: Optional[Union[firestore.DeleteDocumentRequest, dict]] = None,

635 *,

636 name: Optional[str] = None,

637 retry: OptionalRetry = gapic_v1.method.DEFAULT,

638 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

639 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

640 ) -> None:

641 r"""Deletes a document.

642

643 .. code-block:: python

644

645 # This snippet has been automatically generated and should be regarded as a

646 # code template only.

647 # It will require modifications to work:

648 # - It may require correct/in-range values for request initialization.

649 # - It may require specifying regional endpoints when creating the service

650 # client as shown in:

651 # https://googleapis.dev/python/google-api-core/latest/client_options.html

652 from google.cloud import firestore_v1

653

654 async def sample_delete_document():

655 # Create a client

656 client = firestore_v1.FirestoreAsyncClient()

657

658 # Initialize request argument(s)

659 request = firestore_v1.DeleteDocumentRequest(

660 name="name_value",

661 )

662

663 # Make the request

664 await client.delete_document(request=request)

665

666 Args:

667 request (Optional[Union[google.cloud.firestore_v1.types.DeleteDocumentRequest, dict]]):

668 The request object. The request for

669 [Firestore.DeleteDocument][google.firestore.v1.Firestore.DeleteDocument].

670 name (:class:`str`):

671 Required. The resource name of the Document to delete.

672 In the format:

673 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.

674

675 This corresponds to the ``name`` field

676 on the ``request`` instance; if ``request`` is provided, this

677 should not be set.

678 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

679 should be retried.

680 timeout (float): The timeout for this request.

681 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

682 sent along with the request as metadata. Normally, each value must be of type `str`,

683 but for metadata keys ending with the suffix `-bin`, the corresponding values must

684 be of type `bytes`.

685 """

686 # Create or coerce a protobuf request object.

687 # - Quick check: If we got a request object, we should *not* have

688 # gotten any keyword arguments that map to the request.

689 flattened_params = [name]

690 has_flattened_params = (

691 len([param for param in flattened_params if param is not None]) > 0

692 )

693 if request is not None and has_flattened_params:

694 raise ValueError(

695 "If the `request` argument is set, then none of "

696 "the individual field arguments should be set."

697 )

698

699 # - Use the request object if provided (there's no risk of modifying the input as

700 # there are no flattened fields), or create one.

701 if not isinstance(request, firestore.DeleteDocumentRequest):

702 request = firestore.DeleteDocumentRequest(request)

703

704 # If we have keyword arguments corresponding to fields on the

705 # request, apply these.

706 if name is not None:

707 request.name = name

708

709 # Wrap the RPC method; this adds retry and timeout information,

710 # and friendly error handling.

711 rpc = self._client._transport._wrapped_methods[

712 self._client._transport.delete_document

713 ]

714

715 # Certain fields should be provided within the metadata header;

716 # add these here.

717 metadata = tuple(metadata) + (

718 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),

719 )

720

721 # Validate the universe domain.

722 self._client._validate_universe_domain()

723

724 # Send the request.

725 await rpc(

726 request,

727 retry=retry,

728 timeout=timeout,

729 metadata=metadata,

730 )

731

732 def batch_get_documents(

733 self,

734 request: Optional[Union[firestore.BatchGetDocumentsRequest, dict]] = None,

735 *,

736 retry: OptionalRetry = gapic_v1.method.DEFAULT,

737 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

738 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

739 ) -> Awaitable[AsyncIterable[firestore.BatchGetDocumentsResponse]]:

740 r"""Gets multiple documents.

741

742 Documents returned by this method are not guaranteed to

743 be returned in the same order that they were requested.

744

745 .. code-block:: python

746

747 # This snippet has been automatically generated and should be regarded as a

748 # code template only.

749 # It will require modifications to work:

750 # - It may require correct/in-range values for request initialization.

751 # - It may require specifying regional endpoints when creating the service

752 # client as shown in:

753 # https://googleapis.dev/python/google-api-core/latest/client_options.html

754 from google.cloud import firestore_v1

755

756 async def sample_batch_get_documents():

757 # Create a client

758 client = firestore_v1.FirestoreAsyncClient()

759

760 # Initialize request argument(s)

761 request = firestore_v1.BatchGetDocumentsRequest(

762 transaction=b'transaction_blob',

763 database="database_value",

764 )

765

766 # Make the request

767 stream = await client.batch_get_documents(request=request)

768

769 # Handle the response

770 async for response in stream:

771 print(response)

772

773 Args:

774 request (Optional[Union[google.cloud.firestore_v1.types.BatchGetDocumentsRequest, dict]]):

775 The request object. The request for

776 [Firestore.BatchGetDocuments][google.firestore.v1.Firestore.BatchGetDocuments].

777 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

778 should be retried.

779 timeout (float): The timeout for this request.

780 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

781 sent along with the request as metadata. Normally, each value must be of type `str`,

782 but for metadata keys ending with the suffix `-bin`, the corresponding values must

783 be of type `bytes`.

784

785 Returns:

786 AsyncIterable[google.cloud.firestore_v1.types.BatchGetDocumentsResponse]:

787 The streamed response for

788 [Firestore.BatchGetDocuments][google.firestore.v1.Firestore.BatchGetDocuments].

789

790 """

791 # Create or coerce a protobuf request object.

792 # - Use the request object if provided (there's no risk of modifying the input as

793 # there are no flattened fields), or create one.

794 if not isinstance(request, firestore.BatchGetDocumentsRequest):

795 request = firestore.BatchGetDocumentsRequest(request)

796

797 # Wrap the RPC method; this adds retry and timeout information,

798 # and friendly error handling.

799 rpc = self._client._transport._wrapped_methods[

800 self._client._transport.batch_get_documents

801 ]

802

803 # Certain fields should be provided within the metadata header;

804 # add these here.

805 metadata = tuple(metadata) + (

806 gapic_v1.routing_header.to_grpc_metadata((("database", request.database),)),

807 )

808

809 # Validate the universe domain.

810 self._client._validate_universe_domain()

811

812 # Send the request.

813 response = rpc(

814 request,

815 retry=retry,

816 timeout=timeout,

817 metadata=metadata,

818 )

819

820 # Done; return the response.

821 return response

822

823 async def begin_transaction(

824 self,

825 request: Optional[Union[firestore.BeginTransactionRequest, dict]] = None,

826 *,

827 database: Optional[str] = None,

828 retry: OptionalRetry = gapic_v1.method.DEFAULT,

829 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

830 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

831 ) -> firestore.BeginTransactionResponse:

832 r"""Starts a new transaction.

833

834 .. code-block:: python

835

836 # This snippet has been automatically generated and should be regarded as a

837 # code template only.

838 # It will require modifications to work:

839 # - It may require correct/in-range values for request initialization.

840 # - It may require specifying regional endpoints when creating the service

841 # client as shown in:

842 # https://googleapis.dev/python/google-api-core/latest/client_options.html

843 from google.cloud import firestore_v1

844

845 async def sample_begin_transaction():

846 # Create a client

847 client = firestore_v1.FirestoreAsyncClient()

848

849 # Initialize request argument(s)

850 request = firestore_v1.BeginTransactionRequest(

851 database="database_value",

852 )

853

854 # Make the request

855 response = await client.begin_transaction(request=request)

856

857 # Handle the response

858 print(response)

859

860 Args:

861 request (Optional[Union[google.cloud.firestore_v1.types.BeginTransactionRequest, dict]]):

862 The request object. The request for

863 [Firestore.BeginTransaction][google.firestore.v1.Firestore.BeginTransaction].

864 database (:class:`str`):

865 Required. The database name. In the format:

866 ``projects/{project_id}/databases/{database_id}``.

867

868 This corresponds to the ``database`` field

869 on the ``request`` instance; if ``request`` is provided, this

870 should not be set.

871 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

872 should be retried.

873 timeout (float): The timeout for this request.

874 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

875 sent along with the request as metadata. Normally, each value must be of type `str`,

876 but for metadata keys ending with the suffix `-bin`, the corresponding values must

877 be of type `bytes`.

878

879 Returns:

880 google.cloud.firestore_v1.types.BeginTransactionResponse:

881 The response for

882 [Firestore.BeginTransaction][google.firestore.v1.Firestore.BeginTransaction].

883

884 """

885 # Create or coerce a protobuf request object.

886 # - Quick check: If we got a request object, we should *not* have

887 # gotten any keyword arguments that map to the request.

888 flattened_params = [database]

889 has_flattened_params = (

890 len([param for param in flattened_params if param is not None]) > 0

891 )

892 if request is not None and has_flattened_params:

893 raise ValueError(

894 "If the `request` argument is set, then none of "

895 "the individual field arguments should be set."

896 )

897

898 # - Use the request object if provided (there's no risk of modifying the input as

899 # there are no flattened fields), or create one.

900 if not isinstance(request, firestore.BeginTransactionRequest):

901 request = firestore.BeginTransactionRequest(request)

902

903 # If we have keyword arguments corresponding to fields on the

904 # request, apply these.

905 if database is not None:

906 request.database = database

907

908 # Wrap the RPC method; this adds retry and timeout information,

909 # and friendly error handling.

910 rpc = self._client._transport._wrapped_methods[

911 self._client._transport.begin_transaction

912 ]

913

914 # Certain fields should be provided within the metadata header;

915 # add these here.

916 metadata = tuple(metadata) + (

917 gapic_v1.routing_header.to_grpc_metadata((("database", request.database),)),

918 )

919

920 # Validate the universe domain.

921 self._client._validate_universe_domain()

922

923 # Send the request.

924 response = await rpc(

925 request,

926 retry=retry,

927 timeout=timeout,

928 metadata=metadata,

929 )

930

931 # Done; return the response.

932 return response

933

934 async def commit(

935 self,

936 request: Optional[Union[firestore.CommitRequest, dict]] = None,

937 *,

938 database: Optional[str] = None,

939 writes: Optional[MutableSequence[gf_write.Write]] = None,

940 retry: OptionalRetry = gapic_v1.method.DEFAULT,

941 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

942 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

943 ) -> firestore.CommitResponse:

944 r"""Commits a transaction, while optionally updating

945 documents.

946

947 .. code-block:: python

948

949 # This snippet has been automatically generated and should be regarded as a

950 # code template only.

951 # It will require modifications to work:

952 # - It may require correct/in-range values for request initialization.

953 # - It may require specifying regional endpoints when creating the service

954 # client as shown in:

955 # https://googleapis.dev/python/google-api-core/latest/client_options.html

956 from google.cloud import firestore_v1

957

958 async def sample_commit():

959 # Create a client

960 client = firestore_v1.FirestoreAsyncClient()

961

962 # Initialize request argument(s)

963 request = firestore_v1.CommitRequest(

964 database="database_value",

965 )

966

967 # Make the request

968 response = await client.commit(request=request)

969

970 # Handle the response

971 print(response)

972

973 Args:

974 request (Optional[Union[google.cloud.firestore_v1.types.CommitRequest, dict]]):

975 The request object. The request for

976 [Firestore.Commit][google.firestore.v1.Firestore.Commit].

977 database (:class:`str`):

978 Required. The database name. In the format:

979 ``projects/{project_id}/databases/{database_id}``.

980

981 This corresponds to the ``database`` field

982 on the ``request`` instance; if ``request`` is provided, this

983 should not be set.

984 writes (:class:`MutableSequence[google.cloud.firestore_v1.types.Write]`):

985 The writes to apply.

986

987 Always executed atomically and in order.

988

989 This corresponds to the ``writes`` field

990 on the ``request`` instance; if ``request`` is provided, this

991 should not be set.

992 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

993 should be retried.

994 timeout (float): The timeout for this request.

995 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

996 sent along with the request as metadata. Normally, each value must be of type `str`,

997 but for metadata keys ending with the suffix `-bin`, the corresponding values must

998 be of type `bytes`.

999

1000 Returns:

1001 google.cloud.firestore_v1.types.CommitResponse:

1002 The response for

1003 [Firestore.Commit][google.firestore.v1.Firestore.Commit].

1004

1005 """

1006 # Create or coerce a protobuf request object.

1007 # - Quick check: If we got a request object, we should *not* have

1008 # gotten any keyword arguments that map to the request.

1009 flattened_params = [database, writes]

1010 has_flattened_params = (

1011 len([param for param in flattened_params if param is not None]) > 0

1012 )

1013 if request is not None and has_flattened_params:

1014 raise ValueError(

1015 "If the `request` argument is set, then none of "

1016 "the individual field arguments should be set."

1017 )

1018

1019 # - Use the request object if provided (there's no risk of modifying the input as

1020 # there are no flattened fields), or create one.

1021 if not isinstance(request, firestore.CommitRequest):

1022 request = firestore.CommitRequest(request)

1023

1024 # If we have keyword arguments corresponding to fields on the

1025 # request, apply these.

1026 if database is not None:

1027 request.database = database

1028 if writes:

1029 request.writes.extend(writes)

1030

1031 # Wrap the RPC method; this adds retry and timeout information,

1032 # and friendly error handling.

1033 rpc = self._client._transport._wrapped_methods[self._client._transport.commit]

1034

1035 # Certain fields should be provided within the metadata header;

1036 # add these here.

1037 metadata = tuple(metadata) + (

1038 gapic_v1.routing_header.to_grpc_metadata((("database", request.database),)),

1039 )

1040

1041 # Validate the universe domain.

1042 self._client._validate_universe_domain()

1043

1044 # Send the request.

1045 response = await rpc(

1046 request,

1047 retry=retry,

1048 timeout=timeout,

1049 metadata=metadata,

1050 )

1051

1052 # Done; return the response.

1053 return response

1054

1055 async def rollback(

1056 self,

1057 request: Optional[Union[firestore.RollbackRequest, dict]] = None,

1058 *,

1059 database: Optional[str] = None,

1060 transaction: Optional[bytes] = None,

1061 retry: OptionalRetry = gapic_v1.method.DEFAULT,

1062 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

1063 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

1064 ) -> None:

1065 r"""Rolls back a transaction.

1066

1067 .. code-block:: python

1068

1069 # This snippet has been automatically generated and should be regarded as a

1070 # code template only.

1071 # It will require modifications to work:

1072 # - It may require correct/in-range values for request initialization.

1073 # - It may require specifying regional endpoints when creating the service

1074 # client as shown in:

1075 # https://googleapis.dev/python/google-api-core/latest/client_options.html

1076 from google.cloud import firestore_v1

1077

1078 async def sample_rollback():

1079 # Create a client

1080 client = firestore_v1.FirestoreAsyncClient()

1081

1082 # Initialize request argument(s)

1083 request = firestore_v1.RollbackRequest(

1084 database="database_value",

1085 transaction=b'transaction_blob',

1086 )

1087

1088 # Make the request

1089 await client.rollback(request=request)

1090

1091 Args:

1092 request (Optional[Union[google.cloud.firestore_v1.types.RollbackRequest, dict]]):

1093 The request object. The request for

1094 [Firestore.Rollback][google.firestore.v1.Firestore.Rollback].

1095 database (:class:`str`):

1096 Required. The database name. In the format:

1097 ``projects/{project_id}/databases/{database_id}``.

1098

1099 This corresponds to the ``database`` field

1100 on the ``request`` instance; if ``request`` is provided, this

1101 should not be set.

1102 transaction (:class:`bytes`):

1103 Required. The transaction to roll

1104 back.

1105

1106 This corresponds to the ``transaction`` field

1107 on the ``request`` instance; if ``request`` is provided, this

1108 should not be set.

1109 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

1110 should be retried.

1111 timeout (float): The timeout for this request.

1112 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

1113 sent along with the request as metadata. Normally, each value must be of type `str`,

1114 but for metadata keys ending with the suffix `-bin`, the corresponding values must

1115 be of type `bytes`.

1116 """

1117 # Create or coerce a protobuf request object.

1118 # - Quick check: If we got a request object, we should *not* have

1119 # gotten any keyword arguments that map to the request.

1120 flattened_params = [database, transaction]

1121 has_flattened_params = (

1122 len([param for param in flattened_params if param is not None]) > 0

1123 )

1124 if request is not None and has_flattened_params:

1125 raise ValueError(

1126 "If the `request` argument is set, then none of "

1127 "the individual field arguments should be set."

1128 )

1129

1130 # - Use the request object if provided (there's no risk of modifying the input as

1131 # there are no flattened fields), or create one.

1132 if not isinstance(request, firestore.RollbackRequest):

1133 request = firestore.RollbackRequest(request)

1134

1135 # If we have keyword arguments corresponding to fields on the

1136 # request, apply these.

1137 if database is not None:

1138 request.database = database

1139 if transaction is not None:

1140 request.transaction = transaction

1141

1142 # Wrap the RPC method; this adds retry and timeout information,

1143 # and friendly error handling.

1144 rpc = self._client._transport._wrapped_methods[self._client._transport.rollback]

1145

1146 # Certain fields should be provided within the metadata header;

1147 # add these here.

1148 metadata = tuple(metadata) + (

1149 gapic_v1.routing_header.to_grpc_metadata((("database", request.database),)),

1150 )

1151

1152 # Validate the universe domain.

1153 self._client._validate_universe_domain()

1154

1155 # Send the request.

1156 await rpc(

1157 request,

1158 retry=retry,

1159 timeout=timeout,

1160 metadata=metadata,

1161 )

1162

1163 def run_query(

1164 self,

1165 request: Optional[Union[firestore.RunQueryRequest, dict]] = None,

1166 *,

1167 retry: OptionalRetry = gapic_v1.method.DEFAULT,

1168 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

1169 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

1170 ) -> Awaitable[AsyncIterable[firestore.RunQueryResponse]]:

1171 r"""Runs a query.

1172

1173 .. code-block:: python

1174

1175 # This snippet has been automatically generated and should be regarded as a

1176 # code template only.

1177 # It will require modifications to work:

1178 # - It may require correct/in-range values for request initialization.

1179 # - It may require specifying regional endpoints when creating the service

1180 # client as shown in:

1181 # https://googleapis.dev/python/google-api-core/latest/client_options.html

1182 from google.cloud import firestore_v1

1183

1184 async def sample_run_query():

1185 # Create a client

1186 client = firestore_v1.FirestoreAsyncClient()

1187

1188 # Initialize request argument(s)

1189 request = firestore_v1.RunQueryRequest(

1190 transaction=b'transaction_blob',

1191 parent="parent_value",

1192 )

1193

1194 # Make the request

1195 stream = await client.run_query(request=request)

1196

1197 # Handle the response

1198 async for response in stream:

1199 print(response)

1200

1201 Args:

1202 request (Optional[Union[google.cloud.firestore_v1.types.RunQueryRequest, dict]]):

1203 The request object. The request for

1204 [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery].

1205 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

1206 should be retried.

1207 timeout (float): The timeout for this request.

1208 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

1209 sent along with the request as metadata. Normally, each value must be of type `str`,

1210 but for metadata keys ending with the suffix `-bin`, the corresponding values must

1211 be of type `bytes`.

1212

1213 Returns:

1214 AsyncIterable[google.cloud.firestore_v1.types.RunQueryResponse]:

1215 The response for

1216 [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery].

1217

1218 """

1219 # Create or coerce a protobuf request object.

1220 # - Use the request object if provided (there's no risk of modifying the input as

1221 # there are no flattened fields), or create one.

1222 if not isinstance(request, firestore.RunQueryRequest):

1223 request = firestore.RunQueryRequest(request)

1224

1225 # Wrap the RPC method; this adds retry and timeout information,

1226 # and friendly error handling.

1227 rpc = self._client._transport._wrapped_methods[

1228 self._client._transport.run_query

1229 ]

1230

1231 # Certain fields should be provided within the metadata header;

1232 # add these here.

1233 metadata = tuple(metadata) + (

1234 gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),

1235 )

1236

1237 # Validate the universe domain.

1238 self._client._validate_universe_domain()

1239

1240 # Send the request.

1241 response = rpc(

1242 request,

1243 retry=retry,

1244 timeout=timeout,

1245 metadata=metadata,

1246 )

1247

1248 # Done; return the response.

1249 return response

1250

1251 def run_aggregation_query(

1252 self,

1253 request: Optional[Union[firestore.RunAggregationQueryRequest, dict]] = None,

1254 *,

1255 retry: OptionalRetry = gapic_v1.method.DEFAULT,

1256 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

1257 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

1258 ) -> Awaitable[AsyncIterable[firestore.RunAggregationQueryResponse]]:

1259 r"""Runs an aggregation query.

1260

1261 Rather than producing [Document][google.firestore.v1.Document]

1262 results like

1263 [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery],

1264 this API allows running an aggregation to produce a series of

1265 [AggregationResult][google.firestore.v1.AggregationResult]

1266 server-side.

1267

1268 High-Level Example:

1269

1270 ::

1271

1272 -- Return the number of documents in table given a filter.

1273 SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );

1274

1275 .. code-block:: python

1276

1277 # This snippet has been automatically generated and should be regarded as a

1278 # code template only.

1279 # It will require modifications to work:

1280 # - It may require correct/in-range values for request initialization.

1281 # - It may require specifying regional endpoints when creating the service

1282 # client as shown in:

1283 # https://googleapis.dev/python/google-api-core/latest/client_options.html

1284 from google.cloud import firestore_v1

1285

1286 async def sample_run_aggregation_query():

1287 # Create a client

1288 client = firestore_v1.FirestoreAsyncClient()

1289

1290 # Initialize request argument(s)

1291 request = firestore_v1.RunAggregationQueryRequest(

1292 transaction=b'transaction_blob',

1293 parent="parent_value",

1294 )

1295

1296 # Make the request

1297 stream = await client.run_aggregation_query(request=request)

1298

1299 # Handle the response

1300 async for response in stream:

1301 print(response)

1302

1303 Args:

1304 request (Optional[Union[google.cloud.firestore_v1.types.RunAggregationQueryRequest, dict]]):

1305 The request object. The request for

1306 [Firestore.RunAggregationQuery][google.firestore.v1.Firestore.RunAggregationQuery].

1307 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

1308 should be retried.

1309 timeout (float): The timeout for this request.

1310 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

1311 sent along with the request as metadata. Normally, each value must be of type `str`,

1312 but for metadata keys ending with the suffix `-bin`, the corresponding values must

1313 be of type `bytes`.

1314

1315 Returns:

1316 AsyncIterable[google.cloud.firestore_v1.types.RunAggregationQueryResponse]:

1317 The response for

1318 [Firestore.RunAggregationQuery][google.firestore.v1.Firestore.RunAggregationQuery].

1319

1320 """

1321 # Create or coerce a protobuf request object.

1322 # - Use the request object if provided (there's no risk of modifying the input as

1323 # there are no flattened fields), or create one.

1324 if not isinstance(request, firestore.RunAggregationQueryRequest):

1325 request = firestore.RunAggregationQueryRequest(request)

1326

1327 # Wrap the RPC method; this adds retry and timeout information,

1328 # and friendly error handling.

1329 rpc = self._client._transport._wrapped_methods[

1330 self._client._transport.run_aggregation_query

1331 ]

1332

1333 # Certain fields should be provided within the metadata header;

1334 # add these here.

1335 metadata = tuple(metadata) + (

1336 gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),

1337 )

1338

1339 # Validate the universe domain.

1340 self._client._validate_universe_domain()

1341

1342 # Send the request.

1343 response = rpc(

1344 request,

1345 retry=retry,

1346 timeout=timeout,

1347 metadata=metadata,

1348 )

1349

1350 # Done; return the response.

1351 return response

1352

1353 async def partition_query(

1354 self,

1355 request: Optional[Union[firestore.PartitionQueryRequest, dict]] = None,

1356 *,

1357 retry: OptionalRetry = gapic_v1.method.DEFAULT,

1358 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

1359 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

1360 ) -> pagers.PartitionQueryAsyncPager:

1361 r"""Partitions a query by returning partition cursors

1362 that can be used to run the query in parallel. The

1363 returned partition cursors are split points that can be

1364 used by RunQuery as starting/end points for the query

1365 results.

1366

1367 .. code-block:: python

1368

1369 # This snippet has been automatically generated and should be regarded as a

1370 # code template only.

1371 # It will require modifications to work:

1372 # - It may require correct/in-range values for request initialization.

1373 # - It may require specifying regional endpoints when creating the service

1374 # client as shown in:

1375 # https://googleapis.dev/python/google-api-core/latest/client_options.html

1376 from google.cloud import firestore_v1

1377

1378 async def sample_partition_query():

1379 # Create a client

1380 client = firestore_v1.FirestoreAsyncClient()

1381

1382 # Initialize request argument(s)

1383 request = firestore_v1.PartitionQueryRequest(

1384 parent="parent_value",

1385 )

1386

1387 # Make the request

1388 page_result = client.partition_query(request=request)

1389

1390 # Handle the response

1391 async for response in page_result:

1392 print(response)

1393

1394 Args:

1395 request (Optional[Union[google.cloud.firestore_v1.types.PartitionQueryRequest, dict]]):

1396 The request object. The request for

1397 [Firestore.PartitionQuery][google.firestore.v1.Firestore.PartitionQuery].

1398 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

1399 should be retried.

1400 timeout (float): The timeout for this request.

1401 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

1402 sent along with the request as metadata. Normally, each value must be of type `str`,

1403 but for metadata keys ending with the suffix `-bin`, the corresponding values must

1404 be of type `bytes`.

1405

1406 Returns:

1407 google.cloud.firestore_v1.services.firestore.pagers.PartitionQueryAsyncPager:

1408 The response for

1409 [Firestore.PartitionQuery][google.firestore.v1.Firestore.PartitionQuery].

1410

1411 Iterating over this object will yield results and

1412 resolve additional pages automatically.

1413

1414 """

1415 # Create or coerce a protobuf request object.

1416 # - Use the request object if provided (there's no risk of modifying the input as

1417 # there are no flattened fields), or create one.

1418 if not isinstance(request, firestore.PartitionQueryRequest):

1419 request = firestore.PartitionQueryRequest(request)

1420

1421 # Wrap the RPC method; this adds retry and timeout information,

1422 # and friendly error handling.

1423 rpc = self._client._transport._wrapped_methods[

1424 self._client._transport.partition_query

1425 ]

1426

1427 # Certain fields should be provided within the metadata header;

1428 # add these here.

1429 metadata = tuple(metadata) + (

1430 gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),

1431 )

1432

1433 # Validate the universe domain.

1434 self._client._validate_universe_domain()

1435

1436 # Send the request.

1437 response = await rpc(

1438 request,

1439 retry=retry,

1440 timeout=timeout,

1441 metadata=metadata,

1442 )

1443

1444 # This method is paged; wrap the response in a pager, which provides

1445 # an `__aiter__` convenience method.

1446 response = pagers.PartitionQueryAsyncPager(

1447 method=rpc,

1448 request=request,

1449 response=response,

1450 retry=retry,

1451 timeout=timeout,

1452 metadata=metadata,

1453 )

1454

1455 # Done; return the response.

1456 return response

1457

1458 def write(

1459 self,

1460 requests: Optional[AsyncIterator[firestore.WriteRequest]] = None,

1461 *,

1462 retry: OptionalRetry = gapic_v1.method.DEFAULT,

1463 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

1464 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

1465 ) -> Awaitable[AsyncIterable[firestore.WriteResponse]]:

1466 r"""Streams batches of document updates and deletes, in

1467 order. This method is only available via gRPC or

1468 WebChannel (not REST).

1469

1470 .. code-block:: python

1471

1472 # This snippet has been automatically generated and should be regarded as a

1473 # code template only.

1474 # It will require modifications to work:

1475 # - It may require correct/in-range values for request initialization.

1476 # - It may require specifying regional endpoints when creating the service

1477 # client as shown in:

1478 # https://googleapis.dev/python/google-api-core/latest/client_options.html

1479 from google.cloud import firestore_v1

1480

1481 async def sample_write():

1482 # Create a client

1483 client = firestore_v1.FirestoreAsyncClient()

1484

1485 # Initialize request argument(s)

1486 request = firestore_v1.WriteRequest(

1487 database="database_value",

1488 )

1489

1490 # This method expects an iterator which contains

1491 # 'firestore_v1.WriteRequest' objects

1492 # Here we create a generator that yields a single `request` for

1493 # demonstrative purposes.

1494 requests = [request]

1495

1496 def request_generator():

1497 for request in requests:

1498 yield request

1499

1500 # Make the request

1501 stream = await client.write(requests=request_generator())

1502

1503 # Handle the response

1504 async for response in stream:

1505 print(response)

1506

1507 Args:

1508 requests (AsyncIterator[`google.cloud.firestore_v1.types.WriteRequest`]):

1509 The request object AsyncIterator. The request for

1510 [Firestore.Write][google.firestore.v1.Firestore.Write].

1511

1512 The first request creates a stream, or resumes an

1513 existing one from a token.

1514

1515 When creating a new stream, the server replies with a

1516 response containing only an ID and a token, to use in

1517 the next request.

1518

1519 When resuming a stream, the server first streams any

1520 responses later than the given token, then a response

1521 containing only an up-to-date token, to use in the next

1522 request.

1523 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

1524 should be retried.

1525 timeout (float): The timeout for this request.

1526 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

1527 sent along with the request as metadata. Normally, each value must be of type `str`,

1528 but for metadata keys ending with the suffix `-bin`, the corresponding values must

1529 be of type `bytes`.

1530

1531 Returns:

1532 AsyncIterable[google.cloud.firestore_v1.types.WriteResponse]:

1533 The response for

1534 [Firestore.Write][google.firestore.v1.Firestore.Write].

1535

1536 """

1537

1538 # Wrap the RPC method; this adds retry and timeout information,

1539 # and friendly error handling.

1540 rpc = self._client._transport._wrapped_methods[self._client._transport.write]

1541

1542 # Certain fields should be provided within the metadata header;

1543 # add these here.

1544 metadata = tuple(metadata) + (gapic_v1.routing_header.to_grpc_metadata(()),)

1545

1546 # Validate the universe domain.

1547 self._client._validate_universe_domain()

1548

1549 # Send the request.

1550 response = rpc(

1551 requests,

1552 retry=retry,

1553 timeout=timeout,

1554 metadata=metadata,

1555 )

1556

1557 # Done; return the response.

1558 return response

1559

1560 def listen(

1561 self,

1562 requests: Optional[AsyncIterator[firestore.ListenRequest]] = None,

1563 *,

1564 retry: OptionalRetry = gapic_v1.method.DEFAULT,

1565 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

1566 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

1567 ) -> Awaitable[AsyncIterable[firestore.ListenResponse]]:

1568 r"""Listens to changes. This method is only available via

1569 gRPC or WebChannel (not REST).

1570

1571 .. code-block:: python

1572

1573 # This snippet has been automatically generated and should be regarded as a

1574 # code template only.

1575 # It will require modifications to work:

1576 # - It may require correct/in-range values for request initialization.

1577 # - It may require specifying regional endpoints when creating the service

1578 # client as shown in:

1579 # https://googleapis.dev/python/google-api-core/latest/client_options.html

1580 from google.cloud import firestore_v1

1581

1582 async def sample_listen():

1583 # Create a client

1584 client = firestore_v1.FirestoreAsyncClient()

1585

1586 # Initialize request argument(s)

1587 add_target = firestore_v1.Target()

1588 add_target.resume_token = b'resume_token_blob'

1589

1590 request = firestore_v1.ListenRequest(

1591 add_target=add_target,

1592 database="database_value",

1593 )

1594

1595 # This method expects an iterator which contains

1596 # 'firestore_v1.ListenRequest' objects

1597 # Here we create a generator that yields a single `request` for

1598 # demonstrative purposes.

1599 requests = [request]

1600

1601 def request_generator():

1602 for request in requests:

1603 yield request

1604

1605 # Make the request

1606 stream = await client.listen(requests=request_generator())

1607

1608 # Handle the response

1609 async for response in stream:

1610 print(response)

1611

1612 Args:

1613 requests (AsyncIterator[`google.cloud.firestore_v1.types.ListenRequest`]):

1614 The request object AsyncIterator. A request for

1615 [Firestore.Listen][google.firestore.v1.Firestore.Listen]

1616 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

1617 should be retried.

1618 timeout (float): The timeout for this request.

1619 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

1620 sent along with the request as metadata. Normally, each value must be of type `str`,

1621 but for metadata keys ending with the suffix `-bin`, the corresponding values must

1622 be of type `bytes`.

1623

1624 Returns:

1625 AsyncIterable[google.cloud.firestore_v1.types.ListenResponse]:

1626 The response for

1627 [Firestore.Listen][google.firestore.v1.Firestore.Listen].

1628

1629 """

1630

1631 # Wrap the RPC method; this adds retry and timeout information,

1632 # and friendly error handling.

1633 rpc = self._client._transport._wrapped_methods[self._client._transport.listen]

1634

1635 # Certain fields should be provided within the metadata header;

1636 # add these here.

1637 metadata = tuple(metadata) + (gapic_v1.routing_header.to_grpc_metadata(()),)

1638

1639 # Validate the universe domain.

1640 self._client._validate_universe_domain()

1641

1642 # Send the request.

1643 response = rpc(

1644 requests,

1645 retry=retry,

1646 timeout=timeout,

1647 metadata=metadata,

1648 )

1649

1650 # Done; return the response.

1651 return response

1652

1653 async def list_collection_ids(

1654 self,

1655 request: Optional[Union[firestore.ListCollectionIdsRequest, dict]] = None,

1656 *,

1657 parent: Optional[str] = None,

1658 retry: OptionalRetry = gapic_v1.method.DEFAULT,

1659 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

1660 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

1661 ) -> pagers.ListCollectionIdsAsyncPager:

1662 r"""Lists all the collection IDs underneath a document.

1663

1664 .. code-block:: python

1665

1666 # This snippet has been automatically generated and should be regarded as a

1667 # code template only.

1668 # It will require modifications to work:

1669 # - It may require correct/in-range values for request initialization.

1670 # - It may require specifying regional endpoints when creating the service

1671 # client as shown in:

1672 # https://googleapis.dev/python/google-api-core/latest/client_options.html

1673 from google.cloud import firestore_v1

1674

1675 async def sample_list_collection_ids():

1676 # Create a client

1677 client = firestore_v1.FirestoreAsyncClient()

1678

1679 # Initialize request argument(s)

1680 request = firestore_v1.ListCollectionIdsRequest(

1681 parent="parent_value",

1682 )

1683

1684 # Make the request

1685 page_result = client.list_collection_ids(request=request)

1686

1687 # Handle the response

1688 async for response in page_result:

1689 print(response)

1690

1691 Args:

1692 request (Optional[Union[google.cloud.firestore_v1.types.ListCollectionIdsRequest, dict]]):

1693 The request object. The request for

1694 [Firestore.ListCollectionIds][google.firestore.v1.Firestore.ListCollectionIds].

1695 parent (:class:`str`):

1696 Required. The parent document. In the format:

1697 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.

1698 For example:

1699 ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom``

1700

1701 This corresponds to the ``parent`` field

1702 on the ``request`` instance; if ``request`` is provided, this

1703 should not be set.

1704 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

1705 should be retried.

1706 timeout (float): The timeout for this request.

1707 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

1708 sent along with the request as metadata. Normally, each value must be of type `str`,

1709 but for metadata keys ending with the suffix `-bin`, the corresponding values must

1710 be of type `bytes`.

1711

1712 Returns:

1713 google.cloud.firestore_v1.services.firestore.pagers.ListCollectionIdsAsyncPager:

1714 The response from

1715 [Firestore.ListCollectionIds][google.firestore.v1.Firestore.ListCollectionIds].

1716

1717 Iterating over this object will yield results and

1718 resolve additional pages automatically.

1719

1720 """

1721 # Create or coerce a protobuf request object.

1722 # - Quick check: If we got a request object, we should *not* have

1723 # gotten any keyword arguments that map to the request.

1724 flattened_params = [parent]

1725 has_flattened_params = (

1726 len([param for param in flattened_params if param is not None]) > 0

1727 )

1728 if request is not None and has_flattened_params:

1729 raise ValueError(

1730 "If the `request` argument is set, then none of "

1731 "the individual field arguments should be set."

1732 )

1733

1734 # - Use the request object if provided (there's no risk of modifying the input as

1735 # there are no flattened fields), or create one.

1736 if not isinstance(request, firestore.ListCollectionIdsRequest):

1737 request = firestore.ListCollectionIdsRequest(request)

1738

1739 # If we have keyword arguments corresponding to fields on the

1740 # request, apply these.

1741 if parent is not None:

1742 request.parent = parent

1743

1744 # Wrap the RPC method; this adds retry and timeout information,

1745 # and friendly error handling.

1746 rpc = self._client._transport._wrapped_methods[

1747 self._client._transport.list_collection_ids

1748 ]

1749

1750 # Certain fields should be provided within the metadata header;

1751 # add these here.

1752 metadata = tuple(metadata) + (

1753 gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),

1754 )

1755

1756 # Validate the universe domain.

1757 self._client._validate_universe_domain()

1758

1759 # Send the request.

1760 response = await rpc(

1761 request,

1762 retry=retry,

1763 timeout=timeout,

1764 metadata=metadata,

1765 )

1766

1767 # This method is paged; wrap the response in a pager, which provides

1768 # an `__aiter__` convenience method.

1769 response = pagers.ListCollectionIdsAsyncPager(

1770 method=rpc,

1771 request=request,

1772 response=response,

1773 retry=retry,

1774 timeout=timeout,

1775 metadata=metadata,

1776 )

1777

1778 # Done; return the response.

1779 return response

1780

1781 async def batch_write(

1782 self,

1783 request: Optional[Union[firestore.BatchWriteRequest, dict]] = None,

1784 *,

1785 retry: OptionalRetry = gapic_v1.method.DEFAULT,

1786 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

1787 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

1788 ) -> firestore.BatchWriteResponse:

1789 r"""Applies a batch of write operations.

1790

1791 The BatchWrite method does not apply the write operations

1792 atomically and can apply them out of order. Method does not

1793 allow more than one write per document. Each write succeeds or

1794 fails independently. See the

1795 [BatchWriteResponse][google.firestore.v1.BatchWriteResponse] for

1796 the success status of each write.

1797

1798 If you require an atomically applied set of writes, use

1799 [Commit][google.firestore.v1.Firestore.Commit] instead.

1800

1801 .. code-block:: python

1802

1803 # This snippet has been automatically generated and should be regarded as a

1804 # code template only.

1805 # It will require modifications to work:

1806 # - It may require correct/in-range values for request initialization.

1807 # - It may require specifying regional endpoints when creating the service

1808 # client as shown in:

1809 # https://googleapis.dev/python/google-api-core/latest/client_options.html

1810 from google.cloud import firestore_v1

1811

1812 async def sample_batch_write():

1813 # Create a client

1814 client = firestore_v1.FirestoreAsyncClient()

1815

1816 # Initialize request argument(s)

1817 request = firestore_v1.BatchWriteRequest(

1818 database="database_value",

1819 )

1820

1821 # Make the request

1822 response = await client.batch_write(request=request)

1823

1824 # Handle the response

1825 print(response)

1826

1827 Args:

1828 request (Optional[Union[google.cloud.firestore_v1.types.BatchWriteRequest, dict]]):

1829 The request object. The request for

1830 [Firestore.BatchWrite][google.firestore.v1.Firestore.BatchWrite].

1831 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

1832 should be retried.

1833 timeout (float): The timeout for this request.

1834 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

1835 sent along with the request as metadata. Normally, each value must be of type `str`,

1836 but for metadata keys ending with the suffix `-bin`, the corresponding values must

1837 be of type `bytes`.

1838

1839 Returns:

1840 google.cloud.firestore_v1.types.BatchWriteResponse:

1841 The response from

1842 [Firestore.BatchWrite][google.firestore.v1.Firestore.BatchWrite].

1843

1844 """

1845 # Create or coerce a protobuf request object.

1846 # - Use the request object if provided (there's no risk of modifying the input as

1847 # there are no flattened fields), or create one.

1848 if not isinstance(request, firestore.BatchWriteRequest):

1849 request = firestore.BatchWriteRequest(request)

1850

1851 # Wrap the RPC method; this adds retry and timeout information,

1852 # and friendly error handling.

1853 rpc = self._client._transport._wrapped_methods[

1854 self._client._transport.batch_write

1855 ]

1856

1857 # Certain fields should be provided within the metadata header;

1858 # add these here.

1859 metadata = tuple(metadata) + (

1860 gapic_v1.routing_header.to_grpc_metadata((("database", request.database),)),

1861 )

1862

1863 # Validate the universe domain.

1864 self._client._validate_universe_domain()

1865

1866 # Send the request.

1867 response = await rpc(

1868 request,

1869 retry=retry,

1870 timeout=timeout,

1871 metadata=metadata,

1872 )

1873

1874 # Done; return the response.

1875 return response

1876

1877 async def create_document(

1878 self,

1879 request: Optional[Union[firestore.CreateDocumentRequest, dict]] = None,

1880 *,

1881 retry: OptionalRetry = gapic_v1.method.DEFAULT,

1882 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

1883 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

1884 ) -> document.Document:

1885 r"""Creates a new document.

1886

1887 .. code-block:: python

1888

1889 # This snippet has been automatically generated and should be regarded as a

1890 # code template only.

1891 # It will require modifications to work:

1892 # - It may require correct/in-range values for request initialization.

1893 # - It may require specifying regional endpoints when creating the service

1894 # client as shown in:

1895 # https://googleapis.dev/python/google-api-core/latest/client_options.html

1896 from google.cloud import firestore_v1

1897

1898 async def sample_create_document():

1899 # Create a client

1900 client = firestore_v1.FirestoreAsyncClient()

1901

1902 # Initialize request argument(s)

1903 request = firestore_v1.CreateDocumentRequest(

1904 parent="parent_value",

1905 collection_id="collection_id_value",

1906 )

1907

1908 # Make the request

1909 response = await client.create_document(request=request)

1910

1911 # Handle the response

1912 print(response)

1913

1914 Args:

1915 request (Optional[Union[google.cloud.firestore_v1.types.CreateDocumentRequest, dict]]):

1916 The request object. The request for

1917 [Firestore.CreateDocument][google.firestore.v1.Firestore.CreateDocument].

1918 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors, if any,

1919 should be retried.

1920 timeout (float): The timeout for this request.

1921 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

1922 sent along with the request as metadata. Normally, each value must be of type `str`,

1923 but for metadata keys ending with the suffix `-bin`, the corresponding values must

1924 be of type `bytes`.

1925

1926 Returns:

1927 google.cloud.firestore_v1.types.Document:

1928 A Firestore document.

1929

1930 Must not exceed 1 MiB - 4 bytes.

1931

1932 """

1933 # Create or coerce a protobuf request object.

1934 # - Use the request object if provided (there's no risk of modifying the input as

1935 # there are no flattened fields), or create one.

1936 if not isinstance(request, firestore.CreateDocumentRequest):

1937 request = firestore.CreateDocumentRequest(request)

1938

1939 # Wrap the RPC method; this adds retry and timeout information,

1940 # and friendly error handling.

1941 rpc = self._client._transport._wrapped_methods[

1942 self._client._transport.create_document

1943 ]

1944

1945 # Certain fields should be provided within the metadata header;

1946 # add these here.

1947 metadata = tuple(metadata) + (

1948 gapic_v1.routing_header.to_grpc_metadata(

1949 (

1950 ("parent", request.parent),

1951 ("collection_id", request.collection_id),

1952 )

1953 ),

1954 )

1955

1956 # Validate the universe domain.

1957 self._client._validate_universe_domain()

1958

1959 # Send the request.

1960 response = await rpc(

1961 request,

1962 retry=retry,

1963 timeout=timeout,

1964 metadata=metadata,

1965 )

1966

1967 # Done; return the response.

1968 return response

1969

1970 async def list_operations(

1971 self,

1972 request: Optional[operations_pb2.ListOperationsRequest] = None,

1973 *,

1974 retry: OptionalRetry = gapic_v1.method.DEFAULT,

1975 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

1976 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

1977 ) -> operations_pb2.ListOperationsResponse:

1978 r"""Lists operations that match the specified filter in the request.

1979

1980 Args:

1981 request (:class:`~.operations_pb2.ListOperationsRequest`):

1982 The request object. Request message for

1983 `ListOperations` method.

1984 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors,

1985 if any, should be retried.

1986 timeout (float): The timeout for this request.

1987 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

1988 sent along with the request as metadata. Normally, each value must be of type `str`,

1989 but for metadata keys ending with the suffix `-bin`, the corresponding values must

1990 be of type `bytes`.

1991 Returns:

1992 ~.operations_pb2.ListOperationsResponse:

1993 Response message for ``ListOperations`` method.

1994 """

1995 # Create or coerce a protobuf request object.

1996 # The request isn't a proto-plus wrapped type,

1997 # so it must be constructed via keyword expansion.

1998 if isinstance(request, dict):

1999 request = operations_pb2.ListOperationsRequest(**request)

2000

2001 # Wrap the RPC method; this adds retry and timeout information,

2002 # and friendly error handling.

2003 rpc = self.transport._wrapped_methods[self._client._transport.list_operations]

2004

2005 # Certain fields should be provided within the metadata header;

2006 # add these here.

2007 metadata = tuple(metadata) + (

2008 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),

2009 )

2010

2011 # Validate the universe domain.

2012 self._client._validate_universe_domain()

2013

2014 # Send the request.

2015 response = await rpc(

2016 request,

2017 retry=retry,

2018 timeout=timeout,

2019 metadata=metadata,

2020 )

2021

2022 # Done; return the response.

2023 return response

2024

2025 async def get_operation(

2026 self,

2027 request: Optional[operations_pb2.GetOperationRequest] = None,

2028 *,

2029 retry: OptionalRetry = gapic_v1.method.DEFAULT,

2030 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

2031 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

2032 ) -> operations_pb2.Operation:

2033 r"""Gets the latest state of a long-running operation.

2034

2035 Args:

2036 request (:class:`~.operations_pb2.GetOperationRequest`):

2037 The request object. Request message for

2038 `GetOperation` method.

2039 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors,

2040 if any, should be retried.

2041 timeout (float): The timeout for this request.

2042 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

2043 sent along with the request as metadata. Normally, each value must be of type `str`,

2044 but for metadata keys ending with the suffix `-bin`, the corresponding values must

2045 be of type `bytes`.

2046 Returns:

2047 ~.operations_pb2.Operation:

2048 An ``Operation`` object.

2049 """

2050 # Create or coerce a protobuf request object.

2051 # The request isn't a proto-plus wrapped type,

2052 # so it must be constructed via keyword expansion.

2053 if isinstance(request, dict):

2054 request = operations_pb2.GetOperationRequest(**request)

2055

2056 # Wrap the RPC method; this adds retry and timeout information,

2057 # and friendly error handling.

2058 rpc = self.transport._wrapped_methods[self._client._transport.get_operation]

2059

2060 # Certain fields should be provided within the metadata header;

2061 # add these here.

2062 metadata = tuple(metadata) + (

2063 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),

2064 )

2065

2066 # Validate the universe domain.

2067 self._client._validate_universe_domain()

2068

2069 # Send the request.

2070 response = await rpc(

2071 request,

2072 retry=retry,

2073 timeout=timeout,

2074 metadata=metadata,

2075 )

2076

2077 # Done; return the response.

2078 return response

2079

2080 async def delete_operation(

2081 self,

2082 request: Optional[operations_pb2.DeleteOperationRequest] = None,

2083 *,

2084 retry: OptionalRetry = gapic_v1.method.DEFAULT,

2085 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

2086 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

2087 ) -> None:

2088 r"""Deletes a long-running operation.

2089

2090 This method indicates that the client is no longer interested

2091 in the operation result. It does not cancel the operation.

2092 If the server doesn't support this method, it returns

2093 `google.rpc.Code.UNIMPLEMENTED`.

2094

2095 Args:

2096 request (:class:`~.operations_pb2.DeleteOperationRequest`):

2097 The request object. Request message for

2098 `DeleteOperation` method.

2099 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors,

2100 if any, should be retried.

2101 timeout (float): The timeout for this request.

2102 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

2103 sent along with the request as metadata. Normally, each value must be of type `str`,

2104 but for metadata keys ending with the suffix `-bin`, the corresponding values must

2105 be of type `bytes`.

2106 Returns:

2107 None

2108 """

2109 # Create or coerce a protobuf request object.

2110 # The request isn't a proto-plus wrapped type,

2111 # so it must be constructed via keyword expansion.

2112 if isinstance(request, dict):

2113 request = operations_pb2.DeleteOperationRequest(**request)

2114

2115 # Wrap the RPC method; this adds retry and timeout information,

2116 # and friendly error handling.

2117 rpc = self.transport._wrapped_methods[self._client._transport.delete_operation]

2118

2119 # Certain fields should be provided within the metadata header;

2120 # add these here.

2121 metadata = tuple(metadata) + (

2122 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),

2123 )

2124

2125 # Validate the universe domain.

2126 self._client._validate_universe_domain()

2127

2128 # Send the request.

2129 await rpc(

2130 request,

2131 retry=retry,

2132 timeout=timeout,

2133 metadata=metadata,

2134 )

2135

2136 async def cancel_operation(

2137 self,

2138 request: Optional[operations_pb2.CancelOperationRequest] = None,

2139 *,

2140 retry: OptionalRetry = gapic_v1.method.DEFAULT,

2141 timeout: Union[float, object] = gapic_v1.method.DEFAULT,

2142 metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),

2143 ) -> None:

2144 r"""Starts asynchronous cancellation on a long-running operation.

2145

2146 The server makes a best effort to cancel the operation, but success

2147 is not guaranteed. If the server doesn't support this method, it returns

2148 `google.rpc.Code.UNIMPLEMENTED`.

2149

2150 Args:

2151 request (:class:`~.operations_pb2.CancelOperationRequest`):

2152 The request object. Request message for

2153 `CancelOperation` method.

2154 retry (google.api_core.retry_async.AsyncRetry): Designation of what errors,

2155 if any, should be retried.

2156 timeout (float): The timeout for this request.

2157 metadata (Sequence[Tuple[str, Union[str, bytes]]]): Key/value pairs which should be

2158 sent along with the request as metadata. Normally, each value must be of type `str`,

2159 but for metadata keys ending with the suffix `-bin`, the corresponding values must

2160 be of type `bytes`.

2161 Returns:

2162 None

2163 """

2164 # Create or coerce a protobuf request object.

2165 # The request isn't a proto-plus wrapped type,

2166 # so it must be constructed via keyword expansion.

2167 if isinstance(request, dict):

2168 request = operations_pb2.CancelOperationRequest(**request)

2169

2170 # Wrap the RPC method; this adds retry and timeout information,

2171 # and friendly error handling.

2172 rpc = self.transport._wrapped_methods[self._client._transport.cancel_operation]

2173

2174 # Certain fields should be provided within the metadata header;

2175 # add these here.

2176 metadata = tuple(metadata) + (

2177 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),

2178 )

2179

2180 # Validate the universe domain.

2181 self._client._validate_universe_domain()

2182

2183 # Send the request.

2184 await rpc(

2185 request,

2186 retry=retry,

2187 timeout=timeout,

2188 metadata=metadata,

2189 )

2190

2191 async def __aenter__(self) -> "FirestoreAsyncClient":

2192 return self

2193

2194 async def __aexit__(self, exc_type, exc, tb):

2195 await self.transport.close()

2196

2197

2198DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(

2199 gapic_version=package_version.__version__

2200)

2201

2202if hasattr(DEFAULT_CLIENT_INFO, "protobuf_runtime_version"): # pragma: NO COVER

2203 DEFAULT_CLIENT_INFO.protobuf_runtime_version = google.protobuf.__version__

2204

2205

2206__all__ = ("FirestoreAsyncClient",)

Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/google/cloud/firestore_v1/services/firestore/async_client.py: 32%

275 statements