{"library":"paginate","title":"Paginate","description":"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.","status":"active","version":"0.5.7","language":"en","source_language":"en","source_url":"https://github.com/Signum/paginate","tags":["pagination","web","utility","data-handling","lists"],"install":[{"cmd":"pip install paginate","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The library transitioned from `webhelpers.paginate` to a standalone `paginate` module in version 0.5.x.","wrong":"from webhelpers.paginate import Page","symbol":"Page","correct":"from paginate import Page"}],"quickstart":{"code":"from paginate import Page\n\n# A list of items to paginate\nall_items = list(range(1, 101)) # 100 items\n\n# Simulate current page number (e.g., from a URL query parameter)\ncurrent_page_number = 3\nitems_per_page = 10\n\n# Define a URL maker function for pagination links\ndef my_url_maker(page_num):\n    return f\"/items?page={page_num}\"\n\n# Create a Page object\npage = Page(\n    all_items,\n    page=current_page_number,\n    items_per_page=items_per_page,\n    url_maker=my_url_maker\n)\n\n# Access items for the current page\nprint(f\"Items on page {page.page}: {page.items}\")\n# Expected output for page 3 (items_per_page=10): [21, 22, ..., 30]\n\n# Get page information\nprint(f\"Total items: {page.item_count}\")\nprint(f\"Total pages: {page.page_count}\")\nprint(f\"Has previous page: {page.previous_page is not None}\")\nprint(f\"Has next page: {page.next_page is not None}\")\n\n# Generate a simple pager string (HTML representation)\n# For full customization, use page.link_map() with your templating engine.\npager_html = page.pager(\n    link_attr={'class':'pager_link'},\n    curpage_attr={'class':'pager_curpage'},\n    dotdot_attr={'class':'pager_dotdot'}\n)\nprint(\"\\nGenerated Pager (HTML, example output depends on page numbers):\\n\")\nprint(pager_html)\n\n# Example of using link_map for custom rendering\nprint(\"\\nLink Map for custom rendering (partial output):\")\nlink_info = page.link_map()\nfor k, v in list(link_info.items())[:3]: # Show first 3 for brevity\n    print(f\"  {k}: {v}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Migrate to the standalone `paginate` module. For SQLAlchemy integration, install and use `paginate_sqlalchemy`. Refactor code that relied on `presliced_list`.","message":"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.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Replace all instances of `page_nr` or `current_page` with `page` when initializing or accessing the `Page` object.","message":"The parameters `page_nr` and `current_page` have been deprecated and removed. Always use `page` for the current page number.","severity":"breaking","affected_versions":">=0.5.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Account for 1-based indexing when calculating offsets or mapping page numbers to 0-indexed data structures.","message":"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).","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}