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

Documentation Improvements (#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:**
- 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 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`_)
**Minor changes, CI improvements, doc fixes or bug fixes:**
- Added ``tzinfo`` argument to ``helpers.from_timestamp`` (`#1621`_)
- Stabalize CI (`#1919`_, `#1931`_)
- Use ABCs ``@abstractmethod`` instead of raising ``NotImplementedError`` for ``Handler``, ``BasePersistence`` and ``BaseFilter`` (`#1905`_)
- 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/
: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
: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!
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).
### [`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
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.
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
: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
show bold, italic, fixed-width text or inline URLs in the media caption. See the
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.
disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
receive a notification with no sound.
@ -1214,7 +1214,7 @@ class Bot(TelegramObject):
Returns:
: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)
@ -1268,7 +1268,7 @@ class Bot(TelegramObject):
Returns:
: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)
@ -1453,7 +1453,7 @@ class Bot(TelegramObject):
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format @channelusername).
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
receive a notification with no sound.
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.
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -1537,9 +1537,9 @@ class Bot(TelegramObject):
query.
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.
is_personal (:obj:`bool`, optional): Pass True, if results may be cached on the server
side only for the user that sent the query. By default, results may be returned to
any user who sends the same query.
is_personal (:obj:`bool`, optional): Pass :obj:`True`, if results may be cached on
the server side only for the user that sent the query. By default,
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 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
@ -1551,7 +1551,7 @@ class Bot(TelegramObject):
message sent to the bot when user presses the switch button. 1-64 characters,
only A-Z, a-z, 0-9, _ and - are allowed.
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).
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
@ -1565,7 +1565,7 @@ class Bot(TelegramObject):
where they wanted to use the bot's inline capabilities.
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -1723,7 +1723,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool` On success, ``True`` is returned.
:obj:`bool` On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -1760,7 +1760,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool` On success, ``True`` is returned.
:obj:`bool` On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -1797,10 +1797,12 @@ class Bot(TelegramObject):
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
be shown to the user, 0-200 characters.
show_alert (:obj:`bool`, optional): If true, an alert will be shown by the client
instead of a notification at the top of the chat screen. Defaults to false.
show_alert (:obj:`bool`, optional): If :obj:`True`, an alert will be shown by the
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
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
game button. Otherwise, you may use links like t.me/your_bot?start=XXXX that open
your bot with a parameter.
@ -1812,7 +1814,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool` On success, ``True`` is returned.
:obj:`bool` On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -1874,7 +1876,7 @@ class Bot(TelegramObject):
Returns:
: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:
:class:`telegram.TelegramError`
@ -1933,7 +1935,7 @@ class Bot(TelegramObject):
Returns:
: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:
:class:`telegram.TelegramError`
@ -1995,7 +1997,7 @@ class Bot(TelegramObject):
Returns:
: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:
:class:`telegram.TelegramError`
@ -2048,7 +2050,7 @@ class Bot(TelegramObject):
Returns:
: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:
:class:`telegram.TelegramError`
@ -2204,7 +2206,7 @@ class Bot(TelegramObject):
Webhooks`_.
Returns:
:obj:`bool` On success, ``True`` is returned.
:obj:`bool` On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -2256,7 +2258,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool` On success, ``True`` is returned.
:obj:`bool` On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -2283,7 +2285,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool` On success, ``True`` is returned.
:obj:`bool` On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -2439,7 +2441,7 @@ class Bot(TelegramObject):
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
"""
url = '{}/setChatStickerSet'.format(self.base_url)
@ -2466,7 +2468,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
"""
url = '{}/deleteChatStickerSet'.format(self.base_url)
@ -2517,10 +2519,10 @@ class Bot(TelegramObject):
Args:
user_id (:obj:`int`): User identifier.
score (:obj:`int`): New score, must be non-negative.
force (:obj:`bool`, optional): Pass True, if the high score is allowed to 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
be automatically edited to include the current scoreboard.
force (:obj:`bool`, optional): Pass :obj:`True`, if the high score is allowed to
decrease. This can be useful when fixing mistakes or banning cheaters.
disable_edit_message (:obj:`bool`, optional): Pass :obj:`True`, if the game message
should not be automatically edited to include the current scoreboard.
chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
specified. Unique identifier for the target chat.
message_id (:obj:`int`, optional): Required if inline_message_id is not specified.
@ -2534,11 +2536,11 @@ class Bot(TelegramObject):
Returns:
:class:`telegram.Message`: The edited message, or if the message wasn't sent by the bot
, ``True``.
, :obj:`True`.
Raises:
: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)
@ -2641,14 +2643,15 @@ class Bot(TelegramObject):
description (:obj:`str`): Product description, 1-255 characters.
payload (:obj:`str`): Bot-defined invoice payload, 1-128 bytes. This will not be
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
generate this invoice when used as a start parameter.
currency (:obj:`str`): Three-letter ISO 4217 currency code.
prices (List[:class:`telegram.LabeledPrice`)]: Price breakdown, a JSON-serialized list
of components (e.g. product price, tax, discount, delivery cost, delivery tax,
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
required fields should be provided by the payment provider. When an object is
passed, it will be encoded as JSON.
@ -2658,20 +2661,20 @@ class Bot(TelegramObject):
photo_size (:obj:`str`, optional): Photo size.
photo_width (:obj:`int`, optional): Photo width.
photo_height (:obj:`int`, optional): Photo height.
need_name (:obj:`bool`, optional): Pass True, if you require the user's full name to
complete the order.
need_phone_number (:obj:`bool`, optional): Pass True, if you require the user's
need_name (:obj:`bool`, optional): Pass :obj:`True`, if you require the user's full
name to complete the order.
need_phone_number (:obj:`bool`, optional): Pass :obj:`True`, if you require the user's
phone number to complete the order.
need_email (:obj:`bool`, optional): Pass True, if you require the user's email to
complete the order.
need_shipping_address (:obj:`bool`, optional): Pass True, if you require the user's
shipping address to complete the order.
send_phone_number_to_provider (:obj:`bool`, optional): Pass True, if user's phone
number should be sent to provider.
send_email_to_provider (:obj:`bool`, optional): Pass True, if user's email address
should be sent to provider.
is_flexible (:obj:`bool`, optional): Pass True, if the final price depends on the
shipping method.
need_email (:obj:`bool`, optional): Pass :obj:`True`, if you require the user's email
to complete the order.
need_shipping_address (:obj:`bool`, optional): Pass :obj:`True`, if you require the
user's shipping address to complete the order.
send_phone_number_to_provider (:obj:`bool`, optional): Pass :obj:`True`, if user's
phone number should be sent to provider.
send_email_to_provider (:obj:`bool`, optional): Pass :obj:`True`, if user's email
address should be sent to provider.
is_flexible (:obj:`bool`, optional): Pass :obj:`True`, if the final price depends on
the shipping method.
disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
receive a notification with no sound.
reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the
@ -2750,12 +2753,12 @@ class Bot(TelegramObject):
Args:
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
False if there are any problems (for example, if delivery to the specified address
is not possible).
ok (:obj:`bool`): Specify :obj:`True` if delivery to the specified address is possible
and :obj:`False` if there are any problems (for example, if delivery to the
specified address is not possible).
shipping_options (List[:class:`telegram.ShippingOption`]), optional]: Required if ok is
True. A JSON-serialized array of available shipping options.
error_message (:obj:`str`, optional): Required if ok is False. Error message in
:obj:`True`. A JSON-serialized array of available shipping options.
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.
"Sorry, delivery to your desired address is unavailable"). Telegram will display
this message to the user.
@ -2765,7 +2768,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool`: On success, True is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -2811,20 +2814,21 @@ class Bot(TelegramObject):
Args:
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
the bot is ready to proceed with the order. Use False if there are any problems.
error_message (:obj:`str`, optional): Required if ok is False. Error message in human
readable form that explains the reason for failure to proceed with the checkout
(e.g. "Sorry, somebody just bought the last of our amazing black T-shirts while you
were busy filling out your payment details. Please choose a different color or
garment!"). Telegram will display this message to the user.
ok (:obj:`bool`): Specify :obj:`True` if everything is alright
(goods are available, etc.) and the bot is ready to proceed with the order. Use
:obj:`False` if there are any problems.
error_message (:obj:`str`, optional): Required if ok is :obj:`False`. Error message
in human readable form that explains the reason for failure to proceed with
the checkout (e.g. "Sorry, somebody just bought the last of our amazing black
T-shirts while you 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
the read timeout from the server (instead of the one specified during creation of
the connection pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -2855,8 +2859,8 @@ class Bot(TelegramObject):
timeout=None, **kwargs):
"""
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
all boolean parameters to lift restrictions from a user.
the supergroup for this to work and must have the appropriate admin rights. Pass
:obj:`True` for all boolean parameters to lift restrictions from a user.
Note:
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
days or less than 30 seconds from the current time, they are considered to be
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
the read timeout from the server (instead of the one specified during creation of
the connection pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
: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
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:
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target supergroup (in the format @supergroupusername).
user_id (:obj:`int`): Unique identifier of the target user.
can_change_info (:obj:`bool`, optional): Pass True, if the administrator can change
chat title, photo and other settings.
can_post_messages (:obj:`bool`, optional): Pass True, if the administrator can
can_change_info (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
change chat title, photo and other settings.
can_post_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
create channel posts, channels only.
can_edit_messages (:obj:`bool`, optional): Pass True, if the administrator can edit
messages of other users, channels only.
can_delete_messages (:obj:`bool`, optional): Pass True, if the administrator can
can_edit_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
edit messages of other users, channels only.
can_delete_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
delete messages of other users.
can_invite_users (:obj:`bool`, optional): Pass True, if the administrator can invite
new users to the chat.
can_restrict_members (:obj:`bool`, optional): Pass True, if the administrator can
restrict, ban or unban chat members.
can_pin_messages (:obj:`bool`, optional): Pass True, if the administrator can pin
messages, supergroups only.
can_promote_members (:obj:`bool`, optional): Pass True, if the administrator can add
new administrators with a subset of his own privileges or demote administrators
can_invite_users (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
invite new users to the chat.
can_restrict_members (:obj:`bool`, optional): Pass :obj:`True`, if the administrator
can restrict, ban or unban chat members.
can_pin_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
pin messages, supergroups only.
can_promote_members (:obj:`bool`, optional): Pass :obj:`True`, if the 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 that were
appointed by him).
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
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -2985,7 +2990,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3023,7 +3028,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3086,7 +3091,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3120,7 +3125,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3152,7 +3157,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3184,7 +3189,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3212,16 +3217,16 @@ class Bot(TelegramObject):
chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
of the target channel (in the format @channelusername).
message_id (:obj:`int`): Identifier of a message to pin.
disable_notification (:obj:`bool`, optional): Pass True, if it is not necessary to send
a notification to all group members about the new pinned message. Notifications
are always disabled in channels.
disable_notification (:obj:`bool`, optional): Pass :obj:`True`, if it is not necessary
to send a notification to all group members about the new pinned message.
Notifications are always disabled in channels.
timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
the read timeout from the server (instead of the one specified during creation of
the connection pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3256,7 +3261,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3320,7 +3325,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:class:`telegram.File`: The uploaded File
:class:`telegram.File`: On success, the uploaded File is returned.
Raises:
:class:`telegram.TelegramError`
@ -3373,10 +3378,10 @@ class Bot(TelegramObject):
tgs_sticker (:obj:`str` | `filelike object`, optional): TGS animation with the sticker,
uploaded using multipart/form-data. See
https://core.telegram.org/animated_stickers#technical-requirements for technical
requirements
requirements.
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
created.
contains_masks (:obj:`bool`, optional): Pass :obj:`True`, if a set of mask stickers
should be created.
mask_position (:class:`telegram.MaskPosition`, optional): Position where the mask
should be placed on faces.
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.
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3438,7 +3443,7 @@ class Bot(TelegramObject):
Args:
user_id (:obj:`int`): User identifier of created sticker set owner.
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,
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
@ -3447,7 +3452,7 @@ class Bot(TelegramObject):
tgs_sticker (:obj:`str` | `filelike object`, optional): TGS animation with the sticker,
uploaded using multipart/form-data. See
https://core.telegram.org/animated_stickers#technical-requirements for technical
requirements
requirements.
emojis (:obj:`str`): One or more emoji corresponding to the sticker.
mask_position (:class:`telegram.MaskPosition`, optional): Position where the mask
should be placed on faces.
@ -3457,7 +3462,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3500,7 +3505,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3527,7 +3532,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3559,14 +3564,15 @@ class Bot(TelegramObject):
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
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
the read timeout from the server (instead of the one specified during
creation of the connection pool).
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3606,7 +3612,7 @@ class Bot(TelegramObject):
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
Raises:
:class:`telegram.TelegramError`
@ -3648,12 +3654,12 @@ class Bot(TelegramObject):
of the target channel (in the format @channelusername).
question (:obj:`str`): Poll question, 1-255 characters.
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,
defaults to True.
is_anonymous (:obj:`bool`, optional): :obj:`True`, if the poll needs to be anonymous,
defaults to :obj:`True`.
type (:obj:`str`, optional): Poll type, :attr:`telegram.Poll.QUIZ` or
:attr:`telegram.Poll.REGULAR`, defaults to :attr:`telegram.Poll.REGULAR`.
allows_multiple_answers (:obj:`bool`, optional): True, if the poll allows multiple
answers, ignored for polls in quiz mode, defaults to False.
allows_multiple_answers (:obj:`bool`, optional): :obj:`True`, if the poll allows
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
option, required for polls in quiz mode.
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
more than 600 seconds in the future. Can't be used together with
:attr:`open_period`.
is_closed (:obj:`bool`, optional): Pass True, if the poll needs to be immediately
closed. This can be useful for poll preview.
is_closed (:obj:`bool`, optional): Pass :obj:`True`, if the poll needs to be
immediately closed. This can be useful for poll preview.
disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
receive a notification with no sound.
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)
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
"""
return self.bot.answerCallbackQuery(self.id, *args, **kwargs)
@ -134,7 +134,7 @@ class CallbackQuery(TelegramObject):
Returns:
: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:
@ -160,7 +160,7 @@ class CallbackQuery(TelegramObject):
Returns:
: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:
@ -188,7 +188,7 @@ class CallbackQuery(TelegramObject):
Returns:
: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:
@ -217,7 +217,7 @@ class CallbackQuery(TelegramObject):
Returns:
: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:
@ -246,7 +246,7 @@ class CallbackQuery(TelegramObject):
Returns:
: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:
@ -275,7 +275,7 @@ class CallbackQuery(TelegramObject):
Returns:
: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:
@ -302,7 +302,7 @@ class CallbackQuery(TelegramObject):
Returns:
: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:
@ -329,7 +329,7 @@ class CallbackQuery(TelegramObject):
Returns:
: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:

75
telegram/chat.py
View file

@ -37,13 +37,14 @@ class Chat(TelegramObject):
description (:obj:`str`): Optional. Description, for groups, 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.
Returned only in get_chat.
Returned only in :meth:`telegram.Bot.get_chat`.
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
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.
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.
Args:
@ -58,22 +59,26 @@ class Chat(TelegramObject):
available.
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.
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.
Returned only in get_chat.
invite_link (:obj:`str`, optional): Chat invite link, for supergroups and channel chats.
Returned only in get_chat.
pinned_message (:class:`telegram.Message`, optional): Pinned message, for supergroups.
Returned only in get_chat.
Returned only in :meth:`telegram.Bot.get_chat`.
invite_link (:obj:`str`, optional): Chat invite link, for groups, supergroups and channel
chats. Each administrator in a chat generates their own invite links, so the bot must
first generate the link using ``export_chat_invite_link()``. Returned only
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,
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
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.
sticker_set_name (:obj:`str`, optional): For supergroups, name of Group sticker set.
Returned only in get_chat.
can_set_sticker_set (:obj:`bool`, optional): ``True``, if the bot can change group the
sticker set. Returned only in get_chat.
sticker_set_name (:obj:`str`, optional): For supergroups, name of group sticker set.
Returned only in :meth:`telegram.Bot.get_chat`.
can_set_sticker_set (:obj:`bool`, optional): :obj:`True`, if the bot can change group the
sticker set. Returned only in :meth:`telegram.Bot.get_chat`.
**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
:class:`telegram.ChatMember` objects that contains information about all
chat administrators except other bots. If the chat is a group or a supergroup
and no administrators were appointed, only the creator will be returned
and no administrators were appointed, only the creator will be returned.
"""
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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
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)
Where Chat is the current instance.
Returns:
:obj:`True`: On success.
@ -292,8 +291,6 @@ class Chat(TelegramObject):
bot.send_photo(update.effective_chat.id, *args, **kwargs)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
: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)
Where Chat is the current instance.
Returns:
:class:`telegram.Message`: On success, instance representing the message posted.

2
telegram/chataction.py
View file

@ -21,7 +21,7 @@
class ChatAction:
"""Helper class to provide constants for different chatactions."""
"""Helper class to provide constants for different chat actions."""
FIND_LOCATION = '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):
"""This object contains information about one member of the chat.
"""This object contains information about one member of a chat.
Attributes:
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_promote_members (:obj:`bool`): Optional. If the administrator can add new
administrators.
is_member (:obj:`bool`): Optional. Restricted only. True, if the user is a member of the
chat at the moment of the request.
is_member (:obj:`bool`): Optional. Restricted only. :obj:`True`, if the user is a member of
the chat at the moment of the request.
can_send_messages (:obj:`bool`): Optional. If the user can send text messages, contacts,
locations and venues.
can_send_media_messages (:obj:`bool`): Optional. If the user can send media 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.
can_send_other_messages (:obj:`bool`): Optional. If the user can send animations, games,
stickers and use inline bots, implies can_send_media_messages.
@ -67,39 +67,38 @@ class ChatMember(TelegramObject):
Custom title for this user.
until_date (:class:`datetime.datetime`, optional): Restricted and kicked only. Date when
restrictions will be lifted for this user.
can_be_edited (:obj:`bool`, optional): Administrators only. True, if the bot is allowed to
edit administrator privileges of that user.
can_change_info (:obj:`bool`, optional): Administrators and restricted only. True, 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 in the channel, channels only.
can_edit_messages (:obj:`bool`, optional): Administrators only. True, if the administrator
can edit messages of other users, channels only.
can_delete_messages (:obj:`bool`, optional): Administrators only. True, if the
administrator can delete messages of other user.
can_invite_users (:obj:`bool`, optional): Administrators and restricted only. True, if the
user can invite new users to the chat.
can_restrict_members (:obj:`bool`, optional): Administrators only. True, if the
can_be_edited (:obj:`bool`, optional): Administrators only. :obj:`True`, if the bot is
allowed to edit administrator privileges of that user.
can_change_info (:obj:`bool`, optional): Administrators and restricted only. :obj:`True`,
if the user can change the chat title, photo and other settings.
can_post_messages (:obj:`bool`, optional): Administrators only. :obj:`True`, if the
administrator can post in the channel, channels only.
can_edit_messages (:obj:`bool`, optional): Administrators only. :obj:`True`, if the
administrator can edit messages of other users and can pin messages; channels only.
can_delete_messages (:obj:`bool`, optional): Administrators only. :obj:`True`, if the
administrator can delete messages of other users.
can_invite_users (:obj:`bool`, optional): Administrators and restricted only. :obj:`True`,
if the user can invite new users to the chat.
can_restrict_members (:obj:`bool`, optional): Administrators only. :obj:`True`, if the
administrator can restrict, ban or unban chat members.
can_pin_messages (:obj:`bool`, optional): Administrators and restricted only. True, if the
user can pin messages, supergroups only.
can_promote_members (:obj:`bool`, optional): Administrators only. True, if the
can_pin_messages (:obj:`bool`, optional): Administrators and restricted only. :obj:`True`,
if the user can pin messages, groups and supergroups only.
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
administrators that he has promoted, directly or indirectly (promoted by administrators
that were appointed by the user).
is_member (:obj:`bool`, optional): Restricted only. True, if the user is a member of the
chat at the moment of the request.
can_send_messages (:obj:`bool`, optional): Restricted only. True, if the user can send text
messages, contacts, locations and venues.
can_send_media_messages (:obj:`bool`, optional): Restricted only. True, if the user can
send audios, documents, photos, videos, video notes and voice notes, implies
can_send_messages.
can_send_polls (:obj:`bool`, optional): Restricted only. True, if the user is allowed to
send polls.
can_send_other_messages (:obj:`bool`, optional): Restricted only. True, if the user can
send animations, games, stickers and use inline bots, implies can_send_media_messages.
can_add_web_page_previews (:obj:`bool`, optional): Restricted only. True, if user may add
web page previews to his messages, implies can_send_media_messages.
is_member (:obj:`bool`, optional): Restricted only. :obj:`True`, if the user is a member of
the chat at the moment of the request.
can_send_messages (:obj:`bool`, optional): Restricted only. :obj:`True`, if the user can
send text messages, contacts, locations and venues.
can_send_media_messages (:obj:`bool`, optional): Restricted only. :obj:`True`, if the user
can send audios, documents, photos, videos, video notes and voice notes.
can_send_polls (:obj:`bool`, optional): Restricted only. :obj:`True`, if the user is
allowed to send polls.
can_send_other_messages (:obj:`bool`, optional): Restricted only. :obj:`True`, if the user
can send animations, games, stickers and use inline bots.
can_add_web_page_previews (:obj:`bool`, optional): Restricted only. :obj:`True`, if user
may add web page previews to his messages.
"""
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.
Note:
Though not stated explicitly in the offical docs, Telegram changes not only the permissions
that are set, but also sets all the others to :obj:`False`. However, since not documented,
this behaviour may change unbeknown to PTB.
Though not stated explicitly in the official docs, Telegram changes not only the
permissions that are set, but also sets all the others to :obj:`False`. However, since not
documented, this behaviour may change unbeknown to PTB.
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.
can_send_media_messages (:obj:`bool`): Optional. True, if the user is allowed to send
audios, documents, photos, videos, video notes and voice notes, implies
can_send_media_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
send audios, documents, photos, videos, video notes and voice notes, implies
:attr:`can_send_messages`.
can_send_polls (:obj:`bool`): Optional. True, if the user is allowed to send polls, implies
:attr:`can_send_messages`.
can_send_other_messages (:obj:`bool`): Optional. True, if the user is allowed to send
animations, games, stickers and use inline bots, implies
can_send_polls (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to send polls,
implies :attr:`can_send_messages`.
can_send_other_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
send animations, games, stickers and use inline bots, implies
:attr:`can_send_media_messages`.
can_add_web_page_previews (:obj:`bool`): Optional. True, if the user is allowed to 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
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
to the chat.
can_pin_messages (:obj:`bool`): Optional. True, if the user is allowed to pin messages.
Ignored in public supergroups.
can_add_web_page_previews (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
add web page previews to their messages, implies :attr:`can_send_media_messages`.
can_change_info (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to change the
chat title, photo and other settings. Ignored in public supergroups.
can_invite_users (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to invite
new users to the chat.
can_pin_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to pin
messages. Ignored in public supergroups.
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.
can_send_media_messages (:obj:`bool`, optional): True, if the user is allowed to send
audios, documents, photos, videos, video notes and voice notes, implies
can_send_media_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to
send audios, documents, photos, videos, video notes and voice notes, implies
:attr:`can_send_messages`.
can_send_polls (:obj:`bool`, optional): True, if the user is allowed to send polls, implies
:attr:`can_send_messages`.
can_send_other_messages (:obj:`bool`, optional): True, if the user is allowed to send
animations, games, stickers and use inline bots, implies
can_send_polls (:obj:`bool`, optional): :obj:`True`, if the user is allowed to send polls,
implies :attr:`can_send_messages`.
can_send_other_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to
send animations, games, stickers and use inline bots, implies
:attr:`can_send_media_messages`.
can_add_web_page_previews (:obj:`bool`, optional): True, if the user is allowed to 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
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
to the chat.
can_pin_messages (:obj:`bool`, optional): True, if the user is allowed to pin messages.
Ignored in public supergroups.
can_add_web_page_previews (:obj:`bool`, optional): :obj:`True`, if the user is allowed to
add web page previews to their messages, implies :attr:`can_send_media_messages`.
can_change_info (:obj:`bool`, optional): :obj:`True`, if the user is allowed to change the
chat title, photo and other settings. Ignored in public supergroups.
can_invite_users (:obj:`bool`, optional): :obj:`True`, if the user is allowed to invite new
users to the chat.
can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to pin
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.
**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,

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
Returns:
str:
:obj:`str`: The stripped string.
"""
if in_s.startswith(lstr):
@ -77,7 +77,7 @@ class TimedOut(NetworkError):
class ChatMigrated(TelegramError):
"""
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):
"""
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:
* 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`.
* 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`.
* 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`.
* If you want to store conversation data with :class:`telegram.ext.ConversationHandler`, you
must overwrite :meth:`get_conversations` and :meth:`update_conversation`.
@ -47,11 +47,11 @@ class BasePersistence(ABC):
Args:
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
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
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):
@ -83,18 +83,18 @@ class BasePersistence(ABC):
def get_bot_data(self):
""""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
``dict``.
:obj:`dict`.
Returns:
:obj:`defaultdict`: The restored bot data.
:obj:`dict`: The restored bot data.
"""
@abstractmethod
def get_conversations(self, name):
""""Will be called by :class:`telegram.ext.Dispatcher` when a
:class:`telegram.ext.ConversationHandler` is added if
:attr:`telegram.ext.ConversationHandler.persistent` is ``True``.
It should return the conversations for the handler with `name` or an empty ``dict``
:attr:`telegram.ext.ConversationHandler.persistent` is :obj:`True`.
It should return the conversations for the handler with `name` or an empty :obj:`dict`
Args:
name (:obj:`str`): The handlers name.
@ -106,10 +106,10 @@ class BasePersistence(ABC):
@abstractmethod
def update_conversation(self, name, key, new_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:
name (:obj:`str`): The handlers name.
name (:obj:`str`): The handler's name.
key (:obj:`tuple`): The key the state is changed for.
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
: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``
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.
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
: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.
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
handled by this handler.
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``.
Default is ``False``
Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks.
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``.
Default is ``False``
Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
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
: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``
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.
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
: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.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
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
use ``~Filters.update.edited_message`` in the filter argument.
Note:
:class:`telegram.ext.CommandHandler` does *not* handle (edited) channel posts.
Attributes:
command (:obj:`str` | List[:obj:`str`]): The command or list of commands this handler
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.
filters (:class:`telegram.ext.BaseFilter`): Optional. Only allow updates with these
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.
pass_args (:obj:`bool`): Determines whether the handler should be passed
``args``.
@ -59,10 +62,10 @@ class CommandHandler(Handler):
the callback function.
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
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
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
operators (& for and, | for or, ~ for not).
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
``~Filters.update.edited_message``.
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
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.
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``
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.
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
: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.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
Raises:
@ -158,7 +161,7 @@ class CommandHandler(Handler):
update (:class:`telegram.Update`): Incoming telegram update.
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:
@ -213,7 +216,7 @@ class PrefixHandler(CommandHandler):
PrefixHandler(['!', '#'], 'test', callback) will respond to '!test' and
'#test'.
Miltiple prefixes and commands:
Multiple prefixes and commands:
PrefixHandler(['!', '#'], ['test', 'help`], callback) will respond to '!test',
'#test', '!help' and '#help'.
@ -268,23 +271,23 @@ class PrefixHandler(CommandHandler):
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
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.
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``
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.
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
: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.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
"""
@ -349,7 +352,7 @@ class PrefixHandler(CommandHandler):
update (:class:`telegram.Update`): Incoming telegram update.
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:

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
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
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.
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
default), the state will not change. If an entry point callback function returns None,
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 :obj:`None`,
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
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.
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
``False`` on :attr:`check_update`.
:obj:`False` on :attr:`check_update`.
allow_reentry (:obj:`bool`): Determines if a user can restart a conversation with
an entry point.
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
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
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`.
name (:obj:`str`): Optional. The name for this conversationhandler. Required for
persistence
@ -111,32 +111,33 @@ class ConversationHandler(Handler):
Args:
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`
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.
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
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
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
returns ``True`` will be used. If all return ``False``, the update is not handled.
allow_reentry (:obj:`bool`, optional): If set to ``True``, a user that is currently in a
:obj:`False` on :attr:`check_update`. The first handler which :attr:`check_update`
method returns :obj:`True` will be used. If all return :obj:`False`, the update is not
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.
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.
Default is ``True``.
Default is :obj:`True`.
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
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
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`.
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
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
@ -182,7 +183,7 @@ class ConversationHandler(Handler):
raise ValueError("Conversations can't be persistent when handler is unnamed.")
self.persistent = persistent
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"""
self._map_to_parent = map_to_parent

16
telegram/ext/defaults.py
View file

@ -26,7 +26,7 @@ class Defaults:
Attributes:
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
receive a notification with no sound.
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
read timeout from the server (instead of the one specified during creation of the
connection pool).
quote (:obj:`bool`): Optional. If set to ``True``, the reply is sent as an actual reply 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.
quote (:obj:`bool`): Optional. If set to :obj:`True`, the reply is sent as an actual reply
to the message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter will
be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
Parameters:
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
receive a notification with no sound.
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
read timeout from the server (instead of the one specified during creation of the
connection pool).
quote (:obj:`bool`, opitonal): If set to ``True``, the reply is sent as an actual reply 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.
quote (:obj:`bool`, optional): If set to :obj:`True`, the reply is sent as an actual reply
to the message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter will
be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
"""
def __init__(self,
parse_mode=None,

32
telegram/ext/dictpersistence.py
View file

@ -43,11 +43,11 @@ class DictPersistence(BasePersistence):
Args:
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
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
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 on creating this persistence. Default is ``""``.
chat_data_json (:obj:`str`, optional): Json string that will be used to reconstruct
@ -107,7 +107,7 @@ class DictPersistence(BasePersistence):
@property
def user_data(self):
""":obj:`dict`: The user_data as a dict"""
""":obj:`dict`: The user_data as a dict."""
return self._user_data
@property
@ -120,7 +120,7 @@ class DictPersistence(BasePersistence):
@property
def chat_data(self):
""":obj:`dict`: The chat_data as a dict"""
""":obj:`dict`: The chat_data as a dict."""
return self._chat_data
@property
@ -133,7 +133,7 @@ class DictPersistence(BasePersistence):
@property
def bot_data(self):
""":obj:`dict`: The bot_data as a dict"""
""":obj:`dict`: The bot_data as a dict."""
return self._bot_data
@property
@ -146,7 +146,7 @@ class DictPersistence(BasePersistence):
@property
def conversations(self):
""":obj:`dict`: The conversations as a dict"""
""":obj:`dict`: The conversations as a dict."""
return self._conversations
@property
@ -158,7 +158,8 @@ class DictPersistence(BasePersistence):
return encode_conversations_to_json(self.conversations)
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:
:obj:`defaultdict`: The restored user data.
@ -170,10 +171,11 @@ class DictPersistence(BasePersistence):
return deepcopy(self.user_data)
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:
:obj:`defaultdict`: The restored user data.
:obj:`defaultdict`: The restored chat data.
"""
if self.chat_data:
pass
@ -182,10 +184,10 @@ class DictPersistence(BasePersistence):
return deepcopy(self.chat_data)
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:
:obj:`defaultdict`: The restored user data.
:obj:`dict`: The restored bot data.
"""
if self.bot_data:
pass
@ -195,10 +197,10 @@ class DictPersistence(BasePersistence):
def get_conversations(self, name):
"""Returns the conversations created from the ``conversations_json`` or an empty
defaultdict.
:obj:`dict`.
Returns:
:obj:`defaultdict`: The restored user data.
:obj:`dict`: The restored conversations data.
"""
if self.conversations:
pass
@ -210,7 +212,7 @@ class DictPersistence(BasePersistence):
"""Will update the conversations for the given handler.
Args:
name (:obj:`str`): The handlers name.
name (:obj:`str`): The handler's name.
key (:obj:`tuple`): The key the state is changed for.
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.
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
store data that should be persistent over restarts
store data that should be persistent over restarts.
Args:
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`
instance to pass onto handler callbacks.
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
store data that should be persistent over restarts
use_context (:obj:`bool`, optional): If set to ``True`` Use the context based callback API.
During the deprecation period of the old API the default is ``False``. **New users**:
set this to ``True``.
store data that should be persistent over restarts.
use_context (:obj:`bool`, optional): If set to :obj:`True` Use the context based
callback API.
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
a `filter` method that returns a boolean: `True` if the message should be handled, `False`
otherwise. Note that the filters work only as class instances, not actual class objects
(so remember to initialize your filter classes).
a :meth:`filter` method that returns a boolean: :obj:`True` if the message should be
handled, :obj:`False` otherwise. Note that the filters work only as class instances, not
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)
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.
Attributes:
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
will run the filter on :attr:`update.effective_message``. Default is ``False``.
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 :obj:`False`.
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
:class:`telegram.ext.CallbackContext`'s internal dict in most cases
@ -109,14 +109,14 @@ class BaseFilter(ABC):
"""This method must be overwritten.
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`.
Args:
update (:class:`telegram.Update`): The update that is tested.
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.
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.
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
``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`::
buttons = ['Start', 'Settings', 'Back']
@ -377,7 +377,7 @@ class Filters:
command = _Command()
"""
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.
Examples::
@ -390,13 +390,13 @@ class Filters:
Args:
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):
"""
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.
@ -404,8 +404,8 @@ class Filters:
Examples:
Use ``MessageHandler(Filters.regex(r'help'), callback)`` to capture all messages that
contain the word help. You can also use
``MessageHandler(Filters.regex(re.compile(r'help', re.IGNORECASE), callback)`` if
contain the word 'help'. You can also use
``MessageHandler(Filters.regex(re.compile(r'help', re.IGNORECASE)), callback)`` if
you want your pattern to be case insensitive. This approach is recommended
if you need to specify flags on your pattern.
@ -460,7 +460,7 @@ class Filters:
name = 'Filters.document'
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:
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.
Example:
Filters.documents.category('audio/') returns `True` for all types
of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav'
Filters.documents.category('audio/') returns :obj:`True` for all types
of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav'.
"""
def __init__(self, category):
@ -547,7 +547,7 @@ class Filters:
``Filters.document`` for all document messages.
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:
This Filter only filters by the mime_type of the document,
@ -557,13 +557,13 @@ class Filters:
Example:
``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")``.
audio: Same as ``Filters.document.category("audio")``.
image: Same as ``Filters.document.category("image")``.
video: Same as ``Filters.document.category("video")``.
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:
This Filter only filters by the mime_type of the document,
@ -1148,6 +1148,7 @@ officedocument.wordprocessingml.document")``-
def add_usernames(self, username):
"""
Add one or more users to the allowed usernames.
Args:
username(:obj:`str` | List[:obj:`str`], optional): Which username(s) to allow
through. Leading '@'s in usernames will be discarded.
@ -1163,6 +1164,7 @@ officedocument.wordprocessingml.document")``-
def add_bot_ids(self, bot_id):
"""
Add one or more users to the allowed user ids.
Args:
bot_id(:obj:`int` | List[:obj:`int`], optional): Which bot ID(s) to allow
through.
@ -1179,6 +1181,7 @@ officedocument.wordprocessingml.document")``-
def remove_usernames(self, username):
"""
Remove one or more users from allowed usernames.
Args:
username(:obj:`str` | List[:obj:`str`], optional): Which username(s) to disallow
through. Leading '@'s in usernames will be discarded.
@ -1194,6 +1197,7 @@ officedocument.wordprocessingml.document")``-
def remove_bot_ids(self, bot_id):
"""
Remove one or more users from allowed user ids.
Args:
bot_id(:obj:`int` | List[:obj:`int`], optional): Which bot ID(s) to disallow
through.
@ -1241,7 +1245,7 @@ officedocument.wordprocessingml.document")``-
chat_id(:obj:`int` | List[:obj:`int`], optional): Which chat ID(s) to allow
through.
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
is specified in :attr:`chat_ids` and :attr:`usernames`. Defaults to :obj:`False`
@ -1314,7 +1318,7 @@ officedocument.wordprocessingml.document")``-
Args:
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:
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.
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.
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
: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``
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.
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
: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.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
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.
Returns:
Either ``None`` or ``False`` if the update should not be handled. Otherwise an object
that will be passed to :attr:`handle_update` and :attr:`collect_additional_context`
when the update gets handled.
Either :obj:`None` or :obj:`False` if the update should not be handled. Otherwise an
object that will be passed to :meth:`handle_update` and
:meth:`collect_additional_context` when the update gets handled.
"""
def handle_update(self, update, dispatcher, check_result, context=None):
"""
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
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.
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
: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``
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.
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
: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.
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
should be handled by this handler.
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``.
Default is ``False``
Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks.
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``.
Default is ``False``
Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
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).
Defaults to now + ``job.interval``.
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:
@ -131,17 +131,17 @@ class JobQueue:
* :obj:`datetime.timedelta` will be interpreted as "time from now" in which the
job should run.
* :obj:`datetime.datetime` will be interpreted as a specific date and time at
which the job should run. If the timezone (``datetime.tzinfo``) is ``None``, UTC
will be assumed.
which the job should run. If the timezone (``datetime.tzinfo``) is :obj:`None`,
UTC will be assumed.
* :obj:`datetime.time` will be interpreted as a specific time of day at which the
job should run. This could be either today or, if the time has already passed,
tomorrow. If the timezone (``time.tzinfo``) is ``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
then ``when.tzinfo`` will define ``Job.tzinfo``. Otherwise UTC will be assumed.
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
``callback.__name__``.
@ -185,18 +185,18 @@ class JobQueue:
* :obj:`datetime.timedelta` will be interpreted as "time from now" in which the
job should run.
* :obj:`datetime.datetime` will be interpreted as a specific date and time at
which the job should run. If the timezone (``datetime.tzinfo``) is ``None``, UTC
will be assumed.
which the job should run. If the timezone (``datetime.tzinfo``) is :obj:`None`,
UTC will be assumed.
* :obj:`datetime.time` will be interpreted as a specific time of day at which the
job should run. This could be either today or, if the time has already passed,
tomorrow. If the timezone (``time.tzinfo``) is ``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
then ``first.tzinfo`` will define ``Job.tzinfo``. Otherwise UTC will be assumed.
Defaults to ``interval``
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
``callback.__name__``.
@ -234,16 +234,16 @@ class JobQueue:
``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.
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``.
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.
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
``callback.__name__``.
day_is_strict (:obj:`bool`, optional): If ``False`` and day > month.days, will pick
the last day in the month. Defaults to ``True``.
day_is_strict (:obj:`bool`, optional): If :obj:`False` and day > month.days, will pick
the last day in the month. Defaults to :obj:`True`.
Returns:
: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_is_strict (:obj:`bool`):
Specification as to whether the specified day of job should be strictly
respected. If day_is_strict is ``True`` it ignores months whereby the
specified date does not exist (e.g February 31st). If it set to ``False``,
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 :obj:`False`,
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
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.
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.
For stability reasons, this defaults to :obj:`False`, but it needs to be :obj:`True`
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
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.tzinfo``) is ``None``, UTC will be assumed.
(``time.tzinfo``) is :obj:`None`, UTC will be assumed.
``time.tzinfo`` will implicitly define ``Job.tzinfo``.
days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should
run. Defaults to ``EVERY_DAY``
context (:obj:`object`, optional): Additional data needed for the callback function.
Can be accessed through ``job.context`` in the callback. Defaults to ``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
``callback.__name__``.
@ -513,12 +513,12 @@ class Job:
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`,
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.
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
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__``.
days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should run.
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
``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.
Defaults to ``False``.
day_is_strict (:obj:`bool`, optional): If ``False`` and day > month.days, will pick the
last day in the month. Defaults to ``True``. Only relevant when ``is_monthly`` is
``True``.
Defaults to :obj:`False`.
day_is_strict (:obj:`bool`, optional): If :obj:`False` and day > month.days, will pick the
last day in the month. Defaults to :obj:`True`. Only relevant when ``is_monthly`` is
:obj:`True`.
"""
def __init__(self,
@ -635,7 +635,7 @@ class Job:
"""
:obj:`datetime.datetime`: Datetime for the next job execution.
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

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
the callback function.
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?
Default is ``None``.
Default is :obj:`None`.
edited_updates (:obj:`bool`): Should "edited" message updates be handled?
Default is ``None``.
Default is :obj:`None`.
Note:
: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
: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``
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.
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
: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.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
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.
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.
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.
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`
subclass exceptions. If not provided, exceptions are routed through dummy handler,
which re-raises them.
autostart (:obj:`bool`, optional): If True, processor is started immediately after object's
creation; if ``False``, should be started manually by `start` method. Defaults to True.
autostart (:obj:`bool`, optional): If :obj:`True`, processor is started immediately after
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
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
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.
``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))
# 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.
# So, message path is:
# 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``
subclass exceptions. If not provided, exceptions are routed through dummy handler,
which re-raises them.
autostart (:obj:`bool`, optional): If True, processors are started immediately after
object's creation; if ``False``, should be started manually by :attr:`start` method.
Defaults to ``True``.
autostart (:obj:`bool`, optional): If :obj:`True`, processors are started immediately after
object's creation; if :obj:`False`, should be started manually by :attr:`start` method.
Defaults to :obj:`True`.
"""
@ -198,7 +200,7 @@ class MessageQueue:
group_time_limit_ms=60000,
exc_route=None,
autostart=True):
# create accoring delay queues, use composition
# create according delay queues, use composition
self._all_delayq = DelayQueue(
burst_limit=all_burst_limit,
time_limit_ms=all_time_limit_ms,
@ -219,20 +221,20 @@ class MessageQueue:
self._group_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):
"""
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`.
Args:
promise (:obj:`callable`): Mainly the ``telegram.utils.promise.Promise`` (see Notes for
other callables), that is processed in delay queues.
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*
``DelayQueue`` (if set to ``False``), resulting in needed delays to avoid
hitting specified limits. Defaults to ``False``.
group*+*all* ``DelayQueue``s (if set to :obj:`True`), or only through *all*
``DelayQueue`` (if set to :obj:`False`), resulting in needed delays to avoid
hitting specified limits. Defaults to :obj:`False`.
Note:
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:
Args:
queued (:obj:`bool`, optional): If set to ``True``, the ``MessageQueue`` is used to 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
(as there's no obvious way to determine its type in other way at the moment).
queued (:obj:`bool`, optional): If set to :obj:`True`, the ``MessageQueue`` is used to
process output messages. Defaults to `self._is_queued_out`.
isgroup (:obj:`bool`, optional): If set to :obj:`True`, the message is meant to be
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
in `self._out_queue`. Defaults to ``False``.
in `self._out_queue`. Defaults to :obj:`False`.
Returns:
``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:
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
persistence class.
store_chat_data (:obj:`bool`): Optional. Whether user_data should be saved by this
persistence class.
store_bot_data (:obj:`bool`): Optional. Whether bot_data should be saved by this
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
``True``.
on_flush (:obj:`bool`, optional): When ``True`` will only save to file when :meth:`flush`
is called and keep data in memory until that happens. When ``False`` will store data
on any transaction *and* on call fo :meth:`flush`. Default is ``False``.
:obj:`True`.
on_flush (:obj:`bool`, optional): When :obj:`True` will only save to file when
:meth:`flush` is called and keep data in memory until that happens. When
:obj:`False` will store data on any transaction *and* on call to :meth:`flush`.
Default is :obj:`False`.
Args:
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
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
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
persistence class. Default is ``True`` .
single_file (:obj:`bool`, optional): When ``False`` will store 3 sperate files of
persistence class. Default is :obj:`True` .
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
``True``.
on_flush (:obj:`bool`, optional): When ``True`` will only save to file when :meth:`flush`
is called and keep data in memory until that happens. When ``False`` will store data
on any transaction *and* on call fo :meth:`flush`. Default is ``False``.
:obj:`True`.
on_flush (:obj:`bool`, optional): When :obj:`True` will only save to file when
:meth:`flush` is called and keep data in memory until that happens. When
:obj:`False` will store data on any transaction *and* on call to :meth:`flush`.
Default is :obj:`False`.
"""
def __init__(self, filename,
@ -119,7 +121,7 @@ class PicklePersistence(BasePersistence):
pickle.dump(data, f)
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:
:obj:`defaultdict`: The restored user data.
@ -139,7 +141,7 @@ class PicklePersistence(BasePersistence):
return deepcopy(self.user_data)
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:
:obj:`defaultdict`: The restored chat data.
@ -159,10 +161,10 @@ class PicklePersistence(BasePersistence):
return deepcopy(self.chat_data)
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:
:obj:`defaultdict`: The restored bot data.
:obj:`dict`: The restored bot data.
"""
if self.bot_data:
pass
@ -177,7 +179,7 @@ class PicklePersistence(BasePersistence):
return deepcopy(self.bot_data)
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:
name (:obj:`str`): The handlers name.
@ -202,7 +204,7 @@ class PicklePersistence(BasePersistence):
save the pickle file.
Args:
name (:obj:`str`): The handlers name.
name (:obj:`str`): The handler's name.
key (:obj:`tuple`): The key the state is changed for.
new_state (:obj:`tuple` | :obj:`any`): The new state for the given key.
"""
@ -217,8 +219,7 @@ class PicklePersistence(BasePersistence):
self.dump_singlefile()
def update_user_data(self, user_id, data):
"""Will update the user_data (if changed) and depending on :attr:`on_flush` save the
pickle file.
"""Will update the user_data and depending on :attr:`on_flush` save the pickle file.
Args:
user_id (:obj:`int`): The user the data might have been changed for.
@ -237,8 +238,7 @@ class PicklePersistence(BasePersistence):
self.dump_singlefile()
def update_chat_data(self, chat_id, data):
"""Will update the chat_data (if changed) and depending on :attr:`on_flush` save the
pickle file.
"""Will update the chat_data and depending on :attr:`on_flush` save the pickle file.
Args:
chat_id (:obj:`int`): The chat the data might have been changed for.
@ -257,8 +257,7 @@ class PicklePersistence(BasePersistence):
self.dump_singlefile()
def update_bot_data(self, data):
"""Will update the bot_data (if changed) and depending on :attr:`on_flush` save the
pickle file.
"""Will update the bot_data and depending on :attr:`on_flush` save the pickle file.
Args:
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
: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``
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.
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
: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.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
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
: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``
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.
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
: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.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
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
: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``
DEPRECATED: Please switch to context based callbacks.
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``.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
that contains new updates which can be used to insert updates. Default is :obj:`False`.
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
: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.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
"""

28
telegram/ext/regexhandler.py
View file

@ -50,7 +50,7 @@ class RegexHandler(MessageHandler):
the callback function.
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)``
@ -66,28 +66,28 @@ class RegexHandler(MessageHandler):
:class:`telegram.ext.ConversationHandler`.
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``.
Default is ``False``
Default is :obj:`False`
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``.
Default is ``False``
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
Default is :obj:`False`
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``
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``.
pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
that contains new updates which can be used to insert updates. Default is :obj:`False`.
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
:class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
which can be used to schedule new jobs. Default is ``False``.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``.
which can be used to schedule new jobs. Default is :obj:`False`.
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 :obj:`False`.
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 :obj:`False`.
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?
Default is ``True``.
Default is :obj:`True`.
edited_updates (:obj:`bool`, optional): Should "edited" message updates be handled? Default
is ``False``.
is :obj:`False`.
Raises:
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
: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``
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.
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
: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.
pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``user_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
DEPRECATED: Please switch to context based callbacks.
pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
``chat_data`` will be passed to the callback function. Default is ``False``.
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 :obj:`False`.
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
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
consecutive whitespace characters. Default is ``False``
consecutive whitespace characters. Default is :obj:`False`
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``
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.
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
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.
"""

12
telegram/ext/stringregexhandler.py
View file

@ -57,21 +57,21 @@ class StringRegexHandler(Handler):
:class:`telegram.ext.ConversationHandler`.
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``.
Default is ``False``
Default is :obj:`False`
DEPRECATED: Please switch to context based callbacks.
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``.
Default is ``False``
Default is :obj:`False`
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``
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.
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
: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.
"""

