1#!/usr/bin/env python
2#
3# A library that provides a Python interface to the Telegram Bot API
4# Copyright (C) 2015-2020
5# Leandro Toledo de Souza <devs@python-telegram-bot.org>
6#
7# This program is free software: you can redistribute it and/or modify
8# it under the terms of the GNU Lesser Public License as published by
9# the Free Software Foundation, either version 3 of the License, or
10# (at your option) any later version.
11#
12# This program is distributed in the hope that it will be useful,
13# but WITHOUT ANY WARRANTY; without even the implied warranty of
14# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15# GNU Lesser Public License for more details.
16#
17# You should have received a copy of the GNU Lesser Public License
18# along with this program.  If not, see [http://www.gnu.org/licenses/].
19"""This module contains an object that represents a Telegram MessageEntity."""
20
21from typing import TYPE_CHECKING, Any, List, Optional, ClassVar
22
23from telegram import TelegramObject, User, constants
24from telegram.utils.types import JSONDict
25
26if TYPE_CHECKING:
27    from telegram import Bot
28
29
30class MessageEntity(TelegramObject):
31    """
32    This object represents one special entity in a text message. For example, hashtags,
33    usernames, URLs, etc.
34
35    Objects of this class are comparable in terms of equality. Two objects of this class are
36    considered equal, if their :attr:`type`, :attr:`offset` and :attr`length` are equal.
37
38    Attributes:
39        type (:obj:`str`): Type of the entity.
40        offset (:obj:`int`): Offset in UTF-16 code units to the start of the entity.
41        length (:obj:`int`): Length of the entity in UTF-16 code units.
42        url (:obj:`str`): Optional. Url that will be opened after user taps on the text.
43        user (:class:`telegram.User`): Optional. The mentioned user.
44        language (:obj:`str`): Optional. Programming language of the entity text.
45
46    Args:
47        type (:obj:`str`): Type of the entity. Can be mention (@username), hashtag, bot_command,
48            url, email, phone_number, bold (bold text), italic (italic text), strikethrough,
49            code (monowidth string), pre (monowidth block), text_link (for clickable text URLs),
50            text_mention (for users without usernames).
51        offset (:obj:`int`): Offset in UTF-16 code units to the start of the entity.
52        length (:obj:`int`): Length of the entity in UTF-16 code units.
53        url (:obj:`str`, optional): For :attr:`TEXT_LINK` only, url that will be opened after
54            user taps on the text.
55        user (:class:`telegram.User`, optional): For :attr:`TEXT_MENTION` only, the mentioned
56             user.
57        language (:obj:`str`, optional): For :attr:`PRE` only, the programming language of
58            the entity text.
59
60    """
61
62    def __init__(
63        self,
64        type: str,  # pylint: disable=W0622
65        offset: int,
66        length: int,
67        url: str = None,
68        user: User = None,
69        language: str = None,
70        **_kwargs: Any,
71    ):
72        # Required
73        self.type = type
74        self.offset = offset
75        self.length = length
76        # Optionals
77        self.url = url
78        self.user = user
79        self.language = language
80
81        self._id_attrs = (self.type, self.offset, self.length)
82
83    @classmethod
84    def de_json(cls, data: Optional[JSONDict], bot: 'Bot') -> Optional['MessageEntity']:
85        data = cls.parse_data(data)
86
87        if not data:
88            return None
89
90        data['user'] = User.de_json(data.get('user'), bot)
91
92        return cls(**data)
93
94    MENTION: ClassVar[str] = constants.MESSAGEENTITY_MENTION
95    """:const:`telegram.constants.MESSAGEENTITY_MENTION`"""
96    HASHTAG: ClassVar[str] = constants.MESSAGEENTITY_HASHTAG
97    """:const:`telegram.constants.MESSAGEENTITY_HASHTAG`"""
98    CASHTAG: ClassVar[str] = constants.MESSAGEENTITY_CASHTAG
99    """:const:`telegram.constants.MESSAGEENTITY_CASHTAG`"""
100    PHONE_NUMBER: ClassVar[str] = constants.MESSAGEENTITY_PHONE_NUMBER
101    """:const:`telegram.constants.MESSAGEENTITY_PHONE_NUMBER`"""
102    BOT_COMMAND: ClassVar[str] = constants.MESSAGEENTITY_BOT_COMMAND
103    """:const:`telegram.constants.MESSAGEENTITY_BOT_COMMAND`"""
104    URL: ClassVar[str] = constants.MESSAGEENTITY_URL
105    """:const:`telegram.constants.MESSAGEENTITY_URL`"""
106    EMAIL: ClassVar[str] = constants.MESSAGEENTITY_EMAIL
107    """:const:`telegram.constants.MESSAGEENTITY_EMAIL`"""
108    BOLD: ClassVar[str] = constants.MESSAGEENTITY_BOLD
109    """:const:`telegram.constants.MESSAGEENTITY_BOLD`"""
110    ITALIC: ClassVar[str] = constants.MESSAGEENTITY_ITALIC
111    """:const:`telegram.constants.MESSAGEENTITY_ITALIC`"""
112    CODE: ClassVar[str] = constants.MESSAGEENTITY_CODE
113    """:const:`telegram.constants.MESSAGEENTITY_CODE`"""
114    PRE: ClassVar[str] = constants.MESSAGEENTITY_PRE
115    """:const:`telegram.constants.MESSAGEENTITY_PRE`"""
116    TEXT_LINK: ClassVar[str] = constants.MESSAGEENTITY_TEXT_LINK
117    """:const:`telegram.constants.MESSAGEENTITY_TEXT_LINK`"""
118    TEXT_MENTION: ClassVar[str] = constants.MESSAGEENTITY_TEXT_MENTION
119    """:const:`telegram.constants.MESSAGEENTITY_TEXT_MENTION`"""
120    UNDERLINE: ClassVar[str] = constants.MESSAGEENTITY_UNDERLINE
121    """:const:`telegram.constants.MESSAGEENTITY_UNDERLINE`"""
122    STRIKETHROUGH: ClassVar[str] = constants.MESSAGEENTITY_STRIKETHROUGH
123    """:const:`telegram.constants.MESSAGEENTITY_STRIKETHROUGH`"""
124    ALL_TYPES: ClassVar[List[str]] = constants.MESSAGEENTITY_ALL_TYPES
125    """:const:`telegram.constants.MESSAGEENTITY_ALL_TYPES`\n
126    List of all the types"""
127