telebot_py.components¶

Reusable UI components: keyboards, menus, pagination, inline queries (US3).

All builders emit the existing telebot_py.types keyboard dataclasses, so the output can be attached directly to outgoing messages.

telebot_py.components.inline_query¶

Inline query result builders (parity with node inline-query.ts).

Python has no inline-result dataclasses yet (answer_inline_query lands in US4), so the builders return plain Bot API JSON dicts ready to hand to the future answer_inline_query method.

class telebot_py.components.inline_query.ArticleResultBuilder(id: str, title: str, *, description: str | None = None, url: str | None = None, hide_url: bool | None = None, thumbnail_url: str | None = None, thumbnail_width: int | None = None, thumbnail_height: int | None = None, reply_markup: InlineKeyboardMarkup | None = None)¶

Bases: object

Builder for article results; call text() to finalize.

Variables:

id – Unique identifier for this result, 1-64 bytes.
title – Title of the result.

text(message_text: str, *, parse_mode: str | None = None, disable_web_page_preview: bool | None = None) → dict[str, Any]¶

Finalize with a text message content.

Parameters:

message_text – Text of the message to be sent, 1-4096 characters.
parse_mode – Mode for parsing entities in the message text.
disable_web_page_preview – Disables link previews for the message.

Returns:

The article result dict ready for answer_inline_query.

class telebot_py.components.inline_query.InlineQueryResultBuilder¶

Bases: object

Static factory building typed inline query result dicts.

Example

>>> results = [
...     InlineQueryResultBuilder.article("1", "Search Google")
...     .text("https://google.com"),
...     InlineQueryResultBuilder.photo(
...         "2", "https://example.com/img.jpg", title="Wallpaper"
...     ),
... ]
>>> await context.bot.answer_inline_query(query_id, results)

static article(id: str, title: str, **options: Any) → ArticleResultBuilder¶

Create an article result builder.

Parameters:

id – Unique identifier for this result, 1-64 bytes.
title – Title of the result.
**options – Article options: description, url, hide_url, thumbnail_url, thumbnail_width, thumbnail_height, reply_markup.

Returns:

A builder; configure the message content via its text().

static audio(id: str, audio_url: str, title: str, **options: Any) → dict[str, Any]¶

Create an audio result.

Parameters:

id – Unique identifier for this result.
audio_url – A valid URL for the audio file.
title – Title of the audio track.
**options – Extra fields: performer, audio_duration, caption, parse_mode, reply_markup.

Returns:

The audio result dict.

static contact(id: str, phone_number: str, first_name: str, **options: Any) → dict[str, Any]¶

Create a contact result.

Parameters:

id – Unique identifier for this result.
phone_number – Contact’s phone number.
first_name – Contact’s first name.
**options – Extra fields: last_name, vcard, thumbnail_url, reply_markup.

Returns:

The contact result dict.

static document(id: str, title: str, document_url: str, mime_type: str, **options: Any) → dict[str, Any]¶

Create a document result.

Parameters:

id – Unique identifier for this result.
title – Title for the result.
document_url – A valid URL for the file.
mime_type – Mime type of the file contents.
**options – Extra fields: caption, parse_mode, description, thumbnail_url, reply_markup.

Returns:

The document result dict.

static game(id: str, game_short_name: str, **options: Any) → dict[str, Any]¶

Create a game result.

Parameters:

id – Unique identifier for this result.
game_short_name – Short name of the game.
**options – Extra fields: reply_markup.

Returns:

The game result dict.

static gif(id: str, gif_url: str, thumbnail_url: str, **options: Any) → dict[str, Any]¶

Create a GIF animation result.

Parameters:

id – Unique identifier for this result.
gif_url – A valid URL for the GIF file.
thumbnail_url – URL of the static (JPEG or GIF) thumbnail.
**options – Extra fields: title, caption, parse_mode, gif_width, gif_height, gif_duration, reply_markup.

Returns:

The GIF result dict.

static location(id: str, latitude: float, longitude: float, title: str, **options: Any) → dict[str, Any]¶

