Installation¶

Requirements¶

drf-commons requires:

Python 3.8 or higher
Django 3.2 or higher
Django REST Framework 3.12 or higher

Core Installation¶

Install the base package from PyPI:

pip install drf-commons

The core installation includes the full view layer, model mixins, serializer utilities, response formatting, middleware, pagination, and filtering. It does not install optional feature dependencies.

Optional Feature Sets¶

drf-commons uses extras to keep the core dependency surface minimal:

# File export support (CSV, XLSX, PDF)
pip install drf-commons[export]

# File import support (CSV, XLS, XLSX via pandas)
pip install drf-commons[import]

# Debug and profiling utilities (psutil)
pip install drf-commons[debug]

# All optional features
pip install drf-commons[export,import,debug]

Optional Dependencies¶
Extra	Packages Installed	Enables
`export`	`openpyxl>=3.0`, `weasyprint>=60.0`	`ExportService` (XLSX, PDF)
`import`	`openpyxl>=3.0`, `pandas>=1.3`	`FileImportService`
`debug`	`psutil>=5.9`	Memory usage monitoring in debug utilities

Development Installation¶

For contributing or local development:

git clone https://github.com/htvictoire/drf-commons
cd drf-commons

# Full development environment
pip install -e ".[export,import,debug]"

# Install development tools
pip install -e ".[dev,test]"

# Install documentation tools
pip install -r docs/requirements.txt

Django Application Setup¶

Add drf_commons to your INSTALLED_APPS:

# settings.py
INSTALLED_APPS = [
    "django.contrib.contenttypes",
    "django.contrib.auth",
    ...
    "rest_framework",
    "drf_commons",
    ...
]

Middleware Configuration¶

If you use UserActionMixin or CurrentUserField, add CurrentUserMiddleware to your middleware stack:

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    ...
    "drf_commons.middlewares.CurrentUserMiddleware",
    ...
]

Important

CurrentUserMiddleware must be placed after Django’s authentication middleware (django.contrib.auth.middleware.AuthenticationMiddleware) to ensure request.user is populated when the middleware executes.

Configuration Namespace¶

drf-commons reads its configuration from the COMMON dictionary in settings.py. All settings have defaults and are optional:

COMMON = {
    # Batch sizing
    "BULK_OPERATION_BATCH_SIZE": 1000,
    "IMPORT_BATCH_SIZE": 250,

    # Performance thresholds (seconds)
    "DEBUG_SLOW_REQUEST_THRESHOLD": 1.0,
    "DEBUG_SLOW_QUERY_THRESHOLD": 0.1,

    # Query thresholds (count)
    "DEBUG_HIGH_QUERY_COUNT_THRESHOLD": 10,

    # Failed row display limit in import reports
    "IMPORT_FAILED_ROWS_DISPLAY_LIMIT": 10,
}

Verifying Installation¶

import drf_commons
print(drf_commons.__version__)

from drf_commons.models import BaseModelMixin
from drf_commons.views import BaseViewSet
from drf_commons.serializers import BaseModelSerializer
from drf_commons.response import success_response, error_response

All imports at the top level are the primary public API.