Paginate

Warnings

• breaking Version 0.5.x (standalone `paginate`) is not directly compatible with older `webhelpers.paginate` usage. Specifically, `SQLAlchemyObject` and `SQLAlchemyQuery` collections are no longer automatically detected; use `paginate_sqlalchemy` for SQLAlchemy queries. The `presliced_list` parameter is also no longer supported.
  Fix: Migrate to the standalone `paginate` module. For SQLAlchemy integration, install and use `paginate_sqlalchemy`. Refactor code that relied on `presliced_list`.
• breaking The parameters `page_nr` and `current_page` have been deprecated and removed. Always use `page` for the current page number.
  Fix: Replace all instances of `page_nr` or `current_page` with `page` when initializing or accessing the `Page` object.
• breaking Automatic URL generation is removed. You must provide a `url_maker` callable to the `Page` constructor or a `url` argument containing a `$page` placeholder to `Page.pager()`. The generated URL is not quote-escaped. Furthermore, `Page.pager()` no longer automatically adds CSS classes; you need to pass `link_attr`, `curpage_attr`, and `dotdot_attr` explicitly.
  Fix: Implement a `url_maker` function and pass it to the `Page` constructor, or explicitly pass a `url` string with `$page` placeholder to `pager()`. Apply CSS classes via `link_attr`, `curpage_attr`, `dotdot_attr` parameters to `pager()` or use `link_map()` for custom rendering in templates.
• gotcha Page numbers and item indexing in `paginate` are 1-based, not 0-based. If integrating with 0-indexed systems or performing direct array access, remember to adjust indices (e.g., subtract 1).
  Fix: Account for 1-based indexing when calculating offsets or mapping page numbers to 0-indexed data structures.
• gotcha Unless an `item_count` is explicitly passed to the `Page` constructor, the `paginate` library will perform a count operation on the collection every time a `Page` instance is created. For very large collections or inefficient counting mechanisms, this can lead to performance issues.
  Fix: For performance-critical applications or large datasets, pre-calculate the total item count and pass it as the `item_count` parameter to the `Page` constructor.

Install

• pip install paginate Install stable version

Imports

• Page

  from paginate import Page

  The library transitioned from `webhelpers.paginate` to a standalone `paginate` module in version 0.5.x.

Quickstart

This quickstart demonstrates how to paginate a simple list using the `Page` class. It shows how to initialize `Page` with a collection, current page, and items per page, and how to define a `url_maker` function. It then accesses the items for the current page and generates basic pagination links.

from paginate import Page

# A list of items to paginate
all_items = list(range(1, 101)) # 100 items

# Simulate current page number (e.g., from a URL query parameter)
current_page_number = 3
items_per_page = 10

# Define a URL maker function for pagination links
def my_url_maker(page_num):
    return f"/items?page={page_num}"

# Create a Page object
page = Page(
    all_items,
    page=current_page_number,
    items_per_page=items_per_page,
    url_maker=my_url_maker
)

# Access items for the current page
print(f"Items on page {page.page}: {page.items}")
# Expected output for page 3 (items_per_page=10): [21, 22, ..., 30]

# Get page information
print(f"Total items: {page.item_count}")
print(f"Total pages: {page.page_count}")
print(f"Has previous page: {page.previous_page is not None}")
print(f"Has next page: {page.next_page is not None}")

# Generate a simple pager string (HTML representation)
# For full customization, use page.link_map() with your templating engine.
pager_html = page.pager(
    link_attr={'class':'pager_link'},
    curpage_attr={'class':'pager_curpage'},
    dotdot_attr={'class':'pager_dotdot'}
)
print("\nGenerated Pager (HTML, example output depends on page numbers):\n")
print(pager_html)

# Example of using link_map for custom rendering
print("\nLink Map for custom rendering (partial output):")
link_info = page.link_map()
for k, v in list(link_info.items())[:3]: # Show first 3 for brevity
    print(f"  {k}: {v}")