[EventHub] Make doc-owner recommended revisions to eventhub readme and samples.

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.