djresttoolkit 0.14.0__tar.gz → 0.15.0__tar.gz

{djresttoolkit-0.14.0 → djresttoolkit-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djresttoolkit
-Version: 0.14.0
+Version: 0.15.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
@@ -871,6 +871,59 @@ def my_view(request: HttpRequest):
 https://example.com/api/books/123/?ref=newsletter
 ```
 
+### 14. PageNumberPagination — API Reference
+
+```python
+from djresttoolkit.pagination import PageNumberPagination
+```
+
+#### Description of Page Number Pagination
+
+- Extends **DRF’s `PageNumberPagination`** with a **cleaner metadata structure**.
+- Adds support for **dynamic page size** via the `page-size` query parameter.
+- Returns pagination metadata inside a `"page"` object, separate from `"results"`.
+
+#### Features of Page Number Pagination
+
+- 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
+- Standardized API response format.
+
+### Attributes of Page Number Pagination
+
+- `page_size_query_param: str` → Query parameter name (`"page-size"`).
+
+### Page Number Pagination Methods
+
+- `get_paginated_response(data: Any) -> Response`
+  Returns a JSON response with both pagination metadata and results.
+
+### Example Response of Page Number Pagination
+
+```json
+{
+  "page": {
+    "current": 1,
+    "total": 10,
+    "size": 20,
+    "total_items": 200,
+    "next": "http://api.example.com/items/?page=2&page-size=20",
+    "previous": null
+  },
+  "results": [
+    { "id": 1, "name": "Item 1" },
+    { "id": 2, "name": "Item 2" }
+  ]
+}
+```
+
 ## 🛠️ Planned Features
 
 - Add more utils

{djresttoolkit-0.14.0 → djresttoolkit-0.15.0}/README.md

@@ -813,6 +813,59 @@ def my_view(request: HttpRequest):
 https://example.com/api/books/123/?ref=newsletter
 ```
 
+### 14. PageNumberPagination — API Reference
+
+```python
+from djresttoolkit.pagination import PageNumberPagination
+```
+
+#### Description of Page Number Pagination
+
+- Extends **DRF’s `PageNumberPagination`** with a **cleaner metadata structure**.
+- Adds support for **dynamic page size** via the `page-size` query parameter.
+- Returns pagination metadata inside a `"page"` object, separate from `"results"`.
+
+#### Features of Page Number Pagination
+
+- 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
+- Standardized API response format.
+
+### Attributes of Page Number Pagination
+
+- `page_size_query_param: str` → Query parameter name (`"page-size"`).
+
+### Page Number Pagination Methods
+
+- `get_paginated_response(data: Any) -> Response`
+  Returns a JSON response with both pagination metadata and results.
+
+### Example Response of Page Number Pagination
+
+```json
+{
+  "page": {
+    "current": 1,
+    "total": 10,
+    "size": 20,
+    "total_items": 200,
+    "next": "http://api.example.com/items/?page=2&page-size=20",
+    "previous": null
+  },
+  "results": [
+    { "id": 1, "name": "Item 1" },
+    { "id": 2, "name": "Item 2" }
+  ]
+}
+```
+
 ## 🛠️ Planned Features
 
 - Add more utils

{djresttoolkit-0.14.0 → djresttoolkit-0.15.0}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [project]
 name = "djresttoolkit"
-version = "0.14.0"
+version = "0.15.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.15.0/src/djresttoolkit/pagination/__init__.py

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

djresttoolkit-0.15.0/src/djresttoolkit/pagination/_page_number_pagination.py

@@ -0,0 +1,69 @@
+from typing import Any
+
+from rest_framework.exceptions import ValidationError
+from rest_framework.pagination import PageNumberPagination as DrfPageNumberPagination
+from rest_framework.response import Response
+
+
+class PageNumberPagination(DrfPageNumberPagination):
+    """
+    Custom PageNumberPagination for Django REST Framework.
+
+    This pagination class extends DRF's PageNumberPagination to provide:
+    - Dynamic page size support via the "page-size" query parameter.
+    - A streamlined, structured pagination metadata format in API responses.
+
+    Features:
+        - Clients can control the number of items per page using the "page-size" query parameter.
+        - The paginated response includes a "page" object with detailed pagination metadata and a "results" list.
+
+    Paginated Response Example:
+    ```
+    {
+        "page": {
+            "current": 1,
+            "total": 10,
+            "size": 20,
+            "total_items": 200,
+            "next": "http://api.example.com/items/?page=2&page-size=20",
+            "previous": null
+        },
+        "results": [ ... ]
+    }
+    ```
+
+    Attributes:
+        page_size_query_param (str): Query parameter name for dynamic page size ("page-size").
+
+    Methods:
+        get_paginated_response(data: Any) -> Response:
+            Returns a standardized paginated response with metadata and results.
+
+    """
+
+    # Allow clients to set page size via ?page-size=
+    page_size_query_param = "page-size"
+
+    def get_paginated_response(self, data: Any) -> Response:
+        page = getattr(self, "page", None)
+        paginator = getattr(self, "paginator", None)
+        request = getattr(self, "request", None)
+        if page is None or paginator is None or request is None:
+            raise ValidationError(
+                {"detail": "Pagination has not been properly configured."}
+            )
+
+        items_per_page = self.get_page_size(request)
+        return Response(
+            {
+                "page": {
+                    "current": page.number,
+                    "total": paginator.num_pages,
+                    "size": items_per_page,
+                    "total_items": paginator.count,
+                    "next": self.get_next_link(),
+                    "previous": self.get_previous_link(),
+                },
+                "results": data,
+            }
+        )