telebot-py 1.5.0__py3-none-any.whl

telebot_py/__init__.py

@@ -0,0 +1,55 @@
+"""telebot_py — async-first Telegram Bot framework for Python.
+
+Mirrors python-telegram-bot's public API in native snake_case. See
+``specs/004-python-framework/contracts/public-api.md`` for the stable public
+surface.
+"""
+
+from telebot_py import filters
+from telebot_py.bot.errors import (
+    ApplicationError,
+    InvalidTokenError,
+    NetworkError,
+    TelebotError,
+    TelegramApiError,
+)
+from telebot_py.kernel import (
+    Application,
+    ApplicationBuilder,
+    ApplicationState,
+    CallbackContext,
+)
+from telebot_py.routing import (
+    AsyncConversationHandler,
+    ConversationHandler,
+    LinearConversationHandler,
+)
+from telebot_py.routing.handlers import (
+    BaseHandler,
+    CallbackQueryHandler,
+    CommandHandler,
+    MessageHandler,
+)
+
+__version__ = "1.5.0"
+
+__all__ = [
+    "Application",
+    "ApplicationBuilder",
+    "ApplicationError",
+    "ApplicationState",
+    "AsyncConversationHandler",
+    "BaseHandler",
+    "CallbackContext",
+    "CallbackQueryHandler",
+    "CommandHandler",
+    "ConversationHandler",
+    "InvalidTokenError",
+    "LinearConversationHandler",
+    "MessageHandler",
+    "NetworkError",
+    "TelegramApiError",
+    "TelebotError",
+    "__version__",
+    "filters",
+]

telebot_py/bot/__init__.py

@@ -0,0 +1,61 @@
+"""Bot API client: HTTP core, retry policy, typed errors, and method mixins."""
+
+from telebot_py.bot.base import MarkupLike, Requester, SupportsToDict
+from telebot_py.bot.bulk import BulkMixin
+from telebot_py.bot.chat_management import ChatManagementMixin
+from telebot_py.bot.chats import ChatsMixin
+from telebot_py.bot.client import Bot
+from telebot_py.bot.edits import EditsMixin
+from telebot_py.bot.errors import (
+    ApplicationError,
+    InvalidTokenError,
+    NetworkError,
+    TelebotError,
+    TelegramApiError,
+)
+from telebot_py.bot.files import FilesMixin
+from telebot_py.bot.games import GamesMixin
+from telebot_py.bot.inline import InlineMixin
+from telebot_py.bot.invite_links import InviteLinksMixin
+from telebot_py.bot.media import MediaMixin
+from telebot_py.bot.members import MembersMixin
+from telebot_py.bot.messages import MessagesMixin
+from telebot_py.bot.payments import PaymentsMixin
+from telebot_py.bot.profile import ProfileMixin
+from telebot_py.bot.reactions import ReactionsMixin
+from telebot_py.bot.retry import RetryPolicy
+from telebot_py.bot.stickers import StickersMixin
+from telebot_py.bot.stories_gifts import StoriesGiftsMixin
+from telebot_py.bot.topics import TopicsMixin
+from telebot_py.bot.webhook import WebhookMixin
+
+__all__ = [
+    "ApplicationError",
+    "Bot",
+    "BulkMixin",
+    "ChatManagementMixin",
+    "ChatsMixin",
+    "EditsMixin",
+    "FilesMixin",
+    "GamesMixin",
+    "InlineMixin",
+    "InvalidTokenError",
+    "InviteLinksMixin",
+    "MarkupLike",
+    "MediaMixin",
+    "MembersMixin",
+    "MessagesMixin",
+    "NetworkError",
+    "PaymentsMixin",
+    "ProfileMixin",
+    "ReactionsMixin",
+    "Requester",
+    "RetryPolicy",
+    "StoriesGiftsMixin",
+    "StickersMixin",
+    "SupportsToDict",
+    "TelegramApiError",
+    "TelebotError",
+    "TopicsMixin",
+    "WebhookMixin",
+]

telebot_py/bot/base.py

