Metadata-Version: 2.4
Name: asyncbreaker
Version: 2.1.0
Summary: Asyncio Circuit Breaker pattern with optional Redis storage.
Project-URL: Source, https://github.com/freemspwnz/asyncbreaker
Project-URL: Telegram, https://t.me/freems
Author: Sergey Turbinov
License-Expression: BSD-3-Clause
License-File: license.md
Keywords: asyncio,circuit-breaker,redis,resilience
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Provides-Extra: redis
Requires-Dist: redis>=5; extra == 'redis'
Provides-Extra: test
Requires-Dist: fakeredis>=2.21; extra == 'test'
Requires-Dist: mypy>=1.8; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest-cov>=5; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: ruff>=0.9; extra == 'test'
Description-Content-Type: text/markdown

# asyncbreaker

**asyncbreaker** is an **asyncio-first** Python implementation of the Circuit Breaker pattern
from Michael T. Nygard's book [Release It!](https://pragprog.com/titles/mnee2/release-it-second-edition/).

Circuit breakers let one subsystem fail without taking down the whole application: you wrap
risky calls (often I/O or integration boundaries) so that repeated failures **trip** the breaker,
subsequent calls fail fast for a **reset timeout**, then a single **trial** call may close
the circuit again.

## Lineage

- **[pybreaker](https://github.com/danielfm/pybreaker)** (Daniel Fernandes Martins) — original design.
- **aiobreaker fork** (Alexander Lyon) — asyncio instead of Tornado, packaging experiments.
- **Current line** — maintained by Sergey Turbinov; substantial rewrite toward a pure async API,
  async storage, and async listeners. Contact: [@freems](https://t.me/freems) on Telegram.

## Features

- Async `CircuitBreaker` — use `await breaker.call(...)`
- Configurable failure threshold (`fail_max`) and reset window (`timeout_duration`)
- Excluded exceptions and predicate callables (business vs system errors)
- Multiple **async** `Listener` instances
- Pluggable **async** storage: in-process memory or Redis via `redis.asyncio`
- Optional `redis` extra for Redis-backed storage

## Requirements

Python **3.10+** (async patterns and typing used throughout).

## Installation

```bash
pip install asyncbreaker
```

With Redis support (`redis` package):

```bash
pip install asyncbreaker[redis]
```

## Usage

Create a breaker per integration point. Only **async** callables are supported; the decorator
rejects ordinary `def` functions.

```python
from datetime import timedelta

from asyncbreaker import CircuitBreaker

api_breaker = CircuitBreaker(fail_max=5, timeout_duration=timedelta(seconds=60))

@api_breaker
async def fetch_remote():
    ...

# or explicitly:
await api_breaker.call(fetch_remote)
```

See `changelog.md` for the full API story (listeners, storage, `open` / `close` / `half_open`,
exclusion rules). A MkDocs site will be added later.

## Development

This project uses [uv](https://docs.astral.sh/uv/):

```bash
uv sync
uv run pytest test
```

## License

BSD 3-Clause; see `license.md`. This project bundles copyright from the pybreaker lineage;
additional copyright applies to the asyncio rewrite (see `license.md`).
