bot-framework 0.1.3__py3-none-any.whl

bot_framework/__init__.py

@@ -0,0 +1,57 @@
+"""
+Bot Framework - A reusable Python library for building Telegram bots.
+
+This package provides core components for building Telegram bots with
+Clean Architecture principles.
+"""
+
+from bot_framework.entities.bot_callback import BotCallback
+from bot_framework.entities.bot_message import BotMessage, BotMessageUser
+from bot_framework.entities.bot_user import BotUser
+from bot_framework.entities.button import Button
+from bot_framework.entities.keyboard import Keyboard
+from bot_framework.entities.language_code import LanguageCode
+from bot_framework.entities.parse_mode import ParseMode
+from bot_framework.entities.role import Role
+from bot_framework.entities.role_name import RoleName
+from bot_framework.entities.user import User
+from bot_framework.protocols.i_callback_answerer import ICallbackAnswerer
+from bot_framework.protocols.i_callback_handler import ICallbackHandler
+from bot_framework.protocols.i_callback_handler_registry import (
+    ICallbackHandlerRegistry,
+)
+from bot_framework.protocols.i_flow_router import IFlowRouter
+from bot_framework.protocols.i_message_deleter import IMessageDeleter
+from bot_framework.protocols.i_message_handler import IMessageHandler
+from bot_framework.protocols.i_message_handler_registry import IMessageHandlerRegistry
+from bot_framework.protocols.i_message_replacer import IMessageReplacer
+from bot_framework.protocols.i_message_sender import IMessageSender
+from bot_framework.protocols.i_notify_replacer import INotifyReplacer
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Entities
+    "BotCallback",
+    "BotMessage",
+    "BotMessageUser",
+    "BotUser",
+    "Button",
+    "Keyboard",
+    "LanguageCode",
+    "ParseMode",
+    "Role",
+    "RoleName",
+    "User",
+    # Protocols
+    "ICallbackAnswerer",
+    "ICallbackHandler",
+    "ICallbackHandlerRegistry",
+    "IFlowRouter",
+    "IMessageDeleter",
+    "IMessageHandler",
+    "IMessageHandlerRegistry",
+    "IMessageReplacer",
+    "IMessageSender",
+    "INotifyReplacer",
+]

bot_framework/base_protocols/__init__.py

@@ -0,0 +1,21 @@
+from .create import CreateProtocol
+from .delete import DeleteProtocol
+from .get_all import GetAllProtocol
+from .get_by_key import GetByKeyProtocol
+from .get_by_name import GetByNameProtocol
+from .read import ReadProtocol
+from .read_sequence_by_user_id import (
+    ReadSequenceByUserIdProtocol,
+)
+from .update import UpdateProtocol
+
+__all__ = [
+    "CreateProtocol",
+    "ReadProtocol",
+    "UpdateProtocol",
+    "DeleteProtocol",
+    "GetAllProtocol",
+    "GetByKeyProtocol",
+    "GetByNameProtocol",
+    "ReadSequenceByUserIdProtocol",
+]

bot_framework/base_protocols/create.py

@@ -0,0 +1,9 @@
+from typing import (
+    Protocol, TypeVar,
+)
+
+T = TypeVar("T")
+
+
+class CreateProtocol(Protocol[T]):
+    def create(self, entity: T) -> T: ...

bot_framework/base_protocols/delete.py

@@ -0,0 +1,9 @@
+from typing import (
+    Protocol, TypeVar,
+)
+
+T = TypeVar("T", contravariant=True)
+
+
+class DeleteProtocol(Protocol[T]):
+    def delete(self, entity: T) -> None: ...

bot_framework/base_protocols/get_all.py

@@ -0,0 +1,9 @@
+from typing import (
+    Protocol, TypeVar,
+)
+
+T = TypeVar("T")
+
+
+class GetAllProtocol(Protocol[T]):
+    def get_all(self) -> list[T]: ...

