Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.10/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#

16import logging as std_logging

17from collections import OrderedDict

18import re

19from typing import (

20 Dict,

21 Callable,

22 Mapping,

23 MutableMapping,

24 MutableSequence,

25 Optional,

26 AsyncIterable,

27 Awaitable,

28 AsyncIterator,

29 Sequence,

30 Tuple,

31 Type,

32 Union,

33)

35import warnings

36from google.pubsub_v1 import gapic_version as package_version

38from google.api_core.client_options import ClientOptions

39from google.api_core import exceptions as core_exceptions

40from google.api_core import gapic_v1

41from google.api_core import retry_async as retries

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

43from google.oauth2 import service_account # type: ignore

46try:

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

48except AttributeError: # pragma: NO COVER

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

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

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

53from google.protobuf import duration_pb2 # type: ignore

54from google.protobuf import field_mask_pb2 # type: ignore

55from google.protobuf import timestamp_pb2 # type: ignore

56from google.pubsub_v1.services.subscriber import pagers

57from google.pubsub_v1.types import pubsub

58from .transports.base import SubscriberTransport, DEFAULT_CLIENT_INFO

59from .transports.grpc_asyncio import SubscriberGrpcAsyncIOTransport

60from .client import SubscriberClient

62try:

63 from google.api_core import client_logging # type: ignore

65 CLIENT_LOGGING_SUPPORTED = True # pragma: NO COVER

66except ImportError: # pragma: NO COVER

67 CLIENT_LOGGING_SUPPORTED = False

69_LOGGER = std_logging.getLogger(__name__)

72class SubscriberAsyncClient:

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

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

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

76 method.

77 """

79 _client: SubscriberClient

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

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

83 DEFAULT_ENDPOINT = SubscriberClient.DEFAULT_ENDPOINT

84 DEFAULT_MTLS_ENDPOINT = SubscriberClient.DEFAULT_MTLS_ENDPOINT

85 _DEFAULT_ENDPOINT_TEMPLATE = SubscriberClient._DEFAULT_ENDPOINT_TEMPLATE

86 _DEFAULT_UNIVERSE = SubscriberClient._DEFAULT_UNIVERSE

88 snapshot_path = staticmethod(SubscriberClient.snapshot_path)

89 parse_snapshot_path = staticmethod(SubscriberClient.parse_snapshot_path)

90 subscription_path = staticmethod(SubscriberClient.subscription_path)

91 parse_subscription_path = staticmethod(SubscriberClient.parse_subscription_path)

92 topic_path = staticmethod(SubscriberClient.topic_path)

93 parse_topic_path = staticmethod(SubscriberClient.parse_topic_path)

94 common_billing_account_path = staticmethod(

95 SubscriberClient.common_billing_account_path

96 )

97 parse_common_billing_account_path = staticmethod(

98 SubscriberClient.parse_common_billing_account_path

99 )

100 common_folder_path = staticmethod(SubscriberClient.common_folder_path)

101 parse_common_folder_path = staticmethod(SubscriberClient.parse_common_folder_path)

102 common_organization_path = staticmethod(SubscriberClient.common_organization_path)

103 parse_common_organization_path = staticmethod(

104 SubscriberClient.parse_common_organization_path

105 )

106 common_project_path = staticmethod(SubscriberClient.common_project_path)

107 parse_common_project_path = staticmethod(SubscriberClient.parse_common_project_path)

108 common_location_path = staticmethod(SubscriberClient.common_location_path)

109 parse_common_location_path = staticmethod(

110 SubscriberClient.parse_common_location_path

111 )

112

113 @classmethod

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

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

116 info.

117

118 Args:

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

120 args: Additional arguments to pass to the constructor.

121 kwargs: Additional arguments to pass to the constructor.

122

123 Returns:

124 SubscriberAsyncClient: The constructed client.

125 """

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

127

128 @classmethod

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

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

131 file.

132

133 Args:

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

135 file.

136 args: Additional arguments to pass to the constructor.

137 kwargs: Additional arguments to pass to the constructor.

138

139 Returns:

140 SubscriberAsyncClient: The constructed client.

141 """

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

143

144 from_service_account_json = from_service_account_file

145

146 @classmethod

147 def get_mtls_endpoint_and_cert_source(

148 cls, client_options: Optional[ClientOptions] = None

149 ):

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

151

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

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

154 client cert source is None.

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

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

157 source is None.

158

159 The API endpoint is determined in the following order:

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

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

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

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

164 use the default API endpoint.

165

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

167

168 Args:

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

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

171 in this method.

172

173 Returns:

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

175 client cert source to use.

176

177 Raises:

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

179 """

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

181

182 @property

183 def transport(self) -> SubscriberTransport:

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

185

186 Returns:

187 SubscriberTransport: The transport used by the client instance.

188 """

189 return self._client.transport

190

191 @property

192 def api_endpoint(self):

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

194

195 Returns:

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

197 """

198 return self._client._api_endpoint

199

200 @property

201 def universe_domain(self) -> str:

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

203

204 Returns:

205 str: The universe domain used

206 by the client instance.

207 """

208 return self._client._universe_domain

209

210 get_transport_class = SubscriberClient.get_transport_class

211

212 def __init__(

213 self,

214 *,

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

216 transport: Optional[

217 Union[str, SubscriberTransport, Callable[..., SubscriberTransport]]

218 ] = "grpc_asyncio",

219 client_options: Optional[ClientOptions] = None,

220 client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,

221 ) -> None:

222 """Instantiates the subscriber async client.

223

224 Args:

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

226 authorization credentials to attach to requests. These

227 credentials identify the application to the service; if none

228 are specified, the client will attempt to ascertain the

229 credentials from the environment.

230 transport (Optional[Union[str,SubscriberTransport,Callable[..., SubscriberTransport]]]):

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

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

233 arguments as used in the SubscriberTransport constructor.

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

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

236 Custom options for the client.

237

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

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

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

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

242 determined by the GOOGLE_API_USE_MTLS_ENDPOINT environment

243 variable, which have one of the following values:

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

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

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

247 the default value).

248

249 2. If the GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable

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

251 to provide a client certificate for mTLS transport. If

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

253 present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not

254 set, no client certificate will be used.

255

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

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

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

259 currently not supported for mTLS.

260

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

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

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

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

265 your own client library.

266

267 Raises:

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

269 creation failed for any reason.

