Telegrinder

https://telegrinder.readthedocs.io/
Admin
Telegrinder is a fully typed, event-driven Python framework for building Telegram bots with...
Tokens:32,950
Snippets:297
Trust Score:9.6
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Initialize bot for localization example

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/8_text

Initializes a Telegrinder bot with imports for localization nodes (BaseTranslator, I18NConfig, KeySeparator, UserSource) and the Text rule. This is the setup for the localization example that follows.

```python
from telegrinder import API, Telegrinder, Token
from telegrinder.node import BaseTranslator, I18NConfig, KeySeparator, UserSource
from telegrinder.rules import Text

bot = Telegrinder(API(Token.from_env()))

```

--------------------------------

### Minimal handler file example

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/6_dispatch

Shows a minimal handler file that creates a Dispatch instance. This is the pattern for blueprint-style layouts.

```python
# handlers/start.py
from telegrinder import Dispatch

dp = Dispatch(name="start")
```

--------------------------------

### Project directory structure

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/6_dispatch

A minimal starting point for a multi-file bot, separating handlers, keyboards, nodes, and rules into their own directories.

```text
mybot/
  bot.py
  handlers/
    start.py
    admin.py
    payments.py
  keyboards/
    menu.py
  nodes/
    db.py
  rules/
    is_admin.py
```

--------------------------------

### Dispatch checkbox example

Source: https://telegrinder.readthedocs.io/en/latest/tools/checkbox

Recommended usage of Checkbox via the Dispatch shortcut. It sends a message with inline buttons, tracks presses, and returns a dictionary of picked options and the message ID. The example uses the Text rule to trigger on /checkbox and edits the message with the picked items.

```python
from telegrinder import API, Message, Telegrinder, Token, configure_dotenv, setup_logger
from telegrinder.rules import Text

configure_dotenv()
setup_logger()

api = API(token=Token.from_env())
bot = Telegrinder(api)


@bot.on.message(Text("/checkbox"))
async def action(message: Message) -> None:
    picked, message_id = await (
        bot.dispatch.checkbox(
            message.chat_id,
            message="Check your checkbox",
            cancel_text="Cancel",
            max_in_row=2,
        )
        .add_option("apple", "Apple", "Apple 🍏")
        .add_option("banana", "Banana", "Banana 🍌", is_picked=True)
        .add_option("pear", "Pear", "Pear 🍐")
        .wait(message.api)
    )

    await message.edit(
        text="You picked: {}".format(", ".join(key for key, value in picked.items() if value)),
        chat_id=message.chat.id,
        message_id=message_id,
    )


bot.run_forever()
```

--------------------------------

### Set, get, and delete state operations

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/9_states

Shows the three core state operations: set, get, and delete. Use these to store, retrieve, and remove state for a user. The example uses a user_id and a StateEnum value with an optional payload.

```python
await states.set(user_id, StateEnum.BLESSED, {"source": "admin"})
state = await states.get(user_id)
await states.delete(user_id)
```

--------------------------------

### MemoryStateStorage example with StateEnum and handlers

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/9_states

Shows the simplest way to use storage with MemoryStateStorage. Defines a StateEnum, sets states on /curse and /bless commands, and reads the state in a generic handler. Uses states.State() rules to restrict commands based on current state.

```python
import enum

from telegrinder import MemoryStateStorage, Message, StateData
from telegrinder.rules import StateMeta, Text

states = MemoryStateStorage()


class StateEnum(enum.StrEnum):
    CURSED = "cursed"
    BLESSED = "blessed"


@bot.on.message(
    Text("/curse"),
    # /curse is allowed if the user is blessed
    # or if they do not have any state yet.
    states.State(StateEnum.BLESSED) | states.State(StateMeta.NO_STATE),
)
async def curse_handler(message: Message) -> None:
    await states.set(message.from_user.id, StateEnum.CURSED, {})
    await message.answer("You are now cursed.")


@bot.on.message(Text("/bless"), states.State(StateMeta.NO_STATE))
async def bless_handler(message: Message) -> None:
    await states.set(message.from_user.id, StateEnum.BLESSED, {})
    await message.answer("You are now blessed.")


@bot.on.message()
async def any_message_handler(message: Message) -> None:
    state = await states.get(message.from_user.id)
    vibe = state.unwrap_or(StateData("normal", {})).key
    await message.answer(f"You are currently {vibe}.")

```

