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

README.md

@@ -749,6 +749,123 @@ class BookDetailView(RetrieveObjectMixin[Book], APIView):
 - Returns `None` instead of raising `DoesNotExist`, making error handling easier.
 - Works with any Django model and queryset.
 
+### 13. build_absolute_uri — API Reference
+
+```python
+from djresttoolkit.urls import build_absolute_uri
+```
+
+#### build absolute uri Description
+
+- Builds a **fully qualified absolute URL** for a Django or DRF view.
+- Optionally includes **query parameters**.
+- Works with both **Django `HttpRequest`** and **DRF `Request`** objects.
+- Uses Django's `reverse()` to dynamically resolve URL names.
+
+#### build absolute uri Function Signature
+
+```python
+def build_absolute_uri(
+    request: HttpRequest | Request,
+    url_name: str,
+    query_params: dict[str, Any] | None = None,
+    *args: Any,
+    **kwargs: Any,
+) -> str:
+    ...
+```
+
+---
+
+#### build absolute uri Parameters
+
+- `request` (`HttpRequest | Request`): The incoming Django or DRF request object.
+- `url_name` (`str`): Name of the URL pattern to reverse.
+- `query_params` (`dict[str, Any] | None`): Optional dictionary of query parameters to append to the URL.
+- `*args` (`Any`): Positional arguments for the URL reversal.
+- `**kwargs` (`Any`): Keyword arguments for the URL reversal.
+
+---
+
+### build absolute uri Returns
+
+- `str`: Absolute URI of the view including optional query parameters.
+
+### Example of build absolute uri
+
+```python
+from django.http import HttpRequest
+from djresttoolkit.utils import build_absolute_uri
+
+def my_view(request: HttpRequest):
+    absolute_url = build_absolute_uri(
+        request,
+        url_name="book-detail",
+        query_params={"ref": "newsletter"},
+        pk=123
+    )
+    return HttpResponse(f"URL: {absolute_url}")
+```
+
+**Output Example:**
+
+```url
+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.13.0.dist-info → djresttoolkit-0.15.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djresttoolkit
-Version: 0.13.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
@@ -807,6 +807,123 @@ class BookDetailView(RetrieveObjectMixin[Book], APIView):
 - Returns `None` instead of raising `DoesNotExist`, making error handling easier.
 - Works with any Django model and queryset.
 
+### 13. build_absolute_uri — API Reference
+
+```python
+from djresttoolkit.urls import build_absolute_uri
+```
+
+#### build absolute uri Description
+
+- Builds a **fully qualified absolute URL** for a Django or DRF view.
+- Optionally includes **query parameters**.
+- Works with both **Django `HttpRequest`** and **DRF `Request`** objects.
+- Uses Django's `reverse()` to dynamically resolve URL names.
+
+#### build absolute uri Function Signature
+
+```python
+def build_absolute_uri(
+    request: HttpRequest | Request,
+    url_name: str,
+    query_params: dict[str, Any] | None = None,
+    *args: Any,
+    **kwargs: Any,
+) -> str:
+    ...
+```
+
+---
+
+#### build absolute uri Parameters
+
+- `request` (`HttpRequest | Request`): The incoming Django or DRF request object.
+- `url_name` (`str`): Name of the URL pattern to reverse.
+- `query_params` (`dict[str, Any] | None`): Optional dictionary of query parameters to append to the URL.
+- `*args` (`Any`): Positional arguments for the URL reversal.
+- `**kwargs` (`Any`): Keyword arguments for the URL reversal.
+
+---
+
+### build absolute uri Returns
+
+- `str`: Absolute URI of the view including optional query parameters.
+
+### Example of build absolute uri
+
+```python
+from django.http import HttpRequest
+from djresttoolkit.utils import build_absolute_uri
+
+def my_view(request: HttpRequest):
+    absolute_url = build_absolute_uri(
+        request,
+        url_name="book-detail",
+        query_params={"ref": "newsletter"},
+        pk=123
+    )
+    return HttpResponse(f"URL: {absolute_url}")
+```
+
+**Output Example:**
+
+```url
+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.13.0.dist-info → djresttoolkit-0.15.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
-README.md,sha256=GaxIplR2lXkKw0EPirrCMO6rLde0rdkv6Ch0W49a1B4,20113
+README.md,sha256=I7qkoMQKLheto6lBClF21nbUqjIoQL84mJeopKxJxgQ,23157
 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,6 +26,8 @@ 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/_page_number_pagination.py,sha256=NHPdMZfmTurKLdgpMBT2usTiGAoZMyA3dYXq_n11y34,2358
 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
