Bot API

Neutral bot facade and platform-specific Bot shortcuts.

class peyk.bot.BaleBot(token: str, **kwargs: object)[source]

Bases: Bot[BaleClient]

Bot facade fixed to Bale.

property client: BaleClient

Performs the client operation for the bot client.

Returns:

Result produced by the bot operation.

class peyk.bot.Bot(token: str, *, platform: Literal['bale', 'telegram', 'rubika'], defaults: BotDefaults | None = None, on_unsupported: UnsupportedPolicy = UnsupportedPolicy.DEFAULT, session: Session | None = None, retry_policy: RetryPolicy | None = None, logger: Logger | None = None, base_url: str | None = None)[source]

Bases: Generic[ClientT]

Unified async bot facade over one audited platform client.

Example

bot = Bot("TOKEN", platform="telegram")

@bot.command("start")
async def start(message):
    await bot.send_message(message.chat.id, "Hello")

bot.run()
async answer_callback_query(callback_query_id: str, *, text: str | None = None, show_alert: bool = False) → bool[source]

Answers the callback query request through the bot API.

Parameters:

  • callback_query_id – Identifier of the callback query.

  • text – Text content supplied to the operation.

  • show_alert – Value used by this operation.

Returns:

Result produced by the bot operation.

async ban_chat_member(chat_id: int | str, user_id: int) → bool[source]

Performs the ban chat member operation for the bot client.

Parameters:

  • chat_id – Identifier of the target chat.

  • user_id – Identifier of the target user.

Returns:

Result produced by the bot operation.

callback(data: str, *, prefix: bool = False) → Callable[[Callable[[HandlerP], HandlerR]], Callable[[HandlerP], HandlerR]][source]

Register a callback handler for exact data or a data prefix.

callback_query(*filters: object) → Callable[[Callable[[HandlerP], HandlerR]], Callable[[HandlerP], HandlerR]][source]

Register a callback-query handler on the bot’s plain router.

property client: ClientT

Return the lazily-created raw platform client.

async close() → None[source]

Close the underlying client/session when it has been initialized.

command(*names: str, prefix: str = '/') → Callable[[Callable[[HandlerP], HandlerR]], Callable[[HandlerP], HandlerR]][source]

Register one handler for one or more command names.

Each alias is registered independently so all aliases share the exact original Python callable and its type signature. This delegates to peyk.dispatcher.router.Router.command() on the bot’s router.

async delete_message(chat_id: int | str, message_id: int | str) → bool[source]

Removes message through the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • message_id – Identifier of the target message.

Returns:

Result produced by the bot operation.

async delete_webhook(*, drop_pending_updates: bool | None = None) → bool[source]

Remove the configured webhook when the platform exposes that operation.

async download(file_id: str) → bytes[source]

Download file bytes using the platform-specific file descriptor/URL.

async edit_message_reply_markup(chat_id: int | str, message_id: int | str, **kwargs: object) → Message[source]

Edits message reply markup through the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • message_id – Identifier of the target message.

Returns:

Result produced by the bot operation.

async edit_message_text(chat_id: int | str, message_id: int | str, text: str | 'RichText' | Text, *, parse_mode: ParseMode | str | None = None, **kwargs: object) → Message[source]

Edits message text through the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • message_id – Identifier of the target message.

  • text – Text content supplied to the operation.

  • parse_mode – Value used by this operation.

Returns:

Result produced by the bot operation.

async forward_message(chat_id: int | str, from_chat_id: int | str, message_id: int | str) → Message[source]

Performs the forward message operation for the bot client.

Parameters:

  • chat_id – Identifier of the target chat.

  • from_chat_id – Value used by this operation.

  • message_id – Identifier of the target message.

Returns:

Result produced by the bot operation.

async get_chat(chat_id: int | str) → Chat[source]

Retrieves chat from the bot API.

Parameters:

chat_id – Identifier of the target chat.

Returns:

Result produced by the bot operation.

async get_chat_member(chat_id: int | str, user_id: int) → ChatMember[source]

Retrieves chat member from the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • user_id – Identifier of the target user.

Returns:

Result produced by the bot operation.

async get_file(file_id: str) → File[source]

Return a neutral file descriptor.

async get_webhook_info() → WebhookInfo | WebhookInfo[source]

Return the native webhook-info model where the platform exposes it.

property id: int | str

Return the authenticated bot ID after me() has been fetched.

include_router(router: Router) → Router[source]

Include another router in the bot’s router tree.

async me() → User[source]

Fetch and cache the neutral authenticated bot identity.

message(*filters: object) → Callable[[Callable[[HandlerP], HandlerR]], Callable[[HandlerP], HandlerR]][source]

Register a message handler on the bot’s plain router.

normalize_update(raw: Update | Update | Update | InlineMessage) → Message | CallbackQuery | IncomingChatMemberStatusUpdate | IncomingPreCheckoutQuery | IncomingShippingQuery | IncomingMessageDeleted | IncomingBotMembershipChange | Update | Update | Update[source]

Normalize a raw platform update and bind supported events to this bot.

on_shutdown(callback: Callable[[], Awaitable[None] | None]) → Callable[[], Awaitable[None] | None][source]

Register a shutdown callback using the bare-decorator form.

on_startup(callback: Callable[[], Awaitable[None] | None]) → Callable[[], Awaitable[None] | None][source]

Register a startup callback using the bare-decorator form.

run(**polling_options: object) → None[source]

Run this bot’s router with automatic polling in a blocking call.

async run_async(**polling_options: object) → None[source]

Validate the token, log startup, and run automatic polling asynchronously.