--------------------------------

### GlobalContext magic methods

Source: https://telegrinder.readthedocs.io/en/latest/tools/global_context

Demonstrates the magic methods __iter__, __contains__, __eq__, and __bool__. The example uses undefined DatabaseSession and WaiterMachine classes.

```python
from telegrinder.tools.global_context import GlobalContext

global_ctx = GlobalContext(db_session=DatabaseSession(...), waiter_machine=WaiterMachine())
ctx_vars = list(ctx1)
assert "db_session" in global_ctx and "http_client" not in global_ctx  # ok
assert global_ctx  # ok, is not empty
other_ctx = GlobalContext()
assert global_ctx == other_ctx  # ok, same

```

--------------------------------

### Run the bot with run_forever

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/1_setting_up

Starts the bot asynchronously to receive updates in a loop. This line must be at the end of the file.

```python
bot.run_forever()

```

--------------------------------

### Send formatted message in handler

Source: https://telegrinder.readthedocs.io/en/latest/tools/formatting

Example handler that responds to the /formatting command with a formatted message using HTML and mention.

```python
@bot.on.message(Text("/formatting"))
async def formatting(message: Message) -> None:
    await message.answer(
        HTML << "Hello, " << mention(message.from_user.first_name, user_id=message.from_user.id),
        parse_mode=HTML.PARSE_MODE,
    )

```

--------------------------------

### Load a dispatch into the main bot

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/6_dispatch

Shows how to load a dispatch from a separate module into the main bot. The code assumes the dispatch from the previous example lives in `handlers/chat_utilities.py`.

```python
from handlers import chat_utilities
from telegrinder import API, Telegrinder, Token

api = API(Token("your-token-here"))
bot = Telegrinder(api)
```

--------------------------------

### Raw HTML string example

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/8_text

A raw HTML string example that illustrates why hand-writing HTML can be annoying: user input may not be escaped, closing tags are easy to miss, and it's harder to see what each piece does.

```python
text = "<b>Hello</b> <i>world</i>"

```

--------------------------------

### Choice waiter with options and selection

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/9_states

Demonstrates using the built-in Choice waiter to let a user pick exactly one option from a set. The example shows adding options with normal and selected text, waiting for the user's reply, and editing the message with the chosen value.

```python
@bot.on.message(Text("/choice"))
async def action(message: Message) -> None:
    chosen, message_id = await (
        bot.dispatch.choice(message.chat.id, message="Choose something", max_in_row=1)
        # First text is the normal option, second text is the selected version.
        .add_option("apple", "Apple 🔴", "Apple 🟢")
        .add_option("banana", "Banana 🔴", "Banana 🟢", is_picked=True)
        .add_option("pear", "Pear 🔴", "Pear 🟢")
        .wait(message.api)
    )

    await message.edit(
        text=f"You chose: {chosen}",
        message_id=message_id,
    )
```

--------------------------------

### Register startup and shutdown hooks

Source: https://telegrinder.readthedocs.io/en/latest/tools/loop_wrapper

Registers startup and shutdown hooks on a standalone LoopWrapper using the lifespan decorators. The hooks run when the wrapper starts and stops.

```python
from telegrinder.tools import LoopWrapper

loop_wrapper = LoopWrapper()


@loop_wrapper.lifespan.on_startup
async def start() -> None:
    await open_db_connection()


@loop_wrapper.lifespan.on_shutdown
async def stop() -> None:
    await close_db_connection()

```

--------------------------------

### Adding options to Checkbox

Source: https://telegrinder.readthedocs.io/en/latest/tools/checkbox

Shows how to add options to a Checkbox scenario. Each option has a key, default text, picked text, and optional is_picked initial state. The example adds cheese and bacon options with is_picked=True for bacon.

```python
checkbox = (
    bot.dispatch.checkbox(chat_id, message="Choose toppings")
    .add_option("cheese", "Cheese", "Cheese ✅")
    .add_option("bacon", "Bacon", "Bacon ✅", is_picked=True)
)
```

--------------------------------

### Set context variable value

Source: https://telegrinder.readthedocs.io/en/latest/tools/global_context

Set context variables using attribute assignment or item assignment. The example assumes a Kitten class is defined elsewhere.

