telekit 0.0.1__py3-none-any.whl

telekit/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2025 Ving Studio, Romashka
+# Licensed under the MIT License. See LICENSE file for full terms.
+
+# engine/__init__.py
+from .handler import Handler
+from .chain import Chain
+from .callback_query_handler import CallbackQueryHandler
+from .server import Server, example
+from .snapvault.snapvault import Vault # type: ignore
+from .chapters import chapters
+from .user import User
+from . import senders
+
+__all__ = ["senders", "Chain", "Handler", "CallbackQueryHandler", "Server", "Vault", "User", "chapters", "example"]

telekit/callback_query_handler.py

@@ -0,0 +1,58 @@
+from typing import Any
+
+import telebot # type: ignore
+from telebot.types import ( # type: ignore
+    Message, 
+    InaccessibleMessage,
+    CallbackQuery
+)
+
+
+class CallbackQueryHandler:
+
+    bot: telebot.TeleBot
+    
+    @classmethod
+    def init(cls, bot: telebot.TeleBot):
+        """
+        Initializes the bot instance for the class.
+
+        Args:
+            bot (TeleBot): The Telegram bot instance to be used for sending messages.
+        """
+        cls.bot = bot
+
+        @bot.callback_query_handler(func=lambda call: True) # type: ignore
+        def handle_callback(call: telebot.types.CallbackQuery) -> None: # type: ignore
+            CallbackQueryHandler().handle(call)
+
+    def handle(self, call: CallbackQuery):
+        self._simulate(call.message, str(call.data), from_user=call.from_user)
+
+    def _simulate(self, message: Message | InaccessibleMessage, text: str, from_user: Any=None) -> None:
+        args = {}
+
+        is_bot: bool = getattr(getattr(message, "from_user", from_user), "is_bot", False)
+
+        args["message_id"]  = getattr(message, "message_id", None)
+        args["from_user"]   = from_user if from_user else getattr(message, "from_user", None)
+        args["date"]        = getattr(message, "date", None)
+        args["chat"]        = getattr(message, "chat", None)
+        args["json_string"] = getattr(message, "json", None)
+
+        args["content_type"] = "text"
+        args["options"]      = {}
+
+        if any(value is None for value in args.values()): # type: ignore
+            return print("Error: Missing required fields in message simulation.")
+        
+        original_message = message
+
+        message = Message(**args) # type: ignore
+        message.message_thread_id = getattr(original_message, "message_thread_id", None)
+        message.text = text
+
+        if message.from_user:
+            message.from_user.is_bot = is_bot
+
+        self.bot.process_new_messages([message]) # type: ignore

telekit/chain.py

