Make doc-owner recommended revisions to eventhub readme and samples. (#…

…13518)

Move auth samples into samples and link from readme rather than line.
Add snippets to the top of samples lacking any verbiage.
Whitespace improvements in client auth sample
Explicit samples for connstr auth to link from new terse readme auth section.

sdk/eventhub/azure-eventhub/README.md

@@ -39,43 +39,20 @@ $ pip install azure-eventhub
 
 Interaction with Event Hubs starts with an instance of EventHubConsumerClient or EventHubProducerClient class. You need either the host name, SAS/AAD credential and event hub name or a connection string to instantiate the client object.
 
-**Create client from connection string:**
+**[Create client from connection string:](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventhub/azure-eventhub/samples/sync_samples/connection_string_authentication.py)**
 
 For the Event Hubs client library to interact with an Event Hub, the easiest means is to use a connection string, which is created automatically when creating an Event Hubs namespace.
 If you aren't familiar with shared access policies in Azure, you may wish to follow the step-by-step guide to [get an Event Hubs connection string](https://docs.microsoft.com/azure/event-hubs/event-hubs-get-connection-string).
 
-
-```python
-from azure.eventhub import EventHubConsumerClient, EventHubProducerClient
-
-connection_str = '<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>'
-consumer_group = '<< CONSUMER GROUP >>'
-eventhub_name = '<< NAME OF THE EVENT HUB >>'
-producer_client = EventHubProducerClient.from_connection_string(connection_str, eventhub_name=eventhub_name)
-consumer_client = EventHubConsumerClient.from_connection_string(connection_str, consumer_group, eventhub_name=eventhub_name)
-
-```
-
 - The `from_connection_string` method takes the connection string of the form
 `Endpoint=sb://<yournamespace>.servicebus.windows.net/;SharedAccessKeyName=<yoursharedaccesskeyname>;SharedAccessKey=<yoursharedaccesskey>` and
 entity name to your Event Hub instance. You can get the connection string from the [Azure portal](https://docs.microsoft.com/azure/event-hubs/event-hubs-get-connection-string#get-connection-string-from-the-portal).
 
-**Create client using the azure-identity library:**
+**[Create client using the azure-identity library:](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/eventhub/azure-eventhub/samples/sync_samples/client_identity_authentication.py)**
 
-```python
-from azure.eventhub import EventHubConsumerClient
-from azure.identity import DefaultAzureCredential
+Alternately, one can use a Credential object to authenticate via AAD with the azure-identity package.
 
-credential = DefaultAzureCredential()
-
-fully_qualified_namespace = '<< HOSTNAME OF THE EVENT HUB >>'
-eventhub_name = '<< NAME OF THE EVENT HUB >>'
-consumer_group = '<< CONSUMER GROUP >>'
-consumer_client = EventHubConsumerClient(fully_qualified_namespace, eventhub_name, consumer_group, credential)
-
-```
-
-- This constructor takes the host name and entity name of your Event Hub instance and credential that implements the
+- This constructor demonstrated in the sample linked above takes the host name and entity name of your Event Hub instance and credential that implements the
 [TokenCredential](../../core/azure-core/azure/core/credentials.py)
 protocol. There are implementations of the `TokenCredential` protocol available in the
 [azure-identity package](https://pypi.org/project/azure-identity/). The host name is of the format `<yournamespace.servicebus.windows.net>`.
@@ -160,6 +137,9 @@ with client:
 
 ### Consume events from an Event Hub
 
+There are multiple ways to consume events from an EventHub.  To simply trigger a callback when an event is received,
+the `EventHubConsumerClient.receive` method will be of use as follows:
+
 ```python
 import logging
 from azure.eventhub import EventHubConsumerClient
@@ -187,6 +167,9 @@ with client:
 
 ### Consume events from an Event Hub in batches
 
+Whereas the above sample triggers the callback for each message as it is received, the following sample
+triggers the callback on a batch of events, attempting to receive a number at a time.
+
 ```python
 import logging
 from azure.eventhub import EventHubConsumerClient
@@ -248,6 +231,9 @@ if __name__ == '__main__':
 
 ### Consume events from an Event Hub asynchronously
 
+This SDK supports both synchronous and asyncio based code.  To receive as demonstrated in the samples above, but within
+aio, one would need the following:
+
 ```python
 import logging
 import asyncio
@@ -281,6 +267,9 @@ if __name__ == '__main__':
 
 ### Consume events from an Event Hub in batches asynchronously
 
+All synchronous functions are supported in aio as well.  As demonstrated above for synchronous batch receipt, one can accomplish
+the same within asyncio as follows:
+
 ```python
 import logging
 import asyncio

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

@@ -55,13 +55,16 @@ Both [sync version](https://github.com/Azure/azure-sdk-for-python/tree/master/sd
 - [client_identity_authentication.py](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/sync_samples/client_identity_authentication.py) ([async version](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/async_samples/client_identity_authentication_async.py)) - Examples for authentication by Azure Active Directory:
     - Authenticating and creating the client utilizing the `azure.identity` library
 
+- [connection_string_authentication.py](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/sync_samples/connection_string_authentication.py) ([async version](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/async_samples/connection_string_authentication_async.py)) - Examples for authentication by connection string:
+    - Authenticating and creating the client utilizing a connection string.
+
 - [proxy.py](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/sync_samples/proxy.py) ([async version](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/async_samples/proxy_async.py)) - Examples to send and receive events behind a proxy:
     - Send and receive events behind a proxy
 
 - [iot_hub_connection_string_receive_async.py](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/async_samples/iot_hub_connection_string_receive_async.py) - Examples to receive events from an IoT Hub:
     - Convert an IoT Hub connection string to the built-in Event Hub endpoint and receive events from it
 
-- [authenticate_with_sas_token.py]<!--(https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/sync_samples/authenticate_with_sas_token.py)-->
+- [authenticate_with_sas_token.py](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/eventhub/azure-eventhub/samples/sync_samples/authenticate_with_sas_token.py)
     - Utilize a SAS token to authenticate when creating an Event Hub client.
 
 ## Prerequisites

sdk/eventhub/azure-eventhub/samples/async_samples/connection_string_authentication_async.py

@@ -0,0 +1,24 @@
+#!/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.
+# --------------------------------------------------------------------------------------------
+"""
+An example to show authentication using a connection string obtained via the Azure Portal, or the Azure CLI toolkit.
+"""
+
+import os
+from azure.eventhub.aio import EventHubConsumerClient
+
+CONNECTION_STR = os.environ["EVENT_HUB_CONN_STR"]
+EVENTHUB_NAME = os.environ['EVENT_HUB_NAME']
+
+consumer_client = EventHubConsumerClient.from_connection_string(
+    conn_str=CONNECTION_STR,
+    consumer_group='$Default',
+    eventhub_name=EVENTHUB_NAME,
+)
+
+async with consumer_client:
+    pass # consumer_client is now ready to be used.

sdk/eventhub/azure-eventhub/samples/sync_samples/client_identity_authentication.py

@@ -50,6 +50,7 @@
 # For example user to be logged in can be specified by the environment variable AZURE_USERNAME, consumed via the ManagedIdentityCredential
 # Alternately, one can specify the AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET to use the EnvironmentCredentialClass.
 # The docs above specify all mechanisms which the defaultCredential internally support.
+#
 # credential = DefaultAzureCredential()
 
 producer = EventHubProducerClient(fully_qualified_namespace=fully_qualified_namespace,

sdk/eventhub/azure-eventhub/samples/sync_samples/connection_string_authentication.py

@@ -0,0 +1,24 @@
+#!/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.
+# --------------------------------------------------------------------------------------------
+"""
+An example to show authentication using a connection string obtained via the Azure Portal, or the Azure CLI toolkit.
+"""
+
+import os
+from azure.eventhub import EventHubConsumerClient
+
+CONNECTION_STR = os.environ["EVENT_HUB_CONN_STR"]
+EVENTHUB_NAME = os.environ['EVENT_HUB_NAME']
+
+consumer_client = EventHubConsumerClient.from_connection_string(
+    conn_str=CONNECTION_STR,
+    consumer_group='$Default',
+    eventhub_name=EVENTHUB_NAME,
+)
+
+with consumer_client:
+    pass # consumer_client is now ready to be used.