Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/pubsub_v1/services/subscriber/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#

16from collections import OrderedDict

17import functools

18import re

19from typing import (

20 Dict,

21 Mapping,

22 MutableMapping,

23 MutableSequence,

24 Optional,

25 AsyncIterable,

26 Awaitable,

27 AsyncIterator,

28 Sequence,

29 Tuple,

30 Type,

31 Union,

32)

34import warnings

35from google.pubsub_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 as retries

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

42from google.oauth2 import service_account # type: ignore

44try:

45 OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]

46except AttributeError: # pragma: NO COVER

47 OptionalRetry = Union[retries.Retry, object] # type: ignore

49from google.iam.v1 import iam_policy_pb2 # type: ignore

50from google.iam.v1 import policy_pb2 # type: ignore

51from google.protobuf import duration_pb2 # type: ignore

52from google.protobuf import field_mask_pb2 # type: ignore

53from google.protobuf import timestamp_pb2 # type: ignore

54from google.pubsub_v1.services.subscriber import pagers

55from google.pubsub_v1.types import pubsub

56from .transports.base import SubscriberTransport, DEFAULT_CLIENT_INFO

57from .transports.grpc_asyncio import SubscriberGrpcAsyncIOTransport

58from .client import SubscriberClient

61class SubscriberAsyncClient:

62 """The service that an application uses to manipulate subscriptions and

63 to consume messages from a subscription via the ``Pull`` method or

64 by establishing a bi-directional stream using the ``StreamingPull``

65 method.

66 """

68 _client: SubscriberClient

70 DEFAULT_ENDPOINT = SubscriberClient.DEFAULT_ENDPOINT

71 DEFAULT_MTLS_ENDPOINT = SubscriberClient.DEFAULT_MTLS_ENDPOINT

73 snapshot_path = staticmethod(SubscriberClient.snapshot_path)

74 parse_snapshot_path = staticmethod(SubscriberClient.parse_snapshot_path)

75 subscription_path = staticmethod(SubscriberClient.subscription_path)

76 parse_subscription_path = staticmethod(SubscriberClient.parse_subscription_path)

77 topic_path = staticmethod(SubscriberClient.topic_path)

78 parse_topic_path = staticmethod(SubscriberClient.parse_topic_path)

79 common_billing_account_path = staticmethod(

80 SubscriberClient.common_billing_account_path

81 )

82 parse_common_billing_account_path = staticmethod(

83 SubscriberClient.parse_common_billing_account_path

84 )

85 common_folder_path = staticmethod(SubscriberClient.common_folder_path)

86 parse_common_folder_path = staticmethod(SubscriberClient.parse_common_folder_path)

87 common_organization_path = staticmethod(SubscriberClient.common_organization_path)

88 parse_common_organization_path = staticmethod(

89 SubscriberClient.parse_common_organization_path

90 )

91 common_project_path = staticmethod(SubscriberClient.common_project_path)

92 parse_common_project_path = staticmethod(SubscriberClient.parse_common_project_path)

93 common_location_path = staticmethod(SubscriberClient.common_location_path)

94 parse_common_location_path = staticmethod(

95 SubscriberClient.parse_common_location_path

96 )

98 @classmethod

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

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

101 info.

102

103 Args:

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

105 args: Additional arguments to pass to the constructor.

106 kwargs: Additional arguments to pass to the constructor.

107

108 Returns:

109 SubscriberAsyncClient: The constructed client.

110 """

111 return SubscriberClient.from_service_account_info.__func__(SubscriberAsyncClient, info, *args, **kwargs) # type: ignore

112

113 @classmethod

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

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

116 file.

117

118 Args:

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

120 file.

121 args: Additional arguments to pass to the constructor.

122 kwargs: Additional arguments to pass to the constructor.

123

124 Returns:

125 SubscriberAsyncClient: The constructed client.

126 """

127 return SubscriberClient.from_service_account_file.__func__(SubscriberAsyncClient, filename, *args, **kwargs) # type: ignore

128

129 from_service_account_json = from_service_account_file

130

131 @classmethod

132 def get_mtls_endpoint_and_cert_source(

133 cls, client_options: Optional[ClientOptions] = None

134 ):

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

136

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

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

139 client cert source is None.

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

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

142 source is None.

143

144 The API endpoint is determined in the following order:

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

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

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

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

149 use the default API endpoint.

150

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

152

153 Args:

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

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

156 in this method.

157

158 Returns:

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

160 client cert source to use.

161

162 Raises:

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

164 """

165 return SubscriberClient.get_mtls_endpoint_and_cert_source(client_options) # type: ignore

166

167 @property

168 def transport(self) -> SubscriberTransport:

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

170

171 Returns:

172 SubscriberTransport: The transport used by the client instance.

173 """

174 return self._client.transport

175

176 get_transport_class = functools.partial(

177 type(SubscriberClient).get_transport_class, type(SubscriberClient)

178 )

179

180 def __init__(

181 self,

182 *,

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

184 transport: Union[str, SubscriberTransport] = "grpc_asyncio",

185 client_options: Optional[ClientOptions] = None,

186 client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,

187 ) -> None:

188 """Instantiates the subscriber client.

189

190 Args:

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

192 authorization credentials to attach to requests. These

193 credentials identify the application to the service; if none

194 are specified, the client will attempt to ascertain the

195 credentials from the environment.

196 transport (Union[str, ~.SubscriberTransport]): The

197 transport to use. If set to None, a transport is chosen

198 automatically.

199 client_options (ClientOptions): Custom options for the client. It

200 won't take effect if a ``transport`` instance is provided.

201 (1) The ``api_endpoint`` property can be used to override the

202 default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT

203 environment variable can also be used to override the endpoint:

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

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

206 default mTLS endpoint if client certificate is present, this is

207 the default value). However, the ``api_endpoint`` property takes

208 precedence if provided.

209 (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable

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

211 to provide client certificate for mutual TLS transport. If

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

213 present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not

214 set, no client certificate will be used.

215

216 Raises:

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

218 creation failed for any reason.

219 """

220 self._client = SubscriberClient(

221 credentials=credentials,

222 transport=transport,

223 client_options=client_options,

224 client_info=client_info,

225 )

226

227 async def create_subscription(

228 self,

229 request: Optional[Union[pubsub.Subscription, dict]] = None,

230 *,

231 name: Optional[str] = None,

232 topic: Optional[str] = None,

233 push_config: Optional[pubsub.PushConfig] = None,

234 ack_deadline_seconds: Optional[int] = None,

235 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

237 metadata: Sequence[Tuple[str, str]] = (),

238 ) -> pubsub.Subscription:

239 r"""Creates a subscription to a given topic. See the [resource name

240 rules]

241 (https://cloud.google.com/pubsub/docs/admin#resource_names). If

242 the subscription already exists, returns ``ALREADY_EXISTS``. If

243 the corresponding topic doesn't exist, returns ``NOT_FOUND``.

244

245 If the name is not provided in the request, the server will

246 assign a random name for this subscription on the same project

247 as the topic, conforming to the [resource name format]

248 (https://cloud.google.com/pubsub/docs/admin#resource_names). The

249 generated name is populated in the returned Subscription object.

250 Note that for REST API requests, you must specify a name in the

251 request.

252

253 .. code-block:: python

254

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

256 # code template only.

257 # It will require modifications to work:

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

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

260 # client as shown in:

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

262 from google import pubsub_v1

263

264 async def sample_create_subscription():

265 # Create a client

266 client = pubsub_v1.SubscriberAsyncClient()

267

268 # Initialize request argument(s)

269 request = pubsub_v1.Subscription(

270 name="name_value",

271 topic="topic_value",

272 )

273

274 # Make the request

275 response = await client.create_subscription(request=request)

276

277 # Handle the response

278 print(response)

279

280 Args:

281 request (Optional[Union[google.pubsub_v1.types.Subscription, dict]]):

282 The request object. A subscription resource. If none of

283 `push_config` or `bigquery_config` is set, then the

284 subscriber will pull and ack messages using API methods.

285 At most one of these fields may be set.

286 name (:class:`str`):

287 Required. The name of the subscription. It must have the

288 format

289 ``"projects/{project}/subscriptions/{subscription}"``.

290 ``{subscription}`` must start with a letter, and contain

291 only letters (``[A-Za-z]``), numbers (``[0-9]``), dashes

292 (``-``), underscores (``_``), periods (``.``), tildes

293 (``~``), plus (``+``) or percent signs (``%``). It must

294 be between 3 and 255 characters in length, and it must

295 not start with ``"goog"``.

296

297 This corresponds to the ``name`` field

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

299 should not be set.

300 topic (:class:`str`):

301 Required. The name of the topic from which this

302 subscription is receiving messages. Format is

303 ``projects/{project}/topics/{topic}``. The value of this

304 field will be ``_deleted-topic_`` if the topic has been

305 deleted.

306

307 This corresponds to the ``topic`` field

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

309 should not be set.

310 push_config (:class:`google.pubsub_v1.types.PushConfig`):

311 If push delivery is used with this

312 subscription, this field is used to

313 configure it.

314

315 This corresponds to the ``push_config`` field

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

317 should not be set.

318 ack_deadline_seconds (:class:`int`):

319 The approximate amount of time (on a best-effort basis)

320 Pub/Sub waits for the subscriber to acknowledge receipt

321 before resending the message. In the interval after the

322 message is delivered and before it is acknowledged, it

323 is considered to be *outstanding*. During that time

324 period, the message will not be redelivered (on a

325 best-effort basis).

326

327 For pull subscriptions, this value is used as the

328 initial value for the ack deadline. To override this

329 value for a given message, call ``ModifyAckDeadline``

330 with the corresponding ``ack_id`` if using non-streaming

331 pull or send the ``ack_id`` in a

332 ``StreamingModifyAckDeadlineRequest`` if using streaming

333 pull. The minimum custom deadline you can specify is 10

334 seconds. The maximum custom deadline you can specify is

335 600 seconds (10 minutes). If this parameter is 0, a

336 default value of 10 seconds is used.

337

338 For push delivery, this value is also used to set the

339 request timeout for the call to the push endpoint.

340

341 If the subscriber never acknowledges the message, the

342 Pub/Sub system will eventually redeliver the message.

343

344 This corresponds to the ``ack_deadline_seconds`` field

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

346 should not be set.

347 retry (google.api_core.retry.Retry): Designation of what errors, if any,

348 should be retried.

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

350 metadata (Sequence[Tuple[str, str]]): Strings which should be

351 sent along with the request as metadata.

352

353 Returns:

354 google.pubsub_v1.types.Subscription:

355 A subscription resource. If none of push_config or bigquery_config is

356 set, then the subscriber will pull and ack messages

357 using API methods. At most one of these fields may be

358 set.

359

360 """

