Rename autolockrenew shutdown to close to normalize method name with …

…other comparable instances. Adjust tests/docs/guides/etc.

Add changelog entry for the on lock renew callback.

sdk/servicebus/azure-servicebus/CHANGELOG.md

@@ -1,10 +1,16 @@
 # Release History
 
-## 7.0.0b4 (Unreleased)
+## 7.0.0b5 (Unreleased)
 
 **New Features**
 
-* Add an on_lock_renew_failure as a parameter to `AutoLockRenew`, taking a callback for when the lock is lost non-intentially (e.g. not via settling, shutdown, or autolockrenew duration completion)
+* Add `on_lock_renew_failure` as a parameter to `AutoLockRenew.register`, taking a callback for when the lock is lost non-intentially (e.g. not via settling, shutdown, or autolockrenew duration completion)
+
+**Breaking Changes**
+
+* `AutoLockRenew.shutdown` is now `AutoLockRenew.close` to normalize with other equivelent behaviors.
+
+## 7.0.0b4 (Unreleased)
 
 **BugFixes**
 

sdk/servicebus/azure-servicebus/README.md

@@ -381,7 +381,7 @@ connstr = os.environ['SERVICE_BUS_CONN_STR']
 queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']
 session_id = os.environ['SERVICE_BUS_SESSION_ID']
 
-# Can also be called via "with AutoLockRenew() as renewer" to automate shutdown.
+# Can also be called via "with AutoLockRenew() as renewer" to automate closing.
 renewer = AutoLockRenew()
 with ServiceBusClient.from_connection_string(connstr) as client:
     with client.get_queue_session_receiver(queue_name, session_id=session_id) as receiver:
@@ -390,7 +390,7 @@ with ServiceBusClient.from_connection_string(connstr) as client:
             renewer.register(msg, timeout=60)
             # Do your application logic here
             msg.complete()
