[EventHubs] prep release (Azure#24089)

swathipil · web-flow · commit 6640da268ace · 2022-04-20T03:20:02.000Z
diff --git a/sdk/eventhub/azure-eventhub/CHANGELOG.md b/sdk/eventhub/azure-eventhub/CHANGELOG.md
@@ -1,13 +1,13 @@
 # Release History
 
-## 5.9.0b3 (Unreleased)
+## 5.9.0b3 (2022-04-20)
 
 ### Features Added
 
 - Introduced new method `send_event` to `EventHubProducerClient` which allows sending single `EventData` or `AmqpAnnotatedMessage`.
-- Introduced buffered mode sending to `EventHubProducerClient` which is intended to allow for efficient publishing of events 
+- Introduced buffered mode sending to `EventHubProducerClient` which is intended to allow for efficient publishing of events
  without having to explicitly manage batches in the application.
-  - The constructor of `EventHubProducerClient` and `from_connection_string` method now takes the following new keyword arguments 
+  - The constructor of `EventHubProducerClient` and `from_connection_string` method now takes the following new keyword arguments
    for configuration:
     - `buffered_mode`: The flag to enable/disable buffered mode sending.
     - `on_success`: The callback to be called once events have been successfully published.
@@ -541,13 +541,4 @@ Version 5.0.0b1 is a preview of our efforts to create a client library that is u
 - Further testing and minor bug fixes.
 
 
-## 0.2.0a2 (2018-04-02)
-
-- Updated uAQMP dependency.
-
-
-## 0.2.0a1 (unreleased)
-
-- Swapped out Proton dependency for uAMQP.
-
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python/sdk/eventhub/azure-eventhub/HISTORY.png)
diff --git a/sdk/eventhub/azure-eventhub/azure/eventhub/_producer_client.py b/sdk/eventhub/azure-eventhub/azure/eventhub/_producer_client.py
@@ -61,14 +61,18 @@ class EventHubProducerClient(ClientBase):   # pylint: disable=client-accepts-api
      It is required when `buffered_mode` is True while optional if `buffered_mode` is False.
     :paramtype on_success: Optional[Callable[[SendEventTypes, Optional[str]], None]]
     :keyword on_error: The callback to be called once a batch has failed to be published.
-     The callback takes three parameters:
+     The callback function should be defined like: `on_error(events, partition_id, error)`, where:
         - `events`: The list of events that failed to be published,
         - `partition_id`: The partition id that the events in the list have been tried to be published to and
         - `error`: The exception related to the sending failure.
-     The callback function should be defined like: `on_error(events, partition_id, error)`.
-     It is required when `buffered_mode` is True while optional if `buffered_mode` is False.
-     If `on_error` is passed when in non-buffered mode, instead of error being raised from the send methods,
-     the `on_error` callback will be called with the error information related to sending.
+     If `buffered_mode` is False, `on_error` callback is optional and errors will be handled as follows:
+        - If an `on_error` callback is passed during the producer client instantiation,
+            then error information will be passed to the `on_error` callback, which will then be called.
+        - If an `on_error` callback is not passed in during client instantiation,
+            then the error will be raised by default.
+     If `buffered_mode` is True, `on_error` callback is required and errors will be handled as follows:
+        - If events fail to enqueue within the given timeout, then an error will be directly raised.
+        - If events fail to send after enqueuing successfully, the `on_error` callback will be called.
     :paramtype on_error: Optional[Callable[[SendEventTypes, Optional[str], Exception], None]]
     :keyword int max_buffer_length: Buffered mode only.
      The total number of events per partition that can be buffered before a flush will be triggered.
