pyTelegramBotAPI 4.21.0__py3-none-any.whl → 4.22.1__py3-none-any.whl

{pytelegrambotapi-4.21.0.dist-info → pytelegrambotapi-4.22.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyTelegramBotAPI
-Version: 4.21.0
+Version: 4.22.1
 Summary: Python Telegram bot api.
 Project-URL: Homepage, https://github.com/eternnoir/pyTelegramBotAPI
 Project-URL: Documentation, https://pytba.readthedocs.org
@@ -23,8 +23,6 @@ Requires-Python: >=3.8
 Requires-Dist: requests
 Provides-Extra: aiohttp
 Requires-Dist: aiohttp; extra == 'aiohttp'
-Provides-Extra: aioredis
-Requires-Dist: aioredis; extra == 'aioredis'
 Provides-Extra: coloredlogs
 Requires-Dist: coloredlogs; extra == 'coloredlogs'
 Provides-Extra: fastapi
@@ -55,7 +53,7 @@ Description-Content-Type: text/markdown
 <p align="center">A simple, but extensible Python implementation for the <a href="https://core.telegram.org/bots/api">Telegram Bot API</a>.</p>
 <p align="center">Both synchronous and asynchronous.</p>
 
-## <p align="center">Supported Bot API version: <a href="https://core.telegram.org/bots/api#july-7-2024">7.6</a>!
+## <p align="center">Supported Bot API version: <a href="https://core.telegram.org/bots/api-changelog#july-31-2024"><img src="https://img.shields.io/badge/Bot%20API-7.8-blue?logo=telegram" alt="Supported Bot API version"></a>
 
 <h2><a href='https://pytba.readthedocs.io/en/latest/index.html'>Official documentation</a></h2>
 <h2><a href='https://pytba.readthedocs.io/ru/latest/index.html'>Official ru documentation</a></h2>

pytelegrambotapi-4.22.1.dist-info/RECORD

@@ -0,0 +1,41 @@
+telebot/__init__.py,sha256=ty7WzdASNMWG_cqdg4o3A-kagN9aVIGkc0j93R9reT4,412119
+telebot/apihelper.py,sha256=FJwcuzZXK54GqNmUiziobpbgrN5pwk_LcPBbkhlINf4,94286
+telebot/async_telebot.py,sha256=N5vCHak84CCjxZJCehus8eRt1TaSmUlRyzzAw_ONqYk,385225
+telebot/asyncio_filters.py,sha256=0bnF-CPOX-IZUIjViTk5lxa5OR_UxB8Z5ng0kfDq5nM,12856
+telebot/asyncio_handler_backends.py,sha256=BWS7zr93FJNZJmPHBoXo4i_PIHGlmrEoWy1miXax9aI,2785
+telebot/asyncio_helper.py,sha256=Wvd8i8KFqGizkyaL7xZfb4Woan1yphoQGFYHvdErKyw,95049
+telebot/callback_data.py,sha256=k4Rz3lAONG5J2M9TESKMIjqXoBNJMfEy9nnrmJAyi3Q,5358
+telebot/custom_filters.py,sha256=0NX8hR5EMGjOnl11sLPYwl9gwIxd9APTsxqBhxCASLM,12977
+telebot/formatting.py,sha256=_y8M5KOv9UOXfF9z7Et4fPVgh9JnzI1cr4un9sfdlc0,15176
+telebot/handler_backends.py,sha256=lyKu0PaH2c4y5FfyQS3M9tOyBJ8ATjxHZkATzu01XpE,7969
+telebot/service_utils.py,sha256=xLmlZLTVs34UOdQtMvwduor8hnLxQCx8iJ92wDGl2Mw,2053
+telebot/types.py,sha256=KiKe3WnBAGCN_65Uxe104IGG77cvpUthTzlEjwnc0r4,459391
+telebot/util.py,sha256=YLSNl9LYEmj7PxNgZN5OO3IvtR5YESvVfTsReuxZ9Zw,21361
+telebot/version.py,sha256=dvJgb3UnEA3MSfEPGopCGapphKRx6FGNQqRhsbEch3o,99
+telebot/asyncio_storage/__init__.py,sha256=fraOWJby1ddJmPAXf1oXWmZJXRodSpING17MF875NPI,433
+telebot/asyncio_storage/base_storage.py,sha256=I-NII9ZMCxCHStPc-73qSyQhjBtkhNzb2IcZPhjR1Eg,3243
+telebot/asyncio_storage/memory_storage.py,sha256=h8yc2xpfLmbcBjPmKkqNhZtUtpNQ7EuKIfMGue61e7w,5849
+telebot/asyncio_storage/pickle_storage.py,sha256=3uaQGw6jF1kF7x-qLq1VIGjya2hcEY1J9HAouDuXH4U,7647
+telebot/asyncio_storage/redis_storage.py,sha256=ruhh1jPUf0YHQWfg_QAHPEn8Vm9cvBwkybD5R7GSUDw,9897
+telebot/ext/__init__.py,sha256=_mSeNU1cib3cWSZ6Kb6nKy9znEYwEzGNRCYZsD61rLk,66
+telebot/ext/reloader.py,sha256=vzmJxCsA_COHF-bpmyddDuUXroxNih051IYRMiR21LY,826
+telebot/ext/aio/__init__.py,sha256=2yi7jtvEIH1DqAseFevfujNYi7ZSh5aPMOKGrxIgqsw,143
+telebot/ext/aio/webhooks.py,sha256=tf4DMXkKWvM_Uko_lpLRc0uDwttyZGvsvDLNNbwmO_Y,3788
+telebot/ext/sync/__init__.py,sha256=Lj-15dj1TYkf11d0vY14_2mssnoFR5Uk320huWa_rGc,140
+telebot/ext/sync/webhooks.py,sha256=XMMhXnDuFs7CWJ7iDi11H0dwf6fRA4pbAjFjNgNJ18Y,3513
+telebot/states/__init__.py,sha256=ggLBEJyMoh3i_IDpUE_jvtP7NiC7IwIR4QJXmI1BFGc,4401
+telebot/states/asyncio/__init__.py,sha256=vomgAmaY590Ul0U-oovN7-Vjf6CwrchmjAZS8PX-lqY,132
+telebot/states/asyncio/context.py,sha256=LeH1uD3NSkQ6EJ-rsSfJfA1SaQ_FnoPRWg746SwOhFI,4952
+telebot/states/asyncio/middleware.py,sha256=UZgd4Ty8JwOcj50zdI8eJ0tfPCmgiymxyaX-dR2tpVg,730
+telebot/states/sync/__init__.py,sha256=FqxubuunwknusMEAkaUwgFdIBmTZtEhRUaRZE18bzzs,131
+telebot/states/sync/context.py,sha256=mw19DPMSqPsg8e-i3ZVsp-YxZSfHfn1rpisn5smvfrM,4731
+telebot/states/sync/middleware.py,sha256=7mGC0xEQt7vjfCgmJWOKn7BXHxjQyLFoyZ1rL0blm4Q,680
+telebot/storage/__init__.py,sha256=Uagoo-sNYA0PX-hICKSaXtr4YRUOp2GPwlK1vlap9O8,401
+telebot/storage/base_storage.py,sha256=WzGgSflKzcn2ENsgz1Q-D_v-ZKCtnMOURGOHIwNJ0WU,2986
+telebot/storage/memory_storage.py,sha256=-r1vuIt1YHq9btkr6E7BCu4Do-wUDlNcttG22SSgEYo,5799
+telebot/storage/pickle_storage.py,sha256=dqw7syOJuTWyU0KK8XwbJvQ9PMyDHhZQG-MevZImEak,7121
+telebot/storage/redis_storage.py,sha256=DReU2lc8cI0f3XMIT1N9-suGZ6jE8H9I_mapK3A-lyE,9450
+pytelegrambotapi-4.22.1.dist-info/METADATA,sha256=ECBI-3IKxlXtRMzbmXv11FBTUOlP67NghcrAvQArhTk,48162
+pytelegrambotapi-4.22.1.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+pytelegrambotapi-4.22.1.dist-info/licenses/LICENSE,sha256=qz_jTTxi4zSAFaTdASiwml2iAk0UZ6R4MRADNzwYo_A,18387
+pytelegrambotapi-4.22.1.dist-info/RECORD,,

telebot/__init__.py

@@ -7,7 +7,7 @@ import sys
 import threading
 import time
 import traceback
-from typing import Any, Callable, List, Optional, Union
+from typing import Any, Callable, List, Optional, Union, Dict
 
 # these imports are used to avoid circular import error
 import telebot.util
@@ -152,9 +152,14 @@ class TeleBot:
     :param allow_sending_without_reply: Default value for allow_sending_without_reply, defaults to None
     :type allow_sending_without_reply: :obj:`bool`, optional
     
-
     :param colorful_logs: Outputs colorful logs
     :type colorful_logs: :obj:`bool`, optional
+
+    :param validate_token: Validate token, defaults to True;
+    :type validate_token: :obj:`bool`, optional
+
+    :raises ImportError: If coloredlogs module is not installed and colorful_logs is True
+    :raises ValueError: If token is invalid
     """
 
     def __init__(
@@ -168,7 +173,8 @@ class TeleBot:
             disable_notification: Optional[bool]=None,
             protect_content: Optional[bool]=None,
             allow_sending_without_reply: Optional[bool]=None,
-            colorful_logs: Optional[bool]=False
+            colorful_logs: Optional[bool]=False,
+            validate_token: Optional[bool]=True
     ):
 
         # update-related
@@ -186,6 +192,11 @@ class TeleBot:
         self.webhook_listener = None
         self._user = None
 
+        if validate_token:
+            util.validate_token(self.token)
+        
+        self.bot_id: Union[int, None] = util.extract_bot_id(self.token) # subject to change in future, unspecified
+
         # logs-related
         if colorful_logs:
             try:
@@ -280,7 +291,7 @@ class TeleBot:
         self.threaded = threaded
         if self.threaded:
             self.worker_pool = util.ThreadPool(self, num_threads=num_threads)
-    
+        
     @property
     def user(self) -> types.User:
         """
@@ -4640,7 +4651,7 @@ class TeleBot:
 
     def pin_chat_message(
             self, chat_id: Union[int, str], message_id: int, 
-            disable_notification: Optional[bool]=False) -> bool:
+            disable_notification: Optional[bool]=False, business_connection_id: Optional[str]=None) -> bool:
         """
         Use this method to pin a message in a supergroup.
         The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
@@ -4659,15 +4670,19 @@ class TeleBot:
             to all group members about the new pinned message
         :type disable_notification: :obj:`bool`
 
+        :param business_connection_id: Unique identifier of the business connection
+        :type business_connection_id: :obj:`str`
+
         :return: True on success.
         :rtype: :obj:`bool`
         """
         disable_notification = self.disable_notification if (disable_notification is None) else disable_notification
 
