Skip to content

Add more crossrefs to docstrings #3398

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Bibo-Joshi merged 12 commits into from
Nov 30, 2022
Merged

Add more crossrefs to docstrings #3398

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
1ec6504
add references from `Bot.send_message`
lemontree210 Nov 29, 2022
991ba8e
add references from `Bot.get_file`
lemontree210 Nov 29, 2022
ced9536
fix(`_BaseMedium`) :attr:->:meth: in `.get_file()`
lemontree210 Nov 29, 2022
93cdd74
add references from `Bot.get_file()`
lemontree210 Nov 29, 2022
aa07122
fix: `:attr:`->`:meth:` in wrappers for `Bot.get_file()`
lemontree210 Nov 29, 2022
4d57263
add references to `telegram.Game.text`, fix seealso in `set_game_score`
lemontree210 Nov 29, 2022
0ad2f0c
add references from `Bot.get_updates` and `.set_webhook`
lemontree210 Nov 29, 2022
0bd9f53
add references to `Message.get_game_high_scores`, `Message.pin`/`.unpin`
lemontree210 Nov 29, 2022
979f612
add cross-references between `[set/get/delete]_my_commands`
lemontree210 Nov 29, 2022
bb3db8a
fix: reference to `Bot.get_chat_menu_button`
lemontree210 Nov 29, 2022
58ce1d0
fix `:attr:`->`:meth:` in `seealso` for `Bot.answer_shipping_query`
lemontree210 Nov 29, 2022
132ef05
add ref to `Application.run_webhook()`
lemontree210 Nov 30, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 31 additions & 8 deletions telegram/_bot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -694,8 +694,9 @@ async def send_message(
) -> Message:
"""Use this method to send text messages.

.. seealso:: :meth:`telegram.Message.reply_text`, :meth:`telegram.Chat.send_message`,
:meth:`telegram.User.send_message`
.. seealso:: :meth:`telegram.Chat.send_message`, :meth:`telegram.User.send_message`,
:meth:`telegram.Message.reply_text`, :meth:`telegram.Message.reply_html`,
:meth:`telegram.Message.reply_markdown`, :meth:`telegram.Message.reply_markdown_v2`

Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
Expand Down Expand Up @@ -2846,6 +2847,13 @@ async def get_file(
You should save the file's MIME type and name (if available) when the File object
is received.

.. seealso:: :meth:`telegram.Animation.get_file`, :meth:`telegram.Audio.get_file`,
:meth:`telegram.ChatPhoto.get_big_file`, :meth:`telegram.ChatPhoto.get_small_file`,
:meth:`telegram.Document.get_file`, :meth:`telegram.PassportFile.get_file`,
:meth:`telegram.PhotoSize.get_file`, :meth:`telegram.Sticker.get_file`,
:meth:`telegram.Video.get_file`, :meth:`telegram.VideoNote.get_file`,
:meth:`telegram.Voice.get_file`

Args:
file_id (:obj:`str` | :class:`telegram.Animation` | :class:`telegram.Audio` | \
:class:`telegram.ChatPhoto` | :class:`telegram.Document` | \
Expand Down Expand Up @@ -3200,7 +3208,7 @@ async def edit_message_text(
|editreplymarkup|.

.. seealso:: :meth:`telegram.Message.edit_text`,
:meth:`telegram.CallbackQuery.edit_message_text`
:meth:`telegram.CallbackQuery.edit_message_text`, :attr:`telegram.Game.text`

Args:
chat_id (:obj:`int` | :obj:`str`, optional): Required if :paramref:`inline_message_id`
Expand Down Expand Up @@ -3477,6 +3485,9 @@ async def get_updates(
server response.
3. To take full advantage of this library take a look at :class:`telegram.ext.Updater`

.. seealso:: :meth:`telegram.ext.Application.run_polling`,
:meth:`telegram.ext.Updater.start_polling`

Args:
offset (:obj:`int`, optional): Identifier of the first update to be returned. Must be
greater by one than the highest among the identifiers of previously received
Expand Down Expand Up @@ -3594,6 +3605,9 @@ async def set_webhook(
If you're having any trouble setting up webhooks, please check out this `guide to
Webhooks`_.

.. seealso:: :meth:`telegram.ext.Application.run_webhook`,
:meth:`telegram.ext.Updater.start_webhook`

Examples:
:any:`Custom Webhook Bot <examples.customwebhookbot>`

Expand Down Expand Up @@ -4029,7 +4043,7 @@ async def set_game_score(
"""
Use this method to set the score of the specified user in a game message.

.. seealso::`telegram.CallbackQuery.set_game_score`
.. seealso:: :meth:`telegram.CallbackQuery.set_game_score`, :attr:`telegram.Game.text`

