Django Smart Ratelimit

https://github.com/yassershkeir/django-smart-ratelimit
Admin
A comprehensive rate limiting library for Django applications with multiple algorithms, backends,...
Tokens:61,159
Snippets:414
Trust Score:7.4
License:MIT
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install Django Smart Ratelimit and DRF

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/examples/integrations/drf_integration/README.md

Installs the necessary packages for Django REST Framework and Django Smart Ratelimit. This is a prerequisite for using the integration examples.

```bash
pip install djangorestframework django-smart-ratelimit
```

--------------------------------

### Install django-smart-ratelimit with Redis Support

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/README.md

Installs the django-smart-ratelimit library with the necessary dependencies for Redis backend support. This is a common starting point for projects utilizing Redis for rate limiting.

```bash
pip install django-smart-ratelimit[redis]
```

--------------------------------

### Example Test Structure

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/CONTRIBUTING.md

A Python code snippet illustrating the basic structure for writing a unit test, including a docstring explaining the test's purpose and placeholders for setup, test execution, and assertion.

```python
def test_rate_limit_decorator_within_limit(self):
    """Test decorator when requests are within the limit."""
    # Setup
    # Test
    # Assert
```

--------------------------------

### Python Enhanced Memory Backend Example

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/backend_utilities.md

Provides a complete example of an in-memory backend implementation for Django Smart Rate Limit. It includes initialization with configuration validation, thread-safe GET and SET operations, automatic cleanup, and statistics gathering. It utilizes decorators like `@with_retry` and utility functions for operations like key normalization and data serialization.

```python
from django_smart_ratelimit.backends.base import BaseBackend
from django_smart_ratelimit.backends.utils import *
import threading
import time

class EnhancedMemoryBackend(BaseBackend):
    def __init__(self, **config):
        # Validate configuration
        validated_config = validate_backend_config(config, 'memory')

        self.storage = {}
        self.lock = threading.RLock()
        self.max_entries = validated_config.get('max_entries', 10000)
        self.cleanup_interval = validated_config.get('cleanup_interval', 300)
        self.key_prefix = validated_config.get('key_prefix', 'rl:')

    @with_retry(max_retries=2, delay=0.01)
    def get(self, key: str):
        with create_operation_timer() as timer:
            try:
                normalized_key = normalize_key(key, self.key_prefix)

                with self.lock:
                    if normalized_key in self.storage:
                        entry = self.storage[normalized_key]

                        if 'expires_at' in entry and is_expired(entry['expires_at']):
                            del self.storage[normalized_key]
                            result = None
                        else:
                            # Update access time for LRU
                            entry['last_access'] = time.time()
                            result = deserialize_data(entry['value'])
                    else:
                        result = None

                log_backend_operation('get', 'memory', key, timer.elapsed_ms, True)
                return result

            except Exception as e:
                log_backend_operation('get', 'memory', key, timer.elapsed_ms, False, str(e))
                raise

    def set(self, key: str, value, ttl: int = None):
        with create_operation_timer() as timer:
            try:
                normalized_key = normalize_key(key, self.key_prefix)

                with self.lock:
                    entry = {
                        'value': serialize_data(value),
                        'created_at': time.time(),
                        'last_access': time.time()
                    }

                    if ttl:
                        entry['expires_at'] = generate_expiry_timestamp(ttl)

                    self.storage[normalized_key] = entry
                    self._maybe_cleanup()

                log_backend_operation('set', 'memory', key, timer.elapsed_ms, True)
                return True

            except Exception as e:
                log_backend_operation('set', 'memory', key, timer.elapsed_ms, False, str(e))
                raise

    def _maybe_cleanup(self):
        if len(self.storage) > self.max_entries:
            self.storage = cleanup_memory_data(
                self.storage,
                max_size=int(self.max_entries * 0.8),
                cleanup_strategy='lru'
            )

    def get_stats(self):
        with self.lock:
            return {
                'total_entries': len(self.storage),
                'estimated_memory_bytes': estimate_memory_usage(self.storage),
                'max_entries': self.max_entries
            }
```

--------------------------------

### Set Up Virtual Environment and Install Dependencies

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/CONTRIBUTING.md

Instructions for creating a Python virtual environment and installing project dependencies, including development-specific packages, using venv and pip.

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .[dev]
```

--------------------------------

### Docker Configuration for Django Smart RateLimit with Redis

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

This Dockerfile and docker-compose.yml setup configures a production environment for Django Smart RateLimit using Redis. The Dockerfile installs dependencies and sets environment variables for the backend and Redis connection. The docker-compose file defines the web service and a Redis service, ensuring proper startup order and data persistence.

```dockerfile
# Dockerfile
FROM python:3.11-slim

COPY requirements.txt .
RUN pip install -r requirements.txt

# Set environment variables
ENV RATELIMIT_BACKEND=redis
ENV REDIS_HOST=redis
ENV REDIS_PORT=6379