270 """

271 self._client = SubscriberClient(

272 credentials=credentials,

273 transport=transport,

274 client_options=client_options,

275 client_info=client_info,

276 )

277

278 if CLIENT_LOGGING_SUPPORTED and _LOGGER.isEnabledFor(

279 std_logging.DEBUG

280 ): # pragma: NO COVER

281 _LOGGER.debug(

282 "Created client `google.pubsub_v1.SubscriberAsyncClient`.",

283 extra={

284 "serviceName": "google.pubsub.v1.Subscriber",

285 "universeDomain": getattr(

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

287 ),

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

289 "credentialsInfo": getattr(

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

291 )(),

292 }

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

294 else {

295 "serviceName": "google.pubsub.v1.Subscriber",

296 "credentialsType": None,

297 },

298 )

299

300 async def create_subscription(

301 self,

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

303 *,

304 name: Optional[str] = None,

305 topic: Optional[str] = None,

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

307 ack_deadline_seconds: Optional[int] = None,

308 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

311 ) -> pubsub.Subscription:

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

313 rules]

314 (https://cloud.google.com/pubsub/docs/pubsub-basics#resource_names).

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

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

317

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

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

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

321 (https://cloud.google.com/pubsub/docs/pubsub-basics#resource_names).

322 The generated name is populated in the returned Subscription

323 object. Note that for REST API requests, you must specify a name

324 in the request.

325

326 .. code-block:: python

327

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

329 # code template only.

330 # It will require modifications to work:

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

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

333 # client as shown in:

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

335 from google import pubsub_v1

336

337 async def sample_create_subscription():

338 # Create a client

339 client = pubsub_v1.SubscriberAsyncClient()

340

341 # Initialize request argument(s)

342 request = pubsub_v1.Subscription(

343 name="name_value",

344 topic="topic_value",

345 )

346

347 # Make the request

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

349

350 # Handle the response

351 print(response)

352

353 Args:

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

355 The request object. A subscription resource. If none of ``push_config``,

356 ``bigquery_config``, or ``cloud_storage_config`` is set,

357 then the subscriber will pull and ack messages using API

358 methods. At most one of these fields may be set.

359 name (:class:`str`):

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

361 format

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

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

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

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

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

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

368 not start with ``"goog"``.

369

370 This corresponds to the ``name`` field

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

372 should not be set.

373 topic (:class:`str`):

374 Required. The name of the topic from which this

375 subscription is receiving messages. Format is

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

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

378 deleted.

379

380 This corresponds to the ``topic`` field

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

382 should not be set.

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

384 Optional. If push delivery is used

385 with this subscription, this field is

386 used to configure it.

387

388 This corresponds to the ``push_config`` field

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

390 should not be set.

391 ack_deadline_seconds (:class:`int`):

392 Optional. The approximate amount of time (on a

393 best-effort basis) Pub/Sub waits for the subscriber to

394 acknowledge receipt before resending the message. In the

395 interval after the message is delivered and before it is

396 acknowledged, it is considered to be *outstanding*.

397 During that time period, the message will not be

398 redelivered (on a best-effort basis).

399

400 For pull subscriptions, this value is used as the

401 initial value for the ack deadline. To override this

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

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

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

405 ``StreamingModifyAckDeadlineRequest`` if using streaming

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

407 seconds. The maximum custom deadline you can specify is

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

409 default value of 10 seconds is used.

410

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

412 request timeout for the call to the push endpoint.

413

414 If the subscriber never acknowledges the message, the

415 Pub/Sub system will eventually redeliver the message.

416

417 This corresponds to the ``ack_deadline_seconds`` field

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

419 should not be set.

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

421 should be retried.

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

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

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

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

426 be of type `bytes`.

427

428 Returns:

429 google.pubsub_v1.types.Subscription:

430 A subscription resource. If none of push_config, bigquery_config, or

431 cloud_storage_config is set, then the subscriber will

432 pull and ack messages using API methods. At most one

433 of these fields may be set.

434

435 """

436 # Create or coerce a protobuf request object.

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

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

439 flattened_params = [name, topic, push_config, ack_deadline_seconds]

440 has_flattened_params = (

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

442 )

443 if request is not None and has_flattened_params:

444 raise ValueError(

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

446 "the individual field arguments should be set."

447 )

448

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

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

451 if not isinstance(request, pubsub.Subscription):

452 request = pubsub.Subscription(request)

453

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

455 # request, apply these.

456 if name is not None:

457 request.name = name

458 if topic is not None:

459 request.topic = topic

460 if push_config is not None:

461 request.push_config = push_config

462 if ack_deadline_seconds is not None:

463 request.ack_deadline_seconds = ack_deadline_seconds

464

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

466 # and friendly error handling.

467 rpc = self._client._transport._wrapped_methods[

468 self._client._transport.create_subscription

469 ]

470

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

472 # add these here.

473 metadata = tuple(metadata) + (

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

475 )

476

477 # Validate the universe domain.

478 self._client._validate_universe_domain()

479

480 # Send the request.

481 response = await rpc(

482 request,

483 retry=retry,

484 timeout=timeout,

485 metadata=metadata,

486 )

487

488 # Done; return the response.

489 return response

490

491 async def get_subscription(

492 self,

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

494 *,

495 subscription: Optional[str] = None,

496 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

499 ) -> pubsub.Subscription:

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

501

502 .. code-block:: python

503

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

505 # code template only.

506 # It will require modifications to work:

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

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

509 # client as shown in:

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

511 from google import pubsub_v1

512

513 async def sample_get_subscription():

514 # Create a client

515 client = pubsub_v1.SubscriberAsyncClient()

516

517 # Initialize request argument(s)

518 request = pubsub_v1.GetSubscriptionRequest(

519 subscription="subscription_value",

520 )

521

522 # Make the request

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

524

525 # Handle the response

526 print(response)

527

528 Args:

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

530 The request object. Request for the GetSubscription

531 method.

532 subscription (:class:`str`):

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

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

535

536 This corresponds to the ``subscription`` field

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

538 should not be set.

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

540 should be retried.

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

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

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

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

545 be of type `bytes`.

546

547 Returns:

548 google.pubsub_v1.types.Subscription:

549 A subscription resource. If none of push_config, bigquery_config, or

550 cloud_storage_config is set, then the subscriber will

551 pull and ack messages using API methods. At most one

552 of these fields may be set.

553

554 """

555 # Create or coerce a protobuf request object.

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

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

558 flattened_params = [subscription]

559 has_flattened_params = (

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

561 )

562 if request is not None and has_flattened_params:

563 raise ValueError(

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

565 "the individual field arguments should be set."

566 )

567

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

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

570 if not isinstance(request, pubsub.GetSubscriptionRequest):

571 request = pubsub.GetSubscriptionRequest(request)

572

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

574 # request, apply these.

575 if subscription is not None:

576 request.subscription = subscription

577

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

579 # and friendly error handling.

580 rpc = self._client._transport._wrapped_methods[

581 self._client._transport.get_subscription

582 ]

583

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

585 # add these here.

586 metadata = tuple(metadata) + (

587 gapic_v1.routing_header.to_grpc_metadata(

588 (("subscription", request.subscription),)

589 ),

590 )

591

592 # Validate the universe domain.

593 self._client._validate_universe_domain()

594

595 # Send the request.

596 response = await rpc(

597 request,

598 retry=retry,

599 timeout=timeout,

600 metadata=metadata,

601 )

602

603 # Done; return the response.

604 return response

605

606 async def update_subscription(

607 self,

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

609 *,

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

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

612 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

615 ) -> pubsub.Subscription:

616 r"""Updates an existing subscription by updating the

617 fields specified in the update mask. Note that certain

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

619 modifiable.

620

621 .. code-block:: python

622

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

624 # code template only.

625 # It will require modifications to work:

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

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

628 # client as shown in:

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

630 from google import pubsub_v1

631

632 async def sample_update_subscription():

633 # Create a client

634 client = pubsub_v1.SubscriberAsyncClient()

635