-        return apihelper.pin_chat_message(self.token, chat_id, message_id, disable_notification=disable_notification)
+        return apihelper.pin_chat_message(self.token, chat_id, message_id, disable_notification=disable_notification,
+                                            business_connection_id=business_connection_id)
 
 
-    def unpin_chat_message(self, chat_id: Union[int, str], message_id: Optional[int]=None) -> bool:
+    def unpin_chat_message(self, chat_id: Union[int, str], message_id: Optional[int]=None, business_connection_id: Optional[str]=None) -> bool:
         """
         Use this method to unpin specific pinned message in a supergroup chat.
         The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
@@ -4682,10 +4697,13 @@ class TeleBot:
         :param message_id: Int: Identifier of a message to unpin
         :type message_id: :obj:`int`
 
+        :param business_connection_id: Unique identifier of the business connection
+        :type business_connection_id: :obj:`str`
+
         :return: True on success.
         :rtype: :obj:`bool`
         """
-        return apihelper.unpin_chat_message(self.token, chat_id, message_id)
+        return apihelper.unpin_chat_message(self.token, chat_id, message_id, business_connection_id=business_connection_id)
 
 
     def unpin_all_chat_messages(self, chat_id: Union[int, str]) -> bool:
@@ -6634,7 +6652,9 @@ class TeleBot:
         self.middlewares.append(middleware)
 
 
