Metadata-Version: 2.1
Name: lxcor-kotta
Version: 0.1.0
Summary: Throttling and quota enforcement for Django REST Framework — per-endpoint rate limits, tier-based quotas, and usage tracking.
Author-email: Alexandre Scozzafave Alves <frontdesk@lxcor.com>
License: MIT
Project-URL: Homepage, https://github.com/lxcor/api-suite/tree/main/kotta
Project-URL: Repository, https://github.com/lxcor/api-suite
Keywords: django,drf,throttling,rate-limiting,quota
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django>=3.2
Requires-Dist: djangorestframework>=3.14
Requires-Dist: lxcor-reggi>=0.1.0

# kotta

Throttling and quota enforcement for Django REST Framework.

`kotta` provides per-endpoint rate limits, tier-based quotas, and usage tracking. Tiers are database-driven so limits can be changed without a deployment. Integrates with `lxcor-reggi` API keys for per-key tracking.

Part of the [lxcor/api-suite](https://github.com/lxcor/api-suite).

## Install

```bash
pip install lxcor-kotta
```

## Setup

```python
# settings.py
INSTALLED_APPS = [
    ...
    'reggi',  # required
    'kotta',
]

MIDDLEWARE = [
    ...
    'kotta.middleware.KottaMiddleware',
]

REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': [
        'kotta.throttle.AnonEndpointThrottle',
        'kotta.throttle.TierThrottle',
    ],
    'EXCEPTION_HANDLER': 'kotta.exceptions.kotta_exception_handler',
}
```

```python
# urls.py
urlpatterns = [
    path('usage/', include('kotta.urls')),
]
```

Sync your URL patterns into the kotta endpoint registry:

```bash
python manage.py syncendpoints
```

## Settings

| Setting | Default | Description |
|---|---|---|
| `KOTTA_UPGRADE_MESSAGE` | `''` | Message appended to 429 responses pointing users to upgrade |

## Management commands

| Command | Description |
|---|---|
| `syncendpoints` | Register all URL patterns in the kotta endpoint table |
| `dumpconfig` | Export tier and endpoint config to JSON |
| `loadconfig` | Import tier and endpoint config from JSON |

## License

MIT
