djresttoolkit 0.4.0__tar.gz → 0.6.0__tar.gz

{djresttoolkit-0.4.0 → djresttoolkit-0.6.0}/.gitignore

@@ -8,4 +8,6 @@ wheels/
 
 # Virtual environments
 .venv
+**/.env
+**/.environ.yaml
 temp.py

{djresttoolkit-0.4.0 → djresttoolkit-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djresttoolkit
-Version: 0.4.0
+Version: 0.6.0
 Summary: A collection of Django and DRF utilities to simplify API development.
 Project-URL: Homepage, https://github.com/shaileshpandit141/djresttoolkit
 Project-URL: Documentation, https://shaileshpandit141.github.io/djresttoolkit
@@ -46,6 +46,7 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
+Requires-Dist: faker>=37.5.3
 Requires-Dist: pydantic>=2.11.7
 Provides-Extra: dev
 Requires-Dist: mypy; extra == 'dev'
@@ -85,7 +86,197 @@ djresttoolkit is a collection of utilities and helpers for Django and Django RES
 
 ## 📚 API Reference
 
-### Under the development
+### 1. EmailSender
+
+```python
+from djresttoolkit.mail import EmailSender, EmailContent, EmailTemplate
+```
+
+### `EmailSender`
+
+Send templated emails.
+
+#### Init
+
+```python
+EmailSender(email_content: EmailContent | EmailContentDict)
+```
+
+#### Methods
+
+```python
+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
+
+```python
+content = 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"])
+```
+
+#### `EmailContent`
+
+- `subject`, `from_email`, `context`, `template` (EmailTemplate)
+
+#### `EmailTemplate`
+
+- `text`, `html` — template file paths
+
+### 2. Custom DRF Exception Handler
+
+```python
+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`:
+
+```python
+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.
+
+### 3. Response Time Middleware
+
+```python
+from djresttoolkit.middlewares import ResponseTimeMiddleware
+```
+
+### `ResponseTimeMiddleware`
+
+Middleware to calculate and log **HTTP response time** for each request.
+
+#### Constructor from ResponseTimeMiddleware
+
+```python
+ResponseTimeMiddleware(get_response: Callable[[HttpRequest], HttpResponse])
+```
+
+- `get_response`: The next middleware or view callable.
+
+#### Usage
+
+Add it to your Django `MIDDLEWARE` in `settings.py`:
+
+```python
+MIDDLEWARE = [
+    # Other middlewares...
+    'djresttoolkit.middlewares.ResponseTimeMiddleware',
+]
+```
+
+#### 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
+
+```json
+X-Response-Time: 0.01234 seconds
+```
+
+#### Logs a message
+
+```bash
+INFO: Request processed in 0.01234 seconds
+```
+
+### 4. Throttle Utilities
+
+#### `ThrottleInfoJSONRenderer`
+
+```python
+from djresttoolkit.renderers import ThrottleInfoJSONRenderer
+```
+
+A custom DRF JSON renderer that **automatically attaches throttle information to response headers**.
+
+#### Usage (settings.py)
+
+```python
+REST_FRAMEWORK = {
+    "DEFAULT_RENDERER_CLASSES": [
+        "djresttoolkit.renderers.ThrottleInfoJSONRenderer",
+        "rest_framework.renderers.BrowsableAPIRenderer",
+    ],
+}
+```
+
+When enabled, every response includes throttle headers like:
+
+```plaintext
+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`
+
+```python
+from djresttoolkit.throttling import ThrottleInspector
+```
+
+Utility class to **inspect DRF throttle usage** for a view or request.
+
+#### Constructor for ThrottleInspector
+
+```python
+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
 

djresttoolkit-0.6.0/README.md

@@ -0,0 +1,239 @@
+# 🛠️ djresttoolkit (django rest toolkit)
+
+[![PyPI version](https://img.shields.io/pypi/v/djresttoolkit.svg)](https://pypi.org/project/djresttoolkit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/djresttoolkit.svg)](https://pypi.org/project/djresttoolkit/)
+[![License](https://img.shields.io/pypi/l/djresttoolkit.svg)](https://github.com/shaileshpandit141/djresttoolkit/blob/main/LICENSE)
+
+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:**
+  
+    ```bash
+    uv add djresttoolkit
+    ````
+
+- **By using pip:**
+
+    ```bash
+    pip install djresttoolkit
+    ````
+
+## 📚 API Reference
+
+### 1. EmailSender
+
+```python
+from djresttoolkit.mail import EmailSender, EmailContent, EmailTemplate
+```
+
+### `EmailSender`
+
+Send templated emails.
+
+#### Init
+
+```python
+EmailSender(email_content: EmailContent | EmailContentDict)
+```
+
+#### Methods
+
+```python
+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
+
+```python
+content = 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"])
+```
+
+#### `EmailContent`
+
+- `subject`, `from_email`, `context`, `template` (EmailTemplate)
+
+#### `EmailTemplate`
+
+- `text`, `html` — template file paths
+
+### 2. Custom DRF Exception Handler
+
+```python
+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`:
+
+```python
+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.
+
+### 3. Response Time Middleware
+
+```python
+from djresttoolkit.middlewares import ResponseTimeMiddleware
+```
+
+### `ResponseTimeMiddleware`
+
+Middleware to calculate and log **HTTP response time** for each request.
+
+#### Constructor from ResponseTimeMiddleware
+
+```python
+ResponseTimeMiddleware(get_response: Callable[[HttpRequest], HttpResponse])
+```
+
+- `get_response`: The next middleware or view callable.
+
+#### Usage
+
+Add it to your Django `MIDDLEWARE` in `settings.py`:
+
+```python
+MIDDLEWARE = [
+    # Other middlewares...
+    'djresttoolkit.middlewares.ResponseTimeMiddleware',
+]
+```
+
+#### 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
+
+```json
+X-Response-Time: 0.01234 seconds
+```
+
+#### Logs a message
+
+```bash
+INFO: Request processed in 0.01234 seconds
+```
+
+### 4. Throttle Utilities
+
+#### `ThrottleInfoJSONRenderer`
+
+```python
+from djresttoolkit.renderers import ThrottleInfoJSONRenderer
+```
+
+A custom DRF JSON renderer that **automatically attaches throttle information to response headers**.
+
+#### Usage (settings.py)
+
+```python
+REST_FRAMEWORK = {
+    "DEFAULT_RENDERER_CLASSES": [
+        "djresttoolkit.renderers.ThrottleInfoJSONRenderer",
+        "rest_framework.renderers.BrowsableAPIRenderer",
+    ],
+}
+```
+
+When enabled, every response includes throttle headers like:
+
+```plaintext
+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`
+
+```python
+from djresttoolkit.throttling import ThrottleInspector
+```
+
+Utility class to **inspect DRF throttle usage** for a view or request.
+
+#### Constructor for ThrottleInspector
+
+```python
+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](LICENSE).
+
+## 👤 Author
+
+For questions or assistance, contact **Shailesh** at [shaileshpandit141@gmail.com](mailto:shaileshpandit141@gmail.com).

