Registry / azure / azure-eventhub-checkpointstoreblob-aio

azure-eventhub-checkpointstoreblob-aio

JSON →
library1.2.0pypypi✓ verified 22d ago

This asynchronous Python library provides a checkpoint store implementation for Azure Event Hubs, using Azure Blob Storage as the persistent store. It allows Event Hubs consumers to store checkpoints and partition ownership information, ensuring reliable event processing and fault tolerance. The library is part of the larger Azure SDK for Python and is currently at version 1.2.0, receiving updates as needed.

pip install azure-eventhub-checkpointstoreblob-aio
INSTALL
IMPORT
SIG · AZURE-EVENTHUB-CHE
A
azure-eventhub-checkpointstoreblob-aio
azurepythonv1.2.0
Install
6.0s avg
Import
1448ms
Disk
57MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.522s · 56.1MB
glibc
py 3.103.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.
fix
Update 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.
fix
Upgrade 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.
fix
Ensure 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.
fix
Follow 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.
fix
Determine 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.
fix
Migrate 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.
fix
Ensure 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.
fix
Upgrade 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.
fix
Verify 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.
fix
Ensure 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.
Agent activity
39 hits · last 30 days
node
34
OpenAI (training)
1
Resources