[ServiceBus] Track2 Preview1

sdk/servicebus/azure-mgmt-servicebus/dev_requirements.txt

@@ -1,2 +1,2 @@
 -e ../../../tools/azure-sdk-tools
--e ../../../tools/azure-devtools
+-e ../../../tools/azure-devtools

sdk/servicebus/azure-servicebus/CHANGELOG.md

@@ -1,8 +1,58 @@
 # Release History
 
-## 0.50.2 (2019-12-9)
+## 7.0.0b1 (2020-04-03)
 
-**Features**
+Version 7.0.0b1 is a preview of our efforts to create a client library that is user friendly and idiomatic to the Python ecosystem. The reasons for most of the changes in this update can be found in the Azure SDK Design Guidelines for Python. For more information, please visit https://aka.ms/azure-sdk-preview1-python.
+* Note: Not all historical functionality exists in this version at this point.  Topics, Subscriptions, scheduling, dead_letter management and more will be added incrementally over upcoming preview releases.
+
+**New Features**
+
+* Added new configuration parameters when creating `ServiceBusClient`.
+    * `credential`: The credential object used for authentication which implements `TokenCredential` interface of getting tokens.
+    * `http_proxy`: A dictionary populated with proxy settings.  
+    * For detailed information about configuration parameters, please see docstring in `ServiceBusClient` and/or the reference documentation for more information.
+* Added support for authentication using Azure Identity credentials.
+* Added support for retry policy.
+* Added support for http proxy.
+* Manually calling `reconnect` should no longer be necessary, it is now performed implicitly.
+* Manually calling `open` should no longer be necessary, it is now performed implicitly.
+    * Note: `close()`-ing is still required if a context manager is not used, to avoid leaking connections.
+* Added support for sending a batch of messages destined for heterogenous sessions.
+
+**Breaking changes**
+
+* Simplified API and set of clients
+    * `get_queue` no longer exists, utilize `get_queue_sender/receiver` instead.
+    * `peek` and other `queue_client` functions have moved to their respective sender/receiver.
+    * Renamed `fetch_next` to `receive`.
+    * `reconnect` no longer exists, and is performed implicitly if needed.
+    * `open` no longer exists, and is performed implicitly if needed.
+* Normalized top level client parameters with idiomatic and consistent naming.
+    * Renamed `debug` in `ServiceBusClient` initializer to `logging_enable`.
+    * Renamed `service_namespace` in `ServiceBusClient` initializer to `fully_qualified_namespace`.
+* New error hierarchy, with more specific semantics
+    * `azure.servicebus.exceptions.ServiceBusError`
+    * `azure.servicebus.exceptions.ServiceBusConnectionError`
+    * `azure.servicebus.exceptions.ServiceBusResourceNotFound`
+    * `azure.servicebus.exceptions.ServiceBusAuthorizationError`
+    * `azure.servicebus.exceptions.NoActiveSession`
+    * `azure.servicebus.exceptions.OperationTimeoutError`
+    * `azure.servicebus.exceptions.InvalidHandlerState`
+    * `azure.servicebus.exceptions.AutoLockRenewTimeout`
+    * `azure.servicebus.exceptions.AutoLockRenewFailed`
+    * `azure.servicebus.exceptions.EventDataSendError`
+    * `azure.servicebus.exceptions.MessageSendFailed`
+    * `azure.servicebus.exceptions.MessageLockExpired`
+    * `azure.servicebus.exceptions.MessageSettleFailed`
+    * `azure.servicebus.exceptions.MessageAlreadySettled`
+    * `azure.servicebus.exceptions.SessionLockExpired`
+* Session is now set on the message itself, via `session_id` parameter or property, as opposed to on `Send` or `get_sender` via `session`.  This is to allow sending a batch of messages destined to varied sessions.
+* Session management is now encapsulated within a property of a receiver, e.g. `receiver.session`, to better compartmentalize functionality specific to sessions.
+    * To use `AutoLockRenew` against sessions, one would simply pass the inner session object, instead of the receiver itself.
+
+## 0.50.2 (2019-12-09)
+
+**New Features**
 
 * Added support for delivery tag lock tokens
 
