Purgatory

https://mardiros.github.io/purgatory/
Admin
Purgatory is a Python library that implements the circuit breaker pattern for robust failure...
Tokens:9,109
Snippets:112
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Configure SyncCircuitBreakerFactory with Redis

Source: https://mardiros.github.io/purgatory/user/storage_backend.html

Example of configuring a synchronous circuit breaker factory using Redis as the unit of work. The `initialize` method is autogenerated but cannot be used for synchronous clients.

```python
import requests
from purgatory import SyncCircuitBreakerFactory, SyncRedisUnitOfWork

circuit_breaker = SyncCircuitBreakerFactory(
   default_threshold=5,
   default_ttl=30,
   exclude=[
      (requests.HTTPError, lambda exc: 400 <= exc.response.status_code < 500),
   ],
   uow=SyncRedisUnitOfWork("redis://localhost/0"),
)


```

--------------------------------

### Install Redis extra dependency

Source: https://mardiros.github.io/purgatory/user/storage_backend.html

Install the 'redis' extra dependency for Purgatory to enable Redis support. This is required for both asynchronous and synchronous APIs.

```bash
pip install "purgatory[redis]"

```

--------------------------------

### Configure AsyncCircuitBreakerFactory with Redis

Source: https://mardiros.github.io/purgatory/user/storage_backend.html

Example of configuring an asynchronous circuit breaker factory using Redis as the unit of work. The `initialize` coroutine must be called to set up the Redis connection.

```python
import httpx
from purgatory import AsyncCircuitBreakerFactory, AsyncRedisUnitOfWork

circuit_breaker = AsyncCircuitBreakerFactory(
   default_threshold=5,
   default_ttl=30,
   exclude=[
      (httpx.HTTPStatusError, lambda exc: exc.response.is_client_error),
   ],
   uow=AsyncRedisUnitOfWork("redis://localhost/0"),
)

await circuit_breaker.initialize()

```

--------------------------------

### Configure Async Redis Unit of Work

Source: https://mardiros.github.io/purgatory/_sources/user/storage_backend.rst.txt

Use this snippet to configure an asynchronous circuit breaker factory with a Redis unit of work. Ensure the 'redis' extra dependency is installed. The 'initialize' coroutine must be called to set up the Redis connection.

```python
import httpx
from purgatory import AsyncCircuitBreakerFactory, AsyncRedisUnitOfWork

circuit_breaker = AsyncCircuitBreakerFactory(
   default_threshold=5,
   default_ttl=30,
   exclude=[
      (httpx.HTTPStatusError, lambda exc: exc.response.is_client_error),
   ],
   uow=AsyncRedisUnitOfWork("redis://localhost/0"),
)

await circuit_breaker.initialize()
```

--------------------------------

### Using circuit breaker with async context manager

Source: https://mardiros.github.io/purgatory/_sources/user/introduction.rst.txt

Utilize an AsyncCircuitBreakerFactory within an async context manager to perform an HTTP GET request. The circuit breaker automatically registers and manages the circuit for 'www.example.com'.

```python
async with await circuitbreaker.get_breaker("www.example.com"):
   async with httpx.AsyncClient() as client:
       r = await client.get('https://www.example.com/')

```

--------------------------------

### Initialize AsyncCircuitBreakerFactory

Source: https://mardiros.github.io/purgatory/user/introduction.html

Create an asynchronous circuit breaker factory with default settings for failure threshold and time-to-live. Optionally exclude specific exceptions from being counted as failures.

```python
import httpx
from purgatory import AsyncCircuitBreakerFactory

circuitbreaker = AsyncCircuitBreakerFactory(
   default_threshold=5,
   default_ttl=30,
   exclude=[
      (httpx.HTTPStatusError, lambda exc: exc.response.is_client_error),
   ]
)

```

--------------------------------

### Configure Sync Redis Unit of Work

Source: https://mardiros.github.io/purgatory/_sources/user/storage_backend.rst.txt