Args:
user_id (:obj:`int`): User identifier.
Expand Down Expand Up @@ -4100,7 +4114,8 @@ async def get_game_high_scores(
closest neighbors on each side. Will also return the top three users if the user and
his neighbors are not among them. Please note that this behavior is subject to change.

.. seealso:: :meth:`telegram.CallbackQuery.get_game_high_scores`
.. seealso:: :meth:`telegram.CallbackQuery.get_game_high_scores`,
:meth:`telegram.Message.get_game_high_scores`

Args:
user_id (:obj:`int`): Target user id.
Expand Down Expand Up @@ -4353,7 +4368,7 @@ async def answer_shipping_query( # pylint: disable=invalid-name
:class:`telegram.Update` with a :attr:`telegram.Update.shipping_query` field to the bot.
Use this method to reply to shipping queries.

.. seealso:: :attr:`telegram.ShippingQuery.answer`
.. seealso:: :meth:`telegram.ShippingQuery.answer`

Args:
shipping_query_id (:obj:`str`): Unique identifier for the query to be answered.
Expand Down Expand Up @@ -5329,7 +5344,8 @@ async def pin_chat_message(
right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin
right in a channel.

.. seealso:: :meth:`telegram.Chat.pin_message`, :meth:`telegram.User.pin_message`
.. seealso:: :meth:`telegram.Chat.pin_message`, :meth:`telegram.Message.pin`,
:meth:`telegram.User.pin_message`

Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
Expand Down Expand Up @@ -5380,7 +5396,8 @@ async def unpin_chat_message(
right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin
right in a channel.

.. seealso:: :meth:`telegram.Chat.unpin_message`, :meth:`telegram.User.unpin_message`
.. seealso:: :meth:`telegram.Chat.unpin_message`, :meth:`telegram.Message.unpin`,
:meth:`telegram.User.unpin_message`

Args:
chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
Expand Down Expand Up @@ -6355,6 +6372,8 @@ async def get_my_commands(
Use this method to get the current list of the bot's commands for the given scope and user
language.

.. seealso:: :meth:`set_my_commands`, :meth:`delete_my_commands`

Args:
scope (:class:`telegram.BotCommandScope`, optional): An object,
describing scope of users. Defaults to :class:`telegram.BotCommandScopeDefault`.
Expand Down Expand Up @@ -6412,6 +6431,8 @@ async def set_my_commands(
`Telegram docs <https://core.telegram.org/bots/features#commands>`_ for more details about
bot commands.

.. seealso:: :meth:`get_my_commands`, :meth:`delete_my_commands`

Args:
commands (List[:class:`BotCommand` | (:obj:`str`, :obj:`str`)]): A list
of bot commands to be set as the list of the bot's commands. At most
Expand Down Expand Up @@ -6477,6 +6498,8 @@ async def delete_my_commands(

.. versionadded:: 13.7

.. seealso:: :meth:`get_my_commands`, :meth:`set_my_commands`

Args:
scope (:class:`telegram.BotCommandScope`, optional): An object,
describing scope of users for which the commands are relevant. Defaults to
Expand Down
2 changes: 1 addition & 1 deletion telegram/_chat.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2833,7 +2833,7 @@ async def get_menu_button(
await bot.get_chat_menu_button(chat_id=update.effective_chat.id, *args, **kwargs)

For the documentation of the arguments, please see
:meth:`telegram.Bot.set_chat_menu_button`.
:meth:`telegram.Bot.get_chat_menu_button`.

Caution:
Can only work, if the chat is a private chat.
Expand Down
2 changes: 1 addition & 1 deletion telegram/_files/_basemedium.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ async def get_file(
pool_timeout: ODVInput[float] = DEFAULT_NONE,
api_kwargs: JSONDict = None,
) -> "File":
"""Convenience wrapper over :attr:`telegram.Bot.get_file`
"""Convenience wrapper over :meth:`telegram.Bot.get_file`

For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.

Expand Down
4 changes: 2 additions & 2 deletions telegram/_files/chatphoto.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ async def get_small_file(
pool_timeout: ODVInput[float] = DEFAULT_NONE,
api_kwargs: JSONDict = None,
) -> "File":
"""Convenience wrapper over :attr:`telegram.Bot.get_file` for getting the small
"""Convenience wrapper over :meth:`telegram.Bot.get_file` for getting the small
(:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`)
chat photo

Expand Down Expand Up @@ -140,7 +140,7 @@ async def get_big_file(
pool_timeout: ODVInput[float] = DEFAULT_NONE,
api_kwargs: JSONDict = None,
) -> "File":
"""Convenience wrapper over :attr:`telegram.Bot.get_file` for getting the
"""Convenience wrapper over :meth:`telegram.Bot.get_file` for getting the
big (:tg-const:`telegram.ChatPhoto.SIZE_BIG` x :tg-const:`telegram.ChatPhoto.SIZE_BIG`)
chat photo

Expand Down
2 changes: 1 addition & 1 deletion telegram/_passport/passportfile.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@ async def get_file(
api_kwargs: JSONDict = None,
) -> "File":
"""
Wrapper over :attr:`telegram.Bot.get_file`. Will automatically assign the correct
Wrapper over :meth:`telegram.Bot.get_file`. Will automatically assign the correct
credentials to the returned :class:`telegram.File` if originating from
:obj:`telegram.PassportData.decrypted_data`.

Expand Down