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-03-29 09:40:31 +01:00
Code Issues Projects Releases Packages Wiki Activity

Documentation Improvements (#2008)

Browse source 
* Minor doc updates, following official API docs

* Fix spelling in Defaults docstrings

* Clarify Changelog of v12.7 about aware dates

* Fix typo in CHANGES.rst (#2024)

* Fix PicklePersistence.flush() with only bot_data (#2017)

* Update pylint in pre-commit to fix CI (#2018)

* Add Filters.via_bot (#2009)

* feat: via_bot filter

also fixing a small mistake in the empty parameter of the user filter and improve docs slightly

* fix: forgot to set via_bot to None

* fix: redoing subclassing to copy paste solution

* Cosmetic changes

Co-authored-by: Hinrich Mahler <hinrich.mahler@freenet.de>

* Update CHANGES.rst

Fixed Typo

Co-authored-by: Bibo-Joshi <hinrich.mahler@freenet.de>
Co-authored-by: Poolitzer <25934244+Poolitzer@users.noreply.github.com>

* Update downloads badge, add info on IRC Channel to Getting Help section

* Remove RegexHandler from ConversationHandlers Docs (#1973)

Replaced RegexHandler with MessageHandler, since the former is deprecated

* Fix Filters.via_bot docstrings

* Add notes on Markdown v1 being legacy mode

* Fixed typo in the Regex doc.. (#2036)

* Typo: Spelling

* Minor cleanup from #2043

* Document CommandHandler ignoring channel posts

* Doc fixes for a few telegram.ext classes

* Doc fixes for most `telegram` classes.

* pep-8

forgot the hard wrap is at 99 chars, not 100!
fixed a few spelling mistakes too.

* Address review and made rendering of booleans consistent

True, False, None are now rendered with ``bool`` wherever they weren't in telegram and telegram.ext classes.

* Few doc fixes for inline* classes

As usual, docs were cross-checked with official tg api docs.

* Doc fixes for telegram/files classes

As usual, docs were cross-checked with official tg api docs.

* Doc fixes for telegram.Game

Mostly just added hyperlinks. And fixed message length doc.

As usual, docs were cross-checked with official tg api docs.

* Very minor doc fix for passportfile.py and passportelementerrors.py

Didn't bother changing too much since this seems to be a custom implementation.

* Doc fixes for telegram.payments

As usual, cross-checked with official bot api docs.

* Address review 2

Few tiny other fixes too.

* Changed from ``True/False/None`` to :obj:`True/False/None` project-wide.

Few tiny other doc fixes too.

Co-authored-by: Robert Geislinger <mitachundkrach@gmail.com>
Co-authored-by: Poolitzer <25934244+Poolitzer@users.noreply.github.com>
Co-authored-by: GauthamramRavichandran <30320759+GauthamramRavichandran@users.noreply.github.com>
Co-authored-by: Mahesh19 <maheshvagicherla99438@gmail.com>
Co-authored-by: hoppingturtles <ilovebhagwan@gmail.com>
This commit is contained in:
Bibo-Joshi 2020-08-24 19:35:57 +02:00 • committed by GitHub
parent faa93fbf75
commit a0720b9ac6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
77 changed files with 911 additions and 874 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
CHANGES.rst
View file

@ -44,15 +44,15 @@ Version 12.7
**Major Changes:** **Major Changes:**
- Bot API 4.8 support. **Note:** The ``Dice`` object now has a second positional argument ``emoji``. This is relevant, if you instantiate ``Dice`` objects manually. (`#1917`_) - Bot API 4.8 support. **Note:** The ``Dice`` object now has a second positional argument ``emoji``. This is relevant, if you instantiate ``Dice`` objects manually. (`#1917`_)
- Added ``tzinfo`` argument to ``helpers.from_timestamp``. It now returns an timezone aware object. This is relevant for ``Message.{date,forward_date,edit_date}``, ``Poll.close_date`` and ``ChatMember.until_date`` (`#1621`_)
**New Features:** **New Features:**
- New method ``run_mothly`` for the ``JobQueue`` (`#1705`_) - New method ``run_monthly`` for the ``JobQueue`` (`#1705`_)
- ``Job.next_t`` now gives the datetime of the jobs next execution (`#1685`_) - ``Job.next_t`` now gives the datetime of the jobs next execution (`#1685`_)
**Minor changes, CI improvements, doc fixes or bug fixes:** **Minor changes, CI improvements, doc fixes or bug fixes:**
- Added ``tzinfo`` argument to ``helpers.from_timestamp`` (`#1621`_)
- Stabalize CI (`#1919`_, `#1931`_) - Stabalize CI (`#1919`_, `#1931`_)
- Use ABCs ``@abstractmethod`` instead of raising ``NotImplementedError`` for ``Handler``, ``BasePersistence`` and ``BaseFilter`` (`#1905`_) - Use ABCs ``@abstractmethod`` instead of raising ``NotImplementedError`` for ``Handler``, ``BasePersistence`` and ``BaseFilter`` (`#1905`_)
- Doc fixes (`#1914`_, `#1902`_, `#1910`_) - Doc fixes (`#1914`_, `#1902`_, `#1910`_)

10
README.rst
View file

@ -17,7 +17,7 @@ We have a vibrant community of developers helping each other in our `Telegram gr
:target: https://pypi.org/project/python-telegram-bot/ :target: https://pypi.org/project/python-telegram-bot/
:alt: Supported Python versions :alt: Supported Python versions
.. image:: https://www.cpu.re/static/python-telegram-bot/downloads.svg .. image:: https://cpu.re/static/python-telegram-bot/downloads.svg
:target: https://www.cpu.re/static/python-telegram-bot/downloads-by-python-version.txt :target: https://www.cpu.re/static/python-telegram-bot/downloads-by-python-version.txt
:alt: PyPi Package Monthly Download :alt: PyPi Package Monthly Download
@ -187,11 +187,13 @@ You can get help in several ways:
1. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us! 1. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
2. Report bugs, request new features or ask questions by `creating an issue <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_. 2. In case you are unable to join our group due to Telegram restrictions, you can use our `IRC channel <https://webchat.freenode.net/?channels=##python-telegram-bot>`_.
3. Our `Wiki pages <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ offer a growing amount of resources. 3. Report bugs, request new features or ask questions by `creating an issue <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_.
4. You can even ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_. 4. Our `Wiki pages <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ offer a growing amount of resources.
5. You can even ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.

2
examples/README.md
View file

@ -44,7 +44,7 @@ A basic example of a bot that can accept passports. Use in combination with [`pa
A basic example of a bot that can accept payments. Don't forget to enable and configure payments with [@BotFather](https://telegram.me/BotFather). A basic example of a bot that can accept payments. Don't forget to enable and configure payments with [@BotFather](https://telegram.me/BotFather).
### [`errorhandlerbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/errorhandlerbot.py) ### [`errorhandlerbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/errorhandlerbot.py)
A basic example on how to set up a costum error handler. A basic example on how to set up a custom error handler.
## Pure API ## Pure API
The [`rawapibot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/rawapibot.py) example uses only the pure, "bare-metal" API wrapper. The [`rawapibot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/rawapibot.py) example uses only the pure, "bare-metal" API wrapper.

228
telegram/bot.py
View file

@ -373,7 +373,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -769,7 +769,7 @@ class Bot(TelegramObject):
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.
supports_streaming (:obj:`bool`, optional): Pass True, if the uploaded video is supports_streaming (:obj:`bool`, optional): Pass :obj:`True`, if the uploaded video is
suitable for streaming. suitable for streaming.
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.
@ -1214,7 +1214,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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
url = '{}/editMessageLiveLocation'.format(self.base_url) url = '{}/editMessageLiveLocation'.format(self.base_url)
@ -1268,7 +1268,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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
url = '{}/stopMessageLiveLocation'.format(self.base_url) url = '{}/stopMessageLiveLocation'.format(self.base_url)
@ -1453,7 +1453,7 @@ 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).
game_short_name (:obj:`str`): Short name of the game, serves as the unique identifier game_short_name (:obj:`str`): Short name of the game, serves as the unique identifier
for the game. Set up your games via Botfather. for the game. Set up your games via `@BotFather <https://t.me/BotFather>`_.
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
@ -1501,7 +1501,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -1537,9 +1537,9 @@ class Bot(TelegramObject):
query. query.
cache_time (:obj:`int`, optional): The maximum amount of time in seconds that the cache_time (:obj:`int`, optional): The maximum amount of time in seconds that the
result of the inline query may be cached on the server. Defaults to 300. result of the inline query may be cached on the server. Defaults to 300.
is_personal (:obj:`bool`, optional): Pass True, if results may be cached on the server is_personal (:obj:`bool`, optional): Pass :obj:`True`, if results may be cached on
side only for the user that sent the query. By default, results may be returned to the server side only for the user that sent the query. By default,
any user who sends the same query. results may be returned to any user who sends the same query.
next_offset (:obj:`str`, optional): Pass the offset that a client should send in the next_offset (:obj:`str`, optional): Pass the offset that a client should send in the
next query with the same text to receive more results. Pass an empty string if next query with the same text to receive more results. Pass an empty string if
there are no more results or if you don't support pagination. Offset length can't there are no more results or if you don't support pagination. Offset length can't
@ -1551,7 +1551,7 @@ class Bot(TelegramObject):
message sent to the bot when user presses the switch button. 1-64 characters, message sent to the bot when user presses the switch button. 1-64 characters,
only A-Z, a-z, 0-9, _ and - are allowed. only A-Z, a-z, 0-9, _ and - are 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
he 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.
@ -1565,7 +1565,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -1723,7 +1723,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -1760,7 +1760,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -1797,10 +1797,12 @@ class Bot(TelegramObject):
callback_query_id (:obj:`str`): Unique identifier for the query to be answered. callback_query_id (:obj:`str`): Unique identifier for the query to be answered.
text (:obj:`str`, optional): Text of the notification. If not specified, nothing will text (:obj:`str`, optional): Text of the notification. If not specified, nothing will
be shown to the user, 0-200 characters. be shown to the user, 0-200 characters.
show_alert (:obj:`bool`, optional): If true, an alert will be shown by the client show_alert (:obj:`bool`, optional): If :obj:`True`, an alert will be shown by the
instead of a notification at the top of the chat screen. Defaults to false. client instead of a notification at the top of the chat screen. Defaults to
:obj:`False`.
url (:obj:`str`, optional): URL that will be opened by the user's client. If you have url (:obj:`str`, optional): URL that will be opened by the user's client. If you have
created a Game and accepted the conditions via @Botfather, specify the URL that created a Game and accepted the conditions via
`@BotFather <https://t.me/BotFather>`_, specify the URL that
opens your game - note that this will only work if the query comes from a callback opens your game - note that this will only work if the query comes from a callback
game button. Otherwise, you may use links like t.me/your_bot?start=XXXX that open game button. Otherwise, you may use links like t.me/your_bot?start=XXXX that open
your bot with a parameter. your bot with a parameter.
@ -1812,7 +1814,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -1874,7 +1876,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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -1933,7 +1935,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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -1995,7 +1997,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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2048,7 +2050,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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2204,7 +2206,7 @@ class Bot(TelegramObject):
Webhooks`_. Webhooks`_.
Returns: Returns:
:obj:`bool` On success, ``True`` is returned. :obj:`bool` On success, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2256,7 +2258,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2283,7 +2285,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2439,7 +2441,7 @@ class Bot(TelegramObject):
Returns: Returns:
:obj:`bool`: On success, ``True`` is returned. :obj:`bool`: On success, :obj:`True` is returned.
""" """
url = '{}/setChatStickerSet'.format(self.base_url) url = '{}/setChatStickerSet'.format(self.base_url)
@ -2466,7 +2468,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, :obj:`True` is returned.
""" """
url = '{}/deleteChatStickerSet'.format(self.base_url) url = '{}/deleteChatStickerSet'.format(self.base_url)
@ -2517,10 +2519,10 @@ class Bot(TelegramObject):
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 :obj:`True`, if the high score is allowed to
This can be useful when fixing mistakes or banning cheaters. decrease. 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 :obj:`True`, if the game message
be automatically edited to include the current scoreboard. should not be automatically edited to include the current scoreboard.
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.
@ -2534,11 +2536,11 @@ class Bot(TelegramObject):
Returns: Returns:
:class:`telegram.Message`: The edited message, or if the message wasn't sent by the bot :class:`telegram.Message`: The edited message, or if the message wasn't sent by the bot
, ``True``. , :obj:`True`.
Raises: Raises:
:class:`telegram.TelegramError`: If the new score is not greater than the user's :class:`telegram.TelegramError`: If the new score is not greater than the user's
current score in the chat and force is False. current score in the chat and force is :obj:`False`.
""" """
url = '{}/setGameScore'.format(self.base_url) url = '{}/setGameScore'.format(self.base_url)
@ -2641,14 +2643,15 @@ class Bot(TelegramObject):
description (:obj:`str`): Product description, 1-255 characters. 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 <https://t.me/BotFather>`_.
start_parameter (:obj:`str`): Unique deep-linking parameter that can be used to start_parameter (:obj:`str`): Unique deep-linking parameter that can be used to
generate this invoice when used as a start parameter. generate this invoice when used as a start parameter.
currency (:obj:`str`): Three-letter ISO 4217 currency code. currency (:obj:`str`): Three-letter ISO 4217 currency code.
prices (List[:class:`telegram.LabeledPrice`)]: Price breakdown, a JSON-serialized list prices (List[:class:`telegram.LabeledPrice`)]: Price breakdown, a JSON-serialized list
of components (e.g. product price, tax, discount, delivery cost, delivery tax, of components (e.g. product price, tax, discount, delivery cost, delivery tax,
bonus, etc.). bonus, etc.).
provider_data (:obj:`str` | :obj:`object`, optional): JSON-encoded data about the provider_data (:obj:`str` | :obj:`object`, optional): JSON-serialized data about the
invoice, which will be shared with the payment provider. A detailed description of invoice, which will be shared with the payment provider. A detailed description of
required fields should be provided by the payment provider. When an object is required fields should be provided by the payment provider. When an object is
passed, it will be encoded as JSON. passed, it will be encoded as JSON.
@ -2658,20 +2661,20 @@ class Bot(TelegramObject):
photo_size (:obj:`str`, optional): Photo size. photo_size (:obj:`str`, optional): Photo size.
photo_width (:obj:`int`, optional): Photo width. photo_width (:obj:`int`, optional): Photo width.
photo_height (:obj:`int`, optional): Photo height. photo_height (:obj:`int`, optional): Photo height.
need_name (:obj:`bool`, optional): Pass True, if you require the user's full name to need_name (:obj:`bool`, optional): Pass :obj:`True`, if you require the user's full
complete the order. name to complete the order.
need_phone_number (:obj:`bool`, optional): Pass True, if you require the user's need_phone_number (:obj:`bool`, optional): Pass :obj:`True`, if you require the user's
phone number to complete the order. phone number to complete the order.
need_email (:obj:`bool`, optional): Pass True, if you require the user's email to need_email (:obj:`bool`, optional): Pass :obj:`True`, if you require the user's email
complete the order. to complete the order.
need_shipping_address (:obj:`bool`, optional): Pass True, if you require the user's need_shipping_address (:obj:`bool`, optional): Pass :obj:`True`, if you require the
shipping address to complete the order. user's shipping address to complete the order.
send_phone_number_to_provider (:obj:`bool`, optional): Pass True, if user's phone send_phone_number_to_provider (:obj:`bool`, optional): Pass :obj:`True`, if user's
number should be sent to provider. phone number should be sent to provider.
send_email_to_provider (:obj:`bool`, optional): Pass True, if user's email address send_email_to_provider (:obj:`bool`, optional): Pass :obj:`True`, if user's email
should be sent to provider. address should be sent to provider.
is_flexible (:obj:`bool`, optional): Pass True, if the final price depends on the is_flexible (:obj:`bool`, optional): Pass :obj:`True`, if the final price depends on
shipping method. the shipping method.
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
@ -2750,12 +2753,12 @@ class Bot(TelegramObject):
Args: Args:
shipping_query_id (:obj:`str`): Unique identifier for the query to be answered. shipping_query_id (:obj:`str`): Unique identifier for the query to be answered.
ok (:obj:`bool`): Specify True if delivery to the specified address is possible and ok (:obj:`bool`): Specify :obj:`True` if delivery to the specified address is possible
False if there are any problems (for example, if delivery to the specified address and :obj:`False` if there are any problems (for example, if delivery to the
is not possible). specified address is not possible).
shipping_options (List[:class:`telegram.ShippingOption`]), optional]: Required if ok is shipping_options (List[:class:`telegram.ShippingOption`]), optional]: Required if ok is
True. A JSON-serialized array of available shipping options. :obj:`True`. A JSON-serialized array of available shipping options.
error_message (:obj:`str`, optional): Required if ok is False. Error message in error_message (:obj:`str`, optional): Required if ok is :obj:`False`. Error message in
human readable form that explains why it is impossible to complete the order (e.g. human readable form that explains why it is impossible to complete the order (e.g.
"Sorry, delivery to your desired address is unavailable"). Telegram will display "Sorry, delivery to your desired address is unavailable"). Telegram will display
this message to the user. this message to the user.
@ -2765,7 +2768,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2811,20 +2814,21 @@ class Bot(TelegramObject):
Args: Args:
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 :obj:`True` if everything is alright
the bot is ready to proceed with the order. Use False if there are any problems. (goods are available, etc.) and the bot is ready to proceed with the order. Use
error_message (:obj:`str`, optional): Required if ok is False. Error message in human :obj:`False` if there are any problems.
readable form that explains the reason for failure to proceed with the checkout error_message (:obj:`str`, optional): Required if ok is :obj:`False`. Error message
(e.g. "Sorry, somebody just bought the last of our amazing black T-shirts while you in human readable form that explains the reason for failure to proceed with
were busy filling out your payment details. Please choose a different color or the checkout (e.g. "Sorry, somebody just bought the last of our amazing black
garment!"). Telegram will display this message to the user. T-shirts while you were busy filling out your payment details. Please choose a
different color or garment!"). Telegram will display this message to 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:
:obj:`bool`: On success, ``True`` is returned. :obj:`bool`: On success, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2855,8 +2859,8 @@ class Bot(TelegramObject):
timeout=None, **kwargs): timeout=None, **kwargs):
""" """
Use this method to restrict a user in a supergroup. The bot must be an administrator in Use this method to restrict a user in a supergroup. The bot must be an administrator in
the supergroup for this to work and must have the appropriate admin rights. Pass True for the supergroup for this to work and must have the appropriate admin rights. Pass
all boolean parameters to lift restrictions from a user. :obj:`True` for all boolean parameters to lift restrictions from a user.
Note: Note:
Since Bot API 4.4, :attr:`restrict_chat_member` takes the new user permissions in a Since Bot API 4.4, :attr:`restrict_chat_member` takes the new user permissions in a
@ -2871,14 +2875,15 @@ class Bot(TelegramObject):
will be lifted for the user, unix time. If user is restricted for more than 366 will be lifted for the user, unix time. If user is restricted for more than 366
days or less than 30 seconds from the current time, they are considered to be days or less than 30 seconds from the current time, they are considered to be
restricted forever. restricted forever.
permissions (:class:`telegram.ChatPermissions`): New user permissions. permissions (:class:`telegram.ChatPermissions`): A JSON-serialized object for new user
permissions.
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`: On success, ``True`` is returned. :obj:`bool`: On success, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2906,28 +2911,28 @@ 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 :obj:`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
of the target supergroup (in the format @supergroupusername). of the target supergroup (in the format @supergroupusername).
user_id (:obj:`int`): Unique identifier of the target user. user_id (:obj:`int`): Unique identifier of the target user.
can_change_info (:obj:`bool`, optional): Pass True, if the administrator can change can_change_info (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
chat title, photo and other settings. change chat title, photo and other settings.
can_post_messages (:obj:`bool`, optional): Pass True, if the administrator can can_post_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
create channel posts, channels only. create channel posts, channels only.
can_edit_messages (:obj:`bool`, optional): Pass True, if the administrator can edit can_edit_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
messages of other users, channels only. edit messages of other users, channels only.
can_delete_messages (:obj:`bool`, optional): Pass True, if the administrator can can_delete_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
delete messages of other users. delete messages of other users.
can_invite_users (:obj:`bool`, optional): Pass True, if the administrator can invite can_invite_users (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
new users to the chat. invite new users to the chat.
can_restrict_members (:obj:`bool`, optional): Pass True, if the administrator can can_restrict_members (:obj:`bool`, optional): Pass :obj:`True`, if the administrator
restrict, ban or unban chat members. can restrict, ban or unban chat members.
can_pin_messages (:obj:`bool`, optional): Pass True, if the administrator can pin can_pin_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
messages, supergroups only. pin messages, supergroups only.
can_promote_members (:obj:`bool`, optional): Pass True, if the administrator can add can_promote_members (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
new administrators with a subset of his own privileges or demote administrators add new administrators with a subset of his own privileges or demote administrators
that he has promoted, directly or indirectly (promoted by administrators that were that he has promoted, directly or indirectly (promoted by administrators that were
appointed by him). appointed by him).
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
@ -2936,7 +2941,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -2985,7 +2990,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3023,7 +3028,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3086,7 +3091,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3120,7 +3125,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3152,7 +3157,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3184,7 +3189,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3212,16 +3217,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 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 :obj:`True`, if it is not necessary
a notification to all group members about the new pinned message. Notifications to send a notification to all group members about the new pinned message.
are always disabled in channels. 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`: On success, ``True`` is returned. :obj:`bool`: On success, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3256,7 +3261,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3320,7 +3325,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns: Returns:
:class:`telegram.File`: The uploaded File :class:`telegram.File`: On success, the uploaded File is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3373,10 +3378,10 @@ class Bot(TelegramObject):
tgs_sticker (:obj:`str` | `filelike object`, optional): TGS animation with the sticker, tgs_sticker (:obj:`str` | `filelike object`, optional): TGS animation with the sticker,
uploaded using multipart/form-data. See uploaded using multipart/form-data. See
https://core.telegram.org/animated_stickers#technical-requirements for technical https://core.telegram.org/animated_stickers#technical-requirements for technical
requirements requirements.
emojis (:obj:`str`): One or more emoji corresponding to the sticker. emojis (:obj:`str`): One or more emoji corresponding to the sticker.
contains_masks (:obj:`bool`, optional): Pass True, if a set of mask stickers should be contains_masks (:obj:`bool`, optional): Pass :obj:`True`, if a set of mask stickers
created. should be created.
mask_position (:class:`telegram.MaskPosition`, optional): Position where the mask mask_position (:class:`telegram.MaskPosition`, optional): Position where the mask
should be placed 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
@ -3385,7 +3390,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3438,7 +3443,7 @@ class Bot(TelegramObject):
Args: Args:
user_id (:obj:`int`): User identifier of created sticker set owner. user_id (:obj:`int`): User identifier of created sticker set owner.
name (:obj:`str`): Sticker set name. name (:obj:`str`): Sticker set name.
png_sticker (:obj:`str` | `filelike object`, optional): Png image with the sticker, png_sticker (:obj:`str` | `filelike object`, optional): PNG image with the sticker,
must be up to 512 kilobytes in size, dimensions must not exceed 512px, must be up to 512 kilobytes in size, dimensions must not exceed 512px,
and either width or height must be exactly 512px. Pass a file_id as a String to and either width or height must be exactly 512px. Pass a file_id as a String to
send a file that already exists on the Telegram servers, pass an HTTP URL as a send a file that already exists on the Telegram servers, pass an HTTP URL as a
@ -3447,7 +3452,7 @@ class Bot(TelegramObject):
tgs_sticker (:obj:`str` | `filelike object`, optional): TGS animation with the sticker, tgs_sticker (:obj:`str` | `filelike object`, optional): TGS animation with the sticker,
uploaded using multipart/form-data. See uploaded using multipart/form-data. See
https://core.telegram.org/animated_stickers#technical-requirements for technical https://core.telegram.org/animated_stickers#technical-requirements for technical
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 be placed on faces. should be placed on faces.
@ -3457,7 +3462,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3500,7 +3505,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3527,7 +3532,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3559,14 +3564,15 @@ class Bot(TelegramObject):
https://core.telegram.org/animated_stickers#technical-requirements for animated sticker https://core.telegram.org/animated_stickers#technical-requirements for animated sticker
technical requirements. Pass a file_id as a String to send a file that already exists technical requirements. Pass a file_id as a String to send a file that already exists
on the Telegram servers, pass an HTTP URL as a String for Telegram to get a file from on the Telegram servers, pass an HTTP URL as a String for Telegram to get a file from
the Internet, or upload a new one using multipart/form-data. the Internet, or upload a new one using multipart/form-data. Animated sticker set
thumbnail can't be uploaded via HTTP URL.
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).
**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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3606,7 +3612,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, :obj:`True` is returned.
Raises: Raises:
:class:`telegram.TelegramError` :class:`telegram.TelegramError`
@ -3648,12 +3654,12 @@ class Bot(TelegramObject):
of the target channel (in the format @channelusername). 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): :obj:`True`, if the poll needs to be anonymous,
defaults to True. defaults to :obj:`True`.
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): :obj:`True`, if the poll allows
answers, ignored for polls in quiz mode, defaults to False. multiple answers, ignored for polls in quiz mode, defaults to :obj:`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.
explanation (:obj:`str`, optional): Text that is shown when a user chooses an incorrect explanation (:obj:`str`, optional): Text that is shown when a user chooses an incorrect
@ -3668,8 +3674,8 @@ class Bot(TelegramObject):
timestamp) when the poll will be automatically closed. Must be at least 5 and no timestamp) when the poll will be automatically closed. Must be at least 5 and no
more than 600 seconds in the future. Can't be used together with more than 600 seconds in the future. Can't be used together with
:attr:`open_period`. :attr:`open_period`.
is_closed (:obj:`bool`, optional): Pass True, if the poll needs to be immediately is_closed (:obj:`bool`, optional): Pass :obj:`True`, if the poll needs to be
closed. This can be useful for poll preview. immediately 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
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

18
telegram/callbackquery.py
View file

@ -115,7 +115,7 @@ class CallbackQuery(TelegramObject):
bot.answer_callback_query(update.callback_query.id, *args, **kwargs) bot.answer_callback_query(update.callback_query.id, *args, **kwargs)
Returns: Returns:
:obj:`bool`: On success, ``True`` is returned. :obj:`bool`: On success, :obj:`True` is returned.
""" """
return self.bot.answerCallbackQuery(self.id, *args, **kwargs) return self.bot.answerCallbackQuery(self.id, *args, **kwargs)
@ -134,7 +134,7 @@ class CallbackQuery(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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
if self.inline_message_id: if self.inline_message_id:
@ -160,7 +160,7 @@ class CallbackQuery(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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
if self.inline_message_id: if self.inline_message_id:
@ -188,7 +188,7 @@ class CallbackQuery(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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
if self.inline_message_id: if self.inline_message_id:
@ -217,7 +217,7 @@ class CallbackQuery(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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
if self.inline_message_id: if self.inline_message_id:
@ -246,7 +246,7 @@ class CallbackQuery(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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
if self.inline_message_id: if self.inline_message_id:
@ -275,7 +275,7 @@ class CallbackQuery(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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
if self.inline_message_id: if self.inline_message_id:
@ -302,7 +302,7 @@ class CallbackQuery(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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
if self.inline_message_id: if self.inline_message_id:
@ -329,7 +329,7 @@ class CallbackQuery(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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
if self.inline_message_id: if self.inline_message_id:

75
telegram/chat.py
View file

@ -37,13 +37,14 @@ class Chat(TelegramObject):
description (:obj:`str`): Optional. Description, for groups, supergroups and channel chats. description (:obj:`str`): Optional. Description, for groups, supergroups and channel chats.
invite_link (:obj:`str`): Optional. Chat invite link, for supergroups and channel chats. invite_link (:obj:`str`): Optional. Chat invite link, for supergroups and channel chats.
pinned_message (:class:`telegram.Message`): Optional. Pinned message, for supergroups. pinned_message (:class:`telegram.Message`): Optional. Pinned message, for supergroups.
Returned only in get_chat. Returned only in :meth:`telegram.Bot.get_chat`.
permissions (:class:`telegram.ChatPermission`): Optional. Default chat member permissions, permissions (:class:`telegram.ChatPermission`): Optional. Default chat member permissions,
for groups and supergroups. Returned only in getChat. for groups and supergroups. Returned only in :meth:`telegram.Bot.get_chat`.
slow_mode_delay (:obj:`int`): Optional. For supergroups, the minimum allowed delay between slow_mode_delay (:obj:`int`): Optional. For supergroups, the minimum allowed delay between
consecutive messages sent by each unpriviledged user. Returned only in getChat. consecutive messages sent by each unprivileged user. Returned only in
:meth:`telegram.Bot.get_chat`.
sticker_set_name (:obj:`str`): Optional. For supergroups, name of Group sticker set. sticker_set_name (:obj:`str`): Optional. For supergroups, name of Group sticker set.
can_set_sticker_set (:obj:`bool`): Optional. ``True``, if the bot can change group the can_set_sticker_set (:obj:`bool`): Optional. :obj:`True`, if the bot can change group the
sticker set. sticker set.
Args: Args:
@ -58,22 +59,26 @@ class Chat(TelegramObject):
available. available.
first_name(:obj:`str`, optional): First name of the other party in a private chat. first_name(:obj:`str`, optional): First name of the other party in a private chat.
last_name(:obj:`str`, optional): Last name of the other party in a private chat. last_name(:obj:`str`, optional): Last name of the other party in a private chat.
photo (:class:`telegram.ChatPhoto`, optional): Chat photo. Returned only in getChat. photo (:class:`telegram.ChatPhoto`, optional): Chat photo.
Returned only in :meth:`telegram.Bot.get_chat`.
description (:obj:`str`, optional): Description, for groups, supergroups and channel chats. description (:obj:`str`, optional): Description, for groups, supergroups and channel chats.
Returned only in get_chat. Returned only in :meth:`telegram.Bot.get_chat`.
invite_link (:obj:`str`, optional): Chat invite link, for supergroups and channel chats. invite_link (:obj:`str`, optional): Chat invite link, for groups, supergroups and channel
Returned only in get_chat. chats. Each administrator in a chat generates their own invite links, so the bot must
pinned_message (:class:`telegram.Message`, optional): Pinned message, for supergroups. first generate the link using ``export_chat_invite_link()``. Returned only
Returned only in get_chat. in :meth:`telegram.Bot.get_chat`.
pinned_message (:class:`telegram.Message`, optional): Pinned message, for groups,
supergroups and channels. Returned only in :meth:`telegram.Bot.get_chat`.
permissions (:class:`telegram.ChatPermission`): Optional. Default chat member permissions, permissions (:class:`telegram.ChatPermission`): Optional. Default chat member permissions,
for groups and supergroups. Returned only in getChat. for groups and supergroups. Returned only in :meth:`telegram.Bot.get_chat`.
slow_mode_delay (:obj:`int`, optional): For supergroups, the minimum allowed delay between slow_mode_delay (:obj:`int`, optional): For supergroups, the minimum allowed delay between
consecutive messages sent by each unpriviledged user. Returned only in getChat. consecutive messages sent by each unprivileged user.
Returned only in :meth:`telegram.Bot.get_chat`.
bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
sticker_set_name (:obj:`str`, optional): For supergroups, name of Group sticker set. sticker_set_name (:obj:`str`, optional): For supergroups, name of group sticker set.
Returned only in get_chat. Returned only in :meth:`telegram.Bot.get_chat`.
can_set_sticker_set (:obj:`bool`, optional): ``True``, if the bot can change group the can_set_sticker_set (:obj:`bool`, optional): :obj:`True`, if the bot can change group the
sticker set. Returned only in get_chat. sticker set. Returned only in :meth:`telegram.Bot.get_chat`.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
""" """
@ -169,7 +174,7 @@ class Chat(TelegramObject):
List[:class:`telegram.ChatMember`]: A list of administrators in a chat. An Array of List[:class:`telegram.ChatMember`]: A list of administrators in a chat. An Array of
:class:`telegram.ChatMember` objects that contains information about all :class:`telegram.ChatMember` objects that contains information about all
chat administrators except other bots. If the chat is a group or a supergroup 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 and no administrators were appointed, only the creator will be returned.
""" """
return self.bot.get_chat_administrators(self.id, *args, **kwargs) return self.bot.get_chat_administrators(self.id, *args, **kwargs)
@ -250,8 +255,6 @@ class Chat(TelegramObject):
bot.send_message(update.effective_chat.id, *args, **kwargs) bot.send_message(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -263,8 +266,6 @@ class Chat(TelegramObject):
bot.send_media_group(update.effective_chat.id, *args, **kwargs) bot.send_media_group(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
List[:class:`telegram.Message`:] On success, instance representing the message posted. List[:class:`telegram.Message`:] On success, instance representing the message posted.
@ -276,8 +277,6 @@ class Chat(TelegramObject):
bot.send_chat_action(update.effective_chat.id, *args, **kwargs) bot.send_chat_action(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:obj:`True`: On success. :obj:`True`: On success.
@ -292,8 +291,6 @@ class Chat(TelegramObject):
bot.send_photo(update.effective_chat.id, *args, **kwargs) bot.send_photo(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -305,8 +302,6 @@ class Chat(TelegramObject):
bot.send_contact(update.effective_chat.id, *args, **kwargs) bot.send_contact(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -318,8 +313,6 @@ class Chat(TelegramObject):
bot.send_audio(update.effective_chat.id, *args, **kwargs) bot.send_audio(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -331,8 +324,6 @@ class Chat(TelegramObject):
bot.send_document(update.effective_chat.id, *args, **kwargs) bot.send_document(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -344,8 +335,6 @@ class Chat(TelegramObject):
bot.send_dice(update.effective_chat.id, *args, **kwargs) bot.send_dice(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -357,8 +346,6 @@ class Chat(TelegramObject):
bot.send_game(update.effective_chat.id, *args, **kwargs) bot.send_game(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -370,8 +357,6 @@ class Chat(TelegramObject):
bot.send_invoice(update.effective_chat.id, *args, **kwargs) bot.send_invoice(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -383,8 +368,6 @@ class Chat(TelegramObject):
bot.send_location(update.effective_chat.id, *args, **kwargs) bot.send_location(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -396,8 +379,6 @@ class Chat(TelegramObject):
bot.send_animation(update.effective_chat.id, *args, **kwargs) bot.send_animation(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -409,8 +390,6 @@ class Chat(TelegramObject):
bot.send_sticker(update.effective_chat.id, *args, **kwargs) bot.send_sticker(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -422,8 +401,6 @@ class Chat(TelegramObject):
bot.send_venue(update.effective_chat.id, *args, **kwargs) bot.send_venue(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -435,8 +412,6 @@ class Chat(TelegramObject):
bot.send_video(update.effective_chat.id, *args, **kwargs) bot.send_video(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -448,8 +423,6 @@ class Chat(TelegramObject):
bot.send_video_note(update.effective_chat.id, *args, **kwargs) bot.send_video_note(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -461,8 +434,6 @@ class Chat(TelegramObject):
bot.send_voice(update.effective_chat.id, *args, **kwargs) bot.send_voice(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -474,8 +445,6 @@ class Chat(TelegramObject):
bot.send_poll(update.effective_chat.id, *args, **kwargs) bot.send_poll(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.

2
telegram/chataction.py
View file

@ -21,7 +21,7 @@
class ChatAction: class ChatAction:
"""Helper class to provide constants for different chatactions.""" """Helper class to provide constants for different chat actions."""
FIND_LOCATION = 'find_location' FIND_LOCATION = 'find_location'
""":obj:`str`: 'find_location'""" """:obj:`str`: 'find_location'"""

65
telegram/chatmember.py
View file

@ -23,7 +23,7 @@ from telegram.utils.helpers import to_timestamp, from_timestamp
class ChatMember(TelegramObject): class ChatMember(TelegramObject):
"""This object contains information about one member of the chat. """This object contains information about one member of a chat.
Attributes: Attributes:
user (:class:`telegram.User`): Information about the user. user (:class:`telegram.User`): Information about the user.
@ -46,13 +46,13 @@ class ChatMember(TelegramObject):
can_pin_messages (:obj:`bool`): Optional. If the user can pin messages. can_pin_messages (:obj:`bool`): Optional. If the user can pin messages.
can_promote_members (:obj:`bool`): Optional. If the administrator can add new can_promote_members (:obj:`bool`): Optional. If the administrator can add new
administrators. administrators.
is_member (:obj:`bool`): Optional. Restricted only. True, if the user is a member of the is_member (:obj:`bool`): Optional. Restricted only. :obj:`True`, if the user is a member of
chat at the moment of the request. the chat at the moment of the request.
can_send_messages (:obj:`bool`): Optional. If the user can send text messages, contacts, can_send_messages (:obj:`bool`): Optional. If the user can send text messages, contacts,
locations and venues. locations and venues.
can_send_media_messages (:obj:`bool`): Optional. If the user can send media messages, can_send_media_messages (:obj:`bool`): Optional. If the user can send media messages,
implies can_send_messages. implies can_send_messages.
can_send_polls (:obj:`bool`): Optional. True, if the user is allowed to can_send_polls (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
send polls. send polls.
can_send_other_messages (:obj:`bool`): Optional. If the user can send animations, games, can_send_other_messages (:obj:`bool`): Optional. If the user can send animations, games,
stickers and use inline bots, implies can_send_media_messages. stickers and use inline bots, implies can_send_media_messages.
@ -67,39 +67,38 @@ class ChatMember(TelegramObject):
Custom title for this user. Custom title for this user.
until_date (:class:`datetime.datetime`, optional): Restricted and kicked only. Date when until_date (:class:`datetime.datetime`, optional): Restricted and kicked only. Date when
restrictions will be lifted for this user. restrictions will be lifted for this user.
can_be_edited (:obj:`bool`, optional): Administrators only. True, if the bot is allowed to can_be_edited (:obj:`bool`, optional): Administrators only. :obj:`True`, if the bot is
edit administrator privileges of that user. allowed to edit administrator privileges of that user.
can_change_info (:obj:`bool`, optional): Administrators and restricted only. True, if the can_change_info (:obj:`bool`, optional): Administrators and restricted only. :obj:`True`,
user can change the chat title, photo and other settings. if the user can change the chat title, photo and other settings.
can_post_messages (:obj:`bool`, optional): Administrators only. True, if the administrator can_post_messages (:obj:`bool`, optional): Administrators only. :obj:`True`, if the
can post in the channel, channels only. administrator can post in the channel, channels only.
can_edit_messages (:obj:`bool`, optional): Administrators only. True, if the administrator can_edit_messages (:obj:`bool`, optional): Administrators only. :obj:`True`, if the
can edit messages of other users, channels only. administrator can edit messages of other users and can pin messages; channels only.
can_delete_messages (:obj:`bool`, optional): Administrators only. True, if the can_delete_messages (:obj:`bool`, optional): Administrators only. :obj:`True`, if the
administrator can delete messages of other user. administrator can delete messages of other users.
can_invite_users (:obj:`bool`, optional): Administrators and restricted only. True, if the can_invite_users (:obj:`bool`, optional): Administrators and restricted only. :obj:`True`,
user can invite new users to the chat. if the user can invite new users to the chat.
can_restrict_members (:obj:`bool`, optional): Administrators only. True, if the can_restrict_members (:obj:`bool`, optional): Administrators only. :obj:`True`, if the
administrator can restrict, ban or unban chat members. administrator can restrict, ban or unban chat members.
can_pin_messages (:obj:`bool`, optional): Administrators and restricted only. True, if the can_pin_messages (:obj:`bool`, optional): Administrators and restricted only. :obj:`True`,
user can pin messages, supergroups only. if the user can pin messages, groups and supergroups only.
can_promote_members (:obj:`bool`, optional): Administrators only. True, if the can_promote_members (:obj:`bool`, optional): Administrators only. :obj:`True`, if the
administrator can add new administrators with a subset of his own privileges or demote administrator can add new administrators with a subset of his own privileges or demote
administrators that he has promoted, directly or indirectly (promoted by administrators administrators that he has promoted, directly or indirectly (promoted by administrators
that were appointed by the user). that were appointed by the user).
is_member (:obj:`bool`, optional): Restricted only. True, if the user is a member of the is_member (:obj:`bool`, optional): Restricted only. :obj:`True`, if the user is a member of
chat at the moment of the request. the chat at the moment of the request.
can_send_messages (:obj:`bool`, optional): Restricted only. True, if the user can send text can_send_messages (:obj:`bool`, optional): Restricted only. :obj:`True`, if the user can
messages, contacts, locations and venues. send text messages, contacts, locations and venues.
can_send_media_messages (:obj:`bool`, optional): Restricted only. True, if the user can can_send_media_messages (:obj:`bool`, optional): Restricted only. :obj:`True`, if the user
send audios, documents, photos, videos, video notes and voice notes, implies can send audios, documents, photos, videos, video notes and voice notes.
can_send_messages. can_send_polls (:obj:`bool`, optional): Restricted only. :obj:`True`, if the user is
can_send_polls (:obj:`bool`, optional): Restricted only. True, if the user is allowed to allowed to send polls.
send polls. can_send_other_messages (:obj:`bool`, optional): Restricted only. :obj:`True`, if the user
can_send_other_messages (:obj:`bool`, optional): Restricted only. True, if the user can can send animations, games, stickers and use inline bots.
send animations, games, stickers and use inline bots, implies can_send_media_messages. can_add_web_page_previews (:obj:`bool`, optional): Restricted only. :obj:`True`, if user
can_add_web_page_previews (:obj:`bool`, optional): Restricted only. True, if user may add may add web page previews to his messages.
web page previews to his messages, implies can_send_media_messages.
""" """
ADMINISTRATOR = 'administrator' ADMINISTRATOR = 'administrator'

66
telegram/chatpermissions.py
View file

@ -25,49 +25,49 @@ class ChatPermissions(TelegramObject):
"""Describes actions that a non-administrator user is allowed to take in a chat. """Describes actions that a non-administrator user is allowed to take in a chat.
Note: Note:
Though not stated explicitly in the offical docs, Telegram changes not only the permissions Though not stated explicitly in the official docs, Telegram changes not only the
that are set, but also sets all the others to :obj:`False`. However, since not documented, permissions that are set, but also sets all the others to :obj:`False`. However, since not
this behaviour may change unbeknown to PTB. documented, this behaviour may change unbeknown to PTB.
Attributes: Attributes:
can_send_messages (:obj:`bool`): Optional. True, if the user is allowed to send text can_send_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to send text
messages, contacts, locations and venues. messages, contacts, locations and venues.
can_send_media_messages (:obj:`bool`): Optional. True, if the user is allowed to send can_send_media_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
audios, documents, photos, videos, video notes and voice notes, implies send audios, documents, photos, videos, video notes and voice notes, implies
:attr:`can_send_messages`. :attr:`can_send_messages`.
can_send_polls (:obj:`bool`): Optional. True, if the user is allowed to send polls, implies can_send_polls (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to send polls,
:attr:`can_send_messages`. implies :attr:`can_send_messages`.
can_send_other_messages (:obj:`bool`): Optional. True, if the user is allowed to send can_send_other_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
animations, games, stickers and use inline bots, implies send animations, games, stickers and use inline bots, implies
:attr:`can_send_media_messages`. :attr:`can_send_media_messages`.
can_add_web_page_previews (:obj:`bool`): Optional. True, if the user is allowed to add web can_add_web_page_previews (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
page previews to their messages, implies :attr:`can_send_media_messages`. add web page previews to their messages, implies :attr:`can_send_media_messages`.
can_change_info (:obj:`bool`): Optional. True, if the user is allowed to change the chat can_change_info (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to change the
title, photo and other settings. Ignored in public supergroups. chat title, photo and other settings. Ignored in public supergroups.
can_invite_users (:obj:`bool`): Optional. True, if the user is allowed to invite new users can_invite_users (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to invite
to the chat. new users to the chat.
can_pin_messages (:obj:`bool`): Optional. True, if the user is allowed to pin messages. can_pin_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to pin
Ignored in public supergroups. messages. Ignored in public supergroups.
Args: Args:
can_send_messages (:obj:`bool`, optional): True, if the user is allowed to send text can_send_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to send text
messages, contacts, locations and venues. messages, contacts, locations and venues.
can_send_media_messages (:obj:`bool`, optional): True, if the user is allowed to send can_send_media_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to
audios, documents, photos, videos, video notes and voice notes, implies send audios, documents, photos, videos, video notes and voice notes, implies
:attr:`can_send_messages`. :attr:`can_send_messages`.
can_send_polls (:obj:`bool`, optional): True, if the user is allowed to send polls, implies can_send_polls (:obj:`bool`, optional): :obj:`True`, if the user is allowed to send polls,
:attr:`can_send_messages`. implies :attr:`can_send_messages`.
can_send_other_messages (:obj:`bool`, optional): True, if the user is allowed to send can_send_other_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to
animations, games, stickers and use inline bots, implies send animations, games, stickers and use inline bots, implies
:attr:`can_send_media_messages`. :attr:`can_send_media_messages`.
can_add_web_page_previews (:obj:`bool`, optional): True, if the user is allowed to add web can_add_web_page_previews (:obj:`bool`, optional): :obj:`True`, if the user is allowed to
page previews to their messages, implies :attr:`can_send_media_messages`. add web page previews to their messages, implies :attr:`can_send_media_messages`.
can_change_info (:obj:`bool`, optional): True, if the user is allowed to change the chat can_change_info (:obj:`bool`, optional): :obj:`True`, if the user is allowed to change the
title, photo and other settings. Ignored in public supergroups. chat title, photo and other settings. Ignored in public supergroups.
can_invite_users (:obj:`bool`, optional): True, if the user is allowed to invite new users can_invite_users (:obj:`bool`, optional): :obj:`True`, if the user is allowed to invite new
to the chat. users to the chat.
can_pin_messages (:obj:`bool`, optional): True, if the user is allowed to pin messages. can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to pin
Ignored in public supergroups. messages. Ignored in public supergroups.
""" """

4
telegram/choseninlineresult.py
View file

@ -48,6 +48,10 @@ class ChosenInlineResult(TelegramObject):
query (:obj:`str`): The query that was used to obtain the result. query (:obj:`str`): The query that was used to obtain the result.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Note:
It is necessary to enable inline feedback via `@Botfather <https://t.me/BotFather>`_ in
order to receive these objects in updates.
""" """
def __init__(self, def __init__(self,

6
telegram/error.py
View file

@ -26,7 +26,7 @@ def _lstrip_str(in_s, lstr):
lstr (:obj:`str`): substr to strip from left side lstr (:obj:`str`): substr to strip from left side
Returns: Returns:
str: :obj:`str`: The stripped string.
""" """
if in_s.startswith(lstr): if in_s.startswith(lstr):
@ -77,7 +77,7 @@ class TimedOut(NetworkError):
class ChatMigrated(TelegramError): class ChatMigrated(TelegramError):
""" """
Args: Args:
new_chat_id (:obj:`int`): new_chat_id (:obj:`int`): The new chat id of the group.
""" """
@ -89,7 +89,7 @@ class ChatMigrated(TelegramError):
class RetryAfter(TelegramError): class RetryAfter(TelegramError):
""" """
Args: Args:
retry_after (:obj:`int`): retry_after (:obj:`int`): Time in seconds, after which the bot can retry the request.
""" """

24
telegram/ext/basepersistence.py
View file

@ -27,11 +27,11 @@ class BasePersistence(ABC):
All relevant methods must be overwritten. This means: All relevant methods must be overwritten. This means:
* If :attr:`store_bot_data` is ``True`` you must overwrite :meth:`get_bot_data` and * If :attr:`store_bot_data` is :obj:`True` you must overwrite :meth:`get_bot_data` and
:meth:`update_bot_data`. :meth:`update_bot_data`.
* If :attr:`store_chat_data` is ``True`` you must overwrite :meth:`get_chat_data` and * If :attr:`store_chat_data` is :obj:`True` you must overwrite :meth:`get_chat_data` and
:meth:`update_chat_data`. :meth:`update_chat_data`.
* If :attr:`store_user_data` is ``True`` you must overwrite :meth:`get_user_data` and * If :attr:`store_user_data` is :obj:`True` you must overwrite :meth:`get_user_data` and
:meth:`update_user_data`. :meth:`update_user_data`.
* If you want to store conversation data with :class:`telegram.ext.ConversationHandler`, you * If you want to store conversation data with :class:`telegram.ext.ConversationHandler`, you
must overwrite :meth:`get_conversations` and :meth:`update_conversation`. must overwrite :meth:`get_conversations` and :meth:`update_conversation`.
@ -47,11 +47,11 @@ class BasePersistence(ABC):
Args: Args:
store_user_data (:obj:`bool`, optional): Whether user_data should be saved by this store_user_data (:obj:`bool`, optional): Whether user_data should be saved by this
persistence class. Default is ``True``. persistence class. Default is :obj:`True`.
store_chat_data (:obj:`bool`, optional): Whether chat_data should be saved by this store_chat_data (:obj:`bool`, optional): Whether chat_data should be saved by this
persistence class. Default is ``True`` . persistence class. Default is :obj:`True` .
store_bot_data (:obj:`bool`, optional): Whether bot_data should be saved by this store_bot_data (:obj:`bool`, optional): Whether bot_data should be saved by this
persistence class. Default is ``True`` . persistence class. Default is :obj:`True` .
""" """
def __init__(self, store_user_data=True, store_chat_data=True, store_bot_data=True): def __init__(self, store_user_data=True, store_chat_data=True, store_bot_data=True):
@ -83,18 +83,18 @@ class BasePersistence(ABC):
def get_bot_data(self): def get_bot_data(self):
""""Will be called by :class:`telegram.ext.Dispatcher` upon creation with a """"Will be called by :class:`telegram.ext.Dispatcher` upon creation with a
persistence object. It should return the bot_data if stored, or an empty persistence object. It should return the bot_data if stored, or an empty
``dict``. :obj:`dict`.
Returns: Returns:
:obj:`defaultdict`: The restored bot data. :obj:`dict`: The restored bot data.
""" """
@abstractmethod @abstractmethod
def get_conversations(self, name): def get_conversations(self, name):
""""Will be called by :class:`telegram.ext.Dispatcher` when a """"Will be called by :class:`telegram.ext.Dispatcher` when a
:class:`telegram.ext.ConversationHandler` is added if :class:`telegram.ext.ConversationHandler` is added if
:attr:`telegram.ext.ConversationHandler.persistent` is ``True``. :attr:`telegram.ext.ConversationHandler.persistent` is :obj:`True`.
It should return the conversations for the handler with `name` or an empty ``dict`` It should return the conversations for the handler with `name` or an empty :obj:`dict`
Args: Args:
name (:obj:`str`): The handlers name. name (:obj:`str`): The handlers name.
@ -106,10 +106,10 @@ class BasePersistence(ABC):
@abstractmethod @abstractmethod
def update_conversation(self, name, key, new_state): def update_conversation(self, name, key, new_state):
"""Will be called when a :attr:`telegram.ext.ConversationHandler.update_state` """Will be called when a :attr:`telegram.ext.ConversationHandler.update_state`
is called. this allows the storeage of the new state in the persistence. is called. This allows the storage of the new state in the persistence.
Args: Args:
name (:obj:`str`): The handlers name. name (:obj:`str`): The handler's name.
key (:obj:`tuple`): The key the state is changed for. key (:obj:`tuple`): The key the state is changed for.
new_state (:obj:`tuple` | :obj:`any`): The new state for the given key. new_state (:obj:`tuple` | :obj:`any`): The new state for the given key.
""" """

22
telegram/ext/callbackqueryhandler.py
View file

@ -64,32 +64,32 @@ class CallbackQueryHandler(Handler):
The return value of the callback is usually ignored except for the special case of The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`. :class:`telegram.ext.ConversationHandler`.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pattern (:obj:`str` | `Pattern`, optional): Regex pattern. If not ``None``, ``re.match`` pattern (:obj:`str` | `Pattern`, optional): Regex pattern. If not :obj:`None`, ``re.match``
is used on :attr:`telegram.CallbackQuery.data` to determine if an update should be is used on :attr:`telegram.CallbackQuery.data` to determine if an update should be
handled by this handler. handled by this handler.
pass_groups (:obj:`bool`, optional): If the callback should be passed the result of pass_groups (:obj:`bool`, optional): If the callback should be passed the result of
``re.match(pattern, data).groups()`` as a keyword argument called ``groups``. ``re.match(pattern, data).groups()`` as a keyword argument called ``groups``.
Default is ``False`` Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_groupdict (:obj:`bool`, optional): If the callback should be passed the result of pass_groupdict (:obj:`bool`, optional): If the callback should be passed the result of
``re.match(pattern, data).groupdict()`` as a keyword argument called ``groupdict``. ``re.match(pattern, data).groupdict()`` as a keyword argument called ``groupdict``.
Default is ``False`` Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_user_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``. ``user_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_chat_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``. ``chat_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
""" """

16
telegram/ext/choseninlineresulthandler.py
View file

@ -54,21 +54,21 @@ class ChosenInlineResultHandler(Handler):
The return value of the callback is usually ignored except for the special case of The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`. :class:`telegram.ext.ConversationHandler`.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_user_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``. ``user_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_chat_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``. ``chat_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
""" """

53
telegram/ext/commandhandler.py
View file

@ -38,6 +38,9 @@ class CommandHandler(Handler):
By default the handler listens to messages as well as edited messages. To change this behavior By default the handler listens to messages as well as edited messages. To change this behavior
use ``~Filters.update.edited_message`` in the filter argument. use ``~Filters.update.edited_message`` in the filter argument.
Note:
:class:`telegram.ext.CommandHandler` does *not* handle (edited) channel posts.
Attributes: Attributes:
command (:obj:`str` | List[:obj:`str`]): The command or list of commands this handler command (:obj:`str` | List[:obj:`str`]): The command or list of commands this handler
should listen for. Limitations are the same as described here should listen for. Limitations are the same as described here
@ -45,7 +48,7 @@ class CommandHandler(Handler):
callback (:obj:`callable`): The callback function for this handler. callback (:obj:`callable`): The callback function for this handler.
filters (:class:`telegram.ext.BaseFilter`): Optional. Only allow updates with these filters (:class:`telegram.ext.BaseFilter`): Optional. Only allow updates with these
Filters. Filters.
allow_edited (:obj:`bool`): Determines Whether the handler should also accept allow_edited (:obj:`bool`): Determines whether the handler should also accept
edited messages. edited messages.
pass_args (:obj:`bool`): Determines whether the handler should be passed pass_args (:obj:`bool`): Determines whether the handler should be passed
``args``. ``args``.
@ -59,10 +62,10 @@ class CommandHandler(Handler):
the callback function. the callback function.
Note: Note:
:attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a :obj:`dict` you
can use to keep any data in will be sent to the :attr:`callback` function. Related to can use to keep any data in will be sent to the :attr:`callback` function. Related to
either the user or the chat that the update was sent in. For each update from the same user either the user or the chat that the update was sent in. For each update from the same user
or in the same chat, it will be the same ``dict``. or in the same chat, it will be the same :obj:`dict`.
Note that this is DEPRECATED, and you should use context based callbacks. See Note that this is DEPRECATED, and you should use context based callbacks. See
https://git.io/fxJuV for more info. https://git.io/fxJuV for more info.
@ -84,29 +87,29 @@ class CommandHandler(Handler):
:class:`telegram.ext.filters.Filters`. Filters can be combined using bitwise :class:`telegram.ext.filters.Filters`. Filters can be combined using bitwise
operators (& for and, | for or, ~ for not). operators (& for and, | for or, ~ for not).
allow_edited (:obj:`bool`, optional): Determines whether the handler should also accept allow_edited (:obj:`bool`, optional): Determines whether the handler should also accept
edited messages. Default is ``False``. edited messages. Default is :obj:`False`.
DEPRECATED: Edited is allowed by default. To change this behavior use DEPRECATED: Edited is allowed by default. To change this behavior use
``~Filters.update.edited_message``. ``~Filters.update.edited_message``.
pass_args (:obj:`bool`, optional): Determines whether the handler should be passed the pass_args (:obj:`bool`, optional): Determines whether the handler should be passed the
arguments passed to the command as a keyword argument called ``args``. It will contain arguments passed to the command as a keyword argument called ``args``. It will contain
a list of strings, which is the text following the command split on single or a list of strings, which is the text following the command split on single or
consecutive whitespace characters. Default is ``False`` consecutive whitespace characters. Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_user_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``. ``user_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_chat_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``. ``chat_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
Raises: Raises:
@ -158,7 +161,7 @@ class CommandHandler(Handler):
update (:class:`telegram.Update`): Incoming telegram update. update (:class:`telegram.Update`): Incoming telegram update.
Returns: Returns:
:obj:`list`: The list of args for the handler :obj:`list`: The list of args for the handler.
""" """
if isinstance(update, Update) and update.effective_message: if isinstance(update, Update) and update.effective_message:
@ -213,7 +216,7 @@ class PrefixHandler(CommandHandler):
PrefixHandler(['!', '#'], 'test', callback) will respond to '!test' and PrefixHandler(['!', '#'], 'test', callback) will respond to '!test' and
'#test'. '#test'.
Miltiple prefixes and commands: Multiple prefixes and commands:
PrefixHandler(['!', '#'], ['test', 'help`], callback) will respond to '!test', PrefixHandler(['!', '#'], ['test', 'help`], callback) will respond to '!test',
'#test', '!help' and '#help'. '#test', '!help' and '#help'.
@ -268,23 +271,23 @@ class PrefixHandler(CommandHandler):
pass_args (:obj:`bool`, optional): Determines whether the handler should be passed the pass_args (:obj:`bool`, optional): Determines whether the handler should be passed the
arguments passed to the command as a keyword argument called ``args``. It will contain arguments passed to the command as a keyword argument called ``args``. It will contain
a list of strings, which is the text following the command split on single or a list of strings, which is the text following the command split on single or
consecutive whitespace characters. Default is ``False`` consecutive whitespace characters. Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_user_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``. ``user_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_chat_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``. ``chat_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
""" """
@ -349,7 +352,7 @@ class PrefixHandler(CommandHandler):
update (:class:`telegram.Update`): Incoming telegram update. update (:class:`telegram.Update`): Incoming telegram update.
Returns: Returns:
:obj:`list`: The list of args for the handler :obj:`list`: The list of args for the handler.
""" """
if isinstance(update, Update) and update.effective_message: if isinstance(update, Update) and update.effective_message:

35
telegram/ext/conversationhandler.py
View file

@ -43,7 +43,7 @@ class ConversationHandler(Handler):
The first collection, a ``list`` named :attr:`entry_points`, is used to initiate the The first collection, a ``list`` named :attr:`entry_points`, is used to initiate the
conversation, for example with a :class:`telegram.ext.CommandHandler` or conversation, for example with a :class:`telegram.ext.CommandHandler` or
:class:`telegram.ext.RegexHandler`. :class:`telegram.ext.MessageHandler`.
The second collection, a ``dict`` named :attr:`states`, contains the different conversation The second collection, a ``dict`` named :attr:`states`, contains the different conversation
steps and one or more associated handlers that should be used if the user sends a message when steps and one or more associated handlers that should be used if the user sends a message when
@ -59,8 +59,8 @@ class ConversationHandler(Handler):
user know their message was not recognized. user know their message was not recognized.
To change the state of conversation, the callback function of a handler must return the new To change the state of conversation, the callback function of a handler must return the new
state after responding to the user. If it does not return anything (returning ``None`` by state after responding to the user. If it does not return anything (returning :obj:`None` by
default), the state will not change. If an entry point callback function returns None, default), the state will not change. If an entry point callback function returns :obj:`None`,
the conversation ends immediately after the execution of this callback function. the conversation ends immediately after the execution of this callback function.
To end the conversation, the callback function must return :attr:`END` or ``-1``. To To end the conversation, the callback function must return :attr:`END` or ``-1``. To
handle the conversation timeout, use handler :attr:`TIMEOUT` or ``-2``. handle the conversation timeout, use handler :attr:`TIMEOUT` or ``-2``.
@ -87,7 +87,7 @@ class ConversationHandler(Handler):
associated ``Handler`` objects that should be used in that state. associated ``Handler`` objects that should be used in that state.
fallbacks (List[:class:`telegram.ext.Handler`]): A list of handlers that might be used if fallbacks (List[:class:`telegram.ext.Handler`]): A list of handlers that might be used if
the user is in a conversation, but every handler for their current state returned the user is in a conversation, but every handler for their current state returned
``False`` on :attr:`check_update`. :obj:`False` on :attr:`check_update`.
allow_reentry (:obj:`bool`): Determines if a user can restart a conversation with allow_reentry (:obj:`bool`): Determines if a user can restart a conversation with
an entry point. an entry point.
per_chat (:obj:`bool`): If the conversationkey should contain the Chat's ID. per_chat (:obj:`bool`): If the conversationkey should contain the Chat's ID.
@ -98,7 +98,7 @@ class ConversationHandler(Handler):
handler is inactive more than this timeout (in seconds), it will be automatically handler is inactive more than this timeout (in seconds), it will be automatically
ended. If this value is 0 (default), there will be no timeout. When it's triggered, the ended. If this value is 0 (default), there will be no timeout. When it's triggered, the
last received update and the corresponding ``context`` will be handled by ALL the last received update and the corresponding ``context`` will be handled by ALL the
handler's who's `check_update` method returns True that are in the state handler's who's :attr:`check_update` method returns :obj:`True` that are in the state
:attr:`ConversationHandler.TIMEOUT`. :attr:`ConversationHandler.TIMEOUT`.
name (:obj:`str`): Optional. The name for this conversationhandler. Required for name (:obj:`str`): Optional. The name for this conversationhandler. Required for
persistence persistence
@ -111,32 +111,33 @@ class ConversationHandler(Handler):
Args: Args:
entry_points (List[:class:`telegram.ext.Handler`]): A list of ``Handler`` objects that can entry_points (List[:class:`telegram.ext.Handler`]): A list of ``Handler`` objects that can
trigger the start of the conversation. The first handler which :attr:`check_update` trigger the start of the conversation. The first handler which :attr:`check_update`
method returns ``True`` will be used. If all return ``False``, the update is not method returns :obj:`True` will be used. If all return :obj:`False`, the update is not
handled. handled.
states (Dict[:obj:`object`, List[:class:`telegram.ext.Handler`]]): A :obj:`dict` that states (Dict[:obj:`object`, List[:class:`telegram.ext.Handler`]]): A :obj:`dict` that
defines the different states of conversation a user can be in and one or more defines the different states of conversation a user can be in and one or more
associated ``Handler`` objects that should be used in that state. The first handler associated ``Handler`` objects that should be used in that state. The first handler
which :attr:`check_update` method returns ``True`` will be used. which :attr:`check_update` method returns :obj:`True` will be used.
fallbacks (List[:class:`telegram.ext.Handler`]): A list of handlers that might be used if fallbacks (List[:class:`telegram.ext.Handler`]): A list of handlers that might be used if
the user is in a conversation, but every handler for their current state returned the user is in a conversation, but every handler for their current state returned
``False`` on :attr:`check_update`. The first handler which :attr:`check_update` method :obj:`False` on :attr:`check_update`. The first handler which :attr:`check_update`
returns ``True`` will be used. If all return ``False``, the update is not handled. method returns :obj:`True` will be used. If all return :obj:`False`, the update is not
allow_reentry (:obj:`bool`, optional): If set to ``True``, a user that is currently in a handled.
allow_reentry (:obj:`bool`, optional): If set to :obj:`True`, a user that is currently in a
conversation can restart the conversation by triggering one of the entry points. conversation can restart the conversation by triggering one of the entry points.
per_chat (:obj:`bool`, optional): If the conversationkey should contain the Chat's ID. per_chat (:obj:`bool`, optional): If the conversationkey should contain the Chat's ID.
Default is ``True``. Default is :obj:`True`.
per_user (:obj:`bool`, optional): If the conversationkey should contain the User's ID. per_user (:obj:`bool`, optional): If the conversationkey should contain the User's ID.
Default is ``True``. Default is :obj:`True`.
per_message (:obj:`bool`, optional): If the conversationkey should contain the Message's per_message (:obj:`bool`, optional): If the conversationkey should contain the Message's
ID. Default is ``False``. ID. Default is :obj:`False`.
conversation_timeout (:obj:`float` | :obj:`datetime.timedelta`, optional): When this conversation_timeout (:obj:`float` | :obj:`datetime.timedelta`, optional): When this
handler is inactive more than this timeout (in seconds), it will be automatically handler is inactive more than this timeout (in seconds), it will be automatically
ended. If this value is 0 or None (default), there will be no timeout. The last ended. If this value is 0 or :obj:`None` (default), there will be no timeout. The last
received update and the corresponding ``context`` will be handled by ALL the handler's received update and the corresponding ``context`` will be handled by ALL the handler's
who's `check_update` method returns True that are in the state who's :attr:`check_update` method returns :obj:`True` that are in the state
:attr:`ConversationHandler.TIMEOUT`. :attr:`ConversationHandler.TIMEOUT`.
name (:obj:`str`, optional): The name for this conversationhandler. Required for name (:obj:`str`, optional): The name for this conversationhandler. Required for
persistence persistence.
persistent (:obj:`bool`, optional): If the conversations dict for this handler should be persistent (:obj:`bool`, optional): If the conversations dict for this handler should be
saved. Name is required and persistence has to be set in :class:`telegram.ext.Updater` saved. Name is required and persistence has to be set in :class:`telegram.ext.Updater`
map_to_parent (Dict[:obj:`object`, :obj:`object`], optional): A :obj:`dict` that can be map_to_parent (Dict[:obj:`object`, :obj:`object`], optional): A :obj:`dict` that can be
@ -182,7 +183,7 @@ class ConversationHandler(Handler):
raise ValueError("Conversations can't be persistent when handler is unnamed.") raise ValueError("Conversations can't be persistent when handler is unnamed.")
self.persistent = persistent self.persistent = persistent
self._persistence = None self._persistence = None
""":obj:`telegram.ext.BasePersistance`: The persistence used to store conversations. """:obj:`telegram.ext.BasePersistence`: The persistence used to store conversations.
Set by dispatcher""" Set by dispatcher"""
self._map_to_parent = map_to_parent self._map_to_parent = map_to_parent

16
telegram/ext/defaults.py
View file

@ -26,7 +26,7 @@ class Defaults:
Attributes: Attributes:
parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
bold, italic, fixed-width toxt or URLs in your bot's message. bold, italic, fixed-width text or URLs in your bot's 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.
disable_web_page_preview (:obj:`bool`): Optional. Disables link previews for links in this disable_web_page_preview (:obj:`bool`): Optional. Disables link previews for links in this
@ -34,13 +34,13 @@ class Defaults:
timeout (:obj:`int` | :obj:`float`): Optional. If this value is specified, use it as the 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). connection pool).
quote (:obj:`bool`): Optional. If set to ``True``, the reply is sent as an actual reply to quote (:obj:`bool`): Optional. If set to :obj:`True`, the reply is sent as an actual reply
the message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter will to the message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter will
be ignored. Default: ``True`` in group chats and ``False`` in private chats. be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
Parameters: Parameters:
parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
bold, italic, fixed-width toxt or URLs in your bot's message. bold, italic, fixed-width text or URLs in your bot's 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.
disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in this disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in this
@ -48,9 +48,9 @@ class Defaults:
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as the 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). connection pool).
quote (:obj:`bool`, opitonal): If set to ``True``, the reply is sent as an actual reply to quote (:obj:`bool`, optional): If set to :obj:`True`, the reply is sent as an actual reply
the message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter will to the message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter will
be ignored. Default: ``True`` in group chats and ``False`` in private chats. be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
""" """
def __init__(self, def __init__(self,
parse_mode=None, parse_mode=None,

32
telegram/ext/dictpersistence.py
View file

@ -43,11 +43,11 @@ class DictPersistence(BasePersistence):
Args: Args:
store_user_data (:obj:`bool`, optional): Whether user_data should be saved by this store_user_data (:obj:`bool`, optional): Whether user_data should be saved by this
persistence class. Default is ``True``. persistence class. Default is :obj:`True`.
store_chat_data (:obj:`bool`, optional): Whether user_data should be saved by this store_chat_data (:obj:`bool`, optional): Whether user_data should be saved by this
persistence class. Default is ``True``. persistence class. Default is :obj:`True`.
store_bot_data (:obj:`bool`, optional): Whether bot_data should be saved by this store_bot_data (:obj:`bool`, optional): Whether bot_data should be saved by this
persistence class. Default is ``True`` . persistence class. Default is :obj:`True` .
user_data_json (:obj:`str`, optional): Json string that will be used to reconstruct user_data_json (:obj:`str`, optional): Json string that will be used to reconstruct
user_data on creating this persistence. Default is ``""``. user_data on creating this persistence. Default is ``""``.
chat_data_json (:obj:`str`, optional): Json string that will be used to reconstruct chat_data_json (:obj:`str`, optional): Json string that will be used to reconstruct
@ -107,7 +107,7 @@ class DictPersistence(BasePersistence):
@property @property
def user_data(self): def user_data(self):
""":obj:`dict`: The user_data as a dict""" """:obj:`dict`: The user_data as a dict."""
return self._user_data return self._user_data
@property @property
@ -120,7 +120,7 @@ class DictPersistence(BasePersistence):
@property @property
def chat_data(self): def chat_data(self):
""":obj:`dict`: The chat_data as a dict""" """:obj:`dict`: The chat_data as a dict."""
return self._chat_data return self._chat_data
@property @property
@ -133,7 +133,7 @@ class DictPersistence(BasePersistence):
@property @property
def bot_data(self): def bot_data(self):
""":obj:`dict`: The bot_data as a dict""" """:obj:`dict`: The bot_data as a dict."""
return self._bot_data return self._bot_data
@property @property
@ -146,7 +146,7 @@ class DictPersistence(BasePersistence):
@property @property
def conversations(self): def conversations(self):
""":obj:`dict`: The conversations as a dict""" """:obj:`dict`: The conversations as a dict."""
return self._conversations return self._conversations
@property @property
@ -158,7 +158,8 @@ class DictPersistence(BasePersistence):
return encode_conversations_to_json(self.conversations) return encode_conversations_to_json(self.conversations)
def get_user_data(self): def get_user_data(self):
"""Returns the user_data created from the ``user_data_json`` or an empty defaultdict. """Returns the user_data created from the ``user_data_json`` or an empty
:obj:`defaultdict`.
Returns: Returns:
:obj:`defaultdict`: The restored user data. :obj:`defaultdict`: The restored user data.
@ -170,10 +171,11 @@ class DictPersistence(BasePersistence):
return deepcopy(self.user_data) return deepcopy(self.user_data)
def get_chat_data(self): def get_chat_data(self):
"""Returns the chat_data created from the ``chat_data_json`` or an empty defaultdict. """Returns the chat_data created from the ``chat_data_json`` or an empty
:obj:`defaultdict`.
Returns: Returns:
:obj:`defaultdict`: The restored user data. :obj:`defaultdict`: The restored chat data.
""" """
if self.chat_data: if self.chat_data:
pass pass
@ -182,10 +184,10 @@ class DictPersistence(BasePersistence):
return deepcopy(self.chat_data) return deepcopy(self.chat_data)
def get_bot_data(self): def get_bot_data(self):
"""Returns the bot_data created from the ``bot_data_json`` or an empty dict. """Returns the bot_data created from the ``bot_data_json`` or an empty :obj:`dict`.
Returns: Returns:
:obj:`defaultdict`: The restored user data. :obj:`dict`: The restored bot data.
""" """
if self.bot_data: if self.bot_data:
pass pass
@ -195,10 +197,10 @@ class DictPersistence(BasePersistence):
def get_conversations(self, name): def get_conversations(self, name):
"""Returns the conversations created from the ``conversations_json`` or an empty """Returns the conversations created from the ``conversations_json`` or an empty
defaultdict. :obj:`dict`.
Returns: Returns:
:obj:`defaultdict`: The restored user data. :obj:`dict`: The restored conversations data.
""" """
if self.conversations: if self.conversations:
pass pass
@ -210,7 +212,7 @@ class DictPersistence(BasePersistence):
"""Will update the conversations for the given handler. """Will update the conversations for the given handler.
Args: Args:
name (:obj:`str`): The handlers name. name (:obj:`str`): The handler's name.
key (:obj:`tuple`): The key the state is changed for. key (:obj:`tuple`): The key the state is changed for.
new_state (:obj:`tuple` | :obj:`any`): The new state for the given key. new_state (:obj:`tuple` | :obj:`any`): The new state for the given key.
""" """

13
telegram/ext/dispatcher.py
View file

@ -97,7 +97,7 @@ class Dispatcher:
chat_data (:obj:`defaultdict`): A dictionary handlers can use to store data for the chat. chat_data (:obj:`defaultdict`): A dictionary handlers can use to store data for the chat.
bot_data (:obj:`dict`): A dictionary handlers can use to store data for the bot. bot_data (:obj:`dict`): A dictionary handlers can use to store data for the bot.
persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to
store data that should be persistent over restarts store data that should be persistent over restarts.
Args: Args:
bot (:class:`telegram.Bot`): The bot object that should be passed to the handlers. bot (:class:`telegram.Bot`): The bot object that should be passed to the handlers.
@ -105,12 +105,13 @@ class Dispatcher:
job_queue (:class:`telegram.ext.JobQueue`, optional): The :class:`telegram.ext.JobQueue` job_queue (:class:`telegram.ext.JobQueue`, optional): The :class:`telegram.ext.JobQueue`
instance to pass onto handler callbacks. instance to pass onto handler callbacks.
workers (:obj:`int`, optional): Number of maximum concurrent worker threads for the workers (:obj:`int`, optional): Number of maximum concurrent worker threads for the
``@run_async`` decorator. defaults to 4. ``@run_async`` decorator. Defaults to 4.
persistence (:class:`telegram.ext.BasePersistence`, optional): The persistence class to persistence (:class:`telegram.ext.BasePersistence`, optional): The persistence class to
store data that should be persistent over restarts store data that should be persistent over restarts.
use_context (:obj:`bool`, optional): If set to ``True`` Use the context based callback API. use_context (:obj:`bool`, optional): If set to :obj:`True` Use the context based
During the deprecation period of the old API the default is ``False``. **New users**: callback API.
set this to ``True``. During the deprecation period of the old API the default is :obj:`False`.
**New users**: Set this to :obj:`True`.
""" """

52
telegram/ext/filters.py
View file

@ -61,18 +61,18 @@ class BaseFilter(ABC):
If you want to create your own filters create a class inheriting from this class and implement If you want to create your own filters create a class inheriting from this class and implement
a `filter` method that returns a boolean: `True` if the message should be handled, `False` a :meth:`filter` method that returns a boolean: :obj:`True` if the message should be
otherwise. Note that the filters work only as class instances, not actual class objects handled, :obj:`False` otherwise. Note that the filters work only as class instances, not
(so remember to initialize your filter classes). actual class objects (so remember to initialize your filter classes).
By default the filters name (what will get printed when converted to a string for display) By default the filters name (what will get printed when converted to a string for display)
will be the class name. If you want to overwrite this assign a better name to the `name` will be the class name. If you want to overwrite this assign a better name to the :attr:`name`
class variable. class variable.
Attributes: Attributes:
name (:obj:`str`): Name for this filter. Defaults to the type of filter. name (:obj:`str`): Name for this filter. Defaults to the type of filter.
update_filter (:obj:`bool`): Whether this filter should work on update. If ``False`` it update_filter (:obj:`bool`): Whether this filter should work on update. If :obj:`False` it
will run the filter on :attr:`update.effective_message``. Default is ``False``. will run the filter on :attr:`update.effective_message`. Default is :obj:`False`.
data_filter (:obj:`bool`): Whether this filter is a data filter. A data filter should data_filter (:obj:`bool`): Whether this filter is a data filter. A data filter should
return a dict with lists. The dict will be merged with return a dict with lists. The dict will be merged with
:class:`telegram.ext.CallbackContext`'s internal dict in most cases :class:`telegram.ext.CallbackContext`'s internal dict in most cases
@ -109,14 +109,14 @@ class BaseFilter(ABC):
"""This method must be overwritten. """This method must be overwritten.
Note: Note:
If :attr:`update_filter` is false then the first argument is `message` and of If :attr:`update_filter` is :obj:`False` then the first argument is `message` and of
type :class:`telegram.Message`. type :class:`telegram.Message`.
Args: Args:
update (:class:`telegram.Update`): The update that is tested. update (:class:`telegram.Update`): The update that is tested.
Returns: Returns:
:obj:`dict` or :obj:`bool` :obj:`dict` or :obj:`bool`.
""" """
@ -144,7 +144,7 @@ class MergedFilter(BaseFilter):
"""Represents a filter consisting of two other filters. """Represents a filter consisting of two other filters.
Args: Args:
base_filter: Filter 1 of the merged filter base_filter: Filter 1 of the merged filter.
and_filter: Optional filter to "and" with base_filter. Mutually exclusive with or_filter. and_filter: Optional filter to "and" with base_filter. Mutually exclusive with or_filter.
or_filter: Optional filter to "or" with base_filter. Mutually exclusive with and_filter. or_filter: Optional filter to "or" with base_filter. Mutually exclusive with and_filter.
@ -296,7 +296,7 @@ class Filters:
To allow any text message, simply use To allow any text message, simply use
``MessageHandler(Filters.text, callback_method)``. ``MessageHandler(Filters.text, callback_method)``.
A simple usecase for passing a list is to allow only messages that were send by a A simple use case for passing a list is to allow only messages that were sent by a
custom :class:`telegram.ReplyKeyboardMarkup`:: custom :class:`telegram.ReplyKeyboardMarkup`::
buttons = ['Start', 'Settings', 'Back'] buttons = ['Start', 'Settings', 'Back']
@ -377,7 +377,7 @@ class Filters:
command = _Command() command = _Command()
""" """
Messages with a :attr:`telegram.MessageEntity.BOT_COMMAND`. By default only allows Messages with a :attr:`telegram.MessageEntity.BOT_COMMAND`. By default only allows
messages `starting` with a bot command. Pass ``False`` to also allow messages that contain a messages `starting` with a bot command. Pass :obj:`False` to also allow messages that contain a
bot command `anywhere` in the text. bot command `anywhere` in the text.
Examples:: Examples::
@ -390,13 +390,13 @@ class Filters:
Args: Args:
update (:obj:`bool`, optional): Whether to only allow messages that `start` with a bot update (:obj:`bool`, optional): Whether to only allow messages that `start` with a bot
command. Defaults to ``True``. command. Defaults to :obj:`True`.
""" """
class regex(BaseFilter): class regex(BaseFilter):
""" """
Filters updates by searching for an occurrence of ``pattern`` in the message text. Filters updates by searching for an occurrence of ``pattern`` in the message text.
The ``re.search`` function is used to determine whether an update should be filtered. The ``re.search()`` function is used to determine whether an update should be filtered.
Refer to the documentation of the ``re`` module for more information. Refer to the documentation of the ``re`` module for more information.
@ -404,8 +404,8 @@ class Filters:
Examples: Examples:
Use ``MessageHandler(Filters.regex(r'help'), callback)`` to capture all messages that Use ``MessageHandler(Filters.regex(r'help'), callback)`` to capture all messages that
contain the word help. You can also use contain the word 'help'. You can also use
``MessageHandler(Filters.regex(re.compile(r'help', re.IGNORECASE), callback)`` if ``MessageHandler(Filters.regex(re.compile(r'help', re.IGNORECASE)), callback)`` if
you want your pattern to be case insensitive. This approach is recommended you want your pattern to be case insensitive. This approach is recommended
if you need to specify flags on your pattern. if you need to specify flags on your pattern.
@ -460,7 +460,7 @@ class Filters:
name = 'Filters.document' name = 'Filters.document'
class category(BaseFilter): class category(BaseFilter):
"""This Filter filters documents by their category in the mime-type attribute """Filters documents by their category in the mime-type attribute.
Note: Note:
This Filter only filters by the mime_type of the document, This Filter only filters by the mime_type of the document,
@ -469,8 +469,8 @@ class Filters:
send media with wrong types that don't fit to this handler. send media with wrong types that don't fit to this handler.
Example: Example:
Filters.documents.category('audio/') returns `True` for all types Filters.documents.category('audio/') returns :obj:`True` for all types
of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav' of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav'.
""" """
def __init__(self, category): def __init__(self, category):
@ -547,7 +547,7 @@ class Filters:
``Filters.document`` for all document messages. ``Filters.document`` for all document messages.
Attributes: Attributes:
category: This Filter filters documents by their category in the mime-type attribute category: Filters documents by their category in the mime-type attribute
Note: Note:
This Filter only filters by the mime_type of the document, This Filter only filters by the mime_type of the document,
@ -557,13 +557,13 @@ class Filters:
Example: Example:
``Filters.documents.category('audio/')`` filters all types ``Filters.documents.category('audio/')`` filters all types
of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav' of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav'.
application: Same as ``Filters.document.category("application")``. application: Same as ``Filters.document.category("application")``.
audio: Same as ``Filters.document.category("audio")``. audio: Same as ``Filters.document.category("audio")``.
image: Same as ``Filters.document.category("image")``. image: Same as ``Filters.document.category("image")``.
video: Same as ``Filters.document.category("video")``. video: Same as ``Filters.document.category("video")``.
text: Same as ``Filters.document.category("text")``. text: Same as ``Filters.document.category("text")``.
mime_type: This Filter filters documents by their mime-type attribute mime_type: Filters documents by their mime-type attribute
Note: Note:
This Filter only filters by the mime_type of the document, This Filter only filters by the mime_type of the document,
@ -1148,6 +1148,7 @@ officedocument.wordprocessingml.document")``-
def add_usernames(self, username): def add_usernames(self, username):
""" """
Add one or more users to the allowed usernames. Add one or more users to the allowed usernames.
Args: Args:
username(:obj:`str` | List[:obj:`str`], optional): Which username(s) to allow username(:obj:`str` | List[:obj:`str`], optional): Which username(s) to allow
through. Leading '@'s in usernames will be discarded. through. Leading '@'s in usernames will be discarded.
@ -1163,6 +1164,7 @@ officedocument.wordprocessingml.document")``-
def add_bot_ids(self, bot_id): def add_bot_ids(self, bot_id):
""" """
Add one or more users to the allowed user ids. Add one or more users to the allowed user ids.
Args: Args:
bot_id(:obj:`int` | List[:obj:`int`], optional): Which bot ID(s) to allow bot_id(:obj:`int` | List[:obj:`int`], optional): Which bot ID(s) to allow
through. through.
@ -1179,6 +1181,7 @@ officedocument.wordprocessingml.document")``-
def remove_usernames(self, username): def remove_usernames(self, username):
""" """
Remove one or more users from allowed usernames. Remove one or more users from allowed usernames.
Args: Args:
username(:obj:`str` | List[:obj:`str`], optional): Which username(s) to disallow username(:obj:`str` | List[:obj:`str`], optional): Which username(s) to disallow
through. Leading '@'s in usernames will be discarded. through. Leading '@'s in usernames will be discarded.
@ -1194,6 +1197,7 @@ officedocument.wordprocessingml.document")``-
def remove_bot_ids(self, bot_id): def remove_bot_ids(self, bot_id):
""" """
Remove one or more users from allowed user ids. Remove one or more users from allowed user ids.
Args: Args:
bot_id(:obj:`int` | List[:obj:`int`], optional): Which bot ID(s) to disallow bot_id(:obj:`int` | List[:obj:`int`], optional): Which bot ID(s) to disallow
through. through.
@ -1241,7 +1245,7 @@ officedocument.wordprocessingml.document")``-
chat_id(:obj:`int` | List[:obj:`int`], optional): Which chat ID(s) to allow chat_id(:obj:`int` | List[:obj:`int`], optional): Which chat ID(s) to allow
through. through.
username(:obj:`str` | List[:obj:`str`], optional): Which username(s) to allow username(:obj:`str` | List[:obj:`str`], optional): Which username(s) to allow
through. Leading '@'s in usernames will be discarded. through. Leading `'@'` s in usernames will be discarded.
allow_empty(:obj:`bool`, optional): Whether updates should be processed, if no chat allow_empty(:obj:`bool`, optional): Whether updates should be processed, if no chat
is specified in :attr:`chat_ids` and :attr:`usernames`. Defaults to :obj:`False` is specified in :attr:`chat_ids` and :attr:`usernames`. Defaults to :obj:`False`
@ -1314,7 +1318,7 @@ officedocument.wordprocessingml.document")``-
Args: Args:
username(:obj:`str` | List[:obj:`str`], optional): Which username(s) to allow username(:obj:`str` | List[:obj:`str`], optional): Which username(s) to allow
through. Leading '@'s in usernames will be discarded. through. Leading `'@'` s in usernames will be discarded.
""" """
with self.__lock: with self.__lock:
if self._chat_ids: if self._chat_ids:
@ -1457,7 +1461,7 @@ officedocument.wordprocessingml.document")``-
"""Filters messages to only allow those which are from users with a certain language code. """Filters messages to only allow those which are from users with a certain language code.
Note: Note:
According to official telegram api documentation, not every single user has the According to official Telegram API documentation, not every single user has the
`language_code` attribute. Do not count on this filter working on all users. `language_code` attribute. Do not count on this filter working on all users.
Examples: Examples:

26
telegram/ext/handler.py
View file

@ -53,21 +53,21 @@ class Handler(ABC):
The return value of the callback is usually ignored except for the special case of The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`. :class:`telegram.ext.ConversationHandler`.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_user_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``. ``user_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_chat_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``. ``chat_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
""" """
@ -94,18 +94,18 @@ class Handler(ABC):
update (:obj:`str` | :class:`telegram.Update`): The update to be tested. update (:obj:`str` | :class:`telegram.Update`): The update to be tested.
Returns: Returns:
Either ``None`` or ``False`` if the update should not be handled. Otherwise an object Either :obj:`None` or :obj:`False` if the update should not be handled. Otherwise an
that will be passed to :attr:`handle_update` and :attr:`collect_additional_context` object that will be passed to :meth:`handle_update` and
when the update gets handled. :meth:`collect_additional_context` when the update gets handled.
""" """
def handle_update(self, update, dispatcher, check_result, context=None): def handle_update(self, update, dispatcher, check_result, context=None):
""" """
This method is called if it was determined that an update should indeed This method is called if it was determined that an update should indeed
be handled by this instance. Calls :attr:`self.callback` along with its respectful be handled by this instance. Calls :attr:`callback` along with its respectful
arguments. To work with the :class:`telegram.ext.ConversationHandler`, this method arguments. To work with the :class:`telegram.ext.ConversationHandler`, this method
returns the value returned from ``self.callback``. returns the value returned from :attr:`callback`.
Note that it can be overridden if needed by the subclassing handler. Note that it can be overridden if needed by the subclassing handler.
Args: Args:

22
telegram/ext/inlinequeryhandler.py
View file

@ -64,32 +64,32 @@ class InlineQueryHandler(Handler):
The return value of the callback is usually ignored except for the special case of The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`. :class:`telegram.ext.ConversationHandler`.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pattern (:obj:`str` | :obj:`Pattern`, optional): Regex pattern. If not ``None``, pattern (:obj:`str` | :obj:`Pattern`, optional): Regex pattern. If not :obj:`None`,
``re.match`` is used on :attr:`telegram.InlineQuery.query` to determine if an update ``re.match`` is used on :attr:`telegram.InlineQuery.query` to determine if an update
should be handled by this handler. should be handled by this handler.
pass_groups (:obj:`bool`, optional): If the callback should be passed the result of pass_groups (:obj:`bool`, optional): If the callback should be passed the result of
``re.match(pattern, data).groups()`` as a keyword argument called ``groups``. ``re.match(pattern, data).groups()`` as a keyword argument called ``groups``.
Default is ``False`` Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_groupdict (:obj:`bool`, optional): If the callback should be passed the result of pass_groupdict (:obj:`bool`, optional): If the callback should be passed the result of
``re.match(pattern, data).groupdict()`` as a keyword argument called ``groupdict``. ``re.match(pattern, data).groupdict()`` as a keyword argument called ``groupdict``.
Default is ``False`` Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_user_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``. ``user_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_chat_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``. ``chat_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
""" """

54
telegram/ext/jobqueue.py
View file

@ -92,7 +92,7 @@ class JobQueue:
:func:`telegram.ext.JobQueue.run_repeating` for details). :func:`telegram.ext.JobQueue.run_repeating` for details).
Defaults to now + ``job.interval``. Defaults to now + ``job.interval``.
previous_t (optional): previous_t (optional):
Time at which the job last ran (``None`` if it hasn't run yet). Time at which the job last ran (:obj:`None` if it hasn't run yet).
""" """
# get time at which to run: # get time at which to run:
@ -131,17 +131,17 @@ class JobQueue:
* :obj:`datetime.timedelta` will be interpreted as "time from now" in which the * :obj:`datetime.timedelta` will be interpreted as "time from now" in which the
job should run. job should run.
* :obj:`datetime.datetime` will be interpreted as a specific date and time at * :obj:`datetime.datetime` will be interpreted as a specific date and time at
which the job should run. If the timezone (``datetime.tzinfo``) is ``None``, UTC which the job should run. If the timezone (``datetime.tzinfo``) is :obj:`None`,
will be assumed. UTC will be assumed.
* :obj:`datetime.time` will be interpreted as a specific time of day at which the * :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, job should run. This could be either today or, if the time has already passed,
tomorrow. If the timezone (``time.tzinfo``) is ``None``, UTC will be assumed. tomorrow. If the timezone (``time.tzinfo``) is :obj:`None`, UTC will be assumed.
If ``when`` is :obj:`datetime.datetime` or :obj:`datetime.time` type If ``when`` is :obj:`datetime.datetime` or :obj:`datetime.time` type
then ``when.tzinfo`` will define ``Job.tzinfo``. Otherwise UTC will be assumed. then ``when.tzinfo`` will define ``Job.tzinfo``. Otherwise UTC will be assumed.
context (:obj:`object`, optional): Additional data needed for the callback function. 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 ``job.context`` in the callback. Defaults to :obj:`None`.
name (:obj:`str`, optional): The name of the new job. Defaults to name (:obj:`str`, optional): The name of the new job. Defaults to
``callback.__name__``. ``callback.__name__``.
@ -185,18 +185,18 @@ class JobQueue:
* :obj:`datetime.timedelta` will be interpreted as "time from now" in which the * :obj:`datetime.timedelta` will be interpreted as "time from now" in which the
job should run. job should run.
* :obj:`datetime.datetime` will be interpreted as a specific date and time at * :obj:`datetime.datetime` will be interpreted as a specific date and time at
which the job should run. If the timezone (``datetime.tzinfo``) is ``None``, UTC which the job should run. If the timezone (``datetime.tzinfo``) is :obj:`None`,
will be assumed. UTC will be assumed.
* :obj:`datetime.time` will be interpreted as a specific time of day at which the * :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, job should run. This could be either today or, if the time has already passed,
tomorrow. If the timezone (``time.tzinfo``) is ``None``, UTC will be assumed. tomorrow. If the timezone (``time.tzinfo``) is :obj:`None`, UTC will be assumed.
If ``first`` is :obj:`datetime.datetime` or :obj:`datetime.time` type If ``first`` is :obj:`datetime.datetime` or :obj:`datetime.time` type
then ``first.tzinfo`` will define ``Job.tzinfo``. Otherwise UTC will be assumed. then ``first.tzinfo`` will define ``Job.tzinfo``. Otherwise UTC will be assumed.
Defaults to ``interval`` Defaults to ``interval``
context (:obj:`object`, optional): Additional data needed for the callback function. 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 ``job.context`` in the callback. Defaults to :obj:`None`.
name (:obj:`str`, optional): The name of the new job. Defaults to name (:obj:`str`, optional): The name of the new job. Defaults to
``callback.__name__``. ``callback.__name__``.
@ -234,16 +234,16 @@ class JobQueue:
``context.job`` is the :class:`telegram.ext.Job` instance. It can be used to access ``context.job`` is the :class:`telegram.ext.Job` instance. It can be used to access
its ``job.context`` or change it to a repeating job. its ``job.context`` or change it to a repeating job.
when (:obj:`datetime.time`): Time of day at which the job should run. If the timezone when (:obj:`datetime.time`): Time of day at which the job should run. If the timezone
(``when.tzinfo``) is ``None``, UTC will be assumed. This will also implicitly (``when.tzinfo``) is :obj:`None`, UTC will be assumed. This will also implicitly
define ``Job.tzinfo``. define ``Job.tzinfo``.
day (:obj:`int`): Defines the day of the month whereby the job would run. It should day (:obj:`int`): Defines the day of the month whereby the job would run. It should
be within the range of 1 and 31, inclusive. be within the range of 1 and 31, inclusive.
context (:obj:`object`, optional): Additional data needed for the callback function. 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 ``job.context`` in the callback. Defaults to :obj:`None`.
name (:obj:`str`, optional): The name of the new job. Defaults to name (:obj:`str`, optional): The name of the new job. Defaults to
``callback.__name__``. ``callback.__name__``.
day_is_strict (:obj:`bool`, optional): If ``False`` and day > month.days, will pick day_is_strict (:obj:`bool`, optional): If :obj:`False` and day > month.days, will pick
the last day in the month. Defaults to ``True``. the last day in the month. Defaults to :obj:`True`.
Returns: Returns:
:class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job
@ -268,14 +268,14 @@ class JobQueue:
day (:obj:`int`): The day of the month the job should run. day (:obj:`int`): The day of the month the job should run.
day_is_strict (:obj:`bool`): day_is_strict (:obj:`bool`):
Specification as to whether the specified day of job should be strictly Specification as to whether the specified day of job should be strictly
respected. If day_is_strict is ``True`` it ignores months whereby the respected. If day_is_strict is :obj:`True` it ignores months whereby the
specified date does not exist (e.g February 31st). If it set to ``False``, specified date does not exist (e.g February 31st). If it set to :obj:`False`,
it returns the last valid date of the month instead. For example, it returns the last valid date of the month instead. For example,
if the user runs a job on the 31st of every month, and sets if the user runs a job on the 31st of every month, and sets
the day_is_strict variable to ``False``, April, for example, the day_is_strict variable to :obj:`False`, April, for example,
the job would run on April 30th. the job would run on April 30th.
when (:obj:`datetime.time`): Time of day at which the job should run. If the when (:obj:`datetime.time`): Time of day at which the job should run. If the
timezone (``time.tzinfo``) is ``None``, UTC will be assumed. timezone (``time.tzinfo``) is :obj:`None`, UTC will be assumed.
allow_now (:obj:`bool`): Whether executing the job right now is a feasible options. allow_now (:obj:`bool`): Whether executing the job right now is a feasible options.
For stability reasons, this defaults to :obj:`False`, but it needs to be :obj:`True` For stability reasons, this defaults to :obj:`False`, but it needs to be :obj:`True`
on initializing a job. on initializing a job.
@ -341,12 +341,12 @@ class JobQueue:
``context.job`` is the :class:`telegram.ext.Job` instance. It can be used to access ``context.job`` is the :class:`telegram.ext.Job` instance. It can be used to access
its ``job.context`` or change it to a repeating job. its ``job.context`` or change it to a repeating job.
time (:obj:`datetime.time`): Time of day at which the job should run. If the timezone time (:obj:`datetime.time`): Time of day at which the job should run. If the timezone
(``time.tzinfo``) is ``None``, UTC will be assumed. (``time.tzinfo``) is :obj:`None`, UTC will be assumed.
``time.tzinfo`` will implicitly define ``Job.tzinfo``. ``time.tzinfo`` will implicitly define ``Job.tzinfo``.
days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should
run. Defaults to ``EVERY_DAY`` run. Defaults to ``EVERY_DAY``
context (:obj:`object`, optional): Additional data needed for the callback function. 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 ``job.context`` in the callback. Defaults to :obj:`None`.
name (:obj:`str`, optional): The name of the new job. Defaults to name (:obj:`str`, optional): The name of the new job. Defaults to
``callback.__name__``. ``callback.__name__``.
@ -513,12 +513,12 @@ class Job:
interval (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta`, optional): The time interval (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta`, optional): The time
interval between executions of the job. If it is an :obj:`int` or a :obj:`float`, interval between executions of the job. If it is an :obj:`int` or a :obj:`float`,
it will be interpreted as seconds. If you don't set this value, you must set it will be interpreted as seconds. If you don't set this value, you must set
:attr:`repeat` to ``False`` and specify :attr:`time_spec` when you put the job into :attr:`repeat` to :obj:`False` and specify :attr:`time_spec` when you put the job into
the job queue. the job queue.
repeat (:obj:`bool`, optional): If this job should be periodically execute its callback repeat (:obj:`bool`, optional): If this job should be periodically execute its callback
function (``True``) or only once (``False``). Defaults to ``True``. function (:obj:`True`) or only once (:obj:`False`). Defaults to :obj:`True`.
context (:obj:`object`, optional): Additional data needed for the callback function. Can be context (:obj:`object`, optional): Additional data needed for the callback function. Can be
accessed through ``job.context`` in the callback. Defaults to ``None``. accessed through ``job.context`` in the callback. Defaults to :obj:`None`.
name (:obj:`str`, optional): The name of the new job. Defaults to ``callback.__name__``. name (:obj:`str`, optional): The name of the new job. Defaults to ``callback.__name__``.
days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should run. days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should run.
Defaults to ``Days.EVERY_DAY`` Defaults to ``Days.EVERY_DAY``
@ -528,10 +528,10 @@ class Job:
checking the day of the week to determine whether a job should run (only relevant when checking the day of the week to determine whether a job should run (only relevant when
``days is not Days.EVERY_DAY``). Defaults to UTC. ``days is not Days.EVERY_DAY``). Defaults to UTC.
is_monthly (:obj:`bool`, optional): If this job is supposed to be a monthly scheduled job. is_monthly (:obj:`bool`, optional): If this job is supposed to be a monthly scheduled job.
Defaults to ``False``. Defaults to :obj:`False`.
day_is_strict (:obj:`bool`, optional): If ``False`` and day > month.days, will pick the day_is_strict (:obj:`bool`, optional): If :obj:`False` and day > month.days, will pick the
last day in the month. Defaults to ``True``. Only relevant when ``is_monthly`` is last day in the month. Defaults to :obj:`True`. Only relevant when ``is_monthly`` is
``True``. :obj:`True`.
""" """
def __init__(self, def __init__(self,
@ -635,7 +635,7 @@ class Job:
""" """
:obj:`datetime.datetime`: Datetime for the next job execution. :obj:`datetime.datetime`: Datetime for the next job execution.
Datetime is localized according to :attr:`tzinfo`. Datetime is localized according to :attr:`tzinfo`.
If job is removed or already ran it equals to ``None``. If job is removed or already ran it equals to :obj:`None`.
""" """
return datetime.datetime.fromtimestamp(self._next_t, self.tzinfo) if self._next_t else None return datetime.datetime.fromtimestamp(self._next_t, self.tzinfo) if self._next_t else None

28
telegram/ext/messagehandler.py
View file

@ -43,11 +43,11 @@ class MessageHandler(Handler):
pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
the callback function. the callback function.
message_updates (:obj:`bool`): Should "normal" message updates be handled? message_updates (:obj:`bool`): Should "normal" message updates be handled?
Default is ``None``. Default is :obj:`None`.
channel_post_updates (:obj:`bool`): Should channel posts updates be handled? channel_post_updates (:obj:`bool`): Should channel posts updates be handled?
Default is ``None``. Default is :obj:`None`.
edited_updates (:obj:`bool`): Should "edited" message updates be handled? edited_updates (:obj:`bool`): Should "edited" message updates be handled?
Default is ``None``. Default is :obj:`None`.
Note: Note:
:attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
@ -75,30 +75,30 @@ class MessageHandler(Handler):
The return value of the callback is usually ignored except for the special case of The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`. :class:`telegram.ext.ConversationHandler`.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_user_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``. ``user_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_chat_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``. ``chat_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
message_updates (:obj:`bool`, optional): Should "normal" message updates be handled? message_updates (:obj:`bool`, optional): Should "normal" message updates be handled?
Default is ``None``. Default is :obj:`None`.
DEPRECATED: Please switch to filters for update filtering. DEPRECATED: Please switch to filters for update filtering.
channel_post_updates (:obj:`bool`, optional): Should channel posts updates be handled? channel_post_updates (:obj:`bool`, optional): Should channel posts updates be handled?
Default is ``None``. Default is :obj:`None`.
DEPRECATED: Please switch to filters for update filtering. DEPRECATED: Please switch to filters for update filtering.
edited_updates (:obj:`bool`, optional): Should "edited" message updates be handled? Default edited_updates (:obj:`bool`, optional): Should "edited" message updates be handled? Default
is ``None``. is :obj:`None`.
DEPRECATED: Please switch to filters for update filtering. DEPRECATED: Please switch to filters for update filtering.
Raises: Raises:

38
telegram/ext/messagequeue.py
View file

@ -57,8 +57,9 @@ class DelayQueue(threading.Thread):
route exceptions from processor thread to main thread; is called on `Exception` route exceptions from processor thread to main thread; is called on `Exception`
subclass exceptions. If not provided, exceptions are routed through dummy handler, subclass exceptions. If not provided, exceptions are routed through dummy handler,
which re-raises them. which re-raises them.
autostart (:obj:`bool`, optional): If True, processor is started immediately after object's autostart (:obj:`bool`, optional): If :obj:`True`, processor is started immediately after
creation; if ``False``, should be started manually by `start` method. Defaults to True. object's creation; if :obj:`False`, should be started manually by `start` method.
Defaults to :obj:`True`.
name (:obj:`str`, optional): Thread's name. Defaults to ``'DelayQueue-N'``, where N is name (:obj:`str`, optional): Thread's name. Defaults to ``'DelayQueue-N'``, where N is
sequential number of object created. sequential number of object created.
@ -125,7 +126,8 @@ class DelayQueue(threading.Thread):
timeout (:obj:`float`): Indicates maximum time to wait for processor to stop and its timeout (:obj:`float`): Indicates maximum time to wait for processor to stop and its
thread to exit. If timeout exceeds and processor has not stopped, method silently thread to exit. If timeout exceeds and processor has not stopped, method silently
returns. :attr:`is_alive` could be used afterwards to check the actual status. returns. :attr:`is_alive` could be used afterwards to check the actual status.
``timeout`` set to None, blocks until processor is shut down. Defaults to None. ``timeout`` set to :obj:`None`, blocks until processor is shut down.
Defaults to :obj:`None`.
""" """
@ -159,7 +161,7 @@ class DelayQueue(threading.Thread):
self._queue.put((func, args, kwargs)) self._queue.put((func, args, kwargs))
# The most straightforward way to implement this is to use 2 sequenital delay # The most straightforward way to implement this is to use 2 sequential delay
# queues, like on classic delay chain schematics in electronics. # queues, like on classic delay chain schematics in electronics.
# So, message path is: # So, message path is:
# msg --> group delay if group msg, else no delay --> normal msg delay --> out # msg --> group delay if group msg, else no delay --> normal msg delay --> out
@ -185,9 +187,9 @@ class MessageQueue:
to route exceptions from processor threads to main thread; is called on ``Exception`` to route exceptions from processor threads to main thread; is called on ``Exception``
subclass exceptions. If not provided, exceptions are routed through dummy handler, subclass exceptions. If not provided, exceptions are routed through dummy handler,
which re-raises them. which re-raises them.
autostart (:obj:`bool`, optional): If True, processors are started immediately after autostart (:obj:`bool`, optional): If :obj:`True`, processors are started immediately after
object's creation; if ``False``, should be started manually by :attr:`start` method. object's creation; if :obj:`False`, should be started manually by :attr:`start` method.
Defaults to ``True``. Defaults to :obj:`True`.
""" """
@ -198,7 +200,7 @@ class MessageQueue:
group_time_limit_ms=60000, group_time_limit_ms=60000,
exc_route=None, exc_route=None,
autostart=True): autostart=True):
# create accoring delay queues, use composition # create according delay queues, use composition
self._all_delayq = DelayQueue( self._all_delayq = DelayQueue(
burst_limit=all_burst_limit, burst_limit=all_burst_limit,
time_limit_ms=all_time_limit_ms, time_limit_ms=all_time_limit_ms,
@ -219,20 +221,20 @@ class MessageQueue:
self._group_delayq.stop(timeout=timeout) self._group_delayq.stop(timeout=timeout)
self._all_delayq.stop(timeout=timeout) self._all_delayq.stop(timeout=timeout)
stop.__doc__ = DelayQueue.stop.__doc__ or '' # reuse docsting if any stop.__doc__ = DelayQueue.stop.__doc__ or '' # reuse docstring if any
def __call__(self, promise, is_group_msg=False): def __call__(self, promise, is_group_msg=False):
""" """
Processes callables in troughput-limiting queues to avoid hitting limits (specified with Processes callables in throughput-limiting queues to avoid hitting limits (specified with
:attr:`burst_limit` and :attr:`time_limit`. :attr:`burst_limit` and :attr:`time_limit`.
Args: Args:
promise (:obj:`callable`): Mainly the ``telegram.utils.promise.Promise`` (see Notes for promise (:obj:`callable`): Mainly the ``telegram.utils.promise.Promise`` (see Notes for
other callables), that is processed in delay queues. other callables), that is processed in delay queues.
is_group_msg (:obj:`bool`, optional): Defines whether ``promise`` would be processed in is_group_msg (:obj:`bool`, optional): Defines whether ``promise`` would be processed in
group*+*all* ``DelayQueue``s (if set to ``True``), or only through *all* group*+*all* ``DelayQueue``s (if set to :obj:`True`), or only through *all*
``DelayQueue`` (if set to ``False``), resulting in needed delays to avoid ``DelayQueue`` (if set to :obj:`False`), resulting in needed delays to avoid
hitting specified limits. Defaults to ``False``. hitting specified limits. Defaults to :obj:`False`.
Note: Note:
Method is designed to accept ``telegram.utils.promise.Promise`` as ``promise`` Method is designed to accept ``telegram.utils.promise.Promise`` as ``promise``
@ -272,12 +274,12 @@ def queuedmessage(method):
Wrapped method starts accepting the next kwargs: Wrapped method starts accepting the next kwargs:
Args: Args:
queued (:obj:`bool`, optional): If set to ``True``, the ``MessageQueue`` is used to process queued (:obj:`bool`, optional): If set to :obj:`True`, the ``MessageQueue`` is used to
output messages. Defaults to `self._is_queued_out`. process output messages. Defaults to `self._is_queued_out`.
isgroup (:obj:`bool`, optional): If set to ``True``, the message is meant to be group-type isgroup (:obj:`bool`, optional): If set to :obj:`True`, the message is meant to be
(as there's no obvious way to determine its type in other way at the moment). group-type(as there's no obvious way to determine its type in other way at the moment).
Group-type messages could have additional processing delay according to limits set Group-type messages could have additional processing delay according to limits set
in `self._out_queue`. Defaults to ``False``. in `self._out_queue`. Defaults to :obj:`False`.
Returns: Returns:
``telegram.utils.promise.Promise``: In case call is queued or original method's return ``telegram.utils.promise.Promise``: In case call is queued or original method's return

53
telegram/ext/picklepersistence.py
View file

@ -29,35 +29,37 @@ class PicklePersistence(BasePersistence):
Attributes: Attributes:
filename (:obj:`str`): The filename for storing the pickle files. When :attr:`single_file` filename (:obj:`str`): The filename for storing the pickle files. When :attr:`single_file`
is false this will be used as a prefix. is :obj:`False` this will be used as a prefix.
store_user_data (:obj:`bool`): Optional. Whether user_data should be saved by this store_user_data (:obj:`bool`): Optional. Whether user_data should be saved by this
persistence class. persistence class.
store_chat_data (:obj:`bool`): Optional. Whether user_data should be saved by this store_chat_data (:obj:`bool`): Optional. Whether user_data should be saved by this
persistence class. persistence class.
store_bot_data (:obj:`bool`): Optional. Whether bot_data should be saved by this store_bot_data (:obj:`bool`): Optional. Whether bot_data should be saved by this
persistence class. persistence class.
single_file (:obj:`bool`): Optional. When ``False`` will store 3 sperate files of single_file (:obj:`bool`): Optional. When :obj:`False` will store 3 separate files of
`filename_user_data`, `filename_chat_data` and `filename_conversations`. Default is `filename_user_data`, `filename_chat_data` and `filename_conversations`. Default is
``True``. :obj:`True`.
on_flush (:obj:`bool`, optional): When ``True`` will only save to file when :meth:`flush` on_flush (:obj:`bool`, optional): When :obj:`True` will only save to file when
is called and keep data in memory until that happens. When ``False`` will store data :meth:`flush` is called and keep data in memory until that happens. When
on any transaction *and* on call fo :meth:`flush`. Default is ``False``. :obj:`False` will store data on any transaction *and* on call to :meth:`flush`.
Default is :obj:`False`.
Args: Args:
filename (:obj:`str`): The filename for storing the pickle files. When :attr:`single_file` filename (:obj:`str`): The filename for storing the pickle files. When :attr:`single_file`
is false this will be used as a prefix. is :obj:`False` this will be used as a prefix.
store_user_data (:obj:`bool`, optional): Whether user_data should be saved by this store_user_data (:obj:`bool`, optional): Whether user_data should be saved by this
persistence class. Default is ``True``. persistence class. Default is :obj:`True`.
store_chat_data (:obj:`bool`, optional): Whether user_data should be saved by this store_chat_data (:obj:`bool`, optional): Whether user_data should be saved by this
persistence class. Default is ``True``. persistence class. Default is :obj:`True`.
store_bot_data (:obj:`bool`, optional): Whether bot_data should be saved by this store_bot_data (:obj:`bool`, optional): Whether bot_data should be saved by this
persistence class. Default is ``True`` . persistence class. Default is :obj:`True` .
single_file (:obj:`bool`, optional): When ``False`` will store 3 sperate files of single_file (:obj:`bool`, optional): When :obj:`False` will store 3 separate files of
`filename_user_data`, `filename_chat_data` and `filename_conversations`. Default is `filename_user_data`, `filename_chat_data` and `filename_conversations`. Default is
``True``. :obj:`True`.
on_flush (:obj:`bool`, optional): When ``True`` will only save to file when :meth:`flush` on_flush (:obj:`bool`, optional): When :obj:`True` will only save to file when
is called and keep data in memory until that happens. When ``False`` will store data :meth:`flush` is called and keep data in memory until that happens. When
on any transaction *and* on call fo :meth:`flush`. Default is ``False``. :obj:`False` will store data on any transaction *and* on call to :meth:`flush`.
Default is :obj:`False`.
""" """
def __init__(self, filename, def __init__(self, filename,
@ -119,7 +121,7 @@ class PicklePersistence(BasePersistence):
pickle.dump(data, f) pickle.dump(data, f)
def get_user_data(self): def get_user_data(self):
"""Returns the user_data from the pickle file if it exsists or an empty defaultdict. """Returns the user_data from the pickle file if it exists or an empty :obj:`defaultdict`.
Returns: Returns:
:obj:`defaultdict`: The restored user data. :obj:`defaultdict`: The restored user data.
@ -139,7 +141,7 @@ class PicklePersistence(BasePersistence):
return deepcopy(self.user_data) return deepcopy(self.user_data)
def get_chat_data(self): def get_chat_data(self):
"""Returns the chat_data from the pickle file if it exsists or an empty defaultdict. """Returns the chat_data from the pickle file if it exists or an empty :obj:`defaultdict`.
Returns: Returns:
:obj:`defaultdict`: The restored chat data. :obj:`defaultdict`: The restored chat data.
@ -159,10 +161,10 @@ class PicklePersistence(BasePersistence):
return deepcopy(self.chat_data) return deepcopy(self.chat_data)
def get_bot_data(self): def get_bot_data(self):
"""Returns the bot_data from the pickle file if it exsists or an empty dict. """Returns the bot_data from the pickle file if it exists or an empty :obj:`dict`.
Returns: Returns:
:obj:`defaultdict`: The restored bot data. :obj:`dict`: The restored bot data.
""" """
if self.bot_data: if self.bot_data:
pass pass
@ -177,7 +179,7 @@ class PicklePersistence(BasePersistence):
return deepcopy(self.bot_data) return deepcopy(self.bot_data)
def get_conversations(self, name): def get_conversations(self, name):
"""Returns the conversations from the pickle file if it exsists or an empty defaultdict. """Returns the conversations from the pickle file if it exists or an empty :obj:`dict`.
Args: Args:
name (:obj:`str`): The handlers name. name (:obj:`str`): The handlers name.
@ -202,7 +204,7 @@ class PicklePersistence(BasePersistence):
save the pickle file. save the pickle file.
Args: Args:
name (:obj:`str`): The handlers name. name (:obj:`str`): The handler's name.
key (:obj:`tuple`): The key the state is changed for. key (:obj:`tuple`): The key the state is changed for.
new_state (:obj:`tuple` | :obj:`any`): The new state for the given key. new_state (:obj:`tuple` | :obj:`any`): The new state for the given key.
""" """
@ -217,8 +219,7 @@ class PicklePersistence(BasePersistence):
self.dump_singlefile() self.dump_singlefile()
def update_user_data(self, user_id, data): def update_user_data(self, user_id, data):
"""Will update the user_data (if changed) and depending on :attr:`on_flush` save the """Will update the user_data and depending on :attr:`on_flush` save the pickle file.
pickle file.
Args: Args:
user_id (:obj:`int`): The user the data might have been changed for. user_id (:obj:`int`): The user the data might have been changed for.
@ -237,8 +238,7 @@ class PicklePersistence(BasePersistence):
self.dump_singlefile() self.dump_singlefile()
def update_chat_data(self, chat_id, data): def update_chat_data(self, chat_id, data):
"""Will update the chat_data (if changed) and depending on :attr:`on_flush` save the """Will update the chat_data and depending on :attr:`on_flush` save the pickle file.
pickle file.
Args: Args:
chat_id (:obj:`int`): The chat the data might have been changed for. chat_id (:obj:`int`): The chat the data might have been changed for.
@ -257,8 +257,7 @@ class PicklePersistence(BasePersistence):
self.dump_singlefile() self.dump_singlefile()
def update_bot_data(self, data): def update_bot_data(self, data):
"""Will update the bot_data (if changed) and depending on :attr:`on_flush` save the """Will update the bot_data and depending on :attr:`on_flush` save the pickle file.
pickle file.
Args: Args:
data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.bot_data`. data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.bot_data`.

16
telegram/ext/pollanswerhandler.py
View file

@ -53,21 +53,21 @@ class PollAnswerHandler(Handler):
The return value of the callback is usually ignored except for the special case of The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`. :class:`telegram.ext.ConversationHandler`.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_user_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``. ``user_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_chat_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``. ``chat_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
""" """

16
telegram/ext/pollhandler.py
View file

@ -53,21 +53,21 @@ class PollHandler(Handler):
The return value of the callback is usually ignored except for the special case of The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`. :class:`telegram.ext.ConversationHandler`.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_user_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``. ``user_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_chat_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``. ``chat_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
""" """

16
telegram/ext/precheckoutqueryhandler.py
View file

@ -54,21 +54,21 @@ class PreCheckoutQueryHandler(Handler):
The return value of the callback is usually ignored except for the special case of The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`. :class:`telegram.ext.ConversationHandler`.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_user_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``. ``user_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_chat_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``. ``chat_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
""" """

28
telegram/ext/regexhandler.py
View file

@ -50,7 +50,7 @@ class RegexHandler(MessageHandler):
the callback function. the callback function.
Note: Note:
This handler is being deprecated. For the same usecase use: This handler is being deprecated. For the same use case use:
``MessageHandler(Filters.regex(r'pattern'), callback)`` ``MessageHandler(Filters.regex(r'pattern'), callback)``
@ -66,28 +66,28 @@ class RegexHandler(MessageHandler):
:class:`telegram.ext.ConversationHandler`. :class:`telegram.ext.ConversationHandler`.
pass_groups (:obj:`bool`, optional): If the callback should be passed the result of pass_groups (:obj:`bool`, optional): If the callback should be passed the result of
``re.match(pattern, data).groups()`` as a keyword argument called ``groups``. ``re.match(pattern, data).groups()`` as a keyword argument called ``groups``.
Default is ``False`` Default is :obj:`False`
pass_groupdict (:obj:`bool`, optional): If the callback should be passed the result of pass_groupdict (:obj:`bool`, optional): If the callback should be passed the result of
``re.match(pattern, data).groupdict()`` as a keyword argument called ``groupdict``. ``re.match(pattern, data).groupdict()`` as a keyword argument called ``groupdict``.
Default is ``False`` Default is :obj:`False`
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_user_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``. ``user_data`` will be passed to the callback function. Default is :obj:`False`.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_chat_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``. ``chat_data`` will be passed to the callback function. Default is :obj:`False`.
message_updates (:obj:`bool`, optional): Should "normal" message updates be handled? message_updates (:obj:`bool`, optional): Should "normal" message updates be handled?
Default is ``True``. Default is :obj:`True`.
channel_post_updates (:obj:`bool`, optional): Should channel posts updates be handled? channel_post_updates (:obj:`bool`, optional): Should channel posts updates be handled?
Default is ``True``. Default is :obj:`True`.
edited_updates (:obj:`bool`, optional): Should "edited" message updates be handled? Default edited_updates (:obj:`bool`, optional): Should "edited" message updates be handled? Default
is ``False``. is :obj:`False`.
Raises: Raises:
ValueError ValueError

16
telegram/ext/shippingqueryhandler.py
View file

@ -54,21 +54,21 @@ class ShippingQueryHandler(Handler):
The return value of the callback is usually ignored except for the special case of The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`. :class:`telegram.ext.ConversationHandler`.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_user_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``. ``user_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_chat_data (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``. ``chat_data`` will be passed to the callback function. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
""" """

10
telegram/ext/stringcommandhandler.py
View file

@ -50,17 +50,17 @@ class StringCommandHandler(Handler):
pass_args (:obj:`bool`, optional): Determines whether the handler should be passed the pass_args (:obj:`bool`, optional): Determines whether the handler should be passed the
arguments passed to the command as a keyword argument called ``args``. It will contain arguments passed to the command as a keyword argument called ``args``. It will contain
a list of strings, which is the text following the command split on single or a list of strings, which is the text following the command split on single or
consecutive whitespace characters. Default is ``False`` consecutive whitespace characters. Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
""" """

12
telegram/ext/stringregexhandler.py
View file

@ -57,21 +57,21 @@ class StringRegexHandler(Handler):
:class:`telegram.ext.ConversationHandler`. :class:`telegram.ext.ConversationHandler`.
pass_groups (:obj:`bool`, optional): If the callback should be passed the result of pass_groups (:obj:`bool`, optional): If the callback should be passed the result of
``re.match(pattern, data).groups()`` as a keyword argument called ``groups``. ``re.match(pattern, data).groups()`` as a keyword argument called ``groups``.
Default is ``False`` Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_groupdict (:obj:`bool`, optional): If the callback should be passed the result of pass_groupdict (:obj:`bool`, optional): If the callback should be passed the result of
``re.match(pattern, data).groupdict()`` as a keyword argument called ``groupdict``. ``re.match(pattern, data).groupdict()`` as a keyword argument called ``groupdict``.
Default is ``False`` Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
""" """

12
telegram/ext/typehandler.py
View file

@ -27,7 +27,7 @@ class TypeHandler(Handler):
Attributes: Attributes:
type (:obj:`type`): The ``type`` of updates this handler should process. type (:obj:`type`): The ``type`` of updates this handler should process.
callback (:obj:`callable`): The callback function for this handler. callback (:obj:`callable`): The callback function for this handler.
strict (:obj:`bool`): Use ``type`` instead of ``isinstance``. Default is ``False``. strict (:obj:`bool`): Use ``type`` instead of ``isinstance``. Default is :obj:`False`.
pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
passed to the callback function. passed to the callback function.
pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
@ -45,16 +45,16 @@ class TypeHandler(Handler):
The return value of the callback is usually ignored except for the special case of The return value of the callback is usually ignored except for the special case of
:class:`telegram.ext.ConversationHandler`. :class:`telegram.ext.ConversationHandler`.
strict (:obj:`bool`, optional): Use ``type`` instead of ``isinstance``. strict (:obj:`bool`, optional): Use ``type`` instead of ``isinstance``.
Default is ``False`` Default is :obj:`False`
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_update_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``update_queue`` will be passed to the callback function. It will be the ``Queue`` ``update_queue`` will be passed to the callback function. It will be the ``Queue``
instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher` instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
that contains new updates which can be used to insert updates. Default is ``False``. that contains new updates which can be used to insert updates. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called pass_job_queue (:obj:`bool`, optional): If set to :obj:`True`, a keyword argument called
``job_queue`` will be passed to the callback function. It will be a ``job_queue`` will be passed to the callback function. It will be a
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater` :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``. which can be used to schedule new jobs. Default is :obj:`False`.
DEPRECATED: Please switch to context based callbacks. DEPRECATED: Please switch to context based callbacks.
""" """

20
telegram/ext/updater.py
View file

@ -56,7 +56,7 @@ class Updater:
running (:obj:`bool`): Indicates if the updater is running. running (:obj:`bool`): Indicates if the updater is running.
persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to
store data that should be persistent over restarts. store data that should be persistent over restarts.
use_context (:obj:`bool`): Optional. ``True`` if using context based callbacks. use_context (:obj:`bool`): Optional. :obj:`True` if using context based callbacks.
Args: Args:
token (:obj:`str`, optional): The bot's token given by the @BotFather. token (:obj:`str`, optional): The bot's token given by the @BotFather.
@ -75,14 +75,14 @@ class Updater:
private_key_password (:obj:`bytes`, optional): Password for above private key. private_key_password (:obj:`bytes`, optional): Password for above private key.
user_sig_handler (:obj:`function`, optional): Takes ``signum, frame`` as positional user_sig_handler (:obj:`function`, optional): Takes ``signum, frame`` as positional
arguments. This will be called when a signal is received, defaults are (SIGINT, arguments. This will be called when a signal is received, defaults are (SIGINT,
SIGTERM, SIGABRT) setable with :attr:`idle`. SIGTERM, SIGABRT) settable with :attr:`idle`.
request_kwargs (:obj:`dict`, optional): Keyword args to control the creation of a request_kwargs (:obj:`dict`, optional): Keyword args to control the creation of a
`telegram.utils.request.Request` object (ignored if `bot` or `dispatcher` argument is `telegram.utils.request.Request` object (ignored if `bot` or `dispatcher` argument is
used). The request_kwargs are very useful for the advanced users who would like to used). The request_kwargs are very useful for the advanced users who would like to
control the default timeouts and/or control the proxy used for http communication. control the default timeouts and/or control the proxy used for http communication.
use_context (:obj:`bool`, optional): If set to ``True`` Use the context based callback API use_context (:obj:`bool`, optional): If set to :obj:`True` Use the context based callback
(ignored if `dispatcher` argument is used). During the deprecation period of the old API (ignored if :attr:`dispatcher` argument is used). During the deprecation period of
API the default is ``False``. **New users**: set this to ``True``. the old API the default is :obj:`False`. **New users**: set this to :obj:`True`.
persistence (:class:`telegram.ext.BasePersistence`, optional): The persistence class to persistence (:class:`telegram.ext.BasePersistence`, optional): The persistence class to
store data that should be persistent over restarts (ignored if `dispatcher` argument is store data that should be persistent over restarts (ignored if `dispatcher` argument is
used). used).
@ -233,7 +233,7 @@ class Updater:
Telegram in seconds. Default is 0.0. Telegram in seconds. Default is 0.0.
timeout (:obj:`float`, optional): Passed to :attr:`telegram.Bot.get_updates`. timeout (:obj:`float`, optional): Passed to :attr:`telegram.Bot.get_updates`.
clean (:obj:`bool`, optional): Whether to clean any pending updates on Telegram servers clean (:obj:`bool`, optional): Whether to clean any pending updates on Telegram servers
before actually starting to poll. Default is False. before actually starting to poll. Default is :obj:`False`.
bootstrap_retries (:obj:`int`, optional): Whether the bootstrapping phase of the bootstrap_retries (:obj:`int`, optional): Whether the bootstrapping phase of the
`Updater` will retry on failures on the Telegram server. `Updater` will retry on failures on the Telegram server.
@ -291,7 +291,7 @@ class Updater:
cert (:obj:`str`, optional): Path to the SSL certificate file. cert (:obj:`str`, optional): Path to the SSL certificate file.
key (:obj:`str`, optional): Path to the SSL key file. key (:obj:`str`, optional): Path to the SSL key file.
clean (:obj:`bool`, optional): Whether to clean any pending updates on Telegram servers clean (:obj:`bool`, optional): Whether to clean any pending updates on Telegram servers
before actually starting the webhook. Default is ``False``. before actually starting the webhook. Default is :obj:`False`.
bootstrap_retries (:obj:`int`, optional): Whether the bootstrapping phase of the bootstrap_retries (:obj:`int`, optional): Whether the bootstrapping phase of the
`Updater` will retry on failures on the Telegram server. `Updater` will retry on failures on the Telegram server.
@ -360,8 +360,8 @@ class Updater:
def _network_loop_retry(self, action_cb, onerr_cb, description, interval): def _network_loop_retry(self, action_cb, onerr_cb, description, interval):
"""Perform a loop calling `action_cb`, retrying after network errors. """Perform a loop calling `action_cb`, retrying after network errors.
Stop condition for loop: `self.running` evaluates False or return value of `action_cb` Stop condition for loop: `self.running` evaluates :obj:`False` or return value of
evaluates False. `action_cb` evaluates :obj:`False`.
Args: Args:
action_cb (:obj:`callable`): Network oriented callback function to call. action_cb (:obj:`callable`): Network oriented callback function to call.
@ -554,7 +554,7 @@ class Updater:
self.logger.info('Received signal {} ({}), stopping...'.format( self.logger.info('Received signal {} ({}), stopping...'.format(
signum, get_signal_name(signum))) signum, get_signal_name(signum)))
if self.persistence: if self.persistence:
# Update user_data and chat_data before flushing # Update user_data, chat_data and bot_data before flushing
self.dispatcher.update_persistence() self.dispatcher.update_persistence()
self.persistence.flush() self.persistence.flush()
self.stop() self.stop()

10
telegram/files/animation.py
View file

@ -22,7 +22,7 @@ from telegram import TelegramObject
class Animation(TelegramObject): class Animation(TelegramObject):
"""This object represents an animation file to be displayed in the message containing a game. """This object represents an animation file (GIF or H.264/MPEG-4 AVC video without sound).
Attributes: Attributes:
file_id (:obj:`str`): File identifier. file_id (:obj:`str`): File identifier.
@ -32,8 +32,7 @@ class Animation(TelegramObject):
width (:obj:`int`): Video width as defined by sender. width (:obj:`int`): Video width as defined by sender.
height (:obj:`int`): Video height as defined by sender. height (:obj:`int`): Video height as defined by sender.
duration (:obj:`int`): Duration of the video in seconds as defined by sender. duration (:obj:`int`): Duration of the video in seconds as defined by sender.
thumb (:class:`telegram.PhotoSize`): Optional. Animation thumbnail as defined thumb (:class:`telegram.PhotoSize`): Optional. Animation thumbnail as defined by sender.
by sender.
file_name (:obj:`str`): Optional. Original animation filename 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. 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.
@ -42,8 +41,9 @@ class Animation(TelegramObject):
Args: Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file. or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and file_unique_id (:obj:`str`): Unique identifier for this file, which
for different bots file identifier. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
width (:obj:`int`): Video width as defined by sender. width (:obj:`int`): Video width as defined by sender.
height (:obj:`int`): Video height as defined by sender. height (:obj:`int`): Video height as defined by sender.
duration (:obj:`int`): Duration of the video in seconds as defined by sender. duration (:obj:`int`): Duration of the video in seconds as defined by sender.

10
telegram/files/audio.py
View file

@ -25,7 +25,7 @@ class Audio(TelegramObject):
"""This object represents an audio file to be treated as music by the Telegram clients. """This object represents an audio file to be treated as music by the Telegram clients.
Attributes: Attributes:
file_id (:obj:`str`): Unique identifier for this file. file_id (:obj:`str`): Identifier for this file.
file_unique_id (:obj:`str`): Unique identifier for this file, which file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file. Can't be used to download or reuse the file.
@ -36,14 +36,14 @@ class Audio(TelegramObject):
mime_type (:obj:`str`): Optional. MIME type of the file 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.
thumb (:class:`telegram.PhotoSize`): Optional. Thumbnail of the album cover to thumb (:class:`telegram.PhotoSize`): Optional. Thumbnail of the album cover to
which the music file belongs which the music file belongs.
bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods. bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
Args: Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file. or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be
for different bots file identifier. the same over time and for different bots. Can't be used to download or reuse the file.
duration (:obj:`int`): Duration of the audio in seconds as defined by sender. duration (:obj:`int`): Duration of the audio in seconds as defined by sender.
performer (:obj:`str`, optional): Performer of the audio as defined by sender or by audio performer (:obj:`str`, optional): Performer of the audio as defined by sender or by audio
tags. tags.
@ -51,7 +51,7 @@ class Audio(TelegramObject):
mime_type (:obj:`str`, optional): MIME type of the file 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.
thumb (:class:`telegram.PhotoSize`, optional): Thumbnail of the album cover to thumb (:class:`telegram.PhotoSize`, optional): Thumbnail of the album cover to
which the music file belongs which the music file belongs.
bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.

9
telegram/files/document.py
View file

@ -22,10 +22,11 @@ from telegram import PhotoSize, TelegramObject
class Document(TelegramObject): class Document(TelegramObject):
"""This object represents a general file (as opposed to photos, voice messages and audio files). """This object represents a general file
(as opposed to photos, voice messages and audio files).
Attributes: Attributes:
file_id (:obj:`str`): Unique file identifier. file_id (:obj:`str`): File identifier.
file_unique_id (:obj:`str`): Unique identifier for this file, which file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file. Can't be used to download or reuse the file.
@ -38,8 +39,8 @@ class Document(TelegramObject):
Args: Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file. or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be
for different bots file identifier. the same over time and for different bots. Can't be used to download or reuse the file.
thumb (:class:`telegram.PhotoSize`, optional): Document thumbnail as defined by sender. thumb (:class:`telegram.PhotoSize`, optional): Document thumbnail as defined by sender.
file_name (:obj:`str`, optional): Original filename 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. mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.

11
telegram/files/file.py
View file

@ -31,13 +31,13 @@ class File(TelegramObject):
""" """
This object represents a file ready to be downloaded. The file can be downloaded with This object represents a file ready to be downloaded. The file can be downloaded with
:attr:`download`. It is guaranteed that the link will be valid for at least 1 hour. When the :attr:`download`. It is guaranteed that the link will be valid for at least 1 hour. When the
link expires, a new one can be requested by calling getFile. link expires, a new one can be requested by calling :meth:`telegram.Bot.get_file`.
Note: Note:
Maximum file size to download is 20 MB Maximum file size to download is 20 MB.
Attributes: Attributes:
file_id (:obj:`str`): Unique identifier for this file. file_id (:obj:`str`): Identifier for this file.
file_unique_id (:obj:`str`): Unique identifier for this file, which file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file. Can't be used to download or reuse the file.
@ -47,8 +47,9 @@ class File(TelegramObject):
Args: Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file. or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and file_unique_id (:obj:`str`): Unique identifier for this file, which
for different bots file identifier. 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, if known.
file_path (:obj:`str`, optional): File path. Use :attr:`download` to get the file. 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. bot (:obj:`telegram.Bot`, optional): Bot to use with shortcut method.

6
telegram/files/inputfile.py
View file

@ -33,9 +33,9 @@ class InputFile:
"""This object represents a Telegram InputFile. """This object represents a Telegram InputFile.
Attributes: Attributes:
input_file_content (:obj:`bytes`): The binaray content of the file to send. input_file_content (:obj:`bytes`): The binary content of the file to send.
filename (:obj:`str`): Optional, Filename for the file to be sent. filename (:obj:`str`): Optional. Filename for the file to be sent.
attach (:obj:`str`): Optional, attach id for sending multiple files. attach (:obj:`str`): Optional. Attach id for sending multiple files.
Args: Args:
obj (:obj:`File handler`): An open file descriptor. obj (:obj:`File handler`): An open file descriptor.

10
telegram/files/inputmedia.py
View file

@ -155,8 +155,8 @@ class InputMediaVideo(InputMedia):
width (:obj:`int`): Optional. Video width. width (:obj:`int`): Optional. Video width.
height (:obj:`int`): Optional. Video height. height (:obj:`int`): Optional. Video height.
duration (:obj:`int`): Optional. Video duration. duration (:obj:`int`): Optional. Video duration.
supports_streaming (:obj:`bool`): Optional. Pass True, if the uploaded video is suitable supports_streaming (:obj:`bool`): Optional. Pass :obj:`True`, if the uploaded video is
for streaming. suitable for streaming.
thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send. thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send.
Args: Args:
@ -172,8 +172,8 @@ class InputMediaVideo(InputMedia):
width (:obj:`int`, optional): Video width. width (:obj:`int`, optional): Video width.
height (:obj:`int`, optional): Video height. height (:obj:`int`, optional): Video height.
duration (:obj:`int`, optional): Video duration. duration (:obj:`int`, optional): Video duration.
supports_streaming (:obj:`bool`, optional): Pass True, if the uploaded video is suitable supports_streaming (:obj:`bool`, optional): Pass :obj:`True`, if the uploaded video is
for streaming. suitable for streaming.
thumb (`filelike object`, optional): Thumbnail of the file sent; can be ignored if thumb (`filelike object`, optional): Thumbnail of the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be thumbnail generation for the file is supported server-side. The thumbnail should be
in JPEG format and less than 200 kB in size. A thumbnail's width and height should in JPEG format and less than 200 kB in size. A thumbnail's width and height should
@ -236,7 +236,7 @@ class InputMediaAudio(InputMedia):
media (:obj:`str` | `filelike object` | :class:`telegram.Audio`): File to send. Pass a media (:obj:`str` | `filelike object` | :class:`telegram.Audio`): File to send. Pass a
file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP
URL for Telegram to get a file from the Internet. Lastly you can pass an existing URL for Telegram to get a file from the Internet. Lastly you can pass an existing
:class:`telegram.Document` object to send. :class:`telegram.Audio` object to send.
caption (:obj:`str`, optional): Caption of the audio to be sent, 0-1024 characters after caption (:obj:`str`, optional): Caption of the audio to be sent, 0-1024 characters after
entities parsing. entities parsing.
parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show

7
telegram/files/photosize.py
View file

@ -25,7 +25,7 @@ class PhotoSize(TelegramObject):
"""This object represents one size of a photo or a file/sticker thumbnail. """This object represents one size of a photo or a file/sticker thumbnail.
Attributes: Attributes:
file_id (:obj:`str`): Unique identifier for this file. file_id (:obj:`str`): Identifier for this file.
file_unique_id (:obj:`str`): Unique identifier for this file, which file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file. Can't be used to download or reuse the file.
@ -37,8 +37,9 @@ class PhotoSize(TelegramObject):
Args: Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file. or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and file_unique_id (:obj:`str`): Unique identifier for this file, which
for different bots file identifier. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
width (:obj:`int`): Photo width. width (:obj:`int`): Photo width.
height (:obj:`int`): Photo height. height (:obj:`int`): Photo height.
file_size (:obj:`int`, optional): File size. file_size (:obj:`int`, optional): File size.

32
telegram/files/sticker.py
View file

@ -25,13 +25,13 @@ class Sticker(TelegramObject):
"""This object represents a sticker. """This object represents a sticker.
Attributes: Attributes:
file_id (:obj:`str`): Unique identifier for this file. file_id (:obj:`str`): Identifier for this file.
file_unique_id (:obj:`str`): Unique identifier for this file, which file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file. Can't be used to download or reuse the file.
width (:obj:`int`): Sticker width. width (:obj:`int`): Sticker width.
height (:obj:`int`): Sticker height. height (:obj:`int`): Sticker height.
is_animated (:obj:`bool`): True, if the sticker is animated. is_animated (:obj:`bool`): :obj:`True`, if the sticker is animated.
thumb (:class:`telegram.PhotoSize`): Optional. Sticker thumbnail in the .webp or .jpg thumb (:class:`telegram.PhotoSize`): Optional. Sticker thumbnail in the .webp or .jpg
format. format.
emoji (:obj:`str`): Optional. Emoji associated with the sticker. emoji (:obj:`str`): Optional. Emoji associated with the sticker.
@ -44,12 +44,13 @@ class Sticker(TelegramObject):
Args: Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file. or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and file_unique_id (:obj:`str`): Unique identifier for this file, which
for different bots file identifier. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
width (:obj:`int`): Sticker width. width (:obj:`int`): Sticker width.
height (:obj:`int`): Sticker height. height (:obj:`int`): Sticker height.
is_animated (:obj:`bool`): True, if the sticker is animated. is_animated (:obj:`bool`): :obj:`True`, if the sticker is animated.
thumb (:class:`telegram.PhotoSize`, optional): Sticker thumbnail in the .webp or .jpg thumb (:class:`telegram.PhotoSize`, optional): Sticker thumbnail in the .WEBP or .JPG
format. format.
emoji (:obj:`str`, optional): Emoji associated with the sticker emoji (:obj:`str`, optional): Emoji associated with the sticker
set_name (:obj:`str`, optional): Name of the sticker set to which the sticker set_name (:obj:`str`, optional): Name of the sticker set to which the sticker
@ -57,8 +58,9 @@ class Sticker(TelegramObject):
mask_position (:class:`telegram.MaskPosition`, optional): For mask stickers, the mask_position (:class:`telegram.MaskPosition`, optional): For mask stickers, the
position where the mask should be placed. position where the mask should be placed.
file_size (:obj:`int`, optional): File size. file_size (:obj:`int`, optional): File size.
**kwargs (obj:`dict`): Arbitrary keyword arguments.7
bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
**kwargs (obj:`dict`): Arbitrary keyword arguments.
""" """
@ -135,20 +137,20 @@ class StickerSet(TelegramObject):
Attributes: Attributes:
name (:obj:`str`): Sticker set name. name (:obj:`str`): Sticker set name.
title (:obj:`str`): Sticker set title. title (:obj:`str`): Sticker set title.
is_animated (:obj:`bool`): True, if the sticker set contains animated stickers. is_animated (:obj:`bool`): :obj:`True`, if the sticker set contains animated stickers.
contains_masks (:obj:`bool`): True, if the sticker set contains masks. contains_masks (:obj:`bool`): :obj:`True`, if the sticker set contains masks.
stickers (List[:class:`telegram.Sticker`]): List of all set stickers. stickers (List[:class:`telegram.Sticker`]): List of all set stickers.
thumb (:class:`telegram.PhotoSize`): Optional. Sticker set thumbnail in the .WEBP or .TGS thumb (:class:`telegram.PhotoSize`): Optional. Sticker set thumbnail in the .WEBP or .TGS
format format.
Args: Args:
name (:obj:`str`): Sticker set name. name (:obj:`str`): Sticker set name.
title (:obj:`str`): Sticker set title. title (:obj:`str`): Sticker set title.
is_animated (:obj:`bool`): True, if the sticker set contains animated stickers. is_animated (:obj:`bool`): :obj:`True`, if the sticker set contains animated stickers.
contains_masks (:obj:`bool`): True, if the sticker set contains masks. contains_masks (:obj:`bool`): :obj:`True`, if the sticker set contains masks.
stickers (List[:class:`telegram.Sticker`]): List of all set stickers. stickers (List[:class:`telegram.Sticker`]): List of all set stickers.
thumb (:class:`telegram.PhotoSize`, optional): Sticker set thumbnail in the .WEBP or .TGS thumb (:class:`telegram.PhotoSize`, optional): Sticker set thumbnail in the .WEBP or .TGS
format format.
""" """
@ -189,6 +191,7 @@ class MaskPosition(TelegramObject):
Attributes: Attributes:
point (:obj:`str`): The part of the face relative to which the mask should be placed. point (:obj:`str`): The part of the face relative to which the mask should be placed.
One of ``'forehead'``, ``'eyes'``, ``'mouth'``, or ``'chin'``.
x_shift (:obj:`float`): Shift by X-axis measured in widths of the mask scaled to the face x_shift (:obj:`float`): Shift by X-axis measured in widths of the mask scaled to the face
size, from left to right. size, from left to right.
y_shift (:obj:`float`): Shift by Y-axis measured in heights of the mask scaled to the face y_shift (:obj:`float`): Shift by Y-axis measured in heights of the mask scaled to the face
@ -197,10 +200,11 @@ class MaskPosition(TelegramObject):
Note: Note:
:attr:`type` should be one of the following: `forehead`, `eyes`, `mouth` or `chin`. You can :attr:`type` should be one of the following: `forehead`, `eyes`, `mouth` or `chin`. You can
use the classconstants for those. use the class constants for those.
Args: Args:
point (:obj:`str`): The part of the face relative to which the mask should be placed. point (:obj:`str`): The part of the face relative to which the mask should be placed.
One of ``'forehead'``, ``'eyes'``, ``'mouth'``, or ``'chin'``.
x_shift (:obj:`float`): Shift by X-axis measured in widths of the mask scaled to the face x_shift (:obj:`float`): Shift by X-axis measured in widths of the mask scaled to the face
size, from left to right. For example, choosing -1.0 will place mask just to the left size, from left to right. For example, choosing -1.0 will place mask just to the left
of the default mask position. of the default mask position.

7
telegram/files/video.py
View file

@ -25,7 +25,7 @@ class Video(TelegramObject):
"""This object represents a video file. """This object represents a video file.
Attributes: Attributes:
file_id (:obj:`str`): Unique identifier for this file. file_id (:obj:`str`): Identifier for this file.
file_unique_id (:obj:`str`): Unique identifier for this file, which file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file. Can't be used to download or reuse the file.
@ -40,8 +40,9 @@ class Video(TelegramObject):
Args: Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file. or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and file_unique_id (:obj:`str`): Unique identifier for this file, which
for different bots file identifier. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
width (:obj:`int`): Video width as defined by sender. width (:obj:`int`): Video width as defined by sender.
height (:obj:`int`): Video height as defined by sender. height (:obj:`int`): Video height as defined by sender.
duration (:obj:`int`): Duration of the video in seconds as defined by sender. duration (:obj:`int`): Duration of the video in seconds as defined by sender.

10
telegram/files/videonote.py
View file

@ -25,7 +25,7 @@ class VideoNote(TelegramObject):
"""This object represents a video message (available in Telegram apps as of v.4.0). """This object represents a video message (available in Telegram apps as of v.4.0).
Attributes: Attributes:
file_id (:obj:`str`): Unique identifier for this file. file_id (:obj:`str`): Identifier for this file.
file_unique_id (:obj:`str`): Unique identifier for this file, which file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file. Can't be used to download or reuse the file.
@ -38,9 +38,11 @@ class VideoNote(TelegramObject):
Args: Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file. or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and file_unique_id (:obj:`str`): Unique identifier for this file, which
for different bots file identifier. is supposed to be the same over time and for different bots.
length (:obj:`int`): Video width and height as defined by sender. Can't be used to download or reuse the file.
length (:obj:`int`): Video width and height (diameter of the video message) as defined
by sender.
duration (:obj:`int`): Duration of the video in seconds as defined by sender. duration (:obj:`int`): Duration of the video in seconds as defined by sender.
thumb (:class:`telegram.PhotoSize`, optional): Video thumbnail. thumb (:class:`telegram.PhotoSize`, optional): Video thumbnail.
file_size (:obj:`int`, optional): File size. file_size (:obj:`int`, optional): File size.

7
telegram/files/voice.py
View file

@ -25,7 +25,7 @@ class Voice(TelegramObject):
"""This object represents a voice note. """This object represents a voice note.
Attributes: Attributes:
file_id (:obj:`str`): Unique identifier for this file. file_id (:obj:`str`): Identifier for this file.
file_unique_id (:obj:`str`): Unique identifier for this file, which file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file. Can't be used to download or reuse the file.
@ -37,8 +37,9 @@ class Voice(TelegramObject):
Args: Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file. or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and file_unique_id (:obj:`str`): Unique identifier for this file, which
for different bots file identifier. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
duration (:obj:`int`, optional): Duration of the audio in seconds as defined by sender. 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. 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.

7
telegram/forcereply.py
View file

@ -29,15 +29,16 @@ class ForceReply(ReplyMarkup):
to sacrifice privacy mode. to sacrifice privacy mode.
Attributes: Attributes:
force_reply (:obj:`True`): Shows reply interface to the user. force_reply (:obj:`True`): Shows reply interface to the user, as if they manually selected
the bot's message and tapped 'Reply'.
selective (:obj:`bool`): Optional. Force reply from specific users only. selective (:obj:`bool`): Optional. Force reply from specific users only.
Args: Args:
selective (:obj:`bool`, optional): Use this parameter if you want to force reply from selective (:obj:`bool`, optional): Use this parameter if you want to force reply from
specific users only. Targets: specific users only. Targets:
1) users that are @mentioned in the text of the Message object 1) Users that are @mentioned in the text of the Message object.
2) if the bot's message is a reply (has reply_to_message_id), sender of the 2) If the bot's message is a reply (has reply_to_message_id), sender of the
original message. original message.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.

16
telegram/games/game.py
View file

@ -25,8 +25,8 @@ from telegram import MessageEntity, TelegramObject, Animation, PhotoSize
class Game(TelegramObject): class Game(TelegramObject):
""" """
This object represents a game. Use BotFather to create and edit games, their short names will This object represents a game. Use `BotFather <https://t.me/BotFather>`_ to create and edit
act as unique identifiers. games, their short names will act as unique identifiers.
Attributes: Attributes:
title (:obj:`str`): Title of the game. title (:obj:`str`): Title of the game.
@ -35,11 +35,12 @@ class Game(TelegramObject):
in chats. in chats.
text (:obj:`str`): Optional. Brief description of the game or high scores included in the text (:obj:`str`): Optional. Brief description of the game or high scores included in the
game message. Can be automatically edited to include current high scores for the game game message. Can be automatically edited to include current high scores for the game
when the bot calls set_game_score, or manually edited using edit_message_text. when the bot calls :meth:`telegram.Bot.set_game_score`, or manually edited
using :meth:`telegram.Bot.edit_message_text`.
text_entities (List[:class:`telegram.MessageEntity`]): Optional. Special entities that text_entities (List[:class:`telegram.MessageEntity`]): Optional. Special entities that
appear in text, such as usernames, URLs, bot commands, etc. appear in text, such as usernames, URLs, bot commands, etc.
animation (:class:`telegram.Animation`): Optional. Animation that will be displayed in the animation (:class:`telegram.Animation`): Optional. Animation that will be displayed in the
game message in chats. Upload via BotFather. game message in chats. Upload via `BotFather <https://t.me/BotFather>`_.
Args: Args:
title (:obj:`str`): Title of the game. title (:obj:`str`): Title of the game.
@ -48,12 +49,13 @@ class Game(TelegramObject):
in chats. in chats.
text (:obj:`str`, optional): Brief description of the game or high scores included in the text (:obj:`str`, optional): Brief description of the game or high scores included in the
game message. Can be automatically edited to include current high scores for the game game message. Can be automatically edited to include current high scores for the game
when the bot calls set_game_score, or manually edited using edit_message_text. when the bot calls :meth:`telegram.Bot.set_game_score`, or manually edited
0-4096 characters. Also found as ``telegram.constants.MAX_MESSAGE_LENGTH``. using :meth:`telegram.Bot.edit_message_text`.
1-4096 characters. Also found as ``telegram.constants.MAX_MESSAGE_LENGTH``.
text_entities (List[:class:`telegram.MessageEntity`], optional): Special entities that text_entities (List[:class:`telegram.MessageEntity`], optional): Special entities that
appear in text, such as usernames, URLs, bot commands, etc. appear in text, such as usernames, URLs, bot commands, etc.
animation (:class:`telegram.Animation`, optional): Animation that will be displayed in the animation (:class:`telegram.Animation`, optional): Animation that will be displayed in the
game message in chats. Upload via BotFather. game message in chats. Upload via `BotFather <https://t.me/BotFather>`_.
""" """

4
telegram/inline/inlinekeyboardbutton.py
View file

@ -67,8 +67,8 @@ class InlineKeyboardButton(TelegramObject):
callback_game (:class:`telegram.CallbackGame`, optional): Description of the game that will callback_game (:class:`telegram.CallbackGame`, optional): Description of the game that will
be launched when the user presses the button. This type of button must always be be launched when the user presses the button. This type of button must always be
the ``first`` button in the first row. the ``first`` button in the first row.
pay (:obj:`bool`, optional): Specify True, to send a Pay button. This type of button must pay (:obj:`bool`, optional): Specify :obj:`True`, to send a Pay button. This type of button
always be the ``first`` button in the first row. must always be the ``first`` button in the first row.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
""" """

8
telegram/inline/inlinekeyboardmarkup.py
View file

@ -26,12 +26,12 @@ class InlineKeyboardMarkup(ReplyMarkup):
This object represents an inline keyboard that appears right next to the message it belongs to. This object represents an inline keyboard that appears right next to the message it belongs to.
Attributes: Attributes:
inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): Array of button rows, inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): List of button rows,
each represented by an Array of InlineKeyboardButton objects. each represented by a list of InlineKeyboardButton objects.
Args: Args:
inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): Array of button rows, inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): List of button rows,
each represented by an Array of InlineKeyboardButton objects. each represented by a list of InlineKeyboardButton objects.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
""" """

6
telegram/inline/inlinequery.py
View file

@ -85,9 +85,9 @@ class InlineQuery(TelegramObject):
query. query.
cache_time (:obj:`int`, optional): The maximum amount of time in seconds that the cache_time (:obj:`int`, optional): The maximum amount of time in seconds that the
result of the inline query may be cached on the server. Defaults to 300. result of the inline query may be cached on the server. Defaults to 300.
is_personal (:obj:`bool`, optional): Pass True, if results may be cached on the server is_personal (:obj:`bool`, optional): Pass :obj:`True`, if results may be cached on the
side only for the user that sent the query. By default, results may be returned to server side only for the user that sent the query. By default, results may be
any user who sends the same query. returned to any user who sends the same query.
next_offset (:obj:`str`, optional): Pass the offset that a client should send in the next_offset (:obj:`str`, optional): Pass the offset that a client should send in the
next query with the same text to receive more results. Pass an empty string if next query with the same text to receive more results. Pass an empty string if
there are no more results or if you don't support pagination. Offset length can't there are no more results or if you don't support pagination. Offset length can't

8
telegram/inline/inlinequeryresultarticle.py
View file

@ -33,8 +33,8 @@ class InlineQueryResultArticle(InlineQueryResult):
reply_markup (:class:`telegram.ReplyMarkup`): Optional. Inline keyboard attached to reply_markup (:class:`telegram.ReplyMarkup`): Optional. Inline keyboard attached to
the message. the message.
url (:obj:`str`): Optional. URL of the result. url (:obj:`str`): Optional. URL of the result.
hide_url (:obj:`bool`): Optional. Pass True, if you don't want the URL to be shown in the hide_url (:obj:`bool`): Optional. Pass :obj:`True`, if you don't want the URL to be shown
message. in the message.
description (:obj:`str`): Optional. Short description of the result. description (:obj:`str`): Optional. Short description of the result.
thumb_url (:obj:`str`): Optional. Url of the thumbnail for the result. thumb_url (:obj:`str`): Optional. Url of the thumbnail for the result.
thumb_width (:obj:`int`): Optional. Thumbnail width. thumb_width (:obj:`int`): Optional. Thumbnail width.
@ -48,8 +48,8 @@ class InlineQueryResultArticle(InlineQueryResult):
reply_markup (:class:`telegram.ReplyMarkup`, optional): Inline keyboard attached to reply_markup (:class:`telegram.ReplyMarkup`, optional): Inline keyboard attached to
the message the message
url (:obj:`str`, optional): URL of the result. url (:obj:`str`, optional): URL of the result.
hide_url (:obj:`bool`, optional): Pass True, if you don't want the URL to be shown in the hide_url (:obj:`bool`, optional): Pass :obj:`True`, if you don't want the URL to be shown
message. in the message.
description (:obj:`str`, optional): Short description of the result. description (:obj:`str`, optional): Short description of the result.
thumb_url (:obj:`str`, optional): Url of the thumbnail for the result. thumb_url (:obj:`str`, optional): Url of the thumbnail for the result.
thumb_width (:obj:`int`, optional): Thumbnail width. thumb_width (:obj:`int`, optional): Thumbnail width.

4
telegram/inline/inlinequeryresultcachedvoice.py
View file

@ -40,7 +40,7 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
to the message. to the message.
input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
message to be sent instead of the voice. message to be sent instead of the voice message.
Args: Args:
id (:obj:`str`): Unique identifier for this result, 1-64 bytes. id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
@ -53,7 +53,7 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message. to the message.
input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
message to be sent instead of the voice. message to be sent instead of the voice message.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
""" """

2
telegram/inline/inlinequeryresultgame.py
View file

@ -22,7 +22,7 @@ from telegram import InlineQueryResult
class InlineQueryResultGame(InlineQueryResult): class InlineQueryResultGame(InlineQueryResult):
"""Represents a Game. """Represents a :class:`telegram.Game`.
Attributes: Attributes:
type (:obj:`str`): 'game'. type (:obj:`str`): 'game'.

10
telegram/inline/inlinequeryresultgif.py
View file

@ -35,7 +35,8 @@ class InlineQueryResultGif(InlineQueryResult):
gif_width (:obj:`int`): Optional. Width of the GIF. gif_width (:obj:`int`): Optional. Width of the GIF.
gif_height (:obj:`int`): Optional. Height 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.
thumb_url (:obj:`str`): URL of the static thumbnail for the result (jpeg or gif). 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. thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail.
title (:obj:`str`): Optional. Title for the result. title (:obj:`str`): Optional. Title for the result.
caption (:obj:`str`): Optional. Caption of the GIF file to be sent, 0-1024 characters caption (:obj:`str`): Optional. Caption of the GIF file to be sent, 0-1024 characters
@ -54,9 +55,10 @@ class InlineQueryResultGif(InlineQueryResult):
gif_width (:obj:`int`, optional): Width of the GIF. gif_width (:obj:`int`, optional): Width of the GIF.
gif_height (:obj:`int`, optional): Height 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
thumb_url (:obj:`str`): URL of the static thumbnail for the result (jpeg or gif). thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for
thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail, must be one of the result.
“image/jpeg”, “image/gif”, or “video/mp4”. Defaults to “image/jpeg”. 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'``.
title (:obj:`str`, optional): Title for the result. title (:obj:`str`, optional): Title for the result.
caption (:obj:`str`, optional): Caption of the GIF file to be sent, 0-1024 characters caption (:obj:`str`, optional): Caption of the GIF file to be sent, 0-1024 characters
after entities parsing. after entities parsing.

5
telegram/inline/inlinequeryresultmpeg4gif.py
View file

@ -36,7 +36,8 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
mpeg4_width (:obj:`int`): Optional. Video width. mpeg4_width (:obj:`int`): Optional. Video width.
mpeg4_height (:obj:`int`): Optional. Video height. mpeg4_height (:obj:`int`): Optional. Video height.
mpeg4_duration (:obj:`int`): Optional. Video duration. mpeg4_duration (:obj:`int`): Optional. Video duration.
thumb_url (:obj:`str`): URL of the static thumbnail (jpeg or gif) for the result. 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. thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail.
title (:obj:`str`): Optional. Title for the result. title (:obj:`str`): Optional. Title for the result.
caption (:obj:`str`): Optional. Caption of the MPEG-4 file to be sent, 0-1024 characters caption (:obj:`str`): Optional. Caption of the MPEG-4 file to be sent, 0-1024 characters
@ -57,7 +58,7 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
mpeg4_duration (:obj:`int`, optional): Video duration. mpeg4_duration (:obj:`int`, optional): Video duration.
thumb_url (:obj:`str`): URL of the static thumbnail (jpeg or gif) for the result. 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 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”. ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``.
title (:obj:`str`, optional): Title for the result. title (:obj:`str`, optional): Title for the result.
caption (:obj:`str`, optional): Caption of the MPEG-4 file to be sent, 0-1024 characters caption (:obj:`str`, optional): Caption of the MPEG-4 file to be sent, 0-1024 characters
after entities parsing. after entities parsing.

3
telegram/inline/inputlocationmessagecontent.py
View file

@ -28,7 +28,8 @@ class InputLocationMessageContent(InputMessageContent):
Attributes: Attributes:
latitude (:obj:`float`): Latitude of the location in degrees. latitude (:obj:`float`): Latitude of the location in degrees.
longitude (:obj:`float`): Longitude of the location in degrees. longitude (:obj:`float`): Longitude of the location in degrees.
live_period (:obj:`int`): Optional. Period in seconds for which the location can be
updated, should be between 60 and 86400.
Args: Args:
latitude (:obj:`float`): Latitude of the location in degrees. latitude (:obj:`float`): Latitude of the location in degrees.
longitude (:obj:`float`): Longitude of the location in degrees. longitude (:obj:`float`): Longitude of the location in degrees.

6
telegram/inline/inputtextmessagecontent.py
View file

@ -30,7 +30,8 @@ class InputTextMessageContent(InputMessageContent):
message_text (:obj:`str`): Text of the message to be sent, 1-4096 characters after entities message_text (:obj:`str`): Text of the message to be sent, 1-4096 characters after entities
parsing. parsing.
parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show 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. bold, italic, fixed-width text or inline URLs in your bot's message. See the constants
in :class:`telegram.ParseMode` for the available modes.
disable_web_page_preview (:obj:`bool`): Optional. Disables link previews for links in the disable_web_page_preview (:obj:`bool`): Optional. Disables link previews for links in the
sent message. sent message.
@ -38,7 +39,8 @@ class InputTextMessageContent(InputMessageContent):
message_text (:obj:`str`): Text of the message to be sent, 1-4096 characters after entities message_text (:obj:`str`): Text of the message to be sent, 1-4096 characters after entities
parsing. Also found as :attr:`telegram.constants.MAX_MESSAGE_LENGTH`. parsing. Also found as :attr:`telegram.constants.MAX_MESSAGE_LENGTH`.
parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show 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. bold, italic, fixed-width text or inline URLs in your bot's message. See the constants
in :class:`telegram.ParseMode` for the available modes.
disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in the disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in the
sent message. sent message.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.

12
telegram/keyboardbutton.py
View file

@ -31,17 +31,17 @@ class KeyboardButton(TelegramObject):
Attributes: Attributes:
text (:obj:`str`): Text of the button. text (:obj:`str`): Text of the button.
request_contact (:obj:`bool`): Optional. If the user's phone number will be sent. request_contact (:obj:`bool`): Optional. The user's phone number will be sent.
request_location (:obj:`bool`): Optional. If the user's current location will be sent. request_location (:obj:`bool`): Optional. The user's current location will be sent.
request_poll (:class:`KeyboardButtonPollType`): Optional. If the user should create a poll. request_poll (:class:`KeyboardButtonPollType`): Optional. If the user should create a poll.
Args: Args:
text (:obj:`str`): Text of the button. If none of the optional fields are used, it will be text (:obj:`str`): Text of the button. If none of the optional fields are used, it will be
sent to the bot as a message when the button is pressed. sent to the bot as a message when the button is pressed.
request_contact (:obj:`bool`, optional): If True, the user's phone number will be sent as request_contact (:obj:`bool`, optional): If :obj:`True`, the user's phone number will be
a contact when the button is pressed. Available in private chats only. sent as a contact when the button is pressed. Available in private chats only.
request_location (:obj:`bool`, optional): If True, the user's current location will be sent request_location (:obj:`bool`, optional): If :obj:`True`, the user's current location will
when the button is pressed. Available in private chats only. be sent when the button is pressed. Available in private chats only.
request_poll (:class:`KeyboardButtonPollType`, optional): If specified, the user will be request_poll (:class:`KeyboardButtonPollType`, optional): If specified, the user will be
asked to create a poll and send it to the bot when the button is pressed. Available in asked to create a poll and send it to the bot when the button is pressed. Available in
private chats only. private chats only.

28
telegram/loginurl.py
View file

@ -34,23 +34,33 @@ class LoginUrl(TelegramObject):
forward_text (:obj:`str`): Optional. New text of the button in forwarded messages. forward_text (:obj:`str`): Optional. New text of the button in forwarded messages.
bot_username (:obj:`str`): Optional. Username of a bot, which will be used for user bot_username (:obj:`str`): Optional. Username of a bot, which will be used for user
authorization. authorization.
request_write_access (:obj:`bool`): Optional. Pass True to request the permission for your request_write_access (:obj:`bool`): Optional. Pass :obj:`True` to request the permission
bot to send messages to the user. for your bot to send messages to the user.
Args: Args:
url (:obj:`str`): An HTTP URL to be opened with user authorization data added to the query url (:obj:`str`): An HTTP URL to be opened with user authorization data added to the query
string when the button is pressed. If the user refuses to provide authorization data, string when the button is pressed. If the user refuses to provide authorization data,
the original URL without information about the user will be opened. The data added is the original URL without information about the user will be opened. The data added is
the same as described in Receiving authorization data. the same as described in
NOTE: You must always check the hash of the received data to verify the authentication `Receiving authorization data
and the integrity of the data as described in Checking authorization. <https://core.telegram.org/widgets/login#receiving-authorization-data>`_
forward_text (:obj:`str`, optional): New text of the button in forwarded messages. forward_text (:obj:`str`, optional): New text of the button in forwarded messages.
bot_username (:obj:`str`, optional): Username of a bot, which will be used for user bot_username (:obj:`str`, optional): Username of a bot, which will be used for user
authorization. See Setting up a bot for more details. If not specified, the current authorization. See
`Setting up a bot <https://core.telegram.org/widgets/login#setting-up-a-bot>`_
for more details. If not specified, the current
bot's username will be assumed. The url's domain must be the same as the domain linked bot's username will be assumed. The url's domain must be the same as the domain linked
with the bot. See Linking your domain to the bot for more details. with the bot. See
request_write_access (:obj:`bool`, optional): Pass True to request the permission for your `Linking your domain to the bot
bot to send messages to the user. <https://core.telegram.org/widgets/login#linking-your-domain-to-the-bot>`_
for more details.
request_write_access (:obj:`bool`, optional): Pass :obj:`True` to request the permission
for your bot to send messages to the user.
Note:
You must always check the hash of the received data to verify the authentication
and the integrity of the data as described in
`Checking authorization <https://core.telegram.org/widgets/login#checking-authorization>`_
""" """
def __init__(self, url, forward_text=None, bot_username=None, request_write_access=None): def __init__(self, url, forward_text=None, bot_username=None, request_write_access=None):

158
telegram/message.py
View file

@ -116,7 +116,7 @@ class Message(TelegramObject):
Args: Args:
message_id (:obj:`int`): Unique message identifier inside this chat. message_id (:obj:`int`): Unique message identifier inside this chat.
from_user (:class:`telegram.User`, optional): Sender, can be empty for messages sent from_user (:class:`telegram.User`, optional): Sender, empty for messages sent
to channels. to channels.
date (:class:`datetime.datetime`): Date the message was sent in Unix time. Converted to date (:class:`datetime.datetime`): Date the message was sent in Unix time. Converted to
:class:`datetime.datetime`. :class:`datetime.datetime`.
@ -167,17 +167,19 @@ class Message(TelegramObject):
new_chat_members (List[:class:`telegram.User`], optional): New members that were added to new_chat_members (List[:class:`telegram.User`], optional): New members that were added to
the group or supergroup and information about them (the bot itself may be one of these the group or supergroup and information about them (the bot itself may be one of these
members). members).
caption (:obj:`str`, optional): Caption for the document, photo or video, 0-1024 caption (:obj:`str`, optional): Caption for the animation, audio, document, photo, video
characters. or voice, 0-1024 characters.
contact (:class:`telegram.Contact`, optional): Message is a shared contact, information contact (:class:`telegram.Contact`, optional): Message is a shared contact, information
about the contact. about the contact.
location (:class:`telegram.Location`, optional): Message is a shared location, information location (:class:`telegram.Location`, optional): Message is a shared location, information
about the location. about the location.
venue (:class:`telegram.Venue`, optional): Message is a venue, information about the venue. venue (:class:`telegram.Venue`, optional): Message is a venue, information about the venue.
For backward compatibility, when this field is set, the location field will also be
set.
left_chat_member (:class:`telegram.User`, optional): A member was removed from the group, left_chat_member (:class:`telegram.User`, optional): A member was removed from the group,
information about them (this member may be the bot itself). information about them (this member may be the bot itself).
new_chat_title (:obj:`str`, optional): A chat title was changed to this value. new_chat_title (:obj:`str`, optional): A chat title was changed to this value.
new_chat_photo (List[:class:`telegram.PhotoSize`], optional): A chat photo was change to new_chat_photo (List[:class:`telegram.PhotoSize`], optional): A chat photo was changed to
this value. this value.
delete_chat_photo (:obj:`bool`, optional): Service message: The chat photo was deleted. delete_chat_photo (:obj:`bool`, optional): Service message: The chat photo was deleted.
group_chat_created (:obj:`bool`, optional): Service message: The group has been created. group_chat_created (:obj:`bool`, optional): Service message: The group has been created.
@ -209,8 +211,8 @@ class Message(TelegramObject):
message about a successful payment, information about the payment. message about a successful payment, information about the payment.
connected_website (:obj:`str`, optional): The domain name of the website on which the user connected_website (:obj:`str`, optional): The domain name of the website on which the user
has logged in. has logged in.
forward_signature (:obj:`str`, optional): Signature of the post author for messages forward_signature (:obj:`str`, optional): For messages forwarded from channels, signature
forwarded from channels. of the post author if present.
author_signature (:obj:`str`, optional): Signature of the post author for messages author_signature (:obj:`str`, optional): Signature of the post author for messages
in channels. in channels.
passport_data (:class:`telegram.PassportData`, optional): Telegram Passport data. passport_data (:class:`telegram.PassportData`, optional): Telegram Passport data.
@ -219,7 +221,7 @@ class Message(TelegramObject):
dice (:class:`telegram.Dice`, optional): Message is a dice with random value from 1 to 6. dice (:class:`telegram.Dice`, optional): Message is a dice with random value from 1 to 6.
via_bot (:class:`telegram.User`, optional): Message was sent through an inline bot. via_bot (:class:`telegram.User`, optional): Message was sent through an inline bot.
reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
to the message. login_url buttons are represented as ordinary url buttons. to the message. ``login_url`` buttons are represented as ordinary url buttons.
default_quote (:obj:`bool`, optional): Default setting for the `quote` parameter of the default_quote (:obj:`bool`, optional): Default setting for the `quote` parameter of the
:attr:`reply_text` and friends. :attr:`reply_text` and friends.
@ -435,7 +437,7 @@ class Message(TelegramObject):
or :class:`telegram.Video` or :class:`telegram.Video`
or :class:`telegram.VideoNote` or :class:`telegram.VideoNote`
or :class:`telegram.Voice`: The attachment that this message was sent with. May be or :class:`telegram.Voice`: The attachment that this message was sent with. May be
``None`` if no attachment was sent. :obj:`None` if no attachment was sent.
""" """
if self._effective_attachment is not _UNDEFINED: if self._effective_attachment is not _UNDEFINED:
@ -502,9 +504,9 @@ class Message(TelegramObject):
bot.send_message(update.message.chat_id, *args, **kwargs) bot.send_message(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the message is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the message is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
parameter will be ignored. Default: ``True`` in group chats and ``False`` in parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in
private chats. private chats.
Returns: Returns:
@ -520,12 +522,16 @@ class Message(TelegramObject):
bot.send_message(update.message.chat_id, parse_mode=ParseMode.MARKDOWN, *args, bot.send_message(update.message.chat_id, parse_mode=ParseMode.MARKDOWN, *args,
**kwargs) **kwargs)
Sends a message with markdown version 1 formatting. Sends a message with Markdown version 1 formatting.
Note:
:attr:`telegram.ParseMode.MARKDOWN` is a legacy mode, retained by Telegram for
backward compatibility. You should use :meth:`reply_markdown_v2` instead.
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the message is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the message is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
parameter will be ignored. Default: ``True`` in group chats and ``False`` in parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in
private chats. private chats.
Returns: Returns:
@ -547,9 +553,9 @@ class Message(TelegramObject):
Sends a message with markdown version 2 formatting. Sends a message with markdown version 2 formatting.
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the message is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the message is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
parameter will be ignored. Default: ``True`` in group chats and ``False`` in parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in
private chats. private chats.
Returns: Returns:
@ -570,9 +576,9 @@ class Message(TelegramObject):
Sends a message with HTML formatting. Sends a message with HTML formatting.
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the message is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the message is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
parameter will be ignored. Default: ``True`` in group chats and ``False`` in parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in
private chats. private chats.
Returns: Returns:
@ -591,10 +597,10 @@ class Message(TelegramObject):
bot.send_media_group(update.message.chat_id, *args, **kwargs) bot.send_media_group(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the media group is sent as an quote (:obj:`bool`, optional): If set to :obj:`True`, the media group is sent as an
actual reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, actual reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
this parameter will be ignored. Default: ``True`` in group chats and ``False`` in this parameter will be ignored. Default: :obj:`True` in group chats and
private chats. :obj:`False` in private chats.
Returns: Returns:
List[:class:`telegram.Message`]: An array of the sent Messages. List[:class:`telegram.Message`]: An array of the sent Messages.
@ -611,9 +617,10 @@ class Message(TelegramObject):
bot.send_photo(update.message.chat_id, *args, **kwargs) bot.send_photo(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an actual reply quote (:obj:`bool`, optional): If set to :obj:`True`, the photo is sent as an actual
to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
will be ignored. Default: ``True`` in group chats and ``False`` in private chats. this parameter will be ignored. Default: :obj:`True` in group chats and
:obj:`False` in private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -628,9 +635,10 @@ class Message(TelegramObject):
bot.send_audio(update.message.chat_id, *args, **kwargs) bot.send_audio(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the audio is sent as an actual reply quote (:obj:`bool`, optional): If set to :obj:`True`, the audio is sent as an actual
to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
will be ignored. Default: ``True`` in group chats and ``False`` in private chats. this parameter will be ignored. Default: :obj:`True` in group chats and
:obj:`False` in private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -645,9 +653,9 @@ class Message(TelegramObject):
bot.send_document(update.message.chat_id, *args, **kwargs) bot.send_document(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the document is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the document is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
parameter will be ignored. Default: ``True`` in group chats and ``False`` in parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in
private chats. private chats.
Returns: Returns:
@ -663,10 +671,10 @@ class Message(TelegramObject):
bot.send_animation(update.message.chat_id, *args, **kwargs) bot.send_animation(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the animation is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the animation is sent as an
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this actual reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
parameter will be ignored. Default: ``True`` in group chats and ``False`` in this parameter will be ignored. Default: :obj:`True` in group chats and
private chats. :obj:`False` in private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -681,9 +689,9 @@ class Message(TelegramObject):
bot.send_sticker(update.message.chat_id, *args, **kwargs) bot.send_sticker(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the sticker is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the sticker is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
parameter will be ignored. Default: ``True`` in group chats and ``False`` in parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in
private chats. private chats.
Returns: Returns:
@ -699,9 +707,9 @@ class Message(TelegramObject):
bot.send_video(update.message.chat_id, *args, **kwargs) bot.send_video(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the video is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the video is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
parameter will be ignored. Default: ``True`` in group chats and ``False`` in parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in
private chats. private chats.
Returns: Returns:
@ -717,10 +725,10 @@ class Message(TelegramObject):
bot.send_video_note(update.message.chat_id, *args, **kwargs) bot.send_video_note(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the video note is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the video note is sent as an
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this actual reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
parameter will be ignored. Default: ``True`` in group chats and ``False`` in this parameter will be ignored. Default: :obj:`True` in group chats and
private chats. :obj:`False` in private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -735,10 +743,10 @@ class Message(TelegramObject):
bot.send_voice(update.message.chat_id, *args, **kwargs) bot.send_voice(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the voice note is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the voice note is sent as an
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this actual reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
parameter will be ignored. Default: ``True`` in group chats and ``False`` in this parameter will be ignored. Default: :obj:`True` in group chats and
private chats. :obj:`False` in private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -753,9 +761,9 @@ class Message(TelegramObject):
bot.send_location(update.message.chat_id, *args, **kwargs) bot.send_location(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the location is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the location is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
parameter will be ignored. Default: ``True`` in group chats and ``False`` in parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in
private chats. private chats.
Returns: Returns:
@ -771,9 +779,9 @@ class Message(TelegramObject):
bot.send_venue(update.message.chat_id, *args, **kwargs) bot.send_venue(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the venue is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the venue is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
parameter will be ignored. Default: ``True`` in group chats and ``False`` in parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in
private chats. private chats.
Returns: Returns:
@ -789,9 +797,9 @@ class Message(TelegramObject):
bot.send_contact(update.message.chat_id, *args, **kwargs) bot.send_contact(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the contact is sent as an actual quote (:obj:`bool`, optional): If set to :obj:`True`, the contact is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
parameter will be ignored. Default: ``True`` in group chats and ``False`` in parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False` in
private chats. private chats.
Returns: Returns:
@ -807,9 +815,10 @@ class Message(TelegramObject):
bot.send_poll(update.message.chat_id, *args, **kwargs) bot.send_poll(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the poll is sent as an actual reply quote (:obj:`bool`, optional): If set to :obj:`True`, the poll is sent as an actual
to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
will be ignored. Default: ``True`` in group chats and ``False`` in private chats. this parameter will be ignored. Default: :obj:`True` in group chats and
:obj:`False` in private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -824,9 +833,10 @@ class Message(TelegramObject):
bot.send_dice(update.message.chat_id, *args, **kwargs) bot.send_dice(update.message.chat_id, *args, **kwargs)
Keyword Args: Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the dice is sent as an actual reply quote (:obj:`bool`, optional): If set to :obj:`True`, the dice is sent as an actual
to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
will be ignored. Default: ``True`` in group chats and ``False`` in private chats. parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False`
in private chats.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -950,7 +960,7 @@ class Message(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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
return self.bot.edit_message_live_location( return self.bot.edit_message_live_location(
chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs) chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)
@ -970,7 +980,7 @@ class Message(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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
return self.bot.stop_message_live_location( return self.bot.stop_message_live_location(
chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs) chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)
@ -990,7 +1000,7 @@ class Message(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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
return self.bot.set_game_score( return self.bot.set_game_score(
chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs) chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)
@ -1010,7 +1020,7 @@ class Message(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
edited Message is returned, otherwise ``True`` is returned. edited Message is returned, otherwise :obj:`True` is returned.
""" """
return self.bot.get_game_high_scores( return self.bot.get_game_high_scores(
chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs) chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)
@ -1024,7 +1034,7 @@ class Message(TelegramObject):
**kwargs) **kwargs)
Returns: Returns:
:obj:`bool`: On success, ``True`` is returned. :obj:`bool`: On success, :obj:`True` is returned.
""" """
return self.bot.delete_message( return self.bot.delete_message(
@ -1039,8 +1049,8 @@ class Message(TelegramObject):
**kwargs) **kwargs)
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.
""" """
return self.bot.stop_poll( return self.bot.stop_poll(
@ -1074,7 +1084,7 @@ class Message(TelegramObject):
be an entity that belongs to this message. be an entity that belongs to this message.
Returns: Returns:
:obj:`str`: The text of the given entity :obj:`str`: The text of the given entity.
""" """
# Is it a narrow build, if so we don't need to convert # Is it a narrow build, if so we don't need to convert
@ -1099,7 +1109,7 @@ class Message(TelegramObject):
be an entity that belongs to this message. be an entity that belongs to this message.
Returns: Returns:
:obj:`str`: The text of the given entity :obj:`str`: The text of the given entity.
""" """
# Is it a narrow build, if so we don't need to convert # Is it a narrow build, if so we don't need to convert
@ -1293,7 +1303,7 @@ class Message(TelegramObject):
HTML in the same way the original message was formatted. HTML in the same way the original message was formatted.
Returns: Returns:
:obj:`str`: Message caption with captionentities formatted as HTML. :obj:`str`: Message caption with caption entities formatted as HTML.
""" """
return self._parse_html(self.caption, self.parse_caption_entities(), urled=False) return self._parse_html(self.caption, self.parse_caption_entities(), urled=False)
@ -1440,6 +1450,10 @@ class Message(TelegramObject):
Use this if you want to retrieve the message text with the entities formatted as Markdown Use this if you want to retrieve the message text with the entities formatted as Markdown
in the same way the original message was formatted. in the same way the original message was formatted.
Note:
:attr:`telegram.ParseMode.MARKDOWN` is is a legacy mode, retained by Telegram for
backward compatibility. You should use :meth:`text_markdown_v2` instead.
Returns: Returns:
:obj:`str`: Message text with entities formatted as Markdown. :obj:`str`: Message text with entities formatted as Markdown.
@ -1468,6 +1482,10 @@ class Message(TelegramObject):
Use this if you want to retrieve the message text with the entities formatted as Markdown. Use this if you want to retrieve the message text with the entities formatted as Markdown.
This also formats :attr:`telegram.MessageEntity.URL` as a hyperlink. This also formats :attr:`telegram.MessageEntity.URL` as a hyperlink.
Note:
:attr:`telegram.ParseMode.MARKDOWN` is is a legacy mode, retained by Telegram for
backward compatibility. You should use :meth:`text_markdown_v2_urled` instead.
Returns: Returns:
:obj:`str`: Message text with entities formatted as Markdown. :obj:`str`: Message text with entities formatted as Markdown.
@ -1496,6 +1514,10 @@ class Message(TelegramObject):
Use this if you want to retrieve the message caption with the caption entities formatted as Use this if you want to retrieve the message caption with the caption entities formatted as
Markdown in the same way the original message was formatted. Markdown in the same way the original message was formatted.
Note:
:attr:`telegram.ParseMode.MARKDOWN` is is a legacy mode, retained by Telegram for
backward compatibility. You should use :meth:`caption_markdown_v2` instead.
Returns: Returns:
:obj:`str`: Message caption with caption entities formatted as Markdown. :obj:`str`: Message caption with caption entities formatted as Markdown.
@ -1525,6 +1547,10 @@ class Message(TelegramObject):
Use this if you want to retrieve the message caption with the caption entities formatted as Use this if you want to retrieve the message caption with the caption entities formatted as
Markdown. This also formats :attr:`telegram.MessageEntity.URL` as a hyperlink. Markdown. This also formats :attr:`telegram.MessageEntity.URL` as a hyperlink.
Note:
:attr:`telegram.ParseMode.MARKDOWN` is is a legacy mode, retained by Telegram for
backward compatibility. You should use :meth:`caption_markdown_v2_urled` instead.
Returns: Returns:
:obj:`str`: Message caption with caption entities formatted as Markdown. :obj:`str`: Message caption with caption entities formatted as Markdown.

13
telegram/messageentity.py
View file

@ -32,22 +32,21 @@ class MessageEntity(TelegramObject):
length (:obj:`int`): Length of the entity in UTF-16 code units. length (:obj:`int`): Length of the entity in UTF-16 code units.
url (:obj:`str`): Optional. Url that will be opened after user taps on the text. url (:obj:`str`): Optional. Url that will be opened after user taps on the text.
user (:class:`telegram.User`): Optional. The mentioned user. user (:class:`telegram.User`): Optional. The mentioned user.
language (:obj:`str`): Optional. Programming language of the entity language (:obj:`str`): Optional. Programming language of the entity text.
text
Args: Args:
type (:obj:`str`): Type of the entity. Can be mention (@username), hashtag, bot_command, type (:obj:`str`): Type of the entity. Can be mention (@username), hashtag, bot_command,
url, email, bold (bold text), italic (italic text), code (monowidth string), pre url, email, phone_number, bold (bold text), italic (italic text), strikethrough,
(monowidth block), text_link (for clickable text URLs), text_mention (for users code (monowidth string), pre (monowidth block), text_link (for clickable text URLs),
without usernames). text_mention (for users without usernames).
offset (:obj:`int`): Offset in UTF-16 code units to the start of the entity. offset (:obj:`int`): Offset in UTF-16 code units to the start of the entity.
length (:obj:`int`): Length of the entity in UTF-16 code units. length (:obj:`int`): Length of the entity in UTF-16 code units.
url (:obj:`str`, optional): For :attr:`TEXT_LINK` only, url that will be opened after url (:obj:`str`, optional): For :attr:`TEXT_LINK` only, url that will be opened after
usertaps on the text. user taps on the text.
user (:class:`telegram.User`, optional): For :attr:`TEXT_MENTION` only, the mentioned user (:class:`telegram.User`, optional): For :attr:`TEXT_MENTION` only, the mentioned
user. user.
language (:obj:`str`, optional): For :attr:`PRE` only, the programming language of language (:obj:`str`, optional): For :attr:`PRE` only, the programming language of
the entity text the entity text.
""" """

7
telegram/parsemode.py
View file

@ -24,7 +24,12 @@ class ParseMode:
"""This object represents a Telegram Message Parse Modes.""" """This object represents a Telegram Message Parse Modes."""
MARKDOWN = 'Markdown' MARKDOWN = 'Markdown'
""":obj:`str`: 'Markdown'""" """:obj:`str`: 'Markdown'
Note:
:attr:`MARKDOWN` is a legacy mode, retained by Telegram for backward compatibility.
You should use :attr:`MARKDOWN_V2` instead.
"""
MARKDOWN_V2 = 'MarkdownV2' MARKDOWN_V2 = 'MarkdownV2'
""":obj:`str`: 'MarkdownV2'""" """:obj:`str`: 'MarkdownV2'"""
HTML = 'HTML' HTML = 'HTML'

2
telegram/passport/passportelementerrors.py
View file

@ -27,7 +27,7 @@ class PassportElementError(TelegramObject):
Attributes: Attributes:
source (:obj:`str`): Error source. source (:obj:`str`): Error source.
type (:obj:`str`): The section of the user's Telegram Passport which has the error. type (:obj:`str`): The section of the user's Telegram Passport which has the error.
message (:obj:`str`): Error message message (:obj:`str`): Error message.
Args: Args:
source (:obj:`str`): Error source. source (:obj:`str`): Error source.

7
telegram/passport/passportfile.py
View file

@ -27,7 +27,7 @@ class PassportFile(TelegramObject):
files are in JPEG format when decrypted and don't exceed 10MB. files are in JPEG format when decrypted and don't exceed 10MB.
Attributes: Attributes:
file_id (:obj:`str`): Unique identifier for this file. file_id (:obj:`str`): Identifier for this file.
file_unique_id (:obj:`str`): Unique identifier for this file, which file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots. is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file. Can't be used to download or reuse the file.
@ -38,8 +38,9 @@ class PassportFile(TelegramObject):
Args: Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file. or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and file_unique_id (:obj:`str`): Unique identifier for this file, which
for different bots file identifier. 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.
file_date (:obj:`int`): Unix time when the file was uploaded. file_date (:obj:`int`): Unix time when the file was uploaded.
bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.

6
telegram/payment/invoice.py
View file

@ -38,7 +38,11 @@ class Invoice(TelegramObject):
generate this invoice. generate this invoice.
currency (:obj:`str`): Three-letter ISO 4217 currency code. currency (:obj:`str`): Three-letter ISO 4217 currency code.
total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not
float/double). For example, for a price of US$ 1.45 pass amount = 145. float/double). For example, for a price of US$ 1.45 pass ``amount = 145``. See the
:obj:`exp` parameter in
`currencies.json <https://core.telegram.org/bots/payments/currencies.json>`_,
it shows the number of digits past the decimal point for each currency
(2 for the majority of currencies).
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
""" """

10
telegram/payment/labeledprice.py
View file

@ -29,11 +29,13 @@ class LabeledPrice(TelegramObject):
amount (:obj:`int`): Price of the product in the smallest units of the currency. amount (:obj:`int`): Price of the product in the smallest units of the currency.
Args: Args:
label (:obj:`str`): Portion label label (:obj:`str`): Portion label.
amount (:obj:`int`): Price of the product in the smallest units of the currency (integer, amount (:obj:`int`): Price of the product in the smallest units of the currency (integer,
not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp not float/double). For example, for a price of US$ 1.45 pass ``amount = 145``.
parameter in currencies.json, it shows the number of digits past the decimal point for See the :obj:`exp` parameter in
each currency (2 for the majority of currencies). `currencies.json <https://core.telegram.org/bots/payments/currencies.json>`_,
it shows the number of digits past the decimal point for each currency
(2 for the majority of currencies).
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
""" """

25
telegram/payment/precheckoutquery.py
View file

@ -41,11 +41,13 @@ class PreCheckoutQuery(TelegramObject):
Args: Args:
id (:obj:`str`): Unique query identifier. id (:obj:`str`): Unique query identifier.
from_user (:class:`telegram.User`): User who sent the query. from_user (:class:`telegram.User`): User who sent the query.
currency (:obj:`str`): Three-letter ISO 4217 currency code currency (:obj:`str`): Three-letter ISO 4217 currency code.
total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not
float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp float/double). For example, for a price of US$ 1.45 pass ``amount = 145``.
parameter in currencies.json, it shows the number of digits past the decimal point for See the :obj:`exp` parameter in
each currency (2 for the majority of currencies). `currencies.json <https://core.telegram.org/bots/payments/currencies.json>`_,
it shows the number of digits past the decimal point for each currency
(2 for the majority of currencies).
invoice_payload (:obj:`str`): Bot specified invoice payload. invoice_payload (:obj:`str`): Bot specified invoice payload.
shipping_option_id (:obj:`str`, optional): Identifier of the shipping option chosen by the shipping_option_id (:obj:`str`, optional): Identifier of the shipping option chosen by the
user. user.
@ -95,13 +97,14 @@ class PreCheckoutQuery(TelegramObject):
bot.answer_pre_checkout_query(update.pre_checkout_query.id, *args, **kwargs) bot.answer_pre_checkout_query(update.pre_checkout_query.id, *args, **kwargs)
Args: Args:
ok (:obj:`bool`): Specify True if everything is alright (goods are available, etc.) and ok (:obj:`bool`): Specify :obj:`True` if everything is alright
the bot is ready to proceed with the order. Use False if there are any problems. (goods are available, etc.) and the bot is ready to proceed with the order.
error_message (:obj:`str`, optional): Required if ok is False. Error message in human Use :obj:`False` if there are any problems.
readable form that explains the reason for failure to proceed with the checkout error_message (:obj:`str`, optional): Required if ok is :obj:`False`. Error message in
(e.g. "Sorry, somebody just bought the last of our amazing black T-shirts while you human readable form that explains the reason for failure to proceed with the
were busy filling out your payment details. Please choose a different color or checkout (e.g. "Sorry, somebody just bought the last of our amazing black T-shirts
garment!"). Telegram will display this message to the user. while you were busy filling out your payment details. Please choose a different
color or garment!"). Telegram will display this message to the user.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
""" """

12
telegram/payment/shippingquery.py
View file

@ -72,13 +72,13 @@ class ShippingQuery(TelegramObject):
bot.answer_shipping_query(update.shipping_query.id, *args, **kwargs) bot.answer_shipping_query(update.shipping_query.id, *args, **kwargs)
Args: Args:
ok (:obj:`bool`): Specify True if delivery to the specified address is possible and ok (:obj:`bool`): Specify :obj:`True` if delivery to the specified address is
False if there are any problems (for example, if delivery to the specified address possible and :obj:`False` if there are any problems
is not possible). (for example, if delivery to the specified address is not possible).
shipping_options (List[:class:`telegram.ShippingOption`], optional): Required if ok is shipping_options (List[:class:`telegram.ShippingOption`], optional): Required if ok is
True. A JSON-serialized array of available shipping options. :obj:`True`. A JSON-serialized array of available shipping options.
error_message (:obj:`str`, optional): Required if ok is False. Error message in human error_message (:obj:`str`, optional): Required if ok is :obj:`False`. Error message in
readable form that explains why it is impossible to complete the order (e.g. human readable form that explains why it is impossible to complete the order (e.g.
"Sorry, delivery to your desired address is unavailable'). Telegram will display "Sorry, delivery to your desired address is unavailable'). Telegram will display
this message to the user. this message to the user.

10
telegram/payment/successfulpayment.py
View file

@ -37,13 +37,15 @@ class SuccessfulPayment(TelegramObject):
Args: Args:
currency (:obj:`str`): Three-letter ISO 4217 currency code. currency (:obj:`str`): Three-letter ISO 4217 currency code.
total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not total_amount (:obj:`int`): Total price in the smallest units of the currency (integer, not
float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp float/double). For example, for a price of US$ 1.45 pass ``amount = 145``.
parameter in currencies.json, it shows the number of digits past the decimal point for See the :obj:`exp` parameter in
each currency (2 for the majority of currencies). `currencies.json <https://core.telegram.org/bots/payments/currencies.json>`_,
it shows the number of digits past the decimal point for each currency
(2 for the majority of currencies).
invoice_payload (:obj:`str`): Bot specified invoice payload. invoice_payload (:obj:`str`): Bot specified invoice payload.
shipping_option_id (:obj:`str`, optional): Identifier of the shipping option chosen by the shipping_option_id (:obj:`str`, optional): Identifier of the shipping option chosen by the
user. user.
order_info (:class:`telegram.OrderInfo`, optional): Order info provided by the user order_info (:class:`telegram.OrderInfo`, optional): Order info provided by the user.
telegram_payment_charge_id (:obj:`str`): Telegram payment identifier. telegram_payment_charge_id (:obj:`str`): Telegram payment identifier.
provider_payment_charge_id (:obj:`str`): Provider payment identifier. provider_payment_charge_id (:obj:`str`): Provider payment identifier.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.

12
telegram/poll.py
View file

@ -93,10 +93,10 @@ class Poll(TelegramObject):
question (:obj:`str`): Poll question, 1-255 characters. question (:obj:`str`): Poll question, 1-255 characters.
options (List[:class:`PollOption`]): List of poll options. options (List[:class:`PollOption`]): List of poll options.
total_voter_count (:obj:`int`): Total number of users that voted in the poll. total_voter_count (:obj:`int`): Total number of users that voted in the poll.
is_closed (:obj:`bool`): True, if the poll is closed. is_closed (:obj:`bool`): :obj:`True`, if the poll is closed.
is_anonymous (:obj:`bool`): True, if the poll is anonymous. is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous.
type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`. type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`.
allows_multiple_answers (:obj:`bool`): True, if the poll allows multiple answers. 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. 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 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. answer or taps on the lamp icon in a quiz-style poll.
@ -111,10 +111,10 @@ class Poll(TelegramObject):
id (:obj:`str`): Unique poll identifier. id (:obj:`str`): Unique poll identifier.
question (:obj:`str`): Poll question, 1-255 characters. question (:obj:`str`): Poll question, 1-255 characters.
options (List[:class:`PollOption`]): List of poll options. options (List[:class:`PollOption`]): List of poll options.
is_closed (:obj:`bool`): True, if the poll is closed. is_closed (:obj:`bool`): :obj:`True`, if the poll is closed.
is_anonymous (:obj:`bool`): True, if the poll is anonymous. is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous.
type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`. type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`.
allows_multiple_answers (:obj:`bool`): True, if the poll allows multiple answers. allows_multiple_answers (:obj:`bool`): :obj:`True`, if the poll allows multiple answers.
correct_option_id (:obj:`int`, optional): 0-based identifier of the correct answer option. correct_option_id (:obj:`int`, optional): 0-based identifier of the correct answer option.
Available only for polls in the quiz mode, which are closed, or was sent (not Available only for polls in the quiz mode, which are closed, or was sent (not
forwarded) by the bot or to the private chat with the bot. forwarded) by the bot or to the private chat with the bot.

66
telegram/replykeyboardmarkup.py
View file

@ -40,20 +40,20 @@ class ReplyKeyboardMarkup(ReplyMarkup):
each represented by an Array of :class:`telegram.KeyboardButton` objects. each represented by an Array of :class:`telegram.KeyboardButton` objects.
resize_keyboard (:obj:`bool`, optional): Requests clients to resize the keyboard vertically resize_keyboard (:obj:`bool`, optional): Requests clients to resize the keyboard vertically
for optimal fit (e.g., make the keyboard smaller if there are just two rows of for optimal fit (e.g., make the keyboard smaller if there are just two rows of
buttons). Defaults to false, in which case the custom keyboard is always of the same buttons). Defaults to :obj:`False`, in which case the custom keyboard is always of the
height as the app's standard keyboard. Defaults to ``False`` same height as the app's standard keyboard.
one_time_keyboard (:obj:`bool`, optional): Requests clients to hide the keyboard as soon as one_time_keyboard (:obj:`bool`, optional): Requests clients to hide the keyboard as soon as
it's been used. The keyboard will still be available, but clients will automatically it's been used. The keyboard will still be available, but clients will automatically
display the usual letter-keyboard in the chat - the user can press a special button in display the usual letter-keyboard in the chat - the user can press a special button in
the input field to see the custom keyboard again. Defaults to ``False``. the input field to see the custom keyboard again. Defaults to :obj:`False`.
selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard to selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard to
specific users only. Targets: specific users only. Targets:
1) users that are @mentioned in the text of the Message object 1) Users that are @mentioned in the text of the Message object.
2) if the bot's message is a reply (has reply_to_message_id), sender of the original 2) If the bot's message is a reply (has ``reply_to_message_id``), sender of the
message. original message.
Defaults to ``False``. Defaults to :obj:`False`.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
@ -97,28 +97,28 @@ class ReplyKeyboardMarkup(ReplyMarkup):
ReplyKeyboardMarkup([[button]], **kwargs) ReplyKeyboardMarkup([[button]], **kwargs)
Return an ReplyKeyboardMarkup from a single KeyboardButton Return a ReplyKeyboardMarkup from a single KeyboardButton.
Args: Args:
button (:class:`telegram.KeyboardButton` | :obj:`str`): The button to use in the markup button (:class:`telegram.KeyboardButton` | :obj:`str`): The button to use in
the markup.
resize_keyboard (:obj:`bool`, optional): Requests clients to resize the keyboard resize_keyboard (:obj:`bool`, optional): Requests clients to resize the keyboard
vertically for optimal fit (e.g., make the keyboard smaller if there are just two vertically for optimal fit (e.g., make the keyboard smaller if there are just two
rows of buttons). Defaults to false, in which case the custom keyboard is always of rows of buttons). Defaults to :obj:`False`, in which case the custom keyboard is
the same height as the app's standard keyboard. always of the same height as the app's standard keyboard.
Defaults to ``False``
one_time_keyboard (:obj:`bool`, optional): Requests clients to hide the keyboard as one_time_keyboard (:obj:`bool`, optional): Requests clients to hide the keyboard as
soon as it's been used. The keyboard will still be available, but clients will soon as it's been used. The keyboard will still be available, but clients will
automatically display the usual letter-keyboard in the chat - the user can press automatically display the usual letter-keyboard in the chat - the user can press
a special button in the input field to see the custom keyboard again. a special button in the input field to see the custom keyboard again.
Defaults to ``False``. Defaults to :obj:`False`.
selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard
to specific users only. Targets: to specific users only. Targets:
1) users that are @mentioned in the text of the Message object 1) Users that are @mentioned in the text of the Message object.
2) if the bot's message is a reply (has reply_to_message_id), sender of the 2) If the bot's message is a reply (has reply_to_message_id), sender of the
original message. original message.
Defaults to ``False``. Defaults to :obj:`False`.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
""" """
return cls([[button]], return cls([[button]],
@ -138,29 +138,28 @@ class ReplyKeyboardMarkup(ReplyMarkup):
ReplyKeyboardMarkup([button_row], **kwargs) ReplyKeyboardMarkup([button_row], **kwargs)
Return an ReplyKeyboardMarkup from a single row of KeyboardButtons Return a ReplyKeyboardMarkup from a single row of KeyboardButtons.
Args: Args:
button_row (List[:class:`telegram.KeyboardButton` | :obj:`str`]): The button to use in button_row (List[:class:`telegram.KeyboardButton` | :obj:`str`]): The button to use in
the markup the markup.
resize_keyboard (:obj:`bool`, optional): Requests clients to resize the keyboard resize_keyboard (:obj:`bool`, optional): Requests clients to resize the keyboard
vertically for optimal fit (e.g., make the keyboard smaller if there are just two vertically for optimal fit (e.g., make the keyboard smaller if there are just two
rows of buttons). Defaults to false, in which case the custom keyboard is always of rows of buttons). Defaults to :obj:`False`, in which case the custom keyboard is
the same height as the app's standard keyboard. always of the same height as the app's standard keyboard.
Defaults to ``False``
one_time_keyboard (:obj:`bool`, optional): Requests clients to hide the keyboard as one_time_keyboard (:obj:`bool`, optional): Requests clients to hide the keyboard as
soon as it's been used. The keyboard will still be available, but clients will soon as it's been used. The keyboard will still be available, but clients will
automatically display the usual letter-keyboard in the chat - the user can press automatically display the usual letter-keyboard in the chat - the user can press
a special button in the input field to see the custom keyboard again. a special button in the input field to see the custom keyboard again.
Defaults to ``False``. Defaults to :obj:`False`.
selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard
to specific users only. Targets: to specific users only. Targets:
1) users that are @mentioned in the text of the Message object 1) Users that are @mentioned in the text of the Message object.
2) if the bot's message is a reply (has reply_to_message_id), sender of the 2) If the bot's message is a reply (has reply_to_message_id), sender of the
original message. original message.
Defaults to ``False``. Defaults to :obj:`False`.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
""" """
@ -181,29 +180,28 @@ class ReplyKeyboardMarkup(ReplyMarkup):
ReplyKeyboardMarkup([[button] for button in button_column], **kwargs) ReplyKeyboardMarkup([[button] for button in button_column], **kwargs)
Return an ReplyKeyboardMarkup from a single column of KeyboardButtons Return a ReplyKeyboardMarkup from a single column of KeyboardButtons.
Args: Args:
button_column (List[:class:`telegram.KeyboardButton` | :obj:`str`]): The button to use button_column (List[:class:`telegram.KeyboardButton` | :obj:`str`]): The button to use
in the markup in the markup.
resize_keyboard (:obj:`bool`, optional): Requests clients to resize the keyboard resize_keyboard (:obj:`bool`, optional): Requests clients to resize the keyboard
vertically for optimal fit (e.g., make the keyboard smaller if there are just two vertically for optimal fit (e.g., make the keyboard smaller if there are just two
rows of buttons). Defaults to false, in which case the custom keyboard is always of rows of buttons). Defaults to :obj:`False`, in which case the custom keyboard is
the same height as the app's standard keyboard. always of the same height as the app's standard keyboard.
Defaults to ``False``
one_time_keyboard (:obj:`bool`, optional): Requests clients to hide the keyboard as one_time_keyboard (:obj:`bool`, optional): Requests clients to hide the keyboard as
soon as it's been used. The keyboard will still be available, but clients will soon as it's been used. The keyboard will still be available, but clients will
automatically display the usual letter-keyboard in the chat - the user can press automatically display the usual letter-keyboard in the chat - the user can press
a special button in the input field to see the custom keyboard again. a special button in the input field to see the custom keyboard again.
Defaults to ``False``. Defaults to :obj:`False`.
selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard
to specific users only. Targets: to specific users only. Targets:
1) users that are @mentioned in the text of the Message object 1) Users that are @mentioned in the text of the Message object.
2) if the bot's message is a reply (has reply_to_message_id), sender of the 2) If the bot's message is a reply (has reply_to_message_id), sender of the
original message. original message.
Defaults to ``False``. Defaults to :obj:`False`.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
""" """

8
telegram/replykeyboardremove.py
View file

@ -41,12 +41,16 @@ class ReplyKeyboardRemove(ReplyMarkup):
selective (:obj:`bool`, optional): Use this parameter if you want to remove the keyboard selective (:obj:`bool`, optional): Use this parameter if you want to remove the keyboard
for specific users only. Targets: for specific users only. Targets:
1) users that are @mentioned in the text of the Message object 1) Users that are @mentioned in the text of the :class:`telegram.Message` object.
2) if the bot's message is a reply (has reply_to_message_id), sender of the original 2) If the bot's message is a reply (has `reply_to_message_id`), sender of the original
message. message.
**kwargs (:obj:`dict`): Arbitrary keyword arguments. **kwargs (:obj:`dict`): Arbitrary keyword arguments.
Note:
User will not be able to summon this keyboard; if you want to hide the keyboard from
sight but keep it accessible, use :attr:`telegram.ReplyKeyboardMarkup.one_time_keyboard`.
""" """
def __init__(self, selective=False, **kwargs): def __init__(self, selective=False, **kwargs):

18
telegram/update.py
View file

@ -43,7 +43,7 @@ class Update(TelegramObject):
pre_checkout_query (:class:`telegram.PreCheckoutQuery`): Optional. New incoming pre_checkout_query (:class:`telegram.PreCheckoutQuery`): Optional. New incoming
pre-checkout query. pre-checkout query.
poll (:class:`telegram.Poll`): Optional. New poll state. Bots receive only updates poll (:class:`telegram.Poll`): Optional. New poll state. Bots receive only updates
about stopped polls and polls, which are sent by the bot about stopped polls and polls, which are sent by the bot.
poll_answer (:class:`telegram.PollAnswer`): Optional. A user changed their answer poll_answer (:class:`telegram.PollAnswer`): Optional. A user changed their answer
in a non-anonymous poll. Bots receive new votes only in polls that were sent in a non-anonymous poll. Bots receive new votes only in polls that were sent
by the bot itself. by the bot itself.
@ -52,7 +52,9 @@ class Update(TelegramObject):
update_id (:obj:`int`): The update's unique identifier. Update identifiers start from a update_id (:obj:`int`): The update's unique identifier. Update identifiers start from a
certain positive number and increase sequentially. This ID becomes especially handy if certain positive number and increase sequentially. This ID becomes especially handy if
you're using Webhooks, since it allows you to ignore repeated updates or to restore the you're using Webhooks, since it allows you to ignore repeated updates or to restore the
correct update sequence, should they get out of order. correct update sequence, should they get out of order. If there are no new updates for
at least a week, then identifier of the next update will be chosen randomly instead of
sequentially.
message (:class:`telegram.Message`, optional): New incoming message of any kind - text, message (:class:`telegram.Message`, optional): New incoming message of any kind - text,
photo, sticker, etc. photo, sticker, etc.
edited_message (:class:`telegram.Message`, optional): New version of a message that is edited_message (:class:`telegram.Message`, optional): New version of a message that is
@ -68,9 +70,9 @@ class Update(TelegramObject):
shipping_query (:class:`telegram.ShippingQuery`, optional): New incoming shipping query. shipping_query (:class:`telegram.ShippingQuery`, optional): New incoming shipping query.
Only for invoices with flexible price. Only for invoices with flexible price.
pre_checkout_query (:class:`telegram.PreCheckoutQuery`, optional): New incoming pre_checkout_query (:class:`telegram.PreCheckoutQuery`, optional): New incoming
pre-checkout query. Contains full information about checkout pre-checkout query. Contains full information about checkout.
poll (:class:`telegram.Poll`, optional): New poll state. Bots receive only updates poll (:class:`telegram.Poll`, optional): New poll state. Bots receive only updates about
about polls, which are sent or stopped by the bot stopped polls and polls, which are sent by the bot.
poll_answer (:class:`telegram.PollAnswer`, optional): A user changed their answer poll_answer (:class:`telegram.PollAnswer`, optional): A user changed their answer
in a non-anonymous poll. Bots receive new votes only in polls that were sent in a non-anonymous poll. Bots receive new votes only in polls that were sent
by the bot itself. by the bot itself.
@ -117,7 +119,7 @@ class Update(TelegramObject):
def effective_user(self): def effective_user(self):
""" """
:class:`telegram.User`: The user that sent this update, no matter what kind of update this :class:`telegram.User`: The user that sent this update, no matter what kind of update this
is. Will be ``None`` for :attr:`channel_post` and :attr:`poll`. is. Will be :obj:`None` for :attr:`channel_post` and :attr:`poll`.
""" """
if self._effective_user: if self._effective_user:
@ -156,7 +158,7 @@ class Update(TelegramObject):
def effective_chat(self): def effective_chat(self):
""" """
:class:`telegram.Chat`: The chat that this update was sent in, no matter what kind of :class:`telegram.Chat`: The chat that this update was sent in, no matter what kind of
update this is. Will be ``None`` for :attr:`inline_query`, update this is. Will be :obj:`None` for :attr:`inline_query`,
:attr:`chosen_inline_result`, :attr:`callback_query` from inline messages, :attr:`chosen_inline_result`, :attr:`callback_query` from inline messages,
:attr:`shipping_query`, :attr:`pre_checkout_query`, :attr:`poll` and :attr:`shipping_query`, :attr:`pre_checkout_query`, :attr:`poll` and
:attr:`poll_answer`. :attr:`poll_answer`.
@ -189,7 +191,7 @@ class Update(TelegramObject):
def effective_message(self): def effective_message(self):
""" """
:class:`telegram.Message`: The message included in this update, no matter what kind of :class:`telegram.Message`: The message included in this update, no matter what kind of
update this is. Will be ``None`` for :attr:`inline_query`, update this is. Will be :obj:`None` for :attr:`inline_query`,
:attr:`chosen_inline_result`, :attr:`callback_query` from inline messages, :attr:`chosen_inline_result`, :attr:`callback_query` from inline messages,
:attr:`shipping_query`, :attr:`pre_checkout_query`, :attr:`poll` and :attr:`shipping_query`, :attr:`pre_checkout_query`, :attr:`poll` and
:attr:`poll_answer`. :attr:`poll_answer`.

64
telegram/user.py
View file

@ -29,32 +29,32 @@ class User(TelegramObject):
Attributes: Attributes:
id (:obj:`int`): Unique identifier for this user or bot. id (:obj:`int`): Unique identifier for this user or bot.
is_bot (:obj:`bool`): True, if this user is a bot is_bot (:obj:`bool`): :obj:`True`, if this user is a bot.
first_name (:obj:`str`): User's or bot's first name. first_name (:obj:`str`): User's or bot's first name.
last_name (:obj:`str`): Optional. User's or bot's last name. last_name (:obj:`str`): Optional. User's or bot's last name.
username (:obj:`str`): Optional. User's or bot's username. username (:obj:`str`): Optional. User's or bot's username.
language_code (:obj:`str`): Optional. IETF language tag of the user's language. language_code (:obj:`str`): Optional. IETF language tag of the user's language.
can_join_groups (:obj:`str`): Optional. True, if the bot can be invited to groups. can_join_groups (:obj:`str`): Optional. :obj:`True`, if the bot can be invited to groups.
Returned only in :attr:`telegram.Bot.get_me` requests.
can_read_all_group_messages (:obj:`str`): Optional. True, if privacy mode is disabled
for the bot. Returned only in :attr:`telegram.Bot.get_me` requests.
supports_inline_queries (:obj:`str`): Optional. True, if the bot supports inline queries.
Returned only in :attr:`telegram.Bot.get_me` requests. Returned only in :attr:`telegram.Bot.get_me` requests.
can_read_all_group_messages (:obj:`str`): Optional. :obj:`True`, if privacy mode is
disabled for the bot. Returned only in :attr:`telegram.Bot.get_me` requests.
supports_inline_queries (:obj:`str`): Optional. :obj:`True`, if the bot supports inline
queries. Returned only in :attr:`telegram.Bot.get_me` requests.
bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods. bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
Args: Args:
id (:obj:`int`): Unique identifier for this user or bot. id (:obj:`int`): Unique identifier for this user or bot.
is_bot (:obj:`bool`): True, if this user is a bot is_bot (:obj:`bool`): :obj:`True`, if this user is a bot.
first_name (:obj:`str`): User's or bot's first name. first_name (:obj:`str`): User's or bot's first name.
last_name (:obj:`str`, optional): User's or bot's last name. last_name (:obj:`str`, optional): User's or bot's last name.
username (:obj:`str`, optional): User's or bot's username. username (:obj:`str`, optional): User's or bot's username.
language_code (:obj:`str`, optional): IETF language tag of the user's language. language_code (:obj:`str`, optional): IETF language tag of the user's language.
can_join_groups (:obj:`str`, optional): True, if the bot can be invited to groups. can_join_groups (:obj:`str`, optional): :obj:`True`, if the bot can be invited to groups.
Returned only in :attr:`telegram.Bot.get_me` requests.
can_read_all_group_messages (:obj:`str`, optional): True, if privacy mode is disabled
for the bot. Returned only in :attr:`telegram.Bot.get_me` requests.
supports_inline_queries (:obj:`str`, optional): True, if the bot supports inline queries.
Returned only in :attr:`telegram.Bot.get_me` requests. Returned only in :attr:`telegram.Bot.get_me` requests.
can_read_all_group_messages (:obj:`str`, optional): :obj:`True`, if privacy mode is
disabled for the bot. Returned only in :attr:`telegram.Bot.get_me` requests.
supports_inline_queries (:obj:`str`, optional): :obj:`True`, if the bot supports inline
queries. Returned only in :attr:`telegram.Bot.get_me` requests.
bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods. bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
""" """
@ -143,6 +143,10 @@ class User(TelegramObject):
def mention_markdown(self, name=None): def mention_markdown(self, name=None):
""" """
Note:
:attr:`telegram.ParseMode.MARKDOWN` is is a legacy mode, retained by Telegram for
backward compatibility. You should use :meth:`mention_markdown_v2` instead.
Args: Args:
name (:obj:`str`): The name used as a link for the user. Defaults to :attr:`full_name`. name (:obj:`str`): The name used as a link for the user. Defaults to :attr:`full_name`.
@ -185,8 +189,6 @@ class User(TelegramObject):
bot.send_message(update.effective_user.id, *args, **kwargs) bot.send_message(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -198,8 +200,6 @@ class User(TelegramObject):
bot.send_photo(update.effective_user.id, *args, **kwargs) bot.send_photo(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -211,8 +211,6 @@ class User(TelegramObject):
bot.send_media_group(update.effective_user.id, *args, **kwargs) bot.send_media_group(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
List[:class:`telegram.Message`:] On success, instance representing the message posted. List[:class:`telegram.Message`:] On success, instance representing the message posted.
@ -224,8 +222,6 @@ class User(TelegramObject):
bot.send_audio(update.effective_user.id, *args, **kwargs) bot.send_audio(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -237,8 +233,6 @@ class User(TelegramObject):
bot.send_chat_action(update.effective_user.id, *args, **kwargs) bot.send_chat_action(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:obj:`True`: On success. :obj:`True`: On success.
@ -253,8 +247,6 @@ class User(TelegramObject):
bot.send_contact(update.effective_user.id, *args, **kwargs) bot.send_contact(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -266,8 +258,6 @@ class User(TelegramObject):
bot.send_dice(update.effective_user.id, *args, **kwargs) bot.send_dice(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -279,8 +269,6 @@ class User(TelegramObject):
bot.send_document(update.effective_user.id, *args, **kwargs) bot.send_document(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -292,8 +280,6 @@ class User(TelegramObject):
bot.send_game(update.effective_user.id, *args, **kwargs) bot.send_game(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -305,8 +291,6 @@ class User(TelegramObject):
bot.send_invoice(update.effective_user.id, *args, **kwargs) bot.send_invoice(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -318,8 +302,6 @@ class User(TelegramObject):
bot.send_location(update.effective_user.id, *args, **kwargs) bot.send_location(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -331,8 +313,6 @@ class User(TelegramObject):
bot.send_animation(update.effective_user.id, *args, **kwargs) bot.send_animation(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -344,8 +324,6 @@ class User(TelegramObject):
bot.send_sticker(update.effective_user.id, *args, **kwargs) bot.send_sticker(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -357,8 +335,6 @@ class User(TelegramObject):
bot.send_video(update.effective_user.id, *args, **kwargs) bot.send_video(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -370,8 +346,6 @@ class User(TelegramObject):
bot.send_venue(update.effective_user.id, *args, **kwargs) bot.send_venue(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -383,8 +357,6 @@ class User(TelegramObject):
bot.send_video_note(update.effective_user.id, *args, **kwargs) bot.send_video_note(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -396,8 +368,6 @@ class User(TelegramObject):
bot.send_voice(update.effective_user.id, *args, **kwargs) bot.send_voice(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.
@ -409,8 +379,6 @@ class User(TelegramObject):
bot.send_poll(update.effective_user.id, *args, **kwargs) bot.send_poll(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns: Returns:
:class:`telegram.Message`: On success, instance representing the message posted. :class:`telegram.Message`: On success, instance representing the message posted.

15
telegram/utils/helpers.py
View file

@ -93,7 +93,7 @@ def to_float_timestamp(t, reference_timestamp=None):
Any objects from the :class:`datetime` module that are timezone-naive will be assumed Any objects from the :class:`datetime` module that are timezone-naive will be assumed
to be in UTC. to be in UTC.
``None`` s are left alone (i.e. ``to_float_timestamp(None)`` is ``None``). :obj:`None` s are left alone (i.e. ``to_float_timestamp(None)`` is :obj:`None`).
Args: Args:
t (int | float | datetime.timedelta | datetime.datetime | datetime.time): t (int | float | datetime.timedelta | datetime.datetime | datetime.time):
@ -112,7 +112,7 @@ def to_float_timestamp(t, reference_timestamp=None):
If ``t`` is given as an absolute representation of date & time (i.e. a If ``t`` is given as an absolute representation of date & time (i.e. a
``datetime.datetime`` object), ``reference_timestamp`` is not relevant and so its ``datetime.datetime`` object), ``reference_timestamp`` is not relevant and so its
value should be ``None``. If this is not the case, a ``ValueError`` will be raised. value should be :obj:`None`. If this is not the case, a ``ValueError`` will be raised.
Returns: Returns:
(float | None) The return value depends on the type of argument ``t``. If ``t`` is (float | None) The return value depends on the type of argument ``t``. If ``t`` is
@ -167,16 +167,16 @@ def to_timestamp(dt_obj, reference_timestamp=None):
def from_timestamp(unixtime, tzinfo=dtm.timezone.utc): def from_timestamp(unixtime, tzinfo=dtm.timezone.utc):
""" """
Converts an (integer) unix timestamp to a timezone aware datetime object. Converts an (integer) unix timestamp to a timezone aware datetime object.
``None`` s are left alone (i.e. ``from_timestamp(None)`` is ``None``). :obj:`None`s are left alone (i.e. ``from_timestamp(None)`` is :obj:`None`).
Args: Args:
unixtime (int): integer POSIX timestamp unixtime (int): Integer POSIX timestamp.
tzinfo (:obj:`datetime.tzinfo`, optional): The timezone, the timestamp is to be converted tzinfo (:obj:`datetime.tzinfo`, optional): The timezone, the timestamp is to be converted
to. Defaults to UTC. to. Defaults to UTC.
Returns: Returns:
timezone aware equivalent :obj:`datetime.datetime` value if ``timestamp`` is not timezone aware equivalent :obj:`datetime.datetime` value if ``timestamp`` is not
``None``; else ``None`` :obj:`None`; else :obj:`None`
""" """
if unixtime is None: if unixtime is None:
return None return None
@ -265,8 +265,9 @@ def create_deep_linked_url(bot_username, payload=None, group=False):
Args: Args:
bot_username (:obj:`str`): The username to link to bot_username (:obj:`str`): The username to link to
payload (:obj:`str`, optional): Parameters to encode in the created URL payload (:obj:`str`, optional): Parameters to encode in the created URL
group (:obj:`bool`, optional): If `True` the user is prompted to select a group to add the group (:obj:`bool`, optional): If :obj:`True` the user is prompted to select a group to
bot to. If `False`, opens a one-on-one conversation with the bot. Defaults to `False`. add the bot to. If :obj:`False`, opens a one-on-one conversation with the bot.
Defaults to :obj:`False`.
Returns: Returns:
:obj:`str`: An URL to start the bot with specific parameters :obj:`str`: An URL to start the bot with specific parameters

4
telegram/webhookinfo.py
View file

@ -39,11 +39,11 @@ class WebhookInfo(TelegramObject):
Args: Args:
url (:obj:`str`): Webhook URL, may be empty if webhook is not set up. url (:obj:`str`): Webhook URL, may be empty if webhook is not set up.
has_custom_certificate (:obj:`bool`): True, if a custom certificate was provided for has_custom_certificate (:obj:`bool`): :obj:`True`, if a custom certificate was provided for
webhook certificate checks. webhook certificate checks.
pending_update_count (:obj:`int`): Number of updates awaiting delivery. pending_update_count (:obj:`int`): Number of updates awaiting delivery.
last_error_date (:obj:`int`, optional): Unix time for the most recent error that happened last_error_date (:obj:`int`, optional): Unix time for the most recent error that happened
when trying todeliver an update via webhook. when trying to deliver an update via webhook.
last_error_message (:obj:`str`, optional): Error message in human-readable format for the last_error_message (:obj:`str`, optional): Error message in human-readable format for the
most recent error that happened when trying to deliver an update via webhook. most recent error that happened when trying to deliver an update via webhook.
max_connections (:obj:`int`, optional): Maximum allowed number of simultaneous HTTPS max_connections (:obj:`int`, optional): Maximum allowed number of simultaneous HTTPS