This snippet shows how to set up a synchronous circuit breaker factory with a Redis unit of work. The 'redis' extra dependency is required. Note that the 'initialize' method is autogenerated for the synchronous client but cannot be used.

```python
import requests
from purgatory import SyncCircuitBreakerFactory, SyncRedisUnitOfWork

circuit_breaker = SyncCircuitBreakerFactory(
   default_threshold=5,
   default_ttl=30,
   exclude=[
      (requests.HTTPError, lambda exc: 400 <= exc.response.status_code < 500),
   ],
   uow=SyncRedisUnitOfWork("redis://localhost/0"),
)
```

--------------------------------

### AsyncInMemoryRepository Methods

Source: https://mardiros.github.io/purgatory/develop/service/repository.html

Implementation of an asynchronous circuit breaker repository using in-memory storage.

```APIDOC
## AsyncInMemoryRepository

### Description
An asynchronous in-memory implementation of the circuit breaker repository.

### Methods

#### `async _get(name: str)`

##### Description
Retrieves a circuit breaker context from the in-memory store.

##### Parameters
- **name** (str) - Required - The name of the circuit breaker to retrieve.

##### Returns
- `Context | None` - The circuit breaker context if found, otherwise None.

#### `async _register(context: Context)`

##### Description
Adds a circuit breaker context to the in-memory store.

##### Parameters
- **context** (Context) - Required - The circuit breaker context to register.

#### `async _update_state(name: str, state: str, opened_at: float | None)`

##### Description
Updates the state of an existing circuit breaker in the in-memory store. Since `_get` returns the object directly, this method might have no-op behavior depending on the internal object mutability.

##### Parameters
- **name** (str) - Required - The name of the circuit breaker.
- **state** (str) - Required - The new state of the circuit breaker.
- **opened_at** (float | None) - Optional - The timestamp when the circuit breaker was opened.

#### `async _inc_failures(name: str, failure_count: int)`

##### Description
Increments the failure count for a circuit breaker in the in-memory store. This might have no-op behavior as the `_get` method returns the object directly.

##### Parameters
- **name** (str) - Required - The name of the circuit breaker.
- **failure_count** (int) - Required - The number of failures to increment.

#### `async _reset_failure(name: str)`

##### Description
Resets the failure count for a circuit breaker in the in-memory store.

##### Parameters
- **name** (str) - Required - The name of the circuit breaker.
```

--------------------------------

### Sync Context Manager for Circuit Breaker

Source: https://mardiros.github.io/purgatory

This snippet demonstrates using a circuit breaker as a context manager for synchronous API calls. Import SyncCircuitBreakerFactory to utilize this.

```python
from purgatory import SyncCircuitBreakerFactory

circuitbreaker = SyncCircuitBreakerFactory()
with circuitbreaker.get_breaker("my_circuit"):
   ...
```

--------------------------------

### AsyncRedisRepository Methods

Source: https://mardiros.github.io/purgatory/develop/service/repository.html

Implementation of an asynchronous circuit breaker repository using Redis.

```APIDOC
## AsyncRedisRepository

### Description
An asynchronous Redis-based implementation of the circuit breaker repository.

### Initialization

#### `__init__(url: str)`

##### Parameters
- **url** (str) - Required - The connection URL for the Redis instance.

### Methods

#### `async initialize()`

##### Description
Override to initialize the repository asynchronously, potentially establishing a connection to Redis.

#### `async _get(name: str)`

##### Description
Retrieves a circuit breaker context from the Redis store.

##### Parameters
- **name** (str) - Required - The name of the circuit breaker to retrieve.

##### Returns
- `Context | None` - The circuit breaker context if found, otherwise None.

#### `async _register(context: Context)`

##### Description
Adds a circuit breaker context to the Redis store.

##### Parameters
- **context** (Context) - Required - The circuit breaker context to register.

#### `async _update_state(name: str, state: str, opened_at: float | None)`

##### Description
Stores the new state of the circuit breaker in the Redis repository.

##### Parameters
- **name** (str) - Required - The name of the circuit breaker.
- **state** (str) - Required - The new state of the circuit breaker.
- **opened_at** (float | None) - Optional - The timestamp when the circuit breaker was opened.

#### `async _inc_failures(name: str, failure_count: int)`

##### Description
Stores the updated failure count for the circuit breaker in the Redis repository.

##### Parameters
- **name** (str) - Required - The name of the circuit breaker.
- **failure_count** (int) - Required - The number of failures to increment.

#### `async _reset_failure(name: str)`

##### Description
Resets the failure count for a circuit breaker in the Redis repository.

##### Parameters
- **name** (str) - Required - The name of the circuit breaker.
```

