djresttoolkit 0.9.0__tar.gz → 0.11.0__tar.gz

{djresttoolkit-0.9.0 → djresttoolkit-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djresttoolkit
-Version: 0.9.0
+Version: 0.11.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
@@ -258,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
 
@@ -275,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
@@ -324,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
@@ -364,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
@@ -411,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`
 
@@ -527,6 +527,160 @@ data = serializer.data
 - 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.
+
+### 10. ModelChoiceFieldMixin — API Reference
+
+```python
+from djresttoolkit.models.mixins import ModelChoiceFieldMixin
+```
+
+### `ModelChoiceFieldMixin`
+
+A **Django model mixin** to retrieve **choice fields** from a model, designed to work seamlessly with Django's `TextChoices`.
+
+#### Class Attributes in Model Choice Field Mixin
+
+- `model: type[Model] | None` — The Django model class to inspect. **Must be set.**
+- `choice_fields: list[str] | None` — List of model field names that contain choices. **Must be set.**
+
+#### Model Choice Field Mixin Methods
+
+`get_choices() -> dict[str, dict[str, str]]`
+
+Retrieve the choice fields from the model as a dictionary.
+
+- **Returns:**
+
+  ```python
+  {
+      "field_name": {
+          "choice_value": "Choice Label",
+          ...
+      },
+      ...
+  }
+  ```
+
+- **Raises:**
+
+  - `AttributeDoesNotExist` — If `model` or `choice_fields` is not set.
+  - `ChoiceFieldNotFound` — If a field does not exist, has no choices, or has invalid choice format.
+
+---
+
+### Model Choice Field Mixin Example
+
+```python
+from django.db import models
+from djresttoolkit.serializers.mixins import ModelChoiceFieldMixin
+
+class Product(models.Model):
+    class Status(models.TextChoices):
+        DRAFT = "draft", "Draft"
+        PUBLISHED = "published", "Published"
+
+    status = models.CharField(max_length=20, choices=Status.choices)
+    category = models.CharField(max_length=50, choices=[
+      ("a", "Category A"),
+      ("b", "Category B"),
+    ])
+
+class ProductChoiceMixin(ModelChoiceFieldMixin):
+    model = Product
+    choice_fields = ["status", "category"]
+
+choices = ProductChoiceMixin.get_choices()
+print(choices)
+# Output:
+# {
+#   "status": {"draft": "Draft", "published": "Published"},
+#   "category": {"a": "Category A", "b": "Category B"}
+# }
+```
+
+#### Features of Model Choice Field Mixin
+
+- Safely validates that fields exist and have valid choices.
+- Returns a ready-to-use dictionary mapping values to labels.
+- Ideal for DRF serializers, forms, and admin customization.
+
 ## 🛠️ Planned Features
 
 - Add more utils

{djresttoolkit-0.9.0 → djresttoolkit-0.11.0}/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
@@ -200,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
 
@@ -217,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
@@ -266,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
@@ -306,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
@@ -353,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`
 
@@ -469,6 +469,160 @@ data = serializer.data
 - 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.
+
+### 10. ModelChoiceFieldMixin — API Reference
+
+```python
+from djresttoolkit.models.mixins import ModelChoiceFieldMixin
+```
+
+### `ModelChoiceFieldMixin`
+
+A **Django model mixin** to retrieve **choice fields** from a model, designed to work seamlessly with Django's `TextChoices`.
+
+#### Class Attributes in Model Choice Field Mixin
+
+- `model: type[Model] | None` — The Django model class to inspect. **Must be set.**
+- `choice_fields: list[str] | None` — List of model field names that contain choices. **Must be set.**
+
+#### Model Choice Field Mixin Methods
+
+`get_choices() -> dict[str, dict[str, str]]`
+
+Retrieve the choice fields from the model as a dictionary.
+
+- **Returns:**
+
+  ```python
+  {
+      "field_name": {
+          "choice_value": "Choice Label",
+          ...
+      },
+      ...
+  }
+  ```
+
+- **Raises:**
+
+  - `AttributeDoesNotExist` — If `model` or `choice_fields` is not set.
+  - `ChoiceFieldNotFound` — If a field does not exist, has no choices, or has invalid choice format.
+
+---
+
+### Model Choice Field Mixin Example
+
+```python
+from django.db import models
+from djresttoolkit.serializers.mixins import ModelChoiceFieldMixin
+
+class Product(models.Model):
+    class Status(models.TextChoices):
+        DRAFT = "draft", "Draft"
+        PUBLISHED = "published", "Published"
+
+    status = models.CharField(max_length=20, choices=Status.choices)
+    category = models.CharField(max_length=50, choices=[
+      ("a", "Category A"),
+      ("b", "Category B"),
+    ])
+
+class ProductChoiceMixin(ModelChoiceFieldMixin):
+    model = Product
+    choice_fields = ["status", "category"]
+
+choices = ProductChoiceMixin.get_choices()
+print(choices)
+# Output:
+# {
+#   "status": {"draft": "Draft", "published": "Published"},
+#   "category": {"a": "Category A", "b": "Category B"}
+# }
+```
+
+#### Features of Model Choice Field Mixin
+
+- Safely validates that fields exist and have valid choices.
+- Returns a ready-to-use dictionary mapping values to labels.
+- Ideal for DRF serializers, forms, and admin customization.
+
 ## 🛠️ Planned Features
 
 - Add more utils

{djresttoolkit-0.9.0 → djresttoolkit-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [project]
 name = "djresttoolkit"
-version = "0.9.0"
+version = "0.11.0"
 description = "A collection of Django and DRF utilities to simplify API development."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }

djresttoolkit-0.11.0/src/djresttoolkit/models/mixins/__init__.py

@@ -0,0 +1,11 @@
+from ._model_choice_fields_mixin import (
+    AttributeDoesNotExist,
+    ChoiceFieldNotFound,
+    ModelChoiceFieldMixin,
+)
+
+__all__ = [
+    "AttributeDoesNotExist",
+    "ChoiceFieldNotFound",
+    "ModelChoiceFieldMixin",
+]

djresttoolkit-0.11.0/src/djresttoolkit/models/mixins/_model_choice_fields_mixin.py

@@ -0,0 +1,84 @@
+from typing import Iterable, Tuple, cast
+
+from django.db.models import Model
+from django.core.exceptions import FieldDoesNotExist
+
+
+class AttributeDoesNotExist(Exception):
+    """
+    Exception raised when a required attribute is missing in the class.
+    """
+
+
+class ChoiceFieldNotFound(Exception):
+    """
+    Exception raised when a specified choice field is missing
+    or has invalid/empty choices in the model.
+    """
+
+
+class ModelChoiceFieldMixin:
+    """
+    Mixin to retrieve choice fields from a Django model.
+    Designed to work seamlessly with Django's TextChoices.
+    """
+
+    model: type[Model] | None = None
+    choice_fields: list[str] | None = None
+
+    @classmethod
+    def get_choices(cls) -> dict[str, dict[str, str]]:
+        """
+        Retrieve the choice fields from the model class.
+
+        Returns:
+            dict[str, dict[str, str]]: A dictionary where keys are field names
+            and values are dictionaries of choices (value => label).
+
+        Raises:
+            ModelAttributeNotFound: If the model attribute is not set.
+            ChoiceFieldAttributeNotFound: If the choice_fields attribute is not set.
+            ChoiceFieldNotFound: If a field does not exist, has no choices,
+                                 or has an invalid choice format.
+        """
+
+        if cls.model is None:
+            raise AttributeDoesNotExist("Model attribute is not set in the class.")
+
+        if cls.choice_fields is None:
+            raise AttributeDoesNotExist(
+                "The choice_fields attribute must be set in the class."
+            )
+
+        choices_as_dict: dict[str, dict[str, str]] = {}
+
+        for field in cls.choice_fields:
+            try:
+                field_obj = cls.model._meta.get_field(field)  # type: ignore[attr-defined]
+            except FieldDoesNotExist as e:
+                raise ChoiceFieldNotFound(
+                    f"The field '{field}' does not exist in model '{cls.model.__name__}'."
+                ) from e
+
+            raw_choices = cast(
+                Iterable[Tuple[str, str]],
+                field_obj.choices or [],  # type: ignore[union-attr]
+            )
+
+            if not raw_choices:
+                raise ChoiceFieldNotFound(
+                    f"The field '{field}' in model '{cls.model.__name__}' has no choices defined."
+                )
+
+            if not all(
+                isinstance(choice, (list, tuple)) and len(choice) == 2  # type: ignore[misc]
+                for choice in raw_choices
+            ):
+                raise ChoiceFieldNotFound(
+                    f"The field '{field}' in model '{cls.model.__name__}' has invalid choice format. "
+                    "Expected an iterable of 2-tuples (value, label)."
+                )
+
+            choices_as_dict[field] = dict(raw_choices)
+
+        return choices_as_dict

{djresttoolkit-0.9.0 → djresttoolkit-0.11.0}/src/djresttoolkit/serializers/mixins/__init__.py

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

djresttoolkit-0.9.0/src/djresttoolkit/serializers/_serializer_create_mixin.py → djresttoolkit-0.11.0/src/djresttoolkit/serializers/mixins/_bulk_create_mixin.py

@@ -10,7 +10,7 @@ from django.db.models import Field as ModelField
 logger = logging.getLogger(__name__)
 
 
-class RecordsCreationMixin:
+class BulkCreateMixin:
     """
     A mixin for DRF serializers that supports:
       - Single instance creation with extra context fields