Metadata-Version: 2.4
Name: pagination-aiogram3
Version: 0.1.1
Summary: A comprehensive pagination system for aiogram inline keyboards with type safety and easy configuration
Author-email: NavesSapnis <veih.work@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/NavesSapnis/pagination-aiogram3
Project-URL: Documentation, https://github.com/NavesSapnis/pagination-aiogram3#readme
Project-URL: Repository, https://github.com/NavesSapnis/pagination-aiogram3
Project-URL: Bug Tracker, https://github.com/NavesSapnis/pagination-aiogram3/issues
Keywords: telegram,bot,aiogram,pagination,keyboard
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiogram>=3.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Aiogram Inline Pagination

A comprehensive pagination system for aiogram inline keyboards with type safety and easy configuration.

## Features

- **Pagination System**: Navigate through large sets of data with back/next buttons
- **Type Safety**: Full type annotations for better code quality and IDE support
- **Easy Configuration**: Simple setup with customizable navigation buttons
- **Flexible**: Support for additional keyboards and custom page sizes
- **Automatic Handler Registration**: Built-in callback query handlers for navigation

## Installation

```bash
pip install pagination-aiogram3
```

## Quick Start

```python
from aiogram import Bot, Dispatcher
from aiogram.types import Message, InlineKeyboardButton, InlineKeyboardMarkup
from aiogram_pagination import Paginator, NavigationButtons
import asyncio

bot = Bot(token="YOUR_BOT_TOKEN_HERE")
dp = Dispatcher()

def get_test_keyboard() -> InlineKeyboardMarkup:
    inline_keyboard = []
    for i in range(500):
        inline_keyboard.append([
            InlineKeyboardButton(text=str(i), callback_data=f"kb__{i}"),
            InlineKeyboardButton(text=str(i + 1), callback_data=f"kb__{i + 1}")
        ])
    return InlineKeyboardMarkup(inline_keyboard=inline_keyboard)

# Additional keyboard at the bottom
add_kb = InlineKeyboardMarkup(inline_keyboard=[
    [InlineKeyboardButton(text="Назад", callback_data="back")]
])

# Russian paginator
ru_test_paginator = Paginator(
    dp=dp,
    keyboard=get_test_keyboard(),
    page_size=30,
    nav_buttons=NavigationButtons(
        callback_prefix="call",
        back="Назад",
        next="Дальше"
    ),
    additional_keyboard=add_kb
)

# English paginator
en_test_paginator = Paginator(
    dp=dp,
    keyboard=get_test_keyboard(),
    page_size=30,
    nav_buttons=NavigationButtons(
        callback_prefix="en_call"
    ),
    additional_keyboard=add_kb
)

async def menu_handler(message: Message, bot: Bot):
    if message.from_user.language_code == "ru":
        kb = ru_test_paginator
    else:
        kb = en_test_paginator
    await message.answer(
        text='Choose an option:',
        reply_markup=kb()
    )

async def main() -> None:  
    dp.message.register(menu_handler)
    await dp.start_polling(bot)

if __name__ == "__main__":
    asyncio.run(main())
```

## Configuration

### NavigationButtons

Configure the navigation buttons with the following parameters:

- `callback_prefix` (str): Unique prefix for callback data (required)
- `separator` (str): Separator for callback data (default: ":")
- `back` (str): Text for back button (default: "Back")
- `next` (str): Text for next button (default: "Next")

### Paginator

Configure the paginator with:

- `dp` (Dispatcher): Aiogram dispatcher object
- `keyboard` (InlineKeyboardMarkup): Base keyboard to paginate
- `nav_buttons` (NavigationButtons): Navigation configuration
- `page_size` (int): Items per page (default: 10)
- `additional_keyboard` (InlineKeyboardMarkup): Additional keyboard at the bottom (optional)

## Dependencies

- `aiogram>=3.0` - Telegram Bot API framework
- `pydantic>=2.0` - Data validation and settings management

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

This project is licensed under the MIT License. 
