bot-framework 0.1.3__py3-none-any.whl

bot_framework/telegram/services/__init__.py

@@ -0,0 +1,29 @@
+from .callback_answerer import CallbackAnswerer
+from .callback_handler_registry import CallbackHandlerRegistry
+from .close_callback_handler import CloseCallbackHandler
+from .ensure_user_exists import EnsureUserExists
+from .markdown_escaper import MarkdownEscaper
+from .markdown_to_html_converter import MarkdownToHtmlConverter
+from .message_handler_registry import MessageHandlerRegistry
+from .next_step_handler_registrar import NextStepHandlerRegistrar
+from .telegram_message_core import TelegramMessageCore
+from .telegram_message_deleter import TelegramMessageDeleter
+from .telegram_message_replacer import TelegramMessageReplacer
+from .telegram_message_sender import TelegramMessageSender
+from .telegram_notify_replacer import TelegramNotifyReplacer
+
+__all__ = [
+    "CallbackAnswerer",
+    "CallbackHandlerRegistry",
+    "CloseCallbackHandler",
+    "EnsureUserExists",
+    "MarkdownEscaper",
+    "MarkdownToHtmlConverter",
+    "MessageHandlerRegistry",
+    "NextStepHandlerRegistrar",
+    "TelegramMessageCore",
+    "TelegramMessageDeleter",
+    "TelegramMessageReplacer",
+    "TelegramMessageSender",
+    "TelegramNotifyReplacer",
+]

bot_framework/telegram/services/callback_answerer.py

@@ -0,0 +1,16 @@
+from telebot import TeleBot
+
+
+class CallbackAnswerer:
+    def __init__(self, bot: TeleBot):
+        self.bot = bot
+
+    def answer(
+        self,
+        callback_query_id: str,
+        text: str | None = None,
+        show_alert: bool = False,
+    ) -> None:
+        self.bot.answer_callback_query(
+            callback_query_id, text=text, show_alert=show_alert  # pyright: ignore[reportArgumentType]
+        )

bot_framework/telegram/services/callback_handler_registry.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from telebot import TeleBot
+from telebot.types import CallbackQuery
+
+from bot_framework.entities.bot_callback import BotCallback
+from bot_framework.protocols.i_callback_handler import ICallbackHandler
+
+
+class CallbackHandlerRegistry:
+    def __init__(self, bot: TeleBot):
+        self.bot = bot
+
+    def register(self, handler: ICallbackHandler) -> None:
+        def wrapper(call: CallbackQuery) -> None:
+            bot_callback = self._to_bot_callback(call)
+            handler.handle(bot_callback)
+
+        self.bot.register_callback_query_handler(
+            wrapper,
+            func=lambda call: call.data and call.data.startswith(handler.prefix),
+        )
+
+    def _to_bot_callback(self, call: CallbackQuery) -> BotCallback:
+        if not call.from_user:
+            raise ValueError("call.from_user is required but was None")
+
+        message_id: int | None = None
+        message_chat_id: int | None = None
+        if call.message:
+            message_id = call.message.message_id
+            message_chat_id = call.message.chat.id
+
+        bot_callback = BotCallback(
+            id=str(call.id),
+            user_id=call.from_user.id,
+            data=call.data,
+            message_id=message_id,
+            message_chat_id=message_chat_id,
+            user_language_code=call.from_user.language_code,
+        )
+        bot_callback.set_original(call)
+        return bot_callback

bot_framework/telegram/services/close_callback_handler.py

@@ -0,0 +1,25 @@
+from bot_framework.entities.bot_callback import BotCallback
+from bot_framework.telegram.protocols import ICallbackAnswerer, IMessageDeleter
+
+
+class CloseCallbackHandler:
+    def __init__(
+        self,
+        callback_answerer: ICallbackAnswerer,
+        message_deleter: IMessageDeleter,
+    ) -> None:
+        self.callback_answerer = callback_answerer
+        self.message_deleter = message_deleter
+        self.allowed_roles: set[str] | None = None
+        self.prefix = "close:"
+
+    def handle(self, callback: BotCallback) -> None:
+        if not callback.message_id or not callback.message_chat_id:
+            self.callback_answerer.answer(callback.id)
+            return
+
+        self.message_deleter.delete(
+            chat_id=callback.message_chat_id,
+            message_id=callback.message_id,
+        )
+        self.callback_answerer.answer(callback.id)

