Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/google/pubsub

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

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

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

6# You may obtain a copy of the License at

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

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

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

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

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

14# limitations under the License.

15#

16from collections import OrderedDict

17from http import HTTPStatus

18import json

19import logging as std_logging

20import functools

21import os

22import re

23from typing import (

24 Dict,

25 Callable,

26 Mapping,

27 MutableMapping,

28 MutableSequence,

29 Optional,

30 Iterable,

31 Iterator,

32 Sequence,

33 Tuple,

34 Type,

35 Union,

36 cast,

37)

38import warnings

40import warnings

41from google.pubsub_v1 import gapic_version as package_version

43from google.api_core import client_options as client_options_lib

44from google.api_core import exceptions as core_exceptions

45from google.api_core import gapic_v1

46from google.api_core import retry as retries

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

48from google.auth.transport import mtls # type: ignore

49from google.auth.transport.grpc import SslCredentials # type: ignore

50from google.auth.exceptions import MutualTLSChannelError # type: ignore

51from google.oauth2 import service_account # type: ignore

52import google.protobuf

54try:

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

56except AttributeError: # pragma: NO COVER

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

59try:

60 from google.api_core import client_logging # type: ignore

62 CLIENT_LOGGING_SUPPORTED = True # pragma: NO COVER

63except ImportError: # pragma: NO COVER

64 CLIENT_LOGGING_SUPPORTED = False

66_LOGGER = std_logging.getLogger(__name__)

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

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

70from google.protobuf import duration_pb2 # type: ignore

71from google.protobuf import field_mask_pb2 # type: ignore

72from google.protobuf import timestamp_pb2 # type: ignore

73from google.pubsub_v1.services.subscriber import pagers

74from google.pubsub_v1.types import pubsub

76import grpc

77from .transports.base import SubscriberTransport, DEFAULT_CLIENT_INFO

78from .transports.grpc import SubscriberGrpcTransport

79from .transports.grpc_asyncio import SubscriberGrpcAsyncIOTransport

80from .transports.rest import SubscriberRestTransport

83class SubscriberClientMeta(type):

84 """Metaclass for the Subscriber client.

86 This provides class-level methods for building and retrieving

87 support objects (e.g. transport) without polluting the client instance

88 objects.

89 """

91 _transport_registry = OrderedDict() # type: Dict[str, Type[SubscriberTransport]]

92 _transport_registry["grpc"] = SubscriberGrpcTransport

93 _transport_registry["grpc_asyncio"] = SubscriberGrpcAsyncIOTransport

94 _transport_registry["rest"] = SubscriberRestTransport

96 def get_transport_class(

97 cls,

98 label: Optional[str] = None,

99 ) -> Type[SubscriberTransport]:

100 """Returns an appropriate transport class.

101

102 Args:

103 label: The name of the desired transport. If none is

104 provided, then the first transport in the registry is used.

105

106 Returns:

107 The transport class to use.

108 """

109 # If a specific transport is requested, return that one.

110 if label:

111 return cls._transport_registry[label]

112

113 # No transport is requested; return the default (that is, the first one

114 # in the dictionary).

115 return next(iter(cls._transport_registry.values()))

116

117

118class SubscriberClient(metaclass=SubscriberClientMeta):

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

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

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

122 method.

123 """

124

125 @staticmethod

126 def _get_default_mtls_endpoint(api_endpoint):

127 """Converts api endpoint to mTLS endpoint.

128

129 Convert "*.sandbox.googleapis.com" and "*.googleapis.com" to

130 "*.mtls.sandbox.googleapis.com" and "*.mtls.googleapis.com" respectively.

131 Args:

132 api_endpoint (Optional[str]): the api endpoint to convert.

133 Returns:

134 str: converted mTLS api endpoint.

135 """

136 if not api_endpoint:

137 return api_endpoint

138

139 mtls_endpoint_re = re.compile(

140 r"(?P<name>[^.]+)(?P<mtls>\.mtls)?(?P<sandbox>\.sandbox)?(?P<googledomain>\.googleapis\.com)?"

141 )

142

143 m = mtls_endpoint_re.match(api_endpoint)

144 name, mtls, sandbox, googledomain = m.groups()

145 if mtls or not googledomain:

146 return api_endpoint

147

148 if sandbox:

149 return api_endpoint.replace(

150 "sandbox.googleapis.com", "mtls.sandbox.googleapis.com"

151 )

152

153 return api_endpoint.replace(".googleapis.com", ".mtls.googleapis.com")

154

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

156

157 # The scopes needed to make gRPC calls to all of the methods defined in

158 # this service

159 _DEFAULT_SCOPES = (

160 "https://www.googleapis.com/auth/cloud-platform",

161 "https://www.googleapis.com/auth/pubsub",

162 )

163

164 SERVICE_ADDRESS = "pubsub.googleapis.com:443"

165 """The default address of the service."""

166

167 DEFAULT_ENDPOINT = "pubsub.googleapis.com"

168 DEFAULT_MTLS_ENDPOINT = _get_default_mtls_endpoint.__func__( # type: ignore

169 DEFAULT_ENDPOINT

170 )

171

172 _DEFAULT_ENDPOINT_TEMPLATE = "pubsub.{UNIVERSE_DOMAIN}"

173 _DEFAULT_UNIVERSE = "googleapis.com"

174

175 @classmethod

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

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

178 info.

179

180 Args:

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

182 args: Additional arguments to pass to the constructor.

183 kwargs: Additional arguments to pass to the constructor.

184

185 Returns:

186 SubscriberClient: The constructed client.

187 """

188 credentials = service_account.Credentials.from_service_account_info(info)

189 kwargs["credentials"] = credentials

190 return cls(*args, **kwargs)

191

192 @classmethod

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

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

195 file.

196

197 Args:

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

199 file.

200 args: Additional arguments to pass to the constructor.

201 kwargs: Additional arguments to pass to the constructor.

202

203 Returns:

204 SubscriberClient: The constructed client.

205 """

206 credentials = service_account.Credentials.from_service_account_file(filename)

207 kwargs["credentials"] = credentials

208 return cls(*args, **kwargs)

209

210 from_service_account_json = from_service_account_file

211

212 @property

213 def transport(self) -> SubscriberTransport:

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

215

216 Returns:

217 SubscriberTransport: The transport used by the client

218 instance.

219 """

220 return self._transport

221

222 @staticmethod

223 def snapshot_path(

224 project: str,

225 snapshot: str,

226 ) -> str:

227 """Returns a fully-qualified snapshot string."""

228 return "projects/{project}/snapshots/{snapshot}".format(

229 project=project,

230 snapshot=snapshot,

231 )

232

233 @staticmethod

234 def parse_snapshot_path(path: str) -> Dict[str, str]:

235 """Parses a snapshot path into its component segments."""

236 m = re.match(r"^projects/(?P<project>.+?)/snapshots/(?P<snapshot>.+?)$", path)

237 return m.groupdict() if m else {}

238

239 @staticmethod

240 def subscription_path(

241 project: str,

242 subscription: str,

243 ) -> str:

244 """Returns a fully-qualified subscription string."""

245 return "projects/{project}/subscriptions/{subscription}".format(

246 project=project,

247 subscription=subscription,

248 )

249

250 @staticmethod

251 def parse_subscription_path(path: str) -> Dict[str, str]:

252 """Parses a subscription path into its component segments."""

253 m = re.match(

254 r"^projects/(?P<project>.+?)/subscriptions/(?P<subscription>.+?)$", path

255 )

256 return m.groupdict() if m else {}

257

258 @staticmethod

259 def topic_path(

260 project: str,

261 topic: str,

262 ) -> str:

263 """Returns a fully-qualified topic string."""

264 return "projects/{project}/topics/{topic}".format(

265 project=project,

266 topic=topic,

267 )

268

269 @staticmethod

270 def parse_topic_path(path: str) -> Dict[str, str]:

271 """Parses a topic path into its component segments."""

272 m = re.match(r"^projects/(?P<project>.+?)/topics/(?P<topic>.+?)$", path)

273 return m.groupdict() if m else {}

274

275 @staticmethod

276 def common_billing_account_path(

277 billing_account: str,

278 ) -> str:

279 """Returns a fully-qualified billing_account string."""

280 return "billingAccounts/{billing_account}".format(

281 billing_account=billing_account,

282 )

283

284 @staticmethod

285 def parse_common_billing_account_path(path: str) -> Dict[str, str]:

286 """Parse a billing_account path into its component segments."""

287 m = re.match(r"^billingAccounts/(?P<billing_account>.+?)$", path)

288 return m.groupdict() if m else {}

289

290 @staticmethod

291 def common_folder_path(

292 folder: str,

293 ) -> str:

294 """Returns a fully-qualified folder string."""

295 return "folders/{folder}".format(

296 folder=folder,

297 )

298

299 @staticmethod

300 def parse_common_folder_path(path: str) -> Dict[str, str]:

301 """Parse a folder path into its component segments."""

302 m = re.match(r"^folders/(?P<folder>.+?)$", path)

303 return m.groupdict() if m else {}

304

305 @staticmethod

306 def common_organization_path(

307 organization: str,

308 ) -> str:

309 """Returns a fully-qualified organization string."""

