Circuit Breaker

Threadsafe pure-Python implementation of the Circuit Breaker pattern, described by Michael T. Nygard in his book ‘Release It!’.

For more information on this and other patterns and best practices, buy the book at https://pragprog.com/titles/mnee2/release-it-second-edition/

CircuitBreaker

class aiobreaker.circuitbreaker.CircuitBreaker(fail_max=5, timeout_duration=None, exclude=None, listeners=None, state_storage=None, name=None)

Bases: object

A circuit breaker is a route through which functions are executed. When a function is executed via a circuit breaker, the breaker is notified. Multiple failed attempts will open the breaker and block additional calls.

__init__(fail_max=5, timeout_duration=None, exclude=None, listeners=None, state_storage=None, name=None)

Creates a new circuit breaker with the given parameters.

Parameters

• fail_max – The maximum number of failures for the breaker.

• timeout_duration (Optional[timedelta]) – The timeout to elapse for a breaker to close again.

• exclude (Optional[Iterable[Union[Callable, Type[Exception]]]]) – A list of excluded Exception types to ignore.

• listeners (Optional[Iterable[CircuitBreakerListener]]) – A list of CircuitBreakerListener

• state_storage (Optional[CircuitBreakerStorage]) – A type of storage. Defaults to CircuitMemoryStorage

property fail_counter

Returns the current number of consecutive failures.

property fail_max

Returns the maximum number of failures tolerated before the circuit is opened.

property timeout_duration

Once this circuit breaker is opened, it should remain opened until the timeout period elapses.

property opens_at: Optional[datetime.datetime]

Gets the remaining timeout for a breaker.

Return type

Optional[datetime]

property time_until_open: Optional[datetime.timedelta]

Returns a timedelta representing the difference between the current time and when the breaker closes again, or None if it has elapsed.

Return type

Optional[timedelta]

async sleep_until_open()

property state

Update (if needed) and returns the cached state object.

property current_state: aiobreaker.state.CircuitBreakerState

Returns a CircuitBreakerState that identifies the state of the circuit breaker.

Return type

CircuitBreakerState

property excluded_exceptions: tuple

Returns a tuple of the excluded exceptions, e.g., exceptions that should not be considered system errors by this circuit breaker.

Return type

tuple

add_excluded_exception(exception)

Adds an exception to the list of excluded exceptions.

add_excluded_exceptions(*exceptions)

Adds exceptions to the list of excluded exceptions.

Parameters

exceptions – Any Exception types you wish to ignore.

remove_excluded_exception(exception)

Removes an exception from the list of excluded exceptions.

is_system_error(exception)

Returns whether the exception exception is considered a signal of system malfunction. Business exceptions should not cause this circuit breaker to open.

call(func, *args, **kwargs)

Calls func with the given args and kwargs according to the rules implemented by the current state of this circuit breaker.

async call_async(func, *args, **kwargs)

Calls func with the given args and kwargs according to the rules implemented by the current state of this circuit breaker.

open()

Opens the circuit, e.g., the following calls will immediately fail until timeout elapses.

half_open()

Half-opens the circuit, e.g. lets the following call pass through and opens the circuit if the call fails (or closes the circuit if the call succeeds).

close()

Closes the circuit, e.g. lets the following calls execute as usual.

__call__(*call_args, ignore_on_call=True)

Decorates the function such that calls are handled according to the rules implemented by the current state of this circuit breaker.

Parameters

ignore_on_call – Whether the decorated function should be ignored when using call(), preventing the breaker being triggered twice.

property listeners

Returns the registered listeners as a tuple.

add_listener(listener)

Registers a listener for this circuit breaker.

add_listeners(*listeners)

Registers listeners for this circuit breaker.

remove_listener(listener)

Unregisters a listener of this circuit breaker.

property name: str

Returns the name of this circuit breaker. Useful for logging.

Return type

str

Listener

class aiobreaker.listener.CircuitBreakerListener

Bases: object

Listener class used to plug code to a CircuitBreaker instance when certain events happen.

todo async listener handlers

before_call(breaker, func, *args, **kwargs)

Called before a function is executed over a breaker.

Parameters

• breaker (CircuitBreaker) – The breaker that is used.

• func (Callable) – The function that is called.