djresttoolkit-0.6.0/demo/staticfiles/admin/img/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Code Charm Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

{djresttoolkit-0.4.0 → djresttoolkit-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [project]
 name = "djresttoolkit"
-version = "0.4.0"
+version = "0.6.0"
 description = "A collection of Django and DRF utilities to simplify API development."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }
@@ -46,6 +46,7 @@ keywords = [
 ]
 requires-python = ">=3.13"
 dependencies = [
+    "faker>=37.5.3",
     "pydantic>=2.11.7",
 ]
 
@@ -79,6 +80,12 @@ dev = [
     "djangorestframework-stubs>=3.16.2",
     "pytest>=8.4.1",
     "djresttoolkit",
+    "pyyaml>=6.0.2",
+    "pydantic-settings>=2.10.1",
+    "daphne>=4.2.1",
+    "django-redis>=6.0.0",
+    "django-cors-headers>=4.7.0",
+    "argon2-cffi-bindings>=21.2.0",
 ]
 
 # =====================

djresttoolkit-0.6.0/src/djresttoolkit/dbseed/models/__init__.py

@@ -0,0 +1,4 @@
+from ._base_seed_model import BaseSeedModel
+from ._gen import Field, Gen
+
+__all__ = ["BaseSeedModel", "Gen", "Field"]

