From 7d893fd04b451cad1f640d37e9eabc859f80eb4d Mon Sep 17 00:00:00 2001 From: Bibo-Joshi Date: Sun, 14 Mar 2021 16:46:37 +0100 Subject: [PATCH] Doc Fixes (#2404) * Improve some badges for PTB-Raw * doc fix for add_error_handler * Some rendering * Bump sphinx dependency * Change signature annotation setting * fix: chat_id can be string, message_id only int * feat: add RTD link to documentation * improving sender chat docstring (#2412) * fix: improving sender chat docstring also adding a note to a weird edge case * fix: words being hard * Add note on donations * typo * typo in User.get_profile_pictures docstrings * Fix: meth, not attr for meth, not attr * filters + inlinequery doc fix * Bump versions, update RTD config file * Try fix build * Revert "fix: chat_id can be string, message_id only int" This reverts commit ba04e5aa * Add Starry & Harshil to credits Co-authored-by: poolitzer <25934244+Poolitzer@users.noreply.github.com> Co-authored-by: Harshil --- .github/CONTRIBUTING.rst | 3 + .readthedocs.yml | 22 +++-- AUTHORS.rst | 12 ++- README.rst | 5 ++ README_RAW.rst | 5 ++ docs/requirements-docs.txt | 4 +- docs/source/conf.py | 4 +- telegram/bot.py | 158 ++++++++++++++++----------------- telegram/ext/filters.py | 16 ++-- telegram/inline/inlinequery.py | 2 +- telegram/user.py | 2 +- 11 files changed, 136 insertions(+), 97 deletions(-) diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index e0923ed42..7aaf44360 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -50,6 +50,8 @@ Instructions for making a code change The central development branch is ``master``, which should be clean and ready for release at any time. In general, all changes should be done as feature branches based off of ``master``. +If you want to do solely documentation changes, base them and PR to the branch ``doc-fixes``. This branch also has its own `RTD build`_. + Here's how to make a one-off code change. 1. **Choose a descriptive branch name.** It should be lowercase, hyphen-separated, and a noun describing the change (so, ``fuzzy-rules``, but not ``implement-fuzzy-rules``). Also, it shouldn't start with ``hotfix`` or ``release``. @@ -250,3 +252,4 @@ break the API classes. For example: .. _`here`: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html .. _`Black`: https://black.readthedocs.io/en/stable/index.html .. _`popular editors`: https://black.readthedocs.io/en/stable/editor_integration.html +.. _`RTD build`: https://python-telegram-bot.readthedocs.io/en/doc-fixes diff --git a/.readthedocs.yml b/.readthedocs.yml index ca5916374..41af24d63 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,10 +1,22 @@ -# syntax: https://docs.readthedocs.io/en/latest/yaml-config.html +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/source/conf.py + +# Optionally build your docs in additional formats such as PDF formats: - - pdf + - pdf +# Optionally set the version of Python and requirements required to build your docs python: - setup_py_install: true version: 3 - -requirements_file: docs/requirements-docs.txt + install: + - method: pip + path: . + - requirements: docs/requirements-docs.txt diff --git a/AUTHORS.rst b/AUTHORS.rst index 4a584a310..80ef7b6d9 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -2,12 +2,20 @@ Credits ======= ``python-telegram-bot`` was originally created by -`Leandro Toledo `_ and is now maintained by `Hinrich Mahler `_. +`Leandro Toledo `_. +The current development team includes + +- `Hinrich Mahler `_ (maintainer) +- `Poolitzer `_ (community liaison) +- `Shivam `_ +- `Harshil `_ + Emeritus maintainers include `Jannes Höke `_ (`@jh0ker `_ on Telegram), `Noam Meltzer `_, `Pieter Schutz `_ and `Jasmin Bom `_. -The maintainers are actively supported by `Poolitzer `_ in terms of development and community liaison. +Vendored packages +----------------- We're vendoring urllib3 as part of ``python-telegram-bot`` which is distributed under the MIT license. For more info, full credits & license terms, the sources can be found here: diff --git a/README.rst b/README.rst index 8338df67d..4a1f18fa2 100644 --- a/README.rst +++ b/README.rst @@ -230,6 +230,11 @@ Contributing Contributions of all sizes are welcome. Please review our `contribution guidelines `_ to get started. You can also help by `reporting bugs `_. +======== +Donating +======== +Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead. + ======= License ======= diff --git a/README_RAW.rst b/README_RAW.rst index 9fd11b173..37b4b6ec9 100644 --- a/README_RAW.rst +++ b/README_RAW.rst @@ -212,6 +212,11 @@ Contributing Contributions of all sizes are welcome. Please review our `contribution guidelines `_ to get started. You can also help by `reporting bugs `_. +======== +Donating +======== +Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead. + ======= License ======= diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index 14472252a..7347ad9b0 100644 --- a/docs/requirements-docs.txt +++ b/docs/requirements-docs.txt @@ -1,3 +1,3 @@ -sphinx>=1.7.9 -sphinx_rtd_theme +sphinx==3.5.2 +sphinx_rtd_theme==0.5.1 sphinx-pypi-upload diff --git a/docs/source/conf.py b/docs/source/conf.py index fd74c3a02..5e70444a2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -24,7 +24,7 @@ sys.path.insert(0, os.path.abspath('../..')) # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '1.7.9' +needs_sphinx = '3.5.2' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -35,7 +35,7 @@ extensions = [ ] # Don't show type hints in the signature - that just makes it hardly readable # and we document the types anyway -autodoc_typehints = 'description' +autodoc_typehints = 'none' # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/telegram/bot.py b/telegram/bot.py index cf1b16d3c..37488e7c9 100644 --- a/telegram/bot.py +++ b/telegram/bot.py @@ -1574,7 +1574,7 @@ class Bot(TelegramObject): ) -> Union[Message, bool]: """Use this method to edit live location messages sent by the bot or via the bot (for inline bots). A location can be edited until its :attr:`live_period` expires or - editing is explicitly disabled by a call to :attr:`stop_message_live_location`. + editing is explicitly disabled by a call to :meth:`stop_message_live_location`. Note: You can either supply a :obj:`latitude` and :obj:`longitude` or a :obj:`location`. @@ -2200,7 +2200,7 @@ class Bot(TelegramObject): """ Use this method to get basic info about a file and prepare it for downloading. For the moment, bots can download files of up to 20MB in size. The file can then be downloaded - with :attr:`telegram.File.download`. It is guaranteed that the link will be + with :meth:`telegram.File.download`. It is guaranteed that the link will be valid for at least 1 hour. When the link expires, a new one can be requested by calling get_file again. @@ -3074,7 +3074,7 @@ class Bot(TelegramObject): """Use this method to set a new group sticker set for a supergroup. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Use the field :attr:`telegram.Chat.can_set_sticker_set` optionally returned - in :attr:`get_chat` requests to check if the bot can use this method. + in :meth:`get_chat` requests to check if the bot can use this method. Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username @@ -3106,7 +3106,7 @@ class Bot(TelegramObject): """Use this method to delete a group sticker set from a supergroup. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Use the field :attr:`telegram.Chat.can_set_sticker_set` optionally returned in - :attr:`get_chat` requests to check if the bot can use this method. + :meth:`get_chat` requests to check if the bot can use this method. Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username @@ -3541,7 +3541,7 @@ class Bot(TelegramObject): :obj:`True` for all boolean parameters to lift restrictions from a user. Note: - Since Bot API 4.4, :attr:`restrict_chat_member` takes the new user permissions in a + Since Bot API 4.4, :meth:`restrict_chat_member` takes the new user permissions in a single argument of type :class:`telegram.ChatPermissions`. The old way of passing parameters will not keep working forever. @@ -4261,7 +4261,7 @@ class Bot(TelegramObject): ) -> File: """ Use this method to upload a .png file with a sticker for later use in - :attr:`create_new_sticker_set` and :attr:`add_sticker_to_set` methods (can be used multiple + :meth:`create_new_sticker_set` and :meth:`add_sticker_to_set` methods (can be used multiple times). Note: @@ -5061,107 +5061,107 @@ class Bot(TelegramObject): # camelCase aliases getMe = get_me - """Alias for :attr:`get_me`""" + """Alias for :meth:`get_me`""" sendMessage = send_message - """Alias for :attr:`send_message`""" + """Alias for :meth:`send_message`""" deleteMessage = delete_message - """Alias for :attr:`delete_message`""" + """Alias for :meth:`delete_message`""" forwardMessage = forward_message - """Alias for :attr:`forward_message`""" + """Alias for :meth:`forward_message`""" sendPhoto = send_photo - """Alias for :attr:`send_photo`""" + """Alias for :meth:`send_photo`""" sendAudio = send_audio - """Alias for :attr:`send_audio`""" + """Alias for :meth:`send_audio`""" sendDocument = send_document - """Alias for :attr:`send_document`""" + """Alias for :meth:`send_document`""" sendSticker = send_sticker - """Alias for :attr:`send_sticker`""" + """Alias for :meth:`send_sticker`""" sendVideo = send_video - """Alias for :attr:`send_video`""" + """Alias for :meth:`send_video`""" sendAnimation = send_animation - """Alias for :attr:`send_animation`""" + """Alias for :meth:`send_animation`""" sendVoice = send_voice - """Alias for :attr:`send_voice`""" + """Alias for :meth:`send_voice`""" sendVideoNote = send_video_note - """Alias for :attr:`send_video_note`""" + """Alias for :meth:`send_video_note`""" sendMediaGroup = send_media_group - """Alias for :attr:`send_media_group`""" + """Alias for :meth:`send_media_group`""" sendLocation = send_location - """Alias for :attr:`send_location`""" + """Alias for :meth:`send_location`""" editMessageLiveLocation = edit_message_live_location - """Alias for :attr:`edit_message_live_location`""" + """Alias for :meth:`edit_message_live_location`""" stopMessageLiveLocation = stop_message_live_location - """Alias for :attr:`stop_message_live_location`""" + """Alias for :meth:`stop_message_live_location`""" sendVenue = send_venue - """Alias for :attr:`send_venue`""" + """Alias for :meth:`send_venue`""" sendContact = send_contact - """Alias for :attr:`send_contact`""" + """Alias for :meth:`send_contact`""" sendGame = send_game - """Alias for :attr:`send_game`""" + """Alias for :meth:`send_game`""" sendChatAction = send_chat_action - """Alias for :attr:`send_chat_action`""" + """Alias for :meth:`send_chat_action`""" answerInlineQuery = answer_inline_query - """Alias for :attr:`answer_inline_query`""" + """Alias for :meth:`answer_inline_query`""" getUserProfilePhotos = get_user_profile_photos - """Alias for :attr:`get_user_profile_photos`""" + """Alias for :meth:`get_user_profile_photos`""" getFile = get_file - """Alias for :attr:`get_file`""" + """Alias for :meth:`get_file`""" kickChatMember = kick_chat_member - """Alias for :attr:`kick_chat_member`""" + """Alias for :meth:`kick_chat_member`""" unbanChatMember = unban_chat_member - """Alias for :attr:`unban_chat_member`""" + """Alias for :meth:`unban_chat_member`""" answerCallbackQuery = answer_callback_query - """Alias for :attr:`answer_callback_query`""" + """Alias for :meth:`answer_callback_query`""" editMessageText = edit_message_text - """Alias for :attr:`edit_message_text`""" + """Alias for :meth:`edit_message_text`""" editMessageCaption = edit_message_caption - """Alias for :attr:`edit_message_caption`""" + """Alias for :meth:`edit_message_caption`""" editMessageMedia = edit_message_media - """Alias for :attr:`edit_message_media`""" + """Alias for :meth:`edit_message_media`""" editMessageReplyMarkup = edit_message_reply_markup - """Alias for :attr:`edit_message_reply_markup`""" + """Alias for :meth:`edit_message_reply_markup`""" getUpdates = get_updates - """Alias for :attr:`get_updates`""" + """Alias for :meth:`get_updates`""" setWebhook = set_webhook - """Alias for :attr:`set_webhook`""" + """Alias for :meth:`set_webhook`""" deleteWebhook = delete_webhook - """Alias for :attr:`delete_webhook`""" + """Alias for :meth:`delete_webhook`""" leaveChat = leave_chat - """Alias for :attr:`leave_chat`""" + """Alias for :meth:`leave_chat`""" getChat = get_chat - """Alias for :attr:`get_chat`""" + """Alias for :meth:`get_chat`""" getChatAdministrators = get_chat_administrators - """Alias for :attr:`get_chat_administrators`""" + """Alias for :meth:`get_chat_administrators`""" getChatMember = get_chat_member - """Alias for :attr:`get_chat_member`""" + """Alias for :meth:`get_chat_member`""" setChatStickerSet = set_chat_sticker_set - """Alias for :attr:`set_chat_sticker_set`""" + """Alias for :meth:`set_chat_sticker_set`""" deleteChatStickerSet = delete_chat_sticker_set - """Alias for :attr:`delete_chat_sticker_set`""" + """Alias for :meth:`delete_chat_sticker_set`""" getChatMembersCount = get_chat_members_count - """Alias for :attr:`get_chat_members_count`""" + """Alias for :meth:`get_chat_members_count`""" getWebhookInfo = get_webhook_info - """Alias for :attr:`get_webhook_info`""" + """Alias for :meth:`get_webhook_info`""" setGameScore = set_game_score - """Alias for :attr:`set_game_score`""" + """Alias for :meth:`set_game_score`""" getGameHighScores = get_game_high_scores - """Alias for :attr:`get_game_high_scores`""" + """Alias for :meth:`get_game_high_scores`""" sendInvoice = send_invoice - """Alias for :attr:`send_invoice`""" + """Alias for :meth:`send_invoice`""" answerShippingQuery = answer_shipping_query - """Alias for :attr:`answer_shipping_query`""" + """Alias for :meth:`answer_shipping_query`""" answerPreCheckoutQuery = answer_pre_checkout_query - """Alias for :attr:`answer_pre_checkout_query`""" + """Alias for :meth:`answer_pre_checkout_query`""" restrictChatMember = restrict_chat_member - """Alias for :attr:`restrict_chat_member`""" + """Alias for :meth:`restrict_chat_member`""" promoteChatMember = promote_chat_member - """Alias for :attr:`promote_chat_member`""" + """Alias for :meth:`promote_chat_member`""" setChatPermissions = set_chat_permissions - """Alias for :attr:`set_chat_permissions`""" + """Alias for :meth:`set_chat_permissions`""" setChatAdministratorCustomTitle = set_chat_administrator_custom_title - """Alias for :attr:`set_chat_administrator_custom_title`""" + """Alias for :meth:`set_chat_administrator_custom_title`""" exportChatInviteLink = export_chat_invite_link - """Alias for :attr:`export_chat_invite_link`""" + """Alias for :meth:`export_chat_invite_link`""" createChatInviteLink = create_chat_invite_link """Alias for :attr:`create_chat_invite_link`""" editChatInviteLink = edit_chat_invite_link @@ -5169,46 +5169,46 @@ class Bot(TelegramObject): revokeChatInviteLink = revoke_chat_invite_link """Alias for :attr:`revoke_chat_invite_link`""" setChatPhoto = set_chat_photo - """Alias for :attr:`set_chat_photo`""" + """Alias for :meth:`set_chat_photo`""" deleteChatPhoto = delete_chat_photo - """Alias for :attr:`delete_chat_photo`""" + """Alias for :meth:`delete_chat_photo`""" setChatTitle = set_chat_title - """Alias for :attr:`set_chat_title`""" + """Alias for :meth:`set_chat_title`""" setChatDescription = set_chat_description - """Alias for :attr:`set_chat_description`""" + """Alias for :meth:`set_chat_description`""" pinChatMessage = pin_chat_message - """Alias for :attr:`pin_chat_message`""" + """Alias for :meth:`pin_chat_message`""" unpinChatMessage = unpin_chat_message - """Alias for :attr:`unpin_chat_message`""" + """Alias for :meth:`unpin_chat_message`""" unpinAllChatMessages = unpin_all_chat_messages - """Alias for :attr:`unpin_all_chat_messages`""" + """Alias for :meth:`unpin_all_chat_messages`""" getStickerSet = get_sticker_set - """Alias for :attr:`get_sticker_set`""" + """Alias for :meth:`get_sticker_set`""" uploadStickerFile = upload_sticker_file - """Alias for :attr:`upload_sticker_file`""" + """Alias for :meth:`upload_sticker_file`""" createNewStickerSet = create_new_sticker_set - """Alias for :attr:`create_new_sticker_set`""" + """Alias for :meth:`create_new_sticker_set`""" addStickerToSet = add_sticker_to_set - """Alias for :attr:`add_sticker_to_set`""" + """Alias for :meth:`add_sticker_to_set`""" setStickerPositionInSet = set_sticker_position_in_set - """Alias for :attr:`set_sticker_position_in_set`""" + """Alias for :meth:`set_sticker_position_in_set`""" deleteStickerFromSet = delete_sticker_from_set - """Alias for :attr:`delete_sticker_from_set`""" + """Alias for :meth:`delete_sticker_from_set`""" setStickerSetThumb = set_sticker_set_thumb - """Alias for :attr:`set_sticker_set_thumb`""" + """Alias for :meth:`set_sticker_set_thumb`""" setPassportDataErrors = set_passport_data_errors - """Alias for :attr:`set_passport_data_errors`""" + """Alias for :meth:`set_passport_data_errors`""" sendPoll = send_poll - """Alias for :attr:`send_poll`""" + """Alias for :meth:`send_poll`""" stopPoll = stop_poll - """Alias for :attr:`stop_poll`""" + """Alias for :meth:`stop_poll`""" sendDice = send_dice - """Alias for :attr:`send_dice`""" + """Alias for :meth:`send_dice`""" getMyCommands = get_my_commands - """Alias for :attr:`get_my_commands`""" + """Alias for :meth:`get_my_commands`""" setMyCommands = set_my_commands - """Alias for :attr:`set_my_commands`""" + """Alias for :meth:`set_my_commands`""" logOut = log_out - """Alias for :attr:`log_out`""" + """Alias for :meth:`log_out`""" copyMessage = copy_message - """Alias for :attr:`copy_message`""" + """Alias for :meth:`copy_message`""" diff --git a/telegram/ext/filters.py b/telegram/ext/filters.py index 0268fb31d..118b5f24b 100644 --- a/telegram/ext/filters.py +++ b/telegram/ext/filters.py @@ -1117,8 +1117,8 @@ officedocument.wordprocessingml.document")``. left_chat_member: Messages that contain :attr:`telegram.Message.left_chat_member`. migrate: Messages that contain - :attr:`telegram.Message.migrate_from_chat_id` or - :attr: `telegram.Message.migrate_from_chat_id`. + :attr:`telegram.Message.migrate_to_chat_id` or + :attr:`telegram.Message.migrate_from_chat_id`. new_chat_members: Messages that contain :attr:`telegram.Message.new_chat_members`. new_chat_photo: Messages that contain @@ -1738,16 +1738,22 @@ officedocument.wordprocessingml.document")``. username. Examples: - * To filter for messages forwarded from a channel with ID ``-1234``, use - ``MessageHandler(Filters.sender_chat(-1234), callback_method)``. + * To filter for messages forwarded to a discussion group from a channel with ID + ``-1234``, use ``MessageHandler(Filters.sender_chat(-1234), callback_method)``. * To filter for messages of anonymous admins in a super group with username ``@anonymous``, use ``MessageHandler(Filters.sender_chat(username='anonymous'), callback_method)``. - * To filter for messages forwarded from *any* channel, use + * To filter for messages forwarded to a discussion group from *any* channel, use ``MessageHandler(Filters.sender_chat.channel, callback_method)``. * To filter for messages of anonymous admins in *any* super group, use ``MessageHandler(Filters.sender_chat.super_group, callback_method)``. + Note: + Remember, ``sender_chat`` is also set for messages in a channel as the channel itself, + so when your bot is an admin in a channel and the linked discussion group, you would + receive the message twice (once from inside the channel, once inside the discussion + group). + Warning: :attr:`chat_ids` will return a *copy* of the saved chat ids as :class:`frozenset`. This is to ensure thread safety. To add/remove a chat, you should use :meth:`add_usernames`, diff --git a/telegram/inline/inlinequery.py b/telegram/inline/inlinequery.py index fd2fea861..dceb47bbb 100644 --- a/telegram/inline/inlinequery.py +++ b/telegram/inline/inlinequery.py @@ -125,7 +125,7 @@ class InlineQuery(TelegramObject): Defaults to :obj:`False`. Raises: - TypeError: If both :attr:`current_offset` and attr:`auto_pagination` are supplied. + TypeError: If both :attr:`current_offset` and :attr:`auto_pagination` are supplied. """ if current_offset and auto_pagination: # We raise TypeError instead of ValueError for backwards compatibility with versions diff --git a/telegram/user.py b/telegram/user.py index fee2a3135..b136073fa 100644 --- a/telegram/user.py +++ b/telegram/user.py @@ -161,7 +161,7 @@ class User(TelegramObject): """ Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.get_user_profile_photos(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.get_user_profile_photos`.