12
telegram/ext/typehandler.py
View file

@ -27,7 +27,7 @@ class TypeHandler(Handler):
Attributes:
type (:obj:`type`): The ``type`` of updates this handler should process.
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
passed to the callback function.
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
:class:`telegram.ext.ConversationHandler`.
strict (:obj:`bool`, optional): Use ``type`` instead of ``isinstance``.
Default is ``False``
pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
Default is :obj:`False`
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``
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.
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
: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.
"""

20
telegram/ext/updater.py
View file

@ -56,7 +56,7 @@ class Updater:
running (:obj:`bool`): Indicates if the updater is running.
persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to
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:
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.
user_sig_handler (:obj:`function`, optional): Takes ``signum, frame`` as positional
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
`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
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
(ignored if `dispatcher` argument is used). During the deprecation period of the old
API the default is ``False``. **New users**: set this to ``True``.
use_context (:obj:`bool`, optional): If set to :obj:`True` Use the context based callback
API (ignored if :attr:`dispatcher` argument is used). During the deprecation period of
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
store data that should be persistent over restarts (ignored if `dispatcher` argument is
used).
@ -233,7 +233,7 @@ class Updater:
Telegram in seconds. Default is 0.0.
timeout (:obj:`float`, optional): Passed to :attr:`telegram.Bot.get_updates`.
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
`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.
key (:obj:`str`, optional): Path to the SSL key file.
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
`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):
"""Perform a loop calling `action_cb`, retrying after network errors.
Stop condition for loop: `self.running` evaluates False or return value of `action_cb`
evaluates False.
Stop condition for loop: `self.running` evaluates :obj:`False` or return value of
`action_cb` evaluates :obj:`False`.
Args:
action_cb (:obj:`callable`): Network oriented callback function to call.
@ -554,7 +554,7 @@ class Updater:
self.logger.info('Received signal {} ({}), stopping...'.format(
signum, get_signal_name(signum)))
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.persistence.flush()
self.stop()