361 # Create or coerce a protobuf request object.

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

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

364 has_flattened_params = any([name, topic, push_config, ack_deadline_seconds])

365 if request is not None and has_flattened_params:

366 raise ValueError(

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

368 "the individual field arguments should be set."

369 )

370

371 request = pubsub.Subscription(request)

372

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

374 # request, apply these.

375 if name is not None:

376 request.name = name

377 if topic is not None:

378 request.topic = topic

379 if push_config is not None:

380 request.push_config = push_config

381 if ack_deadline_seconds is not None:

382 request.ack_deadline_seconds = ack_deadline_seconds

383

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

385 # and friendly error handling.

386 rpc = gapic_v1.method_async.wrap_method(

387 self._client._transport.create_subscription,

388 default_retry=retries.Retry(

389 initial=0.1,

390 maximum=60.0,

391 multiplier=1.3,

392 predicate=retries.if_exception_type(

393 core_exceptions.Aborted,

394 core_exceptions.ServiceUnavailable,

395 core_exceptions.Unknown,

396 ),

397 deadline=60.0,

398 ),

399 default_timeout=60.0,

400 client_info=DEFAULT_CLIENT_INFO,

401 )

402

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

404 # add these here.

405 metadata = tuple(metadata) + (

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

407 )

408

409 # Send the request.

410 response = await rpc(

411 request,

412 retry=retry,

413 timeout=timeout,

414 metadata=metadata,

415 )

416

417 # Done; return the response.

418 return response

419

420 async def get_subscription(

421 self,

422 request: Optional[Union[pubsub.GetSubscriptionRequest, dict]] = None,

423 *,

424 subscription: Optional[str] = None,

425 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

427 metadata: Sequence[Tuple[str, str]] = (),

428 ) -> pubsub.Subscription:

429 r"""Gets the configuration details of a subscription.

430

431 .. code-block:: python

432

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

434 # code template only.

435 # It will require modifications to work:

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

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

438 # client as shown in:

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

440 from google import pubsub_v1

441

442 async def sample_get_subscription():

443 # Create a client

444 client = pubsub_v1.SubscriberAsyncClient()

445

446 # Initialize request argument(s)

447 request = pubsub_v1.GetSubscriptionRequest(

448 subscription="subscription_value",

449 )

450

451 # Make the request

452 response = await client.get_subscription(request=request)

453

454 # Handle the response

455 print(response)

456

457 Args:

458 request (Optional[Union[google.pubsub_v1.types.GetSubscriptionRequest, dict]]):

459 The request object. Request for the GetSubscription

460 method.

461 subscription (:class:`str`):

462 Required. The name of the subscription to get. Format is

463 ``projects/{project}/subscriptions/{sub}``.

464

465 This corresponds to the ``subscription`` field

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

467 should not be set.

468 retry (google.api_core.retry.Retry): Designation of what errors, if any,

469 should be retried.

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

471 metadata (Sequence[Tuple[str, str]]): Strings which should be

472 sent along with the request as metadata.

473

474 Returns:

475 google.pubsub_v1.types.Subscription:

476 A subscription resource. If none of push_config or bigquery_config is

477 set, then the subscriber will pull and ack messages

478 using API methods. At most one of these fields may be

479 set.

480

481 """

482 # Create or coerce a protobuf request object.

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

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

485 has_flattened_params = any([subscription])

486 if request is not None and has_flattened_params:

487 raise ValueError(

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

489 "the individual field arguments should be set."

490 )

491

492 request = pubsub.GetSubscriptionRequest(request)

493

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

495 # request, apply these.

496 if subscription is not None:

497 request.subscription = subscription

498

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

500 # and friendly error handling.

501 rpc = gapic_v1.method_async.wrap_method(

502 self._client._transport.get_subscription,

503 default_retry=retries.Retry(

504 initial=0.1,

505 maximum=60.0,

506 multiplier=1.3,

507 predicate=retries.if_exception_type(

508 core_exceptions.Aborted,

509 core_exceptions.ServiceUnavailable,

510 core_exceptions.Unknown,

511 ),

512 deadline=60.0,

513 ),

514 default_timeout=60.0,

515 client_info=DEFAULT_CLIENT_INFO,

516 )

517

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

519 # add these here.

520 metadata = tuple(metadata) + (

521 gapic_v1.routing_header.to_grpc_metadata(

522 (("subscription", request.subscription),)

523 ),

524 )

525

526 # Send the request.

527 response = await rpc(

528 request,

529 retry=retry,

530 timeout=timeout,

531 metadata=metadata,

532 )

533

534 # Done; return the response.

535 return response

536

537 async def update_subscription(

538 self,

539 request: Optional[Union[pubsub.UpdateSubscriptionRequest, dict]] = None,

540 *,

541 subscription: Optional[pubsub.Subscription] = None,

542 update_mask: Optional[field_mask_pb2.FieldMask] = None,

543 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

545 metadata: Sequence[Tuple[str, str]] = (),

546 ) -> pubsub.Subscription:

547 r"""Updates an existing subscription. Note that certain

548 properties of a subscription, such as its topic, are not

549 modifiable.

550

551 .. code-block:: python

552

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

554 # code template only.

555 # It will require modifications to work:

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

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

558 # client as shown in:

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

560 from google import pubsub_v1

561

562 async def sample_update_subscription():

563 # Create a client

564 client = pubsub_v1.SubscriberAsyncClient()

565

566 # Initialize request argument(s)

567 subscription = pubsub_v1.Subscription()

568 subscription.name = "name_value"

569 subscription.topic = "topic_value"

570

571 request = pubsub_v1.UpdateSubscriptionRequest(

572 subscription=subscription,

573 )

574

575 # Make the request

576 response = await client.update_subscription(request=request)

577

578 # Handle the response

579 print(response)

580

581 Args:

582 request (Optional[Union[google.pubsub_v1.types.UpdateSubscriptionRequest, dict]]):

583 The request object. Request for the UpdateSubscription

584 method.

585 subscription (:class:`google.pubsub_v1.types.Subscription`):

586 Required. The updated subscription

587 object.

588

589 This corresponds to the ``subscription`` field

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

591 should not be set.

592 update_mask (:class:`google.protobuf.field_mask_pb2.FieldMask`):

593 Required. Indicates which fields in

594 the provided subscription to update.

595 Must be specified and non-empty.

596

597 This corresponds to the ``update_mask`` field

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

599 should not be set.

600 retry (google.api_core.retry.Retry): Designation of what errors, if any,

601 should be retried.

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

603 metadata (Sequence[Tuple[str, str]]): Strings which should be

604 sent along with the request as metadata.

605

606 Returns:

607 google.pubsub_v1.types.Subscription:

608 A subscription resource. If none of push_config or bigquery_config is

609 set, then the subscriber will pull and ack messages

610 using API methods. At most one of these fields may be

611 set.

612

613 """

614 # Create or coerce a protobuf request object.

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

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

617 has_flattened_params = any([subscription, update_mask])

618 if request is not None and has_flattened_params:

619 raise ValueError(

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

621 "the individual field arguments should be set."

622 )

623

624 request = pubsub.UpdateSubscriptionRequest(request)

625

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

627 # request, apply these.

628 if subscription is not None:

629 request.subscription = subscription

630 if update_mask is not None:

631 request.update_mask = update_mask

632

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

634 # and friendly error handling.

635 rpc = gapic_v1.method_async.wrap_method(

636 self._client._transport.update_subscription,

637 default_retry=retries.Retry(

638 initial=0.1,

639 maximum=60.0,

640 multiplier=1.3,

641 predicate=retries.if_exception_type(

642 core_exceptions.ServiceUnavailable,

643 ),

644 deadline=60.0,

645 ),

646 default_timeout=60.0,

647 client_info=DEFAULT_CLIENT_INFO,

648 )

649

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

651 # add these here.

652 metadata = tuple(metadata) + (

653 gapic_v1.routing_header.to_grpc_metadata(

654 (("subscription.name", request.subscription.name),)

655 ),

656 )

657

658 # Send the request.

659 response = await rpc(

660 request,

661 retry=retry,

662 timeout=timeout,

663 metadata=metadata,

664 )

665

666 # Done; return the response.

667 return response

668

669 async def list_subscriptions(

670 self,

671 request: Optional[Union[pubsub.ListSubscriptionsRequest, dict]] = None,

672 *,

673 project: Optional[str] = None,

674 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

676 metadata: Sequence[Tuple[str, str]] = (),

677 ) -> pagers.ListSubscriptionsAsyncPager:

