🌿 tranq

Calm, production-grade error handling & resilience for Python — decorator-based, zero boilerplate.

  

🧘 Why tranq?

Writing repetitive try/except blocks clutters your code and hides business logic. tranq gives you declarative error handling and a full resilience toolkit — retries, circuit breakers, rate limits, bulkheads, hedging, timeouts, budgets, metrics and more — so you focus on what your code does, not how it recovers from failure.

📦 Installation

pip install tranq

Optional integrations:

pip install tranq[rich]         # pretty logging
pip install tranq[sentry]       # Sentry reporter
pip install tranq[slack]        # Slack reporter
pip install tranq[prometheus]   # Prometheus reporter
pip install tranq[all]          # everything

⚡ Quick Start

import tranq

@tranq.handle(on=ConnectionError, retry=3, delay=0.5, backoff=2.0, timeout=5.0)
def fetch():
    ...

@tranq.handle_async(on=TimeoutError, retry=2, fallback=lambda: "offline")
async def fetch_async():
    ...

🔍 Features in Depth

Retry with Backoff

@tranq.handle(on=TimeoutError, retry=5, delay=0.1, backoff=2.0,
              backoff_strategy="exponential", max_delay=10.0, jitter=True)
def fetch(): ...

Timeout

@tranq.handle(on=Exception, retry=2, timeout=3.0)   # raises FunctionTimeoutError
def slow(): ...

Event Hooks

@tranq.handle(on=ValueError, retry=3,
              on_retry=lambda e, n: print(f"retry {n}"),
              on_success=lambda r: print("ok"),
              on_failure=lambda e: print("failed"),
              on_complete=lambda: print("done"))
def work(): ...

Circuit Breaker (count-based & sliding-window)

cb  = tranq.CircuitBreaker(failure_threshold=5, timeout=60)
swc = tranq.SlidingWindowCircuitBreaker(window_size=100,
                                        failure_rate_threshold=0.5,
                                        minimum_calls=10)

@tranq.handle(circuit_breaker=swc)
def call_service(): ...

Rate Limiter

@tranq.rate_limit(rate=10, per=1.0, burst=20)
def api_call(): ...

Bulkhead

@tranq.bulkhead(max_concurrent=5, timeout=1.0)
def limited(): ...

Retry Budget

budget = tranq.RetryBudget(ttl=60, ratio=0.2, min_tokens=10)

@tranq.handle(on=Exception, retry=5, retry_budget=budget)
def protected(): ...

Hedged Requests (async)

@tranq.hedged(hedge_delay=0.1, max_hedges=2)
async def fast_fetch(): ...

Async Context Manager

async with tranq.retry_async(on=ConnectionError, retry=3) as ctx:
    result = await ctx.run(my_async_func, arg)

Metrics & Statistics

@tranq.handle(metrics=True, metric_prefix="svc")
def op(): ...

print(tranq.summary_table())      # aligned table with p50/p95/p99
print(tranq.overall_health())     # {'status': 'healthy', ...}

Reporters

reporters = [
    tranq.FileReporter("errors.jsonl"),
    tranq.LogReporter(),
    tranq.SentryReporter(dsn="..."),
    tranq.SlackReporter(webhook_url="..."),
    tranq.PrometheusReporter(),
]

@tranq.handle(on=Exception, reporters=reporters)
def critical(): ...

📚 API Reference

Decorators

• tranq.handle(on, retry, delay, backoff, backoff_strategy, max_delay, jitter, fallback, reraise, log_level, message, policy, retry_if, retry_on_result, on_error, metrics, metric_prefix, circuit_breaker, stateful, reporters, inject, timeout, on_retry, on_success, on_failure, on_complete, retry_budget)
• tranq.handle_async(...) — same parameters for async def.

Standalone decorators

• tranq.rate_limit(rate, per=1.0, burst=None, timeout=None, raise_on_limit=True)
• tranq.bulkhead(max_concurrent, timeout=None, raise_on_full=True)
• tranq.hedged(hedge_delay=0.1, max_hedges=2)
• tranq.profile / tranq.async_profile

Context managers

• tranq.retry(...) → ctx.run(func, *args, **kwargs)
• tranq.retry_async(...) → async with + await ctx.run(...)

Circuit breakers

• tranq.CircuitBreaker(failure_threshold, timeout, half_open_requests) + .reset()
• tranq.AsyncCircuitBreaker(...) + .reset()
• tranq.SlidingWindowCircuitBreaker(window_size, failure_rate_threshold, timeout, half_open_requests, minimum_calls)
• tranq.AsyncSlidingWindowCircuitBreaker(...)

Resilience primitives

• tranq.RateLimiter(rate, per, burst) / .acquire() / .acquire_async()
• tranq.Bulkhead(max_concurrent, timeout) / tranq.AsyncBulkhead(...)
• tranq.RetryBudget(ttl, ratio, min_tokens) / .allow_retry() / .record_call()
• tranq.hedged_call(func, args, kwargs, hedge_delay, max_hedges)

Metrics & statistics

• tranq.get_metrics() → count, errors, total/avg/min/max, error_rate, p50/p95/p99
• tranq.reset_metrics()
• tranq.summary_table() / tranq.overall_health() / tranq.render_report()
• tranq.get_profile(name=None)

Global policy

• tranq.set_global_policy(tranq.Policy(...)) / tranq.get_global_policy()

Exceptions

📁 Examples

The examples/ directory contains 29 runnable examples (01–29) covering every feature, including the new ones: timeouts, hooks, rate limiting, bulkheads, retry budgets, hedging, sliding-window breakers, statistics and retry_async.

python examples/run_all.py

🧪 Testing

The suite contains 135+ tests (sync, async, thread-safety).

pip install pytest "pytest-asyncio>=0.24"
pytest tests/ -v

⚖️ Comparison

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md.

📄 License

MIT © RaptorVampire