@@ -0,0 +1,248 @@
+import random
+from typing import Callable, Any
+
+import telebot              # type: ignore
+from telebot.types import ( # type: ignore
+    Message, 
+    InlineKeyboardButton,
+    InlineKeyboardMarkup
+)
+
+from . import senders
+from . import input_handler
+
+
+class Chain:
+
+    bot: telebot.TeleBot
+    
+    @classmethod
+    def init(cls, bot: telebot.TeleBot):
+        """
+        Initializes the bot instance for the class.
+
+        Args:
+            bot (TeleBot): The Telegram bot instance to be used for sending messages.
+        """
+        cls.bot = bot
+        
+    def __init__(self, chat_id: int):
+        self.chat_id = chat_id
+        self.sender = senders.AlertSender(chat_id)
+        self.handler = input_handler.InputHandler(chat_id)
+        self.parent: Chain | None = None
+        self._previous_message: Message | None = None
+        self.always_edit_previous_message: bool = False
+
+    def set_inline_keyboard(self, keyboard: dict[str, 'Chain' | Callable[[Message], Any]], row_width: int = 1) -> None:
+        """
+        Sets an inline keyboard for the chain with buttons that call the corresponding functions.
+        Each button will call the function with the message as an argument.
+        
+        Args:
+            keyboard (dict[str, Callable[[Message], Any]]): A dictionary where keys are button captions
+                and values are functions to be called when the button is clicked.
+        """
+        callback_functions: dict[str, Callable[[Message], Any]] = {}
+        buttons: list[InlineKeyboardButton] = []
+
+        for i, (caption, callback) in enumerate(keyboard.items()):
+            callback_data = f"button_{i}_{random.randint(1000, 9999)}"
+            callback_functions[callback_data] = callback
+            buttons.append(
+                InlineKeyboardButton(
+                    text=caption,
+                    callback_data=callback_data
+                )
+            )
+
+        rows = [buttons[i:i + row_width] for i in range(0, len(buttons), row_width)]
+        markup = InlineKeyboardMarkup()
+        markup.keyboard = rows
+
+        self.sender.set_reply_markup(markup)  # type: ignore
+        self.handler.set_callback_functions(callback_functions)
+
+    def inline_keyboard[Caption: str, Value](self, keyboard: dict[Caption, Value], row_width: int = 1) -> Callable[[Callable[[Message, Value], None]], None]:
+        """
+        Decorator to set an inline keyboard for the chain
+        with buttons that call the decorated function with the button value.
+        """
+        def wrapper(func: Callable[[Message, Value], None]) -> None:
+            callback_functions: dict[str, Callable[[Message], Any]] = {}
+            buttons: list[InlineKeyboardButton] = []
+
+            def get_callback(value: Value) -> Callable[[Message], None]:
+                def callback(message: Message) -> None:
+                    func(message, value)
+                return callback
+
+            for i, (caption, value) in enumerate(keyboard.items()):
+                callback_data = f"button_{i}_{random.randint(1000, 9999)}"
+                callback_functions[callback_data] = get_callback(value)
+                buttons.append(
+                    InlineKeyboardButton(
+                        text=caption,
+                        callback_data=callback_data
+                    )
+                )
+
+            rows = [buttons[i:i + row_width] for i in range(0, len(buttons), row_width)]
+            markup = InlineKeyboardMarkup()
+            markup.keyboard = rows
+
+            self.sender.set_reply_markup(markup)  # type: ignore
+            self.handler.set_callback_functions(callback_functions)
+
+        return wrapper
+    
+    def set_entry_suggestions(self, keyboard: dict[str, str] | list[str], row_width: int = 1) -> None:
+        """
+        Sets reply suggestions as inline buttons below the message input field.
+        These buttons act as quick replies, and send the corresponding `callback_data` when clicked.
+
+        Args:
+            keyboard (dict[Caption, Value]): A dictionary where each key is the button's visible text (caption),
+                                            and each value is the string to send as callback_data.
+            row_width (int, optional): Number of buttons per row. Defaults to 1.
+        """
+        
+        buttons: list[InlineKeyboardButton] = []
+
+        if isinstance(keyboard, list):
+            keyboard = {c: c for c in keyboard}
+
+        for caption, value in keyboard.items(): 
+            buttons.append(
+                InlineKeyboardButton(
+                    text=caption,
+                    callback_data=value
+                )
+            )
+
+        rows = [buttons[i:i + row_width] for i in range(0, len(buttons), row_width)]
+        markup = InlineKeyboardMarkup()
+        markup.keyboard = rows
+
+        self.sender.set_reply_markup(markup)  # type: ignore
+
+    def entry(self, 
+              filter_message: Callable[[Message], bool] | None=None,
+              delete_user_response: bool=False) -> Callable[[Callable[[Message], Any]], None]:
+        def wrapper(func: Callable[[Message], Any]) -> None:
+            def callback(message: Message) -> bool:
+                if delete_user_response:
+                    self.sender.delete_message(message)
+                    
+                if filter_message and not filter_message(message):
+                    return False
+                
+                func(message)
+                return True
+            
+            self.handler.set_entry_callback(callback)
+
+        return wrapper 
+    
+    def entry_text(self, 
+              filter_message: Callable[[Message, str], bool] | None=None,
+              delete_user_response: bool=False) -> Callable[[Callable[[Message, str], Any]], None]:
+        def wrapper(func: Callable[[Message, str], Any]) -> None:
+            def callback(message: Message) -> bool:
+                if delete_user_response:
+                    self.sender.delete_message(message)
+
+                if not message.text:
+                    return False # Only text messages
+                    
+                if filter_message and not filter_message(message, message.text):
+                    return False
+                
+                func(message, message.text)
+                return True
+            
+            self.handler.set_entry_callback(callback)
+
+        return wrapper 
+
+    def set_always_edit_previous_message(self, value: bool=True) -> None:
+        self.always_edit_previous_message = value
+
+    def send(self) -> Message | None:
+        self.handler.handle_next_message()
+
+        if self.always_edit_previous_message:
+            self.edit_previous_message()
+
+        message = self.sender.send_or_handle_error()
+        self._set_previous_message(message)
+        return message
+    
+    def _set_previous_message(self, message: Message | None) -> None:
+        self._previous_message = message
+
+        if self.parent:
+            self.parent._set_previous_message(message)
+    
+    def get_previous_message(self) -> Message | None:
+        """
+        Returns the previous message sent by the chain.
+        
+        Returns:
+            Message | None: The previous message or None if no message was sent
+        """
+        if self._previous_message:
+            return self._previous_message
+        elif self.parent:
+            return self.parent.get_previous_message()
+        else:
+            return None
+        
+    def edit_previous_message(self) -> None:
+        """
+        Edits the previous message sent by the chain with the current sender's message
+        """
+        self.sender.set_edit_message(self.get_previous_message())
+    
+    def set_parent(self, parent: 'Chain') -> None:
+        """
+        Sets the parent chain for this chain.
+
+        Args:
+            parent (Chain): The parent chain to be set.
+        """
+        self.parent = parent
+        self.always_edit_previous_message = parent.always_edit_previous_message
+
+    def __call__(self, message: Message | None = None):
+        self.send()
+
+    def get_alert_sender(self) -> senders.AlertSender:
+        """
+        Returns the sender for sending alert messages.
+        """
+        return senders.AlertSender(self.chat_id)
+    
+    def get_bot(self) -> telebot.TeleBot:
+        """
+        Returns the bot instance associated with this chain.
+        
+        Returns:
+            telebot.TeleBot: The bot instance.
+        """
+        return self.bot
+
+    @classmethod
+    def get_chain_factory(cls, chat_id: int) -> Callable[[], 'Chain']:
+        def message_factory() -> Chain:
+            return cls(chat_id)
+        return message_factory
+    
+    @classmethod
+    def get_children_factory(cls, chat_id: int) -> Callable[[Any], 'Chain']:
+        def children_factory(parent: Chain | None=None) -> Chain:
+            chain = cls(chat_id)
+            if parent:
+                chain.set_parent(parent)
+            return chain
+        return children_factory