678 r"""Lists matching subscriptions.

679

680 .. code-block:: python

681

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

683 # code template only.

684 # It will require modifications to work:

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

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

687 # client as shown in:

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

689 from google import pubsub_v1

690

691 async def sample_list_subscriptions():

692 # Create a client

693 client = pubsub_v1.SubscriberAsyncClient()

694

695 # Initialize request argument(s)

696 request = pubsub_v1.ListSubscriptionsRequest(

697 project="project_value",

698 )

699

700 # Make the request

701 page_result = client.list_subscriptions(request=request)

702

703 # Handle the response

704 async for response in page_result:

705 print(response)

706

707 Args:

708 request (Optional[Union[google.pubsub_v1.types.ListSubscriptionsRequest, dict]]):

709 The request object. Request for the `ListSubscriptions`

710 method.

711 project (:class:`str`):

712 Required. The name of the project in which to list

713 subscriptions. Format is ``projects/{project-id}``.

714

715 This corresponds to the ``project`` field

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

717 should not be set.

718 retry (google.api_core.retry.Retry): Designation of what errors, if any,

719 should be retried.

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

721 metadata (Sequence[Tuple[str, str]]): Strings which should be

722 sent along with the request as metadata.

723

724 Returns:

725 google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager:

726 Response for the ListSubscriptions method.

727

728 Iterating over this object will yield results and

729 resolve additional pages automatically.

730

731 """

732 # Create or coerce a protobuf request object.

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

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

735 has_flattened_params = any([project])

736 if request is not None and has_flattened_params:

737 raise ValueError(

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

739 "the individual field arguments should be set."

740 )

741

742 request = pubsub.ListSubscriptionsRequest(request)

743

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

745 # request, apply these.

746 if project is not None:

747 request.project = project

748

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

750 # and friendly error handling.

751 rpc = gapic_v1.method_async.wrap_method(

752 self._client._transport.list_subscriptions,

753 default_retry=retries.Retry(

754 initial=0.1,

755 maximum=60.0,

756 multiplier=1.3,

757 predicate=retries.if_exception_type(

758 core_exceptions.Aborted,

759 core_exceptions.ServiceUnavailable,

760 core_exceptions.Unknown,

761 ),

762 deadline=60.0,

763 ),

764 default_timeout=60.0,

765 client_info=DEFAULT_CLIENT_INFO,

766 )

767

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

769 # add these here.

770 metadata = tuple(metadata) + (

771 gapic_v1.routing_header.to_grpc_metadata((("project", request.project),)),

772 )

773

774 # Send the request.

775 response = await rpc(

776 request,

777 retry=retry,

778 timeout=timeout,

779 metadata=metadata,

780 )

781

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

783 # an `__aiter__` convenience method.

784 response = pagers.ListSubscriptionsAsyncPager(

785 method=rpc,

786 request=request,

787 response=response,

788 metadata=metadata,

789 )

790

791 # Done; return the response.

792 return response

793

794 async def delete_subscription(

795 self,

796 request: Optional[Union[pubsub.DeleteSubscriptionRequest, dict]] = None,

797 *,

798 subscription: Optional[str] = None,

799 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

801 metadata: Sequence[Tuple[str, str]] = (),

802 ) -> None:

803 r"""Deletes an existing subscription. All messages retained in the

804 subscription are immediately dropped. Calls to ``Pull`` after

805 deletion will return ``NOT_FOUND``. After a subscription is

806 deleted, a new one may be created with the same name, but the

807 new one has no association with the old subscription or its

808 topic unless the same topic is specified.

809

810 .. code-block:: python

811

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

813 # code template only.

814 # It will require modifications to work:

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

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

817 # client as shown in:

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

819 from google import pubsub_v1

820

821 async def sample_delete_subscription():

822 # Create a client

823 client = pubsub_v1.SubscriberAsyncClient()

824

825 # Initialize request argument(s)

826 request = pubsub_v1.DeleteSubscriptionRequest(

827 subscription="subscription_value",

828 )

829

830 # Make the request

831 await client.delete_subscription(request=request)

832

833 Args:

834 request (Optional[Union[google.pubsub_v1.types.DeleteSubscriptionRequest, dict]]):

835 The request object. Request for the DeleteSubscription

836 method.

837 subscription (:class:`str`):

838 Required. The subscription to delete. Format is

839 ``projects/{project}/subscriptions/{sub}``.

840

841 This corresponds to the ``subscription`` field

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

843 should not be set.

844 retry (google.api_core.retry.Retry): Designation of what errors, if any,

845 should be retried.

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

847 metadata (Sequence[Tuple[str, str]]): Strings which should be

848 sent along with the request as metadata.

849 """

850 # Create or coerce a protobuf request object.

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

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

853 has_flattened_params = any([subscription])

854 if request is not None and has_flattened_params:

855 raise ValueError(

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

857 "the individual field arguments should be set."

858 )

859

860 request = pubsub.DeleteSubscriptionRequest(request)

861

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

863 # request, apply these.

864 if subscription is not None:

865 request.subscription = subscription

866

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

868 # and friendly error handling.

869 rpc = gapic_v1.method_async.wrap_method(

870 self._client._transport.delete_subscription,

871 default_retry=retries.Retry(

872 initial=0.1,

873 maximum=60.0,

874 multiplier=1.3,

875 predicate=retries.if_exception_type(

876 core_exceptions.ServiceUnavailable,

877 ),

878 deadline=60.0,

879 ),

880 default_timeout=60.0,

881 client_info=DEFAULT_CLIENT_INFO,

882 )

883

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

885 # add these here.

886 metadata = tuple(metadata) + (

887 gapic_v1.routing_header.to_grpc_metadata(

888 (("subscription", request.subscription),)

889 ),

890 )

891

892 # Send the request.

893 await rpc(

894 request,

895 retry=retry,

896 timeout=timeout,

897 metadata=metadata,

898 )

899

900 async def modify_ack_deadline(

901 self,

902 request: Optional[Union[pubsub.ModifyAckDeadlineRequest, dict]] = None,

903 *,

904 subscription: Optional[str] = None,

905 ack_ids: Optional[MutableSequence[str]] = None,

906 ack_deadline_seconds: Optional[int] = None,

907 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

909 metadata: Sequence[Tuple[str, str]] = (),

910 ) -> None:

911 r"""Modifies the ack deadline for a specific message. This method is

912 useful to indicate that more time is needed to process a message

913 by the subscriber, or to make the message available for

914 redelivery if the processing was interrupted. Note that this

915 does not modify the subscription-level ``ackDeadlineSeconds``

916 used for subsequent messages.

917

918 .. code-block:: python

919

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

921 # code template only.

922 # It will require modifications to work:

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

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

925 # client as shown in:

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

927 from google import pubsub_v1

928

929 async def sample_modify_ack_deadline():

930 # Create a client

931 client = pubsub_v1.SubscriberAsyncClient()

932

933 # Initialize request argument(s)

934 request = pubsub_v1.ModifyAckDeadlineRequest(

935 subscription="subscription_value",

936 ack_ids=['ack_ids_value1', 'ack_ids_value2'],

937 ack_deadline_seconds=2066,

938 )

939

940 # Make the request

941 await client.modify_ack_deadline(request=request)

942

943 Args:

944 request (Optional[Union[google.pubsub_v1.types.ModifyAckDeadlineRequest, dict]]):

945 The request object. Request for the ModifyAckDeadline

946 method.

947 subscription (:class:`str`):

948 Required. The name of the subscription. Format is

949 ``projects/{project}/subscriptions/{sub}``.

950

951 This corresponds to the ``subscription`` field

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

953 should not be set.

954 ack_ids (:class:`MutableSequence[str]`):

955 Required. List of acknowledgment IDs.

956 This corresponds to the ``ack_ids`` field

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

958 should not be set.

959 ack_deadline_seconds (:class:`int`):

960 Required. The new ack deadline with respect to the time

961 this request was sent to the Pub/Sub system. For

962 example, if the value is 10, the new ack deadline will

963 expire 10 seconds after the ``ModifyAckDeadline`` call

964 was made. Specifying zero might immediately make the

965 message available for delivery to another subscriber

966 client. This typically results in an increase in the

967 rate of message redeliveries (that is, duplicates). The

968 minimum deadline you can specify is 0 seconds. The

969 maximum deadline you can specify is 600 seconds (10

970 minutes).

971

972 This corresponds to the ``ack_deadline_seconds`` field

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

974 should not be set.

975 retry (google.api_core.retry.Retry): Designation of what errors, if any,

976 should be retried.

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

978 metadata (Sequence[Tuple[str, str]]): Strings which should be

979 sent along with the request as metadata.

980 """

981 # Create or coerce a protobuf request object.

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

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

984 has_flattened_params = any([subscription, ack_ids, ack_deadline_seconds])

985 if request is not None and has_flattened_params:

986 raise ValueError(

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

988 "the individual field arguments should be set."

989 )

990

991 request = pubsub.ModifyAckDeadlineRequest(request)

992

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

994 # request, apply these.

995 if subscription is not None:

996 request.subscription = subscription

997 if ack_deadline_seconds is not None:

998 request.ack_deadline_seconds = ack_deadline_seconds

999 if ack_ids:

1000 request.ack_ids.extend(ack_ids)

1001

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

1003 # and friendly error handling.

1004 rpc = gapic_v1.method_async.wrap_method(

1005 self._client._transport.modify_ack_deadline,

1006 default_retry=retries.Retry(

1007 initial=0.1,

1008 maximum=60.0,

1009 multiplier=1.3,

1010 predicate=retries.if_exception_type(

1011 core_exceptions.ServiceUnavailable,

1012 ),

1013 deadline=60.0,

1014 ),

1015 default_timeout=60.0,

1016 client_info=DEFAULT_CLIENT_INFO,

1017 )

1018

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

1020 # add these here.

1021 metadata = tuple(metadata) + (

1022 gapic_v1.routing_header.to_grpc_metadata(

1023 (("subscription", request.subscription),)

1024 ),

1025 )

1026

1027 # Send the request.