636 # Initialize request argument(s)

637 subscription = pubsub_v1.Subscription()

638 subscription.name = "name_value"

639 subscription.topic = "topic_value"

640

641 request = pubsub_v1.UpdateSubscriptionRequest(

642 subscription=subscription,

643 )

644

645 # Make the request

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

647

648 # Handle the response

649 print(response)

650

651 Args:

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

653 The request object. Request for the UpdateSubscription

654 method.

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

656 Required. The updated subscription

657 object.

658

659 This corresponds to the ``subscription`` field

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

661 should not be set.

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

663 Required. Indicates which fields in

664 the provided subscription to update.

665 Must be specified and non-empty.

666

667 This corresponds to the ``update_mask`` field

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

669 should not be set.

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

671 should be retried.

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

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

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

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

676 be of type `bytes`.

677

678 Returns:

679 google.pubsub_v1.types.Subscription:

680 A subscription resource. If none of push_config, bigquery_config, or

681 cloud_storage_config is set, then the subscriber will

682 pull and ack messages using API methods. At most one

683 of these fields may be set.

684

685 """

686 # Create or coerce a protobuf request object.

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

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

689 flattened_params = [subscription, update_mask]

690 has_flattened_params = (

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

692 )

693 if request is not None and has_flattened_params:

694 raise ValueError(

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

696 "the individual field arguments should be set."

697 )

698

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

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

701 if not isinstance(request, pubsub.UpdateSubscriptionRequest):

702 request = pubsub.UpdateSubscriptionRequest(request)

703

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

705 # request, apply these.

706 if subscription is not None:

707 request.subscription = subscription

708 if update_mask is not None:

709 request.update_mask = update_mask

710

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

712 # and friendly error handling.

713 rpc = self._client._transport._wrapped_methods[

714 self._client._transport.update_subscription

715 ]

716

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

718 # add these here.

719 metadata = tuple(metadata) + (

720 gapic_v1.routing_header.to_grpc_metadata(

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

722 ),

723 )

724

725 # Validate the universe domain.

726 self._client._validate_universe_domain()

727

728 # Send the request.

729 response = await rpc(

730 request,

731 retry=retry,

732 timeout=timeout,

733 metadata=metadata,

734 )

735

736 # Done; return the response.

737 return response

738

739 async def list_subscriptions(

740 self,

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

742 *,

743 project: Optional[str] = None,

744 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

747 ) -> pagers.ListSubscriptionsAsyncPager:

748 r"""Lists matching subscriptions.

749

750 .. code-block:: python

751

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

753 # code template only.

754 # It will require modifications to work:

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

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

757 # client as shown in:

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

759 from google import pubsub_v1

760

761 async def sample_list_subscriptions():

762 # Create a client

763 client = pubsub_v1.SubscriberAsyncClient()

764

765 # Initialize request argument(s)

766 request = pubsub_v1.ListSubscriptionsRequest(

767 project="project_value",

768 )

769

770 # Make the request

771 page_result = client.list_subscriptions(request=request)

772

773 # Handle the response

774 async for response in page_result:

775 print(response)

776

777 Args:

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

779 The request object. Request for the ``ListSubscriptions`` method.

780 project (:class:`str`):

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

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

783

784 This corresponds to the ``project`` field

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

786 should not be set.

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

788 should be retried.

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

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

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

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

793 be of type `bytes`.

794

795 Returns:

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

797 Response for the ListSubscriptions method.

798

799 Iterating over this object will yield results and

800 resolve additional pages automatically.

801

802 """

803 # Create or coerce a protobuf request object.

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

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

806 flattened_params = [project]

807 has_flattened_params = (

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

809 )

810 if request is not None and has_flattened_params:

811 raise ValueError(

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

813 "the individual field arguments should be set."

814 )

815

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

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

818 if not isinstance(request, pubsub.ListSubscriptionsRequest):

819 request = pubsub.ListSubscriptionsRequest(request)

820

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

822 # request, apply these.

823 if project is not None:

824 request.project = project

825

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

827 # and friendly error handling.

828 rpc = self._client._transport._wrapped_methods[

829 self._client._transport.list_subscriptions

830 ]

831

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

833 # add these here.

834 metadata = tuple(metadata) + (

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

836 )

837

838 # Validate the universe domain.

839 self._client._validate_universe_domain()

840

841 # Send the request.

842 response = await rpc(

843 request,

844 retry=retry,

845 timeout=timeout,

846 metadata=metadata,

847 )

848

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

850 # an `__aiter__` convenience method.

851 response = pagers.ListSubscriptionsAsyncPager(

852 method=rpc,

853 request=request,

854 response=response,

855 retry=retry,

856 timeout=timeout,

857 metadata=metadata,

858 )

859

860 # Done; return the response.

861 return response

862

863 async def delete_subscription(

864 self,

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

866 *,

867 subscription: Optional[str] = None,

868 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

871 ) -> None:

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

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

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

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

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

877 topic unless the same topic is specified.

878

879 .. code-block:: python

880

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

882 # code template only.

883 # It will require modifications to work:

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

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

886 # client as shown in:

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

888 from google import pubsub_v1

889

890 async def sample_delete_subscription():

891 # Create a client

892 client = pubsub_v1.SubscriberAsyncClient()

893

894 # Initialize request argument(s)

895 request = pubsub_v1.DeleteSubscriptionRequest(

896 subscription="subscription_value",

897 )

898

899 # Make the request

900 await client.delete_subscription(request=request)

901

902 Args:

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

904 The request object. Request for the DeleteSubscription

905 method.

906 subscription (:class:`str`):

907 Required. The subscription to delete. Format is

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

909

910 This corresponds to the ``subscription`` field

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

912 should not be set.

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

914 should be retried.

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

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

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

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

919 be of type `bytes`.

920 """

921 # Create or coerce a protobuf request object.

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

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

924 flattened_params = [subscription]

925 has_flattened_params = (

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

927 )

928 if request is not None and has_flattened_params:

929 raise ValueError(

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

931 "the individual field arguments should be set."

932 )

933

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

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

936 if not isinstance(request, pubsub.DeleteSubscriptionRequest):

937 request = pubsub.DeleteSubscriptionRequest(request)

938

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

940 # request, apply these.

941 if subscription is not None:

942 request.subscription = subscription

943

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

945 # and friendly error handling.

946 rpc = self._client._transport._wrapped_methods[

947 self._client._transport.delete_subscription

948 ]

949

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

951 # add these here.

952 metadata = tuple(metadata) + (

953 gapic_v1.routing_header.to_grpc_metadata(

954 (("subscription", request.subscription),)

955 ),

956 )

957

958 # Validate the universe domain.

959 self._client._validate_universe_domain()

960

961 # Send the request.

962 await rpc(

963 request,

964 retry=retry,

965 timeout=timeout,

966 metadata=metadata,

967 )

968

969 async def modify_ack_deadline(

970 self,

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

972 *,

973 subscription: Optional[str] = None,

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

975 ack_deadline_seconds: Optional[int] = None,

976 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

979 ) -> None:

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

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

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

983 redelivery if the processing was interrupted. Note that this

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

985 used for subsequent messages.

986

987 .. code-block:: python