async send_audio(chat_id: int | str, audio: object, *, caption: str | 'RichText' | Text | None = None, parse_mode: ParseMode | str | None = None, **kwargs: object) → Message[source]

Sends audio through the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • audio – Audio input supplied to the operation.

  • caption – Value used by this operation.

  • parse_mode – Value used by this operation.

Returns:

Result produced by the bot operation.

async send_chat_action(chat_id: int | str, action: str) → bool[source]

Sends chat action through the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • action – Value used by this operation.

Returns:

Result produced by the bot operation.

async send_contact(chat_id: int | str, phone_number: str, first_name: str, **kwargs: object) → Message[source]

Sends contact through the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • phone_number – Value used by this operation.

  • first_name – Value used by this operation.

Returns:

Result produced by the bot operation.

async send_document(chat_id: int | str, document: object, *, caption: str | 'RichText' | Text | None = None, parse_mode: ParseMode | str | None = None, **kwargs: object) → Message[source]

Sends document through the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • document – Document input supplied to the operation.

  • caption – Value used by this operation.

  • parse_mode – Value used by this operation.

Returns:

Result produced by the bot operation.

async send_location(chat_id: int | str, latitude: float, longitude: float, **kwargs: object) → Message[source]

Sends location through the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • latitude – Value used by this operation.

  • longitude – Value used by this operation.

Returns:

Result produced by the bot operation.

async send_media_group(chat_id: int | str, media: Sequence[object], **kwargs: object) → list[Message][source]

Send a media group when the active platform advertises album support.

async send_message(chat_id: int | str, text: str | 'RichText' | Text, *, reply_to_message_id: int | str | None = None, reply_markup: object | None = None, parse_mode: ParseMode | str | None = None, **kwargs: object) → Message[source]

Send plain or composable text and resolve formatting for the active platform.

async send_photo(chat_id: int | str, photo: object, *, caption: str | 'RichText' | Text | None = None, parse_mode: ParseMode | str | None = None, **kwargs: object) → Message[source]

Sends photo through the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • photo – Photo input supplied to the operation.

  • caption – Value used by this operation.

  • parse_mode – Value used by this operation.

Returns:

Result produced by the bot operation.

async send_poll(chat_id: int | str, question: str, options: Sequence[str], **kwargs: object) → Message[source]

Sends poll through the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • question – Value used by this operation.

  • options – Value used by this operation.

Returns:

Result produced by the bot operation.

async send_video(chat_id: int | str, video: object, *, caption: str | 'RichText' | Text | None = None, parse_mode: ParseMode | str | None = None, **kwargs: object) → Message[source]

Sends video through the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • video – Video input supplied to the operation.

  • caption – Value used by this operation.

  • parse_mode – Value used by this operation.

Returns:

Result produced by the bot operation.

async send_voice(chat_id: int | str, voice: object, *, caption: str | 'RichText' | Text | None = None, parse_mode: ParseMode | str | None = None, **kwargs: object) → Message[source]

Sends voice through the bot API.

Parameters:

  • chat_id – Identifier of the target chat.

  • voice – Voice input supplied to the operation.

  • caption – Value used by this operation.

  • parse_mode – Value used by this operation.

Returns:

Result produced by the bot operation.

async set_webhook(url: str, *, max_connections: int | None = None, allowed_updates: Sequence[str] | None = None, drop_pending_updates: bool | None = None, secret_token: str | None = None) → bool[source]

Set the platform webhook after checking its audited capabilities.

secret_token is enforceable by Telegram only. Bale and Rubika use the framework-level path secret instead and therefore reject this platform-specific option rather than silently ignoring it.

supports(feature: Feature) → bool[source]

Return whether the audited capability is usable.

async unban_chat_member(chat_id: int | str, user_id: int) → bool[source]

Performs the unban chat member operation for the bot client.

Parameters:

  • chat_id – Identifier of the target chat.

  • user_id – Identifier of the target user.

Returns:

Result produced by the bot operation.

class peyk.bot.BotDefaults(parse_mode: ParseMode | str | None = None, link_preview: bool | None = None, protect_content: bool | None = None, style_fallback: StyleFallback = StyleFallback.NONE)[source]

Bases: object

Defaults applied only when the active capability registry confirms them.

parse_mode: ParseMode | str | None = None
protect_content: bool | None = None
style_fallback: StyleFallback = 'none'
exception peyk.bot.BotNotBoundError[source]

Bases: RuntimeError

Raised when an inbound event action is used without a bound bot.

exception peyk.bot.InvalidTokenError(platform: str, detail: str = '')[source]

Bases: HTTPStatusError

Raised when a platform rejects the configured bot token.

class peyk.bot.RubikaBot(token: str, **kwargs: object)[source]

Bases: Bot[RubikaClient]

Bot facade fixed to Rubika.

property client: RubikaClient

Performs the client operation for the bot client.

Returns:

Result produced by the bot operation.

class peyk.bot.TelegramBot(token: str, **kwargs: object)[source]

Bases: Bot[TelegramClient]

Bot facade fixed to Telegram.

property client: TelegramClient

Performs the client operation for the bot client.

Returns:

Result produced by the bot operation.

class peyk.bot.UnsupportedPolicy(*values)[source]

Bases: str, Enum

How unsupported cosmetic operations are handled.

DEFAULT = 'default'
RAISE = 'raise'
DEGRADE = 'degrade'
STRIP = 'strip'
class peyk.bot.StyleFallback(*values)[source]

Bases: str, Enum

Fallback for button styles on platforms without native color styles.

NONE = 'none'
EMOJI = 'emoji'