Django Easy Pagination

A Django REST Framework library providing customizable pagination classes with rich metadata and flexible configuration options.

Features

Rich Metadata: Get comprehensive pagination information including total pages, current page, and page size
Multiple Pagination Classes: Pre-configured classes for different use cases
Highly Customizable: Easy to customize page sizes and behavior
Client Control: Allow clients to specify page size via query parameters
Production Ready: Includes comprehensive test suite
Well Documented: Clear documentation and examples

Installation

Install using pip:

pip install easy_pagination

Or install from source:

git clone https://github.com/digitaltouchcode/easy-pagination.git
cd easy-pagination
pip install -e .

Quick Start

1. Add to your Django REST Framework view:

from rest_framework import viewsets
from easy_pagination import StandardPagination

class MyViewSet(viewsets.ModelViewSet):
    queryset = MyModel.objects.all()
    serializer_class = MySerializer
    pagination_class = StandardPagination

2. Get paginated responses with rich metadata:

{
    "count": 100,
    "next": "http://api.example.com/items/?page=3",
    "previous": "http://api.example.com/items/?page=1",
    "total_pages": 10,
    "current_page": 2,
    "page_size": 10,
    "results": [...]
}

Available Pagination Classes

StandardPagination

Default pagination for most list views.

• Default page size: 20 items
• Max page size: 100 items
• Best for: General purpose API endpoints

from easy_pagination import StandardPagination

class MyViewSet(viewsets.ModelViewSet):
    pagination_class = StandardPagination

SmallResultsPagination

Optimized for small, quick-loading lists.

• Default page size: 10 items
• Max page size: 50 items
• Best for: Dropdown lists, autocomplete, quick searches

from easy_pagination import SmallResultsPagination

class QuickListViewSet(viewsets.ModelViewSet):
    pagination_class = SmallResultsPagination

LargeResultsPagination

Designed for large datasets and reports.

• Default page size: 50 items
• Max page size: 500 items
• Best for: Reports, data exports, admin interfaces

from easy_pagination import LargeResultsPagination

class ReportViewSet(viewsets.ModelViewSet):
    pagination_class = LargeResultsPagination

NoPagination

Disable pagination for specific views.

• Returns: All results without pagination
• Best for: Small datasets, configuration endpoints
• Warning: Use carefully with large datasets!

from easy_pagination import NoPagination

class ConfigViewSet(viewsets.ModelViewSet):
    pagination_class = NoPagination

Advanced Usage

Custom Pagination Class

Create your own pagination class by extending CustomPageNumberPagination:

from easy_pagination import CustomPageNumberPagination

class MyCustomPagination(CustomPageNumberPagination):
    page_size = 25
    max_page_size = 200
    page_size_query_param = 'page_size'

Dynamic Pagination

Use the factory function to create pagination classes on the fly:

from easy_pagination import get_pagination_class

class MyViewSet(viewsets.ModelViewSet):
    pagination_class = get_pagination_class(page_size=30, max_page_size=200)

Client-Controlled Page Size

Clients can control page size using query parameters:

# Get 50 items per page
GET /api/items/?page_size=50

# Navigate to page 3
GET /api/items/?page=3

# Combine both
GET /api/items/?page=3&page_size=50

Global Configuration

Set a default pagination class for all views in your Django settings:

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'easy_pagination.StandardPagination',
    'PAGE_SIZE': 20
}

Response Schema

All pagination classes return responses with the following structure:

Field	Type	Description
count	integer	Total number of items across all pages
next	string/null	URL to the next page (null if on last page)
previous	string/null	URL to the previous page (null if on first page)
total_pages	integer	Total number of pages
current_page	integer	Current page number (1-indexed)
page_size	integer	Number of items per page
results	array	Array of serialized objects for current page

Requirements

• Python >= 3.9
• Django >= 4.0
• djangorestframework >= 3.12

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/digitaltouchcode/easy-pagination.git
cd easy-pagination

# Install in development mode
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=easy_pagination

# Run specific test file
pytest tests/test_pagination.py

Code Quality

# Format code with black
black easy_pagination/

# Sort imports
isort easy_pagination/

# Lint with flake8
flake8 easy_pagination/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Casper

• Email: cassymyo@gmail.com
• GitHub: @casperspec-1

Changelog

See CHANGELOG.md for a list of changes.

Support

If you encounter any issues or have questions, please open an issue on GitHub.

Acknowledgments

Built with ❤️ using Django REST Framework.