From 5555582b72678ae93b29fb3f544453bf411b5490 Mon Sep 17 00:00:00 2001 From: Bibo-Joshi Date: Wed, 7 Oct 2020 17:12:05 +0200 Subject: [PATCH] Doc Fixes/Additions (#2094) * Add notes on thumbs being ignored for small video files * Fix some cross refs * Add not to DictPersistence about it not actually writing to file * Fix reply_to_message docs of Message --- telegram/bot.py | 19 +++++++++++++++---- telegram/ext/dictpersistence.py | 6 ++++++ telegram/ext/filters.py | 2 +- telegram/files/inputmedia.py | 9 ++++++--- telegram/message.py | 10 +++++----- 5 files changed, 33 insertions(+), 13 deletions(-) diff --git a/telegram/bot.py b/telegram/bot.py index 823bd4fc9..ebed048b7 100644 --- a/telegram/bot.py +++ b/telegram/bot.py @@ -751,8 +751,11 @@ class Bot(TelegramObject): the future. Note: - The video argument can be either a file_id, an URL or a file from disk - ``open(filename, 'rb')`` + * The video argument can be either a file_id, an URL or a file from disk + ``open(filename, 'rb')`` + * ``thumb`` will be ignored for small video files, for which Telegram can easily + generate thumb nails. However, this behaviour is undocumented and might be changed + by Telegram. Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username @@ -841,8 +844,11 @@ class Bot(TelegramObject): Use this method to send video messages. Note: - The video_note argument can be either a file_id or a file from disk - ``open(filename, 'rb')`` + * The video_note argument can be either a file_id or a file from disk + ``open(filename, 'rb')`` + * ``thumb`` will be ignored for small video files, for which Telegram can easily + generate thumb nails. However, this behaviour is undocumented and might be changed + by Telegram. Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username @@ -919,6 +925,11 @@ class Bot(TelegramObject): Bots can currently send animation files of up to 50 MB in size, this limit may be changed in the future. + Note: + ``thumb`` will be ignored for small files, for which Telegram can easily + generate thumb nails. However, this behaviour is undocumented and might be changed + by Telegram. + Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username of the target channel (in the format @channelusername). diff --git a/telegram/ext/dictpersistence.py b/telegram/ext/dictpersistence.py index 84d4161ce..c70fee54c 100644 --- a/telegram/ext/dictpersistence.py +++ b/telegram/ext/dictpersistence.py @@ -33,6 +33,12 @@ from telegram.ext import BasePersistence class DictPersistence(BasePersistence): """Using python's dicts and json for making your bot persistent. + Note: + This class does *not* implement a :meth:`flush` method, meaning that data managed by + ``DictPersistence`` is in-memory only and will be lost when the bot shuts down. This is, + because ``DictPersistence`` is mainly intended as starting point for custom persistence + classes that need to JSON-serialize the stored data before writing them to file/database. + Attributes: store_user_data (:obj:`bool`): Whether user_data should be saved by this persistence class. diff --git a/telegram/ext/filters.py b/telegram/ext/filters.py index ba89877de..d4e9cafe3 100644 --- a/telegram/ext/filters.py +++ b/telegram/ext/filters.py @@ -748,7 +748,7 @@ officedocument.wordprocessingml.document")``- migrate = _Migrate() """Messages that contain :attr:`telegram.Message.migrate_from_chat_id` or - :attr: `telegram.Message.migrate_to_chat_id`.""" + :attr:`telegram.Message.migrate_to_chat_id`.""" class _PinnedMessage(BaseFilter): name = 'Filters.status_update.pinned_message' diff --git a/telegram/files/inputmedia.py b/telegram/files/inputmedia.py index 32b8ef386..d4ec84703 100644 --- a/telegram/files/inputmedia.py +++ b/telegram/files/inputmedia.py @@ -181,9 +181,12 @@ class InputMediaVideo(InputMedia): Thumbnails can't be reused and can be only uploaded as a new file. Note: - When using a :class:`telegram.Video` for the :attr:`media` attribute. It will take the - width, height and duration from that video, unless otherwise specified with the optional - arguments. + * When using a :class:`telegram.Video` for the :attr:`media` attribute. It will take the + width, height and duration from that video, unless otherwise specified with the optional + arguments. + * ``thumb`` will be ignored for small video files, for which Telegram can easily + generate thumb nails. However, this behaviour is undocumented and might be changed + by Telegram. """ def __init__(self, media, caption=None, width=None, height=None, duration=None, diff --git a/telegram/message.py b/telegram/message.py index 6bf90265d..032fc47b3 100644 --- a/telegram/message.py +++ b/telegram/message.py @@ -47,7 +47,9 @@ class Message(TelegramObject): forward_from_message_id (:obj:`int`): Optional. Identifier of the original message in the channel. forward_date (:class:`datetime.datetime`): Optional. Date the original message was sent. - reply_to_message (:class:`telegram.Message`): Optional. The original message. + reply_to_message (:class:`telegram.Message`): Optional. For replies, the original message. + Note that the Message object in this field will not contain further + ``reply_to_message`` fields even if it itself is a reply. edit_date (:class:`datetime.datetime`): Optional. Date the message was last edited. media_group_id (:obj:`str`): Optional. The unique identifier of a media message group this message belongs to. @@ -132,8 +134,6 @@ class Message(TelegramObject): forward_date (:class:`datetime.datetime`, optional): For forwarded messages, date the original message was sent in Unix time. Converted to :class:`datetime.datetime`. reply_to_message (:class:`telegram.Message`, optional): For replies, the original message. - Note that the Message object in this field will not contain further - ``reply_to_message`` fields even if it itself is a reply. edit_date (:class:`datetime.datetime`, optional): Date the message was last edited in Unix time. Converted to :class:`datetime.datetime`. media_group_id (:obj:`str`, optional): The unique identifier of a media message group this @@ -142,7 +142,7 @@ class Message(TelegramObject): characters. Also found as :attr:`telegram.constants.MAX_MESSAGE_LENGTH`. entities (List[:class:`telegram.MessageEntity`], optional): For text messages, special entities like usernames, URLs, bot commands, etc. that appear in the text. See - attr:`parse_entity` and attr:`parse_entities` methods for how to use properly. + :attr:`parse_entity` and :attr:`parse_entities` methods for how to use properly. caption_entities (List[:class:`telegram.MessageEntity`]): Optional. For Messages with a Caption. Special entities like usernames, URLs, bot commands, etc. that appear in the caption. See :attr:`Message.parse_caption_entity` and :attr:`parse_caption_entities` @@ -191,7 +191,7 @@ class Message(TelegramObject): channel_chat_created (:obj:`bool`, optional): Service message: The channel has been created. This field can't be received in a message coming through updates, because bot can't be a member of a channel when it is created. It can only be found in - attr:`reply_to_message` if someone replies to a very first message in a channel. + :attr:`reply_to_message` if someone replies to a very first message in a channel. migrate_to_chat_id (:obj:`int`, optional): The group has been migrated to a supergroup with the specified identifier. This number may be greater than 32 bits and some programming languages may have difficulty/silent defects in interpreting it. But it is smaller than