--------------------------------

### Override default circuit breaker configuration

Source: https://mardiros.github.io/purgatory/_sources/user/introduction.rst.txt

Use the circuit breaker with overridden threshold and TTL values for a specific circuit named 'www.example.net'. Note that the first registered circuit configures subsequent ones.

```python
async with await circuitbreaker.get_breaker("www.example.net", threshold=7, ttl=42):
   async with httpx.AsyncClient() as client:
       r = await client.get('https://www.example.net/')

```

--------------------------------

### AsyncAbstractRepository Methods

Source: https://mardiros.github.io/purgatory/develop/service/repository.html

Abstract methods defining the interface for asynchronous circuit breaker repositories. These methods must be implemented by concrete repository classes.

```APIDOC
## AsyncAbstractRepository

### Description
Abstract base class for asynchronous circuit breaker repositories. Defines the interface for managing circuit breaker states and configurations.

### Methods

#### `async initialize()`

##### Description
Override to initialize the repository asynchronously.

#### `async _get(name: str)`

##### Description
Load breakers from the repository.

##### Parameters
- **name** (str) - Required - The name of the circuit breaker to retrieve.

##### Returns
- `Context | None` - The circuit breaker context if found, otherwise None.

#### `async _register(context: Context)`

##### Description
Add a circuit breaker into the repository.

##### Parameters
- **context** (Context) - Required - The circuit breaker context to register.

#### `async _update_state(name: str, state: str, opened_at: float | None)`

##### Description
Update the new state of the circuit breaker in the repository.

##### Parameters
- **name** (str) - Required - The name of the circuit breaker.
- **state** (str) - Required - The new state of the circuit breaker.
- **opened_at** (float | None) - Optional - The timestamp when the circuit breaker was opened.

#### `async _inc_failures(name: str, failure_count: int)`

##### Description
Increment the number of failures for the circuit breaker in the repository.

##### Parameters
- **name** (str) - Required - The name of the circuit breaker.
- **failure_count** (int) - Required - The number of failures to increment.

#### `async _reset_failure(name: str)`

##### Description
Reset the number of failures for the circuit breaker in the repository.

##### Parameters
- **name** (str) - Required - The name of the circuit breaker.
```

--------------------------------

### AsyncCircuitBreakerFactory with httpx exclusion

Source: https://mardiros.github.io/purgatory/_sources/user/introduction.rst.txt

Initialize an AsyncCircuitBreakerFactory with default failure threshold and TTL, excluding client errors from httpx responses.

```python
import httpx
from purgatory import AsyncCircuitBreakerFactory

circuitbreaker = AsyncCircuitBreakerFactory(
   default_threshold=5,
   default_ttl=30,
   exclude=[
      (httpx.HTTPStatusError, lambda exc: exc.response.is_client_error),
   ]
)
```

--------------------------------

### SyncRedisRepository

Source: https://mardiros.github.io/purgatory/develop/service/repository.html

Redis-backed implementation of the synchronous circuit breaker repository.

```APIDOC
## SyncRedisRepository(_url : str_)

### Description
Redis-backed implementation of the synchronous circuit breaker repository.

### Methods
- **initialize()** -> None: Override to initialize the repository asynchronously.
- **get(_name : str_)** -> Context | None: Add a circuit breaker into the repository.
- **register(_context : Context_)** -> None: Add a circuit breaker into the repository.
- **update_state(_name : str_, _state : str_, _opened_at : float | None_)** -> None: Store the new state in the repository.
- **inc_failures(_name : str_, _failure_count : int_)** -> None: Store the new state in the repository.
- **reset_failure(_name : str_)** -> None: Reset the number of failure in the repository.
```