@@ -398,17 +402,22 @@ def from_connection_string(
             - `events`: The list of events that have been successfully published
             - `partition_id`: The partition id that the events in the list have been published to.
          The callback function should be defined like: `on_success(events, partition_id)`.
-         It is required when `buffered_mode` is True while optional if `buffered_mode` is False.
+         Required when `buffered_mode` is True while optional if `buffered_mode` is False.
         :paramtype on_success: Optional[Callable[[SendEventTypes, Optional[str]], None]]
         :keyword on_error: The callback to be called once a batch has failed to be published.
-         The callback takes three parameters:
+         Required when in `buffered_mode` is True while optional if `buffered_mode` is False.
+         The callback function should be defined like: `on_error(events, partition_id, error)`, where:
             - `events`: The list of events that failed to be published,
             - `partition_id`: The partition id that the events in the list have been tried to be published to and
             - `error`: The exception related to the sending failure.
-         The callback function should be defined like: `on_error(events, partition_id, error)`.
-         It is required when in `buffered_mode` is True while optional if `buffered_mode` is False.
-         If `on_error` is passed in non-buffered mode, instead of error being raised from the send methods,
-         the `on_error` callback will be called with the error information related to sending.
+         If `buffered_mode` is False, `on_error` callback is optional and errors will be handled as follows:
+            - If an `on_error` callback is passed during the producer client instantiation,
+                then error information will be passed to the `on_error` callback, which will then be called.
+            - If an `on_error` callback is not passed in during client instantiation,
+                then the error will be raised by default.
+         If `buffered_mode` is True, `on_error` callback is required and errors will be handled as follows:
+            - If events fail to enqueue within the given timeout, then an error will be directly raised.
+            - If events fail to send after enqueuing successfully, the `on_error` callback will be called.
         :paramtype on_error: Optional[Callable[[SendEventTypes, Optional[str], Exception], None]]
         :keyword int max_buffer_length: Buffered mode only.
          The total number of events per partition that can be buffered before a flush will be triggered.
@@ -483,9 +492,15 @@ def send_event(self, event_data, **kwargs):
         the events into buffer within the given time if specified and return.
         The producer will do automatic sending in the background in buffered mode.
 
-        If `on_error` is passed while `buffered_mode` is False when instantiating the producer client,
-        instead of error being raised from the send methods,
-        the `on_error` callback will be called with the error information related to sending.
+         If `buffered_mode` is False, `on_error` callback is optional and errors will be handled as follows:
+            - If an `on_error` callback is passed during the producer client instantiation,
+                then error information will be passed to the `on_error` callback, which will then be called.
+            - If an `on_error` callback is not passed in during client instantiation,
+                then the error will be raised by default.
+
+         If `buffered_mode` is True, `on_error` callback is required and errors will be handled as follows:
+            - If events fail to enqueue within the given timeout, then an error will be directly raised.
+            - If events fail to send after enqueuing successfully, the `on_error` callback will be called.
 
         :param event_data: The `EventData` object to be sent.
         :type event_data: Union[~azure.eventhub.EventData, ~azure.eventhub.amqp.AmqpAnnotatedMessage]
@@ -548,9 +563,15 @@ def send_batch(self, event_data_batch, **kwargs):
         the events into buffer within the given time if specified and return.
         The producer will do automatic sending in the background in buffered mode.
 
-        In non-buffered mode, if `on_error` is passed in when instantiating the producer client,
-        instead of error being raised from the send methods in error scenarios,
-        the `on_error` callback will be called with the error related to sending failure.
+        If `buffered_mode` is False, `on_error` callback is optional and errors will be handled as follows:
+           - If an `on_error` callback is passed during the producer client instantiation,
+               then error information will be passed to the `on_error` callback, which will then be called.
+           - If an `on_error` callback is not passed in during client instantiation,
+               then the error will be raised by default.
+
+        If `buffered_mode` is True, `on_error` callback is required and errors will be handled as follows:
+           - If events fail to enqueue within the given timeout, then an error will be directly raised.
+           - If events fail to send after enqueuing successfully, the `on_error` callback will be called.
 
         In buffered mode, sending a batch will remain intact and sent as a single unit.
         The batch will not be rearranged. This may result in inefficiency of sending events.
diff --git a/sdk/eventhub/azure-eventhub/azure/eventhub/aio/_producer_client_async.py b/sdk/eventhub/azure-eventhub/azure/eventhub/aio/_producer_client_async.py
@@ -63,17 +63,22 @@ class EventHubProducerClient(ClientBaseAsync):  # pylint: disable=client-accepts
         - `events`: The list of events that have been successfully published
         - `partition_id`: The partition id that the events in the list have been published to.
      The callback function should be defined like: `on_success(events, partition_id)`.
-     It is required when `buffered_mode` is True while optional if `buffered_mode` is False.
+     Required when `buffered_mode` is True while optional if `buffered_mode` is False.
     :paramtype on_success: Optional[Callable[[SendEventTypes, Optional[str]], Awaitable[None]]]
     :keyword on_error: The callback to be called once a batch has failed to be published.
-     The callback takes three parameters:
+     Required when in `buffered_mode` is True while optional if `buffered_mode` is False.
+     The callback function should be defined like: `on_error(events, partition_id, error)`, where:
         - `events`: The list of events that failed to be published,
         - `partition_id`: The partition id that the events in the list have been tried to be published to and
         - `error`: The exception related to the sending failure.
-     The callback function should be defined like: `on_error(events, partition_id, error)`.
-     It is required when in `buffered_mode` is True while optional if `buffered_mode` is False.
-     If `on_error` is passed when in non-buffered mode, instead of error being raised from the send methods,
-     the `on_error` callback will be called with the error information related to sending.
+     If `buffered_mode` is False, `on_error` callback is optional and errors will be handled as follows:
+        - If an `on_error` callback is passed during the producer client instantiation,
+            then error information will be passed to the `on_error` callback, which will then be called.
+        - If an `on_error` callback is not passed in during client instantiation,
+            then the error will be raised by default.
+     If `buffered_mode` is True, `on_error` callback is required and errors will be handled as follows:
+        - If events fail to enqueue within the given timeout, then an error will be directly raised.
+        - If events fail to send after enqueuing successfully, the `on_error` callback will be called.
     :paramtype on_error: Optional[Callable[[SendEventTypes, Optional[str], Exception], Awaitable[None]]]
     :keyword int max_buffer_length: Buffered mode only.
      The total number of events per partition that can be buffered before a flush will be triggered.
@@ -409,14 +414,18 @@ def from_connection_string(
          It is required when `buffered_mode` is True while optional if `buffered_mode` is False.
         :paramtype on_success: Optional[Callable[[SendEventTypes, Optional[str]], Awaitable[None]]]
         :keyword on_error: The callback to be called once a batch has failed to be published.
-         The callback takes three parameters:
+         The callback function should be defined like: `on_error(events, partition_id, error)`, where:
             - `events`: The list of events that failed to be published,
             - `partition_id`: The partition id that the events in the list have been tried to be published to and
             - `error`: The exception related to the sending failure.
-         The callback function should be defined like: `on_error(events, partition_id, error)`.
-         It is required when `buffered mode` is True while optional if `buffered_mode` is False.
-         If `on_error` is passed in non-buffered mode, instead of error being raised from the send methods,
-         the `on_error` callback will be called with the error information related to sending.
+         If `buffered_mode` is False, `on_error` callback is optional and errors will be handled as follows:
+            - If an `on_error` callback is passed during the producer client instantiation,
+                then error information will be passed to the `on_error` callback, which will then be called.
+            - If an `on_error` callback is not passed in during client instantiation,
+                then the error will be raised by default.
+         If `buffered_mode` is True, `on_error` callback is required and errors will be handled as follows:
+            - If events fail to enqueue within the given timeout, then an error will be directly raised.
+            - If events fail to send after enqueuing successfully, the `on_error` callback will be called.
         :paramtype on_error: Optional[Callable[[SendEventTypes, Optional[str], Exception], Awaitable[None]]]
         :keyword int max_buffer_length: Buffered mode only.
          The total number of events per partition that can be buffered before a flush will be triggered.
@@ -499,9 +508,15 @@ async def send_event(
         If the `EventHubProducerClient` is configured to run in buffered mode, the method will enqueue the event
         into local buffer and return. The producer will do automatic batching and sending in the background.
 
-        If `on_error` is passed while `buffered_mode` is False when instantiating the producer client,
-        instead of error being raised from the send methods,
-        the `on_error` callback will be called with the error information related to sending.
+         If `buffered_mode` is False, `on_error` callback is optional and errors will be handled as follows:
+            - If an `on_error` callback is passed during the producer client instantiation,
+                then error information will be passed to the `on_error` callback, which will then be called.
+            - If an `on_error` callback is not passed in during client instantiation,
+                then the error will be raised by default.
+
+         If `buffered_mode` is True, `on_error` callback is required and errors will be handled as follows:
+            - If events fail to enqueue within the given timeout, then an error will be directly raised.
+            - If events fail to send after enqueuing successfully, the `on_error` callback will be called.
 
         :param event_data: The `EventData` object to be sent.
         :type event_data: Union[~azure.eventhub.EventData, ~azure.eventhub.amqp.AmqpAnnotatedMessage]
@@ -566,9 +581,15 @@ async def send_batch(
         If the `EventHubProducerClient` is configured to run in buffered mode, the method will enqueue the events
         into local buffer and return. The producer will do automatic sending in the background.
 
-        In non-buffered mode, if `on_error` is passed in when instantiating the producer client,
-        instead of error being raised from the send methods in error scenarios,
-        the `on_error` callback will be called with the error related to sending failure.
+        If `buffered_mode` is False, `on_error` callback is optional and errors will be handled as follows:
+           - If an `on_error` callback is passed during the producer client instantiation,
+               then error information will be passed to the `on_error` callback, which will then be called.
+           - If an `on_error` callback is not passed in during client instantiation,
+               then the error will be raised by default.
+
+        If `buffered_mode` is True, `on_error` callback is required and errors will be handled as follows:
+           - If events fail to enqueue within the given timeout, then an error will be directly raised.
+           - If events fail to send after enqueuing successfully, the `on_error` callback will be called.
 
         In buffered mode, sending a batch will remain intact and sent as a single unit.
         The batch will not be rearranged. This may result in inefficiency of sending events.
diff --git a/sdk/eventhub/azure-eventhub/samples/README.md b/sdk/eventhub/azure-eventhub/samples/README.md
@@ -74,12 +74,17 @@ Both [sync version](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/
     - Utilize `azure.core.credentials.AzureNamedKeyCredential` to authenticate when creating an Event Hub client.
 
 - [connection_to_custom_endpoint_address.py](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/eventhub/azure-eventhub/samples/sync_samples/connection_to_custom_endpoint_address.py) ([async version](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/eventhub/azure-eventhub/samples/async_samples/connection_to_custom_endpoint_address_async.py)) - Examples:
-  to create EventHubProducerClient and EventHubConsumerClient that connect to a custom endpoint with a custom certificate.
+    - Create EventHubProducerClient and EventHubConsumerClient that connect to a custom endpoint with a custom certificate.
 
 - [send_and_receive_amqp_annotated_message.py](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/eventhub/azure-eventhub/samples/sync_samples/send_and_receive_amqp_annotated_message.py) ([async_version](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/eventhub/azure-eventhub/samples/async_samples/send_and_receive_amqp_annotated_message_async.py)) - Examples to send AMQPAnnotatedMessage to and receive events from an event hub and parse the body:
     - Send AMQPAnnotatedMessage of different body types.
     - Receive messages and parse the body according to the body type.
 
+- [send_buffered_mode.py](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/eventhub/azure-eventhub/samples/sync_samples/send_buffered_mode.py) ([async_version](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/eventhub/azure-eventhub/samples/async_samples/send_buffered_mode_async.py)) - Examples to send events in buffered mode:
+    - Send single events, which will be automatically batched.
+    - Send a batch of events by enqueuing an EventDataBatch object to the buffer.
+    - Send events in buffer immediately by calling `flush`.
+
 ## Prerequisites
 - Python 3.6 or later.
 - **Microsoft Azure Subscription:**  To use Azure services, including Azure Event Hubs, you'll need a subscription.
