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

Doc Fixes (#2551)

Browse source 
* 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 012663e0c3.

* 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 <ilovebhagwan@gmail.com>
Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>
This commit is contained in:
Bibo-Joshi 2021-07-01 17:34:23 +02:00 committed by GitHub
parent fce2993d21
commit a75dffd4a8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
15 changed files with 60 additions and 64 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.rst
View file

@ -93,7 +93,7 @@ Introduction
This library provides a pure Python interface for the
`Telegram Bot API <https://core.telegram.org/bots/api>`_.
It's compatible with Python versions 3.6.2+. PTB might also work on `PyPy <http://pypy.org/>`_, 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 <http://pypy.org/>`_, 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

2
README_RAW.rst
View file

@ -91,7 +91,7 @@ Introduction
This library provides a pure Python, lightweight interface for the
`Telegram Bot API <https://core.telegram.org/bots/api>`_.
It's compatible with Python versions 3.6.2+. PTB-Raw might also work on `PyPy <http://pypy.org/>`_, 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 <http://pypy.org/>`_, 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 <https://python-telegram-bot.org>`_ 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.

2
docs/source/telegram.ext.extbot.rst
View file

@ -5,3 +5,5 @@ telegram.ext.ExtBot
.. autoclass:: telegram.ext.ExtBot
:show-inheritance:
.. autofunction:: telegram.ext.ExtBot.insert_callback_data

1
docs/source/telegram.ext.handler.rst
View file

@ -5,5 +5,4 @@ telegram.ext.Handler
.. autoclass:: telegram.ext.Handler
:members:
:undoc-members:
:show-inheritance:

1
docs/source/telegram.update.rst
View file

@ -5,5 +5,4 @@ telegram.Update
.. autoclass:: telegram.Update
:members:
:undoc-members:
:show-inheritance:

1
docs/source/telegram.user.rst
View file

@ -5,5 +5,4 @@ telegram.User
.. autoclass:: telegram.User
:members:
:undoc-members:
:show-inheritance:

22
telegram/chat.py
View file

@ -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(

14
telegram/ext/basepersistence.py
View file

@ -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

2
telegram/ext/conversationhandler.py
View file

@ -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

10
telegram/ext/dictpersistence.py
View file

@ -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

3
telegram/ext/jobqueue.py
View file

@ -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.

14
telegram/ext/picklepersistence.py
View file

@ -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
@ -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

2
telegram/loginurl.py
View file

@ -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 <https://t.me/dicussbot>`_
Sample bot: `@discussbot <https://t.me/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.

4
telegram/update.py
View file

@ -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:

36
telegram/user.py
View file

@ -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`.