Metadata-Version: 2.4
Name: metered
Version: 1.0.0
Summary: Enterprise-grade, asynchronous rate limiting and quota management library for Python.
Project-URL: Homepage, https://github.com/arissupriy/metered
Project-URL: Repository, https://github.com/arissupriy/metered
Author-email: Aris Supriyanto <aris.jrj@gmail.com>
License-File: LICENSE
Keywords: asyncio,fastapi,flask,llm-cost,quota,rate-limit,redis
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: FastAPI
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Provides-Extra: dashboard
Requires-Dist: plotly; extra == 'dashboard'
Requires-Dist: starlette-admin; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: fakeredis; extra == 'dev'
Requires-Dist: httpx2; extra == 'dev'
Requires-Dist: locust; extra == 'dev'
Requires-Dist: lupa; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.139.2; extra == 'fastapi'
Requires-Dist: httpx2; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask[async]>=3.1.3; extra == 'flask'
Requires-Dist: werkzeug>=2.0; extra == 'flask'
Provides-Extra: full
Requires-Dist: fakeredis; extra == 'full'
Requires-Dist: fastapi>=0.139.2; extra == 'full'
Requires-Dist: flask[async]>=3.1.3; extra == 'full'
Requires-Dist: httpx2; extra == 'full'
Requires-Dist: locust; extra == 'full'
Requires-Dist: lupa; extra == 'full'
Requires-Dist: mypy; extra == 'full'
Requires-Dist: plotly; extra == 'full'
Requires-Dist: pytest; extra == 'full'
Requires-Dist: pytest-asyncio; extra == 'full'
Requires-Dist: pytest-cov; extra == 'full'
Requires-Dist: redis[hiredis]>=4.0; extra == 'full'
Requires-Dist: starlette-admin; extra == 'full'
Requires-Dist: werkzeug>=2.0; extra == 'full'
Provides-Extra: redis
Requires-Dist: redis[hiredis]>=4.0; extra == 'redis'
Description-Content-Type: text/markdown

# Metered ⏱️

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

**Metered** is an enterprise-grade, asynchronous rate limiting and quota management library for Python. Designed for modern SaaS architectures, it supports FastAPI and Flask natively, offering highly precise algorithms, dynamic LLM token costing, and robust distributed state management via Redis.

---

## 🚀 Features

- **4 Core Rate Limiting Algorithms**: 
  - Token Bucket (Smooth bursting)
  - Sliding Window (High precision, dynamic costs)
  - Fixed Window (Standard quota tracking)
  - Leaky Bucket (Strict egress shaping)
- **Dynamic Costing**: Perfect for GenAI/LLM wrappers—calculate the cost (tokens) of a request dynamically at runtime.
- **Quota Persistence**: Define limits like "10,000 tokens per month" that survive app restarts and synchronize globally via Redis.
- **Event-Driven Architecture**: Native webhook/event dispatcher with DLQ (Dead Letter Queue), exponential backoff, and strict event throttling to prevent spam when quotas are breached.
- **Backend Agnostic**: Ships with a thread-safe `InMemoryBackend` for development and an atomic, Lua-powered `RedisBackend` for high-throughput production.
- **Async Native**: Built with `asyncio` from the ground up, guaranteeing non-blocking behavior.

---

## 📦 Installation

```bash
pip install metered
```
*(Coming soon to PyPI)*

---

## ⚡ Quick Start

### FastAPI Example

```python
from fastapi import FastAPI, Request
from metered import Metered, Strategy, IdentifierType

app = FastAPI()
# By default, uses the lightweight InMemoryBackend
meter = Metered()

# Helper to identify users
def get_client_ip(req: Request) -> str:
    return req.client.host if req.client else "127.0.0.1"

# Restrict to 5 requests per 10 seconds per IP
@app.get("/api/data")
@meter.limit(
    max_tokens=5, 
    period=10, 
    strategy=Strategy.FIXED_WINDOW, 
    identifier=get_client_ip
)
async def get_data(request: Request):
    return {"data": "Success!"}
```

### Flask Example

```python
from flask import Flask, request, jsonify
from metered import Metered, Strategy

app = Flask(__name__)
meter = Metered()

def get_client_ip(req):
    return req.remote_addr or "127.0.0.1"

@app.route("/api/data", methods=["GET"])
@meter.limit(max_tokens=5, period=10, strategy=Strategy.FIXED_WINDOW, identifier=get_client_ip)
def get_data():
    return jsonify({"data": "Here is your data!"})
```

---

## 🧠 Core Concepts