• args – The args to the function.

• kwargs – The kwargs to the function.

Return type

None

failure(breaker, exception)

Called when a function executed over the circuit breaker ‘breaker’ fails.

Return type

None

success(breaker)

Called when a function executed over the circuit breaker ‘breaker’ succeeds.

Return type

None

state_change(breaker, old, new)

Called when the state of the circuit breaker ‘breaker’ changes.

Return type

None

State

exception aiobreaker.state.CircuitBreakerError(message, reopen_time)

Bases: Exception

Raised when the function fails due to the breaker being open.

__init__(message, reopen_time)

Parameters

• message (str) – The reasoning.

• reopen_time (datetime) – When the breaker re-opens.

property time_remaining: datetime.timedelta

Return type

timedelta

async sleep_until_open()

class aiobreaker.state.CircuitBreakerBaseState(breaker, state)

Bases: abc.ABC

Implements the behavior needed by all circuit breaker states.

__init__(breaker, state)

Creates a new instance associated with the circuit breaker cb and identified by name.

property state: aiobreaker.state.CircuitBreakerState

Returns a human friendly name that identifies this state.

Return type

CircuitBreakerState

call(func, *args, **kwargs)

Calls func with the given args and kwargs, and updates the circuit breaker state according to the result.

Return type

~T

async call_async(func, *args, **kwargs)

Return type

Awaitable[~T]

generator_call(wrapped_generator)

before_call(func, *args, **kwargs)

Override this method to be notified before a call to the guarded operation is attempted.

on_success()

Override this method to be notified when a call to the guarded operation succeeds.

on_failure(exception)

Override this method to be notified when a call to the guarded operation fails.

class aiobreaker.state.CircuitClosedState(breaker, prev_state=None, notify=False)

Bases: aiobreaker.state.CircuitBreakerBaseState

In the normal “closed” state, the circuit breaker executes operations as usual. If the call succeeds, nothing happens. If it fails, however, the circuit breaker makes a note of the failure.

Once the number of failures exceeds a threshold, the circuit breaker trips and “opens” the circuit.

__init__(breaker, prev_state=None, notify=False)

Moves the given circuit breaker to the “closed” state.

on_failure(exception)

Moves the circuit breaker to the “open” state once the failures threshold is reached.

class aiobreaker.state.CircuitOpenState(breaker, prev_state=None, notify=False)

Bases: aiobreaker.state.CircuitBreakerBaseState

When the circuit is “open”, calls to the circuit breaker fail immediately, without any attempt to execute the real operation. This is indicated by the CircuitBreakerError exception.

After a suitable amount of time, the circuit breaker decides that the operation has a chance of succeeding, so it goes into the “half-open” state.

__init__(breaker, prev_state=None, notify=False)

Moves the given circuit breaker to the “open” state.

before_call(func, *args, **kwargs)

After the timeout elapses, move the circuit breaker to the “half-open” state. :raises CircuitBreakerError: if the timeout has still to be elapsed.

call(func, *args, **kwargs)

Call before_call to check if the breaker should close and open it if it passes.

async call_async(func, *args, **kwargs)

Call before_call to check if the breaker should close and open it if it passes.

class aiobreaker.state.CircuitHalfOpenState(breaker, prev_state=None, notify=False)

Bases: aiobreaker.state.CircuitBreakerBaseState

In the “half-open” state, the next call to the circuit breaker is allowed to execute the dangerous operation. Should the call succeed, the circuit breaker resets and returns to the “closed” state. If this trial call fails, however, the circuit breaker returns to the “open” state until another timeout elapses.

__init__(breaker, prev_state=None, notify=False)

Moves the given circuit breaker to the “half-open” state.

on_failure(exception)

Opens the circuit breaker.

on_success()

Closes the circuit breaker.

class aiobreaker.state.CircuitBreakerState(value)

Bases: enum.Enum

An enumeration.

OPEN = <class 'aiobreaker.state.CircuitOpenState'>

CLOSED(breaker, prev_state=None, notify=False) = <class 'aiobreaker.state.CircuitClosedState'>

HALF_OPEN = <class 'aiobreaker.state.CircuitHalfOpenState'>

Version

aiobreaker.version.short_version = '1.1'

A short version.