Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: mark exactly once as preview feature #657

Merged
merged 2 commits into from
Apr 14, 2022
Merged

docs: mark exactly once as preview feature #657

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
93b5bed
docs: mark eod as preview
acocuzzo Apr 14, 2022
ebb789d
Merge branch 'main' into mark-eod-preview
acocuzzo Apr 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 27 additions & 15 deletions google/cloud/pubsub_v1/subscriber/message.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -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:
Expand Down Expand Up @@ -434,15 +443,18 @@ 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,
the future's result will be an AcknowledgeStatus.SUCCESS.
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`
Expand Down
5 changes: 4 additions & 1 deletion samples/snippets/subscriber.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down