New ServiceBus SDK (Azure#4165)

* New ServiceBus SDK (Azure#4137) * Servicebus docs updates (Azure#4180) * Docs updates * Some docs cleanup * More docs fixes * Fixed docs indentation * More docs updates * Added Example tags * More docstrings * Fixed return type * Update CODEOWNERS * Test fixes * Review feedback (Azure#4201) * Review feedback * Moved pylint config * Test stabilization * Updated readme * SB capitalization * Docstring fixes * Block comments * Flake8 docs pass * Pylint fix * Updated readme
florentx · Jan 18, 2019 · 7105cb6 · 7105cb6
1 parent 3390380
commit 7105cb6
Show file tree

Hide file tree

Showing 182 changed files with 14,590 additions and 821 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -26,4 +26,5 @@
 /azure-mgmt-servicefabric/ @QingChenmsft
 /azure-mgmt-sql/ @jaredmoo
 /azure-mgmt-web/ @yugangw-msft
+/azure-servicebus/ @annatisch
 /azure-servicefabric/ @samedder
diff --git a/azure-sdk-tools/setup.py b/azure-sdk-tools/setup.py
@@ -38,5 +38,8 @@
         'console_scripts': [
             'generate_package=packaging_tools.generate_package:generate_main',
         ],
+    },
+    extras_require={
+        ":python_version>='3.5'": ['pytest-asyncio>=0.9.0']
     }
 )
diff --git a/azure-servicebus/HISTORY.rst b/azure-servicebus/HISTORY.rst
@@ -3,8 +3,28 @@
 Release History
 ===============
 
+0.50.0 (2019-01-17)
+-------------------
+
+**Breaking changes**
+
+* Introduces new AMQP-based API.
+* Original HTTP-based API still available under new namespace: azure.servicebus.control_client
+* For full API changes, please see updated `reference documentation <https://docs.microsoft.com/python/api/overview/azure/servicebus/client?view=azure-python>`__.
+
+Within the new namespace, the original HTTP-based API from version 0.21.1 remains unchanged (i.e. no additional features or bugfixes)
+so for those intending to only use HTTP operations - there is no additional benefit in updating at this time.
+
+**Features**
+
+* New API supports message send and receive via AMQP with improved performance and stability.
+* New asynchronous APIs (using `asyncio`) for send, receive and message handling.
+* Support for message and session auto lock renewal via background thread or async operation.
+* Now supports scheduled message cancellation.
+
+
 0.21.1 (2017-04-27)
-+++++++++++++++++++
+-------------------
 
 This wheel package is now built with the azure wheel extension
 
@@ -53,4 +73,4 @@ This wheel package is now built with the azure wheel extension
 
 Initial release of this package, from the split of the `azure` package.
 See the `azure` package release note for 1.0.0 for details and previous
-history on service bus.
+history on Service Bus.
diff --git a/azure-servicebus/MANIFEST.in b/azure-servicebus/MANIFEST.in
@@ -1,2 +1,2 @@
 include *.rst
-include azure_bdist_wheel.py
+include azure/__init__.py
diff --git a/azure-servicebus/README.rst b/azure-servicebus/README.rst
@@ -1,222 +1,87 @@
-Microsoft Azure SDK for Python
-==============================
+Microsoft Azure Service Bus SDK for Python
+==========================================
 
-This is the Microsoft Azure Service Bus Runtime Client Library.
+This is the Microsoft Azure Service Bus Client Library.
+This package has been tested with Python 2.7, 3.4, 3.5, 3.6 and 3.7.
 
-This package has been tested with Python 2.7, 3.3, 3.4 and 3.5.
+Microsoft Azure Service Bus supports a set of cloud-based, message-oriented middleware technologies including reliable message queuing and durable publish/subscribe messaging.
 
-For a more complete set of Azure libraries, see the `azure <https://pypi.python.org/pypi/azure>`__ bundle package.
+* `SDK source code <https://github.com/Azure/azure-sdk-for-python/tree/master/azure-servicebus>`__
+* `SDK reference documentation <https://docs.microsoft.com/python/api/overview/azure/servicebus/client?view=azure-python>`__
+* `Service Bus documentation <https://docs.microsoft.com/azure/service-bus-messaging/>`__
 
 
-Compatibility
-=============
+What's new in v0.50.0?
+----------------------
 