bot_framework/base_protocols/get_by_key.py

@@ -0,0 +1,9 @@
+from typing import (
+    Protocol, TypeVar,
+)
+
+T = TypeVar("T", covariant=True)
+
+
+class GetByKeyProtocol(Protocol[T]):
+    def get_by_key(self, key: str) -> T: ...

bot_framework/base_protocols/get_by_name.py

@@ -0,0 +1,9 @@
+from typing import (
+    Protocol, TypeVar,
+)
+
+T = TypeVar("T")
+
+
+class GetByNameProtocol(Protocol[T]):
+    def get_by_name(self, name: str) -> list[T]: ...

bot_framework/base_protocols/read.py

@@ -0,0 +1,11 @@
+from typing import (
+    Protocol,
+    TypeVar,
+)
+
+T = TypeVar("T", covariant=True)
+
+
+class ReadProtocol(Protocol[T]):
+    def get_by_id(self, id: int) -> T: ...
+    def find_by_id(self, id: int) -> T | None: ...

bot_framework/base_protocols/read_sequence_by_user_id.py

@@ -0,0 +1,11 @@
+from collections.abc import Sequence
+from typing import (
+    Protocol,
+    TypeVar,
+)
+
+T = TypeVar("T", covariant=True)
+
+
+class ReadSequenceByUserIdProtocol(Protocol[T]):
+    def get_by_user_id(self, user_id: int) -> Sequence[T]: ...

bot_framework/base_protocols/update.py

@@ -0,0 +1,9 @@
+from typing import (
+    Protocol, TypeVar,
+)
+
+T = TypeVar("T")
+
+
+class UpdateProtocol(Protocol[T]):
+    def update(self, entity: T) -> T: ...

bot_framework/entities/__init__.py

@@ -0,0 +1,24 @@
+from .bot_callback import BotCallback
+from .bot_message import BotMessage, BotMessageUser
+from .bot_user import BotUser
+from .button import Button
+from .keyboard import Keyboard
+from .language_code import LanguageCode
+from .parse_mode import ParseMode
+from .role import Role
+from .role_name import RoleName
+from .user import User
+
+__all__ = [
+    "BotCallback",
+    "BotMessage",
+    "BotMessageUser",
+    "BotUser",
+    "Button",
+    "Keyboard",
+    "LanguageCode",
+    "ParseMode",
+    "Role",
+    "RoleName",
+    "User",
+]

bot_framework/entities/bot_callback.py