-    def set_state(self, user_id: int, state: Union[int, str, State], chat_id: Optional[int]=None) -> None:
+    def set_state(self, user_id: int, state: Union[str, State], chat_id: Optional[int]=None,
+                    business_connection_id: Optional[str]=None, message_thread_id: Optional[int]=None,
+                    bot_id: Optional[int]=None) -> bool:
         """
         Sets a new state of a user.
 
@@ -6644,25 +6664,49 @@ class TeleBot:
             Otherwise, if you only set user_id, chat_id will equal to user_id, this means that
             state will be set for the user in his private chat with a bot.
 
+        .. versionchanged:: 4.23.0
+
+            Added additional parameters to support topics, business connections, and message threads.
+
+        .. seealso:: 
+        
+            For more details, visit the `custom_states.py example <https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/custom_states.py>`_.
+
         :param user_id: User's identifier
         :type user_id: :obj:`int`
 
-        :param state: new state. can be string, integer, or :class:`telebot.types.State`
+        :param state: new state. can be string, or :class:`telebot.types.State`
         :type state: :obj:`int` or :obj:`str` or :class:`telebot.types.State`
 
         :param chat_id: Chat's identifier
         :type chat_id: :obj:`int`
 
-        :return: None
+        :param bot_id: Bot's identifier, defaults to current bot id
+        :type bot_id: :obj:`int`
+
+        :param business_connection_id: Business identifier
+        :type business_connection_id: :obj:`str`
+
+        :param message_thread_id: Identifier of the message thread
+        :type message_thread_id: :obj:`int`
+
+        :return: True on success
+        :rtype: :obj:`bool`
         """
         if chat_id is None:
             chat_id = user_id
