mirror of
https://github.com/python-telegram-bot/python-telegram-bot.git
synced 2024-12-29 15:49:02 +01:00
195 lines
7 KiB
Python
195 lines
7 KiB
Python
#!/usr/bin/env python
|
|
#
|
|
# A library that provides a Python interface to the Telegram Bot API
|
|
# Copyright (C) 2015-2023
|
|
# Leandro Toledo de Souza <devs@python-telegram-bot.org>
|
|
#
|
|
# This program is free software: you can redistribute it and/or modify
|
|
# it under the terms of the GNU Lesser Public License as published by
|
|
# the Free Software Foundation, either version 3 of the License, or
|
|
# (at your option) any later version.
|
|
#
|
|
# This program is distributed in the hope that it will be useful,
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
# GNU Lesser Public License for more details.
|
|
#
|
|
# You should have received a copy of the GNU Lesser Public License
|
|
# along with this program. If not, see [http://www.gnu.org/licenses/].
|
|
"""This module contains convenience helper functions.
|
|
|
|
.. versionchanged:: 20.0
|
|
Previously, the contents of this module were available through the (no longer existing)
|
|
module ``telegram.utils.helpers``.
|
|
"""
|
|
|
|
__all__ = (
|
|
"create_deep_linked_url",
|
|
"effective_message_type",
|
|
"escape_markdown",
|
|
"mention_html",
|
|
"mention_markdown",
|
|
)
|
|
|
|
import re
|
|
from html import escape
|
|
from typing import TYPE_CHECKING, Optional, Union
|
|
|
|
from telegram.constants import MessageType
|
|
|
|
if TYPE_CHECKING:
|
|
from telegram import Message, Update
|
|
|
|
|
|
def escape_markdown(text: str, version: int = 1, entity_type: Optional[str] = None) -> str:
|
|
"""Helper function to escape telegram markup symbols.
|
|
|
|
.. versionchanged:: 20.3
|
|
Custom emoji entity escaping is now supported.
|
|
|
|
Args:
|
|
text (:obj:`str`): The text.
|
|
version (:obj:`int` | :obj:`str`): Use to specify the version of telegrams Markdown.
|
|
Either ``1`` or ``2``. Defaults to ``1``.
|
|
entity_type (:obj:`str`, optional): For the entity types
|
|
:tg-const:`telegram.MessageEntity.PRE`, :tg-const:`telegram.MessageEntity.CODE` and
|
|
the link part of :tg-const:`telegram.MessageEntity.TEXT_LINK` and
|
|
:tg-const:`telegram.MessageEntity.CUSTOM_EMOJI`, only certain characters need to be
|
|
escaped in :tg-const:`telegram.constants.ParseMode.MARKDOWN_V2`. See the `official API
|
|
documentation <https://core.telegram.org/bots/api#formatting-options>`_ for details.
|
|
Only valid in combination with ``version=2``, will be ignored else.
|
|
"""
|
|
if int(version) == 1:
|
|
escape_chars = r"_*`["
|
|
elif int(version) == 2:
|
|
if entity_type in ["pre", "code"]:
|
|
escape_chars = r"\`"
|
|
elif entity_type in ["text_link", "custom_emoji"]:
|
|
escape_chars = r"\)"
|
|
else:
|
|
escape_chars = r"\_*[]()~`>#+-=|{}.!"
|
|
else:
|
|
raise ValueError("Markdown version must be either 1 or 2!")
|
|
|
|
return re.sub(f"([{re.escape(escape_chars)}])", r"\\\1", text)
|
|
|
|
|
|
def mention_html(user_id: Union[int, str], name: str) -> str:
|
|
"""
|
|
Helper function to create a user mention as HTML tag.
|
|
|
|
Args:
|
|
user_id (:obj:`int`): The user's id which you want to mention.
|
|
name (:obj:`str`): The name the mention is showing.
|
|
|
|
Returns:
|
|
:obj:`str`: The inline mention for the user as HTML.
|
|
"""
|
|
return f'<a href="tg://user?id={user_id}">{escape(name)}</a>'
|
|
|
|
|
|
def mention_markdown(user_id: Union[int, str], name: str, version: int = 1) -> str:
|
|
"""
|
|
Helper function to create a user mention in Markdown syntax.
|
|
|
|
Args:
|
|
user_id (:obj:`int`): The user's id which you want to mention.
|
|
name (:obj:`str`): The name the mention is showing.
|
|
version (:obj:`int` | :obj:`str`): Use to specify the version of Telegram's Markdown.
|
|
Either ``1`` or ``2``. Defaults to ``1``.
|
|
|
|
Returns:
|
|
:obj:`str`: The inline mention for the user as Markdown.
|
|
"""
|
|
tg_link = f"tg://user?id={user_id}"
|
|
if version == 1:
|
|
return f"[{name}]({tg_link})"
|
|
return f"[{escape_markdown(name, version=version)}]({tg_link})"
|
|
|
|
|
|
def effective_message_type(entity: Union["Message", "Update"]) -> Optional[str]:
|
|
"""
|
|
Extracts the type of message as a string identifier from a :class:`telegram.Message` or a
|
|
:class:`telegram.Update`.
|
|
|
|
Args:
|
|
entity (:class:`telegram.Update` | :class:`telegram.Message`): The ``update`` or
|
|
``message`` to extract from.
|
|
|
|
Returns:
|
|
:obj:`str` | :obj:`None`: One of :class:`telegram.constants.MessageType` if the entity
|
|
contains a message that matches one of those types. :obj:`None` otherwise.
|
|
|
|
"""
|
|
# Importing on file-level yields cyclic Import Errors
|
|
from telegram import Message, Update # pylint: disable=import-outside-toplevel
|
|
|
|
if isinstance(entity, Message):
|
|
message = entity
|
|
elif isinstance(entity, Update):
|
|
if not entity.effective_message:
|
|
return None
|
|
message = entity.effective_message
|
|
else:
|
|
raise TypeError(f"The entity is neither Message nor Update (got: {type(entity)})")
|
|
|
|
for message_type in MessageType:
|
|
if message[message_type]:
|
|
return message_type
|
|
|
|
return None
|
|
|
|
|
|
def create_deep_linked_url(
|
|
bot_username: str, payload: Optional[str] = None, group: bool = False
|
|
) -> str:
|
|
"""
|
|
Creates a deep-linked URL for this :paramref:`~create_deep_linked_url.bot_username` with the
|
|
specified :paramref:`~create_deep_linked_url.payload`. See
|
|
https://core.telegram.org/bots/features#deep-linking to learn more.
|
|
|
|
The :paramref:`~create_deep_linked_url.payload` may consist of the following characters:
|
|
``A-Z, a-z, 0-9, _, -``
|
|
|
|
Note:
|
|
Works well in conjunction with
|
|
``CommandHandler("start", callback, filters=filters.Regex('payload'))``
|
|
|
|
Examples:
|
|
* ``create_deep_linked_url(bot.get_me().username, "some-params")``
|
|
* :any:`Deep Linking <examples.deeplinking>`
|
|
|
|
Args:
|
|
bot_username (:obj:`str`): The username to link to.
|
|
payload (:obj:`str`, optional): Parameters to encode in the created URL.
|
|
group (:obj:`bool`, optional): If :obj:`True` the user is prompted to select a group to
|
|
add the bot to. If :obj:`False`, opens a one-on-one conversation with the bot.
|
|
Defaults to :obj:`False`.
|
|
|
|
Returns:
|
|
:obj:`str`: An URL to start the bot with specific parameters.
|
|
|
|
Raises:
|
|
:exc:`ValueError`: If the length of the :paramref:`payload` exceeds 64 characters,
|
|
contains invalid characters, or if the :paramref:`bot_username` is less than 4
|
|
characters.
|
|
"""
|
|
if bot_username is None or len(bot_username) <= 3:
|
|
raise ValueError("You must provide a valid bot_username.")
|
|
|
|
base_url = f"https://t.me/{bot_username}"
|
|
if not payload:
|
|
return base_url
|
|
|
|
if len(payload) > 64:
|
|
raise ValueError("The deep-linking payload must not exceed 64 characters.")
|
|
|
|
if not re.match(r"^[A-Za-z0-9_-]+$", payload):
|
|
raise ValueError(
|
|
"Only the following characters are allowed for deep-linked "
|
|
"URLs: A-Z, a-z, 0-9, _ and -"
|
|
)
|
|
|
|
key = "startgroup" if group else "start"
|
|
|
|
return f"{base_url}?{key}={payload}"
|