--------------------------------

### SyncInMemoryRepository

Source: https://mardiros.github.io/purgatory/develop/service/repository.html

In-memory implementation of the synchronous circuit breaker repository.

```APIDOC
## SyncInMemoryRepository

### Description
In-memory implementation of the synchronous circuit breaker repository.

### Methods
- **get(_name : str_)** -> Context | None: Add a circuit breaker into the repository.
- **register(_context : Context_)** -> None: Add a circuit breaker into the repository.
- **update_state(_name : str_, _state : str_, _opened_at : float | None_)** -> None: Because the get method return the object directly, nothing to do here.
- **inc_failures(_name : str_, _failure_count : int_)** -> None: Because the get method return the object directly, nothing to do here.
- **reset_failure(_name : str_)** -> None: Reset the number of failure in the repository.
```

--------------------------------

### SyncAbstractRepository

Source: https://mardiros.github.io/purgatory/develop/service/repository.html

Abstract base class for synchronous circuit breaker repositories. Defines the interface for managing circuit breaker states.

```APIDOC
## SyncAbstractRepository

### Description
Abstract base class for synchronous circuit breaker repositories. Defines the interface for managing circuit breaker states.

### Methods
- **initialize()** -> None: Override to initialize the repository asynchronously.
- **get(_name : str_)** -> Context | None: Load breakers from the repository.
- **register(_context : Context_)** -> None: Add a circuit breaker into the repository.
- **update_state(_name : str_, _state : str_, _opened_at : float | None_)** -> None: State the new state of the circuit breaker into the repository.
- **inc_failures(_name : str_, _failure_count : int_)** -> None: Increment the number of failure in the repository.
- **reset_failure(_name : str_)** -> None: Reset the number of failure in the repository.
```

--------------------------------

### AsyncMessageRegistry.handle

Source: https://mardiros.github.io/purgatory/develop/service/messagebus.html

Notifies listeners of an event registered with messagebus.add_listener. It returns the first event from the command processed by the listeners.

```APIDOC
## AsyncMessageRegistry.handle

### Description
Notifies listeners of an event registered with messagebus.add_listener. It returns the first event from the command processed by the listeners.

### Method
```
_async _handle(_message : Message_, _uow : AsyncAbstractUnitOfWork_)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **Any** - The first event from the command.

#### Response Example
None
```

--------------------------------

### SyncMessageRegistry.handle

Source: https://mardiros.github.io/purgatory/develop/service/messagebus.html

Notifies listeners of an event registered with messagebus.add_listener. It returns the first event from the command processed by the listeners.

```APIDOC
## SyncMessageRegistry.handle

### Description
Notifies listeners of an event registered with messagebus.add_listener. It returns the first event from the command processed by the listeners.

### Method
```
handle(_message : Message_, _uow : SyncAbstractUnitOfWork_)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **Any** - The first event from the command.

#### Response Example
None
```

--------------------------------

### AsyncRedisUnitOfWork

Source: https://mardiros.github.io/purgatory/develop/service/unit_of_work.html

An asynchronous Unit of Work implementation using Redis. It overrides initialization and provides no-op implementations for commit and rollback.

```APIDOC
## AsyncRedisUnitOfWork

### Description
An asynchronous Unit of Work implementation using Redis. It overrides initialization and provides no-op implementations for commit and rollback.

### Parameters
- **`_url`** (str) - The URL for the Redis connection.

### Methods
- **`initialize()`**: Initializes repositories.
- **`commit()`**: Does nothing.
- **`rollback()`**: Does nothing.
```

--------------------------------

### SyncRedisUnitOfWork

Source: https://mardiros.github.io/purgatory/develop/service/unit_of_work.html

A synchronous Unit of Work implementation using Redis. It overrides initialization and provides no-op implementations for commit and rollback.

