webhelpers – helper functions for web applications

paginate: a module to help split up lists or results from ORM queries

What is pagination?

This module helps dividing large lists of items into pages. The user is shown one page at a time and can navigate to other pages. Imagine you are offering a company phonebook and let the user search the entries. If the search result contains 23 entries but you may want to display no more than 10 entries at once. The first page contains entries 1-10, the second 11-20 and the third 21-23. See the documentation of the “Page” class for more information.

How do I use it?

One page of items is represented by the Page object. A Page gets initialized with at least two arguments and usually three:

  • The collection of items to pick a range from.
  • The page number we want to display. (Default is 1: the first page.)
  • A URL generator callback. (This tells what the URLs to other pages are. It’s required if using the pager() method, although it may be omitted under Pylons for backward compatibility. It is required for Pyramid.)

Here’s an interactive example.

First we’ll create a URL generator using the basic PageURL class, which works with all frameworks and has no dependencies. It creates URLs by overriding the ‘page’ query parameter.

# Instantiate the URL generator, and call it to see what it does.
>>> url_for_page = PageURL("/articles/2013", {"page": "3"})
>>> url_for_page(page=2)

Now we can create a collection and instantiate the Page:

# Create a sample collection of 1000 items
>>> my_collection = range(1000)

# Create a Page object for the 3rd page (20 items per page is the default)
>>> my_page = Page(my_collection, page=3, url=url_for_page)

# The page object can be printed directly to get its details
>>> my_page
Collection type:  <type 'list'>
(Current) page:   3
First item:       41
Last item:        60
First page:       1
Last page:        50
Previous page:    2
Next page:        4
Items per page:   20
Number of items:  1000
Number of pages:  50

# Print a list of items on the current page
>>> my_page.items
[40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59]

# The *Page* object can be used as an iterator:
>>> for my_item in my_page: print my_item,
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59

# The .pager() method returns an HTML fragment with links to surrounding
# pages.
# [The ">>" prompt is to hide untestable examples from doctest.]
>> my_page.pager()
1 2 [3] 4 5 .. 50       (this is actually HTML)

# The pager can be customized:
>> my_page.pager('$link_previous ~3~ $link_next (Page $page of $page_count)')
1 2 [3] 4 5 6 .. 50 > (Page 3 of 50)

There are many parameters that customize the Page’s behavor. See the documentation on Page and Page.pager().

URL generator

The constructor’s url argument is a callback that returns URLs to other pages. It’s required when using the Page.pager() method except under Pylons, where it will fall back to pylons.url.current (Pylons 1) and then routes.url_for (Pylons 0.9.7). If none of these are available, you’ll get an exception “NotImplementedError: no URL generator available”.

WebHelpers 1.3 introduces a few URL generators for convenience. PageURL is described above. PageURL_WebOb takes a webobb.Request object, and is suitable for Pyramid, Pylons, TurboGears, and other frameworks that have a WebOb-compatible Request object. Both of these classes assume that the page number is in the ‘page’ query parameter.

Here’s an example for Pyramid and other WebOb-compatible frameworks:

# Assume ``request`` is the current request.
import webhelpers.paginate as paginate
current_page = int(request.params["page"])
page_url = paginate.PageURL_WebOb(request)
records = paginate.Page(q, current_page, url=page_url)

If the page number is in the URL path, you’ll have to use a framework-specific URL generator. For instance, in Pyramid if the current route is “/articles/{id}/page/{page}” and the current URL is “/articles/ABC/page/3?print=1”, you can use Pyramid’s “current_route_url” function as follows:

# Assume ``request`` is the current request.
import webhelpers.paginate as paginate
from pyramid.url import current_route_url
def page_url(page):
    return current_route_url(request, page=page, _query=request.GET)
current_page = int(request.matchdict["page"])
records = Page(q, current_page, url=page_url)

This overrides the ‘page’ path variable, while leaving the ‘id’ variable and the query string intact.