@@ -29,7 +79,7 @@
 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 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.
@@ -43,7 +93,7 @@ This wheel package is now built with the azure wheel extension
 
 ## 0.21.0 (2017-01-13)
 
-**Features**
+**New Features**
 
 * `str` messages are now accepted in Python 3 and will be encoded in 'utf-8' (will not raise TypeError anymore)
 * `broker_properties` can now be defined as a dict, and not only a JSON `str`. datetime, int, float and boolean are converted.

sdk/servicebus/azure-servicebus/README.md

@@ -1,78 +1,197 @@
-# Microsoft Azure Service Bus SDK for Python
+# Azure Service Bus client library for Python
 
-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.
+Azure Service Bus is a high performance cloud-managed messaging service for providing real-time and fault-tolerant communication between distributed senders and receivers.
 
-Microsoft Azure Service Bus supports a set of cloud-based, message-oriented middleware technologies including reliable message queuing and durable publish/subscribe messaging.
+Service Bus provides multiple mechanisms for asynchronous highly reliable communication, such as structured first-in-first-out messaging, 
+publish/subscribe capabilities, and the ability to easily scale as your needs grow.
 
-* [SDK source code](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/servicebus/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/)
+Use the Service Bus client library for Python to communicate between applications and services and implement asynchronous messaging patterns.
 
+* Create Service Bus namespaces, queues, topics, and subscriptions, and modify their settings
+* Send and receive messages within your Service Bus channels.
+* Utilize message locks, sessions, and dead letter functionality to implement complex messaging patterns.
 
-## What's new in v0.50.2?
+[Source code](./) | [Package (PyPi)][pypi] | [API reference documentation][api_docs] | [Product documentation][product_docs] | [Samples](./samples) | [Changelog](./CHANGELOG.md)
 
-As of version 0.50.2 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.2](#migration-from-0211-to-0502) to determine if upgrading is
-right for you at this time.
+## Getting started
 
-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.
+### Install the package
 
-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).
+Install the Azure Service Bus client library for Python with [pip][pip]:
 
+```Bash
+pip install azure-servicebus --pre
+```
+
+### Prerequisites: 
+To use this package, you must have:
+* Azure subscription - [Create a free account][azure_sub]
+* Azure Service Bus - [Namespace and management credentials][service_bus_namespace]
+* Python 2.7, 3.5, 3.6, 3.7 or 3.8 - [Install Python][python]
+
+
+If you need an Azure service bus namespace, you can create it via the [Azure Portal][azure_namespace_creation].
+If you do not wish to use the graphical portal UI, you can use the Azure CLI via [Cloud Shell][cloud_shell_bash], or Azure CLI run locally, to create one with this Azure CLI command:
+
+```Bash
+az servicebus namespace create --resource-group <resource-group-name> --name <servicebus-namespace-name> --location <servicebus-namespace-location>
+```
+
+### Authenticate the client
+
+Interaction with Service Bus starts with an instance of the `ServiceBusClient` class. You either need a **connection string with SAS key**, or a **namespace** and one of its **account keys** to instantiate the client object.
+
+#### Get credentials
+
+Use the [Azure CLI][azure_cli] snippet below to populate an environment variable with the service bus connection string (you can also find these values in the [Azure portal][azure_portal]. The snippet is formatted for the Bash shell.
+
+```Bash
+RES_GROUP=<resource-group-name>
+NAMESPACE_NAME=<servicebus-namespace-name>
+
+export SERVICE_BUS_CONN_STR=$(az servicebus namespace authorization-rule keys list --resource-group $RES_GROUP --namespace-name $NAMESPACE_NAME --query RootManageSharedAccessKey --output tsv)
+```
+
+#### Create client
+
+Once you've populated the `SERVICE_BUS_CONN_STR` environment variable, you can create the `ServiceBusClient`.
+
+```Python
+from azure.servicebus import ServiceBusClient
+
+import os
+connstr = os.environ['SERVICE_BUS_CONN_STR']
+
+with ServiceBusClient.from_connection_string(connstr) as client:
+    ...
+```
 
-## Prerequisites
+Note: client can be initialized without a context manager, but must be manually closed via client.close() to not leak resources.
 
-* 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)
+## Key concepts
 