```APIDOC
## SyncRedisUnitOfWork

### Description
A synchronous Unit of Work implementation using Redis. It overrides initialization and provides no-op implementations for commit and rollback.

### Parameters
- **`_url`** (str) - The URL for the Redis connection.

### Methods
- **`initialize()`**: Initializes repositories.
- **`commit()`**: Does nothing.
- **`rollback()`**: Does nothing.
```

--------------------------------

### Async Context Manager for Circuit Breaker

Source: https://mardiros.github.io/purgatory

Use this snippet to manage potential failures in asynchronous operations using a circuit breaker as a context manager. It requires importing AsyncCircuitBreakerFactory.

```python
from purgatory import AsyncCircuitBreakerFactory

circuitbreaker = AsyncCircuitBreakerFactory()
async with await circuitbreaker.get_breaker("my_circuit"):
   ...
```

--------------------------------

### SyncCircuitBreakerFactory

Source: https://mardiros.github.io/purgatory/develop/service/circuitbreaker.html

Factory for creating and managing synchronous circuit breakers. Allows adding and removing listeners for circuit breaker events.

```APIDOC
## SyncCircuitBreakerFactory

### Description
Factory for creating and managing synchronous circuit breakers. Allows adding and removing listeners for circuit breaker events.

### Methods

*   **`initialize()`**
    Initializes the factory.

*   **`add_listener(listener)`**
    Adds a listener to receive notifications about circuit breaker events.
    - **listener** (Callable) - The callback function to be called on events.

*   **`remove_listener(listener)`**
    Removes a previously added listener.
    - **listener** (Callable) - The listener function to remove.

*   **`get_breaker(circuit, threshold, ttl, exclude)`**
    Retrieves or creates a synchronous circuit breaker.
    - **circuit** (str) - The name of the circuit.
    - **threshold** (int, optional) - The number of failures before tripping the circuit.
    - **ttl** (float, optional) - The time-to-live for the circuit breaker state in seconds.
    - **exclude** (list, optional) - Exceptions to exclude from tripping the circuit.
    Returns: SyncCircuitBreaker
```

--------------------------------

### Prometheus Hook for Circuit Breaker Metrics

Source: https://mardiros.github.io/purgatory/_sources/user/monitoring.rst.txt

This hook collects circuit breaker state changes and errors, exposing them as Prometheus metrics. It requires the 'prometheus_client' library and should be registered with an AsyncCircuitBreakerFactory.

```python
from prometheus_client import Counter, Gauge
from purgatory import AsyncCircuitBreakerFactory


class GaugeStateValue:
   CLOSED = 0
   HALF_OPEN = 1
   OPEN = 2


class PrometheusHook:
   def __init__(self):
      circuit_breaker_error = Counter(
         "circuit_breaker_error",
         "Count the circuit breaker exception raised",
         labelnames=["circuit"],
      )

      circuit_breaker_state = Gauge(
         "circuit_breaker_state",
         "State of the circuit breaker. 0 is closed, 1 is half-opened, 2 is opened.",
         labelnames=["circuit"],
      )

   def __call__(self, circuit_name: str, evt_type: str, payload: Any) -> None:
      if evt_type == "state_changed":
            state = {
               "closed": GaugeStateValue.CLOSED,
               "half-opened": GaugeStateValue.HALF_OPEN,
               "opened": GaugeStateValue.OPEN,
            }[payload.state]
            self.prometheus_metrics.blacksmith_circuit_breaker_state.labels(
               circuit_name
            ).set(state)
      elif evt_type == "failed":
            self.prometheus_metrics.blacksmith_circuit_breaker_error.labels(
               circuit_name
            ).inc()


circuitbreaker = AsyncCircuitBreakerFactory()
circuitbreaker.add_listener(PrometheusHook())
```

--------------------------------

### SyncAbstractUnitOfWork

Source: https://mardiros.github.io/purgatory/develop/service/unit_of_work.html

Abstract base class for synchronous Unit of Work implementations. It defines the interface for managing repositories and transaction operations.