-        self.current_states.set_state(chat_id, user_id, state)
+        if bot_id is None:
+            bot_id = self.bot_id
+        return self.current_states.set_state(
+            chat_id=chat_id, user_id=user_id, state=state, bot_id=bot_id,
+            business_connection_id=business_connection_id, message_thread_id=message_thread_id)
 
 
-    def reset_data(self, user_id: int, chat_id: Optional[int]=None):
+    def reset_data(self, user_id: int, chat_id: Optional[int]=None, 
+                     business_connection_id: Optional[str]=None,
+                     message_thread_id: Optional[int]=None, bot_id: Optional[int]=None) -> bool:
         """
-        Reset data for a user in chat.
+        Reset data for a user in chat: sets the 'data' field to an empty dictionary.
 
         :param user_id: User's identifier
         :type user_id: :obj:`int`
@@ -6670,16 +6714,34 @@ class TeleBot:
         :param chat_id: Chat's identifier
         :type chat_id: :obj:`int`
 
-        :return: None
+        :param bot_id: Bot's identifier, defaults to current bot id
+        :type bot_id: :obj:`int`
+
+        :param business_connection_id: Business identifier
+        :type business_connection_id: :obj:`str`
+
+        :param message_thread_id: Identifier of the message thread
+        :type message_thread_id: :obj:`int`
+
+        :return: True on success
+        :rtype: :obj:`bool`
         """
         if chat_id is None:
             chat_id = user_id
-        self.current_states.reset_data(chat_id, user_id)
+        if bot_id is None:
+            bot_id = self.bot_id
+        return self.current_states.reset_data(chat_id=chat_id, user_id=user_id, bot_id=bot_id,
+                                        business_connection_id=business_connection_id, message_thread_id=message_thread_id)
 
 
-    def delete_state(self, user_id: int, chat_id: Optional[int]=None) -> None:
+    def delete_state(self, user_id: int, chat_id: Optional[int]=None, business_connection_id: Optional[str]=None,
+                     message_thread_id: Optional[int]=None, bot_id: Optional[int]=None) -> bool:
         """
-        Delete the current state of a user.
+        Fully deletes the storage record of a user in chat.
+
+        .. warning::
+
+            This does NOT set state to None, but deletes the object from storage.
 
         :param user_id: User's identifier
         :type user_id: :obj:`int`
@@ -6687,14 +6749,19 @@ class TeleBot:
         :param chat_id: Chat's identifier
         :type chat_id: :obj:`int`
 
-        :return: None
+        :return: True on success
+        :rtype: :obj:`bool`
         """
         if chat_id is None:
             chat_id = user_id
-        self.current_states.delete_state(chat_id, user_id)
+        if bot_id is None:
+            bot_id = self.bot_id
+        return self.current_states.delete_state(chat_id=chat_id, user_id=user_id, bot_id=bot_id,
+                                            business_connection_id=business_connection_id, message_thread_id=message_thread_id)
 
 
-    def retrieve_data(self, user_id: int, chat_id: Optional[int]=None) -> Optional[Any]:
+    def retrieve_data(self, user_id: int, chat_id: Optional[int]=None, business_connection_id: Optional[str]=None,
+                      message_thread_id: Optional[int]=None, bot_id: Optional[int]=None) -> Optional[Dict[str, Any]]:
         """
         Returns context manager with data for a user in chat.
 
@@ -6704,34 +6771,70 @@ class TeleBot:
         :param chat_id: Chat's unique identifier, defaults to user_id
         :type chat_id: int, optional
 
+        :param bot_id: Bot's identifier, defaults to current bot id
+        :type bot_id: int, optional
+
+        :param business_connection_id: Business identifier
+        :type business_connection_id: str, optional
+
+        :param message_thread_id: Identifier of the message thread
+        :type message_thread_id: int, optional
+
         :return: Context manager with data for a user in chat
         :rtype: Optional[Any]
         """
         if chat_id is None:
             chat_id = user_id