10
telegram/files/animation.py
View file

@ -22,7 +22,7 @@ from telegram import 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:
file_id (:obj:`str`): File identifier.
@ -32,8 +32,7 @@ class Animation(TelegramObject):
width (:obj:`int`): Video width 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.
thumb (:class:`telegram.PhotoSize`): Optional. Animation thumbnail as defined
by sender.
thumb (:class:`telegram.PhotoSize`): Optional. Animation thumbnail as defined by sender.
file_name (:obj:`str`): Optional. Original animation filename as defined by sender.
mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender.
file_size (:obj:`int`): Optional. File size.
@ -42,8 +41,9 @@ class Animation(TelegramObject):
Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and
for different bots file identifier.
file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
width (:obj:`int`): Video width 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.

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.
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
is supposed to be the same over time and for different bots.
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.
file_size (:obj:`int`): Optional. File size.
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.
Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and
for different bots file identifier.
file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be
the same over time and for different bots. Can't be used to download or reuse the file.
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
tags.
@ -51,7 +51,7 @@ class Audio(TelegramObject):
mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.
file_size (:obj:`int`, optional): File size.
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.
**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):
"""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:
file_id (:obj:`str`): Unique file identifier.
file_id (:obj:`str`): File identifier.
file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
@ -38,8 +39,8 @@ class Document(TelegramObject):
Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and
for different bots file identifier.
file_unique_id (:obj:`str`): Unique identifier for this file, which is supposed to be
the same over time and for different bots. Can't be used to download or reuse the file.
thumb (:class:`telegram.PhotoSize`, optional): Document thumbnail as defined by sender.
file_name (:obj:`str`, optional): Original filename as defined by sender.
mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.

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
: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:
Maximum file size to download is 20 MB
Maximum file size to download is 20 MB.
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
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
@ -47,8 +47,9 @@ class File(TelegramObject):
Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and
for different bots file identifier.
file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
file_size (:obj:`int`, optional): Optional. File size, if known.
file_path (:obj:`str`, optional): File path. Use :attr:`download` to get the file.
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.
Attributes:
input_file_content (:obj:`bytes`): The binaray content of the file to send.
filename (:obj:`str`): Optional, Filename for the file to be sent.
attach (:obj:`str`): Optional, attach id for sending multiple files.
input_file_content (:obj:`bytes`): The binary content of the file to send.
filename (:obj:`str`): Optional. Filename for the file to be sent.
attach (:obj:`str`): Optional. Attach id for sending multiple files.
Args:
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.
height (:obj:`int`): Optional. Video height.
duration (:obj:`int`): Optional. Video duration.
supports_streaming (:obj:`bool`): Optional. Pass True, if the uploaded video is suitable
for streaming.
supports_streaming (:obj:`bool`): Optional. Pass :obj:`True`, if the uploaded video is
suitable for streaming.
thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send.
Args:
@ -172,8 +172,8 @@ class InputMediaVideo(InputMedia):
width (:obj:`int`, optional): Video width.
height (:obj:`int`, optional): Video height.
duration (:obj:`int`, optional): Video duration.
supports_streaming (:obj:`bool`, optional): Pass True, if the uploaded video is suitable
for streaming.
supports_streaming (:obj:`bool`, optional): Pass :obj:`True`, if the uploaded video is
suitable for streaming.
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
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
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
: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
entities parsing.
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.
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
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
@ -37,8 +37,9 @@ class PhotoSize(TelegramObject):
Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and
for different bots file identifier.
file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
width (:obj:`int`): Photo width.
height (:obj:`int`): Photo height.
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.
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
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.
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
format.
emoji (:obj:`str`): Optional. Emoji associated with the sticker.
@ -44,12 +44,13 @@ class Sticker(TelegramObject):
Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and
for different bots file identifier.
file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
width (:obj:`int`): Sticker width.
height (:obj:`int`): Sticker height.
is_animated (:obj:`bool`): True, if the sticker is animated.
thumb (:class:`telegram.PhotoSize`, optional): Sticker thumbnail in the .webp or .jpg
is_animated (:obj:`bool`): :obj:`True`, if the sticker is animated.
thumb (:class:`telegram.PhotoSize`, optional): Sticker thumbnail in the .WEBP or .JPG
format.
emoji (:obj:`str`, optional): Emoji associated with 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
position where the mask should be placed.
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.
**kwargs (obj:`dict`): Arbitrary keyword arguments.
"""
@ -135,20 +137,20 @@ class StickerSet(TelegramObject):
Attributes:
name (:obj:`str`): Sticker set name.
title (:obj:`str`): Sticker set title.
is_animated (:obj:`bool`): True, if the sticker set contains animated stickers.
contains_masks (:obj:`bool`): True, if the sticker set contains masks.
is_animated (:obj:`bool`): :obj:`True`, if the sticker set contains animated stickers.
contains_masks (:obj:`bool`): :obj:`True`, if the sticker set contains masks.
stickers (List[:class:`telegram.Sticker`]): List of all set stickers.
thumb (:class:`telegram.PhotoSize`): Optional. Sticker set thumbnail in the .WEBP or .TGS
format
format.
Args:
name (:obj:`str`): Sticker set name.
title (:obj:`str`): Sticker set title.
is_animated (:obj:`bool`): True, if the sticker set contains animated stickers.
contains_masks (:obj:`bool`): True, if the sticker set contains masks.
is_animated (:obj:`bool`): :obj:`True`, if the sticker set contains animated stickers.
contains_masks (:obj:`bool`): :obj:`True`, if the sticker set contains masks.
stickers (List[:class:`telegram.Sticker`]): List of all set stickers.
thumb (:class:`telegram.PhotoSize`, optional): Sticker set thumbnail in the .WEBP or .TGS
format
format.
"""
@ -189,6 +191,7 @@ class MaskPosition(TelegramObject):
Attributes:
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
size, from left to right.
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:
: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:
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
size, from left to right. For example, choosing -1.0 will place mask just to the left
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.
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
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
@ -40,8 +40,9 @@ class Video(TelegramObject):
Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and
for different bots file identifier.
file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
width (:obj:`int`): Video width 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.

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).
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
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
@ -38,9 +38,11 @@ class VideoNote(TelegramObject):
Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and
for different bots file identifier.
length (:obj:`int`): Video width and height as defined by sender.
file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
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.
thumb (:class:`telegram.PhotoSize`, optional): Video thumbnail.
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.
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
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
@ -37,8 +37,9 @@ class Voice(TelegramObject):
Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and
for different bots file identifier.
file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
duration (:obj:`int`, optional): Duration of the audio in seconds as defined by sender.
mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.
file_size (:obj:`int`, optional): File size.

7
telegram/forcereply.py
View file

@ -29,15 +29,16 @@ class ForceReply(ReplyMarkup):
to sacrifice privacy mode.
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.
Args:
selective (:obj:`bool`, optional): Use this parameter if you want to force reply from
specific users only. Targets:
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
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 message.
**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):
"""
This object represents a game. Use BotFather to create and edit games, their short names will
act as unique identifiers.
This object represents a game. Use `BotFather <https://t.me/BotFather>`_ to create and edit
games, their short names will act as unique identifiers.
Attributes:
title (:obj:`str`): Title of the game.
@ -35,11 +35,12 @@ class Game(TelegramObject):
in chats.
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
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
appear in text, such as usernames, URLs, bot commands, etc.
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:
title (:obj:`str`): Title of the game.
@ -48,12 +49,13 @@ class Game(TelegramObject):
in chats.
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
when the bot calls set_game_score, or manually edited using edit_message_text.
0-4096 characters. Also found as ``telegram.constants.MAX_MESSAGE_LENGTH``.
when the bot calls :meth:`telegram.Bot.set_game_score`, or manually edited
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
appear in text, such as usernames, URLs, bot commands, etc.
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
be launched when the user presses the button. This type of button must always be
the ``first`` button in the first row.
pay (:obj:`bool`, optional): Specify True, to send a Pay button. This type of button must
always be the ``first`` button in the first row.
pay (:obj:`bool`, optional): Specify :obj:`True`, to send a Pay button. This type of button
must always be the ``first`` button in the first row.
**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.
Attributes:
inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): Array of button rows,
each represented by an Array of InlineKeyboardButton objects.
inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): List of button rows,
each represented by a list of InlineKeyboardButton objects.
Args:
inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): Array of button rows,
each represented by an Array of InlineKeyboardButton objects.
inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): List of button rows,
each represented by a list of InlineKeyboardButton objects.
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
"""

6
telegram/inline/inlinequery.py
View file

@ -85,9 +85,9 @@ class InlineQuery(TelegramObject):
query.
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.
is_personal (:obj:`bool`, optional): Pass True, if results may be cached on the server
side only for the user that sent the query. By default, results may be returned to
any user who sends the same query.
is_personal (:obj:`bool`, optional): Pass :obj:`True`, if results may be cached on the
server side only for the user that sent the query. By default, 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 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

8
telegram/inline/inlinequeryresultarticle.py
View file

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

2
telegram/inline/inlinequeryresultgame.py
View file

@ -22,7 +22,7 @@ from telegram import InlineQueryResult
class InlineQueryResultGame(InlineQueryResult):
"""Represents a Game.
"""Represents a :class:`telegram.Game`.
Attributes:
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_height (:obj:`int`): Optional. Height 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.
title (:obj:`str`): Optional. Title for the result.
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_height (:obj:`int`, optional): Height 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_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”.
thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for
the result.
thumb_mime_type (:obj:`str`, optional): MIME type of the thumbnail, must be one of
``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``.
title (:obj:`str`, optional): Title for the result.
caption (:obj:`str`, optional): Caption of the GIF file to be sent, 0-1024 characters
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_height (:obj:`int`): Optional. Video height.
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.
title (:obj:`str`): Optional. Title for the result.
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.
thumb_url (:obj:`str`): URL of the static thumbnail (jpeg or gif) for the result.
thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail, must be one of
“image/jpeg”, “image/gif”, or “video/mp4”. Defaults to “image/jpeg”.
``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``.
title (:obj:`str`, optional): Title for the result.
caption (:obj:`str`, optional): Caption of the MPEG-4 file to be sent, 0-1024 characters
after entities parsing.

3
telegram/inline/inputlocationmessagecontent.py
View file

@ -28,7 +28,8 @@ class InputLocationMessageContent(InputMessageContent):
Attributes:
latitude (:obj:`float`): Latitude 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:
latitude (:obj:`float`): Latitude 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
parsing.
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
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
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
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
sent message.
**kwargs (:obj:`dict`): Arbitrary keyword arguments.

12
telegram/keyboardbutton.py
View file

@ -31,17 +31,17 @@ class KeyboardButton(TelegramObject):
Attributes:
text (:obj:`str`): Text of the button.
request_contact (:obj:`bool`): Optional. If the user's phone number will be sent.
request_location (:obj:`bool`): Optional. If the user's current location will be sent.
request_contact (:obj:`bool`): Optional. The user's phone number 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.
Args:
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.
request_contact (:obj:`bool`, optional): If True, the user's phone number will be 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
when the button is pressed. Available in private chats only.
request_contact (:obj:`bool`, optional): If :obj:`True`, the user's phone number will be
sent as a contact when the button is pressed. Available in private chats only.
request_location (:obj:`bool`, optional): If :obj:`True`, the user's current location will
be sent when the button is pressed. Available in private chats only.
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
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.
bot_username (:obj:`str`): Optional. Username of a bot, which will be used for user
authorization.
request_write_access (:obj:`bool`): Optional. Pass True to request the permission for your
bot to send messages to the user.
request_write_access (:obj:`bool`): Optional. Pass :obj:`True` to request the permission
for your bot to send messages to the user.
Args:
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,
the original URL without information about the user will be opened. The data added is
the same as described in Receiving authorization data.
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.
the same as described in
`Receiving authorization data
<https://core.telegram.org/widgets/login#receiving-authorization-data>`_
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
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
with the bot. See Linking your domain to the bot for more details.
request_write_access (:obj:`bool`, optional): Pass True to request the permission for your
bot to send messages to the user.
with the bot. See
`Linking your domain to the bot
<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):

158
telegram/message.py
View file

@ -116,7 +116,7 @@ class Message(TelegramObject):
Args:
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.
date (:class:`datetime.datetime`): Date the message was sent in Unix time. Converted to
:class:`datetime.datetime`.
@ -167,17 +167,19 @@ class Message(TelegramObject):
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
members).
caption (:obj:`str`, optional): Caption for the document, photo or video, 0-1024
characters.
caption (:obj:`str`, optional): Caption for the animation, audio, document, photo, video
or voice, 0-1024 characters.
contact (:class:`telegram.Contact`, optional): Message is a shared contact, information
about the contact.
location (:class:`telegram.Location`, optional): Message is a shared location, information
about the location.
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,
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_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.
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.
@ -209,8 +211,8 @@ class Message(TelegramObject):
message about a successful payment, information about the payment.
connected_website (:obj:`str`, optional): The domain name of the website on which the user
has logged in.
forward_signature (:obj:`str`, optional): Signature of the post author for messages
forwarded from channels.
forward_signature (:obj:`str`, optional): For messages forwarded from channels, signature
of the post author if present.
author_signature (:obj:`str`, optional): Signature of the post author for messages
in channels.
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.
via_bot (:class:`telegram.User`, optional): Message was sent through an inline bot.
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
:attr:`reply_text` and friends.
@ -435,7 +437,7 @@ class Message(TelegramObject):
or :class:`telegram.Video`
or :class:`telegram.VideoNote`
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:
@ -502,9 +504,9 @@ class Message(TelegramObject):
bot.send_message(update.message.chat_id, *args, **kwargs)
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
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.
Returns:
@ -520,12 +522,16 @@ class Message(TelegramObject):
bot.send_message(update.message.chat_id, parse_mode=ParseMode.MARKDOWN, *args,
**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:
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
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.
Returns:
@ -547,9 +553,9 @@ class Message(TelegramObject):
Sends a message with markdown version 2 formatting.
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
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.
Returns:
@ -570,9 +576,9 @@ class Message(TelegramObject):
Sends a message with HTML formatting.
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
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.
Returns:
@ -591,10 +597,10 @@ class Message(TelegramObject):
bot.send_media_group(update.message.chat_id, *args, **kwargs)
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``,
this parameter 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:
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)
Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an 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 private chats.
quote (:obj:`bool`, optional): If set to :obj:`True`, the photo is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
this parameter will be ignored. Default: :obj:`True` in group chats and
:obj:`False` in private chats.
Returns:
: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)
Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the audio is sent as an 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 private chats.
quote (:obj:`bool`, optional): If set to :obj:`True`, the audio is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
this parameter will be ignored. Default: :obj:`True` in group chats and
:obj:`False` in private chats.
Returns:
: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)
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
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.
Returns:
@ -663,10 +671,10 @@ class Message(TelegramObject):
bot.send_animation(update.message.chat_id, *args, **kwargs)
Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the animation is sent as an 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
private chats.
quote (:obj:`bool`, optional): If set to :obj:`True`, the animation is sent as an
actual reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
this parameter will be ignored. Default: :obj:`True` in group chats and
:obj:`False` in private chats.
Returns:
: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)
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
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.
Returns:
@ -699,9 +707,9 @@ class Message(TelegramObject):
bot.send_video(update.message.chat_id, *args, **kwargs)
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
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.
Returns:
@ -717,10 +725,10 @@ class Message(TelegramObject):
bot.send_video_note(update.message.chat_id, *args, **kwargs)
Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the video note is sent as an 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
private chats.
quote (:obj:`bool`, optional): If set to :obj:`True`, the video note is sent as an
actual reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
this parameter will be ignored. Default: :obj:`True` in group chats and
:obj:`False` in private chats.
Returns:
: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)
Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the voice note is sent as an 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
private chats.
quote (:obj:`bool`, optional): If set to :obj:`True`, the voice note is sent as an
actual reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
this parameter will be ignored. Default: :obj:`True` in group chats and
:obj:`False` in private chats.
Returns:
: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)
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
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.
Returns:
@ -771,9 +779,9 @@ class Message(TelegramObject):
bot.send_venue(update.message.chat_id, *args, **kwargs)
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
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.
Returns:
@ -789,9 +797,9 @@ class Message(TelegramObject):
bot.send_contact(update.message.chat_id, *args, **kwargs)
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
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.
Returns:
@ -807,9 +815,10 @@ class Message(TelegramObject):
bot.send_poll(update.message.chat_id, *args, **kwargs)
Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the poll is sent as an 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 private chats.
quote (:obj:`bool`, optional): If set to :obj:`True`, the poll is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``,
this parameter will be ignored. Default: :obj:`True` in group chats and
:obj:`False` in private chats.
Returns:
: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)
Keyword Args:
quote (:obj:`bool`, optional): If set to ``True``, the dice is sent as an 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 private chats.
quote (:obj:`bool`, optional): If set to :obj:`True`, the dice is sent as an actual
reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
parameter will be ignored. Default: :obj:`True` in group chats and :obj:`False`
in private chats.
Returns:
:class:`telegram.Message`: On success, instance representing the message posted.
@ -950,7 +960,7 @@ class Message(TelegramObject):
Returns:
: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(
chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)
@ -970,7 +980,7 @@ class Message(TelegramObject):
Returns:
: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(
chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)
@ -990,7 +1000,7 @@ class Message(TelegramObject):
Returns:
: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(
chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)
@ -1010,7 +1020,7 @@ class Message(TelegramObject):
Returns:
: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(
chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)
@ -1024,7 +1034,7 @@ class Message(TelegramObject):
**kwargs)
Returns:
:obj:`bool`: On success, ``True`` is returned.
:obj:`bool`: On success, :obj:`True` is returned.
"""
return self.bot.delete_message(
@ -1039,8 +1049,8 @@ class Message(TelegramObject):
**kwargs)
Returns:
:class:`telegram.Poll`: On success, the stopped Poll with the
final results is returned.
:class:`telegram.Poll`: On success, the stopped Poll with the final results is
returned.
"""
return self.bot.stop_poll(
@ -1074,7 +1084,7 @@ class Message(TelegramObject):
be an entity that belongs to this message.
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
@ -1099,7 +1109,7 @@ class Message(TelegramObject):
be an entity that belongs to this message.
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
@ -1293,7 +1303,7 @@ class Message(TelegramObject):
HTML in the same way the original message was formatted.
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)
@ -1440,6 +1450,10 @@ class Message(TelegramObject):
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.
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:
: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.
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:
: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
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:
: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
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:
: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.
url (:obj:`str`): Optional. Url that will be opened after user taps on the text.
user (:class:`telegram.User`): Optional. The mentioned user.
language (:obj:`str`): Optional. Programming language of the entity
text
language (:obj:`str`): Optional. Programming language of the entity text.
Args:
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
(monowidth block), text_link (for clickable text URLs), text_mention (for users
without usernames).
url, email, phone_number, bold (bold text), italic (italic text), strikethrough,
code (monowidth string), pre (monowidth block), text_link (for clickable text URLs),
text_mention (for users without usernames).
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.
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.
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."""
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'
""":obj:`str`: 'MarkdownV2'"""
HTML = 'HTML'