+Once you've initialized a `ServiceBusClient`, you can interact with the primary resource types within a Service Bus Namespace, of which multiple can exist and on which actual message transmission takes place, the namespace often serving as an application container:
 
-## Installation
+* [Queue][queue_concept]: Allows for Sending and Receiving of messages, ordered first-in-first-out.  Often used for point-to-point communication.
 
-```shell
-pip install azure-servicebus
+* [Topic][topic_concept]: As opposed to Queues, Topics are better suited to publish/subscribe scenarios.  A topic can be sent to, but requires a subscription, of which there can be multiple in parallel, to consume from.
+
+* [Subscription][subscription_concept]: The mechanism to consume from a Topic.  Each subscription is independent, and receaves a copy of each message sent to the topic.  Rules and Filters can be used to tailor which messages are received by a specific subscription.
+
+For more information about these resources, see [What is Azure Service Bus?][service_bus_overview].
+
+## Examples
+
+The following sections provide several code snippets covering some of the most common Service Bus tasks, including:
+
+* [Send a message to a queue](#send-to-a-queue)
+* [Receive a message from a queue](#receive-from-a-queue)
+* [Defer a message on receipt](#defer-a-message)
+
+
+### Send to a queue
+
+This example sends a message to a queue that is assumed to already exist, created via the Azure portal or az commands.
+
+```Python
+from azure.servicebus import ServiceBusClient
+
+import os
+connstr = os.environ['SERVICE_BUS_CONN_STR']
+
+with ServiceBusClient.from_connection_string(connstr) as client:
+    with client.get_queue_sender(queue_name):
+
+        message = Message("Single message")
+        queue_sender.send(message)
 ```
 
-## Migration from 0.21.1 to 0.50.2
+### Receive from a queue
 
-Major breaking changes were introduced in version 0.50.2.
-The original HTTP-based API is still available in v0.50.2 - however it now exists under a new namesapce: `azure.servicebus.control_client`.
+To receive from a queue, you can either perform a one-off receive via "receiver.receive()" or receive persistently as follows:
 
-### Should I upgrade?
+```Python
+from azure.servicebus import ServiceBusClient
 
-The new package (v0.50.2) 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.
+import os
+connstr = os.environ['SERVICE_BUS_CONN_STR']
 
+with ServiceBusClient.from_connection_string(connstr) as client:
+    with client.get_queue_receiver(queue_name) as receiver:
+        for msg in receiver:
+            print(str(msg))
+            msg.complete()
+```
 
-### How do I migrate my code to the new version?
+### Defer a message
 
-Code written against v0.21.0 can be ported to version 0.50.2 by simply changing the import namespace:
+When receiving from a queue, you have multiple actions you can take on the messages you receive.  Where the prior example completes a message,
+permanently removing it from the queue and marking as complete, this example demonstrates how to defer the message, sending it back to the queue
+such that it must now be received via sequence number:
 
-```python
-# from azure.servicebus import ServiceBusService  <- This will now raise an ImportError
-from azure.servicebus.control_client import ServiceBusService
+```Python
+from azure.servicebus import ServiceBusClient
 
-key_name = 'RootManageSharedAccessKey' # SharedAccessKeyName 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)
+import os
+connstr = os.environ['SERVICE_BUS_CONN_STR']
+
+with ServiceBusClient.from_connection_string(connstr) as client:
+    with client.get_queue_receiver(queue_name) as receiver:
+        for msg in receiver:
+            print(str(msg))
+            msg.defer()
 ```
 
+## Troubleshooting
+
+### Logging
+
+- Enable `azure.servicebus` logger to collect traces from the library.
+- Enable `uamqp` logger to collect traces from the underlying uAMQP library.
+- Enable AMQP frame level trace by setting `logging_enable=True` when creating the client.
+
+## Next steps
+
+### More sample code
+
+Please find further examples in the [samples](./samples) directory demonstrating common Service Bus scenarios such as sending, receiving, and message handling.
 
-# Usage
+### Additional documentation
 