988

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

990 # code template only.

991 # It will require modifications to work:

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

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

994 # client as shown in:

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

996 from google import pubsub_v1

997

998 async def sample_modify_ack_deadline():

999 # Create a client

1000 client = pubsub_v1.SubscriberAsyncClient()

1001

1002 # Initialize request argument(s)

1003 request = pubsub_v1.ModifyAckDeadlineRequest(

1004 subscription="subscription_value",

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

1006 ack_deadline_seconds=2066,

1007 )

1008

1009 # Make the request

1010 await client.modify_ack_deadline(request=request)

1011

1012 Args:

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

1014 The request object. Request for the ModifyAckDeadline

1015 method.

1016 subscription (:class:`str`):

1017 Required. The name of the subscription. Format is

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

1019

1020 This corresponds to the ``subscription`` field

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

1022 should not be set.

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

1024 Required. List of acknowledgment IDs.

1025 This corresponds to the ``ack_ids`` field

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

1027 should not be set.

1028 ack_deadline_seconds (:class:`int`):

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

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

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

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

1033 was made. Specifying zero might immediately make the

1034 message available for delivery to another subscriber

1035 client. This typically results in an increase in the

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

1037 minimum deadline you can specify is 0 seconds. The

1038 maximum deadline you can specify in a single request is

1039 600 seconds (10 minutes).

1040

1041 This corresponds to the ``ack_deadline_seconds`` field

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

1043 should not be set.

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

1045 should be retried.

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

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

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

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

1050 be of type `bytes`.

1051 """

1052 # Create or coerce a protobuf request object.

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

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

1055 flattened_params = [subscription, ack_ids, ack_deadline_seconds]

1056 has_flattened_params = (

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

1058 )

1059 if request is not None and has_flattened_params:

1060 raise ValueError(

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

1062 "the individual field arguments should be set."

1063 )

1064

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

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

1067 if not isinstance(request, pubsub.ModifyAckDeadlineRequest):

1068 request = pubsub.ModifyAckDeadlineRequest(request)

1069

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

1071 # request, apply these.

1072 if subscription is not None:

1073 request.subscription = subscription

1074 if ack_deadline_seconds is not None:

1075 request.ack_deadline_seconds = ack_deadline_seconds

1076 if ack_ids:

1077 request.ack_ids.extend(ack_ids)

1078

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

1080 # and friendly error handling.

1081 rpc = self._client._transport._wrapped_methods[

1082 self._client._transport.modify_ack_deadline

1083 ]

1084

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

1086 # add these here.

1087 metadata = tuple(metadata) + (

1088 gapic_v1.routing_header.to_grpc_metadata(

1089 (("subscription", request.subscription),)

1090 ),

1091 )

1092

1093 # Validate the universe domain.

1094 self._client._validate_universe_domain()

1095

1096 # Send the request.

1097 await rpc(

1098 request,

1099 retry=retry,

1100 timeout=timeout,

1101 metadata=metadata,

1102 )

1103

1104 async def acknowledge(

1105 self,

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

1107 *,

1108 subscription: Optional[str] = None,

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

1110 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1113 ) -> None:

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

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

1116 relevant messages from the subscription.

1117

1118 Acknowledging a message whose ack deadline has expired may

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

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

1121 error.

1122

1123 .. code-block:: python

1124

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

1126 # code template only.

1127 # It will require modifications to work:

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

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

1130 # client as shown in:

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

1132 from google import pubsub_v1

1133

1134 async def sample_acknowledge():

1135 # Create a client

1136 client = pubsub_v1.SubscriberAsyncClient()

1137

1138 # Initialize request argument(s)

1139 request = pubsub_v1.AcknowledgeRequest(

1140 subscription="subscription_value",

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

1142 )

1143

1144 # Make the request

1145 await client.acknowledge(request=request)

1146

1147 Args:

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

1149 The request object. Request for the Acknowledge method.

1150 subscription (:class:`str`):

1151 Required. The subscription whose message is being

1152 acknowledged. Format is

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

1154

1155 This corresponds to the ``subscription`` field

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

1157 should not be set.

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

1159 Required. The acknowledgment ID for the messages being

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

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

1162

1163 This corresponds to the ``ack_ids`` field

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

1165 should not be set.

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

1167 should be retried.

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

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

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

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

1172 be of type `bytes`.

1173 """

1174 # Create or coerce a protobuf request object.

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

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

1177 flattened_params = [subscription, ack_ids]

1178 has_flattened_params = (

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

1180 )

1181 if request is not None and has_flattened_params:

1182 raise ValueError(

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

1184 "the individual field arguments should be set."

1185 )

1186

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

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

1189 if not isinstance(request, pubsub.AcknowledgeRequest):

1190 request = pubsub.AcknowledgeRequest(request)

1191

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

1193 # request, apply these.

1194 if subscription is not None:

1195 request.subscription = subscription

1196 if ack_ids:

1197 request.ack_ids.extend(ack_ids)

1198

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

1200 # and friendly error handling.

1201 rpc = self._client._transport._wrapped_methods[

1202 self._client._transport.acknowledge

1203 ]

1204

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

1206 # add these here.

1207 metadata = tuple(metadata) + (

1208 gapic_v1.routing_header.to_grpc_metadata(

1209 (("subscription", request.subscription),)

1210 ),

1211 )

1212

1213 # Validate the universe domain.

1214 self._client._validate_universe_domain()

1215

1216 # Send the request.

1217 await rpc(

1218 request,

1219 retry=retry,

1220 timeout=timeout,

1221 metadata=metadata,

1222 )

1223

1224 async def pull(

1225 self,

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

1227 *,

1228 subscription: Optional[str] = None,

1229 return_immediately: Optional[bool] = None,

1230 max_messages: Optional[int] = None,

1231 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1234 ) -> pubsub.PullResponse:

1235 r"""Pulls messages from the server.

1236

1237 .. code-block:: python

1238

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

1240 # code template only.

1241 # It will require modifications to work:

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

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

1244 # client as shown in:

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

1246 from google import pubsub_v1

1247

1248 async def sample_pull():

1249 # Create a client

1250 client = pubsub_v1.SubscriberAsyncClient()

1251

1252 # Initialize request argument(s)

1253 request = pubsub_v1.PullRequest(

1254 subscription="subscription_value",

1255 max_messages=1277,

1256 )

1257

1258 # Make the request

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

1260

1261 # Handle the response

1262 print(response)

1263

1264 Args:

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

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

1267 subscription (:class:`str`):

1268 Required. The subscription from which messages should be

1269 pulled. Format is

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

1271

1272 This corresponds to the ``subscription`` field

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

1274 should not be set.

1275 return_immediately (:class:`bool`):

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

1277 respond immediately even if it there are no messages

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

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

1280 at least one message is available, rather than returning

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

1282 discouraged because it adversely impacts the performance

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

1284 set this field.

1285

1286 This corresponds to the ``return_immediately`` field

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

1288 should not be set.

1289 max_messages (:class:`int`):

1290 Required. The maximum number of

1291 messages to return for this request.

1292 Must be a positive integer. The Pub/Sub

1293 system may return fewer than the number

1294 specified.

1295

1296 This corresponds to the ``max_messages`` field

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

1298 should not be set.

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

1300 should be retried.

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

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

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

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

1305 be of type `bytes`.

1306

1307 Returns:

1308 google.pubsub_v1.types.PullResponse:

1309 Response for the Pull method.

1310 """

