maxapi-python 1.1.20__py3-none-any.whl → 1.2.1__py3-none-any.whl

pymax/mixins/handler.py

@@ -1,26 +1,37 @@
 from collections.abc import Awaitable, Callable
 from typing import Any
 
-from pymax.filters import Filter
+from pymax.filters import BaseFilter
 from pymax.interfaces import ClientProtocol
 from pymax.types import Chat, Message, ReactionInfo
 
 
 class HandlerMixin(ClientProtocol):
     def on_message(
-        self, *, filter: Filter | None = None
+        self, filter: BaseFilter[Message] | None = None
     ) -> Callable[
         [Callable[[Any], Any | Awaitable[Any]]],
         Callable[[Any], Any | Awaitable[Any]],
     ]:
         """
-        Декоратор для установки обработчика входящих сообщений.
+        Декоратор для регистрации обработчика входящих сообщений.
 
-        Args:
-            filter: Фильтр для обработки сообщений.
+        Позволяет установить функцию-обработчик для всех входящих сообщений
+        или только для сообщений, соответствующих заданному фильтру.
 
-        Returns:
-            Декоратор.
+        :param filter: Фильтр для обработки сообщений. По умолчанию None.
+        :type filter: BaseFilter[Message] | None
+        :return: Декоратор для функции-обработчика.
+        :rtype: Callable
+
+        Example::
+
+            @client.on_message(Filter.text("hello"))
+            async def handle_hello(message: Message):
+                await client.send_message(
+                    chat_id=message.chat_id,
+                    text="Hello!"
+                )
         """
 
         def decorator(
@@ -33,7 +44,7 @@ class HandlerMixin(ClientProtocol):
         return decorator
 
     def on_message_edit(
-        self, *, filter: Filter | None = None
+        self, filter: BaseFilter[Message] | None = None
     ) -> Callable[
         [Callable[[Any], Any | Awaitable[Any]]],
         Callable[[Any], Any | Awaitable[Any]],
@@ -41,11 +52,10 @@ class HandlerMixin(ClientProtocol):
         """
         Декоратор для установки обработчика отредактированных сообщений.
 
-        Args:
-            filter: Фильтр для обработки сообщений.
-
-        Returns:
-            Декоратор.
+        :param filter: Фильтр для обработки сообщений. По умолчанию None.
+        :type filter: BaseFilter[Message] | None
+        :return: Декоратор для функции-обработчика.
+        :rtype: Callable
         """
 
         def decorator(
@@ -60,7 +70,7 @@ class HandlerMixin(ClientProtocol):
         return decorator
 
     def on_message_delete(
-        self, *, filter: Filter | None = None
+        self, filter: BaseFilter[Message] | None = None
     ) -> Callable[
         [Callable[[Any], Any | Awaitable[Any]]],
         Callable[[Any], Any | Awaitable[Any]],
@@ -68,11 +78,10 @@ class HandlerMixin(ClientProtocol):
         """
         Декоратор для установки обработчика удаленных сообщений.
 
-        Args:
-            filter: Фильтр для обработки сообщений.
-
-        Returns:
-            Декоратор.
+        :param filter: Фильтр для обработки сообщений. По умолчанию None.
+        :type filter: BaseFilter[Message] | None
+        :return: Декоратор для функции-обработчика.
+        :rtype: Callable
         """
 
         def decorator(
@@ -93,13 +102,12 @@ class HandlerMixin(ClientProtocol):
         """
         Устанавливает обработчик изменения реакций на сообщения.
 
-        Args:
-            handler: Функция или coroutine с аргументами (message_id: str, chat_id: int, reaction_info: ReactionInfo).
-
-        Returns:
-            Установленный обработчик.
+        :param handler: Функция или coroutine с аргументами (message_id: str, chat_id: int, reaction_info: ReactionInfo).
+        :type handler: Callable[[str, int, ReactionInfo], Any | Awaitable[Any]]
+        :return: Установленный обработчик.
+        :rtype: Callable[[str, int, ReactionInfo], Any | Awaitable[Any]]
         """
-        self._on_reaction_change_handlers.append((handler,))
+        self._on_reaction_change_handlers.append(handler)
         self.logger.debug("on_reaction_change handler set: %r", handler)
         return handler
 
@@ -109,37 +117,93 @@ class HandlerMixin(ClientProtocol):
         """
         Устанавливает обработчик обновления информации о чате.
 
-        Args:
-            handler: Функция или coroutine с аргументом (chat: Chat).
-
-        Returns:
-            Установленный обработчик.
+        :param handler: Функция или coroutine с аргументом (chat: Chat).
+        :type handler: Callable[[Chat], Any | Awaitable[Any]]
+        :return: Установленный обработчик.
+        :rtype: Callable[[Chat], Any | Awaitable[Any]]
         """
-        self._on_chat_update_handlers.append((handler,))
+        self._on_chat_update_handlers.append(handler)
         self.logger.debug("on_chat_update handler set: %r", handler)
         return handler
 
+    def on_raw_receive(
+        self, handler: Callable[[dict[str, Any]], Any | Awaitable[Any]]
+    ) -> Callable[[dict[str, Any]], Any | Awaitable[Any]]:
+        """
+        Устанавливает обработчик для получения необработанных данных от сервера.
+
+        :param handler: Функция или coroutine с аргументом (data: dict).
+        :type handler: Callable[[dict[str, Any]], Any | Awaitable[Any]]
+        :return: Установленный обработчик.
+        :rtype: Callable[[dict[str, Any]], Any | Awaitable[Any]]
+        """
+        self._on_raw_receive_handlers.append(handler)
+        self.logger.debug("on_raw_receive handler set: %r", handler)
+        return handler
+
     def on_start(
         self, handler: Callable[[], Any | Awaitable[Any]]
     ) -> Callable[[], Any | Awaitable[Any]]:
         """
         Устанавливает обработчик, вызываемый при старте клиента.
 
-        Args:
-            handler: Функция или coroutine без аргументов.
-
-        Returns:
-            Установленный обработчик.
+        :param handler: Функция или coroutine без аргументов.
+        :type handler: Callable[[], Any | Awaitable[Any]]
+        :return: Установленный обработчик.
+        :rtype: Callable[[], Any | Awaitable[Any]]
         """
         self._on_start_handler = handler
         self.logger.debug("on_start handler set: %r", handler)
         return handler
 
+    def task(self, seconds: float, minutes: float = 0, hours: float = 0):
+        """
+        Декоратор для планирования периодической задачи.
+
+        :param seconds: Интервал выполнения в секундах.
+        :type seconds: float
+        :param minutes: Интервал выполнения в минутах. По умолчанию 0.
+        :type minutes: float
+        :param hours: Интервал выполнения в часах. По умолчанию 0.
+        :type hours: float
+        :return: Декоратор для функции-обработчика.
+        :rtype: Callable[[], Any | Awaitable[Any]]
+
+        Example::
+
+            @client.task(seconds=10)
+            async def task():
+                await client.send_message(chat_id=123, text="Hello!")
+        """
+
+        def decorator(
+            handler: Callable[[], Any | Awaitable[Any]],
+        ) -> Callable[[], Any | Awaitable[Any]]:
+            self._scheduled_tasks.append(
+                (handler, seconds + minutes * 60 + hours * 3600)
+            )
+            self.logger.debug(
+                f"task scheduled: {handler}, interval: {seconds + minutes * 60 + hours * 3600}s"
+            )
+            return handler
+
+        return decorator
+
     def add_message_handler(
         self,
         handler: Callable[[Message], Any | Awaitable[Any]],
-        filter: Filter | None,
+        filter: BaseFilter[Message] | None = None,
     ) -> Callable[[Message], Any | Awaitable[Any]]:
+        """
+        Добавляет обработчик входящих сообщений.
+
+        :param handler: Обработчик.
+        :type handler: Callable[[Message], Any | Awaitable[Any]]
+        :param filter: Фильтр. По умолчанию None.
+        :type filter: BaseFilter[Message] | None
+        :return: Обработчик.
+        :rtype: Callable[[Message], Any | Awaitable[Any]]
+        """
         self.logger.debug("add_message_handler (alias) used")
         self._on_message_handlers.append((handler, filter))
         return handler
@@ -147,6 +211,14 @@ class HandlerMixin(ClientProtocol):
     def add_on_start_handler(
         self, handler: Callable[[], Any | Awaitable[Any]]
     ) -> Callable[[], Any | Awaitable[Any]]:
+        """
+        Добавляет обработчик, вызываемый при старте клиента.
+
+        :param handler: Функция или coroutine без аргументов.
+        :type handler: Callable[[], Any | Awaitable[Any]]
+        :return: Установленный обработчик.
+        :rtype: Callable[[], Any | Awaitable[Any]]
+        """
         self.logger.debug("add_on_start_handler (alias) used")
         self._on_start_handler = handler
         return handler
@@ -155,13 +227,65 @@ class HandlerMixin(ClientProtocol):
         self,
         handler: Callable[[str, int, ReactionInfo], Any | Awaitable[Any]],
     ) -> Callable[[str, int, ReactionInfo], Any | Awaitable[Any]]:
+        """
+        Добавляет обработчик изменения реакций на сообщения.
+
+        :param handler: Функция или coroutine с аргументами (message_id: str, chat_id: int, reaction_info: ReactionInfo).
+        :type handler: Callable[[str, int, ReactionInfo], Any | Awaitable[Any]]
+        :return: Установленный обработчик.
+        :rtype: Callable[[str, int, ReactionInfo], Any | Awaitable[Any]]
+        """
         self.logger.debug("add_reaction_change_handler (alias) used")
-        self._on_reaction_change_handlers.append((handler,))
+        self._on_reaction_change_handlers.append(
+            handler,
+        )
         return handler
 
     def add_chat_update_handler(
         self, handler: Callable[[Chat], Any | Awaitable[Any]]
     ) -> Callable[[Chat], Any | Awaitable[Any]]:
+        """
+        Добавляет обработчик обновления информации о чате.
+
+        :param handler: Функция или coroutine с аргументом (chat: Chat).
+        :type handler: Callable[[Chat], Any | Awaitable[Any]]
+        :return: Установленный обработчик.
+        :rtype: Callable[[Chat], Any | Awaitable[Any]]
+        """
         self.logger.debug("add_chat_update_handler (alias) used")
-        self._on_chat_update_handlers.append((handler,))
+        self._on_chat_update_handlers.append(handler)
+        return handler
+
+    def add_raw_receive_handler(
+        self, handler: Callable[[dict[str, Any]], Any | Awaitable[Any]]
+    ) -> Callable[[dict[str, Any]], Any | Awaitable[Any]]:
+        """
+        Добавляет обработчик для получения необработанных данных от сервера.
+
+        :param handler: Функция или coroutine с аргументом (data: dict).
+        :type handler: Callable[[dict[str, Any]], Any | Awaitable[Any]]
+        :return: Установленный обработчик.
+        :rtype: Callable[[dict[str, Any]], Any | Awaitable[Any]]
+        """
+        self.logger.debug("add_raw_receive_handler (alias) used")
+        self._on_raw_receive_handlers.append(handler)
+        return handler
+
+    def add_scheduled_task(
+        self,
+        handler: Callable[[], Any | Awaitable[Any]],
+        interval: float,
+    ) -> Callable[[], Any | Awaitable[Any]]:
+        """
+        Добавляет периодическую задачу.
+
+        :param handler: Функция или coroutine без аргументов.
+        :type handler: Callable[[], Any | Awaitable[Any]]
+        :param interval: Интервал выполнения в секундах.
+        :type interval: float
+        :return: Установленный обработчик.
+        :rtype: Callable[[], Any | Awaitable[Any]]
+        """
+        self.logger.debug("add_scheduled_task (alias) used")
+        self._scheduled_tasks.append((handler, interval))
         return handler