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

README.md

@@ -6,13 +6,53 @@
 
 djresttoolkit is a collection of utilities and helpers for Django and Django REST Framework (DRF) that simplify common development tasks such as API handling, authentication, and email sending and much more.
 
-## ✨ Features
+## 📖 Feature Index (djresttoolkit)
 
-- Django REST Framework helpers (serializers, views, pagination, etc.)
-- Django utilities (e.g., email sending, model mixins)
-- Ready-to-use shortcuts to speed up API development
-- Lightweight, no unnecessary dependencies
-- Type Safe - written with modern Python type hints.
+- **DB Seed Command (`dbseed`)**
+  Seed your database with fake data using Pydantic models powered by **Faker**. Supports relationships, transactions, and a `manage.py dbseed` command.
+
+- **DB Flush Command (`dbflush`)**
+  Management command to flush all models or a specific model, resetting auto-increment IDs safely with transaction support.
+
+- **EnvBaseSettings**
+  Typed settings loader using **YAML + .env**, supports nested keys and overrides. Great for structured configuration management.
+
+- **EmailSender**
+  Custom class to send templated emails (`text` and `html`) with context. Supports error handling and logging.
+
+- **Custom DRF Exception Handler**
+  Centralized error handler for DRF that extends default behavior and adds throttle support (`429 Too Many Requests` with retry info).
+
+- **Response Time Middleware**
+  Middleware to measure, log, and inject `X-Response-Time` headers into every response.
+
+- **Throttle**
+  - `ThrottleInfoJSONRenderer`: Automatically adds throttle headers to responses.
+  - `ThrottleInspector`: Inspect view/request throttling and attach structured headers.
+
+- **AbsoluteUrlFileMixin**
+  DRF serializer mixin that converts `FileField` / `ImageField` URLs to **absolute URLs** automatically.
+
+- **BulkCreateMixin**
+  Serializer mixin that enables **bulk creation** of objects and syncs field error messages with model fields.
+
+- **ModelChoiceFieldMixin**
+  Retrieve choice fields (`TextChoices`, etc.) from Django models as structured dictionaries for API responses.
+
+- **ChoiceFieldsAPIView**
+  Generic API view that exposes model `choices` in a REST-friendly JSON format.
+
+- **RetrieveObjectMixin**
+  Lightweight mixin to fetch a single object from a queryset with filters, raising a custom error if `queryset` is not defined.
+
+- **build\_absolute\_uri**
+  Helper to build full absolute URLs for named routes with optional query params. Works with Django + DRF requests.
+
+- **PageNumberPagination**
+  Custom paginator with a structured `"page"` metadata block and support for dynamic `page-size` query param.
+
+- **PaginatedDataBuilder**
+  Builder that combines `PageNumberPagination` + serializers to return standardized paginated responses with `"page"` + `"results"`.
 
 ## 📦 Installation
 
@@ -30,7 +70,7 @@ djresttoolkit is a collection of utilities and helpers for Django and Django RES
 
 ## 📚 All API Reference
 
-### 1. DB Seed Utilities — API Reference
+### 1. DB Seed Command — API Reference
 
 #### `Generator`
 
@@ -353,7 +393,7 @@ X-Response-Time: 0.01234 seconds
 INFO: Request processed in 0.01234 seconds
 ```
 
-### 7. Throttle Utilities — API Reference
+### 7. Throttle — API Reference
 
 #### `ThrottleInfoJSONRenderer`
 
@@ -866,6 +906,73 @@ from djresttoolkit.pagination import PageNumberPagination
 }
 ```
 
