[feature] Added OpenWispPagination class with suitable default values

Author: pushpit kamboj

docs/developer/other-utilities.rst

@@ -83,6 +83,77 @@ 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 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``:
+
+.. code-block:: python
+
+    from openwisp_utils.api.pagination import OpenWispPagination
+
+
+    class LargePagination(OpenWispPagination):
+        page_size = 50
+        max_page_size = 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",
+    }
+
 Storage Utilities
 -----------------
 

openwisp_utils/api/pagination.py

@@ -0,0 +1,25 @@
+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')
+    """
+
+    page_size = getattr(settings, "OPENWISP_PAGINATION_PAGE_SIZE", 10)
+    max_page_size = getattr(settings, "OPENWISP_PAGINATION_MAX_PAGE_SIZE", 100)
+    page_size_query_param = getattr(
+        settings, "OPENWISP_PAGINATION_PAGE_SIZE_QUERY_PARAM", "page_size"
+    )