djresttoolkit 0.16.1__tar.gz → 0.17.1__tar.gz

djresttoolkit-0.17.1/.python-version

@@ -0,0 +1 @@
+3.13

djresttoolkit-0.17.1/.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+    "files.exclude": {
+        "**/.git": true,
+        "**/.svn": true,
+        "**/.hg": true,
+        "**/.DS_Store": true,
+        "**/Thumbs.db": true,
+        "**/__pycache__": true,
+        "**/.pytest_cache": true,
+        "**/.ruff_cache": true
+    }
+}

{djresttoolkit-0.16.1 → djresttoolkit-0.17.1}/PKG-INFO

@@ -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.16.1 → djresttoolkit-0.17.1}/README.md

@@ -54,6 +54,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:**
@@ -254,7 +257,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
@@ -870,17 +873,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
 
@@ -925,8 +928,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**.
 
 ---
@@ -941,9 +944,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
 
@@ -973,6 +976,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/demo/apps/todos/admin.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.contrib import admin
+from django.contrib.admin import ModelAdmin
+
+from .models import Tag, Todo, TodoTag
+
+if TYPE_CHECKING:
+    class TodoAdminBase(ModelAdmin[Todo]): ...
+    class TagAdminBase(ModelAdmin[Todo]): ...
+    class TodoTagAdminBase(ModelAdmin[Todo]): ...
+else:
+    class TodoAdminBase(ModelAdmin): ... 
+    class TagAdminBase(ModelAdmin): ...
+    class TodoTagAdminBase(ModelAdmin): ...
+
+
+@admin.register(Todo)
+class TodoAdmin(TodoAdminBase):
+    list_display = [
+        "id",
+        "user",
+        "title",
+        "due_date",
+        "priority",
+        "status",
+    ]
+    list_display_links = list_display
+    ordering = ("-id",)
+    list_filter = ["priority", "status"]
+    search_fields = ["title"]
+
+
+@admin.register(Tag)
+class TagAdmin(TagAdminBase):
+    list_display = ["id", "name"]
+    list_display_links = list_display
+    ordering = ("-id",)
+    search_fields = ["name"]
+
+
+@admin.register(TodoTag)
+class TodoTagAdmin(TodoTagAdminBase):
+    list_display = ["id", "todo", "tag"]
+    list_display_links = list_display
+    ordering = ("-id",)

djresttoolkit-0.17.1/demo/apps/todos/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class TodosConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.todos"
+    label = "todos"

djresttoolkit-0.17.1/demo/apps/todos/dbseed/tag_seed.py

@@ -0,0 +1,13 @@
+from djresttoolkit.dbseed.models import (  # type: ignore[import-not-found]
+    Field,
+    Gen,
+    SeedModel,
+)
+
+from ..models import Tag
+
+
+class TagSeedModel(SeedModel):
+    __model__ = Tag
+
+    name: str = Field(default_factory=Gen.word)

djresttoolkit-0.17.1/demo/apps/todos/dbseed/todo_seed.py

@@ -0,0 +1,44 @@
+from django.utils import timezone
+
+from djresttoolkit.dbseed.models import (  # type: ignore[import-not-found]
+    Field,
+    Gen,
+    SeedModel,
+)
+
+from ..models import Todo, TodoPriority, TodoStatus
+
+
+class TodoSeedModel(SeedModel):
+    __model__ = Todo
+
+    title: str = Field(
+        default_factory=lambda: Gen.sentence(nb_words=4),
+    )
+    description: str = Field(
+        default_factory=lambda: Gen.sentence(nb_words=20),
+    )
+    due_date: str | None = Field(
+        default_factory=lambda: Gen.date_time_this_year(
+            before_now=False, after_now=True
+        )
+        .replace(tzinfo=timezone.get_current_timezone())
+        .isoformat(),
+    )
+    priority: str = Field(
+        default_factory=lambda: Gen.random_element(
+            elements=[choice[0] for choice in TodoPriority.choices]
+        ),
+    )
+    status: str = Field(
+        default_factory=lambda: Gen.random_element(
+            elements=[choice[0] for choice in TodoStatus.choices]
+        ),
+    )
+    completed_at: str | None = Field(
+        default_factory=lambda: Gen.date_time_this_year(
+            before_now=False, after_now=True
+        )
+        .replace(tzinfo=timezone.get_current_timezone())
+        .isoformat(),
+    )

djresttoolkit-0.17.1/demo/apps/todos/dbseed/todo_tag_seed.py

@@ -0,0 +1,22 @@
+from djresttoolkit.dbseed.models import (  # type: ignore[import-not-found]
+    Field,
+    Gen,
+    SeedModel,
+)
+
+from ..models import Tag, Todo, TodoTag
+
+
+class TodoTagSeedModel(SeedModel):
+    __model__ = TodoTag
+
+    todo: int = Field(
+        default_factory=lambda: Gen.random_element(
+            list(Todo.objects.all().values_list("id", flat=True))
+        )
+    )
+    tag: int = Field(
+        default_factory=lambda: Gen.random_element(
+            list(Tag.objects.all().values_list("id", flat=True))
+        )
+    )

djresttoolkit-0.17.1/demo/apps/todos/migrations/0001_initial.py

@@ -0,0 +1,131 @@
+# Generated by Django 5.2.5 on 2025-08-18 05:32
+
+import django.db.models.deletion
+import uuid
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Tag",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                (
+                    "uuid",
+                    models.UUIDField(default=uuid.uuid4, editable=False, unique=True),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                ("name", models.CharField(max_length=50, unique=True)),
+            ],
+            options={
+                "abstract": False,
+            },
+        ),
+        migrations.CreateModel(
+            name="Todo",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                (
+                    "uuid",
+                    models.UUIDField(default=uuid.uuid4, editable=False, unique=True),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                ("title", models.CharField(max_length=255)),
+                ("description", models.TextField(blank=True, default="")),
+                ("due_date", models.DateTimeField(blank=True, null=True)),
+                (
+                    "priority",
+                    models.CharField(
+                        choices=[
+                            ("low", "Low"),
+                            ("medium", "Medium"),
+                            ("high", "High"),
+                            ("critical", "Critical"),
+                        ],
+                        default="medium",
+                        max_length=20,
+                    ),
+                ),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("pending", "Pending"),
+                            ("in_progress", "In Progress"),
+                            ("completed", "Completed"),
+                            ("archived", "Archived"),
+                        ],
+                        default="pending",
+                        max_length=20,
+                    ),
+                ),
+                ("completed_at", models.DateTimeField(blank=True, null=True)),
+                (
+                    "user",
+                    models.ForeignKey(
+                        help_text="Owner of this todo",
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="todos",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "abstract": False,
+            },
+        ),
+        migrations.CreateModel(
+            name="TodoTag",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "tag",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="tag_todos",
+                        to="todos.tag",
+                    ),
+                ),
+                (
+                    "todo",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="todo_tags",
+                        to="todos.todo",
+                    ),
+                ),
+            ],
+            options={
+                "unique_together": {("todo", "tag")},
+            },
+        ),
+    ]