metered 1.0.0__tar.gz

metered-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [ "master", "main" ]
+  pull_request:
+    branches: [ "master", "main" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    services:
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+        
+    - name: Check typing with mypy
+      run: |
+        mypy metered/
+        
+    - name: Test with pytest
+      run: |
+        pytest

metered-1.0.0/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs and Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing, reporting, and coverage
+.coverage
+.tox/
+.pytest_cache/
+htmlcov/
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/

metered-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aris Supriyanto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metered-1.0.0/PKG-INFO

@@ -0,0 +1,275 @@
+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.

metered-1.0.0/README.md

@@ -0,0 +1,218 @@
+# 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.

metered-1.0.0/benchmarks/locustfile.py

@@ -0,0 +1,24 @@
+import os
+from locust import HttpUser, task, between
+
+# Make sure to run the FastAPI test server before running this benchmark:
+# uvicorn examples.fastapi_saas:app --port 8000
+class MeteredUser(HttpUser):
+    # Wait between 10ms and 100ms between tasks to simulate high concurrency
+    wait_time = between(0.01, 0.1)
+
+    @task
+    def access_premium_endpoint(self):
+        # We simulate passing a mock API key
+        headers = {"x-api-key": f"user_bench_{os.getpid()}"}
+        
+        # Test normal endpoint
+        with self.client.get("/premium-data", headers=headers, catch_response=True) as response:
+            if response.status_code == 200:
+                response.success()
+            elif response.status_code == 429:
+                # 429 is an expected response from rate limiting, we can mark it as success for benchmark purposes
+                # or keep it as failure if we want to measure purely allowed throughput.
+                response.success()
+            else:
+                response.failure(f"Unexpected status code: {response.status_code}")

metered-1.0.0/docs/index.md

@@ -0,0 +1,14 @@
+# Welcome to Metered
+
+**Production-grade rate limiting and quota tracking for Python web frameworks.**
+
+`metered` is a modular, high-performance rate limiting library designed to unify short-term API abuse protection and long-term quota tracking (e.g., billing boundaries). 
+
+## Why Metered?
+
+1. **Framework Agnostic:** First-class support for FastAPI and Flask.
+2. **Distributed Ready:** Start with `InMemoryBackend` in dev, scale out with atomic `RedisBackend` in production.
+3. **Flexible Algorithms:** Choose from Token Bucket, Sliding Window, Fixed Window, or Leaky Bucket.
+4. **Event Hooks:** React to quota thresholds instantly.
+
+For full usage instructions, check out the API references.

metered-1.0.0/docs/migration.md

@@ -0,0 +1,70 @@
+# Migrating from fastapi-limiter to metered
+
+If you are currently using `fastapi-limiter` for your FastAPI application, upgrading to `metered` provides several advantages:
+- Built-in billing/quota tracking (separated from ephemeral rate limits)
+- Robust timezone-aware quota resets
+- Analytics and usage tracking ready
+- Event hooks (e.g. `on_quota_warning`) for sending webhooks or emails
+
+## 1. Initialization
+
+**fastapi-limiter:**
+```python
+import redis.asyncio as redis
+from fastapi_limiter import FastAPILimiter
+
+@app.on_event("startup")
+async def startup():
+    redis_client = redis.from_url("redis://localhost", encoding="utf-8", decode_responses=True)
+    await FastAPILimiter.init(redis_client)
+```
+
+**metered:**
+```python
+from metered import Metered, RedisBackend
+from redis.asyncio import Redis
+
+redis_client = Redis.from_url("redis://localhost:6379", decode_responses=True)
+meter = Metered(backend=RedisBackend(redis_client))
+```
+
+## 2. Route Decorators
+
+**fastapi-limiter:**
+```python
+from fastapi_limiter.depends import RateLimiter
+from fastapi import Depends
+
+@app.get("/", dependencies=[Depends(RateLimiter(times=2, seconds=5))])
+async def index():
+    return {"msg": "Hello World"}
+```
+
+**metered:**
+```python
+from metered import Limit
+
+def get_ip(request):
+    return request.client.host
+
+@app.get("/")
+@meter.apply(Limit(max_tokens=2, period_seconds=5, identifier=get_ip))
+async def index():
+    return {"msg": "Hello World"}
+```
+
+## 3. Adding Quotas (metered exclusive)
+
+Unlike `fastapi-limiter`, `metered` allows you to stack a long-term billing Quota directly on top of your short-term rate limit:
+
+```python
+from metered import Quota
+
+@app.get("/")
+@meter.apply(
+    Limit(max_tokens=2, period_seconds=5, identifier=get_ip),
+    Quota(plan_name="premium", identifier=get_ip)
+)
+async def index():
+    return {"msg": "Hello World"}
+```