2
telegram/passport/passportelementerrors.py
View file

@ -27,7 +27,7 @@ class PassportElementError(TelegramObject):
Attributes:
source (:obj:`str`): Error source.
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:
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.
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
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
@ -38,8 +38,9 @@ class PassportFile(TelegramObject):
Args:
file_id (:obj:`str`): Identifier for this file, which can be used to download
or reuse the file.
file_unique_id (:obj:`str`): Unique and the same over time and
for different bots file identifier.
file_unique_id (:obj:`str`): Unique identifier for this file, which
is supposed to be the same over time and for different bots.
Can't be used to download or reuse the file.
file_size (:obj:`int`): File size.
file_date (:obj:`int`): Unix time when the file was uploaded.
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.
currency (:obj:`str`): Three-letter ISO 4217 currency code.
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.
"""

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.
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,
not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp
parameter in currencies.json, it shows the number of digits past the decimal point for
each currency (2 for the majority of currencies).
not 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.
"""

25
telegram/payment/precheckoutquery.py
View file

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

12
telegram/payment/shippingquery.py
View file

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

10
telegram/payment/successfulpayment.py
View file

@ -37,13 +37,15 @@ class SuccessfulPayment(TelegramObject):
Args:
currency (:obj:`str`): Three-letter ISO 4217 currency code.
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
parameter in currencies.json, it shows the number of digits past the decimal point for
each currency (2 for the majority of currencies).
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).
invoice_payload (:obj:`str`): Bot specified invoice payload.
shipping_option_id (:obj:`str`, optional): Identifier of the shipping option chosen by the
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.
provider_payment_charge_id (:obj:`str`): Provider payment identifier.
**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.
options (List[:class:`PollOption`]): List of poll options.
total_voter_count (:obj:`int`): Total number of users that voted in the poll.
is_closed (:obj:`bool`): True, if the poll is closed.
is_anonymous (:obj:`bool`): True, if the poll is anonymous.
is_closed (:obj:`bool`): :obj:`True`, if the poll is closed.
is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous.
type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`.
allows_multiple_answers (:obj:`bool`): 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.
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.
@ -111,10 +111,10 @@ class Poll(TelegramObject):
id (:obj:`str`): Unique poll identifier.
question (:obj:`str`): Poll question, 1-255 characters.
options (List[:class:`PollOption`]): List of poll options.
is_closed (:obj:`bool`): True, if the poll is closed.
is_anonymous (:obj:`bool`): True, if the poll is anonymous.
is_closed (:obj:`bool`): :obj:`True`, if the poll is closed.
is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous.
type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`.
allows_multiple_answers (:obj:`bool`): 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.
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.

