Pagination calculator designed for APIs
Project description
Pagination calculator designed for APIs
When building an API, out of bound pages should be treated with empty result sets. The existing solutions were not doing this. We have designed api-pagination to handle these edge cases from the perspective of an API.
Getting Started
Install the module with: pip install api_pagination
# Load in dependencies
from api_pagination import Paginator
# Generate a paginator and get info about a page
paginator = Paginator(total=100, items_per_page=10)
page_info = paginator.get_page_info(page=2)
{
'overall': {
'first_page': 1,
'last_page': 10,
'pages': 10,
'total': 100
},
'page': {
'current_page': 2,
'next_page': 3,
'previous_page': 1
}
}
# Use a classmethod to get info in one fell swoop
page_info = Paginator.page_info(page=1, total=100, items_per_page=10)
{
'overall': {
'first_page': 1,
'last_page': 10,
'pages': 10,
'total': 100
},
'page': {
'current_page': 1,
'next_page': 2,
'previous_page': None
}
}
# Handle out of bounds properly
page_info = Paginator.page_info(page=20, total=100, items_per_page=10)
{
'overall': {
'first_page': 1,
'last_page': 10,
'pages': 10,
'total': 100
},
'page': {
'current_page': 20,
'next_page': None,
'previous_page': 10
}
}Documentation
We expose the Paginator class via our package api_pagination
Paginator(total, items_per_page)
Class for calculating pagination info about items
total int - Overall amount of items present
items_per_page int - How many items to include on each page
paginator.get_page_info(page)
Gather information about a given page
page int - Human based index for a page
For example, page 1 will be for items 1-10 (where items_per_page=10)
Returns:
ret_val dict - Container for information about overall information and page specific information
overall dict - Container for overall information
first_page int - Human based index for first page
For example, with total=20 and items_per_page=10, we have first_page=1
last_page int - Human based index for last page
For example, with total=25 and items_per_page=10, we have last_page=3 (includes items 21-25)
pages int - Amount of pages overall
For example, with total=25 and items_per_page=10, we have pages=3
total int - Amount of items overall
page dict - Container for page specific information
current_page int - Human based index of requested page
next_page int|None - If there is another page after this one, next_page will be that page’s human based index
For example, with total=25, items_per_page=10, and page=2, we have next_page=3 (includes items 21-25)
When on the last page (e.g. total=25, items_per_page=10, page=3) next_page will be None
If we are under bounds (e.g. page=-1), then next_page will be the first page (page=1)
previous_page int|None - If there is another page before this one, previous_page will be that page’s human based index
For example, with total=25, items_per_page=10, and page=2, we have previous_page=1 (includes items 1-10)
When on the first page (e.g. total=25, items_per_page=10, page=1) then previous_page will be None
If we are over bounds (e.g. total=25, items_per_page=10, page=4), then previous_page will be the last page (page=3)
Paginator.page_info(page, *args, **kwargs)
Helper function to get page info without calling multiple actions
page int - Page to pass through to paginator.get_page_info
*args - Ordered arguments to pass through to Paginator constructor
**kwargs - Keyword based arguments to pass through to Paginator constructor
Returns:
Returns same format as paginator.get_page_info
Example:
page_info = Paginator.page_info(page=1, total=100, items_per_page=10)
# Same as
# paginator = Paginator(total=100, items_per_page=10)
# page_info = paginator.get_page_info(page=1)Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Test via ./test.sh.
License
Copyright (c) 2015 Underdog.io
Licensed under the MIT license.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