```python
from telegrinder.tools.global_context import GlobalContext

ctx = GlobalContext()
ctx.kitten = Kitten()  # cool!
ctx["items"] = ["Oopa", "Loopa", "Woopa"]  # very nice!

```

--------------------------------

### Import HTML and formatting helpers

Source: https://telegrinder.readthedocs.io/en/latest/tools/formatting

Import the HTML entrypoint and core formatting helpers from telegrinder.tools.formatting.

```python
from telegrinder.tools.formatting import HTML, bold, italic, mention

```

--------------------------------

### Initialize Telegrinder bot with API and Token

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/1_setting_up

Creates the core Telegrinder instance by importing Telegrinder, API, and Token, then instantiating API with a token and passing it to Telegrinder. The token is wrapped in a Token instance for strong typing and security.

```python
from telegrinder import Telegrinder, API, Token

api = API(Token("your-token-here"))
bot = Telegrinder(api)

```

--------------------------------

### IncomingMessageId node and handler

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/5_nodes

Defines a scalar node that extracts the message id and wraps it in a custom MessageId type. The handler uses this node to get the message id and respond with it. This example shows a practical use of nodes to remove duplication.

```python
from nodnod.interface.scalar import scalar_node

from telegrinder import Message

MessageId = type("MessageId", (int,), {})


@scalar_node
class IncomingMessageId:
    @classmethod
    def __compose__(cls, message: Message) -> MessageId:
        # Tiny wrapper types can make code more expressive.
        return MessageId(message.message_id)


@bot.on.message()
async def show_id(message: Message, message_id: IncomingMessageId) -> None:
    await message.answer(f"Your message id is {message_id}")

```

--------------------------------

### Get context variable with type

Source: https://telegrinder.readthedocs.io/en/latest/tools/global_context

Retrieve a context variable with a specified type using get. If the type does not match, an AssertionError is raised. The unwrap() method returns the underlying value.

```python
from telegrinder.tools.global_context import GlobalContext, CtxVar

ctx = GlobalContext(name="Alex", URL=CtxVar("https://google.com", const=True))
URL = ctx.get("URL", int)  # AssertionError: "Context variable value type of 'str' does not correspond to the expected type 'int'."
URL = ctx.get("URL", str).unwrap()  # <GlobalCtxVar(URL=ConstCtxVar(value='https://google.com'))>

```

--------------------------------

### Direct Construction

Source: https://telegrinder.readthedocs.io/en/latest/tools/checkbox

Shows how to directly instantiate a Checkbox scenario and the important detail about the WaiterMachine.

```APIDOC
## Direct Construction

### Description
Instantiates a Checkbox scenario directly without using the dispatch shortcut.

### Example
```python
from telegrinder import Checkbox

checkbox = Checkbox(
    chat_id=message.chat_id,
    message="Pick your options",
    waiter_machine=bot.dispatch.callback_query.waiter_machine,
)
```

### Usage Notes
- After construction, call `.add_option(...)` and `.wait(api)` the same way as with the dispatch shortcut.
- The `Checkbox` requires a `WaiterMachine`. The dispatch shortcut provides the correct one automatically, which is why it is the recommended path.
```

--------------------------------

### Create a regular keyboard with Button and Keyboard

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/7_keyboard

Builds a keyboard with two rows: buttons '1' and '2' on the first row, and '3' on the second row. Use this to create a simple keyboard for a bot.

```python
from telegrinder.tools import Button, Keyboard

keyboard = (
    Keyboard()
    .add(Button("1"))
    .add(Button("2"))
    .row()
    .add(Button("3"))
)

```

--------------------------------

### Initialize API with Token

Source: https://telegrinder.readthedocs.io/en/latest/api

Creates an API instance using a Token object. Required before making any Telegram Bot API requests.

```python
from telegrinder import API, Token
api = API(Token("token"))

```

--------------------------------

### Send a local file with InputFile

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/10_media

Build an InputFile from bytes read from a local file and send it as a photo with a caption. Works when the file already exists on disk or in memory.

```python
import pathlib

from telegrinder import Message
from telegrinder.types import InputFile

cool_bytes = pathlib.Path("examples/assets/satie.jpeg").read_bytes()


@bot.on.message(Text("/photo"))
async def start(message: Message) -> None:
    await message.answer_photo(
        InputFile("satie.jpeg", cool_bytes),
        caption="Erik",
    )

```