+### 15. PaginatedDataBuilder — API Reference
+
+```python
+from djresttoolkit.pagination import PaginatedDataBuilder
+```
+
+---
+
+#### Description of Paginated Data Builder
+
+- A **builder utility** to paginate and serialize Django QuerySets using DRF.
+- Uses the custom **`PageNumberPagination`** class for consistent pagination responses.
+- Designed for reusability inside DRF views and APIs.
+
+#### Features of Paginated Data Builder
+
+- Integrates with **DRF serializers**.
+- Handles **invalid pages** gracefully by raising `NotFound`.
+- Returns both:
+  - `"page"` → pagination metadata
+  - `"results"` → serialized data.
+- Provides **structured pagination response format**.
+
+---
+
+#### Initialization of Paginated Data Builder
+
+```python
+builder = PaginatedDataBuilder(
+    request=request,
+    serializer_class=MySerializer,
+    queryset=MyModel.objects.all()
+)
+```
+
+- `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
+
+- `get_paginated_data() -> dict[str, Any]`
+
+  - Applies pagination to the queryset.
+  - Serializes the paginated results.
+  - Returns a dictionary with `"page"` and `"results"`.
+  - Raises `NotFound` if no page data is found.
+
+### Example Response of Paginated Data Builder
+
+```json
+{
+  "page": {
+    "current": 2,
+    "total": 5,
+    "size": 20,
+    "total_items": 100,
+    "next": "http://api.example.com/items/?page=3&page-size=20",
+    "previous": "http://api.example.com/items/?page=1&page-size=20"
+  },
+  "results": [
+    { "id": 21, "name": "Item 21" },
+    { "id": 22, "name": "Item 22" }
+  ]
+}
+```
+
 ## 🛠️ Planned Features
 
 - Add more utils

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djresttoolkit
-Version: 0.15.0
+Version: 0.16.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
@@ -64,13 +64,53 @@ Description-Content-Type: text/markdown
 
 djresttoolkit is a collection of utilities and helpers for Django and Django REST Framework (DRF) that simplify common development tasks such as API handling, authentication, and email sending and much more.
 
-## ✨ Features
+## 📖 Feature Index (djresttoolkit)
 
-- Django REST Framework helpers (serializers, views, pagination, etc.)
-- Django utilities (e.g., email sending, model mixins)
-- Ready-to-use shortcuts to speed up API development
-- Lightweight, no unnecessary dependencies
-- Type Safe - written with modern Python type hints.
+- **DB Seed Command (`dbseed`)**
+  Seed your database with fake data using Pydantic models powered by **Faker**. Supports relationships, transactions, and a `manage.py dbseed` command.
+
+- **DB Flush Command (`dbflush`)**
+  Management command to flush all models or a specific model, resetting auto-increment IDs safely with transaction support.
+
+- **EnvBaseSettings**
+  Typed settings loader using **YAML + .env**, supports nested keys and overrides. Great for structured configuration management.
+
+- **EmailSender**
+  Custom class to send templated emails (`text` and `html`) with context. Supports error handling and logging.
+
+- **Custom DRF Exception Handler**
+  Centralized error handler for DRF that extends default behavior and adds throttle support (`429 Too Many Requests` with retry info).
+
+- **Response Time Middleware**
+  Middleware to measure, log, and inject `X-Response-Time` headers into every response.
+
+- **Throttle**
+  - `ThrottleInfoJSONRenderer`: Automatically adds throttle headers to responses.
+  - `ThrottleInspector`: Inspect view/request throttling and attach structured headers.
+
+- **AbsoluteUrlFileMixin**
+  DRF serializer mixin that converts `FileField` / `ImageField` URLs to **absolute URLs** automatically.
+
+- **BulkCreateMixin**
+  Serializer mixin that enables **bulk creation** of objects and syncs field error messages with model fields.
+
+- **ModelChoiceFieldMixin**
+  Retrieve choice fields (`TextChoices`, etc.) from Django models as structured dictionaries for API responses.
+
+- **ChoiceFieldsAPIView**
+  Generic API view that exposes model `choices` in a REST-friendly JSON format.
+
+- **RetrieveObjectMixin**
+  Lightweight mixin to fetch a single object from a queryset with filters, raising a custom error if `queryset` is not defined.
+
+- **build\_absolute\_uri**
+  Helper to build full absolute URLs for named routes with optional query params. Works with Django + DRF requests.
+
+- **PageNumberPagination**
+  Custom paginator with a structured `"page"` metadata block and support for dynamic `page-size` query param.
+
+- **PaginatedDataBuilder**
+  Builder that combines `PageNumberPagination` + serializers to return standardized paginated responses with `"page"` + `"results"`.
 
 ## 📦 Installation
 
@@ -88,7 +128,7 @@ djresttoolkit is a collection of utilities and helpers for Django and Django RES
 
 ## 📚 All API Reference
 
-### 1. DB Seed Utilities — API Reference
+### 1. DB Seed Command — API Reference
 
 #### `Generator`
 
@@ -411,7 +451,7 @@ X-Response-Time: 0.01234 seconds
 INFO: Request processed in 0.01234 seconds
 ```
 
