PubSub: Deprecate several FlowControl settings and things in Message class (googleapis#8796)

plamut · web-flow · commit b32e4e9904f0 · 2019-07-29T12:46:22.000+02:00
* Deprecate several PubSub FlowControl settings

* Deprecate things in PubSub message.Message class

* Change deprecation release version to 0.44.0
diff --git a/pubsub/google/cloud/pubsub_v1/subscriber/message.py b/pubsub/google/cloud/pubsub_v1/subscriber/message.py
@@ -18,6 +18,7 @@
 import json
 import math
 import time
+import warnings
 
 from google.api_core import datetime_helpers
 from google.cloud.pubsub_v1.subscriber._protocol import requests
@@ -88,6 +89,10 @@ def __init__(self, message, ack_id, request_queue, autolease=True):
             autolease (bool): An optional flag determining whether a new Message
                 instance should automatically lease itself upon creation.
                 Defaults to :data:`True`.
+
+                .. note::
+                    .. deprecated:: 0.44.0
+                        Parameter will be removed in future versions.
         """
         self._message = message
         self._ack_id = ack_id
@@ -216,7 +221,14 @@ def lease(self):
             never need to call it manually, unless the
             :class:`~.pubsub_v1.subscriber.message.Message` instance was
             created with ``autolease=False``.
+
+            .. deprecated:: 0.44.0
+                Will be removed in future versions.
         """
+        warnings.warn(
+            "lease() is deprecated since 0.44.0, and will be removed in future versions.",
+            category=DeprecationWarning,
+        )
         self._request_queue.put(
             requests.LeaseRequest(ack_id=self._ack_id, byte_size=self.size)
         )
diff --git a/pubsub/google/cloud/pubsub_v1/types.py b/pubsub/google/cloud/pubsub_v1/types.py
@@ -15,6 +15,7 @@
 from __future__ import absolute_import
 import collections
 import sys
+import textwrap
 
 from google.api import http_pb2
 from google.iam.v1 import iam_policy_pb2
@@ -100,19 +101,41 @@
         "The maximum number of received - but not yet processed - messages before "
         "pausing the message stream."
     )
-    FlowControl.resume_threshold.__doc__ = (
-        "The relative threshold of the ``max_bytes`` and ``max_messages`` limits "
-        "below which to resume the message stream. Must be a positive number not "
-        "greater than ``1.0``."
+    FlowControl.resume_threshold.__doc__ = textwrap.dedent(
+        """
+        The relative threshold of the ``max_bytes`` and ``max_messages`` limits
+        below which to resume the message stream. Must be a positive number not
+        greater than ``1.0``.
+
+        .. note::
+            .. deprecated:: 0.44.0
+                Will be removed in future versions."""
     )
-    FlowControl.max_requests.__doc__ = "Currently not in use."
-    FlowControl.max_request_batch_size.__doc__ = (
-        "The maximum number of requests scheduled by callbacks to process and "
-        "dispatch at a time."
+    FlowControl.max_requests.__doc__ = textwrap.dedent(
+        """
+        Currently not in use.
+
+        .. note::
+            .. deprecated:: 0.44.0
+                Will be removed in future versions."""
+    )
+    FlowControl.max_request_batch_size.__doc__ = textwrap.dedent(
+        """
+        The maximum number of requests scheduled by callbacks to process and
+        dispatch at a time.
+
+        .. note::
+            .. deprecated:: 0.44.0
+                Will be removed in future versions."""
     )
-    FlowControl.max_request_batch_latency.__doc__ = (
-        "The maximum amount of time in seconds to wait for additional request "
-        "items before processing the next batch of requests."
+    FlowControl.max_request_batch_latency.__doc__ = textwrap.dedent(
+        """
+        The maximum amount of time in seconds to wait for additional request
+        items before processing the next batch of requests.
+
+        .. note::
+            .. deprecated:: 0.44.0
+                Will be removed in future versions."""
     )
     FlowControl.max_lease_duration.__doc__ = (
         "The maximum amount of time in seconds to hold a lease on a message "
diff --git a/pubsub/tests/unit/pubsub_v1/subscriber/test_message.py b/pubsub/tests/unit/pubsub_v1/subscriber/test_message.py
@@ -16,6 +16,7 @@
 import time
 
 import mock
+import pytest
 import pytz
 from six.moves import queue
 from google.protobuf import timestamp_pb2
@@ -135,7 +136,9 @@ def test_drop():
 
 def test_lease():
     msg = create_message(b"foo", ack_id="bogus_ack_id")
-    with mock.patch.object(msg._request_queue, "put") as put:
+
+    pytest_warns = pytest.warns(DeprecationWarning)
+    with pytest_warns, mock.patch.object(msg._request_queue, "put") as put:
         msg.lease()
         put.assert_called_once_with(
             requests.LeaseRequest(ack_id="bogus_ack_id", byte_size=30)
