Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/cloud/firestore_v1/services/firestore/client.py: 32%
325 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-09 06:27 +0000
1# -*- coding: utf-8 -*-
2# Copyright 2023 Google LLC
3#
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
7#
8# http://www.apache.org/licenses/LICENSE-2.0
9#
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#
16from collections import OrderedDict
17import os
18import re
19from typing import (
20 Dict,
21 Mapping,
22 MutableMapping,
23 MutableSequence,
24 Optional,
25 Iterable,
26 Iterator,
27 Sequence,
28 Tuple,
29 Type,
30 Union,
31 cast,
32)
34from google.cloud.firestore_v1 import gapic_version as package_version
36from google.api_core import client_options as client_options_lib
37from google.api_core import exceptions as core_exceptions
38from google.api_core import gapic_v1
39from google.api_core import retry as retries
40from google.auth import credentials as ga_credentials # type: ignore
41from google.auth.transport import mtls # type: ignore
42from google.auth.transport.grpc import SslCredentials # type: ignore
43from google.auth.exceptions import MutualTLSChannelError # type: ignore
44from google.oauth2 import service_account # type: ignore
46try:
47 OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]
48except AttributeError: # pragma: NO COVER
49 OptionalRetry = Union[retries.Retry, object] # 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 write as gf_write
59from google.cloud.location import locations_pb2 # type: ignore
60from google.longrunning import operations_pb2 # type: ignore
61from google.protobuf import timestamp_pb2 # type: ignore
62from google.rpc import status_pb2 # type: ignore
63from .transports.base import FirestoreTransport, DEFAULT_CLIENT_INFO
64from .transports.grpc import FirestoreGrpcTransport
65from .transports.grpc_asyncio import FirestoreGrpcAsyncIOTransport
66from .transports.rest import FirestoreRestTransport
69class FirestoreClientMeta(type):
70 """Metaclass for the Firestore client.
72 This provides class-level methods for building and retrieving
73 support objects (e.g. transport) without polluting the client instance
74 objects.
75 """
77 _transport_registry = OrderedDict() # type: Dict[str, Type[FirestoreTransport]]
78 _transport_registry["grpc"] = FirestoreGrpcTransport
79 _transport_registry["grpc_asyncio"] = FirestoreGrpcAsyncIOTransport
80 _transport_registry["rest"] = FirestoreRestTransport
82 def get_transport_class(
83 cls,
84 label: Optional[str] = None,
85 ) -> Type[FirestoreTransport]:
86 """Returns an appropriate transport class.
88 Args:
89 label: The name of the desired transport. If none is
90 provided, then the first transport in the registry is used.
92 Returns:
93 The transport class to use.
94 """
95 # If a specific transport is requested, return that one.
96 if label:
97 return cls._transport_registry[label]
99 # No transport is requested; return the default (that is, the first one
100 # in the dictionary).
101 return next(iter(cls._transport_registry.values()))
104class FirestoreClient(metaclass=FirestoreClientMeta):
105 """The Cloud Firestore service.
107 Cloud Firestore is a fast, fully managed, serverless,
108 cloud-native NoSQL document database that simplifies storing,
109 syncing, and querying data for your mobile, web, and IoT apps at
110 global scale. Its client libraries provide live synchronization
111 and offline support, while its security features and
112 integrations with Firebase and Google Cloud Platform accelerate
113 building truly serverless apps.
114 """
116 @staticmethod
117 def _get_default_mtls_endpoint(api_endpoint):
118 """Converts api endpoint to mTLS endpoint.
120 Convert "*.sandbox.googleapis.com" and "*.googleapis.com" to
121 "*.mtls.sandbox.googleapis.com" and "*.mtls.googleapis.com" respectively.
122 Args:
123 api_endpoint (Optional[str]): the api endpoint to convert.
124 Returns:
125 str: converted mTLS api endpoint.
126 """
127 if not api_endpoint:
128 return api_endpoint
130 mtls_endpoint_re = re.compile(
131 r"(?P<name>[^.]+)(?P<mtls>\.mtls)?(?P<sandbox>\.sandbox)?(?P<googledomain>\.googleapis\.com)?"
132 )
134 m = mtls_endpoint_re.match(api_endpoint)
135 name, mtls, sandbox, googledomain = m.groups()
136 if mtls or not googledomain:
137 return api_endpoint
139 if sandbox:
140 return api_endpoint.replace(
141 "sandbox.googleapis.com", "mtls.sandbox.googleapis.com"
142 )
144 return api_endpoint.replace(".googleapis.com", ".mtls.googleapis.com")
146 DEFAULT_ENDPOINT = "firestore.googleapis.com"
147 DEFAULT_MTLS_ENDPOINT = _get_default_mtls_endpoint.__func__( # type: ignore
148 DEFAULT_ENDPOINT
149 )
151 @classmethod
152 def from_service_account_info(cls, info: dict, *args, **kwargs):
153 """Creates an instance of this client using the provided credentials
154 info.
156 Args:
157 info (dict): The service account private key info.
158 args: Additional arguments to pass to the constructor.
159 kwargs: Additional arguments to pass to the constructor.
161 Returns:
162 FirestoreClient: The constructed client.
163 """
164 credentials = service_account.Credentials.from_service_account_info(info)
165 kwargs["credentials"] = credentials
166 return cls(*args, **kwargs)
168 @classmethod
169 def from_service_account_file(cls, filename: str, *args, **kwargs):
170 """Creates an instance of this client using the provided credentials
171 file.
173 Args:
174 filename (str): The path to the service account private key json
175 file.
176 args: Additional arguments to pass to the constructor.
177 kwargs: Additional arguments to pass to the constructor.
179 Returns:
180 FirestoreClient: The constructed client.
181 """
182 credentials = service_account.Credentials.from_service_account_file(filename)
183 kwargs["credentials"] = credentials
184 return cls(*args, **kwargs)
186 from_service_account_json = from_service_account_file
188 @property
189 def transport(self) -> FirestoreTransport:
190 """Returns the transport used by the client instance.
192 Returns:
193 FirestoreTransport: The transport used by the client
194 instance.
195 """
196 return self._transport
198 @staticmethod
199 def common_billing_account_path(
200 billing_account: str,
201 ) -> str:
202 """Returns a fully-qualified billing_account string."""
203 return "billingAccounts/{billing_account}".format(
204 billing_account=billing_account,
205 )
207 @staticmethod
208 def parse_common_billing_account_path(path: str) -> Dict[str, str]:
209 """Parse a billing_account path into its component segments."""
210 m = re.match(r"^billingAccounts/(?P<billing_account>.+?)$", path)
211 return m.groupdict() if m else {}
213 @staticmethod
214 def common_folder_path(
215 folder: str,
216 ) -> str:
217 """Returns a fully-qualified folder string."""
218 return "folders/{folder}".format(
219 folder=folder,
220 )
222 @staticmethod
223 def parse_common_folder_path(path: str) -> Dict[str, str]:
224 """Parse a folder path into its component segments."""
225 m = re.match(r"^folders/(?P<folder>.+?)$", path)
226 return m.groupdict() if m else {}
228 @staticmethod
229 def common_organization_path(
230 organization: str,
231 ) -> str:
232 """Returns a fully-qualified organization string."""
233 return "organizations/{organization}".format(
234 organization=organization,
235 )
237 @staticmethod
238 def parse_common_organization_path(path: str) -> Dict[str, str]:
239 """Parse a organization path into its component segments."""
240 m = re.match(r"^organizations/(?P<organization>.+?)$", path)
241 return m.groupdict() if m else {}
243 @staticmethod
244 def common_project_path(
245 project: str,
246 ) -> str:
247 """Returns a fully-qualified project string."""
248 return "projects/{project}".format(
249 project=project,
250 )
252 @staticmethod
253 def parse_common_project_path(path: str) -> Dict[str, str]:
254 """Parse a project path into its component segments."""
255 m = re.match(r"^projects/(?P<project>.+?)$", path)
256 return m.groupdict() if m else {}
258 @staticmethod
259 def common_location_path(
260 project: str,
261 location: str,
262 ) -> str:
263 """Returns a fully-qualified location string."""
264 return "projects/{project}/locations/{location}".format(
265 project=project,
266 location=location,
267 )
269 @staticmethod
270 def parse_common_location_path(path: str) -> Dict[str, str]:
271 """Parse a location path into its component segments."""
272 m = re.match(r"^projects/(?P<project>.+?)/locations/(?P<location>.+?)$", path)
273 return m.groupdict() if m else {}
275 @classmethod
276 def get_mtls_endpoint_and_cert_source(
277 cls, client_options: Optional[client_options_lib.ClientOptions] = None
278 ):
279 """Return the API endpoint and client cert source for mutual TLS.
281 The client cert source is determined in the following order:
282 (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
283 client cert source is None.
284 (2) if `client_options.client_cert_source` is provided, use the provided one; if the
285 default client cert source exists, use the default one; otherwise the client cert
286 source is None.
288 The API endpoint is determined in the following order:
289 (1) if `client_options.api_endpoint` if provided, use the provided one.
290 (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
291 default mTLS endpoint; if the environment variable is "never", use the default API
292 endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
293 use the default API endpoint.
295 More details can be found at https://google.aip.dev/auth/4114.
297 Args:
298 client_options (google.api_core.client_options.ClientOptions): Custom options for the
299 client. Only the `api_endpoint` and `client_cert_source` properties may be used
300 in this method.
302 Returns:
303 Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
304 client cert source to use.
306 Raises:
307 google.auth.exceptions.MutualTLSChannelError: If any errors happen.
308 """
309 if client_options is None:
310 client_options = client_options_lib.ClientOptions()
311 use_client_cert = os.getenv("GOOGLE_API_USE_CLIENT_CERTIFICATE", "false")
312 use_mtls_endpoint = os.getenv("GOOGLE_API_USE_MTLS_ENDPOINT", "auto")
313 if use_client_cert not in ("true", "false"):
314 raise ValueError(
315 "Environment variable `GOOGLE_API_USE_CLIENT_CERTIFICATE` must be either `true` or `false`"
316 )
317 if use_mtls_endpoint not in ("auto", "never", "always"):
318 raise MutualTLSChannelError(
319 "Environment variable `GOOGLE_API_USE_MTLS_ENDPOINT` must be `never`, `auto` or `always`"
320 )
322 # Figure out the client cert source to use.
323 client_cert_source = None
324 if use_client_cert == "true":
325 if client_options.client_cert_source:
326 client_cert_source = client_options.client_cert_source
327 elif mtls.has_default_client_cert_source():
328 client_cert_source = mtls.default_client_cert_source()
330 # Figure out which api endpoint to use.
331 if client_options.api_endpoint is not None:
332 api_endpoint = client_options.api_endpoint
333 elif use_mtls_endpoint == "always" or (
334 use_mtls_endpoint == "auto" and client_cert_source
335 ):
336 api_endpoint = cls.DEFAULT_MTLS_ENDPOINT
337 else:
338 api_endpoint = cls.DEFAULT_ENDPOINT
340 return api_endpoint, client_cert_source
342 def __init__(
343 self,
344 *,
345 credentials: Optional[ga_credentials.Credentials] = None,
346 transport: Optional[Union[str, FirestoreTransport]] = None,
347 client_options: Optional[Union[client_options_lib.ClientOptions, dict]] = None,
348 client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
349 ) -> None:
350 """Instantiates the firestore client.
352 Args:
353 credentials (Optional[google.auth.credentials.Credentials]): The
354 authorization credentials to attach to requests. These
355 credentials identify the application to the service; if none
356 are specified, the client will attempt to ascertain the
357 credentials from the environment.
358 transport (Union[str, FirestoreTransport]): The
359 transport to use. If set to None, a transport is chosen
360 automatically.
361 client_options (Optional[Union[google.api_core.client_options.ClientOptions, dict]]): Custom options for the
362 client. It won't take effect if a ``transport`` instance is provided.
363 (1) The ``api_endpoint`` property can be used to override the
364 default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
365 environment variable can also be used to override the endpoint:
366 "always" (always use the default mTLS endpoint), "never" (always
367 use the default regular endpoint) and "auto" (auto switch to the
368 default mTLS endpoint if client certificate is present, this is
369 the default value). However, the ``api_endpoint`` property takes
370 precedence if provided.
371 (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
372 is "true", then the ``client_cert_source`` property can be used
373 to provide client certificate for mutual TLS transport. If
374 not provided, the default SSL client certificate will be used if
375 present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
376 set, no client certificate will be used.
377 client_info (google.api_core.gapic_v1.client_info.ClientInfo):
378 The client info used to send a user-agent string along with
379 API requests. If ``None``, then default info will be used.
380 Generally, you only need to set this if you're developing
381 your own client library.
383 Raises:
384 google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
385 creation failed for any reason.
386 """
387 if isinstance(client_options, dict):
388 client_options = client_options_lib.from_dict(client_options)
389 if client_options is None:
390 client_options = client_options_lib.ClientOptions()
391 client_options = cast(client_options_lib.ClientOptions, client_options)
393 api_endpoint, client_cert_source_func = self.get_mtls_endpoint_and_cert_source(
394 client_options
395 )
397 api_key_value = getattr(client_options, "api_key", None)
398 if api_key_value and credentials:
399 raise ValueError(
400 "client_options.api_key and credentials are mutually exclusive"
401 )
403 # Save or instantiate the transport.
404 # Ordinarily, we provide the transport, but allowing a custom transport
405 # instance provides an extensibility point for unusual situations.
406 if isinstance(transport, FirestoreTransport):
407 # transport is a FirestoreTransport instance.
408 if credentials or client_options.credentials_file or api_key_value:
409 raise ValueError(
410 "When providing a transport instance, "
411 "provide its credentials directly."
412 )
413 if client_options.scopes:
414 raise ValueError(
415 "When providing a transport instance, provide its scopes "
416 "directly."
417 )
418 self._transport = transport
419 else:
420 import google.auth._default # type: ignore
422 if api_key_value and hasattr(
423 google.auth._default, "get_api_key_credentials"
424 ):
425 credentials = google.auth._default.get_api_key_credentials(
426 api_key_value
427 )
429 Transport = type(self).get_transport_class(transport)
430 self._transport = Transport(
431 credentials=credentials,
432 credentials_file=client_options.credentials_file,
433 host=api_endpoint,
434 scopes=client_options.scopes,
435 client_cert_source_for_mtls=client_cert_source_func,
436 quota_project_id=client_options.quota_project_id,
437 client_info=client_info,
438 always_use_jwt_access=True,
439 api_audience=client_options.api_audience,
440 )
442 def get_document(
443 self,
444 request: Optional[Union[firestore.GetDocumentRequest, dict]] = None,
445 *,
446 retry: OptionalRetry = gapic_v1.method.DEFAULT,
447 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
448 metadata: Sequence[Tuple[str, str]] = (),
449 ) -> document.Document:
450 r"""Gets a single document.
452 .. code-block:: python
454 # This snippet has been automatically generated and should be regarded as a
455 # code template only.
456 # It will require modifications to work:
457 # - It may require correct/in-range values for request initialization.
458 # - It may require specifying regional endpoints when creating the service
459 # client as shown in:
460 # https://googleapis.dev/python/google-api-core/latest/client_options.html
461 from google.cloud import firestore_v1
463 def sample_get_document():
464 # Create a client
465 client = firestore_v1.FirestoreClient()
467 # Initialize request argument(s)
468 request = firestore_v1.GetDocumentRequest(
469 transaction=b'transaction_blob',
470 name="name_value",
471 )
473 # Make the request
474 response = client.get_document(request=request)
476 # Handle the response
477 print(response)
479 Args:
480 request (Union[google.cloud.firestore_v1.types.GetDocumentRequest, dict]):
481 The request object. The request for
482 [Firestore.GetDocument][google.firestore.v1.Firestore.GetDocument].
483 retry (google.api_core.retry.Retry): Designation of what errors, if any,
484 should be retried.
485 timeout (float): The timeout for this request.
486 metadata (Sequence[Tuple[str, str]]): Strings which should be
487 sent along with the request as metadata.
489 Returns:
490 google.cloud.firestore_v1.types.Document:
491 A Firestore document.
493 Must not exceed 1 MiB - 4 bytes.
495 """
496 # Create or coerce a protobuf request object.
497 # Minor optimization to avoid making a copy if the user passes
498 # in a firestore.GetDocumentRequest.
499 # There's no risk of modifying the input as we've already verified
500 # there are no flattened fields.
501 if not isinstance(request, firestore.GetDocumentRequest):
502 request = firestore.GetDocumentRequest(request)
504 # Wrap the RPC method; this adds retry and timeout information,
505 # and friendly error handling.
506 rpc = self._transport._wrapped_methods[self._transport.get_document]
508 # Certain fields should be provided within the metadata header;
509 # add these here.
510 metadata = tuple(metadata) + (
511 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
512 )
514 # Send the request.
515 response = rpc(
516 request,
517 retry=retry,
518 timeout=timeout,
519 metadata=metadata,
520 )
522 # Done; return the response.
523 return response
525 def list_documents(
526 self,
527 request: Optional[Union[firestore.ListDocumentsRequest, dict]] = None,
528 *,
529 retry: OptionalRetry = gapic_v1.method.DEFAULT,
530 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
531 metadata: Sequence[Tuple[str, str]] = (),
532 ) -> pagers.ListDocumentsPager:
533 r"""Lists documents.
535 .. code-block:: python
537 # This snippet has been automatically generated and should be regarded as a
538 # code template only.
539 # It will require modifications to work:
540 # - It may require correct/in-range values for request initialization.
541 # - It may require specifying regional endpoints when creating the service
542 # client as shown in:
543 # https://googleapis.dev/python/google-api-core/latest/client_options.html
544 from google.cloud import firestore_v1
546 def sample_list_documents():
547 # Create a client
548 client = firestore_v1.FirestoreClient()
550 # Initialize request argument(s)
551 request = firestore_v1.ListDocumentsRequest(
552 transaction=b'transaction_blob',
553 parent="parent_value",
554 )
556 # Make the request
557 page_result = client.list_documents(request=request)
559 # Handle the response
560 for response in page_result:
561 print(response)
563 Args:
564 request (Union[google.cloud.firestore_v1.types.ListDocumentsRequest, dict]):
565 The request object. The request for
566 [Firestore.ListDocuments][google.firestore.v1.Firestore.ListDocuments].
567 retry (google.api_core.retry.Retry): Designation of what errors, if any,
568 should be retried.
569 timeout (float): The timeout for this request.
570 metadata (Sequence[Tuple[str, str]]): Strings which should be
571 sent along with the request as metadata.
573 Returns:
574 google.cloud.firestore_v1.services.firestore.pagers.ListDocumentsPager:
575 The response for
576 [Firestore.ListDocuments][google.firestore.v1.Firestore.ListDocuments].
578 Iterating over this object will yield results and
579 resolve additional pages automatically.
581 """
582 # Create or coerce a protobuf request object.
583 # Minor optimization to avoid making a copy if the user passes
584 # in a firestore.ListDocumentsRequest.
585 # There's no risk of modifying the input as we've already verified
586 # there are no flattened fields.
587 if not isinstance(request, firestore.ListDocumentsRequest):
588 request = firestore.ListDocumentsRequest(request)
590 # Wrap the RPC method; this adds retry and timeout information,
591 # and friendly error handling.
592 rpc = self._transport._wrapped_methods[self._transport.list_documents]
594 # Certain fields should be provided within the metadata header;
595 # add these here.
596 metadata = tuple(metadata) + (
597 gapic_v1.routing_header.to_grpc_metadata(
598 (
599 ("parent", request.parent),
600 ("collection_id", request.collection_id),
601 )
602 ),
603 )
605 # Send the request.
606 response = rpc(
607 request,
608 retry=retry,
609 timeout=timeout,
610 metadata=metadata,
611 )
613 # This method is paged; wrap the response in a pager, which provides
614 # an `__iter__` convenience method.
615 response = pagers.ListDocumentsPager(
616 method=rpc,
617 request=request,
618 response=response,
619 metadata=metadata,
620 )
622 # Done; return the response.
623 return response
625 def update_document(
626 self,
627 request: Optional[Union[firestore.UpdateDocumentRequest, dict]] = None,
628 *,
629 document: Optional[gf_document.Document] = None,
630 update_mask: Optional[common.DocumentMask] = None,
631 retry: OptionalRetry = gapic_v1.method.DEFAULT,
632 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
633 metadata: Sequence[Tuple[str, str]] = (),
634 ) -> gf_document.Document:
635 r"""Updates or inserts a document.
637 .. code-block:: python
639 # This snippet has been automatically generated and should be regarded as a
640 # code template only.
641 # It will require modifications to work:
642 # - It may require correct/in-range values for request initialization.
643 # - It may require specifying regional endpoints when creating the service
644 # client as shown in:
645 # https://googleapis.dev/python/google-api-core/latest/client_options.html
646 from google.cloud import firestore_v1
648 def sample_update_document():
649 # Create a client
650 client = firestore_v1.FirestoreClient()
652 # Initialize request argument(s)
653 request = firestore_v1.UpdateDocumentRequest(
654 )
656 # Make the request
657 response = client.update_document(request=request)
659 # Handle the response
660 print(response)
662 Args:
663 request (Union[google.cloud.firestore_v1.types.UpdateDocumentRequest, dict]):
664 The request object. The request for
665 [Firestore.UpdateDocument][google.firestore.v1.Firestore.UpdateDocument].
666 document (google.cloud.firestore_v1.types.Document):
667 Required. The updated document.
668 Creates the document if it does not
669 already exist.
671 This corresponds to the ``document`` field
672 on the ``request`` instance; if ``request`` is provided, this
673 should not be set.
674 update_mask (google.cloud.firestore_v1.types.DocumentMask):
675 The fields to update.
676 None of the field paths in the mask may
677 contain a reserved name.
679 If the document exists on the server and
680 has fields not referenced in the mask,
681 they are left unchanged.
682 Fields referenced in the mask, but not
683 present in the input document, are
684 deleted from the document on the server.
686 This corresponds to the ``update_mask`` field
687 on the ``request`` instance; if ``request`` is provided, this
688 should not be set.
689 retry (google.api_core.retry.Retry): Designation of what errors, if any,
690 should be retried.
691 timeout (float): The timeout for this request.
692 metadata (Sequence[Tuple[str, str]]): Strings which should be
693 sent along with the request as metadata.
695 Returns:
696 google.cloud.firestore_v1.types.Document:
697 A Firestore document.
699 Must not exceed 1 MiB - 4 bytes.
701 """
702 # Create or coerce a protobuf request object.
703 # Quick check: If we got a request object, we should *not* have
704 # gotten any keyword arguments that map to the request.
705 has_flattened_params = any([document, update_mask])
706 if request is not None and has_flattened_params:
707 raise ValueError(
708 "If the `request` argument is set, then none of "
709 "the individual field arguments should be set."
710 )
712 # Minor optimization to avoid making a copy if the user passes
713 # in a firestore.UpdateDocumentRequest.
714 # There's no risk of modifying the input as we've already verified
715 # there are no flattened fields.
716 if not isinstance(request, firestore.UpdateDocumentRequest):
717 request = firestore.UpdateDocumentRequest(request)
718 # If we have keyword arguments corresponding to fields on the
719 # request, apply these.
720 if document is not None:
721 request.document = document
722 if update_mask is not None:
723 request.update_mask = update_mask
725 # Wrap the RPC method; this adds retry and timeout information,
726 # and friendly error handling.
727 rpc = self._transport._wrapped_methods[self._transport.update_document]
729 # Certain fields should be provided within the metadata header;
730 # add these here.
731 metadata = tuple(metadata) + (
732 gapic_v1.routing_header.to_grpc_metadata(
733 (("document.name", request.document.name),)
734 ),
735 )
737 # Send the request.
738 response = rpc(
739 request,
740 retry=retry,
741 timeout=timeout,
742 metadata=metadata,
743 )
745 # Done; return the response.
746 return response
748 def delete_document(
749 self,
750 request: Optional[Union[firestore.DeleteDocumentRequest, dict]] = None,
751 *,
752 name: Optional[str] = None,
753 retry: OptionalRetry = gapic_v1.method.DEFAULT,
754 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
755 metadata: Sequence[Tuple[str, str]] = (),
756 ) -> None:
757 r"""Deletes a document.
759 .. code-block:: python
761 # This snippet has been automatically generated and should be regarded as a
762 # code template only.
763 # It will require modifications to work:
764 # - It may require correct/in-range values for request initialization.
765 # - It may require specifying regional endpoints when creating the service
766 # client as shown in:
767 # https://googleapis.dev/python/google-api-core/latest/client_options.html
768 from google.cloud import firestore_v1
770 def sample_delete_document():
771 # Create a client
772 client = firestore_v1.FirestoreClient()
774 # Initialize request argument(s)
775 request = firestore_v1.DeleteDocumentRequest(
776 name="name_value",
777 )
779 # Make the request
780 client.delete_document(request=request)
782 Args:
783 request (Union[google.cloud.firestore_v1.types.DeleteDocumentRequest, dict]):
784 The request object. The request for
785 [Firestore.DeleteDocument][google.firestore.v1.Firestore.DeleteDocument].
786 name (str):
787 Required. The resource name of the Document to delete.
788 In the format:
789 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
791 This corresponds to the ``name`` field
792 on the ``request`` instance; if ``request`` is provided, this
793 should not be set.
794 retry (google.api_core.retry.Retry): Designation of what errors, if any,
795 should be retried.
796 timeout (float): The timeout for this request.
797 metadata (Sequence[Tuple[str, str]]): Strings which should be
798 sent along with the request as metadata.
799 """
800 # Create or coerce a protobuf request object.
801 # Quick check: If we got a request object, we should *not* have
802 # gotten any keyword arguments that map to the request.
803 has_flattened_params = any([name])
804 if request is not None and has_flattened_params:
805 raise ValueError(
806 "If the `request` argument is set, then none of "
807 "the individual field arguments should be set."
808 )
810 # Minor optimization to avoid making a copy if the user passes
811 # in a firestore.DeleteDocumentRequest.
812 # There's no risk of modifying the input as we've already verified
813 # there are no flattened fields.
814 if not isinstance(request, firestore.DeleteDocumentRequest):
815 request = firestore.DeleteDocumentRequest(request)
816 # If we have keyword arguments corresponding to fields on the
817 # request, apply these.
818 if name is not None:
819 request.name = name
821 # Wrap the RPC method; this adds retry and timeout information,
822 # and friendly error handling.
823 rpc = self._transport._wrapped_methods[self._transport.delete_document]
825 # Certain fields should be provided within the metadata header;
826 # add these here.
827 metadata = tuple(metadata) + (
828 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
829 )
831 # Send the request.
832 rpc(
833 request,
834 retry=retry,
835 timeout=timeout,
836 metadata=metadata,
837 )
839 def batch_get_documents(
840 self,
841 request: Optional[Union[firestore.BatchGetDocumentsRequest, dict]] = None,
842 *,
843 retry: OptionalRetry = gapic_v1.method.DEFAULT,
844 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
845 metadata: Sequence[Tuple[str, str]] = (),
846 ) -> Iterable[firestore.BatchGetDocumentsResponse]:
847 r"""Gets multiple documents.
849 Documents returned by this method are not guaranteed to
850 be returned in the same order that they were requested.
852 .. code-block:: python
854 # This snippet has been automatically generated and should be regarded as a
855 # code template only.
856 # It will require modifications to work:
857 # - It may require correct/in-range values for request initialization.
858 # - It may require specifying regional endpoints when creating the service
859 # client as shown in:
860 # https://googleapis.dev/python/google-api-core/latest/client_options.html
861 from google.cloud import firestore_v1
863 def sample_batch_get_documents():
864 # Create a client
865 client = firestore_v1.FirestoreClient()
867 # Initialize request argument(s)
868 request = firestore_v1.BatchGetDocumentsRequest(
869 transaction=b'transaction_blob',
870 database="database_value",
871 )
873 # Make the request
874 stream = client.batch_get_documents(request=request)
876 # Handle the response
877 for response in stream:
878 print(response)
880 Args:
881 request (Union[google.cloud.firestore_v1.types.BatchGetDocumentsRequest, dict]):
882 The request object. The request for
883 [Firestore.BatchGetDocuments][google.firestore.v1.Firestore.BatchGetDocuments].
884 retry (google.api_core.retry.Retry): Designation of what errors, if any,
885 should be retried.
886 timeout (float): The timeout for this request.
887 metadata (Sequence[Tuple[str, str]]): Strings which should be
888 sent along with the request as metadata.
890 Returns:
891 Iterable[google.cloud.firestore_v1.types.BatchGetDocumentsResponse]:
892 The streamed response for
893 [Firestore.BatchGetDocuments][google.firestore.v1.Firestore.BatchGetDocuments].
895 """
896 # Create or coerce a protobuf request object.
897 # Minor optimization to avoid making a copy if the user passes
898 # in a firestore.BatchGetDocumentsRequest.
899 # There's no risk of modifying the input as we've already verified
900 # there are no flattened fields.
901 if not isinstance(request, firestore.BatchGetDocumentsRequest):
902 request = firestore.BatchGetDocumentsRequest(request)
904 # Wrap the RPC method; this adds retry and timeout information,
905 # and friendly error handling.
906 rpc = self._transport._wrapped_methods[self._transport.batch_get_documents]
908 # Certain fields should be provided within the metadata header;
909 # add these here.
910 metadata = tuple(metadata) + (
911 gapic_v1.routing_header.to_grpc_metadata((("database", request.database),)),
912 )
914 # Send the request.
915 response = rpc(
916 request,
917 retry=retry,
918 timeout=timeout,
919 metadata=metadata,
920 )
922 # Done; return the response.
923 return response
925 def begin_transaction(
926 self,
927 request: Optional[Union[firestore.BeginTransactionRequest, dict]] = None,
928 *,
929 database: Optional[str] = None,
930 retry: OptionalRetry = gapic_v1.method.DEFAULT,
931 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
932 metadata: Sequence[Tuple[str, str]] = (),
933 ) -> firestore.BeginTransactionResponse:
934 r"""Starts a new transaction.
936 .. code-block:: python
938 # This snippet has been automatically generated and should be regarded as a
939 # code template only.
940 # It will require modifications to work:
941 # - It may require correct/in-range values for request initialization.
942 # - It may require specifying regional endpoints when creating the service
943 # client as shown in:
944 # https://googleapis.dev/python/google-api-core/latest/client_options.html
945 from google.cloud import firestore_v1
947 def sample_begin_transaction():
948 # Create a client
949 client = firestore_v1.FirestoreClient()
951 # Initialize request argument(s)
952 request = firestore_v1.BeginTransactionRequest(
953 database="database_value",
954 )
956 # Make the request
957 response = client.begin_transaction(request=request)
959 # Handle the response
960 print(response)
962 Args:
963 request (Union[google.cloud.firestore_v1.types.BeginTransactionRequest, dict]):
964 The request object. The request for
965 [Firestore.BeginTransaction][google.firestore.v1.Firestore.BeginTransaction].
966 database (str):
967 Required. The database name. In the format:
968 ``projects/{project_id}/databases/{database_id}``.
970 This corresponds to the ``database`` field
971 on the ``request`` instance; if ``request`` is provided, this
972 should not be set.
973 retry (google.api_core.retry.Retry): Designation of what errors, if any,
974 should be retried.
975 timeout (float): The timeout for this request.
976 metadata (Sequence[Tuple[str, str]]): Strings which should be
977 sent along with the request as metadata.
979 Returns:
980 google.cloud.firestore_v1.types.BeginTransactionResponse:
981 The response for
982 [Firestore.BeginTransaction][google.firestore.v1.Firestore.BeginTransaction].
984 """
985 # Create or coerce a protobuf request object.
986 # Quick check: If we got a request object, we should *not* have
987 # gotten any keyword arguments that map to the request.
988 has_flattened_params = any([database])
989 if request is not None and has_flattened_params:
990 raise ValueError(
991 "If the `request` argument is set, then none of "
992 "the individual field arguments should be set."
993 )
995 # Minor optimization to avoid making a copy if the user passes
996 # in a firestore.BeginTransactionRequest.
997 # There's no risk of modifying the input as we've already verified
998 # there are no flattened fields.
999 if not isinstance(request, firestore.BeginTransactionRequest):
1000 request = firestore.BeginTransactionRequest(request)
1001 # If we have keyword arguments corresponding to fields on the
1002 # request, apply these.
1003 if database is not None:
1004 request.database = database
1006 # Wrap the RPC method; this adds retry and timeout information,
1007 # and friendly error handling.
1008 rpc = self._transport._wrapped_methods[self._transport.begin_transaction]
1010 # Certain fields should be provided within the metadata header;
1011 # add these here.
1012 metadata = tuple(metadata) + (
1013 gapic_v1.routing_header.to_grpc_metadata((("database", request.database),)),
1014 )
1016 # Send the request.
1017 response = rpc(
1018 request,
1019 retry=retry,
1020 timeout=timeout,
1021 metadata=metadata,
1022 )
1024 # Done; return the response.
1025 return response
1027 def commit(
1028 self,
1029 request: Optional[Union[firestore.CommitRequest, dict]] = None,
1030 *,
1031 database: Optional[str] = None,
1032 writes: Optional[MutableSequence[gf_write.Write]] = None,
1033 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1034 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1035 metadata: Sequence[Tuple[str, str]] = (),
1036 ) -> firestore.CommitResponse:
1037 r"""Commits a transaction, while optionally updating
1038 documents.
1040 .. code-block:: python
1042 # This snippet has been automatically generated and should be regarded as a
1043 # code template only.
1044 # It will require modifications to work:
1045 # - It may require correct/in-range values for request initialization.
1046 # - It may require specifying regional endpoints when creating the service
1047 # client as shown in:
1048 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1049 from google.cloud import firestore_v1
1051 def sample_commit():
1052 # Create a client
1053 client = firestore_v1.FirestoreClient()
1055 # Initialize request argument(s)
1056 request = firestore_v1.CommitRequest(
1057 database="database_value",
1058 )
1060 # Make the request
1061 response = client.commit(request=request)
1063 # Handle the response
1064 print(response)
1066 Args:
1067 request (Union[google.cloud.firestore_v1.types.CommitRequest, dict]):
1068 The request object. The request for
1069 [Firestore.Commit][google.firestore.v1.Firestore.Commit].
1070 database (str):
1071 Required. The database name. In the format:
1072 ``projects/{project_id}/databases/{database_id}``.
1074 This corresponds to the ``database`` field
1075 on the ``request`` instance; if ``request`` is provided, this
1076 should not be set.
1077 writes (MutableSequence[google.cloud.firestore_v1.types.Write]):
1078 The writes to apply.
1080 Always executed atomically and in order.
1082 This corresponds to the ``writes`` field
1083 on the ``request`` instance; if ``request`` is provided, this
1084 should not be set.
1085 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1086 should be retried.
1087 timeout (float): The timeout for this request.
1088 metadata (Sequence[Tuple[str, str]]): Strings which should be
1089 sent along with the request as metadata.
1091 Returns:
1092 google.cloud.firestore_v1.types.CommitResponse:
1093 The response for
1094 [Firestore.Commit][google.firestore.v1.Firestore.Commit].
1096 """
1097 # Create or coerce a protobuf request object.
1098 # Quick check: If we got a request object, we should *not* have
1099 # gotten any keyword arguments that map to the request.
1100 has_flattened_params = any([database, writes])
1101 if request is not None and has_flattened_params:
1102 raise ValueError(
1103 "If the `request` argument is set, then none of "
1104 "the individual field arguments should be set."
1105 )
1107 # Minor optimization to avoid making a copy if the user passes
1108 # in a firestore.CommitRequest.
1109 # There's no risk of modifying the input as we've already verified
1110 # there are no flattened fields.
1111 if not isinstance(request, firestore.CommitRequest):
1112 request = firestore.CommitRequest(request)
1113 # If we have keyword arguments corresponding to fields on the
1114 # request, apply these.
1115 if database is not None:
1116 request.database = database
1117 if writes is not None:
1118 request.writes = writes
1120 # Wrap the RPC method; this adds retry and timeout information,
1121 # and friendly error handling.
1122 rpc = self._transport._wrapped_methods[self._transport.commit]
1124 # Certain fields should be provided within the metadata header;
1125 # add these here.
1126 metadata = tuple(metadata) + (
1127 gapic_v1.routing_header.to_grpc_metadata((("database", request.database),)),
1128 )
1130 # Send the request.
1131 response = rpc(
1132 request,
1133 retry=retry,
1134 timeout=timeout,
1135 metadata=metadata,
1136 )
1138 # Done; return the response.
1139 return response
1141 def rollback(
1142 self,
1143 request: Optional[Union[firestore.RollbackRequest, dict]] = None,
1144 *,
1145 database: Optional[str] = None,
1146 transaction: Optional[bytes] = None,
1147 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1148 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1149 metadata: Sequence[Tuple[str, str]] = (),
1150 ) -> None:
1151 r"""Rolls back a transaction.
1153 .. code-block:: python
1155 # This snippet has been automatically generated and should be regarded as a
1156 # code template only.
1157 # It will require modifications to work:
1158 # - It may require correct/in-range values for request initialization.
1159 # - It may require specifying regional endpoints when creating the service
1160 # client as shown in:
1161 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1162 from google.cloud import firestore_v1
1164 def sample_rollback():
1165 # Create a client
1166 client = firestore_v1.FirestoreClient()
1168 # Initialize request argument(s)
1169 request = firestore_v1.RollbackRequest(
1170 database="database_value",
1171 transaction=b'transaction_blob',
1172 )
1174 # Make the request
1175 client.rollback(request=request)
1177 Args:
1178 request (Union[google.cloud.firestore_v1.types.RollbackRequest, dict]):
1179 The request object. The request for
1180 [Firestore.Rollback][google.firestore.v1.Firestore.Rollback].
1181 database (str):
1182 Required. The database name. In the format:
1183 ``projects/{project_id}/databases/{database_id}``.
1185 This corresponds to the ``database`` field
1186 on the ``request`` instance; if ``request`` is provided, this
1187 should not be set.
1188 transaction (bytes):
1189 Required. The transaction to roll
1190 back.
1192 This corresponds to the ``transaction`` field
1193 on the ``request`` instance; if ``request`` is provided, this
1194 should not be set.
1195 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1196 should be retried.
1197 timeout (float): The timeout for this request.
1198 metadata (Sequence[Tuple[str, str]]): Strings which should be
1199 sent along with the request as metadata.
1200 """
1201 # Create or coerce a protobuf request object.
1202 # Quick check: If we got a request object, we should *not* have
1203 # gotten any keyword arguments that map to the request.
1204 has_flattened_params = any([database, transaction])
1205 if request is not None and has_flattened_params:
1206 raise ValueError(
1207 "If the `request` argument is set, then none of "
1208 "the individual field arguments should be set."
1209 )
1211 # Minor optimization to avoid making a copy if the user passes
1212 # in a firestore.RollbackRequest.
1213 # There's no risk of modifying the input as we've already verified
1214 # there are no flattened fields.
1215 if not isinstance(request, firestore.RollbackRequest):
1216 request = firestore.RollbackRequest(request)
1217 # If we have keyword arguments corresponding to fields on the
1218 # request, apply these.
1219 if database is not None:
1220 request.database = database
1221 if transaction is not None:
1222 request.transaction = transaction
1224 # Wrap the RPC method; this adds retry and timeout information,
1225 # and friendly error handling.
1226 rpc = self._transport._wrapped_methods[self._transport.rollback]
1228 # Certain fields should be provided within the metadata header;
1229 # add these here.
1230 metadata = tuple(metadata) + (
1231 gapic_v1.routing_header.to_grpc_metadata((("database", request.database),)),
1232 )
1234 # Send the request.
1235 rpc(
1236 request,
1237 retry=retry,
1238 timeout=timeout,
1239 metadata=metadata,
1240 )
1242 def run_query(
1243 self,
1244 request: Optional[Union[firestore.RunQueryRequest, dict]] = None,
1245 *,
1246 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1247 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1248 metadata: Sequence[Tuple[str, str]] = (),
1249 ) -> Iterable[firestore.RunQueryResponse]:
1250 r"""Runs a query.
1252 .. code-block:: python
1254 # This snippet has been automatically generated and should be regarded as a
1255 # code template only.
1256 # It will require modifications to work:
1257 # - It may require correct/in-range values for request initialization.
1258 # - It may require specifying regional endpoints when creating the service
1259 # client as shown in:
1260 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1261 from google.cloud import firestore_v1
1263 def sample_run_query():
1264 # Create a client
1265 client = firestore_v1.FirestoreClient()
1267 # Initialize request argument(s)
1268 request = firestore_v1.RunQueryRequest(
1269 transaction=b'transaction_blob',
1270 parent="parent_value",
1271 )
1273 # Make the request
1274 stream = client.run_query(request=request)
1276 # Handle the response
1277 for response in stream:
1278 print(response)
1280 Args:
1281 request (Union[google.cloud.firestore_v1.types.RunQueryRequest, dict]):
1282 The request object. The request for
1283 [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery].
1284 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1285 should be retried.
1286 timeout (float): The timeout for this request.
1287 metadata (Sequence[Tuple[str, str]]): Strings which should be
1288 sent along with the request as metadata.
1290 Returns:
1291 Iterable[google.cloud.firestore_v1.types.RunQueryResponse]:
1292 The response for
1293 [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery].
1295 """
1296 # Create or coerce a protobuf request object.
1297 # Minor optimization to avoid making a copy if the user passes
1298 # in a firestore.RunQueryRequest.
1299 # There's no risk of modifying the input as we've already verified
1300 # there are no flattened fields.
1301 if not isinstance(request, firestore.RunQueryRequest):
1302 request = firestore.RunQueryRequest(request)
1304 # Wrap the RPC method; this adds retry and timeout information,
1305 # and friendly error handling.
1306 rpc = self._transport._wrapped_methods[self._transport.run_query]
1308 # Certain fields should be provided within the metadata header;
1309 # add these here.
1310 metadata = tuple(metadata) + (
1311 gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
1312 )
1314 # Send the request.
1315 response = rpc(
1316 request,
1317 retry=retry,
1318 timeout=timeout,
1319 metadata=metadata,
1320 )
1322 # Done; return the response.
1323 return response
1325 def run_aggregation_query(
1326 self,
1327 request: Optional[Union[firestore.RunAggregationQueryRequest, dict]] = None,
1328 *,
1329 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1330 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1331 metadata: Sequence[Tuple[str, str]] = (),
1332 ) -> Iterable[firestore.RunAggregationQueryResponse]:
1333 r"""Runs an aggregation query.
1335 Rather than producing [Document][google.firestore.v1.Document]
1336 results like
1337 [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery],
1338 this API allows running an aggregation to produce a series of
1339 [AggregationResult][google.firestore.v1.AggregationResult]
1340 server-side.
1342 High-Level Example:
1344 ::
1346 -- Return the number of documents in table given a filter.
1347 SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
1349 .. code-block:: python
1351 # This snippet has been automatically generated and should be regarded as a
1352 # code template only.
1353 # It will require modifications to work:
1354 # - It may require correct/in-range values for request initialization.
1355 # - It may require specifying regional endpoints when creating the service
1356 # client as shown in:
1357 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1358 from google.cloud import firestore_v1
1360 def sample_run_aggregation_query():
1361 # Create a client
1362 client = firestore_v1.FirestoreClient()
1364 # Initialize request argument(s)
1365 request = firestore_v1.RunAggregationQueryRequest(
1366 transaction=b'transaction_blob',
1367 parent="parent_value",
1368 )
1370 # Make the request
1371 stream = client.run_aggregation_query(request=request)
1373 # Handle the response
1374 for response in stream:
1375 print(response)
1377 Args:
1378 request (Union[google.cloud.firestore_v1.types.RunAggregationQueryRequest, dict]):
1379 The request object. The request for
1380 [Firestore.RunAggregationQuery][google.firestore.v1.Firestore.RunAggregationQuery].
1381 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1382 should be retried.
1383 timeout (float): The timeout for this request.
1384 metadata (Sequence[Tuple[str, str]]): Strings which should be
1385 sent along with the request as metadata.
1387 Returns:
1388 Iterable[google.cloud.firestore_v1.types.RunAggregationQueryResponse]:
1389 The response for
1390 [Firestore.RunAggregationQuery][google.firestore.v1.Firestore.RunAggregationQuery].
1392 """
1393 # Create or coerce a protobuf request object.
1394 # Minor optimization to avoid making a copy if the user passes
1395 # in a firestore.RunAggregationQueryRequest.
1396 # There's no risk of modifying the input as we've already verified
1397 # there are no flattened fields.
1398 if not isinstance(request, firestore.RunAggregationQueryRequest):
1399 request = firestore.RunAggregationQueryRequest(request)
1401 # Wrap the RPC method; this adds retry and timeout information,
1402 # and friendly error handling.
1403 rpc = self._transport._wrapped_methods[self._transport.run_aggregation_query]
1405 # Certain fields should be provided within the metadata header;
1406 # add these here.
1407 metadata = tuple(metadata) + (
1408 gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
1409 )
1411 # Send the request.
1412 response = rpc(
1413 request,
1414 retry=retry,
1415 timeout=timeout,
1416 metadata=metadata,
1417 )
1419 # Done; return the response.
1420 return response
1422 def partition_query(
1423 self,
1424 request: Optional[Union[firestore.PartitionQueryRequest, dict]] = None,
1425 *,
1426 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1427 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1428 metadata: Sequence[Tuple[str, str]] = (),
1429 ) -> pagers.PartitionQueryPager:
1430 r"""Partitions a query by returning partition cursors
1431 that can be used to run the query in parallel. The
1432 returned partition cursors are split points that can be
1433 used by RunQuery as starting/end points for the query
1434 results.
1436 .. code-block:: python
1438 # This snippet has been automatically generated and should be regarded as a
1439 # code template only.
1440 # It will require modifications to work:
1441 # - It may require correct/in-range values for request initialization.
1442 # - It may require specifying regional endpoints when creating the service
1443 # client as shown in:
1444 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1445 from google.cloud import firestore_v1
1447 def sample_partition_query():
1448 # Create a client
1449 client = firestore_v1.FirestoreClient()
1451 # Initialize request argument(s)
1452 request = firestore_v1.PartitionQueryRequest(
1453 parent="parent_value",
1454 )
1456 # Make the request
1457 page_result = client.partition_query(request=request)
1459 # Handle the response
1460 for response in page_result:
1461 print(response)
1463 Args:
1464 request (Union[google.cloud.firestore_v1.types.PartitionQueryRequest, dict]):
1465 The request object. The request for
1466 [Firestore.PartitionQuery][google.firestore.v1.Firestore.PartitionQuery].
1467 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1468 should be retried.
1469 timeout (float): The timeout for this request.
1470 metadata (Sequence[Tuple[str, str]]): Strings which should be
1471 sent along with the request as metadata.
1473 Returns:
1474 google.cloud.firestore_v1.services.firestore.pagers.PartitionQueryPager:
1475 The response for
1476 [Firestore.PartitionQuery][google.firestore.v1.Firestore.PartitionQuery].
1478 Iterating over this object will yield results and
1479 resolve additional pages automatically.
1481 """
1482 # Create or coerce a protobuf request object.
1483 # Minor optimization to avoid making a copy if the user passes
1484 # in a firestore.PartitionQueryRequest.
1485 # There's no risk of modifying the input as we've already verified
1486 # there are no flattened fields.
1487 if not isinstance(request, firestore.PartitionQueryRequest):
1488 request = firestore.PartitionQueryRequest(request)
1490 # Wrap the RPC method; this adds retry and timeout information,
1491 # and friendly error handling.
1492 rpc = self._transport._wrapped_methods[self._transport.partition_query]
1494 # Certain fields should be provided within the metadata header;
1495 # add these here.
1496 metadata = tuple(metadata) + (
1497 gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
1498 )
1500 # Send the request.
1501 response = rpc(
1502 request,
1503 retry=retry,
1504 timeout=timeout,
1505 metadata=metadata,
1506 )
1508 # This method is paged; wrap the response in a pager, which provides
1509 # an `__iter__` convenience method.
1510 response = pagers.PartitionQueryPager(
1511 method=rpc,
1512 request=request,
1513 response=response,
1514 metadata=metadata,
1515 )
1517 # Done; return the response.
1518 return response
1520 def write(
1521 self,
1522 requests: Optional[Iterator[firestore.WriteRequest]] = None,
1523 *,
1524 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1525 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1526 metadata: Sequence[Tuple[str, str]] = (),
1527 ) -> Iterable[firestore.WriteResponse]:
1528 r"""Streams batches of document updates and deletes, in
1529 order. This method is only available via gRPC or
1530 WebChannel (not REST).
1532 .. code-block:: python
1534 # This snippet has been automatically generated and should be regarded as a
1535 # code template only.
1536 # It will require modifications to work:
1537 # - It may require correct/in-range values for request initialization.
1538 # - It may require specifying regional endpoints when creating the service
1539 # client as shown in:
1540 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1541 from google.cloud import firestore_v1
1543 def sample_write():
1544 # Create a client
1545 client = firestore_v1.FirestoreClient()
1547 # Initialize request argument(s)
1548 request = firestore_v1.WriteRequest(
1549 database="database_value",
1550 )
1552 # This method expects an iterator which contains
1553 # 'firestore_v1.WriteRequest' objects
1554 # Here we create a generator that yields a single `request` for
1555 # demonstrative purposes.
1556 requests = [request]
1558 def request_generator():
1559 for request in requests:
1560 yield request
1562 # Make the request
1563 stream = client.write(requests=request_generator())
1565 # Handle the response
1566 for response in stream:
1567 print(response)
1569 Args:
1570 requests (Iterator[google.cloud.firestore_v1.types.WriteRequest]):
1571 The request object iterator. The request for
1572 [Firestore.Write][google.firestore.v1.Firestore.Write].
1574 The first request creates a stream, or resumes an
1575 existing one from a token.
1577 When creating a new stream, the server replies with a
1578 response containing only an ID and a token, to use in
1579 the next request.
1581 When resuming a stream, the server first streams any
1582 responses later than the given token, then a response
1583 containing only an up-to-date token, to use in the next
1584 request.
1585 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1586 should be retried.
1587 timeout (float): The timeout for this request.
1588 metadata (Sequence[Tuple[str, str]]): Strings which should be
1589 sent along with the request as metadata.
1591 Returns:
1592 Iterable[google.cloud.firestore_v1.types.WriteResponse]:
1593 The response for
1594 [Firestore.Write][google.firestore.v1.Firestore.Write].
1596 """
1598 # Wrap the RPC method; this adds retry and timeout information,
1599 # and friendly error handling.
1600 rpc = self._transport._wrapped_methods[self._transport.write]
1602 # Certain fields should be provided within the metadata header;
1603 # add these here.
1604 metadata = tuple(metadata) + (gapic_v1.routing_header.to_grpc_metadata(()),)
1606 # Send the request.
1607 response = rpc(
1608 requests,
1609 retry=retry,
1610 timeout=timeout,
1611 metadata=metadata,
1612 )
1614 # Done; return the response.
1615 return response
1617 def listen(
1618 self,
1619 requests: Optional[Iterator[firestore.ListenRequest]] = None,
1620 *,
1621 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1622 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1623 metadata: Sequence[Tuple[str, str]] = (),
1624 ) -> Iterable[firestore.ListenResponse]:
1625 r"""Listens to changes. This method is only available via
1626 gRPC or WebChannel (not REST).
1628 .. code-block:: python
1630 # This snippet has been automatically generated and should be regarded as a
1631 # code template only.
1632 # It will require modifications to work:
1633 # - It may require correct/in-range values for request initialization.
1634 # - It may require specifying regional endpoints when creating the service
1635 # client as shown in:
1636 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1637 from google.cloud import firestore_v1
1639 def sample_listen():
1640 # Create a client
1641 client = firestore_v1.FirestoreClient()
1643 # Initialize request argument(s)
1644 add_target = firestore_v1.Target()
1645 add_target.resume_token = b'resume_token_blob'
1647 request = firestore_v1.ListenRequest(
1648 add_target=add_target,
1649 database="database_value",
1650 )
1652 # This method expects an iterator which contains
1653 # 'firestore_v1.ListenRequest' objects
1654 # Here we create a generator that yields a single `request` for
1655 # demonstrative purposes.
1656 requests = [request]
1658 def request_generator():
1659 for request in requests:
1660 yield request
1662 # Make the request
1663 stream = client.listen(requests=request_generator())
1665 # Handle the response
1666 for response in stream:
1667 print(response)
1669 Args:
1670 requests (Iterator[google.cloud.firestore_v1.types.ListenRequest]):
1671 The request object iterator. A request for
1672 [Firestore.Listen][google.firestore.v1.Firestore.Listen]
1673 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1674 should be retried.
1675 timeout (float): The timeout for this request.
1676 metadata (Sequence[Tuple[str, str]]): Strings which should be
1677 sent along with the request as metadata.
1679 Returns:
1680 Iterable[google.cloud.firestore_v1.types.ListenResponse]:
1681 The response for
1682 [Firestore.Listen][google.firestore.v1.Firestore.Listen].
1684 """
1686 # Wrap the RPC method; this adds retry and timeout information,
1687 # and friendly error handling.
1688 rpc = self._transport._wrapped_methods[self._transport.listen]
1690 # Certain fields should be provided within the metadata header;
1691 # add these here.
1692 metadata = tuple(metadata) + (gapic_v1.routing_header.to_grpc_metadata(()),)
1694 # Send the request.
1695 response = rpc(
1696 requests,
1697 retry=retry,
1698 timeout=timeout,
1699 metadata=metadata,
1700 )
1702 # Done; return the response.
1703 return response
1705 def list_collection_ids(
1706 self,
1707 request: Optional[Union[firestore.ListCollectionIdsRequest, dict]] = None,
1708 *,
1709 parent: Optional[str] = None,
1710 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1711 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1712 metadata: Sequence[Tuple[str, str]] = (),
1713 ) -> pagers.ListCollectionIdsPager:
1714 r"""Lists all the collection IDs underneath a document.
1716 .. code-block:: python
1718 # This snippet has been automatically generated and should be regarded as a
1719 # code template only.
1720 # It will require modifications to work:
1721 # - It may require correct/in-range values for request initialization.
1722 # - It may require specifying regional endpoints when creating the service
1723 # client as shown in:
1724 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1725 from google.cloud import firestore_v1
1727 def sample_list_collection_ids():
1728 # Create a client
1729 client = firestore_v1.FirestoreClient()
1731 # Initialize request argument(s)
1732 request = firestore_v1.ListCollectionIdsRequest(
1733 parent="parent_value",
1734 )
1736 # Make the request
1737 page_result = client.list_collection_ids(request=request)
1739 # Handle the response
1740 for response in page_result:
1741 print(response)
1743 Args:
1744 request (Union[google.cloud.firestore_v1.types.ListCollectionIdsRequest, dict]):
1745 The request object. The request for
1746 [Firestore.ListCollectionIds][google.firestore.v1.Firestore.ListCollectionIds].
1747 parent (str):
1748 Required. The parent document. In the format:
1749 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
1750 For example:
1751 ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom``
1753 This corresponds to the ``parent`` field
1754 on the ``request`` instance; if ``request`` is provided, this
1755 should not be set.
1756 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1757 should be retried.
1758 timeout (float): The timeout for this request.
1759 metadata (Sequence[Tuple[str, str]]): Strings which should be
1760 sent along with the request as metadata.
1762 Returns:
1763 google.cloud.firestore_v1.services.firestore.pagers.ListCollectionIdsPager:
1764 The response from
1765 [Firestore.ListCollectionIds][google.firestore.v1.Firestore.ListCollectionIds].
1767 Iterating over this object will yield results and
1768 resolve additional pages automatically.
1770 """
1771 # Create or coerce a protobuf request object.
1772 # Quick check: If we got a request object, we should *not* have
1773 # gotten any keyword arguments that map to the request.
1774 has_flattened_params = any([parent])
1775 if request is not None and has_flattened_params:
1776 raise ValueError(
1777 "If the `request` argument is set, then none of "
1778 "the individual field arguments should be set."
1779 )
1781 # Minor optimization to avoid making a copy if the user passes
1782 # in a firestore.ListCollectionIdsRequest.
1783 # There's no risk of modifying the input as we've already verified
1784 # there are no flattened fields.
1785 if not isinstance(request, firestore.ListCollectionIdsRequest):
1786 request = firestore.ListCollectionIdsRequest(request)
1787 # If we have keyword arguments corresponding to fields on the
1788 # request, apply these.
1789 if parent is not None:
1790 request.parent = parent
1792 # Wrap the RPC method; this adds retry and timeout information,
1793 # and friendly error handling.
1794 rpc = self._transport._wrapped_methods[self._transport.list_collection_ids]
1796 # Certain fields should be provided within the metadata header;
1797 # add these here.
1798 metadata = tuple(metadata) + (
1799 gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
1800 )
1802 # Send the request.
1803 response = rpc(
1804 request,
1805 retry=retry,
1806 timeout=timeout,
1807 metadata=metadata,
1808 )
1810 # This method is paged; wrap the response in a pager, which provides
1811 # an `__iter__` convenience method.
1812 response = pagers.ListCollectionIdsPager(
1813 method=rpc,
1814 request=request,
1815 response=response,
1816 metadata=metadata,
1817 )
1819 # Done; return the response.
1820 return response
1822 def batch_write(
1823 self,
1824 request: Optional[Union[firestore.BatchWriteRequest, dict]] = None,
1825 *,
1826 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1827 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1828 metadata: Sequence[Tuple[str, str]] = (),
1829 ) -> firestore.BatchWriteResponse:
1830 r"""Applies a batch of write operations.
1832 The BatchWrite method does not apply the write operations
1833 atomically and can apply them out of order. Method does not
1834 allow more than one write per document. Each write succeeds or
1835 fails independently. See the
1836 [BatchWriteResponse][google.firestore.v1.BatchWriteResponse] for
1837 the success status of each write.
1839 If you require an atomically applied set of writes, use
1840 [Commit][google.firestore.v1.Firestore.Commit] instead.
1842 .. code-block:: python
1844 # This snippet has been automatically generated and should be regarded as a
1845 # code template only.
1846 # It will require modifications to work:
1847 # - It may require correct/in-range values for request initialization.
1848 # - It may require specifying regional endpoints when creating the service
1849 # client as shown in:
1850 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1851 from google.cloud import firestore_v1
1853 def sample_batch_write():
1854 # Create a client
1855 client = firestore_v1.FirestoreClient()
1857 # Initialize request argument(s)
1858 request = firestore_v1.BatchWriteRequest(
1859 database="database_value",
1860 )
1862 # Make the request
1863 response = client.batch_write(request=request)
1865 # Handle the response
1866 print(response)
1868 Args:
1869 request (Union[google.cloud.firestore_v1.types.BatchWriteRequest, dict]):
1870 The request object. The request for
1871 [Firestore.BatchWrite][google.firestore.v1.Firestore.BatchWrite].
1872 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1873 should be retried.
1874 timeout (float): The timeout for this request.
1875 metadata (Sequence[Tuple[str, str]]): Strings which should be
1876 sent along with the request as metadata.
1878 Returns:
1879 google.cloud.firestore_v1.types.BatchWriteResponse:
1880 The response from
1881 [Firestore.BatchWrite][google.firestore.v1.Firestore.BatchWrite].
1883 """
1884 # Create or coerce a protobuf request object.
1885 # Minor optimization to avoid making a copy if the user passes
1886 # in a firestore.BatchWriteRequest.
1887 # There's no risk of modifying the input as we've already verified
1888 # there are no flattened fields.
1889 if not isinstance(request, firestore.BatchWriteRequest):
1890 request = firestore.BatchWriteRequest(request)
1892 # Wrap the RPC method; this adds retry and timeout information,
1893 # and friendly error handling.
1894 rpc = self._transport._wrapped_methods[self._transport.batch_write]
1896 # Certain fields should be provided within the metadata header;
1897 # add these here.
1898 metadata = tuple(metadata) + (
1899 gapic_v1.routing_header.to_grpc_metadata((("database", request.database),)),
1900 )
1902 # Send the request.
1903 response = rpc(
1904 request,
1905 retry=retry,
1906 timeout=timeout,
1907 metadata=metadata,
1908 )
1910 # Done; return the response.
1911 return response
1913 def create_document(
1914 self,
1915 request: Optional[Union[firestore.CreateDocumentRequest, dict]] = None,
1916 *,
1917 retry: OptionalRetry = gapic_v1.method.DEFAULT,
1918 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
1919 metadata: Sequence[Tuple[str, str]] = (),
1920 ) -> document.Document:
1921 r"""Creates a new document.
1923 .. code-block:: python
1925 # This snippet has been automatically generated and should be regarded as a
1926 # code template only.
1927 # It will require modifications to work:
1928 # - It may require correct/in-range values for request initialization.
1929 # - It may require specifying regional endpoints when creating the service
1930 # client as shown in:
1931 # https://googleapis.dev/python/google-api-core/latest/client_options.html
1932 from google.cloud import firestore_v1
1934 def sample_create_document():
1935 # Create a client
1936 client = firestore_v1.FirestoreClient()
1938 # Initialize request argument(s)
1939 request = firestore_v1.CreateDocumentRequest(
1940 parent="parent_value",
1941 collection_id="collection_id_value",
1942 )
1944 # Make the request
1945 response = client.create_document(request=request)
1947 # Handle the response
1948 print(response)
1950 Args:
1951 request (Union[google.cloud.firestore_v1.types.CreateDocumentRequest, dict]):
1952 The request object. The request for
1953 [Firestore.CreateDocument][google.firestore.v1.Firestore.CreateDocument].
1954 retry (google.api_core.retry.Retry): Designation of what errors, if any,
1955 should be retried.
1956 timeout (float): The timeout for this request.
1957 metadata (Sequence[Tuple[str, str]]): Strings which should be
1958 sent along with the request as metadata.
1960 Returns:
1961 google.cloud.firestore_v1.types.Document:
1962 A Firestore document.
1964 Must not exceed 1 MiB - 4 bytes.
1966 """
1967 # Create or coerce a protobuf request object.
1968 # Minor optimization to avoid making a copy if the user passes
1969 # in a firestore.CreateDocumentRequest.
1970 # There's no risk of modifying the input as we've already verified
1971 # there are no flattened fields.
1972 if not isinstance(request, firestore.CreateDocumentRequest):
1973 request = firestore.CreateDocumentRequest(request)
1975 # Wrap the RPC method; this adds retry and timeout information,
1976 # and friendly error handling.
1977 rpc = self._transport._wrapped_methods[self._transport.create_document]
1979 # Certain fields should be provided within the metadata header;
1980 # add these here.
1981 metadata = tuple(metadata) + (
1982 gapic_v1.routing_header.to_grpc_metadata(
1983 (
1984 ("parent", request.parent),
1985 ("collection_id", request.collection_id),
1986 )
1987 ),
1988 )
1990 # Send the request.
1991 response = rpc(
1992 request,
1993 retry=retry,
1994 timeout=timeout,
1995 metadata=metadata,
1996 )
1998 # Done; return the response.
1999 return response
2001 def __enter__(self) -> "FirestoreClient":
2002 return self
2004 def __exit__(self, type, value, traceback):
2005 """Releases underlying transport's resources.
2007 .. warning::
2008 ONLY use as a context manager if the transport is NOT shared
2009 with other clients! Exiting the with block will CLOSE the transport
2010 and may cause errors in other clients!
2011 """
2012 self.transport.close()
2014 def list_operations(
2015 self,
2016 request: Optional[operations_pb2.ListOperationsRequest] = None,
2017 *,
2018 retry: OptionalRetry = gapic_v1.method.DEFAULT,
2019 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
2020 metadata: Sequence[Tuple[str, str]] = (),
2021 ) -> operations_pb2.ListOperationsResponse:
2022 r"""Lists operations that match the specified filter in the request.
2024 Args:
2025 request (:class:`~.operations_pb2.ListOperationsRequest`):
2026 The request object. Request message for
2027 `ListOperations` method.
2028 retry (google.api_core.retry.Retry): Designation of what errors,
2029 if any, should be retried.
2030 timeout (float): The timeout for this request.
2031 metadata (Sequence[Tuple[str, str]]): Strings which should be
2032 sent along with the request as metadata.
2033 Returns:
2034 ~.operations_pb2.ListOperationsResponse:
2035 Response message for ``ListOperations`` method.
2036 """
2037 # Create or coerce a protobuf request object.
2038 # The request isn't a proto-plus wrapped type,
2039 # so it must be constructed via keyword expansion.
2040 if isinstance(request, dict):
2041 request = operations_pb2.ListOperationsRequest(**request)
2043 # Wrap the RPC method; this adds retry and timeout information,
2044 # and friendly error handling.
2045 rpc = gapic_v1.method.wrap_method(
2046 self._transport.list_operations,
2047 default_timeout=None,
2048 client_info=DEFAULT_CLIENT_INFO,
2049 )
2051 # Certain fields should be provided within the metadata header;
2052 # add these here.
2053 metadata = tuple(metadata) + (
2054 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
2055 )
2057 # Send the request.
2058 response = rpc(
2059 request,
2060 retry=retry,
2061 timeout=timeout,
2062 metadata=metadata,
2063 )
2065 # Done; return the response.
2066 return response
2068 def get_operation(
2069 self,
2070 request: Optional[operations_pb2.GetOperationRequest] = None,
2071 *,
2072 retry: OptionalRetry = gapic_v1.method.DEFAULT,
2073 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
2074 metadata: Sequence[Tuple[str, str]] = (),
2075 ) -> operations_pb2.Operation:
2076 r"""Gets the latest state of a long-running operation.
2078 Args:
2079 request (:class:`~.operations_pb2.GetOperationRequest`):
2080 The request object. Request message for
2081 `GetOperation` method.
2082 retry (google.api_core.retry.Retry): Designation of what errors,
2083 if any, should be retried.
2084 timeout (float): The timeout for this request.
2085 metadata (Sequence[Tuple[str, str]]): Strings which should be
2086 sent along with the request as metadata.
2087 Returns:
2088 ~.operations_pb2.Operation:
2089 An ``Operation`` object.
2090 """
2091 # Create or coerce a protobuf request object.
2092 # The request isn't a proto-plus wrapped type,
2093 # so it must be constructed via keyword expansion.
2094 if isinstance(request, dict):
2095 request = operations_pb2.GetOperationRequest(**request)
2097 # Wrap the RPC method; this adds retry and timeout information,
2098 # and friendly error handling.
2099 rpc = gapic_v1.method.wrap_method(
2100 self._transport.get_operation,
2101 default_timeout=None,
2102 client_info=DEFAULT_CLIENT_INFO,
2103 )
2105 # Certain fields should be provided within the metadata header;
2106 # add these here.
2107 metadata = tuple(metadata) + (
2108 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
2109 )
2111 # Send the request.
2112 response = rpc(
2113 request,
2114 retry=retry,
2115 timeout=timeout,
2116 metadata=metadata,
2117 )
2119 # Done; return the response.
2120 return response
2122 def delete_operation(
2123 self,
2124 request: Optional[operations_pb2.DeleteOperationRequest] = None,
2125 *,
2126 retry: OptionalRetry = gapic_v1.method.DEFAULT,
2127 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
2128 metadata: Sequence[Tuple[str, str]] = (),
2129 ) -> None:
2130 r"""Deletes a long-running operation.
2132 This method indicates that the client is no longer interested
2133 in the operation result. It does not cancel the operation.
2134 If the server doesn't support this method, it returns
2135 `google.rpc.Code.UNIMPLEMENTED`.
2137 Args:
2138 request (:class:`~.operations_pb2.DeleteOperationRequest`):
2139 The request object. Request message for
2140 `DeleteOperation` method.
2141 retry (google.api_core.retry.Retry): Designation of what errors,
2142 if any, should be retried.
2143 timeout (float): The timeout for this request.
2144 metadata (Sequence[Tuple[str, str]]): Strings which should be
2145 sent along with the request as metadata.
2146 Returns:
2147 None
2148 """
2149 # Create or coerce a protobuf request object.
2150 # The request isn't a proto-plus wrapped type,
2151 # so it must be constructed via keyword expansion.
2152 if isinstance(request, dict):
2153 request = operations_pb2.DeleteOperationRequest(**request)
2155 # Wrap the RPC method; this adds retry and timeout information,
2156 # and friendly error handling.
2157 rpc = gapic_v1.method.wrap_method(
2158 self._transport.delete_operation,
2159 default_timeout=None,
2160 client_info=DEFAULT_CLIENT_INFO,
2161 )
2163 # Certain fields should be provided within the metadata header;
2164 # add these here.
2165 metadata = tuple(metadata) + (
2166 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
2167 )
2169 # Send the request.
2170 rpc(
2171 request,
2172 retry=retry,
2173 timeout=timeout,
2174 metadata=metadata,
2175 )
2177 def cancel_operation(
2178 self,
2179 request: Optional[operations_pb2.CancelOperationRequest] = None,
2180 *,
2181 retry: OptionalRetry = gapic_v1.method.DEFAULT,
2182 timeout: Union[float, object] = gapic_v1.method.DEFAULT,
2183 metadata: Sequence[Tuple[str, str]] = (),
2184 ) -> None:
2185 r"""Starts asynchronous cancellation on a long-running operation.
2187 The server makes a best effort to cancel the operation, but success
2188 is not guaranteed. If the server doesn't support this method, it returns
2189 `google.rpc.Code.UNIMPLEMENTED`.
2191 Args:
2192 request (:class:`~.operations_pb2.CancelOperationRequest`):
2193 The request object. Request message for
2194 `CancelOperation` method.
2195 retry (google.api_core.retry.Retry): Designation of what errors,
2196 if any, should be retried.
2197 timeout (float): The timeout for this request.
2198 metadata (Sequence[Tuple[str, str]]): Strings which should be
2199 sent along with the request as metadata.
2200 Returns:
2201 None
2202 """
2203 # Create or coerce a protobuf request object.
2204 # The request isn't a proto-plus wrapped type,
2205 # so it must be constructed via keyword expansion.
2206 if isinstance(request, dict):
2207 request = operations_pb2.CancelOperationRequest(**request)
2209 # Wrap the RPC method; this adds retry and timeout information,
2210 # and friendly error handling.
2211 rpc = gapic_v1.method.wrap_method(
2212 self._transport.cancel_operation,
2213 default_timeout=None,
2214 client_info=DEFAULT_CLIENT_INFO,
2215 )
2217 # Certain fields should be provided within the metadata header;
2218 # add these here.
2219 metadata = tuple(metadata) + (
2220 gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
2221 )
2223 # Send the request.
2224 rpc(
2225 request,
2226 retry=retry,
2227 timeout=timeout,
2228 metadata=metadata,
2229 )
2232DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
2233 gapic_version=package_version.__version__
2234)
2237__all__ = ("FirestoreClient",)