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 2025-01-10 20:12:52 +01:00
Code Issues Projects Releases Packages Wiki Activity

Doc fixes (#1884)

Browse source 
* Bot.py doc fixes

All docs obtained from official Bot API docs

* made flake8 happy

* address review

Also improved consistency of `returns:` in docs

Co-authored-by: Hinrich Mahler <hinrich.mahler@freenet.de>
This commit is contained in:
Harshil 2020-04-10 22:05:01 +04:00 committed by GitHub
parent c4364c7166
commit 0a9f4bfbdd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 175 additions and 162 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

337
telegram/bot.py
View file

@ -309,8 +309,8 @@ class Bot(TelegramObject):
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format @channelusername). of the target channel (in the format @channelusername).
text (:obj:`str`): Text of the message to be sent. Max 4096 characters. Also found as text (:obj:`str`): Text of the message to be sent. Max 4096 characters after entities
:attr:`telegram.constants.MAX_MESSAGE_LENGTH`. parsing. Also found as :attr:`telegram.constants.MAX_MESSAGE_LENGTH`.
parse_mode (:obj:`str`): Send Markdown or HTML, if you want Telegram apps to show bold, parse_mode (:obj:`str`): Send Markdown or HTML, if you want Telegram apps to show bold,
italic, fixed-width text or inline URLs in your bot's message. See the constants in italic, fixed-width text or inline URLs in your bot's message. See the constants in
:class:`telegram.ParseMode` for the available modes. :class:`telegram.ParseMode` for the available modes.
@ -369,9 +369,8 @@ class Bot(TelegramObject):
of the target channel (in the format @channelusername). of the target channel (in the format @channelusername).
message_id (:obj:`int`): Identifier of the message to delete. message_id (:obj:`int`): Identifier of the message to delete.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout the read timeout from the server (instead of the one specified during creation of
from the server (instead of the one specified during creation of the connection the connection pool).
pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns: Returns:
@ -408,9 +407,8 @@ class Bot(TelegramObject):
receive a notification with no sound. receive a notification with no sound.
message_id (:obj:`int`): Message identifier in the chat specified in from_chat_id. message_id (:obj:`int`): Message identifier in the chat specified in from_chat_id.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout the read timeout from the server (instead of the one specified during creation of
from the server (instead of the one specified during creation of the connection the connection pool).
pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns: Returns:
@ -516,9 +514,10 @@ class Bot(TelegramObject):
**kwargs): **kwargs):
""" """
Use this method to send audio files, if you want Telegram clients to display them in the Use this method to send audio files, if you want Telegram clients to display them in the
music player. Your audio must be in the .mp3 format. On success, the sent Message is music player. Your audio must be in the .mp3 or .m4a format.
returned. Bots can currently send audio files of up to 50 MB in size, this limit may be
changed in the future. Bots can currently send audio files of up to 50 MB in size, this limit may be changed in
the future.
For sending voice messages, use the sendVoice method instead. For sending voice messages, use the sendVoice method instead.
@ -549,10 +548,10 @@ class Bot(TelegramObject):
reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A
JSON-serialized object for an inline keyboard, custom reply keyboard, instructions JSON-serialized object for an inline keyboard, custom reply keyboard, instructions
to remove reply keyboard or to force a reply from the user. to remove reply keyboard or to force a reply from the user.
thumb (`filelike object`, optional): Thumbnail of the thumb (`filelike object`, optional): Thumbnail of the file sent; can be ignored if
file sent. The thumbnail should be in JPEG format and less than 200 kB in size. thumbnail generation for the file is supported server-side. The thumbnail should
A thumbnail's width and height should not exceed 320. Ignored if the file is not be in JPEG format and less than 200 kB in size. A thumbnail's width and height
is passed as a string or file_id. should not exceed 320. Ignored if the file is not is passed as a string or file_id.
timeout (:obj:`int` | :obj:`float`, optional): Send file timeout (default: 20 seconds). timeout (:obj:`int` | :obj:`float`, optional): Send file timeout (default: 20 seconds).
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
@ -604,7 +603,11 @@ class Bot(TelegramObject):
parse_mode=None, parse_mode=None,
thumb=None, thumb=None,
**kwargs): **kwargs):
"""Use this method to send general files. """
Use this method to send general files.
Bots can currently send files of any type of up to 50 MB in size, this limit may be
changed in the future.
Note: Note:
The document argument can be either a file_id, an URL or a file from disk The document argument can be either a file_id, an URL or a file from disk
@ -632,10 +635,10 @@ class Bot(TelegramObject):
reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A
JSON-serialized object for an inline keyboard, custom reply keyboard, instructions JSON-serialized object for an inline keyboard, custom reply keyboard, instructions
to remove reply keyboard or to force a reply from the user. to remove reply keyboard or to force a reply from the user.
thumb (`filelike object`, optional): Thumbnail of the thumb (`filelike object`, optional): Thumbnail of the file sent; can be ignored if
file sent. The thumbnail should be in JPEG format and less than 200 kB in size. thumbnail generation for the file is supported server-side. The thumbnail should
A thumbnail's width and height should not exceed 320. Ignored if the file is not be in JPEG format and less than 200 kB in size. A thumbnail's width and height
is passed as a string or file_id. should not exceed 320. Ignored if the file is not passed as a string or file_id.
timeout (:obj:`int` | :obj:`float`, optional): Send file timeout (default: 20 seconds). timeout (:obj:`int` | :obj:`float`, optional): Send file timeout (default: 20 seconds).
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
@ -677,7 +680,8 @@ class Bot(TelegramObject):
reply_markup=None, reply_markup=None,
timeout=20, timeout=20,
**kwargs): **kwargs):
"""Use this method to send .webp stickers. """
Use this method to send static .WEBP or animated .TGS stickers.
Note: Note:
The sticker argument can be either a file_id, an URL or a file from disk The sticker argument can be either a file_id, an URL or a file from disk
@ -741,6 +745,9 @@ class Bot(TelegramObject):
Use this method to send video files, Telegram clients support mp4 videos Use this method to send video files, Telegram clients support mp4 videos
(other formats may be sent as Document). (other formats may be sent as Document).
Bots can currently send video files of up to 50 MB in size, this limit may be changed in
the future.
Note: Note:
The video argument can be either a file_id, an URL or a file from disk The video argument can be either a file_id, an URL or a file from disk
``open(filename, 'rb')`` ``open(filename, 'rb')``
@ -770,10 +777,10 @@ class Bot(TelegramObject):
reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A
JSON-serialized object for an inline keyboard, custom reply keyboard, instructions JSON-serialized object for an inline keyboard, custom reply keyboard, instructions
to remove reply keyboard or to force a reply from the user. to remove reply keyboard or to force a reply from the user.
thumb (`filelike object`, optional): Thumbnail of the thumb (`filelike object`, optional): Thumbnail of the file sent; can be ignored if
file sent. The thumbnail should be in JPEG format and less than 200 kB in size. thumbnail generation for the file is supported server-side. The thumbnail should
A thumbnail's width and height should not exceed 320. Ignored if the file is not be in JPEG format and less than 200 kB in size. A thumbnail‘s width and height
is passed as a string or file_id. should not exceed 320. Ignored if the file is not is passed as a string or file_id.
timeout (:obj:`int` | :obj:`float`, optional): Send file timeout (default: 20 seconds). timeout (:obj:`int` | :obj:`float`, optional): Send file timeout (default: 20 seconds).
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
@ -826,7 +833,9 @@ class Bot(TelegramObject):
timeout=20, timeout=20,
thumb=None, thumb=None,
**kwargs): **kwargs):
"""Use this method to send video messages. """
As of v.4.0, Telegram clients support rounded square mp4 videos of up to 1 minute long.
Use this method to send video messages.
Note: Note:
The video_note argument can be either a file_id or a file from disk The video_note argument can be either a file_id or a file from disk
@ -841,7 +850,8 @@ class Bot(TelegramObject):
pass an existing :class:`telegram.VideoNote` object to send. Sending video notes by pass an existing :class:`telegram.VideoNote` object to send. Sending video notes by
a URL is currently unsupported. a URL is currently unsupported.
duration (:obj:`int`, optional): Duration of sent video in seconds. duration (:obj:`int`, optional): Duration of sent video in seconds.
length (:obj:`int`, optional): Video width and height length (:obj:`int`, optional): Video width and height, i.e. diameter of the video
message.
disable_notification (:obj:`bool`, optional): Sends the message silently. Users will disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
receive a notification with no sound. receive a notification with no sound.
reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the
@ -849,10 +859,10 @@ class Bot(TelegramObject):
reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A
JSON-serialized object for an inline keyboard, custom reply keyboard, JSON-serialized object for an inline keyboard, custom reply keyboard,
instructions to remove reply keyboard or to force a reply from the user. instructions to remove reply keyboard or to force a reply from the user.
thumb (`filelike object`, optional): Thumbnail of the thumb (`filelike object`, optional): Thumbnail of the file sent; can be ignored if
file sent. The thumbnail should be in JPEG format and less than 200 kB in size. thumbnail generation for the file is supported server-side. The thumbnail should
A thumbnail's width and height should not exceed 320. Ignored if the file is not be in JPEG format and less than 200 kB in size. A thumbnail‘s width and height
is passed as a string or file_id. should not exceed 320. Ignored if the file is not is passed as a string or file_id.
timeout (:obj:`int` | :obj:`float`, optional): Send file timeout (default: 20 seconds). timeout (:obj:`int` | :obj:`float`, optional): Send file timeout (default: 20 seconds).
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
@ -902,6 +912,8 @@ class Bot(TelegramObject):
**kwargs): **kwargs):
""" """
Use this method to send animation files (GIF or H.264/MPEG-4 AVC video without sound). Use this method to send animation files (GIF or H.264/MPEG-4 AVC video without sound).
Bots can currently send animation files of up to 50 MB in size, this limit may be changed
in the future.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -914,10 +926,10 @@ class Bot(TelegramObject):
duration (:obj:`int`, optional): Duration of sent animation in seconds. duration (:obj:`int`, optional): Duration of sent animation in seconds.
width (:obj:`int`, optional): Animation width. width (:obj:`int`, optional): Animation width.
height (:obj:`int`, optional): Animation height. height (:obj:`int`, optional): Animation height.
thumb (`filelike object`, optional): Thumbnail of the thumb (`filelike object`, optional): Thumbnail of the file sent; can be ignored if
file sent. The thumbnail should be in JPEG format and less than 200 kB in size. thumbnail generation for the file is supported server-side. The thumbnail should
A thumbnail's width and height should not exceed 320. Ignored if the file is not be in JPEG format and less than 200 kB in size. A thumbnail‘s width and height
is passed as a string or file_id. should not exceed 320. Ignored if the file is not is passed as a string or file_id.
caption (:obj:`str`, optional): Animation caption (may also be used when resending caption (:obj:`str`, optional): Animation caption (may also be used when resending
animations by file_id), 0-1024 characters after entities parsing. animations by file_id), 0-1024 characters after entities parsing.
parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
@ -983,7 +995,8 @@ class Bot(TelegramObject):
""" """
Use this method to send audio files, if you want Telegram clients to display the file Use this method to send audio files, if you want Telegram clients to display the file
as a playable voice message. For this to work, your audio must be in an .ogg file as a playable voice message. For this to work, your audio must be in an .ogg file
encoded with OPUS (other formats may be sent as Audio or Document). encoded with OPUS (other formats may be sent as Audio or Document). Bots can currently
send voice messages of up to 50 MB in size, this limit may be changed in the future.
Note: Note:
The voice argument can be either a file_id, an URL or a file from disk The voice argument can be either a file_id, an URL or a file from disk
@ -1183,20 +1196,21 @@ class Bot(TelegramObject):
specified. Unique identifier for the target chat or username of the target channel specified. Unique identifier for the target chat or username of the target channel
(in the format @channelusername). (in the format @channelusername).
message_id (:obj:`int`, optional): Required if inline_message_id is not specified. message_id (:obj:`int`, optional): Required if inline_message_id is not specified.
Identifier of the sent message. Identifier of the message to edit.
inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not
specified. Identifier of the inline message. specified. Identifier of the inline message.
latitude (:obj:`float`, optional): Latitude of location. latitude (:obj:`float`, optional): Latitude of location.
longitude (:obj:`float`, optional): Longitude of location. longitude (:obj:`float`, optional): Longitude of location.
location (:class:`telegram.Location`, optional): The location to send. location (:class:`telegram.Location`, optional): The location to send.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): A JSON-serialized reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): A JSON-serialized
object for an inline keyboard. object for a new inline keyboard.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout from the server (instead of the one specified during creation of the read timeout from the server (instead of the one specified during creation of
the connection pool). the connection pool).
Returns: Returns:
:class:`telegram.Message`: On success the edited message. :class:`telegram.Message`: On success, if edited message is sent by the bot, the
edited Message is returned, otherwise ``True`` is returned.
""" """
url = '{0}/editMessageLiveLocation'.format(self.base_url) url = '{0}/editMessageLiveLocation'.format(self.base_url)
@ -1235,21 +1249,22 @@ class Bot(TelegramObject):
(for inline bots) before live_period expires. (for inline bots) before live_period expires.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Required if inline_message_id is not specified.
of the target channel (in the format @channelusername). Unique identifier for the target chat or username of the target channel
(in the format @channelusername).
message_id (:obj:`int`, optional): Required if inline_message_id is not specified. message_id (:obj:`int`, optional): Required if inline_message_id is not specified.
Identifier of the sent message. Identifier of the sent message with live location to stop.
inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not
specified. Identifier of the inline message. specified. Identifier of the inline message.
reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): A JSON-serialized
JSON-serialized object for an inline keyboard, custom reply keyboard, instructions object for a new inline keyboard.
to remove reply keyboard or to force a reply from the user.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout from the server (instead of the one specified during creation of the read timeout from the server (instead of the one specified during creation of
the connection pool). the connection pool).
Returns: Returns:
:class:`telegram.Message`: On success the edited message. :class:`telegram.Message`: On success, if edited message is sent by the bot, the
edited Message is returned, otherwise ``True`` is returned.
""" """
url = '{0}/stopMessageLiveLocation'.format(self.base_url) url = '{0}/stopMessageLiveLocation'.format(self.base_url)
@ -1283,7 +1298,7 @@ class Bot(TelegramObject):
"""Use this method to send information about a venue. """Use this method to send information about a venue.
Note: Note:
you can either supply :obj:`venue`, or :obj:`latitude`, :obj:`longitude`, You can either supply :obj:`venue`, or :obj:`latitude`, :obj:`longitude`,
:obj:`title` and :obj:`address` and optionally :obj:`foursquare_id` and optionally :obj:`title` and :obj:`address` and optionally :obj:`foursquare_id` and optionally
:obj:`foursquare_type`. :obj:`foursquare_type`.
@ -1439,9 +1454,9 @@ class Bot(TelegramObject):
receive a notification with no sound. receive a notification with no sound.
reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the
original message. original message.
reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): A JSON-serialized
JSON-serialized object for an inline keyboard, custom reply keyboard, instructions object for a new inline keyboard. If empty, one ‘Play game_title’ button will be
to remove reply keyboard or to force a reply from the user. shown. If not empty, the first button must launch the game.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout from the server (instead of the one specified during creation of the read timeout from the server (instead of the one specified during creation of
the connection pool). the connection pool).
@ -1467,7 +1482,8 @@ class Bot(TelegramObject):
""" """
Use this method when you need to tell the user that something is happening on the bot's Use this method when you need to tell the user that something is happening on the bot's
side. The status is set for 5 seconds or less (when a message arrives from your bot, side. The status is set for 5 seconds or less (when a message arrives from your bot,
Telegram clients clear its typing status). Telegram clients clear its typing status). Telegram only recommends using this method when
a response from the bot will take a noticeable amount of time to arrive.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -1481,7 +1497,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns: Returns:
:obj:`bool`: ``True`` on success. :obj:`bool`: On success, ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -1545,7 +1561,7 @@ class Bot(TelegramObject):
where they wanted to use the bot's inline capabilities. where they wanted to use the bot's inline capabilities.
Returns: Returns:
:obj:`bool` On success, ``True`` is returned. :obj:`bool`: On success, ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -1640,6 +1656,11 @@ class Bot(TelegramObject):
valid for at least 1 hour. When the link expires, a new one can be requested by valid for at least 1 hour. When the link expires, a new one can be requested by
calling get_file again. calling get_file again.
Note:
This function may not preserve the original file name and MIME type.
You should save the file's MIME type and name (if available) when the File object
is received.
Args: Args:
file_id (:obj:`str` | :class:`telegram.Animation` | :class:`telegram.Audio` | \ file_id (:obj:`str` | :class:`telegram.Animation` | :class:`telegram.Audio` | \
:class:`telegram.ChatPhoto` | :class:`telegram.Document` | \ :class:`telegram.ChatPhoto` | :class:`telegram.Document` | \
@ -1680,9 +1701,10 @@ class Bot(TelegramObject):
@log @log
def kick_chat_member(self, chat_id, user_id, timeout=None, until_date=None, **kwargs): def kick_chat_member(self, chat_id, user_id, timeout=None, until_date=None, **kwargs):
""" """
Use this method to kick a user from a group or a supergroup. In the case of supergroups, Use this method to kick a user from a group or a supergroup or a channel. In the case of
the user will not be able to return to the group on their own using invite links, etc., supergroups and channels, the user will not be able to return to the group on their own
unless unbanned first. The bot must be an administrator in the group for this to work. using invite links, etc., unless unbanned first. The bot must be an administrator in the
group for this to work.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -1696,11 +1718,6 @@ class Bot(TelegramObject):
seconds from the current time they are considered to be banned forever. seconds from the current time they are considered to be banned forever.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Note:
In regular groups (non-supergroups), this method will only work if the
'All Members Are Admins' setting is off in the target group. Otherwise
members may only be removed by the group's creator or by the member that added them.
Returns: Returns:
:obj:`bool` On success, ``True`` is returned. :obj:`bool` On success, ``True`` is returned.
@ -1724,7 +1741,7 @@ class Bot(TelegramObject):
@log @log
def unban_chat_member(self, chat_id, user_id, timeout=None, **kwargs): def unban_chat_member(self, chat_id, user_id, timeout=None, **kwargs):
"""Use this method to unban a previously kicked user in a supergroup. """Use this method to unban a previously kicked user in a supergroup or channel.
The user will not return to the group automatically, but will be able to join via link, The user will not return to the group automatically, but will be able to join via link,
etc. The bot must be an administrator in the group for this to work. etc. The bot must be an administrator in the group for this to work.
@ -1835,10 +1852,10 @@ class Bot(TelegramObject):
specified. Unique identifier for the target chat or username of the target channel specified. Unique identifier for the target chat or username of the target channel
(in the format @channelusername) (in the format @channelusername)
message_id (:obj:`int`, optional): Required if inline_message_id is not specified. message_id (:obj:`int`, optional): Required if inline_message_id is not specified.
Identifier of the sent message. Identifier of the message to edit.
inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not
specified. Identifier of the inline message. specified. Identifier of the inline message.
text (:obj:`str`): New text of the message, 0-1024 characters after entities parsing. text (:obj:`str`): New text of the message, 1-4096 characters after entities parsing.
parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
show bold, italic, fixed-width text or inline URLs in your bot's message. See the show bold, italic, fixed-width text or inline URLs in your bot's message. See the
constants in :class:`telegram.ParseMode` for the available modes. constants in :class:`telegram.ParseMode` for the available modes.
@ -1895,10 +1912,11 @@ class Bot(TelegramObject):
specified. Unique identifier for the target chat or username of the target channel specified. Unique identifier for the target chat or username of the target channel
(in the format @channelusername) (in the format @channelusername)
message_id (:obj:`int`, optional): Required if inline_message_id is not specified. message_id (:obj:`int`, optional): Required if inline_message_id is not specified.
Identifier of the sent message. Identifier of the message to edit.
inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not
specified. Identifier of the inline message. specified. Identifier of the inline message.
caption (:obj:`str`, optional): New caption of the message. caption (:obj:`str`, optional): New caption of the message, 0-1024 characters after
entities parsing.
parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
show bold, italic, fixed-width text or inline URLs in the media caption. See the show bold, italic, fixed-width text or inline URLs in the media caption. See the
constants in :class:`telegram.ParseMode` for the available modes. constants in :class:`telegram.ParseMode` for the available modes.
@ -1948,19 +1966,18 @@ class Bot(TelegramObject):
reply_markup=None, reply_markup=None,
timeout=None, timeout=None,
**kwargs): **kwargs):
"""Use this method to edit audio, document, photo, or video messages. If a message is a """
part of a message album, then it can be edited only to a photo or a video. Otherwise, Use this method to edit animation, audio, document, photo, or video messages. If a
message type can be changed arbitrarily. When inline message is edited, new file can't be message is a part of a message album, then it can be edited only to a photo or a video.
uploaded. Use previously uploaded file via its file_id or specify a URL. On success, if the Otherwise, message type can be changed arbitrarily. When inline message is edited,
edited message was sent by the bot, the edited Message is returned, otherwise True is new file can't be uploaded. Use previously uploaded file via its file_id or specify a URL.
returned.
Args: Args:
chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
specified. Unique identifier for the target chat or username of the target channel specified. Unique identifier for the target chat or username of the target channel
(in the format @channelusername). (in the format @channelusername).
message_id (:obj:`int`, optional): Required if inline_message_id is not specified. message_id (:obj:`int`, optional): Required if inline_message_id is not specified.
Identifier of the sent message. Identifier of the message to edit.
inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not
specified. Identifier of the inline message. specified. Identifier of the inline message.
media (:class:`telegram.InputMedia`): An object for a new media content media (:class:`telegram.InputMedia`): An object for a new media content
@ -1971,6 +1988,13 @@ class Bot(TelegramObject):
the read timeout from the server (instead of the one specified during creation of the read timeout from the server (instead of the one specified during creation of
the connection pool). the connection pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:class:`telegram.Message`: On success, if edited message is sent by the bot, the
edited Message is returned, otherwise ``True`` is returned.
Raises:
:class:`telegram.TelegramError`
""" """
if inline_message_id is None and (chat_id is None or message_id is None): if inline_message_id is None and (chat_id is None or message_id is None):
@ -2008,7 +2032,7 @@ class Bot(TelegramObject):
specified. Unique identifier for the target chat or username of the target channel specified. Unique identifier for the target chat or username of the target channel
(in the format @channelusername). (in the format @channelusername).
message_id (:obj:`int`, optional): Required if inline_message_id is not specified. message_id (:obj:`int`, optional): Required if inline_message_id is not specified.
Identifier of the sent message. Identifier of the message to edit.
inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not
specified. Identifier of the inline message. specified. Identifier of the inline message.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): A JSON-serialized reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): A JSON-serialized
@ -2020,7 +2044,7 @@ class Bot(TelegramObject):
Returns: Returns:
:class:`telegram.Message`: On success, if edited message is sent by the bot, the :class:`telegram.Message`: On success, if edited message is sent by the bot, the
editedMessage is returned, otherwise ``True`` is returned. edited Message is returned, otherwise ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2130,13 +2154,13 @@ class Bot(TelegramObject):
**kwargs): **kwargs):
""" """
Use this method to specify a url and receive incoming updates via an outgoing webhook. Use this method to specify a url and receive incoming updates via an outgoing webhook.
Whenever there is an update for the bot, we will send an HTTPS POST request to the Whenever there is an update for the bot, Telegram will send an HTTPS POST request to the
specified url, containing a JSON-serialized Update. In case of an unsuccessful request, specified url, containing a JSON-serialized Update. In case of an unsuccessful request,
we will give up after a reasonable amount of attempts. Telegram will give up after a reasonable amount of attempts.
If you'd like to make sure that the Webhook request comes from Telegram, we recommend If you'd like to make sure that the Webhook request comes from Telegram, Telegram
using a secret path in the URL, e.g. https://www.example.com/<token>. Since nobody else recommends using a secret path in the URL, e.g. https://www.example.com/<token>. Since
knows your bot's token, you can be pretty sure it's us. nobody else knows your bot's token, you can be pretty sure it's us.
Note: Note:
The certificate argument should be a file from disk ``open(filename, 'rb')``. The certificate argument should be a file from disk ``open(filename, 'rb')``.
@ -2306,10 +2330,7 @@ class Bot(TelegramObject):
@log @log
def get_chat_administrators(self, chat_id, timeout=None, **kwargs): def get_chat_administrators(self, chat_id, timeout=None, **kwargs):
""" """
Use this method to get a list of administrators in a chat. On success, returns an Array of Use this method to get a list of administrators in a chat.
ChatMember objects that contains information about all chat administrators except other
bots. If the chat is a group or a supergroup and no administrators were appointed,
only the creator will be returned.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -2320,7 +2341,10 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns: Returns:
List[:class:`telegram.ChatMember`] List[:class:`telegram.ChatMember`]: On success, returns a list of ``ChatMember``
objects that contains information about all chat administrators except
other bots. If the chat is a group or a supergroup and no administrators were
appointed, only the creator will be returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2337,7 +2361,7 @@ class Bot(TelegramObject):
@log @log
def get_chat_members_count(self, chat_id, timeout=None, **kwargs): def get_chat_members_count(self, chat_id, timeout=None, **kwargs):
"""Use this method to get the number of members in a chat """Use this method to get the number of members in a chat.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -2348,7 +2372,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns: Returns:
int: Number of members in the chat. :obj:`int`: Number of members in the chat.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2411,7 +2435,7 @@ class Bot(TelegramObject):
Returns: Returns:
:obj:`bool`: True on success. :obj:`bool`: On success, ``True`` is returned.
""" """
url = '{0}/setChatStickerSet'.format(self.base_url) url = '{0}/setChatStickerSet'.format(self.base_url)
@ -2438,7 +2462,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns: Returns:
:obj:`bool`: True on success. :obj:`bool`: On success, ``True`` is returned.
""" """
url = '{0}/deleteChatStickerSet'.format(self.base_url) url = '{0}/deleteChatStickerSet'.format(self.base_url)
@ -2484,20 +2508,17 @@ class Bot(TelegramObject):
timeout=None, timeout=None,
**kwargs): **kwargs):
""" """
Use this method to set the score of the specified user in a game. On success, if the Use this method to set the score of the specified user in a game.
message was sent by the bot, returns the edited Message, otherwise returns True. Returns
an error, if the new score is not greater than the user's current score in the chat and
force is False.
Args: Args:
user_id (:obj:`int`): User identifier. user_id (:obj:`int`): User identifier.
score (:obj:`int`): New score, must be non-negative. score (:obj:`int`): New score, must be non-negative.
force (:obj:`bool`, optional): Pass True, if the high score is allowed to decrease. force (:obj:`bool`, optional): Pass True, if the high score is allowed to decrease.
This can be useful when fixing mistakes or banning cheaters This can be useful when fixing mistakes or banning cheaters.
disable_edit_message (:obj:`bool`, optional): Pass True, if the game message should not disable_edit_message (:obj:`bool`, optional): Pass True, if the game message should not
be automatically edited to include the current scoreboard. be automatically edited to include the current scoreboard.
chat_id (int|str, optional): Required if inline_message_id is not specified. Unique chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
identifier for the target chat. specified. Unique identifier for the target chat.
message_id (:obj:`int`, optional): Required if inline_message_id is not specified. message_id (:obj:`int`, optional): Required if inline_message_id is not specified.
Identifier of the sent message. Identifier of the sent message.
inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not
@ -2543,10 +2564,10 @@ class Bot(TelegramObject):
**kwargs): **kwargs):
""" """
Use this method to get data for high score tables. Will return the score of the specified Use this method to get data for high score tables. Will return the score of the specified
user and several of his neighbors in a game user and several of his neighbors in a game.
Args: Args:
user_id (:obj:`int`): User identifier. user_id (:obj:`int`): Target user id.
chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
specified. Unique identifier for the target chat. specified. Unique identifier for the target chat.
message_id (:obj:`int`, optional): Required if inline_message_id is not specified. message_id (:obj:`int`, optional): Required if inline_message_id is not specified.
@ -2612,8 +2633,8 @@ class Bot(TelegramObject):
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target private chat. chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target private chat.
title (:obj:`str`): Product name. title (:obj:`str`): Product name, 1-32 characters.
description (:obj:`str`): Product description. description (:obj:`str`): Product description, 1-255 characters.
payload (:obj:`str`): Bot-defined invoice payload, 1-128 bytes. This will not be payload (:obj:`str`): Bot-defined invoice payload, 1-128 bytes. This will not be
displayed to the user, use for your internal processes. displayed to the user, use for your internal processes.
provider_token (:obj:`str`): Payments provider token, obtained via Botfather. provider_token (:obj:`str`): Payments provider token, obtained via Botfather.
@ -2651,9 +2672,9 @@ class Bot(TelegramObject):
receive a notification with no sound. receive a notification with no sound.
reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the
original message. original message.
reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): A JSON-serialized
An inlinekeyboard. If empty, one 'Pay total price' button will be shown. object for an inline keyboard. If empty, one 'Pay total price' button will be
If not empty, the first button must be a Pay button. shown. If not empty, the first button must be a Pay button.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout from the server (instead of the one specified during creation of the read timeout from the server (instead of the one specified during creation of
the connection pool). the connection pool).
@ -2740,7 +2761,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns: Returns:
:obj:`bool`; On success, True is returned. :obj:`bool`: On success, True is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2788,7 +2809,7 @@ class Bot(TelegramObject):
pre_checkout_query_id (:obj:`str`): Unique identifier for the query to be answered. pre_checkout_query_id (:obj:`str`): Unique identifier for the query to be answered.
ok (:obj:`bool`): Specify True if everything is alright (goods are available, etc.) and ok (:obj:`bool`): Specify True if everything is alright (goods are available, etc.) and
the bot is ready to proceed with the order. Use False if there are any problems. the bot is ready to proceed with the order. Use False if there are any problems.
error_message (:obj:`str`, optional): Required if ok is False. Error message in human error_message (:obj:`str`, optional): Required if ok is False. Error message in human
readable form that explains the reason for failure to proceed with the checkout readable form that explains the reason for failure to proceed with the checkout
(e.g. "Sorry, somebody just bought the last of our amazing black T-shirts while you (e.g. "Sorry, somebody just bought the last of our amazing black T-shirts while you
were busy filling out your payment details. Please choose a different color or were busy filling out your payment details. Please choose a different color or
@ -2853,7 +2874,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments **kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns: Returns:
:obj:`bool`: Returns True on success. :obj:`bool`: On success, ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2881,7 +2902,7 @@ class Bot(TelegramObject):
""" """
Use this method to promote or demote a user in a supergroup or a channel. The bot must be Use this method to promote or demote a user in a supergroup or a channel. The bot must be
an administrator in the chat for this to work and must have the appropriate admin rights. an administrator in the chat for this to work and must have the appropriate admin rights.
Pass False for all boolean parameters to demote a user Pass False for all boolean parameters to demote a user.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -2911,7 +2932,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments **kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns: Returns:
:obj:`bool`: Returns True on success. :obj:`bool`: On success, ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2948,7 +2969,7 @@ class Bot(TelegramObject):
""" """
Use this method to set default chat permissions for all members. The bot must be an Use this method to set default chat permissions for all members. The bot must be an
administrator in the group or a supergroup for this to work and must have the administrator in the group or a supergroup for this to work and must have the
:attr:`can_restrict_members` admin rights. Returns True on success. :attr:`can_restrict_members` admin rights.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username of chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username of
@ -2960,7 +2981,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments **kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns: Returns:
:obj:`bool`: Returns True on success. :obj:`bool`: On success, ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2984,21 +3005,21 @@ class Bot(TelegramObject):
**kwargs): **kwargs):
""" """
Use this method to set a custom title for administrators promoted by the bot in a Use this method to set a custom title for administrators promoted by the bot in a
supergroup. The bot must be an administrator for this to work. Returns True on success. supergroup. The bot must be an administrator for this to work.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username of chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username of
the target supergroup (in the format `@supergroupusername`). the target supergroup (in the format `@supergroupusername`).
user_id (:obj:`int`): Unique identifier of the target administrator. user_id (:obj:`int`): Unique identifier of the target administrator.
custom_title (:obj:`str`) New custom title for the administrator. It must be a string custom_title (:obj:`str`) New custom title for the administrator; 0-16 characters,
with len 0-16 characters, emoji are not allowed. emoji are not allowed.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout from the server (instead of the one specified during creation of the read timeout from the server (instead of the one specified during creation of
the connection pool). the connection pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments **kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns: Returns:
:obj:`bool`: Returns True on success. :obj:`bool`: On success, ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3016,8 +3037,9 @@ class Bot(TelegramObject):
@log @log
def export_chat_invite_link(self, chat_id, timeout=None, **kwargs): def export_chat_invite_link(self, chat_id, timeout=None, **kwargs):
""" """
Use this method to export an invite link to a supergroup or a channel. The bot must be an Use this method to generate a new invite link for a chat; any previously generated link
administrator in the chat for this to work and must have the appropriate admin rights. is revoked. The bot must be an administrator in the chat for this to work and must have
the appropriate admin rights.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -3028,7 +3050,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments **kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns: Returns:
:obj:`str`: Exported invite link on success. :obj:`str`: New invite link on success.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3059,12 +3081,8 @@ class Bot(TelegramObject):
the connection pool). the connection pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments **kwargs (:obj:`dict`): Arbitrary keyword arguments
Note:
In regular groups (non-supergroups), this method will only work if the
'All Members Are Admins' setting is off in the target group.
Returns: Returns:
:obj:`bool`: Returns True on success. :obj:`bool`: On success, ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3097,12 +3115,8 @@ class Bot(TelegramObject):
the connection pool). the connection pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments **kwargs (:obj:`dict`): Arbitrary keyword arguments
Note:
In regular groups (non-supergroups), this method will only work if the
'All Members Are Admins' setting is off in the target group.
Returns: Returns:
:obj:`bool`: Returns ``True`` on success. :obj:`bool`: On success, ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3133,12 +3147,8 @@ class Bot(TelegramObject):
the connection pool). the connection pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments **kwargs (:obj:`dict`): Arbitrary keyword arguments
Note:
In regular groups (non-supergroups), this method will only work if the
'All Members Are Admins' setting is off in the target group.
Returns: Returns:
:obj:`bool`: Returns ``True`` on success. :obj:`bool`: On success, ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3163,14 +3173,14 @@ class Bot(TelegramObject):
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format @channelusername). of the target channel (in the format @channelusername).
description (:obj:`str`): New chat description, 1-255 characters. description (:obj:`str`): New chat description, 0-255 characters.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout from the server (instead of the one specified during creation of the read timeout from the server (instead of the one specified during creation of
the connection pool). the connection pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments **kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns: Returns:
:obj:`bool`: Returns ``True`` on success. :obj:`bool`: On success, ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3189,22 +3199,25 @@ class Bot(TelegramObject):
def pin_chat_message(self, chat_id, message_id, disable_notification=None, timeout=None, def pin_chat_message(self, chat_id, message_id, disable_notification=None, timeout=None,
**kwargs): **kwargs):
""" """
Use this method to pin a message in a supergroup. The bot must be an administrator in the Use this method to pin a message in a group, a supergroup, or a channel.
chat for this to work and must have the appropriate admin rights. The bot must be an administrator in the chat for this to work and must have the
‘can_pin_messages’ admin right in the supergroup or ‘can_edit_messages’ admin right
in the channel.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format @channelusername). of the target channel (in the format @channelusername).
message_id (:obj:`int`): Identifier of a message to pin. message_id (:obj:`int`): Identifier of a message to pin.
disable_notification (:obj:`bool`, optional): Pass True, if it is not necessary to send disable_notification (:obj:`bool`, optional): Pass True, if it is not necessary to send
a notification to all group members about the new pinned message. a notification to all group members about the new pinned message. Notifications
are always disabled in channels.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout from the server (instead of the one specified during creation of the read timeout from the server (instead of the one specified during creation of
the connection pool). the connection pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments **kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns: Returns:
:obj:`bool`: Returns ``True`` on success. :obj:`bool`: On success, ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3225,8 +3238,10 @@ class Bot(TelegramObject):
@log @log
def unpin_chat_message(self, chat_id, timeout=None, **kwargs): def unpin_chat_message(self, chat_id, timeout=None, **kwargs):
""" """
Use this method to unpin a message in a supergroup. The bot must be an administrator in the Use this method to unpin a message in a group, a supergroup, or a channel.
chat for this to work and must have the appropriate admin rights. The bot must be an administrator in the chat for this to work and must have the
``can_pin_messages`` admin right in the supergroup or ``can_edit_messages`` admin right
in the channel.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@ -3237,7 +3252,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments **kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns: Returns:
:obj:`bool`: Returns ``True`` on success. :obj:`bool`: On success, ``True`` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3257,8 +3272,7 @@ class Bot(TelegramObject):
"""Use this method to get a sticker set. """Use this method to get a sticker set.
Args: Args:
name (:obj:`str`): Short name of the sticker set that is used in t.me/addstickers/ name (:obj:`str`): Name of the sticker set.
URLs (e.g., animals)
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout from the server (instead of the one specified during the read timeout from the server (instead of the one specified during
creation of the connection pool). creation of the connection pool).
@ -3324,11 +3338,10 @@ class Bot(TelegramObject):
def create_new_sticker_set(self, user_id, name, title, emojis, png_sticker=None, def create_new_sticker_set(self, user_id, name, title, emojis, png_sticker=None,
contains_masks=None, mask_position=None, timeout=20, contains_masks=None, mask_position=None, timeout=20,
tgs_sticker=None, **kwargs): tgs_sticker=None, **kwargs):
"""Use this method to create new sticker set owned by a user. """
Use this method to create new sticker set owned by a user.
The bot will be able to edit the created sticker set. The bot will be able to edit the created sticker set.
You must use exactly one of the fields png_sticker or tgs_sticker.
You must use exactly one of the fields :attr:`png_sticker` or :attr:`tgs_sticker`.
Warning: Warning:
As of API 4.7 ``png_sticker`` is an optional argument and therefore the order of the As of API 4.7 ``png_sticker`` is an optional argument and therefore the order of the
@ -3401,10 +3414,11 @@ class Bot(TelegramObject):
@log @log
def add_sticker_to_set(self, user_id, name, emojis, png_sticker=None, mask_position=None, def add_sticker_to_set(self, user_id, name, emojis, png_sticker=None, mask_position=None,
timeout=20, tgs_sticker=None, **kwargs): timeout=20, tgs_sticker=None, **kwargs):
"""Use this method to add a new sticker to a set created by the bot. You must use exactly """
one of the fields png_sticker or tgs_sticker. Animated stickers can be added to animated Use this method to add a new sticker to a set created by the bot.
sticker sets and only to them. Animated sticker sets can have up to 50 stickers. Static You must use exactly one of the fields png_sticker or tgs_sticker. Animated stickers
sticker sets can have up to 120 stickers. can be added to animated sticker sets and only to them. Animated sticker sets can have up
to 50 stickers. Static sticker sets can have up to 120 stickers.
Warning: Warning:
As of API 4.7 ``png_sticker`` is an optional argument and therefore the order of the As of API 4.7 ``png_sticker`` is an optional argument and therefore the order of the
@ -3430,7 +3444,7 @@ class Bot(TelegramObject):
requirements requirements
emojis (:obj:`str`): One or more emoji corresponding to the sticker. emojis (:obj:`str`): One or more emoji corresponding to the sticker.
mask_position (:class:`telegram.MaskPosition`, optional): Position where the mask mask_position (:class:`telegram.MaskPosition`, optional): Position where the mask
should beplaced on faces. should be placed on faces.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout from the server (instead of the one specified during the read timeout from the server (instead of the one specified during
creation of the connection pool). creation of the connection pool).
@ -3567,8 +3581,7 @@ class Bot(TelegramObject):
""" """
Informs a user that some of the Telegram Passport elements they provided contains errors. Informs a user that some of the Telegram Passport elements they provided contains errors.
The user will not be able to re-submit their Passport to you until the errors are fixed The user will not be able to re-submit their Passport to you until the errors are fixed
(the contents of the field for which you returned the error must change). Returns True (the contents of the field for which you returned the error must change).
on success.
Use this if the data submitted by the user doesn't satisfy the standards your service Use this if the data submitted by the user doesn't satisfy the standards your service
requires for any reason. For example, if a birthday date seems invalid, a submitted requires for any reason. For example, if a birthday date seems invalid, a submitted
@ -3619,7 +3632,8 @@ class Bot(TelegramObject):
Use this method to send a native poll. Use this method to send a native poll.
Args: Args:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target private chat. chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format @channelusername).
question (:obj:`str`): Poll question, 1-255 characters. question (:obj:`str`): Poll question, 1-255 characters.
options (List[:obj:`str`]): List of answer options, 2-10 strings 1-100 characters each. options (List[:obj:`str`]): List of answer options, 2-10 strings 1-100 characters each.
is_anonymous (:obj:`bool`, optional): True, if the poll needs to be anonymous, is_anonymous (:obj:`bool`, optional): True, if the poll needs to be anonymous,
@ -3627,9 +3641,9 @@ class Bot(TelegramObject):
type (:obj:`str`, optional): Poll type, :attr:`telegram.Poll.QUIZ` or type (:obj:`str`, optional): Poll type, :attr:`telegram.Poll.QUIZ` or
:attr:`telegram.Poll.REGULAR`, defaults to :attr:`telegram.Poll.REGULAR`. :attr:`telegram.Poll.REGULAR`, defaults to :attr:`telegram.Poll.REGULAR`.
allows_multiple_answers (:obj:`bool`, optional): True, if the poll allows multiple allows_multiple_answers (:obj:`bool`, optional): True, if the poll allows multiple
answers, ignored for polls in quiz mode, defaults to False answers, ignored for polls in quiz mode, defaults to False.
correct_option_id (:obj:`int`, optional): 0-based identifier of the correct answer correct_option_id (:obj:`int`, optional): 0-based identifier of the correct answer
option, required for polls in quiz mode option, required for polls in quiz mode.
is_closed (:obj:`bool`, optional): Pass True, if the poll needs to be immediately is_closed (:obj:`bool`, optional): Pass True, if the poll needs to be immediately
closed. This can be useful for poll preview. closed. This can be useful for poll preview.
disable_notification (:obj:`bool`, optional): Sends the message silently. Users will disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
@ -3688,17 +3702,16 @@ class Bot(TelegramObject):
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format @channelusername). of the target channel (in the format @channelusername).
message_id (:obj:`int`): Identifier of the original message with the poll. message_id (:obj:`int`): Identifier of the original message with the poll.
reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): A JSON-serialized
JSON-serialized object for an inline keyboard, custom reply keyboard, instructions object for a new message inline keyboard.
to remove reply keyboard or to force a reply from the user.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout from the server (instead of the one specified during creation of the read timeout from the server (instead of the one specified during creation of
the connection pool). the connection pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns: Returns:
:class:`telegram.Poll`: On success, the stopped Poll with the :class:`telegram.Poll`: On success, the stopped Poll with the final results is
final results is returned. returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`