From 93b5bedfc56f0682ae2609960317d0ebbf11abba Mon Sep 17 00:00:00 2001 From: acocuzzo Date: Thu, 14 Apr 2022 16:15:45 -0400 Subject: [PATCH] docs: mark eod as preview --- google/cloud/pubsub_v1/subscriber/message.py | 42 +++++++++++++------- samples/snippets/subscriber.py | 5 ++- 2 files changed, 31 insertions(+), 16 deletions(-) diff --git a/google/cloud/pubsub_v1/subscriber/message.py b/google/cloud/pubsub_v1/subscriber/message.py index ab17bab78..c0a2e70ea 100644 --- a/google/cloud/pubsub_v1/subscriber/message.py +++ b/google/cloud/pubsub_v1/subscriber/message.py @@ -246,7 +246,10 @@ def ack(self) -> None: receive any given message more than once. If you need strong guarantees about acks and re-deliveres, enable exactly-once delivery on your subscription and use the `ack_with_response` - method instead. + method instead. Exactly once delivery is a preview feature. + For more details, see: + https://cloud.google.com/pubsub/docs/exactly-once-delivery." + """ time_to_ack = math.ceil(time.time() - self._received_timestamp) self._request_queue.put( @@ -268,13 +271,6 @@ def ack_with_response(self) -> "futures.Future": *finished* processing them, so that in the event of a failure, you receive the message again. - If exactly-once delivery is enabled on the subscription, the - future returned by this method tracks the state of acknowledgement - operation. If the future completes successfully, the message is - guaranteed NOT to be re-delivered. Otherwise, the future will - contain an exception with more details about the failure and the - message may be re-delivered. - If exactly-once delivery is NOT enabled on the subscription, the future returns immediately with an AcknowledgeStatus.SUCCESS. Since acks in Cloud Pub/Sub are best effort when exactly-once @@ -283,6 +279,16 @@ def ack_with_response(self) -> "futures.Future": code is idempotent, as you may receive any given message more than once. + If exactly-once delivery is enabled on the subscription, the + future returned by this method tracks the state of acknowledgement + operation. If the future completes successfully, the message is + guaranteed NOT to be re-delivered. Otherwise, the future will + contain an exception with more details about the failure and the + message may be re-delivered. + + Exactly once delivery is a preview feature. For more details, + see https://cloud.google.com/pubsub/docs/exactly-once-delivery." + Returns: A :class:`~google.cloud.pubsub_v1.subscriber.futures.Future` instance that conforms to Python Standard library's @@ -363,6 +369,12 @@ def modify_ack_deadline_with_response(self, seconds: int) -> "futures.Future": if you are implementing your own custom subclass of :class:`~.pubsub_v1.subcriber._consumer.Consumer`. + If exactly-once delivery is NOT enabled on the subscription, the + future returns immediately with an AcknowledgeStatus.SUCCESS. + Since modify-ack-deadline operations in Cloud Pub/Sub are best effort + when exactly-once delivery is disabled, the message may be re-delivered + within the set deadline. + If exactly-once delivery is enabled on the subscription, the future returned by this method tracks the state of the modify-ack-deadline operation. If the future completes successfully, @@ -371,11 +383,8 @@ def modify_ack_deadline_with_response(self, seconds: int) -> "futures.Future": the failure and the message will be redelivered according to its currently-set ack deadline. - If exactly-once delivery is NOT enabled on the subscription, the - future returns immediately with an AcknowledgeStatus.SUCCESS. - Since modify-ack-deadline operations in Cloud Pub/Sub are best effort - when exactly-once delivery is disabled, the message may be re-delivered - within the set deadline. + Exactly once delivery is a preview feature. For more details, + see https://cloud.google.com/pubsub/docs/exactly-once-delivery." Args: seconds: @@ -434,6 +443,9 @@ def nack_with_response(self) -> "futures.Future": may take place immediately or after a delay, and may arrive at this subscriber or another. + If exactly-once delivery is NOT enabled on the subscription, the + future returns immediately with an AcknowledgeStatus.SUCCESS. + If exactly-once delivery is enabled on the subscription, the future returned by this method tracks the state of the nack operation. If the future completes successfully, @@ -441,8 +453,8 @@ def nack_with_response(self) -> "futures.Future": Otherwise, the future will contain an exception with more details about the failure. - If exactly-once delivery is NOT enabled on the subscription, the - future returns immediately with an AcknowledgeStatus.SUCCESS. + Exactly once delivery is a preview feature. For more details, + see https://cloud.google.com/pubsub/docs/exactly-once-delivery." Returns: A :class:`~google.cloud.pubsub_v1.subscriber.futures.Future` diff --git a/samples/snippets/subscriber.py b/samples/snippets/subscriber.py index 5a9d0a7a5..a642bf03a 100644 --- a/samples/snippets/subscriber.py +++ b/samples/snippets/subscriber.py @@ -614,7 +614,10 @@ def callback(message: pubsub_v1.subscriber.message.Message) -> None: def receive_messages_with_exactly_once_delivery_enabled( project_id: str, subscription_id: str, timeout: Optional[float] = None ) -> None: - """Receives messages from a pull subscription with exactly-once delivery enabled.""" + """Receives messages from a pull subscription with exactly-once delivery enabled. + This is a preview feature. For more details, see: + https://cloud.google.com/pubsub/docs/exactly-once-delivery." + """ # [START pubsub_subscriber_exactly_once] from concurrent.futures import TimeoutError from google.cloud import pubsub_v1