paginate

library0.5.7pypypi✓ verified 25d ago

Paginate is a Python module that helps divide large lists of items into pages for easier browsing. It's a standalone library, previously maintained as `webhelpers.paginate`, and aims to be framework-agnostic. The current version is 0.5.7, last updated in August 2024, indicating active maintenance for its core functionality.

web-framework

pip install paginate

github ↗package ↗

INSTALL

IMPORT

SIG · PAGINATE

paginate

web-frameworkpythonv0.5.7

Install

1.5s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.7 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Page

✓ from paginate import Page

✗ from webhelpers.paginate import Page

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

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}")

Debug

Known issues

breakingVersion 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`.

affects: >=0.5.0

breakingThe 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.

affects: >=0.5.0

breakingAutomatic 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.

affects: >=0.5.0

gotchaPage 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.

affects: All

gotchaUnless 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.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'paginate'

The 'paginate' library is not installed in your current Python environment, or the environment is not correctly activated.

fix

Ensure the 'paginate' library is installed using pip: `pip install paginate`

AttributeError: 'list' object has no attribute 'paginate'

The 'paginate' library does not extend Python's built-in list type with a '.paginate()' method. Instead, you create a 'Page' object by passing your iterable (like a list) to the 'Page' constructor.

fix

Correctly instantiate a Page object: `from paginate import Page; my_list = [1, 2, 3, ...]; current_page = 1; items_per_page = 10; paginator = Page(my_list, page=current_page, items_per_page=items_per_page)`

TypeError: 'Page' object is not iterable

You are attempting to directly iterate over a 'Page' object. To access the actual items on the current page, you need to access its 'items' attribute.

fix

Iterate over the 'items' attribute of the Page object: `from paginate import Page; my_list = [1, 2, 3, ...]; paginator = Page(my_list, page=1, items_per_page=10); for item in paginator.items: print(item)`

ModuleNotFoundError: No module named 'webhelpers.paginate'

The 'webhelpers.paginate' module is a Python 2 package and has been superseded by the standalone 'paginate' library for Python 3. Your code is attempting to import the old, deprecated module.

fix

Install the 'paginate' library (`pip install paginate`) and update your import statements from `from webhelpers.paginate import Page` to `from paginate import Page`. You may also need to adjust other API calls as the standalone 'paginate' library has a slightly different interface.

Upgrade

Version history

0.5.7latest on PyPI · released Aug 25, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/Signum/paginate ↗

packagehttps://pypi.org/project/paginate/ ↗