bot_framework/telegram/services/ensure_user_exists.py

@@ -0,0 +1,37 @@
+from bot_framework.entities import RoleName, User
+from bot_framework.entities.bot_user import BotUser
+from bot_framework.protocols import IEnsureUserExists
+from bot_framework.role_management.repos.protocols.i_role_repo import IRoleRepo
+from bot_framework.role_management.repos.protocols.i_user_repo import IUserRepo
+
+
+class EnsureUserExists(IEnsureUserExists):
+    def __init__(
+        self,
+        user_repo: IUserRepo,
+        role_repo: IRoleRepo,
+    ) -> None:
+        self.user_repo = user_repo
+        self.role_repo = role_repo
+
+    def execute(
+        self,
+        user: BotUser,
+    ) -> None:
+        existing_user = self.user_repo.find_by_id(id=user.id)
+
+        if not existing_user:
+            new_user = User(
+                id=user.id,
+                username=user.username,
+                first_name=user.first_name,
+                last_name=user.last_name,
+                language_code=user.language_code or "en",
+                is_bot=user.is_bot,
+                is_premium=user.is_premium,
+            )
+            self.user_repo.create(entity=new_user)
+            self.role_repo.assign_role_by_name(
+                user_id=user.id,
+                role_name=RoleName.USER,
+            )

bot_framework/telegram/services/markdown_escaper.py

@@ -0,0 +1,8 @@
+import re
+
+from bot_framework.telegram.protocols.i_markdown_escaper import IMarkdownEscaper
+
+
+class MarkdownEscaper(IMarkdownEscaper):
+    def escape(self, text: str) -> str:
+        return re.sub(r"([_*\[\]()~`>#+=|{}.!-])", r"\\\1", text)

bot_framework/telegram/services/markdown_to_html_converter.py

@@ -0,0 +1,16 @@
+import html
+import re
+
+from bot_framework.telegram.protocols import IMarkdownToHtmlConverter
+
+
+class MarkdownToHtmlConverter(IMarkdownToHtmlConverter):
+    def convert(self, text: str) -> str:
+        result = html.escape(text)
+        result = re.sub(r'\*\*(.+?)\*\*', r'<b>\1</b>', result)
+        result = re.sub(r'__(.+?)__', r'<u>\1</u>', result)
+        result = re.sub(r'\*(.+?)\*', r'<i>\1</i>', result)
+        result = re.sub(r'_(.+?)_', r'<i>\1</i>', result)
+        result = re.sub(r'~~(.+?)~~', r'<s>\1</s>', result)
+        result = re.sub(r'`(.+?)`', r'<code>\1</code>', result)
+        return result

bot_framework/telegram/services/message_handler_registry.py

@@ -0,0 +1,49 @@
+from collections.abc import Callable
+
+from telebot import TeleBot
+from telebot.types import Message
+
+from bot_framework.entities.bot_message import BotMessage, BotMessageUser
+from bot_framework.protocols.i_message_handler import IMessageHandler
+
+
+class MessageHandlerRegistry:
+    def __init__(self, bot: TeleBot):
+        self.bot = bot
+
+    def register(
+        self,
+        handler: IMessageHandler,
+        commands: list[str] | None = None,
+        content_types: list[str] | None = None,
+        func: Callable[[Message], bool] | None = None,
+    ) -> None:
+        def wrapper(message: Message) -> bool | None:
+            bot_message = self._to_bot_message(message)
+            return handler.handle(bot_message)
+
+        self.bot.register_message_handler(
+            callback=wrapper,
+            commands=commands,
+            content_types=content_types,
+            func=func,
+        )
+
+    def _to_bot_message(self, message: Message) -> BotMessage:
+        if not message.from_user:
+            raise ValueError("message.from_user is required but was None")
+
+        from_user = BotMessageUser(
+            id=message.from_user.id,
+            language_code=message.from_user.language_code,
+        )
+
+        bot_message = BotMessage(
+            chat_id=message.chat.id,
+            message_id=message.message_id,
+            user_id=message.from_user.id,
+            text=message.text,
+            from_user=from_user,
+        )
+        bot_message.set_original(message)
+        return bot_message