310 return "organizations/{organization}".format(

311 organization=organization,

312 )

313

314 @staticmethod

315 def parse_common_organization_path(path: str) -> Dict[str, str]:

316 """Parse a organization path into its component segments."""

317 m = re.match(r"^organizations/(?P<organization>.+?)$", path)

318 return m.groupdict() if m else {}

319

320 @staticmethod

321 def common_project_path(

322 project: str,

323 ) -> str:

324 """Returns a fully-qualified project string."""

325 return "projects/{project}".format(

326 project=project,

327 )

328

329 @staticmethod

330 def parse_common_project_path(path: str) -> Dict[str, str]:

331 """Parse a project path into its component segments."""

332 m = re.match(r"^projects/(?P<project>.+?)$", path)

333 return m.groupdict() if m else {}

334

335 @staticmethod

336 def common_location_path(

337 project: str,

338 location: str,

339 ) -> str:

340 """Returns a fully-qualified location string."""

341 return "projects/{project}/locations/{location}".format(

342 project=project,

343 location=location,

344 )

345

346 @staticmethod

347 def parse_common_location_path(path: str) -> Dict[str, str]:

348 """Parse a location path into its component segments."""

349 m = re.match(r"^projects/(?P<project>.+?)/locations/(?P<location>.+?)$", path)

350 return m.groupdict() if m else {}

351

352 @classmethod

353 def get_mtls_endpoint_and_cert_source(

354 cls, client_options: Optional[client_options_lib.ClientOptions] = None

355 ):

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

357

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

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

360 client cert source is None.

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

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

363 source is None.

364

365 The API endpoint is determined in the following order:

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

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

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

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

370 use the default API endpoint.

371

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

373

374 Args:

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

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

377 in this method.

378

379 Returns:

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

381 client cert source to use.

382

383 Raises:

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

385 """

386

387 warnings.warn(

388 "get_mtls_endpoint_and_cert_source is deprecated. Use the api_endpoint property instead.",

389 DeprecationWarning,

390 )

391 if client_options is None:

392 client_options = client_options_lib.ClientOptions()

393 use_client_cert = os.getenv("GOOGLE_API_USE_CLIENT_CERTIFICATE", "false")

394 use_mtls_endpoint = os.getenv("GOOGLE_API_USE_MTLS_ENDPOINT", "auto")

395 if use_client_cert not in ("true", "false"):

396 raise ValueError(

397 "Environment variable `GOOGLE_API_USE_CLIENT_CERTIFICATE` must be either `true` or `false`"

398 )

399 if use_mtls_endpoint not in ("auto", "never", "always"):

400 raise MutualTLSChannelError(

401 "Environment variable `GOOGLE_API_USE_MTLS_ENDPOINT` must be `never`, `auto` or `always`"

402 )

403

404 # Figure out the client cert source to use.

405 client_cert_source = None

406 if use_client_cert == "true":

407 if client_options.client_cert_source:

408 client_cert_source = client_options.client_cert_source

409 elif mtls.has_default_client_cert_source():

410 client_cert_source = mtls.default_client_cert_source()

411

412 # Figure out which api endpoint to use.

413 if client_options.api_endpoint is not None:

414 api_endpoint = client_options.api_endpoint

415 elif use_mtls_endpoint == "always" or (

416 use_mtls_endpoint == "auto" and client_cert_source

417 ):

418 api_endpoint = cls.DEFAULT_MTLS_ENDPOINT

419 else:

420 api_endpoint = cls.DEFAULT_ENDPOINT

421

422 return api_endpoint, client_cert_source

423

424 @staticmethod

425 def _read_environment_variables():

426 """Returns the environment variables used by the client.

427

428 Returns:

429 Tuple[bool, str, str]: returns the GOOGLE_API_USE_CLIENT_CERTIFICATE,

430 GOOGLE_API_USE_MTLS_ENDPOINT, and GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variables.

431

432 Raises:

433 ValueError: If GOOGLE_API_USE_CLIENT_CERTIFICATE is not

434 any of ["true", "false"].

435 google.auth.exceptions.MutualTLSChannelError: If GOOGLE_API_USE_MTLS_ENDPOINT

436 is not any of ["auto", "never", "always"].

437 """

438 use_client_cert = os.getenv(

439 "GOOGLE_API_USE_CLIENT_CERTIFICATE", "false"

440 ).lower()

441 use_mtls_endpoint = os.getenv("GOOGLE_API_USE_MTLS_ENDPOINT", "auto").lower()

442 universe_domain_env = os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN")

443 if use_client_cert not in ("true", "false"):

444 raise ValueError(

445 "Environment variable `GOOGLE_API_USE_CLIENT_CERTIFICATE` must be either `true` or `false`"

446 )

447 if use_mtls_endpoint not in ("auto", "never", "always"):

448 raise MutualTLSChannelError(

449 "Environment variable `GOOGLE_API_USE_MTLS_ENDPOINT` must be `never`, `auto` or `always`"

450 )

451 return use_client_cert == "true", use_mtls_endpoint, universe_domain_env

452

453 @staticmethod

454 def _get_client_cert_source(provided_cert_source, use_cert_flag):

455 """Return the client cert source to be used by the client.

456

457 Args:

458 provided_cert_source (bytes): The client certificate source provided.

459 use_cert_flag (bool): A flag indicating whether to use the client certificate.

460

461 Returns:

462 bytes or None: The client cert source to be used by the client.

463 """

464 client_cert_source = None

465 if use_cert_flag:

466 if provided_cert_source:

467 client_cert_source = provided_cert_source

468 elif mtls.has_default_client_cert_source():

469 client_cert_source = mtls.default_client_cert_source()

470 return client_cert_source

471

472 @staticmethod

473 def _get_api_endpoint(

474 api_override, client_cert_source, universe_domain, use_mtls_endpoint

475 ):

476 """Return the API endpoint used by the client.

477

478 Args:

479 api_override (str): The API endpoint override. If specified, this is always

480 the return value of this function and the other arguments are not used.

481 client_cert_source (bytes): The client certificate source used by the client.

482 universe_domain (str): The universe domain used by the client.

483 use_mtls_endpoint (str): How to use the mTLS endpoint, which depends also on the other parameters.

484 Possible values are "always", "auto", or "never".

485

486 Returns:

487 str: The API endpoint to be used by the client.

488 """

489 if api_override is not None:

490 api_endpoint = api_override

491 elif use_mtls_endpoint == "always" or (

492 use_mtls_endpoint == "auto" and client_cert_source

493 ):

494 _default_universe = SubscriberClient._DEFAULT_UNIVERSE

495 if universe_domain != _default_universe:

496 raise MutualTLSChannelError(

497 f"mTLS is not supported in any universe other than {_default_universe}."

498 )

499 api_endpoint = SubscriberClient.DEFAULT_MTLS_ENDPOINT

500 else:

501 api_endpoint = SubscriberClient._DEFAULT_ENDPOINT_TEMPLATE.format(

502 UNIVERSE_DOMAIN=universe_domain

503 )

504 return api_endpoint

505

506 @staticmethod

507 def _get_universe_domain(

508 client_universe_domain: Optional[str], universe_domain_env: Optional[str]

509 ) -> str:

510 """Return the universe domain used by the client.

511

512 Args:

513 client_universe_domain (Optional[str]): The universe domain configured via the client options.

514 universe_domain_env (Optional[str]): The universe domain configured via the "GOOGLE_CLOUD_UNIVERSE_DOMAIN" environment variable.

515

516 Returns:

517 str: The universe domain to be used by the client.

518

519 Raises:

520 ValueError: If the universe domain is an empty string.

521 """

522 universe_domain = SubscriberClient._DEFAULT_UNIVERSE

523 if client_universe_domain is not None:

524 universe_domain = client_universe_domain

525 elif universe_domain_env is not None:

526 universe_domain = universe_domain_env

527 if len(universe_domain.strip()) == 0:

528 raise ValueError("Universe Domain cannot be an empty string.")

529 return universe_domain

530

531 def _validate_universe_domain(self):

532 """Validates client's and credentials' universe domains are consistent.

533

534 Returns:

535 bool: True iff the configured universe domain is valid.

536

537 Raises:

538 ValueError: If the configured universe domain is not valid.

539 """

540

541 # NOTE (b/349488459): universe validation is disabled until further notice.

542 return True

543

544 def _add_cred_info_for_auth_errors(

545 self, error: core_exceptions.GoogleAPICallError

546 ) -> None:

547 """Adds credential info string to error details for 401/403/404 errors.

548

549 Args:

550 error (google.api_core.exceptions.GoogleAPICallError): The error to add the cred info.

551 """

552 if error.code not in [

553 HTTPStatus.UNAUTHORIZED,

554 HTTPStatus.FORBIDDEN,

555 HTTPStatus.NOT_FOUND,

556 ]:

557 return

558

559 cred = self._transport._credentials

560

561 # get_cred_info is only available in google-auth>=2.35.0

562 if not hasattr(cred, "get_cred_info"):

563 return

564

565 # ignore the type check since pypy test fails when get_cred_info

566 # is not available

567 cred_info = cred.get_cred_info() # type: ignore

568 if cred_info and hasattr(error._details, "append"):

569 error._details.append(json.dumps(cred_info))

570

571 @property

572 def api_endpoint(self):

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

574

575 Returns:

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

577 """

