{"id":1416,"library":"circuitbreaker","title":"Python Circuit Breaker","description":"A Python implementation of the Circuit Breaker pattern, designed to prevent applications from repeatedly trying to perform an operation that is likely to fail. It supports both synchronous and asynchronous functions and has been classified as a 'Critical Project' on PyPI. The current version is 2.1.3.","status":"active","version":"2.1.3","language":"en","source_language":"en","source_url":"https://github.com/fabfuel/circuitbreaker","tags":["circuit breaker","resilience","fault tolerance","async","design pattern"],"install":[{"cmd":"pip install circuitbreaker","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.7 or newer. Python 2.x is no longer supported since version 2.0.0.","package":"Python","optional":false}],"imports":[{"note":"Commonly used as a decorator for functions (both sync and async) to apply circuit breaker logic.","symbol":"circuit","correct":"from circuitbreaker import circuit"},{"note":"The class for creating custom circuit breaker instances or for more advanced control.","symbol":"CircuitBreaker","correct":"from circuitbreaker import CircuitBreaker"},{"note":"The exception raised when the circuit is open and a protected function is called.","symbol":"CircuitBreakerError","correct":"from circuitbreaker import CircuitBreakerError"}],"quickstart":{"code":"import time\nfrom circuitbreaker import circuit\n\n# Define a service call that might fail\ndef unreliable_service():\n    # Simulate failure 75% of the time\n    if time.time() % 4 < 3:\n        raise ConnectionError(\"Service is currently unavailable!\")\n    print(\"Service call successful!\")\n    return \"Data from service\"\n\n# Decorate the unreliable service call with a circuit breaker\n# Trips after 3 failures, resets after 5 seconds\n@circuit(fail_max=3, reset_timeout=5, exclude=[ValueError])\ndef get_data():\n    return unreliable_service()\n\nprint(\"--- Circuit Breaker Quickstart ---\")\nfor i in range(10):\n    print(f\"Attempt {i+1}:\")\n    try:\n        result = get_data()\n        print(f\"  Result: {result}\")\n    except ConnectionError as e: # Handle the underlying service error\n        print(f\"  Caught service error: {e}\")\n    except Exception as e: # Catch CircuitBreakerError or other unexpected errors\n        print(f\"  Caught general error from circuit: {e}\")\n    time.sleep(1)","lang":"python","description":"This example demonstrates how to use the `@circuit` decorator to protect a potentially unreliable synchronous function. It configures the circuit to trip after 3 failures (`fail_max=3`) and attempt to reset after 5 seconds (`reset_timeout=5`). It also shows how to exclude certain exceptions from tripping the circuit and handling both the underlying service errors and `CircuitBreakerError` when the circuit is open."},"warnings":[{"fix":"Upgrade your Python environment to 3.7 or newer before upgrading `circuitbreaker` to version 2.0.0 or later.","message":"Version 2.0.0 completely dropped support for Python 2.x and early Python 3 versions. Applications running on Python 2.x or Python 3.x prior to 3.7 will break upon upgrade.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use the `exceptions` parameter in the `@circuit` decorator or `CircuitBreaker` constructor (e.g., `@circuit(exceptions=ConnectionError)`) to specify the types of exceptions that should cause the circuit to trip. Alternatively, use `exclude` for exceptions that should *not* trip the circuit.","message":"By default, the `@circuit` decorator (and `CircuitBreaker` class without `exceptions` specified) will trip on *any* `Exception`. This can be overly broad; it's often better to specify which exceptions should trip the circuit to avoid tripping on non-recoverable or expected errors.","severity":"gotcha","affected_versions":"All"},{"fix":"Carefully review the documentation for `fail_max` (number of failures before opening), `reset_timeout` (time in seconds to wait before transitioning to HALF_OPEN), and `recovery_timeout` (time for HALF_OPEN to attempt recovery). Adjust these parameters based on the expected behavior and recovery time of your external service.","message":"Misconfiguring `fail_max`, `reset_timeout`, or `recovery_timeout` (for HALF_OPEN state) can lead to a circuit that never opens, opens too frequently, or stays open indefinitely. Understanding the state transitions is crucial.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}