CircuitBreakerError and State Constants

PyBreaker exposes a single exception class — CircuitBreakerError — and three string constants that represent the circuit’s possible states. Understanding both is essential for writing correct error-handling code and for initialising or inspecting storage backends.

CircuitBreakerError

CircuitBreakerError inherits directly from Exception. It is raised in two distinct situations:

A call is made to a function protected by an already-open circuit. The breaker short-circuits immediately without invoking the guarded function and raises CircuitBreakerError with the message "Timeout not elapsed yet, circuit breaker still open".
The circuit trips (i.e., the failure count reaches fail_max) and throw_new_error_on_trip=True (the default). The breaker opens and raises CircuitBreakerError with the message "Failures threshold reached, circuit breaker opened".

import pybreaker

try:
    result = db_breaker.call(query_db)
except pybreaker.CircuitBreakerError:
    # Circuit is open — fail fast and serve a fallback
    result = get_from_cache()
except Exception as e:
    # A real error from the guarded function (circuit still closed)
    raise

When throw_new_error_on_trip=False, the original exception is re-raised at the moment the circuit trips, so the first failing call that opens the breaker will surface the underlying error rather than a CircuitBreakerError. However, all subsequent calls while the circuit remains open will still raise CircuitBreakerError. Keep this asymmetry in mind when writing catch blocks.

State Constants

PyBreaker exports three string constants that represent the three possible circuit states:

pybreaker.STATE_CLOSED    # 'closed'    — Normal operation; calls pass through
pybreaker.STATE_OPEN      # 'open'      — Failing fast; calls raise CircuitBreakerError
pybreaker.STATE_HALF_OPEN # 'half-open' — Trial call allowed; outcome determines next state

Always use these constants rather than raw string literals so your code stays correct if the underlying values ever change and to benefit from IDE autocompletion. They are useful in three contexts: Initialising storage backends:

storage = pybreaker.CircuitMemoryStorage(pybreaker.STATE_CLOSED)

Setting a Redis fallback state:

pybreaker.CircuitRedisStorage(
    pybreaker.STATE_CLOSED,
    redis_conn,
    fallback_circuit_state=pybreaker.STATE_CLOSED,
)

Inspecting the current state at runtime:

if db_breaker.current_state == pybreaker.STATE_OPEN:
    return serve_from_cache()

All Public Exports

All public symbols can be imported directly from the pybreaker package:

from pybreaker import (
    CircuitBreaker,
    CircuitBreakerListener,
    CircuitBreakerError,
    CircuitMemoryStorage,
    CircuitRedisStorage,
    STATE_OPEN,
    STATE_CLOSED,
    STATE_HALF_OPEN,
)

Classes

CircuitBreakerError and State Constants — PyBreaker