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

README.md

@@ -547,6 +547,154 @@ products = serializer.save()
 - 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.
+
+Here’s a concise **docs entry** for your `ChoiceFieldsAPIView` suitable for `djresttoolkit` documentation:
+
+---
+
+### 11. ChoiceFieldsAPIView — API Reference
+
+```python
+from djresttoolkit.views import ChoiceFieldsAPIView
+```
+
+#### `ChoiceFieldsAPIView`
+
+A **generic DRF API view** to return all choices for specified model fields.
+
+#### Class Attributes of Choice Fields APIView
+
+- `model_class: type[Model] | None` — The Django model to inspect. **Must be set.**
+- `choice_fields: list[str] | None` — List of fields on the model with choices. **Must be set.**
+
+---
+
+#### Choice Fields APIView Methods
+
+- `get(request: Request) -> Response`
+
+Fetches the choices for the configured model fields.
+
+- **Returns:**
+  - `200 OK` — JSON object containing all choices:
+
+    ```json
+    {
+        "choices": {
+            "status": {"draft": "Draft", "published": "Published"},
+            "category": {"a": "Category A", "b": "Category B"}
+        }
+    }
+    ```
+
+  - `400 Bad Request` — If any error occurs while retrieving choices.
+
+- **Raises:**
+  - `AttributeDoesNotExist` — If `model_class` or `choice_fields` is not set.
+
+---
+
+### Example of Choice Fields APIView
+
+```python
+from django.urls import path
+from djresttoolkit.views import ChoiceFieldsAPIView
+from myapp.models import Product
+
+class ProductChoiceAPI(ChoiceFieldsAPIView):
+    model_class = Product
+    choice_fields = ["status", "category"]
+
+urlpatterns = [
+    path(
+      "api/v1/product-choices/",
+      ProductChoiceAPI.as_view(),
+      name="product-choices"
+    ),
+]
+```
+
+#### Choice Fields APIView Features
+
+- Dynamically returns all choices for selected fields in a model.
+- Useful for frontend forms or API consumers that need selectable options.
+- Integrates seamlessly with `ModelChoiceFieldMixin` from `djresttoolkit`.
+
 ## 🛠️ Planned Features
 
 - Add more utils

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djresttoolkit
-Version: 0.10.0
+Version: 0.12.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
@@ -605,6 +605,154 @@ products = serializer.save()
 - 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.
+
+Here’s a concise **docs entry** for your `ChoiceFieldsAPIView` suitable for `djresttoolkit` documentation:
+
+---
+
+### 11. ChoiceFieldsAPIView — API Reference
+
+```python
+from djresttoolkit.views import ChoiceFieldsAPIView
+```
+
+#### `ChoiceFieldsAPIView`
+
+A **generic DRF API view** to return all choices for specified model fields.
+
+#### Class Attributes of Choice Fields APIView
+
+- `model_class: type[Model] | None` — The Django model to inspect. **Must be set.**
+- `choice_fields: list[str] | None` — List of fields on the model with choices. **Must be set.**
+
+---
+
+#### Choice Fields APIView Methods
+
+- `get(request: Request) -> Response`
+
+Fetches the choices for the configured model fields.
+
+- **Returns:**
+  - `200 OK` — JSON object containing all choices:
+
+    ```json
+    {
+        "choices": {
+            "status": {"draft": "Draft", "published": "Published"},
+            "category": {"a": "Category A", "b": "Category B"}
+        }
+    }
+    ```
+
+  - `400 Bad Request` — If any error occurs while retrieving choices.
+
+- **Raises:**
+  - `AttributeDoesNotExist` — If `model_class` or `choice_fields` is not set.
+
+---
+
+### Example of Choice Fields APIView
+
+```python
+from django.urls import path
+from djresttoolkit.views import ChoiceFieldsAPIView
+from myapp.models import Product
+
+class ProductChoiceAPI(ChoiceFieldsAPIView):
+    model_class = Product
+    choice_fields = ["status", "category"]
+
+urlpatterns = [
+    path(
+      "api/v1/product-choices/",
+      ProductChoiceAPI.as_view(),
+      name="product-choices"
+    ),
+]
+```
+
+#### Choice Fields APIView Features
+
+- Dynamically returns all choices for selected fields in a model.
+- Useful for frontend forms or API consumers that need selectable options.
+- Integrates seamlessly with `ModelChoiceFieldMixin` from `djresttoolkit`.
+
 ## 🛠️ Planned Features
 
 - Add more utils

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