@@ -0,0 +1,108 @@
+"""Shared seam and helpers for the Bot method mixins."""
+
+from __future__ import annotations
+
+import abc
+import typing as t
+
+from telebot_py.types.base import TelegramObject, TypeParseError
+from telebot_py.types.message import Message
+
+TObj = t.TypeVar("TObj", bound=TelegramObject)
+
+
+class SupportsToDict(t.Protocol):
+    """Any typed object serializable to Telegram's wire shape."""
+
+    def to_dict(self) -> dict[str, object]:
+        """Serialize this object to a plain snake_case dict."""
+        ...
+
+
+#: Markup-shaped parameters accept plain dicts or typed objects with ``to_dict``.
+MarkupLike = t.Mapping[str, object] | SupportsToDict
+
+
+class Requester(abc.ABC):
+    """Abstract request seam every Bot method mixin builds on."""
+
+    @abc.abstractmethod
+    async def request(
+        self,
+        method: str,
+        payload: t.Mapping[str, object] | None = None,
+    ) -> object:
+        """Call a Bot API method and return the unwrapped ``result``.
+
+        Args:
+            method: The Bot API method name (e.g. ``sendMessage``).
+            payload: Method parameters keyed by Telegram field names.
+
+        Returns:
+            The ``result`` field of Telegram's response envelope.
+        """
+
+
+def to_wire(value: MarkupLike | None) -> dict[str, object] | None:
+    """Serialize a markup-shaped parameter for the wire, ``None`` passing through."""
+    if value is None:
+        return None
+    if isinstance(value, t.Mapping):
+        return dict(value)
+    return value.to_dict()
+
+
+def clean_payload(**fields: object) -> dict[str, object]:
+    """Build a wire payload, omitting parameters the caller left unset."""
+    return {name: value for name, value in fields.items() if value is not None}
+
+
+def parse_result(cls: type[TObj], result: object) -> TObj:
+    """Hydrate a single JSON object result into a typed Telegram object."""
+    if isinstance(result, t.Mapping):
+        return cls.from_dict(t.cast("t.Mapping[str, object]", result))
+    msg = f"expected JSON object for {cls.__name__}, got {type(result).__name__}"
+    raise TypeParseError(msg)
+
+
+def parse_list_result(cls: type[TObj], result: object) -> list[TObj]:
+    """Hydrate a JSON array result into a list of typed Telegram objects."""
+    if isinstance(result, list):
+        return [
+            cls.from_dict(t.cast("t.Mapping[str, object]", item))
+            for item in result
+            if isinstance(item, t.Mapping)
+        ]
+    msg = f"expected JSON array of {cls.__name__}, got {type(result).__name__}"
+    raise TypeParseError(msg)
+
+
+def parse_flag(result: object) -> bool:
+    """Coerce a boolean Bot API result, rejecting unexpected shapes."""
+    if isinstance(result, bool):
+        return result
+    msg = f"expected boolean result, got {type(result).__name__}"
+    raise TypeParseError(msg)
+
+
+def parse_count(result: object) -> int:
+    """Coerce an integer Bot API result, rejecting unexpected shapes."""
+    if isinstance(result, int) and not isinstance(result, bool):
+        return result
+    msg = f"expected integer result, got {type(result).__name__}"
+    raise TypeParseError(msg)
+
+
+def parse_string(result: object) -> str:
+    """Coerce a string Bot API result, rejecting unexpected shapes."""
+    if isinstance(result, str):
+        return result
+    msg = f"expected string result, got {type(result).__name__}"
+    raise TypeParseError(msg)
+
+
+def parse_message_or_true(result: object) -> Message | bool:
+    """Coerce edit-method results: the edited Message, or True for inline edits."""
+    if isinstance(result, bool):
+        return result
+    return parse_result(Message, result)

telebot_py/bot/bulk.py