@@ -34,6 +36,8 @@ src/djresttoolkit/serializers/mixins/_absolute_url_file_mixin.py,sha256=5ewael0_
 src/djresttoolkit/serializers/mixins/_bulk_create_mixin.py,sha256=9ZWm2MNaZOhmhKlWOu6VECtlDbUtaPeceGHmivDYwYQ,3248
 src/djresttoolkit/throttling/__init__.py,sha256=01sjMymjx8XjqnAw3bEBLc-JtfhCDrp5dGxSNXMvPpU,84
 src/djresttoolkit/throttling/_throttle_inspector.py,sha256=Kss6ZxKy-EXq9UGaGprGDhpSuJ5992bmEYZSWmUVBHo,6480
+src/djresttoolkit/urls/__init__.py,sha256=u-Hj8GARO0mWZwiehCi3VslMXqtkdAFff7VcXVuiN8w,86
+src/djresttoolkit/urls/_build_absolute_uri.py,sha256=X9kdoTRGIJ2ordpkHgSXmqwmmMT-OZBgluV5ULUhJEk,915
 src/djresttoolkit/views/__init__.py,sha256=QuJ9C0Vfzkfrwyqzunxh-A-aErmS6yOoy0uzjDu3oG8,177
 src/djresttoolkit/views/_api_views/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 src/djresttoolkit/views/_api_views/_choice_fields_apiview.py,sha256=zABPgqxMVaWd814B_sC64bWL61fDJkyYQZmJXQCa6Xc,1395
@@ -41,8 +45,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.13.0.dist-info/METADATA,sha256=iq6CfG1jgD-bHq6mREQaoixT451gcA4DIyoBSe6hRNg,23123
-djresttoolkit-0.13.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-djresttoolkit-0.13.0.dist-info/entry_points.txt,sha256=YMhfTF-7mYppO8QqqWnvR_hyMWvoYxD6XI94_ViFu3k,60
-djresttoolkit-0.13.0.dist-info/licenses/LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
-djresttoolkit-0.13.0.dist-info/RECORD,,
+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,,

src/djresttoolkit/pagination/__init__.py

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

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,
+            }
+        )

src/djresttoolkit/urls/__init__.py

@@ -0,0 +1,3 @@
+from ._build_absolute_uri import build_absolute_uri
+
+__all__ = ["build_absolute_uri"]

src/djresttoolkit/urls/_build_absolute_uri.py

@@ -0,0 +1,33 @@
+from typing import Any
+from urllib.parse import urlencode
+from django.http import HttpRequest
+from django.urls import reverse
+from rest_framework.request import Request
+
+
+def build_absolute_uri(
+    request: HttpRequest | Request,
+    url_name: str,
+    query_params: dict[str, Any] | None = None,
+    *args: Any,
+    **kwargs: Any,
+) -> str:
+    """
+    Build an absolute URI for a given Django or DRF view.
+
+    Args:
+        request: Django or DRF request object.
+        url_name: Name of the URL pattern to reverse.
+        query_params: Optional dictionary of query parameters.
+        *args: Positional arguments for the URL.
+        **kwargs: Keyword arguments for the URL.
+
+    Returns:
+        Absolute URI as a string.
+    """
+    url = reverse(url_name, args=args, kwargs=kwargs)
+
+    if query_params:
+        url += f"?{urlencode(query_params, doseq=True)}"
+
+    return request.build_absolute_uri(url)