COPY . .
CMD ["gunicorn", "myproject.wsgi:application"]
```

```yaml
# docker-compose.yml
version: "3.8"
services:
  web:
    build: .
    environment:
      - RATELIMIT_BACKEND=redis
      - REDIS_HOST=redis
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data

volumes:
  redis_data:
```

--------------------------------

### Install Django Smart RateLimit for Development

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Installs the package in editable mode from a Git repository, including development dependencies. Useful for contributing to the project or making direct modifications.

```bash
git clone https://github.com/YasserShkeir/django-smart-ratelimit.git
cd django-smart-ratelimit
pip install -e .[dev]
```

--------------------------------

### Install Django Smart RateLimit with Optional Dependencies

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Installs django-smart-ratelimit with optional backends like Redis, MongoDB, JWT, or all dependencies. Recommended for production environments that require specific backends.

```bash
# Redis backend (recommended for production)
pip install django-smart-ratelimit[redis]

# MongoDB backend
pip install django-smart-ratelimit[mongodb]

# JWT-based rate limiting
pip install django-smart-ratelimit[jwt]

# All optional dependencies
pip install django-smart-ratelimit[all]
```

--------------------------------

### Multi-Level Rate Limiting Example (Python)

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/integrations/drf.md

Demonstrates applying multiple rate limits to a single view using django-smart-ratelimit. This example enforces IP-based, user-based, and global endpoint limits simultaneously, requiring all conditions to be met for a request to succeed.

```python
from rest_framework.views import APIView
from rest_framework.response import Response
from django_smart_ratelimit import rate_limit

class MultiLevelRateView(APIView):
    @rate_limit(key='ip', rate='1000/h')      # IP-based limit
    @rate_limit(key='user', rate='500/h')     # User-based limit
    @rate_limit(key='endpoint', rate='10000/h')  # Global limit
    def get(self, request):
        return Response({'data': 'Your data'})
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/CONTRIBUTING.md

This command installs the pre-commit framework, which automates running checks before each commit to ensure code quality and consistency.

```bash
pre-commit install
```

--------------------------------

### Run Project Tests

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/CONTRIBUTING.md

Demonstrates how to run the project's test suite using pytest to verify the setup and ensure all functionalities are working as expected.

```bash
pytest
```

--------------------------------

### Install Django Smart RateLimit with Pip

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Installs the django-smart-ratelimit package using pip. This is the primary method for adding the package to your project.

```bash
pip install django-smart-ratelimit
```

--------------------------------

### Integrate Custom Health Check

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Provides an example of how to create a custom health check function that utilizes the `get_backend` utility to check the rate limiting backend's health, allowing integration with external monitoring systems.

```python
# health_checks.py
from django_smart_ratelimit import get_backend

def ratelimit_health_check():
    backend = get_backend()
    return backend.health_check()

# In your monitoring system
if not ratelimit_health_check():
    alert("Rate limiting backend is unhealthy")
```

--------------------------------

### Troubleshoot Import Errors for Django Smart RateLimit

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

These commands assist in troubleshooting import errors related to Django Smart RateLimit. First, verify the package installation using `pip show`. Second, ensure the `django_smart_ratelimit` application is correctly added to your Django project's `INSTALLED_APPS` in `settings.py`, and then use `python manage.py check` to validate your project's configuration.

```bash
# Verify installation
pip show django-smart-ratelimit

# Check INSTALLED_APPS
python manage.py check
```

--------------------------------

### Best Practices: Choosing Rate Limits and Smart Keys (Python)

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/integrations/drf.md

Illustrates best practices for setting rate limits and defining smart key functions in django-smart-ratelimit. Examples show how to apply granular limits for different operation types (read, write, destructive) and how to create a `smart_key` function that uses either the authenticated user's ID or the IP address for key generation.

```python
@rate_limit(key='user', rate='100/h')  # Read operations
@rate_limit(key='user', rate='20/h')   # Write operations
@rate_limit(key='user', rate='5/h')    # Destructive operations
```

```python
def smart_key(request):
    if request.user.is_authenticated:
        return f"user:{request.user.id}"
    return f"ip:{request.META.get('REMOTE_ADDR', 'unknown')}"
```

--------------------------------

### Configure Database Backend for Rate Limiting

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Sets up the database backend for rate limiting. This involves setting RATELIMIT_BACKEND to 'database' and running Django migrations to create the necessary table.

```python
# settings.py
RATELIMIT_BACKEND = 'database'

# Run migrations
python manage.py migrate

# Optional: verify that the RateLimitCounter table now includes the `data` column
python manage.py showmigrations django_smart_ratelimit
```

--------------------------------

### Configure Django Settings for Rate Limiting

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/examples/integrations/drf_integration/README.md

Configures Django settings to include 'rest_framework' and 'django_smart_ratelimit' in INSTALLED_APPS. It also sets up the rate limiting backend, using Redis in this example, and its connection options.

```python
INSTALLED_APPS = [
    # ... other apps
    'rest_framework',
    'django_smart_ratelimit',
]

# Configure rate limiting backend
RATELIMIT_BACKEND = 'django_smart_ratelimit.backends.redis_backend.RedisBackend'
RATELIMIT_BACKEND_OPTIONS = {
    'CONNECTION_POOL_KWARGS': {
        'host': 'localhost',
        'port': 6379,
        'db': 0,
    }
}
```

