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 this module?
---------------------------
The paginate module contains extensive in-line documentation with examples.
Concerning WebHelpers
-----------------------
This is a standalone module. Former versions were included in the WebHelpers Python module as
webhelpers.paginate and were tightly coupled with the WebHelpers and the Pylons web framework. This
version aims to be useful independent of any web framework.
Subclassing Page()
------------------
This module supports pagination through list-like objects. To paginate though other types of objects
you can subclass the paginate.Page() class and provide a wrapper class that defines how to access
elements of that special collection.
You can find examples in other paginate_* modules like paginate_sqlalchemy. Basically you would have
to provide a class that implements the __init__, __getitem__ and __len__ methods.
It is trivial to make pagination for other datastores like Elasticsearch/Solr extending the base class.
Example::
class SqlalchemyOrmWrapper(object):
"""Wrapper class to access elements of a collection."""
def __init__(self, obj):
self.obj = obj
def __getitem__(self, range):
# Return a range of objects of an sqlalchemy.orm.query.Query object
return self.obj[range]
def __len__(self):
# Count the number of objects in an sqlalchemy.orm.query.Query object
return self.obj.count()
Then you can create your own Page class that uses the above wrapper class::
class SqlalchemyOrmPage(paginate.Page):
"""A pagination page that deals with SQLAlchemy ORM objects."""
def __init__(self, *args, **kwargs):
super(SqlalchemyOrmPage, self).__init__(*args, wrapper_class=SqlalchemyOrmWrapper, **kwargs)
As you can see it does not do much. It basically calls paginate.Page.__init__ and adds
wrapper_class=SqlalchemyOrmWrapper as an argument. The paginate.Page instance will use that wrapper
class to access the elements.
Generating HTML come for current page
-------------------------------------
Example::
p = paginate.Page([], page=15, items_per_page=15, item_count=1010)
# item_count is optional, but we pass a dummy empty resultset for this example
pattern = '$link_first $link_previous ~4~ $link_next $link_last (Page $page our of $page_count - total $item_count)'
p.pager(pattern, url='http://foo.com?x=$page', dotdot_attr={'x':5}, link_attr={'y':6}, curpage_attr={'z':77})
# *_attr arguments are optional and can be used to attach additional classes/attrs to tags
Results in::
'<a class="L" href="URL?x=1"><<</a> <a class="L" href="URL?x=14"><</a> <a class="L" href="URL?x=1">1</a> <span class="D">..</span> <a class="L" href="URL?x=11">11</a> <a class="L" href="URL?x=12">12</a> <a class="L" href="URL?x=13">13</a> <a class="L" href="URL?x=14">14</a> <span class="C">15</span> <a class="L" href="URL?x=16">16</a> <a class="L" href="URL?x=17">17</a> <a class="L" href="URL?x=18">18</a> <a class="L" href="URL?x=19">19</a> <span class="D">..</span> <a class="L" href="URL?x=68">68</a> <a class="L" href="URL?x=16">></a> <a class="L" href="URL?x=68">>></a> (Page 15 our of 68 - total items 1010)'
Using url maker to generate links to specific result ranges
-----------------------------------------------------------
You can pass `url_maker` Callback to generate the URL of other pages, given its numbers.
Must accept one int parameter and return a URI string.
Example::
def url_maker(page_number):
return str('foo/%s' % page_number)
page = paginate.Page(range(100), page=1, url_maker=url_maker)
eq_(page.pager(), '1 <a href="foo/2">2</a> <a href="foo/3">3</a> .. <a href="foo/5">5</a>')
Alternatively if you will not pass the link builder function, the pager() method can also accept `url` argument that contains URL that page links will point to.
Make sure it contains the string $page which will be replaced by the actual page number.
Must be given unless a url_maker is specified to __init__, in which case this parameter is ignored.
Using link information for custom paginator templates
-----------------------------------------------------
If you do not like the default HTML format produced by paginator you can use link_map() function to generate
a dictionary of links you can use in your own template.
Example::
p.link_map('$link_first $link_previous ~4~ $link_next $link_last (Page $page our of $page_count - total items $item_count)',url='URL?x=$page',dotdot_attr={'class':'D'}, link_attr={'class':"L"}, curpage_attr={'class':"C"})
Returns something like::
{'current_page': {'attrs': {'class': 'C'}, 'href': 'URL?x=15', 'value': 15},
'first_page': {'attrs': {'class': 'L'}, 'href': 'URL?x=1', 'type': 'first_page', 'value': 1},
'last_page': {'attrs': {'class': 'L'}, 'href': 'URL?x=68', 'type': 'last_page', 'value': 68},
'next_page': {'attrs': {'class': 'L'}, 'href': 'URL?x=16', 'type': 'next_page', 'value': 16},
'previous_page': {'attrs': {'class': 'L'}, 'href': 'URL?x=14', 'type': 'previous_page', 'value': 14},
'range_pages': [{'attrs': {'class': 'D'}, 'href': '', 'type': 'span', 'value': '..'},
{'attrs': {'class': 'L'}, 'href': 'URL?x=11', 'type': 'page', 'value': '11'},
{'attrs': {'class': 'L'}, 'href': 'URL?x=12', 'type': 'page', 'value': '12'},
{'attrs': {'class': 'L'}, 'href': 'URL?x=13', 'type': 'page', 'value': '13'},
{'attrs': {'class': 'L'}, 'href': 'URL?x=14', 'type': 'page', 'value': '14'},
{'attrs': {'class': 'C'}, 'href': 'URL?x=15', 'type': 'current_page', 'value': 15},
{'attrs': {'class': 'L'}, 'href': 'URL?x=16', 'type': 'page', 'value': '16'},
{'attrs': {'class': 'L'}, 'href': 'URL?x=17', 'type': 'page', 'value': '17'},
{'attrs': {'class': 'L'}, 'href': 'URL?x=18', 'type': 'page', 'value': '18'},
{'attrs': {'class': 'L'}, 'href': 'URL?x=19', 'type': 'page', 'value': '19'},
{'attrs': {'class': 'D'}, 'href': '', 'type': 'span', 'value': '..'}],
'radius': 4}
Using link_tag callable to generate custom link markup
------------------------------------------------------
In case you want to generate custom link markup for your project - for example for use with bootstrap,
`pager()` accepts `link_tag` argument that expects a callable that can be used to easly override the way links are
generated.
Example::
from paginate import Page, make_html_tag
def paginate_link_tag(item):
"""
Create an A-HREF tag that points to another page usable in paginate.
"""
a_tag = Page.default_link_tag(item)
if item['type'] == 'current_page':
return make_html_tag('li', a_tag, **{'class':'active'})
return make_html_tag('li', a_tag)
paginator.pager(
curpage_attr={'class':'current_page'},
dotdot_attr={'class':'spacer'},
symbol_first='<i class="fa fa-chevron-circle-left"></i>',
symbol_last='<i class="fa fa-chevron-circle-right"></i>',
symbol_previous='<i class="fa fa-chevron-left"></i>',
symbol_next='<i class="fa fa-chevron-right"></i>',
link_tag=paginate_link_tag)
Version 0.5.5 - 2016-11-22
--------------------------
Changes:
- Python 2.7/3.4+ compatibility improvements
Version 0.5.4 - 2016-04-25
--------------------------
Changes:
- Added radius size config option
Version 0.5.3 - 2016-03-09
--------------------------
Changes:
- Unocode related fixes
Version 0.5.2 - 2015-08-29
--------------------------
Changes:
- Handle the slice prior to handling the length - for better experience with
various databases that include item count in results
- bugfixes
Version 0.5.1 - 2015-10-22
--------------------------
Changes:
- bugfixes
Version 0.5.0 - 2015-08-29
--------------------------
Changes:
- link_tag callable can now be passed to generate custom link markup
- page object now has link_map() method that returns a mapping of information useful for generating
custom markup based on paginator data
Version 0.4.0 - 2012-12-06
--------------------------
Paginate has prior been maintained as webhelpers.paginate in the _webhelpers_ packages.
This version is a standalone version that should be useful outside of the webhelpers'
context.
Changes:
- Python 3 compatibility.
- SQLAlchemyObject and SQLAlchemyQuery collections are not automatically detected any more.
Instead you can use the respective Page class from the paginate_sqlalchemy module also
available on PyPi.
- presliced_list parameter no longer supported
- 'page_nr' and 'current_page' had been deprecated already and are now removed. Please use 'page'
instead.
- No automatic URL generation. You need to pass a 'url' argument to the Page.pager() method
containing a $page placeholder where you want the page number to be put in. Beware that the URL
is not quote-escaped any further.
- The Page.pager() does not automatically add CSS classes any more. If you want the old
behavior you need to pass these parameters explicitly:
link_attr={'class':'pager_link'}
curpage_attr={'class':'pager_curpage'}
dotdot_attr={'class':'pager_dotdot'}
- The partial_param parameter from Page.pager() is gone. You should use your own URLs for
AJAX/partial updates in the 'url' parameter.
- The page_param parameter from Page.pager() is also gone as URL generation has been severely
simplified.
- The string returned from Page.pager() consists of escaped HTML already. So you need to tell
your web framework to use the string verbatim and without further escaping.
The parameters symbol_first, symbol_last, symbol_previous and symbol_next use
< and > instead of "<" and ">" now.
- Page.__repr__ now returns a brief representation. E.g. <paginate.Page: 1 of 1>
Page.__str__ returns the verbose view you may be used to.
Version 0.3.2 - 2008-01-31
--------------------------
Public release on PyPi
Raw data
{
"_id": null,
"home_page": "https://github.com/Signum/paginate",
"name": "paginate",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "pagination paginate pages",
"author": "Christoph Haas",
"author_email": "email@christoph-haas.de",
"download_url": "https://files.pythonhosted.org/packages/68/58/e670a947136fdcece8ac5376b3df1369d29e4f6659b0c9b358605b115e9e/paginate-0.5.6.tar.gz",
"platform": "UNKNOWN",
"description": "What is pagination?\n---------------------\nThis module helps dividing large lists of items into pages. The user is shown one page at a time and\ncan navigate to other pages. Imagine you are offering a company phonebook and let the user search\nthe entries. If the search result contains 23 entries but you may want to display no more than 10\nentries at once. The first page contains entries 1-10, the second 11-20 and the third 21-23. See the\ndocumentation of the \"Page\" class for more information.\n\nHow do I use this module?\n---------------------------\nThe paginate module contains extensive in-line documentation with examples.\n\nConcerning WebHelpers\n-----------------------\nThis is a standalone module. Former versions were included in the WebHelpers Python module as\nwebhelpers.paginate and were tightly coupled with the WebHelpers and the Pylons web framework. This\nversion aims to be useful independent of any web framework.\n\nSubclassing Page()\n------------------\nThis module supports pagination through list-like objects. To paginate though other types of objects\nyou can subclass the paginate.Page() class and provide a wrapper class that defines how to access\nelements of that special collection.\n\nYou can find examples in other paginate_* modules like paginate_sqlalchemy. Basically you would have\nto provide a class that implements the __init__, __getitem__ and __len__ methods.\n\nIt is trivial to make pagination for other datastores like Elasticsearch/Solr extending the base class.\n\nExample::\n\n class SqlalchemyOrmWrapper(object):\n \"\"\"Wrapper class to access elements of a collection.\"\"\"\n def __init__(self, obj):\n self.obj = obj\n\n def __getitem__(self, range):\n # Return a range of objects of an sqlalchemy.orm.query.Query object\n return self.obj[range]\n\n def __len__(self):\n # Count the number of objects in an sqlalchemy.orm.query.Query object\n return self.obj.count()\n\nThen you can create your own Page class that uses the above wrapper class::\n\n class SqlalchemyOrmPage(paginate.Page):\n \"\"\"A pagination page that deals with SQLAlchemy ORM objects.\"\"\"\n def __init__(self, *args, **kwargs):\n super(SqlalchemyOrmPage, self).__init__(*args, wrapper_class=SqlalchemyOrmWrapper, **kwargs)\n\nAs you can see it does not do much. It basically calls paginate.Page.__init__ and adds\nwrapper_class=SqlalchemyOrmWrapper as an argument. The paginate.Page instance will use that wrapper\nclass to access the elements.\n\n\nGenerating HTML come for current page\n-------------------------------------\n\nExample::\n\n p = paginate.Page([], page=15, items_per_page=15, item_count=1010)\n # item_count is optional, but we pass a dummy empty resultset for this example\n pattern = '$link_first $link_previous ~4~ $link_next $link_last (Page $page our of $page_count - total $item_count)'\n p.pager(pattern, url='http://foo.com?x=$page', dotdot_attr={'x':5}, link_attr={'y':6}, curpage_attr={'z':77})\n # *_attr arguments are optional and can be used to attach additional classes/attrs to tags\n\n\nResults in::\n\n '<a class=\"L\" href=\"URL?x=1\"><<</a> <a class=\"L\" href=\"URL?x=14\"><</a> <a class=\"L\" href=\"URL?x=1\">1</a> <span class=\"D\">..</span> <a class=\"L\" href=\"URL?x=11\">11</a> <a class=\"L\" href=\"URL?x=12\">12</a> <a class=\"L\" href=\"URL?x=13\">13</a> <a class=\"L\" href=\"URL?x=14\">14</a> <span class=\"C\">15</span> <a class=\"L\" href=\"URL?x=16\">16</a> <a class=\"L\" href=\"URL?x=17\">17</a> <a class=\"L\" href=\"URL?x=18\">18</a> <a class=\"L\" href=\"URL?x=19\">19</a> <span class=\"D\">..</span> <a class=\"L\" href=\"URL?x=68\">68</a> <a class=\"L\" href=\"URL?x=16\">></a> <a class=\"L\" href=\"URL?x=68\">>></a> (Page 15 our of 68 - total items 1010)'\n\nUsing url maker to generate links to specific result ranges\n-----------------------------------------------------------\n\nYou can pass `url_maker` Callback to generate the URL of other pages, given its numbers.\nMust accept one int parameter and return a URI string.\n\nExample::\n\n def url_maker(page_number):\n return str('foo/%s' % page_number)\n page = paginate.Page(range(100), page=1, url_maker=url_maker)\n eq_(page.pager(), '1 <a href=\"foo/2\">2</a> <a href=\"foo/3\">3</a> .. <a href=\"foo/5\">5</a>')\n\n\n\nAlternatively if you will not pass the link builder function, the pager() method can also accept `url` argument that contains URL that page links will point to.\nMake sure it contains the string $page which will be replaced by the actual page number.\nMust be given unless a url_maker is specified to __init__, in which case this parameter is ignored.\n\nUsing link information for custom paginator templates\n-----------------------------------------------------\n\nIf you do not like the default HTML format produced by paginator you can use link_map() function to generate\na dictionary of links you can use in your own template.\n\nExample::\n\n p.link_map('$link_first $link_previous ~4~ $link_next $link_last (Page $page our of $page_count - total items $item_count)',url='URL?x=$page',dotdot_attr={'class':'D'}, link_attr={'class':\"L\"}, curpage_attr={'class':\"C\"})\n\nReturns something like::\n\n {'current_page': {'attrs': {'class': 'C'}, 'href': 'URL?x=15', 'value': 15},\n 'first_page': {'attrs': {'class': 'L'}, 'href': 'URL?x=1', 'type': 'first_page', 'value': 1},\n 'last_page': {'attrs': {'class': 'L'}, 'href': 'URL?x=68', 'type': 'last_page', 'value': 68},\n 'next_page': {'attrs': {'class': 'L'}, 'href': 'URL?x=16', 'type': 'next_page', 'value': 16},\n 'previous_page': {'attrs': {'class': 'L'}, 'href': 'URL?x=14', 'type': 'previous_page', 'value': 14},\n 'range_pages': [{'attrs': {'class': 'D'}, 'href': '', 'type': 'span', 'value': '..'},\n {'attrs': {'class': 'L'}, 'href': 'URL?x=11', 'type': 'page', 'value': '11'},\n {'attrs': {'class': 'L'}, 'href': 'URL?x=12', 'type': 'page', 'value': '12'},\n {'attrs': {'class': 'L'}, 'href': 'URL?x=13', 'type': 'page', 'value': '13'},\n {'attrs': {'class': 'L'}, 'href': 'URL?x=14', 'type': 'page', 'value': '14'},\n {'attrs': {'class': 'C'}, 'href': 'URL?x=15', 'type': 'current_page', 'value': 15},\n {'attrs': {'class': 'L'}, 'href': 'URL?x=16', 'type': 'page', 'value': '16'},\n {'attrs': {'class': 'L'}, 'href': 'URL?x=17', 'type': 'page', 'value': '17'},\n {'attrs': {'class': 'L'}, 'href': 'URL?x=18', 'type': 'page', 'value': '18'},\n {'attrs': {'class': 'L'}, 'href': 'URL?x=19', 'type': 'page', 'value': '19'},\n {'attrs': {'class': 'D'}, 'href': '', 'type': 'span', 'value': '..'}],\n 'radius': 4}\n\n\nUsing link_tag callable to generate custom link markup\n------------------------------------------------------\n\nIn case you want to generate custom link markup for your project - for example for use with bootstrap,\n`pager()` accepts `link_tag` argument that expects a callable that can be used to easly override the way links are\ngenerated.\n\n\nExample::\n\n from paginate import Page, make_html_tag\n\n def paginate_link_tag(item):\n \"\"\"\n Create an A-HREF tag that points to another page usable in paginate.\n \"\"\"\n a_tag = Page.default_link_tag(item)\n if item['type'] == 'current_page':\n return make_html_tag('li', a_tag, **{'class':'active'})\n return make_html_tag('li', a_tag)\n\n paginator.pager(\n curpage_attr={'class':'current_page'},\n dotdot_attr={'class':'spacer'},\n symbol_first='<i class=\"fa fa-chevron-circle-left\"></i>',\n symbol_last='<i class=\"fa fa-chevron-circle-right\"></i>',\n symbol_previous='<i class=\"fa fa-chevron-left\"></i>',\n symbol_next='<i class=\"fa fa-chevron-right\"></i>',\n link_tag=paginate_link_tag)\n\n\n\nVersion 0.5.5 - 2016-11-22\n--------------------------\nChanges:\n- Python 2.7/3.4+ compatibility improvements\n\nVersion 0.5.4 - 2016-04-25\n--------------------------\nChanges:\n- Added radius size config option\n\n\nVersion 0.5.3 - 2016-03-09\n--------------------------\nChanges:\n- Unocode related fixes\n\nVersion 0.5.2 - 2015-08-29\n--------------------------\nChanges:\n- Handle the slice prior to handling the length - for better experience with\n various databases that include item count in results\n- bugfixes\n\nVersion 0.5.1 - 2015-10-22\n--------------------------\nChanges:\n- bugfixes\n\n\nVersion 0.5.0 - 2015-08-29\n--------------------------\nChanges:\n- link_tag callable can now be passed to generate custom link markup\n- page object now has link_map() method that returns a mapping of information useful for generating\n custom markup based on paginator data\n\nVersion 0.4.0 - 2012-12-06\n--------------------------\nPaginate has prior been maintained as webhelpers.paginate in the _webhelpers_ packages.\nThis version is a standalone version that should be useful outside of the webhelpers'\ncontext.\n\nChanges:\n- Python 3 compatibility.\n- SQLAlchemyObject and SQLAlchemyQuery collections are not automatically detected any more.\n Instead you can use the respective Page class from the paginate_sqlalchemy module also\n available on PyPi.\n- presliced_list parameter no longer supported\n- 'page_nr' and 'current_page' had been deprecated already and are now removed. Please use 'page'\n instead.\n- No automatic URL generation. You need to pass a 'url' argument to the Page.pager() method\n containing a $page placeholder where you want the page number to be put in. Beware that the URL\n is not quote-escaped any further.\n- The Page.pager() does not automatically add CSS classes any more. If you want the old\n behavior you need to pass these parameters explicitly:\n link_attr={'class':'pager_link'}\n curpage_attr={'class':'pager_curpage'}\n dotdot_attr={'class':'pager_dotdot'}\n- The partial_param parameter from Page.pager() is gone. You should use your own URLs for\n AJAX/partial updates in the 'url' parameter.\n- The page_param parameter from Page.pager() is also gone as URL generation has been severely\n simplified.\n- The string returned from Page.pager() consists of escaped HTML already. So you need to tell\n your web framework to use the string verbatim and without further escaping.\n The parameters symbol_first, symbol_last, symbol_previous and symbol_next use\n < and > instead of \"<\" and \">\" now.\n- Page.__repr__ now returns a brief representation. E.g. <paginate.Page: 1 of 1>\n Page.__str__ returns the verbose view you may be used to.\n\nVersion 0.3.2 - 2008-01-31\n--------------------------\nPublic release on PyPi",
"bugtrack_url": null,
"license": "MIT",
"summary": "Divides large result sets into pages for easier browsing",
"version": "0.5.6",
"project_urls": {
"Homepage": "https://github.com/Signum/paginate"
},
"split_keywords": [
"pagination",
"paginate",
"pages"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6858e670a947136fdcece8ac5376b3df1369d29e4f6659b0c9b358605b115e9e",
"md5": "f806f880fc459e9bf2b194034144eafd",
"sha256": "5e6007b6a9398177a7e1648d04fdd9f8c9766a1a945bceac82f1929e8c78af2d"
},
"downloads": -1,
"filename": "paginate-0.5.6.tar.gz",
"has_sig": false,
"md5_digest": "f806f880fc459e9bf2b194034144eafd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12840,
"upload_time": "2016-11-22T12:54:04",
"upload_time_iso_8601": "2016-11-22T12:54:04.503904Z",
"url": "https://files.pythonhosted.org/packages/68/58/e670a947136fdcece8ac5376b3df1369d29e4f6659b0c9b358605b115e9e/paginate-0.5.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2016-11-22 12:54:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Signum",
"github_project": "paginate",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "paginate"
}
JSON
