{"id":1951,"library":"blockbuster","title":"Utility to detect blocking calls in the async event loop","description":"Blockbuster is a Python package designed to detect and prevent blocking calls within an asynchronous event loop. It's particularly useful during testing to ensure asynchronous code doesn't inadvertently perform blocking operations, which can cause performance bottlenecks. It works by monkey-patching common blocking functions and raising a `BlockingError` if called within an `asyncio` event loop. It currently only detects `asyncio` event loops and is tested with CPython.","status":"active","version":"1.5.26","language":"en","source_language":"en","source_url":"https://github.com/cbornet/blockbuster.git","tags":["async","block","detect","event loop","asyncio","testing","performance"],"install":[{"cmd":"pip install blockbuster","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for monkey-patching CPython immutable builtin functions and methods.","package":"forbiddenfruit","optional":false},{"reason":"Requires Python version >=3.8.","package":"Python","optional":false}],"imports":[{"note":"Context manager to activate blocking call detection.","symbol":"blockbuster_ctx","correct":"from blockbuster import blockbuster_ctx"},{"note":"The exception raised when a blocking call is detected.","symbol":"BlockingError","correct":"from blockbuster import BlockingError"}],"quickstart":{"code":"import asyncio\nimport time\nfrom blockbuster import blockbuster_ctx, BlockingError\n\nasync def main():\n    print(\"Running async task with blockbuster (should fail on time.sleep)...\")\n    try:\n        with blockbuster_ctx():\n            # This is a blocking call and should raise BlockingError\n            time.sleep(0.1)\n        print(\"This line should not be reached if blocking call is detected.\")\n    except BlockingError as e:\n        print(f\"Caught expected BlockingError: {e}\")\n    except Exception as e:\n        print(f\"Caught unexpected error: {e}\")\n\n    print(\"\\nRunning async task without blockbuster (should complete)...\")\n    try:\n        # This will complete without error\n        time.sleep(0.1)\n        print(\"Blocking call completed without blockbuster activated.\")\n    except BlockingError as e:\n        print(f\"Caught BlockingError (unexpected): {e}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to use `blockbuster_ctx` to detect blocking calls within an `asyncio` event loop. It runs an `async` function that intentionally calls `time.sleep()`, which is a blocking operation. When `blockbuster_ctx` is active, this call will raise a `BlockingError`. The second part shows the same blocking call without `blockbuster` activated, which completes without error, highlighting the utility of the library."},"warnings":[{"fix":"Always pin to a specific minor version or range for stability, e.g., `pip install 'blockbuster<X.Y'` where X.Y is your current major.minor version.","message":"Breaking changes, such as new rules, may be introduced between minor versions. It is recommended to constrain the Blockbuster version on the minor version (e.g., `blockbuster>=1.5.0,<1.6`).","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure your project exclusively uses `asyncio` or understand that other async contexts will not be monitored. For other frameworks, consider alternative detection mechanisms or custom rules.","message":"Blockbuster currently only detects `asyncio` event loops. It does not provide detection for other asynchronous frameworks.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use Blockbuster predominantly with CPython. If using other Python implementations (e.g., PyPy, Jython), thoroughly test its behavior and be prepared for potential inconsistencies.","message":"Blockbuster is primarily tested with CPython. While it might work with other Python implementations, its functionality relies on the ability to monkey-patch functions with `setattr`, which may not be consistently available or behave identically across all interpreters.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For such cases, you may need to add custom rules to Blockbuster's configuration during your test setup to specifically target the blocking functions used by those C-wrapped libraries. Contributions to the core project for common libraries are also welcome.","message":"Blockbuster may not detect blocking calls made by third-party libraries that wrap C libraries instead of using standard Python framework methods for I/O.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}