-For reference documentation and code snippets see [Service Bus](https://docs.microsoft.com/python/api/overview/azure/servicebus)
-on docs.microsoft.com.
+For more extensive documentation on the Service Bus service, see the [Service Bus DB documentation][service_bus_docs] on docs.microsoft.com.
 
+## Contributing
 
-# Provide Feedback
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.microsoft.com.
 
-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.
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
 
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
 
-![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fazure-servicebus%2FREADME.png)
+<!-- LINKS -->
+[azure_cli]: https://docs.microsoft.com/cli/azure
+[api_docs]: https://docs.microsoft.com/python/api/overview/azure/servicebus/client?view=azure-python
+[product_docs]: https://docs.microsoft.com/azure/service-bus-messaging/
+[azure_portal]: https://portal.azure.com
+[azure_sub]: https://azure.microsoft.com/free/
+[cloud_shell]: https://docs.microsoft.com/azure/cloud-shell/overview
+[cloud_shell_bash]: https://shell.azure.com/bash
+[pip]: https://pypi.org/project/pip/
+[pypi]: https://pypi.org/project/azure-servicebus/
+[python]: https://www.python.org/downloads/
+[venv]: https://docs.python.org/3/library/venv.html
+[virtualenv]: https://virtualenv.pypa.io
+[service_bus_namespace]: https://docs.microsoft.com/azure/service-bus-messaging/service-bus-create-namespace-portal
+[service_bus_overview]: https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messaging-overview
+[queue_status_codes]: https://docs.microsoft.com/rest/api/servicebus/create-queue#response-codes
+[service_bus_docs]: https://docs.microsoft.com/azure/service-bus/
+[queue_concept]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview#queues
+[topic_concept]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview#topics
+[subscription_concept]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#topics-and-subscriptions
+[azure_namespace_creation]: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-create-namespace-portal

sdk/servicebus/azure-servicebus/azure/servicebus/__init__.py

@@ -3,16 +3,19 @@
 # Licensed under the MIT License. See License.txt in the project root for
 # license information.
 # -------------------------------------------------------------------------
+from uamqp import constants
 
 from ._version import VERSION
 __version__ = VERSION
 
-
-from azure.servicebus.common.message import Message, BatchMessage, PeekMessage, DeferredMessage
-from azure.servicebus.servicebus_client import ServiceBusClient, QueueClient, TopicClient, SubscriptionClient
-from azure.servicebus.common.constants import ReceiveSettleMode, NEXT_AVAILABLE
-from azure.servicebus.common.utils import AutoLockRenew
-from azure.servicebus.common.errors import (
+from ._servicebus_client import ServiceBusClient
+from ._servicebus_sender import ServiceBusSender
+from ._servicebus_receiver import ServiceBusReceiver, ServiceBusSession
+from ._base_handler import ServiceBusSharedKeyCredential
+from ._common.message import Message, BatchMessage, PeekMessage, ReceivedMessage
+from ._common.constants import ReceiveSettleMode, NEXT_AVAILABLE
+from ._common.utils import AutoLockRenew
+from .exceptions import (
     ServiceBusError,
     ServiceBusResourceNotFound,
     ServiceBusConnectionError,
@@ -25,21 +28,16 @@
     MessageLockExpired,
     SessionLockExpired,
     AutoLockRenewFailed,
-    AutoLockRenewTimeout)
+    AutoLockRenewTimeout,)
 
-from uamqp.constants import TransportType
 
+TransportType = constants.TransportType
 
 __all__ = [
     'Message',
     'BatchMessage',
     'PeekMessage',
-    'AutoLockRenew',
-    'DeferredMessage',
-    'ServiceBusClient',
-    'QueueClient',
-    'TopicClient',
-    'SubscriptionClient',
+    'ReceivedMessage',
     'ReceiveSettleMode',
     'NEXT_AVAILABLE',
     'ServiceBusError',
@@ -55,4 +53,11 @@
     'SessionLockExpired',
     'AutoLockRenewFailed',
     'AutoLockRenewTimeout',
-    'TransportType']
+    'ServiceBusClient',
+    'ServiceBusReceiver',
+    'ServiceBusSender',
+    'ServiceBusSharedKeyCredential',
+    'TransportType',
+    'AutoLockRenew',
+    'ServiceBusSession'
+]