-**IMPORTANT**: If you have an earlier version of the azure package
-(version < 1.0), you should uninstall it before installing this package.
+As of version 0.50.0 a new AMQP-based API is available for sending and receiving messages. This update involves **breaking changes**.
+Please read `Migration from 0.21.1 to 0.50.0 <#migration-from-0211-to-0500>`__ to determine if upgrading is
+right for you at this time.
 
-You can check the version using pip:
+The new AMQP-based API offers improved message passing reliability, performance and expanded feature support going forward.
+The new API also offers support for asynchronous operations (based on asyncio) for sending, receiving and handling messages.
 
-.. code:: shell
-
-    pip freeze
-
-If you see azure==0.11.0 (or any version below 1.0), uninstall it first:
-
-.. code:: shell
+For documentation on the legacy HTTP-based operations please see `Using HTTP-based operations of the legacy API <https://docs.microsoft.com/python/api/overview/azure/servicebus?view=azure-python#using-http-based-operations-of-the-legacy-api>`__.
 
-    pip uninstall azure
 
+Prerequisites
+-------------
 
-Features
-========
-
--  Queues: create, list and delete queues; create, list, and delete subscriptions; send, receive, unlock and delete messages
--  Topics: create, list, and delete topics; create, list, and delete rules
--  Event Hubs: create and delete event hubs; send events
+* Azure subscription - `Create a free account <https://azure.microsoft.com/free/>`__
+* Azure Service Bus `namespace and management credentials <https://docs.microsoft.com/azure/service-bus-messaging/service-bus-create-namespace-portal>`__
 
 
 Installation
-============
-
-Download Package
-----------------
-
-To install via the Python Package Index (PyPI), type:
+------------
 
 .. code:: shell
 
     pip install azure-servicebus
 
 
-Download Source Code
---------------------
-
-To get the source code of the SDK via **git** type:
-
-.. code:: shell
-
-    git clone https://github.com/Azure/azure-sdk-for-python.git
-    cd azure-sdk-for-python
-    cd azure-servicebus
-    python setup.py install
+Migration from 0.21.1 to 0.50.0
+-------------------------------
 
+Major breaking changes were introduced in version 0.50.0.
+The original HTTP-based API is still available in v0.50.0 - however it now exists under a new namesapce: `azure.servicebus.control_client`.
 
-Usage
-=====
 
-ServiceBus Queues
------------------
+Should I upgrade?
++++++++++++++++++
 
-ServiceBus Queues are an alternative to Storage Queues that might be
-useful in scenarios where more advanced messaging features are needed
-(larger message sizes, message ordering, single-operation destructive
-reads, scheduled delivery) using push-style delivery (using long
-polling).
+The new package (v0.50.0) offers no improvements in HTTP-based operations over v0.21.1. The HTTP-based API is identical except that it now
+exists under a new namespace. For this reason if you only wish to use HTTP-based operations (`create_queue`, `delete_queue` etc) - there will be
+no additional benefit in upgrading at this time.
 
-The service can use Shared Access Signature authentication, or ACS
-authentication.
 
-Service bus namespaces created using the Azure portal after August 2014
-no longer support ACS authentication. You can create ACS compatible
-namespaces with the Azure SDK.
+How do I migrate my code to the new version?
+++++++++++++++++++++++++++++++++++++++++++++
 
-Shared Access Signature Authentication
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To use Shared Access Signature authentication, create the service bus
-service with:
+Code written against v0.21.0 can be ported to version 0.50.0 by simply changing the import namespace:
 
 .. code:: python
 
-    from azure.servicebus import ServiceBusService
+    # from azure.servicebus import ServiceBusService  <- This will now raise an ImportError
+    from azure.servicebus.control_client import ServiceBusService
 
     key_name = 'RootManageSharedAccessKey' # SharedAccessKeyName from Azure portal
-    key_value = '' # SharedAccessKey from Azure portal
+    key_value = ''  # SharedAccessKey from Azure portal
     sbs = ServiceBusService(service_namespace,
                             shared_access_key_name=key_name,
                             shared_access_key_value=key_value)
 
