# blockbuster

> Utility to detect blocking calls in the async event loop

- **URL**: https://www.freshcrate.ai/projects/blockbuster
- **Author**: pypi
- **Category**: Developer Tools
- **Latest version**: `1.5.26` (2026-04-21)
- **License**: Unknown
- **Source**: https://github.com/cbornet/blockbuster/issues
- **Homepage**: https://pypi.org/project/blockbuster/
- **Language**: Python
- **GitHub**: 79 stars, 5 forks
- **Registry**: pypi (`blockbuster`)
- **Tags**: `async`, `asyncio`, `block`, `detect`, `event`, `loop`, `pypi`

## Description

# Blockbuster

Blockbuster is a Python package designed to detect and prevent blocking calls within an asynchronous event loop.
It is particularly useful when executing tests to ensure that your asynchronous code does not inadvertently call blocking operations, 
which can lead to performance bottlenecks and unpredictable behavior.

In Python, the asynchronous event loop allows for concurrent execution of tasks without the need for multiple threads or processes.
This is achieved by running tasks cooperatively, where tasks yield control back to the event loop when they are waiting for I/O operations or other long-running tasks to complete.

However, blocking calls, such as file I/O operations or certain networking operations, can halt the entire event loop, preventing other tasks from running.
This can lead to increased latency and reduced performance, defeating the purpose of using asynchronous programming.

The difficulty with blocking calls is that they are not always obvious, especially when working with third-party libraries or legacy code.
This is where Blockbuster comes in: it helps you identify and eliminate blocking calls in your codebase during testing, ensuring that your asynchronous code runs smoothly and efficiently.
It does this by wrapping common blocking functions and raising an exception when they are called within an asynchronous context.

Notes:
- Blockbuster currently only detects `asyncio` event loops.
- Blockbuster is tested only with CPython. It may work with other Python implementations if it's possible to monkey-patch the functions with `setattr`.

## Installation

The package is named `blockbuster`.
For instance with `pip`:

```bash
pip install blockbuster
```

It is recommended to constrain the version of Blockbuster.
Blockbuster doesn't strictly follow semver. Breaking changes such as new rules added may be introduced between minor versions, but not between patch versions.
So it is recommended to constrain the Blockbuster version on the minor version.
For instance, with `uv`:

```bash
uv add "blockbuster>=1.5.5,<1.6"
```

## Using BlockBuster

### Manually

To activate BlockBuster manually, create an instance of the `BlockBuster` class and call the `activate()` method:

```python
from blockbuster import BlockBuster

blockbuster = BlockBuster()
blockbuster.activate()
```

Once activated, BlockBuster will raise a `BlockingError` exception whenever a blocking call is detected within an `asyncio` event loop.

To deactivate BlockBuster, call the `deactivate()` method:

```python
blockbuster.deactivate()
```

### Using the context manager

BlockBuster can also be activated using a context manager, which automatically activates and deactivates the checks within the `with` block:

```python
from blockbuster import blockbuster_ctx

with blockbuster_ctx():
    # Your test code here
```

### Usage with Pytest

Blockbuster is intended to be used with testing frameworks like `pytest` to catch blocking calls. 
Here's how you can integrate Blockbuster into your `pytest` test suite:

```python
import pytest
import time
from blockbuster import BlockBuster, BlockingError, blockbuster_ctx
from typing import Iterator

@pytest.fixture(autouse=True)
def blockbuster() -> Iterator[BlockBuster]:
    with blockbuster_ctx() as bb:
        yield bb

async def test_time_sleep() -> None:
    with pytest.raises(BlockingError, match="sleep"):
        time.sleep(1)  # This should raise a BlockingError
```

By using the `blockbuster_ctx` context manager, Blockbuster is automatically activated for every test, and blocking calls will raise a `BlockingError`.

## How it works

Blockbuster works by wrapping common blocking functions from various modules (e.g., `os`, `socket`, `time`) and replacing them with versions that check if they are being called from within an `asyncio` event loop.
If such a call is detected, Blockbuster raises a `BlockingError` to indicate that a blocking operation is being performed inappropriately.

Blockbuster supports by default the following functions and modules:

- **Time Functions**:
  - `time.sleep`
