proxywhirl.circuit_breaker.async

Async circuit breaker implementation with RWLock for reduced contention.

This is the async-first implementation that uses AsyncRWLock for better performance in high-concurrency scenarios.

Classes

AsyncCircuitBreaker

Async circuit breaker for a single proxy with RWLock for high concurrency.

Module Contents

class proxywhirl.circuit_breaker.async_.AsyncCircuitBreaker(/, **data)

Bases: proxywhirl.circuit_breaker.base.CircuitBreakerBase

Async circuit breaker for a single proxy with RWLock for high concurrency.

This is the ASYNCHRONOUS implementation designed for async/await contexts. Uses AsyncRWLock for event-loop-safe operations with reduced lock contention.

Key Features:

• Event-loop safe: All methods are async and use asyncio-compatible locks

• High concurrency: RWLock allows multiple readers or single writer

• Zero blocking: Never blocks the event loop with synchronous operations

For synchronous contexts, use CircuitBreaker from circuit_breaker module instead.

Parameters:

data (Any)

proxy_id

Unique identifier for the proxy

state

Current circuit breaker state (CLOSED, OPEN, HALF_OPEN)

failure_count

Number of failures in current window

failure_threshold

Number of failures before opening circuit

window_duration

Rolling window duration in seconds

timeout_duration

How long circuit stays open before testing recovery

Example

>>> from proxywhirl.circuit_breaker_async import AsyncCircuitBreaker
>>> cb = AsyncCircuitBreaker(proxy_id="proxy-1")
>>> await cb.record_failure()  # Event-loop safe
>>> if await cb.should_attempt_request():
...     # make async request
...     await cb.record_success()

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod create(proxy_id, config=None, **kwargs)

Factory method to create a circuit breaker with optional config.

Parameters:

• proxy_id (str) – Unique identifier for the proxy

• config (proxywhirl.models.CircuitBreakerConfig | None) – CircuitBreakerConfig with settings

• **kwargs (Any) – Additional AsyncCircuitBreaker field overrides

Returns:

AsyncCircuitBreaker instance

Return type:

AsyncCircuitBreaker

classmethod from_config(proxy_id, config=None, **kwargs)

Backward-compatible alias for create().

Parameters:

• proxy_id (str)

• config (proxywhirl.models.CircuitBreakerConfig | None)

• kwargs (Any)

Return type:

AsyncCircuitBreaker

async record_failure()

Record a failure and update state if threshold reached.

Return type:

None

async record_success()

Record a success and potentially close circuit.

Return type:

None

async reset()

Manually reset circuit breaker to CLOSED state.

Return type:

None

async should_attempt_request()

Check if proxy is available for requests.

Uses write lock to prevent TOCTOU race conditions.

Returns:

True if proxy should be attempted, False if circuit is open.

Return type:

bool