-ACS Authentication
-~~~~~~~~~~~~~~~~~~
-
-To use ACS authentication, create the service bus service with:
-
-.. code:: python
-
-    from azure.servicebus import ServiceBusService
-
-    account_key = '' # DEFAULT KEY from Azure portal
-    issuer = 'owner' # DEFAULT ISSUER from Azure portal
-    sbs = ServiceBusService(service_namespace,
-                            account_key=account_key,
-                            issuer=issuer)
-
-Sending and Receiving Messages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The **create\_queue** method can be used to ensure a queue exists:
-
-.. code:: python
-
-    sbs.create_queue('taskqueue')
-
-The **send\_queue\_message** method can then be called to insert the
-message into the queue:
-
-.. code:: python
-
-    from azure.servicebus import Message
-
-    msg = Message('Hello World!')
-    sbs.send_queue_message('taskqueue', msg)
-
-It is then possible to call the **receive\_queue\_message** method to
-dequeue the message.
-
-.. code:: python
-
-    msg = sbs.receive_queue_message('taskqueue')
 
-ServiceBus Topics
------------------
-
-ServiceBus topics are an abstraction on top of ServiceBus Queues that
-make pub/sub scenarios easy to implement.
-
-The **create\_topic** method can be used to create a server-side topic:
-
-.. code:: python
-
-    sbs.create_topic('taskdiscussion')
-
-The **send\_topic\_message** method can be used to send a message to a
-topic:
-
-.. code:: python
-
-    from azure.servicebus import Message
-
-    msg = Message('Hello World!')
-    sbs.send_topic_message('taskdiscussion', msg)
-
-A client can then create a subscription and start consuming messages by
-calling the **create\_subscription** method followed by the
-**receive\_subscription\_message** method. Please note that any messages
-sent before the subscription is created will not be received.
-
-.. code:: python
-
-    from azure.servicebus import Message
-
-    sbs.create_subscription('taskdiscussion', 'client1')
-    msg = Message('Hello World!')
-    sbs.send_topic_message('taskdiscussion', msg)
-    msg = sbs.receive_subscription_message('taskdiscussion', 'client1')
-
-Event Hub
----------
-
-Event Hubs enable the collection of event streams at high throughput, from
-a diverse set of devices and services.
-
-The **create\_event\_hub** method can be used to create an event hub:
-
-.. code:: python
-
-    sbs.create_event_hub('myhub')
-
-To send an event:
-
-.. code:: python
-
-    sbs.send_event('myhub', '{ "DeviceId":"dev-01", "Temperature":"37.0" }')
-
-The event content is the event message or JSON-encoded string that contains multiple messages.
-
-
-Need Help?
-==========
-
-Be sure to check out the Microsoft Azure `Developer Forums on Stack
-Overflow <http://go.microsoft.com/fwlink/?LinkId=234489>`__ if you have
-trouble with the provided code.
+Usage
+=====
 
+For reference documentation and code snippets see `Service Bus
+<https://docs.microsoft.com/python/api/overview/azure/servicebus>`__
+on docs.microsoft.com.
 
-Contribute Code or Provide Feedback
-===================================
 
-If you would like to become an active contributor to this project please
-follow the instructions provided in `Microsoft Azure Projects
-Contribution
-Guidelines <http://azure.github.io/guidelines.html>`__.
+Provide Feedback
+================
 
-If you encounter any bugs with the library please file an issue in the
+If you encounter any bugs or have suggestions, please file an issue in the
 `Issues <https://github.com/Azure/azure-sdk-for-python/issues>`__
 section of the project.
-
-
-Learn More
-==========
-
-`Microsoft Azure Python Developer
-Center <http://azure.microsoft.com/en-us/develop/python/>`__
diff --git a/azure-servicebus/azure/__init__.py b/azure-servicebus/azure/__init__.py
@@ -1 +1 @@
-__path__ = __import__('pkgutil').extend_path(__path__, __name__)
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		__path__ = __import__('pkgutil').extend_path(__path__, __name__)
		__path__ = __import__('pkgutil').extend_path(__path__, __name__)