1311 # Create or coerce a protobuf request object.

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

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

1314 flattened_params = [subscription, return_immediately, max_messages]

1315 has_flattened_params = (

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

1317 )

1318 if request is not None and has_flattened_params:

1319 raise ValueError(

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

1321 "the individual field arguments should be set."

1322 )

1323

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

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

1326 if not isinstance(request, pubsub.PullRequest):

1327 request = pubsub.PullRequest(request)

1328

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

1330 # request, apply these.

1331 if subscription is not None:

1332 request.subscription = subscription

1333 if return_immediately is not None:

1334 request.return_immediately = return_immediately

1335 if max_messages is not None:

1336 request.max_messages = max_messages

1337

1338 if request.return_immediately:

1339 warnings.warn(

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

1341 category=DeprecationWarning,

1342 )

1343

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

1345 # and friendly error handling.

1346 rpc = self._client._transport._wrapped_methods[self._client._transport.pull]

1347

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

1349 # add these here.

1350 metadata = tuple(metadata) + (

1351 gapic_v1.routing_header.to_grpc_metadata(

1352 (("subscription", request.subscription),)

1353 ),

1354 )

1355

1356 # Validate the universe domain.

1357 self._client._validate_universe_domain()

1358

1359 # Send the request.

1360 response = await rpc(

1361 request,

1362 retry=retry,

1363 timeout=timeout,

1364 metadata=metadata,

1365 )

1366

1367 # Done; return the response.

1368 return response

1369

