Update readme for track 2 preview 1 release

sdk/servicebus/azure-servicebus/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Release History
 
+## 1.0.0b1 (2020-3-20)
+
+**Features**
+
+* Simplified API and set of clients
+* Support for Azure Identity
+* Support Sending and Receiving on queues
+
 ## 0.50.2 (2019-12-9)
 
 **Features**

sdk/servicebus/azure-servicebus/README.md

@@ -1,78 +1,170 @@
-# 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 and 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
 
-## Prerequisites
+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.
 
-* 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)
+#### 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.
 
-## Installation
+```Bash
+RES_GROUP=<resource-group-name>
+NAMESPACE_NAME=<servicebus-namespace-name>
 
-```shell
-pip install azure-servicebus
+export SERVICE_BUS_CONN_STR=$(az servicebus namespace authorization-rule keys list --resource-group $RES_GROUP --namespace-name $NAMESPACE_NAME --query RootManageSharedAccessKey --output tsv)
 ```
 
-## Migration from 0.21.1 to 0.50.2
+#### 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:
+    ...
+```
+
+Note: client can be initialized without a context manager, but must be manually closed via client.close() to not leak resources.
+
+## 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:
+
+* Queue: Allows for Sending and Receiving of messages, ordered first-in-first-out.  Often used for point-to-point communication.
 
-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`.
+* Topic: 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.
 
-### Should I upgrade?
+* Subscription: 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.
 
-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.
+For more information about these resources, see [What is Azure Service Bus?][service_bus_overview].
 
+## Examples
 
-### How do I migrate my code to the new version?
+The following sections provide several code snippets covering some of the most common Service Bus tasks, including:
 
-Code written against v0.21.0 can be ported to version 0.50.2 by simply changing the import namespace:
+* [Send a message to a queue](#send-to-a-queue)
+* [Receive a message from a queue](#receive-from-a-queue)
+* [Deadletter a message on receipt](#deadletter-a-message)
 
-```python
-# 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
-sbs = ServiceBusService(service_namespace,
-                        shared_access_key_name=key_name,
-                        shared_access_key_value=key_value)
+### 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
+with client.get_queue_sender(queue_name):
+
+    message = Message("Single message")
+    queue_sender.send(message)
+```
+
+### Receive from a queue
+
+To receive from a queue, you can either perform a one-off receive via "receiver.receive()" or receive persistently as follows:
+
+```Python
+with client.get_queue_receiver(queue_name) as receiver:
+    for msg in receiver:
+        print(str(msg))
+        msg.complete()
 ```
 
+### Deadletter a message
+
+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 send the message to the dead letter queue:
+
+```Python
+with client.get_queue_receiver(queue_name) as receiver:
+    for msg in receiver:
+        print(str(msg))
+        msg.dead_letter()
+```
+
+## 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.
+
+### Additional documentation
+
+For more extensive documentation on the Service Bus service, see the [Service Bus DB documentation][service_bus_docs] on docs.microsoft.com.
 
-# Usage
+### Logging
 
-For reference documentation and code snippets see [Service Bus](https://docs.microsoft.com/python/api/overview/azure/servicebus)
-on docs.microsoft.com.
+- 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.
 
+## 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 [[email protected]](mailto:[email protected]) 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/

sdk/servicebus/azure-servicebus/azure/servicebus/_version.py

@@ -3,4 +3,4 @@
 # Licensed under the MIT License.
 # ------------------------------------
 
-VERSION = '0.50.2'
+VERSION = '1.0.0b1'

sdk/servicebus/azure-servicebus/samples/README.md

@@ -13,7 +13,7 @@ urlFragment: servicebus-samples
 These are code samples that show common scenario operations with the Azure Service Bus client library.
 Both [sync version](./sync_sampes) and [async version](./async_samples) of samples are provided, async samples require Python 3.5 or later.
 
-- [topic_send.py](./sync_samples/topic_send.py) ([async version](./async_samples/topic_send_async.py)) - Examples to send messages on a service bus topic:
+- [send_queue.py](./sync_samples/send_queue.py) ([async version](./async_samples/send_queue_async.py)) - Examples to send messages on a service bus queue:
     - From a connection string
     - Enabling Logging
 
@@ -35,10 +35,7 @@ pip install azure-servicebus
 
 1. Open a terminal window and `cd` to the directory that the samples are saved in.
 2. Set the environment variables specified in the sample file you wish to run.
-3. Follow the usage described in the file, e.g. `python topic_send.py`.
-
-        Note: If the sample in question uses pytest (look for @livetest marks) please run via pytest specifying the test name, and have the servicebus credentials present in environment variables
-        as described in conftest.py.
+3. Follow the usage described in the file, e.g. `python send_queue.py`.
 
 ## Next steps
 

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

@@ -17,7 +17,7 @@
 CONNECTION_STR = os.environ['SERVICE_BUS_CONNECTION_STR']
 QUEUE_NAME = os.environ["SERVICE_BUS_QUEUE_NAME"]
 
-servicebus_client = ServiceBusClient.from_connection_string(conn_str=CONNECTION_STR)
+servicebus_client = ServiceBusClient.from_connection_string(conn_str=CONNECTION_STR, logging_enable=True)
 
 sender = servicebus_client.get_queue_sender(
     queue_name=QUEUE_NAME