578 return self._api_endpoint

579

580 @property

581 def universe_domain(self) -> str:

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

583

584 Returns:

585 str: The universe domain used by the client instance.

586 """

587 return self._universe_domain

588

589 def __init__(

590 self,

591 *,

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

593 transport: Optional[

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

595 ] = None,

596 client_options: Optional[Union[client_options_lib.ClientOptions, dict]] = None,

597 client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,

598 ) -> None:

599 """Instantiates the subscriber client.

600

601 Args:

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

603 authorization credentials to attach to requests. These

604 credentials identify the application to the service; if none

605 are specified, the client will attempt to ascertain the

606 credentials from the environment.

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

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

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

610 arguments as used in the SubscriberTransport constructor.

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

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

613 Custom options for the client.

614

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

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

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

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

619 determined by the GOOGLE_API_USE_MTLS_ENDPOINT environment

620 variable, which have one of the following values:

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

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

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

624 the default value).

625

626 2. If the GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable

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

628 to provide a client certificate for mTLS transport. If

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

630 present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not

631 set, no client certificate will be used.

632

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

634 default "googleapis.com" universe. Note that the ``api_endpoint``

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

636 currently not supported for mTLS.

637

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

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

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

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

642 your own client library.

643

644 Raises:

645 google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport

646 creation failed for any reason.

647 """

648 self._client_options = client_options

649 if isinstance(self._client_options, dict):

650 self._client_options = client_options_lib.from_dict(self._client_options)

651 if self._client_options is None:

652 self._client_options = client_options_lib.ClientOptions()

653 self._client_options = cast(

654 client_options_lib.ClientOptions, self._client_options

655 )

656

657 universe_domain_opt = getattr(self._client_options, "universe_domain", None)

658

659 (

660 self._use_client_cert,

661 self._use_mtls_endpoint,

662 self._universe_domain_env,

663 ) = SubscriberClient._read_environment_variables()

664 self._client_cert_source = SubscriberClient._get_client_cert_source(

665 self._client_options.client_cert_source, self._use_client_cert

666 )

667 self._universe_domain = SubscriberClient._get_universe_domain(

668 universe_domain_opt, self._universe_domain_env

669 )

670 self._api_endpoint = None # updated below, depending on `transport`

671

672 # Initialize the universe domain validation.

673 self._is_universe_domain_valid = False

674

675 if CLIENT_LOGGING_SUPPORTED: # pragma: NO COVER

676 # Setup logging.

677 client_logging.initialize_logging()

678

679 api_key_value = getattr(self._client_options, "api_key", None)

680 if api_key_value and credentials:

681 raise ValueError(

682 "client_options.api_key and credentials are mutually exclusive"

683 )

684

685 # Save or instantiate the transport.

686 # Ordinarily, we provide the transport, but allowing a custom transport

687 # instance provides an extensibility point for unusual situations.

688 transport_provided = isinstance(transport, SubscriberTransport)

689 if transport_provided:

690 # transport is a SubscriberTransport instance.

691 if credentials or self._client_options.credentials_file or api_key_value:

692 raise ValueError(

693 "When providing a transport instance, "

694 "provide its credentials directly."

695 )

696 if self._client_options.scopes:

697 raise ValueError(

698 "When providing a transport instance, provide its scopes "

699 "directly."

700 )

701 self._transport = cast(SubscriberTransport, transport)

702 self._api_endpoint = self._transport.host

703

704 self._api_endpoint = self._api_endpoint or SubscriberClient._get_api_endpoint(

705 self._client_options.api_endpoint,

706 self._client_cert_source,

707 self._universe_domain,

708 self._use_mtls_endpoint,

709 )

710

711 if not transport_provided:

712 import google.auth._default # type: ignore

713

714 if api_key_value and hasattr(

715 google.auth._default, "get_api_key_credentials"

716 ):

717 credentials = google.auth._default.get_api_key_credentials(

718 api_key_value

719 )

720

721 transport_init: Union[

722 Type[SubscriberTransport], Callable[..., SubscriberTransport]

723 ] = (

724 SubscriberClient.get_transport_class(transport)

725 if isinstance(transport, str) or transport is None

726 else cast(Callable[..., SubscriberTransport], transport)

727 )

728 # initialize with the provided callable or the passed in class

729

730 emulator_host = os.environ.get("PUBSUB_EMULATOR_HOST")

731 if emulator_host:

732 if issubclass(transport_init, type(self)._transport_registry["grpc"]):

733 channel = grpc.insecure_channel(target=emulator_host)

734 else:

735 channel = grpc.aio.insecure_channel(target=emulator_host)

736 transport_init = functools.partial(transport_init, channel=channel)

737

738 self._transport = transport_init(

739 credentials=credentials,

740 credentials_file=self._client_options.credentials_file,

741 host=self._api_endpoint,

742 scopes=self._client_options.scopes,

743 client_cert_source_for_mtls=self._client_cert_source,

744 quota_project_id=self._client_options.quota_project_id,

745 client_info=client_info,

746 always_use_jwt_access=True,

747 api_audience=self._client_options.api_audience,

748 )

749

750 if "async" not in str(self._transport):

751 if CLIENT_LOGGING_SUPPORTED and _LOGGER.isEnabledFor(

752 std_logging.DEBUG

753 ): # pragma: NO COVER

754 _LOGGER.debug(

755 "Created client `google.pubsub_v1.SubscriberClient`.",

756 extra={

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

758 "universeDomain": getattr(

759 self._transport._credentials, "universe_domain", ""

760 ),

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

762 "credentialsInfo": getattr(

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

764 )(),

765 }

766 if hasattr(self._transport, "_credentials")

767 else {

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

769 "credentialsType": None,

770 },

771 )

772

773 def create_subscription(

774 self,

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

776 *,

777 name: Optional[str] = None,

778 topic: Optional[str] = None,

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

780 ack_deadline_seconds: Optional[int] = None,

781 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

784 ) -> pubsub.Subscription:

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

786 rules]

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

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

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

790

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

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

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

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

795 The generated name is populated in the returned Subscription

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

797 in the request.

798

799 .. code-block:: python

800

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

802 # code template only.

803 # It will require modifications to work:

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

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

806 # client as shown in:

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

808 from google import pubsub_v1

809

810 def sample_create_subscription():

811 # Create a client

812 client = pubsub_v1.SubscriberClient()

813

814 # Initialize request argument(s)

815 request = pubsub_v1.Subscription(

816 name="name_value",

817 topic="topic_value",

818 )

819

820 # Make the request

821 response = client.create_subscription(request=request)

822

823 # Handle the response

824 print(response)

825

826 Args:

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

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

829 ``bigquery_config``, or ``cloud_storage_config`` is set,

830 then the subscriber will pull and ack messages using API

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

832 name (str):

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

834 format

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

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

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

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

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

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

841 not start with ``"goog"``.

842

843 This corresponds to the ``name`` field

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

845 should not be set.

846 topic (str):

847 Required. The name of the topic from which this

848 subscription is receiving messages. Format is

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

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

851 deleted.

852

853 This corresponds to the ``topic`` field

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

855 should not be set.

856 push_config (google.pubsub_v1.types.PushConfig):

857 Optional. If push delivery is used

858 with this subscription, this field is

859 used to configure it.

860

861 This corresponds to the ``push_config`` field

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

863 should not be set.

864 ack_deadline_seconds (int):

865 Optional. The approximate amount of time (on a

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

867 acknowledge receipt before resending the message. In the

868 interval after the message is delivered and before it is

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

870 During that time period, the message will not be

871 redelivered (on a best-effort basis).

872

873 For pull subscriptions, this value is used as the

874 initial value for the ack deadline. To override this

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

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

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

878 ``StreamingModifyAckDeadlineRequest`` if using streaming

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

880 seconds. The maximum custom deadline you can specify is

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

882 default value of 10 seconds is used.

883

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

885 request timeout for the call to the push endpoint.

886

887 If the subscriber never acknowledges the message, the

888 Pub/Sub system will eventually redeliver the message.

889

890 This corresponds to the ``ack_deadline_seconds`` field

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

892 should not be set.

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

894 should be retried.

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

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

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

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

899 be of type `bytes`.

900

901 Returns:

902 google.pubsub_v1.types.Subscription:

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

904 cloud_storage_config is set, then the subscriber will

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

906 of these fields may be set.

907

908 """

909 # Create or coerce a protobuf request object.

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

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

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

913 has_flattened_params = (

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

915 )

916 if request is not None and has_flattened_params:

917 raise ValueError(

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

919 "the individual field arguments should be set."

920 )

921

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

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

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

925 request = pubsub.Subscription(request)

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

927 # request, apply these.

928 if name is not None:

929 request.name = name

930 if topic is not None:

931 request.topic = topic

932 if push_config is not None:

933 request.push_config = push_config

934 if ack_deadline_seconds is not None:

935 request.ack_deadline_seconds = ack_deadline_seconds

936

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

938 # and friendly error handling.

939 rpc = self._transport._wrapped_methods[self._transport.create_subscription]

940

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

942 # add these here.

943 metadata = tuple(metadata) + (

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

945 )

