djresttoolkit
Advanced tools
djresttoolkit is a collection of utilities and helpers for Django and Django REST Framework (DRF) that simplify common development tasks such as API handling, authentication, and email sending and much more.
DB Seed Command (dbseed)
Seed your database with fake data using Pydantic models powered by Faker. Supports relationships, transactions, and a manage.py dbseed command.
DB Flush Command (dbflush)
Management command to flush all models or a specific model, resetting auto-increment IDs safely with transaction support.
BaseEnvConfig Singleton environment loader that reads and parses environment variables.
EmailSender
Custom class to send templated emails (text and html) with context. Supports error handling and logging.
Custom DRF Exception Handler
Centralized error handler for DRF that extends default behavior and adds throttle support (429 Too Many Requests with retry info).
Response Time Middleware
Middleware to measure, log, and inject X-Response-Time headers into every response.
Throttle
ThrottleInfoJSONRenderer: Automatically adds throttle headers to responses.ThrottleInspector: Inspect view/request throttling and attach structured headers.AbsoluteUrlFileMixin
DRF serializer mixin that converts FileField / ImageField URLs to absolute URLs automatically.
BulkCreateMixin Serializer mixin that enables bulk creation of objects and syncs field error messages with model fields.
ModelChoiceFieldMixin
Retrieve choice fields (TextChoices, etc.) from Django models as structured dictionaries for API responses.
ChoiceFieldsAPIView
Generic API view that exposes model choices in a REST-friendly JSON format.
RetrieveObjectMixin
Lightweight mixin to fetch a single object from a queryset with filters, raising a custom error if queryset is not defined.
build_absolute_uri Helper to build full absolute URLs for named routes with optional query params. Works with Django + DRF requests.
PageNumberPagination
Custom paginator with a structured "page" metadata block and support for dynamic page-size query param.
PaginatedDataBuilder
Builder that combines PageNumberPagination + serializers to return standardized paginated responses with "page" + "results".
Caching Mixins
This module provides a set of DRF mixins to handle caching for list, retrieve, and custom actions with automatic invalidation on create, update, and destroy.
By using uv:
uv add djresttoolkit
By using pip:
pip install djresttoolkit
Generatorfrom djresttoolkit.dbseed.models import Generator, Gen, Field
Gen: Pre-initialized Faker instance for generating fake data.Field: Alias for pydantic.Field to define seed model fields.from djresttoolkit.dbseed.models import SeedModel
from myapp.models import User
class UserSeedModel(SeedModel):
__model__ = User
username: str = Field(default_factory=lambda: Gen.user_name())
email: str = Field(default_factory=lambda: Gen.email())
manage.py Command: dbseedSeed the database from all dbseed directories in installed apps.
python manage.py dbseed [--count 5] [--model User] [--seed 42]
--count: Number of records per model (default: 5).--model: Specific model name to seed (optional).--seed: Faker seed for reproducible data (optional).dbseed models in installed apps.# Seed 10 records for all models
python manage.py dbseed --count 10
# Seed only the User model with fixed Faker seed
python manage.py dbseed --model User --seed 42
from djresttoolkit.management.commands import flush
manage.py dbflushCommand to delete all records from the database for all models or a specific model and reset auto-increment IDs.
python manage.py flush [--model ModelName] [--yes]
--model: Name of the model to flush (case-sensitive, e.g., User). If omitted, flushes all models.--yes: Skip confirmation prompt. Without this, the command asks for confirmation before deleting.Deletes all records for the specified model or all models.
Resets primary key sequences for supported databases:
ALTER SEQUENCE ... RESTART WITH 1sqlite_sequence tableUses transactions to ensure safe operations.
# Flush all models with confirmation
python manage.py dbflush
# Flush a specific model (User) with confirmation
python manage.py dbflush --model User
# Flush all models without prompt
python manage.py dbflush --yes
Flushed 10 records from model "User" and reset IDs.
or
Flushed 120 records from all models and reset IDs.
from djresttoolkit.envconfig import BaseEnvConfig
BaseEnvConfigSingleton environment loader that reads and parses environment variables with support for booleans, numbers, and JSON.
⚠️ Note: Note: If you are using a .env file, load it first with python-dotenv:
from dotenv import load_dotenv load_dotenv()
or
from djresttoolkit.envconfig import load_dotenv
load_dotenv()
from djresttoolkit.envconfig import load_dotenv, BaseEnvConfig
load_dotenv()
class EnvConfig(BaseEnvConfig):
DEBUG: bool = False
DATABASE_URL: str
config = EnvConfig()
print(config.DEBUG)
print(config.DATABASE_URL)
config.reload()
from djresttoolkit.mail import EmailSender, EmailContent, EmailTemplate
EmailSenderSend templated emails.
EmailSender(email_content: EmailContent | EmailContentDict)
send(to: list[str], exceptions: bool = False) -> bool
to: recipient emailsexceptions: raise on error if True, else logs errorTrue if sent, False on failurecontent = EmailContent(
subject="Hello",
from_email="noreply@example.com",
context={"username": "Alice"},
template=EmailTemplate(
text="emails/welcome.txt",
html="emails/welcome.html"
)
)
EmailSender(content).send(to=["user@example.com"])
EmailContentsubject, from_email, context, template (EmailTemplate)EmailTemplatetext, html — template file pathsfrom djresttoolkit.views import exception_handler
exception_handler(exc: Exception, context: dict[str, Any]) -> Response | NoneA DRF exception handler that:
AnonRateThrottle).retry_after if throttle limit is exceeded.exc: Exception object.context: DRF context dictionary containing "request" and "view".Response — DRF Response object (with throttling info if applicable), or None.In settings.py:
REST_FRAMEWORK = {
'EXCEPTION_HANDLER': 'djresttoolkit.views.exception_handler',
# Other DRF settings...
}
view.throttle_classes if defined, else defaults to AnonRateThrottle.retry_after.from djresttoolkit.middlewares import ResponseTimeMiddleware
ResponseTimeMiddlewareMiddleware to calculate and log HTTP response time for each request.
ResponseTimeMiddleware(get_response: Callable[[HttpRequest], HttpResponse])
get_response: The next middleware or view callable.Add it to your Django MIDDLEWARE in settings.py:
MIDDLEWARE = [
# Other middlewares...
'djresttoolkit.middlewares.ResponseTimeMiddleware',
]
X-Response-Time to each HTTP response.X-Response-Time: 0.01234 seconds
INFO: Request processed in 0.01234 seconds
ThrottleInfoJSONRendererfrom djresttoolkit.renderers import ThrottleInfoJSONRenderer
A custom DRF JSON renderer that automatically attaches throttle information to response headers.
REST_FRAMEWORK = {
"DEFAULT_RENDERER_CLASSES": [
"djresttoolkit.renderers.ThrottleInfoJSONRenderer",
"rest_framework.renderers.BrowsableAPIRenderer",
],
}
When enabled, every response includes throttle headers like:
X-Throttle-User-Limit: 100
X-Throttle-User-Remaining: 98
X-Throttle-User-Reset: 2025-08-18T07:30:00Z
X-Throttle-User-Retry-After: 0
ThrottleInspectorfrom djresttoolkit.throttling import ThrottleInspector
Utility class to inspect DRF throttle usage for a view or request.
ThrottleInspector(
view: APIView,
request: Request | None = None,
throttle_classes: list[type[BaseThrottle]] | None = None,
)
get_details() -> dict[str, Any]
Returns structured throttle info: limit, remaining, reset time, retry_after.
attach_headers(response: Response, throttle_info: dict | None)
Attaches throttle data to HTTP headers.
from djresttoolkit.serializers.mixins import AbsoluteUrlFileMixin
AbsoluteUrlFileMixinA serializer mixin that converts FileField and ImageField URLs to absolute URLs, ensuring compatibility with cloud storage backends.
file_fieldslist[str] | NoneNoneto_representation(self, instance: Any) -> dict[str, Any]to_representation.enhance_file_fields(self, instance: Any, representation: dict[str, Any], request: Any) -> dict[str, Any]request.build_absolute_uri().file_fields.MissingRequestContext: Raised if the request object is missing in serializer context and DEBUG=True.from rest_framework import serializers
from djresttoolkit.serializers.mixins import AbsoluteUrlFileMixin
from myapp.models import Document
class DocumentSerializer(AbsoluteUrlFileMixin, serializers.ModelSerializer):
class Meta:
model = Document
fields = ["id", "title", "file"]
# Output will convert `file` field to an absolute URL
serializer = DocumentSerializer(instance, context={"request": request})
data = serializer.data
file_fields for non-model serializers.from djresttoolkit.serializers.mixins import BulkCreateMixin
BulkCreateMixinA DRF serializer mixin that adds support for:
bulk_create() does not trigger model signals or call .save() on instances.Meta.model must be defined in the serializer.create(self, validated_data: dict[str, Any] | list[dict[str, Any]]) -> Model | list[Model]validated_data: dict for single instance or list of dicts for bulk creation.AttributeError if Meta.model is not defined.NotImplementedError if used with a serializer that does not implement create().get_fields(self) -> dict[str, SerializerField]Extends DRF serializer get_fields() to update error messages using model field definitions.
Returns:
Warning:
from rest_framework import serializers
from djresttoolkit.serializers.mixins import BulkCreateMixin
from myapp.models import Product
class ProductSerializer(BulkCreateMixin, serializers.ModelSerializer):
class Meta:
model = Product
fields = ["id", "name", "price"]
# Single creation
serializer = ProductSerializer(data={"name": "Item1", "price": 10})
serializer.is_valid(raise_exception=True)
product = serializer.save()
# Bulk creation
serializer = ProductSerializer(
data=[
{"name": "Item2", "price": 20},
{"name": "Item3", "price": 30},
],
many=True
)
serializer.is_valid(raise_exception=True)
products = serializer.save()
ModelSerializer.model.objects.bulk_create() for efficiency.from djresttoolkit.models.mixins import ModelChoiceFieldMixin
ModelChoiceFieldMixinA Django model mixin to retrieve choice fields from a model, designed to work seamlessly with Django's TextChoices.
model: type[Model] | None — The Django model class to inspect. Must be set.choice_fields: list[str] | None — List of model field names that contain choices. Must be set.get_choices() -> dict[str, dict[str, str]]Retrieve the choice fields from the model as a dictionary.
Returns:
{
"field_name": {
"choice_value": "Choice Label",
...
},
...
}
Raises:
AttributeDoesNotExist — If model or choice_fields is not set.ChoiceFieldNotFound — If a field does not exist, has no choices, or has invalid choice format.from django.db import models
from djresttoolkit.serializers.mixins import ModelChoiceFieldMixin
class Product(models.Model):
class Status(models.TextChoices):
DRAFT = "draft", "Draft"
PUBLISHED = "published", "Published"
status = models.CharField(max_length=20, choices=Status.choices)
category = models.CharField(max_length=50, choices=[
("a", "Category A"),
("b", "Category B"),
])
class ProductChoiceMixin(ModelChoiceFieldMixin):
model = Product
choice_fields = ["status", "category"]
choices = ProductChoiceMixin.get_choices()
print(choices)
# Output:
# {
# "status": {"draft": "Draft", "published": "Published"},
# "category": {"a": "Category A", "b": "Category B"}
# }
Here’s a concise docs entry for your ChoiceFieldsAPIView suitable for djresttoolkit documentation:
from djresttoolkit.views import ChoiceFieldsAPIView
ChoiceFieldsAPIViewA generic DRF API view to return all choices for specified model fields.
model_class: type[Model] | None — The Django model to inspect. Must be set.choice_fields: list[str] | None — List of fields on the model with choices. Must be set.get(request: Request) -> ResponseFetches the choices for the configured model fields.
Returns:
200 OK — JSON object containing all choices:
{
"choices": {
"status": {"draft": "Draft", "published": "Published"},
"category": {"a": "Category A", "b": "Category B"}
}
}
400 Bad Request — If any error occurs while retrieving choices.
Raises:
AttributeDoesNotExist — If model_class or choice_fields is not set.from django.urls import path
from djresttoolkit.views import ChoiceFieldsAPIView
from myapp.models import Product
class ProductChoiceAPI(ChoiceFieldsAPIView):
model_class = Product
choice_fields = ["status", "category"]
urlpatterns = [
path(
"api/v1/product-choices/",
ProductChoiceAPI.as_view(),
name="product-choices"
),
]
ModelChoiceFieldMixin from djresttoolkit.from djresttoolkit.views.mixins import RetrieveObjectMixin
RetrieveObjectMixin[T: Model]A generic mixin to retrieve a single Django model instance by filters.
queryset: QuerySet[T] | None — The queryset used to retrieve objects. Must be set.QuerysetNotDefinedError — If queryset is not set in the class.get_object(**filters: Any) -> T | NoneRetrieve a single model object using the provided filter criteria.
Parameters:
**filters — Keyword arguments to filter the queryset (e.g., id=1, slug="abc").Returns:
None if no match is found.from rest_framework.views import APIView
from rest_framework.response import Respone
from django.http import JsonResponse
from myapp.models import Book
from djresttoolkit.mixins import RetrieveObjectMixin
class BookDetailView(RetrieveObjectMixin[Book], APIView):
queryset = Book.objects.all()
def not_found_detail(self) -> dict[str, str] | str:
return "The requested Book was not found."
def get(self, request, *args, **kwargs) -> Respone:
book = self.get_object(id=kwargs["id"])
return Respone({"title": book.title, "author": book.author})
http404 if requested resource does not extst.from djresttoolkit.urls import build_absolute_uri
HttpRequest and DRF Request objects.reverse() to dynamically resolve URL names.def build_absolute_uri(
request: HttpRequest | Request,
url_name: str,
query_params: dict[str, Any] | None = None,
*args: Any,
**kwargs: Any,
) -> str:
...
request (HttpRequest | Request): The incoming Django or DRF request object.url_name (str): Name of the URL pattern to reverse.query_params (dict[str, Any] | None): Optional dictionary of query parameters to append to the URL.*args (Any): Positional arguments for the URL reversal.**kwargs (Any): Keyword arguments for the URL reversal.str: Absolute URI of the view including optional query parameters.from django.http import HttpRequest
from djresttoolkit.utils import build_absolute_uri
def my_view(request: HttpRequest):
absolute_url = build_absolute_uri(
request,
url_name="book-detail",
query_params={"ref": "newsletter"},
pk=123
)
return HttpResponse(f"URL: {absolute_url}")
Output Example:
https://example.com/api/books/123/?ref=newsletter
from djresttoolkit.pagination import PageNumberPagination
PageNumberPagination with a cleaner metadata structure.page-size query parameter."page" object, separate from "results".Clients can control items per page using ?page-size=.
Structured pagination metadata:
current:- current page numbertotal:- total number of pagessize:- number of items per pagetotal_items:- total number of items across all pagesnext:- next page URLprevious:- previous page URLStandardized API response format.
page_size_query_param: str:- Query parameter name ("page-size").get_paginated_response(data: Any) -> Response
Returns a JSON response with both pagination metadata and results.{
"page": {
"current": 1,
"total": 10,
"size": 20,
"total_items": 200,
"next": "http://api.example.com/items/?page=2&page-size=20",
"previous": null
},
"results": [
{ "id": 1, "name": "Item 1" },
{ "id": 2, "name": "Item 2" }
]
}
from djresttoolkit.pagination import PaginatedDataBuilder
PageNumberPagination class for consistent pagination responses.NotFound."page":- pagination metadata"results":- serialized data.builder = PaginatedDataBuilder(
request=request,
serializer_class=BookSerializer,
queryset=MyModel.objects.all()
)
request: Request:- DRF request object.serializer_class: type[BaseSerializer]:- DRF serializer class for the model.queryset: QuerySet:- Django queryset to paginate.get_paginated_data() -> dict[str, Any]
"page" and "results".NotFound if no page data is found.paginated_data -> dict[str, Any]
paginated_data property that internaly call get_paginated_data() method{
"page": {
"current": 2,
"total": 5,
"size": 20,
"total_items": 100,
"next": "http://api.example.com/items/?page=3&page-size=20",
"previous": "http://api.example.com/items/?page=1&page-size=20"
},
"results": [
{ "id": 21, "title": "Title 21" },
{ "id": 22, "title": "Title 22" }
]
}
This module provides a set of DRF mixins to handle caching for list, retrieve, and custom actions with automatic invalidation on create, update, and destroy.
CacheKeyMixincache_timeout: int = 300:- default cache duration in seconds.get_cache_timeout():- returns the cache timeout.get_cache_key(action_type, pk=None, action_name=None):- returns a cache key string based on action type:**
list or custom-list:- hash of query parameters.retrieve or custom-detail:- uses primary key (pk).CacheOpsMixinget_or_set_cache(cache_key, data_fn, timeout=None):- fetch from cache or compute and set.invalidate_cache(pk=None, custom_actions=None):- delete cached items:
pk.delete_pattern if available).CacheActionMixin@action methods.cache_action(detail=False, action_name=None):- returns a decorator that caches action results automatically.detail=False:- custom-list action cache.detail=True:- custom-detail action cache.CacheListRetrieveMixinlist() and retrieve() responses.list(request, *args, **kwargs):- caches list responses.retrieve(request, *args, **kwargs):- caches detail responses._get_list_data(request):- internal method to fetch paginated list data._get_detail_data():- internal method to fetch a single object.CacheInvalidateMixincreate(request, *args, **kwargs):- invalidates list caches.update(request, *args, **kwargs):- invalidates detail caches for pk.destroy(request, *args, **kwargs):- invalidates detail caches for pk.from rest_framework.viewsets import ModelViewSet
from myapp.models import Book
from myapp.serializers import BookSerializer
from djresttoolkit.cache.mixins import CacheInvalidateMixin, CacheActionMixin
class BookViewSet(CacheInvalidateMixin, ModelViewSet):
queryset = Book.objects.all()
serializer_class = BookSerializer
basename = "book"
@CacheActionMixin.cache_action(detail=False)
def popular(self, request):
data = Book.objects.filter(is_popular=True)
serializer = self.get_serializer(data, many=True)
return Response(serializer.data)
list, retrieve, and popular actions.A subclass of Django REST Framework’s ModelSerializer that automatically merges Django model field error_messages into the serializer field, unless explicitly overridden.
This helps maintain consistent validation messages between the model and the serializer.
T (Model): The Django model type that the serializer corresponds to.from myapp.models import Book
from myapp.serializers import EnhancedModelSerializer
class BookSerializer(EnhancedModelSerializer[Book]):
class Meta:
model = Book
fields = "__all__"
Contributions are welcome! Please open an issue or PR for any improvements.
MIT License — See LICENSE.
For questions or assistance, contact Shailesh at shaileshpandit141@gmail.com.
FAQs
A collection of Django and DRF utilities to simplify API development.
We found that djresttoolkit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Product
Socket Firewall Free is now bundled into Docker Hardened Images, adding build-time and dependency-install supply chain protection on top of hardened base images for Node.js, Python, and Rust.
Security News
Season’s greetings from Socket, and here’s to a calm end of year: clean dependencies, boring pipelines, no surprises.
Research
/Security News
Impostor NuGet package Tracer.Fody.NLog typosquats Tracer.Fody and its author, using homoglyph tricks, and exfiltrates Stratis wallet JSON/passwords to a Russian IP address.