djresttoolkit 0.8.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

README.md

@@ -30,7 +30,7 @@ djresttoolkit is a collection of utilities and helpers for Django and Django RES
 
 ## 📚 All API Reference
 
-### 1. DB Seed Utilities
+### 1. DB Seed Utilities — API Reference
 
 #### `Generator`
 
@@ -89,7 +89,7 @@ Here’s a **concise API reference** for your database flush management command
 
 ---
 
-### 2. DB Flush Command
+### 2. DB Flush Command — API Reference
 
 ```python
 from djresttoolkit.management.commands import flush
@@ -145,7 +145,7 @@ or
 Flushed 120 records from all models and reset IDs.
 ```
 
-### 3. EnvBaseSettings
+### 3. EnvBaseSettings — API Reference
 
 ```python
 from djresttoolkit.envconfig import EnvBaseSettings
@@ -162,11 +162,18 @@ Supports **nested configuration** using double underscores (`__`) in environment
 
 #### Class Attributes
 
-| Attribute      | Type                 | Default         | Description                                                        |
-| -------------- | -------------------- | --------------- | ------------------------------------------------------------------ |
-| `env_file`     | `str`                | `.env`          | Environment variable file path.                                    |
-| `yaml_file`    | `str`                | `.environ.yaml` | YAML configuration file path.                                      |
-| `model_config` | `SettingsConfigDict` | —               | Pydantic settings configuration (file encoding, nested delimiter). |
+- Attributes
+  - `env_file`
+    - Type: `str`
+    - Default: `.env`
+    - Description: Environment variable file path.
+  - `yaml_file`
+    - Type: `str`
+    - Default: `.environ.yaml`
+    - Description: YAML configuration file path.
+  - `model_config`
+    - Type: `SettingsConfigDict`
+    - Description: Pydantic settings configuration (file encoding, nested delimiter).
 
 #### Methods
 
@@ -193,7 +200,7 @@ Loads configuration from **YAML first**, then overrides with **environment varia
 ```python
 from djresttoolkit.envconfig import EnvBaseSettings
 
-class EnvSettings(EnvBaseSettings):
+class EnvSettings(EnvBaseSettings["EnvSettings"]):
     debug: bool = False
     database_url: str
 
@@ -210,7 +217,7 @@ print(settings.database_url)
 - Supports nested keys: `DATABASE__HOST` → `settings.database.host`.
 - Designed to be subclassed for project-specific settings.
 
-### 4. EmailSender
+### 4. EmailSender — API Reference
 
 ```python
 from djresttoolkit.mail import EmailSender, EmailContent, EmailTemplate
@@ -259,7 +266,7 @@ EmailSender(content).send(to=["user@example.com"])
 
 - `text`, `html` — template file paths
 
-### 5. Custom DRF Exception Handler
+### 5. Custom DRF Exception Handler — API Reference
 
 ```python
 from djresttoolkit.views import exception_handler
