Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danielfm/pybreaker/llms.txt

Use this file to discover all available pages before exploring further.

PyBreaker brings the Circuit Breaker pattern to Python, letting you wrap any integration point — database calls, HTTP requests, queue operations — with a component that automatically stops forwarding calls when the downstream system is unhealthy. When the system recovers, PyBreaker seamlessly re-enables traffic.

Quickstart

Protect your first integration point in under 5 minutes

Core Concepts

Understand states, thresholds, and how the breaker works

API Reference

Full reference for CircuitBreaker and all public classes

Guides

Decorators, listeners, Redis storage, async support, and more

​
Why PyBreaker?

In distributed systems, a slow or failing dependency can exhaust thread pools and connection resources, eventually taking down the entire application. PyBreaker implements the Circuit Breaker pattern described in Michael T. Nygard’s Release It! to prevent this class of failure.

Thread-Safe

Built on Python’s threading.RLock — safe to use across threads and concurrent requests

Flexible Usage

Use as a decorator, call directly, or use the with context manager — whatever fits your code style

Redis Backing

Distribute circuit breaker state across multiple processes or nodes with optional Redis storage

Event Listeners

Hook into state changes, failures, and successes with CircuitBreakerListener

Smart Exceptions

Exclude business exceptions so only real system errors count against the failure threshold

Fully Typed

Ships with complete type annotations and a py.typed marker for mypy and pyright

​
How It Works

1

Install PyBreaker

pip install pybreaker
2

Create a circuit breaker

Instantiate CircuitBreaker once, at application scope, for each integration point you want to protect.
import pybreaker

db_breaker = pybreaker.CircuitBreaker(fail_max=5, reset_timeout=60)
3

Wrap your integration calls

Use the decorator syntax or call your function through cb.call().
@db_breaker
def get_user(user_id):
    return db.query("SELECT * FROM users WHERE id = %s", user_id)
4

Handle open-circuit errors

When the circuit opens, calls raise CircuitBreakerError. Catch it to serve a fallback response.
from pybreaker import CircuitBreakerError

try:
    user = get_user(user_id)
except CircuitBreakerError:
    user = get_cached_user(user_id)
PyBreaker requires Python 3.10 or later. Redis and Tornado integrations are optional extras.

Build docs developers (and LLMs) love

Get started for freeTalk to us