djresttoolkit 0.6.2

A collection of Django and DRF utilities to simplify API development.

🛠️ djresttoolkit (django rest toolkit)

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.

✨ Features

• Django REST Framework helpers (serializers, views, pagination, etc.)
• Django utilities (e.g., email sending, model mixins)
• Ready-to-use shortcuts to speed up API development
• Lightweight, no unnecessary dependencies
• Type Safe - written with modern Python type hints.

📦 Installation

• By using uv:

  uv add djresttoolkit
  

• By using pip:

  pip install djresttoolkit
  

📚 All API Reference

1. DB Seed Utilities

Generator

from 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.

Example

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: dbseed

Seed the database from all dbseed directories in installed apps.

python manage.py dbseed [--count 5] [--model User] [--seed 42]

Options

• --count: Number of records per model (default: 5).
• --model: Specific model name to seed (optional).
• --seed: Faker seed for reproducible data (optional).

Behavior

• Auto-discovers all dbseed models in installed apps.
• Handles ForeignKey, OneToOneField, and ManyToMany relationships.
• Uses transactions to ensure safe creation of records.
• Logs errors for failed instance creation but continues seeding.

Command Example

# 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

2. EmailSender

from djresttoolkit.mail import EmailSender, EmailContent, EmailTemplate

EmailSender

Send templated emails.

Init

EmailSender(email_content: EmailContent | EmailContentDict)

Methods

send(to: list[str], exceptions: bool = False) -> bool

• to: recipient emails
• exceptions: raise on error if True, else logs error
• Returns True if sent, False on failure

Example for sending an email

content = EmailContent(
    subject="Hello",
    from_email="[e-mail]",
    context={"username": "Alice"},
    template=EmailTemplate(
        text="emails/welcome.txt",
        html="emails/welcome.html"
    )
)
EmailSender(content).send(to=["[e-mail]"])

EmailContent

• subject, from_email, context, template (EmailTemplate)

EmailTemplate

• text, html — template file paths

3. Custom DRF Exception Handler

from djresttoolkit.views import exception_handler

exception_handler(exc: Exception, context: dict[str, Any]) -> Response | None

A DRF exception handler that:

• Preserves DRF’s default exception behavior.
• Adds throttling support (defaults to AnonRateThrottle).
• Returns 429 Too Many Requests with retry_after if throttle limit is exceeded.

Parameters

• exc: Exception object.
• context: DRF context dictionary containing "request" and "view".

Returns

• Response — DRF Response object (with throttling info if applicable), or None.

Settings Configuration

In settings.py:

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'djresttoolkit.views.exception_handler',
    # Other DRF settings...
}

Throttle Behavior

• Uses view.throttle_classes if defined, else defaults to AnonRateThrottle.
• Tracks requests in cache and calculates retry_after.
• Cleans expired timestamps automatically.

4. Response Time Middleware

from djresttoolkit.middlewares import ResponseTimeMiddleware

ResponseTimeMiddleware

Middleware to calculate and log HTTP response time for each request.

Constructor from ResponseTimeMiddleware

ResponseTimeMiddleware(get_response: Callable[[HttpRequest], HttpResponse])

• get_response: The next middleware or view callable.

Usage

Add it to your Django MIDDLEWARE in settings.py:

MIDDLEWARE = [
    # Other middlewares...
    'djresttoolkit.middlewares.ResponseTimeMiddleware',
]

Response Time Middleware Behavior

• Measures the time taken to process each request.
• Adds a header X-Response-Time to each HTTP response.
• Logs the response time using Django's logging system.

The response headers will include

X-Response-Time: 0.01234 seconds

Logs a message

INFO: Request processed in 0.01234 seconds

5. Throttle Utilities

ThrottleInfoJSONRenderer

from djresttoolkit.renderers import ThrottleInfoJSONRenderer

A custom DRF JSON renderer that automatically attaches throttle information to response headers.

Usage (settings.py)

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

ThrottleInspector

from djresttoolkit.throttling import ThrottleInspector

Utility class to inspect DRF throttle usage for a view or request.

Constructor for ThrottleInspector

ThrottleInspector(
    view: APIView,
    request: Request | None = None,
    throttle_classes: list[type[BaseThrottle]] | None = None,
)

Key Methods

• 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.

🛠️ Planned Features

• Add more utils

🤝 Contributing

Contributions are welcome! Please open an issue or PR for any improvements.

📜 License

MIT License — See LICENSE.

👤 Author

For questions or assistance, contact Shailesh at [e-mail].