66
telegram/replykeyboardmarkup.py
View file

@ -40,20 +40,20 @@ class ReplyKeyboardMarkup(ReplyMarkup):
each represented by an Array of :class:`telegram.KeyboardButton` objects.
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
buttons). Defaults to false, in which case the custom keyboard is always of the same
height as the app's standard keyboard. Defaults to ``False``
buttons). Defaults to :obj:`False`, in which case the custom keyboard is always of the
same height as the app's standard keyboard.
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
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
specific users only. Targets:
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
message.
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 message.
Defaults to ``False``.
Defaults to :obj:`False`.
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
@ -97,28 +97,28 @@ class ReplyKeyboardMarkup(ReplyMarkup):
ReplyKeyboardMarkup([[button]], **kwargs)
Return an ReplyKeyboardMarkup from a single KeyboardButton
Return a ReplyKeyboardMarkup from a single KeyboardButton.
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
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
the same height as the app's standard keyboard.
Defaults to ``False``
rows of buttons). Defaults to :obj:`False`, in which case the custom keyboard is
always of the same height as the app's standard keyboard.
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 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``.
Defaults to :obj:`False`.
selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard
to specific users only. Targets:
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
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 message.
Defaults to ``False``.
Defaults to :obj:`False`.
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
"""
return cls([[button]],
@ -138,29 +138,28 @@ class ReplyKeyboardMarkup(ReplyMarkup):
ReplyKeyboardMarkup([button_row], **kwargs)
Return an ReplyKeyboardMarkup from a single row of KeyboardButtons
Return a ReplyKeyboardMarkup from a single row of KeyboardButtons.
Args:
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
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
the same height as the app's standard keyboard.
Defaults to ``False``
rows of buttons). Defaults to :obj:`False`, in which case the custom keyboard is
always of the same height as the app's standard keyboard.
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 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``.
Defaults to :obj:`False`.
selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard
to specific users only. Targets:
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
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 message.
Defaults to ``False``.
Defaults to :obj:`False`.
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
"""
@ -181,29 +180,28 @@ class ReplyKeyboardMarkup(ReplyMarkup):
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:
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
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
the same height as the app's standard keyboard.
Defaults to ``False``
rows of buttons). Defaults to :obj:`False`, in which case the custom keyboard is
always of the same height as the app's standard keyboard.
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 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``.
Defaults to :obj:`False`.
selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard
to specific users only. Targets:
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
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 message.
Defaults to ``False``.
Defaults to :obj:`False`.
**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
for specific users only. Targets:
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
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
message.
**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):

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.
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
in a non-anonymous poll. Bots receive new votes only in polls that were sent
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
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
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,
photo, sticker, etc.
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.
Only for invoices with flexible price.
pre_checkout_query (:class:`telegram.PreCheckoutQuery`, optional): New incoming
pre-checkout query. Contains full information about checkout
poll (:class:`telegram.Poll`, optional): New poll state. Bots receive only updates
about polls, which are sent or stopped by the bot
pre-checkout query. Contains full information about checkout.
poll (:class:`telegram.Poll`, optional): New poll state. Bots receive only updates about
stopped polls and polls, which are sent by the bot.
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
by the bot itself.
@ -117,7 +119,7 @@ class Update(TelegramObject):
def effective_user(self):
"""
: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:
@ -156,7 +158,7 @@ class Update(TelegramObject):
def effective_chat(self):
"""
: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:`shipping_query`, :attr:`pre_checkout_query`, :attr:`poll` and
:attr:`poll_answer`.
@ -189,7 +191,7 @@ class Update(TelegramObject):
def effective_message(self):
"""
: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:`shipping_query`, :attr:`pre_checkout_query`, :attr:`poll` and
:attr:`poll_answer`.

64
telegram/user.py
View file

@ -29,32 +29,32 @@ class User(TelegramObject):
Attributes:
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.
last_name (:obj:`str`): Optional. User's or bot's last name.
username (:obj:`str`): Optional. User's or bot's username.
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.
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.
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. :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.
Args:
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.
last_name (:obj:`str`, optional): User's or bot's last name.
username (:obj:`str`, optional): User's or bot's username.
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.
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.
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): :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.
"""
@ -143,6 +143,10 @@ class User(TelegramObject):
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:
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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
:obj:`True`: On success.
@ -253,8 +247,6 @@ class User(TelegramObject):
bot.send_contact(update.effective_user.id, *args, **kwargs)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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)
Where User is the current instance.
Returns:
: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
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:
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
``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:
(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):
"""
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:
unixtime (int): integer POSIX timestamp
unixtime (int): Integer POSIX timestamp.
tzinfo (:obj:`datetime.tzinfo`, optional): The timezone, the timestamp is to be converted
to. Defaults to UTC.
Returns:
timezone aware equivalent :obj:`datetime.datetime` value if ``timestamp`` is not
``None``; else ``None``
:obj:`None`; else :obj:`None`
"""
if unixtime is None:
return None
@ -265,8 +265,9 @@ def create_deep_linked_url(bot_username, payload=None, group=False):
Args:
bot_username (:obj:`str`): The username to link to
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
bot to. If `False`, opens a one-on-one conversation with the bot. Defaults to `False`.
group (:obj:`bool`, optional): If :obj:`True` the user is prompted to select a group to
add the bot to. If :obj:`False`, opens a one-on-one conversation with the bot.
Defaults to :obj:`False`.
Returns:
: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:
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.
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
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
most recent error that happened when trying to deliver an update via webhook.
max_connections (:obj:`int`, optional): Maximum allowed number of simultaneous HTTPS