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.

In a distributed system, your application constantly reaches out to things it doesn’t fully control — databases, message queues, third-party APIs, microservices. When one of those dependencies starts failing or slowing down, calls pile up: threads block waiting for responses that never arrive, connection pools fill to capacity, and memory climbs. What started as a problem in one downstream service cascades upward until the calling service becomes unresponsive too. The Circuit Breaker pattern exists to stop that cascade before it starts.

​
The Pattern

A circuit breaker acts as a smart proxy that wraps every integration point in your application. Rather than letting your code call a dependency directly, every call passes through the breaker. Under normal conditions the breaker is transparent — it simply forwards the call and returns the result. The breaker watches for failures. Each time the guarded function raises an exception that qualifies as a system error, the breaker increments an internal failure counter. Once that counter reaches a configured threshold, the breaker trips: it opens the circuit and begins rejecting all incoming calls immediately, without ever invoking the guarded function. Instead of waiting for a slow or broken service to time out, callers receive an error instantly and can choose a fallback path. After a configured timeout the breaker allows a single trial call through — the half-open state. If that call succeeds, the breaker closes and normal traffic resumes. If it fails, the breaker opens again and the timeout restarts. This automatic probe-and-recover loop means the system heals itself without human intervention.

​
The Analogy

The name comes directly from the electrical world. When a fault causes excess current to flow through a circuit, a physical breaker trips — it breaks the circuit before the surge can start a fire or destroy connected equipment. An electrician inspects the problem, fixes the fault, then manually resets the breaker to restore power. A software circuit breaker works the same way. When a downstream service is causing damage to your system, the breaker trips and breaks the connection before the failure can spread. After a timeout it tentatively closes again (the equivalent of the electrician resetting the switch), and if the downstream service has recovered, normal operation resumes automatically.

​
Key Terminology

TermParameterDescription
Failure thresholdfail_maxThe number of consecutive system errors required to trip (open) the circuit. Defaults to 5.
Reset timeoutreset_timeoutSeconds the circuit stays open before the breaker transitions to half-open and allows a trial call. Defaults to 60.
Success thresholdsuccess_thresholdNumber of consecutive successful trial calls in half-open state required before the circuit closes. Defaults to 1.
Trip—The event of the circuit opening because fail_counter reached fail_max.
Trial call—The single call allowed through when the breaker is in the half-open state, used to probe whether the downstream service has recovered.

​
Benefits

  • Prevents cascading failures — a broken dependency can’t drag down the services that depend on it.
  • Fails fast — callers get an immediate error instead of blocking until a slow service times out, freeing threads and connections.
  • Provides automatic recovery — the half-open probe mechanism closes the circuit again without any operator action once the downstream service is healthy.
  • Gives downstream systems time to recover — the open state stops the flood of traffic that would otherwise hammer an already-struggling service.
  • Enables observability via state change events — PyBreaker’s CircuitBreakerListener fires callbacks on every state transition, giving you hooks for metrics, alerting, and logging.

​
In PyBreaker

PyBreaker is a threadsafe, pure-Python implementation of the Circuit Breaker pattern, as described by Michael T. Nygard in Release It!. The central class is CircuitBreaker. You create an instance — optionally giving it a fail_max, reset_timeout, success_threshold, and a list of exceptions to exclude — then use it to wrap any callable: 
import pybreaker

db_breaker = pybreaker.CircuitBreaker(
    fail_max=5,
    reset_timeout=60,
    success_threshold=1,
)

# Wrap a function call
result = db_breaker.call(query_database, user_id=42)

# Or use it as a decorator
@db_breaker
def query_database(user_id):
    ...
When the circuit opens, PyBreaker raises CircuitBreakerError so you can distinguish between “the downstream service failed” and “the circuit is open, skip the call entirely”. The breaker transitions through three states — closed, open, and half-open — automatically, with manual override methods (open(), half_open(), close()) available for operational use.

Circuit Breaker States

Understand how PyBreaker transitions between the closed, open, and half-open states.

Failure Detection

Learn how PyBreaker counts failures, excludes business exceptions, and resets counters.

Build docs developers (and LLMs) love

Get started for freeTalk to us