asbflow 1.0.0__tar.gz

asbflow-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mattia Volpato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

asbflow-1.0.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: asbflow
+Version: 1.0.0
+Summary: A high-level Azure Service Bus abstraction for publishing, consuming, and DLQ workflows.
+Author-email: Mattia Volpato <volpato.mattia.2001@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/iFoxz17/asbflow
+Project-URL: Repository, https://github.com/iFoxz17/asbflow
+Project-URL: Issues, https://github.com/iFoxz17/asbflow/issues
+Project-URL: Changelog, https://github.com/iFoxz17/asbflow/blob/main/CHANGELOG.md
+Keywords: azure,service-bus,asb,messaging,dlq,pydantic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: azure-servicebus>=7.12.0
+Requires-Dist: azure-identity>=1.16.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: overrides>=7.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Provides-Extra: notebook
+Requires-Dist: jupyterlab>=4.2.0; extra == "notebook"
+Requires-Dist: ipykernel>=6.29.0; extra == "notebook"
+Requires-Dist: python-dotenv>=1.0.0; extra == "notebook"
+Dynamic: license-file
+
+# asbflow
+
+`asbflow` is a Python library built on top of the Microsoft Azure Service Bus SDK that abstracts the most common messaging workflows.
+
+## Workflow Status
+
+[![Dev CI](https://github.com/iFoxz17/asbflow/actions/workflows/dev.yml/badge.svg)](https://github.com/iFoxz17/asbflow/actions/workflows/dev.yml)
+[![Main CI](https://github.com/iFoxz17/asbflow/actions/workflows/main.yml/badge.svg)](https://github.com/iFoxz17/asbflow/actions/workflows/main.yml)
+[![Release](https://github.com/iFoxz17/asbflow/actions/workflows/release.yml/badge.svg)](https://github.com/iFoxz17/asbflow/actions/workflows/release.yml)
+
+It provides a clean service API for:
+- publishing to topics and queues,
+- consuming from subscriptions and queues,
+- managing dead-letter queue (DLQ) operations.
+
+The library is model-agnostic by default and integrates with Pydantic parsing when you want typed payload validation.
+
+## Why asbflow
+
+- Keep Azure Service Bus integration explicit but compact.
+- Reuse the same high-level APIs across projects.
+- Control parse behavior and settlement behavior per call.
+- Use strategy-based execution (`sequential`, `thread_pool`, `async`) without changing business code.
+
+## Core Components
+
+- `ASBPublisher`: publish payloads (`dict` or Pydantic models).
+- `ASBConsumer`: consume (settling) or read (non-settling) messages.
+- `ASBDLQManager`: read/consume/redrive/purge DLQ messages.
+- `ASBClientProvider`: pluggable auth provider (connection string or managed identity).
+- Entity abstraction: topic/queue sender and receiver access via dedicated entity clients.
+
+## Installation
+
+```bash
+pip install asbflow
+```
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+For notebook quickstarts:
+
+```bash
+pip install -e .[notebook]
+```
+
+## Quick Start
+
+```python
+from asbflow import (
+    ASBConnectionConfig,
+    ASBConsumer,
+    ASBConsumerConfig,
+    ASBPublisher,
+    ASBPublisherConfig,
+)
+
+connection = ASBConnectionConfig(
+    connection_string="<connection-string>",
+)
+
+publisher = ASBPublisher(
+    connection=connection,
+    publisher=ASBPublisherConfig(topic_name="<topic-name>"),
+)
+
+consumer = ASBConsumer(
+    connection=connection,
+    consumer=ASBConsumerConfig(
+        topic_name="<topic-name>",
+        subscription_name="<subscription-name>",
+    ),
+)
+
+publisher.publish(payload={"id": "a1", "severity": "high"}, parse=False)
+result = consumer.consume(parse=False, raise_on_error=False)
+print(result.succeeded, result.failed)
+```
+
+A richer walkthrough is available in [`quickstart/`](quickstart/README.md), including [`quickstart/asbflow_quickstart.ipynb`](quickstart/asbflow_quickstart.ipynb).
+
+## Design Principles
+
+- Abstraction over boilerplate, not over behavior.
+- Safe defaults with explicit overrides.
+- Uniform result contracts (`succeeded`, `failed`, `successes`, `failures`).
+- Structured logging across services and strategies.
+
+## Development
+
+Run tests:
+
+```bash
+pytest -q test/unit
+```
+
+Build package:
+
+```bash
+python -m build
+```
+
+## CI/CD Branch Model
+
+The repository ships with branch-oriented GitHub Actions:
+- `dev`: fast CI feedback (tests + quality checks).
+- `main`: full CI matrix + package build verification.
+- `release`: release validation and publish workflow.
+
+## Roadmap
+
+- More built-in payload parser adapters.
+- Additional reliability patterns around retries/backoff.
+- Optional observability integrations (metrics/tracing).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

asbflow-1.0.0/README.md

@@ -0,0 +1,122 @@
+# asbflow
+
+`asbflow` is a Python library built on top of the Microsoft Azure Service Bus SDK that abstracts the most common messaging workflows.
+
+## Workflow Status
+
+[![Dev CI](https://github.com/iFoxz17/asbflow/actions/workflows/dev.yml/badge.svg)](https://github.com/iFoxz17/asbflow/actions/workflows/dev.yml)
+[![Main CI](https://github.com/iFoxz17/asbflow/actions/workflows/main.yml/badge.svg)](https://github.com/iFoxz17/asbflow/actions/workflows/main.yml)
+[![Release](https://github.com/iFoxz17/asbflow/actions/workflows/release.yml/badge.svg)](https://github.com/iFoxz17/asbflow/actions/workflows/release.yml)
+
+It provides a clean service API for:
+- publishing to topics and queues,
+- consuming from subscriptions and queues,
+- managing dead-letter queue (DLQ) operations.
+
+The library is model-agnostic by default and integrates with Pydantic parsing when you want typed payload validation.
+
+## Why asbflow
+
+- Keep Azure Service Bus integration explicit but compact.
+- Reuse the same high-level APIs across projects.
+- Control parse behavior and settlement behavior per call.
+- Use strategy-based execution (`sequential`, `thread_pool`, `async`) without changing business code.
+
+## Core Components
+
+- `ASBPublisher`: publish payloads (`dict` or Pydantic models).
+- `ASBConsumer`: consume (settling) or read (non-settling) messages.
+- `ASBDLQManager`: read/consume/redrive/purge DLQ messages.
+- `ASBClientProvider`: pluggable auth provider (connection string or managed identity).
+- Entity abstraction: topic/queue sender and receiver access via dedicated entity clients.
+
+## Installation
+
+```bash
+pip install asbflow
+```
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+For notebook quickstarts:
+
+```bash
+pip install -e .[notebook]
+```
+
+## Quick Start
+
+```python
+from asbflow import (
+    ASBConnectionConfig,
+    ASBConsumer,
+    ASBConsumerConfig,
+    ASBPublisher,
+    ASBPublisherConfig,
+)
+
+connection = ASBConnectionConfig(
+    connection_string="<connection-string>",
+)
+
+publisher = ASBPublisher(
+    connection=connection,
+    publisher=ASBPublisherConfig(topic_name="<topic-name>"),
+)
+
+consumer = ASBConsumer(
+    connection=connection,
+    consumer=ASBConsumerConfig(
+        topic_name="<topic-name>",
+        subscription_name="<subscription-name>",
+    ),
+)
+
+publisher.publish(payload={"id": "a1", "severity": "high"}, parse=False)
+result = consumer.consume(parse=False, raise_on_error=False)
+print(result.succeeded, result.failed)
+```
+
+A richer walkthrough is available in [`quickstart/`](quickstart/README.md), including [`quickstart/asbflow_quickstart.ipynb`](quickstart/asbflow_quickstart.ipynb).
+
+## Design Principles
+
+- Abstraction over boilerplate, not over behavior.
+- Safe defaults with explicit overrides.
+- Uniform result contracts (`succeeded`, `failed`, `successes`, `failures`).
+- Structured logging across services and strategies.
+
+## Development
+
+Run tests:
+
+```bash
+pytest -q test/unit
+```
+
+Build package:
+
+```bash
+python -m build
+```
+
+## CI/CD Branch Model
+
+The repository ships with branch-oriented GitHub Actions:
+- `dev`: fast CI feedback (tests + quality checks).
+- `main`: full CI matrix + package build verification.
+- `release`: release validation and publish workflow.
+
+## Roadmap
+
+- More built-in payload parser adapters.
+- Additional reliability patterns around retries/backoff.
+- Optional observability integrations (metrics/tracing).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

asbflow-1.0.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "asbflow"
+version = "1.0.0"
+description = "A high-level Azure Service Bus abstraction for publishing, consuming, and DLQ workflows."
+readme = "README.md"
+license = "MIT"
+authors = [{name = "Mattia Volpato", email = "volpato.mattia.2001@gmail.com"}]
+requires-python = ">=3.10"
+keywords = ["azure", "service-bus", "asb", "messaging", "dlq", "pydantic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Distributed Computing",
+]
+
+dependencies = [
+    "azure-servicebus>=7.12.0",
+    "azure-identity>=1.16.0",
+    "pydantic>=2.0",
+    "overrides>=7.7.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-mock",
+    "black",
+    "isort",
+    "mypy",
+    "build>=1.2.2",
+    "twine>=5.1.1",
+    "pre-commit",
+]
+notebook = [
+    "jupyterlab>=4.2.0",
+    "ipykernel>=6.29.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/iFoxz17/asbflow"
+Repository = "https://github.com/iFoxz17/asbflow"
+Issues = "https://github.com/iFoxz17/asbflow/issues"
+Changelog = "https://github.com/iFoxz17/asbflow/blob/main/CHANGELOG.md"
+
+[tool.setuptools]
+packages = {find = {where = ["src"]}}
+
+[tool.setuptools.package-data]
+"asbflow" = ["py.typed"]
+
+[tool.black]
+line-length = 120
+target-version = ["py310"]
+
+[tool.isort]
+profile = "black"
+line_length = 120
+src_paths = ["src", "test", "quickstart"]

asbflow-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

asbflow-1.0.0/src/asbflow/__init__.py

@@ -0,0 +1,75 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from asbflow.config import (
+    ASBAuthMethod,
+    ASBConnectionConfig,
+    ASBConsumerConfig,
+    ASBMessageConfig,
+    ASBMessagingEntity,
+    ASBPublisherConfig,
+    ParseFailurePolicy,
+)
+from asbflow.consumer import (
+    ASBConsumer,
+    ConsumedPayloadFailure,
+    ConsumeExecutionMode,
+    ConsumeResult,
+    ParsedConsumeResult,
+    PydanticModelParser,
+    RawConsumeResult,
+    create_consumer,
+)
+from asbflow.dlq import (
+    ASBDLQManager,
+    DLQParsedReadResult,
+    DLQPurgeResult,
+    DLQRawReadResult,
+    DLQReadResult,
+    DLQRedriveResult,
+    create_dlq_manager,
+)
+from asbflow.exceptions import (
+    ConsumeError,
+    DLQError,
+    DLQPublisherNotConfiguredError,
+    PublishError,
+)
+from asbflow.publisher import ASBPublisher, PublishExecutionMode, create_publisher
+
+try:
+    __version__ = version("asbflow")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "__version__",
+    "ASBConnectionConfig",
+    "ASBPublisherConfig",
+    "ASBConsumerConfig",
+    "ASBMessagingEntity",
+    "ParseFailurePolicy",
+    "ASBAuthMethod",
+    "ASBMessageConfig",
+    "ASBPublisher",
+    "create_publisher",
+    "PublishExecutionMode",
+    "ASBConsumer",
+    "create_consumer",
+    "ASBDLQManager",
+    "create_dlq_manager",
+    "ConsumeExecutionMode",
+    "RawConsumeResult",
+    "ParsedConsumeResult",
+    "ConsumeResult",
+    "ConsumedPayloadFailure",
+    "DLQRawReadResult",
+    "DLQParsedReadResult",
+    "DLQReadResult",
+    "DLQRedriveResult",
+    "DLQPurgeResult",
+    "ConsumeError",
+    "PublishError",
+    "DLQError",
+    "DLQPublisherNotConfiguredError",
+    "PydanticModelParser",
+]

asbflow-1.0.0/src/asbflow/auth/__init__.py

@@ -0,0 +1,13 @@
+from asbflow.auth.base import ASBClientProvider
+from asbflow.auth.factory import ASBClientProviderFactory
+from asbflow.auth.providers import (
+    ConnectionStringClientProvider,
+    ManagedIdentityClientProvider,
+)
+
+__all__ = [
+    "ASBClientProvider",
+    "ASBClientProviderFactory",
+    "ConnectionStringClientProvider",
+    "ManagedIdentityClientProvider",
+]

asbflow-1.0.0/src/asbflow/auth/base.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from asbflow.config.connection import ASBConnectionConfig
+from asbflow.shared.sdk import ASBAsyncClient, ASBSyncClient
+
+
+class ASBClientProvider(ABC):
+    """Base abstraction for Azure Service Bus client providers."""
+
+    def __init__(self, config: ASBConnectionConfig) -> None:
+        """Initialize the provider.
+
+        Parameters
+        ----------
+        config : ASBConnectionConfig
+            Connection/auth configuration used to create clients.
+        """
+        self._config: ASBConnectionConfig = config
+
+    @property
+    def config(self) -> ASBConnectionConfig:
+        """Return the connection configuration used by this provider."""
+        return self._config
+
+    @abstractmethod
+    def create_sync_client(self) -> ASBSyncClient:
+        """Create a synchronous Azure Service Bus client.
+
+        Returns
+        -------
+        ASBSyncClient
+            Sync client implementing context manager semantics.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def create_async_client(self) -> ASBAsyncClient:
+        """Create an asynchronous Azure Service Bus client.
+
+        Returns
+        -------
+        ASBAsyncClient
+            Async client implementing async context manager semantics.
+        """
+        raise NotImplementedError
+
+
+__all__ = ["ASBClientProvider"]

asbflow-1.0.0/src/asbflow/auth/factory.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from asbflow.auth.base import ASBClientProvider
+from asbflow.auth.providers import (
+    ConnectionStringClientProvider,
+    ManagedIdentityClientProvider,
+)
+from asbflow.config.connection import ASBAuthMethod, ASBConnectionConfig
+
+
+class ASBClientProviderFactory:
+    """Build the client provider matching the configured auth method."""
+
+    @staticmethod
+    def create(config: ASBConnectionConfig) -> ASBClientProvider:
+        """Create an auth provider.
+
+        Parameters
+        ----------
+        config : ASBConnectionConfig
+            Connection/auth configuration.
+
+        Returns
+        -------
+        ASBClientProvider
+            Provider implementation compatible with the selected auth method.
+
+        Raises
+        ------
+        ValueError
+            If the auth method is unsupported.
+        """
+        match config.auth:
+            case ASBAuthMethod.CONNECTION_STRING:
+                return ConnectionStringClientProvider(config)
+            case ASBAuthMethod.MANAGED_IDENTITY:
+                return ManagedIdentityClientProvider(config)
+
+        raise ValueError(f"Unsupported Service Bus auth method: {config.auth}")
+
+
+__all__ = ["ASBClientProviderFactory"]

asbflow-1.0.0/src/asbflow/auth/providers.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from importlib import import_module
+from types import ModuleType
+from typing import Any
+
+from asbflow.auth.base import ASBClientProvider
+from asbflow.config.connection import ASBConnectionConfig
+from asbflow.config.defaults import get_asbflow_logger
+from asbflow.shared.sdk import (
+    ASBAsyncClient,
+    ASBAsyncClientFactory,
+    ASBSyncClient,
+    ASBSyncClientFactory,
+    load_asb_async_client,
+    load_asb_client_factory,
+)
+
+LOGGER = get_asbflow_logger(__name__)
+
+
+class ConnectionStringClientProvider(ASBClientProvider):
+    """Create clients using Service Bus connection-string authentication."""
+
+    def create_sync_client(self) -> ASBSyncClient:
+        """Create a synchronous client from connection-string auth.
+
+        Returns
+        -------
+        ASBSyncClient
+            Synchronous Service Bus client.
+        """
+        LOGGER.info("Creating synchronous ASB client with connection-string auth")
+        servicebus_client: ASBSyncClientFactory = load_asb_client_factory()
+        LOGGER.debug(
+            "Loaded sync ASB factory class: %s",
+            type(servicebus_client).__name__,
+        )
+        return servicebus_client.from_connection_string(**self.config.to_connection_string_client_kwargs())
+
+    async def create_async_client(self) -> ASBAsyncClient:
+        """Create an asynchronous client from connection-string auth.
+
+        Returns
+        -------
+        ASBAsyncClient
+            Asynchronous Service Bus client.
+        """
+        LOGGER.info("Creating asynchronous ASB client with connection-string auth")
+        servicebus_client: ASBAsyncClientFactory = load_asb_async_client()
+        LOGGER.debug(
+            "Loaded async ASB factory class: %s",
+            type(servicebus_client).__name__,
+        )
+        return servicebus_client.from_connection_string(**self.config.to_connection_string_client_kwargs())
+
+
+class ManagedIdentityClientProvider(ASBClientProvider):
+    """Create clients using Azure Managed Identity authentication."""
+
+    def _build_credential(self) -> Any:
+        config: ASBConnectionConfig = self.config
+        if config.credential is not None:
+            LOGGER.debug("Using explicit credential instance from configuration")
+            return self.config.credential
+
+        try:
+            identity_module: ModuleType = import_module("azure.identity")
+        except Exception:
+            LOGGER.exception("Unable to import azure.identity while building managed-identity credential")
+            raise
+
+        credential_class: Any = getattr(identity_module, "ManagedIdentityCredential")
+        if config.managed_identity_client_id is not None:
+            LOGGER.debug("Building ManagedIdentityCredential with client_id")
+            return credential_class(client_id=config.managed_identity_client_id)
+
+        LOGGER.debug("Building default ManagedIdentityCredential")
+        return credential_class()
+
+    def _build_kwargs(self) -> dict[str, Any]:
+        credential: Any = self._build_credential()
+        LOGGER.debug(
+            "Managed-identity client kwargs prepared (namespace=%s, logging_enable=%s)",
+            self.config.fully_qualified_namespace,
+            self.config.logging_enable,
+        )
+        return self.config.to_managed_identity_client_kwargs(credential=credential)
+
+    def create_sync_client(self) -> ASBSyncClient:
+        """Create a synchronous client from managed-identity auth.
+
+        Returns
+        -------
+        ASBSyncClient
+            Synchronous Service Bus client.
+        """
+        LOGGER.info("Creating synchronous ASB client with managed-identity auth")
+        servicebus_client: ASBSyncClientFactory = load_asb_client_factory()
+        LOGGER.debug(
+            "Loaded sync ASB factory class: %s",
+            type(servicebus_client).__name__,
+        )
+        return servicebus_client(**self._build_kwargs())
+
+    async def create_async_client(self) -> ASBAsyncClient:
+        """Create an asynchronous client from managed-identity auth.
+
+        Returns
+        -------
+        ASBAsyncClient
+            Asynchronous Service Bus client.
+        """
+        LOGGER.info("Creating asynchronous ASB client with managed-identity auth")
+        servicebus_client: ASBAsyncClientFactory = load_asb_async_client()
+        LOGGER.debug(
+            "Loaded async ASB factory class: %s",
+            type(servicebus_client).__name__,
+        )
+        return servicebus_client(**self._build_kwargs())
+
+
+__all__ = [
+    "ConnectionStringClientProvider",
+    "ManagedIdentityClientProvider",
+]