From c8fb83c97cab4e2d120dec067830b52d0325ee89 Mon Sep 17 00:00:00 2001 From: coder2020official Date: Mon, 7 Mar 2022 14:24:28 +0500 Subject: [PATCH] Fix documentation --- docs/source/async_version/index.rst | 8 --- docs/source/index.rst | 2 +- docs/source/install.rst | 2 - docs/source/sync_version/index.rst | 8 --- telebot/__init__.py | 65 ++++++++++---------- telebot/async_telebot.py | 92 ++++++++++++++--------------- telebot/types.py | 14 ++--- telebot/util.py | 50 +++++++++------- 8 files changed, 113 insertions(+), 128 deletions(-) diff --git a/docs/source/async_version/index.rst b/docs/source/async_version/index.rst index 6b53c6a..0e0418f 100644 --- a/docs/source/async_version/index.rst +++ b/docs/source/async_version/index.rst @@ -28,14 +28,6 @@ Asynchronous storage for states :undoc-members: :show-inheritance: -asyncio_helper file -------------------- - -.. automodule:: telebot.asyncio_helper - :members: - :undoc-members: - :show-inheritance: - Asyncio handler backends ------------------------ diff --git a/docs/source/index.rst b/docs/source/index.rst index 98efb79..596f901 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -25,7 +25,7 @@ Pypi: `Pypi `__ Source: `Github repository `__ Some features: -------------- +-------------- Easy to learn and use. Easy to understand. diff --git a/docs/source/install.rst b/docs/source/install.rst index f2589c9..7998ff8 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -3,8 +3,6 @@ Installation Guide ================== -:toctree - Using PIP ---------- .. code-block:: bash diff --git a/docs/source/sync_version/index.rst b/docs/source/sync_version/index.rst index 84e490d..590cfe5 100644 --- a/docs/source/sync_version/index.rst +++ b/docs/source/sync_version/index.rst @@ -33,11 +33,3 @@ handler_backends file :undoc-members: :show-inheritance: -apihelper ------------------------- - -.. automodule:: telebot.apihelper - :members: - :undoc-members: - :show-inheritance: - diff --git a/telebot/__init__.py b/telebot/__init__.py index eec844b..cf1be1f 100644 --- a/telebot/__init__.py +++ b/telebot/__init__.py @@ -343,7 +343,7 @@ class TeleBot: :param offset: Integer. Identifier of the first update to be returned. :param limit: Integer. Limits the number of updates to be retrieved. :param timeout: Integer. Request connection timeout - :param long_polling_timeout. Timeout in seconds for long polling. + :param long_polling_timeout: Timeout in seconds for long polling. :return: array of Updates """ json_updates = apihelper.get_updates(self.token, offset, limit, timeout, allowed_updates, long_polling_timeout) @@ -876,7 +876,7 @@ class TeleBot: """ Use this method to get a list of administrators in a chat. On success, returns an Array of ChatMember objects that contains - information about all chat administrators except other bots. + information about all chat administrators except other bots. Telegram documentation: https://core.telegram.org/bots/api#getchatadministrators @@ -932,8 +932,7 @@ class TeleBot: Telegram documentation: https://core.telegram.org/bots/api#deletechatstickerset - :param chat_id: Unique identifier for the target chat or username of the target supergroup - (in the format @supergroupusername) + :param chat_id: Unique identifier for the target chat or username of the target supergroup (in the format @supergroupusername) :return: API reply. """ result = apihelper.delete_chat_sticker_set(self.token, chat_id) @@ -1199,7 +1198,7 @@ class TeleBot: :param duration: Duration of sent audio in seconds :param reply_to_message_id: :param reply_markup: - :param parse_mode + :param parse_mode: :param disable_notification: :param timeout: :param caption_entities: @@ -1663,7 +1662,7 @@ class TeleBot: :return: API reply. :type: boolean """ return apihelper.send_chat_action(self.token, chat_id, action, timeout) - + def kick_chat_member( self, chat_id: Union[int, str], user_id: int, until_date:Optional[Union[int, datetime]]=None, @@ -1742,11 +1741,10 @@ class TeleBot: If user is restricted for more than 366 days or less than 30 seconds from the current time, they are considered to be restricted forever :param can_send_messages: Pass True, if the user can send text messages, contacts, locations and venues - :param can_send_media_messages Pass True, if the user can send audios, documents, photos, videos, video notes + :param can_send_media_messages: Pass True, if the user can send audios, documents, photos, videos, video notes and voice notes, implies can_send_messages :param can_send_polls: Pass True, if the user is allowed to send polls, implies can_send_messages - :param can_send_other_messages: Pass True, if the user can send animations, games, stickers and - use inline bots, implies can_send_media_messages + :param can_send_other_messages: Pass True, if the user can send animations, games, stickers and use inline bots, implies can_send_media_messages :param can_add_web_page_previews: Pass True, if the user may add web page previews to their messages, implies can_send_media_messages :param can_change_info: Pass True, if the user is allowed to change the chat title, photo and other settings. @@ -1932,7 +1930,7 @@ class TeleBot: """ Use this method to revoke an invite link created by the bot. Note: If the primary link is revoked, a new link is automatically generated The bot must be an administrator - in the chat for this to work and must have the appropriate admin rights. + in the chat for this to work and must have the appropriate admin rights. Telegram documentation: https://core.telegram.org/bots/api#revokechatinvitelink @@ -1994,7 +1992,7 @@ class TeleBot: The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success. Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’ - setting is off in the target group. + setting is off in the target group. Telegram documentation: https://core.telegram.org/bots/api#setchatphoto @@ -2010,8 +2008,7 @@ class TeleBot: Use this method to delete a chat photo. Photos can't be changed for private chats. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success. - Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’ - setting is off in the target group. + Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’ setting is off in the target group. Telegram documentation: https://core.telegram.org/bots/api#deletechatphoto @@ -2078,7 +2075,7 @@ class TeleBot: The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success. Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’ - setting is off in the target group. + setting is off in the target group. Telegram documentation: https://core.telegram.org/bots/api#setchattitle @@ -2989,30 +2986,32 @@ class TeleBot: All message handlers are tested in the order they were added. Example: + + .. code-block:: python - bot = TeleBot('TOKEN') + bot = TeleBot('TOKEN') - # Handles all messages which text matches regexp. - @bot.message_handler(regexp='someregexp') - def command_help(message): - bot.send_message(message.chat.id, 'Did someone call for help?') + # Handles all messages which text matches regexp. + @bot.message_handler(regexp='someregexp') + def command_help(message): + bot.send_message(message.chat.id, 'Did someone call for help?') - # Handles messages in private chat - @bot.message_handler(chat_types=['private']) # You can add more chat types - def command_help(message): - bot.send_message(message.chat.id, 'Private chat detected, sir!') + # Handles messages in private chat + @bot.message_handler(chat_types=['private']) # You can add more chat types + def command_help(message): + bot.send_message(message.chat.id, 'Private chat detected, sir!') - # Handle all sent documents of type 'text/plain'. - @bot.message_handler(func=lambda message: message.document.mime_type == 'text/plain', - content_types=['document']) - def command_handle_document(message): - bot.send_message(message.chat.id, 'Document received, sir!') + # Handle all sent documents of type 'text/plain'. + @bot.message_handler(func=lambda message: message.document.mime_type == 'text/plain', + content_types=['document']) + def command_handle_document(message): + bot.send_message(message.chat.id, 'Document received, sir!') - # Handle all other messages. - @bot.message_handler(func=lambda message: True, content_types=['audio', 'photo', 'voice', 'video', 'document', - 'text', 'location', 'contact', 'sticker']) - def default_command(message): - bot.send_message(message.chat.id, "This is the default command handler.") + # Handle all other messages. + @bot.message_handler(func=lambda message: True, content_types=['audio', 'photo', 'voice', 'video', 'document', + 'text', 'location', 'contact', 'sticker']) + def default_command(message): + bot.send_message(message.chat.id, "This is the default command handler.") :param commands: Optional list of strings (commands to handle). :param regexp: Optional regular expression. diff --git a/telebot/async_telebot.py b/telebot/async_telebot.py index 8305931..f654083 100644 --- a/telebot/async_telebot.py +++ b/telebot/async_telebot.py @@ -584,29 +584,31 @@ class AsyncTeleBot: Example: - bot = TeleBot('TOKEN') + .. code-block:: python - # Handles all messages which text matches regexp. - @bot.message_handler(regexp='someregexp') - async def command_help(message): - bot.send_message(message.chat.id, 'Did someone call for help?') + bot = TeleBot('TOKEN') - # Handles messages in private chat - @bot.message_handler(chat_types=['private']) # You can add more chat types - async def command_help(message): - bot.send_message(message.chat.id, 'Private chat detected, sir!') + # Handles all messages which text matches regexp. + @bot.message_handler(regexp='someregexp') + async def command_help(message): + bot.send_message(message.chat.id, 'Did someone call for help?') - # Handle all sent documents of type 'text/plain'. - @bot.message_handler(func=lambda message: message.document.mime_type == 'text/plain', - content_types=['document']) - async def command_handle_document(message): - bot.send_message(message.chat.id, 'Document received, sir!') + # Handles messages in private chat + @bot.message_handler(chat_types=['private']) # You can add more chat types + async def command_help(message): + bot.send_message(message.chat.id, 'Private chat detected, sir!') - # Handle all other messages. - @bot.message_handler(func=lambda message: True, content_types=['audio', 'photo', 'voice', 'video', 'document', - 'text', 'location', 'contact', 'sticker']) - async def async default_command(message): - bot.send_message(message.chat.id, "This is the async default command handler.") + # Handle all sent documents of type 'text/plain'. + @bot.message_handler(func=lambda message: message.document.mime_type == 'text/plain', + content_types=['document']) + async def command_handle_document(message): + bot.send_message(message.chat.id, 'Document received, sir!') + + # Handle all other messages. + @bot.message_handler(func=lambda message: True, content_types=['audio', 'photo', 'voice', 'video', 'document', + 'text', 'location', 'contact', 'sticker']) + async def async default_command(message): + bot.send_message(message.chat.id, "This is the async default command handler.") :param commands: Optional list of strings (commands to handle). :param regexp: Optional regular expression. @@ -950,6 +952,7 @@ class AsyncTeleBot: """ Description: TBD + :param func: :param kwargs: :return: @@ -1487,13 +1490,12 @@ class AsyncTeleBot: """ Use this method to get a list of administrators in a chat. On success, returns an Array of ChatMember objects that contains - information about all chat administrators except other bots. + information about all chat administrators except other bots. Telegram documentation: https://core.telegram.org/bots/api#getchatadministrators - :param chat_id: Unique identifier for the target chat or username - of the target supergroup or channel (in the format @channelusername) - :return: + :param chat_id: Unique identifier for the target chat or username of the target supergroup or channel (in the format @channelusername) + :return: API reply. """ result = await asyncio_helper.get_chat_administrators(self.token, chat_id) return [types.ChatMember.de_json(r) for r in result] @@ -1527,10 +1529,9 @@ class AsyncTeleBot: Telegram documentation: https://core.telegram.org/bots/api#setchatstickerset - :param chat_id: Unique identifier for the target chat or username of the target supergroup - (in the format @supergroupusername) + :param chat_id: Unique identifier for the target chat or username of the target supergroup (in the format @supergroupusername) :param sticker_set_name: Name of the sticker set to be set as the group sticker set - :return: + :return: API reply. """ result = await asyncio_helper.set_chat_sticker_set(self.token, chat_id, sticker_set_name) return result @@ -1543,8 +1544,7 @@ class AsyncTeleBot: Telegram documentation: https://core.telegram.org/bots/api#deletechatstickerset - :param chat_id: Unique identifier for the target chat or username of the target supergroup - (in the format @supergroupusername) + :param chat_id: Unique identifier for the target chat or username of the target supergroup (in the format @supergroupusername) :return: API reply. """ result = await asyncio_helper.delete_chat_sticker_set(self.token, chat_id) @@ -1767,10 +1767,10 @@ class AsyncTeleBot: :param caption: :param duration: Duration of the audio in seconds :param performer: Performer - :param title:Track name + :param title: Track name :param reply_to_message_id: If the message is a reply, ID of the original message :param reply_markup: - :param parse_mode + :param parse_mode: :param disable_notification: :param timeout: :param thumb: @@ -1810,7 +1810,7 @@ class AsyncTeleBot: :param duration: Duration of sent audio in seconds :param reply_to_message_id: :param reply_markup: - :param parse_mode + :param parse_mode: :param disable_notification: :param timeout: :param caption_entities: @@ -2338,24 +2338,23 @@ class AsyncTeleBot: Telegram documentation: https://core.telegram.org/bots/api#restrictchatmember - :param chat_id: Int or String : Unique identifier for the target group or username of the target supergroup - or channel (in the format @channelusername) + :param chat_id: Int or String : Unique identifier for the target group or username of the target supergroup or channel (in the format @channelusername) :param user_id: Int : Unique identifier of the target user :param until_date: Date when restrictions will be lifted for the user, unix time. If user is restricted for more than 366 days or less than 30 seconds from the current time, they are considered to be restricted forever :param can_send_messages: Pass True, if the user can send text messages, contacts, locations and venues :param can_send_media_messages Pass True, if the user can send audios, documents, photos, videos, video notes - and voice notes, implies can_send_messages + and voice notes, implies can_send_messages :param can_send_polls: Pass True, if the user is allowed to send polls, implies can_send_messages :param can_send_other_messages: Pass True, if the user can send animations, games, stickers and - use inline bots, implies can_send_media_messages + use inline bots, implies can_send_media_messages :param can_add_web_page_previews: Pass True, if the user may add web page previews to their messages, - implies can_send_media_messages + implies can_send_media_messages :param can_change_info: Pass True, if the user is allowed to change the chat title, photo and other settings. - Ignored in public supergroups + Ignored in public supergroups :param can_invite_users: Pass True, if the user is allowed to invite new users to the chat, - implies can_invite_users + implies can_invite_users :param can_pin_messages: Pass True, if the user is allowed to pin messages. Ignored in public supergroups :return: True on success """ @@ -2536,14 +2535,13 @@ class AsyncTeleBot: """ Use this method to revoke an invite link created by the bot. Note: If the primary link is revoked, a new link is automatically generated The bot must be an administrator - in the chat for this to work and must have the appropriate admin rights. + in the chat for this to work and must have the appropriate admin rights. Telegram documentation: https://core.telegram.org/bots/api#revokechatinvitelink - :param chat_id: Id: Unique identifier for the target chat or username of the target channel - (in the format @channelusername) + :param chat_id: Id: Unique identifier for the target chat or username of the target channel(in the format @channelusername) :param invite_link: The invite link to revoke - :return: + :return: API reply. """ return types.ChatInviteLink.de_json( await asyncio_helper.revoke_chat_invite_link(self.token, chat_id, invite_link) @@ -2598,13 +2596,11 @@ class AsyncTeleBot: Use this method to set a new profile photo for the chat. Photos can't be changed for private chats. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success. - Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’ - setting is off in the target group. + Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’ setting is off in the target group. Telegram documentation: https://core.telegram.org/bots/api#setchatphoto - :param chat_id: Int or Str: Unique identifier for the target chat or username of the target channel - (in the format @channelusername) + :param chat_id: Int or Str: Unique identifier for the target chat or username of the target channel (in the format @channelusername) :param photo: InputFile: New chat photo, uploaded using multipart/form-data :return: """ @@ -2616,7 +2612,7 @@ class AsyncTeleBot: The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success. Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’ - setting is off in the target group. + setting is off in the target group. Telegram documentation: https://core.telegram.org/bots/api#deletechatphoto @@ -2683,7 +2679,7 @@ class AsyncTeleBot: The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success. Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’ - setting is off in the target group. + setting is off in the target group. Telegram documentation: https://core.telegram.org/bots/api#setchattitle diff --git a/telebot/types.py b/telebot/types.py index 15cd2d1..081c0ed 100644 --- a/telebot/types.py +++ b/telebot/types.py @@ -1041,9 +1041,9 @@ class InlineKeyboardMarkup(Dictionaryable, JsonSerializable, JsonDeserializable) def __init__(self, keyboard=None, row_width=3): """ This object represents an inline keyboard that appears - right next to the message it belongs to. + right next to the message it belongs to. - :return: + :return: None """ if row_width > self.max_row_keys: # Todo: Will be replaced with Exception in future releases @@ -1058,10 +1058,10 @@ class InlineKeyboardMarkup(Dictionaryable, JsonSerializable, JsonDeserializable) This method adds buttons to the keyboard without exceeding row_width. E.g. InlineKeyboardMarkup.add("A", "B", "C") yields the json result: - {keyboard: [["A"], ["B"], ["C"]]} + {keyboard: [["A"], ["B"], ["C"]]} when row_width is set to 1. When row_width is set to 2, the result: - {keyboard: [["A", "B"], ["C"]]} + {keyboard: [["A", "B"], ["C"]]} See https://core.telegram.org/bots/api#inlinekeyboardmarkup :param args: Array of InlineKeyboardButton to append to the keyboard @@ -1085,10 +1085,10 @@ class InlineKeyboardMarkup(Dictionaryable, JsonSerializable, JsonDeserializable) def row(self, *args): """ Adds a list of InlineKeyboardButton to the keyboard. - This method does not consider row_width. + This method does not consider row_width. InlineKeyboardMarkup.row("A").row("B", "C").to_json() outputs: - '{keyboard: [["A"], ["B", "C"]]}' + '{keyboard: [["A"], ["B", "C"]]}' See https://core.telegram.org/bots/api#inlinekeyboardmarkup :param args: Array of InlineKeyboardButton to append to the keyboard @@ -1100,7 +1100,7 @@ class InlineKeyboardMarkup(Dictionaryable, JsonSerializable, JsonDeserializable) def to_json(self): """ Converts this object to its json representation - following the Telegram API guidelines described here: + following the Telegram API guidelines described here: https://core.telegram.org/bots/api#inlinekeyboardmarkup :return: """ diff --git a/telebot/util.py b/telebot/util.py index bec0411..f7e9e4a 100644 --- a/telebot/util.py +++ b/telebot/util.py @@ -350,24 +350,27 @@ def quick_markup(values: Dict[str, Dict[str, Any]], row_width: int=2) -> types.I This is useful to avoid always typing 'btn1 = InlineKeyboardButton(...)' 'btn2 = InlineKeyboardButton(...)' Example: - quick_markup({ - 'Twitter': {'url': 'https://twitter.com'}, - 'Facebook': {'url': 'https://facebook.com'}, - 'Back': {'callback_data': 'whatever'} - }, row_width=2): - returns an InlineKeyboardMarkup with two buttons in a row, one leading to Twitter, the other to facebook - and a back button below - kwargs can be: - { - 'url': None, - 'callback_data': None, - 'switch_inline_query': None, - 'switch_inline_query_current_chat': None, - 'callback_game': None, - 'pay': None, - 'login_url': None - } + .. code-block:: python + + quick_markup({ + 'Twitter': {'url': 'https://twitter.com'}, + 'Facebook': {'url': 'https://facebook.com'}, + 'Back': {'callback_data': 'whatever'} + }, row_width=2): + # returns an InlineKeyboardMarkup with two buttons in a row, one leading to Twitter, the other to facebook + # and a back button below + + # kwargs can be: + { + 'url': None, + 'callback_data': None, + 'switch_inline_query': None, + 'switch_inline_query_current_chat': None, + 'callback_game': None, + 'pay': None, + 'login_url': None + } :param values: a dict containing all buttons to create in this format: {text: kwargs} {str:} :param row_width: int row width @@ -484,12 +487,17 @@ def antiflood(function, *args, **kwargs): """ Use this function inside loops in order to avoid getting TooManyRequests error. Example: - - from telebot.util import antiflood - for chat_id in chat_id_list: + + .. code-block:: python3 + + from telebot.util import antiflood + for chat_id in chat_id_list: msg = antiflood(bot.send_message, chat_id, text) - You want get the + :param function: + :param args: + :param kwargs: + :return: None """ from telebot.apihelper import ApiTelegramException from time import sleep