Create a location result.

Parameters:

id – Unique identifier for this result.
latitude – Location latitude in degrees.
longitude – Location longitude in degrees.
title – Location title.
**options – Extra fields: live_period, horizontal_accuracy, heading, proximity_alert_radius, thumbnail_url, reply_markup.

Returns:

The location result dict.

Create a photo result; thumbnail defaults to the photo URL.

Parameters:

id – Unique identifier for this result.
photo_url – A valid URL of the photo (JPEG, <= 5MB).
title – Title for the result.
description – Short description of the result.
caption – Caption of the photo, 0-1024 characters.
parse_mode – Mode for parsing entities in the caption.
show_caption_above_media – Show the caption above the media.
thumbnail_url – URL of the thumbnail; defaults to photo_url.
reply_markup – Inline keyboard attached to the message.

Returns:

The photo result dict.

static venue(id: str, latitude: float, longitude: float, title: str, address: str, **options: Any) → dict[str, Any]¶

Create a venue result.

Parameters:

id – Unique identifier for this result.
latitude – Latitude of the venue in degrees.
longitude – Longitude of the venue in degrees.
title – Title of the venue.
address – Address of the venue.
**options – Extra fields: foursquare_id, foursquare_type, google_place_id, google_place_type, thumbnail_url, reply_markup.

Returns:

The venue result dict.

static video(id: str, video_url: str, mime_type: str, thumbnail_url: str, title: str, **options: Any) → dict[str, Any]¶

Create a video result.

Parameters:

id – Unique identifier for this result.
video_url – URL for the embedded video player or video file.
mime_type – Mime type of the video URL (‘text/html’ or ‘video/mp4’).
thumbnail_url – URL of the thumbnail (JPEG or GIF).
title – Title for the result.
**options – Extra fields: caption, parse_mode, video_width, video_height, video_duration, description, reply_markup.

Returns:

The video result dict.

telebot_py.components.keyboard.inline¶

Fluent builder for inline keyboards (parity with node keyboard/inline.ts).

Produces the framework’s telebot_py.types.InlineKeyboardMarkup / telebot_py.types.InlineKeyboardButton types directly; no component specific button classes exist in Python (the node classes duplicate the wire types, which telebot_py.types already provides).

class telebot_py.components.keyboard.inline.InlineKeyboard¶

Bases: object

Fluent builder for creating inline keyboards.

Example

>>> keyboard = (
...     InlineKeyboard()
...     .text("Option 1", "opt_1")
...     .text("Option 2", "opt_2")
...     .row()
...     .url("Website", "https://example.com")
... )
>>> await bot.send_message(chat_id, "Choose:", reply_markup=keyboard.build())

build() → InlineKeyboardMarkup¶

Build the final markup, dropping empty rows.

Returns:: The constructed InlineKeyboardMarkup.

copy_text(text: str, copy_text: str) → InlineKeyboard¶

Append a copy-to-clipboard button to the current row.

Parameters:

text – Label text on the button.
copy_text – Text copied to the clipboard when pressed.

Returns:

This builder, for chaining.

row() → InlineKeyboard¶

Advance the builder to start a new keyboard row.

A no-op when the current row is already empty (node parity).

Returns:: This builder, for chaining.

switch_inline_query(text: str, query: str = '') → InlineKeyboard¶

Append an inline-query button to the current row.

Parameters:

text – Label text on the button.
query – Inline query inserted in the chat input field.

Returns:

This builder, for chaining.

switch_inline_query_current_chat(text: str, query: str = '') → InlineKeyboard¶

Append an inline-query button targeting the current chat.

Parameters:

text – Label text on the button.
query – Inline query inserted in the current chat.

Returns:

This builder, for chaining.

text(text: str, callback_data: str) → InlineKeyboard¶

Append a callback button to the current row.

Parameters:

text – Label text on the button.
callback_data – Data sent in a callback query when pressed.

Returns:

This builder, for chaining.

url(text: str, url: str) → InlineKeyboard¶

Append an HTTP or tg:// URL button to the current row.