--------------------------------

### Configure Multi-Backend for High Availability

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Sets up multiple rate limiting backends for high availability. Supports strategies like 'first_healthy' to ensure resilience.

```python
# settings.py
RATELIMIT_BACKENDS = [
    {
        'name': 'primary_redis',
        'backend': 'redis',
        'config': {
            'host': 'redis-primary.example.com',
            'port': 6379,
            'db': 0,
        }
    },
    {
        'name': 'fallback_redis',
        'backend': 'redis',
        'config': {
            'host': 'redis-fallback.example.com',
            'port': 6379,
            'db': 0,
        }
    },
    {
        'name': 'emergency_db',
        'backend': 'database',
        'config': {}
    }
]
RATELIMIT_MULTI_BACKEND_STRATEGY = 'first_healthy'
```

--------------------------------

### Environment-Specific Rate Limiting Configuration

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Demonstrates how to configure rate limiting settings differently for various environments (production, development, testing) using environment variables or separate settings files.

```python
# settings/production.py
RATELIMIT_BACKEND = 'redis'
RATELIMIT_REDIS = {
    'host': os.environ.get('REDIS_HOST', 'localhost'),
    'port': int(os.environ.get('REDIS_PORT', 6379)),
    'password': os.environ.get('REDIS_PASSWORD'),
}

# settings/development.py
RATELIMIT_BACKEND = 'memory'

# settings/testing.py
RATELIMIT_BACKEND = 'memory'
RATELIMIT_ENABLE = False  # Disable in tests
```

--------------------------------

### Example Rate Limit Response Headers

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/README.md

Illustrates the standard HTTP headers returned by the library to provide rate limit information to clients. Includes limit, remaining requests, reset time, and retry delay.

```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1642678800
Retry-After: 200
```

--------------------------------

### Basic IP-Based Rate Limiting Example

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/README.md

Demonstrates basic IP-based rate limiting using the `@rate_limit` decorator. This example limits requests to 10 per minute for each unique IP address.

```python
from django_smart_ratelimit import rate_limit
from django.http import JsonResponse

# Basic IP-based limiting
@rate_limit(key='ip', rate='10/m')
def public_api(request):
    return JsonResponse({'message': 'Hello World'})
```

--------------------------------

### Mock Rate Limiting Backend for Testing

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Demonstrates how to mock the rate limiting backend using `unittest.mock.patch` to isolate tests and control the behavior of the rate limiting mechanism.

```python
# tests.py
from unittest.mock import patch
from django_smart_ratelimit.backends.memory import MemoryBackend

@patch('django_smart_ratelimit.backends.get_backend')
def test_with_mock_backend(mock_get_backend):
    mock_get_backend.return_value = MemoryBackend()
    # Your test code here
```

--------------------------------

### Basic Rate Limiting with @rate_limit Decorator

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Demonstrates the fundamental usage of the @rate_limit decorator to enforce rate limits on individual Django views. It requires importing the decorator and specifying the key and rate parameters. This example limits requests to 10 per minute based on IP address.

```python
from django_smart_ratelimit import rate_limit
from django.http import JsonResponse

@rate_limit(key='ip', rate='10/m')
def api_endpoint(request):
    return JsonResponse({'message': 'Hello World'})
```

--------------------------------

### Configure Django INSTALLED_APPS

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Adds 'django_smart_ratelimit' to your Django project's INSTALLED_APPS in settings.py. This is a mandatory step for the package to function.

```python
# settings.py
INSTALLED_APPS = [
    # ... your apps
    'django_smart_ratelimit',
]
```

--------------------------------

### Configure Redis Backend for Rate Limiting

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Sets up the Redis backend for rate limiting in Django settings. Requires a running Redis instance and provides configuration options for connection.

```python
# settings.py
RATELIMIT_BACKEND = 'redis'
RATELIMIT_REDIS = {
    'host': 'localhost',
    'port': 6379,
    'db': 0,
    'password': None,  # Optional
    'socket_timeout': 0.1,
    'socket_connect_timeout': 0.1,
    'socket_keepalive': True,
    'socket_keepalive_options': {},
    'health_check_interval': 30,
}
```

--------------------------------

### Best Practices: Monitoring Rate Limit Usage (Python)

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/integrations/drf.md

Shows how to monitor rate limit usage in django-smart-ratelimit by retrieving backend information. This example uses `get_backend()` to access the rate limiting backend and `get_usage_info()` to fetch details like `remaining_requests` and `reset_time` for a given key, returning this information in a response.

```python
from django_smart_ratelimit import get_backend

def rate_limit_status(request):
    backend = get_backend()
    key = f"user:{request.user.id}"
    usage_info = backend.get_usage_info(key)
    return Response({
        'remaining_requests': usage_info.get('remaining', 0),
        'reset_time': usage_info.get('reset_time')
    })
```

--------------------------------

