djresttoolkit 0.12.0__tar.gz → 0.13.0__tar.gz

{djresttoolkit-0.12.0 → djresttoolkit-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djresttoolkit
-Version: 0.12.0
+Version: 0.13.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
@@ -753,6 +753,60 @@ urlpatterns = [
 - Useful for frontend forms or API consumers that need selectable options.
 - Integrates seamlessly with `ModelChoiceFieldMixin` from `djresttoolkit`.
 
+### 12. RetrieveObjectMixin — API Reference
+
+```python
+from djresttoolkit.views.mixins import RetrieveObjectMixin
+```
+
+#### `RetrieveObjectMixin[T: Model]`
+
+A **generic mixin** to retrieve a single Django model instance by filters.
+
+#### Class Attributes of Retrieve Object Mixin
+
+- `queryset: QuerySet[T] | None` — The queryset used to retrieve objects. **Must be set.**
+
+#### Raises of Retrieve Object Mixin
+
+- `QuerysetNotDefinedError` — If `queryset` is not set in the class.
+
+#### Retrieve Object Mixin Methods
+
+- `get_object(**filters: Any) -> T | None`
+
+Retrieve a single model object using the provided filter criteria.
+
+- **Parameters:**
+  - `**filters` — Keyword arguments to filter the queryset (e.g., `id=1`, `slug="abc"`).
+
+- **Returns:**
+  - Model instance matching the filters, or `None` if no match is found.
+
+#### Example of Retrieve Object Mixin
+
+```python
+from rest_framework.views import APIView
+from django.http import JsonResponse
+from myapp.models import Book
+from djresttoolkit.mixins import RetrieveObjectMixin
+
+class BookDetailView(RetrieveObjectMixin[Book], APIView):
+    queryset = Book.objects.all()
+
+    def get(self, request, *args, **kwargs):
+        book = self.get_object(id=kwargs["id"])
+        if book:
+            return JsonResponse({"title": book.title, "author": book.author})
+        return JsonResponse({"detail": "Not found"}, status=404)
+```
+
+#### Features of Retrieve Object Mixin
+
+- Simplifies object retrieval in class-based views or DRF views.
+- Returns `None` instead of raising `DoesNotExist`, making error handling easier.
+- Works with any Django model and queryset.
+
 ## 🛠️ Planned Features
 
 - Add more utils

{djresttoolkit-0.12.0 → djresttoolkit-0.13.0}/README.md

@@ -695,6 +695,60 @@ urlpatterns = [
 - Useful for frontend forms or API consumers that need selectable options.
 - Integrates seamlessly with `ModelChoiceFieldMixin` from `djresttoolkit`.
 
+### 12. RetrieveObjectMixin — API Reference
+
+```python
+from djresttoolkit.views.mixins import RetrieveObjectMixin
+```
+
+#### `RetrieveObjectMixin[T: Model]`
+
+A **generic mixin** to retrieve a single Django model instance by filters.
+
+#### Class Attributes of Retrieve Object Mixin
+
+- `queryset: QuerySet[T] | None` — The queryset used to retrieve objects. **Must be set.**
+
+#### Raises of Retrieve Object Mixin
+
+- `QuerysetNotDefinedError` — If `queryset` is not set in the class.
+
+#### Retrieve Object Mixin Methods
+
+- `get_object(**filters: Any) -> T | None`
+
+Retrieve a single model object using the provided filter criteria.
+
+- **Parameters:**
+  - `**filters` — Keyword arguments to filter the queryset (e.g., `id=1`, `slug="abc"`).
+
+- **Returns:**
+  - Model instance matching the filters, or `None` if no match is found.
+
+#### Example of Retrieve Object Mixin
+
+```python
+from rest_framework.views import APIView
+from django.http import JsonResponse
+from myapp.models import Book
+from djresttoolkit.mixins import RetrieveObjectMixin
+
+class BookDetailView(RetrieveObjectMixin[Book], APIView):
+    queryset = Book.objects.all()
+
+    def get(self, request, *args, **kwargs):
+        book = self.get_object(id=kwargs["id"])
+        if book:
+            return JsonResponse({"title": book.title, "author": book.author})
+        return JsonResponse({"detail": "Not found"}, status=404)
+```
+
+#### Features of Retrieve Object Mixin
+
+- Simplifies object retrieval in class-based views or DRF views.
+- Returns `None` instead of raising `DoesNotExist`, making error handling easier.
+- Works with any Django model and queryset.
+
 ## 🛠️ Planned Features
 
 - Add more utils

{djresttoolkit-0.12.0 → djresttoolkit-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [project]
 name = "djresttoolkit"
-version = "0.12.0"
+version = "0.13.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.13.0/src/djresttoolkit/views/mixins/__init__.py

@@ -0,0 +1,6 @@
+from ._retrieve_object_mixin import RetrieveObjectMixin, QuerysetNotDefinedError
+
+__all__ = [
+    "RetrieveObjectMixin",
+    "QuerysetNotDefinedError",
+]

djresttoolkit-0.13.0/src/djresttoolkit/views/mixins/_retrieve_object_mixin.py

@@ -0,0 +1,41 @@
+from typing import Any
+from django.db.models import Model, QuerySet
+
+
+class QuerysetNotDefinedError(Exception):
+    """Exception raised when the `queryset` attribute is not set in the class."""
+
+    pass
+
+
+class RetrieveObjectMixin[T: Model]:
+    """
+    Mixin to provide a method for retrieving a single model object by filters.
+
+    Requires the `queryset` attribute to be set in the class that inherits this mixin.
+
+    Example:
+    ```
+        class MyView(RetrieveModelMixin[Book], APIView):
+            queryset = Book.objects.all()
+
+            def get(self, request, *args, **kwargs):
+                obj = self.get_object(id=1)
+                return JsonResponse(obj.to_dict())
+    ```
+    """
+
+    queryset: QuerySet[T] | None = None
+
+    def get_object(self, **filters: Any) -> T | None:
+        """Retrieve a model object based on provided filters."""
+
+        if self.queryset is None:
+            raise QuerysetNotDefinedError(
+                "Queryset attribute is not set in the class.",
+            )
+
+        try:
+            return self.queryset.get(**filters)
+        except self.queryset.model.DoesNotExist:
+            return None