-### 7. Throttle Utilities — API Reference
+### 7. Throttle — API Reference
 
 #### `ThrottleInfoJSONRenderer`
 
@@ -924,6 +964,73 @@ from djresttoolkit.pagination import PageNumberPagination
 }
 ```
 
+### 15. PaginatedDataBuilder — API Reference
+
+```python
+from djresttoolkit.pagination import PaginatedDataBuilder
+```
+
+---
+
+#### Description of Paginated Data Builder
+
+- A **builder utility** to paginate and serialize Django QuerySets using DRF.
+- Uses the custom **`PageNumberPagination`** class for consistent pagination responses.
+- Designed for reusability inside DRF views and APIs.
+
+#### Features of Paginated Data Builder
+
+- Integrates with **DRF serializers**.
+- Handles **invalid pages** gracefully by raising `NotFound`.
+- Returns both:
+  - `"page"` → pagination metadata
+  - `"results"` → serialized data.
+- Provides **structured pagination response format**.
+
+---
+
+#### Initialization of Paginated Data Builder
+
+```python
+builder = PaginatedDataBuilder(
+    request=request,
+    serializer_class=MySerializer,
+    queryset=MyModel.objects.all()
+)
+```
+
+- `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
+
+- `get_paginated_data() -> dict[str, Any]`
+
+  - Applies pagination to the queryset.
+  - Serializes the paginated results.
+  - Returns a dictionary with `"page"` and `"results"`.
+  - Raises `NotFound` if no page data is found.
+
+### Example Response of Paginated Data Builder
+
+```json
+{
+  "page": {
+    "current": 2,
+    "total": 5,
+    "size": 20,
+    "total_items": 100,
+    "next": "http://api.example.com/items/?page=3&page-size=20",
+    "previous": "http://api.example.com/items/?page=1&page-size=20"
+  },
+  "results": [
+    { "id": 21, "name": "Item 21" },
+    { "id": 22, "name": "Item 22" }
+  ]
+}
+```
+
 ## 🛠️ Planned Features
 
 - Add more utils

{djresttoolkit-0.15.0.dist-info → djresttoolkit-0.16.1.dist-info}/RECORD

@@ -1,5 +1,5 @@
 LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
-README.md,sha256=I7qkoMQKLheto6lBClF21nbUqjIoQL84mJeopKxJxgQ,23157
+README.md,sha256=67zRUEO0Ccp-TqVpe3FsgHqRi5JGfckiZlAjLyI2jSw,26809
 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
@@ -26,8 +26,9 @@ src/djresttoolkit/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NM
 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/pagination/__init__.py,sha256=_Kb6oY2Aod6r4RYhmK0kmyiBdL0Dg-w15b9egtLdMMA,94
+src/djresttoolkit/pagination/__init__.py,sha256=lQhyyX381RbWBsYV9Os3OQIbY7Z6aouL0QE5kI_u5SU,176
 src/djresttoolkit/pagination/_page_number_pagination.py,sha256=NHPdMZfmTurKLdgpMBT2usTiGAoZMyA3dYXq_n11y34,2358
+src/djresttoolkit/pagination/_paginated_data_builder.py,sha256=N4JaJwmfmC2NiC8MqOpkxV8-itKTueaOdawnv_it4bU,2239
 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