djresttoolkit-0.6.0/src/djresttoolkit/dbseed/models/_base_seed_model.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Any
+
+from django.db.models import ForeignKey, ManyToManyField, Model, OneToOneField
+from pydantic import BaseModel
+
+
+class BaseSeedModel(BaseModel):
+    """
+    Base class for all fake data models.
+    Each subclass must define a `model` attribute.
+    """
+
+    class Meta:
+        model: type[Model]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if not hasattr(cls, "Meta") or not hasattr(cls.Meta, "model"):
+            raise TypeError(
+                f"{cls.__name__} must define a Meta class with a Django model"
+            )
+
+    @classmethod
+    def get_meta(cls) -> type[Meta]:
+        """Class-level access."""
+        return cls.Meta
+
+    @classmethod
+    def create_instance(cls) -> tuple[dict[str, Any], list[ManyToManyField[Any, Any]]]:
+        """Handle ForeignKey, OneToOneField and ManyToMany relationship."""
+
+        # dump pydantic model to python dict
+        data = cls().model_dump()
+
+        # Handle ForeignKey and OneToOneField
+        for field in cls.get_meta().model._meta.get_fields():
+            if isinstance(field, (ForeignKey, OneToOneField)):
+                rel_model = field.remote_field.model
+                if rel_model.objects.exists():
+                    # For OneToOne, must ensure unique (pick unused relation)
+                    if isinstance(field, OneToOneField):
+                        used_ids = cls.get_meta().model.objects.values_list(
+                            field.name, flat=True
+                        )
+                        available = rel_model.objects.exclude(pk__in=used_ids)
+                        if available.exists():
+                            data[field.name] = available.order_by("?").first()
+                    else:  # Normal ForeignKey
+                        data[field.name] = rel_model.objects.order_by("?").first()
+
+        # Collect ManyToMany fields
+        m2m_fields: list[ManyToManyField[Any, Any]] = [
+            field
+            for field in cls.get_meta().model._meta.get_fields()
+            if isinstance(field, ManyToManyField)
+        ]
+        return data, m2m_fields

djresttoolkit-0.6.0/src/djresttoolkit/dbseed/models/_gen.py

@@ -0,0 +1,11 @@
+from faker import Faker
+from pydantic import Field as PydField
+
+
+class Generator:
+    @classmethod
+    def create_faker(cls) -> Faker:
+        return Faker()
+
+Gen = Generator.create_faker()
+Field = PydField

{djresttoolkit-0.4.0 → djresttoolkit-0.6.0}/src/djresttoolkit/mail/_email_sender.py

@@ -5,7 +5,6 @@ from typing import cast
 from django.core.exceptions import ValidationError
 from django.core.mail import EmailMultiAlternatives
 from django.template.loader import render_to_string
-from pydantic import EmailStr
 
 from ._models import EmailContent
 from ._types import EmailContentDict
@@ -30,7 +29,7 @@ class EmailSender:
 
     Methods
     -------
-    send(to: list[EmailStr], exceptions: bool = False) -> bool
+    send(to: list[str], exceptions: bool = False) -> bool
         Sends the email to the given recipients.
         - `exceptions=True` riase exceptions on failure and returns False if `exceptions=False`.
 
@@ -64,7 +63,7 @@ class EmailSender:
 
     def send(
         self,
-        to: list[EmailStr],
+        to: list[str],
         exceptions: bool = False,
     ) -> bool:
         """Send email to recipients."""

{djresttoolkit-0.4.0 → djresttoolkit-0.6.0}/src/djresttoolkit/mail/_models.py

@@ -1,6 +1,6 @@
 from typing import Any
 
-from pydantic import BaseModel, EmailStr, field_validator
+from pydantic import BaseModel, field_validator
 
 
 class EmailTemplate(BaseModel):
@@ -48,6 +48,6 @@ class EmailContent(BaseModel):
     """
 
     subject: str
-    from_email: EmailStr | None
+    from_email: str | None
     context: dict[str, Any] | None = None
     template: EmailTemplate

{djresttoolkit-0.4.0 → djresttoolkit-0.6.0}/src/djresttoolkit/mail/_types.py

@@ -1,7 +1,5 @@
 from typing import Any, TypedDict
 
-from pydantic import EmailStr
-
 
 class EmailTemplateDict(TypedDict):
     """Template for rendering email content."""
@@ -23,6 +21,6 @@ class EmailContentDict(TypedDict):
     """
 
     subject: str
-    from_email: EmailStr | None
+    from_email: str | None
     context: dict[str, Any] | None
     template: EmailTemplateDict

djresttoolkit-0.6.0/src/djresttoolkit/management/commands/dbseed.py

