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.

This guide walks you through protecting your first integration point with PyBreaker. By the end you’ll have a working circuit breaker that opens on repeated failures, short-circuits calls while open, and automatically attempts recovery after a timeout — all in a handful of lines of Python.
1

Install PyBreaker

Install PyBreaker from PyPI:
pip install pybreaker
2

Create a CircuitBreaker

Instantiate a CircuitBreaker at application scope — as a module-level global or injected singleton. Do not create a new instance per request; the circuit breaker must persist across calls to accumulate failure counts and track state.
import pybreaker

# Protects database integration points
# Opens after 5 consecutive failures, resets after 60 seconds
db_breaker = pybreaker.CircuitBreaker(fail_max=5, reset_timeout=60)
  • fail_max — number of consecutive failures required to open the circuit.
  • reset_timeout — seconds to wait in the open state before allowing a trial call (half-open).
3

Protect a Function with the Decorator

Apply the circuit breaker as a decorator. The wrapped function behaves exactly as before when the circuit is closed — the breaker is completely transparent during normal operation.
@db_breaker
def get_user(user_id):
    # This call is now protected by the circuit breaker
    return db.query("SELECT * FROM users WHERE id = %s", user_id)

# Call it normally — the circuit breaker is transparent when healthy
user = get_user(42)
4

Handle Circuit Open Errors

When the circuit opens (after fail_max consecutive failures), any call to the protected function immediately raises CircuitBreakerError — without executing the underlying function. Catch this exception separately from real errors so you can serve a fallback.
from pybreaker import CircuitBreakerError

try:
    user = get_user(42)
except CircuitBreakerError:
    # Circuit is open — serve from cache or return a default
    user = cache.get_user(42)
except Exception as e:
    # Actual error from the guarded function
    raise
5

Check Circuit State

Inspect the circuit breaker at any time to understand its current condition:
# Inspect current state
print(db_breaker.current_state)   # 'closed', 'open', or 'half-open'
print(db_breaker.fail_counter)    # consecutive failures so far
The current_state property reads directly from the underlying storage (memory or Redis), always reflecting the true state even when multiple instances share storage.

​
Alternative Usage Patterns

The decorator isn’t the only way to use PyBreaker. Two additional patterns give you more control when you can’t or don’t want to decorate a function. Direct call — invoke any callable through the breaker without modifying it: 
db_breaker.call(get_user, 42)
Context manager — wrap an inline block of code rather than a named function: 
with db_breaker.calling():
    user = db.query("SELECT * FROM users WHERE id = %s", 42)
All three patterns — decorator, call(), and context manager — enforce the same circuit breaker logic and update the same state.
Want to understand exactly how the closed → open → half-open transitions work, how success_threshold affects recovery, and how excluded exceptions let you filter out business errors? See the Core Concepts section for a deep dive into circuit breaker states and behavior.
Add a CircuitBreakerListener to your breaker and implement the state_change method to log every transition. This gives you immediate visibility into when circuits open and close — invaluable for debugging production incidents and tuning your fail_max and reset_timeout values.

Build docs developers (and LLMs) love

Get started for freeTalk to us