### DRF URL Configuration with ViewSet Routers

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/examples/integrations/drf_integration/README.md

Configures URL routing for DRF ViewSets using `DefaultRouter`. This example registers `PostViewSet` and `CommentViewSet` under the '/api/' prefix, allowing them to be accessed via RESTful endpoints.

```python
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import PostViewSet, CommentViewSet

router = DefaultRouter()
router.register(r'posts', PostViewSet)
router.register(r'comments', CommentViewSet)

urlpatterns = [
    path('api/', include(router.urls)),
]
```

--------------------------------

### Configure Memory Backend for Rate Limiting (Development)

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Configures the in-memory backend for rate limiting, suitable for development or testing. It has a configurable maximum number of keys.

```python
# settings.py
RATELIMIT_BACKEND = 'memory'
RATELIMIT_MEMORY_MAX_KEYS = 10000
```

--------------------------------

### Configure Logging for Rate Limiting in Python

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/examples/integrations/drf_integration/README.md

Configure Django's logging settings to capture information related to django-smart-ratelimit. This example sets up a file handler to write INFO level logs to 'ratelimit.log' specifically for the 'django_smart_ratelimit' logger.

```python
LOGGING = {
    'version': 1,
    'handlers': {
        'file': {
            'level': 'INFO',
            'class': 'logging.FileHandler',
            'filename': 'ratelimit.log',
        },
    },
    'loggers': {
        'django_smart_ratelimit': {
            'handlers': ['file'],
            'level': 'INFO',
            'propagate': True,
        },
    },
}
```

--------------------------------

### Check Redis Connectivity

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

A basic command-line check to verify connectivity to a Redis server. Useful for troubleshooting Redis backend issues.

```bash
# Check Redis connectivity
redis-cli ping
```

--------------------------------

### Configure RateLimitMiddleware

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Adds the RateLimitMiddleware to your Django project's middleware stack and configures its behavior, including default rates, specific path rates, and skip paths.

```python
# settings.py
MIDDLEWARE = [
    'django_smart_ratelimit.middleware.RateLimitMiddleware',
    # ... other middleware
]

RATELIMIT_MIDDLEWARE = {
    'DEFAULT_RATE': '100/m',
    'RATE_LIMITS': {
        '/api/auth/': '10/m',
        '/api/upload/': '5/h',
        '/api/': '200/h',
    },
    'SKIP_PATHS': ['/admin/', '/health/', '/static/'],
    'BLOCK': True,
    'KEY_FUNCTION': 'django_smart_ratelimit.utils.get_ip_key',
}
```

--------------------------------

### Run Django Smart RateLimit Health Check

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

Executes the `ratelimit_health` management command to check the status of the configured rate limiting backend. Options for verbose and JSON output are available.

```bash
# Check backend health
python manage.py ratelimit_health

# Verbose output
python manage.py ratelimit_health --verbose

# JSON output for monitoring
python manage.py ratelimit_health --json
```

--------------------------------

### Environment-Specific Circuit Breaker Configuration Examples

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/circuit_breaker.md

Provides example Python dictionaries for configuring circuit breakers tailored to different environments (production, critical services, development). These configurations adjust parameters like failure thresholds and recovery timeouts.

```python
# For high-traffic production APIs
PRODUCTION_CONFIG = {
    'failure_threshold': 10,     # More tolerance for occasional failures
    'recovery_timeout': 30,      # Quick recovery testing
    'exponential_backoff_max': 180,  # Shorter max backoff
}

# For critical external services
CRITICAL_SERVICE_CONFIG = {
    'failure_threshold': 3,      # Fail fast
    'recovery_timeout': 120,     # Give more time to recover
    'exponential_backoff_max': 600,  # Longer backoff for stability
}

# Development/testing
DEVELOPMENT_CONFIG = {
    'failure_threshold': 1,      # Immediate testing
    'recovery_timeout': 5,       # Quick recovery for development
}
```

--------------------------------

### IP-Based Rate Limiting Example

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Illustrates rate limiting requests based on the client's IP address using the 'ip' key type. This is a common method for public APIs to prevent abuse. This example allows 50 requests per hour from each IP.

```python
@rate_limit(key='ip', rate='50/h')
def public_api(request):
    return JsonResponse({'data': 'public'})
```

--------------------------------

### Conditional Rate Limiting Logic in Python

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/examples/integrations/drf_integration/README.md

Implement conditional rate limiting using a Python function that returns a boolean. If the function returns `True`, rate limiting is applied; if it returns `False`, rate limiting is bypassed for that request. This example bypasses rate limiting for GET requests and requests from staff users.

```python
def conditional_rate_limit(request):
    if request.method == 'GET':
        return True  # No rate limiting for GET requests
    if request.user.is_staff:
        return True  # No rate limiting for staff
    return False  # Apply rate limiting
```

--------------------------------

### Rate Limiting with Different Time Periods

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Provides examples of using the `@rate_limit` decorator with various time periods for rate enforcement. Supported periods include per second (`/s`), per minute (`/m`), per hour (`/h`), and per day (`/d`). These examples show how to configure limits for different granularities.

