Docs: Mark exactly once delivery as preview

.github/sync-repo-settings.yaml

@@ -13,3 +13,5 @@ branchProtectionRules:
     - 'Samples - Lint'
     - 'Samples - Python 3.7'
     - 'Samples - Python 3.8'
+    - 'Samples - Python 3.9'
+    - 'Samples - Python 3.10'

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,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`

google/pubsub_v1/services/publisher/async_client.py

@@ -16,7 +16,7 @@
 from collections import OrderedDict
 import functools
 import re
-from typing import Dict, Optional, Sequence, Tuple, Type, Union
+from typing import Dict, Mapping, Optional, Sequence, Tuple, Type, Union
 import pkg_resources
 
 from google.api_core.client_options import ClientOptions
@@ -220,7 +220,6 @@ async def create_topic(
         name rules]
         (https://cloud.google.com/pubsub/docs/admin#resource_names).
 
-
         .. code-block:: python
 
             from google import pubsub_v1
@@ -329,7 +328,6 @@ async def update_topic(
         r"""Updates an existing topic. Note that certain
         properties of a topic are not modifiable.
 
-
         .. code-block:: python
 
             from google import pubsub_v1
@@ -418,7 +416,6 @@ async def publish(
         r"""Adds one or more messages to the topic. Returns ``NOT_FOUND`` if
         the topic does not exist.
 
-
         .. code-block:: python
 
             from google import pubsub_v1
@@ -758,7 +755,6 @@ async def list_topic_subscriptions(
         r"""Lists the names of the attached subscriptions on this
         topic.
 
-
         .. code-block:: python
 
             from google import pubsub_v1
@@ -884,7 +880,6 @@ async def list_topic_snapshots(
         bulk. That is, you can set the acknowledgment state of messages
         in an existing subscription to the state captured by a snapshot.
 
-
         .. code-block:: python
 
             from google import pubsub_v1
@@ -1010,7 +1005,6 @@ async def delete_topic(
         subscriptions to this topic are not deleted, but their ``topic``
         field is set to ``_deleted-topic_``.
 
-
         .. code-block:: python
 
             from google import pubsub_v1
@@ -1107,7 +1101,6 @@ async def detach_subscription(
         the subscription is a push subscription, pushes to the endpoint
         will stop.
 
-
         .. code-block:: python
 
             from google import pubsub_v1

google/pubsub_v1/services/publisher/client.py

@@ -17,7 +17,7 @@
 import functools
 import os
 import re
-from typing import Dict, Optional, Sequence, Tuple, Type, Union
+from typing import Dict, Mapping, Optional, Sequence, Tuple, Type, Union
 import pkg_resources
 
 from google.api_core import client_options as client_options_lib
@@ -503,7 +503,6 @@ def create_topic(
         name rules]
         (https://cloud.google.com/pubsub/docs/admin#resource_names).
 
-
         .. code-block:: python
 
             from google import pubsub_v1
@@ -604,7 +603,6 @@ def update_topic(
         r"""Updates an existing topic. Note that certain
         properties of a topic are not modifiable.
 
-
         .. code-block:: python
 
             from google import pubsub_v1
@@ -686,7 +684,6 @@ def publish(
         r"""Adds one or more messages to the topic. Returns ``NOT_FOUND`` if
         the topic does not exist.
 
-
         .. code-block:: python
 
             from google import pubsub_v1
@@ -992,7 +989,6 @@ def list_topic_subscriptions(
         r"""Lists the names of the attached subscriptions on this
         topic.
 
-
         .. code-block:: python
 
             from google import pubsub_v1
@@ -1108,7 +1104,6 @@ def list_topic_snapshots(
         bulk. That is, you can set the acknowledgment state of messages
         in an existing subscription to the state captured by a snapshot.
 
-
         .. code-block:: python
 
             from google import pubsub_v1
@@ -1224,7 +1219,6 @@ def delete_topic(
         subscriptions to this topic are not deleted, but their ``topic``
         field is set to ``_deleted-topic_``.
 
-
         .. code-block:: python
 
             from google import pubsub_v1
@@ -1313,7 +1307,6 @@ def detach_subscription(
         the subscription is a push subscription, pushes to the endpoint
         will stop.
 
-
         .. code-block:: python
 
             from google import pubsub_v1

google/pubsub_v1/services/publisher/transports/base.py

@@ -86,6 +86,7 @@ def __init__(
             always_use_jwt_access (Optional[bool]): Whether self signed JWT should
                 be used for service account credentials.
         """
+
         # Save the hostname. Default to port 443 (HTTPS) if none is specified.
         if ":" not in host:
             host += ":443"
@@ -391,5 +392,9 @@ def test_iam_permissions(
     ]:
         raise NotImplementedError()
 
+    @property
+    def kind(self) -> str:
+        raise NotImplementedError()
+
 
 __all__ = ("PublisherTransport",)

google/pubsub_v1/services/publisher/transports/grpc.py

@@ -565,5 +565,9 @@ def test_iam_permissions(
     def close(self):
         self.grpc_channel.close()
 
+    @property
+    def kind(self) -> str:
+        return "grpc"
+
 
 __all__ = ("PublisherGrpcTransport",)

google/pubsub_v1/services/schema_service/async_client.py

@@ -16,7 +16,7 @@
 from collections import OrderedDict
 import functools
 import re
-from typing import Dict, Optional, Sequence, Tuple, Type, Union
+from typing import Dict, Mapping, Optional, Sequence, Tuple, Type, Union
 import pkg_resources
 
 from google.api_core.client_options import ClientOptions

google/pubsub_v1/services/schema_service/client.py

@@ -16,7 +16,7 @@
 from collections import OrderedDict
 import os
 import re
-from typing import Dict, Optional, Sequence, Tuple, Type, Union
+from typing import Dict, Mapping, Optional, Sequence, Tuple, Type, Union
 import pkg_resources
 
 from google.api_core import client_options as client_options_lib

google/pubsub_v1/services/schema_service/transports/base.py

@@ -87,6 +87,7 @@ def __init__(
             always_use_jwt_access (Optional[bool]): Whether self signed JWT should
                 be used for service account credentials.
         """
+
         # Save the hostname. Default to port 443 (HTTPS) if none is specified.
         if ":" not in host:
             host += ":443"
@@ -255,5 +256,9 @@ def test_iam_permissions(
     ]:
         raise NotImplementedError()
 
+    @property
+    def kind(self) -> str:
+        raise NotImplementedError()
+
 
 __all__ = ("SchemaServiceTransport",)

google/pubsub_v1/services/schema_service/transports/grpc.py

@@ -468,5 +468,9 @@ def test_iam_permissions(
     def close(self):
         self.grpc_channel.close()
 
+    @property
+    def kind(self) -> str:
+        return "grpc"
+
 
 __all__ = ("SchemaServiceGrpcTransport",)