-        return self.current_states.get_interactive_data(chat_id, user_id)
+        if bot_id is None:
+            bot_id = self.bot_id
+        return self.current_states.get_interactive_data(chat_id=chat_id, user_id=user_id, bot_id=bot_id,
+                                                            business_connection_id=business_connection_id,
+                                                            message_thread_id=message_thread_id)
 
 
-    def get_state(self, user_id: int, chat_id: Optional[int]=None) -> Optional[Union[int, str, State]]:
+    def get_state(self, user_id: int, chat_id: Optional[int]=None, 
+                    business_connection_id: Optional[str]=None,
+                    message_thread_id: Optional[int]=None, bot_id: Optional[int]=None) -> str:
         """
         Gets current state of a user.
         Not recommended to use this method. But it is ok for debugging.
 
+        .. warning::
+
+            Even if you are using :class:`telebot.types.State`, this method will return a string.
+            When comparing(not recommended), you should compare this string with :class:`telebot.types.State`.name
+
         :param user_id: User's identifier
         :type user_id: :obj:`int`
 
         :param chat_id: Chat's identifier
         :type chat_id: :obj:`int`
 
+        :param bot_id: Bot's identifier, defaults to current bot id
+        :type bot_id: :obj:`int`
+
+        :param business_connection_id: Business identifier
+        :type business_connection_id: :obj:`str`
+
+        :param message_thread_id: Identifier of the message thread
+        :type message_thread_id: :obj:`int`
+
         :return: state of a user
         :rtype: :obj:`int` or :obj:`str` or :class:`telebot.types.State`
         """
         if chat_id is None:
             chat_id = user_id
-        return self.current_states.get_state(chat_id, user_id)
+        if bot_id is None:
+            bot_id = self.bot_id
+        return self.current_states.get_state(chat_id=chat_id, user_id=user_id, bot_id=bot_id,
+                                                business_connection_id=business_connection_id, message_thread_id=message_thread_id)
 
 
-    def add_data(self, user_id: int, chat_id: Optional[int]=None, **kwargs):
+    def add_data(self, user_id: int, chat_id: Optional[int]=None, 
+                    business_connection_id: Optional[str]=None,
+                    message_thread_id: Optional[int]=None, 
+                    bot_id: Optional[int]=None,
+                    **kwargs) -> None:
         """
         Add data to states.
 
@@ -6741,13 +6844,25 @@ class TeleBot:
         :param chat_id: Chat's identifier
         :type chat_id: :obj:`int`
 
+        :param bot_id: Bot's identifier, defaults to current bot id
+        :type bot_id: :obj:`int`
+
+        :param business_connection_id: Business identifier
+        :type business_connection_id: :obj:`str`
+
+        :param message_thread_id: Identifier of the message thread
+        :type message_thread_id: :obj:`int`
+
         :param kwargs: Data to add
         :return: None
         """
         if chat_id is None:
             chat_id = user_id
+        if bot_id is None:
+            bot_id = self.bot_id
         for key, value in kwargs.items():
-            self.current_states.set_data(chat_id, user_id, key, value)
+            self.current_states.set_data(chat_id=chat_id, user_id=user_id, key=key, value=value, bot_id=bot_id,
+                                            business_connection_id=business_connection_id, message_thread_id=message_thread_id)
 
 
     def register_next_step_handler_by_chat_id(
@@ -7700,7 +7815,7 @@ class TeleBot:
         self.add_chosen_inline_handler(handler_dict)
 
 
-    def callback_query_handler(self, func, **kwargs):
+    def callback_query_handler(self, func=None, **kwargs):
         """
         Handles new incoming callback query.
         As a parameter to the decorator function, it passes :class:`telebot.types.CallbackQuery` object.

telebot/apihelper.py

@@ -1386,19 +1386,23 @@ def set_chat_description(token, chat_id, description):
     return _make_request(token, method_url, params=payload, method='post')
 
 
-def pin_chat_message(token, chat_id, message_id, disable_notification=None):
+def pin_chat_message(token, chat_id, message_id, disable_notification=None, business_connection_id=None):
     method_url = 'pinChatMessage'
     payload = {'chat_id': chat_id, 'message_id': message_id}
     if disable_notification is not None:
         payload['disable_notification'] = disable_notification
+    if business_connection_id:
+        payload['business_connection_id'] = business_connection_id
     return _make_request(token, method_url, params=payload, method='post')
 
 
-def unpin_chat_message(token, chat_id, message_id):
+def unpin_chat_message(token, chat_id, message_id, business_connection_id=None):
     method_url = 'unpinChatMessage'
     payload = {'chat_id': chat_id}
     if message_id:
         payload['message_id'] = message_id
+    if business_connection_id:
+        payload['business_connection_id'] = business_connection_id
     return _make_request(token, method_url, params=payload, method='post')