bot_framework/telegram/services/next_step_handler_registrar.py

@@ -0,0 +1,43 @@
+from telebot import TeleBot
+from telebot.types import Message
+
+from bot_framework.entities.bot_message import BotMessage, BotMessageUser
+from bot_framework.protocols.i_message_handler import IMessageHandler
+
+
+class NextStepHandlerRegistrar:
+    def __init__(self, bot: TeleBot):
+        self.bot = bot
+
+    def register(
+        self,
+        message: BotMessage,
+        handler: IMessageHandler,
+    ) -> None:
+        def wrapper(msg: Message) -> bool | None:
+            bot_msg = self._to_bot_message(msg)
+            return handler.handle(bot_msg)
+
+        self.bot.register_next_step_handler(
+            message.get_original(),
+            wrapper,
+        )
+
+    def _to_bot_message(self, message: Message) -> BotMessage:
+        if not message.from_user:
+            raise ValueError("message.from_user is required but was None")
+
+        from_user = BotMessageUser(
+            id=message.from_user.id,
+            language_code=message.from_user.language_code,
+        )
+
+        bot_message = BotMessage(
+            chat_id=message.chat.id,
+            message_id=message.message_id,
+            user_id=message.from_user.id,
+            text=message.text,
+            from_user=from_user,
+        )
+        bot_message.set_original(message)
+        return bot_message

bot_framework/telegram/services/telegram_message_core.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from telebot import TeleBot
+from telebot.types import (
+    InlineKeyboardButton,
+    InlineKeyboardMarkup,
+)
+
+from bot_framework.entities.bot_message import BotMessage
+from bot_framework.entities.keyboard import Keyboard
+from bot_framework.flow_management import IFlowMessageStorage
+
+from .markdown_escaper import MarkdownEscaper
+from .markdown_to_html_converter import MarkdownToHtmlConverter
+
+
+class TelegramMessageCore:
+    def __init__(
+        self,
+        bot: TeleBot,
+        flow_message_storage: IFlowMessageStorage | None = None,
+    ) -> None:
+        self.bot = bot
+        self.flow_message_storage = flow_message_storage
+        self._markdown_escaper = MarkdownEscaper()
+        self._markdown_to_html_converter = MarkdownToHtmlConverter()
+
+    def register_message(
+        self,
+        chat_id: int,
+        message_id: int,
+        flow_name: str | None,
+    ) -> None:
+        if flow_name and self.flow_message_storage:
+            self.flow_message_storage.add_message(
+                telegram_id=chat_id,
+                flow_name=flow_name,
+                message_id=message_id,
+            )
+
+    def create_bot_message(self, chat_id: int, msg: object) -> BotMessage:
+        bot_message = BotMessage(chat_id=chat_id, message_id=msg.message_id)  # type: ignore[attr-defined]
+        bot_message.set_original(msg)
+        return bot_message
+
+    def convert_keyboard(self, keyboard: Keyboard) -> InlineKeyboardMarkup:
+        markup = InlineKeyboardMarkup()
+        for row in keyboard.rows:
+            buttons = [
+                InlineKeyboardButton(
+                    text=button.text, callback_data=button.callback_data
+                )
+                for button in row
+            ]
+            markup.row(*buttons)
+        return markup
+
+    def escape_markdown(self, text: str) -> str:
+        return self._markdown_escaper.escape(text)
+
+    def convert_markdown_to_html(self, text: str) -> str:
+        return self._markdown_to_html_converter.convert(text)