telekit/example/__init__.py

@@ -0,0 +1 @@
+from . import example_server

telekit/example/example_handlers/__init__.py

@@ -0,0 +1,4 @@
+from . import start # type: ignore
+from . import help  # type: ignore
+from . import entry # type: ignore
+

telekit/example/example_handlers/entry.py

@@ -0,0 +1,125 @@
+import telebot.types # type: ignore
+import telekit
+import telekit.snapvault
+import telekit.snapvault.snapvault
+
+class User:
+    names: telekit.Vault = telekit.Vault(
+        path             = "data_base", 
+        table_name       = "names", 
+        key_field_name   = "user_id", 
+        value_field_name = "name"
+    )
+    
+    ages: telekit.Vault = telekit.Vault(
+        path             = "data_base", 
+        table_name       = "ages", 
+        key_field_name   = "user_id", 
+        value_field_name = "age"
+    )
+    
+    def __init__(self, chat_id: int):
+        self.chat_id = chat_id
+
+    def get_name(self, default: str | None=None) -> str | None:
+        return self.names.get(self.chat_id, default)
+
+    def set_name(self, value: str):
+        self.names[self.chat_id] = value
+
+    def get_age(self, default: int | None=None) -> int | None:
+        return self.ages.get(self.chat_id, default)
+
+    def set_age(self, value: int):
+        self.ages[self.chat_id] = value
+    
+
+class EntryHandler(telekit.Handler):
+
+    @classmethod
+    def init_handler(cls, bot: telebot.TeleBot) -> None:
+        """
+        Initializes the command handler.
+        """
+        @bot.message_handler(commands=['entry']) # type: ignore
+        def handler(message: telebot.types.Message) -> None: # type: ignore
+            cls(message).handle()
+
+    # ------------------------------------------
+    # Handling Logic
+    # ------------------------------------------
+
+    def handle(self) -> None:
+        self._user = User(self.message.chat.id)
+        self.entry_name()
+
+    def entry_name(self, message: telebot.types.Message | None=None) -> None:
+        prompt: telekit.Chain = self.get_child()
+        prompt.set_always_edit_previous_message(True)
+         
+        prompt.sender.set_title("⌨️ What`s your name?")
+        prompt.sender.set_message("Please, send a text message")
+
+        name = self._user.get_name(
+            self.user.get_username()
+        )
+        
+        if name:
+            prompt.set_entry_suggestions([name])
+
+        @prompt.entry_text(delete_user_response=True) # Text message only (User will not be abled to send photos, stickers, ...)
+        def _(message: telebot.types.Message, name: str) -> None:
+            received: telekit.Chain = self.get_child()
+
+            received.sender.set_title(f"👋 Bonjour, {name}!")
+            received.sender.set_message(f"Is that your name?")
+
+            self._user.set_name(name)
+
+            received.set_inline_keyboard(
+                {
+                    "« Change": prompt,
+                    "Yes »": self.entry_age,
+                }, row_width=2
+            )
+
+            received.send()
+
+        prompt.send()
+
+    def entry_age(self, message: telebot.types.Message) -> None:
+        prompt: telekit.Chain = self.get_child() # Child of `entry_name.<locals>.received` (previous chain)
+         
+        prompt.sender.set_title("⏳ How old are you?")
+        prompt.sender.set_message("Please, send a numeric message")
+
+        @prompt.entry_text(                                 # Text message only (User will not be abled to send photos, stickers, ...)
+            filter_message=lambda message, text: text.isdigit() and 0 < int(text) < 130, # Numeric message only
+            delete_user_response=True)
+        def _(message: telebot.types.Message, text: str) -> None:
+            received: telekit.Chain = self.get_child()
+
+            received.sender.set_title(f"😏 {text} years old?")
+            received.sender.set_message(f"Noted. Now I know which memes are safe to show you")
+            self._user.set_age(int(text))
+
+            received.set_inline_keyboard(
+                {
+                    "« Change": prompt,
+                    "Ok »": self.result,
+                }, row_width=2
+            )
+
+            received.send()
+
+        prompt.send()
+
+    def result(self, message: telebot.types.Message) -> None:
+        result: telekit.Chain = self.get_child() # Child of `entry_age.<locals>.received` (previous chain)
+         
+        result.sender.set_title("😏 Well well well")
+        result.sender.set_message(f"So your name is {self._user.get_name()} and you're {self._user.get_age()}? Fancy!")
+
+        result.set_inline_keyboard({"« Change": self.entry_name})
+
+        result.send()