Parameters:

text – Label text on the button.
url – URL opened when the button is pressed.

Returns:

This builder, for chaining.

web_app(text: str, url: str) → InlineKeyboard¶

Append a Web App button to the current row.

Parameters:

text – Label text on the button.
url – HTTPS URL of the Web App to open.

Returns:

This builder, for chaining.

telebot_py.components.keyboard.reply¶

Fluent builder for reply keyboards (parity with node keyboard/reply.ts).

Bases: object

Fluent builder for creating reply keyboards.

Example

>>> keyboard = (
...     ReplyKeyboard(resize_keyboard=True)
...     .text("Option A")
...     .text("Option B")
...     .row()
...     .request_location("Share Location")
... )
>>> await bot.send_message(chat_id, "Choose:", reply_markup=keyboard.build())

build() → ReplyKeyboardMarkup¶

Build the final markup, dropping empty rows.

Returns:: The constructed ReplyKeyboardMarkup with the configured options.

request_chat(text: str, request_id: int, *, chat_is_channel: bool, chat_is_forum: bool | None = None, chat_has_username: bool | None = None, chat_is_created: bool | None = None, bot_is_member: bool | None = None, request_title: bool | None = None, request_username: bool | None = None, request_photo: bool | None = None) → ReplyKeyboard¶

Append a button prompting the user to select a chat.

Parameters:

text – Button label text.
request_id – Signed 32-bit identifier of the request.
chat_is_channel – True to request a channel chat, False for a group or supergroup chat.
chat_is_forum – True to request a forum supergroup.
chat_has_username – True to request a chat with a username.
chat_is_created – True to request a chat owned by the user.
bot_is_member – True to request a chat with the bot as a member.
request_title – Request the chat’s title.
request_username – Request the chat’s username.
request_photo – Request the chat’s photo.

Returns:

This builder, for chaining.

request_contact(text: str) → ReplyKeyboard¶

Append a button prompting the user to share their contact.

Parameters:: text – Button label text.
Returns:: This builder, for chaining.

request_location(text: str) → ReplyKeyboard¶

Append a button prompting the user to share their location.

Parameters:: text – Button label text.
Returns:: This builder, for chaining.

request_poll(text: str, *, type: str | None = None) → ReplyKeyboard¶

Append a button prompting the user to create a poll.

Parameters:

text – Button label text.
type – Optional poll type restriction (‘quiz’ or ‘regular’).

Returns:

This builder, for chaining.

Append a button prompting the user to select one or more users.

Parameters:

text – Button label text.
request_id – Signed 32-bit identifier of the request.
user_is_bot – Pass True to request bots, False for regular users.
user_is_premium – Pass True to request premium users.
max_quantity – Maximum number of users selectable; 1-10.
request_name – Request the users’ first and last name.
request_username – Request the users’ username.
request_photo – Request the users’ photo.

Returns:

This builder, for chaining.

row() → ReplyKeyboard¶

Advance the builder to start a new keyboard row.

A no-op when the current row is already empty (node parity).

Returns:: This builder, for chaining.

text(text: str) → ReplyKeyboard¶

Append a plain text button to the current row.

Parameters:: text – Text sent to the bot as a message when pressed.
Returns:: This builder, for chaining.

web_app(text: str, url: str) → ReplyKeyboard¶

Append a button launching a Telegram Mini App.

Parameters:

text – Button label text.
url – HTTPS URL of the Web App.

Returns:

This builder, for chaining.

telebot_py.components.menu.menu¶

Interactive nested inline menu builder (parity with node menu/menu.ts).

Callback routing uses the node scheme so buttons are wire-compatible: m:{menu}:b:{row}:{col} (text), m:{menu}:s:{target}:{row}:{col} (submenu), m:{menu}:k:{row}:{col} (back). The dispatch middleware from the node version lands with the kernel integration pass; this module covers the builder/render/lookup surface.

class telebot_py.components.menu.menu.Menu(id: str)¶

Bases: object

A nested inline menu with dynamic navigation and callback routing.

Example

