[ServiceBus] Clean up README prior to P6 with doc-owner recommendatio…

…ns. (Azure#13511)

* Remove long-form samples from readme authentication section and move them into formal samples with URIs. (This by recommendation of docs folks, and supported via UX interview with user stating that the README was getting long in the teeth with this section being less critical)

sdk/servicebus/azure-servicebus/README.md

@@ -47,43 +47,13 @@ az servicebus namespace create --resource-group <resource-group-name> --name <se
 ### 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.
+Please find the samples linked below for demonstration as to how to authenticate via either approach.
 
-#### Create client from connection string
+#### [Create client from connection string][sample_authenticate_client_connstr]
 
-- 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] by following the step-by-step guide to [Get a service bus connection string][get_servicebus_conn_str]). The snippet is formatted for the Bash shell.
+- To obtain the required credentials, one can use the [Azure CLI][azure_cli] snippet (Formatted for Bash Shell) at the top of the linked sample to populate an environment variable with the service bus connection string (you can also find these values in the [Azure Portal][azure_portal] by following the step-by-step guide to [Get a service bus connection string][get_servicebus_conn_str]).
 
-```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 --name RootManageSharedAccessKey --query primaryConnectionString --output tsv)
-```
-
-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:
-    ...
-```
-
-#### Create client using the azure-identity library:
-
-```python
-import os
-from azure.servicebus import ServiceBusClient
-from azure.identity import DefaultAzureCredential
-
-credential = DefaultAzureCredential()
-
-FULLY_QUALIFIED_NAMESPACE = os.environ['SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE']
-with ServiceBusClient(FULLY_QUALIFIED_NAMESPACE, credential):
-    ...
-```
+#### [Create client using the azure-identity library][sample_authenticate_client_aad]:
 
 - This constructor takes the fully qualified namespace of your Service Bus instance and a credential that implements the
 [TokenCredential][token_credential_interface]
@@ -93,7 +63,7 @@ protocol. There are implementations of the `TokenCredential` protocol available
 Azure Service Bus Data Owner role. For more information about using Azure Active Directory authorization with Service Bus,
 please refer to [the associated documentation][servicebus_aad_authentication].
 
-Note: client can be initialized without a context manager, but must be manually closed via client.close() to not leak resources.
+>**Note:** client can be initialized without a context manager, but must be manually closed via client.close() to not leak resources.
 
 ## Key concepts
 
@@ -126,6 +96,7 @@ The following sections provide several code snippets covering some of the most c
 * [Send and receive a message from a session enabled queue](#send-and-receive-a-message-from-a-session-enabled-queue)
 * [Working with topics and subscriptions](#working-with-topics-and-subscriptions)
 * [Settle a message after receipt](#settle-a-message-after-receipt)
+* [Automatically renew Message or Session locks](#automatically-renew-message-or-session-locks)
 
 To perform management tasks such as creating and deleting queues/topics/subscriptions, please utilize the azure-mgmt-servicebus library, available [here][servicebus_management_repository].
 
@@ -346,27 +317,7 @@ with ServiceBusClient.from_connection_string(connstr) as client:
             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.
-
-### Timeouts
-
-There are various timeouts a user should be aware of within the library.
-- 10 minute service side link closure:  A link, once opened, will be closed after 10 minutes idle to protect the service against resource leakage.  This should largely
-be transparent to a user, but if you notice a reconnect occurring after such a duration, this is why.  Performing any operations, including management operations, on the
-link will extend this timeout.
-- max_wait_time: Provided on creation of a receiver or when calling `receive_messages()` or `get_streaming_message_iter()`, the time after which receiving messages will halt after no traffic.  This applies both to the imperative `receive_messages()` function as well as the length
-a generator-style receive will run for before exiting if there are no messages.  Passing None (default) will wait forever, up until the 10 minute threshold if no other action is taken.
-
-> **NOTE:** If processing of a message or session is sufficiently long as to cause timeouts, as an alternative to calling `renew_lock()` manually, one can
-> leverage the `AutoLockRenew` functionality detailed below.
-
-### [AutoLockRenew][autolockrenew_reference]
+### [Automatically renew Message or Session locks][autolockrenew_reference]
 
 `AutoLockRenew` is a simple method for ensuring your message or session remains locked even over long periods of time, if calling `renew_lock()` is impractical or undesired.
 Internally, it is not much more than shorthand for creating a concurrent watchdog to call `renew_lock()` if the object is nearing expiry.
@@ -395,6 +346,26 @@ 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.
 It would also manifest when trying to take action (such as completing a message) on the specified object.
 
+## 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.
+
+### Timeouts
+
+There are various timeouts a user should be aware of within the library.
+- 10 minute service side link closure:  A link, once opened, will be closed after 10 minutes idle to protect the service against resource leakage.  This should largely
+be transparent to a user, but if you notice a reconnect occurring after such a duration, this is why.  Performing any operations, including management operations, on the
+link will extend this timeout.
+- max_wait_time: Provided on creation of a receiver or when calling `receive_messages()` or `get_streaming_message_iter()`, the time after which receiving messages will halt after no traffic.  This applies both to the imperative `receive_messages()` function as well as the length
+a generator-style receive will run for before exiting if there are no messages.  Passing None (default) will wait forever, up until the 10 minute threshold if no other action is taken.
+
+> **NOTE:** If processing of a message or session is sufficiently long as to cause timeouts, as an alternative to calling `renew_lock()` manually, one can
+> leverage the `AutoLockRenew` functionality detailed [above](#automatically-renew-message-or-session-locks).
+
 ### Common Exceptions
 
 Please view the [exceptions reference docs][exception_reference] for detailed descriptions of our common Exception types.
@@ -473,6 +444,8 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
 [exception_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html#module-azure.servicebus.exceptions
 [subscription_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.aio.html?highlight=subscription#azure.servicebus.aio.ServiceBusClient.get_subscription_receiver
 [topic_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/latest/azure.servicebus.html?highlight=topic#azure.servicebus.ServiceBusClient.get_topic_sender
+[sample_authenticate_client_connstr]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/servicebus/azure-servicebus/samples/sync_samples/authenticate_client_connstr.py
+[sample_authenticate_client_aad]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/servicebus/azure-servicebus/samples/sync_samples/client_identity_authentication.py
 [0_50_source]: https://github.com/Azure/azure-sdk-for-python/tree/servicebus_v0.50.3/sdk/servicebus/azure-servicebus/
 [0_50_pypi]: https://pypi.org/project/azure-servicebus/0.50.3/
 [0_50_api_docs]:https://azuresdkdocs.blob.core.windows.net/$web/python/azure-servicebus/0.50.3/index.html

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

@@ -49,6 +49,8 @@ Both [sync version](./sync_samples) and [async version](./async_samples) of samp
     - Cancel scheduled messages from a topic
 - [client_identity_authentication.py](./sync_samples/client_identity_authentication.py) ([async_version](./async_samples/client_identity_authentication_async.py)) - Examples to authenticate the client by Azure Activate Directory
     - Authenticate and create the client utilizing the `azure.identity` library
+- [authenticate_client_connstr.py](./sync_samples/authenticate_client_connstr.py) ([async_version](./async_samples/authenticate_client_connstr_async.py)) - Examples to authenticate the client by Connection String
+    - Authenticate and create the client utilizing the connection string available in the Azure portal or via Azure CLI.
 - [proxy.py](./sync_samples/proxy.py) ([async_version](./async_samples/proxy_async.py)) - Examples to send message behind a proxy:
     - Send message behind a proxy
 - [auto_lock_renew.py](./sync_samples/auto_lock_renew.py) ([async_version](./async_samples/auto_lock_renew_async.py)) - Examples to show usage of AutoLockRenew:

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

@@ -0,0 +1,36 @@
+#!/usr/bin/env python
+
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+"""
+Example to show connection-string based authentication of the ServiceBusClient.
+
+Note: To get credentials, one can either obtain the connection string from the Azure Portal,
+or use the Azure CLI snippet below to populate an environment variable with the service bus connection string. The following is in bash:
+
+```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 --name RootManageSharedAccessKey --query primaryConnectionString --output tsv)
+```
+"""
+
+# pylint: disable=C0111
+
+from azure.servicebus.aio import ServiceBusClient
+
+import os
+import asyncio
+
+connstr = os.environ['SERVICE_BUS_CONN_STR']
+
+async def run():
+    async with ServiceBusClient.from_connection_string(connstr) as client:
+        pass # Client is now initialized and can be used.
+
+loop = asyncio.get_event_loop()
+loop.run_until_complete(run())

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

@@ -0,0 +1,31 @@
+#!/usr/bin/env python
+
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+"""
+Example to show connection-string based authentication of the ServiceBusClient.
+
+Note: To get credentials, one can either obtain the connection string from the Azure Portal,
+or use the Azure CLI snippet below to populate an environment variable with the service bus connection string. The following is in bash:
+
+```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 --name RootManageSharedAccessKey --query primaryConnectionString --output tsv)
+```
+"""
+
+# pylint: disable=C0111
+
+from azure.servicebus import ServiceBusClient
+
+import os
+connstr = os.environ['SERVICE_BUS_CONN_STR']
+
+with ServiceBusClient.from_connection_string(connstr) as client:
+    pass # Client is now initialized and can be used.
+