telekit/example/example_handlers/help.py

@@ -0,0 +1,42 @@
+import telebot.types # type: ignore
+import telekit
+
+pages: dict[str, tuple[str, str]] = {}
+
+for title, text in telekit.chapters.read("help.txt").items():
+    pages[title] = (title, text)
+
+class HelpHandler(telekit.Handler):
+
+    @classmethod
+    def init_handler(cls, bot: telebot.TeleBot) -> None:
+        """
+        Initializes the command handler.
+        """
+        @bot.message_handler(commands=['help']) # type: ignore
+        def handler(message: telebot.types.Message) -> None: # type: ignore
+            cls(message).handle()
+
+    # ------------------------------------------
+    # Handling Logic
+    # ------------------------------------------
+
+    def handle(self) -> None:
+        main: telekit.Chain = self.get_chain()
+        main.set_always_edit_previous_message(True)
+         
+        main.sender.set_title("FAQ - Frequently Asked Questions")
+        main.sender.set_message("Here are some common questions and answers to help you get started:")
+
+        @main.inline_keyboard(pages)
+        def _(message: telebot.types.Message, value: tuple[str, str]) -> None:
+            page: telekit.Chain = self.get_child()
+
+            page.sender.set_title(value[0])
+            page.sender.set_message(value[1])
+
+            page.set_inline_keyboard({"« Back": main})
+
+            page.send()
+
+        main.send()

telekit/example/example_handlers/start.py