```python
@rate_limit(key='ip', rate='5/s')    # 5 requests per second
@rate_limit(key='ip', rate='100/m')  # 100 requests per minute
@rate_limit(key='ip', rate='1000/h') # 1000 requests per hour
@rate_limit(key='ip', rate='10000/d') # 10000 requests per day
```

--------------------------------

### Troubleshoot Database Backend Issues for Django Smart RateLimit

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

These commands help troubleshoot database backend issues for Django Smart RateLimit. They include running migrations, checking database connectivity via `dbshell`, and verifying the presence of the `RateLimitCounter` table with the required `data` column for token bucket functionality. Ensure the `django_smart_ratelimit` app is listed in `INSTALLED_APPS`.

```bash
# Run migrations
python manage.py migrate

# Check database connectivity
python manage.py dbshell

# Ensure the RateLimitCounter table has the `data` column (required for token bucket)
python manage.py showmigrations django_smart_ratelimit
```

--------------------------------

### DRF Function-Based View Rate Limiting

Source: https://context7.com/yassershkeir/django-smart-ratelimit/llms.txt

Applies rate limiting to a function-based Django REST Framework view using the `@rate_limit` decorator. This example shows how to protect both GET and POST requests with a unified rate limit.

```python
from rest_framework.decorators import api_view
from rest_framework.response import Response
from rest_framework import status
from django_smart_ratelimit import rate_limit

@api_view(['GET', 'POST'])
@rate_limit(key='user_or_ip', rate='100/h')
def api_function_view(request):
    if request.method == 'GET':
        return Response({'data': 'list'})
    return Response({'data': 'created'}, status=status.HTTP_201_CREATED)
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/CONTRIBUTING.md

This snippet demonstrates how to clone the Django Smart Ratelimit repository and navigate into the project directory using Git and bash.

```bash
git clone https://github.com/YasserShkeir/django-smart-ratelimit.git
cd django-smart-ratelimit
```

--------------------------------

### DRF APIView Basic Rate Limiting

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/integrations/drf.md

Applies rate limiting to different HTTP methods (GET, POST) within a DRF APIView using the @rate_limit decorator. It demonstrates limiting by IP address and user.

```python
from rest_framework.views import APIView
from rest_framework.response import Response
from django_smart_ratelimit import rate_limit

class UserListView(APIView):
    @rate_limit(key='ip', rate='10/m')
    def get(self, request):
        return Response({'users': []})

    @rate_limit(key='user', rate='5/m')
    def post(self, request):
        return Response({'message': 'User created'})
```

--------------------------------

### Migrate from Fixed Window to Token Bucket

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/algorithms.md

Provides a code example showing the migration path from a fixed window rate limiting configuration to a token bucket configuration with similar average rate and added burst allowance.

```python
# Before (Fixed Window)
@rate_limit(key='user', rate='100/h', algorithm='fixed_window')

# After (Token Bucket with same average rate)
@rate_limit(
    key='user',
    rate='100/h',
    algorithm='token_bucket',
    algorithm_config={'bucket_size': 150}  # 50% burst allowance
)
```

--------------------------------

### Fixed Window Algorithm for Rate Limiting

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Demonstrates the use of the 'fixed_window' algorithm for rate limiting. This algorithm is memory efficient and simple, though it can allow bursts at window boundaries. This example limits requests to 100 per hour.

```python
@rate_limit(
    key='ip',
    rate='100/h',
    algorithm='fixed_window'
)
def simple_api(request):
    return JsonResponse({'algorithm': 'fixed_window'})
```

--------------------------------

### Decorate Methods in Class-Based Views (Python)

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Demonstrates how to apply different rate limits to specific HTTP methods (GET, POST) within a Django class-based view using `django.utils.decorators.method_decorator`. This allows granular control over rate limiting per method.

```python
from django.views import View
from django.utils.decorators import method_decorator
from django.http import JsonResponse
from smart_ratelimit import rate_limit

@method_decorator(rate_limit(key='user', rate='100/h'), name='get')
@method_decorator(rate_limit(key='user', rate='20/h'), name='post')
class MyView(View):
    def get(self, request):
        return JsonResponse({'method': 'GET'})

    def post(self, request):
        return JsonResponse({'method': 'POST'})
```

--------------------------------

### Backend Configuration (Python)

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/design.md

Python examples for configuring different rate limiting backends (Redis, Database, Memory) in Django settings. It also shows how to select the rate limiting algorithm and set a key prefix.

```python
# Redis Backend
RATELIMIT_BACKEND = 'redis'
RATELIMIT_REDIS = {
    'host': 'localhost',
    'port': 6379,
    'db': 0,
    'password': None,
}

# Database Backend
RATELIMIT_BACKEND = 'database'
RATELIMIT_DATABASE_CLEANUP_THRESHOLD = 1000


# Memory Backend
RATELIMIT_BACKEND = 'memory'
RATELIMIT_MEMORY_MAX_KEYS = 10000