--------------------------------

### Direct Checkbox construction with WaiterMachine

Source: https://telegrinder.readthedocs.io/en/latest/tools/checkbox

Directly instantiate a Checkbox scenario without using bot.dispatch.checkbox(...). Requires a WaiterMachine; the dispatch shortcut provides the correct one, so direct construction is only recommended when you need that control. After construction, call .add_option(...) and .wait(api) the same way.

```python
from telegrinder import Checkbox

checkbox = Checkbox(
    chat_id=message.chat_id,
    message="Pick your options",
    waiter_machine=bot.dispatch.callback_query.waiter_machine,
)
```

--------------------------------

### Shutdown the wrapper

Source: https://telegrinder.readthedocs.io/en/latest/tools/loop_wrapper

Stops the wrapper programmatically. The wrapper also installs signal handlers and performs safe cancellation of pending tasks during shutdown.

```python
loop_wrapper.shutdown()

```

--------------------------------

### Using bot.loop_wrapper in a bot

Source: https://telegrinder.readthedocs.io/en/latest/tools/loop_wrapper

Shows the typical way to interact with the wrapper inside a bot: adding tasks, registering startup hooks, and scheduling timers via bot.loop_wrapper.

```python
bot.loop_wrapper.add_task(...)
bot.loop_wrapper.lifespan.on_startup(...)
bot.loop_wrapper.timer(...)

```

--------------------------------

### Initialize API

Source: https://telegrinder.readthedocs.io/en/latest/api

Initializes an API instance with a token, which is required for making Telegram Bot API requests.

```APIDOC
## Initialize API

### Description
Creates an API instance with a token for making Telegram Bot API requests.

### Initialization
```python
from telegrinder import API, Token
api = API(Token("token"))
```
```

--------------------------------

### Create a minimal dispatch with handlers

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/6_dispatch

Creates a local dispatch named "chat-utilities" with two handlers: one for messages from bots and one for the /repeat command with an optional times argument. The dispatch can live in its own file and be plugged into the main bot later.

```python
from telegrinder import Dispatch, Message
from telegrinder.rules import Argument, Command, IsBot

dp = Dispatch(name="chat-utilities")


@dp.message(IsBot())
async def bot_message_handler(message: Message) -> None:
    # A normal handler, just registered in a local dispatch instead of bot.on.
    await message.answer("Hey bot!")


@dp.message(
    Command(
        "repeat",
        Argument("text"),
        Argument("times", validators=[lambda s: int(s) if s.isdigit() else None], optional=True),
    )
)
async def command_handler(message: Message, text: str, times: int = 5) -> None:
    # times will contain the parsed number or the default value.
    await message.answer(", ".join([text] * times))
```

--------------------------------

### Unwrap result and use expect for detailed errors

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/4_api

Shows using .unwrap() to get the message_id directly, and .expect() to raise a custom error message on failure.

```python
message_id = (
    await message.api.send_message(
        chat_id=message.chat_id,
        text="Hi!",
    )
).unwrap().message_id

# Even if we want to break the control flow, it might be much better to directly specify why the error happened (either with custom exception class or just a simple detail information). To transform the raising exception into something more detailed, we use expect

message_id = (
    await message.api.send_message(...)
).expect("Could not send a message").message_id

```

--------------------------------

### Set context variables in __init__

Source: https://telegrinder.readthedocs.io/en/latest/tools/global_context

Initialize a GlobalContext with context variables using keyword arguments. The 'url' variable is a constant CtxVar.

```python
from telegrinder.tools.global_context import GlobalContext, CtxVar

ctx = GlobalContext(name="Alex", url=CtxVar("https://google.com", const=True))

```

--------------------------------

### Import GlobalContext

Source: https://telegrinder.readthedocs.io/en/latest/tools/global_context

Import the GlobalContext class from the telegrinder.tools.global_context module.

```python
from telegrinder.tools.global_context import GlobalContext

```

--------------------------------

### Get context variable value

Source: https://telegrinder.readthedocs.io/en/latest/tools/global_context

Retrieve context variable values using attribute access, item access, or get_value with type checking. Accessing a missing variable raises NameError or UnwrapError.