@@ -0,0 +1,49 @@
+import telebot.types # type: ignore
+import telekit
+import typing
+
+
+class StartHandler(telekit.Handler):
+
+    # ------------------------------------------
+    # Initialization
+    # ------------------------------------------
+
+    @classmethod
+    def init_handler(cls, bot: telebot.TeleBot) -> None:
+        """
+        Initializes the message handler for the '/start' command.
+        """
+        @bot.message_handler(commands=['start']) # type: ignore
+        def handler(message: telebot.types.Message) -> None: # type: ignore
+            cls(message).handle()
+
+    # ------------------------------------------
+    # Handling Logic
+    # ------------------------------------------
+
+    def handle(self) -> None:
+        chain: telekit.Chain = self.get_chain()
+         
+        chain.sender.set_title("Hello")
+        chain.sender.set_message("Welcome to the bot! Click the button below to start interacting.")
+        chain.sender.set_photo("https://static.wikia.nocookie.net/ssb-tourney/images/d/db/Bot_CG_Art.jpg/revision/latest?cb=20151224123450")
+        chain.sender.set_effect(chain.sender.Effect.PARTY)
+
+        def counter_factory() -> typing.Callable[[int], int]:
+            count = 0
+            def counter(value: int=1) -> int:
+                nonlocal count
+                count += value
+                return count
+            return counter
+        
+        click_counter = counter_factory()
+
+        @chain.inline_keyboard({"⊕": 1, "⊖": -1}, row_width=2)
+        def _(message: telebot.types.Message, value: int) -> None:
+            chain.sender.set_message(f"You clicked {click_counter(value)} times")
+            chain.edit_previous_message()
+            chain.send()
+
+        chain.send()

telekit/example/example_server.py

@@ -0,0 +1,9 @@
+# -*- encoding:utf-8 -*-
+import telebot # type: ignore
+import telekit
+
+from . import example_handlers # type: ignore
+
+def run_example(token: str):
+    bot = telebot.TeleBot(token)
+    telekit.Server(bot).polling()

telekit/handler.py

@@ -0,0 +1,59 @@
+from typing import Callable
+
+from telebot.types import Message # type: ignore
+import telebot # type: ignore
+
+from .chain import Chain
+from .user import User
+
+
+class Handler:
+    
+    bot: telebot.TeleBot
+
+    # def __init__(self, message: telebot.types.Message):
+    #     super().__init__(message)
+    
+    @classmethod
+    def init(cls, bot: telebot.TeleBot):
+        """
+        Initializes the bot instance for the class.
+
+        Args:
+            bot (TeleBot): The Telegram bot instance to be used for sending messages.
+        """
+        cls.bot = bot
+
+        for handler in cls.handlers:
+            handler.init_handler(bot)
+
+    @classmethod
+    def init_handler(cls, bot: telebot.TeleBot) -> None:
+        """
+        Initializes the message handler
+        """
+        pass
+
+    def __init__(self, message: Message):
+        self.message: Message = message
+        self.chain: Chain | None = None
+        self.user = User(self.message.chat.id, self.message.from_user)
+        self._chain_factory: Callable[[], Chain] = Chain.get_chain_factory(self.message.chat.id)
+        self._children_factory: Callable[[Chain | None], Chain] = Chain.get_children_factory(self.message.chat.id)
+
+    def get_chain(self) -> Chain:
+        self.chain = self._chain_factory()
+        return self.chain
+    
+    def get_child(self, parent: Chain | None = None) -> Chain:
+        if parent is None:
+            parent = self.chain
+
+        self.chain = self._children_factory(self.chain)
+        return self.chain
+
+    handlers: list[type['Handler']] = []
+
+    def __init_subclass__(cls, **kwargs): # type: ignore
+        super().__init_subclass__(**kwargs)
+        Handler.handlers.append(cls)

telekit/init.py

@@ -0,0 +1,18 @@
+from .handler import Handler
+from .chain import Chain
+from .input_handler import InputHandler
+from .callback_query_handler import CallbackQueryHandler
+from .user import User
+from . import senders
+
+import telebot  # type: ignore
+
+__all__ = ["init"]
+
+def init(bot: telebot.TeleBot) -> None:
+    senders.BaseSender.init(bot)
+    Handler.init(bot)
+    Chain.init(bot)
+    InputHandler.init(bot)
+    CallbackQueryHandler.init(bot)
+    User.init(bot)