# Algorithm Selection
RATELIMIT_ALGORITHM = "sliding_window"  # vs "fixed_window"
RATELIMIT_KEY_PREFIX = 'ratelimit:'
```

--------------------------------

### Strict Rate Limiting with Blocking Enabled

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Demonstrates the default blocking behavior of the `@rate_limit` decorator. When the rate limit is exceeded, requests are blocked, and an HTTP 429 (Too Many Requests) response is returned. This example limits requests to 10 per minute.

```python
@rate_limit(key='ip', rate='10/m', block=True)
def strict_api(request):
    # Returns HTTP 429 when rate limit exceeded
    return JsonResponse({'data': 'strict'})
```

--------------------------------

### Run Tests with Coverage and Linting

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/CONTRIBUTING.md

Commands to execute the test suite with code coverage reporting and run static analysis tools like flake8, black, and mypy to check code quality and style.

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=django_smart_ratelimit

# Run linting
flake8 django_smart_ratelimit tests
black django_smart_ratelimit tests
mypy django_smart_ratelimit
```

--------------------------------

### User-Based Rate Limiting with @rate_limit

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Shows how to apply rate limiting based on the authenticated user. This decorator uses the 'user' key type to track requests per user. The example limits authenticated users to 100 requests per hour.

```python
@rate_limit(key='user', rate='100/h')
def user_dashboard(request):
    return JsonResponse({'user_data': request.user.username})
```

--------------------------------

### DRF APIView with Varied Rate Limits

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/integrations/drf.md

Demonstrates applying different rate limits to various HTTP methods (GET, POST, PUT, DELETE) within a single DRF APIView. This allows for granular control over request frequency per action.

```python
from rest_framework.views import APIView
from rest_framework.response import Response
from django_smart_ratelimit import rate_limit

class ProductAPIView(APIView):
    @rate_limit(key='ip', rate='100/h')
    def get(self, request):
        return Response([{'id': 1, 'name': 'Product 1'}])

    @rate_limit(key='user', rate='10/h')
    def post(self, request):
        return Response({'message': 'Product created'}, status=201)

    @rate_limit(key='user', rate='5/h')
    def put(self, request):
        return Response({'message': 'Product updated'})

    @rate_limit(key='user', rate='2/h')
    def delete(self, request):
        return Response(status=204)
```

--------------------------------

### Method-Specific Rate Limiting in Python

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/examples/integrations/drf_integration/README.md

Apply different rate limits to different HTTP methods within a Django view using the @rate_limit decorator. This allows for granular control over request frequency based on the operation being performed (e.g., GET vs. POST).

```python
from smart_ratelimit import rate_limit

@rate_limit(key='ip', rate='100/m')
@rate_limit(key='user', rate='10/m')
def my_view(request):
    pass
```

--------------------------------

### Rate Limit DRF APIView Classes (Python)

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Shows how to apply rate limits to different HTTP methods (GET, POST) within a Django REST Framework `APIView` class. This allows customizing rate limiting for each endpoint's HTTP verb.

```python
from rest_framework.views import APIView
from rest_framework.response import Response
from smart_ratelimit import rate_limit

class RateLimitedAPIView(APIView):
    @rate_limit(key='user', rate='200/h')
    def get(self, request):
        return Response({'data': 'GET response'})

    @rate_limit(key='user', rate='50/h')
    def post(self, request):
        return Response({'data': 'POST response'})
```

--------------------------------

### Sliding Window Algorithm for Rate Limiting

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Illustrates the 'sliding_window' algorithm for more precise rate limiting without boundary bursts. This method offers smoother traffic control but typically consumes more memory. The example limits users to 500 requests per hour.

```python
@rate_limit(
    key='user',
    rate='500/h',
    algorithm='sliding_window'
)
def smooth_api(request):
    return JsonResponse({'algorithm': 'sliding_window'})
```

--------------------------------

### Migration and Scaling Backend Configurations in Django

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/backends.md

Illustrates how to configure the rate limiting backend during migration scenarios, such as moving from 'django-ratelimit' or scaling up the infrastructure. It shows the progression from 'database' to 'redis' and then to a highly available setup.

```python
# From django-ratelimit:
RATELIMIT_BACKEND = 'database'  # Similar to cache backend
RATELIMIT_ALGORITHM = 'fixed_window'
```

```python
# Scaling up:
# Start with database
RATELIMIT_BACKEND = 'database'

# Move to Redis
RATELIMIT_BACKEND = 'redis'

# Add high availability
RATELIMIT_BACKENDS = [...]
```

--------------------------------

### Python Load Testing Script for API Endpoints

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/examples/integrations/drf_integration/README.md

A Python script using `threading` and `rest_framework.test.APIClient` to simulate load on an API endpoint. It runs multiple threads, each making a series of GET requests to '/api/posts/', with a small delay between requests. This helps in testing the performance and rate limiting behavior under concurrent access.

