[SB] Update max_wait_time docstrings (Azure#31513)

* update docstring

* update receive_messages()

* deprecation docstring

* update doc

* update statement

* pylint

* update wording

* line too long

* update deprecation statement

* add warnings.warn

* update deprecation

* remove deprecated max_wait_time

* add back msg count

* update max_wait_time samples

Author: l0lawrence

sdk/servicebus/azure-servicebus/azure/servicebus/_servicebus_client.py

@@ -356,10 +356,12 @@ def get_queue_receiver(
          will be immediately removed from the queue, and cannot be subsequently rejected or re-received if
          the client fails to process the message. The default receive_mode is PEEK_LOCK.
         :paramtype receive_mode: Union[~azure.servicebus.ServiceBusReceiveMode, str]
-        :keyword Optional[float] max_wait_time: The timeout in seconds between received messages after which the
-         receiver will automatically stop receiving. The default value is None, meaning no timeout. If connection
-         errors are occurring due to write timing out, the connection timeout value may need to be adjusted. See
-         the `socket_timeout` optional parameter for more details.
+        :keyword Optional[float] max_wait_time:  The timeout in seconds to wait for the first and subsequent
+         messages to arrive after which the receiver will automatically stop receiving. If no messages arrive,
+         and no timeout is specified, this call will not return until the connection is closed.
+         The default value is None, meaning no timeout. If connection errors are occurring due to write timing out,
+         the connection timeout value may need to be adjusted. See the `socket_timeout`
+         optional parameter for more details.
         :keyword Optional[~azure.servicebus.AutoLockRenewer] auto_lock_renewer: An ~azure.servicebus.AutoLockRenewer
          can be provided such that messages are automatically registered on receipt. If the receiver is a session
          receiver, it will apply to the session instead.
@@ -538,10 +540,12 @@ def get_subscription_receiver(
          will be immediately removed from the subscription, and cannot be subsequently rejected or re-received if
          the client fails to process the message. The default receive_mode is PEEK_LOCK.
         :paramtype receive_mode: Union[~azure.servicebus.ServiceBusReceiveMode, str]
-        :keyword Optional[float] max_wait_time: The timeout in seconds between received messages after which the
-         receiver will automatically stop receiving. The default value is None, meaning no timeout. If connection
-         errors are occurring due to write timing out, the connection timeout value may need to be adjusted. See
-         the `socket_timeout` optional parameter for more details.
+        :keyword Optional[float] max_wait_time: The timeout in seconds to wait for the first and subsequent
+         messages to arrive after which the receiver will automatically stop receiving. If no messages arrive,
+         and no timeout is specified, this call will not return until the connection is closed.
+         The default value is None, meaning no timeout. If connection errors are occurring due to write timing out,
+         the connection timeout value may need to be adjusted. See the `socket_timeout`
+         optional parameter for more details.
         :keyword Optional[~azure.servicebus.AutoLockRenewer] auto_lock_renewer: An ~azure.servicebus.AutoLockRenewer
          can be provided such that messages are automatically registered on receipt. If the receiver is a session
          receiver, it will apply to the session instead.

sdk/servicebus/azure-servicebus/azure/servicebus/_servicebus_receiver.py

@@ -105,8 +105,10 @@ class ServiceBusReceiver(
      the client connects to.
     :keyword str subscription_name: The path of specific Service Bus Subscription under the
      specified Topic the client connects to.
-    :keyword Optional[float] max_wait_time: The timeout in seconds between received messages after which the
-     receiver will automatically stop receiving. The default value is None, meaning no timeout.
+    :keyword Optional[float] max_wait_time: The timeout in seconds to wait for the first and subsequent
+     messages to arrive after which the receiver will automatically stop receiving. If no messages arrive,
+     and no timeout is specified, this call will not return until the connection is closed.
+     The default value is None, meaning no timeout.
     :keyword receive_mode: The mode with which messages will be retrieved from the entity. The two options
      are PEEK_LOCK and RECEIVE_AND_DELETE. Messages received with PEEK_LOCK must be settled within a given
      lock period before they will be removed from the queue. Messages received with RECEIVE_AND_DELETE
@@ -286,8 +288,10 @@ def _from_connection_string(
          if the client fails to process the message.
          The default mode is PEEK_LOCK.
         :paramtype receive_mode: Union[~azure.servicebus.ServiceBusReceiveMode, str]
-        :keyword Optional[float] max_wait_time: The timeout in seconds between received messages after which the
-         receiver will automatically stop receiving. The default value is None, meaning no timeout.
+        :keyword Optional[float] max_wait_time:  The timeout in seconds to wait for the first and subsequent
+         messages to arrive after which the receiver will automatically stop receiving. If no messages arrive,
+         and no timeout is specified, this call will not return until the connection is closed.
+         The default value is None, meaning no timeout.
         :keyword bool logging_enable: Whether to output network trace logs to the logger. Default is `False`.
         :keyword transport_type: The type of transport protocol that will be used for communicating with
          the Service Bus service. Default is `TransportType.Amqp`.
@@ -656,10 +660,10 @@ def receive_messages(
         :param Optional[int] max_message_count: Maximum number of messages in the batch. Actual number
          returned will depend on prefetch_count and incoming stream rate.
          Setting to None will fully depend on the prefetch config. The default value is 1.
-        :param Optional[float] max_wait_time: Maximum time to wait in seconds for the first message to arrive.
-         If no messages arrive, and no timeout is specified, this call will not return
-         until the connection is closed. If specified, an no messages arrive within the
-         timeout period, an empty list will be returned.
+        :param Optional[float] max_wait_time: DEPRECATED. It is not advised to use this parameter when
+         calling this method. If you'd like to specify max_wait_time, please pass it in during client
+         construction. If specified, this parameter will interact with the absolute operation timeout
+         and impact the amount of time alloted to retry the receive operation.
         :return: A list of messages received. If no messages are available, this will be an empty list.
         :rtype: List[~azure.servicebus.ServiceBusReceivedMessage]
 
@@ -674,6 +678,8 @@ def receive_messages(
 
         """
         self._check_live()
+        if max_wait_time:
+            warnings.warn("max_wait_time is deprecated. Please set it in client constructor.", DeprecationWarning)
         if max_wait_time is not None and max_wait_time <= 0:
             raise ValueError("The max_wait_time must be greater than 0.")
         if max_message_count is not None and max_message_count <= 0:

sdk/servicebus/azure-servicebus/azure/servicebus/aio/_servicebus_client_async.py

@@ -341,10 +341,12 @@ def get_queue_receiver(
          will be immediately removed from the queue, and cannot be subsequently rejected or re-received if
          the client fails to process the message. The default mode is PEEK_LOCK.
         :paramtype receive_mode: Union[~azure.servicebus.ServiceBusReceiveMode, str]
-        :keyword Optional[float] max_wait_time: The timeout in seconds between received messages after which the
-         receiver will automatically stop receiving. The default value is None, meaning no timeout. If connection
-         errors are occurring due to write timing out, the connection timeout value may need to be adjusted. See
-         the `socket_timeout` optional parameter for more details.
+        :keyword Optional[float] max_wait_time: The timeout in seconds to wait for the first and subsequent
+         messages to arrive after which the receiver will automatically stop receiving. If no messages arrive,
+         and no timeout is specified, this call will not return until the connection is closed.
+         The default value is None, meaning no timeout. If connection errors are occurring due to write timing out,
+         the connection timeout value may need to be adjusted. See the `socket_timeout`
+         optional parameter for more details.
         :keyword Optional[~azure.servicebus.aio.AutoLockRenewer] auto_lock_renewer: An
          ~azure.servicebus.aio.AutoLockRenewer can be provided such that messages are automatically registered on
          receipt. If the receiver is a session receiver, it will apply to the session instead.
@@ -520,10 +522,12 @@ def get_subscription_receiver(
          will be immediately removed from the subscription, and cannot be subsequently rejected or re-received if
          the client fails to process the message. The default mode is PEEK_LOCK.
         :paramtype receive_mode: Union[~azure.servicebus.ServiceBusReceiveMode, str]
-        :keyword Optional[float] max_wait_time: The timeout in seconds between received messages after which the
-         receiver will automatically stop receiving. The default value is None, meaning no timeout. If connection
-         errors are occurring due to write timing out, the connection timeout value may need to be adjusted. See
-         the `socket_timeout` optional parameter for more details.
+        :keyword Optional[float] max_wait_time: The timeout in seconds to wait for the first and subsequent
+         messages to arrive after which the receiver will automatically stop receiving. If no messages arrive,
+         and no timeout is specified, this call will not return until the connection is closed.
+         The default value is None, meaning no timeout. If connection errors are occurring due to write timing out,
+         the connection timeout value may need to be adjusted. See the `socket_timeout`
+         optional parameter for more details.
         :keyword Optional[~azure.servicebus.aio.AutoLockRenewer] auto_lock_renewer: An
          ~azure.servicebus.aio.AutoLockRenewer can be provided such that messages are automatically registered on
          receipt. If the receiver is a session receiver, it will apply to the session instead.

sdk/servicebus/azure-servicebus/azure/servicebus/aio/_servicebus_receiver_async.py

@@ -109,8 +109,10 @@ class ServiceBusReceiver(collections.abc.AsyncIterator, BaseHandler, ReceiverMix
      if the client fails to process the message.
      The default mode is PEEK_LOCK.
     :paramtype receive_mode: Union[~azure.servicebus.ServiceBusReceiveMode, str]
-    :keyword Optional[float] max_wait_time: The timeout in seconds between received messages after which the receiver
-     will automatically stop receiving. The default value is None, meaning no timeout.
+    :keyword Optional[float] max_wait_time:  The timeout in seconds to wait for the first and subsequent
+     messages to arrive after which the receiver will automatically stop receiving. If no messages arrive,
+     and no timeout is specified, this call will not return until the connection is closed.
+     The default value is None, meaning no timeout.
     :keyword bool logging_enable: Whether to output network trace logs to the logger. Default is `False`.
     :keyword transport_type: The type of transport protocol that will be used for communicating with
      the Service Bus service. Default is `TransportType.Amqp`.
@@ -277,8 +279,10 @@ def _from_connection_string(
          if the client fails to process the message.
          The default mode is PEEK_LOCK.
         :paramtype receive_mode: Union[~azure.servicebus.ServiceBusReceiveMode, str]
-        :keyword Optional[float] max_wait_time: The timeout in seconds between received messages after which the
-         receiver will automatically stop receiving. The default value is None, meaning no timeout.
+        :keyword Optional[float] max_wait_time:  The timeout in seconds to wait for the first and subsequent
+         messages to arrive after which the receiver will automatically stop receiving. If no messages arrive,
+         and no timeout is specified, this call will not return until the connection is closed.
+         The default value is None, meaning no timeout.
         :keyword bool logging_enable: Whether to output network trace logs to the logger. Default is `False`.
         :keyword transport_type: The type of transport protocol that will be used for communicating with
          the Service Bus service. Default is `TransportType.Amqp`.
@@ -629,10 +633,10 @@ async def receive_messages(
         :param Optional[int] max_message_count: Maximum number of messages in the batch. Actual number
          returned will depend on prefetch_count size and incoming stream rate.
          Setting to None will fully depend on the prefetch config. The default value is 1.
-        :param Optional[float] max_wait_time: Maximum time to wait in seconds for the first message to arrive.
-         If no messages arrive, and no timeout is specified, this call will not return
-         until the connection is closed. If specified, and no messages arrive within the
-         timeout period, an empty list will be returned.
+        :param Optional[float] max_wait_time: DEPRECATED. It is not advised to use this parameter when
+         calling this method. If you'd like to specify max_wait_time, please pass it in during client
+         construction. If specified, this parameter will interact with the absolute operation timeout
+         and impact the amount of time alloted to retry the receive operation.
         :return: A list of messages received. If no messages are available, this will be an empty list.
         :rtype: list[~azure.servicebus.aio.ServiceBusReceivedMessage]
 
@@ -647,6 +651,8 @@ async def receive_messages(
 
         """
         self._check_live()
+        if max_wait_time:
+            warnings.warn("max_wait_time is deprecated. Please set it in client constructor.", DeprecationWarning)
         if max_wait_time is not None and max_wait_time <= 0:
             raise ValueError("The max_wait_time must be greater than 0.")
         if max_message_count is not None and max_message_count <= 0:

sdk/servicebus/azure-servicebus/samples/async_samples/auto_lock_renew_async.py

@@ -39,8 +39,8 @@ async def renew_lock_on_message_received_from_non_sessionful_entity():
         # Can also be called via "with AutoLockRenewer() as renewer" to automate shutdown.
         renewer = AutoLockRenewer()
 
-        async with servicebus_client.get_queue_receiver(queue_name=QUEUE_NAME, prefetch_count=10) as receiver:
-            received_msgs = await receiver.receive_messages(max_message_count=10, max_wait_time=5)
+        async with servicebus_client.get_queue_receiver(queue_name=QUEUE_NAME, prefetch_count=10, max_wait_time=5) as receiver:
+            received_msgs = await receiver.receive_messages(max_message_count=10)
 
             for msg in received_msgs:
                 # automatically renew the lock on each message for 100 seconds
@@ -71,13 +71,14 @@ async def renew_lock_on_session_of_the_sessionful_entity():
         async with servicebus_client.get_queue_receiver(
             queue_name=SESSION_QUEUE_NAME,
             session_id='SESSION',
-            prefetch_count=10
+            prefetch_count=10,
+            max_wait_time=5
         ) as receiver:
             # automatically renew the lock on the session for 100 seconds
             renewer.register(receiver, receiver.session, max_lock_renewal_duration=100)
             print('Register session into AutoLockRenewer.')
 
-            received_msgs = await receiver.receive_messages(max_message_count=10, max_wait_time=5)
+            received_msgs = await receiver.receive_messages(max_message_count=10)
             await asyncio.sleep(100)  # message handling for long period (E.g. application logic)
 
             for msg in received_msgs:
@@ -96,7 +97,7 @@ async def renew_lock_with_lock_renewal_failure_callback():
             # For this sample we're going to set the renewal recurrence of the autolockrenewer to greater than the
             # service side message lock duration, to demonstrate failure.  Normally, this should not be adjusted.
             renewer._sleep_time = 40
-            async with servicebus_client.get_queue_receiver(queue_name=QUEUE_NAME, prefetch_count=10) as receiver:
+            async with servicebus_client.get_queue_receiver(queue_name=QUEUE_NAME, prefetch_count=10, max_wait_time=5) as receiver:
 
                 async def on_lock_renew_failure_callback(renewable, error):
                     # If auto-lock-renewal fails, this function will be called.
@@ -106,7 +107,7 @@ async def on_lock_renew_failure_callback(renewable, error):
                     # handle any processing on the message or session that was in progress.
                     print("Intentionally failed to renew lock on {} due to {}".format(renewable, error))
 
-                received_msgs = await receiver.receive_messages(max_message_count=1, max_wait_time=5)
+                received_msgs = await receiver.receive_messages(max_message_count=1)
 
                 for msg in received_msgs:
                     # automatically renew the lock on each message for 120 seconds