djresttoolkit 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

README.md

@@ -30,7 +30,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
 

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.dist-info → djresttoolkit-0.6.0.dist-info}/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,34 @@
+LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
+README.md,sha256=mgYuT5MNL2ZmWzXLyU3VN0FA0sgyRM85Xn5EKxOM0Bs,5562
+demo/staticfiles/admin/img/LICENSE,sha256=0RT6_zSIwWwxmzI13EH5AjnT1j2YU3MwM9j3U19cAAQ,1081
+src/djresttoolkit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/admin.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/apps.py,sha256=nKb5GUIEhAB3IL3lTmEXNc5XuvvaZupH-1CCuYKFrEQ,158
+src/djresttoolkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/dbseed/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/dbseed/models/__init__.py,sha256=SpAEE8mfd_cX8qgI-CeC4r1e17YLAwAlxeFgbK8gtE4,118
+src/djresttoolkit/dbseed/models/_base_seed_model.py,sha256=DlbmdafLicKd_ja1AIvKKzyBxdnxdq23zPJwlqxiTl8,2187
+src/djresttoolkit/dbseed/models/_gen.py,sha256=qBPQaLvh1rcEam0YmE4JBJqpa-Vv5IFlIIagkEMHDVw,206
+src/djresttoolkit/mail/__init__.py,sha256=tB9SdMlhfWQ640q4aobZ0H1c7fTWalpDL2I-onkr2VI,268
+src/djresttoolkit/mail/_email_sender.py,sha256=bPMqgD5HibJcOZgO6xxHOhdK9HEhnGNC6BoMPpo-h7k,3096
+src/djresttoolkit/mail/_models.py,sha256=of5KsLGvsN2OWgDYgdtLEijulg817TXgsLKuUdsnDQc,1447
+src/djresttoolkit/mail/_types.py,sha256=zf6CcXR1ei_UmZ1nLAJa378OAJ6ftnBICqEOkzXPNw8,646
+src/djresttoolkit/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/management/commands/dbseed.py,sha256=tMpvvDx_es08GxYKgJ1umJddh_kmIB1Fy0J5Ich2hiE,4248
+src/djresttoolkit/middlewares/__init__.py,sha256=GZHU3Yy4xXoEi62tHn0UJNxN6XgGM2_HES8Bt5AS5Lk,100
+src/djresttoolkit/middlewares/_response_time_middleware.py,sha256=1wCwdkW5Ng6HJo8zx0F7ylms84OGP-1K0kbyG6Vacuk,908
+src/djresttoolkit/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/renderers/__init__.py,sha256=kmFMPRiMfD8CuJTN1_-6Z_Hqil3x8GBM0IN1roZESm0,107
+src/djresttoolkit/renderers/_throttle_info_json_renderer.py,sha256=aP2cN4cB_Imcpy732zsPBQrMQqcKEs5R3dld5Y_4AMU,1089
+src/djresttoolkit/throttling/__init__.py,sha256=01sjMymjx8XjqnAw3bEBLc-JtfhCDrp5dGxSNXMvPpU,84
+src/djresttoolkit/throttling/_throttle_inspector.py,sha256=Kss6ZxKy-EXq9UGaGprGDhpSuJ5992bmEYZSWmUVBHo,6480
+src/djresttoolkit/views/__init__.py,sha256=XrxBrs6sH4HmUzp41omcmy_y94pSaXAVn01ttQ022-4,76
+src/djresttoolkit/views/_exceptions/__init__.py,sha256=DrCUxuPNyBR4WhzNutn5HDxLa--q51ykIxSG7_bFsOI,83
+src/djresttoolkit/views/_exceptions/_exception_handler.py,sha256=_o7If47bzWLl57LeSXSWsIDsJGo2RIpwYAwNQ-hsHVY,2839
+djresttoolkit-0.6.0.dist-info/METADATA,sha256=KKviIBCDtQeoaRNcs8w5zZvlTNVyK1KJXwqNo7hcogM,8501
+djresttoolkit-0.6.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+djresttoolkit-0.6.0.dist-info/entry_points.txt,sha256=YMhfTF-7mYppO8QqqWnvR_hyMWvoYxD6XI94_ViFu3k,60
+djresttoolkit-0.6.0.dist-info/licenses/LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
+djresttoolkit-0.6.0.dist-info/RECORD,,

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"]

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

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

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

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

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

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__}"
+                )
+            )

src/djresttoolkit/renderers/__init__.py

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

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,
+        )

src/djresttoolkit/throttling/__init__.py

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

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()}.")

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.dist-info/RECORD

@@ -1,22 +0,0 @@
-LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
-README.md,sha256=P0hcRXIpkEZZIiyWKsvuCkOIlqPxQ4tRkdb5R_mTARQ,1464
-src/djresttoolkit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-src/djresttoolkit/admin.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-src/djresttoolkit/apps.py,sha256=nKb5GUIEhAB3IL3lTmEXNc5XuvvaZupH-1CCuYKFrEQ,158
-src/djresttoolkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-src/djresttoolkit/mail/__init__.py,sha256=tB9SdMlhfWQ640q4aobZ0H1c7fTWalpDL2I-onkr2VI,268
-src/djresttoolkit/mail/_email_sender.py,sha256=vvTPZzSAfX2FXHv1IY0ST8dEsq8M4wAxkihm0JbRh1Y,3136
-src/djresttoolkit/mail/_models.py,sha256=_41pH3xC0jP8SHSty2FkxvRh2_ddKk-4peT11OHcBBE,1462
-src/djresttoolkit/mail/_types.py,sha256=est1mrN80vB_4-j-2yuAr_l_7rNzO4AJlqpq74zO5ow,682
-src/djresttoolkit/middlewares/__init__.py,sha256=GZHU3Yy4xXoEi62tHn0UJNxN6XgGM2_HES8Bt5AS5Lk,100
-src/djresttoolkit/middlewares/_response_time_middleware.py,sha256=1wCwdkW5Ng6HJo8zx0F7ylms84OGP-1K0kbyG6Vacuk,908
-src/djresttoolkit/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-src/djresttoolkit/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-src/djresttoolkit/views/__init__.py,sha256=XrxBrs6sH4HmUzp41omcmy_y94pSaXAVn01ttQ022-4,76
-src/djresttoolkit/views/_exceptions/__init__.py,sha256=DrCUxuPNyBR4WhzNutn5HDxLa--q51ykIxSG7_bFsOI,83
-src/djresttoolkit/views/_exceptions/_exception_handler.py,sha256=lg6kfAABex-UbAsF78uX-M-ZnJ3u1vK1eIXytb-4KSw,2375
-djresttoolkit-0.4.0.dist-info/METADATA,sha256=FGDP5PR0AZoaPvEyrG95DVC516vGOWlXk2ZgyLfm8kE,4374
-djresttoolkit-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-djresttoolkit-0.4.0.dist-info/entry_points.txt,sha256=YMhfTF-7mYppO8QqqWnvR_hyMWvoYxD6XI94_ViFu3k,60
-djresttoolkit-0.4.0.dist-info/licenses/LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
-djresttoolkit-0.4.0.dist-info/RECORD,,