@@ -45,8 +46,8 @@ src/djresttoolkit/views/_exceptions/__init__.py,sha256=DrCUxuPNyBR4WhzNutn5HDxLa
 src/djresttoolkit/views/_exceptions/_exception_handler.py,sha256=_o7If47bzWLl57LeSXSWsIDsJGo2RIpwYAwNQ-hsHVY,2839
 src/djresttoolkit/views/mixins/__init__.py,sha256=K-1tk5d8tCVViMynw5DdffJ3Oo5uHpEx32E3_4X2UxM,154
 src/djresttoolkit/views/mixins/_retrieve_object_mixin.py,sha256=Q9znYPb07YXXUhsL7VIrk3BC-zDwjOhwLJKe2GPJ-k0,1155
-djresttoolkit-0.15.0.dist-info/METADATA,sha256=zrnyfZFOoLT9ZcY179fBwk4j4xJjvTFWQRburyaeOxc,26167
-djresttoolkit-0.15.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-djresttoolkit-0.15.0.dist-info/entry_points.txt,sha256=YMhfTF-7mYppO8QqqWnvR_hyMWvoYxD6XI94_ViFu3k,60
-djresttoolkit-0.15.0.dist-info/licenses/LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
-djresttoolkit-0.15.0.dist-info/RECORD,,
+djresttoolkit-0.16.1.dist-info/METADATA,sha256=-GXgWkX-WeP5Mo3t1Id8QjeQnJWtHNts4PEAjahmePE,29819
+djresttoolkit-0.16.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+djresttoolkit-0.16.1.dist-info/entry_points.txt,sha256=YMhfTF-7mYppO8QqqWnvR_hyMWvoYxD6XI94_ViFu3k,60
+djresttoolkit-0.16.1.dist-info/licenses/LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
+djresttoolkit-0.16.1.dist-info/RECORD,,

src/djresttoolkit/pagination/__init__.py

@@ -1,3 +1,4 @@
 from ._page_number_pagination import PageNumberPagination
+from ._paginated_data_builder import PaginatedDataBuilder
 
-__all__ = ["PageNumberPagination"]
+__all__ = ["PageNumberPagination", "PaginatedDataBuilder"]

src/djresttoolkit/pagination/_paginated_data_builder.py

@@ -0,0 +1,65 @@
+import logging
+from typing import Any
+
+from django.db.models import QuerySet
+from rest_framework.exceptions import NotFound
+from rest_framework.request import Request
+from rest_framework.serializers import BaseSerializer
+from django.db.models import Model
+from ._page_number_pagination import PageNumberPagination
+
+# Get logger from logging.
+logger = logging.getLogger(__name__)
+
+
+class PaginatedDataBuilder[T: Model]:
+    """Builder class to handle pagination and serialization."""
+
+    def __init__(
+        self,
+        request: Request,
+        serializer_class: type[BaseSerializer[T]],
+        queryset: QuerySet[T],
+    ) -> None:
+        """Initilize the PaginatedDataBuilder class."""
+        self.request = request
+        self.serializer_class = serializer_class
+        self.queryset = queryset
+
+    def get_paginated_data(self) -> dict[str, Any]:
+        """Paginate and serialize the queryset."""
+
+        logger.debug("Starting pagination with custom PageNumberPagination.")
+        paginator = PageNumberPagination()
+        page = paginator.paginate_queryset(
+            self.queryset,
+            self.request,
+        )
+
+        # If no data is returned from pagination, raise NotFound
+        if page is None:
+            logger.warning("No data returned from pagination. Possibly invalid page.")
+            raise NotFound("The requested records were not found.")
+
+        # Serialize the paginated data
+        serializer = self.serializer_class(
+            instance=page,  # type: ignore
+            many=True,
+            context={"request": self.request},
+        )
+
+        # Construct the paginated response
+        paginated_data = {
+            "page": {
+                "current": paginator.page.number,  # type: ignore
+                "total": paginator.page.paginator.num_pages,  # type: ignore
+                "size": paginator.get_page_size(self.request),
+                "total_items": paginator.page.paginator.count,  # type: ignore
+                "next": paginator.get_next_link(),
+                "previous": paginator.get_previous_link(),
+            },
+            "results": serializer.data,
+        }
+
+        logger.debug(f"Pagination result: {paginated_data}")
+        return paginated_data