- **OS Functions**:
  - `os.getcwd`
  - `os.statvfs`
  - `os.sendfile`
  - `os.rename`
  - `os.remove`
  - `os.unlink`
  - `os.mkdir`
  - `os.rmdir`
  - `os.link`
  - `os.symlink`
  - `os.readlink`
  - `os.listdir`
  - `os.scandir`
  - `os.access`
  - `os.stat`
  - `os.replace`
  - `os.read`
  - `os.write`
- **OS path Functions**:
  - `os.path.ismount`
  - `os.path.samestat`
  - `os.path.sameopenfile`
  - `os.path.islink`
  - `os.path.abspath`
- **IO Functions**:
  - `io.BufferedReader.read`
  - `io.BufferedWriter.write`
  - `io.BufferedRandom.read`
  - `io.BufferedRandom.write`
  - `io.TextIOWrapper.read`
  - `io.TextIOWrapper.write`
- **Socket Functions**:
  - `socket.socket.connect`
  - `socket.socket.accept`
  - `socket.socket.send`
  - `socket.socket.sendall`
  - `socket.socket.sendto`
  - `socket.socket.recv`
  - `socket.socket.recv_into`
  - `socket.socket.recvfrom`
  - `socket.socket

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `1.5.26` | 2026-04-21 | Low | Imported from PyPI (1.5.26) |
| `v1.5.23` | 2025-02-24 | Low | ## What's Changed * Add exclusion for os.getcwd in coverage by @cbornet in https://github.com/cbornet/blockbuster/pull/44   **Full Changelog**: https://github.com/cbornet/blockbuster/compare/v1.5.21...v1.5.23 |
| `v1.5.23` | 2025-02-24 | Low | ## What's Changed * Add exclusion for os.getcwd in coverage by @cbornet in https://github.com/cbornet/blockbuster/pull/44   **Full Changelog**: https://github.com/cbornet/blockbuster/compare/v1.5.21...v1.5.23 |
| `v1.5.23` | 2025-02-24 | Low | ## What's Changed * Add exclusion for os.getcwd in coverage by @cbornet in https://github.com/cbornet/blockbuster/pull/44   **Full Changelog**: https://github.com/cbornet/blockbuster/compare/v1.5.21...v1.5.23 |
| `v1.5.23` | 2025-02-24 | Low | ## What's Changed * Add exclusion for os.getcwd in coverage by @cbornet in https://github.com/cbornet/blockbuster/pull/44   **Full Changelog**: https://github.com/cbornet/blockbuster/compare/v1.5.21...v1.5.23 |
| `v1.5.23` | 2025-02-24 | Low | ## What's Changed * Add exclusion for os.getcwd in coverage by @cbornet in https://github.com/cbornet/blockbuster/pull/44   **Full Changelog**: https://github.com/cbornet/blockbuster/compare/v1.5.21...v1.5.23 |
| `v1.5.23` | 2025-02-24 | Low | ## What's Changed * Add exclusion for os.getcwd in coverage by @cbornet in https://github.com/cbornet/blockbuster/pull/44   **Full Changelog**: https://github.com/cbornet/blockbuster/compare/v1.5.21...v1.5.23 |
| `v1.5.23` | 2025-02-24 | Low | ## What's Changed * Add exclusion for os.getcwd in coverage by @cbornet in https://github.com/cbornet/blockbuster/pull/44   **Full Changelog**: https://github.com/cbornet/blockbuster/compare/v1.5.21...v1.5.23 |
| `v1.5.23` | 2025-02-24 | Low | ## What's Changed * Add exclusion for os.getcwd in coverage by @cbornet in https://github.com/cbornet/blockbuster/pull/44   **Full Changelog**: https://github.com/cbornet/blockbuster/compare/v1.5.21...v1.5.23 |
| `v1.5.23` | 2025-02-24 | Low | ## What's Changed * Add exclusion for os.getcwd in coverage by @cbornet in https://github.com/cbornet/blockbuster/pull/44   **Full Changelog**: https://github.com/cbornet/blockbuster/compare/v1.5.21...v1.5.23 |

## Dependency audit

- **Score**: 76/100
- **Total deps**: 1
- **Resolved**: 0
- **Unresolved**: 1
- **License conflicts**: 0
- **Warnings**: 2
- **Scanned**: 2026-05-25

## Citation

- HTML: https://www.freshcrate.ai/projects/blockbuster
- Markdown: https://www.freshcrate.ai/projects/blockbuster.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/blockbuster/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._