@@ -1,5 +1,5 @@
 LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
-README.md,sha256=OzvflId2K79hvwsZr4VIf393Fvm1PhTExUHAAnBvpzo,14651
+README.md,sha256=swcg_Yd0tKwp4PDXQn7gfj7HKpwLs-UPV4jvqOHvHvQ,18485
 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
@@ -24,6 +24,8 @@ src/djresttoolkit/middlewares/__init__.py,sha256=GZHU3Yy4xXoEi62tHn0UJNxN6XgGM2_
 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/models/mixins/__init__.py,sha256=MHwv36f3nHwI0bXeejuO7MTYuV93ln2tSyCCipS2xVw,223
+src/djresttoolkit/models/mixins/_model_choice_fields_mixin.py,sha256=9FZbe3PwrtIUZYGQh1gcOix5bfeyvKEOaNmkemvZX8E,2843
 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
@@ -32,11 +34,13 @@ src/djresttoolkit/serializers/mixins/_absolute_url_file_mixin.py,sha256=5ewael0_
 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/__init__.py,sha256=QuJ9C0Vfzkfrwyqzunxh-A-aErmS6yOoy0uzjDu3oG8,177
+src/djresttoolkit/views/_api_views/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/views/_api_views/_choice_fields_apiview.py,sha256=zABPgqxMVaWd814B_sC64bWL61fDJkyYQZmJXQCa6Xc,1395
 src/djresttoolkit/views/_exceptions/__init__.py,sha256=DrCUxuPNyBR4WhzNutn5HDxLa--q51ykIxSG7_bFsOI,83
 src/djresttoolkit/views/_exceptions/_exception_handler.py,sha256=_o7If47bzWLl57LeSXSWsIDsJGo2RIpwYAwNQ-hsHVY,2839
-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,,
+djresttoolkit-0.12.0.dist-info/METADATA,sha256=QP01vFRs3pOUXn7AuZ4kCVC37ZVo06HgiFm48wdaWVE,21495
+djresttoolkit-0.12.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+djresttoolkit-0.12.0.dist-info/entry_points.txt,sha256=YMhfTF-7mYppO8QqqWnvR_hyMWvoYxD6XI94_ViFu3k,60
+djresttoolkit-0.12.0.dist-info/licenses/LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
+djresttoolkit-0.12.0.dist-info/RECORD,,

src/djresttoolkit/models/mixins/__init__.py

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

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

src/djresttoolkit/views/__init__.py

@@ -1,3 +1,7 @@
 from ._exceptions import exception_handler
+from ._api_views._choice_fields_apiview import ChoiceFieldsAPIView
 
-__all__ = ["exception_handler"]
+__all__ = [
+    "exception_handler",
+    "ChoiceFieldsAPIView",
+]

src/djresttoolkit/views/_api_views/_choice_fields_apiview.py

@@ -0,0 +1,42 @@
+# views.py
+from rest_framework.views import APIView
+from rest_framework.response import Response
+from rest_framework.request import Request
+from rest_framework import status
+from djresttoolkit.models.mixins import ModelChoiceFieldMixin, AttributeDoesNotExist
+from django.db.models import Model
+
+
+class ChoiceFieldsAPIView(APIView):
+    """
+    Generic API view to return choice fields from a model.
+    """
+
+    model_class: type[Model] | None = None
+    choice_fields: list[str] | None = None
+
+    def get(self, request: Request) -> Response:
+        """
+        Return a JSON response with all choices for the specified fields.
+        """
+        if not self.model_class or not self.choice_fields:
+            raise AttributeDoesNotExist(
+                "model_class and choice_fields must be set.",
+            )
+
+        # Dynamically create a mixin instance
+        class DynamicChoiceMixin(ModelChoiceFieldMixin):
+            model = self.model_class
+            choice_fields = self.choice_fields
+
+        try:
+            choices = DynamicChoiceMixin.get_choices()
+            return Response(
+                {"choices": choices},
+                status=status.HTTP_200_OK,
+            )
+        except Exception:
+            return Response(
+                {"detail": "An error occurred while retrieving choices."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )