Metadata-Version: 2.4
Name: aio-kb
Version: 0.1.1
Summary: Simple keyboard helpers for aiogram 3.x
Author: MikioNatsu
License: MIT
Keywords: aiogram,telegram,bot,keyboard,reply-keyboard,inline-keyboard
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: aiogram>=3.0.0

# aio-kb

Simple and flexible keyboard helpers for **aiogram 3.x**.

`aio-kb` helps you create Telegram bot keyboards faster and cleaner.

---

## Features

- Reply keyboards
- Inline keyboards
- URL buttons
- Callback buttons
- Web App buttons
- Copy text buttons
- Login URL buttons
- Contact request button
- Location request button
- Pagination keyboard
- Back / Close buttons
- Yes / No buttons
- Custom button texts
- Simple builder helpers

---

## Installation

```bash
pip install aio-kb
```

---

## Requirements

```txt
Python >= 3.10
aiogram >= 3.0.0
```

---

## Quick Start

```python
from aio_kb import reply_kb, inline_kb, Btn

menu = reply_kb([
    ["Start", "Help"],
    ["About"]
])

inline = inline_kb([
    [Btn("Website", url="https://example.com")],
    [Btn("Click", callback="click")]
])
```

---

## Reply Keyboard

```python
from aio_kb import reply_kb

keyboard = reply_kb([
    ["Menu", "Help"],
    ["About"]
])
```

Use it in a handler:

```python
await message.answer("Choose an option:", reply_markup=keyboard)
```

---

## Inline Keyboard

```python
from aio_kb import inline_kb, Btn

keyboard = inline_kb([
    [Btn("Open website", url="https://example.com")],
    [Btn("Profile", callback="profile")]
])
```

Use it in a handler:

```python
await message.answer("Inline menu:", reply_markup=keyboard)
```

---

## URL Button

```python
from aio_kb import inline_buttons, url_btn

keyboard = inline_buttons(
    url_btn("GitHub", "https://github.com")
)
```

---

## Callback Button

```python
from aio_kb import inline_buttons, cb_btn

keyboard = inline_buttons(
    cb_btn("Open menu", "menu:open")
)
```

Callback handler:

```python
from aiogram import F
from aiogram.types import CallbackQuery

@router.callback_query(F.data == "menu:open")
async def open_menu(call: CallbackQuery):
    await call.answer("Menu opened")
```

---

## Web App Button

```python
from aio_kb import inline_buttons, webapp_btn

keyboard = inline_buttons(
    webapp_btn("Open Web App", "https://example.com/app")
)
```

---

## Copy Text Button

```python
from aio_kb import inline_buttons, copy_btn

keyboard = inline_buttons(
    copy_btn("Copy code", "ABC-123")
)
```

---

## Contact Button

```python
from aio_kb import contact_kb

keyboard = contact_kb()
```

Custom text:

```python
keyboard = contact_kb("📞 Send phone number")
```

---

## Location Button

```python
from aio_kb import location_kb

keyboard = location_kb()
```

Custom text:

```python
keyboard = location_kb("📍 Send location")
```

---

## Back / Close Buttons

```python
from aio_kb import back_kb, close_kb, back_close_kb

back = back_kb()
close = close_kb()
both = back_close_kb()
```

Custom text:

```python
keyboard = back_close_kb(
    back_text="⬅️ Back",
    close_text="❌ Close"
)
```

---

## Yes / No Keyboard

```python
from aio_kb import yes_no_kb

keyboard = yes_no_kb()
```

Custom callbacks and texts:

```python
keyboard = yes_no_kb(
    yes_callback="confirm:yes",
    no_callback="confirm:no",
    yes_text="✅ Yes",
    no_text="❌ No"
)
```

---

## Pagination

```python
from aio_kb import pager

keyboard = pager(
    page=1,
    total_pages=5
)
```

Custom prefix:

```python
keyboard = pager(
    page=2,
    total_pages=10,
    prefix="products"
)
```

Example callback values:

```txt
products:1
products:2
products:home
products:current
```

---

## Custom Language

Default texts are English, but you can use any language.

```python
from aio_kb import yes_no_kb, back_close_kb

confirm = yes_no_kb(
    yes_text="✅ Ha",
    no_text="❌ Yo‘q"
)

navigation = back_close_kb(
    back_text="⬅️ Orqaga",
    close_text="❌ Yopish"
)
```

---

## Full Bot Example

```python
import asyncio
from os import getenv

from aiogram import Bot, Dispatcher, Router, F
from aiogram.filters import Command
from aiogram.types import Message, CallbackQuery
from dotenv import load_dotenv

from aio_kb import reply_kb, inline_kb, Btn, yes_no_kb

load_dotenv()

BOT_TOKEN = getenv("BOT_TOKEN")

router = Router()


@router.message(Command("start"))
async def start(message: Message):
    keyboard = reply_kb([
        ["Help", "About"],
        ["Settings"]
    ])

    await message.answer(
        "Hello! Choose menu:",
        reply_markup=keyboard
    )


@router.message(F.text == "Help")
async def help_handler(message: Message):
    keyboard = inline_kb([
        [Btn("Open website", url="https://example.com")],
        [Btn("Show profile", callback="profile:show")],
        [Btn("Confirm", callback="confirm")]
    ])

    await message.answer(
        "Help menu:",
        reply_markup=keyboard
    )


@router.callback_query(F.data == "profile:show")
async def show_profile(call: CallbackQuery):
    await call.message.answer("This is your profile.")
    await call.answer()


@router.callback_query(F.data == "confirm")
async def confirm_handler(call: CallbackQuery):
    await call.message.answer(
        "Are you sure?",
        reply_markup=yes_no_kb(
            yes_callback="confirm:yes",
            no_callback="confirm:no"
        )
    )
    await call.answer()


@router.callback_query(F.data == "confirm:yes")
async def confirm_yes(call: CallbackQuery):
    await call.message.answer("Confirmed!")
    await call.answer()


@router.callback_query(F.data == "confirm:no")
async def confirm_no(call: CallbackQuery):
    await call.message.answer("Cancelled!")
    await call.answer()


async def main():
    bot = Bot(token=BOT_TOKEN)
    dp = Dispatcher()
    dp.include_router(router)

    await dp.start_polling(bot)


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

---

## Available Imports

```python
from aio_kb import (
    Btn,

    reply_kb,
    reply_keyboard,
    rk,
    reply_buttons,
    contact_kb,
    location_kb,

    inline_kb,
    inline_keyboard,
    ikb,
    inline_buttons,

    url_btn,
    cb_btn,
    webapp_btn,
    switch_btn,
    switch_current_btn,
    copy_btn,
    login_btn,

    reply_builder,
    inline_builder,

    pager,

    back_kb,
    close_kb,
    back_close_kb,
    yes_no_kb,
    social_kb,
)
```

---

## License

MIT License

---

## Author

Created by Natsu.