```APIDOC
## SyncAbstractUnitOfWork

### Description
Abstract base class for synchronous Unit of Work implementations. It defines the interface for managing repositories and transaction operations.

### Methods
- **`contexts()`**: Returns the associated repositories.
- **`collect_new_events()`**: Collects new events as a generator.
- **`initialize()`**: Initializes repositories (override in subclasses).
- **`commit()`**: Commits the transaction (abstract, must be implemented).
- **`rollback()`**: Rolls back the transaction (abstract, must be implemented).
```

--------------------------------

### CreateCircuitBreaker Command

Source: https://mardiros.github.io/purgatory/develop/domain/messages.html

Represents a command to create a new circuit breaker with a specified name, threshold, and time-to-live.

```APIDOC
## CreateCircuitBreaker Command

### Description

This command is used to initiate the creation of a circuit breaker.

### Parameters

#### Request Body

- **name** (str) - Required - The unique name of the circuit breaker.
- **threshold** (int) - Required - The number of failures allowed before the circuit breaker trips.
- **ttl** (float) - Required - The time-to-live for the circuit breaker in seconds.
```

--------------------------------

### AsyncCircuitBreakerFactory

Source: https://mardiros.github.io/purgatory/develop/service/circuitbreaker.html

Factory for creating and managing asynchronous circuit breakers. Allows adding and removing listeners for circuit breaker events.

```APIDOC
## AsyncCircuitBreakerFactory

### Description
Factory for creating and managing asynchronous circuit breakers. Allows adding and removing listeners for circuit breaker events.

### Methods

*   **`initialize()`**
    Initializes the factory.

*   **`add_listener(listener)`**
    Adds a listener to receive notifications about circuit breaker events.
    - **listener** (Callable) - The callback function to be called on events.

*   **`remove_listener(listener)`**
    Removes a previously added listener.
    - **listener** (Callable) - The listener function to remove.

*   **`get_breaker(circuit, threshold, ttl, exclude)`**
    Retrieves or creates an asynchronous circuit breaker.
    - **circuit** (str) - The name of the circuit.
    - **threshold** (int, optional) - The number of failures before tripping the circuit.
    - **ttl** (float, optional) - The time-to-live for the circuit breaker state in seconds.
    - **exclude** (list, optional) - Exceptions to exclude from tripping the circuit.
    Returns: AsyncCircuitBreaker
```

--------------------------------

### AsyncAbstractUnitOfWork

Source: https://mardiros.github.io/purgatory/develop/service/unit_of_work.html

Abstract base class for asynchronous Unit of Work implementations. It defines the interface for managing repositories and transaction operations.

```APIDOC
## AsyncAbstractUnitOfWork

### Description
Abstract base class for asynchronous Unit of Work implementations. It defines the interface for managing repositories and transaction operations.

### Methods
- **`contexts()`**: Returns the associated repositories.
- **`collect_new_events()`**: Collects new events as a generator.
- **`initialize()`**: Initializes repositories (override in subclasses).
- **`commit()`**: Commits the transaction (abstract, must be implemented).
- **`rollback()`**: Rolls back the transaction (abstract, must be implemented).
```

--------------------------------

### AsyncInMemoryUnitOfWork

Source: https://mardiros.github.io/purgatory/develop/service/unit_of_work.html

An in-memory implementation of the asynchronous Unit of Work. It provides no-op implementations for commit and rollback.

```APIDOC
## AsyncInMemoryUnitOfWork

### Description
An in-memory implementation of the asynchronous Unit of Work. It provides no-op implementations for commit and rollback.

### Methods
- **`commit()`**: Does nothing.
- **`rollback()`**: Does nothing.
```

--------------------------------

### SyncMessageRegistry.add_listener

Source: https://mardiros.github.io/purgatory/develop/service/messagebus.html

Adds a listener callback for a specific message type to the synchronous message registry. This callback will be invoked when a message of the specified type is handled.

