[feature] Added OpenWispPagination class with suitable default values

Author: pushpit kamboj

docs/developer/other-utilities.rst

@@ -83,6 +83,99 @@ 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
+
+
+    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
 -----------------
 

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