```python
from telegrinder.tools.global_context import GlobalContext, CtxVar

ctx = GlobalContext(arseny="cool programmer")
ctx.arseny  # 'cool programmer' (unknown type)
ctx["arseny"]  # 'cool programmer' (unknown type)
ctx.get_value("arseny", str).unwrap()  # 'cool programmer' (type 'str')
ctx.lul  # NameError: Name 'lul' is not defined in '<Unnamed global context at 0x7f8d07eb1f80>'.
ctx.get_value("wupi woop").unwrap()  # UnwrapError: Name 'wupi woop' is not defined in '<Unnamed global context at 0x7f8d07eb1f80>'.

```

--------------------------------

### Resolve and download a photo file

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/10_media

Resolve a photo's file_id, get the Telegram file path, and download the bytes to a local directory. Uses a custom ABCRule to detect photos and returns a confirmation string.

```python
import pathlib

from telegrinder import Message
from telegrinder.rules import ABCRule

photos_path = pathlib.Path("photos")
photos_path.mkdir(exist_ok=True)


class HasPhoto(ABCRule):
    async def check(self, message: Message) -> bool:
        return bool(message.photo.unwrap_or_none())


@bot.on.message(HasPhoto())
async def downloader(message: Message) -> str:
    photo_file = (await message.api.get_file(file_id=message.photo.unwrap()[-1].file_id)).unwrap()
    photo_path = photo_file.file_path.unwrap()

    path = photos_path / pathlib.Path(photo_path.split("/")[-1])
    path.write_bytes((await message.api.download_file(photo_path)).unwrap())
    return "Photo downloaded!"

```

--------------------------------

### Bot startup and shutdown hooks

Source: https://telegrinder.readthedocs.io/en/latest/tools/loop_wrapper

Registers startup and shutdown hooks on the bot's loop_wrapper. The startup hook sends a message, the shutdown hook prints a farewell.

```python
@bot.loop_wrapper.lifespan.on_startup
async def hello() -> None:
    await bot.api.send_message(chat_id=SECRET_CHAT_ID, text="Hello!!!")


@bot.loop_wrapper.lifespan.on_shutdown
async def bye() -> None:
    print("Bye!!!")

```

--------------------------------

### Import TelegrinderContext

Source: https://telegrinder.readthedocs.io/en/latest/tools/global_context

Import the built-in type-hinted global context TelegrinderContext.

```python
from telegrinder.tools.global_context import TelegrinderContext

```

--------------------------------

### Use formatting helpers

Source: https://telegrinder.readthedocs.io/en/latest/tools/formatting

Shows usage of several formatting helpers: blockquote, pre_code with language, mention, link, tg_emoji, and code_inline.

```python
from telegrinder.tools.formatting import (
    HTML,
    blockquote,
    bold,
    code_inline,
    link,
    mention,
    pre_code,
    tg_emoji,
)

text = HTML << blockquote("Quoted text")
code = pre_code("print('hello')", lang="python")
user = mention("arseny", user_id=549019276)
repo = link("https://github.com/timoniq/telegrinder", text="telegrinder")
emoji = tg_emoji("👍", emoji_id=5368324170671202286)
inline = code_inline("TOKEN")

```

--------------------------------

### Use .request method

Source: https://telegrinder.readthedocs.io/en/latest/api

Makes a raw request to the 'getMe' method with empty parameters, unwraps the result, and accesses the 'first_name' field.

```python
result = await api.request("getMe", {})
result.unwrap()["first_name"]

```

--------------------------------

### Load a dispatch with bot.on.load

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/6_dispatch

Loads an external dispatch (e.g., chat_utilities.dp) into the bot's main dispatch. This is the standard way to include routers from other files.

```python
bot.on.load(chat_utilities.dp)

bot.run_forever()
```

--------------------------------

### Access API instance from bot or event

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/4_api

Shows how to access the API instance from the bot or the event object.

```python
bot.api
message.api

```

--------------------------------

### Use typed methods

Source: https://telegrinder.readthedocs.io/en/latest/api

Demonstrates using a typed method like get_me that returns a result model or APIError, and how to unwrap and access data.

```APIDOC
## Use typed methods

### Description
All methods are in snake case and return a result of model or APIError. Example shows how to call get_me and access the result.

### Example
```python
user = (await api.get_me()).unwrap()
user.first_name
```
```

--------------------------------