bot_framework/telegram/services/telegram_message_deleter.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from logging import getLogger
+
+from telebot import TeleBot
+
+from bot_framework.protocols.i_message_deleter import IMessageDeleter
+
+
+class TelegramMessageDeleter(IMessageDeleter):
+    def __init__(self, bot: TeleBot) -> None:
+        self._bot = bot
+        self._logger = getLogger(__name__)
+
+    def delete(self, chat_id: int, message_id: int) -> None:
+        try:
+            self._bot.delete_message(chat_id=chat_id, message_id=message_id)
+        except Exception as er:
+            self._logger.warning("Failed to delete message", exc_info=er)

bot_framework/telegram/services/telegram_message_replacer.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from logging import getLogger
+
+from bot_framework.entities.bot_message import BotMessage
+from bot_framework.entities.keyboard import Keyboard
+from bot_framework.entities.parse_mode import ParseMode
+from bot_framework.protocols.i_message_replacer import IMessageReplacer
+
+from .telegram_message_core import TelegramMessageCore
+
+
+class TelegramMessageReplacer(IMessageReplacer):
+    def __init__(self, core: TelegramMessageCore) -> None:
+        self._core = core
+        self._logger = getLogger(__name__)
+
+    def replace(
+        self,
+        chat_id: int,
+        message_id: int,
+        text: str,
+        parse_mode: ParseMode = ParseMode.HTML,
+        keyboard: Keyboard | None = None,
+        flow_name: str | None = None,
+    ) -> BotMessage:
+        reply_markup = self._core.convert_keyboard(keyboard) if keyboard else None
+        text_to_send = text
+        if parse_mode == ParseMode.MARKDOWN:
+            text_to_send = self._core.escape_markdown(text)
+        try:
+            msg = self._core.bot.edit_message_text(
+                chat_id=chat_id,
+                message_id=message_id,
+                text=text_to_send,
+                parse_mode=parse_mode.value,
+                reply_markup=reply_markup,
+            )
+            self._core.register_message(chat_id, message_id, flow_name)
+            return self._core.create_bot_message(chat_id, msg)
+        except Exception as er:
+            if "message is not modified" in str(er):
+                self._logger.debug("Message content unchanged, skipping edit")
+                bot_message = BotMessage(chat_id=chat_id, message_id=message_id)
+                return bot_message
+            self._logger.error("Failed to replace message", exc_info=er)
+            raise

bot_framework/telegram/services/telegram_message_sender.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from logging import getLogger
+
+from bot_framework.entities.bot_message import BotMessage
+from bot_framework.entities.keyboard import Keyboard
+from bot_framework.entities.parse_mode import ParseMode
+from bot_framework.protocols.i_message_sender import IMessageSender
+
+from .telegram_message_core import TelegramMessageCore
+
+
+class TelegramMessageSender(IMessageSender):
+    def __init__(self, core: TelegramMessageCore) -> None:
+        self._core = core
+        self._logger = getLogger(__name__)
+
+    def send(
+        self,
+        chat_id: int,
+        text: str,
+        parse_mode: ParseMode = ParseMode.HTML,
+        keyboard: Keyboard | None = None,
+        flow_name: str | None = None,
+    ) -> BotMessage:
+        reply_markup = self._core.convert_keyboard(keyboard) if keyboard else None
+        text_to_send = text
+        if parse_mode == ParseMode.MARKDOWN:
+            text_to_send = self._core.escape_markdown(text)
+        try:
+            msg = self._core.bot.send_message(
+                chat_id=chat_id,
+                text=text_to_send,
+                parse_mode=parse_mode.value,
+                reply_markup=reply_markup,
+            )
+            self._core.register_message(chat_id, msg.message_id, flow_name)
+            return self._core.create_bot_message(chat_id, msg)
+        except Exception as er:
+            self._logger.error("Failed to send message", exc_info=er)
+            msg = self._core.bot.send_message(
+                chat_id=chat_id,
+                text=text,
+                reply_markup=reply_markup,
+            )
+            self._core.register_message(chat_id, msg.message_id, flow_name)
+            return self._core.create_bot_message(chat_id, msg)
+
+    def send_markdown_as_html(
+        self,
+        chat_id: int,
+        text: str,
+        keyboard: Keyboard | None = None,
+        flow_name: str | None = None,
+    ) -> BotMessage:
+        html_text = self._core.convert_markdown_to_html(text)
+        return self.send(chat_id, html_text, ParseMode.HTML, keyboard, flow_name)
+
+    def send_document(
+        self,
+        chat_id: int,
+        document: bytes,
+        filename: str,
+    ) -> BotMessage:
+        from io import BytesIO
+
+        file_obj = BytesIO(document)
+        file_obj.name = filename
+        msg = self._core.bot.send_document(
+            chat_id=chat_id,
+            document=file_obj,
+        )
+        return self._core.create_bot_message(chat_id, msg)

