djresttoolkit 0.16.1__py3-none-any.whl → 0.17.1__py3-none-any.whl

djresttoolkit/views/mixins/__init__.py

@@ -0,0 +1,16 @@
+from ._retrieve_object_mixin import RetrieveObjectMixin, QuerysetNotDefinedError
+from ._cache_action_mixin import CacheActionMixin
+from ._cache_invalidate_mixin import CacheInvalidateMixin
+from ._cache_key_mixin import CacheKeyMixin
+from ._cache_list_retrieve_mixin import CacheListRetrieveMixin
+from ._cache_ops_mixin import CacheOpsMixin
+
+__all__ = [
+    "RetrieveObjectMixin",
+    "QuerysetNotDefinedError",
+    "CacheActionMixin",
+    "CacheInvalidateMixin",
+    "CacheKeyMixin",
+    "CacheListRetrieveMixin",
+    "CacheOpsMixin",
+]

djresttoolkit/views/mixins/_cache_action_mixin.py

@@ -0,0 +1,44 @@
+from functools import wraps
+from typing import Any, Callable
+
+from rest_framework.response import Response
+from ._cache_ops_mixin import CacheOpsMixin
+from rest_framework.request import Request
+
+
+class CacheActionMixin(CacheOpsMixin):
+    """Provides decorator for caching custom @action methods."""
+
+    def cache_action(
+        self,
+        detail: bool = False,
+        action_name: str | None = None,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        def decorator(view_method: Callable[..., Any]) -> Callable[..., Any]:
+            @wraps(view_method)
+            def wrapper(
+                viewset: Any,
+                request: Request,
+                *args: Any,
+                **kwargs: Any,
+            ) -> Response:
+                name = action_name or view_method.__name__
+                pk = kwargs.get("pk") if detail else None
+                action_type = "custom-detail" if detail else "custom-list"
+                key = viewset.get_cache_key(action_type, pk=pk, action_name=name)
+
+                def get_data() -> None | Any:
+                    response = view_method(
+                        viewset,
+                        request,
+                        *args,
+                        **kwargs,
+                    )
+                    return response.data if isinstance(response, Response) else response
+
+                data = viewset.get_or_set_cache(key, get_data)
+                return Response(data)
+
+            return wrapper
+
+        return decorator

djresttoolkit/views/mixins/_cache_invalidate_mixin.py

@@ -0,0 +1,38 @@
+from typing import Any
+from rest_framework.request import Request
+from rest_framework.response import Response
+from ._cache_list_retrieve_mixin import CacheListRetrieveMixin
+
+
+class CacheInvalidateMixin(CacheListRetrieveMixin):
+    """Invalidate caches after create, update, destroy."""
+
+    def create(
+        self,
+        request: Request,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Response:
+        response = super().create(request, *args, **kwargs)  # type: ignore
+        self.invalidate_cache()
+        return response  # type: ignore
+
+    def update(
+        self,
+        request: Request,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Response:
+        response = super().update(request, *args, **kwargs)  # type: ignore
+        self.invalidate_cache(pk=self.kwargs.get("pk"))  # type: ignore
+        return response  # type: ignore
+
+    def destroy(
+        self,
+        request: Request,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Response:
+        response = super().destroy(request, *args, **kwargs)  # type: ignore
+        self.invalidate_cache(pk=self.kwargs.get("pk"))  # type: ignore
+        return response  # type: ignore

djresttoolkit/views/mixins/_cache_key_mixin.py

@@ -0,0 +1,33 @@
+import hashlib
+import json
+from typing import Any
+
+
+class CacheKeyMixin:
+    """Handles generating unique cache keys for views."""
+
+    cache_timeout: int = 300
+
+    def get_cache_timeout(self) -> int:
+        return self.cache_timeout
+
+    def get_cache_key(
+        self,
+        action_type: str,
+        pk: Any | str = None,
+        action_name: str | None = None,
+    ) -> str | None:
+        if action_type in ("list", "custom-list"):
+            query_params = dict(sorted(self.request.query_params.items()))  # type: ignore
+            query_string = json.dumps(query_params, separators=(",", ":"))
+            query_hash = hashlib.md5(query_string.encode()).hexdigest()
+            if action_type == "list":
+                return f"{self.basename}_list_{query_hash}"  # type: ignore
+            return f"{self.basename}_{action_name}_list_{query_hash}"  # type: ignore
+
+        if action_type in ("retrieve", "custom-detail") and pk is not None:
+            if action_type == "retrieve":
+                return f"{self.basename}_detail_{pk}"  # type: ignore
+            return f"{self.basename}_{action_name}_detail_{pk}"  # type: ignore
+
+        return None

djresttoolkit/views/mixins/_cache_list_retrieve_mixin.py

@@ -0,0 +1,57 @@
+from typing import Any
+
+from rest_framework.response import Response
+from rest_framework.request import Request
+from ._cache_action_mixin import CacheActionMixin
+
+
+class CacheListRetrieveMixin(CacheActionMixin):
+    """Caches list() and retrieve() responses."""
+
+    def list(
+        self,
+        request: Request,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Response:
+        cache_key = self.get_cache_key("list")
+        if not cache_key:
+            return super().list(request, *args, **kwargs)  # type: ignore
+
+        data = self.get_or_set_cache(
+            cache_key,
+            lambda: self._get_list_data(request),  # type: ignore
+        )
+        return Response(data)
+
+    def _get_list_data(self, request: Response) -> Any:
+        queryset = self.filter_queryset(self.get_queryset())  # type: ignore
+        page = self.paginate_queryset(queryset)  # type: ignore
+        if page is not None:
+            serializer = self.get_serializer(page, many=True)  # type: ignore
+            return self.get_paginated_response(serializer.data).data  # type: ignore
+        else:
+            serializer = self.get_serializer(queryset, many=True)  # type: ignore
+            return serializer.data  # type: ignore
+
+    def retrieve(
+        self,
+        request: Request,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Response:
+        pk = self.kwargs.get("pk")  # type: ignore
+        cache_key = self.get_cache_key("retrieve", pk=pk)  # type: ignore
+        if not cache_key:
+            return super().retrieve(request, *args, **kwargs)  # type: ignore
+
+        data = self.get_or_set_cache(
+            cache_key,
+            lambda: self._get_detail_data(),
+        )
+        return Response(data)
+
+    def _get_detail_data(self) -> Any:
+        instance = self.get_object()  # type: ignore
+        serializer = self.get_serializer(instance)  # type: ignore
+        return serializer.data  # type: ignore

djresttoolkit/views/mixins/_cache_ops_mixin.py

@@ -0,0 +1,47 @@
+from typing import Any, Callable
+
+from django.core.cache import cache
+
+from ._cache_key_mixin import CacheKeyMixin
+
+
+class CacheOpsMixin(CacheKeyMixin):
+    """Handles getting, setting, and invalidating cache."""
+
+    def get_or_set_cache(
+        self,
+        cache_key: str,
+        data_fn: Callable[[], Any],
+        timeout: int | None = None,
+    ) -> Any:
+        data = cache.get(cache_key)
+        if data is None:
+            data = data_fn()
+            cache.set(cache_key, data, timeout or self.get_cache_timeout())
+        return data
+
+    def invalidate_cache(
+        self,
+        pk: Any | None = None,
+        custom_actions: list[str] | None = None,
+    ) -> None:
+        if pk:
+            key = self.get_cache_key("retrieve", pk=pk)
+            if key:
+                cache.delete(key)
+
+            if custom_actions:
+                for action in custom_actions:
+                    key = self.get_cache_key(
+                        "custom-detail",
+                        pk=pk,
+                        action_name=action,
+                    )
+                    if key:
+                        cache.delete(key)
+
+        if hasattr(cache, "delete_pattern"):
+            cache.delete_pattern(f"{self.basename}_list_*")  # type: ignore
+            if custom_actions:
+                for action in custom_actions:
+                    cache.delete_pattern(f"{self.basename}_{action}_list_*")  # type: ignore

{djresttoolkit-0.16.1.dist-info → djresttoolkit-0.17.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djresttoolkit
-Version: 0.16.1
+Version: 0.17.1
 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
@@ -112,6 +112,9 @@ djresttoolkit is a collection of utilities and helpers for Django and Django RES
 - **PaginatedDataBuilder**
   Builder that combines `PageNumberPagination` + serializers to return standardized paginated responses with `"page"` + `"results"`.
 
+- **Caching Mixins**
+  This module provides a set of DRF mixins to handle caching for `list`, `retrieve`, and `custom actions` with automatic invalidation on create, update, and destroy.
+
 ## 📦 Installation
 
 - **By using uv:**
@@ -312,7 +315,7 @@ print(settings.database_url)
 #### Features
 
 - Prioritizes `.env` variables over YAML.
-- Supports nested keys: `DATABASE__HOST` → `settings.database.host`.
+- Supports nested keys: `DATABASE__HOST`:- `settings.database.host`.
 - Designed to be subclassed for project-specific settings.
 
 ### 4. EmailSender — API Reference
@@ -928,17 +931,17 @@ from djresttoolkit.pagination import PageNumberPagination
 - Clients can control items per page using `?page-size=`.
 - Structured pagination metadata:
 
-  - `current` → current page number
-  - `total` → total number of pages
-  - `size` → number of items per page
-  - `total_items` → total number of items across all pages
-  - `next` → next page URL
-  - `previous` → previous page URL
+  - `current`:- current page number
+  - `total`:- total number of pages
+  - `size`:- number of items per page
+  - `total_items`:- total number of items across all pages
+  - `next`:- next page URL
+  - `previous`:- previous page URL
 - Standardized API response format.
 
 ### Attributes of Page Number Pagination
 
-- `page_size_query_param: str` → Query parameter name (`"page-size"`).
+- `page_size_query_param: str`:- Query parameter name (`"page-size"`).
 
 ### Page Number Pagination Methods
 
@@ -983,8 +986,8 @@ from djresttoolkit.pagination import PaginatedDataBuilder
 - Integrates with **DRF serializers**.
 - Handles **invalid pages** gracefully by raising `NotFound`.
 - Returns both:
-  - `"page"` → pagination metadata
-  - `"results"` → serialized data.
+  - `"page"`:- pagination metadata
+  - `"results"`:- serialized data.
 - Provides **structured pagination response format**.
 
 ---
@@ -999,9 +1002,9 @@ builder = PaginatedDataBuilder(
 )
 ```
 
-- `request: Request` → DRF request object.
-- `serializer_class: type[BaseSerializer]` → DRF serializer class for the model.
-- `queryset: QuerySet` → Django queryset to paginate.
+- `request: Request`:- DRF request object.
+- `serializer_class: type[BaseSerializer]`:- DRF serializer class for the model.
+- `queryset: QuerySet`:- Django queryset to paginate.
 
 ### Paginated Data Builder Methods
 
@@ -1031,6 +1034,80 @@ builder = PaginatedDataBuilder(
 }
 ```
 
+### 16. Caching Mixins — API Reference
+
+This module provides a set of DRF mixins to handle **caching for list, retrieve, and custom actions** with automatic invalidation on create, update, and destroy.
+
+#### 1️ `CacheKeyMixin`
+
+- **Purpose**: Generate unique cache keys for DRF viewset actions.
+- **Attributes**:
+  - `cache_timeout: int = 300`:- default cache duration in seconds.
+- **Methods**:
+  - `get_cache_timeout()`:- returns the cache timeout.
+  - `get_cache_key(action_type, pk=None, action_name=None)`:- returns a cache key string based on action type:**
+    - `list` or `custom-list`:- hash of query parameters.
+    - `retrieve` or `custom-detail`:- uses primary key (`pk`).
+
+#### 2️ `CacheOpsMixin`
+
+- **Purpose**: Get, set, and invalidate cache.
+- **Methods**:
+  - `get_or_set_cache(cache_key, data_fn, timeout=None)`:- fetch from cache or compute and set.
+  - `invalidate_cache(pk=None, custom_actions=None)`:- delete cached items:
+    - Deletes retrieve/detail caches for a `pk`.
+    - Deletes list caches (supports `delete_pattern` if available).
+
+#### 3️ `CacheActionMixin`
+
+- **Purpose**: Decorator for caching custom DRF `@action` methods.
+- **Methods**:
+  - `cache_action(detail=False, action_name=None)`:- returns a decorator that caches action results automatically.
+  - Works for:
+    - `detail=False`:- custom-list action cache.
+    - `detail=True`:- custom-detail action cache.
+
+#### 4️ `CacheListRetrieveMixin`
+
+- **Purpose**: Caches DRF `list()` and `retrieve()` responses.
+- **Methods**:
+  - `list(request, *args, **kwargs)`:- caches list responses.
+  - `retrieve(request, *args, **kwargs)`:- caches detail responses.
+  - `_get_list_data(request)`:- internal method to fetch paginated list data.
+  - `_get_detail_data()`:- internal method to fetch a single object.
+
+#### 5️ `CacheInvalidateMixin`
+
+- **Purpose**: Automatically invalidates caches on write operations.
+- **Methods**:
+  - `create(request, *args, **kwargs)`:- invalidates list caches.
+  - `update(request, *args, **kwargs)`:- invalidates detail caches for `pk`.
+  - `destroy(request, *args, **kwargs)`:- invalidates detail caches for `pk`.
+
+#### Example of Caching Mixins
+
+```python
+from rest_framework.viewsets import ModelViewSet
+from myapp.models import Book
+from myapp.serializers import BookSerializer
+from djresttoolkit.cache_mixins import CacheInvalidateMixin, CacheActionMixin
+
+class BookViewSet(CacheInvalidateMixin, ModelViewSet):
+    queryset = Book.objects.all()
+    serializer_class = BookSerializer
+    basename = "book"
+
+    @CacheActionMixin.cache_action(detail=False)
+    def popular(self, request):
+        data = Book.objects.filter(is_popular=True)
+        serializer = self.get_serializer(data, many=True)
+        return Response(serializer.data)
+```
+
+- Automatically caches `list`, `retrieve`, and `popular` actions.
+- Invalidates caches when books are created, updated, or deleted.
+- Supports custom cache keys per action.
+
 ## 🛠️ Planned Features
 
 - Add more utils

djresttoolkit-0.17.1.dist-info/RECORD

@@ -0,0 +1,55 @@
+djresttoolkit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djresttoolkit/admin.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djresttoolkit/apps.py,sha256=nKb5GUIEhAB3IL3lTmEXNc5XuvvaZupH-1CCuYKFrEQ,158
+djresttoolkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djresttoolkit/dbseed/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djresttoolkit/dbseed/models/__init__.py,sha256=uuynQIcfVqEaZN9hF_caI24zm8az23JdXLDrv7xOKTQ,180
+djresttoolkit/dbseed/models/_choice_field.py,sha256=T7LAzbyXqlYp2mtCAKL8E1Da_MEh9RzgLZrFJ7fa4gM,446
+djresttoolkit/dbseed/models/_gen.py,sha256=qBPQaLvh1rcEam0YmE4JBJqpa-Vv5IFlIIagkEMHDVw,206
+djresttoolkit/dbseed/models/_seed_model.py,sha256=0cmbi0VNKjmJbwhjeCFsvb3iKYjok6TJOk6Y2MF_3N4,2443
+djresttoolkit/envconfig/__init__.py,sha256=PcLaPaVfQmz3-4m6SwoOQF2W4U7F0agBGJ4Qjqbcyfw,74
+djresttoolkit/envconfig/_env_settings.py,sha256=X-pgHqNtUNQLBHiGpbYB4ViCuY14n6aff5HZqYL4Tlc,3236
+djresttoolkit/mail/__init__.py,sha256=tB9SdMlhfWQ640q4aobZ0H1c7fTWalpDL2I-onkr2VI,268
+djresttoolkit/mail/_email_sender.py,sha256=bPMqgD5HibJcOZgO6xxHOhdK9HEhnGNC6BoMPpo-h7k,3096
+djresttoolkit/mail/_models.py,sha256=of5KsLGvsN2OWgDYgdtLEijulg817TXgsLKuUdsnDQc,1447
+djresttoolkit/mail/_types.py,sha256=zf6CcXR1ei_UmZ1nLAJa378OAJ6ftnBICqEOkzXPNw8,646
+djresttoolkit/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djresttoolkit/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djresttoolkit/management/commands/dbflush.py,sha256=v7rXcuNQDiXLV7p0xzKMNXVeWAN7QKmq2qQQAbhHEEw,3423
+djresttoolkit/management/commands/dbseed.py,sha256=sY87TvvzECG7aQXxsDjr45VzCzJpofLacBK49EYFK8M,4225
+djresttoolkit/middlewares/__init__.py,sha256=GZHU3Yy4xXoEi62tHn0UJNxN6XgGM2_HES8Bt5AS5Lk,100
+djresttoolkit/middlewares/_response_time_middleware.py,sha256=1wCwdkW5Ng6HJo8zx0F7ylms84OGP-1K0kbyG6Vacuk,908
+djresttoolkit/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djresttoolkit/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djresttoolkit/models/mixins/__init__.py,sha256=MHwv36f3nHwI0bXeejuO7MTYuV93ln2tSyCCipS2xVw,223
+djresttoolkit/models/mixins/_model_choice_fields_mixin.py,sha256=9FZbe3PwrtIUZYGQh1gcOix5bfeyvKEOaNmkemvZX8E,2843
+djresttoolkit/pagination/__init__.py,sha256=lQhyyX381RbWBsYV9Os3OQIbY7Z6aouL0QE5kI_u5SU,176
+djresttoolkit/pagination/_page_number_pagination.py,sha256=NHPdMZfmTurKLdgpMBT2usTiGAoZMyA3dYXq_n11y34,2358
+djresttoolkit/pagination/_paginated_data_builder.py,sha256=N4JaJwmfmC2NiC8MqOpkxV8-itKTueaOdawnv_it4bU,2239
+djresttoolkit/renderers/__init__.py,sha256=kmFMPRiMfD8CuJTN1_-6Z_Hqil3x8GBM0IN1roZESm0,107
+djresttoolkit/renderers/_throttle_info_json_renderer.py,sha256=aP2cN4cB_Imcpy732zsPBQrMQqcKEs5R3dld5Y_4AMU,1089
+djresttoolkit/serializers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djresttoolkit/serializers/mixins/__init__.py,sha256=dRT0kXDckOkZo1RQHrT1gXbGFMIv5M8TBHGF2uF-81Q,225
+djresttoolkit/serializers/mixins/_absolute_url_file_mixin.py,sha256=5ewael0_RsJZ9b36IfXacxjb-Vx1eQ9Dk6dWuj5D_dc,3261
+djresttoolkit/serializers/mixins/_bulk_create_mixin.py,sha256=9ZWm2MNaZOhmhKlWOu6VECtlDbUtaPeceGHmivDYwYQ,3248
+djresttoolkit/throttling/__init__.py,sha256=01sjMymjx8XjqnAw3bEBLc-JtfhCDrp5dGxSNXMvPpU,84
+djresttoolkit/throttling/_throttle_inspector.py,sha256=Kss6ZxKy-EXq9UGaGprGDhpSuJ5992bmEYZSWmUVBHo,6480
+djresttoolkit/urls/__init__.py,sha256=u-Hj8GARO0mWZwiehCi3VslMXqtkdAFff7VcXVuiN8w,86
+djresttoolkit/urls/_build_absolute_uri.py,sha256=X9kdoTRGIJ2ordpkHgSXmqwmmMT-OZBgluV5ULUhJEk,915
+djresttoolkit/views/__init__.py,sha256=QuJ9C0Vfzkfrwyqzunxh-A-aErmS6yOoy0uzjDu3oG8,177
+djresttoolkit/views/_api_views/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djresttoolkit/views/_api_views/_choice_fields_apiview.py,sha256=zABPgqxMVaWd814B_sC64bWL61fDJkyYQZmJXQCa6Xc,1395
+djresttoolkit/views/_exceptions/__init__.py,sha256=DrCUxuPNyBR4WhzNutn5HDxLa--q51ykIxSG7_bFsOI,83
+djresttoolkit/views/_exceptions/_exception_handler.py,sha256=_o7If47bzWLl57LeSXSWsIDsJGo2RIpwYAwNQ-hsHVY,2839
+djresttoolkit/views/mixins/__init__.py,sha256=Ge-Dwa6S5-4BpfzMjLfxEkkepk8F3IJn0DNWBETq1Hw,537
+djresttoolkit/views/mixins/_cache_action_mixin.py,sha256=Vle_xbHc6dzI2SqxLiM5HsrDkOzSgqj8GFB85MyPdaw,1516
+djresttoolkit/views/mixins/_cache_invalidate_mixin.py,sha256=Ax6VC1lg8qYGW5IK339hqq40SRKj61J3Jp-mB_2gPWc,1170
+djresttoolkit/views/mixins/_cache_key_mixin.py,sha256=0kt1rgz34q43DCLFwlR4rkyHtoWDYCMLXaTe7XfRZu4,1170
+djresttoolkit/views/mixins/_cache_list_retrieve_mixin.py,sha256=nxJpfkNZWuOpf7wDDkGwq_ZQNT_17-iRisdTB2Cc0iY,1935
+djresttoolkit/views/mixins/_cache_ops_mixin.py,sha256=veaBwH3Bp3GAzFizIxXT8EhmUF1AY3kCZBcF7rHPfyc,1435
+djresttoolkit/views/mixins/_retrieve_object_mixin.py,sha256=Q9znYPb07YXXUhsL7VIrk3BC-zDwjOhwLJKe2GPJ-k0,1155
+djresttoolkit-0.17.1.dist-info/METADATA,sha256=hnb1so12F-UOfjK4704Qlk6gQrArmZJDxzfoBby7B3s,32930
+djresttoolkit-0.17.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+djresttoolkit-0.17.1.dist-info/entry_points.txt,sha256=YMhfTF-7mYppO8QqqWnvR_hyMWvoYxD6XI94_ViFu3k,60
+djresttoolkit-0.17.1.dist-info/licenses/LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
+djresttoolkit-0.17.1.dist-info/RECORD,,