### Stacking Decorators
You can combine multiple constraints on a single endpoint. Metered evaluates them top-down (or as passed) and enforces the strictest rule.

```python
@app.get("/search")
@meter.quota(plan_name="pro_plan", identifier=get_user_id)  # Evaluated first
@meter.limit(max_tokens=100, period=60, strategy=Strategy.SLIDING_WINDOW, identifier=get_user_id) # Sustained limit
@meter.limit(max_tokens=10, period=1, strategy=Strategy.SLIDING_WINDOW, identifier=get_user_id)   # Burst limit
async def search(request: Request):
    return {"results": []}
```

### Dynamic Costs (LLMs / AI Apps)
Unlike standard rate limiters where 1 Request = 1 Token, `metered` allows you to define a `cost` function.

```python
async def calculate_llm_cost(req: Request) -> int:
    body = await req.json()
    prompt = body.get("prompt", "")
    # e.g., 1 word = ~1.3 tokens
    return max(1, int(len(prompt.split()) * 1.3))

@app.post("/v1/completions")
@meter.limit(
    max_tokens=5000, 
    period=60, 
    strategy=Strategy.TOKEN_BUCKET, 
    identifier=get_api_key, 
    cost=calculate_llm_cost
)
async def generate_text(request: Request):
    return {"text": "AI response..."}
```

---

## 🏭 Production Guide

### Using Redis (Recommended for Production)

For distributed systems and multi-worker deployments (e.g., Uvicorn/Gunicorn), use the `RedisBackend`. It relies entirely on atomic Lua scripts to prevent race conditions.

```python
from redis.asyncio import Redis
from metered import Metered, RedisBackend

redis_client = Redis.from_url("redis://localhost:6379", decode_responses=True)
redis_backend = RedisBackend(redis_client)

meter = Metered(backend=redis_backend, quota_backend=redis_backend)
```

### Quota Engine & Plans
Unlike short-lived rate limits, Quotas are persistent billing boundaries (e.g., Monthly API usage).

```python
# During your app startup phase
@app.on_event("startup")
async def startup():
    # Store a persistent quota plan into the backend
    await meter.quotas.set_plan(
        target="user_123",
        plan_name="pro_plan",
        limit=100000,               # 100k tokens
        reset_period="monthly",     # resets on the 1st of every month
        identifier_type=IdentifierType.USER_ID
    )
```

### Event Dispatcher (Alerts & Webhooks)
Metered includes an advanced event dispatcher with two-phase commits, throttling, and a DLQ (Dead Letter Queue) to reliably notify you (e.g. via Slack) when users approach their limits without spamming your network.

```python
# 1. Configure Persistent Outbox
meter.events.configure(
    backend=redis_backend, 
    persist=True, 
    cooldown_seconds=3600 # Only alert once per hour per user
)

# 2. Start the Background Worker
asyncio.create_task(meter.events.start_worker())

# 3. Listen to Quota Warnings
@meter.events.on_quota_warning(threshold=0.8)
async def handle_quota_warning(target: str, plan_name: str, usage_ratio: float, remaining: int):
    # This handler will be retried with exponential backoff if it fails
    await send_slack_alert(f"User {target} is at {usage_ratio*100}% of their {plan_name} plan.")
```

---

## 📊 Performance & Benchmarks

Metered is built to sustain massive concurrency. Below is a benchmark result using `locust` against the `fastapi_saas.py` example (which includes dynamic Redis Quotas, Rate Limits, and Event Dispatching):

```text
Type     Name                                           # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
--------|---------------------------------------------------------------------------------------------------|--------|-----------
GET      /premium-data                                    7865     0(0.00%) |    104       2     349    100 |  530.32        0.00
```
*(Tested with 100 concurrent headless users. Zero failures or unhandled exceptions).*

---

## 🌍 Global Middleware
If you want to apply limits globally rather than per-route, `metered` exports standard middlewares.

**FastAPI:**
```python
from metered.integrations.fastapi import MeteredMiddleware
from metered import Limit, Strategy

# Limits all traffic globally to 100 req/sec
app.add_middleware(
    MeteredMiddleware, 
    meter=meter, 
    limits=[Limit(max_tokens=100, period=1, strategy=Strategy.FIXED_WINDOW)]
)
```

---

## 🤝 Contributing
Contributions are highly welcomed! Please check our open issues.
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Run static checks (`mypy metered/`)
5. Push to the Branch (`git push origin feature/AmazingFeature`)
6. Open a Pull Request

## 📄 License
Distributed under the MIT License. See `LICENSE` for more information.