@@ -0,0 +1,21 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+
+
+class BotCallback(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    user_id: int
+    data: str | None
+    message_id: int | None
+    message_chat_id: int | None
+    user_language_code: str | None = None
+    _original: Any = PrivateAttr(default=None)
+
+    def get_original(self) -> Any:
+        return self._original
+
+    def set_original(self, original: Any) -> None:
+        self._original = original

bot_framework/entities/bot_message.py

@@ -0,0 +1,27 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+
+
+class BotMessageUser(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    language_code: str | None = None
+
+
+class BotMessage(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    chat_id: int
+    message_id: int
+    user_id: int | None = None
+    text: str | None = None
+    from_user: BotMessageUser | None = None
+    _original: Any = PrivateAttr(default=None)
+
+    def get_original(self) -> Any:
+        return self._original
+
+    def set_original(self, original: Any) -> None:
+        self._original = original

bot_framework/entities/bot_user.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+
+
+class BotUser(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    username: str | None
+    first_name: str | None
+    last_name: str | None
+    language_code: str
+    is_bot: bool
+    is_premium: bool
+    _original: Any = PrivateAttr(default=None)
+
+    def get_original(self) -> Any:
+        return self._original
+
+    def set_original(self, original: Any) -> None:
+        self._original = original

bot_framework/entities/button.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class Button(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    text: str
+    callback_data: str

bot_framework/entities/keyboard.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel, ConfigDict
+
+from bot_framework.entities.button import Button
+
+
+class Keyboard(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    rows: list[list[Button]]

bot_framework/entities/language_code.py

@@ -0,0 +1,8 @@
+from enum import StrEnum
+
+
+class LanguageCode(StrEnum):
+    EN = "en"
+    RU = "ru"
+    KZ = "kz"
+    KH = "kh"

bot_framework/entities/parse_mode.py

@@ -0,0 +1,6 @@
+from enum import StrEnum
+
+
+class ParseMode(StrEnum):
+    HTML = "HTML"
+    MARKDOWN = "MarkdownV2"

bot_framework/entities/role.py

@@ -0,0 +1,16 @@
+from datetime import datetime
+
+from pydantic import (
+    BaseModel, ConfigDict, Field,
+)
+
+
+class Role(BaseModel):
+    id: int = 0
+    name: str
+    description: str | None = None
+    is_active: bool = True
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+
+    model_config = ConfigDict(from_attributes=True)

bot_framework/entities/role_name.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class RoleName(str, Enum):
+    USER = "user"
+    ADMIN = "admin"
+    MODERATOR = "moderator"

bot_framework/entities/user.py

@@ -0,0 +1,23 @@
+from datetime import datetime
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+)
+
+from bot_framework.entities.language_code import LanguageCode
+
+
+class User(BaseModel):
+    id: int
+    username: str | None = None
+    first_name: str | None = None
+    last_name: str | None = None
+    language_code: str = LanguageCode.EN
+    is_bot: bool = False
+    is_premium: bool = False
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+
+    model_config = ConfigDict(from_attributes=True)

bot_framework/flow_management/__init__.py

@@ -0,0 +1,31 @@
+from bot_framework.flow_management.entities import FlowStackEntry
+from bot_framework.flow_management.flow_registry import FlowRegistry
+from bot_framework.flow_management.protocols import (
+    IFlowMessageDeleter,
+    IFlowMessageStorage,
+    IFlowStackStorage,
+    IFlowStackValidator,
+)
+from bot_framework.flow_management.repos import (
+    RedisFlowMessageStorage,
+    RedisFlowStackStorage,
+)
+from bot_framework.flow_management.services import (
+    FlowMessageDeleter,
+    FlowStackNavigator,
+    FlowStackValidator,
+)
+
+__all__ = [
+    "FlowStackEntry",
+    "FlowRegistry",
+    "RedisFlowMessageStorage",
+    "RedisFlowStackStorage",
+    "IFlowMessageStorage",
+    "IFlowStackStorage",
+    "FlowMessageDeleter",
+    "FlowStackNavigator",
+    "FlowStackValidator",
+    "IFlowMessageDeleter",
+    "IFlowStackValidator",
+]

bot_framework/flow_management/entities/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from bot_framework.flow_management.entities.flow_stack_entry import FlowStackEntry
+
+__all__ = ["FlowStackEntry"]

bot_framework/flow_management/entities/flow_stack_entry.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class FlowStackEntry(BaseModel):
+    flow_name: str
+    started_at: datetime

bot_framework/flow_management/flow_registry.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from bot_framework.protocols.i_flow_router import IFlowRouter
+
+
+class FlowRegistry:
+    def __init__(self):
+        self._flows: dict[str, IFlowRouter] = {}
+
+    def register(self, name: str, router: IFlowRouter) -> None:
+        self._flows[name] = router
+
+    def get(self, name: str) -> IFlowRouter | None:
+        return self._flows.get(name)

bot_framework/flow_management/protocols/__init__.py

@@ -0,0 +1,11 @@
+from bot_framework.flow_management.protocols.i_flow_message_deleter import IFlowMessageDeleter
+from bot_framework.flow_management.protocols.i_flow_message_storage import IFlowMessageStorage
+from bot_framework.flow_management.protocols.i_flow_stack_storage import IFlowStackStorage
+from bot_framework.flow_management.protocols.i_flow_stack_validator import IFlowStackValidator
+
+__all__ = [
+    "IFlowMessageDeleter",
+    "IFlowMessageStorage",
+    "IFlowStackStorage",
+    "IFlowStackValidator",
+]

bot_framework/flow_management/protocols/i_flow_message_deleter.py

@@ -0,0 +1,8 @@
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class IFlowMessageDeleter(Protocol):
+    def delete_flow_messages(self, chat_id: int, flow_name: str) -> None: ...
+
+    def delete_all_flow_messages(self, chat_id: int) -> None: ...

bot_framework/flow_management/protocols/i_flow_message_storage.py

@@ -0,0 +1,12 @@
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class IFlowMessageStorage(Protocol):
+    def add_message(self, telegram_id: int, flow_name: str, message_id: int) -> None: ...
+
+    def get_messages(self, telegram_id: int, flow_name: str) -> list[int]: ...
+
+    def clear_messages(self, telegram_id: int, flow_name: str) -> None: ...
+
+    def clear_all_messages(self, telegram_id: int) -> None: ...

bot_framework/flow_management/protocols/i_flow_stack_storage.py

@@ -0,0 +1,14 @@
+from typing import Protocol, runtime_checkable
+
+from bot_framework.flow_management.entities import FlowStackEntry
+
+
+@runtime_checkable
+class IFlowStackStorage(Protocol):
+    def push(self, telegram_id: int, entry: FlowStackEntry) -> None: ...
+
+    def pop(self, telegram_id: int) -> FlowStackEntry | None: ...
+
+    def get_stack(self, telegram_id: int) -> list[FlowStackEntry]: ...
+
+    def clear(self, telegram_id: int) -> None: ...

bot_framework/flow_management/protocols/i_flow_stack_validator.py

@@ -0,0 +1,6 @@
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class IFlowStackValidator(Protocol):
+    def validate_push(self, user_id: int, flow_name: str) -> None: ...

bot_framework/flow_management/repos/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from bot_framework.flow_management.repos.redis_flow_message_storage import (
+    RedisFlowMessageStorage,
+)
+from bot_framework.flow_management.repos.redis_flow_stack_storage import RedisFlowStackStorage
+
+__all__ = ["RedisFlowMessageStorage", "RedisFlowStackStorage"]

bot_framework/flow_management/repos/redis_flow_message_storage.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import redis
+
+
+class RedisFlowMessageStorage:
+    def __init__(self, redis_url: str):
+        self.redis_client = redis.from_url(redis_url)  # pyright: ignore[reportUnknownMemberType]
+        self.ttl = 600
+
+    def _get_key(self, telegram_id: int, flow_name: str) -> str:
+        return f"flow_messages:{telegram_id}:{flow_name}"
+
+    def _get_pattern(self, telegram_id: int) -> str:
+        return f"flow_messages:{telegram_id}:*"
+
+    def add_message(self, telegram_id: int, flow_name: str, message_id: int) -> None:
+        key = self._get_key(telegram_id, flow_name)
+        self.redis_client.rpush(key, message_id)
+        self.redis_client.expire(key, self.ttl)
+
+    def get_messages(self, telegram_id: int, flow_name: str) -> list[int]:
+        key = self._get_key(telegram_id, flow_name)
+        messages = self.redis_client.lrange(key, 0, -1)
+        return [int(m) for m in messages]  # pyright: ignore[reportGeneralTypeIssues]
+
+    def clear_messages(self, telegram_id: int, flow_name: str) -> None:
+        key = self._get_key(telegram_id, flow_name)
+        self.redis_client.delete(key)
+
+    def clear_all_messages(self, telegram_id: int) -> None:
+        pattern = self._get_pattern(telegram_id)
+        keys = self.redis_client.keys(pattern)
+        if keys:
+            self.redis_client.delete(*keys)  # pyright: ignore[reportGeneralTypeIssues]

bot_framework/flow_management/repos/redis_flow_stack_storage.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import json
+
+import redis
+
+from bot_framework.flow_management.entities import FlowStackEntry
+
+
+class RedisFlowStackStorage:
+    def __init__(self, redis_url: str):
+        self.redis_client = redis.from_url(redis_url)
+        self.ttl = 600
+
+    def _get_key(self, telegram_id: int) -> str:
+        return f"flow_stack:{telegram_id}"
+
+    def _get_raw_stack(self, telegram_id: int) -> list[dict]:
+        value = self.redis_client.get(self._get_key(telegram_id))
+        if value is None:
+            return []
+        if isinstance(value, bytes):
+            return json.loads(value.decode())
+        if isinstance(value, str):
+            return json.loads(value)
+        return []
+
+    def _save_raw_stack(self, telegram_id: int, stack: list[dict]) -> None:
+        self.redis_client.setex(
+            name=self._get_key(telegram_id),
+            time=self.ttl,
+            value=json.dumps(stack),
+        )
+
+    def push(self, telegram_id: int, entry: FlowStackEntry) -> None:
+        stack = self._get_raw_stack(telegram_id)
+        stack.append(entry.model_dump(mode="json"))
+        self._save_raw_stack(telegram_id, stack)
+
+    def pop(self, telegram_id: int) -> FlowStackEntry | None:
+        stack = self._get_raw_stack(telegram_id)
+        if not stack:
+            return None
+        entry_dict = stack.pop()
+        self._save_raw_stack(telegram_id, stack)
+        return FlowStackEntry.model_validate(entry_dict)
+
+    def get_stack(self, telegram_id: int) -> list[FlowStackEntry]:
+        raw_stack = self._get_raw_stack(telegram_id)
+        return [FlowStackEntry.model_validate(entry) for entry in raw_stack]
+
+    def clear(self, telegram_id: int) -> None:
+        self.redis_client.delete(self._get_key(telegram_id))

bot_framework/flow_management/services/__init__.py

@@ -0,0 +1,15 @@
+from bot_framework.flow_management.protocols import (
+    IFlowMessageDeleter,
+    IFlowStackValidator,
+)
+from bot_framework.flow_management.services.flow_message_deleter import FlowMessageDeleter
+from bot_framework.flow_management.services.flow_stack_navigator import FlowStackNavigator
+from bot_framework.flow_management.services.flow_stack_validator import FlowStackValidator
+
+__all__ = [
+    "FlowMessageDeleter",
+    "FlowStackNavigator",
+    "FlowStackValidator",
+    "IFlowMessageDeleter",
+    "IFlowStackValidator",
+]

bot_framework/flow_management/services/flow_message_deleter.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import logging
+
+from bot_framework.flow_management.protocols import IFlowMessageStorage
+from bot_framework.protocols import IMessageDeleter
+
+logger = logging.getLogger(__name__)
+
+
+class FlowMessageDeleter:
+    def __init__(
+        self,
+        message_deleter: IMessageDeleter,
+        message_storage: IFlowMessageStorage,
+    ):
+        self._message_deleter = message_deleter
+        self._message_storage = message_storage
+
+    def delete_flow_messages(self, chat_id: int, flow_name: str) -> None:
+        message_ids = self._message_storage.get_messages(chat_id, flow_name)
+        if not message_ids:
+            return
+
+        self._delete_messages_batch(chat_id, message_ids)
+        self._message_storage.clear_messages(chat_id, flow_name)
+
+    def delete_all_flow_messages(self, chat_id: int) -> None:
+        self._message_storage.clear_all_messages(chat_id)
+
+    def _delete_messages_batch(self, chat_id: int, message_ids: list[int]) -> None:
+        for message_id in message_ids:
+            self._message_deleter.delete(chat_id, message_id)