purgatory

What it is and what it does

Purgatory is a Python circuit breaker library that wraps calls to external services or dependencies to detect and respond to failures. It implements the circuit breaker design pattern, which maintains system stability by preventing repeated calls to failing services during outages or maintenance windows. The library supports both synchronous and asynchronous code paths and can be used as a context manager or decorator, making it flexible for different integration patterns.

The library offers configurable state storage (in-memory or Redis), event hooks for monitoring circuit state changes, and full type annotations. It's designed for distributed systems where shared state across multiple processes is important, and it provides visibility into circuit behavior through monitoring events.

Use it for:

• Wrap HTTP calls to external APIs to prevent request storms when a service is temporarily down.
• Protect database queries in microservices to stop cascading failures across service boundaries.
• Monitor and react to circuit state changes in real time using event hooks for alerting or logging.
• Share circuit state across multiple application instances using Redis as a distributed backend.
• Decorate async functions in asyncio applications to add automatic failure isolation without refactoring.

Worth the install?

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

Purgatory implements the circuit breaker pattern for both synchronous and asynchronous Python code, preventing cascading failures by stopping repeated calls to failing services.

Yes, if you need circuit breaker functionality for async or sync code. The library is permissively licensed, has no external dependencies, and is fully typed. However, the aging maintenance status (650 days since last release) means you should verify that the library's feature set and behavior match your exact needs before committing to it in a critical system.

Install

purgatory on PyPI

pip install purgatory

uv add purgatory

poetry add purgatory

Installing purgatory

Before you install

Low install friction with no runtime dependencies. Maintenance shows aging status—last release was 650 days ago, though the repository remains active with a recent commit on 2025-07-15.

License in practice

MIT license (permissive) allows free use, modification, and distribution in both open-source and proprietary projects with minimal restrictions.

Quickstart

from purgatory import AsyncCircuitBreakerFactory

circuitbreaker = AsyncCircuitBreakerFactory()
async with await circuitbreaker.get_breaker("my_circuit"):
    # protected code here
    pass

Requires Python 3.9 or later.

Verify before relying

• Whether Redis backend integration is production-ready and what configuration is required.
• Performance characteristics under high concurrency or with many simultaneous circuit breakers.
• Compatibility with popular async frameworks beyond asyncio (e.g., Trio, Curio).

Package facts

Evidence: purgatory-3.0.1-py3-none-any.whl

Tags

More Libraries packages