1028 await rpc(

1029 request,

1030 retry=retry,

1031 timeout=timeout,

1032 metadata=metadata,

1033 )

1034

1035 async def acknowledge(

1036 self,

1037 request: Optional[Union[pubsub.AcknowledgeRequest, dict]] = None,

1038 *,

1039 subscription: Optional[str] = None,

1040 ack_ids: Optional[MutableSequence[str]] = None,

1041 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

1043 metadata: Sequence[Tuple[str, str]] = (),

1044 ) -> None:

1045 r"""Acknowledges the messages associated with the ``ack_ids`` in the

1046 ``AcknowledgeRequest``. The Pub/Sub system can remove the

1047 relevant messages from the subscription.

1048

1049 Acknowledging a message whose ack deadline has expired may

1050 succeed, but such a message may be redelivered later.

1051 Acknowledging a message more than once will not result in an

1052 error.

1053

1054 .. code-block:: python

1055

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

1057 # code template only.

1058 # It will require modifications to work:

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

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

1061 # client as shown in:

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

1063 from google import pubsub_v1

1064

1065 async def sample_acknowledge():

1066 # Create a client

1067 client = pubsub_v1.SubscriberAsyncClient()

1068

1069 # Initialize request argument(s)

1070 request = pubsub_v1.AcknowledgeRequest(

1071 subscription="subscription_value",

1072 ack_ids=['ack_ids_value1', 'ack_ids_value2'],

1073 )

1074

1075 # Make the request

1076 await client.acknowledge(request=request)

1077

1078 Args:

1079 request (Optional[Union[google.pubsub_v1.types.AcknowledgeRequest, dict]]):

1080 The request object. Request for the Acknowledge method.

1081 subscription (:class:`str`):

1082 Required. The subscription whose message is being

1083 acknowledged. Format is

1084 ``projects/{project}/subscriptions/{sub}``.

1085

1086 This corresponds to the ``subscription`` field

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

1088 should not be set.

1089 ack_ids (:class:`MutableSequence[str]`):

1090 Required. The acknowledgment ID for the messages being

1091 acknowledged that was returned by the Pub/Sub system in

1092 the ``Pull`` response. Must not be empty.

1093

1094 This corresponds to the ``ack_ids`` field

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

1096 should not be set.

1097 retry (google.api_core.retry.Retry): Designation of what errors, if any,

1098 should be retried.

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

1100 metadata (Sequence[Tuple[str, str]]): Strings which should be

1101 sent along with the request as metadata.

1102 """

1103 # Create or coerce a protobuf request object.

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

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

1106 has_flattened_params = any([subscription, ack_ids])

1107 if request is not None and has_flattened_params:

1108 raise ValueError(

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

1110 "the individual field arguments should be set."

1111 )

1112

1113 request = pubsub.AcknowledgeRequest(request)

1114

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

1116 # request, apply these.

1117 if subscription is not None:

1118 request.subscription = subscription

1119 if ack_ids:

1120 request.ack_ids.extend(ack_ids)

1121

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

1123 # and friendly error handling.

1124 rpc = gapic_v1.method_async.wrap_method(

1125 self._client._transport.acknowledge,

1126 default_retry=retries.Retry(

1127 initial=0.1,

1128 maximum=60.0,

1129 multiplier=1.3,

1130 predicate=retries.if_exception_type(

1131 core_exceptions.ServiceUnavailable,

1132 ),

1133 deadline=60.0,

1134 ),

1135 default_timeout=60.0,

1136 client_info=DEFAULT_CLIENT_INFO,

1137 )

1138

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

1140 # add these here.

1141 metadata = tuple(metadata) + (

1142 gapic_v1.routing_header.to_grpc_metadata(

1143 (("subscription", request.subscription),)

1144 ),

1145 )

1146

1147 # Send the request.

1148 await rpc(

1149 request,

1150 retry=retry,

1151 timeout=timeout,

1152 metadata=metadata,

1153 )

1154

1155 async def pull(

1156 self,

1157 request: Optional[Union[pubsub.PullRequest, dict]] = None,

1158 *,

1159 subscription: Optional[str] = None,

1160 return_immediately: Optional[bool] = None,

1161 max_messages: Optional[int] = None,

1162 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

1164 metadata: Sequence[Tuple[str, str]] = (),

1165 ) -> pubsub.PullResponse:

1166 r"""Pulls messages from the server.

1167

1168 .. code-block:: python

1169

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

1171 # code template only.

1172 # It will require modifications to work:

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

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

1175 # client as shown in:

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

1177 from google import pubsub_v1

1178

1179 async def sample_pull():

1180 # Create a client

1181 client = pubsub_v1.SubscriberAsyncClient()

1182

1183 # Initialize request argument(s)

1184 request = pubsub_v1.PullRequest(

1185 subscription="subscription_value",

1186 max_messages=1277,

1187 )

1188

1189 # Make the request

1190 response = await client.pull(request=request)

1191

1192 # Handle the response

1193 print(response)

1194

1195 Args:

1196 request (Optional[Union[google.pubsub_v1.types.PullRequest, dict]]):

1197 The request object. Request for the `Pull` method.

1198 subscription (:class:`str`):

1199 Required. The subscription from which messages should be

1200 pulled. Format is

1201 ``projects/{project}/subscriptions/{sub}``.

1202

1203 This corresponds to the ``subscription`` field

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

1205 should not be set.

1206 return_immediately (:class:`bool`):

1207 Optional. If this field set to true, the system will

1208 respond immediately even if it there are no messages

1209 available to return in the ``Pull`` response. Otherwise,

1210 the system may wait (for a bounded amount of time) until

1211 at least one message is available, rather than returning

1212 no messages. Warning: setting this field to ``true`` is

1213 discouraged because it adversely impacts the performance

1214 of ``Pull`` operations. We recommend that users do not

1215 set this field.

1216

1217 This corresponds to the ``return_immediately`` field

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

1219 should not be set.

1220 max_messages (:class:`int`):

1221 Required. The maximum number of

1222 messages to return for this request.

1223 Must be a positive integer. The Pub/Sub

1224 system may return fewer than the number

1225 specified.

1226

1227 This corresponds to the ``max_messages`` field

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

1229 should not be set.

1230 retry (google.api_core.retry.Retry): Designation of what errors, if any,

1231 should be retried.

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

1233 metadata (Sequence[Tuple[str, str]]): Strings which should be

1234 sent along with the request as metadata.

1235

1236 Returns:

1237 google.pubsub_v1.types.PullResponse:

1238 Response for the Pull method.

1239 """

1240 # Create or coerce a protobuf request object.

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

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

1243 has_flattened_params = any([subscription, return_immediately, max_messages])

1244 if request is not None and has_flattened_params:

1245 raise ValueError(

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

1247 "the individual field arguments should be set."

1248 )

1249

1250 request = pubsub.PullRequest(request)

1251

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

1253 # request, apply these.

1254 if subscription is not None:

1255 request.subscription = subscription

1256 if return_immediately is not None:

1257 request.return_immediately = return_immediately

1258 if max_messages is not None:

1259 request.max_messages = max_messages

1260

1261 if request.return_immediately:

1262 warnings.warn(

1263 "The return_immediately flag is deprecated and should be set to False.",

1264 category=DeprecationWarning,

1265 )

1266

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

1268 # and friendly error handling.

1269 rpc = gapic_v1.method_async.wrap_method(

1270 self._client._transport.pull,

1271 default_retry=retries.Retry(

1272 initial=0.1,

1273 maximum=60.0,

1274 multiplier=1.3,

1275 predicate=retries.if_exception_type(

1276 core_exceptions.Aborted,

1277 core_exceptions.InternalServerError,

1278 core_exceptions.ServiceUnavailable,

1279 core_exceptions.Unknown,

1280 ),

1281 deadline=60.0,

1282 ),

1283 default_timeout=60.0,

1284 client_info=DEFAULT_CLIENT_INFO,

1285 )

1286

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

1288 # add these here.

1289 metadata = tuple(metadata) + (

1290 gapic_v1.routing_header.to_grpc_metadata(

1291 (("subscription", request.subscription),)

1292 ),

1293 )

1294

1295 # Send the request.

1296 response = await rpc(

1297 request,

1298 retry=retry,

1299 timeout=timeout,

1300 metadata=metadata,

1301 )

1302

1303 # Done; return the response.

1304 return response

1305

1306 def streaming_pull(

1307 self,

1308 requests: Optional[AsyncIterator[pubsub.StreamingPullRequest]] = None,

1309 *,

1310 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

1312 metadata: Sequence[Tuple[str, str]] = (),

1313 ) -> Awaitable[AsyncIterable[pubsub.StreamingPullResponse]]:

1314 r"""Establishes a stream with the server, which sends messages down

1315 to the client. The client streams acknowledgements and ack

1316 deadline modifications back to the server. The server will close

1317 the stream and return the status on any error. The server may

1318 close the stream with status ``UNAVAILABLE`` to reassign

1319 server-side resources, in which case, the client should

1320 re-establish the stream. Flow control can be achieved by

1321 configuring the underlying RPC channel.

1322

1323 .. code-block:: python

1324

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

1326 # code template only.

1327 # It will require modifications to work:

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

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

1330 # client as shown in:

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

1332 from google import pubsub_v1

1333

1334 async def sample_streaming_pull():

1335 # Create a client

1336 client = pubsub_v1.SubscriberAsyncClient()

1337

1338 # Initialize request argument(s)

1339 request = pubsub_v1.StreamingPullRequest(

1340 subscription="subscription_value",

1341 stream_ack_deadline_seconds=2813,

1342 )

1343

1344 # This method expects an iterator which contains

1345 # 'pubsub_v1.StreamingPullRequest' objects

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

1347 # demonstrative purposes.

1348 requests = [request]

1349

1350 def request_generator():

1351 for request in requests:

1352 yield request

1353

1354 # Make the request

1355 stream = await client.streaming_pull(requests=request_generator())

1356

1357 # Handle the response

1358 async for response in stream:

1359 print(response)

1360

1361 Args:

1362 requests (AsyncIterator[`google.pubsub_v1.types.StreamingPullRequest`]):

1363 The request object AsyncIterator. Request for the `StreamingPull`

1364 streaming RPC method. This request is used to establish

1365 the initial stream as well as to stream acknowledgements

1366 and ack deadline modifications from the client to the

1367 server.

1368 retry (google.api_core.retry.Retry): Designation of what errors, if any,

1369 should be retried.

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

1371 metadata (Sequence[Tuple[str, str]]): Strings which should be

1372 sent along with the request as metadata.

1373

1374 Returns:

1375 AsyncIterable[google.pubsub_v1.types.StreamingPullResponse]:

1376 Response for the StreamingPull method. This response is used to stream

1377 messages from the server to the client.

1378

1379 """