### Create a code block with pre_code

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/8_text

Creates a proper code block using pre_code with a language hint. Gives a real block of code instead of a plain string that happens to contain indentation.

```python
from telegrinder.tools.formatting import pre_code


snippet = pre_code(
    "print('Hello from telegrinder')",
    lang="python",
)

```

--------------------------------

### Compose HTML with helpers

Source: https://telegrinder.readthedocs.io/en/latest/tools/formatting

Build a Telegram-ready HTML string by chaining the HTML object with the << operator and helper functions like mention and bold.

```python
from telegrinder.tools.formatting import HTML, bold, italic, mention

text = HTML << "Hello, " << mention("Arseny", user_id=549019276) << "! " << bold(italic("Welcome"))

```

--------------------------------

### Checkbox Constructor

Source: https://telegrinder.readthedocs.io/en/latest/tools/checkbox

Documentation for the Checkbox constructor, including its parameters and usage notes.

```APIDOC
## Checkbox Constructor

### Description
Creates a new Checkbox scenario instance for collecting multiple options from a user in a Telegram chat.

### Constructor Signature
```python
Checkbox(
    chat_id: int,
    message: str,
    *,
    parse_mode: str | None = None,
    max_in_row: int = 3,
    callback_answer: str | None = None,
    callback_answer_as_alert: bool | None = None,
    ready_text: str = "Ready",
    ready_icon_id: str | int | None = None,
    ready_style: KeyboardButtonStyle | None = None,
    cancel_text: str | None = None,
    cancel_icon_id: str | int | None = None,
    cancel_style: KeyboardButtonStyle | None = None,
    waiter_machine: WaiterMachine | None = None,
)
```

### Parameters
- **chat_id** (int) - Required - The chat identifier where the checkbox will be sent.
- **message** (str) - Required - The text displayed above the checkbox.
- **parse_mode** (str | None) - Optional - Formatting mode for the message text.
- **max_in_row** (int) - Optional - Maximum number of options per row. Defaults to 3.
- **callback_answer** (str | None) - Optional - Text for the callback answer.
- **callback_answer_as_alert** (bool | None) - Optional - Whether the callback answer is shown as an alert.
- **ready_text** (str) - Optional - Text for the submit button. Defaults to "Ready".
- **ready_icon_id** (str | int | None) - Optional - Icon identifier for the ready button.
- **ready_style** (KeyboardButtonStyle | None) - Optional - Style for the ready button.
- **cancel_text** (str | None) - Optional - Text for the cancel button.
- **cancel_icon_id** (str | int | None) - Optional - Icon identifier for the cancel button.
- **cancel_style** (KeyboardButtonStyle | None) - Optional - Style for the cancel button.
- **waiter_machine** (WaiterMachine | None) - Optional - The waiter machine used for waiting for user interaction.

### Usage Notes
- The `message` parameter is used for the text above the checkbox.
- `max_in_row` controls the layout of options.
- `ready_text` customizes the submit button.
- `cancel_text` adds a cancel button.
- `parse_mode` is used if the scenario message uses formatting.
- Checkbox buttons use regular `InlineButton` under the hood, so style-aware buttons are supported through scenario parameters and option styles.
- You can visually distinguish the ready action, cancel action, and individual options via `KeyboardButtonStyle` values.
```

--------------------------------

### Import serializers

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/7_keyboard

Imports the two main serializers: JSONSerializer and MsgPackSerializer.

```python
from telegrinder.tools import JSONSerializer, MsgPackSerializer

```

--------------------------------

### Import ABCGlobalContext

Source: https://telegrinder.readthedocs.io/en/latest/tools/global_context

Import the ABCGlobalContext abstract interface from the telegrinder.tools.global_context module.

```python
from telegrinder.tools.global_context import ABCGlobalContext

```

--------------------------------

### Send a static keyboard with get_markup

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/7_keyboard

Sends a message with the static keyboard attached. The handler triggers on the /eat command.

```python
@bot.on.message(Text("/eat"))
async def eat(message: Message) -> None:
    await message.answer(
        "What do you want to eat?",
        reply_markup=FruitsKeyboard.get_markup(),
    )

```

--------------------------------

### Handler for mini player with state matching

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/9_states

A handler that uses pattern matching on the current state to perform actions. It handles play, pause, and stop commands, returning appropriate messages.