bot_framework/telegram/services/telegram_notify_replacer.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from bot_framework.entities.bot_message import BotMessage
+from bot_framework.entities.keyboard import Keyboard
+from bot_framework.entities.parse_mode import ParseMode
+from bot_framework.protocols.i_message_deleter import IMessageDeleter
+from bot_framework.protocols.i_message_sender import IMessageSender
+from bot_framework.protocols.i_notify_replacer import INotifyReplacer
+
+
+class TelegramNotifyReplacer(INotifyReplacer):
+    def __init__(
+        self,
+        sender: IMessageSender,
+        deleter: IMessageDeleter,
+    ) -> None:
+        self._sender = sender
+        self._deleter = deleter
+
+    def notify_replace(
+        self,
+        chat_id: int,
+        message_id: int,
+        text: str,
+        parse_mode: ParseMode = ParseMode.HTML,
+        keyboard: Keyboard | None = None,
+        flow_name: str | None = None,
+    ) -> BotMessage:
+        self._deleter.delete(chat_id=chat_id, message_id=message_id)
+        return self._sender.send(chat_id, text, parse_mode, keyboard, flow_name)

bot_framework-0.1.3.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: bot-framework
+Version: 0.1.3
+Summary: Reusable Telegram bot framework with Clean Architecture
+Author-email: Vladimir Sumarokov <sumarokov.vp@gmail.com>
+Requires-Python: >=3.13
+Requires-Dist: pydantic>=2.11.0
+Provides-Extra: all
+Requires-Dist: psycopg[binary]>=3.2.0; extra == 'all'
+Requires-Dist: pytelegrambotapi>=4.29.0; extra == 'all'
+Requires-Dist: redis>=6.0.0; extra == 'all'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2.0; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=6.0.0; extra == 'redis'
+Provides-Extra: telegram
+Requires-Dist: pytelegrambotapi>=4.29.0; extra == 'telegram'
+Description-Content-Type: text/markdown
+
+# Bot Framework
+
+Reusable Python library for building Telegram bots with Clean Architecture principles.
+
+## Installation
+
+```bash
+# Basic installation
+pip install bot-framework
+
+# With Telegram support
+pip install bot-framework[telegram]
+
+# With all optional dependencies
+pip install bot-framework[all]
+```
+
+## Features
+
+- **Clean Architecture** - Layered architecture with import-linter enforcement
+- **Telegram Integration** - Ready-to-use services for pyTelegramBotAPI
+- **Flow Management** - Dialog flow stack management with Redis storage
+- **Role Management** - User roles and permissions
+- **Language Management** - Multilingual phrase support
+- **Request Role Flow** - Pre-built flow for role requests
+
+## Quick Start
+
+```python
+from bot_framework import Button, Keyboard, IMessageSender
+from bot_framework.telegram import TelegramMessageSender
+
+# Create keyboard
+keyboard = Keyboard(rows=[
+    [Button(text="Option 1", callback_data="opt1")],
+    [Button(text="Option 2", callback_data="opt2")],
+])
+
+# Send message (implement IMessageSender or use TelegramMessageSender)
+sender.send(chat_id=123, text="Choose an option:", keyboard=keyboard)
+```
+
+## Optional Dependencies
+
+- `telegram` - pyTelegramBotAPI for Telegram bot integration
+- `postgres` - psycopg for PostgreSQL database support
+- `redis` - Redis for caching and flow state management
+- `all` - All optional dependencies
+
+## License
+
+MIT