@@ -0,0 +1,140 @@
+"""Bulk message Bot API methods (parity with packages/go/pkg/bot/bulk.go)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from telebot_py.bot.base import Requester, clean_payload, parse_flag, parse_list_result
+from telebot_py.types.common import MessageId
+
+
+class BulkMixin(Requester):
+    """Bot methods for forwarding, copying, and deleting many messages at once."""
+
+    async def forward_messages(
+        self,
+        chat_id: int | str,
+        from_chat_id: int | str,
+        message_ids: Sequence[int],
+        *,
+        business_connection_id: str | None = None,
+        message_thread_id: int | None = None,
+        disable_notification: bool | None = None,
+        protect_content: bool | None = None,
+    ) -> list[MessageId]:
+        """Forward multiple messages of any kind to a target chat.
+
+        Example:
+            >>> ids = await bot.forward_messages(123, "@source", [11, 12])
+
+        Args:
+            chat_id: Unique identifier for the target chat or username of the
+                target channel.
+            from_chat_id: Unique identifier of the source chat or username of
+                the source channel.
+            message_ids: Identifiers of the messages to forward, 1-100.
+            business_connection_id: Business connection on whose behalf to act.
+            message_thread_id: Target message thread identifier.
+            disable_notification: Send silently.
+            protect_content: Protect the forwarded content from saving.
+
+        Returns:
+            The MessageId list of the forwarded messages.
+
+        Raises:
+            InvalidTokenError: If Telegram rejects the token (HTTP 401).
+            TelegramApiError: If Telegram responds not-ok or retries exhaust.
+            NetworkError: If the transport keeps failing after retries.
+        """
+        payload = clean_payload(
+            chat_id=chat_id,
+            from_chat_id=from_chat_id,
+            message_ids=list(message_ids),
+            business_connection_id=business_connection_id,
+            message_thread_id=message_thread_id,
+            disable_notification=disable_notification,
+            protect_content=protect_content,
+        )
+        return parse_list_result(MessageId, await self.request("forwardMessages", payload))
+
+    async def copy_messages(
+        self,
+        chat_id: int | str,
+        from_chat_id: int | str,
+        message_ids: Sequence[int],
+        *,
+        business_connection_id: str | None = None,
+        message_thread_id: int | None = None,
+        disable_notification: bool | None = None,
+        protect_content: bool | None = None,
+        remove_caption: bool | None = None,
+    ) -> list[MessageId]:
+        """Copy multiple messages without linking to the originals.
+
+        Example:
+            >>> ids = await bot.copy_messages("@target", 456, [1, 2])
+
+        Args:
+            chat_id: Unique identifier for the target chat or username of the
+                target channel.
+            from_chat_id: Unique identifier of the source chat or username of
+                the source channel.
+            message_ids: Identifiers of the messages to copy, 1-100.
+            business_connection_id: Business connection on whose behalf to act.
+            message_thread_id: Target message thread identifier.
+            disable_notification: Send silently.
+            protect_content: Protect the copied content from saving.
+            remove_caption: Pass True to copy messages without their captions.
+
+        Returns:
+            The MessageId list of the copied messages.
+
+        Raises:
+            InvalidTokenError: If Telegram rejects the token (HTTP 401).
+            TelegramApiError: If Telegram responds not-ok or retries exhaust.
+            NetworkError: If the transport keeps failing after retries.
+        """
+        payload = clean_payload(
+            chat_id=chat_id,
+            from_chat_id=from_chat_id,
+            message_ids=list(message_ids),
+            business_connection_id=business_connection_id,
+            message_thread_id=message_thread_id,
+            disable_notification=disable_notification,
+            protect_content=protect_content,
+            remove_caption=remove_caption,
+        )
+        return parse_list_result(MessageId, await self.request("copyMessages", payload))
+
+    async def delete_messages(
+        self,
+        chat_id: int | str,
+        message_ids: Sequence[int],
+        *,
+        business_connection_id: str | None = None,
+    ) -> bool:
+        """Delete multiple messages from a chat at once.
+
+        Example:
+            >>> ok = await bot.delete_messages(789, [5, 6])
+
+        Args:
+            chat_id: Unique identifier for the target chat or username of the
+                target channel.
+            message_ids: Identifiers of the messages to delete, 1-100.
+            business_connection_id: Business connection on whose behalf to act.
+
+        Returns:
+            True on success.
+
+        Raises:
+            InvalidTokenError: If Telegram rejects the token (HTTP 401).
+            TelegramApiError: If Telegram responds not-ok or retries exhaust.
+            NetworkError: If the transport keeps failing after retries.
+        """
+        payload = clean_payload(
+            chat_id=chat_id,
+            message_ids=list(message_ids),
+            business_connection_id=business_connection_id,
+        )
+        return parse_flag(await self.request("deleteMessages", payload))