```python
@bot.on.message(Command("play", Argument("song_name", optional=True)))
async def play_song_handler(state: Stopped | Paused | Playing, song_name: str | None = None) -> str:
    match state:
        case Stopped():
            if song_name is None:
                return "You need to provide a song name"

            await state.play(song_name)
            return f"Started {song_name}"

        case Paused():
            await state.play()
            return f"Continuing {state.song}"

        case Playing():
            return "Already playing"
```

--------------------------------

### Define MainMenuKeyboard with inline buttons

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/7_keyboard

Defines a static inline keyboard class with two buttons: 'Show fact' and 'Exit', using PrimaryInlineButton and DangerInlineButton. The 'new_row=True' parameter places the exit button on a new row.

```python
class MainMenuKeyboard(InlineKeyboard):
    show_fact = PrimaryInlineButton("Show fact", callback_data="menu/fact", new_row=True)
    exit = DangerInlineButton("Exit", callback_data="menu/exit")
```

--------------------------------

### Basic error handling with event_error

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/11_handling_errors

Shows how to register a regular handler that raises an exception and an event_error handler that catches it. The error handler receives an Error node with the exception and can reply to the user.

```python
from telegrinder import Message
from telegrinder.node import Error
from telegrinder.rules import IsUser, Text


@bot.on.message(Text("oops"))
async def oops_handler(message: Message) -> None:
    await message.answer("Oh no")
    raise RuntimeError("Wow")


@bot.on.message(Text("woops"))
def woops_handler() -> None:
    raise ValueError("Wow oopsii!")


@bot.on.event_error(IsUser())
async def error_handler(err: Error[RuntimeError, ValueError], message: Message) -> None:
    await message.answer(f"Something went wrong: {err.exception}")

```

--------------------------------

### Handle media groups with MediaGroup node

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/10_media

Handle a media group with the dedicated media_group view and MediaGroup node. Uses Option[Caption] to access an optional caption and returns a summary string.

```python
from kungfu.library.monad.option import Option

from telegrinder.node import Caption, MediaGroup


@bot.on.media_group()
async def handle_media_group(media_group: MediaGroup, caption: Option[Caption]) -> str:
    return (
        f"Received media group with {len(media_group.items)} items\n"
        f"Caption: {caption.unwrap_or('no caption')}"
    )

```

--------------------------------

### Auto-load dispatches from a directory

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/6_dispatch

Loads all dispatches from a directory recursively. Telegrinder imports Python files and looks for global Dispatch instances.

```python
bot.on.load_from_dir("handlers", recursive=True)
```

--------------------------------

### Template formatting with HTML

Source: https://telegrinder.readthedocs.io/en/latest/tools/formatting

Use template-based formatting with Python template strings and format specifiers like bold.

```python
from telegrinder.tools.formatting import HTML

text = HTML(t"Hello, {name:bold}!")

```

--------------------------------

### Import ParseMode constants

Source: https://telegrinder.readthedocs.io/en/latest/tools/formatting

Import ParseMode constants explicitly from telegrinder.tools.parse_mode.

```python
from telegrinder.tools.parse_mode import ParseMode

```

--------------------------------

### Build formatted text with link, spoiler, code_inline, and bold

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/8_text

Builds a formatted text string using HTML helpers: link, spoiler, code_inline, and bold. Shows how to combine multiple helpers with the HTML builder. Easier to read than hand-written HTML strings.

```python
from telegrinder.tools.formatting import HTML, bold, code_inline, link, spoiler


text = (
    HTML
    << "Documentation: "
    << link("https://docs.python.org/3/", text="Python docs")
    << "\n"
    << "Token: "
    << spoiler(code_inline("123:secret-token"))
    << "\n"
    << bold("Do not share this with anyone.")
)

```

--------------------------------

### Handle a regular button press with Text rule

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/7_keyboard

Handles a button press by matching the button text '1' with the Text rule. This is the simplest way to handle regular keyboard buttons.

```python
@bot.on.message(Text("1"))
async def handle_press_button(message: Message) -> None:
    await message.answer("You pressed button 1")

```

--------------------------------

### Basic LoopWrapper usage

Source: https://telegrinder.readthedocs.io/en/latest/tools/loop_wrapper

Creates a standalone LoopWrapper, schedules a coroutine with add_task(), and runs it. This is the basic usage when not using Telegrinder's built-in wrapper.

