Ñò
{XHc @ s d Z d Z d Z d Z d Z d d k Z d d k Z y d d k l Z Wn# e j
o d d k
l Z n Xd d k l Z l
Z
y d d k Z Wn
e Z n
Xe i Z d d „ Z d
e f d „ ƒ YZ d e f d
„ ƒ YZ d e f d „ ƒ YZ d S( s¯
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
initalized with two parameters at least:
- the collection of items to pick a range from
- the page number that is required (default is 1 - the first page)
A simple example (ipython session)::
# Set up the routes context (only if you are not using a Pylons application)
>>> from routes import Mapper; mapper=Mapper(); mapper.connect(':controller')
# 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)
# The page object can be printed directly to get its details
>>> my_page
Page:
Collection type:
(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
# On a web page you will want to use a "pager" that creates links that
# the user can click on to load other pages in the set.
# [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)
Please see the documentation on *Page* and *Page.pager()*. There are many
parameters that customize the Page's behavior.
Can I use AJAX / AJAH?
------------------------
Yes. See *partial_param* and *onclick* in *Page.pager()*.
Notes
-------
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 substract 1.
This module is the successor to the deprecated ``webhelpers.pagination``
module. It is *NOT* API compatible.
This version of paginate is based on the code from
http://workaround.org/cgi-bin/hg-paginate that is known at the
"Paginate" module on PyPi.
s 0.3.6s
2008-05-01s( Christoph Haas s@ Copyright (c) 2007,2008 Christoph Haas iÿÿÿÿN( t Template( t literalt HTMLc C s³ t | t t f ƒ o | St i d ƒ p t i d ƒ oh t | t i i i ƒ o t | ƒ St | t i
i i ƒ p t | t i
i i
ƒ o t | | ƒ Sn t d ƒ ‚ d S( si
Auto-detect the kind of object and return a list/tuple
to access items from the collection.
s 0.4s 0.5s³ Sorry, your collection type is not supported by the paginate module. You can either provide a list, a tuple, an SQLAlchemy 0.4 select object or an SQLAlchemy 0.4 ORM-query object.N( t
isinstancet listt tuplet sqlalchemy_availablet
startswitht
sqlalchemyt ormt queryt Queryt _SQLAlchemyQueryt sqlt
expressiont CompoundSelectt Selectt _SQLAlchemySelectt TypeError( t objt sqlalchemy_session( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyt get_wrapper s R c B s, e Z d Z d d „ Z d „ Z d „ Z RS( sM
Iterable that allows to get slices from an SQLAlchemy Select object
c C s? t | t i i i ƒ p t d ƒ ‚ n | | _ | | _ d S( Ns¤ If you want to page an SQLAlchemy 'select' object then you have to provide a 'sqlalchemy_session' argument. See also: http://www.sqlalchemy.org/docs/04/session.html( R R R t scopingt
ScopedSessionR R R ( t selfR R ( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyt __init__« s c C sg t | t ƒ p
t d ‚ n | i } | i | i } | i i | ƒ i | ƒ } | i i | ƒ i
ƒ S( Ns) __getitem__ without slicing not supported( R t slicet Exceptiont startt stopR t offsett limitR t executet fetchall( R t rangeR R t select( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyt __getitem__´ s
c C s | i i | i ƒ i S( N( R R R t rowcount( R ( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyt __len__¼ s N( t __name__t
__module__t __doc__t NoneR R$ R& ( ( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyR § s R c B s) e Z d Z d „ Z d „ Z d „ Z RS( sL
Iterable that allows to get slices from an SQLAlchemy Query object
c C s
| | _ d S( N( R ( R R ( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyR Ã s c C s( t | t ƒ p
t d ‚ n | i | S( Ns) __getitem__ without slicing not supported( R R R R ( R R" ( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyR$ Æ s
c C s
| i i ƒ S( N( R t count( R ( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyR& Ë s ( R' R( R) R R$ R& ( ( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyR ¿ s t Pagec B sq e Z d Z d d d d d „ Z d „ Z d d d e d d d d
d d h d
d 6h d d 6h d d 6d „
Z RS( s! 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:
original_collection
Points to the collection object being paged through
item_count
Number of items in the collection
page
Number of the current page
items_per_page
Maximal number of items displayed on a page
first_page
Number of the first page - starts with 1
last_page
Number of the last page
page_count
Number of pages
items
Sequence/iterator of items on the current page
first_item
Index of first item on the current page - starts with 1
last_item
Index of last item on the current page
i i c O s¬ d | j o" t i d ƒ | d } | d =n d | j o" t i d ƒ | d } | d =n | | _ | | _ | o t | | ƒ | _ n
g | _ y t | ƒ | _ Wn t j
o d | _ n X| | _ | d j o
| | _ n t | i ƒ | _ | i d j o@d | _
| i d | i d | _ | i
| i d | _ | i | i j o | i | _ n$ | i | i
j o | i
| _ n | i d | d | _ t | i | d | i ƒ | _ t | i | i d | i !ƒ | _ | i | i
j o | i d | _ n
d | _ | i | i j o | i d | _ q•d | _ nI d | _
d | _ d | _ d | _ d | _ d | _ d | _ g | _ t i | | i ƒ d S( sa Create a "Page" instance.
Parameters:
collection
Sequence, SQLAlchemy select object or SQLAlchemy ORM-query
representing the collection of items to page through.
page
The requested page number - starts with 1. Default: 1.
items_per_page
The maximal number of items to be displayed per page.
Default: 20.
item_count (optional)
The total number of items in the collection - if known.
If this parameter is not given then the paginator will count
the number of elements in the collection every time a "Page"
is created. Giving this parameter will speed up things.
sqlalchemy_session (optional)
If you want to use an SQLAlchemy (0.4) select object as a
collection then you need to provide an SQLAlchemy session object.
Select objects do not have a database connection attached so it
would not be able to execute the SELECT query.
Further keyword arguments are used as link arguments in the pager().
t page_nrs3 'page_nr' is deprecated. Please use 'page' instead.t current_pages8 'current_page' is deprecated. Please use 'page' instead.i i N( t warningst warnt kwargst original_collectionR t
collectiont intt paget
ValueErrort items_per_pageR* t
item_countt lent
first_paget
page_countt last_paget
first_itemt mint last_itemR t itemst
previous_paget next_pageR ( R R3 R5 R7 R8 R t argsR1 ( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyR s^
#
c C s| d h t | i ƒ d 6| i d 6| i d 6| i d 6| i d 6| i d 6| i d 6| i d 6| i d
6| i
d 6| i d 6S(
Nsi Page:
Collection type: %(type)s
(Current) page: %(page)s
First item: %(first_item)s
Last item: %(last_item)s
First page: %(first_page)s
Last page: %(last_page)s
Previous page: %(previous_page)s
Next page: %(next_page)s
Items per page: %(items_per_page)s
Number of items: %(item_count)s
Number of pages: %(page_count)s
t typeR5 R= R? R: R< RA RB R7 R8 R; ( RD R3 R5 R= R? R: R< RA RB R7 R8 R; ( R ( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyt __repr__ s
s ~2~R5 t partialt s <>t t
pager_linkt classt
pager_curpaget pager_dotdotc sŒ ‡ ‡ ‡ ‡ ‡ ‡ f d † ‰ ‡ ‡ ‡ ‡ ‡ f d † } ˆ i d j p ˆ i d j o
| o d St i d | | ƒ } t | ƒ i h ˆ i d 6ˆ i d 6ˆ i d 6ˆ i d
6ˆ i d 6ˆ i d 6ˆ i
d
6ˆ i d 6ˆ i ˆ i j o ˆ ˆ i | ƒ p d d 6ˆ i ˆ i j o ˆ ˆ i | ƒ p d d 6ˆ i o ˆ ˆ i | ƒ p d d 6ˆ i
o ˆ ˆ i
|
ƒ p d d 6ƒ } t | ƒ S( s&
Return string with links to other pages (e.g. "1 2 [3] 4 5 6 7").
format:
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~'
symbol_first
String to be displayed as the text for the %(link_first)s
link above.
Default: '<<'
symbol_last
String to be displayed as the text for the %(link_last)s
link above.
Default: '>>'
symbol_previous
String to be displayed as the text for the %(link_previous)s
link above.
Default: '<'
symbol_next
String to be displayed as the text for the %(link_next)s
link above.
Default: '>'
separator:
String that is used to seperate page links/numbers in the
above range of pages.
Default: ' '
page_param:
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'.
partial_param:
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 existance 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'
show_if_single_page:
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 used as the 'onclick' action of each pager link.
Use '%s' in your string where the URL linking to the desired
page will be inserted. This can be used to enhance your pager
with AJAX actions loading another page into a DOM object.
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).
jQuery example:
"$('#my-page-area').load('%s'); return false;"
Yahoo UI example:
"YAHOO.util.Connect.asyncRequest('GET','%s',{
success:function(o){YAHOO.util.Dom.get('#my-page-area').innerHTML=o.responseText;}
},null); return false;"
scriptaculous example:
"new Ajax.Updater('#my-page-area', '%s',
{asynchronous:true, evalScripts:true}); return false;"
ExtJS example:
"Ext.get('#my-page-area').load({url:'%s'}); return false;"
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.
c sª d d k l } h } | i ˆ i ƒ | i ˆ ƒ | | ˆ <| | } d | ˆ <| | } ˆ o* ˆ | f } t i | d | d | ˆ St i | d | ˆ Sd S( s
Create a URL that links to another page using url_for().
Parameters:
pagenr
Number of the page that the link points to
text
Text to be printed in the A-HREF tag
iÿÿÿÿ( t url_fori t hreft onclickN( t routesRN t updateR1 R t a( t pagenrt textRN t link_paramst link_urlt partial_urlt onclick_action( t
page_paramR t link_attrt
partial_paramRP R1 ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyt
_pagerlink: s
c s t | i d ƒ ƒ } t ˆ i ˆ i | ƒ } t ˆ i ˆ i | ƒ } g } ˆ i ˆ i j o0 ˆ i | j o | i ˆ ˆ i ˆ i ƒ ƒ n | ˆ i d j o7 d } ˆ o t i d | ˆ } n | i | ƒ n xŒ t
| | d ƒ D]w } | ˆ i j o> d | f } ˆ o t i d | ˆ } n | i | ƒ qï d | f } | i ˆ | | ƒ ƒ qï Wˆ i | d j o7 d } ˆ o t i d | ˆ } n | i | ƒ n ˆ i ˆ i j o0 | ˆ i j o | i ˆ ˆ i ˆ i ƒ ƒ n ˆ i | ƒ S( s·
Return range of linked pages (e.g. '1 2 [3] 4 5 6 7 8').
Arguments:
regexp_match
A "re" (regular expressions) match object containing the
radius of linked pages around the current page in
regexp_match.group(1) as a string
This funtion is supposed to be called as a callable in
re.sub.
i s ..t cs %s( R4 t groupt maxR: R5 R> R< t appendR t spant xranget join( t regexp_matcht radiust
leftmost_paget rightmost_paget nav_itemsRU t thispage( R] R t separatort curpage_attrt dotdot_attr( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyt _rangeb s8 #
# i i t s ~(\d+)~R: R< R5 R; R7 R= R? R8 t
link_firstt link_lastt
link_previoust link_next( R; t ret subR t safe_substituteR: R< R5 R7 R= R? R8 RA RB R ( R t formatRZ R\ t show_if_single_pageRk RP t symbol_firstt symbol_lastt symbol_previoust symbol_nextR[ Rl Rm R1 Rn t result( (
R] RZ R1 R R\ Rl Rk RP R[ Rm s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyt pagerœ s. ž (I(
N( R' R( R) R* R RE t FalseR~ ( ( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyR, Ï s 6z ( R) t __version__t __date__t
__author__t
__copyright__Rt R/ t stringR t ImportErrort webhelpers.string24t webhelpers.htmlR R R R R R* R t objectR R R R, ( ( ( s7 /usr/lib/python2.6/site-packages/webhelpers/paginate.pyt \ s(