Pagination

Built-in pagination for inline keyboards with configurable navigation symbols, duplicate hash prevention, and page change detection.

Basic Usage

Paginated keyboard

from pykeyboard import InlineKeyboard

kb = InlineKeyboard()
kb.paginate(
    count_pages=10,
    current_page=3,
    callback_pattern="page_{}",  # {} is replaced with page number
)

# Produces: [« 1] [‹ 2] [· 3 ·] [4 ›] [10 »]
await message.reply("Page 3 of 10", reply_markup=kb)

Parameters

Parameter	Type	Description
`count_pages`	`int`	Total number of pages
`current_page`	`int`	Currently active page (1-indexed)
`callback_pattern`	`str`	Pattern with `{}` placeholder for page number

Custom Symbols

Override the default navigation symbols:

kb = InlineKeyboard()
kb.PAGINATION_SYMBOLS = {
    "first": "⏮ {}",
    "prev": "◀ {}",
    "current": "[{}]",
    "next": "{} ▶",
    "last": "{} ⏭",
}
kb.paginate(count_pages=5, current_page=2, callback_pattern="p:{}")

# Produces: [⏮ 1] [◀ 1] [[2]] [3 ▶] [5 ⏭]

Duplicate Prevention

Pagination uses SHA-256 hashing to detect when the user taps the current page button (no-op). A PaginationUnchangedError is raised when the page hasn't changed, which you can catch to avoid unnecessary edits.

from pykeyboard.errors import PaginationUnchangedError

try:
    kb.paginate(count_pages=5, current_page=3, callback_pattern="p:{}")
except PaginationUnchangedError:
    # User tapped the current page — nothing to update
    pass