```python
import threading
import time
from rest_framework.test import APIClient

def load_test_endpoint():
    client = APIClient()
    for i in range(100):
        response = client.get('/api/posts/')
        print(f"Response {i}: {response.status_code}")
        time.sleep(0.1)

# Run multiple threads
threads = []
for i in range(10):
    thread = threading.Thread(target=load_test_endpoint)
    threads.append(thread)
    thread.start()

for thread in threads:
    thread.join()
```

--------------------------------

### Token Bucket Algorithm for Rate Limiting

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Shows how to implement rate limiting using the 'token_bucket' algorithm, which allows for configurable burst capacity. This is suitable for APIs that need to handle occasional traffic spikes while maintaining an average rate. The example limits to 100 per minute with a burst capacity of 200.

```python
@rate_limit(
    key='api_key',
    rate='100/m',
    algorithm='token_bucket',
    algorithm_config={
        'bucket_size': 200,    # Allow bursts up to 200 requests
        'refill_rate': 2.0,    # Refill at 2 tokens per second
    }
)
def burst_friendly_api(request):
    return JsonResponse({'algorithm': 'token_bucket'})
```

--------------------------------

### Resource-Specific Rate Limiting Configuration in Python

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/examples/integrations/drf_integration/README.md

Define resource-specific rate limits using a Python dictionary. This configuration maps resources (e.g., 'posts', 'comments') to dictionaries containing rate limits for different HTTP methods (e.g., 'GET', 'POST'). This is useful for varying access frequencies based on the data being manipulated.

```python
RESOURCE_RATE_LIMITS = {
    'posts': {'GET': 200, 'POST': 10},
    'comments': {'GET': 500, 'POST': 30},
}
```

--------------------------------

### Custom Rate Limiting with Named Function Key

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Illustrates using a dedicated named function to generate a dynamic rate limiting key. This is useful for complex key logic, such as combining tenant information with user or IP addresses. This example limits requests to 500 per hour based on tenant and user/IP.

```python
def get_tenant_key(request):
    tenant_id = request.headers.get('X-Tenant-ID', 'default')
    if request.user.is_authenticated:
        return f"tenant:{tenant_id}:user:{request.user.id}"
    return f"tenant:{tenant_id}:ip:{request.META.get('REMOTE_ADDR')}"

@rate_limit(key=get_tenant_key, rate='500/h')
def multi_tenant_api(request):
    return JsonResponse({'tenant': 'data'})
```

--------------------------------

### Custom Rate Limiting with Lambda Function Key

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Shows how to define a custom rate limiting key using a lambda function. This allows for dynamic key generation based on request attributes, such as an API key from headers. This example limits requests to 100 per minute, keyed by API key or 'anonymous'.

```python
@rate_limit(
    key=lambda req: f"api_key:{req.headers.get('X-API-Key', 'anonymous')}",
    rate='100/m'
)
def api_with_keys(request):
    return JsonResponse({'data': 'api_key_based'})
```

--------------------------------

### Multi-Tier Rate Limiting Example

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/utilities.md

Demonstrates how to implement multi-tier rate limiting based on user subscription levels. The `tier_based_key` function generates a unique key incorporating the user's tier and ID. This allows different rate limits to be applied to users based on their subscription plan, ensuring fair usage.

```python
from django_smart_ratelimit import rate_limit, get_device_fingerprint_key

def tier_based_key(request):
    """Rate limiting based on user subscription tier."""
    if hasattr(request, 'user') and request.user.is_authenticated:
        tier = getattr(request.user, 'subscription_tier', 'basic')
        return f"{tier}:user:{request.user.id}"
    return get_device_fingerprint_key(request)

@rate_limit(key=tier_based_key, rate='1000/h')  # Adjust per tier
def premium_feature(request):
    return JsonResponse({"premium": "content"})
```

--------------------------------

### Configure IP Address Detection Metadata Keys

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

This setting configures the metadata keys Django Smart RateLimit uses to detect client IP addresses. It includes common headers like `HTTP_CF_CONNECTING_IP` (Cloudflare), `HTTP_X_FORWARDED_FOR` (proxies), `HTTP_X_REAL_IP` (Nginx), and falls back to `REMOTE_ADDR`. This ensures accurate IP identification in various proxy setups.

```python
# settings.py
RATELIMIT_IP_META_KEYS = [
    'HTTP_CF_CONNECTING_IP',    # Cloudflare
    'HTTP_X_FORWARDED_FOR',     # Standard proxy
    'HTTP_X_REAL_IP',           # Nginx
    'REMOTE_ADDR',              # Fallback
]
```

--------------------------------

### Lenient Rate Limiting with Blocking Disabled

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Shows how to configure the `@rate_limit` decorator to operate in a non-blocking mode. When the rate limit is exceeded, requests are not blocked, but rate limit information (e.g., headers) is still added to the response. This allows the request to proceed while signaling the rate limit status. This example limits to 10 per minute.

```python
@rate_limit(key='ip', rate='10/m', block=False)
def lenient_api(request):
    # Continues execution but adds rate limit headers
    return JsonResponse({'data': 'lenient'})
```

--------------------------------

### Run Tests with Pytest and Coverage

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/README.md