@@ -299,7 +306,7 @@ REST_FRAMEWORK = {
 - Tracks requests in cache and calculates `retry_after`.
 - Cleans expired timestamps automatically.
 
-### 6. Response Time Middleware
+### 6. Response Time Middleware — API Reference
 
 ```python
 from djresttoolkit.middlewares import ResponseTimeMiddleware
@@ -346,7 +353,7 @@ X-Response-Time: 0.01234 seconds
 INFO: Request processed in 0.01234 seconds
 ```
 
-### 7. Throttle Utilities
+### 7. Throttle Utilities — API Reference
 
 #### `ThrottleInfoJSONRenderer`
 
@@ -402,6 +409,144 @@ ThrottleInspector(
 - `attach_headers(response: Response, throttle_info: dict | None)`
   Attaches throttle data to HTTP headers.
 
+### 8. AbsoluteUrlFileMixin — API Reference
+
+```python
+from djresttoolkit.serializers.mixins import AbsoluteUrlFileMixin
+```
+
+### `AbsoluteUrlFileMixin`
+
+A **serializer mixin** that converts **FileField** and **ImageField** URLs to **absolute URLs**, ensuring compatibility with cloud storage backends.
+
+---
+
+### Attributes
+
+- `file_fields`
+- type: `list[str] | None`
+- default: `None`
+- description: Manual list of file field names for non-model serializers.
+
+### Absolute Url File Mixin Methods
+
+#### `to_representation(self, instance: Any) -> dict[str, Any]`
+
+- Overrides default serializer `to_representation`.
+- Enhances all file-related fields in the serialized output to **absolute URLs**.
+
+#### `enhance_file_fields(self, instance: Any, representation: dict[str, Any], request: Any) -> dict[str, Any]`
+
+- Core logic to process each file field.
+- Converts relative URLs to absolute URLs using `request.build_absolute_uri()`.
+- Supports model serializers or manual `file_fields`.
+- Logs warnings if request context is missing or file is not found.
+
+#### Exceptions
+
+- `MissingRequestContext`: Raised if the request object is missing in serializer context and `DEBUG=True`.
+
+### Absolute Url File Mixin Example
+
+```python
+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
+```
+
+#### Notes
+
+- Works with both Django model serializers and custom serializers.
+- Relative file paths are automatically converted to absolute URLs.
+- Can manually specify fields via `file_fields` for non-model serializers.
+
+### 9. BulkCreateMixin — API Reference
+
+```python
+from djresttoolkit.serializers.mixins import BulkCreateMixin
+```
+
+#### `BulkCreateMixin`
+
+A **DRF serializer mixin** that adds support for:
+
+- **Single instance creation** with extra context fields
+- **Bulk creation** from a list of validated data dictionaries
+- **Updating serializer field error messages** with model-specific messages
+
+#### Bulk Create Mixin Notes
+
+- `bulk_create()` does **not trigger model signals** or call `.save()` on instances.
+- `Meta.model` **must** be defined in the serializer.
+
+#### Bulk Create Mixin Methods
+
+#### `create(self, validated_data: dict[str, Any] | list[dict[str, Any]]) -> Model | list[Model]`
+
+- Creates single or multiple model instances.
+- **Parameters:**
+  - `validated_data`: dict for single instance or list of dicts for bulk creation.
+  
+- **Returns:**
+  - Single model instance or list of instances.
+  
+- **Raises:**
+  - `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:**
+  - Dictionary of serializer fields.
+
+- **Warning:**
+  - Logs a warning if a serializer field is not present on the model.
+
+### Bulk Create Mixin Example
+
+```python
+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()
+```
+
+#### Bulk Create Mixin Features
+
+- Works seamlessly with DRF `ModelSerializer`.
+- Automatically updates field error messages based on Django model definitions.
+- Bulk creation is optimized using `model.objects.bulk_create()` for efficiency.
+
 ## 🛠️ Planned Features
 
 - Add more utils

{djresttoolkit-0.8.0.dist-info → djresttoolkit-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djresttoolkit
-Version: 0.8.0
+Version: 0.10.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
@@ -88,7 +88,7 @@ djresttoolkit is a collection of utilities and helpers for Django and Django RES
 
 ## 📚 All API Reference
 
-### 1. DB Seed Utilities
+### 1. DB Seed Utilities — API Reference
 
 #### `Generator`
 
@@ -147,7 +147,7 @@ Here’s a **concise API reference** for your database flush management command
 
 ---
 
-### 2. DB Flush Command
+### 2. DB Flush Command — API Reference
 
 ```python
 from djresttoolkit.management.commands import flush
@@ -203,7 +203,7 @@ or
 Flushed 120 records from all models and reset IDs.
 ```
 
-### 3. EnvBaseSettings
+### 3. EnvBaseSettings — API Reference
 
 ```python
 from djresttoolkit.envconfig import EnvBaseSettings
@@ -220,11 +220,18 @@ Supports **nested configuration** using double underscores (`__`) in environment
 
 #### Class Attributes
 
-| Attribute      | Type                 | Default         | Description                                                        |
-| -------------- | -------------------- | --------------- | ------------------------------------------------------------------ |
-| `env_file`     | `str`                | `.env`          | Environment variable file path.                                    |
-| `yaml_file`    | `str`                | `.environ.yaml` | YAML configuration file path.                                      |
-| `model_config` | `SettingsConfigDict` | —               | Pydantic settings configuration (file encoding, nested delimiter). |
+- Attributes
+  - `env_file`
+    - Type: `str`
+    - Default: `.env`
+    - Description: Environment variable file path.
+  - `yaml_file`
+    - Type: `str`
+    - Default: `.environ.yaml`
+    - Description: YAML configuration file path.
+  - `model_config`
+    - Type: `SettingsConfigDict`
+    - Description: Pydantic settings configuration (file encoding, nested delimiter).
 
 #### Methods
 
@@ -251,7 +258,7 @@ Loads configuration from **YAML first**, then overrides with **environment varia
 ```python
 from djresttoolkit.envconfig import EnvBaseSettings
 
-class EnvSettings(EnvBaseSettings):
+class EnvSettings(EnvBaseSettings["EnvSettings"]):
     debug: bool = False
     database_url: str
 
@@ -268,7 +275,7 @@ print(settings.database_url)
 - Supports nested keys: `DATABASE__HOST` → `settings.database.host`.
 - Designed to be subclassed for project-specific settings.
 
-### 4. EmailSender
+### 4. EmailSender — API Reference
 
 ```python
 from djresttoolkit.mail import EmailSender, EmailContent, EmailTemplate
@@ -317,7 +324,7 @@ EmailSender(content).send(to=["user@example.com"])
 
 - `text`, `html` — template file paths
 
-### 5. Custom DRF Exception Handler
+### 5. Custom DRF Exception Handler — API Reference
 
 ```python
 from djresttoolkit.views import exception_handler
@@ -357,7 +364,7 @@ REST_FRAMEWORK = {
 - Tracks requests in cache and calculates `retry_after`.
 - Cleans expired timestamps automatically.
 
-### 6. Response Time Middleware
+### 6. Response Time Middleware — API Reference
 
 ```python
 from djresttoolkit.middlewares import ResponseTimeMiddleware
@@ -404,7 +411,7 @@ X-Response-Time: 0.01234 seconds
 INFO: Request processed in 0.01234 seconds
 ```
 
-### 7. Throttle Utilities
+### 7. Throttle Utilities — API Reference
 
 #### `ThrottleInfoJSONRenderer`
 
@@ -460,6 +467,144 @@ ThrottleInspector(
 - `attach_headers(response: Response, throttle_info: dict | None)`
   Attaches throttle data to HTTP headers.
 
+### 8. AbsoluteUrlFileMixin — API Reference
+
+```python
+from djresttoolkit.serializers.mixins import AbsoluteUrlFileMixin
+```
+
+### `AbsoluteUrlFileMixin`
+
+A **serializer mixin** that converts **FileField** and **ImageField** URLs to **absolute URLs**, ensuring compatibility with cloud storage backends.
+
+---
+
+### Attributes
+
+- `file_fields`
+- type: `list[str] | None`
+- default: `None`
+- description: Manual list of file field names for non-model serializers.
+
+### Absolute Url File Mixin Methods
+
+#### `to_representation(self, instance: Any) -> dict[str, Any]`
+
+- Overrides default serializer `to_representation`.
+- Enhances all file-related fields in the serialized output to **absolute URLs**.
+
+#### `enhance_file_fields(self, instance: Any, representation: dict[str, Any], request: Any) -> dict[str, Any]`
+
+- Core logic to process each file field.
+- Converts relative URLs to absolute URLs using `request.build_absolute_uri()`.
+- Supports model serializers or manual `file_fields`.
+- Logs warnings if request context is missing or file is not found.
+
+#### Exceptions
+
+- `MissingRequestContext`: Raised if the request object is missing in serializer context and `DEBUG=True`.
+
+### Absolute Url File Mixin Example
+
+```python
+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
+```
+
+#### Notes
+
+- Works with both Django model serializers and custom serializers.
+- Relative file paths are automatically converted to absolute URLs.
+- Can manually specify fields via `file_fields` for non-model serializers.
+
+### 9. BulkCreateMixin — API Reference
+
+```python
+from djresttoolkit.serializers.mixins import BulkCreateMixin
+```
+
+#### `BulkCreateMixin`
+
+A **DRF serializer mixin** that adds support for:
+
+- **Single instance creation** with extra context fields
+- **Bulk creation** from a list of validated data dictionaries
+- **Updating serializer field error messages** with model-specific messages
+
+#### Bulk Create Mixin Notes
+
+- `bulk_create()` does **not trigger model signals** or call `.save()` on instances.
+- `Meta.model` **must** be defined in the serializer.
+
+#### Bulk Create Mixin Methods
+
+#### `create(self, validated_data: dict[str, Any] | list[dict[str, Any]]) -> Model | list[Model]`
+
+- Creates single or multiple model instances.
+- **Parameters:**
+  - `validated_data`: dict for single instance or list of dicts for bulk creation.
+  
+- **Returns:**
+  - Single model instance or list of instances.
+  
+- **Raises:**
+  - `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:**
+  - Dictionary of serializer fields.
+
+- **Warning:**
+  - Logs a warning if a serializer field is not present on the model.
+
+### Bulk Create Mixin Example
+
+```python
+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()
+```
+
+#### Bulk Create Mixin Features
+
+- Works seamlessly with DRF `ModelSerializer`.
+- Automatically updates field error messages based on Django model definitions.
+- Bulk creation is optimized using `model.objects.bulk_create()` for efficiency.
+
 ## 🛠️ Planned Features
 
 - Add more utils

{djresttoolkit-0.8.0.dist-info → djresttoolkit-0.10.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
-README.md,sha256=9S8AiRr4U5uA-YrgtQbUZiYpbg4rT_UejlDGhJ2WYzM,10558
+README.md,sha256=OzvflId2K79hvwsZr4VIf393Fvm1PhTExUHAAnBvpzo,14651
 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
@@ -11,7 +11,7 @@ src/djresttoolkit/dbseed/models/_choice_field.py,sha256=T7LAzbyXqlYp2mtCAKL8E1Da
 src/djresttoolkit/dbseed/models/_gen.py,sha256=qBPQaLvh1rcEam0YmE4JBJqpa-Vv5IFlIIagkEMHDVw,206
 src/djresttoolkit/dbseed/models/_seed_model.py,sha256=0cmbi0VNKjmJbwhjeCFsvb3iKYjok6TJOk6Y2MF_3N4,2443
 src/djresttoolkit/envconfig/__init__.py,sha256=PcLaPaVfQmz3-4m6SwoOQF2W4U7F0agBGJ4Qjqbcyfw,74
-src/djresttoolkit/envconfig/_env_settings.py,sha256=cKGDLo7WU0wzQGkWSwgrUxGCb0sT111JUt4HGlDVSxo,3221
+src/djresttoolkit/envconfig/_env_settings.py,sha256=X-pgHqNtUNQLBHiGpbYB4ViCuY14n6aff5HZqYL4Tlc,3236
 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
@@ -26,13 +26,17 @@ src/djresttoolkit/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NM
 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/serializers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/serializers/mixins/__init__.py,sha256=dRT0kXDckOkZo1RQHrT1gXbGFMIv5M8TBHGF2uF-81Q,225
+src/djresttoolkit/serializers/mixins/_absolute_url_file_mixin.py,sha256=5ewael0_RsJZ9b36IfXacxjb-Vx1eQ9Dk6dWuj5D_dc,3261
+src/djresttoolkit/serializers/mixins/_bulk_create_mixin.py,sha256=9ZWm2MNaZOhmhKlWOu6VECtlDbUtaPeceGHmivDYwYQ,3248
 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.8.0.dist-info/METADATA,sha256=qCwxDQnmpbQygUL7gytkkO826sOs9Zm8Xy_NXmlLvQY,13567
-djresttoolkit-0.8.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-djresttoolkit-0.8.0.dist-info/entry_points.txt,sha256=YMhfTF-7mYppO8QqqWnvR_hyMWvoYxD6XI94_ViFu3k,60
-djresttoolkit-0.8.0.dist-info/licenses/LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
-djresttoolkit-0.8.0.dist-info/RECORD,,
+djresttoolkit-0.10.0.dist-info/METADATA,sha256=A91Vw-rZ7cni31PQzgw568wk5tGRLROJkBe9mLXYa14,17661
+djresttoolkit-0.10.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+djresttoolkit-0.10.0.dist-info/entry_points.txt,sha256=YMhfTF-7mYppO8QqqWnvR_hyMWvoYxD6XI94_ViFu3k,60
+djresttoolkit-0.10.0.dist-info/licenses/LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
+djresttoolkit-0.10.0.dist-info/RECORD,,

src/djresttoolkit/envconfig/_env_settings.py

@@ -6,7 +6,7 @@ import yaml
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
-class EnvBaseSettings(BaseSettings):
+class EnvBaseSettings[T: "EnvBaseSettings"](BaseSettings):
     """ "
     EnvBaseSettings is a base settings class for managing application configuration
     using both YAML files and environment variables.
@@ -60,12 +60,12 @@ class EnvBaseSettings(BaseSettings):
 
     @classmethod
     def load(
-        cls,
+        cls: type[T],
         *,
         env_file: str | None = None,
         ymal_file: str | None = None,
         warning: bool = True,
-    ) -> "EnvBaseSettings":
+    ) -> T:
         """Load from YAML first, then override with .env."""
         if env_file:
             cls.env_file = env_file

src/djresttoolkit/serializers/mixins/__init__.py

@@ -0,0 +1,8 @@
+from ._absolute_url_file_mixin import AbsoluteUrlFileMixin, MissingRequestContext
+from ._bulk_create_mixin import BulkCreateMixin
+
+__all__ = [
+    "AbsoluteUrlFileMixin",
+    "MissingRequestContext",
+    "BulkCreateMixin",
+]

src/djresttoolkit/serializers/mixins/_absolute_url_file_mixin.py

@@ -0,0 +1,94 @@
+import logging
+from typing import Any, cast
+from urllib.parse import urlparse
+
+from django.conf import settings
+from django.db import models
+
+logger = logging.getLogger(__name__)
+
+
+class MissingRequestContext(Exception):
+    """Custom exception for missing request in serializer context."""
+
+    ...
+
+
+class AbsoluteUrlFileMixin:
+    """
+    A mixin that updates FileField and ImageField URLs in serializer output
+    to be absolute URLs, compatible with cloud storage backends.
+    """
+
+    # manually specify file fields for non-model serializers
+    file_fields: list[str] | None = None
+
+    def to_representation(self, instance: Any) -> dict[str, Any]:
+        """Extend serializer representation to enhance file field URLs."""
+        representation = cast(dict[str, Any], super().to_representation(instance))  # type: ignore[misc]
+        request = self.context.get("request")  # type: ignore
+        return self.enhance_file_fields(instance, representation, request)
+
+    def enhance_file_fields(
+        self,
+        instance: Any,
+        representation: dict[str, Any],
+        request: Any,
+    ) -> dict[str, Any]:
+        if request is None:
+            logger.warning("Request not found in serializer context.")
+            if settings.DEBUG:
+                raise MissingRequestContext("Request not found in serializer context.")
+            return representation
+
+        # Collect only file-related model fields if available
+        model_fields = (
+            {
+                field.name: field
+                for field in instance._meta.get_fields()
+                if isinstance(field, (models.FileField, models.ImageField))
+            }
+            if hasattr(instance, "_meta")
+            else {}
+        )
+
+        manual_fields = getattr(self, "file_fields", []) or []
+
+        for field_name, field_value in representation.items():
+            model_field = model_fields.get(field_name)
+
+            is_file_field = model_field or (field_name in manual_fields)
+            if not is_file_field:
+                continue
+
+            try:
+                # Get file URL from instance or raw serializer value
+                if model_field:
+                    file_instance = getattr(instance, field_name, None)
+                    file_url = (
+                        getattr(file_instance, "url", None) if file_instance else None
+                    )
+                else:
+                    file_url = field_value
+
+                if not file_url:
+                    logger.info("No file found for field: %s", field_name)
+                    representation[field_name] = None
+                    continue
+
+                # Only build absolute URL if it's relative
+                parsed_url = urlparse(str(file_url))
+                if not parsed_url.netloc:  # relative path
+                    file_url = request.build_absolute_uri(file_url)
+
+                representation[field_name] = file_url
+                logger.debug("Enhanced URL for %s: %s", field_name, file_url)
+
+            except Exception as error:
+                logger.error(
+                    "Unexpected error processing file field %s: %s",
+                    field_name,
+                    error,
+                )
+
+        return representation

src/djresttoolkit/serializers/mixins/_bulk_create_mixin.py

@@ -0,0 +1,87 @@
+import logging
+from typing import Any, cast
+
+from django.core.exceptions import FieldDoesNotExist
+from django.db.models import Model
+from rest_framework.serializers import Field as SerializerField
+from django.db.models import Field as ModelField
+
+
+logger = logging.getLogger(__name__)
+
+
+class BulkCreateMixin:
+    """
+    A mixin for DRF serializers that supports:
+      - Single instance creation with extra context fields
+      - Bulk creation from a list of validated_data dicts
+      - Updating field error messages with model-specific messages
+
+    Notes:
+      - bulk_create() does not trigger model signals or .save()
+      - Meta.model must be defined
+    """
+
+    def create(
+        self, validated_data: dict[str, Any] | list[dict[str, Any]]
+    ) -> Model | list[Model]:
+        logger.debug("Starting creation", extra={"validated_data": validated_data})
+
+        model: type[Model] | None = getattr(getattr(self, "Meta", None), "model", None)
+        if model is None:
+            logger.error("Meta.model not defined.")
+            raise AttributeError(f"{self.__class__.__name__} missing Meta.model.")
+
+        # Bulk creation
+        if isinstance(validated_data, list):
+            instances = [model(**item) for item in validated_data]
+            if instances:
+                logger.info(
+                    "Bulk creating instances",
+                    extra={"count": len(instances), "model": model.__name__},
+                )
+                return model.objects.bulk_create(instances)
+            logger.info("No instances to create.")
+            return []
+
+        # Single instance creation
+        if not hasattr(super(), "create"):
+            raise NotImplementedError(
+                f"{self.__class__.__name__} must be used with a DRF serializer "
+                "that implements create()."
+            )
+
+        logger.info("Creating a single instance", extra={"model": model.__name__})
+        return super().create({**validated_data})  # type: ignore[misc]
+
+    def get_fields(self) -> dict[str, SerializerField[Any, Any, Any, Any]]:
+        # DRF serializer fields
+        fields = cast(
+            dict[str, SerializerField[Any, Any, Any, Any]],
+            super().get_fields(),  # type: ignore
+        )
+
+        meta = getattr(self, "Meta", None)
+        model: type[Model] | None = getattr(meta, "model", None)
+
+        if model is None:
+            raise ValueError(f"{self.__class__.__name__}.Meta.model must be defined.")
+
+        logger.debug("Setting up serializer fields", extra={"model": model.__name__})
+
+        for field_name, serializer_field in fields.items():
+            try:
+                # Django model field
+                model_field = cast(
+                    ModelField[Any, Any],
+                    model._meta.get_field(field_name),  # type: ignore
+                )
+                if hasattr(model_field, "error_messages"):
+                    serializer_field.error_messages.update(model_field.error_messages)
+            except FieldDoesNotExist:
+                logger.warning(
+                    "Skipping serializer field not present on model",
+                    extra={"field_name": field_name, "model": model.__name__},
+                )
+
+        return fields