```python
from telegrinder.tools import LoopWrapper

loop_wrapper = LoopWrapper()


async def main() -> None:
    await open_db_connection()
    await close_db_connection()


loop_wrapper.add_task(main())
loop_wrapper.run()

```

--------------------------------

### Import the Text rule

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/2_rules

Imports the prebuilt Text rule, which accepts a string or a list of strings to match against the message text.

```python
from telegrinder.rules import Text
```

--------------------------------

### Register a message handler with @bot.on.message

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/6_dispatch

Registers a handler for messages matching the Text('/start') rule. This is the typical way to add a command handler.

```python
@bot.on.message(Text("/start"))
async def start(...): ...
```

--------------------------------

### Inline Keyboard with Callback Data

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/7_keyboard

Creates an inline keyboard with three buttons, each having a callback_data payload. Uses .row() to place the third button on a new line.

```python
from telegrinder.tools.keyboard import InlineButton, InlineKeyboard

inline_keyboard = (
    InlineKeyboard()
    .add(InlineButton("1", callback_data="button/1"))
    .add(InlineButton("2", callback_data="button/2"))
    .row()
    .add(InlineButton("3", callback_data="button/3"))
)

```

--------------------------------

### InlineKeyboard.add with InlineButton

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/7_keyboard

Creates an inline keyboard with a button that carries a structured payload model as callback_data.

```APIDOC
## InlineKeyboard.add with InlineButton

### Description
Creates an inline keyboard with a button that carries a structured payload model as callback_data.

### Method
N/A (Object construction)

### Endpoint
N/A

### Parameters
#### Constructor Parameters
- **keyboard** (InlineKeyboard) - Required - The keyboard instance to which the button is added.
- **button** (InlineButton) - Required - The button to add, containing text and callback_data.

### Request Example
```python
import msgspec

from telegrinder.tools.keyboard import InlineButton, InlineKeyboard


class ItemModel(msgspec.Struct):
    item: str
    amount: int
    action: str


keyboard = (
    InlineKeyboard()
    .add(
        InlineButton(
            "Buy doughnut",
            callback_data=ItemModel(item="doughnut", amount=100, action="buy"),
        )
    )
)
```

### Response
#### Success Response (200)
- **keyboard** (InlineKeyboard) - The keyboard with the button added.

#### Response Example
```python
keyboard
```

ERROR HANDLING:
- No explicit error handling is documented.
```

--------------------------------

### Create a Router for admin area

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/6_dispatch

Creates a Router named 'admin' with a handler for /ban, then wraps it in a Dispatch. This isolates admin logic.

```python
from telegrinder import Dispatch, Message, Router
from telegrinder.rules import Text

admin_router = Router(name="admin")


@admin_router.message(Text("/ban"))
async def ban_handler(message: Message) -> None:
    # All admin-related logic can stay inside this router.
    await message.answer("Admin action")


admin = Dispatch(router=admin_router, name="admin-dispatch")
```

--------------------------------

### InlineButton with Callback Data String

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/7_keyboard

Shows the minimal creation of an inline button with a callback_data string, which is then matched by PayloadEqRule.

```python
InlineButton("1", callback_data="button/1")

```

--------------------------------

### Create unnamed GlobalContext

Source: https://telegrinder.readthedocs.io/en/latest/tools/global_context

Create an unnamed GlobalContext and compare it with a named one. The assertion passes because the contexts are different.

```python
from telegrinder.tools.global_context import GlobalContext

ctx = GlobalContext()  # unnamed
assert ctx != GlobalContext("context")

```

--------------------------------

### Styled Keyboard with Success, Primary, Danger Buttons

Source: https://telegrinder.readthedocs.io/en/latest/tutorial/en/7_keyboard

Defines a keyboard class with three styled buttons: SuccessButton for confirmation, PrimaryButton for main action, and DangerButton for cancel/delete/exit. Uses max_in_row=2 to control layout.

```python
from telegrinder import DangerButton, Keyboard, PrimaryButton, SuccessButton


class MenuKeyboard(Keyboard, max_in_row=2):
    PROFILE = SuccessButton("Profile")
    BALANCE = PrimaryButton("Balance")
    EXIT = DangerButton("Exit")

```
Tokens:
Raw