@@ -0,0 +1,115 @@
+import pkgutil
+from importlib import import_module
+from types import ModuleType
+from typing import Any
+
+from django.apps import apps
+from django.core.management.base import BaseCommand, CommandParser
+from django.db import transaction
+from django.db.models import Model, QuerySet
+
+from djresttoolkit.dbseed.models import BaseSeedModel
+
+
+class Command(BaseCommand):
+    help = "Seed the database with fake data for any Django model"
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        """Add command arguments."""
+        parser.add_argument(
+            "--count",
+            type=int,
+            default=5,
+            help="Number of records per model",
+        )
+        parser.add_argument(
+            "--model",
+            type=str,
+            default=None,
+            help="Specific model name to seed (e.g., User, Product)",
+        )
+        parser.add_argument(
+            "--seed",
+            type=int,
+            default=None,
+            help="Optional Faker seed for reproducible data",
+        )
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        """Handle ForeignKey, OneToOneField and ManyToMany relationship."""
+
+        count = options["count"]
+        model_name = options["model"]
+        seed = options["seed"]
+
+        if seed is not None:
+            from faker import Faker
+
+            faker = Faker()
+            faker.seed_instance(seed)
+
+        seed_model_classes: list[type[BaseSeedModel]] = []
+
+        # Discover all dbseed dirs in installed apps
+        for app_config in apps.get_app_configs():
+            try:
+                module: ModuleType = import_module(f"{app_config.name}.dbseed")
+            except ModuleNotFoundError:
+                continue  # app has no dbseed dir
+
+            # Iterate over modules in the dbseed package
+            for _, name, ispkg in pkgutil.iter_modules(module.__path__):
+                if ispkg:
+                    continue
+
+                submodule = import_module(f"{app_config.name}.dbseed.{name}")
+                for attr_name in dir(submodule):
+                    attr = getattr(submodule, attr_name)
+                    if (
+                        isinstance(attr, type)
+                        and issubclass(attr, BaseSeedModel)
+                        and attr is not BaseSeedModel
+                    ):
+                        # Filter by model name if provided
+                        if (
+                            not model_name
+                            or model_name.lower()
+                            == attr.__name__.replace("DBSeedModel", "").lower()
+                        ):
+                            seed_model_classes.append(attr)
+
+        if not seed_model_classes:
+            self.stdout.write(self.style.WARNING("No matching dbseed models found."))
+            return None
+
+        # Generate fake data for each discovered dbseed model
+        for dbseed_cls in seed_model_classes:
+            django_model = dbseed_cls.get_meta().model
+            created_count: int = 0
+
+            for _ in range(count):
+                try:
+                    with transaction.atomic():
+                        data, m2m_fields = dbseed_cls.create_instance()
+                        obj = django_model.objects.create(**data)
+                        created_count += 1
+
+                        # Assign ManyToMany fields
+                        for m2m_field in m2m_fields:
+                            rel_model = m2m_field.remote_field.model
+                            related_instances: QuerySet[Model] | list[Any] = (
+                                rel_model.objects.order_by("?")[:2]
+                                if rel_model.objects.exists()
+                                else []
+                            )
+                            getattr(obj, m2m_field.name).set(related_instances)
+                except Exception as error:
+                    self.stderr.write(
+                        f"Error creating {django_model.__name__} instance: {error}"
+                    )
+                    continue
+            self.stdout.write(
+                self.style.SUCCESS(
+                    f"{created_count} records inserted for {django_model.__name__}"
+                )
+            )

djresttoolkit-0.6.0/src/djresttoolkit/renderers/__init__.py

@@ -0,0 +1,3 @@
+from ._throttle_info_json_renderer import ThrottleInfoJSONRenderer
+
+__all__ = ["ThrottleInfoJSONRenderer"]

djresttoolkit-0.6.0/src/djresttoolkit/renderers/_throttle_info_json_renderer.py

@@ -0,0 +1,33 @@
+from typing import Any, Mapping
+
+from rest_framework.renderers import JSONRenderer
+from rest_framework.response import Response
+
+from ..throttling import ThrottleInspector
+
+
+class ThrottleInfoJSONRenderer(JSONRenderer):
+    def render(
+        self,
+        data: Any,
+        accepted_media_type: str | None = None,
+        renderer_context: Mapping[str, Any] | None = None,
+    ) -> Any:
+        """Handle throttle info to headers."""
+        if renderer_context:
+            response: Response | None = renderer_context.get("response")
+            view = renderer_context.get("view")
+            if response and view:
+                # Attach throttle info to headers
+                inspector = ThrottleInspector(view)
+                throttle_info = inspector.get_details()
+                inspector.attach_headers(
+                    response=response,
+                    throttle_info=throttle_info,
+                )
+        # Retuen Final rendered payload
+        return super().render(
+            data,
+            accepted_media_type,
+            renderer_context,
+        )

djresttoolkit-0.6.0/src/djresttoolkit/throttling/__init__.py