1380

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

1382 # and friendly error handling.

1383 rpc = gapic_v1.method_async.wrap_method(

1384 self._client._transport.streaming_pull,

1385 default_retry=retries.Retry(

1386 initial=0.1,

1387 maximum=60.0,

1388 multiplier=1.3,

1389 predicate=retries.if_exception_type(

1390 core_exceptions.Aborted,

1391 core_exceptions.DeadlineExceeded,

1392 core_exceptions.InternalServerError,

1393 core_exceptions.ResourceExhausted,

1394 core_exceptions.ServiceUnavailable,

1395 ),

1396 deadline=900.0,

1397 ),

1398 default_timeout=900.0,

1399 client_info=DEFAULT_CLIENT_INFO,

1400 )

1401

1402 # Send the request.

1403 response = rpc(

1404 requests,

1405 retry=retry,

1406 timeout=timeout,

1407 metadata=metadata,

1408 )

1409

1410 # Done; return the response.

1411 return response

1412

1413 async def modify_push_config(

1414 self,

1415 request: Optional[Union[pubsub.ModifyPushConfigRequest, dict]] = None,

1416 *,

1417 subscription: Optional[str] = None,

1418 push_config: Optional[pubsub.PushConfig] = None,

1419 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

1421 metadata: Sequence[Tuple[str, str]] = (),

1422 ) -> None:

1423 r"""Modifies the ``PushConfig`` for a specified subscription.

1424

1425 This may be used to change a push subscription to a pull one

1426 (signified by an empty ``PushConfig``) or vice versa, or change

1427 the endpoint URL and other attributes of a push subscription.

1428 Messages will accumulate for delivery continuously through the

1429 call regardless of changes to the ``PushConfig``.

1430

1431 .. code-block:: python

1432

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

1434 # code template only.

1435 # It will require modifications to work:

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

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

1438 # client as shown in:

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

1440 from google import pubsub_v1

1441

1442 async def sample_modify_push_config():

1443 # Create a client

1444 client = pubsub_v1.SubscriberAsyncClient()

1445

1446 # Initialize request argument(s)

1447 request = pubsub_v1.ModifyPushConfigRequest(

1448 subscription="subscription_value",

1449 )

1450

1451 # Make the request

1452 await client.modify_push_config(request=request)

1453

1454 Args:

1455 request (Optional[Union[google.pubsub_v1.types.ModifyPushConfigRequest, dict]]):

1456 The request object. Request for the ModifyPushConfig

1457 method.

1458 subscription (:class:`str`):

1459 Required. The name of the subscription. Format is

1460 ``projects/{project}/subscriptions/{sub}``.

1461

1462 This corresponds to the ``subscription`` field

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

1464 should not be set.

1465 push_config (:class:`google.pubsub_v1.types.PushConfig`):

1466 Required. The push configuration for future deliveries.

1467

1468 An empty ``pushConfig`` indicates that the Pub/Sub

1469 system should stop pushing messages from the given

1470 subscription and allow messages to be pulled and

1471 acknowledged - effectively pausing the subscription if

1472 ``Pull`` or ``StreamingPull`` is not called.

1473

1474 This corresponds to the ``push_config`` field

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

1476 should not be set.

1477 retry (google.api_core.retry.Retry): Designation of what errors, if any,

1478 should be retried.

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

1480 metadata (Sequence[Tuple[str, str]]): Strings which should be

1481 sent along with the request as metadata.

1482 """

1483 # Create or coerce a protobuf request object.

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

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

1486 has_flattened_params = any([subscription, push_config])

1487 if request is not None and has_flattened_params:

1488 raise ValueError(

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

1490 "the individual field arguments should be set."

1491 )

1492

1493 request = pubsub.ModifyPushConfigRequest(request)

1494

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

1496 # request, apply these.

1497 if subscription is not None:

1498 request.subscription = subscription

1499 if push_config is not None:

1500 request.push_config = push_config

1501

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

1503 # and friendly error handling.

1504 rpc = gapic_v1.method_async.wrap_method(

1505 self._client._transport.modify_push_config,

1506 default_retry=retries.Retry(

1507 initial=0.1,

1508 maximum=60.0,

1509 multiplier=1.3,

1510 predicate=retries.if_exception_type(

1511 core_exceptions.ServiceUnavailable,

1512 ),

1513 deadline=60.0,

1514 ),

1515 default_timeout=60.0,

1516 client_info=DEFAULT_CLIENT_INFO,

1517 )

1518

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

1520 # add these here.

1521 metadata = tuple(metadata) + (

1522 gapic_v1.routing_header.to_grpc_metadata(

1523 (("subscription", request.subscription),)

1524 ),

1525 )

1526

1527 # Send the request.

1528 await rpc(

1529 request,

1530 retry=retry,

1531 timeout=timeout,

1532 metadata=metadata,

1533 )

1534

1535 async def get_snapshot(

1536 self,

1537 request: Optional[Union[pubsub.GetSnapshotRequest, dict]] = None,

1538 *,

1539 snapshot: Optional[str] = None,

1540 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

1542 metadata: Sequence[Tuple[str, str]] = (),

1543 ) -> pubsub.Snapshot:

1544 r"""Gets the configuration details of a snapshot. Snapshots are used

1545 in

1546 `Seek <https://cloud.google.com/pubsub/docs/replay-overview>`__

1547 operations, which allow you to manage message acknowledgments in

1548 bulk. That is, you can set the acknowledgment state of messages

1549 in an existing subscription to the state captured by a snapshot.

1550

1551 .. code-block:: python

1552

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

1554 # code template only.

1555 # It will require modifications to work:

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

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

1558 # client as shown in:

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

1560 from google import pubsub_v1

1561

1562 async def sample_get_snapshot():

1563 # Create a client

1564 client = pubsub_v1.SubscriberAsyncClient()

1565

1566 # Initialize request argument(s)

1567 request = pubsub_v1.GetSnapshotRequest(

1568 snapshot="snapshot_value",

1569 )

1570

1571 # Make the request

1572 response = await client.get_snapshot(request=request)

1573

1574 # Handle the response

1575 print(response)

1576

1577 Args:

1578 request (Optional[Union[google.pubsub_v1.types.GetSnapshotRequest, dict]]):

1579 The request object. Request for the GetSnapshot method.

1580 snapshot (:class:`str`):

1581 Required. The name of the snapshot to get. Format is

1582 ``projects/{project}/snapshots/{snap}``.

1583

1584 This corresponds to the ``snapshot`` field

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

1586 should not be set.

1587 retry (google.api_core.retry.Retry): Designation of what errors, if any,

1588 should be retried.

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

1590 metadata (Sequence[Tuple[str, str]]): Strings which should be

1591 sent along with the request as metadata.

1592

1593 Returns:

1594 google.pubsub_v1.types.Snapshot:

1595 A snapshot resource. Snapshots are used in

1596 [Seek](https://cloud.google.com/pubsub/docs/replay-overview)

1597 operations, which allow you to manage message

1598 acknowledgments in bulk. That is, you can set the

1599 acknowledgment state of messages in an existing

1600 subscription to the state captured by a snapshot.

1601

1602 """

1603 # Create or coerce a protobuf request object.

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

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

1606 has_flattened_params = any([snapshot])

1607 if request is not None and has_flattened_params:

1608 raise ValueError(

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

1610 "the individual field arguments should be set."

1611 )

1612

1613 request = pubsub.GetSnapshotRequest(request)

1614

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

1616 # request, apply these.

1617 if snapshot is not None:

1618 request.snapshot = snapshot

1619

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

1621 # and friendly error handling.

1622 rpc = gapic_v1.method_async.wrap_method(

1623 self._client._transport.get_snapshot,

1624 default_retry=retries.Retry(

1625 initial=0.1,

1626 maximum=60.0,

1627 multiplier=1.3,

1628 predicate=retries.if_exception_type(

1629 core_exceptions.Aborted,

1630 core_exceptions.ServiceUnavailable,

1631 core_exceptions.Unknown,

1632 ),

1633 deadline=60.0,

1634 ),

1635 default_timeout=60.0,

1636 client_info=DEFAULT_CLIENT_INFO,

1637 )

1638

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

1640 # add these here.

1641 metadata = tuple(metadata) + (

1642 gapic_v1.routing_header.to_grpc_metadata((("snapshot", request.snapshot),)),

1643 )

1644

1645 # Send the request.

1646 response = await rpc(

1647 request,

1648 retry=retry,

1649 timeout=timeout,

1650 metadata=metadata,

1651 )

1652

1653 # Done; return the response.

1654 return response

1655

1656 async def list_snapshots(

1657 self,

1658 request: Optional[Union[pubsub.ListSnapshotsRequest, dict]] = None,

1659 *,

1660 project: Optional[str] = None,

1661 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

1663 metadata: Sequence[Tuple[str, str]] = (),

1664 ) -> pagers.ListSnapshotsAsyncPager:

