Metadata-Version: 2.4
Name: wyolet-api-tools
Version: 0.0.1
Summary: Stateful FastAPI primitives — rate limit, distributed lock, idempotency keys — sharing one Backend protocol.
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# wyolet-api-tools

Stateful FastAPI primitives — rate limit, distributed lock, idempotency keys — sharing one `Backend` protocol. Memory or Redis today; sqlite and postgres on the roadmap.

First package under the [`wyolet`](https://wyolet.com) umbrella.

```bash
uv add wyolet-api-tools
```

## Why

Every FastAPI project ends up reinventing the same primitives. The existing packages are each scoped to one of them — slowapi for rate limiting, redlock-py for locks, aiocache for caching — each with its own backend abstraction and lifecycle quirks. `wyolet.api_tools` unifies them: write one backend, get every primitive that needs state.

## Quickstart

```python
from fastapi import FastAPI, Depends
from wyolet.api_tools.backends.redis import RedisBackend
from wyolet.api_tools.ratelimit import RateLimit
from wyolet.api_tools.lock import Lock
from wyolet.api_tools.idempotency import Idempotency

backend = RedisBackend("redis://localhost")

app = FastAPI()

@app.post("/transfer", dependencies=[Depends(RateLimit(backend, "10/minute"))])
async def transfer(...):
    async with Lock(backend, key=f"user:{user_id}", ttl=30):
        ...

@app.post("/charge", dependencies=[Depends(Idempotency(backend, ttl=3600))])
async def charge(...):
    ...
```

## Backends

| Backend | Status | Use for |
|---|---|---|
| `MemoryBackend` | v0.1 | dev, tests, single-process |
| `RedisBackend` | v0.1 | production |
| `SqliteBackend` | planned | small deployments without redis |
| `PostgresBackend` | planned | when redis is overkill |

Bring-your-own backend by implementing the `Backend` protocol — every primitive in this package will work with it.

## Status

Pre-alpha. v0.1 ships rate limit, distributed lock, idempotency on memory + redis. Roadmap: dedup, OTP, feature flags, cache decorator, circuit breaker, retry, outbound throttle, pool/health composers.

## License

TBD.
