Bale API

The Bale adapter provides the typed asynchronous client and Bale-specific request/response models. The generated reference below recursively discovers the restructured types and methods packages.

Client

Bale platform public API.

Shared client methods

Bale and Telegram inherit a small set of proven platform-neutral request methods. They are documented here as part of each platform reference so the complete public client surface is discoverable from either page.

Shared transport-facing mechanics for Telegram-shaped bot clients.

This module contains the shared request/retry/envelope mechanics plus the M1-confirmed A-level public methods migrated in M3 and M5. M1 found that most same-named public methods remain semantically different, so only identical-logic methods are promoted here.

class peyk.platforms._telegram_like.base_client.TelegramLikeClient(token: str, session: Session | None = None, *, retry_policy: RetryPolicy | None = None, logger: object = None, base_url: str | None = None)

Bases: Generic[UserT, WebhookInfoT, FileT, ChatT, ChatMemberT]

Base for Bale/Telegram clients sharing request mechanics.

Only behavior proven identical by the architecture audit belongs here; platform-specific methods remain on their concrete clients.

base_url: str

max_callback_data_bytes: int = 64

user_model: type[_FromDictModel[UserT]]

webhook_info_model: type[_FromDictModel[WebhookInfoT]]

file_model: type[_FromDictModel[FileT]]

chat_model: type[_FromDictModel[ChatT]]

chat_member_parser: Callable[[dict | None], ChatMemberT | None]

chat_member_count_method: str

async close() → None

Close only a transport session created by this client.

Returns:

The operation result (None).

async get_me() → UserT

Return the authenticated bot user using the platform’s user model.

Returns:

The concrete user model configured by the subclass.

async get_webhook_info() → WebhookInfoT

Return webhook status using the platform’s webhook-info model.

Returns:

The concrete webhook-info model configured by the subclass.

async get_file(file_id: str) → FileT

Fetch the platform’s file descriptor for file_id.

Parameters:

file_id – Platform-specific file identifier.

Returns:

The concrete file model configured by the subclass.

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

Removes message through the shared Telegram-like API.

Parameters:

• chat_id – Identifier of the target chat.

• message_id – Identifier of the target message.

Returns:

Result produced by the shared Telegram-like operation.

async unban_chat_member(chat_id: int | str, user_id: int, *, only_if_banned: bool | None = None) → bool

Performs the unban chat member operation for the shared Telegram-like client.

Parameters:

• chat_id – Identifier of the target chat.

• user_id – Identifier of the target user.

• only_if_banned – Value used by this operation.

Returns:

Result produced by the shared Telegram-like operation.

async unpin_all_chat_messages(chat_id: int | str) → bool

Performs the unpin all chat messages operation for the shared Telegram-like client.

Parameters:

chat_id – Identifier of the target chat.

Returns:

Result produced by the shared Telegram-like operation.

async leave_chat(chat_id: int | str) → bool

Performs the leave chat operation for the shared Telegram-like client.

Parameters:

chat_id – Identifier of the target chat.

Returns:

Result produced by the shared Telegram-like operation.

async get_chat(chat_id: int | str) → ChatT

Return chat information using the platform’s chat model.

Parameters:

chat_id – Integer or string identifier accepted by the platform.

Returns:

The concrete chat model configured by the subclass.

async get_chat_member(chat_id: int | str, user_id: int) → ChatMemberT

Return a member record parsed by the concrete platform adapter.

Parameters:

• chat_id – Integer or string chat identifier.

• user_id – User identifier whose membership should be fetched.

Returns:

The concrete chat-member type configured by the subclass.

async set_chat_title(chat_id: int | str, title: str) → bool

Updates chat title through the shared Telegram-like API.

Parameters:

• chat_id – Identifier of the target chat.

• title – Title to apply to the target resource.

Returns:

Result produced by the shared Telegram-like operation.

async delete_chat_photo(chat_id: int | str) → bool

Removes chat photo through the shared Telegram-like API.

Parameters:

chat_id – Identifier of the target chat.

Returns:

Result produced by the shared Telegram-like operation.

classmethod validate_callback_data(data: str) → None

Performs the validate callback data operation for the shared Telegram-like client.

Parameters:

data – Value used by this operation.

Types and methods

peyk.platforms.bale.types	Bale API types, one file per type.
peyk.platforms.bale.methods	Bale client methods, one module per method.

Supporting modules

Bale application-level API errors.

Every Bale response is a JSON envelope with an ok flag. On ok: false, Bale still returns a plain HTTP 200 – the failure is encoded in the JSON body (description + error_code + optional parameters), not in the HTTP status line. That makes it an application-level failure, distinct from peyk.transport’s transport-level errors (HTTPStatusError, NetworkError, TimeoutError_, RateLimitedError), which are raised from transport-level facts only (connection failures, timeouts, non-2xx status codes).

BaleAPIError subclasses peyk.transport.errors.TransportError so it can still be caught alongside transport errors by callers that want a single “something about this Bale call failed” catch-all – but it is deliberately not included in peyk.transport.retry.DEFAULT_RETRYABLE, and BaleClient never passes it through run_with_retry in the first place (see client.py): a run_with_retry-wrapped call to Session.request() already returns successfully (HTTP 200, valid JSON) before BaleClient ever looks at the ok flag, so the retry layer never even sees a BaleAPIError to (correctly) decline to retry.

exception peyk.platforms.bale.errors.BaleAPIError(message: str, *, error_code: int, description: str, parameters: object | None = None)

Bases: TransportError

Raised when a Bale API response has ok: false.

Variables:

• error_code – Bale’s error_code integer from the response body.

• description – Bale’s human-readable description string.

• parameters – The optional parameters object Bale sometimes includes alongside an error (e.g. retry hints for specific error codes). None when absent.