946

947 # Validate the universe domain.

948 self._validate_universe_domain()

949

950 # Send the request.

951 response = rpc(

952 request,

953 retry=retry,

954 timeout=timeout,

955 metadata=metadata,

956 )

957

958 # Done; return the response.

959 return response

960

961 def get_subscription(

962 self,

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

964 *,

965 subscription: Optional[str] = None,

966 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

969 ) -> pubsub.Subscription:

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

971

972 .. code-block:: python

973

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

975 # code template only.

976 # It will require modifications to work:

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

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

979 # client as shown in:

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

981 from google import pubsub_v1

982

983 def sample_get_subscription():

984 # Create a client

985 client = pubsub_v1.SubscriberClient()

986

987 # Initialize request argument(s)

988 request = pubsub_v1.GetSubscriptionRequest(

989 subscription="subscription_value",

990 )

991

992 # Make the request

993 response = client.get_subscription(request=request)

994

995 # Handle the response

996 print(response)

997

998 Args:

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

1000 The request object. Request for the GetSubscription

1001 method.

1002 subscription (str):

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

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

1005

1006 This corresponds to the ``subscription`` field

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

1008 should not be set.

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

1010 should be retried.

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

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

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

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

1015 be of type `bytes`.

1016

1017 Returns:

1018 google.pubsub_v1.types.Subscription:

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

1020 cloud_storage_config is set, then the subscriber will

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

1022 of these fields may be set.

1023

1024 """

1025 # Create or coerce a protobuf request object.

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

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

1028 flattened_params = [subscription]

1029 has_flattened_params = (

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

1031 )

1032 if request is not None and has_flattened_params:

1033 raise ValueError(

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

1035 "the individual field arguments should be set."

1036 )

1037

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

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

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

1041 request = pubsub.GetSubscriptionRequest(request)

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

1043 # request, apply these.

1044 if subscription is not None:

1045 request.subscription = subscription

1046

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

1048 # and friendly error handling.

1049 rpc = self._transport._wrapped_methods[self._transport.get_subscription]

1050

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

1052 # add these here.

1053 metadata = tuple(metadata) + (

1054 gapic_v1.routing_header.to_grpc_metadata(

1055 (("subscription", request.subscription),)

1056 ),

1057 )

1058

1059 # Validate the universe domain.

1060 self._validate_universe_domain()

1061

1062 # Send the request.

1063 response = rpc(

1064 request,

1065 retry=retry,

1066 timeout=timeout,

1067 metadata=metadata,

1068 )

1069

1070 # Done; return the response.

1071 return response

1072

1073 def update_subscription(

1074 self,

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

1076 *,

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

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

1079 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1082 ) -> pubsub.Subscription:

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

1084 fields specified in the update mask. Note that certain

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

1086 modifiable.

1087

1088 .. code-block:: python

1089

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

1091 # code template only.

1092 # It will require modifications to work:

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

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

1095 # client as shown in:

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

1097 from google import pubsub_v1

1098

1099 def sample_update_subscription():

1100 # Create a client

1101 client = pubsub_v1.SubscriberClient()

1102

1103 # Initialize request argument(s)

1104 subscription = pubsub_v1.Subscription()

1105 subscription.name = "name_value"

1106 subscription.topic = "topic_value"

1107

1108 request = pubsub_v1.UpdateSubscriptionRequest(

1109 subscription=subscription,

1110 )

1111

1112 # Make the request

1113 response = client.update_subscription(request=request)

1114

1115 # Handle the response

1116 print(response)

1117

1118 Args:

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

1120 The request object. Request for the UpdateSubscription

1121 method.

1122 subscription (google.pubsub_v1.types.Subscription):

1123 Required. The updated subscription

1124 object.

1125

1126 This corresponds to the ``subscription`` field

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

1128 should not be set.

1129 update_mask (google.protobuf.field_mask_pb2.FieldMask):

1130 Required. Indicates which fields in

1131 the provided subscription to update.

1132 Must be specified and non-empty.

1133

1134 This corresponds to the ``update_mask`` field

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

1136 should not be set.

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

1138 should be retried.

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

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

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

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

1143 be of type `bytes`.

1144

1145 Returns:

1146 google.pubsub_v1.types.Subscription:

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

1148 cloud_storage_config is set, then the subscriber will

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

1150 of these fields may be set.

1151

1152 """

1153 # Create or coerce a protobuf request object.

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

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

1156 flattened_params = [subscription, update_mask]

1157 has_flattened_params = (

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

1159 )

1160 if request is not None and has_flattened_params:

1161 raise ValueError(

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

1163 "the individual field arguments should be set."

1164 )

1165

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

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

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

1169 request = pubsub.UpdateSubscriptionRequest(request)

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

1171 # request, apply these.

1172 if subscription is not None:

1173 request.subscription = subscription

1174 if update_mask is not None:

1175 request.update_mask = update_mask

1176

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

1178 # and friendly error handling.

1179 rpc = self._transport._wrapped_methods[self._transport.update_subscription]

1180

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

1182 # add these here.

1183 metadata = tuple(metadata) + (

1184 gapic_v1.routing_header.to_grpc_metadata(

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

1186 ),

1187 )

1188

1189 # Validate the universe domain.

1190 self._validate_universe_domain()

1191

1192 # Send the request.

1193 response = rpc(

1194 request,

1195 retry=retry,

1196 timeout=timeout,

1197 metadata=metadata,

1198 )

1199

1200 # Done; return the response.

1201 return response

1202

1203 def list_subscriptions(

1204 self,

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

1206 *,

1207 project: Optional[str] = None,

1208 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1211 ) -> pagers.ListSubscriptionsPager:

1212 r"""Lists matching subscriptions.

1213

1214 .. code-block:: python

1215

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

1217 # code template only.

1218 # It will require modifications to work:

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

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

1221 # client as shown in:

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

1223 from google import pubsub_v1

1224

1225 def sample_list_subscriptions():

1226 # Create a client

1227 client = pubsub_v1.SubscriberClient()

1228

1229 # Initialize request argument(s)

1230 request = pubsub_v1.ListSubscriptionsRequest(

1231 project="project_value",

1232 )

1233

1234 # Make the request

1235 page_result = client.list_subscriptions(request=request)

1236

1237 # Handle the response

1238 for response in page_result:

1239 print(response)

1240

1241 Args:

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

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

1244 project (str):

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

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

1247

1248 This corresponds to the ``project`` field

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

1250 should not be set.

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

1252 should be retried.

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

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

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

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

1257 be of type `bytes`.

1258

1259 Returns:

1260 google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager:

1261 Response for the ListSubscriptions method.

1262

1263 Iterating over this object will yield results and

1264 resolve additional pages automatically.

1265

1266 """

1267 # Create or coerce a protobuf request object.

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

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

1270 flattened_params = [project]

1271 has_flattened_params = (

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

1273 )

1274 if request is not None and has_flattened_params:

1275 raise ValueError(

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

1277 "the individual field arguments should be set."

1278 )

1279

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

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

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

1283 request = pubsub.ListSubscriptionsRequest(request)

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

1285 # request, apply these.

1286 if project is not None:

1287 request.project = project

1288

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

1290 # and friendly error handling.

1291 rpc = self._transport._wrapped_methods[self._transport.list_subscriptions]

1292

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

1294 # add these here.

1295 metadata = tuple(metadata) + (

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

1297 )

1298

1299 # Validate the universe domain.

1300 self._validate_universe_domain()

1301

1302 # Send the request.

1303 response = rpc(

1304 request,

1305 retry=retry,

1306 timeout=timeout,

1307 metadata=metadata,

1308 )

1309

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

1311 # an `__iter__` convenience method.

1312 response = pagers.ListSubscriptionsPager(

1313 method=rpc,

1314 request=request,

1315 response=response,

1316 retry=retry,

1317 timeout=timeout,

1318 metadata=metadata,

1319 )

1320

1321 # Done; return the response.

1322 return response

1323

1324 def delete_subscription(

1325 self,

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

1327 *,

1328 subscription: Optional[str] = None,

1329 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1332 ) -> None:

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

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

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

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

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

1338 topic unless the same topic is specified.

1339

1340 .. code-block:: python

1341

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

1343 # code template only.

1344 # It will require modifications to work:

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

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

1347 # client as shown in:

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

1349 from google import pubsub_v1

1350

1351 def sample_delete_subscription():

1352 # Create a client

1353 client = pubsub_v1.SubscriberClient()

1354

1355 # Initialize request argument(s)

1356 request = pubsub_v1.DeleteSubscriptionRequest(

1357 subscription="subscription_value",

1358 )

1359

1360 # Make the request

1361 client.delete_subscription(request=request)

1362

1363 Args:

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

1365 The request object. Request for the DeleteSubscription

1366 method.

1367 subscription (str):

1368 Required. The subscription to delete. Format is

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

1370

1371 This corresponds to the ``subscription`` field

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

1373 should not be set.

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

1375 should be retried.

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

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

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

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

1380 be of type `bytes`.