1370 def streaming_pull(

1371 self,

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

1373 *,

1374 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

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

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

1379 to the client. The client streams acknowledgements and ack

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

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

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

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

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

1385 configuring the underlying RPC channel.

1386

1387 .. code-block:: python

1388

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

1390 # code template only.

1391 # It will require modifications to work:

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

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

1394 # client as shown in:

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

1396 from google import pubsub_v1

1397

1398 async def sample_streaming_pull():

1399 # Create a client

1400 client = pubsub_v1.SubscriberAsyncClient()

1401

1402 # Initialize request argument(s)

1403 request = pubsub_v1.StreamingPullRequest(

1404 subscription="subscription_value",

1405 stream_ack_deadline_seconds=2813,

1406 )

1407

1408 # This method expects an iterator which contains

1409 # 'pubsub_v1.StreamingPullRequest' objects

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

1411 # demonstrative purposes.

1412 requests = [request]

1413

1414 def request_generator():

1415 for request in requests:

1416 yield request

1417

1418 # Make the request

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

1420

1421 # Handle the response

1422 async for response in stream:

1423 print(response)

1424

1425 Args:

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

1427 The request object AsyncIterator. Request for the ``StreamingPull`` streaming RPC method.

1428 This request is used to establish the initial stream as

1429 well as to stream acknowledgements and ack deadline

1430 modifications from the client to the server.

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

1432 should be retried.

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

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

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

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

1437 be of type `bytes`.

1438

1439 Returns:

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

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

1442 messages from the server to the client.

1443

1444 """

1445

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

1447 # and friendly error handling.

1448 rpc = self._client._transport._wrapped_methods[

1449 self._client._transport.streaming_pull

1450 ]

1451

1452 # Validate the universe domain.

1453 self._client._validate_universe_domain()

1454

1455 # Send the request.

1456 response = rpc(

1457 requests,

1458 retry=retry,

1459 timeout=timeout,

1460 metadata=metadata,

1461 )

1462

1463 # Done; return the response.

1464 return response

1465

1466 async def modify_push_config(

1467 self,

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

1469 *,

1470 subscription: Optional[str] = None,

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

1472 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1475 ) -> None:

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

1477

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

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

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

1481 Messages will accumulate for delivery continuously through the

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

1483

1484 .. code-block:: python

1485

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

1487 # code template only.

1488 # It will require modifications to work:

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

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

1491 # client as shown in:

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

1493 from google import pubsub_v1

1494

1495 async def sample_modify_push_config():

1496 # Create a client

1497 client = pubsub_v1.SubscriberAsyncClient()

1498

1499 # Initialize request argument(s)

1500 request = pubsub_v1.ModifyPushConfigRequest(

1501 subscription="subscription_value",

1502 )

1503

1504 # Make the request

1505 await client.modify_push_config(request=request)

1506

1507 Args:

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

1509 The request object. Request for the ModifyPushConfig

1510 method.

1511 subscription (:class:`str`):

1512 Required. The name of the subscription. Format is

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

1514

1515 This corresponds to the ``subscription`` field

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

1517 should not be set.

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

1519 Required. The push configuration for future deliveries.

1520

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

1522 system should stop pushing messages from the given

1523 subscription and allow messages to be pulled and

1524 acknowledged - effectively pausing the subscription if

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

1526

1527 This corresponds to the ``push_config`` field

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

1529 should not be set.

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

1531 should be retried.

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

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

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

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

1536 be of type `bytes`.

1537 """

1538 # Create or coerce a protobuf request object.

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

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

1541 flattened_params = [subscription, push_config]

1542 has_flattened_params = (

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

1544 )

1545 if request is not None and has_flattened_params:

1546 raise ValueError(

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

1548 "the individual field arguments should be set."

1549 )

1550

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

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

1553 if not isinstance(request, pubsub.ModifyPushConfigRequest):

1554 request = pubsub.ModifyPushConfigRequest(request)

1555

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

1557 # request, apply these.

1558 if subscription is not None:

1559 request.subscription = subscription

1560 if push_config is not None:

1561 request.push_config = push_config

1562

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

1564 # and friendly error handling.

1565 rpc = self._client._transport._wrapped_methods[

1566 self._client._transport.modify_push_config

1567 ]

1568

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

1570 # add these here.

1571 metadata = tuple(metadata) + (

1572 gapic_v1.routing_header.to_grpc_metadata(

1573 (("subscription", request.subscription),)

1574 ),

1575 )

1576

1577 # Validate the universe domain.

1578 self._client._validate_universe_domain()

1579

1580 # Send the request.

1581 await rpc(

1582 request,

1583 retry=retry,

1584 timeout=timeout,

1585 metadata=metadata,

1586 )

1587

1588 async def get_snapshot(

1589 self,

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

1591 *,

1592 snapshot: Optional[str] = None,

1593 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1596 ) -> pubsub.Snapshot:

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

1598 in

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

1600 operations, which allow you to manage message acknowledgments in

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

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

1603

1604 .. code-block:: python

1605

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

1607 # code template only.

1608 # It will require modifications to work:

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

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

1611 # client as shown in:

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

1613 from google import pubsub_v1

1614

1615 async def sample_get_snapshot():

1616 # Create a client

1617 client = pubsub_v1.SubscriberAsyncClient()

1618

1619 # Initialize request argument(s)

1620 request = pubsub_v1.GetSnapshotRequest(

1621 snapshot="snapshot_value",

1622 )

1623

1624 # Make the request

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

1626

1627 # Handle the response

1628 print(response)

1629

1630 Args:

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

1632 The request object. Request for the GetSnapshot method.

1633 snapshot (:class:`str`):

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

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

1636

1637 This corresponds to the ``snapshot`` field

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

1639 should not be set.

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

1641 should be retried.

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

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

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

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

1646 be of type `bytes`.

1647

1648 Returns:

1649 google.pubsub_v1.types.Snapshot:

1650 A snapshot resource. Snapshots are used in

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

1652 operations, which allow you to manage message

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

1654 acknowledgment state of messages in an existing

1655 subscription to the state captured by a snapshot.

1656

1657 """

1658 # Create or coerce a protobuf request object.

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

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

1661 flattened_params = [snapshot]

1662 has_flattened_params = (

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

1664 )

1665 if request is not None and has_flattened_params:

1666 raise ValueError(

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

1668 "the individual field arguments should be set."

1669 )

1670

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

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

1673 if not isinstance(request, pubsub.GetSnapshotRequest):

1674 request = pubsub.GetSnapshotRequest(request)

1675

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

1677 # request, apply these.

1678 if snapshot is not None:

1679 request.snapshot = snapshot

1680

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

1682 # and friendly error handling.

1683 rpc = self._client._transport._wrapped_methods[

1684 self._client._transport.get_snapshot

1685 ]

1686

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

1688 # add these here.

1689 metadata = tuple(metadata) + (

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

1691 )

1692

1693 # Validate the universe domain.

1694 self._client._validate_universe_domain()

1695

1696 # Send the request.

1697 response = await rpc(

1698 request,

1699 retry=retry,

1700 timeout=timeout,

1701 metadata=metadata,

1702 )

1703

1704 # Done; return the response.

1705 return response

1706

1707 async def list_snapshots(

1708 self,

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

1710 *,

1711 project: Optional[str] = None,

1712 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1715 ) -> pagers.ListSnapshotsAsyncPager:

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

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

1718 operations, which allow you to manage message acknowledgments in

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

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

1721

1722 .. code-block:: python

1723

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

1725 # code template only.

1726 # It will require modifications to work:

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

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

1729 # client as shown in:

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

1731 from google import pubsub_v1

1732

1733 async def sample_list_snapshots():

1734 # Create a client

1735 client = pubsub_v1.SubscriberAsyncClient()

1736

1737 # Initialize request argument(s)

1738 request = pubsub_v1.ListSnapshotsRequest(

1739 project="project_value",

1740 )

1741

1742 # Make the request

1743 page_result = client.list_snapshots(request=request)

1744

1745 # Handle the response

1746 async for response in page_result:

1747 print(response)

1748

1749 Args:

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

1751 The request object. Request for the ``ListSnapshots`` method.

1752 project (:class:`str`):

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

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

1755

1756 This corresponds to the ``project`` field

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

1758 should not be set.

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

1760 should be retried.

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

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

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

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

1765 be of type `bytes`.

1766

1767 Returns:

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

1769 Response for the ListSnapshots method.

1770

1771 Iterating over this object will yield results and

1772 resolve additional pages automatically.

1773

1774 """

1775 # Create or coerce a protobuf request object.

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

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

1778 flattened_params = [project]

1779 has_flattened_params = (

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

1781 )

1782 if request is not None and has_flattened_params:

1783 raise ValueError(

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

1785 "the individual field arguments should be set."

1786 )

1787

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

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

1790 if not isinstance(request, pubsub.ListSnapshotsRequest):

1791 request = pubsub.ListSnapshotsRequest(request)

1792

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

1794 # request, apply these.

1795 if project is not None:

1796 request.project = project

1797

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

1799 # and friendly error handling.

1800 rpc = self._client._transport._wrapped_methods[

1801 self._client._transport.list_snapshots

1802 ]

1803

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

1805 # add these here.

1806 metadata = tuple(metadata) + (

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

1808 )

1809

1810 # Validate the universe domain.

1811 self._client._validate_universe_domain()

1812

1813 # Send the request.

1814 response = await rpc(

1815 request,

1816 retry=retry,

1817 timeout=timeout,

1818 metadata=metadata,

1819 )

1820

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

1822 # an `__aiter__` convenience method.

1823 response = pagers.ListSnapshotsAsyncPager(

1824 method=rpc,

1825 request=request,

1826 response=response,

1827 retry=retry,

1828 timeout=timeout,

1829 metadata=metadata,

1830 )

1831

1832 # Done; return the response.

1833 return response

1834

1835 async def create_snapshot(

1836 self,

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

1838 *,

1839 name: Optional[str] = None,

1840 subscription: Optional[str] = None,

1841 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1844 ) -> pubsub.Snapshot:

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

1846 are used in

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

1848 operations, which allow you to manage message acknowledgments in

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

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

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

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

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

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

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

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

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

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

1859 the [resource name format]

1860 (https://cloud.google.com/pubsub/docs/pubsub-basics#resource_names).

1861 The generated name is populated in the returned Snapshot object.

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

1863 request.

1864

1865 .. code-block:: python

1866

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

1868 # code template only.

1869 # It will require modifications to work:

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

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

1872 # client as shown in:

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

1874 from google import pubsub_v1

1875

1876 async def sample_create_snapshot():

1877 # Create a client

1878 client = pubsub_v1.SubscriberAsyncClient()

1879

1880 # Initialize request argument(s)

1881 request = pubsub_v1.CreateSnapshotRequest(

1882 name="name_value",

1883 subscription="subscription_value",

1884 )

1885

1886 # Make the request

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

1888

1889 # Handle the response

1890 print(response)

1891

1892 Args:

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

1894 The request object. Request for the ``CreateSnapshot`` method.

1895 name (:class:`str`):

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

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

1898 assign a random name for this snapshot on the same

1899 project as the subscription. Note that for REST API

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

1901 name

1902 rules <https://cloud.google.com/pubsub/docs/pubsub-basics#resource_names>`__.

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

1904

1905 This corresponds to the ``name`` field

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

1907 should not be set.

1908 subscription (:class:`str`):

1909 Required. The subscription whose backlog the snapshot

1910 retains. Specifically, the created snapshot is

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

1912 subscription. More precisely, this is defined as the

1913 messages in the subscription's backlog that are

1914 unacknowledged upon the successful completion of the

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

1916 published to the subscription's topic following the

1917 successful completion of the CreateSnapshot request.

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

1919

1920 This corresponds to the ``subscription`` field

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

1922 should not be set.

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

1924 should be retried.

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

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

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

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

1929 be of type `bytes`.

1930

1931 Returns:

1932 google.pubsub_v1.types.Snapshot:

1933 A snapshot resource. Snapshots are used in

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

1935 operations, which allow you to manage message

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

1937 acknowledgment state of messages in an existing

1938 subscription to the state captured by a snapshot.

1939

1940 """

1941 # Create or coerce a protobuf request object.

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

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

1944 flattened_params = [name, subscription]

1945 has_flattened_params = (

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

1947 )

1948 if request is not None and has_flattened_params:

1949 raise ValueError(

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

1951 "the individual field arguments should be set."

1952 )

1953

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

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

1956 if not isinstance(request, pubsub.CreateSnapshotRequest):

1957 request = pubsub.CreateSnapshotRequest(request)

1958

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

1960 # request, apply these.

1961 if name is not None:

1962 request.name = name

1963 if subscription is not None:

1964 request.subscription = subscription

1965

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

1967 # and friendly error handling.

1968 rpc = self._client._transport._wrapped_methods[

1969 self._client._transport.create_snapshot

1970 ]

1971

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

1973 # add these here.

1974 metadata = tuple(metadata) + (

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

1976 )

1977

1978 # Validate the universe domain.

1979 self._client._validate_universe_domain()

1980

1981 # Send the request.

1982 response = await rpc(

1983 request,

1984 retry=retry,

1985 timeout=timeout,

1986 metadata=metadata,

1987 )

1988

1989 # Done; return the response.

1990 return response

1991

1992 async def update_snapshot(

1993 self,

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

1995 *,

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

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

1998 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2001 ) -> pubsub.Snapshot:

2002 r"""Updates an existing snapshot by updating the fields specified in

2003 the update mask. Snapshots are used in

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

2005 operations, which allow you to manage message acknowledgments in

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

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

2008

2009 .. code-block:: python

2010

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

2012 # code template only.

2013 # It will require modifications to work:

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

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

2016 # client as shown in:

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

2018 from google import pubsub_v1

2019

2020 async def sample_update_snapshot():

2021 # Create a client

2022 client = pubsub_v1.SubscriberAsyncClient()

2023

2024 # Initialize request argument(s)

2025 request = pubsub_v1.UpdateSnapshotRequest(

2026 )

2027

2028 # Make the request

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

2030

2031 # Handle the response

2032 print(response)

2033

2034 Args:

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

2036 The request object. Request for the UpdateSnapshot

2037 method.

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

2039 Required. The updated snapshot

2040 object.

2041

2042 This corresponds to the ``snapshot`` field

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

2044 should not be set.

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

2046 Required. Indicates which fields in

2047 the provided snapshot to update. Must be

2048 specified and non-empty.

2049

2050 This corresponds to the ``update_mask`` field

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

2052 should not be set.

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

2054 should be retried.

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

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

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

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

2059 be of type `bytes`.

2060

2061 Returns:

2062 google.pubsub_v1.types.Snapshot:

2063 A snapshot resource. Snapshots are used in

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

2065 operations, which allow you to manage message

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

2067 acknowledgment state of messages in an existing

2068 subscription to the state captured by a snapshot.

2069

2070 """

2071 # Create or coerce a protobuf request object.

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

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

2074 flattened_params = [snapshot, update_mask]

2075 has_flattened_params = (

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

2077 )

2078 if request is not None and has_flattened_params:

2079 raise ValueError(

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

2081 "the individual field arguments should be set."

2082 )

2083

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

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

2086 if not isinstance(request, pubsub.UpdateSnapshotRequest):

2087 request = pubsub.UpdateSnapshotRequest(request)

2088

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

2090 # request, apply these.

2091 if snapshot is not None:

2092 request.snapshot = snapshot

2093 if update_mask is not None:

2094 request.update_mask = update_mask

2095

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

2097 # and friendly error handling.

2098 rpc = self._client._transport._wrapped_methods[

2099 self._client._transport.update_snapshot

2100 ]

2101

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

2103 # add these here.

2104 metadata = tuple(metadata) + (

2105 gapic_v1.routing_header.to_grpc_metadata(

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

2107 ),

2108 )

2109

2110 # Validate the universe domain.

2111 self._client._validate_universe_domain()

2112

2113 # Send the request.

2114 response = await rpc(

2115 request,

2116 retry=retry,

2117 timeout=timeout,

2118 metadata=metadata,

2119 )

2120

2121 # Done; return the response.

2122 return response

2123

2124 async def delete_snapshot(

2125 self,

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

2127 *,

2128 snapshot: Optional[str] = None,

2129 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2132 ) -> None:

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

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

2135 operations, which allow you to manage message acknowledgments in

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

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

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

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

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

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

2142 the same subscription is specified.

2143

2144 .. code-block:: python

2145

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

2147 # code template only.

2148 # It will require modifications to work:

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

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

2151 # client as shown in:

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

2153 from google import pubsub_v1

2154

2155 async def sample_delete_snapshot():

2156 # Create a client

2157 client = pubsub_v1.SubscriberAsyncClient()

2158

2159 # Initialize request argument(s)

2160 request = pubsub_v1.DeleteSnapshotRequest(

2161 snapshot="snapshot_value",

2162 )

2163

2164 # Make the request

2165 await client.delete_snapshot(request=request)

2166

2167 Args:

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

2169 The request object. Request for the ``DeleteSnapshot`` method.

2170 snapshot (:class:`str`):

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

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

2173

2174 This corresponds to the ``snapshot`` field

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

2176 should not be set.

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

2178 should be retried.

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

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

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

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

2183 be of type `bytes`.

2184 """

2185 # Create or coerce a protobuf request object.

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

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

2188 flattened_params = [snapshot]

2189 has_flattened_params = (

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

2191 )

2192 if request is not None and has_flattened_params:

2193 raise ValueError(

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

2195 "the individual field arguments should be set."

2196 )

2197

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

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

2200 if not isinstance(request, pubsub.DeleteSnapshotRequest):

2201 request = pubsub.DeleteSnapshotRequest(request)

2202

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

2204 # request, apply these.

2205 if snapshot is not None:

2206 request.snapshot = snapshot

2207

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

2209 # and friendly error handling.

2210 rpc = self._client._transport._wrapped_methods[

2211 self._client._transport.delete_snapshot

2212 ]

2213

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

2215 # add these here.

2216 metadata = tuple(metadata) + (

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

2218 )

2219

2220 # Validate the universe domain.

2221 self._client._validate_universe_domain()

2222

2223 # Send the request.

2224 await rpc(

2225 request,

2226 retry=retry,

2227 timeout=timeout,

2228 metadata=metadata,

2229 )

2230

2231 async def seek(

2232 self,

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

2234 *,

2235 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2238 ) -> pubsub.SeekResponse:

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

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

2241 used in [Seek]

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

2243 operations, which allow you to manage message acknowledgments in

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

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

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

2247 same topic.

2248

2249 .. code-block:: python

2250

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

2252 # code template only.

2253 # It will require modifications to work:

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

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

2256 # client as shown in:

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

2258 from google import pubsub_v1

2259

2260 async def sample_seek():

2261 # Create a client

2262 client = pubsub_v1.SubscriberAsyncClient()

2263

2264 # Initialize request argument(s)

2265 request = pubsub_v1.SeekRequest(

2266 subscription="subscription_value",

2267 )

2268

2269 # Make the request

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

2271

2272 # Handle the response

2273 print(response)

2274

2275 Args:

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

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

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

2279 should be retried.

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

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

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

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

2284 be of type `bytes`.

2285

2286 Returns:

2287 google.pubsub_v1.types.SeekResponse:

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

2289 """

2290 # Create or coerce a protobuf request object.

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

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

2293 if not isinstance(request, pubsub.SeekRequest):

2294 request = pubsub.SeekRequest(request)

2295

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

2297 # and friendly error handling.

2298 rpc = self._client._transport._wrapped_methods[self._client._transport.seek]

2299

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

2301 # add these here.

2302 metadata = tuple(metadata) + (

2303 gapic_v1.routing_header.to_grpc_metadata(

2304 (("subscription", request.subscription),)

2305 ),

2306 )

2307

2308 # Validate the universe domain.

2309 self._client._validate_universe_domain()

2310

2311 # Send the request.

2312 response = await rpc(

2313 request,

2314 retry=retry,

2315 timeout=timeout,

2316 metadata=metadata,

2317 )

2318

2319 # Done; return the response.

2320 return response

2321

2322 async def set_iam_policy(

2323 self,

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

2325 *,

2326 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2329 ) -> policy_pb2.Policy:

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

2331

2332 Replaces any existing policy.

2333

2334 Args:

2335 request (:class:`~.iam_policy_pb2.SetIamPolicyRequest`):

2336 The request object. Request message for `SetIamPolicy`

2337 method.

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

2339 should be retried.

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

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

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

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

2344 be of type `bytes`.

2345 Returns:

2346 ~.policy_pb2.Policy:

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

2348 It is used to specify access control policies for Cloud

2349 Platform resources.

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

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

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

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

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

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

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

2357 expression that further constrains the role binding

2358 based on attributes about the request and/or target

2359 resource.

2360

2361 **JSON Example**

2362

2363 ::

2364

2365 {

2366 "bindings": [

2367 {

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

2369 "members": [

2370 "user:mike@example.com",

2371 "group:admins@example.com",

2372 "domain:google.com",

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

2374 ]

2375 },

2376 {

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

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

2379 "condition": {

2380 "title": "expirable access",

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

2382 "expression": "request.time <

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

2384 }

2385 }

2386 ]

2387 }

2388

2389 **YAML Example**

2390

2391 ::

2392

2393 bindings:

2394 - members:

2395 - user:mike@example.com

2396 - group:admins@example.com

2397 - domain:google.com

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

2399 role: roles/resourcemanager.organizationAdmin

2400 - members:

2401 - user:eve@example.com

2402 role: roles/resourcemanager.organizationViewer

2403 condition:

2404 title: expirable access

2405 description: Does not grant access after Sep 2020

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

2407

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

2409 developer's

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

2411 """

2412 # Create or coerce a protobuf request object.

2413

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

2415 # so it must be constructed via keyword expansion.

2416 if isinstance(request, dict):

2417 request = iam_policy_pb2.SetIamPolicyRequest(**request)

2418

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

2420 # and friendly error handling.

2421 rpc = self.transport._wrapped_methods[self._client._transport.set_iam_policy]

2422

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

2424 # add these here.

2425 metadata = tuple(metadata) + (

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

2427 )

2428

2429 # Validate the universe domain.

2430 self._client._validate_universe_domain()

2431

2432 # Send the request.

2433 response = await rpc(

2434 request,

2435 retry=retry,

2436 timeout=timeout,

2437 metadata=metadata,

2438 )

2439

2440 # Done; return the response.

2441 return response

2442

2443 async def get_iam_policy(

2444 self,

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

2446 *,

2447 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2450 ) -> policy_pb2.Policy:

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

2452

2453 Returns an empty policy if the function exists and does not have a

2454 policy set.

2455

2456 Args:

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

2458 The request object. Request message for `GetIamPolicy`

2459 method.

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

2461 any, should be retried.

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

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

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

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

2466 be of type `bytes`.

2467 Returns:

2468 ~.policy_pb2.Policy:

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

2470 It is used to specify access control policies for Cloud

2471 Platform resources.

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

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

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

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

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

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

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

2479 expression that further constrains the role binding

2480 based on attributes about the request and/or target

2481 resource.

2482

2483 **JSON Example**

2484

2485 ::

2486

2487 {

2488 "bindings": [

2489 {

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

2491 "members": [

2492 "user:mike@example.com",

2493 "group:admins@example.com",

2494 "domain:google.com",

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

2496 ]

2497 },

2498 {

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

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

2501 "condition": {

2502 "title": "expirable access",

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

2504 "expression": "request.time <

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

2506 }

2507 }

2508 ]

2509 }

2510

2511 **YAML Example**

2512

2513 ::

2514

2515 bindings:

2516 - members:

2517 - user:mike@example.com

2518 - group:admins@example.com

2519 - domain:google.com

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

2521 role: roles/resourcemanager.organizationAdmin

2522 - members:

2523 - user:eve@example.com

2524 role: roles/resourcemanager.organizationViewer

2525 condition:

2526 title: expirable access

2527 description: Does not grant access after Sep 2020

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

2529

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

2531 developer's

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

2533 """

2534 # Create or coerce a protobuf request object.

2535

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

2537 # so it must be constructed via keyword expansion.

2538 if isinstance(request, dict):

2539 request = iam_policy_pb2.GetIamPolicyRequest(**request)

2540

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

2542 # and friendly error handling.

2543 rpc = self.transport._wrapped_methods[self._client._transport.get_iam_policy]

2544

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

2546 # add these here.

2547 metadata = tuple(metadata) + (

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

2549 )

2550

2551 # Validate the universe domain.

2552 self._client._validate_universe_domain()

2553

2554 # Send the request.

2555 response = await rpc(

2556 request,

2557 retry=retry,

2558 timeout=timeout,

2559 metadata=metadata,

2560 )

2561

2562 # Done; return the response.

2563 return response

2564

2565 async def test_iam_permissions(

2566 self,

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

2568 *,

2569 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2572 ) -> iam_policy_pb2.TestIamPermissionsResponse:

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

2574 policy for a function.

2575

2576 If the function does not exist, this will return an empty set

2577 of permissions, not a NOT_FOUND error.

2578

2579 Args:

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

2581 The request object. Request message for

2582 `TestIamPermissions` method.

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

2584 if any, should be retried.

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

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

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

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

2589 be of type `bytes`.

2590 Returns:

2591 ~.iam_policy_pb2.TestIamPermissionsResponse:

2592 Response message for ``TestIamPermissions`` method.

2593 """

2594 # Create or coerce a protobuf request object.

2595

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

2597 # so it must be constructed via keyword expansion.

2598 if isinstance(request, dict):

2599 request = iam_policy_pb2.TestIamPermissionsRequest(**request)

2600

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

2602 # and friendly error handling.

2603 rpc = self.transport._wrapped_methods[

2604 self._client._transport.test_iam_permissions

2605 ]

2606

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

2608 # add these here.

2609 metadata = tuple(metadata) + (

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

2611 )

2612

2613 # Validate the universe domain.

2614 self._client._validate_universe_domain()

2615

2616 # Send the request.

2617 response = await rpc(

2618 request,

2619 retry=retry,

2620 timeout=timeout,

2621 metadata=metadata,

2622 )

2623

2624 # Done; return the response.

2625 return response

2626

2627 async def __aenter__(self) -> "SubscriberAsyncClient":

2628 return self

2629

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

2631 await self.transport.close()

2632

2633

2634DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(

2635 client_library_version=package_version.__version__

2636)

2637

2638

2639__all__ = ("SubscriberAsyncClient",)

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

333 statements