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 uses pluggable storage backends to persist circuit breaker state and counters. The default CircuitMemoryStorage keeps everything in local process memory — zero dependencies, zero configuration. CircuitRedisStorage stores state in Redis, enabling multiple processes or service instances to share a single circuit breaker state, which is essential in distributed deployments.

​
CircuitBreakerStorage (Abstract Base)

CircuitBreakerStorage defines the interface that all storage backends must implement. You can build a custom backend by subclassing it and providing concrete implementations for every abstract member.
​
state
str
Abstract get/set property. Returns the current state string — one of 'closed', 'open', or 'half-open'. Setting this property persists the new state to the underlying storage.
​
counter
int
Abstract read-only property. Returns the current failure count.
​
success_counter
int
Abstract read-only property. Returns the current consecutive-success count (relevant in half-open state).
​
opened_at
datetime | None
Abstract get/set property. Returns the UTC datetime at which the circuit was most recently opened, or None if the circuit has never been opened. Setting this property records when the circuit tripped.
MethodDescription
increment_counter()Increase the failure counter by one.
reset_counter()Reset the failure counter to zero.
increment_success_counter()Increase the success counter by one.
reset_success_counter()Reset the success counter to zero.

​
CircuitMemoryStorage

CircuitMemoryStorage is the default backend. State and counters are stored as plain Python attributes — there are no external dependencies and no I/O overhead.

​
Constructor

pybreaker.CircuitMemoryStorage(state: str)
​
state
str
required
The initial circuit state. Use one of the exported constants:
  • pybreaker.STATE_CLOSED — normal operation (recommended default)
  • pybreaker.STATE_OPEN — start in the open/failing-fast state
  • pybreaker.STATE_HALF_OPEN — start in the trial-call state

​
Example

import pybreaker

# Explicit construction (identical to the automatic default)
storage = pybreaker.CircuitMemoryStorage(pybreaker.STATE_CLOSED)
db_breaker = pybreaker.CircuitBreaker(state_storage=storage)
Each process has its own memory. State is not shared across processes, threads (beyond the single CircuitBreaker instance), or restarts. If you run multiple worker processes behind a load balancer, each process maintains an independent breaker state. Use CircuitRedisStorage for shared state.

​
CircuitRedisStorage

CircuitRedisStorage persists circuit breaker state in Redis, making it suitable for distributed deployments where multiple processes or hosts need to observe and react to a shared breaker state. Requires the redis package to be installed. An ImportError is raised at instantiation if it is not available.

​
Constructor

pybreaker.CircuitRedisStorage(
    state,
    redis_object,
    namespace=None,
    fallback_circuit_state=STATE_CLOSED,
    cluster_mode=False,
)
​
state
str
required
The initial circuit state to write into Redis if the key does not already exist (uses Redis SETNX). Accepts the same constants as CircuitMemoryStorage: pybreaker.STATE_CLOSED, pybreaker.STATE_OPEN, or pybreaker.STATE_HALF_OPEN.
​
redis_object
redis.StrictRedis
required
A configured redis.StrictRedis (or compatible) client instance.
Do not create the Redis client with decode_responses=True. PyBreaker decodes byte responses internally; enabling automatic decoding will cause unexpected errors.
​
namespace
str | None
An optional string prefix that is prepended to every Redis key managed by this storage instance. Required when multiple independent circuit breakers share the same Redis connection — without a namespace their keys will collide.See the key format table below for details.
​
fallback_circuit_state
str
default:"STATE_CLOSED"
The state to report when a RedisError is raised during a read. Defaults to STATE_CLOSED (treat the system as healthy when Redis is unreachable). Set to STATE_OPEN for a fail-closed policy.
​
cluster_mode
bool
default:"false"
Set to True when using Redis Cluster. In cluster mode the storage uses simple GET/SET commands instead of MULTI/EXEC transactions (which are not supported across cluster slots) when updating opened_at.

​
Redis Key Format

namespaceExample key
None (no namespace)pybreaker:state, pybreaker:fail_counter, pybreaker:success_counter, pybreaker:opened_at
"my-service-db"my-service-db:pybreaker:state, my-service-db:pybreaker:fail_counter, …

​
Example

import pybreaker
import redis

redis_conn = redis.StrictRedis(host='localhost', port=6379, db=0)

db_breaker = pybreaker.CircuitBreaker(
    fail_max=5,
    reset_timeout=60,
    state_storage=pybreaker.CircuitRedisStorage(
        pybreaker.STATE_CLOSED,
        redis_conn,
        namespace='my-service-db',
        fallback_circuit_state=pybreaker.STATE_CLOSED,
    )
)

​
Custom Storage

To use a different persistence layer (e.g., Memcached, a SQL database, or a distributed key-value store), subclass CircuitBreakerStorage and provide concrete implementations for all abstract properties and methods:
  • state (property + setter)
  • counter (property)
  • success_counter (property)
  • opened_at (property + setter)
  • increment_counter()
  • reset_counter()
  • increment_success_counter()
  • reset_success_counter()
Pass an instance of your custom class to the state_storage parameter of CircuitBreaker.

Build docs developers (and LLMs) love

Get started for freeTalk to us