Boilermaker

Async Python background tasks with Azure ServiceBus

Boilermaker is a lightweight task runner exclusively for async Python and Azure Service Bus Queues. If you need a fully-featured task runner with multiple backends, consider Celery instead.

Quick Start

Install

pip install "boilermaker-servicebus"

Basic Usage

import asyncio
from boilermaker import Boilermaker, retries
from boilermaker.config import Config
from boilermaker.service_bus import AzureServiceBus

# Configure (loads from environment variables)
config = Config()
service_bus = AzureServiceBus.from_config(config)

# Create app with shared state
class AppState:
    def __init__(self):
        self.data = {"count": 0}

app = Boilermaker(AppState(), service_bus)

# Define background task
async def process_data(state, data_id):
    """state is injected automatically as first parameter"""
    print(f"Processing {data_id}")
    state.data["count"] += 1
    return f"Processed {data_id}"

# Register task
app.register_async(process_data, policy=retries.RetryPolicy.default())

# Publish task
async def main():
    await app.apply_async(process_data, "item_123")

# Run worker (separate process)
async def worker():
    await app.run()  # Runs forever

if __name__ == "__main__":
    asyncio.run(main())

Environment Variables

export SERVICE_BUS_NAMESPACE_URL="https://your-namespace.servicebus.windows.net/"
export SERVICE_BUS_QUEUE_NAME="your-queue-name"

Key Features

• Async-only: Built for async Python applications
• Retry Policies: Exponential, linear, and fixed backoff strategies
• Task Chaining: Success/failure callbacks and workflows

Documentation

📖 Complete Documentation

• Getting Started - Installation and basic usage
• Callbacks & Chains - Task workflows
• Retry Policies - Error handling and retries
• Task Graphs - Task Graphs
• Task Registration - Task Registration
• API Reference - Complete API docs

Requirements

• Python 3.11+
• Azure ServiceBus namespace and queue
• All task arguments must be JSON-serializable

TLA+ Specs Running

# Safety (exhaustive, terminates):
java -jar tla2tools.jar -workers auto \
    -config specs/TaskGraphTinySafety.cfg specs/TaskGraphTiny.tla

# Liveness (simulation, bounded depth: not exhaustive but practical):
java -jar tla2tools.jar -simulate num=100000 -depth 200 \
    -config specs/TaskGraphTiny.cfg specs/TaskGraphTiny.tla