```APIDOC
## SyncMessageRegistry.add_listener

### Description
Adds a listener callback for a specific message type to the synchronous message registry. This callback will be invoked when a message of the specified type is handled.

### Method
```
add_listener(_msg_type : type[Message]_, _callback : Callable[[Any, SyncAbstractUnitOfWork], Any] | Callable[[Any, SyncAbstractUnitOfWork], None]_)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### Decorating a function with a circuit breaker

Source: https://mardiros.github.io/purgatory/_sources/user/introduction.rst.txt

Apply a circuit breaker as a decorator to an asynchronous function. This method is elegant but has restrictions on static circuit names.

```python
@circuitbreaker("www.example.com")
async def get_page():
   async with httpx.AsyncClient() as client:
       r = await client.get('https://www.example.com/')

```

--------------------------------

### SyncInMemoryUnitOfWork

Source: https://mardiros.github.io/purgatory/develop/service/unit_of_work.html

A synchronous in-memory implementation of the Unit of Work. It provides no-op implementations for commit and rollback.

```APIDOC
## SyncInMemoryUnitOfWork

### Description
A synchronous in-memory implementation of the Unit of Work. It provides no-op implementations for commit and rollback.

### Methods
- **`commit()`**: Does nothing.
- **`rollback()`**: Does nothing.
```

--------------------------------

### Sync Message Handlers

Source: https://mardiros.github.io/purgatory/develop/service/message_handlers.html

Synchronous handlers for processing circuit breaker related messages.

```APIDOC
## Sync Handlers

### `register_circuit_breaker(_cmd : CreateCircuitBreaker_, _uow : SyncAbstractUnitOfWork_) -> Context`

#### Description
Register circuit breaker in the repository when receiving the CreateCircuitBreaker command.

### `save_circuit_breaker_state(_evt : ContextChanged_, _uow : SyncAbstractUnitOfWork_) -> None`

#### Description
Save the circuit breaker state in the repository when receiving the ContextChanged event.

### `inc_circuit_breaker_failure(_evt : CircuitBreakerFailed_, _uow : SyncAbstractUnitOfWork_) -> None`

#### Description
Increment the number of failures in the repository when receiving the CircuitBreakerFailed event.

### `reset_failure(_evt : CircuitBreakerRecovered_, _uow : SyncAbstractUnitOfWork_) -> None`

#### Description
Reset the number of failures in the repository when receiving the CircuitBreakerRecovered event.
```

--------------------------------

### Async Message Handlers

Source: https://mardiros.github.io/purgatory/develop/service/message_handlers.html

Asynchronous handlers for processing circuit breaker related messages.

```APIDOC
## Async Handlers

### `register_circuit_breaker(_cmd : CreateCircuitBreaker_, _uow : AsyncAbstractUnitOfWork_) -> Context`

#### Description
Register circuit breaker in the repository when receiving the CreateCircuitBreaker command.

### `save_circuit_breaker_state(_evt : ContextChanged_, _uow : AsyncAbstractUnitOfWork_) -> None`

#### Description
Save the circuit breaker state in the repository when receiving the ContextChanged event.

### `inc_circuit_breaker_failure(_evt : CircuitBreakerFailed_, _uow : AsyncAbstractUnitOfWork_) -> None`

#### Description
Increment the number of failures in the repository when receiving the CircuitBreakerFailed event.

### `reset_failure(_evt : CircuitBreakerRecovered_, _uow : AsyncAbstractUnitOfWork_) -> None`

#### Description
Reset the number of failures in the repository when receiving the CircuitBreakerRecovered event.
```

--------------------------------

### Async Decorator for Circuit Breaker

Source: https://mardiros.github.io/purgatory

Apply this decorator to asynchronous functions to automatically manage failures with a circuit breaker. Ensure AsyncCircuitBreakerFactory is imported.

```python
from purgatory import AsyncCircuitBreakerFactory

circuitbreaker = AsyncCircuitBreakerFactory()

@circuitbreaker("another circuit")
async def function_that_may_fail():
   ...
```

--------------------------------

### AsyncMessageRegistry.add_listener

