Azure Event Hubs Client Library

5.15.1 · active · verified Thu Apr 09

The Microsoft Azure Event Hubs Client Library for Python facilitates sending and receiving events to and from Azure Event Hubs. It follows the Azure SDK 'Track 2' design principles, offering an async-first API for high-throughput data streaming scenarios. The current version is 5.15.1, and it receives regular updates, typically monthly or bi-monthly, in alignment with other Azure SDKs.

Warnings

breaking Version 5.0.0 introduced a complete rewrite following Azure SDK 'Track 2' guidelines. This includes an async-first API, new client class names (`EventHubProducerClient`, `EventHubConsumerClient`, `EventProcessorClient`), and removal of older classes like `EventHubClient`. Code written for v1-v4 will not work with v5+ without significant refactoring.
Fix: Refer to the official 'Azure Event Hubs client library for Python' documentation and migration guides for v5.0.0+. Redesign your application to use the new client classes and async patterns (e.g., `await` for all operations, `async with` for client contexts).
gotcha The `EventProcessorClient` (used for distributed event processing with checkpointing) requires an *additional* storage provider package for checkpointing (e.g., `azure-eventhub-checkpointstoreblob` for Azure Blob Storage). Without this, checkpointing will not work, and the client will not save its progress.
Fix: Install the appropriate checkpoint store library, for example: `pip install azure-eventhub-checkpointstoreblob`. Then, pass an instance of the checkpoint store client (e.g., `BlobCheckpointStore`) to the `EventProcessorClient` constructor.
gotcha This library is async-first. Most operations (sending, receiving, creating batches, closing clients) are coroutines and *must* be `await`ed. Forgetting `await` will result in `RuntimeWarning: coroutine '...' was never awaited` or `TypeError: object NoneType can't be used in 'await' expression`.
Fix: Always use `await` when calling methods on `EventHubProducerClient`, `EventHubConsumerClient`, `EventProcessorClient`, and their associated objects (e.g., `batch.send_batch()`, `client.close()`). Use `async with` for client context management to ensure proper closing.
gotcha Python version compatibility has changed. While earlier v5.x versions supported Python >=3.6, `azure-eventhub>=5.14.0` requires `Python >=3.9`. Attempting to install or run on older Python versions (e.g., 3.7, 3.8) will fail during installation or at runtime.
Fix: Ensure your environment is running Python 3.9 or newer. If you must use an older Python version, pin `azure-eventhub` to an older compatible version (e.g., `azure-eventhub<5.14.0` for Python 3.8, or `azure-eventhub<5.11.0` for Python 3.6/3.7) and consult its documentation for features and breaking changes.

Install

pip install azure-eventhub Install core library
pip install azure-eventhub-checkpointstoreblob Install for Azure Blob Storage Checkpointing (optional)

Imports

EventHubProducerClient

from azure.eventhub import EventHubProducerClient

EventHubConsumerClient

from azure.eventhub import EventHubConsumerClient

EventData
```
from azure.eventhub import EventData
```

EventProcessorClient

from azure.eventhub import EventProcessorClient

EventHubClient
```
from azure.eventhub import EventHubProducerClient, EventHubConsumerClient
```
The `EventHubClient` class from previous 'Track 1' SDKs (v1-v4) was removed in v5.0.0. Use `EventHubProducerClient` for sending and `EventHubConsumerClient` for basic receiving, or `EventProcessorClient` for distributed processing with checkpointing.

Quickstart

This quickstart demonstrates how to send a batch of events to an Azure Event Hub using the `EventHubProducerClient`. It uses environment variables for secure credential management and showcases the async API pattern, which is standard for the Track 2 Azure SDKs.

import os
import asyncio
from azure.eventhub import EventHubProducerClient, EventData

# Retrieve connection string and Event Hub name from environment variables.
# For local development, replace 'os.environ.get(...)' with your actual values.
# Connection string for Event Hubs Namespace, NOT a specific Event Hub.
CONNECTION_STR = os.environ.get("EVENT_HUB_CONNECTION_STR", "Endpoint=sb://<NAMESPACE>.servicebus.windows.net/;SharedAccessKeyName=<KEY_NAME>;SharedAccessKey=<KEY>")
# The specific Event Hub name within the namespace
EVENTHUB_NAME = os.environ.get("EVENT_HUB_NAME", "<YOUR_EVENT_HUB_NAME>")

async def send_events():
    producer = EventHubProducerClient.from_connection_string(
        conn_str=CONNECTION_STR,
        eventhub_name=EVENTHUB_NAME
    )
    async with producer:
        event_data_batch = await producer.create_batch()
        event_data_batch.add(EventData("Hello Azure Event Hubs!"))
        event_data_batch.add(EventData("This is my second event."))
        await producer.send_batch(event_data_batch)
    print("Sent a batch of two events successfully.")

if __name__ == "__main__":
    # Ensure you have set the EVENT_HUB_CONNECTION_STR and EVENT_HUB_NAME
    # environment variables or replaced the placeholders.
    if not CONNECTION_STR or '<NAMESPACE>' in CONNECTION_STR:
        print("Please set the EVENT_HUB_CONNECTION_STR and EVENT_HUB_NAME environment variables.")
        print("Example: export EVENT_HUB_CONNECTION_STR='Endpoint=sb://...;SharedAccessKeyName=...;SharedAccessKey=...'")
        print("Example: export EVENT_HUB_NAME='myhub'")
    else:
        asyncio.run(send_events())

view raw JSON →