1381 """

1382 # Create or coerce a protobuf request object.

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

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

1385 flattened_params = [subscription]

1386 has_flattened_params = (

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

1388 )

1389 if request is not None and has_flattened_params:

1390 raise ValueError(

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

1392 "the individual field arguments should be set."

1393 )

1394

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

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

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

1398 request = pubsub.DeleteSubscriptionRequest(request)

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

1400 # request, apply these.

1401 if subscription is not None:

1402 request.subscription = subscription

1403

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

1405 # and friendly error handling.

1406 rpc = self._transport._wrapped_methods[self._transport.delete_subscription]

1407

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

1409 # add these here.

1410 metadata = tuple(metadata) + (

1411 gapic_v1.routing_header.to_grpc_metadata(

1412 (("subscription", request.subscription),)

1413 ),

1414 )

1415

1416 # Validate the universe domain.

1417 self._validate_universe_domain()

1418

1419 # Send the request.

1420 rpc(

1421 request,

1422 retry=retry,

1423 timeout=timeout,

1424 metadata=metadata,

1425 )

1426

1427 def modify_ack_deadline(

1428 self,

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

1430 *,

1431 subscription: Optional[str] = None,

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

1433 ack_deadline_seconds: Optional[int] = None,

1434 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1437 ) -> None:

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

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

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

1441 redelivery if the processing was interrupted. Note that this

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

1443 used for subsequent messages.

1444

1445 .. code-block:: python

1446

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

1448 # code template only.

1449 # It will require modifications to work:

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

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

1452 # client as shown in:

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

1454 from google import pubsub_v1

1455

1456 def sample_modify_ack_deadline():

1457 # Create a client

1458 client = pubsub_v1.SubscriberClient()

1459

1460 # Initialize request argument(s)

1461 request = pubsub_v1.ModifyAckDeadlineRequest(

1462 subscription="subscription_value",

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

1464 ack_deadline_seconds=2066,

1465 )

1466

1467 # Make the request

1468 client.modify_ack_deadline(request=request)

1469

1470 Args:

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

1472 The request object. Request for the ModifyAckDeadline

1473 method.

1474 subscription (str):

1475 Required. The name of the subscription. Format is

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

1477

1478 This corresponds to the ``subscription`` field

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

1480 should not be set.

1481 ack_ids (MutableSequence[str]):

1482 Required. List of acknowledgment IDs.

1483 This corresponds to the ``ack_ids`` field

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

1485 should not be set.

1486 ack_deadline_seconds (int):

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

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

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

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

1491 was made. Specifying zero might immediately make the

1492 message available for delivery to another subscriber

1493 client. This typically results in an increase in the

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

1495 minimum deadline you can specify is 0 seconds. The

1496 maximum deadline you can specify in a single request is

1497 600 seconds (10 minutes).

1498

1499 This corresponds to the ``ack_deadline_seconds`` field

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

1501 should not be set.

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

1503 should be retried.

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

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

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

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

1508 be of type `bytes`.

1509 """

1510 # Create or coerce a protobuf request object.

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

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

1513 flattened_params = [subscription, ack_ids, ack_deadline_seconds]

1514 has_flattened_params = (

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

1516 )

1517 if request is not None and has_flattened_params:

1518 raise ValueError(

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

1520 "the individual field arguments should be set."

1521 )

1522

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

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

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

1526 request = pubsub.ModifyAckDeadlineRequest(request)

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

1528 # request, apply these.

1529 if subscription is not None:

1530 request.subscription = subscription

1531 if ack_ids is not None:

1532 request.ack_ids = ack_ids

1533 if ack_deadline_seconds is not None:

1534 request.ack_deadline_seconds = ack_deadline_seconds

1535

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

1537 # and friendly error handling.

1538 rpc = self._transport._wrapped_methods[self._transport.modify_ack_deadline]

1539

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

1541 # add these here.

1542 metadata = tuple(metadata) + (

1543 gapic_v1.routing_header.to_grpc_metadata(

1544 (("subscription", request.subscription),)

1545 ),

1546 )

1547

1548 # Validate the universe domain.

1549 self._validate_universe_domain()

1550

1551 # Send the request.

1552 rpc(

1553 request,

1554 retry=retry,

1555 timeout=timeout,

1556 metadata=metadata,

1557 )

1558

1559 def acknowledge(

1560 self,

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

1562 *,

1563 subscription: Optional[str] = None,

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

1565 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1568 ) -> None:

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

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

1571 relevant messages from the subscription.

1572

1573 Acknowledging a message whose ack deadline has expired may

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

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

1576 error.

1577

1578 .. code-block:: python

1579

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

1581 # code template only.

1582 # It will require modifications to work:

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

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

1585 # client as shown in:

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

1587 from google import pubsub_v1

1588

1589 def sample_acknowledge():

1590 # Create a client

1591 client = pubsub_v1.SubscriberClient()

1592

1593 # Initialize request argument(s)

1594 request = pubsub_v1.AcknowledgeRequest(

1595 subscription="subscription_value",

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

1597 )

1598

1599 # Make the request

1600 client.acknowledge(request=request)

1601

1602 Args:

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

1604 The request object. Request for the Acknowledge method.

1605 subscription (str):

1606 Required. The subscription whose message is being

1607 acknowledged. Format is

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

1609

1610 This corresponds to the ``subscription`` field

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

1612 should not be set.

1613 ack_ids (MutableSequence[str]):

1614 Required. The acknowledgment ID for the messages being

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

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

1617

1618 This corresponds to the ``ack_ids`` field

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

1620 should not be set.

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

1622 should be retried.

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

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

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

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

1627 be of type `bytes`.

1628 """

1629 # Create or coerce a protobuf request object.

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

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

1632 flattened_params = [subscription, ack_ids]

1633 has_flattened_params = (

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

1635 )

1636 if request is not None and has_flattened_params:

1637 raise ValueError(

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

1639 "the individual field arguments should be set."

1640 )

1641

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

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

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

1645 request = pubsub.AcknowledgeRequest(request)

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

1647 # request, apply these.

1648 if subscription is not None:

1649 request.subscription = subscription

1650 if ack_ids is not None:

1651 request.ack_ids = ack_ids

1652

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

1654 # and friendly error handling.

1655 rpc = self._transport._wrapped_methods[self._transport.acknowledge]

1656

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

1658 # add these here.

1659 metadata = tuple(metadata) + (

1660 gapic_v1.routing_header.to_grpc_metadata(

1661 (("subscription", request.subscription),)

1662 ),

1663 )

1664

1665 # Validate the universe domain.

1666 self._validate_universe_domain()

1667

1668 # Send the request.

1669 rpc(

1670 request,

1671 retry=retry,

1672 timeout=timeout,

1673 metadata=metadata,

1674 )

1675

1676 def pull(

1677 self,

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

1679 *,

1680 subscription: Optional[str] = None,

1681 return_immediately: Optional[bool] = None,

1682 max_messages: Optional[int] = None,

1683 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1686 ) -> pubsub.PullResponse:

1687 r"""Pulls messages from the server.

1688

1689 .. code-block:: python

1690

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

1692 # code template only.

1693 # It will require modifications to work:

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

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

1696 # client as shown in:

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

1698 from google import pubsub_v1

1699

1700 def sample_pull():

1701 # Create a client

1702 client = pubsub_v1.SubscriberClient()

1703

1704 # Initialize request argument(s)

1705 request = pubsub_v1.PullRequest(

1706 subscription="subscription_value",

1707 max_messages=1277,

1708 )

1709

1710 # Make the request

1711 response = client.pull(request=request)

1712

1713 # Handle the response

1714 print(response)

1715

1716 Args:

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

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

1719 subscription (str):

1720 Required. The subscription from which messages should be

1721 pulled. Format is

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

1723

1724 This corresponds to the ``subscription`` field

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

1726 should not be set.

1727 return_immediately (bool):

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

1729 respond immediately even if it there are no messages

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

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

1732 at least one message is available, rather than returning

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

1734 discouraged because it adversely impacts the performance

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

1736 set this field.

1737

1738 This corresponds to the ``return_immediately`` field

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

1740 should not be set.

1741 max_messages (int):

1742 Required. The maximum number of

1743 messages to return for this request.

1744 Must be a positive integer. The Pub/Sub

1745 system may return fewer than the number

1746 specified.

1747

1748 This corresponds to the ``max_messages`` field

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

1750 should not be set.

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

1752 should be retried.

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

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

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

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

1757 be of type `bytes`.

1758

1759 Returns:

1760 google.pubsub_v1.types.PullResponse:

1761 Response for the Pull method.