Source: https://mardiros.github.io/purgatory/develop/service/messagebus.html

Adds a listener callback for a specific message type to the asynchronous message registry. This callback will be invoked when a message of the specified type is handled.

```APIDOC
## AsyncMessageRegistry.add_listener

### Description
Adds a listener callback for a specific message type to the asynchronous message registry. This callback will be invoked when a message of the specified type is handled.

### Method
```
add_listener(_msg_type : type[Message]_, _callback : Callable[[Any, AsyncAbstractUnitOfWork], Coroutine[Any, Any, Any]] | Callable[[Any, AsyncAbstractUnitOfWork], Coroutine[Any, Any, None]]_)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### ContextChanged Event

Source: https://mardiros.github.io/purgatory/develop/domain/messages.html

An event indicating a change in the state of a circuit breaker's context.

```APIDOC
## ContextChanged Event

### Description

This event signals a change in the operational state of a circuit breaker.

### Parameters

#### Response Body

- **name** (str) - The name of the circuit breaker whose context has changed.
- **state** (Literal['opened', 'closed', 'half-opened']) - The new state of the circuit breaker.
- **opened_at** (float | None) - The timestamp when the circuit breaker entered the 'opened' state, if applicable.
```

--------------------------------

### CircuitBreakerCreated Event

Source: https://mardiros.github.io/purgatory/develop/domain/messages.html

An event indicating that a circuit breaker has been successfully created.

```APIDOC
## CircuitBreakerCreated Event

### Description

This event is published when a circuit breaker is successfully created.

### Parameters

#### Response Body

- **name** (str) - The name of the created circuit breaker.
- **threshold** (int) - The failure threshold configured for the circuit breaker.
- **ttl** (float) - The time-to-live for the circuit breaker.
```

--------------------------------

### CircuitBreakerFailed Event

Source: https://mardiros.github.io/purgatory/develop/domain/messages.html

An event indicating that a circuit breaker has failed.

```APIDOC
## CircuitBreakerFailed Event

### Description

This event is triggered when a circuit breaker experiences a failure.

### Parameters

#### Response Body

- **name** (str) - The name of the circuit breaker that failed.
- **failure_count** (int) - The current count of consecutive failures.
```

--------------------------------

### CircuitBreakerRecovered Event

Source: https://mardiros.github.io/purgatory/develop/domain/messages.html

An event indicating that a circuit breaker has recovered from a failed state.

```APIDOC
## CircuitBreakerRecovered Event

### Description

This event is published when a circuit breaker successfully recovers from a fault state.

### Parameters

#### Response Body

- **name** (str) - The name of the circuit breaker that has recovered.
```

--------------------------------

### SyncMessageRegistry.remove_listener

Source: https://mardiros.github.io/purgatory/develop/service/messagebus.html

Removes a listener callback for a specific message type from the synchronous message registry. This prevents the callback from being invoked for future messages of that type.

```APIDOC
## SyncMessageRegistry.remove_listener

### Description
Removes a listener callback for a specific message type from the synchronous message registry. This prevents the callback from being invoked for future messages of that type.

### Method
```
remove_listener(_msg_type : type_, _callback : Callable[[Any, SyncAbstractUnitOfWork], Any] | Callable[[Any, SyncAbstractUnitOfWork], None]_)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### AsyncMessageRegistry.remove_listener

Source: https://mardiros.github.io/purgatory/develop/service/messagebus.html

Removes a listener callback for a specific message type from the asynchronous message registry. This prevents the callback from being invoked for future messages of that type.

```APIDOC
## AsyncMessageRegistry.remove_listener

### Description
Removes a listener callback for a specific message type from the asynchronous message registry. This prevents the callback from being invoked for future messages of that type.

### Method
```
remove_listener(_msg_type : type_, _callback : Callable[[Any, AsyncAbstractUnitOfWork], Coroutine[Any, Any, Any]] | Callable[[Any, AsyncAbstractUnitOfWork], Coroutine[Any, Any, None]]_)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None
```
Tokens:
Raw