Metadata-Version: 2.4
Name: philiprehberger-rate-limiter
Version: 0.1.0
Summary: In-memory rate limiter with sliding window and token bucket
Project-URL: Homepage, https://github.com/philiprehberger/py-rate-limiter
Project-URL: Repository, https://github.com/philiprehberger/py-rate-limiter
Project-URL: Issues, https://github.com/philiprehberger/py-rate-limiter/issues
Author: Philip Rehberger
License-Expression: MIT
License-File: LICENSE
Keywords: api,rate-limit,sliding-window,throttle,token-bucket
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# philiprehberger-rate-limiter

In-memory rate limiter with sliding window and token bucket algorithms.

## Installation

```bash
pip install philiprehberger-rate-limiter
```

## Usage

### Basic Rate Limiting

```python
from philiprehberger_rate_limiter import RateLimiter, Algorithm

limiter = RateLimiter(
    requests=100,
    window_seconds=60,
    algorithm=Algorithm.SLIDING_WINDOW,
)

if limiter.allow("user-123"):
    handle_request()
```

### Check Status

```python
status = limiter.status("user-123")
print(f"Allowed: {status.allowed}")
print(f"Remaining: {status.remaining}/{status.limit}")
print(f"Resets at: {status.reset_at}")
```

### Decorator

```python
limiter = RateLimiter(10, 60)

@limiter.limit("10/minute")
def api_endpoint():
    return {"data": "ok"}
```

### Algorithms

```python
# Fixed window — resets at interval boundaries
RateLimiter(100, 60, Algorithm.FIXED_WINDOW)

# Sliding window (default) — rolling time window
RateLimiter(100, 60, Algorithm.SLIDING_WINDOW)

# Token bucket — smooth rate with burst capacity
RateLimiter(100, 60, Algorithm.TOKEN_BUCKET)
```

## API

- `RateLimiter(requests, window_seconds, algorithm=SLIDING_WINDOW)` — Create a rate limiter
- `limiter.allow(key)` — Check if request is allowed
- `limiter.status(key)` — Get detailed `LimitStatus`
- `limiter.reset(key)` — Reset state for a key
- `limiter.limit(rate)` — Decorator with rate string (e.g., `"10/minute"`)

## License

MIT