Execute the project's test suite using pytest. To generate a code coverage report, use the `--cov` flag along with the package name.

```bash
# Run tests
python -m pytest

# Run with coverage
python -m pytest --cov=django_smart_ratelimit
```

--------------------------------

### Custom Rate Limiting with Class-based Key Generator

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

Demonstrates creating a custom rate limiting key using a class instance. The class implements the `__call__` method to generate the key dynamically based on request attributes, allowing for stateful key generation or configuration. This example limits requests to 200 per minute, keyed by API key or IP.

```python
class RateLimitKeyGenerator:
    def __init__(self, prefix='custom'):
        self.prefix = prefix

    def __call__(self, request):
        if hasattr(request, 'api_key'):
            return f"{self.prefix}:api_key:{request.api_key}"
        return f"{self.prefix}:ip:{request.META.get('REMOTE_ADDR')}"

api_key_generator = RateLimitKeyGenerator('api')

@rate_limit(key=api_key_generator, rate='200/m')
def custom_key_api(request):
    return JsonResponse({'custom': 'key'})
```

--------------------------------

### Database Backend Tuning for Rate Limiting

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/CONTRIBUTING.md

Details database backend tuning for Django Smart Ratelimit. It suggests increasing the frequency of database cleanup by setting `RATELIMIT_DATABASE_CLEANUP_THRESHOLD` and recommends using the `fixed_window` algorithm for potentially faster database operations. It also includes example SQL commands for adding necessary database indexes to improve query performance.

```python
# settings.py - Database backend optimization
RATELIMIT_DATABASE_CLEANUP_THRESHOLD = 5000  # Clean more frequently
RATELIMIT_ALGORITHM = 'fixed_window'          # Faster for DB

# Add database indexes (in your migration)
"""
ALTER TABLE django_smart_ratelimit_ratelimitentry
ADD INDEX idx_key_window (key, window_start);

ALTER TABLE django_smart_ratelimit_ratelimitcounter
ADD INDEX idx_key_expires (key, expires_at);
"""
```

--------------------------------

### Implement Graceful Degradation for Rate Limited Views in Python

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/decorator.md

This Python example shows how to implement graceful degradation for API views when rate limits are exceeded. It uses the `@rate_limit` decorator and checks for a custom attribute `request.rate_limit_exceeded` (which would typically be set by middleware) to conditionally modify the response data. This allows serving a limited response instead of an error when the rate limit is hit.

```python
from django.http import JsonResponse
from django_smart_ratelimit.decorators import rate_limit

@rate_limit(key='user', rate='100/h', block=False)
def graceful_api(request):
    response_data = {'data': 'full_response'}

    # Check rate limit status from headers
    # Note: This requires custom middleware or response processing
    if hasattr(request, 'rate_limit_exceeded'):
        response_data = {'data': 'limited_response'}

    return JsonResponse(response_data)
```

--------------------------------

### Database Backend Configuration

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/README.md

Configures the library to use Django's default database as the rate limiting backend. No additional configuration is typically needed beyond setting `RATELIMIT_BACKEND` to 'database'.

```python
RATELIMIT_BACKEND = 'database'
# Uses your default Django database
```

--------------------------------

### Datadog Integration Configuration for Django Rate Limiting

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/installation.md

This Django settings snippet configures integration with Datadog for monitoring rate limiting. It specifies 'datadog' as the monitoring backend and provides a configuration dictionary including the API key (fetched from environment variables) and tags for organizing metrics. This allows for centralized monitoring and alerting on rate limiting events.

```python
# settings.py
RATELIMIT_MONITORING = {
    'BACKEND': 'datadog',
    'CONFIG': {
        'api_key': os.environ.get('DATADOG_API_KEY'),
        'tags': ['environment:production', 'service:ratelimit'],
    }
}
```

--------------------------------

### Middleware Configuration (Python)

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/design.md

Python settings example for configuring Django Smart Ratelimit's middleware. It includes default rate, backend, custom key function, blocking, skip paths, and specific rate limits for different URL paths.

```python
# settings.py
RATELIMIT_MIDDLEWARE = {
    'DEFAULT_RATE': '100/m',
    'BACKEND': 'redis',
    'KEY_FUNCTION': 'myapp.utils.custom_key_function',
    'BLOCK': True,
    'SKIP_PATHS': ['/admin/', '/health/'],
    'RATE_LIMITS': {
        '/api/': '1000/h',
        '/auth/': '5/m',
    }
}
```

--------------------------------

### Decorator Configuration (Python)

Source: https://github.com/yassershkeir/django-smart-ratelimit/blob/main/docs/design.md

Python example demonstrating how to configure rate limiting using the `@rate_limit` decorator on a Django view. It shows parameters for key generation, rate limits, blocking behavior, and backend selection.

```python
@rate_limit(
    key='user:{user.id}',     # Key template or callable
    rate='10/m',              # Rate limit (10 per minute)
    block=True,               # Block or allow with headers
    backend='redis'           # Backend to use
)
def my_view(request):
    pass
```
Tokens:
Raw