-renewer.shutdown()
+renewer.close()
 ```
 
 If for any reason auto-renewal has been interrupted or failed, this can be observed via the `auto_renew_error` property on the object being renewed.

sdk/servicebus/azure-servicebus/azure/servicebus/_common/auto_lock_renewer.py

@@ -60,7 +60,7 @@ def __enter__(self):
         return self
 
     def __exit__(self, *args):
-        self.shutdown()
+        self.close()
 
     def _renewable(self, renewable):
         if self._shutdown.is_set():
@@ -118,8 +118,8 @@ def register(self, renewable, timeout=300, on_lock_renew_failure=None):
         starttime = renewable_start_time(renewable)
         self.executor.submit(self._auto_lock_renew, renewable, starttime, timeout, on_lock_renew_failure)
 
-    def shutdown(self, wait=True):
-        """Shutdown the thread pool to clean up any remaining lock renewal threads.
+    def close(self, wait=True):
+        """Cease autorenewal by shutting down the thread pool to clean up any remaining lock renewal threads.
 
         :param wait: Whether to block until thread pool has shutdown. Default is `True`.
         :type wait: bool

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

@@ -59,7 +59,7 @@ async def __aenter__(self) -> "AutoLockRenew":
         return self
 
     async def __aexit__(self, *args: Iterable[Any]) -> None:
-        await self.shutdown()
+        await self.close()
 
     def _renewable(self, renewable: "Union[ReceivedMessage, ServiceBusSession]") -> bool:
         if self._shutdown.is_set():
@@ -124,7 +124,7 @@ def register(self,
         renew_future = asyncio.ensure_future(self._auto_lock_renew(renewable, starttime, timeout, on_lock_renew_failure), loop=self.loop)
         self._futures.append(renew_future)
 
-    async def shutdown(self) -> None:
-        """Cancel remaining open lock renewal futures."""
+    async def close(self) -> None:
+        """Cease autorenewal by cancelling any remaining open lock renewal futures."""
         self._shutdown.set()
         await asyncio.wait(self._futures)

sdk/servicebus/azure-servicebus/migration_guide.md

@@ -76,6 +76,11 @@ semantics with the sender or receiver lifetime.
 | `azure.servicebus.control_client.ServiceBusService().create_queue(queue_name)` | `azure.servicebus.management.ServiceBusManagementClient().create_queue(queue_name)` | [Create a queue](./samples/sync_samples/mgmt_queue.py) |
 | `azure.servicebus.ServiceBusClient().list_queues()` | `azure.servicebus.management.ServiceBusManagementClient().list_queues()` | [List queues](./samples/sync_samples/mgmt_queue.py ) |
 
+### Working with AutoLockRenew
+| In v0.50 | Equivalent in v7 | Sample |
+|---|---|---|
+| `azure.servicebus.AutoLockRenew().shutdown()` | `azure.servicebus.AutoLockRenew().close()` | [Close an auto-lock-renewer](./samples/sync_samples/auto_lock_renew.py) |
+
 
 ## Migration samples
 

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

@@ -50,7 +50,7 @@ async def renew_lock_on_message_received_from_non_sessionful_entity():
                 await msg.complete()
             print('Complete messages.')
 
-        await renewer.shutdown()
+        await renewer.close()
 
 
 async def renew_lock_on_session_of_the_sessionful_entity():
@@ -81,7 +81,7 @@ async def renew_lock_on_session_of_the_sessionful_entity():
                 await msg.complete()
             print('Complete messages.')
 
-        await renewer.shutdown()
+        await renewer.close()
 
 
 loop = asyncio.get_event_loop()

sdk/servicebus/azure-servicebus/samples/sync_samples/auto_lock_renew.py

@@ -49,7 +49,7 @@ def renew_lock_on_message_received_from_non_sessionful_entity():
                 msg.complete() # Settling the message deregisters it from the AutoLockRenewer
             print('Complete messages.')
 
-        renewer.shutdown()
+        renewer.close()
 
 
 def renew_lock_on_session_of_the_sessionful_entity():
@@ -82,7 +82,7 @@ def renew_lock_on_session_of_the_sessionful_entity():
 
             print('Complete messages.')
 
-        renewer.shutdown()
+        renewer.close()
 
 
 renew_lock_on_message_received_from_non_sessionful_entity()

sdk/servicebus/azure-servicebus/tests/async_tests/test_queues_async.py

@@ -725,7 +725,7 @@ async def test_async_queue_by_queue_client_conn_str_receive_handler_with_autoloc
                             print("Remaining messages", message.locked_until_utc, utc_now())
                             messages.append(message)
                             await message.complete()
-            await renewer.shutdown()
+            await renewer.close()
             assert len(messages) == 11
 
     @pytest.mark.liveTest
@@ -1148,7 +1148,7 @@ async def callback_mock(renewable):
         async with auto_lock_renew: # Check that it is not called when the renewer is shutdown
             message = MockReceivedMessage(prevent_renew_lock=True)
             auto_lock_renew.register(renewable=message, on_lock_renew_failure=callback_mock)
-            await auto_lock_renew.shutdown()
+            await auto_lock_renew.close()
             await asyncio.sleep(3)
             assert len(results) == 2
 
@@ -1184,7 +1184,7 @@ async def test_async_queue_mock_no_reusing_auto_lock_renew(self):
         auto_lock_renew.register(renewable=MockReceivedMessage())
         time.sleep(3)
 
-        await auto_lock_renew.shutdown()
+        await auto_lock_renew.close()
 
         with pytest.raises(ServiceBusError):
             async with auto_lock_renew:

sdk/servicebus/azure-servicebus/tests/async_tests/test_sessions_async.py

@@ -525,7 +525,7 @@ async def lock_lost_callback(renewable):
             await asyncio.sleep(max(0,(session.locked_until_utc - utc_now()).total_seconds()+1)) # If this pattern repeats make sleep_until_expired_async
             assert not results
 
-            await renewer.shutdown()
+            await renewer.close()
             assert len(messages) == 2
 
 
@@ -626,7 +626,7 @@ async def test_async_session_schedule_message(self, servicebus_namespace_connect
                     assert len(messages) == 1
                 else:
                     raise Exception("Failed to receive schdeduled message.")
-            await renewer.shutdown()
+            await renewer.close()
 
 
     @pytest.mark.liveTest
@@ -666,7 +666,7 @@ async def test_async_session_schedule_multiple_messages(self, servicebus_namespa
                     assert len(messages) == 2
                 else:
                     raise Exception("Failed to receive schdeduled message.")
-            await renewer.shutdown()
+            await renewer.close()
 
 
     @pytest.mark.liveTest
@@ -700,7 +700,7 @@ async def test_async_session_cancel_scheduled_messages(self, servicebus_namespac
                         print(str(m))
                         await m.complete()
                     raise
-            await renewer.shutdown()
+            await renewer.close()
 
 
     @pytest.mark.liveTest

sdk/servicebus/azure-servicebus/tests/test_queues.py

@@ -821,7 +821,7 @@ def test_queue_by_queue_client_conn_str_receive_handler_with_autolockrenew(self,
                             print("Remaining messages", message.locked_until_utc, utc_now())
                             messages.append(message)
                             message.complete()
-            renewer.shutdown()
+            renewer.close()
             assert len(messages) == 11
 
     @pytest.mark.liveTest
@@ -1259,7 +1259,7 @@ def callback_mock(renewable):
         with auto_lock_renew: # Check that it is not called when the renewer is shutdown
             message = MockReceivedMessage(prevent_renew_lock=True)
             auto_lock_renew.register(renewable=message, on_lock_renew_failure=callback_mock)
-            auto_lock_renew.shutdown()
+            auto_lock_renew.close()
             time.sleep(3)
             assert len(results) == 2
 
@@ -1294,7 +1294,7 @@ def test_queue_mock_no_reusing_auto_lock_renew(self):
             auto_lock_renew.register(renewable=MockReceivedMessage())
             time.sleep(3)
 
-        auto_lock_renew.shutdown()
+        auto_lock_renew.close()
 
         with pytest.raises(ServiceBusError):
             with auto_lock_renew:

sdk/servicebus/azure-servicebus/tests/test_sessions.py

@@ -597,7 +597,7 @@ def lock_lost_callback(renewable):
             sleep_until_expired(receiver.session)
             assert not results
 
-            renewer.shutdown()
+            renewer.close()
             assert len(messages) == 2