{"id":1349,"library":"azure-eventhub","title":"Azure Event Hubs Client Library","description":"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.","status":"active","version":"5.15.1","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/eventhub/azure-eventhub","tags":["azure","event-streaming","messaging","cloud","async"],"install":[{"cmd":"pip install azure-eventhub","lang":"bash","label":"Install core library"},{"cmd":"pip install azure-eventhub-checkpointstoreblob","lang":"bash","label":"Install for Azure Blob Storage Checkpointing (optional)"}],"dependencies":[{"reason":"Fundamental shared components for Azure SDKs (implicit dependency).","package":"azure-core","optional":false},{"reason":"Required for EventProcessorClient to store checkpoints in Azure Blob Storage. Other checkpoint stores exist but must be explicitly installed.","package":"azure-eventhub-checkpointstoreblob","optional":true}],"imports":[{"symbol":"EventHubProducerClient","correct":"from azure.eventhub import EventHubProducerClient"},{"symbol":"EventHubConsumerClient","correct":"from azure.eventhub import EventHubConsumerClient"},{"symbol":"EventData","correct":"from azure.eventhub import EventData"},{"symbol":"EventProcessorClient","correct":"from azure.eventhub import EventProcessorClient"},{"note":"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.","wrong":"from azure.eventhub import EventHubClient","symbol":"EventHubClient","correct":"from azure.eventhub import EventHubProducerClient, EventHubConsumerClient"}],"quickstart":{"code":"import os\nimport asyncio\nfrom azure.eventhub import EventHubProducerClient, EventData\n\n# Retrieve connection string and Event Hub name from environment variables.\n# For local development, replace 'os.environ.get(...)' with your actual values.\n# Connection string for Event Hubs Namespace, NOT a specific Event Hub.\nCONNECTION_STR = os.environ.get(\"EVENT_HUB_CONNECTION_STR\", \"Endpoint=sb://<NAMESPACE>.servicebus.windows.net/;SharedAccessKeyName=<KEY_NAME>;SharedAccessKey=<KEY>\")\n# The specific Event Hub name within the namespace\nEVENTHUB_NAME = os.environ.get(\"EVENT_HUB_NAME\", \"<YOUR_EVENT_HUB_NAME>\")\n\nasync def send_events():\n    producer = EventHubProducerClient.from_connection_string(\n        conn_str=CONNECTION_STR,\n        eventhub_name=EVENTHUB_NAME\n    )\n    async with producer:\n        event_data_batch = await producer.create_batch()\n        event_data_batch.add(EventData(\"Hello Azure Event Hubs!\"))\n        event_data_batch.add(EventData(\"This is my second event.\"))\n        await producer.send_batch(event_data_batch)\n    print(\"Sent a batch of two events successfully.\")\n\nif __name__ == \"__main__\":\n    # Ensure you have set the EVENT_HUB_CONNECTION_STR and EVENT_HUB_NAME\n    # environment variables or replaced the placeholders.\n    if not CONNECTION_STR or '<NAMESPACE>' in CONNECTION_STR:\n        print(\"Please set the EVENT_HUB_CONNECTION_STR and EVENT_HUB_NAME environment variables.\")\n        print(\"Example: export EVENT_HUB_CONNECTION_STR='Endpoint=sb://...;SharedAccessKeyName=...;SharedAccessKey=...'\")\n        print(\"Example: export EVENT_HUB_NAME='myhub'\")\n    else:\n        asyncio.run(send_events())\n","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.14.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}