blockbuster

What it is and what it does

Blockbuster is a testing utility that detects blocking calls within an asyncio event loop by wrapping common blocking functions from modules like time, os, socket, io, sqlite3, and threading. When a blocking operation is called from within an async context, it raises a BlockingError to alert developers. This helps identify performance bottlenecks and unpredictable behavior that can occur when blocking operations halt the entire event loop.

The package works by monkey-patching standard library functions and checking whether they are being invoked from within an asyncio event loop. It can be used manually by instantiating and activating a BlockBuster instance, as a context manager, or integrated into pytest test suites via fixtures. It supports customization through adding custom rules for third-party libraries and allowing blocking calls in specific contexts.

Use it for:

• Integrate into pytest test suites to automatically catch blocking calls in async code during test execution.
• Verify that refactored legacy code no longer makes blocking calls when converted to async.
• Identify third-party library calls that inadvertently block the event loop during development.
• Validate that async APIs do not call blocking functions like time.sleep or file I/O operations.
• Catch blocking socket or database operations in async networking or data-access layers.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Blockbuster detects and prevents blocking calls within an asyncio event loop by wrapping common blocking functions and raising BlockingError when they are called from async contexts.

Yes, if you write asyncio code and want to catch blocking calls during testing. The package is actively maintained, has low install friction, carries no known vulnerabilities, and solves a real problem in async development. The alpha status and single external dependency are minor considerations; the permissive license and broad Python version support make it straightforward to adopt in test suites.

Install

blockbuster on PyPI

pip install blockbuster

uv add blockbuster

poetry add blockbuster

Installing blockbuster

Before you install

Low install friction with a single runtime dependency (forbiddenfruit). Package is actively maintained with recent commits and marked as alpha-stage. Supports Python 3.8 through 3.13.

License in practice

Licensed under Apache Software License (permissive), which allows commercial and private use with minimal restrictions.

Quickstart

pip install blockbuster

from blockbuster import BlockBuster

blockbuster = BlockBuster()
blockbuster.activate()
# Blocking calls within asyncio will now raise BlockingError

Requires asyncio event loop to be running; only detects blocking calls within active async contexts. Works with CPython; other implementations require setattr monkey-patching support.

Verify before relying

• Whether forbiddenfruit dependency introduces any compatibility or maintenance concerns not evident from the fact sheet.
• Performance overhead of wrapping blocking functions during test execution.
• Coverage of blocking calls in C extensions from third-party libraries beyond the documented list.

Package facts

Evidence: blockbuster-1.5.26-py3-none-any.whl

Keywords: async, asyncio, block, detect, event loop

Tags

More Build Tools packages