1665 r"""Lists the existing snapshots. Snapshots are used in

1666 `Seek <https://cloud.google.com/pubsub/docs/replay-overview>`__

1667 operations, which allow you to manage message acknowledgments in

1668 bulk. That is, you can set the acknowledgment state of messages

1669 in an existing subscription to the state captured by a snapshot.

1670

1671 .. code-block:: python

1672

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

1674 # code template only.

1675 # It will require modifications to work:

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

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

1678 # client as shown in:

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

1680 from google import pubsub_v1

1681

1682 async def sample_list_snapshots():

1683 # Create a client

1684 client = pubsub_v1.SubscriberAsyncClient()

1685

1686 # Initialize request argument(s)

1687 request = pubsub_v1.ListSnapshotsRequest(

1688 project="project_value",

1689 )

1690

1691 # Make the request

1692 page_result = client.list_snapshots(request=request)

1693

1694 # Handle the response

1695 async for response in page_result:

1696 print(response)

1697

1698 Args:

1699 request (Optional[Union[google.pubsub_v1.types.ListSnapshotsRequest, dict]]):

1700 The request object. Request for the `ListSnapshots`

1701 method.

1702 project (:class:`str`):

1703 Required. The name of the project in which to list

1704 snapshots. Format is ``projects/{project-id}``.

1705

1706 This corresponds to the ``project`` field

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

1708 should not be set.

1709 retry (google.api_core.retry.Retry): Designation of what errors, if any,

1710 should be retried.

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

1712 metadata (Sequence[Tuple[str, str]]): Strings which should be

1713 sent along with the request as metadata.

1714

1715 Returns:

1716 google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager:

1717 Response for the ListSnapshots method.

1718

1719 Iterating over this object will yield results and

1720 resolve additional pages automatically.

1721

1722 """

1723 # Create or coerce a protobuf request object.

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

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

1726 has_flattened_params = any([project])

1727 if request is not None and has_flattened_params:

1728 raise ValueError(

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

1730 "the individual field arguments should be set."

1731 )

1732

1733 request = pubsub.ListSnapshotsRequest(request)

1734

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

1736 # request, apply these.

1737 if project is not None:

1738 request.project = project

1739

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

1741 # and friendly error handling.

1742 rpc = gapic_v1.method_async.wrap_method(

1743 self._client._transport.list_snapshots,

1744 default_retry=retries.Retry(

1745 initial=0.1,

1746 maximum=60.0,

1747 multiplier=1.3,

1748 predicate=retries.if_exception_type(

1749 core_exceptions.Aborted,

1750 core_exceptions.ServiceUnavailable,

1751 core_exceptions.Unknown,

1752 ),

1753 deadline=60.0,

1754 ),

1755 default_timeout=60.0,

1756 client_info=DEFAULT_CLIENT_INFO,

1757 )

1758

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

1760 # add these here.

1761 metadata = tuple(metadata) + (

1762 gapic_v1.routing_header.to_grpc_metadata((("project", request.project),)),

1763 )

1764

1765 # Send the request.

1766 response = await rpc(

1767 request,

1768 retry=retry,

1769 timeout=timeout,

1770 metadata=metadata,

1771 )

1772

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

1774 # an `__aiter__` convenience method.

1775 response = pagers.ListSnapshotsAsyncPager(

1776 method=rpc,

1777 request=request,

1778 response=response,

1779 metadata=metadata,

1780 )

1781

1782 # Done; return the response.

1783 return response

1784

1785 async def create_snapshot(

1786 self,

1787 request: Optional[Union[pubsub.CreateSnapshotRequest, dict]] = None,

1788 *,

1789 name: Optional[str] = None,

1790 subscription: Optional[str] = None,

1791 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

1793 metadata: Sequence[Tuple[str, str]] = (),

1794 ) -> pubsub.Snapshot:

1795 r"""Creates a snapshot from the requested subscription. Snapshots

1796 are used in

1797 `Seek <https://cloud.google.com/pubsub/docs/replay-overview>`__

1798 operations, which allow you to manage message acknowledgments in

1799 bulk. That is, you can set the acknowledgment state of messages

1800 in an existing subscription to the state captured by a snapshot.

1801 If the snapshot already exists, returns ``ALREADY_EXISTS``. If

1802 the requested subscription doesn't exist, returns ``NOT_FOUND``.

1803 If the backlog in the subscription is too old -- and the

1804 resulting snapshot would expire in less than 1 hour -- then

1805 ``FAILED_PRECONDITION`` is returned. See also the

1806 ``Snapshot.expire_time`` field. If the name is not provided in

1807 the request, the server will assign a random name for this

1808 snapshot on the same project as the subscription, conforming to

1809 the [resource name format]

1810 (https://cloud.google.com/pubsub/docs/admin#resource_names). The

1811 generated name is populated in the returned Snapshot object.

1812 Note that for REST API requests, you must specify a name in the

1813 request.

1814

1815 .. code-block:: python

1816

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

1818 # code template only.

1819 # It will require modifications to work:

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

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

1822 # client as shown in:

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

1824 from google import pubsub_v1

1825

1826 async def sample_create_snapshot():

1827 # Create a client

1828 client = pubsub_v1.SubscriberAsyncClient()

1829

1830 # Initialize request argument(s)

1831 request = pubsub_v1.CreateSnapshotRequest(

1832 name="name_value",

1833 subscription="subscription_value",

1834 )

1835

1836 # Make the request

1837 response = await client.create_snapshot(request=request)

1838

1839 # Handle the response

1840 print(response)

1841

1842 Args:

1843 request (Optional[Union[google.pubsub_v1.types.CreateSnapshotRequest, dict]]):

1844 The request object. Request for the `CreateSnapshot`

1845 method.

1846 name (:class:`str`):

1847 Required. User-provided name for this snapshot. If the

1848 name is not provided in the request, the server will

1849 assign a random name for this snapshot on the same

1850 project as the subscription. Note that for REST API

1851 requests, you must specify a name. See the `resource

1852 name

1853 rules <https://cloud.google.com/pubsub/docs/admin#resource_names>`__.

1854 Format is ``projects/{project}/snapshots/{snap}``.

1855

1856 This corresponds to the ``name`` field

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

1858 should not be set.

1859 subscription (:class:`str`):

1860 Required. The subscription whose backlog the snapshot

1861 retains. Specifically, the created snapshot is

1862 guaranteed to retain: (a) The existing backlog on the

1863 subscription. More precisely, this is defined as the

1864 messages in the subscription's backlog that are

1865 unacknowledged upon the successful completion of the

1866 ``CreateSnapshot`` request; as well as: (b) Any messages

1867 published to the subscription's topic following the

1868 successful completion of the CreateSnapshot request.

1869 Format is ``projects/{project}/subscriptions/{sub}``.

1870

1871 This corresponds to the ``subscription`` field

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

1873 should not be set.

1874 retry (google.api_core.retry.Retry): Designation of what errors, if any,

1875 should be retried.

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

1877 metadata (Sequence[Tuple[str, str]]): Strings which should be

1878 sent along with the request as metadata.

1879

1880 Returns:

1881 google.pubsub_v1.types.Snapshot:

1882 A snapshot resource. Snapshots are used in

1883 [Seek](https://cloud.google.com/pubsub/docs/replay-overview)

1884 operations, which allow you to manage message

1885 acknowledgments in bulk. That is, you can set the

1886 acknowledgment state of messages in an existing

1887 subscription to the state captured by a snapshot.

1888

1889 """

1890 # Create or coerce a protobuf request object.

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

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

1893 has_flattened_params = any([name, subscription])

1894 if request is not None and has_flattened_params:

1895 raise ValueError(

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

1897 "the individual field arguments should be set."

1898 )

1899

1900 request = pubsub.CreateSnapshotRequest(request)

1901

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

1903 # request, apply these.

1904 if name is not None:

1905 request.name = name

1906 if subscription is not None:

1907 request.subscription = subscription

1908

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

1910 # and friendly error handling.

1911 rpc = gapic_v1.method_async.wrap_method(

1912 self._client._transport.create_snapshot,

1913 default_retry=retries.Retry(

1914 initial=0.1,

1915 maximum=60.0,

1916 multiplier=1.3,

1917 predicate=retries.if_exception_type(

1918 core_exceptions.ServiceUnavailable,

1919 ),

1920 deadline=60.0,

1921 ),

1922 default_timeout=60.0,

1923 client_info=DEFAULT_CLIENT_INFO,

1924 )

1925

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

1927 # add these here.

1928 metadata = tuple(metadata) + (

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

1930 )

1931

1932 # Send the request.

1933 response = await rpc(

1934 request,

1935 retry=retry,

1936 timeout=timeout,

1937 metadata=metadata,

1938 )

1939

1940 # Done; return the response.

1941 return response

1942

1943 async def update_snapshot(

1944 self,

1945 request: Optional[Union[pubsub.UpdateSnapshotRequest, dict]] = None,

1946 *,

1947 snapshot: Optional[pubsub.Snapshot] = None,

1948 update_mask: Optional[field_mask_pb2.FieldMask] = None,

1949 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

1951 metadata: Sequence[Tuple[str, str]] = (),

1952 ) -> pubsub.Snapshot:

