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

Documentation Improvements (#3103, #3121, #3098)

Browse source 
Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>
Co-authored-by: David <dsb321mp@gmail.com>
Co-authored-by: Harshil Mehta <37377066+harshil21@users.noreply.github.com>
Co-authored-by: poolitzer <github@poolitzer.eu>
Co-authored-by: Alex <53974096+ExalFabu@users.noreply.github.com>
This commit is contained in:
Bibo-Joshi 2022-06-27 18:58:51 +02:00 committed by GitHub
parent 08e223ba90
commit 2d2cede442
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 69 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
AUTHORS.rst
View file

@ -46,6 +46,7 @@ The following wonderful people contributed directly or indirectly to this projec
- `Evan Haberecht <https://github.com/habereet>`_
- `Evgeny Denisov <https://github.com/eIGato>`_
- `evgfilim1 <https://github.com/evgfilim1>`_
- `ExalFabu <https://github.com/ExalFabu>`_
- `franciscod <https://github.com/franciscod>`_
- `gamgi <https://github.com/gamgi>`_
- `Gauthamram Ravichandran <https://github.com/GauthamramRavichandran>`_

4
README.rst
View file

@ -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 <https://docs.python-telegram-bot.org/>`_ 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 <https://docs.python-telegram-bot.org/changelog.html>`_.
- The `wiki <https://github.com/python-telegram-bot/python-telegram-bot/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 <https://docs.python-telegram-bot.org/examples.html>`_ 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.

4
README_RAW.rst
View file

@ -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 <https://docs.python-telegram-bot.org/>`_ 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 <https://docs.python-telegram-bot.org/changelog.html>`_.
- The `wiki <https://github.com/python-telegram-bot/python-telegram-bot/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 <https://docs.python-telegram-bot.org/examples.html>`_ 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.

4
docs/requirements-docs.txt
View file

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

66
telegram/_bot.py
View file

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

6
telegram/_inline/inlinekeyboardbutton.py
View file

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

3
telegram/ext/_application.py
View file

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

3
telegram/ext/_callbackdatacache.py
View file

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

17
telegram/ext/_jobqueue.py
View file

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