PyBreaker is a pure-Python, thread-safe implementation of the Circuit Breaker pattern, as described by Michael T. Nygard in his book Release It!. It wraps dangerous integration points — database calls, HTTP requests, third-party APIs — with a component that can automatically short-circuit calls when the downstream system is unhealthy, preventing cascading failures from bringing down your entire application.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.
What is the Circuit Breaker Pattern?
In distributed systems, calls to remote services can fail or hang indefinitely. Without a safety mechanism, a single slow or unavailable dependency can exhaust thread pools, saturate connection queues, and cascade into a full system outage — even when the rest of your application is perfectly healthy. The Circuit Breaker pattern addresses this by acting as a proxy around potentially-failing operations. It monitors calls for failures and, once a threshold is crossed, “opens” the circuit so that subsequent calls fail immediately rather than waiting for a timeout or making the situation worse. After a configurable timeout, the circuit enters a half-open state and allows a trial call through. If the trial succeeds, the circuit closes and normal operation resumes; if it fails, the circuit opens again. This gives the failing subsystem time to recover while protecting the rest of your application from accumulating load against a broken dependency.Key Features
Configurable Thresholds
Tune
fail_max (consecutive failures before opening) and reset_timeout (seconds to wait before attempting recovery) to match each integration point’s characteristics.Success Threshold
Configure
success_threshold to require multiple consecutive successes in the half-open state before fully closing the circuit, preventing premature recovery.Three Circuit States
Implements the canonical closed, open, and half-open states with correct transitions, exposed as
STATE_CLOSED, STATE_OPEN, and STATE_HALF_OPEN constants.Flexible Usage Patterns
Use as a decorator (
@db_breaker), via direct call (db_breaker.call(fn, *args)), or as a context manager (with db_breaker.calling():). All three patterns are first-class.Event Listeners
Plug in
CircuitBreakerListener subclasses to hook into before_call, success, failure, and state_change events — ideal for logging, metrics, and alerting.Excluded Exceptions
Distinguish business errors from system errors using the
exclude parameter. Excluded exceptions won’t increment the failure counter, so a 404 Not Found won’t trip your circuit.Redis-Backed Distributed State
Use
CircuitRedisStorage to share circuit state across multiple processes or hosts, enabling a truly distributed circuit breaker without additional infrastructure.Tornado Async Support
Optional integration with Tornado coroutines via
call_async and the __pybreaker_call_async decorator keyword, available when tornado is installed.Generator Function Support
Correctly handles generator functions — the circuit breaker tracks successes and failures across the full lifetime of a generator, not just the initial call.
Thread-Safe by Design
All state mutations are guarded by a
threading.RLock, making CircuitBreaker instances safe to share across threads without any additional synchronization.Fully Type-Annotated
Ships with complete type annotations and a
py.typed marker, providing accurate IDE autocompletion and full compatibility with mypy and other static type checkers.Project Information
PyBreaker requires Python 3.9 or later and is released under the BSD-3-Clause license. It has no required dependencies — Redis and Tornado support are both optional extras.- PyPI:
pip install pybreaker - GitHub: https://github.com/danielfm/pybreaker
- License: BSD-3-Clause
Ready to protect your first integration point? Head over to the Quickstart to be up and running in under 5 minutes.