diff --git a/CHANGES.rst b/CHANGES.rst index aafaa3205..c5d21e929 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -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`_) diff --git a/README.rst b/README.rst index 6e7fd493f..b1bef16ce 100644 --- a/README.rst +++ b/README.rst @@ -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 `_. Join us! -2. Report bugs, request new features or ask questions by `creating an issue `_. +2. In case you are unable to join our group due to Telegram restrictions, you can use our `IRC channel `_. -3. Our `Wiki pages `_ offer a growing amount of resources. +3. Report bugs, request new features or ask questions by `creating an issue `_. -4. You can even ask for help on Stack Overflow using the `python-telegram-bot tag `_. +4. Our `Wiki pages `_ offer a growing amount of resources. + +5. You can even ask for help on Stack Overflow using the `python-telegram-bot tag `_. diff --git a/examples/README.md b/examples/README.md index 4b2e21977..7407365d4 100644 --- a/examples/README.md +++ b/examples/README.md @@ -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. diff --git a/telegram/bot.py b/telegram/bot.py index 8f84ecf0d..86fb0ef63 100644 --- a/telegram/bot.py +++ b/telegram/bot.py @@ -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 `_. 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 `_, 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 `_. 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 diff --git a/telegram/callbackquery.py b/telegram/callbackquery.py index 6d37bd17b..13d526e1e 100644 --- a/telegram/callbackquery.py +++ b/telegram/callbackquery.py @@ -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: diff --git a/telegram/chat.py b/telegram/chat.py index a7b3254ac..fad8430e6 100644 --- a/telegram/chat.py +++ b/telegram/chat.py @@ -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. diff --git a/telegram/chataction.py b/telegram/chataction.py index 66fd3ff31..0ff4024d8 100644 --- a/telegram/chataction.py +++ b/telegram/chataction.py @@ -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'""" diff --git a/telegram/chatmember.py b/telegram/chatmember.py index 18f8f7fbd..aa3b9d1c1 100644 --- a/telegram/chatmember.py +++ b/telegram/chatmember.py @@ -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' diff --git a/telegram/chatpermissions.py b/telegram/chatpermissions.py index 6f135918a..18d8f7878 100644 --- a/telegram/chatpermissions.py +++ b/telegram/chatpermissions.py @@ -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. """ diff --git a/telegram/choseninlineresult.py b/telegram/choseninlineresult.py index a2074c238..16fd32c16 100644 --- a/telegram/choseninlineresult.py +++ b/telegram/choseninlineresult.py @@ -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 `_ in + order to receive these objects in updates. + """ def __init__(self, diff --git a/telegram/error.py b/telegram/error.py index 789042a36..32b9da7ae 100644 --- a/telegram/error.py +++ b/telegram/error.py @@ -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. """ diff --git a/telegram/ext/basepersistence.py b/telegram/ext/basepersistence.py index b4004a7c3..ce8f34f00 100644 --- a/telegram/ext/basepersistence.py +++ b/telegram/ext/basepersistence.py @@ -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. """ diff --git a/telegram/ext/callbackqueryhandler.py b/telegram/ext/callbackqueryhandler.py index 90417f0ce..7da74a921 100644 --- a/telegram/ext/callbackqueryhandler.py +++ b/telegram/ext/callbackqueryhandler.py @@ -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. """ diff --git a/telegram/ext/choseninlineresulthandler.py b/telegram/ext/choseninlineresulthandler.py index 349fd6207..69499e6c7 100644 --- a/telegram/ext/choseninlineresulthandler.py +++ b/telegram/ext/choseninlineresulthandler.py @@ -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. """ diff --git a/telegram/ext/commandhandler.py b/telegram/ext/commandhandler.py index bb483ce02..5b97f5d97 100644 --- a/telegram/ext/commandhandler.py +++ b/telegram/ext/commandhandler.py @@ -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: diff --git a/telegram/ext/conversationhandler.py b/telegram/ext/conversationhandler.py index 36a2901b0..811d82b10 100644 --- a/telegram/ext/conversationhandler.py +++ b/telegram/ext/conversationhandler.py @@ -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 diff --git a/telegram/ext/defaults.py b/telegram/ext/defaults.py index 918ad6d1d..06d32dfed 100644 --- a/telegram/ext/defaults.py +++ b/telegram/ext/defaults.py @@ -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, diff --git a/telegram/ext/dictpersistence.py b/telegram/ext/dictpersistence.py index 3d18aa148..84d4161ce 100644 --- a/telegram/ext/dictpersistence.py +++ b/telegram/ext/dictpersistence.py @@ -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. """ diff --git a/telegram/ext/dispatcher.py b/telegram/ext/dispatcher.py index 78e0daee4..828993c53 100644 --- a/telegram/ext/dispatcher.py +++ b/telegram/ext/dispatcher.py @@ -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`. """ diff --git a/telegram/ext/filters.py b/telegram/ext/filters.py index de1d85771..ba89877de 100644 --- a/telegram/ext/filters.py +++ b/telegram/ext/filters.py @@ -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: diff --git a/telegram/ext/handler.py b/telegram/ext/handler.py index c7706985f..8126a8fc5 100644 --- a/telegram/ext/handler.py +++ b/telegram/ext/handler.py @@ -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: diff --git a/telegram/ext/inlinequeryhandler.py b/telegram/ext/inlinequeryhandler.py index 518ac9a7a..39612b562 100644 --- a/telegram/ext/inlinequeryhandler.py +++ b/telegram/ext/inlinequeryhandler.py @@ -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. """ diff --git a/telegram/ext/jobqueue.py b/telegram/ext/jobqueue.py index 75ffb877d..b72193ea8 100644 --- a/telegram/ext/jobqueue.py +++ b/telegram/ext/jobqueue.py @@ -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 diff --git a/telegram/ext/messagehandler.py b/telegram/ext/messagehandler.py index b01259f7e..b0d4d8b5c 100644 --- a/telegram/ext/messagehandler.py +++ b/telegram/ext/messagehandler.py @@ -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: diff --git a/telegram/ext/messagequeue.py b/telegram/ext/messagequeue.py index 3c4bef749..abdb93822 100644 --- a/telegram/ext/messagequeue.py +++ b/telegram/ext/messagequeue.py @@ -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 diff --git a/telegram/ext/picklepersistence.py b/telegram/ext/picklepersistence.py index 2c484a7db..481153032 100644 --- a/telegram/ext/picklepersistence.py +++ b/telegram/ext/picklepersistence.py @@ -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`. diff --git a/telegram/ext/pollanswerhandler.py b/telegram/ext/pollanswerhandler.py index 7a7ccfed1..86132acd5 100644 --- a/telegram/ext/pollanswerhandler.py +++ b/telegram/ext/pollanswerhandler.py @@ -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. """ diff --git a/telegram/ext/pollhandler.py b/telegram/ext/pollhandler.py index e31e942d0..4ff191b8d 100644 --- a/telegram/ext/pollhandler.py +++ b/telegram/ext/pollhandler.py @@ -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. """ diff --git a/telegram/ext/precheckoutqueryhandler.py b/telegram/ext/precheckoutqueryhandler.py index 900eedf8a..0d3b7314c 100644 --- a/telegram/ext/precheckoutqueryhandler.py +++ b/telegram/ext/precheckoutqueryhandler.py @@ -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. """ diff --git a/telegram/ext/regexhandler.py b/telegram/ext/regexhandler.py index e8df56b11..4921f007d 100644 --- a/telegram/ext/regexhandler.py +++ b/telegram/ext/regexhandler.py @@ -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 diff --git a/telegram/ext/shippingqueryhandler.py b/telegram/ext/shippingqueryhandler.py index a6d2603f1..becc976c2 100644 --- a/telegram/ext/shippingqueryhandler.py +++ b/telegram/ext/shippingqueryhandler.py @@ -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. """ diff --git a/telegram/ext/stringcommandhandler.py b/telegram/ext/stringcommandhandler.py index 12cda5bf7..dc2e47536 100644 --- a/telegram/ext/stringcommandhandler.py +++ b/telegram/ext/stringcommandhandler.py @@ -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. """ diff --git a/telegram/ext/stringregexhandler.py b/telegram/ext/stringregexhandler.py index 2177664bb..ff1716470 100644 --- a/telegram/ext/stringregexhandler.py +++ b/telegram/ext/stringregexhandler.py @@ -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. """ diff --git a/telegram/ext/typehandler.py b/telegram/ext/typehandler.py index d39755e9e..3bb5e990b 100644 --- a/telegram/ext/typehandler.py +++ b/telegram/ext/typehandler.py @@ -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. """ diff --git a/telegram/ext/updater.py b/telegram/ext/updater.py index 07e72e0bb..827001937 100644 --- a/telegram/ext/updater.py +++ b/telegram/ext/updater.py @@ -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() diff --git a/telegram/files/animation.py b/telegram/files/animation.py index 2e63b1ca4..f0c371446 100644 --- a/telegram/files/animation.py +++ b/telegram/files/animation.py @@ -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. diff --git a/telegram/files/audio.py b/telegram/files/audio.py index 65a0deee7..aa25a4a7c 100644 --- a/telegram/files/audio.py +++ b/telegram/files/audio.py @@ -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. diff --git a/telegram/files/document.py b/telegram/files/document.py index 43ad2537f..746e7ffaa 100644 --- a/telegram/files/document.py +++ b/telegram/files/document.py @@ -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. diff --git a/telegram/files/file.py b/telegram/files/file.py index c97bc06dc..bde1ea6ea 100644 --- a/telegram/files/file.py +++ b/telegram/files/file.py @@ -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. diff --git a/telegram/files/inputfile.py b/telegram/files/inputfile.py index 96c7c02fe..7d052ac87 100644 --- a/telegram/files/inputfile.py +++ b/telegram/files/inputfile.py @@ -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. diff --git a/telegram/files/inputmedia.py b/telegram/files/inputmedia.py index 02157dcf5..32b8ef386 100644 --- a/telegram/files/inputmedia.py +++ b/telegram/files/inputmedia.py @@ -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 diff --git a/telegram/files/photosize.py b/telegram/files/photosize.py index 930321943..63996562f 100644 --- a/telegram/files/photosize.py +++ b/telegram/files/photosize.py @@ -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. diff --git a/telegram/files/sticker.py b/telegram/files/sticker.py index 08255a054..728350f30 100644 --- a/telegram/files/sticker.py +++ b/telegram/files/sticker.py @@ -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. diff --git a/telegram/files/video.py b/telegram/files/video.py index b49bf19ec..36d54e740 100644 --- a/telegram/files/video.py +++ b/telegram/files/video.py @@ -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. diff --git a/telegram/files/videonote.py b/telegram/files/videonote.py index e92528b7d..7562ffb93 100644 --- a/telegram/files/videonote.py +++ b/telegram/files/videonote.py @@ -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. diff --git a/telegram/files/voice.py b/telegram/files/voice.py index 22a4a70c2..901cdbbae 100644 --- a/telegram/files/voice.py +++ b/telegram/files/voice.py @@ -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. diff --git a/telegram/forcereply.py b/telegram/forcereply.py index d0cfbafa7..0a6d23c16 100644 --- a/telegram/forcereply.py +++ b/telegram/forcereply.py @@ -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. diff --git a/telegram/games/game.py b/telegram/games/game.py index 9fbf4b1cc..4b8ac7823 100644 --- a/telegram/games/game.py +++ b/telegram/games/game.py @@ -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 `_ 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 `_. 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 `_. """ diff --git a/telegram/inline/inlinekeyboardbutton.py b/telegram/inline/inlinekeyboardbutton.py index fda629bbe..3b297fd46 100644 --- a/telegram/inline/inlinekeyboardbutton.py +++ b/telegram/inline/inlinekeyboardbutton.py @@ -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. """ diff --git a/telegram/inline/inlinekeyboardmarkup.py b/telegram/inline/inlinekeyboardmarkup.py index 6a6c15175..3bb544098 100644 --- a/telegram/inline/inlinekeyboardmarkup.py +++ b/telegram/inline/inlinekeyboardmarkup.py @@ -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. """ diff --git a/telegram/inline/inlinequery.py b/telegram/inline/inlinequery.py index 3c76e4497..3c6df66a7 100644 --- a/telegram/inline/inlinequery.py +++ b/telegram/inline/inlinequery.py @@ -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 diff --git a/telegram/inline/inlinequeryresultarticle.py b/telegram/inline/inlinequeryresultarticle.py index cb13aae8c..6abb4dcd8 100644 --- a/telegram/inline/inlinequeryresultarticle.py +++ b/telegram/inline/inlinequeryresultarticle.py @@ -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. diff --git a/telegram/inline/inlinequeryresultcachedvoice.py b/telegram/inline/inlinequeryresultcachedvoice.py index dfa2ac3af..91bd11aa2 100644 --- a/telegram/inline/inlinequeryresultcachedvoice.py +++ b/telegram/inline/inlinequeryresultcachedvoice.py @@ -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. """ diff --git a/telegram/inline/inlinequeryresultgame.py b/telegram/inline/inlinequeryresultgame.py index 03cc34b12..fee463216 100644 --- a/telegram/inline/inlinequeryresultgame.py +++ b/telegram/inline/inlinequeryresultgame.py @@ -22,7 +22,7 @@ from telegram import InlineQueryResult class InlineQueryResultGame(InlineQueryResult): - """Represents a Game. + """Represents a :class:`telegram.Game`. Attributes: type (:obj:`str`): 'game'. diff --git a/telegram/inline/inlinequeryresultgif.py b/telegram/inline/inlinequeryresultgif.py index df8de2089..21bdb9687 100644 --- a/telegram/inline/inlinequeryresultgif.py +++ b/telegram/inline/inlinequeryresultgif.py @@ -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. diff --git a/telegram/inline/inlinequeryresultmpeg4gif.py b/telegram/inline/inlinequeryresultmpeg4gif.py index 9bbd59ad4..5e101fd63 100644 --- a/telegram/inline/inlinequeryresultmpeg4gif.py +++ b/telegram/inline/inlinequeryresultmpeg4gif.py @@ -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. diff --git a/telegram/inline/inputlocationmessagecontent.py b/telegram/inline/inputlocationmessagecontent.py index 7375e073a..b3567d5f5 100644 --- a/telegram/inline/inputlocationmessagecontent.py +++ b/telegram/inline/inputlocationmessagecontent.py @@ -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. diff --git a/telegram/inline/inputtextmessagecontent.py b/telegram/inline/inputtextmessagecontent.py index d23aa694c..24e130bbe 100644 --- a/telegram/inline/inputtextmessagecontent.py +++ b/telegram/inline/inputtextmessagecontent.py @@ -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. diff --git a/telegram/keyboardbutton.py b/telegram/keyboardbutton.py index 0b2cf5023..72b969fe7 100644 --- a/telegram/keyboardbutton.py +++ b/telegram/keyboardbutton.py @@ -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. diff --git a/telegram/loginurl.py b/telegram/loginurl.py index 81a44abe4..723519268 100644 --- a/telegram/loginurl.py +++ b/telegram/loginurl.py @@ -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 + `_ 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 `_ + 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 + `_ + 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 `_ """ def __init__(self, url, forward_text=None, bot_username=None, request_write_access=None): diff --git a/telegram/message.py b/telegram/message.py index b71407013..6bf90265d 100644 --- a/telegram/message.py +++ b/telegram/message.py @@ -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. diff --git a/telegram/messageentity.py b/telegram/messageentity.py index 5328ee5fe..d61567ae5 100644 --- a/telegram/messageentity.py +++ b/telegram/messageentity.py @@ -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. """ diff --git a/telegram/parsemode.py b/telegram/parsemode.py index 40a966f21..96ee5a111 100644 --- a/telegram/parsemode.py +++ b/telegram/parsemode.py @@ -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' diff --git a/telegram/passport/passportelementerrors.py b/telegram/passport/passportelementerrors.py index 185d54d46..352204b45 100644 --- a/telegram/passport/passportelementerrors.py +++ b/telegram/passport/passportelementerrors.py @@ -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. diff --git a/telegram/passport/passportfile.py b/telegram/passport/passportfile.py index 4936ab608..580696546 100644 --- a/telegram/passport/passportfile.py +++ b/telegram/passport/passportfile.py @@ -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. diff --git a/telegram/payment/invoice.py b/telegram/payment/invoice.py index 4993f9b87..7027f99a7 100644 --- a/telegram/payment/invoice.py +++ b/telegram/payment/invoice.py @@ -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 `_, + 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. """ diff --git a/telegram/payment/labeledprice.py b/telegram/payment/labeledprice.py index 7fc08d30c..57ca52861 100644 --- a/telegram/payment/labeledprice.py +++ b/telegram/payment/labeledprice.py @@ -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 `_, + 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. """ diff --git a/telegram/payment/precheckoutquery.py b/telegram/payment/precheckoutquery.py index ead678252..c5df4a5d6 100644 --- a/telegram/payment/precheckoutquery.py +++ b/telegram/payment/precheckoutquery.py @@ -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 `_, + 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. """ diff --git a/telegram/payment/shippingquery.py b/telegram/payment/shippingquery.py index f0bc2d341..fe07ddbac 100644 --- a/telegram/payment/shippingquery.py +++ b/telegram/payment/shippingquery.py @@ -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. diff --git a/telegram/payment/successfulpayment.py b/telegram/payment/successfulpayment.py index db010ad3d..2d7ae67dc 100644 --- a/telegram/payment/successfulpayment.py +++ b/telegram/payment/successfulpayment.py @@ -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 `_, + 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. diff --git a/telegram/poll.py b/telegram/poll.py index d8544e8ac..943176d52 100644 --- a/telegram/poll.py +++ b/telegram/poll.py @@ -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. diff --git a/telegram/replykeyboardmarkup.py b/telegram/replykeyboardmarkup.py index c1f4d9ebc..c7f6005da 100644 --- a/telegram/replykeyboardmarkup.py +++ b/telegram/replykeyboardmarkup.py @@ -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. """ diff --git a/telegram/replykeyboardremove.py b/telegram/replykeyboardremove.py index 5474e36fd..edcc30835 100644 --- a/telegram/replykeyboardremove.py +++ b/telegram/replykeyboardremove.py @@ -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): diff --git a/telegram/update.py b/telegram/update.py index c6094d89e..cbb5666ea 100644 --- a/telegram/update.py +++ b/telegram/update.py @@ -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`. diff --git a/telegram/user.py b/telegram/user.py index 7aa254ee7..9b2963bbd 100644 --- a/telegram/user.py +++ b/telegram/user.py @@ -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. diff --git a/telegram/utils/helpers.py b/telegram/utils/helpers.py index b5b766909..21f750b64 100644 --- a/telegram/utils/helpers.py +++ b/telegram/utils/helpers.py @@ -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 diff --git a/telegram/webhookinfo.py b/telegram/webhookinfo.py index e063035fc..0d5815a38 100644 --- a/telegram/webhookinfo.py +++ b/telegram/webhookinfo.py @@ -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