[feature] Added OpenWispPagination class with suitable default values

pushpit kamboj · pushpit kamboj · commit 469ee65deaad · 2026-02-06T14:26:19.000+05:30
diff --git a/docs/developer/other-utilities.rst b/docs/developer/other-utilities.rst
@@ -83,6 +83,100 @@ Every openwisp module which has an API should use this class to configure
 its own default settings, which will be merged with the settings of the
 other modules.
 
+``openwisp_utils.api.pagination.OpenWispPagination``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A reusable pagination class for DRF views that provides consistent
+pagination behavior across OpenWISP modules with sensible defaults and
+flexible configuration.
+
+**Default Behavior:**
+
+- 10 items per page
+- Clients can request custom page sizes via ``?page_size=N`` query
+  parameter
+- Maximum 100 items per page to prevent performance issues
+- Standard page navigation via ``?page=N``
+
+**Configuration via Django Settings:**
+
+The pagination class reads settings dynamically, making it compatible with
+Django's ``override_settings`` decorator in tests. The following settings
+can be used to customize the default pagination behavior:
+
+- ``OPENWISP_PAGINATION_PAGE_SIZE`` (default: ``10``): Default number of
+  items per page
+- ``OPENWISP_PAGINATION_MAX_PAGE_SIZE`` (default: ``100``): Maximum
+  allowed page size
+- ``OPENWISP_PAGINATION_PAGE_SIZE_QUERY_PARAM`` (default:
+  ``"page_size"``): Query parameter name for page size
+
+**Usage in Views:**
+
+.. code-block:: python
+
+    from openwisp_utils.api.pagination import OpenWispPagination
+    from rest_framework.viewsets import ModelViewSet
+
+
+    class DeviceViewSet(ModelViewSet):
+        queryset = Device.objects.all()
+        serializer_class = DeviceSerializer
+        pagination_class = OpenWispPagination
+
+**Custom Configuration via Subclassing:**
+
+For view-specific pagination requirements, you can subclass
+``OpenWispPagination`` and override the properties:
+
+.. code-block:: python
+
+    from openwisp_utils.api.pagination import OpenWispPagination
+    from rest_framework.viewsets import ModelViewSet
+
+
+    class LargePagination(OpenWispPagination):
+        @property
+        def page_size(self):
+            return 50
+
+        @property
+        def max_page_size(self):
+            return 500
+
+
+    class ReportViewSet(ModelViewSet):
+        queryset = Report.objects.all()
+        serializer_class = ReportSerializer
+        pagination_class = LargePagination
+
+**Global Configuration:**
+
+To use ``OpenWispPagination`` as the default pagination class for all DRF
+views in your project, add it to ``REST_FRAMEWORK`` settings:
+
+.. code-block:: python
+
+    REST_FRAMEWORK = {
+        "DEFAULT_PAGINATION_CLASS": "openwisp_utils.api.pagination.OpenWispPagination",
+    }
+
+**API Request Examples:**
+
+.. code-block:: bash
+
+    # Returns first 10 items (default page size)
+    GET /api/devices/
+
+    # Returns items 11-20 (second page)
+    GET /api/devices/?page=2
+
+    # Returns first 25 items (custom page size)
+    GET /api/devices/?page_size=25
+
+    # Returns items 26-50 with custom page size
+    GET /api/devices/?page=2&page_size=25
+
 Storage Utilities
 -----------------
 
diff --git a/openwisp_utils/api/pagination.py b/openwisp_utils/api/pagination.py
@@ -0,0 +1,53 @@
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+
+try:
+    from rest_framework.pagination import PageNumberPagination
+except ImportError:  # pragma: nocover
+    raise ImproperlyConfigured(
+        "Django REST Framework is required to use "
+        "this feature but it is not installed"
+    )
+
+
+class OpenWispPagination(PageNumberPagination):
+    """Reusable pagination class with sensible defaults.
+
+    Configurable via Django settings: - OPENWISP_PAGINATION_PAGE_SIZE
+    (default: 10) - OPENWISP_PAGINATION_MAX_PAGE_SIZE (default: 100) -
+    OPENWISP_PAGINATION_PAGE_SIZE_QUERY_PARAM (default: 'page_size')
+    """
+
+    @property
+    def page_size(self):
+        """Return the page size from settings or default."""
+        if hasattr(self, "_page_size"):
+            return self._page_size
+        return getattr(settings, "OPENWISP_PAGINATION_PAGE_SIZE", 10)
+
+    @page_size.setter
+    def page_size(self, value):
+        self._page_size = value
+
+    @property
+    def max_page_size(self):
+        if hasattr(self, "_max_page_size"):
+            return self._max_page_size
+        return getattr(settings, "OPENWISP_PAGINATION_MAX_PAGE_SIZE", 100)
+
+    @max_page_size.setter
+    def max_page_size(self, value):
+        """Allow setting max_page_size."""
+        self._max_page_size = value
+
+    @property
+    def page_size_query_param(self):
+        if hasattr(self, "_page_size_query_param"):
+            return self._page_size_query_param
+        return getattr(
+            settings, "OPENWISP_PAGINATION_PAGE_SIZE_QUERY_PARAM", "page_size"
+        )
+
+    @page_size_query_param.setter
+    def page_size_query_param(self, value):
+        self._page_size_query_param = value
diff --git a/tests/test_project/tests/test_api.py b/tests/test_project/tests/test_api.py
@@ -1,6 +1,9 @@
 from django.conf import settings
 from django.core.exceptions import ValidationError
-from django.test import TestCase
+from django.test import TestCase, override_settings
+from openwisp_utils.api.pagination import OpenWispPagination
+from rest_framework.pagination import PageNumberPagination
+from rest_framework.test import APIRequestFactory
 from test_project.serializers import ShelfSerializer
 
 from ..models import Shelf