@@ -0,0 +1,3 @@
+from ._throttle_inspector import ThrottleInspector
+
+__all__ = ["ThrottleInspector"]

djresttoolkit-0.6.0/src/djresttoolkit/throttling/_throttle_inspector.py

@@ -0,0 +1,179 @@
+import logging
+import re
+from datetime import timedelta
+from datetime import timezone as dt_timezone
+from typing import TYPE_CHECKING, Any
+
+from django.conf import settings
+from django.utils import timezone
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.throttling import BaseThrottle, UserRateThrottle
+
+if TYPE_CHECKING:
+    from rest_framework.views import APIView
+
+    ViewType = APIView
+else:
+    ViewType = object
+
+# Get logger from logging.
+logger = logging.getLogger(__name__)
+
+
+class ThrottleInspector:
+    """
+    Inspects and retrieves DRF throttle details for both class-based
+    and function-based views.
+    """
+
+    def __init__(
+        self,
+        view: ViewType,
+        request: Request | None = None,
+        throttle_classes: list[type[BaseThrottle]] | None = None,
+    ) -> None:
+        self.view = view
+        self.request: Request | None = getattr(view, "request", request)
+        self.throttle_classes: list[type[BaseThrottle]] = (
+            getattr(view, "throttle_classes", throttle_classes) or []
+        )
+
+        if not self.request:
+            logger.warning(f"Request object missing in {self._view_name()}.")
+        if not self.throttle_classes:
+            logger.info(f"No throttles configured for {self._view_name()}.")
+
+    def _view_name(self) -> str:
+        if callable(self.view):
+            return getattr(self.view, "__name__", str(self.view))
+        return type(self.view).__name__
+
+    @staticmethod
+    def to_snake_case(name: str) -> str:
+        """Convert UpperCamelCase to snake_case and remove 'RateThrottle'."""
+        return re.sub(r"(?<!^)(?=[A-Z])", "_", name.replace("RateThrottle", "")).lower()
+
+    @staticmethod
+    def parse_rate(rate: str) -> tuple[int, int] | None:
+        """Parse rate string like '100/day' into (limit, duration_in_seconds)."""
+        if not rate:
+            return None
+        match = re.match(r"(\d+)/(second|minute|hour|day)", rate)
+        if not match:
+            return None
+        num_requests, period = match.groups()
+        duration_map = {"second": 1, "minute": 60, "hour": 3600, "day": 86400}
+        return int(num_requests), duration_map[period]
+
+    def get_throttle_rate(
+        self, throttle_class: type[BaseThrottle]
+    ) -> tuple[int, int] | None:
+        """Return the (limit, duration_in_seconds) for a throttle class."""
+        scope = getattr(throttle_class, "scope", None)
+        if not scope:
+            logger.warning(f"No scope defined in {throttle_class.__name__}. Skipping.")
+            return None
+
+        rate = settings.REST_FRAMEWORK.get("DEFAULT_THROTTLE_RATES", {}).get(scope)
+        if not rate:
+            logger.warning(f"No rate limit found for scope '{scope}'. Skipping.")
+            return None
+
+        return self.parse_rate(rate)
+
+    def get_throttle_usage(
+        self,
+        throttle: UserRateThrottle,
+        limit: int,
+        duration: int,
+    ) -> dict[str, Any]:
+        """Return current usage info for a given throttle instance."""
+        if not self.request:
+            return {
+                "limit": limit,
+                "remaining": limit,
+                "reset_time": None,
+                "retry_after": {"time": None, "unit": "seconds"},
+            }
+
+        cache_key = throttle.get_cache_key(
+            self.request,
+            getattr(self.view, "view", self.view),  # type: ignore
+        )  # type: ignore
+        history: list[Any] = throttle.cache.get(cache_key, []) if cache_key else []
+
+        remaining = max(0, limit - len(history))
+        first_request_time = (  # type: ignore
+            timezone.datetime.fromtimestamp(history[0], tz=dt_timezone.utc)  # type: ignore[attr-defined]
+            if history
+            else timezone.now()
+        )
+        reset_time = first_request_time + timedelta(seconds=duration)  # type: ignore
+        retry_after = max(0, int((reset_time - timezone.now()).total_seconds()))  # type: ignore
+
+        return {
+            "limit": limit,
+            "remaining": remaining,
+            "reset_time": reset_time.isoformat(),  # type: ignore
+            "retry_after": {"time": retry_after, "unit": "seconds"},
+        }
+
+    def get_details(self) -> dict[str, Any]:
+        """
+        Return detailed throttle info for all configured throttles.
+        If throttling is not configured, returns an empty dict.
+        """
+        if not self.throttle_classes:
+            return {}
+
+        details: dict[str, Any] = {"throttled_by": None, "throttles": {}}
+
+        for throttle_class in self.throttle_classes:
+            throttle = throttle_class()
+            parsed_rate = self.get_throttle_rate(throttle_class)
+            if not parsed_rate:
+                continue
+
+            limit, duration = parsed_rate
+            scope = getattr(
+                throttle_class, "scope", self.to_snake_case(throttle_class.__name__)
+            )
+            usage = self.get_throttle_usage(throttle, limit, duration)  # type: ignore[arg-type]
+            details["throttles"][scope] = usage
+
+            if usage["remaining"] == 0 and not details["throttled_by"]:
+                details["throttled_by"] = scope
+                logger.info(f"Request throttled by {scope}")
+
+        return details
+
+    def attach_headers(
+        self,
+        response: Response,
+        throttle_info: dict[str, Any] | None,
+    ) -> None:
+        """
+        Attaches throttle details to response headers in DRF-style.
+
+        Header format:
+            X-Throttle-{throttle_type}-Limit
+            X-Throttle-{throttle_type}-Remaining
+            X-Throttle-{throttle_type}-Reset
+            X-Throttle-{throttle_type}-Retry-After (in seconds)
+        """
+        if not throttle_info:
+            return
+
+        for throttle_type, data in throttle_info.get("throttles", {}).items():
+            response[f"X-Throttle-{throttle_type}-Limit"] = str(data.get("limit", ""))
+            response[f"X-Throttle-{throttle_type}-Remaining"] = str(
+                data.get("remaining", "")
+            )
+            response[f"X-Throttle-{throttle_type}-Reset"] = data.get("reset_time") or ""
+            retry_after = data.get("retry_after", {}).get("time")
+            response[f"X-Throttle-{throttle_type}-Retry-After"] = (
+                str(retry_after) if retry_after is not None else "0"
+            )
+
+        logger.info(f"Throttle headers attached to response for {self._view_name()}.")

