diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index 11cb69378..d204cd74b 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -137,6 +137,8 @@ Here's how to make a one-off code change. - Make a new commit addressing the comments you agree with, and push it to the same branch. Ideally, the commit message would explain what the commit does (e.g. "Fix lint error"), but if there are lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)". + - In order to keep the commit history intact, please avoid squashing or amending history and then force-pushing to the PR. Reviewers often want to look at individual commits. + - In addition, please reply to each comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. All comments must be resolved before LGTM can be given. - Resolve any merge conflicts that arise. To resolve conflicts between 'your-branch-name' (in your fork) and 'master' (in the ``python-telegram-bot`` repository), run: diff --git a/README.rst b/README.rst index 06be5a4b9..c80c8692c 100644 --- a/README.rst +++ b/README.rst @@ -167,8 +167,8 @@ Learning by example We believe that the best way to learn this package is by example. Here are some examples for you to review. Even if it is not your approach for learning, please take a -look at ``echobot.py``, it is the de facto base for most of the bots out there. Best of all, -the code for these examples are released to the public domain, so you can start by grabbing the +look at ``echobot.py``. It is the de facto base for most of the bots out there. Best of all, +the code for these examples is released to the public domain, so you can start by grabbing the code and building on top of it. Visit `this page `_ to discover the official examples or look at the examples on the `wiki `_ to see other bots the community has built. @@ -231,7 +231,7 @@ Contributions of all sizes are welcome. Please review our `contribution guidelin ======== 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. +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 405877701..d25ad6efc 100644 --- a/README_RAW.rst +++ b/README_RAW.rst @@ -213,7 +213,7 @@ Contributions of all sizes are welcome. Please review our `contribution guidelin ======== 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. +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/source/conf.py b/docs/source/conf.py index 430464f3d..e96519011 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -38,8 +38,16 @@ needs_sphinx = '4.2.0' # ones. extensions = [ 'sphinx.ext.autodoc', - 'sphinx.ext.napoleon' + 'sphinx.ext.napoleon', + 'sphinx.ext.intersphinx' ] + +# Use intersphinx to reference the python builtin library docs +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + 'APScheduler': ('https://apscheduler.readthedocs.io/en/3.x/', None) +} + # Don't show type hints in the signature - that just makes it hardly readable # and we document the types anyway autodoc_typehints = 'none' diff --git a/telegram/_callbackquery.py b/telegram/_callbackquery.py index d3b459149..b18bf91d3 100644 --- a/telegram/_callbackquery.py +++ b/telegram/_callbackquery.py @@ -47,7 +47,7 @@ class CallbackQuery(TelegramObject): considered equal, if their :attr:`id` is equal. Note: - * In Python ``from`` is a reserved word, use ``from_user`` instead. + * In Python :keyword:`from` is a reserved word, use ``from_user`` instead. * Exactly one of the fields :attr:`data` or :attr:`game_short_name` will be present. * After the user presses an inline button, Telegram clients will display a progress bar until you call :attr:`answer`. It is, therefore, necessary to react diff --git a/telegram/_chatmemberupdated.py b/telegram/_chatmemberupdated.py index a5815cc73..32f5fe112 100644 --- a/telegram/_chatmemberupdated.py +++ b/telegram/_chatmemberupdated.py @@ -38,7 +38,7 @@ class ChatMemberUpdated(TelegramObject): .. versionadded:: 13.4 Note: - In Python ``from`` is a reserved word, use ``from_user`` instead. + In Python :keyword:`from` is a reserved word, use ``from_user`` instead. Args: chat (:class:`telegram.Chat`): Chat the user belongs to. diff --git a/telegram/_choseninlineresult.py b/telegram/_choseninlineresult.py index 6af2349c7..9aef361a1 100644 --- a/telegram/_choseninlineresult.py +++ b/telegram/_choseninlineresult.py @@ -37,7 +37,7 @@ class ChosenInlineResult(TelegramObject): considered equal, if their :attr:`result_id` is equal. Note: - * In Python ``from`` is a reserved word, use ``from_user`` instead. + * In Python :keyword:`from` is a reserved word, use ``from_user`` instead. * It is necessary to enable inline feedback via `@Botfather `_ in order to receive these objects in updates. diff --git a/telegram/_files/animation.py b/telegram/_files/animation.py index 4d28af1c4..cbaf9e723 100644 --- a/telegram/_files/animation.py +++ b/telegram/_files/animation.py @@ -44,7 +44,7 @@ class Animation(_BaseThumbedMedium): thumb (:class:`telegram.PhotoSize`, optional): Animation thumbnail as defined by sender. file_name (:obj:`str`, optional): Original animation filename as defined by sender. mime_type (:obj:`str`, optional): MIME type of the file as defined by sender. - file_size (:obj:`int`, optional): File size. + file_size (:obj:`int`, optional): File size in bytes. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. **kwargs (:obj:`dict`): Arbitrary keyword arguments. @@ -59,7 +59,7 @@ class Animation(_BaseThumbedMedium): thumb (:class:`telegram.PhotoSize`): Optional. Animation thumbnail as defined by sender. file_name (:obj:`str`): Optional. Original animation filename as defined by sender. mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender. - file_size (:obj:`int`): Optional. File size. + file_size (:obj:`int`): Optional. File size in bytes. bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods. """ diff --git a/telegram/_files/audio.py b/telegram/_files/audio.py index 0ed85f089..e4f617eca 100644 --- a/telegram/_files/audio.py +++ b/telegram/_files/audio.py @@ -44,7 +44,7 @@ class Audio(_BaseThumbedMedium): title (:obj:`str`, optional): Title of the audio as defined by sender or by audio tags. file_name (:obj:`str`, optional): Original filename as defined by sender. mime_type (:obj:`str`, optional): MIME type of the file as defined by sender. - file_size (:obj:`int`, optional): File size. + file_size (:obj:`int`, optional): File size in bytes. thumb (:class:`telegram.PhotoSize`, optional): Thumbnail of the album cover to which the music file belongs. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. @@ -61,7 +61,7 @@ class Audio(_BaseThumbedMedium): title (:obj:`str`): Optional. Title of the audio as defined by sender or by audio tags. file_name (:obj:`str`): Optional. Original filename as defined by sender. mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender. - file_size (:obj:`int`): Optional. File size. + file_size (:obj:`int`): Optional. File size in bytes. thumb (:class:`telegram.PhotoSize`): Optional. Thumbnail of the album cover to which the music file belongs. bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods. diff --git a/telegram/_files/document.py b/telegram/_files/document.py index 276427928..c4f1da714 100644 --- a/telegram/_files/document.py +++ b/telegram/_files/document.py @@ -42,7 +42,7 @@ class Document(_BaseThumbedMedium): thumb (:class:`telegram.PhotoSize`, optional): Document thumbnail as defined by sender. file_name (:obj:`str`, optional): Original filename as defined by sender. mime_type (:obj:`str`, optional): MIME type of the file as defined by sender. - file_size (:obj:`int`, optional): File size. + file_size (:obj:`int`, optional): File size in bytes. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. **kwargs (:obj:`dict`): Arbitrary keyword arguments. @@ -54,7 +54,7 @@ class Document(_BaseThumbedMedium): thumb (:class:`telegram.PhotoSize`): Optional. Document thumbnail. file_name (:obj:`str`): Original filename. mime_type (:obj:`str`): Optional. MIME type of the file. - file_size (:obj:`int`): Optional. File size. + file_size (:obj:`int`): Optional. File size in bytes. bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods. """ diff --git a/telegram/_files/file.py b/telegram/_files/file.py index e9ac05c29..c1fe7ce02 100644 --- a/telegram/_files/file.py +++ b/telegram/_files/file.py @@ -53,7 +53,7 @@ class File(TelegramObject): file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - file_size (:obj:`int`, optional): Optional. File size, if known. + file_size (:obj:`int`, optional): Optional. File size in bytes, if known. file_path (:obj:`str`, optional): File path. Use :attr:`download` to get the file. bot (:obj:`telegram.Bot`, optional): Bot to use with shortcut method. **kwargs (:obj:`dict`): Arbitrary keyword arguments. @@ -63,7 +63,7 @@ class File(TelegramObject): file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - file_size (:obj:`str`): Optional. File size. + file_size (:obj:`str`): Optional. File size in bytes. file_path (:obj:`str`): Optional. File path. Use :attr:`download` to get the file. """ diff --git a/telegram/_files/inputmedia.py b/telegram/_files/inputmedia.py index f934811b2..c20909b7a 100644 --- a/telegram/_files/inputmedia.py +++ b/telegram/_files/inputmedia.py @@ -146,7 +146,7 @@ class InputMediaAnimation(InputMedia): entities that appear in the caption, which can be specified instead of parse_mode. width (:obj:`int`, optional): Animation width. height (:obj:`int`, optional): Animation height. - duration (:obj:`int`, optional): Animation duration. + duration (:obj:`int`, optional): Animation duration in seconds. Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.ANIMATION`. @@ -158,7 +158,7 @@ class InputMediaAnimation(InputMedia): thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. width (:obj:`int`): Optional. Animation width. height (:obj:`int`): Optional. Animation height. - duration (:obj:`int`): Optional. Animation duration. + duration (:obj:`int`): Optional. Animation duration in seconds. """ @@ -276,7 +276,7 @@ class InputMediaVideo(InputMedia): entities that appear in the caption, which can be specified instead of parse_mode. width (:obj:`int`, optional): Video width. height (:obj:`int`, optional): Video height. - duration (:obj:`int`, optional): Video duration. + duration (:obj:`int`, optional): Video duration in seconds. supports_streaming (:obj:`bool`, optional): Pass :obj:`True`, if the uploaded video is suitable for streaming. thumb (`filelike object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail of @@ -298,7 +298,7 @@ class InputMediaVideo(InputMedia): entities that appear in the caption. width (:obj:`int`): Optional. Video width. height (:obj:`int`): Optional. Video height. - duration (:obj:`int`): Optional. Video duration. + duration (:obj:`int`): Optional. Video duration in seconds. supports_streaming (:obj:`bool`): Optional. Pass :obj:`True`, if the uploaded video is suitable for streaming. thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. diff --git a/telegram/_files/photosize.py b/telegram/_files/photosize.py index 266a2800b..df6009855 100644 --- a/telegram/_files/photosize.py +++ b/telegram/_files/photosize.py @@ -40,7 +40,7 @@ class PhotoSize(_BaseMedium): Can't be used to download or reuse the file. width (:obj:`int`): Photo width. height (:obj:`int`): Photo height. - file_size (:obj:`int`, optional): File size. + file_size (:obj:`int`, optional): File size in bytes. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. **kwargs (:obj:`dict`): Arbitrary keyword arguments. @@ -51,7 +51,7 @@ class PhotoSize(_BaseMedium): Can't be used to download or reuse the file. width (:obj:`int`): Photo width. height (:obj:`int`): Photo height. - file_size (:obj:`int`): Optional. File size. + file_size (:obj:`int`): Optional. File size in bytes. bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods. """ diff --git a/telegram/_files/sticker.py b/telegram/_files/sticker.py index 28e986c67..60772694f 100644 --- a/telegram/_files/sticker.py +++ b/telegram/_files/sticker.py @@ -58,7 +58,7 @@ class Sticker(_BaseThumbedMedium): belongs. mask_position (:class:`telegram.MaskPosition`, optional): For mask stickers, the position where the mask should be placed. - file_size (:obj:`int`, optional): File size. + file_size (:obj:`int`, optional): File size in bytes. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. **kwargs (obj:`dict`): Arbitrary keyword arguments. @@ -79,7 +79,7 @@ class Sticker(_BaseThumbedMedium): set_name (:obj:`str`): Optional. Name of the sticker set to which the sticker belongs. mask_position (:class:`telegram.MaskPosition`): Optional. For mask stickers, the position where the mask should be placed. - file_size (:obj:`int`): Optional. File size. + file_size (:obj:`int`): Optional. File size in bytes. bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods. """ diff --git a/telegram/_files/video.py b/telegram/_files/video.py index ee00f23e2..73dca49bf 100644 --- a/telegram/_files/video.py +++ b/telegram/_files/video.py @@ -45,7 +45,7 @@ class Video(_BaseThumbedMedium): thumb (:class:`telegram.PhotoSize`, optional): Video thumbnail. file_name (:obj:`str`, optional): Original filename as defined by sender. mime_type (:obj:`str`, optional): Mime type of a file as defined by sender. - file_size (:obj:`int`, optional): File size. + file_size (:obj:`int`, optional): File size in bytes. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. **kwargs (:obj:`dict`): Arbitrary keyword arguments. @@ -60,7 +60,7 @@ class Video(_BaseThumbedMedium): thumb (:class:`telegram.PhotoSize`): Optional. Video thumbnail. file_name (:obj:`str`): Optional. Original filename as defined by sender. mime_type (:obj:`str`): Optional. Mime type of a file as defined by sender. - file_size (:obj:`int`): Optional. File size. + file_size (:obj:`int`): Optional. File size in bytes. bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods. """ diff --git a/telegram/_files/videonote.py b/telegram/_files/videonote.py index a9fe4958f..f1c496b72 100644 --- a/telegram/_files/videonote.py +++ b/telegram/_files/videonote.py @@ -43,7 +43,7 @@ class VideoNote(_BaseThumbedMedium): by sender. duration (:obj:`int`): Duration of the video in seconds as defined by sender. thumb (:class:`telegram.PhotoSize`, optional): Video thumbnail. - file_size (:obj:`int`, optional): File size. + file_size (:obj:`int`, optional): File size in bytes. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. **kwargs (:obj:`dict`): Arbitrary keyword arguments. @@ -55,7 +55,7 @@ class VideoNote(_BaseThumbedMedium): length (:obj:`int`): Video width and height as defined by sender. duration (:obj:`int`): Duration of the video in seconds as defined by sender. thumb (:class:`telegram.PhotoSize`): Optional. Video thumbnail. - file_size (:obj:`int`): Optional. File size. + file_size (:obj:`int`): Optional. File size in bytes. bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods. """ diff --git a/telegram/_files/voice.py b/telegram/_files/voice.py index cc71aa2be..c2bf1bc83 100644 --- a/telegram/_files/voice.py +++ b/telegram/_files/voice.py @@ -40,7 +40,7 @@ class Voice(_BaseMedium): Can't be used to download or reuse the file. duration (:obj:`int`, optional): Duration of the audio in seconds as defined by sender. mime_type (:obj:`str`, optional): MIME type of the file as defined by sender. - file_size (:obj:`int`, optional): File size. + file_size (:obj:`int`, optional): File size in bytes. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. **kwargs (:obj:`dict`): Arbitrary keyword arguments. @@ -51,7 +51,7 @@ class Voice(_BaseMedium): Can't be used to download or reuse the file. duration (:obj:`int`): Duration of the audio in seconds as defined by sender. mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender. - file_size (:obj:`int`): Optional. File size. + file_size (:obj:`int`): Optional. File size in bytes. bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods. """ diff --git a/telegram/_inline/inlinequery.py b/telegram/_inline/inlinequery.py index 0eeb78948..970893037 100644 --- a/telegram/_inline/inlinequery.py +++ b/telegram/_inline/inlinequery.py @@ -38,7 +38,7 @@ class InlineQuery(TelegramObject): considered equal, if their :attr:`id` is equal. Note: - In Python ``from`` is a reserved word, use ``from_user`` instead. + In Python :keyword:`from` is a reserved word, use ``from_user`` instead. Args: id (:obj:`str`): Unique identifier for this query. diff --git a/telegram/_inline/inlinequeryresultdocument.py b/telegram/_inline/inlinequeryresultdocument.py index 32b8c51bf..525484ffe 100644 --- a/telegram/_inline/inlinequeryresultdocument.py +++ b/telegram/_inline/inlinequeryresultdocument.py @@ -56,7 +56,7 @@ class InlineQueryResultDocument(InlineQueryResult): to the message. input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the message to be sent instead of the file. - thumb_url (:obj:`str`, optional): URL of the thumbnail (jpeg only) for the file. + thumb_url (:obj:`str`, optional): URL of the thumbnail (JPEG only) for the file. thumb_width (:obj:`int`, optional): Thumbnail width. thumb_height (:obj:`int`, optional): Thumbnail height. **kwargs (:obj:`dict`): Arbitrary keyword arguments. @@ -82,7 +82,7 @@ class InlineQueryResultDocument(InlineQueryResult): to the message. input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the message to be sent instead of the file. - thumb_url (:obj:`str`): Optional. URL of the thumbnail (jpeg only) for the file. + thumb_url (:obj:`str`): Optional. URL of the thumbnail (JPEG only) for the file. thumb_width (:obj:`int`): Optional. Thumbnail width. thumb_height (:obj:`int`): Optional. Thumbnail height. diff --git a/telegram/_inline/inlinequeryresultgif.py b/telegram/_inline/inlinequeryresultgif.py index 82e9f20e0..fbcb44deb 100644 --- a/telegram/_inline/inlinequeryresultgif.py +++ b/telegram/_inline/inlinequeryresultgif.py @@ -41,7 +41,7 @@ class InlineQueryResultGif(InlineQueryResult): gif_url (:obj:`str`): A valid URL for the GIF file. File size must not exceed 1MB. gif_width (:obj:`int`, optional): Width of the GIF. gif_height (:obj:`int`, optional): Height of the GIF. - gif_duration (:obj:`int`, optional): Duration of the GIF + gif_duration (:obj:`int`, optional): Duration of the GIF in seconds. thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result. thumb_mime_type (:obj:`str`, optional): MIME type of the thumbnail, must be one of @@ -68,7 +68,7 @@ class InlineQueryResultGif(InlineQueryResult): gif_url (:obj:`str`): A valid URL for the GIF file. File size must not exceed 1MB. gif_width (:obj:`int`): Optional. Width of the GIF. gif_height (:obj:`int`): Optional. Height of the GIF. - gif_duration (:obj:`int`): Optional. Duration of the GIF. + gif_duration (:obj:`int`): Optional. Duration of the GIF in seconds. thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result. thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail. diff --git a/telegram/_inline/inlinequeryresultmpeg4gif.py b/telegram/_inline/inlinequeryresultmpeg4gif.py index f2b169a0a..97a771b6a 100644 --- a/telegram/_inline/inlinequeryresultmpeg4gif.py +++ b/telegram/_inline/inlinequeryresultmpeg4gif.py @@ -41,7 +41,7 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult): mpeg4_url (:obj:`str`): A valid URL for the MP4 file. File size must not exceed 1MB. mpeg4_width (:obj:`int`, optional): Video width. mpeg4_height (:obj:`int`, optional): Video height. - mpeg4_duration (:obj:`int`, optional): Video duration. + mpeg4_duration (:obj:`int`, optional): Video duration in seconds. thumb_url (:obj:`str`): URL of the static thumbnail (jpeg or gif) for the result. thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail, must be one of ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``. @@ -67,7 +67,7 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult): mpeg4_url (:obj:`str`): A valid URL for the MP4 file. File size must not exceed 1MB. mpeg4_width (:obj:`int`): Optional. Video width. mpeg4_height (:obj:`int`): Optional. Video height. - mpeg4_duration (:obj:`int`): Optional. Video duration. + mpeg4_duration (:obj:`int`): Optional. Video duration in seconds. thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for the result. thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail. diff --git a/telegram/_inline/inlinequeryresultphoto.py b/telegram/_inline/inlinequeryresultphoto.py index 43ce522de..67001aac4 100644 --- a/telegram/_inline/inlinequeryresultphoto.py +++ b/telegram/_inline/inlinequeryresultphoto.py @@ -37,7 +37,7 @@ class InlineQueryResultPhoto(InlineQueryResult): Args: id (:obj:`str`): Unique identifier for this result, 1-64 bytes. - photo_url (:obj:`str`): A valid URL of the photo. Photo must be in jpeg format. Photo size + photo_url (:obj:`str`): A valid URL of the photo. Photo must be in JPEG format. Photo size must not exceed 5MB. thumb_url (:obj:`str`): URL of the thumbnail for the photo. photo_width (:obj:`int`, optional): Width of the photo. @@ -62,7 +62,7 @@ class InlineQueryResultPhoto(InlineQueryResult): Attributes: type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.PHOTO`. id (:obj:`str`): Unique identifier for this result, 1-64 bytes. - photo_url (:obj:`str`): A valid URL of the photo. Photo must be in jpeg format. Photo size + photo_url (:obj:`str`): A valid URL of the photo. Photo must be in JPEG format. Photo size must not exceed 5MB. thumb_url (:obj:`str`): URL of the thumbnail for the photo. photo_width (:obj:`int`): Optional. Width of the photo. diff --git a/telegram/_inline/inlinequeryresultvideo.py b/telegram/_inline/inlinequeryresultvideo.py index d420e425a..a4d34e16a 100644 --- a/telegram/_inline/inlinequeryresultvideo.py +++ b/telegram/_inline/inlinequeryresultvideo.py @@ -44,7 +44,7 @@ class InlineQueryResultVideo(InlineQueryResult): id (:obj:`str`): Unique identifier for this result, 1-64 bytes. video_url (:obj:`str`): A valid URL for the embedded video player or video file. mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4". - thumb_url (:obj:`str`): URL of the thumbnail (jpeg only) for the video. + thumb_url (:obj:`str`): URL of the thumbnail (JPEG only) for the video. title (:obj:`str`): Title for the result. caption (:obj:`str`, optional): Caption, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities @@ -72,7 +72,7 @@ class InlineQueryResultVideo(InlineQueryResult): id (:obj:`str`): Unique identifier for this result, 1-64 bytes. video_url (:obj:`str`): A valid URL for the embedded video player or video file. mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4". - thumb_url (:obj:`str`): URL of the thumbnail (jpeg only) for the video. + thumb_url (:obj:`str`): URL of the thumbnail (JPEG only) for the video. title (:obj:`str`): Title for the result. caption (:obj:`str`): Optional. Caption of the video to be sent, 0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after diff --git a/telegram/_message.py b/telegram/_message.py index ea6ac02b1..462d48ba0 100644 --- a/telegram/_message.py +++ b/telegram/_message.py @@ -82,7 +82,7 @@ class Message(TelegramObject): considered equal, if their :attr:`message_id` and :attr:`chat` are equal. Note: - In Python ``from`` is a reserved word, use ``from_user`` instead. + In Python :keyword:`from` is a reserved word, use ``from_user`` instead. Args: message_id (:obj:`int`): Unique message identifier inside this chat. diff --git a/telegram/_passport/passportfile.py b/telegram/_passport/passportfile.py index f88ad8d86..a8df26a57 100644 --- a/telegram/_passport/passportfile.py +++ b/telegram/_passport/passportfile.py @@ -42,7 +42,7 @@ class PassportFile(TelegramObject): file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - file_size (:obj:`int`): File size. + file_size (:obj:`int`): File size in bytes. file_date (:obj:`int`): Unix time when the file was uploaded. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. **kwargs (:obj:`dict`): Arbitrary keyword arguments. @@ -52,7 +52,7 @@ class PassportFile(TelegramObject): file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file. - file_size (:obj:`int`): File size. + file_size (:obj:`int`): File size in bytes. file_date (:obj:`int`): Unix time when the file was uploaded. bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods. diff --git a/telegram/_payment/precheckoutquery.py b/telegram/_payment/precheckoutquery.py index 06ddd51aa..b7497e73a 100644 --- a/telegram/_payment/precheckoutquery.py +++ b/telegram/_payment/precheckoutquery.py @@ -35,7 +35,7 @@ class PreCheckoutQuery(TelegramObject): considered equal, if their :attr:`id` is equal. Note: - In Python ``from`` is a reserved word, use ``from_user`` instead. + In Python :keyword:`from` is a reserved word, use ``from_user`` instead. Args: id (:obj:`str`): Unique query identifier. diff --git a/telegram/_payment/shippingquery.py b/telegram/_payment/shippingquery.py index 7d0b2f34a..8f3718e50 100644 --- a/telegram/_payment/shippingquery.py +++ b/telegram/_payment/shippingquery.py @@ -35,7 +35,7 @@ class ShippingQuery(TelegramObject): considered equal, if their :attr:`id` is equal. Note: - In Python ``from`` is a reserved word, use ``from_user`` instead. + In Python :keyword:`from` is a reserved word, use ``from_user`` instead. Args: id (:obj:`str`): Unique query identifier. diff --git a/telegram/_poll.py b/telegram/_poll.py index 2ca5e3d85..dea2b4570 100644 --- a/telegram/_poll.py +++ b/telegram/_poll.py @@ -67,17 +67,17 @@ class PollAnswer(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`poll_id`, :attr:`user` and :attr:`options_ids` are equal. - Attributes: - poll_id (:obj:`str`): Unique poll identifier. - user (:class:`telegram.User`): The user, who changed the answer to the poll. - option_ids (List[:obj:`int`]): Identifiers of answer options, chosen by the user. - Args: poll_id (:obj:`str`): Unique poll identifier. user (:class:`telegram.User`): The user, who changed the answer to the poll. option_ids (List[:obj:`int`]): 0-based identifiers of answer options, chosen by the user. May be empty if the user retracted their vote. + Attributes: + poll_id (:obj:`str`): Unique poll identifier. + user (:class:`telegram.User`): The user, who changed the answer to the poll. + option_ids (List[:obj:`int`]): Identifiers of answer options, chosen by the user. + """ __slots__ = ('option_ids', 'user', 'poll_id') @@ -109,25 +109,6 @@ class Poll(TelegramObject): Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`id` is equal. - Attributes: - id (:obj:`str`): Unique poll identifier. - question (:obj:`str`): Poll question, 1-300 characters. - options (List[:class:`PollOption`]): List of poll options. - total_voter_count (:obj:`int`): Total number of users that voted in the poll. - is_closed (:obj:`bool`): :obj:`True`, if the poll is closed. - is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous. - type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`. - allows_multiple_answers (:obj:`bool`): :obj:`True`, if the poll allows multiple answers. - correct_option_id (:obj:`int`): Optional. Identifier of the correct answer option. - explanation (:obj:`str`): Optional. Text that is shown when a user chooses an incorrect - answer or taps on the lamp icon in a quiz-style poll. - explanation_entities (List[:class:`telegram.MessageEntity`]): Optional. Special entities - like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`. - open_period (:obj:`int`): Optional. Amount of time in seconds the poll will be active - after creation. - close_date (:obj:`datetime.datetime`): Optional. Point in time when the poll will be - automatically closed. - Args: id (:obj:`str`): Unique poll identifier. question (:obj:`str`): Poll question, 1-300 characters. @@ -148,6 +129,25 @@ class Poll(TelegramObject): close_date (:obj:`datetime.datetime`, optional): Point in time (Unix timestamp) when the poll will be automatically closed. Converted to :obj:`datetime.datetime`. + Attributes: + id (:obj:`str`): Unique poll identifier. + question (:obj:`str`): Poll question, 1-300 characters. + options (List[:class:`PollOption`]): List of poll options. + total_voter_count (:obj:`int`): Total number of users that voted in the poll. + is_closed (:obj:`bool`): :obj:`True`, if the poll is closed. + is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous. + type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`. + allows_multiple_answers (:obj:`bool`): :obj:`True`, if the poll allows multiple answers. + correct_option_id (:obj:`int`): Optional. Identifier of the correct answer option. + explanation (:obj:`str`): Optional. Text that is shown when a user chooses an incorrect + answer or taps on the lamp icon in a quiz-style poll. + explanation_entities (List[:class:`telegram.MessageEntity`]): Optional. Special entities + like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`. + open_period (:obj:`int`): Optional. Amount of time in seconds the poll will be active + after creation. + close_date (:obj:`datetime.datetime`): Optional. Point in time when the poll will be + automatically closed. + """ __slots__ = ( diff --git a/telegram/error.py b/telegram/error.py index 364ba5a59..64fc70393 100644 --- a/telegram/error.py +++ b/telegram/error.py @@ -163,7 +163,12 @@ class Conflict(TelegramError): class PassportDecryptionError(TelegramError): - """Something went wrong with decryption.""" + """Something went wrong with decryption. + + .. versionchanged:: 14.0 + This class was previously named ``TelegramDecryptionError`` and was available via + ``telegram.TelegramDecryptionError``. + """ __slots__ = ('_msg',) diff --git a/telegram/ext/_builders.py b/telegram/ext/_builders.py index 92b80535e..de723f9fa 100644 --- a/telegram/ext/_builders.py +++ b/telegram/ext/_builders.py @@ -823,7 +823,7 @@ class UpdaterBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]): Example: .. code:: python - dispatcher = UpdaterBuilder().token('TOKEN').build() + updater = UpdaterBuilder().token('TOKEN').build() Please see the description of the individual methods for information on which arguments can be set and what the defaults are when not called. When no default is mentioned, the argument will @@ -1192,7 +1192,7 @@ class UpdaterBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]): dispatcher: Optional[Dispatcher[InBT, InCCT, InUD, InCD, InBD, InJQ, InPT]], ) -> 'UpdaterBuilder[Optional[Dispatcher[InBT, InCCT, InUD, InCD, InBD, InJQ, InPT]], InBT, InCCT, InUD, InCD, InBD, InJQ, InPT]': """Sets a :class:`telegram.ext.Dispatcher` instance to be used for - :attr:`telegram.ext.Updater.dispatcher`. If not called, a queue will be instantiated. + :attr:`telegram.ext.Updater.dispatcher`. The dispatchers :attr:`telegram.ext.Dispatcher.bot`, :attr:`telegram.ext.Dispatcher.update_queue` and :attr:`telegram.ext.Dispatcher.exception_event` will be used for the respective arguments diff --git a/telegram/ext/_dispatcher.py b/telegram/ext/_dispatcher.py index 2cb55fb8a..a0a052fc1 100644 --- a/telegram/ext/_dispatcher.py +++ b/telegram/ext/_dispatcher.py @@ -661,9 +661,8 @@ class Dispatcher(Generic[BT, CCT, UD, CD, BD, JQ, PT]): Args: callback (:obj:`callable`): The callback function for this error handler. Will be called when an error is raised. Callback signature: - ``def callback(update: Update, context: CallbackContext)`` - - The error that happened will be present in context.error. + ``def callback(update: Update, context: CallbackContext)``. + The error that happened will be present in ``context.error``. run_async (:obj:`bool`, optional): Whether this handlers callback should be run asynchronously using :meth:`run_async`. Defaults to :obj:`False`. """ diff --git a/telegram/ext/_jobqueue.py b/telegram/ext/_jobqueue.py index 4b7c9e722..c6d0a349c 100644 --- a/telegram/ext/_jobqueue.py +++ b/telegram/ext/_jobqueue.py @@ -116,11 +116,11 @@ class JobQueue: name: str = None, job_kwargs: JSONDict = None, ) -> 'Job': - """Creates a new ``Job`` that runs once and adds it to the queue. + """Creates a new :class:`Job` instance that runs once and adds it to the queue. Args: callback (:obj:`callable`): The callback function that should be executed by the new - job. Callback signature: ``def callback(update: Update, context: CallbackContext)`` + job. Callback signature: ``def callback(context: CallbackContext)`` when (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` | \ :obj:`datetime.datetime` | :obj:`datetime.time`): Time in or at which the job should run. This parameter will be interpreted @@ -131,22 +131,23 @@ class JobQueue: * :obj:`datetime.timedelta` will be interpreted as "time from now" in which the job should run. * :obj:`datetime.datetime` will be interpreted as a specific date and time at - which the job should run. If the timezone (``datetime.tzinfo``) is :obj:`None`, - the default timezone of the bot will be used. + which the job should run. If the timezone (:attr:`datetime.datetime.tzinfo`) is + :obj:`None`, the default timezone of the bot will be used. * :obj:`datetime.time` will be interpreted as a specific time of day at which the job should run. This could be either today or, if the time has already passed, - tomorrow. If the timezone (``time.tzinfo``) is :obj:`None`, the + tomorrow. If the timezone (:attr:`datetime.time.tzinfo`) is :obj:`None`, the default timezone of the bot will be used. context (:obj:`object`, optional): Additional data needed for the callback function. - Can be accessed through ``job.context`` in the callback. Defaults to :obj:`None`. + Can be accessed through :attr:`Job.context` in the callback. Defaults to + :obj:`None`. name (:obj:`str`, optional): The name of the new job. Defaults to ``callback.__name__``. job_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to pass to the - ``scheduler.add_job()``. + :meth:`apscheduler.schedulers.base.BaseScheduler.add_job()`. Returns: - :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job + :class:`telegram.ext.Job`: The new :class:`Job` instance that has been added to the job queue. """ @@ -180,7 +181,8 @@ class JobQueue: name: str = None, job_kwargs: JSONDict = None, ) -> 'Job': - """Creates a new ``Job`` that runs at specified intervals and adds it to the queue. + """Creates a new :class:`Job` instance that runs at specified intervals and adds it to the + queue. Note: For a note about DST, please see the documentation of `APScheduler`_. @@ -190,7 +192,7 @@ class JobQueue: Args: callback (:obj:`callable`): The callback function that should be executed by the new - job. Callback signature: ``def callback(update: Update, context: CallbackContext)`` + job. Callback signature: ``def callback(context: CallbackContext)`` interval (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta`): The interval in which the job will run. If it is an :obj:`int` or a :obj:`float`, it will be interpreted as seconds. @@ -204,11 +206,11 @@ class JobQueue: * :obj:`datetime.timedelta` will be interpreted as "time from now" in which the job should run. * :obj:`datetime.datetime` will be interpreted as a specific date and time at - which the job should run. If the timezone (``datetime.tzinfo``) is :obj:`None`, - the default timezone of the bot will be used. + which the job should run. If the timezone (:attr:`datetime.datetime.tzinfo`) is + :obj:`None`, the default timezone of the bot will be used. * :obj:`datetime.time` will be interpreted as a specific time of day at which the job should run. This could be either today or, if the time has already passed, - tomorrow. If the timezone (``time.tzinfo``) is :obj:`None`, the + tomorrow. If the timezone (:attr:`datetime.time.tzinfo`) is :obj:`None`, the default timezone of the bot will be used. Defaults to ``interval`` @@ -223,14 +225,15 @@ class JobQueue: Defaults to :obj:`None`. context (:obj:`object`, optional): Additional data needed for the callback function. - Can be accessed through ``job.context`` in the callback. Defaults to :obj:`None`. + Can be accessed through :attr:`Job.context` in the callback. Defaults to + :obj:`None`. name (:obj:`str`, optional): The name of the new job. Defaults to ``callback.__name__``. job_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to pass to the - ``scheduler.add_job()``. + :meth:`apscheduler.schedulers.base.BaseScheduler.add_job()`. Returns: - :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job + :class:`telegram.ext.Job`: The new :class:`Job` instance that has been added to the job queue. """ @@ -272,7 +275,11 @@ class JobQueue: name: str = None, job_kwargs: JSONDict = None, ) -> 'Job': - """Creates a new ``Job`` that runs on a monthly basis and adds it to the queue. + """Creates a new :class:`Job` that runs on a monthly basis and adds it to the queue. + + .. versionchanged:: 14.0 + The ``day_is_strict`` argument was removed. Instead one can now pass -1 to the ``day`` + parameter to have the job run on the last day of the month. .. versionchanged:: 14.0 The ``day_is_strict`` argument was removed. Instead one can now pass -1 to the ``day`` @@ -280,7 +287,7 @@ class JobQueue: Args: callback (:obj:`callable`): The callback function that should be executed by the new - job. Callback signature: ``def callback(update: Update, context: CallbackContext)`` + job. Callback signature: ``def callback(context: CallbackContext)`` when (:obj:`datetime.time`): Time of day at which the job should run. If the timezone (``when.tzinfo``) is :obj:`None`, the default timezone of the bot will be used. day (:obj:`int`): Defines the day of the month whereby the job would run. It should @@ -288,14 +295,15 @@ class JobQueue: number, the job will not run in this month. Passing -1 leads to the job running on the last day of the month. context (:obj:`object`, optional): Additional data needed for the callback function. - Can be accessed through ``job.context`` in the callback. Defaults to :obj:`None`. + Can be accessed through :attr:`Job.context` in the callback. Defaults to + :obj:`None`. name (:obj:`str`, optional): The name of the new job. Defaults to ``callback.__name__``. job_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to pass to the - ``scheduler.add_job()``. + :meth:`apscheduler.schedulers.base.BaseScheduler.add_job()`. Returns: - :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job + :class:`telegram.ext.Job`: The new :class:`Job` instance that has been added to the job queue. """ @@ -329,7 +337,7 @@ class JobQueue: name: str = None, job_kwargs: JSONDict = None, ) -> 'Job': - """Creates a new ``Job`` that runs on a daily basis and adds it to the queue. + """Creates a new :class:`Job` that runs on a daily basis and adds it to the queue. Note: For a note about DST, please see the documentation of `APScheduler`_. @@ -339,20 +347,21 @@ class JobQueue: Args: callback (:obj:`callable`): The callback function that should be executed by the new - job. Callback signature: ``def callback(update: Update, context: CallbackContext)`` + job. Callback signature: ``def callback(context: CallbackContext)`` time (:obj:`datetime.time`): Time of day at which the job should run. If the timezone - (``time.tzinfo``) is :obj:`None`, the default timezone of the bot will be used. + (:obj:`time.tzinfo`) is :obj:`None`, the default timezone of the bot will be used. days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should run (where ``0-6`` correspond to monday - sunday). Defaults to ``EVERY_DAY`` context (:obj:`object`, optional): Additional data needed for the callback function. - Can be accessed through ``job.context`` in the callback. Defaults to :obj:`None`. + Can be accessed through :attr:`Job.context` in the callback. Defaults to + :obj:`None`. name (:obj:`str`, optional): The name of the new job. Defaults to ``callback.__name__``. job_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to pass to the - ``scheduler.add_job()``. + :meth:`apscheduler.schedulers.base.BaseScheduler.add_job()`. Returns: - :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job + :class:`telegram.ext.Job`: The new :class:`Job` instance that has been added to the job queue. """ @@ -385,20 +394,21 @@ class JobQueue: context: object = None, name: str = None, ) -> 'Job': - """Creates a new customly defined ``Job``. + """Creates a new custom defined :class:`Job`. Args: callback (:obj:`callable`): The callback function that should be executed by the new - job. Callback signature: ``def callback(update: Update, context: CallbackContext)`` + job. Callback signature: ``def callback(context: CallbackContext)`` job_kwargs (:obj:`dict`): Arbitrary keyword arguments. Used as arguments for - ``scheduler.add_job``. + :meth:`apscheduler.schedulers.base.BaseScheduler.add_job`. context (:obj:`object`, optional): Additional data needed for the callback function. - Can be accessed through ``job.context`` in the callback. Defaults to ``None``. + Can be accessed through :attr:`Job.context` in the callback. Defaults to + :obj:`None`. name (:obj:`str`, optional): The name of the new job. Defaults to ``callback.__name__``. Returns: - :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job + :class:`telegram.ext.Job`: The new :class:`Job` instance that has been added to the job queue. """ @@ -421,7 +431,7 @@ class JobQueue: self.scheduler.shutdown() def jobs(self) -> Tuple['Job', ...]: - """Returns a tuple of all *scheduled* jobs that are currently in the ``JobQueue``.""" + """Returns a tuple of all *scheduled* jobs that are currently in the :class:`JobQueue`.""" return tuple( Job._from_aps_job(job) # pylint: disable=protected-access for job in self.scheduler.get_jobs() @@ -429,7 +439,7 @@ class JobQueue: def get_jobs_by_name(self, name: str) -> Tuple['Job', ...]: """Returns a tuple of all *pending/scheduled* jobs with the given name that are currently - in the ``JobQueue``. + in the :class:`JobQueue`. """ return tuple(job for job in self.jobs() if job.name == name) @@ -446,7 +456,7 @@ class Job: * All attributes and instance methods of :attr:`job` are also directly available as attributes/methods of the corresponding :class:`telegram.ext.Job` object. * Two instances of :class:`telegram.ext.Job` are considered equal, if their corresponding - ``job`` attributes have the same ``id``. + :attr:`job` attributes have the same ``id``. * If :attr:`job` isn't passed on initialization, it must be set manually afterwards for this :class:`telegram.ext.Job` to be useful. @@ -455,9 +465,9 @@ class Job: Args: callback (:obj:`callable`): The callback function that should be executed by the new job. - Callback signature: ``def callback(update: Update, context: CallbackContext)`` + Callback signature: ``def callback(context: CallbackContext)`` context (:obj:`object`, optional): Additional data needed for the callback function. Can be - accessed through ``job.context`` in the callback. Defaults to :obj:`None`. + accessed through :attr:`Job.context` in the callback. Defaults to :obj:`None`. name (:obj:`str`, optional): The name of the new job. Defaults to ``callback.__name__``. job (:class:`apscheduler.job.Job`, optional): The APS Job this job is a wrapper for. @@ -498,7 +508,7 @@ class Job: """Executes the callback function independently of the jobs schedule. Also calls :meth:`telegram.ext.Dispatcher.update_persistence`. - .. versionchaged:: 14.0 + .. versionchanged:: 14.0 Calls :meth:`telegram.ext.Dispatcher.update_persistence`. Args: @@ -531,8 +541,8 @@ class Job: def schedule_removal(self) -> None: """ - Schedules this job for removal from the ``JobQueue``. It will be removed without executing - its callback function again. + Schedules this job for removal from the :class:`JobQueue`. It will be removed without + executing its callback function again. """ self.job.remove() self._removed = True @@ -559,7 +569,7 @@ class Job: def next_t(self) -> Optional[datetime.datetime]: """ :obj:`datetime.datetime`: Datetime for the next job execution. - Datetime is localized according to :attr:`tzinfo`. + Datetime is localized according to :attr:`datetime.datetime.tzinfo`. If job is removed or already ran it equals to :obj:`None`. """ return self.job.next_run_time