# API reference

## Policies

- `Policy`, `AsyncPolicy`
  - Unified resilience containers; use `Policy(retry=Retry(...))`
  - `.call(func, on_metric=None, on_log=None, operation=None, abort_if=None, sleep=None, before_sleep=None, sleeper=None, on_attempt_start=None, on_attempt_end=None)`
  - `.execute(func, on_metric=None, on_log=None, operation=None, abort_if=None, sleep=None, before_sleep=None, sleeper=None, on_attempt_start=None, on_attempt_end=None, capture_timeline=False)`
  - `.context(on_metric=None, on_log=None, operation=None, abort_if=None, sleep=None, before_sleep=None, sleeper=None, on_attempt_start=None, on_attempt_end=None)`
- `Retry`, `AsyncRetry`
  - Retry components with `result_classifier` support
  - Support per-attempt timeouts via `attempt_timeout_s`
  - `.call(..., abort_if=None, sleep=None, before_sleep=None, sleeper=None, on_attempt_start=None, on_attempt_end=None)`
  - `.execute(..., abort_if=None, sleep=None, before_sleep=None, sleeper=None, on_attempt_start=None, on_attempt_end=None, capture_timeline=False)`
  - `.context(..., abort_if=None, sleep=None, before_sleep=None, sleeper=None, on_attempt_start=None, on_attempt_end=None)`
  - `.from_config(config, classifier=...)`
- `RetryPolicy`, `AsyncRetryPolicy`
  - Backward-compatible sugar for `Policy(retry=Retry(...))`
  - `.call(..., abort_if=None, sleep=None, before_sleep=None, sleeper=None, on_attempt_start=None, on_attempt_end=None)`
  - `.execute(..., abort_if=None, sleep=None, before_sleep=None, sleeper=None, on_attempt_start=None, on_attempt_end=None, capture_timeline=False)`
  - `.context(..., abort_if=None, sleep=None, before_sleep=None, sleeper=None, on_attempt_start=None, on_attempt_end=None)`
- `CircuitBreaker`
  - State machine with open/half-open/closed transitions
  - `failure_threshold=5` failures in `window_s=60.0` seconds to open
  - `recovery_timeout_s=30.0` before half-open probe
  - `trip_on` set of ErrorClass values that count (default: TRANSIENT, SERVER_ERROR)
  - `class_thresholds` per-class override thresholds
  - `clock` optional monotonic clock override
  - Use with `Policy(circuit_breaker=...)`
- `CircuitState` enum
## Budgets

- `Budget(max_retries, window_s)` for shared retry limits across policies

## Decorator

- `retry`
  - Defaults: `classifier=default_classifier`, `strategy=decorrelated_jitter(max_s=5.0)`
  - Works on sync and async callables

## Classifiers

- `default_classifier`
- `strict_classifier`
- `http_classifier`, `http_retry_after_classifier`
- `sqlstate_classifier`, `pyodbc_classifier`
- Optional extras: `aiohttp_classifier`, `grpc_classifier`, `boto3_classifier`, `redis_classifier`, `urllib3_classifier`
- `Classification` dataclass for structured classifier outputs

## Strategies

- `decorrelated_jitter`
- `equal_jitter`
- `token_backoff`
- `retry_after_or`
- `adaptive`
- `BackoffContext` for context-aware strategy functions

## Errors

- `ErrorClass` enum
- `CircuitOpenError` fail-fast error when breaker is open
- `StopReason` enum
- `RetryExhaustedError` terminal error (result-based exhaustion)
- `AbortRetryError` cooperative abort signal (alias: `AbortRetry`)
- Marker exceptions: `PermanentError`, `RateLimitError`, `ConcurrencyError`, `ServerError`

## Outcomes

- `RetryOutcome[T]` from `execute()` with attempts, stop_reason, and last error info
- `RetryOutcome.next_sleep_s` when retries are deferred via a sleep handler
- `RetryOutcome.timeline` contains a `RetryTimeline` when `capture_timeline=True`
- `RetryTimeline` with `TimelineEvent` entries (attempt, event, stop_reason, cause, sleep_s, elapsed_s)
- `capture_timeline` accepts `True` or a `RetryTimeline` instance to reuse a collector

## Metrics helpers

- `prometheus_metric_hook(counter)`
- `otel_metric_hook(meter, name="redress_attempts")`
- `redress.contrib.otel.otel_hooks(tracer=None, meter=None)` (spans + metrics)

## Events

- `EventName` enum (`redress.events.EventName`) for hook event constants
- `StopReason` enum is re-exported from `redress.events`

## Sleep handlers

- `SleepDecision` enum (`sleep`, `defer`, `abort`)
- `SleepFn` for custom sleep handling (decide sleep/defer/abort)
- `BeforeSleepHook` / `AsyncBeforeSleepHook` run right before an actual sleep
- `SleeperFn` / `AsyncSleeperFn` replace the actual sleep call

## Testing utilities

Available under `redress.testing`:

- `DeterministicStrategy`, `instant_retries`, `no_retries`
- `RecordingPolicy`, `FakePolicy`
- `FakeCircuitBreaker`, `BreakerDecision`