@@ -64,3 +67,135 @@ def test_rest_framework_settings_override(self):
                 "TEST": True,
             },
         )
+
+
+class TestOpenWispPagination(TestCase):
+    """Tests for the OpenWispPagination class."""
+
+    def setUp(self):
+        self.factory = APIRequestFactory()
+        self.pagination = OpenWispPagination()
+
+    def test_inheritance(self):
+        """Test that OpenWispPagination inherits from PageNumberPagination."""
+        self.assertIsInstance(self.pagination, PageNumberPagination)
+
+    def test_default_page_size(self):
+        """Test that default page_size is 10."""
+        pagination = OpenWispPagination()
+        self.assertEqual(pagination.page_size, 10)
+
+    def test_default_max_page_size(self):
+        """Test that default max_page_size is 100."""
+        pagination = OpenWispPagination()
+        self.assertEqual(pagination.max_page_size, 100)
+
+    def test_default_page_size_query_param(self):
+        """Test that default page_size_query_param is 'page_size'."""
+        pagination = OpenWispPagination()
+        self.assertEqual(pagination.page_size_query_param, "page_size")
+
+    @override_settings(OPENWISP_PAGINATION_PAGE_SIZE=25)
+    def test_custom_page_size_from_settings(self):
+        """Test that page_size can be overridden via settings."""
+        pagination = OpenWispPagination()
+        self.assertEqual(pagination.page_size, 25)
+
+    @override_settings(OPENWISP_PAGINATION_MAX_PAGE_SIZE=500)
+    def test_custom_max_page_size_from_settings(self):
+        """Test that max_page_size can be overridden via settings."""
+        pagination = OpenWispPagination()
+        self.assertEqual(pagination.max_page_size, 500)
+
+    @override_settings(OPENWISP_PAGINATION_PAGE_SIZE_QUERY_PARAM="limit")
+    def test_custom_page_size_query_param_from_settings(self):
+        """Test that page_size_query_param can be overridden via settings."""
+        pagination = OpenWispPagination()
+        self.assertEqual(pagination.page_size_query_param, "limit")
+
+    def test_page_size_setter(self):
+        """Test that page_size can be set directly."""
+        pagination = OpenWispPagination()
+        pagination.page_size = 50
+        self.assertEqual(pagination.page_size, 50)
+
+    def test_max_page_size_setter(self):
+        """Test that max_page_size can be set directly."""
+        pagination = OpenWispPagination()
+        pagination.max_page_size = 200
+        self.assertEqual(pagination.max_page_size, 200)
+
+    def test_page_size_query_param_setter(self):
+        """Test that page_size_query_param can be set directly."""
+        pagination = OpenWispPagination()
+        pagination.page_size_query_param = "per_page"
+        self.assertEqual(pagination.page_size_query_param, "per_page")
+
+
+class TestOpenWispPaginationIntegration(CreateMixin, TestCase):
+    """Integration tests for OpenWispPagination with actual queryset."""
+
+    shelf_model = Shelf
+
+    def setUp(self):
+        self.factory = APIRequestFactory()
+        # Create test shelves
+        for i in range(15):
+            self._create_shelf(name=f"shelf{i}")
+
+    def _get_request(self, path="/api/shelves/", data=None):
+        """Create a DRF Request object with query_params support."""
+        from rest_framework.request import Request
+
+        wsgi_request = self.factory.get(path, data)
+        return Request(wsgi_request)
+
+    def test_paginate_queryset(self):
+        """Test that pagination works correctly with a queryset."""
+        pagination = OpenWispPagination()
+        request = self._get_request()
+        queryset = Shelf.objects.all().order_by("id")
+        paginated = pagination.paginate_queryset(queryset, request)
+        # Default page size is 10
+        self.assertEqual(len(paginated), 10)
+
+    def test_paginate_queryset_second_page(self):
+        """Test that pagination returns correct items for second page."""
+        pagination = OpenWispPagination()
+        request = self._get_request(data={"page": 2})
+        queryset = Shelf.objects.all().order_by("id")
+        paginated = pagination.paginate_queryset(queryset, request)
+        # Remaining 5 items on second page
+        self.assertEqual(len(paginated), 5)
+
+    def test_paginate_queryset_custom_page_size(self):
+        """Test pagination with custom page size via query parameter."""
+        pagination = OpenWispPagination()
+        request = self._get_request(data={"page_size": 5})
+        queryset = Shelf.objects.all().order_by("id")
+        paginated = pagination.paginate_queryset(queryset, request)
+        self.assertEqual(len(paginated), 5)
+
+    def test_paginate_queryset_respects_max_page_size(self):
+        """Test that page_size is capped at max_page_size."""
+        pagination = OpenWispPagination()
+        pagination.max_page_size = 10
+        # Request more than max
+        request = self._get_request(data={"page_size": 100})
+        queryset = Shelf.objects.all().order_by("id")
+        paginated = pagination.paginate_queryset(queryset, request)
+        # Should be capped at max_page_size (10)
+        self.assertEqual(len(paginated), 10)
+
+    def test_get_paginated_response(self):
+        """Test that paginated response has correct structure."""
+        pagination = OpenWispPagination()
+        request = self._get_request()
+        queryset = Shelf.objects.all().order_by("id")
+        pagination.paginate_queryset(queryset, request)
+        response = pagination.get_paginated_response([])
+        self.assertIn("count", response.data)
+        self.assertIn("next", response.data)
+        self.assertIn("previous", response.data)
+        self.assertIn("results", response.data)
+        self.assertEqual(response.data["count"], 15)
