From 2d2cede442caaa7ff039ef7e641fe7c9dcf5e1ba Mon Sep 17 00:00:00 2001 From: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Date: Mon, 27 Jun 2022 18:58:51 +0200 Subject: [PATCH] Documentation Improvements (#3103, #3121, #3098) Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Co-authored-by: David Co-authored-by: Harshil Mehta <37377066+harshil21@users.noreply.github.com> Co-authored-by: poolitzer Co-authored-by: Alex <53974096+ExalFabu@users.noreply.github.com> --- AUTHORS.rst | 1 + README.rst | 4 +- README_RAW.rst | 4 +- docs/requirements-docs.txt | 4 +- telegram/_bot.py | 66 ++++++++++++++++-------- telegram/_inline/inlinekeyboardbutton.py | 6 +-- telegram/ext/_application.py | 3 +- telegram/ext/_callbackdatacache.py | 3 +- telegram/ext/_jobqueue.py | 17 +++--- 9 files changed, 69 insertions(+), 39 deletions(-) diff --git a/AUTHORS.rst b/AUTHORS.rst index d5565b8c0..ada18a4ce 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -46,6 +46,7 @@ The following wonderful people contributed directly or indirectly to this projec - `Evan Haberecht `_ - `Evgeny Denisov `_ - `evgfilim1 `_ +- `ExalFabu `_ - `franciscod `_ - `gamgi `_ - `Gauthamram Ravichandran `_ diff --git a/README.rst b/README.rst index c7ea960a9..9de229707 100644 --- a/README.rst +++ b/README.rst @@ -34,7 +34,7 @@ :target: https://github.com/python-telegram-bot/python-telegram-bot/ :alt: Github Actions workflow -.. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg +.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot :alt: Code coverage @@ -149,7 +149,7 @@ Resources ========= - The `package documentation `_ is the technical reference for ``python-telegram-bot``. - It contains descriptions of all available classes, modules, methods and arguments. + It contains descriptions of all available classes, modules, methods and arguments as well as the `changelog `_. - The `wiki `_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation. - Our `examples section `_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``. Even if it is not your approach for learning, please take a look at ``echobot.py``. It is the de facto base for most of the bots out there. diff --git a/README_RAW.rst b/README_RAW.rst index 813139fef..04e1ce75f 100644 --- a/README_RAW.rst +++ b/README_RAW.rst @@ -34,7 +34,7 @@ :target: https://github.com/python-telegram-bot/python-telegram-bot/ :alt: Github Actions workflow -.. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg +.. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot :alt: Code coverage @@ -146,7 +146,7 @@ Resources ========= - The `package documentation `_ is the technical reference for ``python-telegram-bot``. - It contains descriptions of all available classes, modules, methods and arguments. + It contains descriptions of all available classes, modules, methods and arguments as well as the `changelog `_. - The `wiki `_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation. - Our `examples section `_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``. Even if it is not your approach for learning, please take a look at ``echobot.py``. It is the de facto base for most of the bots out there. diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index e1b3231bb..6d425e4ae 100644 --- a/docs/requirements-docs.txt +++ b/docs/requirements-docs.txt @@ -1,5 +1,5 @@ -sphinx==5.0.1 +sphinx==5.0.2 sphinx-pypi-upload -furo==2022.6.4.1 +furo==2022.6.21 sphinx-paramlinks==0.5.4 sphinxcontrib-mermaid==0.7.1 \ No newline at end of file diff --git a/telegram/_bot.py b/telegram/_bot.py index 8f9f9e47d..46c0cfa04 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -1612,7 +1612,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): changed in the future. Note: - ``thumb`` will be ignored for small files, for which Telegram can easily + :paramref:`thumb` will be ignored for small files, for which Telegram can easily generate thumb nails. However, this behaviour is undocumented and might be changed by Telegram. @@ -3025,7 +3025,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager): seconds from the current time they are considered to be banned forever. Applied for supergroups and channels only. For timezone naive :obj:`datetime.datetime` objects, the default timezone of the - bot will be used. + bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is + used. revoke_messages (:obj:`bool`, optional): Pass :obj:`True` to delete all messages from the chat for the user that is being removed. If :obj:`False`, the user will be able to see messages in the group that were sent before the user was removed. @@ -3373,6 +3374,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager): """ Use this method to edit text and game messages. + Note: + It is currently only possible to edit messages without + :attr:`telegram.Message.reply_markup` or with inline keyboards. + Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not specified. Unique identifier for the target chat or username of the target channel @@ -3465,6 +3470,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager): """ Use this method to edit captions of messages. + Note: + It is currently only possible to edit messages without + :attr:`telegram.Message.reply_markup` or with inline keyboards + Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not specified. Unique identifier for the target chat or username of the target channel @@ -3553,7 +3562,11 @@ class Bot(TelegramObject, AbstractAsyncContextManager): is part of a message album, then it can be edited only to an audio for audio albums, only to a document for document albums and to a photo or a video otherwise. When an inline message is edited, a new file can't be uploaded; use a previously uploaded file via its - ``file_id`` or specify a URL. + :attr:`~telegram.File.file_id` or specify a URL. + + Note: + It is currently only possible to edit messages without + :attr:`telegram.Message.reply_markup` or with inline keyboards Args: media (:class:`telegram.InputMedia`): An object for a new media content @@ -3629,6 +3642,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager): Use this method to edit only the reply markup of messages sent by the bot or via the bot (for inline bots). + Note: + It is currently only possible to edit messages without + :attr:`telegram.Message.reply_markup` or with inline keyboards + Args: chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not specified. Unique identifier for the target chat or username of the target channel @@ -4632,7 +4649,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): suggested amounts of tips in the *smallest* units of the currency (integer, **not** float/double). At most 4 suggested tip amounts can be specified. The suggested tip amounts must be positive, passed in a strictly increased order and must not exceed - ``max_tip_amount``. + :paramref:`max_tip_amount`. .. versionadded:: 13.5 start_parameter (:obj:`str`, optional): Unique deep-linking parameter. If left empty, @@ -4776,10 +4793,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager): api_kwargs: JSONDict = None, ) -> bool: """ - If you sent an invoice requesting a shipping address and the parameter ``is_flexible`` was - specified, the Bot API will send an :class:`telegram.Update` with a - :attr:`telegram.Update.shipping_query` field to the bot. Use this method to reply to - shipping queries. + If you sent an invoice requesting a shipping address and the parameter + :paramref:`send_invoice.is_flexible` was specified, the Bot API will send an + :class:`telegram.Update` with a :attr:`telegram.Update.shipping_query` field to the bot. + Use this method to reply to shipping queries. Args: shipping_query_id (:obj:`str`): Unique identifier for the query to be answered. @@ -4999,7 +5016,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager): days or less than 30 seconds from the current time, they are considered to be restricted forever. For timezone naive :obj:`datetime.datetime` objects, the default timezone of the - bot will be used. + bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is + used. permissions (:class:`telegram.ChatPermissions`): An object for new user permissions. @@ -5383,7 +5401,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager): expire_date (:obj:`int` | :obj:`datetime.datetime`, optional): Date when the link will expire. Integer input will be interpreted as Unix timestamp. For timezone naive :obj:`datetime.datetime` objects, the default timezone of the - bot will be used. + bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is + used. member_limit (:obj:`int`, optional): Maximum number of users that can be members of the chat simultaneously after joining the chat via this invite link; 1-:tg-const:`telegram.constants.ChatInviteLinkLimit.MEMBER_LIMIT`. @@ -5393,7 +5412,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 13.8 creates_join_request (:obj:`bool`, optional): :obj:`True`, if users joining the chat via the link need to be approved by chat administrators. - If :obj:`True`, ``member_limit`` can't be specified. + If :obj:`True`, :paramref:`member_limit` can't be specified. .. versionadded:: 13.8 @@ -5484,7 +5503,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager): expire_date (:obj:`int` | :obj:`datetime.datetime`, optional): Date when the link will expire. For timezone naive :obj:`datetime.datetime` objects, the default timezone of the - bot will be used. + bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is + used. member_limit (:obj:`int`, optional): Maximum number of users that can be members of the chat simultaneously after joining the chat via this invite link; 1-:tg-const:`telegram.constants.ChatInviteLinkLimit.MEMBER_LIMIT`. @@ -5494,7 +5514,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): .. versionadded:: 13.8 creates_join_request (:obj:`bool`, optional): :obj:`True`, if users joining the chat via the link need to be approved by chat administrators. - If :obj:`True`, ``member_limit`` can't be specified. + If :obj:`True`, :paramref:`member_limit` can't be specified. .. versionadded:: 13.8 @@ -5981,8 +6001,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): """ Use this method to add a message to the list of pinned messages in a chat. If the chat is not a private chat, the bot must be an administrator in the chat for this to work - and must have the ``can_pin_messages`` admin right in a supergroup - or :attr:`telegram.ChatMemberAdministrator.can_edit_messages` admin right in a channel. + and must have the :paramref:`~telegram.ChatAdministratorRights.can_pin_messages` admin + right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin + right in a channel. Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username @@ -6046,9 +6067,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): """ Use this method to remove a message from the list of pinned messages in a chat. If the chat is not a private chat, the bot must be an administrator in the chat for this to work - and must have the ``can_pin_messages`` admin right in a - supergroup or :attr:`telegram.ChatMemberAdministrator.can_edit_messages` admin right in a - channel. + and must have the :paramref:`~telegram.ChatAdministratorRights.can_pin_messages` admin + right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin + right in a channel. Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username @@ -6108,9 +6129,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager): """ Use this method to clear the list of pinned messages in a chat. If the chat is not a private chat, the bot must be an administrator in the chat for this - to work and must have the ``can_pin_messages`` admin right in a - supergroup or :attr:`telegram.ChatMemberAdministrator.can_edit_messages` admin right in a - channel. + to work and must have the :paramref:`~telegram.ChatAdministratorRights.can_pin_messages` + admin right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` + admin right in a channel. Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username @@ -6804,7 +6825,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager): more than 600 seconds in the future. Can't be used together with :paramref:`open_period`. For timezone naive :obj:`datetime.datetime` objects, the default timezone of the - bot will be used. + bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is + used. 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 diff --git a/telegram/_inline/inlinekeyboardbutton.py b/telegram/_inline/inlinekeyboardbutton.py index a2cd5990f..59a1c4574 100644 --- a/telegram/_inline/inlinekeyboardbutton.py +++ b/telegram/_inline/inlinekeyboardbutton.py @@ -18,7 +18,7 @@ # along with this program. If not, see [http://www.gnu.org/licenses/]. """This module contains an object that represents a Telegram InlineKeyboardButton.""" -from typing import TYPE_CHECKING, Any, Optional +from typing import TYPE_CHECKING, Any, Optional, Union from telegram._games.callbackgame import CallbackGame from telegram._loginurl import LoginUrl @@ -163,7 +163,7 @@ class InlineKeyboardButton(TelegramObject): self, text: str, url: str = None, - callback_data: object = None, + callback_data: Union[str, object] = None, switch_inline_query: str = None, switch_inline_query_current_chat: str = None, callback_game: CallbackGame = None, @@ -214,7 +214,7 @@ class InlineKeyboardButton(TelegramObject): return cls(**data) - def update_callback_data(self, callback_data: object) -> None: + def update_callback_data(self, callback_data: Union[str, object]) -> None: """ Sets :attr:`callback_data` to the passed object. Intended to be used by :class:`telegram.ext.CallbackDataCache`. diff --git a/telegram/ext/_application.py b/telegram/ext/_application.py index 4b4e73575..c4086ba7a 100644 --- a/telegram/ext/_application.py +++ b/telegram/ext/_application.py @@ -359,7 +359,8 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager) * :attr:`bot` by calling :meth:`telegram.Bot.shutdown` * :attr:`updater` by calling :meth:`telegram.ext.Updater.shutdown` - * :attr:`persistence` by calling :meth:`update_persistence` and :meth`persistence.flush` + * :attr:`persistence` by calling :meth:`update_persistence` and + :meth:`BasePersistence.flush` .. seealso:: :meth:`initialize` diff --git a/telegram/ext/_callbackdatacache.py b/telegram/ext/_callbackdatacache.py index c5bceab58..47b763c2c 100644 --- a/telegram/ext/_callbackdatacache.py +++ b/telegram/ext/_callbackdatacache.py @@ -369,7 +369,8 @@ class CallbackDataCache: time_cutoff (:obj:`float` | :obj:`datetime.datetime`, optional): Pass a UNIX timestamp or a :obj:`datetime.datetime` to clear only entries which are older. For timezone naive :obj:`datetime.datetime` objects, the default timezone of the - bot will be used. + bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is + used. """ self.__clear(self._keyboard_data, time_cutoff=time_cutoff) diff --git a/telegram/ext/_jobqueue.py b/telegram/ext/_jobqueue.py index c852a9305..6710cc22e 100644 --- a/telegram/ext/_jobqueue.py +++ b/telegram/ext/_jobqueue.py @@ -148,11 +148,13 @@ class JobQueue: job should run. * :obj:`datetime.datetime` will be interpreted as a specific date and time at which the job should run. If the timezone (:attr:`datetime.datetime.tzinfo`) is - :obj:`None`, the default timezone of the bot will be used. + :obj:`None`, the default timezone of the bot will be used, which is UTC unless + :attr:`telegram.ext.Defaults.tzinfo` is used. * :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 (:attr:`datetime.time.tzinfo`) is :obj:`None`, the - default timezone of the bot will be used. + default timezone of the bot will be used, which is UTC unless + :attr:`telegram.ext.Defaults.tzinfo` is used. chat_id (:obj:`int`, optional): Chat id of the chat associated with this job. If passed, the corresponding :attr:`~telegram.ext.CallbackContext.chat_data` will @@ -246,7 +248,8 @@ class JobQueue: * :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 (:attr:`datetime.time.tzinfo`) is :obj:`None`, the - default timezone of the bot will be used. + default timezone of the bot will be used, which is UTC unless + :attr:`telegram.ext.Defaults.tzinfo` is used. Defaults to :paramref:`interval` last (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` | \ @@ -256,7 +259,7 @@ class JobQueue: If :paramref:`last` is :obj:`datetime.datetime` or :obj:`datetime.time` type and ``last.tzinfo`` is :obj:`None`, the default timezone of the bot will be - assumed. + assumed, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is used. Defaults to :obj:`None`. data (:obj:`object`, optional): Additional data needed for the callback function. @@ -339,7 +342,8 @@ class JobQueue: async def callback(context: CallbackContext) when (:obj:`datetime.time`): Time of day at which the job should run. If the timezone - (``when.tzinfo``) is :obj:`None`, the default timezone of the bot will be used. + (``when.tzinfo``) is :obj:`None`, the default timezone of the bot will be used, + which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is used. 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. If a month has fewer days than this number, the job will not run in this month. Passing ``-1`` leads to the job @@ -419,7 +423,7 @@ class JobQueue: time (:obj:`datetime.time`): Time of day at which the job should run. If the timezone (:obj:`datetime.time.tzinfo`) is :obj:`None`, the default timezone of the bot will - be used. + be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is used. days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should run (where ``0-6`` correspond to sunday - saturday). By default, the job will run every day. @@ -591,6 +595,7 @@ class Job: this :class:`telegram.ext.Job` to be useful. .. versionchanged:: 20.0 + * Removed argument and attribute ``job_queue``. * Renamed ``Job.context`` to :attr:`Job.data`.