{djresttoolkit-0.4.0 → djresttoolkit-0.6.0}/src/djresttoolkit/views/_exceptions/_exception_handler.py

@@ -1,7 +1,9 @@
 from typing import Any, cast
 
+from django.conf import settings
 from django.core.cache import cache
 from django.utils import timezone
+from django.utils.module_loading import import_string
 from rest_framework import status, views
 from rest_framework.request import Request
 from rest_framework.response import Response
@@ -26,6 +28,15 @@ def exception_handler(exc: Exception, context: dict[str, Any]) -> Response | Non
             view, "throttle_classes", [AnonRateThrottle]
         )
 
+        # Set default throttles if user doesn't provide
+        default = settings.REST_FRAMEWORK.get("DEFAULT_THROTTLE_CLASSES", [])
+        if not throttle_classes:
+            if default:
+                throttle_classes = []
+                for path in default:
+                    throttle_classes.append(import_string(path))
+
+        # Handle all throttles by looping it
         for throttle_class in throttle_classes:
             throttle = throttle_class()
             cache_key = throttle.get_cache_key(request, view)

djresttoolkit-0.4.0/README.md

@@ -1,49 +0,0 @@
-# 🛠️ djresttoolkit (django rest toolkit)
-
-[![PyPI version](https://img.shields.io/pypi/v/djresttoolkit.svg)](https://pypi.org/project/djresttoolkit/)
-[![Python versions](https://img.shields.io/pypi/pyversions/djresttoolkit.svg)](https://pypi.org/project/djresttoolkit/)
-[![License](https://img.shields.io/pypi/l/djresttoolkit.svg)](https://github.com/shaileshpandit141/djresttoolkit/blob/main/LICENSE)
-
-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:**
-  
-    ```bash
-    uv add djresttoolkit
-    ````
-
-- **By using pip:**
-
-    ```bash
-    pip install djresttoolkit
-    ````
-
-## 📚 API Reference
-
-### Under the development
-
-## 🛠️ Planned Features
-
-- Add more utils
-
-## 🤝 Contributing
-
-Contributions are welcome! Please open an issue or PR for any improvements.
-
-## 📜 License
-
-MIT License — See [LICENSE](LICENSE).
-
-## 👤 Author
-
-For questions or assistance, contact **Shailesh** at [shaileshpandit141@gmail.com](mailto:shaileshpandit141@gmail.com).