>>> settings = Menu("settings").back("Go back")
>>> main = (
...     Menu("main")
...     .text("Click me", on_click)
...     .row()
...     .submenu("Settings", settings)
... )
>>> await bot.send_message(chat_id, "Menu:", reply_markup=main.build())

Variables:

id – Unique string identifier for this menu.
parent – The parent menu when this instance is a submenu.

back(label: MenuLabel = 'Back', on_navigate: MenuNavigationHandler | None = None) → Menu¶

Append a back button returning to the parent menu.

Parameters:

label – Button label; defaults to ‘Back’.
on_navigate – Optional hook executed before navigating back.

Returns:

This menu, for chaining.

Example

>>> submenu.back("Go back")

build(ctx: CallbackContext | None = None) → InlineKeyboardMarkup¶

Synchronously build this menu’s inline keyboard markup.

Parameters:: ctx – Optional context for dynamic label resolution.
Returns:: The constructed InlineKeyboardMarkup.

Example

>>> await bot.send_message(chat_id, "Choose:", reply_markup=menu.build(ctx))

find_menu(menu_id: str, visited: set[Menu] | None = None) → Menu | None¶

Find a menu by identifier anywhere in this menu’s hierarchy.

Parameters:

menu_id – Identifier of the menu to locate.
visited – Internal cycle guard; omit on the first call.

Returns:

The matching menu, or None when not found.

async render(ctx: CallbackContext | None = None) → InlineKeyboardMarkup¶

Asynchronously build the markup, awaiting async label resolvers.

Parameters:: ctx – Optional context for dynamic label resolution.
Returns:: The constructed InlineKeyboardMarkup.

row() → Menu¶

Advance to a new button row; no-op if the current row is empty.

Returns:: This menu, for chaining.

submenu(label: MenuLabel, target_menu: Menu, on_navigate: MenuNavigationHandler | None = None) → Menu¶

Append a navigation button leading to a child menu.

Parameters:

label – Static label or (possibly async) resolver.
target_menu – The destination submenu to open.
on_navigate – Optional hook executed before switching menus.

Returns:

This menu, for chaining.

Example

>>> menu.submenu("Preferences", preferences_menu)

text(label: MenuLabel, handler: MenuButtonHandler) → Menu¶

Append an interactive callback button to the current row.

Parameters:

label – Static label or (possibly async) resolver.
handler – Callback executed when the button is clicked.

Returns:

This menu, for chaining.

Example

>>> menu.text("Click me", on_click)

url(label: MenuLabel, url: str) → Menu¶

Append an external URL button to the current row.

Parameters:

label – Static label or (possibly async) resolver.
url – HTTP or tg:// URL opened when the button is clicked.

Returns:

This menu, for chaining.

telebot_py.components.menu.renderer¶

Menu keyboard rendering engine (parity with node menu/renderer.ts).

telebot_py.components.menu.renderer.build_menu_keyboard(menu_id: str, rows: list[list[MenuButtonItem]], ctx: CallbackContext | None = None) → InlineKeyboardMarkup¶

Synchronously build a menu’s inline keyboard markup.

Parameters:

menu_id – Identifier embedded in each button’s callback data.
rows – The menu’s button grid.
ctx – Optional context for dynamic label resolution.

Returns:

The constructed InlineKeyboardMarkup (empty rows dropped).

async telebot_py.components.menu.renderer.render_menu_keyboard(menu_id: str, rows: list[list[MenuButtonItem]], ctx: CallbackContext | None = None) → InlineKeyboardMarkup¶

Asynchronously build a menu’s markup, awaiting async labels.

Parameters:

menu_id – Identifier embedded in each button’s callback data.
rows – The menu’s button grid.
ctx – Optional context for dynamic label resolution.

Returns:

The constructed InlineKeyboardMarkup (empty rows dropped).

telebot_py.components.menu.types¶

Menu button item model and label/handler type aliases (parity with node).

class telebot_py.components.menu.types.BackButton(label: MenuLabel, on_navigate: MenuNavigationHandler | None = None)¶