1762 """

1763 # Create or coerce a protobuf request object.

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

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

1766 flattened_params = [subscription, return_immediately, max_messages]

1767 has_flattened_params = (

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

1769 )

1770 if request is not None and has_flattened_params:

1771 raise ValueError(

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

1773 "the individual field arguments should be set."

1774 )

1775

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

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

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

1779 request = pubsub.PullRequest(request)

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

1781 # request, apply these.

1782 if subscription is not None:

1783 request.subscription = subscription

1784 if return_immediately is not None:

1785 request.return_immediately = return_immediately

1786 if max_messages is not None:

1787 request.max_messages = max_messages

1788

1789 if request.return_immediately:

1790 warnings.warn(

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

1792 category=DeprecationWarning,

1793 )

1794

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

1796 # and friendly error handling.

1797 rpc = self._transport._wrapped_methods[self._transport.pull]

1798

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

1800 # add these here.

1801 metadata = tuple(metadata) + (

1802 gapic_v1.routing_header.to_grpc_metadata(

1803 (("subscription", request.subscription),)

1804 ),

1805 )

1806

1807 # Validate the universe domain.

1808 self._validate_universe_domain()

1809

1810 # Send the request.

1811 response = rpc(

1812 request,

1813 retry=retry,

1814 timeout=timeout,

1815 metadata=metadata,

1816 )

1817

1818 # Done; return the response.

1819 return response

1820

1821 def streaming_pull(

1822 self,

1823 requests: Optional[Iterator[pubsub.StreamingPullRequest]] = None,

1824 *,

1825 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1828 ) -> Iterable[pubsub.StreamingPullResponse]:

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

1830 to the client. The client streams acknowledgments and ack

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

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

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

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

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

1836 configuring the underlying RPC channel.

1837

1838 .. code-block:: python

1839

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

1841 # code template only.

1842 # It will require modifications to work:

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

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

1845 # client as shown in:

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

1847 from google import pubsub_v1

1848

1849 def sample_streaming_pull():

1850 # Create a client

1851 client = pubsub_v1.SubscriberClient()

1852

1853 # Initialize request argument(s)

1854 request = pubsub_v1.StreamingPullRequest(

1855 subscription="subscription_value",

1856 stream_ack_deadline_seconds=2813,

1857 )

1858

1859 # This method expects an iterator which contains

1860 # 'pubsub_v1.StreamingPullRequest' objects

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

1862 # demonstrative purposes.

1863 requests = [request]

1864

1865 def request_generator():

1866 for request in requests:

1867 yield request

1868

1869 # Make the request

1870 stream = client.streaming_pull(requests=request_generator())

1871

1872 # Handle the response

1873 for response in stream:

1874 print(response)

1875

1876 Args:

1877 requests (Iterator[google.pubsub_v1.types.StreamingPullRequest]):

1878 The request object iterator. Request for the ``StreamingPull`` streaming RPC method.

1879 This request is used to establish the initial stream as

1880 well as to stream acknowledgments and ack deadline

1881 modifications from the client to the server.

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

1883 should be retried.

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

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

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

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

1888 be of type `bytes`.

1889

1890 Returns:

1891 Iterable[google.pubsub_v1.types.StreamingPullResponse]:

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

1893 messages from the server to the client.

1894

1895 """

1896

1897 # Wrappers in api-core should not automatically pre-fetch the first

1898 # stream result, as this breaks the stream when re-opening it.

1899 # https://github.com/googleapis/python-pubsub/issues/93#issuecomment-630762257

1900 self._transport.streaming_pull._prefetch_first_result_ = False

1901

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

1903 # and friendly error handling.

1904 rpc = self._transport._wrapped_methods[self._transport.streaming_pull]

1905

1906 # Validate the universe domain.

1907 self._validate_universe_domain()

1908

1909 # Send the request.

1910 response = rpc(

1911 requests,

1912 retry=retry,

1913 timeout=timeout,

1914 metadata=metadata,

1915 )

1916

1917 # Done; return the response.

1918 return response

1919

1920 def modify_push_config(

1921 self,

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

1923 *,

1924 subscription: Optional[str] = None,

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

1926 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

1929 ) -> None:

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

1931

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

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

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

1935 Messages will accumulate for delivery continuously through the

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

1937

1938 .. code-block:: python

1939

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

1941 # code template only.

1942 # It will require modifications to work:

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

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

1945 # client as shown in:

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

1947 from google import pubsub_v1

1948

1949 def sample_modify_push_config():

1950 # Create a client

1951 client = pubsub_v1.SubscriberClient()

1952

1953 # Initialize request argument(s)

1954 request = pubsub_v1.ModifyPushConfigRequest(

1955 subscription="subscription_value",

1956 )

1957

1958 # Make the request

1959 client.modify_push_config(request=request)

1960

1961 Args:

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

1963 The request object. Request for the ModifyPushConfig

1964 method.

1965 subscription (str):

1966 Required. The name of the subscription. Format is

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

1968

1969 This corresponds to the ``subscription`` field

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

1971 should not be set.

1972 push_config (google.pubsub_v1.types.PushConfig):

1973 Required. The push configuration for future deliveries.

1974

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

1976 system should stop pushing messages from the given

1977 subscription and allow messages to be pulled and

1978 acknowledged - effectively pausing the subscription if

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

1980

1981 This corresponds to the ``push_config`` field

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

1983 should not be set.

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

1985 should be retried.

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

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

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

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

1990 be of type `bytes`.

1991 """

1992 # Create or coerce a protobuf request object.

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

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

1995 flattened_params = [subscription, push_config]

1996 has_flattened_params = (

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

1998 )

1999 if request is not None and has_flattened_params:

2000 raise ValueError(

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

2002 "the individual field arguments should be set."

2003 )

2004

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

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

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

2008 request = pubsub.ModifyPushConfigRequest(request)

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

2010 # request, apply these.

2011 if subscription is not None:

2012 request.subscription = subscription

2013 if push_config is not None:

2014 request.push_config = push_config

2015

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

2017 # and friendly error handling.

2018 rpc = self._transport._wrapped_methods[self._transport.modify_push_config]

2019

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

2021 # add these here.

2022 metadata = tuple(metadata) + (

2023 gapic_v1.routing_header.to_grpc_metadata(

2024 (("subscription", request.subscription),)

2025 ),

2026 )

2027

2028 # Validate the universe domain.

2029 self._validate_universe_domain()

2030

2031 # Send the request.

2032 rpc(

2033 request,

2034 retry=retry,

2035 timeout=timeout,

2036 metadata=metadata,

2037 )

2038

2039 def get_snapshot(

2040 self,

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

2042 *,

2043 snapshot: Optional[str] = None,

2044 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2047 ) -> pubsub.Snapshot:

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

2049 in

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

2051 operations, which allow you to manage message acknowledgments in

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

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

2054

2055 .. code-block:: python

2056

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

2058 # code template only.

2059 # It will require modifications to work:

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

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

2062 # client as shown in:

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

2064 from google import pubsub_v1

2065

2066 def sample_get_snapshot():

2067 # Create a client

2068 client = pubsub_v1.SubscriberClient()

2069

2070 # Initialize request argument(s)

2071 request = pubsub_v1.GetSnapshotRequest(

2072 snapshot="snapshot_value",

2073 )

2074

2075 # Make the request

2076 response = client.get_snapshot(request=request)

2077

2078 # Handle the response

2079 print(response)

2080

2081 Args:

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

2083 The request object. Request for the GetSnapshot method.

2084 snapshot (str):

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

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

2087

2088 This corresponds to the ``snapshot`` field

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

2090 should not be set.

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

2092 should be retried.

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

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

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

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

2097 be of type `bytes`.

2098

2099 Returns:

2100 google.pubsub_v1.types.Snapshot:

2101 A snapshot resource. Snapshots are used in

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

2103 operations, which allow you to manage message

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

2105 acknowledgment state of messages in an existing

2106 subscription to the state captured by a snapshot.

2107

2108 """

2109 # Create or coerce a protobuf request object.

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

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

2112 flattened_params = [snapshot]

2113 has_flattened_params = (

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

2115 )

2116 if request is not None and has_flattened_params:

2117 raise ValueError(

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

2119 "the individual field arguments should be set."

2120 )

2121

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

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

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

2125 request = pubsub.GetSnapshotRequest(request)

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

2127 # request, apply these.

2128 if snapshot is not None:

2129 request.snapshot = snapshot

2130

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

2132 # and friendly error handling.

2133 rpc = self._transport._wrapped_methods[self._transport.get_snapshot]

2134

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

2136 # add these here.

2137 metadata = tuple(metadata) + (

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

2139 )

2140

2141 # Validate the universe domain.

2142 self._validate_universe_domain()

2143

2144 # Send the request.

2145 response = rpc(

2146 request,

2147 retry=retry,

2148 timeout=timeout,

2149 metadata=metadata,

2150 )

2151

2152 # Done; return the response.

2153 return response

2154

2155 def list_snapshots(

2156 self,

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

2158 *,

2159 project: Optional[str] = None,

2160 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2163 ) -> pagers.ListSnapshotsPager:

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

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

2166 operations, which allow you to manage message acknowledgments in

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

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

2169

2170 .. code-block:: python

2171

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

2173 # code template only.

2174 # It will require modifications to work:

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

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

2177 # client as shown in:

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

2179 from google import pubsub_v1

2180

2181 def sample_list_snapshots():

2182 # Create a client

2183 client = pubsub_v1.SubscriberClient()

2184

2185 # Initialize request argument(s)

2186 request = pubsub_v1.ListSnapshotsRequest(

2187 project="project_value",

2188 )

2189

2190 # Make the request

2191 page_result = client.list_snapshots(request=request)

2192

2193 # Handle the response

2194 for response in page_result:

2195 print(response)

2196

2197 Args:

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

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

2200 project (str):

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

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

2203

2204 This corresponds to the ``project`` field

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

2206 should not be set.

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

2208 should be retried.

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

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

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

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

2213 be of type `bytes`.

2214

2215 Returns:

2216 google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager:

2217 Response for the ListSnapshots method.

2218

2219 Iterating over this object will yield results and

2220 resolve additional pages automatically.

2221

2222 """

2223 # Create or coerce a protobuf request object.

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

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

2226 flattened_params = [project]

2227 has_flattened_params = (

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

2229 )

2230 if request is not None and has_flattened_params:

2231 raise ValueError(

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

2233 "the individual field arguments should be set."

2234 )

2235

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

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

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

2239 request = pubsub.ListSnapshotsRequest(request)

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

2241 # request, apply these.

2242 if project is not None:

2243 request.project = project

2244

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

2246 # and friendly error handling.

2247 rpc = self._transport._wrapped_methods[self._transport.list_snapshots]

2248

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

2250 # add these here.

2251 metadata = tuple(metadata) + (

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

2253 )

2254

2255 # Validate the universe domain.

2256 self._validate_universe_domain()

2257

2258 # Send the request.

2259 response = rpc(

2260 request,

2261 retry=retry,

2262 timeout=timeout,

2263 metadata=metadata,

2264 )

2265

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

2267 # an `__iter__` convenience method.

2268 response = pagers.ListSnapshotsPager(

2269 method=rpc,

2270 request=request,

2271 response=response,

2272 retry=retry,

2273 timeout=timeout,

2274 metadata=metadata,

2275 )

2276

2277 # Done; return the response.

2278 return response

2279

2280 def create_snapshot(

2281 self,

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

2283 *,

2284 name: Optional[str] = None,

2285 subscription: Optional[str] = None,

2286 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2289 ) -> pubsub.Snapshot:

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

2291 are used in

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

2293 operations, which allow you to manage message acknowledgments in

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

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

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

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

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

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

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

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

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

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

2304 the [resource name format]

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

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

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

2308 request.

2309

2310 .. code-block:: python

2311

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

2313 # code template only.

2314 # It will require modifications to work:

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

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

2317 # client as shown in:

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

2319 from google import pubsub_v1

2320

2321 def sample_create_snapshot():

2322 # Create a client

2323 client = pubsub_v1.SubscriberClient()

2324

2325 # Initialize request argument(s)

2326 request = pubsub_v1.CreateSnapshotRequest(

2327 name="name_value",

2328 subscription="subscription_value",

2329 )

2330

2331 # Make the request

2332 response = client.create_snapshot(request=request)

2333

2334 # Handle the response

2335 print(response)

2336

2337 Args:

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

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

2340 name (str):

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

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

2343 assign a random name for this snapshot on the same

2344 project as the subscription. Note that for REST API

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

2346 name

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

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

2349

2350 This corresponds to the ``name`` field

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

2352 should not be set.

2353 subscription (str):

2354 Required. The subscription whose backlog the snapshot

2355 retains. Specifically, the created snapshot is

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

2357 subscription. More precisely, this is defined as the

2358 messages in the subscription's backlog that are

2359 unacknowledged upon the successful completion of the

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

2361 published to the subscription's topic following the

2362 successful completion of the CreateSnapshot request.

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

2364

2365 This corresponds to the ``subscription`` field

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

2367 should not be set.

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

2369 should be retried.

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

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

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

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

2374 be of type `bytes`.

2375

2376 Returns:

2377 google.pubsub_v1.types.Snapshot:

2378 A snapshot resource. Snapshots are used in

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

2380 operations, which allow you to manage message

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

2382 acknowledgment state of messages in an existing

2383 subscription to the state captured by a snapshot.

2384

2385 """

2386 # Create or coerce a protobuf request object.

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

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

2389 flattened_params = [name, subscription]

2390 has_flattened_params = (

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

2392 )

2393 if request is not None and has_flattened_params:

2394 raise ValueError(

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

2396 "the individual field arguments should be set."

2397 )

2398

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

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

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

2402 request = pubsub.CreateSnapshotRequest(request)

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

2404 # request, apply these.

2405 if name is not None:

2406 request.name = name

2407 if subscription is not None:

2408 request.subscription = subscription

2409

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

2411 # and friendly error handling.

2412 rpc = self._transport._wrapped_methods[self._transport.create_snapshot]

2413

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

2415 # add these here.

2416 metadata = tuple(metadata) + (

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

2418 )

2419

2420 # Validate the universe domain.

2421 self._validate_universe_domain()

2422

2423 # Send the request.

2424 response = rpc(

2425 request,

2426 retry=retry,

2427 timeout=timeout,

2428 metadata=metadata,

2429 )

2430

2431 # Done; return the response.

2432 return response

2433

2434 def update_snapshot(

2435 self,

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

2437 *,

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

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

2440 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2443 ) -> pubsub.Snapshot:

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

2445 the update mask. Snapshots are used in

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

2447 operations, which allow you to manage message acknowledgments in

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

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

2450

2451 .. code-block:: python

2452

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

2454 # code template only.

2455 # It will require modifications to work:

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

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

2458 # client as shown in:

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

2460 from google import pubsub_v1

2461

2462 def sample_update_snapshot():

2463 # Create a client

2464 client = pubsub_v1.SubscriberClient()

2465

2466 # Initialize request argument(s)

2467 request = pubsub_v1.UpdateSnapshotRequest(

2468 )

2469

2470 # Make the request

2471 response = client.update_snapshot(request=request)

2472

2473 # Handle the response

2474 print(response)

2475

2476 Args:

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

2478 The request object. Request for the UpdateSnapshot

2479 method.

2480 snapshot (google.pubsub_v1.types.Snapshot):

2481 Required. The updated snapshot

2482 object.

2483

2484 This corresponds to the ``snapshot`` field

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

2486 should not be set.

2487 update_mask (google.protobuf.field_mask_pb2.FieldMask):

2488 Required. Indicates which fields in

2489 the provided snapshot to update. Must be

2490 specified and non-empty.

2491

2492 This corresponds to the ``update_mask`` field

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

2494 should not be set.

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

2496 should be retried.

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

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

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

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

2501 be of type `bytes`.

2502

2503 Returns:

2504 google.pubsub_v1.types.Snapshot:

2505 A snapshot resource. Snapshots are used in

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

2507 operations, which allow you to manage message

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

2509 acknowledgment state of messages in an existing

2510 subscription to the state captured by a snapshot.

2511

2512 """

2513 # Create or coerce a protobuf request object.

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

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

2516 flattened_params = [snapshot, update_mask]

2517 has_flattened_params = (

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

2519 )

2520 if request is not None and has_flattened_params:

2521 raise ValueError(

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

2523 "the individual field arguments should be set."

2524 )

2525

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

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

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

2529 request = pubsub.UpdateSnapshotRequest(request)

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

2531 # request, apply these.

2532 if snapshot is not None:

2533 request.snapshot = snapshot

2534 if update_mask is not None:

2535 request.update_mask = update_mask

2536

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

2538 # and friendly error handling.

2539 rpc = self._transport._wrapped_methods[self._transport.update_snapshot]

2540

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

2542 # add these here.

2543 metadata = tuple(metadata) + (

2544 gapic_v1.routing_header.to_grpc_metadata(

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

2546 ),

2547 )

2548

2549 # Validate the universe domain.

2550 self._validate_universe_domain()

2551

2552 # Send the request.

2553 response = rpc(

2554 request,

2555 retry=retry,

2556 timeout=timeout,

2557 metadata=metadata,

2558 )

2559

2560 # Done; return the response.

2561 return response

2562

2563 def delete_snapshot(

2564 self,

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

2566 *,

2567 snapshot: Optional[str] = None,

2568 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2571 ) -> None:

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

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

2574 operations, which allow you to manage message acknowledgments in

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

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

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

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

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

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

2581 the same subscription is specified.

2582

2583 .. code-block:: python

2584

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

2586 # code template only.

2587 # It will require modifications to work:

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

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

2590 # client as shown in:

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

2592 from google import pubsub_v1

2593

2594 def sample_delete_snapshot():

2595 # Create a client

2596 client = pubsub_v1.SubscriberClient()

2597

2598 # Initialize request argument(s)

2599 request = pubsub_v1.DeleteSnapshotRequest(

2600 snapshot="snapshot_value",

2601 )

2602

2603 # Make the request

2604 client.delete_snapshot(request=request)

2605

2606 Args:

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

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

2609 snapshot (str):

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

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

2612

2613 This corresponds to the ``snapshot`` field

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

2615 should not be set.

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

2617 should be retried.

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

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

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

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

2622 be of type `bytes`.

2623 """

2624 # Create or coerce a protobuf request object.

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

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

2627 flattened_params = [snapshot]

2628 has_flattened_params = (

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

2630 )

2631 if request is not None and has_flattened_params:

2632 raise ValueError(

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

2634 "the individual field arguments should be set."

2635 )

2636

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

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

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

2640 request = pubsub.DeleteSnapshotRequest(request)

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

2642 # request, apply these.

2643 if snapshot is not None:

2644 request.snapshot = snapshot

2645

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

2647 # and friendly error handling.

2648 rpc = self._transport._wrapped_methods[self._transport.delete_snapshot]

2649

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

2651 # add these here.

2652 metadata = tuple(metadata) + (

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

2654 )

2655

2656 # Validate the universe domain.

