Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Python implementation of the Circuit Breaker pattern

Project description

PyBreaker is a Python implementation of the Circuit Breaker pattern, described in Michael T. Nygard’s book Release It!.

In Nygard’s words, “circuit breakers exists to allow one subsystem to fail without destroying the entire system. This is done by wrapping dangerous operations (typically integration points) with a component that can circumvent calls when the system is not healthy”.


  • Configurable list of excluded exceptions (e.g. business exceptions)
  • Configurable failure threshold and reset timeout
  • Support for several event listeners per circuit breaker
  • Can guard generator functions
  • Functions and properties for easy monitoring and management
  • Thread-safe
  • Optional redis backing
  • Optional support for asynchronous Tornado calls


  • Python 2.7+ (or Python 3.0+)


Run the following command line to download the latest stable version of PyBreaker from PyPI:

$ easy_install -U pybreaker

If you are a Git user, you might want to download the current development version:

$ git clone git://
$ cd pybreaker
$ python test
$ python install


The first step is to create an instance of CircuitBreaker for each integration point you want to protect against:

import pybreaker

# Used in database integration points
db_breaker = pybreaker.CircuitBreaker(fail_max=5, reset_timeout=60)

CircuitBreaker instances should live globally inside the application scope, e.g., live across requests.


Integration points to external services (i.e. databases, queues, etc) are more likely to fail, so make sure to always use timeouts when accessing such services if there’s support at the API level.

If you’d like to use the Redis backing, initialize the CircuitBreaker with a CircuitRedisStorage:

import pybreaker
import redis

redis = redis.StrictRedis()
db_breaker = pybreaker.CircuitBreaker(
    state_storage=pybreaker.CircuitRedisStorage(pybreaker.STATE_CLOSED, redis))


You may want to reuse a connection already created in your application, if you’re using django_redis for example:

import pybreaker
from django_redis import get_redis_connection

db_breaker = pybreaker.CircuitBreaker(
    state_storage=pybreaker.CircuitRedisStorage(pybreaker.STATE_CLOSED, get_redis_connection('default')))

Event Listening

There’s no need to subclass CircuitBreaker if you just want to take action when certain events occur. In that case, it’s better to subclass CircuitBreakerListener instead:

class DBListener(pybreaker.CircuitBreakerListener):
    "Listener used by circuit breakers that execute database operations."

    def before_call(self, cb, func, *args, **kwargs):
        "Called before the circuit breaker `cb` calls `func`."

    def state_change(self, cb, old_state, new_state):
        "Called when the circuit breaker `cb` state changes."

    def failure(self, cb, exc):
        "Called when a function invocation raises a system error."

    def success(self, cb):
        "Called when a function invocation succeeds."

class LogListener(pybreaker.CircuitBreakerListener):
    "Listener used to log circuit breaker events."

    def state_change(self, cb, old_state, new_state):
        msg = "State Change: CB: {0}, New State: {1}".format(, new_state)

To add listeners to a circuit breaker:

# At creation time...
db_breaker = pybreaker.CircuitBreaker(listeners=[DBListener(), LogListener()])

# ...or later
db_breaker.add_listeners(OneListener(), AnotherListener())

What Does a Circuit Breaker Do?

Let’s say you want to use a circuit breaker on a function that updates a row in the customer database table:

def update_customer(cust):
    # Do stuff here...

# Will trigger the circuit breaker
updated_customer = update_customer(my_customer)

Or if you don’t want to use the decorator syntax:

def update_customer(cust):
    # Do stuff here...

# Will trigger the circuit breaker
updated_customer =, my_customer)

According to the default parameters, the circuit breaker db_breaker will automatically open the circuit after 5 consecutive failures in update_customer.

When the circuit is open, all calls to update_customer will fail immediately (raising CircuitBreakerError) without any attempt to execute the real operation.

After 60 seconds, the circuit breaker will allow the next call to update_customer pass through. If that call succeeds, the circuit is closed; if it fails, however, the circuit is opened again until another timeout elapses.

Optional Tornado Support

A circuit breaker can (optionally) be used to call asynchronous Tornado functions:

from tornado import gen

def async_update(cust):
    # Do async stuff here...

Or if you don’t want to use the decorator syntax:

def async_update(cust):
    # Do async stuff here...

updated_customer = db_breaker.call_async(async_update, my_customer)

Excluding Exceptions

By default, a failed call is any call that raises an exception. However, it’s common to raise exceptions to also indicate business exceptions, and those exceptions should be ignored by the circuit breaker as they don’t indicate system errors:

# At creation time...
db_breaker = CircuitBreaker(exclude=[CustomerValidationError])

# ...or later

In that case, when any function guarded by that circuit breaker raises CustomerValidationError (or any exception derived from CustomerValidationError), that call won’t be considered a system failure.

So as to cover cases where the exception class alone is not enough to determine whether it represents a system error, you may also pass a callable rather than a type:

db_breaker = CircuitBreaker(exclude=[lambda e: type(e) == HTTPError and e.status_code < 500])

You may mix types and filter callables freely.

Monitoring and Management

A circuit breaker provides properties and functions you can use to monitor and change its current state:

# Get the current number of consecutive failures
print db_breaker.fail_counter

# Get/set the maximum number of consecutive failures
print db_breaker.fail_max
db_breaker.fail_max = 10

# Get/set the current reset timeout period (in seconds)
print db_breaker.reset_timeout
db_breaker.reset_timeout = 60

# Get the current state, i.e., 'open', 'half-open', 'closed'
print db_breaker.current_state

# Closes the circuit

# Half-opens the circuit

# Opens the circuit

These properties and functions might and should be exposed to the operations staff somehow as they help them to detect problems in the system.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pybreaker, version 0.6.0
Filename, size File type Python version Upload date Hashes
Filename, size pybreaker-0.6.0.tar.gz (10.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page