tdlib-oracle 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,29 @@
1
+ """Telegram Bot API message validator for HTML and MarkdownV2, ported from TDLib.
2
+
3
+ Public surface
4
+ --------------
5
+ - `check`: the pinned Bot API server's verdict on a bot's message text.
6
+ - `Verdict`: what `check` returns: the server's refusal, or the text it keeps.
7
+ - `Refusal`: the error description the server refuses a text with.
8
+ - `Entity`: a formatting entity of the kept text, in the Bot API's form.
9
+ - `BOT_API_VERSION`: the Bot API release whose server the verdicts reproduce.
10
+ - `BOT_API_COMMIT`: the pinned commit of `tdlib/telegram-bot-api`.
11
+ - `TDLIB_COMMIT`: the pinned commit of `tdlib/td`.
12
+ """
13
+
14
+ from tdlib_oracle.server import Entity, Refusal, Verdict, check
15
+
16
+ __version__ = "0.1.0"
17
+ BOT_API_VERSION = "10.4"
18
+ BOT_API_COMMIT = "7232881b39dfcd048a0d569f1983c5184249ee05"
19
+ TDLIB_COMMIT = "c8828d50f5eac2fc7089ce1089d7ce9095c61b5e"
20
+
21
+ __all__ = [
22
+ "BOT_API_COMMIT",
23
+ "BOT_API_VERSION",
24
+ "TDLIB_COMMIT",
25
+ "Entity",
26
+ "Refusal",
27
+ "Verdict",
28
+ "check",
29
+ ]
@@ -0,0 +1 @@
1
+ """The Bot API server's request checks and error descriptions."""
@@ -0,0 +1,28 @@
1
+ # Ported from telegram-bot-api/Client.cpp of the Telegram Bot API server at the commit
2
+ # in tdlib_oracle.BOT_API_COMMIT.
3
+ #
4
+ # Copyright Aliaksei Levin (levlam@telegram.org), Arseny Smirnov (arseny30@gmail.com)
5
+ # 2014-2026. Distributed under the Boost Software License, Version 1.0;
6
+ # see LICENSES/BSL-1.0.txt.
7
+ """The Bot API server's checks on a text field before TDLib sees it."""
8
+
9
+ from tdlib_oracle.text.failure import Failure
10
+
11
+ _MAX_TEXT_SIZE = 1 << 15 # 32,768 bytes
12
+
13
+
14
+ # Ported from telegram-bot-api/Client.cpp, Client::get_formatted_text(), for a text
15
+ # without a parse mode or entities.
16
+ def _get_formatted_text(text: bytes) -> bytes | Failure:
17
+ if len(text) > _MAX_TEXT_SIZE:
18
+ return Failure(400, "Text is too long")
19
+ return text
20
+
21
+
22
+ # Ported from telegram-bot-api/Client.cpp, Client::get_input_message_text(td::string
23
+ # text, ...), for a text without link preview options.
24
+ def get_input_message_text(text: bytes) -> bytes | Failure:
25
+ """Return the text as the Bot API server passes it to TDLib, or its `Failure`."""
26
+ if not text:
27
+ return Failure(400, "Message text is empty")
28
+ return _get_formatted_text(text)
@@ -0,0 +1,53 @@
1
+ # Ported from telegram-bot-api/Client.cpp of the Telegram Bot API server at the commit
2
+ # in tdlib_oracle.BOT_API_COMMIT, and from tdutils/td/utils/misc.h of TDLib at the
3
+ # commit in tdlib_oracle.TDLIB_COMMIT.
4
+ #
5
+ # Copyright Aliaksei Levin (levlam@telegram.org), Arseny Smirnov (arseny30@gmail.com)
6
+ # 2014-2026. Distributed under the Boost Software License, Version 1.0;
7
+ # see LICENSES/BSL-1.0.txt.
8
+ """The Bot API server's error descriptions."""
9
+
10
+ from tdlib_oracle.text.failure import Failure
11
+
12
+
13
+ # Ported from tdutils/td/utils/misc.h, to_lower(char c).
14
+ def _to_lower(c: str) -> str:
15
+ if "A" <= c <= "Z":
16
+ return chr(ord(c) - ord("A") + ord("a"))
17
+ return c
18
+
19
+
20
+ # Ported from telegram-bot-api/Client.cpp,
21
+ # Client::fail_query_with_error(PromisedQueryPtr query, int32 error_code, ...), without
22
+ # the rate-limit branch and the table of backend errors, which no check of a
23
+ # text reaches.
24
+ def get_error_description(failure: Failure) -> str:
25
+ """Return the error description the Bot API server gives a client for `failure`."""
26
+ code = failure.code
27
+ message = failure.message
28
+ if code < 400 or code == 404:
29
+ code = 400
30
+ elif code == 403 and all(
31
+ c == "_" or "A" <= c <= "Z" or "0" <= c <= "9" for c in message
32
+ ):
33
+ code = 400
34
+
35
+ match code:
36
+ case 400:
37
+ prefix = "Bad Request"
38
+ case 401:
39
+ prefix = "Unauthorized"
40
+ case 403:
41
+ prefix = "Forbidden"
42
+ case 500:
43
+ prefix = "Internal Server Error"
44
+ case _:
45
+ return f"Bad Request: {message}"
46
+
47
+ if message.startswith(prefix):
48
+ return message
49
+ if not message:
50
+ return prefix
51
+ if len(message) >= 2 and (message[1] == "_" or "A" <= message[1] <= "Z"):
52
+ return f"{prefix}: {message}"
53
+ return f"{prefix}: {_to_lower(message[0])}{message[1:]}"
@@ -0,0 +1,9 @@
1
+ """Exception hierarchy rooted at `TDLibOracleError`."""
2
+
3
+
4
+ class TDLibOracleError(Exception):
5
+ """Root of the exceptions the package defines.
6
+
7
+ Each exception class the package defines derives from it, so one `except` clause
8
+ catches them all.
9
+ """
tdlib_oracle/py.typed ADDED
File without changes
tdlib_oracle/server.py ADDED
@@ -0,0 +1,126 @@
1
+ """The pinned Bot API server's handling of a message text, and the verdict it gives.
2
+
3
+ `check` runs a text through the server's call order: the Bot API server's checks, then
4
+ TDLib's processing. `Verdict`, `Refusal`, and `Entity`, the types of its result, are
5
+ defined here too.
6
+ """
7
+
8
+ from dataclasses import dataclass
9
+
10
+ from tdlib_oracle.botapi.checks import get_input_message_text
11
+ from tdlib_oracle.botapi.descriptions import get_error_description
12
+ from tdlib_oracle.tdlib.content import get_input_message_content
13
+ from tdlib_oracle.text.failure import Failure
14
+
15
+
16
+ @dataclass(frozen=True)
17
+ class Refusal:
18
+ """The pinned Bot API server's refusal of a text.
19
+
20
+ Attributes:
21
+ description: The error description the server returns, such
22
+ as `Bad Request: message is too long`.
23
+ offset: The byte offset the description names, or `None` when it names none.
24
+ """
25
+
26
+ description: str
27
+ offset: int | None
28
+
29
+
30
+ @dataclass(frozen=True)
31
+ class Entity:
32
+ """A formatting entity of the kept text, in the Bot API's `MessageEntity` form.
33
+
34
+ Attributes:
35
+ type: The entity type, in the Bot API's names, such as `bold` or `text_link`.
36
+ offset: Where the entity starts, in UTF-16 code units.
37
+ length: The length of the entity, in UTF-16 code units.
38
+ url: The URL a `text_link` opens.
39
+ user_id: The user a `text_mention` names.
40
+ language: The programming language of a `pre` block.
41
+ custom_emoji_id: The custom emoji a `custom_emoji` shows.
42
+ unix_time: The Unix time a `date_time` shows.
43
+ date_time_format: The format a `date_time` shows its time in.
44
+ depends_on_backend: Whether Telegram's backend, not TDLib, decides if the
45
+ entity survives.
46
+ """
47
+
48
+ type: str
49
+ offset: int
50
+ length: int
51
+ url: str | None = None
52
+ user_id: int | None = None
53
+ language: str | None = None
54
+ custom_emoji_id: str | None = None
55
+ unix_time: int | None = None
56
+ date_time_format: str | None = None
57
+ depends_on_backend: bool = False
58
+
59
+
60
+ @dataclass(frozen=True)
61
+ class Verdict:
62
+ """The pinned Bot API server's verdict on a text: its refusal or the text it keeps.
63
+
64
+ `text` is `None` exactly when `accepted` is false, which is also exactly when
65
+ `refusal` is set.
66
+
67
+ Attributes:
68
+ accepted: Whether the server accepts the text.
69
+ text: The text the server keeps, or `None` when it refuses the text.
70
+ entities: The formatting entities of the kept text.
71
+ refusal: The server's refusal, or `None` when it accepts the text.
72
+ depends_on_backend: Whether Telegram's backend decides if an entity survives.
73
+ """
74
+
75
+ accepted: bool
76
+ text: str | None
77
+ entities: tuple[Entity, ...]
78
+ refusal: Refusal | None
79
+ depends_on_backend: bool
80
+
81
+
82
+ def _encode(text: object) -> bytes:
83
+ """Return `text` as the bytes the server receives.
84
+
85
+ Raises:
86
+ TypeError: If `text` is neither `str` nor `bytes`.
87
+ """
88
+ if isinstance(text, str):
89
+ return text.encode("utf-8", "surrogatepass")
90
+ if isinstance(text, bytes):
91
+ return text
92
+ raise TypeError(f"text must be str or bytes, not {type(text).__name__}")
93
+
94
+
95
+ def check(text: str | bytes) -> Verdict:
96
+ """Return the pinned Bot API server's verdict on a bot's message text.
97
+
98
+ A `str` stands for what a client sends: it is encoded as UTF-8, and a surrogate code
99
+ point keeps its 3-byte form, which the server refuses as invalid UTF-8. `bytes`
100
+ stand for the field as the server receives it.
101
+
102
+ Raises:
103
+ TypeError: If `text` is neither `str` nor `bytes`.
104
+ """
105
+ result = get_input_message_text(_encode(text))
106
+ if not isinstance(result, Failure):
107
+ result = get_input_message_content(result)
108
+
109
+ if isinstance(result, Failure):
110
+ # No refusal of a plain text names a byte offset.
111
+ refusal = Refusal(description=get_error_description(result), offset=None)
112
+ return Verdict(
113
+ accepted=False,
114
+ text=None,
115
+ entities=(),
116
+ refusal=refusal,
117
+ depends_on_backend=False,
118
+ )
119
+
120
+ return Verdict(
121
+ accepted=True,
122
+ text=result.decode("utf-8", "replace"),
123
+ entities=(),
124
+ refusal=None,
125
+ depends_on_backend=False,
126
+ )
@@ -0,0 +1 @@
1
+ """TDLib's processing of a message text before it is sent."""
@@ -0,0 +1,198 @@
1
+ # Ported from td/telegram/misc.cpp and tdutils/td/utils/misc.h of TDLib at the commit
2
+ # in tdlib_oracle.TDLIB_COMMIT.
3
+ #
4
+ # Copyright Aliaksei Levin (levlam@telegram.org), Arseny Smirnov (arseny30@gmail.com)
5
+ # 2014-2026. Distributed under the Boost Software License, Version 1.0;
6
+ # see LICENSES/BSL-1.0.txt.
7
+ """TDLib's cleaning of input strings, and its test for a text of blank characters."""
8
+
9
+ from tdlib_oracle.text.utf8 import (
10
+ check_utf8,
11
+ is_utf8_character_first_code_unit,
12
+ utf8_truncate,
13
+ )
14
+
15
+ # Ported from td/telegram/misc.cpp, LENGTH_LIMIT in clean_input_string().
16
+ _LENGTH_LIMIT = 35000 # server-side limit
17
+
18
+ # Ported from tdutils/td/utils/misc.h, is_space(), the characters it accepts.
19
+ _SPACES = b" \t\r\n\x00\x0b"
20
+
21
+ # Ported from td/telegram/misc.cpp, space_characters in strip_empty_characters(). Each
22
+ # space character takes 3 bytes.
23
+ _SPACE_CHARACTERS = tuple(
24
+ chr(code_point).encode()
25
+ for code_point in (
26
+ 0x1680,
27
+ 0x180E,
28
+ 0x2000,
29
+ 0x2001,
30
+ 0x2002,
31
+ 0x2003,
32
+ 0x2004,
33
+ 0x2005,
34
+ 0x2006,
35
+ 0x2007,
36
+ 0x2008,
37
+ 0x2009,
38
+ 0x200A,
39
+ 0x202E,
40
+ 0x202F,
41
+ 0x205F,
42
+ 0x2800,
43
+ 0x3000,
44
+ 0xFFFC,
45
+ )
46
+ )
47
+
48
+ # Ported from td/telegram/misc.cpp, can_be_first in strip_empty_characters(). The byte
49
+ # 0xF3 can start a tag character, U+E0000 to U+E007F.
50
+ _CAN_BE_FIRST = frozenset(character[0] for character in _SPACE_CHARACTERS) | {0xF3}
51
+
52
+ # Ported from td/telegram/misc.cpp, strip_empty_characters(), its check for U+202E.
53
+ _RTLO = chr(0x202E).encode()
54
+
55
+
56
+ def _byte_at(text: bytes | bytearray, index: int) -> int:
57
+ """Return the byte at `index`, or `0` past the end like the C++ terminator."""
58
+ return text[index] if index < len(text) else 0
59
+
60
+
61
+ # Ported from tdutils/td/utils/misc.h, trim().
62
+ def _trim(text: bytes) -> bytes:
63
+ return text.strip(_SPACES)
64
+
65
+
66
+ # Ported from td/telegram/misc.cpp, replace_offending_characters().
67
+ def _replace_offending_characters(text: bytearray) -> None:
68
+ """Turn each U+200E or U+200F mark that another follows into U+200C, in place."""
69
+ pos = 0
70
+ while pos < len(text):
71
+ if (
72
+ text[pos] == 0xE2
73
+ and _byte_at(text, pos + 1) == 0x80
74
+ and _byte_at(text, pos + 2) in (0x8E, 0x8F)
75
+ ):
76
+ while (
77
+ _byte_at(text, pos + 3) == 0xE2
78
+ and _byte_at(text, pos + 4) == 0x80
79
+ and _byte_at(text, pos + 5) in (0x8E, 0x8F)
80
+ ):
81
+ text[pos + 2] = 0x8C
82
+ pos += 3
83
+ pos += 2
84
+ pos += 1
85
+
86
+
87
+ # Ported from td/telegram/misc.cpp, clean_input_string().
88
+ def clean_input_string(text: bytes) -> bytes | None:
89
+ """Return `text` cleaned as TDLib cleans input strings, or `None` if not UTF-8.
90
+
91
+ Control characters become spaces, except line feeds, which stay, and carriage
92
+ returns, which are dropped along with U+2028 to U+202E and the combining marks
93
+ U+030A, U+0333, and U+033F. In a run of U+200E and U+200F marks, each but the last
94
+ becomes U+200C. The string is cut before the first character that starts at offset
95
+ 34,996 or later, so it stays under the 35,000-byte server-side limit.
96
+ """
97
+ if not check_utf8(text):
98
+ return None
99
+
100
+ result = bytearray()
101
+ size = len(text)
102
+ pos = 0
103
+ while pos < size:
104
+ c = text[pos]
105
+ if c <= 0x20 and c not in (0x0A, 0x0D):
106
+ result.append(0x20)
107
+ elif c == 0x0D:
108
+ pass # a carriage return is dropped
109
+ elif (
110
+ c == 0xE2
111
+ and pos + 2 < size
112
+ and text[pos + 1] == 0x80
113
+ and 0xA8 <= text[pos + 2] <= 0xAE
114
+ ):
115
+ pos += 2
116
+ elif c == 0xCC and pos + 1 < size and text[pos + 1] in (0xB3, 0xBF, 0x8A):
117
+ pos += 1
118
+ else:
119
+ result.append(c)
120
+ if len(result) >= _LENGTH_LIMIT - 3 and (
121
+ is_utf8_character_first_code_unit(result[-1])
122
+ ):
123
+ del result[-1]
124
+ break
125
+ pos += 1
126
+
127
+ _replace_offending_characters(result)
128
+ return bytes(result)
129
+
130
+
131
+ # Ported from td/telegram/misc.cpp, strip_empty_characters().
132
+ def strip_empty_characters( # noqa: PLR0912 # mirrors upstream
133
+ text: bytes, max_length: int, strip_rtlo: bool = False
134
+ ) -> bytes:
135
+ """Return `text` trimmed and cut to `max_length` code points, or empty if blank.
136
+
137
+ Unicode spaces and tag characters become spaces first, and so does U+202E with
138
+ `strip_rtlo`. The text is blank when nothing but spaces, line feeds, U+200B to
139
+ U+200F, U+202E, U+FEFF, and U+00A0 is left.
140
+ """
141
+ replaced = bytearray()
142
+ size = len(text)
143
+ i = 0
144
+ while i < size:
145
+ c = text[i]
146
+ if c in _CAN_BE_FIRST and i + 3 <= size:
147
+ if c == 0xF3:
148
+ if (
149
+ text[i + 1] == 0xA0
150
+ and (text[i + 2] & 0xFE) == 0x80
151
+ and i + 4 <= size
152
+ ):
153
+ replaced.append(0x20)
154
+ i += 4
155
+ continue
156
+ else:
157
+ found = False
158
+ for space in _SPACE_CHARACTERS:
159
+ if text[i : i + 3] == space:
160
+ found = space != _RTLO or strip_rtlo
161
+ break
162
+ if found:
163
+ replaced.append(0x20)
164
+ i += 3
165
+ continue
166
+ replaced.append(c)
167
+ i += 1
168
+
169
+ trimmed = _trim(utf8_truncate(_trim(bytes(replaced)), max_length))
170
+ i = 0
171
+ while i < len(trimmed):
172
+ c = trimmed[i]
173
+ if c in (0x20, 0x0A):
174
+ i += 1
175
+ continue
176
+ if c == 0xE2 and _byte_at(trimmed, i + 1) == 0x80:
177
+ following = _byte_at(trimmed, i + 2)
178
+ if 0x8B <= following <= 0x8F or following == 0xAE:
179
+ i += 3
180
+ continue
181
+ if (
182
+ c == 0xEF
183
+ and _byte_at(trimmed, i + 1) == 0xBB
184
+ and _byte_at(trimmed, i + 2) == 0xBF
185
+ ):
186
+ i += 3
187
+ continue
188
+ if c == 0xC2 and _byte_at(trimmed, i + 1) == 0xA0:
189
+ i += 2
190
+ continue
191
+ return trimmed
192
+ return b""
193
+
194
+
195
+ # Ported from td/telegram/misc.cpp, is_empty_string().
196
+ def is_empty_string(text: bytes) -> bool:
197
+ """Return whether `text` holds blank characters only."""
198
+ return not strip_empty_characters(text, len(text))
@@ -0,0 +1,44 @@
1
+ # Ported from td/telegram/InputMessageText.cpp, td/telegram/MessageContent.cpp, and
2
+ # td/telegram/OptionManager.cpp of TDLib at the commit in tdlib_oracle.TDLIB_COMMIT.
3
+ #
4
+ # Copyright Aliaksei Levin (levlam@telegram.org), Arseny Smirnov (arseny30@gmail.com)
5
+ # 2014-2026. Distributed under the Boost Software License, Version 1.0;
6
+ # see LICENSES/BSL-1.0.txt.
7
+ """TDLib's processing of an input message text, through its length check."""
8
+
9
+ from tdlib_oracle.tdlib.fixing import get_formatted_text
10
+ from tdlib_oracle.text.failure import Failure
11
+ from tdlib_oracle.text.utf8 import utf8_length
12
+
13
+ # Ported from td/telegram/OptionManager.cpp, OptionManager::OptionManager(), its default
14
+ # for the option message_text_length_max, which Telegram's configuration may raise.
15
+ _MESSAGE_TEXT_LENGTH_MAX = 4096
16
+
17
+
18
+ # Ported from td/telegram/InputMessageText.cpp, process_input_message_text(), for a text
19
+ # without link preview options.
20
+ def _process_input_message_text(text: bytes) -> bytes | Failure:
21
+ # Without a link preview URL, an empty text is refused and the text is trimmed.
22
+ return get_formatted_text(text, allow_empty=False, skip_trim=False)
23
+
24
+
25
+ # Ported from td/telegram/MessageContent.cpp, create_input_message_content(), its case
26
+ # of a message text.
27
+ def _create_input_message_content(text: bytes) -> bytes | Failure:
28
+ result = _process_input_message_text(text)
29
+ if isinstance(result, Failure):
30
+ return result
31
+ if utf8_length(result) > _MESSAGE_TEXT_LENGTH_MAX:
32
+ return Failure(400, "Message is too long")
33
+ return result
34
+
35
+
36
+ # Ported from td/telegram/MessageContent.cpp, get_input_message_content(), for a
37
+ # message text.
38
+ def get_input_message_content(text: bytes) -> bytes | Failure:
39
+ """Return the text TDLib keeps of a bot's message text, or its `Failure`.
40
+
41
+ A message text has no file and no caption, so none of the steps before the content
42
+ is created applies to it.
43
+ """
44
+ return _create_input_message_content(text)
@@ -0,0 +1,89 @@
1
+ # Ported from td/telegram/MessageEntity.cpp of TDLib at the commit
2
+ # in tdlib_oracle.TDLIB_COMMIT.
3
+ #
4
+ # Copyright Aliaksei Levin (levlam@telegram.org), Arseny Smirnov (arseny30@gmail.com)
5
+ # 2014-2026. Distributed under the Boost Software License, Version 1.0;
6
+ # see LICENSES/BSL-1.0.txt.
7
+ """TDLib's fixing of a formatted text: cleaning, trimming, and the emptiness checks."""
8
+
9
+ from tdlib_oracle.tdlib.cleaning import clean_input_string, is_empty_string
10
+ from tdlib_oracle.text.failure import Failure
11
+
12
+
13
+ # Ported from td/telegram/MessageEntity.cpp, remove_invalid_entities(), its path for a
14
+ # text without entities.
15
+ def _remove_invalid_entities(text: bytes) -> tuple[int, int]:
16
+ """Return the offset of the last byte that is neither a space nor a line feed.
17
+
18
+ When every byte is one of them, the offset is the length of `text` and the second
19
+ value is `-1`; otherwise the second value is `0`.
20
+ """
21
+ for pos in range(len(text)):
22
+ back_pos = len(text) - pos - 1
23
+ if text[back_pos] not in (0x0A, 0x20):
24
+ return back_pos, 0
25
+ return len(text), -1
26
+
27
+
28
+ # Ported from td/telegram/MessageEntity.cpp, fix_formatted_text(), its path for a text
29
+ # without entities.
30
+ def fix_formatted_text(
31
+ text: bytes, *, allow_empty: bool, allow_empty_string: bool, skip_trim: bool
32
+ ) -> bytes | Failure:
33
+ """Return `text` as TDLib fixes a formatted text, or the `Failure` that refuses it.
34
+
35
+ The text is cleaned, refused when only spaces and line feeds are left, trimmed of
36
+ them at both ends unless `skip_trim` is set, and refused again when only blank
37
+ characters are left. `allow_empty` turns both refusals into an empty text, and
38
+ `allow_empty_string` keeps a text of blank characters.
39
+ """
40
+ result = clean_input_string(text)
41
+ if result is None:
42
+ return Failure(400, "Strings must be encoded in UTF-8")
43
+
44
+ last_non_whitespace_pos, last_non_whitespace_utf16_offset = (
45
+ _remove_invalid_entities(result)
46
+ )
47
+ if last_non_whitespace_utf16_offset == -1:
48
+ if allow_empty:
49
+ return b""
50
+ return Failure(400, "Text must be non-empty")
51
+
52
+ if skip_trim:
53
+ fixed = result
54
+ else:
55
+ result = result[: last_non_whitespace_pos + 1]
56
+ ltrim_count = 0
57
+ while ltrim_count < len(result) and result[ltrim_count] in (0x0A, 0x20):
58
+ ltrim_count += 1
59
+ fixed = result[ltrim_count:]
60
+
61
+ if is_empty_string(fixed):
62
+ if not allow_empty:
63
+ return Failure(400, "Text must be non-empty")
64
+ if not allow_empty_string:
65
+ fixed = b""
66
+
67
+ # The C++ goes on to cut a text over 35,000 bytes, which cannot happen here, since
68
+ # `clean_input_string` stops short of that limit. It then adds the entities TDLib
69
+ # finds on its own, such as links and mentions, which verdicts leave out.
70
+ return fixed
71
+
72
+
73
+ # Ported from td/telegram/MessageEntity.cpp, get_formatted_text(const Td *td, ...), for
74
+ # a bot's text without entities.
75
+ def get_formatted_text(
76
+ text: bytes, *, allow_empty: bool, skip_trim: bool
77
+ ) -> bytes | Failure:
78
+ """Return a bot's `text` as TDLib fixes it, or the `Failure` that refuses it.
79
+
80
+ A bot sends the text, so a text of blank characters is kept exactly when an empty
81
+ text is allowed. The Bot API server never sets the `always_parse_markdown` option,
82
+ so no Markdown is parsed.
83
+ """
84
+ return fix_formatted_text(
85
+ text,
86
+ allow_empty=allow_empty,
87
+ allow_empty_string=allow_empty,
88
+ skip_trim=skip_trim,
89
+ )
@@ -0,0 +1 @@
1
+ """Values and text helpers that both domains share."""
@@ -0,0 +1,22 @@
1
+ """The error status a ported function returns instead of raising.
2
+
3
+ The pinned code refuses a request with an error `Status`: a code and a message. A
4
+ message can quote its input, which no exception may carry, so a ported function returns
5
+ a `Failure` where the C++ returns such a `Status`, and only the composition module turns
6
+ one into a refusal.
7
+ """
8
+
9
+ from dataclasses import dataclass
10
+
11
+
12
+ @dataclass(frozen=True)
13
+ class Failure:
14
+ """An error `Status` of the pinned code, as a value.
15
+
16
+ Attributes:
17
+ code: The status code, such as `400`.
18
+ message: The error message, worded as the pinned code words it.
19
+ """
20
+
21
+ code: int
22
+ message: str
@@ -0,0 +1,108 @@
1
+ # Ported from tdutils/td/utils/utf8.cpp and tdutils/td/utils/utf8.h of TDLib at the
2
+ # commit in tdlib_oracle.TDLIB_COMMIT.
3
+ #
4
+ # Copyright Aliaksei Levin (levlam@telegram.org), Arseny Smirnov (arseny30@gmail.com)
5
+ # 2014-2026. Distributed under the Boost Software License, Version 1.0;
6
+ # see LICENSES/BSL-1.0.txt.
7
+ """UTF-8 helpers of tdutils: validity, length in code points, and truncation."""
8
+
9
+ # Ported from tdutils/td/utils/utf8.cpp, the enum that opens with UTF8_REJECT: the
10
+ # states of the shift-based DFA that checks UTF-8 validity. The transitions by one byte
11
+ # are packed into one integer, which stores the next state for a state S in the 6 bits
12
+ # from bit S.
13
+ _UTF8_REJECT = 0 # zero, so that every unspecified transition leads to it
14
+ _UTF8_ACCEPT = 6
15
+ _UTF8_NEED_1 = 12 # 1 more continuation byte
16
+ _UTF8_NEED_2 = 18 # 2 more continuation bytes
17
+ _UTF8_NEED_3 = 24 # 3 more continuation bytes
18
+ _UTF8_AFTER_E0 = 30 # a continuation byte 0xa0-0xbf, then 1 more
19
+ _UTF8_AFTER_ED = 36 # a continuation byte 0x80-0x9f, then 1 more
20
+ _UTF8_AFTER_F0 = 42 # a continuation byte 0x90-0xbf, then 2 more
21
+ _UTF8_AFTER_F4 = 48 # a continuation byte 0x80-0x8f, then 2 more
22
+
23
+
24
+ # Ported from tdutils/td/utils/utf8.cpp, utf8_transition().
25
+ def _utf8_transition(from_state: int, to_state: int) -> int:
26
+ return to_state << from_state
27
+
28
+
29
+ # Ported from tdutils/td/utils/utf8.cpp, get_utf8_transitions().
30
+ def _get_utf8_transitions(c: int) -> int: # noqa: PLR0911, PLR0912 # mirrors upstream
31
+ if c < 0x80:
32
+ return _utf8_transition(_UTF8_ACCEPT, _UTF8_ACCEPT)
33
+ if c < 0xC0:
34
+ result = (
35
+ _utf8_transition(_UTF8_NEED_1, _UTF8_ACCEPT)
36
+ | _utf8_transition(_UTF8_NEED_2, _UTF8_NEED_1)
37
+ | _utf8_transition(_UTF8_NEED_3, _UTF8_NEED_2)
38
+ )
39
+ if c < 0xA0:
40
+ result |= _utf8_transition(_UTF8_AFTER_ED, _UTF8_NEED_1)
41
+ else:
42
+ result |= _utf8_transition(_UTF8_AFTER_E0, _UTF8_NEED_1)
43
+ if c < 0x90:
44
+ result |= _utf8_transition(_UTF8_AFTER_F4, _UTF8_NEED_2)
45
+ else:
46
+ result |= _utf8_transition(_UTF8_AFTER_F0, _UTF8_NEED_2)
47
+ return result
48
+ if c < 0xC2:
49
+ return 0 # overlong encoding
50
+ if c < 0xE0:
51
+ return _utf8_transition(_UTF8_ACCEPT, _UTF8_NEED_1)
52
+ if c == 0xE0:
53
+ # Prevent overlong encoding.
54
+ return _utf8_transition(_UTF8_ACCEPT, _UTF8_AFTER_E0)
55
+ if c == 0xED:
56
+ # Prevent surrogates.
57
+ return _utf8_transition(_UTF8_ACCEPT, _UTF8_AFTER_ED)
58
+ if c < 0xF0:
59
+ return _utf8_transition(_UTF8_ACCEPT, _UTF8_NEED_2)
60
+ if c == 0xF0:
61
+ # Prevent overlong encoding.
62
+ return _utf8_transition(_UTF8_ACCEPT, _UTF8_AFTER_F0)
63
+ if c < 0xF4:
64
+ return _utf8_transition(_UTF8_ACCEPT, _UTF8_NEED_3)
65
+ if c == 0xF4:
66
+ # Prevent code points after U+10FFFF.
67
+ return _utf8_transition(_UTF8_ACCEPT, _UTF8_AFTER_F4)
68
+ return 0
69
+
70
+
71
+ # Ported from tdutils/td/utils/utf8.cpp, Utf8Dfa.
72
+ _UTF8_DFA = tuple(_get_utf8_transitions(c) for c in range(256))
73
+
74
+
75
+ # Ported from tdutils/td/utils/utf8.cpp, check_utf8().
76
+ def check_utf8(text: bytes) -> bool:
77
+ """Return whether `text` is valid UTF-8.
78
+
79
+ Overlong encodings, surrogates, and code points past U+10FFFF are invalid.
80
+ """
81
+ state = _UTF8_ACCEPT
82
+ for byte in text:
83
+ state = _UTF8_DFA[byte] >> (state & 63)
84
+ return (state & 63) == _UTF8_ACCEPT
85
+
86
+
87
+ # Ported from tdutils/td/utils/utf8.h, is_utf8_character_first_code_unit().
88
+ def is_utf8_character_first_code_unit(c: int) -> bool:
89
+ """Return whether the byte `c` is the first byte of a UTF-8 character."""
90
+ return (c & 0xC0) != 0x80
91
+
92
+
93
+ # Ported from tdutils/td/utils/utf8.h, utf8_length().
94
+ def utf8_length(text: bytes) -> int:
95
+ """Return the length of `text` in code points."""
96
+ return sum(is_utf8_character_first_code_unit(c) for c in text)
97
+
98
+
99
+ # Ported from tdutils/td/utils/utf8.h, utf8_truncate().
100
+ def utf8_truncate(text: bytes, length: int) -> bytes:
101
+ """Return the first `length` code points of `text`."""
102
+ if len(text) > length:
103
+ for i, c in enumerate(text):
104
+ if is_utf8_character_first_code_unit(c):
105
+ if length == 0:
106
+ return text[:i]
107
+ length -= 1
108
+ return text
@@ -0,0 +1,111 @@
1
+ Metadata-Version: 2.5
2
+ Name: tdlib-oracle
3
+ Version: 0.1.0
4
+ Summary: Telegram Bot API message validator for HTML and MarkdownV2, ported from TDLib
5
+ Project-URL: Bug Tracker, https://github.com/theodiv/tdlib-oracle/issues
6
+ Project-URL: Changelog, https://github.com/theodiv/tdlib-oracle/blob/main/CHANGELOG.md
7
+ Project-URL: Documentation, https://github.com/theodiv/tdlib-oracle/tree/main/docs
8
+ Project-URL: Repository, https://github.com/theodiv/tdlib-oracle
9
+ Author: Theodosios Divolis
10
+ License-Expression: MIT AND BSL-1.0
11
+ License-File: LICENSE
12
+ License-File: LICENSES/BSL-1.0.txt
13
+ Keywords: bot-api,entities,html,markdown,markdownv2,parse-mode,tdlib,telegram,testing
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Programming Language :: Python :: 3.15
22
+ Classifier: Topic :: Communications :: Chat
23
+ Classifier: Topic :: Software Development :: Testing
24
+ Classifier: Topic :: Text Processing :: Markup :: HTML
25
+ Classifier: Topic :: Text Processing :: Markup :: Markdown
26
+ Classifier: Typing :: Typed
27
+ Requires-Python: >=3.11
28
+ Description-Content-Type: text/markdown
29
+
30
+ # TDLib Oracle
31
+
32
+ Catch Telegram's refusals and silent edits before sending.
33
+
34
+ [![License: MIT AND BSL-1.0](https://img.shields.io/badge/dynamic/toml?url=https://raw.githubusercontent.com/theodiv/tdlib-oracle/main/pyproject.toml&query=$.project.license&style=flat-square&label=License&color=yellow)](https://github.com/theodiv/tdlib-oracle/blob/main/LICENSE)
35
+ [![Python: 3.11+](https://img.shields.io/python/required-version-toml?tomlFilePath=https://raw.githubusercontent.com/theodiv/tdlib-oracle/main/pyproject.toml&style=flat-square&label=Python)](https://www.python.org/downloads/)
36
+ [![CI](https://img.shields.io/github/actions/workflow/status/theodiv/tdlib-oracle/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/theodiv/tdlib-oracle/actions/workflows/ci.yml)
37
+
38
+ ---
39
+
40
+ ## Overview
41
+
42
+ TDLib Oracle tells a test whether the Telegram Bot API server would accept a
43
+ bot's plain message text and what it would keep, by running the text through the
44
+ server's own checks and TDLib's processing, ported from their code at a pinned
45
+ Bot API release. It serves the test suites of Telegram bots and of the libraries
46
+ that build their messages, with no token and no network request. Sending the
47
+ message stays with the caller.
48
+
49
+ ## Features
50
+
51
+ - **The server's own refusals** — a refused text gets the Bot API's error
52
+ description, word for word, such as `Bad Request: message is too long`.
53
+ - **The text Telegram keeps** — an accepted text comes back as the pinned code
54
+ keeps it: `\r` dropped, other control characters turned into spaces, both
55
+ ends trimmed.
56
+ - **Pinned to a Bot API release** — each step is ported from the code of the Bot
57
+ API server and TDLib at the commits that `BOT_API_COMMIT` and
58
+ `TDLIB_COMMIT` name.
59
+
60
+ ## Example
61
+
62
+ ```pycon
63
+ >>> from tdlib_oracle import check
64
+ >>> check("Total:\t42 \r\n").text
65
+ 'Total: 42'
66
+ >>> check("\N{ZERO WIDTH SPACE}").refusal
67
+ Refusal(description='Bad Request: text must be non-empty', offset=None)
68
+ ```
69
+
70
+ ## Requirements
71
+
72
+ Python 3.11 or later. No runtime dependencies.
73
+
74
+ ## Installation
75
+
76
+ ```console
77
+ $ pip install tdlib-oracle
78
+ ```
79
+
80
+ ## Documentation
81
+
82
+ - [Library](https://github.com/theodiv/tdlib-oracle/blob/main/docs/library.md) —
83
+ every public name, with its parameters, return value, and exceptions.
84
+ - [Behavior](https://github.com/theodiv/tdlib-oracle/blob/main/docs/behavior.md) —
85
+ what happens to the input, step by step, and the limits on it.
86
+ - [Compatibility](https://github.com/theodiv/tdlib-oracle/blob/main/docs/compatibility.md) —
87
+ what a release may change, and what stays stable.
88
+
89
+ ## Contributing
90
+
91
+ Development setup, coding standards, and the pull request process are documented
92
+ in the [contributing guide](https://github.com/theodiv/tdlib-oracle/blob/main/CONTRIBUTING.md).
93
+
94
+ ## Code of Conduct
95
+
96
+ Expectations for every participant are set in the
97
+ [code of conduct](https://github.com/theodiv/tdlib-oracle/blob/main/CODE_OF_CONDUCT.md).
98
+
99
+ ## Changelog
100
+
101
+ Every change is recorded in the [changelog](https://github.com/theodiv/tdlib-oracle/blob/main/CHANGELOG.md).
102
+
103
+ ## Security
104
+
105
+ The vulnerability reporting and disclosure process is documented in the
106
+ [security policy](https://github.com/theodiv/tdlib-oracle/blob/main/SECURITY.md).
107
+
108
+ ---
109
+
110
+ Distributed under the [MIT License](https://github.com/theodiv/tdlib-oracle/blob/main/LICENSE)
111
+ and the [Boost Software License 1.0](https://github.com/theodiv/tdlib-oracle/blob/main/LICENSES/BSL-1.0.txt).
@@ -0,0 +1,19 @@
1
+ tdlib_oracle/__init__.py,sha256=1c37chIShhP5xV4sw-L0gj81Q_lXSnOtXT7IKSAsDsU,972
2
+ tdlib_oracle/exceptions.py,sha256=LHs4J2QZEIX6iMsv8WCS6d6IeO_5yJhdI0p7aM245l8,260
3
+ tdlib_oracle/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
4
+ tdlib_oracle/server.py,sha256=8OPuL9D3KszHGkXfBwOJaiUcr-UToTw37zKnw7m01y0,4249
5
+ tdlib_oracle/botapi/__init__.py,sha256=QOIzw8sKYDnjBKMouQ_R_GV2Pr2tputpG7HJ6cjdR2c,66
6
+ tdlib_oracle/botapi/checks.py,sha256=1BoSOatscYMfp3VlYSpw_uU0IPOCw_oeDM3fTrl_BTE,1143
7
+ tdlib_oracle/botapi/descriptions.py,sha256=MQFj42d7xktNW9uOzyE77Rfrn0nNTxuWDFoSbLaSl5g,1844
8
+ tdlib_oracle/tdlib/__init__.py,sha256=gGGH3Ai4jFOAtSxWqltWS1T4udx0xNvisBj9IPU2o6M,62
9
+ tdlib_oracle/tdlib/cleaning.py,sha256=yaiE125uLzAYa_hvB50IOddWjpm5GwtDGa2AW-c2C0k,6414
10
+ tdlib_oracle/tdlib/content.py,sha256=G-CAjwOx9TrgUzHg2svEV0zsm5m8xUJqTG8d-9m40uE,1954
11
+ tdlib_oracle/tdlib/fixing.py,sha256=4kc2tUw5q-QpCs_iWfpD7dx_KfxH4BVuacJ99YRHTRo,3507
12
+ tdlib_oracle/text/__init__.py,sha256=16NSmawFvOSRJxUuLD6gc2cFG9foescMT2nDWFhdX9I,55
13
+ tdlib_oracle/text/failure.py,sha256=I2LsN5zryds3vdhpEaHJQX_w9SjyfC-nJ7zHSqgESpw,658
14
+ tdlib_oracle/text/utf8.py,sha256=PolZPaH9LQLNTrYesZwXorzFeyUEQgwHo4Kldk6GyTU,4241
15
+ tdlib_oracle-0.1.0.dist-info/METADATA,sha256=l6KLCQ9bMt7dMftoHgGL1fntAm79qSNOs5rt4WRg290,4757
16
+ tdlib_oracle-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
17
+ tdlib_oracle-0.1.0.dist-info/licenses/LICENSE,sha256=4THsH2wYx5qaHXSWJvn-nLh5D10FsuO3iD1p1tc2q-o,1075
18
+ tdlib_oracle-0.1.0.dist-info/licenses/LICENSES/BSL-1.0.txt,sha256=yb_3VziSIZPmf6cm-iJVNYcNKqEFn5FFLEEXNihK1WY,1338
19
+ tdlib_oracle-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Theodosios Divolis
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,23 @@
1
+ Boost Software License - Version 1.0 - August 17th, 2003
2
+
3
+ Permission is hereby granted, free of charge, to any person or organization
4
+ obtaining a copy of the software and accompanying documentation covered by
5
+ this license (the "Software") to use, reproduce, display, distribute,
6
+ execute, and transmit the Software, and to prepare derivative works of the
7
+ Software, and to permit third-parties to whom the Software is furnished to
8
+ do so, all subject to the following:
9
+
10
+ The copyright notices in the Software and this entire statement, including
11
+ the above license grant, this restriction and the following disclaimer,
12
+ must be included in all copies of the Software, in whole or in part, and
13
+ all derivative works of the Software, unless such copies or derivative
14
+ works are solely in the form of machine-executable object code generated by
15
+ a source language processor.
16
+
17
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19
+ FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
20
+ SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
21
+ FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
22
+ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
23
+ DEALINGS IN THE SOFTWARE.