1953 r"""Updates an existing snapshot. Snapshots are used in

1954 `Seek <https://cloud.google.com/pubsub/docs/replay-overview>`__

1955 operations, which allow you to manage message acknowledgments in

1956 bulk. That is, you can set the acknowledgment state of messages

1957 in an existing subscription to the state captured by a snapshot.

1958

1959 .. code-block:: python

1960

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

1962 # code template only.

1963 # It will require modifications to work:

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

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

1966 # client as shown in:

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

1968 from google import pubsub_v1

1969

1970 async def sample_update_snapshot():

1971 # Create a client

1972 client = pubsub_v1.SubscriberAsyncClient()

1973

1974 # Initialize request argument(s)

1975 request = pubsub_v1.UpdateSnapshotRequest(

1976 )

1977

1978 # Make the request

1979 response = await client.update_snapshot(request=request)

1980

1981 # Handle the response

1982 print(response)

1983

1984 Args:

1985 request (Optional[Union[google.pubsub_v1.types.UpdateSnapshotRequest, dict]]):

1986 The request object. Request for the UpdateSnapshot

1987 method.

1988 snapshot (:class:`google.pubsub_v1.types.Snapshot`):

1989 Required. The updated snapshot

1990 object.

1991

1992 This corresponds to the ``snapshot`` field

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

1994 should not be set.

1995 update_mask (:class:`google.protobuf.field_mask_pb2.FieldMask`):

1996 Required. Indicates which fields in

1997 the provided snapshot to update. Must be

1998 specified and non-empty.

1999

2000 This corresponds to the ``update_mask`` field

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

2002 should not be set.

2003 retry (google.api_core.retry.Retry): Designation of what errors, if any,

2004 should be retried.

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

2006 metadata (Sequence[Tuple[str, str]]): Strings which should be

2007 sent along with the request as metadata.

2008

2009 Returns:

2010 google.pubsub_v1.types.Snapshot:

2011 A snapshot resource. Snapshots are used in

2012 [Seek](https://cloud.google.com/pubsub/docs/replay-overview)

2013 operations, which allow you to manage message

2014 acknowledgments in bulk. That is, you can set the

2015 acknowledgment state of messages in an existing

2016 subscription to the state captured by a snapshot.

2017

2018 """

2019 # Create or coerce a protobuf request object.

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

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

2022 has_flattened_params = any([snapshot, update_mask])

2023 if request is not None and has_flattened_params:

2024 raise ValueError(

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

2026 "the individual field arguments should be set."

2027 )

2028

2029 request = pubsub.UpdateSnapshotRequest(request)

2030

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

2032 # request, apply these.

2033 if snapshot is not None:

2034 request.snapshot = snapshot

2035 if update_mask is not None:

2036 request.update_mask = update_mask

2037

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

2039 # and friendly error handling.

2040 rpc = gapic_v1.method_async.wrap_method(

2041 self._client._transport.update_snapshot,

2042 default_retry=retries.Retry(

2043 initial=0.1,

2044 maximum=60.0,

2045 multiplier=1.3,

2046 predicate=retries.if_exception_type(

2047 core_exceptions.ServiceUnavailable,

2048 ),

2049 deadline=60.0,

2050 ),

2051 default_timeout=60.0,

2052 client_info=DEFAULT_CLIENT_INFO,

2053 )

2054

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

2056 # add these here.

2057 metadata = tuple(metadata) + (

2058 gapic_v1.routing_header.to_grpc_metadata(

2059 (("snapshot.name", request.snapshot.name),)

2060 ),

2061 )

2062

2063 # Send the request.

2064 response = await rpc(

2065 request,

2066 retry=retry,

2067 timeout=timeout,

2068 metadata=metadata,

2069 )

2070

2071 # Done; return the response.

2072 return response

2073

2074 async def delete_snapshot(

2075 self,

2076 request: Optional[Union[pubsub.DeleteSnapshotRequest, dict]] = None,

2077 *,

2078 snapshot: Optional[str] = None,

2079 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

2081 metadata: Sequence[Tuple[str, str]] = (),

2082 ) -> None:

2083 r"""Removes an existing snapshot. Snapshots are used in [Seek]

2084 (https://cloud.google.com/pubsub/docs/replay-overview)

2085 operations, which allow you to manage message acknowledgments in

2086 bulk. That is, you can set the acknowledgment state of messages

2087 in an existing subscription to the state captured by a snapshot.

2088 When the snapshot is deleted, all messages retained in the

2089 snapshot are immediately dropped. After a snapshot is deleted, a

2090 new one may be created with the same name, but the new one has

2091 no association with the old snapshot or its subscription, unless

2092 the same subscription is specified.

2093

2094 .. code-block:: python

2095

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

2097 # code template only.

2098 # It will require modifications to work:

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

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

2101 # client as shown in:

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

2103 from google import pubsub_v1

2104

2105 async def sample_delete_snapshot():

2106 # Create a client

2107 client = pubsub_v1.SubscriberAsyncClient()

2108

2109 # Initialize request argument(s)

2110 request = pubsub_v1.DeleteSnapshotRequest(

2111 snapshot="snapshot_value",

2112 )

2113

2114 # Make the request

2115 await client.delete_snapshot(request=request)

2116

2117 Args:

2118 request (Optional[Union[google.pubsub_v1.types.DeleteSnapshotRequest, dict]]):

2119 The request object. Request for the `DeleteSnapshot`

2120 method.

2121 snapshot (:class:`str`):

2122 Required. The name of the snapshot to delete. Format is

2123 ``projects/{project}/snapshots/{snap}``.

2124

2125 This corresponds to the ``snapshot`` field

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

2127 should not be set.

2128 retry (google.api_core.retry.Retry): Designation of what errors, if any,

2129 should be retried.

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

2131 metadata (Sequence[Tuple[str, str]]): Strings which should be

2132 sent along with the request as metadata.

2133 """

2134 # Create or coerce a protobuf request object.

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

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

2137 has_flattened_params = any([snapshot])

2138 if request is not None and has_flattened_params:

2139 raise ValueError(

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

2141 "the individual field arguments should be set."

2142 )

2143

2144 request = pubsub.DeleteSnapshotRequest(request)

2145

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

2147 # request, apply these.

2148 if snapshot is not None:

2149 request.snapshot = snapshot

2150

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

2152 # and friendly error handling.

2153 rpc = gapic_v1.method_async.wrap_method(

2154 self._client._transport.delete_snapshot,

2155 default_retry=retries.Retry(

2156 initial=0.1,

2157 maximum=60.0,

2158 multiplier=1.3,

2159 predicate=retries.if_exception_type(

2160 core_exceptions.ServiceUnavailable,

2161 ),

2162 deadline=60.0,

2163 ),

2164 default_timeout=60.0,

2165 client_info=DEFAULT_CLIENT_INFO,

2166 )

2167

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

2169 # add these here.

2170 metadata = tuple(metadata) + (

2171 gapic_v1.routing_header.to_grpc_metadata((("snapshot", request.snapshot),)),

2172 )

2173

2174 # Send the request.

2175 await rpc(

2176 request,

2177 retry=retry,

2178 timeout=timeout,

2179 metadata=metadata,

2180 )

2181

2182 async def seek(

2183 self,

2184 request: Optional[Union[pubsub.SeekRequest, dict]] = None,

2185 *,

2186 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

2188 metadata: Sequence[Tuple[str, str]] = (),

2189 ) -> pubsub.SeekResponse:

2190 r"""Seeks an existing subscription to a point in time or to a given

2191 snapshot, whichever is provided in the request. Snapshots are

2192 used in [Seek]

2193 (https://cloud.google.com/pubsub/docs/replay-overview)

2194 operations, which allow you to manage message acknowledgments in

2195 bulk. That is, you can set the acknowledgment state of messages

2196 in an existing subscription to the state captured by a snapshot.

2197 Note that both the subscription and the snapshot must be on the

2198 same topic.

2199

2200 .. code-block:: python

2201

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

2203 # code template only.

2204 # It will require modifications to work:

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

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

2207 # client as shown in:

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

2209 from google import pubsub_v1

2210

2211 async def sample_seek():

2212 # Create a client

2213 client = pubsub_v1.SubscriberAsyncClient()

2214

2215 # Initialize request argument(s)

2216 request = pubsub_v1.SeekRequest(

2217 subscription="subscription_value",

2218 )

2219

2220 # Make the request

2221 response = await client.seek(request=request)

2222

2223 # Handle the response

2224 print(response)

2225

2226 Args:

2227 request (Optional[Union[google.pubsub_v1.types.SeekRequest, dict]]):

2228 The request object. Request for the `Seek` method.

2229 retry (google.api_core.retry.Retry): Designation of what errors, if any,

2230 should be retried.

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

2232 metadata (Sequence[Tuple[str, str]]): Strings which should be

2233 sent along with the request as metadata.

2234

2235 Returns:

2236 google.pubsub_v1.types.SeekResponse:

2237 Response for the Seek method (this response is empty).

2238 """

2239 # Create or coerce a protobuf request object.

2240 request = pubsub.SeekRequest(request)

2241

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

2243 # and friendly error handling.

2244 rpc = gapic_v1.method_async.wrap_method(

2245 self._client._transport.seek,

2246 default_retry=retries.Retry(

2247 initial=0.1,

2248 maximum=60.0,

2249 multiplier=1.3,

2250 predicate=retries.if_exception_type(

2251 core_exceptions.Aborted,

2252 core_exceptions.ServiceUnavailable,

2253 core_exceptions.Unknown,

2254 ),

2255 deadline=60.0,

2256 ),

2257 default_timeout=60.0,

2258 client_info=DEFAULT_CLIENT_INFO,

2259 )

2260

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

2262 # add these here.

2263 metadata = tuple(metadata) + (

2264 gapic_v1.routing_header.to_grpc_metadata(

2265 (("subscription", request.subscription),)

2266 ),

2267 )

2268

2269 # Send the request.

2270 response = await rpc(

2271 request,

2272 retry=retry,

2273 timeout=timeout,

2274 metadata=metadata,

2275 )

2276

2277 # Done; return the response.

2278 return response

2279

