From a75dffd4a813386a7ebdb27bfdb22842029e482f Mon Sep 17 00:00:00 2001 From: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Date: Thu, 1 Jul 2021 17:34:23 +0200 Subject: [PATCH] Doc Fixes (#2551) * Document ExtBot.insert_callbakc_data * fix duplicate object descriptions Fixed by removing `:undoc-members:` in the affected classes. Closes https://github.com/sphinx-doc/sphinx/issues/9294 * fix incorrect shortcut docstrings in user.py * fix object type in forcereply.py * fix discuss bot link in loginurl.py * document that message is None for (my)_chat_member in `effective_message` * numerous persistence rendering fixes * move docstring from property setter to property * Revert "fix object type in forcereply.py" This reverts commit 012663e0c3743e91f5102fd4fc19638aa7a49bbb. * Document comparison of jobs * Update min python version to 3.6.8 * remove old note from chat.py + some return msg fixes * fix colon placement Co-authored-by: Harshil Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> --- README.rst | 2 +- README_RAW.rst | 2 +- docs/source/telegram.ext.extbot.rst | 2 ++ docs/source/telegram.ext.handler.rst | 1 - docs/source/telegram.update.rst | 1 - docs/source/telegram.user.rst | 1 - telegram/chat.py | 22 +++++++---------- telegram/ext/basepersistence.py | 18 +++++++------- telegram/ext/conversationhandler.py | 2 +- telegram/ext/dictpersistence.py | 12 +++++----- telegram/ext/jobqueue.py | 3 +++ telegram/ext/picklepersistence.py | 16 ++++++------- telegram/loginurl.py | 2 +- telegram/update.py | 4 ++-- telegram/user.py | 36 ++++++++++++++-------------- 15 files changed, 60 insertions(+), 64 deletions(-) diff --git a/README.rst b/README.rst index 2ed398141..6e8aa44ce 100644 --- a/README.rst +++ b/README.rst @@ -93,7 +93,7 @@ Introduction This library provides a pure Python interface for the `Telegram Bot API `_. -It's compatible with Python versions 3.6.2+. PTB might also work on `PyPy `_, though there have been a lot of issues before. Hence, PyPy is not officially supported. +It's compatible with Python versions 3.6.8+. PTB might also work on `PyPy `_, though there have been a lot of issues before. Hence, PyPy is not officially supported. In addition to the pure API implementation, this library features a number of high-level classes to make the development of bots easy and straightforward. These classes are contained in the diff --git a/README_RAW.rst b/README_RAW.rst index f875e3919..3020fec94 100644 --- a/README_RAW.rst +++ b/README_RAW.rst @@ -91,7 +91,7 @@ Introduction This library provides a pure Python, lightweight interface for the `Telegram Bot API `_. -It's compatible with Python versions 3.6.2+. PTB-Raw might also work on `PyPy `_, though there have been a lot of issues before. Hence, PyPy is not officially supported. +It's compatible with Python versions 3.6.8+. PTB-Raw might also work on `PyPy `_, though there have been a lot of issues before. Hence, PyPy is not officially supported. ``python-telegram-bot-raw`` is part of the `python-telegram-bot `_ ecosystem and provides the pure API functionality extracted from PTB. It therefore does *not* have independent release schedules, changelogs or documentation. Please consult the PTB resources. diff --git a/docs/source/telegram.ext.extbot.rst b/docs/source/telegram.ext.extbot.rst index a43d04823..a295f2aa4 100644 --- a/docs/source/telegram.ext.extbot.rst +++ b/docs/source/telegram.ext.extbot.rst @@ -5,3 +5,5 @@ telegram.ext.ExtBot .. autoclass:: telegram.ext.ExtBot :show-inheritance: + + .. autofunction:: telegram.ext.ExtBot.insert_callback_data diff --git a/docs/source/telegram.ext.handler.rst b/docs/source/telegram.ext.handler.rst index 7b8224573..065cbba98 100644 --- a/docs/source/telegram.ext.handler.rst +++ b/docs/source/telegram.ext.handler.rst @@ -5,5 +5,4 @@ telegram.ext.Handler .. autoclass:: telegram.ext.Handler :members: - :undoc-members: :show-inheritance: diff --git a/docs/source/telegram.update.rst b/docs/source/telegram.update.rst index f8a5d69be..e19fc411b 100644 --- a/docs/source/telegram.update.rst +++ b/docs/source/telegram.update.rst @@ -5,5 +5,4 @@ telegram.Update .. autoclass:: telegram.Update :members: - :undoc-members: :show-inheritance: diff --git a/docs/source/telegram.user.rst b/docs/source/telegram.user.rst index 23fc2d3f3..338631f01 100644 --- a/docs/source/telegram.user.rst +++ b/docs/source/telegram.user.rst @@ -5,5 +5,4 @@ telegram.User .. autoclass:: telegram.User :members: - :undoc-members: :show-inheritance: diff --git a/telegram/chat.py b/telegram/chat.py index 95ed61d5b..ae7e2717d 100644 --- a/telegram/chat.py +++ b/telegram/chat.py @@ -284,7 +284,7 @@ class Chat(TelegramObject): For the documentation of the arguments, please see :meth:`telegram.Bot.leave_chat`. Returns: - :obj:`bool` If the action was sent successfully. + :obj:`bool`: On success, :obj:`True` is returned. """ return self.bot.leave_chat( @@ -375,13 +375,7 @@ class Chat(TelegramObject): :meth:`telegram.Bot.kick_chat_member`. Returns: - :obj:`bool`: If the action was sent successfully. - - Note: - This method will only work if the `All Members Are Admins` setting is off in the - target group. Otherwise members may only be removed by the group's creator or by the - member that added them. - + :obj:`bool`: On success, :obj:`True` is returned. """ return self.bot.kick_chat_member( chat_id=self.id, @@ -406,7 +400,7 @@ class Chat(TelegramObject): For the documentation of the arguments, please see :meth:`telegram.Bot.unban_chat_member`. Returns: - :obj:`bool`: If the action was sent successfully. + :obj:`bool`: On success, :obj:`True` is returned. """ return self.bot.unban_chat_member( @@ -444,7 +438,7 @@ class Chat(TelegramObject): .. versionadded:: 13.2 Returns: - :obj:`bool`: If the action was sent successfully. + :obj:`bool`: On success, :obj:`True` is returned. """ return self.bot.promote_chat_member( @@ -483,7 +477,7 @@ class Chat(TelegramObject): .. versionadded:: 13.2 Returns: - :obj:`bool`: If the action was sent successfully. + :obj:`bool`: On success, :obj:`True` is returned. """ return self.bot.restrict_chat_member( @@ -509,7 +503,7 @@ class Chat(TelegramObject): :meth:`telegram.Bot.set_chat_permissions`. Returns: - :obj:`bool`: If the action was sent successfully. + :obj:`bool`: On success, :obj:`True` is returned. """ return self.bot.set_chat_permissions( @@ -534,7 +528,7 @@ class Chat(TelegramObject): :meth:`telegram.Bot.set_chat_administrator_custom_title`. Returns: - :obj:`bool`: If the action was sent successfully. + :obj:`bool`: On success, :obj:`True` is returned. """ return self.bot.set_chat_administrator_custom_title( @@ -678,7 +672,7 @@ class Chat(TelegramObject): For the documentation of the arguments, please see :meth:`telegram.Bot.send_media_group`. Returns: - List[:class:`telegram.Message`:] On success, instance representing the message posted. + List[:class:`telegram.Message`]: On success, instance representing the message posted. """ return self.bot.send_media_group( diff --git a/telegram/ext/basepersistence.py b/telegram/ext/basepersistence.py index 070d458fa..92101c581 100644 --- a/telegram/ext/basepersistence.py +++ b/telegram/ext/basepersistence.py @@ -446,8 +446,8 @@ class BasePersistence(Generic[UD, CD, BD], ABC): .. versionadded:: 13.6 Returns: - Optional[:class:`telegram.ext.utils.types.CDCData`]: The restored meta data or - :obj:`None`, if no data was stored. + Optional[:class:`telegram.ext.utils.types.CDCData`]: The restored meta data or + :obj:`None`, if no data was stored. """ raise NotImplementedError @@ -469,8 +469,8 @@ class BasePersistence(Generic[UD, CD, BD], ABC): def update_conversation( self, name: str, key: Tuple[int, ...], new_state: Optional[object] ) -> None: - """Will be called when a :attr:`telegram.ext.ConversationHandler.update_state` - is called. This allows the storage of the new state in the persistence. + """Will be called when a :class:`telegram.ext.ConversationHandler` changes states. + This allows the storage of the new state in the persistence. Args: name (:obj:`str`): The handler's name. @@ -486,7 +486,7 @@ class BasePersistence(Generic[UD, CD, BD], ABC): Args: user_id (:obj:`int`): The user the data might have been changed for. data (:class:`telegram.ext.utils.types.UD`): The - :attr:`telegram.ext.dispatcher.user_data` ``[user_id]``. + :attr:`telegram.ext.Dispatcher.user_data` ``[user_id]``. """ @abstractmethod @@ -497,7 +497,7 @@ class BasePersistence(Generic[UD, CD, BD], ABC): Args: chat_id (:obj:`int`): The chat the data might have been changed for. data (:class:`telegram.ext.utils.types.CD`): The - :attr:`telegram.ext.dispatcher.chat_data` ``[chat_id]``. + :attr:`telegram.ext.Dispatcher.chat_data` ``[chat_id]``. """ @abstractmethod @@ -507,7 +507,7 @@ class BasePersistence(Generic[UD, CD, BD], ABC): Args: data (:class:`telegram.ext.utils.types.BD`): The - :attr:`telegram.ext.dispatcher.bot_data`. + :attr:`telegram.ext.Dispatcher.bot_data`. """ def refresh_user_data(self, user_id: int, user_data: UD) -> None: @@ -552,8 +552,8 @@ class BasePersistence(Generic[UD, CD, BD], ABC): .. versionadded:: 13.6 Args: - data (:class:`telegram.ext.utils.types.CDCData`:): The relevant data to restore - :attr:`telegram.ext.dispatcher.bot.callback_data_cache`. + data (:class:`telegram.ext.utils.types.CDCData`): The relevant data to restore + :class:`telegram.ext.CallbackDataCache`. """ raise NotImplementedError diff --git a/telegram/ext/conversationhandler.py b/telegram/ext/conversationhandler.py index df94f9b7e..ba621fdea 100644 --- a/telegram/ext/conversationhandler.py +++ b/telegram/ext/conversationhandler.py @@ -350,11 +350,11 @@ class ConversationHandler(Handler[Update, CCT]): @property def allow_reentry(self) -> bool: + """:obj:`bool`: Determines if a user can restart a conversation with an entry point.""" return self._allow_reentry @allow_reentry.setter def allow_reentry(self, value: object) -> NoReturn: - """:obj:`bool`: Determines if a user can restart a conversation with an entry point.""" raise ValueError('You can not assign a new value to allow_reentry after initialization.') @property diff --git a/telegram/ext/dictpersistence.py b/telegram/ext/dictpersistence.py index 044fc652f..72c767d74 100644 --- a/telegram/ext/dictpersistence.py +++ b/telegram/ext/dictpersistence.py @@ -294,7 +294,7 @@ class DictPersistence(BasePersistence): Returns: Optional[:class:`telegram.ext.utils.types.CDCData`]: The restored meta data or - :obj:`None`, if no data was stored. + :obj:`None`, if no data was stored. """ if self.callback_data is None: self._callback_data = None @@ -334,7 +334,7 @@ class DictPersistence(BasePersistence): Args: user_id (:obj:`int`): The user the data might have been changed for. - data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.user_data` ``[user_id]``. + data (:obj:`dict`): The :attr:`telegram.ext.Dispatcher.user_data` ``[user_id]``. """ if self._user_data is None: self._user_data = defaultdict(dict) @@ -348,7 +348,7 @@ class DictPersistence(BasePersistence): Args: chat_id (:obj:`int`): The chat the data might have been changed for. - data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.chat_data` ``[chat_id]``. + data (:obj:`dict`): The :attr:`telegram.ext.Dispatcher.chat_data` ``[chat_id]``. """ if self._chat_data is None: self._chat_data = defaultdict(dict) @@ -361,7 +361,7 @@ class DictPersistence(BasePersistence): """Will update the bot_data (if changed). Args: - data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.bot_data`. + data (:obj:`dict`): The :attr:`telegram.ext.Dispatcher.bot_data`. """ if self._bot_data == data: return @@ -374,8 +374,8 @@ class DictPersistence(BasePersistence): .. versionadded:: 13.6 Args: - data (:class:`telegram.ext.utils.types.CDCData`:): The relevant data to restore - :attr:`telegram.ext.dispatcher.bot.callback_data_cache`. + data (:class:`telegram.ext.utils.types.CDCData`): The relevant data to restore + :class:`telegram.ext.CallbackDataCache`. """ if self._callback_data == data: return diff --git a/telegram/ext/jobqueue.py b/telegram/ext/jobqueue.py index a6e8e1afb..da2dea4f2 100644 --- a/telegram/ext/jobqueue.py +++ b/telegram/ext/jobqueue.py @@ -518,6 +518,9 @@ class Job: With the current backend APScheduler, :attr:`job` holds a :class:`apscheduler.job.Job` instance. + Objects of this class are comparable in terms of equality. Two objects of this class are + considered equal, if their :attr:`id` is equal. + Note: * All attributes and instance methods of :attr:`job` are also directly available as attributes/methods of the corresponding :class:`telegram.ext.Job` object. diff --git a/telegram/ext/picklepersistence.py b/telegram/ext/picklepersistence.py index 3870d4138..cf0059ad1 100644 --- a/telegram/ext/picklepersistence.py +++ b/telegram/ext/picklepersistence.py @@ -60,7 +60,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]): .. versionadded:: 13.6 single_file (:obj:`bool`, optional): When :obj:`False` will store 5 separate files of - `filename_user_data`, `filename_chat_data`, `filename_bot_data`, `filename_chat_data`, + `filename_user_data`, `filename_bot_data`, `filename_chat_data`, `filename_callback_data` and `filename_conversations`. Default is :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 @@ -87,7 +87,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]): .. versionadded:: 13.6 single_file (:obj:`bool`): Optional. When :obj:`False` will store 5 separate files of - `filename_user_data`, `filename_chat_data`, `filename_bot_data`, `filename_chat_data`, + `filename_user_data`, `filename_bot_data`, `filename_chat_data`, `filename_callback_data` and `filename_conversations`. Default is :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 @@ -281,7 +281,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]): Returns: Optional[:class:`telegram.ext.utils.types.CDCData`]: The restored meta data or - :obj:`None`, if no data was stored. + :obj:`None`, if no data was stored. """ if self.callback_data: pass @@ -347,7 +347,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]): Args: user_id (:obj:`int`): The user the data might have been changed for. data (:class:`telegram.ext.utils.types.UD`): The - :attr:`telegram.ext.dispatcher.user_data` ``[user_id]``. + :attr:`telegram.ext.Dispatcher.user_data` ``[user_id]``. """ if self.user_data is None: self.user_data = defaultdict(self.context_types.user_data) @@ -367,7 +367,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]): Args: chat_id (:obj:`int`): The chat the data might have been changed for. data (:class:`telegram.ext.utils.types.CD`): The - :attr:`telegram.ext.dispatcher.chat_data` ``[chat_id]``. + :attr:`telegram.ext.Dispatcher.chat_data` ``[chat_id]``. """ if self.chat_data is None: self.chat_data = defaultdict(self.context_types.chat_data) @@ -386,7 +386,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]): Args: data (:class:`telegram.ext.utils.types.BD`): The - :attr:`telegram.ext.dispatcher.bot_data`. + :attr:`telegram.ext.Dispatcher.bot_data`. """ if self.bot_data == data: return @@ -405,8 +405,8 @@ class PicklePersistence(BasePersistence[UD, CD, BD]): .. versionadded:: 13.6 Args: - data (:class:`telegram.ext.utils.types.CDCData`:): The relevant data to restore - :attr:`telegram.ext.dispatcher.bot.callback_data`. + data (:class:`telegram.ext.utils.types.CDCData`): The relevant data to restore + :class:`telegram.ext.CallbackDataCache`. """ if self.callback_data == data: return diff --git a/telegram/loginurl.py b/telegram/loginurl.py index 81792735b..a5f38300a 100644 --- a/telegram/loginurl.py +++ b/telegram/loginurl.py @@ -29,7 +29,7 @@ class LoginUrl(TelegramObject): coming from Telegram. All the user needs to do is tap/click a button and confirm that they want to log in. Telegram apps support these buttons as of version 5.7. - Sample bot: `@discussbot `_ + Sample bot: `@discussbot `_ Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their :attr:`url` is equal. diff --git a/telegram/update.py b/telegram/update.py index b610b35b0..8497ee213 100644 --- a/telegram/update.py +++ b/telegram/update.py @@ -334,8 +334,8 @@ class Update(TelegramObject): :class:`telegram.Message`: The message included in this update, no matter what kind of 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`. + :attr:`shipping_query`, :attr:`pre_checkout_query`, :attr:`poll`, + :attr:`poll_answer`, :attr:`my_chat_member` and :attr:`chat_member`. """ if self._effective_message: diff --git a/telegram/user.py b/telegram/user.py index ecb4a3cf1..7949e249e 100644 --- a/telegram/user.py +++ b/telegram/user.py @@ -193,7 +193,7 @@ class User(TelegramObject): def mention_markdown(self, name: str = None) -> str: """ Note: - :attr:`telegram.ParseMode.MARKDOWN` is is a legacy mode, retained by Telegram for + :attr:`telegram.ParseMode.MARKDOWN` is a legacy mode, retained by Telegram for backward compatibility. You should use :meth:`mention_markdown_v2` instead. Args: @@ -362,7 +362,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_photo(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_photo`. @@ -398,7 +398,7 @@ class User(TelegramObject): ) -> List['Message']: """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_media_group(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_media_group`. @@ -436,7 +436,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_audio(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_audio`. @@ -471,7 +471,7 @@ class User(TelegramObject): ) -> bool: """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_chat_action(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_chat_action`. @@ -505,7 +505,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_contact(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_contact`. @@ -540,7 +540,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_dice(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_dice`. @@ -577,7 +577,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_document(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_document`. @@ -614,7 +614,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_game(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_game`. @@ -665,7 +665,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_invoice(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_invoice`. @@ -730,7 +730,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_location(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_location`. @@ -775,7 +775,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_animation(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_animation`. @@ -814,7 +814,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_sticker(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_sticker`. @@ -854,7 +854,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_video(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_video`. @@ -902,7 +902,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_venue(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_venue`. @@ -945,7 +945,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_video_note(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_video_note`. @@ -985,7 +985,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_voice(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_voice`. @@ -1033,7 +1033,7 @@ class User(TelegramObject): ) -> 'Message': """Shortcut for:: - bot.send_message(update.effective_user.id, *args, **kwargs) + bot.send_poll(update.effective_user.id, *args, **kwargs) For the documentation of the arguments, please see :meth:`telegram.Bot.send_poll`.