Registry /
azure / azure-eventhub-checkpointstoreblob-aio
Install & Compatibility
Where this runs
tested against v1.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.522s · 56.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.0s · import 1.374s · 58MB
57MB installed
● package 57MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BlobCheckpointStore
✓ from azure.eventhub.extensions.checkpointstoreblobaio import BlobCheckpointStore
✗ from azure.eventhub.extensions.checkpointstoreblobaio.blobstoragepmaio import BlobPartitionManager
The class was renamed from `BlobPartitionManager` to `BlobCheckpointStore` and the internal module `blobstoragepmaio` should not be imported directly since version 1.0.0b6.
This quickstart demonstrates how to set up an `EventHubConsumerClient` to receive events from Azure Event Hubs, using `BlobCheckpointStore` for managing checkpoints and partition ownership. It uses `DefaultAzureCredential` from `azure-identity` for passwordless authentication, which is recommended for production scenarios. Ensure the necessary environment variables for your Event Hubs namespace, Event Hub name, Blob Storage account URL, and container name are set, and the consuming identity has appropriate 'Azure Event Hubs Data Owner' and 'Storage Blob Data Contributor' roles.
import asyncio
import os
from azure.eventhub.aio import EventHubConsumerClient
from azure.eventhub.extensions.checkpointstoreblobaio import BlobCheckpointStore
from azure.identity.aio import DefaultAzureCredential
# Environment variables for Event Hubs
FULLY_QUALIFIED_NAMESPACE = os.environ.get('EVENT_HUB_FULLY_QUALIFIED_NAMESPACE', 'your_namespace.servicebus.windows.net')
EVENT_HUB_NAME = os.environ.get('EVENT_HUB_NAME', 'your_event_hub_name')
CONSUMER_GROUP = os.environ.get('EVENT_HUB_CONSUMER_GROUP', '$Default')
# Environment variables for Blob Storage
BLOB_STORAGE_ACCOUNT_URL = os.environ.get('AZURE_STORAGE_BLOB_URL', 'https://yourstorageaccount.blob.core.windows.net')
BLOB_CONTAINER_NAME = os.environ.get('BLOB_CONTAINER_NAME', 'your_container_name')
async def on_event(partition_context, event):
# Process the event here
if event.body_as_str():
print(f"Received event from partition ID: {partition_context.partition_id}, Body: {event.body_as_str()}")
# Update the checkpoint to mark the event as processed
await partition_context.update_checkpoint(event)
async def main():
credential = None
checkpoint_store = None
client = None
try:
# Authenticate using DefaultAzureCredential (Managed Identity, Environment variables, etc.)
credential = DefaultAzureCredential()
# Create an Azure Blob checkpoint store to store the checkpoints.
checkpoint_store = BlobCheckpointStore(
blob_account_url=BLOB_STORAGE_ACCOUNT_URL,
container_name=BLOB_CONTAINER_NAME,
credential=credential
)
# Create a consumer client for the event hub.
client = EventHubConsumerClient(
fully_qualified_namespace=FULLY_QUALIFIED_NAMESPACE,
eventhub_name=EVENT_HUB_NAME,
consumer_group=CONSUMER_GROUP,
checkpoint_store=checkpoint_store,
credential=credential,
)
async with client:
# Start receiving events
print(f"Listening for events in consumer group: {CONSUMER_GROUP} from Event Hub: {EVENT_HUB_NAME}")
await client.receive(on_event=on_event, starting_position="-1") # Start from beginning if no checkpoint
except Exception as e:
print(f"An error occurred: {e}")
finally:
if client:
await client.close()
if checkpoint_store:
await checkpoint_store.close()
if credential:
await credential.close()
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingThe `BlobPartitionManager` class was renamed to `BlobCheckpointStore` in version 1.0.0b6. The constructor signature also changed, now taking storage container details directly instead of a `ContainerClient` instance.fixUpdate class name to `BlobCheckpointStore` and adjust constructor parameters. Use `BlobCheckpointStore.from_connection_string` for connection string-based initialization or pass `blob_account_url`, `container_name`, and `credential`.
affects: <1.0.0b6
breakingAs of version 1.2.0, support for Python 2.7, 3.6, and 3.7 has been dropped. The library now requires Python 3.8 or later.fixUpgrade your Python environment to version 3.8 or newer.
affects: <1.2.0
gotchaThis is an asynchronous (aio) library. All operations and client instantiation require `async` and `await` keywords within an `asyncio` event loop.fixEnsure your application structure is asynchronous, utilizing `async def` functions and `await` calls for library methods.
affects: All
gotchaWhen using Azure Blob Storage for checkpointing, it's recommended to use a separate container for each consumer group, locate the storage account in the same region as the deployed application, and disable Hierarchical Namespace, Blob Soft Delete, and Versioning on the storage account for optimal performance and to prevent issues.fixFollow Azure's best practices for Blob Storage configuration when used as a checkpoint store, as detailed in the documentation.
affects: All
gotchaIf deploying on Azure Stack Hub or environments using older Azure Storage Service APIs, you may need to explicitly specify the `api_version` in the `BlobCheckpointStore` constructor (e.g., `api_version='2017-11-09'`) to avoid `HttpResponseError` due to incorrect header values.fixDetermine the supported Storage Service API version for your environment and pass it as the `api_version` keyword argument during `BlobCheckpointStore` instantiation.
affects: All (specific deployment environments)
gotchaWhile connection strings can be used for authentication, for production applications, Azure recommends passwordless authentication using Azure Active Directory and the `azure-identity` library. Ensure the principal has 'Azure Event Hubs Data Owner' and 'Storage Blob Data Contributor' roles.fixMigrate to passwordless authentication using `DefaultAzureCredential` or other `azure-identity` credentials. Assign the necessary Azure RBAC roles to your application's identity.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.eventhub.extensions.checkpointstoreblobaio'
This error typically occurs when the `azure-eventhub-checkpointstoreblob-aio` package is not installed, or there's a version mismatch/installation issue, especially in environments like Azure Databricks where package isolation can be complex.
fixEnsure the package is correctly installed using pip: `pip install azure-eventhub-checkpointstoreblob-aio`. If the issue persists in specific environments, try explicitly installing compatible versions of `azure-eventhub` and `azure-eventhub-checkpointstoreblob-aio`, for example: `pip install azure-eventhub==5.12.1 azure-eventhub-checkpointstoreblob-aio==1.1.4`.
KeyError: 'ownerid'
This `KeyError` often arises when the checkpoint blobs in Azure Storage are corrupted, missing expected metadata (like 'ownerid'), or when using older SDK versions with storage accounts that have Hierarchical Namespace (Data Lake Gen2) enabled, which can cause `list_blobs` to return directory entries without metadata.
fixUpgrade to the latest version of `azure-eventhub-checkpointstoreblob-aio` and `azure-eventhub`. If the issue persists, inspect the blobs in your checkpoint store container for missing 'ownerid' metadata. Clearing the checkpoint container and allowing the consumer client to recreate the blobs can also resolve the issue.
HttpResponseError: The value for one of the HTTP headers is not in the correct format. (or similar ClientAuthenticationError: Server failed to authenticate the request. Request date header too old)
These errors indicate a problem with authentication or header validation when the library attempts to interact with Azure Blob Storage. Common causes include incorrect storage account connection strings/credentials, clock skew between the client and Azure services, or using an unsupported Storage API version (e.g., when running on Azure Stack Hub). Firewall rules on the storage account can also cause connectivity issues.
fixVerify the storage account connection string or credential is correct and has the necessary permissions (Storage Blob Data Contributor role for managed identities/service principals). Ensure your system's clock is synchronized. If running on Azure Stack Hub, explicitly set the `api_version` during `BlobCheckpointStore` initialization to a version supported by your environment (e.g., `api_version='2017-11-09'`). Check storage account networking settings for firewalls or virtual network restrictions.
TypeError: 'credential' (or similar parameter) is not a constructor
This error typically occurs when initializing `BlobCheckpointStore` with an incorrectly instantiated credential object, or if an asynchronous credential object is passed where a synchronous one (or a connection string/SAS token) is expected, or vice-versa.
fixEnsure you are passing the correct type of credential object. If using `AsyncTokenCredential` (e.g., `DefaultAzureCredential(exclude_sync_token_credential=True)` from `azure-identity`), make sure it's compatible with the `BlobCheckpointStore` constructor, which expects an `AsyncTokenCredential`. Alternatively, use `BlobCheckpointStore.from_connection_string` if you have a storage connection string, or `AzureSasCredential` or `AzureNamedKeyCredential` for explicit key-based authentication.
Upgrade
Version history
1.2.0latest on PyPI · released Feb 13, 2025
Audit
Dependencies
azure-eventhubrequiredRequired for core Event Hubs consumer functionality, as this library acts as a plug-in for EventHubConsumerClient.
azure-storage-blobrequiredUnderlying client library used for interacting with Azure Blob Storage.
azure-identityoptionalRecommended for passwordless authentication using Azure Active Directory credentials.