2657 self._validate_universe_domain()

2658

2659 # Send the request.

2660 rpc(

2661 request,

2662 retry=retry,

2663 timeout=timeout,

2664 metadata=metadata,

2665 )

2666

2667 def seek(

2668 self,

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

2670 *,

2671 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2674 ) -> pubsub.SeekResponse:

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

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

2677 used in [Seek]

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

2679 operations, which allow you to manage message acknowledgments in

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

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

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

2683 same topic.

2684

2685 .. code-block:: python

2686

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

2688 # code template only.

2689 # It will require modifications to work:

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

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

2692 # client as shown in:

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

2694 from google import pubsub_v1

2695

2696 def sample_seek():

2697 # Create a client

2698 client = pubsub_v1.SubscriberClient()

2699

2700 # Initialize request argument(s)

2701 request = pubsub_v1.SeekRequest(

2702 subscription="subscription_value",

2703 )

2704

2705 # Make the request

2706 response = client.seek(request=request)

2707

2708 # Handle the response

2709 print(response)

2710

2711 Args:

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

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

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

2715 should be retried.

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

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

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

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

2720 be of type `bytes`.

2721

2722 Returns:

2723 google.pubsub_v1.types.SeekResponse:

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

2725 """

2726 # Create or coerce a protobuf request object.

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

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

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

2730 request = pubsub.SeekRequest(request)

2731

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

2733 # and friendly error handling.

2734 rpc = self._transport._wrapped_methods[self._transport.seek]

2735

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

2737 # add these here.

2738 metadata = tuple(metadata) + (

2739 gapic_v1.routing_header.to_grpc_metadata(

2740 (("subscription", request.subscription),)

2741 ),

2742 )

2743

2744 # Validate the universe domain.

2745 self._validate_universe_domain()

2746

2747 # Send the request.

2748 response = rpc(

2749 request,

2750 retry=retry,

2751 timeout=timeout,

2752 metadata=metadata,

2753 )

2754

2755 # Done; return the response.

2756 return response

2757

2758 def __enter__(self) -> "SubscriberClient":

2759 return self

2760

2761 def __exit__(self, type, value, traceback):

2762 """Releases underlying transport's resources.

2763

2764 .. warning::

2765 ONLY use as a context manager if the transport is NOT shared

2766 with other clients! Exiting the with block will CLOSE the transport

2767 and may cause errors in other clients!

2768 """

2769 self.transport.close()

2770

2771 def set_iam_policy(

2772 self,

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

2774 *,

2775 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2778 ) -> policy_pb2.Policy:

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

2780

2781 Replaces any existing policy.

2782

2783 Args:

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

2785 The request object. Request message for `SetIamPolicy`

2786 method.

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

2788 should be retried.

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

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

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

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

2793 be of type `bytes`.

2794 Returns:

2795 ~.policy_pb2.Policy:

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

2797 It is used to specify access control policies for Cloud

2798 Platform resources.

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

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

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

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

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

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

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

2806 expression that further constrains the role binding

2807 based on attributes about the request and/or target

2808 resource.

2809

2810 **JSON Example**

2811

2812 ::

2813

2814 {

2815 "bindings": [

2816 {

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

2818 "members": [

2819 "user:mike@example.com",

2820 "group:admins@example.com",

2821 "domain:google.com",

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

2823 ]

2824 },

2825 {

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

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

2828 "condition": {

2829 "title": "expirable access",

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

2831 "expression": "request.time <

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

2833 }

2834 }

2835 ]

2836 }

2837

2838 **YAML Example**

2839

2840 ::

2841

2842 bindings:

2843 - members:

2844 - user:mike@example.com

2845 - group:admins@example.com

2846 - domain:google.com

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

2848 role: roles/resourcemanager.organizationAdmin

2849 - members:

2850 - user:eve@example.com

2851 role: roles/resourcemanager.organizationViewer

2852 condition:

2853 title: expirable access

2854 description: Does not grant access after Sep 2020

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

2856

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

2858 developer's

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

2860 """

2861 # Create or coerce a protobuf request object.

2862

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

2864 # so it must be constructed via keyword expansion.

2865 if isinstance(request, dict):

2866 request = iam_policy_pb2.SetIamPolicyRequest(**request)

2867

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

2869 # and friendly error handling.

2870 rpc = self._transport._wrapped_methods[self._transport.set_iam_policy]

2871

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

2873 # add these here.

2874 metadata = tuple(metadata) + (

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

2876 )

2877

2878 # Validate the universe domain.

2879 self._validate_universe_domain()

2880

2881 try:

2882 # Send the request.

2883 response = rpc(

2884 request,

2885 retry=retry,

2886 timeout=timeout,

2887 metadata=metadata,

2888 )

2889

2890 # Done; return the response.

2891 return response

2892 except core_exceptions.GoogleAPICallError as e:

2893 self._add_cred_info_for_auth_errors(e)

2894 raise e

2895

2896 def get_iam_policy(

2897 self,

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

2899 *,

2900 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

2903 ) -> policy_pb2.Policy:

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

2905

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

2907 policy set.

2908

2909 Args:

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

2911 The request object. Request message for `GetIamPolicy`

2912 method.

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

2914 any, should be retried.

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

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

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

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

2919 be of type `bytes`.

2920 Returns:

2921 ~.policy_pb2.Policy:

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

2923 It is used to specify access control policies for Cloud

2924 Platform resources.

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

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

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

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

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

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

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

2932 expression that further constrains the role binding

2933 based on attributes about the request and/or target

2934 resource.

2935

2936 **JSON Example**

2937

2938 ::

2939

2940 {

2941 "bindings": [

2942 {

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

2944 "members": [

2945 "user:mike@example.com",

2946 "group:admins@example.com",

2947 "domain:google.com",

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

2949 ]

2950 },

2951 {

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

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

2954 "condition": {

2955 "title": "expirable access",

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

2957 "expression": "request.time <

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

2959 }

2960 }

2961 ]

2962 }

2963

2964 **YAML Example**

2965

2966 ::

2967

2968 bindings:

2969 - members:

2970 - user:mike@example.com

2971 - group:admins@example.com

2972 - domain:google.com

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

2974 role: roles/resourcemanager.organizationAdmin

2975 - members:

2976 - user:eve@example.com

2977 role: roles/resourcemanager.organizationViewer

2978 condition:

2979 title: expirable access

2980 description: Does not grant access after Sep 2020

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

2982

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

2984 developer's

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

2986 """

2987 # Create or coerce a protobuf request object.

2988

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

2990 # so it must be constructed via keyword expansion.

2991 if isinstance(request, dict):

2992 request = iam_policy_pb2.GetIamPolicyRequest(**request)

2993

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

2995 # and friendly error handling.

2996 rpc = self._transport._wrapped_methods[self._transport.get_iam_policy]

2997

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

2999 # add these here.

3000 metadata = tuple(metadata) + (

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

3002 )

3003

3004 # Validate the universe domain.

3005 self._validate_universe_domain()

3006

3007 try:

3008 # Send the request.

3009 response = rpc(

3010 request,

3011 retry=retry,

3012 timeout=timeout,

3013 metadata=metadata,

3014 )

3015

3016 # Done; return the response.

3017 return response

3018 except core_exceptions.GoogleAPICallError as e:

3019 self._add_cred_info_for_auth_errors(e)

3020 raise e

3021

3022 def test_iam_permissions(

3023 self,

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

3025 *,

3026 retry: OptionalRetry = gapic_v1.method.DEFAULT,

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

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

3029 ) -> iam_policy_pb2.TestIamPermissionsResponse:

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

3031 policy for a function.

3032

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

3034 of permissions, not a NOT_FOUND error.

3035

3036 Args:

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

3038 The request object. Request message for

3039 `TestIamPermissions` method.

3040 retry (google.api_core.retry.Retry): Designation of what errors,

3041 if any, should be retried.

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

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

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

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

3046 be of type `bytes`.

3047 Returns:

3048 ~.iam_policy_pb2.TestIamPermissionsResponse:

3049 Response message for ``TestIamPermissions`` method.

3050 """

3051 # Create or coerce a protobuf request object.

3052

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

3054 # so it must be constructed via keyword expansion.

3055 if isinstance(request, dict):

3056 request = iam_policy_pb2.TestIamPermissionsRequest(**request)

3057

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

3059 # and friendly error handling.

3060 rpc = self._transport._wrapped_methods[self._transport.test_iam_permissions]

3061

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

3063 # add these here.

3064 metadata = tuple(metadata) + (

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

3066 )

3067

3068 # Validate the universe domain.

3069 self._validate_universe_domain()

3070

3071 try:

3072 # Send the request.

3073 response = rpc(

3074 request,

3075 retry=retry,

3076 timeout=timeout,

3077 metadata=metadata,

3078 )

3079

3080 # Done; return the response.

3081 return response

3082 except core_exceptions.GoogleAPICallError as e:

3083 self._add_cred_info_for_auth_errors(e)

3084 raise e

3085

3086

3087DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(

3088 client_library_version=package_version.__version__

3089)

3090

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

3092 DEFAULT_CLIENT_INFO.protobuf_runtime_version = google.protobuf.__version__

3093

3094__all__ = ("SubscriberClient",)

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

531 statements