The callback API is simple.

  1. It must accept an integer argument ‘page’, which will be passed by name.
  2. It should return the URL for that page.
  3. If you’re using AJAX ‘partial’ functionality described in the Page.pager docstring, the callback should also accept a ‘partial’ argument and, if true, set a query parameter ‘partial=1’.
  4. If you use the ‘page_param’ or ‘partial_param’ argument to Page.pager, the ‘page’ and ‘partial’ arguments will be renamed to whatever you specify. In this case, the callback would also have to expect these other argument names.

The supplied classes adhere to this API in their .__call__ method, all except the fourth condition. So you can use their instances as callbacks as long as you don’t use ‘page_param’ or ‘partial_param’.

For convenience in writing callbacks that update the ‘page’ query parameter, a make_page_url function is available that assembles the pieces into a complete URL. Other callbacks may find webhelpers.utl.update_params useful, which overrides query parameters on a more general basis.

Can I use AJAX / AJAH?

Yes. See partial_param and onclick in Page.pager().


Page numbers and item numbers start at 1. This concept has been used because users expect that the first page has number 1 and the first item on a page also has number 1. So if you want to use the page’s items by their index number please note that you have to subtract 1.

This module is the successor to the obsolete webhelpers.pagination module. It is NOT API compatible.

This module is based on the code from http://workaround.org/cgi-bin/hg-paginate that is known at the “Paginate” module on PyPI. It was written by Christoph Haas <email@christoph-haas.de>, and modified by Christoph Haas and Mike Orr for WebHelpers. (c) 2007-2011.

Package Contents

class webhelpers.paginate.Page(collection, page=1, items_per_page=20, item_count=None, sqlalchemy_session=None, presliced_list=False, url=None, **kwargs)

A list/iterator of items representing one page in a larger collection.

An instance of the “Page” class is created from a collection of things. The instance works as an iterator running from the first item to the last item on the given page. The collection can be:

  • a sequence
  • an SQLAlchemy query - e.g.: Session.query(MyModel)
  • an SQLAlchemy select - e.g.: sqlalchemy.select([my_table])

A “Page” instance maintains pagination logic associated with each page, where it begins, what the first/last item on the page is, etc. The pager() method creates a link list allowing the user to go to other pages.

WARNING: Unless you pass in an item_count, a count will be performed on the collection every time a Page instance is created. If using an ORM, it’s advised to pass in the number of items in the collection if that number is known.

Instance attributes:

Points to the collection object being paged through
Number of items in the collection
Number of the current page
Maximal number of items displayed on a page
Number of the first page - starts with 1
Number of the last page
Number of pages
Sequence/iterator of items on the current page
Index of first item on the current page - starts with 1
Index of last item on the current page
Page.pager(format='~2~', page_param='page', partial_param='partial', show_if_single_page=False, separator=' ', onclick=None, symbol_first='<<', symbol_last='>>', symbol_previous='<', symbol_next='>', link_attr={'class': 'pager_link'}, curpage_attr={'class': 'pager_curpage'}, dotdot_attr={'class': 'pager_dotdot'}, **kwargs)

Return string with links to other pages (e.g. “1 2 [3] 4 5 6 7”).


Format string that defines how the pager is rendered. The string can contain the following $-tokens that are substituted by the string.Template module:

  • $first_page: number of first reachable page
  • $last_page: number of last reachable page
  • $page: number of currently selected page
  • $page_count: number of reachable pages
  • $items_per_page: maximal number of items per page
  • $first_item: index of first item on the current page
  • $last_item: index of last item on the current page
  • $item_count: total number of items
  • $link_first: link to first page (unless this is first page)
  • $link_last: link to last page (unless this is last page)
  • $link_previous: link to previous page (unless this is first page)
  • $link_next: link to next page (unless this is last page)

To render a range of pages the token ‘~3~’ can be used. The number sets the radius of pages around the current page. Example for a range with radius 3:

‘1 .. 5 6 7 [8] 9 10 11 .. 500’

Default: ‘~2~’