2280 async def set_iam_policy(

2281 self,

2282 request: Optional[iam_policy_pb2.SetIamPolicyRequest] = None,

2283 *,

2284 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

2286 metadata: Sequence[Tuple[str, str]] = (),

2287 ) -> policy_pb2.Policy:

2288 r"""Sets the IAM access control policy on the specified function.

2289

2290 Replaces any existing policy.

2291

2292 Args:

2293 request (:class:`~.policy_pb2.SetIamPolicyRequest`):

2294 The request object. Request message for `SetIamPolicy`

2295 method.

2296 retry (google.api_core.retry.Retry): Designation of what errors, if any,

2297 should be retried.

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

2299 metadata (Sequence[Tuple[str, str]]): Strings which should be

2300 sent along with the request as metadata.

2301 Returns:

2302 ~.policy_pb2.Policy:

2303 Defines an Identity and Access Management (IAM) policy.

2304 It is used to specify access control policies for Cloud

2305 Platform resources.

2306 A ``Policy`` is a collection of ``bindings``. A

2307 ``binding`` binds one or more ``members`` to a single

2308 ``role``. Members can be user accounts, service

2309 accounts, Google groups, and domains (such as G Suite).

2310 A ``role`` is a named list of permissions (defined by

2311 IAM or configured by users). A ``binding`` can

2312 optionally specify a ``condition``, which is a logic

2313 expression that further constrains the role binding

2314 based on attributes about the request and/or target

2315 resource.

2316

2317 **JSON Example**

2318

2319 ::

2320 {

2321 "bindings": [

2322 {

2323 "role": "roles/resourcemanager.organizationAdmin",

2324 "members": [

2325 "user:mike@example.com",

2326 "group:admins@example.com",

2327 "domain:google.com",

2328 "serviceAccount:my-project-id@appspot.gserviceaccount.com"

2329 ]

2330 },

2331 {

2332 "role": "roles/resourcemanager.organizationViewer",

2333 "members": ["user:eve@example.com"],

2334 "condition": {

2335 "title": "expirable access",

2336 "description": "Does not grant access after Sep 2020",

2337 "expression": "request.time <

2338 timestamp('2020-10-01T00:00:00.000Z')",

2339 }

2340 }

2341 ]

2342 }

2343

2344 **YAML Example**

2345

2346 ::

2347

2348 bindings:

2349 - members:

2350 - user:mike@example.com

2351 - group:admins@example.com

2352 - domain:google.com

2353 - serviceAccount:my-project-id@appspot.gserviceaccount.com

2354 role: roles/resourcemanager.organizationAdmin

2355 - members:

2356 - user:eve@example.com

2357 role: roles/resourcemanager.organizationViewer

2358 condition:

2359 title: expirable access

2360 description: Does not grant access after Sep 2020

2361 expression: request.time < timestamp('2020-10-01T00:00:00.000Z')

2362

2363 For a description of IAM and its features, see the `IAM

2364 developer's

2365 guide <https://cloud.google.com/iam/docs>`__.

2366 """

2367 # Create or coerce a protobuf request object.

2368

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

2370 # so it must be constructed via keyword expansion.

2371 if isinstance(request, dict):

2372 request = iam_policy_pb2.SetIamPolicyRequest(**request)

2373

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

2375 # and friendly error handling.

2376 rpc = gapic_v1.method_async.wrap_method(

2377 self._client._transport.set_iam_policy,

2378 default_timeout=None,

2379 client_info=DEFAULT_CLIENT_INFO,

2380 )

2381

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

2383 # add these here.

2384 metadata = tuple(metadata) + (

2385 gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),

2386 )

2387

2388 # Send the request.

2389 response = await rpc(

2390 request,

2391 retry=retry,

2392 timeout=timeout,

2393 metadata=metadata,

2394 )

2395

2396 # Done; return the response.

2397 return response

2398

2399 async def get_iam_policy(

2400 self,

2401 request: Optional[iam_policy_pb2.GetIamPolicyRequest] = None,

2402 *,

2403 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

2405 metadata: Sequence[Tuple[str, str]] = (),

2406 ) -> policy_pb2.Policy:

2407 r"""Gets the IAM access control policy for a function.

2408

2409 Returns an empty policy if the function exists and does

2410 not have a policy set.

2411

2412 Args:

2413 request (:class:`~.iam_policy_pb2.GetIamPolicyRequest`):

2414 The request object. Request message for `GetIamPolicy`

2415 method.

2416 retry (google.api_core.retry.Retry): Designation of what errors, if any,

2417 should be retried.

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

2419 metadata (Sequence[Tuple[str, str]]): Strings which should be

2420 sent along with the request as metadata.

2421 Returns:

2422 ~.policy_pb2.Policy:

2423 Defines an Identity and Access Management (IAM) policy.

2424 It is used to specify access control policies for Cloud

2425 Platform resources.

2426 A ``Policy`` is a collection of ``bindings``. A

2427 ``binding`` binds one or more ``members`` to a single

2428 ``role``. Members can be user accounts, service

2429 accounts, Google groups, and domains (such as G Suite).

2430 A ``role`` is a named list of permissions (defined by

2431 IAM or configured by users). A ``binding`` can

2432 optionally specify a ``condition``, which is a logic

2433 expression that further constrains the role binding

2434 based on attributes about the request and/or target

2435 resource.

2436

2437 **JSON Example**

2438

2439 ::

2440

2441 {

2442 "bindings": [

2443 {

2444 "role": "roles/resourcemanager.organizationAdmin",

2445 "members": [

2446 "user:mike@example.com",

2447 "group:admins@example.com",

2448 "domain:google.com",

2449 "serviceAccount:my-project-id@appspot.gserviceaccount.com"

2450 ]

2451 },

2452 {

2453 "role": "roles/resourcemanager.organizationViewer",

2454 "members": ["user:eve@example.com"],

2455 "condition": {

2456 "title": "expirable access",

2457 "description": "Does not grant access after Sep 2020",

2458 "expression": "request.time <

2459 timestamp('2020-10-01T00:00:00.000Z')",

2460 }

2461 }

2462 ]

2463 }

2464

2465 **YAML Example**

2466

2467 ::

2468

2469 bindings:

2470 - members:

2471 - user:mike@example.com

2472 - group:admins@example.com

2473 - domain:google.com

2474 - serviceAccount:my-project-id@appspot.gserviceaccount.com

2475 role: roles/resourcemanager.organizationAdmin

2476 - members:

2477 - user:eve@example.com

2478 role: roles/resourcemanager.organizationViewer

2479 condition:

2480 title: expirable access

2481 description: Does not grant access after Sep 2020

2482 expression: request.time < timestamp('2020-10-01T00:00:00.000Z')

2483

2484 For a description of IAM and its features, see the `IAM

2485 developer's

2486 guide <https://cloud.google.com/iam/docs>`__.

2487 """

2488 # Create or coerce a protobuf request object.

2489

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

2491 # so it must be constructed via keyword expansion.

2492 if isinstance(request, dict):

2493 request = iam_policy_pb2.GetIamPolicyRequest(**request)

2494

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

2496 # and friendly error handling.

2497 rpc = gapic_v1.method_async.wrap_method(

2498 self._client._transport.get_iam_policy,

2499 default_timeout=None,

2500 client_info=DEFAULT_CLIENT_INFO,

2501 )

2502

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

2504 # add these here.

2505 metadata = tuple(metadata) + (

2506 gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),

2507 )

2508

2509 # Send the request.

2510 response = await rpc(

2511 request,

2512 retry=retry,

2513 timeout=timeout,

2514 metadata=metadata,

2515 )

2516

2517 # Done; return the response.

2518 return response

2519

2520 async def test_iam_permissions(

2521 self,

2522 request: Optional[iam_policy_pb2.TestIamPermissionsRequest] = None,

2523 *,

2524 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

2526 metadata: Sequence[Tuple[str, str]] = (),

2527 ) -> iam_policy_pb2.TestIamPermissionsResponse:

2528 r"""Tests the specified permissions against the IAM access control

2529 policy for a function.

2530

2531 If the function does not exist, this will

2532 return an empty set of permissions, not a NOT_FOUND error.

2533

2534 Args:

2535 request (:class:`~.iam_policy_pb2.TestIamPermissionsRequest`):

2536 The request object. Request message for

2537 `TestIamPermissions` method.

2538 retry (google.api_core.retry.Retry): Designation of what errors, if any,

2539 should be retried.

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

2541 metadata (Sequence[Tuple[str, str]]): Strings which should be

2542 sent along with the request as metadata.

2543 Returns:

2544 ~iam_policy_pb2.PolicyTestIamPermissionsResponse:

2545 Response message for ``TestIamPermissions`` method.

2546 """

2547 # Create or coerce a protobuf request object.

2548

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

2550 # so it must be constructed via keyword expansion.

2551 if isinstance(request, dict):

2552 request = iam_policy_pb2.TestIamPermissionsRequest(**request)

2553

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

2555 # and friendly error handling.

2556 rpc = gapic_v1.method_async.wrap_method(

2557 self._client._transport.test_iam_permissions,

2558 default_timeout=None,

2559 client_info=DEFAULT_CLIENT_INFO,

2560 )

2561

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

2563 # add these here.

2564 metadata = tuple(metadata) + (

2565 gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),

2566 )

2567

2568 # Send the request.

2569 response = await rpc(

2570 request,

2571 retry=retry,

2572 timeout=timeout,

2573 metadata=metadata,

2574 )

2575

2576 # Done; return the response.

2577 return response

2578

2579 async def __aenter__(self):

2580 return self

2581

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

2583 await self.transport.close()

2584

2585

2586DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(

2587 client_library_version=package_version.__version__

2588)

2589

2590

2591__all__ = ("SubscriberAsyncClient",)

Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/pubsub_v1/services/subscriber/async_client.py: 28%

274 statements