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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

boilermaker_servicebus-1.4.0.tar.gz (187.0 kB view details)

Uploaded Jul 10, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

boilermaker_servicebus-1.4.0-py3-none-any.whl (216.0 kB view details)

Uploaded Jul 10, 2026 Python 3

File details

Details for the file boilermaker_servicebus-1.4.0.tar.gz.

File metadata

Download URL: boilermaker_servicebus-1.4.0.tar.gz
Upload date: Jul 10, 2026
Size: 187.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for boilermaker_servicebus-1.4.0.tar.gz
Algorithm	Hash digest
SHA256	`5e1732c6cae6d8ccb031cbe0db3047b599ffe1ddab44734fa3202a47a583bc33`
MD5	`d9ffab11c3a6b359a06a6788d876773a`
BLAKE2b-256	`739abd6c0c06440d7b5013845049d853356b2c64e9437ec8e8a628c8ea819148`

See more details on using hashes here.

Provenance

The following attestation bundles were made for boilermaker_servicebus-1.4.0.tar.gz:

Publisher: release.yaml on MulliganFunding/boilermaker-servicebus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: boilermaker_servicebus-1.4.0.tar.gz
- Subject digest: 5e1732c6cae6d8ccb031cbe0db3047b599ffe1ddab44734fa3202a47a583bc33
- Sigstore transparency entry: 2139415070
- Sigstore integration time: Jul 10, 2026
Source repository:
- Permalink: MulliganFunding/boilermaker-servicebus@bb4747ff67b6079e82a4ae553359d0c4832df3f5
- Branch / Tag: refs/tags/v1.4.0
- Owner: https://github.com/MulliganFunding
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yaml@bb4747ff67b6079e82a4ae553359d0c4832df3f5
- Trigger Event: release