OpenSource/python-telegram-bot
OpenSource/python-telegram-bot
1
0
Fork 0
mirror of https://github.com/python-telegram-bot/python-telegram-bot.git synced 2024-12-22 14:35:00 +01:00
Code Issues Projects Releases Packages Wiki Activity

Documentation Improvements (#2693, #2691, #2739)

Browse source
This commit is contained in:
Bibo-Joshi 2021-12-13 18:21:38 +01:00 committed by Hinrich Mahler
parent 89d5310504
commit ced58b790e
32 changed files with 141 additions and 117 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/CONTRIBUTING.rst vendored
View file

@ -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:

6
README.rst
View file

@ -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 <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/README.md>`_ to discover the official examples or look at the examples on the `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Examples>`_ 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

2
README_RAW.rst
View file

@ -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

10
docs/source/conf.py
View file

@ -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'

2
telegram/_callbackquery.py
View file

@ -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

2
telegram/_chatmemberupdated.py
View file

@ -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.

2
telegram/_choseninlineresult.py
View file

@ -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 <https://t.me/BotFather>`_ in
order to receive these objects in updates.

4
telegram/_files/animation.py
View file

@ -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.
"""

4
telegram/_files/audio.py
View file

@ -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.

4
telegram/_files/document.py
View file

@ -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.
"""

4
telegram/_files/file.py
View file

@ -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.
"""

8
telegram/_files/inputmedia.py
View file

@ -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.

4
telegram/_files/photosize.py
View file

@ -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.
"""

4
telegram/_files/sticker.py
View file

@ -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.
"""

4
telegram/_files/video.py
View file

@ -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.
"""

4
telegram/_files/videonote.py
View file

@ -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.
"""

4
telegram/_files/voice.py
View file

@ -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.
"""

2
telegram/_inline/inlinequery.py
View file

@ -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.

4
telegram/_inline/inlinequeryresultdocument.py
View file

@ -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.

4
telegram/_inline/inlinequeryresultgif.py
View file

@ -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.

4
telegram/_inline/inlinequeryresultmpeg4gif.py
View file

@ -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.

4
telegram/_inline/inlinequeryresultphoto.py
View file

@ -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.

4
telegram/_inline/inlinequeryresultvideo.py
View file

@ -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

2
telegram/_message.py
View file

@ -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.

4
telegram/_passport/passportfile.py
View file

@ -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.

2
telegram/_payment/precheckoutquery.py
View file

@ -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.

2
telegram/_payment/shippingquery.py
View file

@ -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.

48
telegram/_poll.py
View file

@ -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__ = (

7
telegram/error.py
View file

@ -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',)

4
telegram/ext/_builders.py
View file

@ -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

5
telegram/ext/_dispatcher.py
View file

@ -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`.
"""

92
telegram/ext/_jobqueue.py
View file

@ -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