chore: emit a warning if return_immediately is set (#355)

This flag is deprecated and should always be set to `False` when
pulling messages synchronously.

google/pubsub_v1/services/subscriber/async_client.py

@@ -28,6 +28,7 @@
  Type,
  Union,
 )
+import warnings
 import pkg_resources
 
 import google.api_core.client_options as ClientOptions # type: ignore
@@ -935,6 +936,12 @@ async def pull(
  if max_messages is not None:
  request.max_messages = max_messages
 
+ if request.return_immediately:
+ warnings.warn(
+ "The return_immediately flag is deprecated and should be set to False.",
+ category=DeprecationWarning,
+ )
+
  # Wrap the RPC method; this adds retry and timeout information,
  # and friendly error handling.
  rpc = gapic_v1.method_async.wrap_method(

google/pubsub_v1/services/subscriber/client.py

@@ -31,6 +31,7 @@
  Type,
  Union,
 )
+import warnings
 import pkg_resources
 
 from google.api_core import client_options as client_options_lib # type: ignore
@@ -1124,6 +1125,12 @@ def pull(
  if max_messages is not None:
  request.max_messages = max_messages
 
+ if request.return_immediately:
+ warnings.warn(
+ "The return_immediately flag is deprecated and should be set to False.",
+ category=DeprecationWarning,
+ )
+
  # Wrap the RPC method; this adds retry and timeout information,
  # and friendly error handling.
  rpc = self._transport._wrapped_methods[self._transport.pull]

synth.py

@@ -76,7 +76,7 @@
  flags=re.MULTILINE | re.DOTALL,
 )
 
-if count < 18:
+if count < 15:
  raise Exception("Expected replacements for gRPC channel options not made.")
 
 # If the emulator is used, force an insecure gRPC channel to avoid SSL errors.
@@ -141,6 +141,35 @@
  \g<0>""",
 )
 
+# Emit deprecation warning if return_immediately flag is set with synchronous pull.
+count = s.replace(
+ "google/pubsub_v1/services/subscriber/*client.py",
+ r"import pkg_resources",
+ "import warnings\n\g<0>",
+)
+count = s.replace(
+ "google/pubsub_v1/services/subscriber/*client.py",
+ r"""
+ ([^\n\S]+(?:async\ )?def\ pull\(.*?->\ pubsub\.PullResponse:.*?)
+ ((?P<indent>[^\n\S]+)\#\ Wrap\ the\ RPC\ method)
+ """,
+ textwrap.dedent(
+ """
+ \g<1>
+ \g<indent>if request.return_immediately:
+ \g<indent> warnings.warn(
+ \g<indent> "The return_immediately flag is deprecated and should be set to False.",
+ \g<indent> category=DeprecationWarning,
+ \g<indent> )
+
+ \g<2>"""
+ ),
+ flags=re.MULTILINE | re.DOTALL | re.VERBOSE,
+)
+
+if count != 2:
+ raise Exception("Too many or too few replacements in pull() methods.")
+
 # Make sure that client library version is present in user agent header.
 s.replace(
  [

tests/unit/pubsub_v1/subscriber/test_subscriber_client.py

@@ -12,9 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import warnings
+
 from google.auth import credentials
 import grpc
 import mock
+import pytest
 
 from google.api_core.gapic_v1.client_info import METRICS_METADATA_KEY
 from google.cloud.pubsub_v1 import subscriber
@@ -217,3 +220,43 @@ def test_streaming_pull_gapic_monkeypatch():
  transport = client.api._transport
  assert hasattr(transport.streaming_pull, "_prefetch_first_result_")
  assert not transport.streaming_pull._prefetch_first_result_
+
+
+def test_sync_pull_warning_if_return_immediately():
+ client = subscriber.Client()
+ subscription_path = "projects/foo/subscriptions/bar"
+
+ with mock.patch.object(
+ client.api._transport, "_wrapped_methods"
+ ), warnings.catch_warnings(record=True) as warned:
+ client.pull(subscription=subscription_path, return_immediately=True)
+
+ # Setting the deprecated return_immediately flag to True should emit a warning.
+ assert len(warned) == 1
+ assert issubclass(warned[0].category, DeprecationWarning)
+ warning_msg = str(warned[0].message)
+ assert "return_immediately" in warning_msg
+ assert "deprecated" in warning_msg
+
+
+@pytest.mark.asyncio
+async def test_sync_pull_warning_if_return_immediately_async():
+ from google.pubsub_v1.services.subscriber.async_client import SubscriberAsyncClient
+
+ client = SubscriberAsyncClient()
+ subscription_path = "projects/foo/subscriptions/bar"
+
+ patcher = mock.patch(
+ "google.pubsub_v1.services.subscriber.async_client.gapic_v1.method_async.wrap_method",
+ new=mock.AsyncMock,
+ )
+
+ with patcher, warnings.catch_warnings(record=True) as warned:
+ await client.pull(subscription=subscription_path, return_immediately=True)
+
+ # Setting the deprecated return_immediately flag to True should emit a warning.
+ assert len(warned) == 1
+ assert issubclass(warned[0].category, DeprecationWarning)
+ warning_msg = str(warned[0].message)
+ assert "return_immediately" in warning_msg
+ assert "deprecated" in warning_msg