String to be displayed as the text for the %(link_first)s link above.

Default: ‘<<’


String to be displayed as the text for the %(link_last)s link above.

Default: ‘>>’


String to be displayed as the text for the %(link_previous)s link above.

Default: ‘<’


String to be displayed as the text for the %(link_next)s link above.

Default: ‘>’


String that is used to separate page links/numbers in the above range of pages.

Default: ‘ ‘


The name of the parameter that will carry the number of the page the user just clicked on. The parameter will be passed to a url_for() call so if you stay with the default ‘:controller/:action/:id’ routing and set page_param=’id’ then the :id part of the URL will be changed. If you set page_param=’page’ then url_for() will make it an extra parameters like ‘:controller/:action/:id?page=1’. You need the page_param in your action to determine the page number the user wants to see. If you do not specify anything else the default will be a parameter called ‘page’.

Note: If you set this argument and are using a URL generator callback, the callback must accept this name as an argument instead of ‘page’. callback, becaust the callback requires its argument to be ‘page’. Instead the callback itself can return any URL necessary.


When using AJAX/AJAH to do partial updates of the page area the application has to know whether a partial update (only the area to be replaced) or a full update (reloading the whole page) is required. So this parameter is the name of the URL parameter that gets set to 1 if the ‘onclick’ parameter is used. So if the user requests a new page through a Javascript action (onclick) then this parameter gets set and the application is supposed to return a partial content. And without Javascript this parameter is not set. The application thus has to check for the existence of this parameter to determine whether only a partial or a full page needs to be returned. See also the examples in this modules docstring.

Default: ‘partial’

Note: If you set this argument and are using a URL generator callback, the callback must accept this name as an argument instead of ‘partial’.


if True the navigator will be shown even if there is only one page

Default: False

link_attr (optional)

A dictionary of attributes that get added to A-HREF links pointing to other pages. Can be used to define a CSS style or class to customize the look of links.

Example: { ‘style’:’border: 1px solid green’ }

Default: { ‘class’:’pager_link’ }

curpage_attr (optional)

A dictionary of attributes that get added to the current page number in the pager (which is obviously not a link). If this dictionary is not empty then the elements will be wrapped in a SPAN tag with the given attributes.

Example: { ‘style’:’border: 3px solid blue’ }

Default: { ‘class’:’pager_curpage’ }

dotdot_attr (optional)

A dictionary of attributes that get added to the ‘..’ string in the pager (which is obviously not a link). If this dictionary is not empty then the elements will be wrapped in a SPAN tag with the given attributes.

Example: { ‘style’:’color: #808080’ }

Default: { ‘class’:’pager_dotdot’ }

onclick (optional)

This paramter is a string containing optional Javascript code that will be used as the ‘onclick’ action of each pager link. It can be used to enhance your pager with AJAX actions loading another page into a DOM object.

In this string the variable ‘$partial_url’ will be replaced by the URL linking to the desired page with an added ‘partial=1’ parameter (or whatever you set ‘partial_param’ to). In addition the ‘$page’ variable gets replaced by the respective page number.

Note that the URL to the destination page contains a ‘partial_param’ parameter so that you can distinguish between AJAX requests (just refreshing the paginated area of your page) and full requests (loading the whole new page).

[Backward compatibility: you can use ‘%s’ instead of ‘$partial_url’]

jQuery example:
“$(‘#my-page-area’).load(‘$partial_url’); return false;”
Yahoo UI example:
success:function(o){YAHOO.util.Dom.get(‘#my-page-area’).innerHTML=o.responseText;} },null); return false;”
scriptaculous example:
“new Ajax.Updater(‘#my-page-area’, ‘$partial_url’,
{asynchronous:true, evalScripts:true}); return false;”
ExtJS example:
“Ext.get(‘#my-page-area’).load({url:’$partial_url’}); return false;”
Custom example:

Additional keyword arguments are used as arguments in the links. Otherwise the link will be created with url_for() which points to the page you are currently displaying.