Bases: object

Navigation button returning to the parent menu.

Variables:

label (MenuLabel) – Static or dynamic button label.
on_navigate (MenuNavigationHandler | None) – Optional hook executed before navigating back.

label: MenuLabel¶

on_navigate: MenuNavigationHandler | None¶

class telebot_py.components.menu.types.SubmenuButton(label: MenuLabel, target_menu: Menu, on_navigate: MenuNavigationHandler | None = None)¶

Bases: object

Navigation button leading to a child menu.

Variables:

label (MenuLabel) – Static or dynamic button label.
target_menu (Menu) – Destination submenu to open.
on_navigate (MenuNavigationHandler | None) – Optional hook executed before switching menus.

label: MenuLabel¶

on_navigate: MenuNavigationHandler | None¶

target_menu: Menu¶

class telebot_py.components.menu.types.TextButton(label: MenuLabel, handler: MenuButtonHandler)¶

Bases: object

Interactive callback button with a click handler.

Variables:

label (MenuLabel) – Static or dynamic button label.
handler (MenuButtonHandler) – Callback executed when the button is clicked.

handler: MenuButtonHandler¶

label: MenuLabel¶

class telebot_py.components.menu.types.UrlButton(label: MenuLabel, url: str)¶

Bases: object

External URL button.

Variables:

label (MenuLabel) – Static or dynamic button label.
url (str) – HTTP or tg:// URL opened when clicked.

label: MenuLabel¶

url: str¶

telebot_py.components.pagination¶

Paginated inline keyboard builder (parity with node pagination.ts).

class telebot_py.components.pagination.PaginationKeyboard(*, items: Sequence[T], page: int = 1, page_size: int = 5, item_button: Callable[[T, int], InlineKeyboardButton], callback_data: Callable[[Literal['prev', 'next', 'noop'], int], str] | None = None, navigation: Mapping[str, Any] | None = None)¶

Bases: Generic[T]

Fluent builder for paginated inline keyboard menus.

Example

>>> keyboard = PaginationKeyboard(
...     items=products,
...     page=1,
...     page_size=3,
...     item_button=lambda item, index: InlineKeyboardButton(
...         text=item, callback_data=f"buy:{item}"
...     ),
... )
>>> await bot.send_message(chat_id, "Catalog:", reply_markup=keyboard.build())

Variables:

total_pages – Number of pages after chunking items by page size.
current_page – The active page, clamped into 1..total_pages.

build() → InlineKeyboardMarkup¶

Build the markup with item buttons and the navigation row.

Returns:: The constructed InlineKeyboardMarkup; the navigation row is only present when there is more than one page.

property current_page: int¶: The active page clamped between 1 and total_pages.

property total_pages: int¶: Number of pages; at least one even for an empty item list.

class telebot_py.components.pagination.PaginationNavigation¶

Bases: TypedDict

Customization of pagination control labels and formatting.

Variables:

prev (str | collections.abc.Callable[[int, int], str]) – Label of the previous-page button; static or a formatter (current_page, total_pages) -> label. Defaults to ‘Previous’.
next (str | collections.abc.Callable[[int, int], str]) – Label of the next-page button, same shapes. Defaults to ‘Next’.
page_indicator (str | collections.abc.Callable[[int, int], str]) – Label of the middle indicator button. Defaults to "{current} / {total}".
disabled (str) – Placeholder shown for a disabled navigation button. Defaults to ‘-‘.
hide_disabled (bool) – Hide disabled navigation buttons entirely instead of the placeholder. Defaults to False.

disabled: str¶

hide_disabled: bool¶

next: str | Callable[[int, int], str]¶

page_indicator: str | Callable[[int, int], str]¶

prev: str | Callable[[int, int], str]¶

telebot_py.components¶

telebot_py.components.inline_query¶

telebot_py.components.keyboard.inline¶

telebot_py.components.keyboard.reply¶

telebot_py.components.menu.menu¶

telebot_py.components.menu.renderer¶

telebot_py.components.menu.types¶

telebot-py

Navigation

Related Topics