Pytdbot 0.10.2.dev2__py3-none-any.whl → 1.0.0b1__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.
- pytdbot/__init__.py +1 -1
- pytdbot/ai/SKILL.md +100 -16
- pytdbot/ai/helpers.json +349 -84
- pytdbot/ai/lookup.py +2 -2
- pytdbot/client.py +10 -21
- pytdbot/docs.py +158 -63
- pytdbot/handlers/td_updates.py +296 -1
- pytdbot/methods/methods.py +110 -3
- pytdbot/methods/td_functions.py +462 -14
- pytdbot/td_api.json +767 -51
- pytdbot/types/__init__.py +51 -3
- pytdbot/types/bound_methods/message.py +201 -30
- pytdbot/types/td_types.py +2284 -512
- pytdbot/utils/__init__.py +10 -0
- pytdbot/utils/diff.py +72 -0
- pytdbot/utils/rich_converter.py +377 -149
- pytdbot/utils/rich_messages.py +158 -4
- pytdbot/utils/text_format.py +236 -1
- {pytdbot-0.10.2.dev2.dist-info → pytdbot-1.0.0b1.dist-info}/METADATA +18 -6
- {pytdbot-0.10.2.dev2.dist-info → pytdbot-1.0.0b1.dist-info}/RECORD +24 -23
- {pytdbot-0.10.2.dev2.dist-info → pytdbot-1.0.0b1.dist-info}/WHEEL +1 -1
- {pytdbot-0.10.2.dev2.dist-info → pytdbot-1.0.0b1.dist-info}/entry_points.txt +0 -0
- {pytdbot-0.10.2.dev2.dist-info → pytdbot-1.0.0b1.dist-info}/licenses/LICENSE +0 -0
- {pytdbot-0.10.2.dev2.dist-info → pytdbot-1.0.0b1.dist-info}/top_level.txt +0 -0
pytdbot/__init__.py
CHANGED
pytdbot/ai/SKILL.md
CHANGED
|
@@ -1,38 +1,41 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: pytdbot
|
|
3
3
|
description: >
|
|
4
|
-
Write Telegram bots and userbots with Pytdbot (async TDLib
|
|
4
|
+
Write Telegram bots and userbots with Pytdbot (async TDLib wrapper
|
|
5
|
+
with high-level helpers; not the Telegram Bot API).
|
|
5
6
|
Use when the user works with Pytdbot, TDLib, or pytdbot.Client.
|
|
6
7
|
---
|
|
7
8
|
|
|
8
9
|
# Pytdbot
|
|
9
10
|
|
|
10
|
-
|
|
11
|
+
Pytdbot is an async [TDLib](https://github.com/tdlib/td) wrapper for Telegram users/bots in Python, with high-level helpers (bound methods, Client helpers, utils). It is **not** the HTTP Telegram Bot API — do not use Bot API method names, types, or libraries. Use Pytdbot/TDLib names and types only.
|
|
11
12
|
|
|
12
13
|
## `python -m pytdbot.docs` (use this for the API)
|
|
13
14
|
|
|
14
15
|
Before calling an unfamiliar method or building a type, run the docs CLI. It searches the installed library and prints parameters, types, and descriptions.
|
|
15
16
|
|
|
16
|
-
| Command
|
|
17
|
-
|
|
|
18
|
-
| `search <query>`
|
|
19
|
-
| `function <name
|
|
20
|
-
| `type <name
|
|
21
|
-
| `class <name
|
|
22
|
-
| `update <name
|
|
23
|
-
| `helper [name]` | Pytdbot bound methods, Client helpers, utils | `python -m pytdbot.docs helper reply_text`
|
|
24
|
-
| `helper -q <query>`
|
|
25
|
-
| `
|
|
17
|
+
| Command | When to use | Example |
|
|
18
|
+
| -------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------- |
|
|
19
|
+
| `search <query>` | Find symbols by keyword | `python -m pytdbot.docs search "send photo"` |
|
|
20
|
+
| `function <name…>` | Full TDLib method signature(s) | `python -m pytdbot.docs function sendMessage getChat` |
|
|
21
|
+
| `type <name…>` | Fields of a TDLib type | `python -m pytdbot.docs type message` |
|
|
22
|
+
| `class <name…>` | Abstract class → concrete types | `python -m pytdbot.docs class InputFile` |
|
|
23
|
+
| `update <name…>` | Update payload shape | `python -m pytdbot.docs update updateNewMessage` |
|
|
24
|
+
| `helper [name…]` | Pytdbot bound methods, Client helpers, utils | `python -m pytdbot.docs helper reply_text reply_photo` |
|
|
25
|
+
| `helper -q <query>` | Search helpers only | `python -m pytdbot.docs helper -q escape` |
|
|
26
|
+
| `batch <kind:name…>` | Mixed lookups in one call | `python -m pytdbot.docs batch function:sendMessage type:message helper:reply_text` |
|
|
27
|
+
| `stats` | Counts / TDLib version | `python -m pytdbot.docs stats` |
|
|
26
28
|
|
|
27
29
|
Workflow: `search` → pick a name → `function` / `type` / `class` / `helper` for full detail.
|
|
28
|
-
|
|
30
|
+
Prefer one invocation: pass several names, or `batch kind:name …` (`function`/`fn`, `type`, `class`, `update`, `helper`).
|
|
31
|
+
Flags: `--json` for machine-readable output (one name is still a single object; several names and `batch` are a JSON array); `search --kind function` (or `type`, `class`, `update`, `helper`) to narrow results.
|
|
29
32
|
Also available as `pytdbot-docs` after install. Same commands either way.
|
|
30
33
|
|
|
31
34
|
## Preference order
|
|
32
35
|
|
|
33
36
|
1. Bound methods — `message.reply_text`, `message.reply_photo`, `message.text`, …
|
|
34
37
|
2. Client helpers — `sendTextMessage`, `sendPhoto`, `sendAlbum`, `parseText`, …
|
|
35
|
-
3. `pytdbot.utils` — formatting, callback data, escapes, …
|
|
38
|
+
3. `pytdbot.utils` — formatting (including rich messages), callback data, escapes, …
|
|
36
39
|
4. TDLib methods on `Client` — `sendMessage`, `getChat`, … (camelCase)
|
|
37
40
|
|
|
38
41
|
## Basic bot
|
|
@@ -83,7 +86,7 @@ Parse mode on helpers: `"html"`, `"markdown"`, `"markdownv2"` (or `default_parse
|
|
|
83
86
|
await message.reply_text("<b>hi</b>", parse_mode="html")
|
|
84
87
|
```
|
|
85
88
|
|
|
86
|
-
Inline keyboard + callback (with `utils.callback_data`)
|
|
89
|
+
Inline keyboard + callback (with `utils.callback_data`). For **rich messages**, use `utils.tg_button` instead unless the user asks for an inline keyboard — see [Rich messages](#rich-messages).
|
|
87
90
|
|
|
88
91
|
```python
|
|
89
92
|
from pytdbot import utils
|
|
@@ -139,7 +142,7 @@ Signatures: `python -m pytdbot.docs helper bold` / `helper -q webapp`.
|
|
|
139
142
|
- **Mini Apps (Web App)**: `create_webapp_secret_key(bot_token)` → secret; `parse_webapp_data(secret_key, init_data, max_data_age=60)` → validated `dict` (raises `WebAppDataInvalid` / `WebAppDataOutdated` / `WebAppDataMismatch` from `pytdbot.exception`)
|
|
140
143
|
- **Flood / retry**: `get_retry_after_time(error_message)`
|
|
141
144
|
- **Other**: `get_bot_id_from_token`, `get_message_sender_id`
|
|
142
|
-
- **Rich messages**: builders
|
|
145
|
+
- **Rich messages**: builders and send helpers — see [Rich messages](#rich-messages)
|
|
143
146
|
|
|
144
147
|
```python
|
|
145
148
|
from pytdbot import utils
|
|
@@ -152,6 +155,87 @@ secret = utils.create_webapp_secret_key(bot_token)
|
|
|
152
155
|
data = utils.parse_webapp_data(secret, init_data)
|
|
153
156
|
```
|
|
154
157
|
|
|
158
|
+
## Rich messages
|
|
159
|
+
|
|
160
|
+
TDLib rich messages (not Bot API). Build HTML with `pytdbot.utils` helpers (they return strings; join with `+`), then send. Signatures: `python -m pytdbot.docs helper reply_rich_message` / `helper tg_button` / `helper -q tg_`.
|
|
161
|
+
|
|
162
|
+
```python
|
|
163
|
+
from pytdbot import utils
|
|
164
|
+
|
|
165
|
+
html = (
|
|
166
|
+
utils.heading(1, "Title")
|
|
167
|
+
+ utils.paragraph("Hello ", utils.bold(name))
|
|
168
|
+
+ utils.unordered_list("one", "two")
|
|
169
|
+
+ utils.tg_button_row(
|
|
170
|
+
utils.tg_button("OK", type="callback_data", data="ok", style="success"),
|
|
171
|
+
utils.tg_button("Site", type="url", url="https://example.com"),
|
|
172
|
+
)
|
|
173
|
+
)
|
|
174
|
+
await message.reply_rich_message(html=html)
|
|
175
|
+
# or: await client.sendRichMessage(chat_id, html=html)
|
|
176
|
+
# markdown= instead of html= is also accepted (not both)
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Edit later with `client.editRichMessage`. Convert a received rich payload with `utils.rich_message_to_html`.
|
|
180
|
+
|
|
181
|
+
### Formatting
|
|
182
|
+
|
|
183
|
+
Usual HTML helpers work inside rich HTML too: `bold`, `italic`, `underline`, `strikethrough`, `spoiler`, `code`, `pre` / `pre_code`, `hyperlink`, `mention`, `custom_emoji`, `quote`.
|
|
184
|
+
|
|
185
|
+
| Helper | Role |
|
|
186
|
+
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
|
|
187
|
+
| `paragraph(*children)` | Paragraph. Put inline `tg_button`s here |
|
|
188
|
+
| `heading(level, text, name=None)` | `h1`–`h6`; optional in-doc anchor `name` |
|
|
189
|
+
| `footer(*children)`, `newline(count=1)`, `horizontal_rule()` | Footer, `<br>`, `<hr>` |
|
|
190
|
+
| `marked`, `subscript`, `superscript` | Highlight / sub / sup |
|
|
191
|
+
| `thinking(text)` | Telegram thinking block |
|
|
192
|
+
| `tg_math` / `tg_math_block` | Inline / block LaTeX |
|
|
193
|
+
| `tg_time(unix, format, text="")` | Date-time entity |
|
|
194
|
+
| `tg_reference(name, text)`, `anchor(name)`, `in_doc_link(anchor, text)` | In-document references |
|
|
195
|
+
| `email_link(address, text)`, `phone(number, text)` | `mailto:` / `tel:` |
|
|
196
|
+
| `blockquote(*children, cite=None, expandable=False)`, `aside(*children, cite=None)` | Quotes |
|
|
197
|
+
| `details(*children, summary, open=False)` | Collapsible block |
|
|
198
|
+
| `unordered_list(*items)`, `ordered_list(*items, start=, type=, reversed=)`, `list_item(*children, value=, checked=, type=)` | Lists; `checked=` makes a checkbox item |
|
|
199
|
+
| `table(*rows, bordered=, striped=, compact=, caption=)`, `table_row`, `table_header`, `table_cell`, `table_header_cell` | Tables (`align` / `valign` / `colspan` / `rowspan` on cells) |
|
|
200
|
+
| `image(src, alt=, spoiler=)`, `video(src, spoiler=)`, `audio(src)`, `tg_document(src)` | Media (`src` URL or `tg://…` media id) |
|
|
201
|
+
| `figure(*children)`, `figcaption(*children)` | Figure + caption |
|
|
202
|
+
| `tg_map(lat, long, zoom)`, `tg_collage(*media, caption=)`, `tg_slideshow(*media, caption=)` | Map / collage / slideshow |
|
|
203
|
+
|
|
204
|
+
### Buttons
|
|
205
|
+
|
|
206
|
+
If you are sending a **rich message**, prefer `utils.tg_button` / `utils.tg_button_row` (rich-message buttons). Do **not** attach `reply_markup=types.ReplyMarkupInlineKeyboard(...)` unless the user explicitly asks for an inline keyboard.
|
|
207
|
+
|
|
208
|
+
- **Inline** (in the text flow): put `tg_button(...)` inside `paragraph(...)`.
|
|
209
|
+
- **Row** (full-width bar): pass buttons to `tg_button_row(*buttons, align=None)`. `align` is `"left"`, `"center"`, or `"right"`; omit it for full-width buttons.
|
|
210
|
+
|
|
211
|
+
```python
|
|
212
|
+
html = utils.paragraph(
|
|
213
|
+
"Pick: ",
|
|
214
|
+
utils.tg_button("Go", type="callback_data", data=utils.callback_data("ok", {"id": 1}), style="success"),
|
|
215
|
+
) + utils.tg_button_row(
|
|
216
|
+
utils.tg_button("Open", type="url", url="https://t.me"),
|
|
217
|
+
utils.tg_button("Copy", type="copy_text", text="hello"),
|
|
218
|
+
)
|
|
219
|
+
await message.reply_rich_message(html=html)
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
`tg_button(*label, type, …)`:
|
|
223
|
+
|
|
224
|
+
| `type` | Extra args |
|
|
225
|
+
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
226
|
+
| `url` | `url=`; user buttons: `url="tg://user?id=…"` |
|
|
227
|
+
| `callback_data` | `data=` (`str` or `bytes` from `utils.callback_data`) |
|
|
228
|
+
| `web_app` | `url=` |
|
|
229
|
+
| `login_url` | `url=`, optional `forward_text=`, `request_write_access=` |
|
|
230
|
+
| `switch_inline_query` / `switch_inline_query_current_chat` | `query=` |
|
|
231
|
+
| `switch_inline_query_chosen_chat` | `query=`, `allow_user_chats=`, `allow_bot_chats=`, `allow_group_chats=`, `allow_channel_chats=` |
|
|
232
|
+
| `copy_text` | `text=` (clipboard) |
|
|
233
|
+
| `disabled` | no extra args |
|
|
234
|
+
|
|
235
|
+
`style=` (optional): `"primary"`, `"danger"`, `"success"`, `"link"` (`"link"` only on callback buttons).
|
|
236
|
+
|
|
237
|
+
Callback presses are still `on_updateNewCallbackQuery` + `utils.load_callback_data` / `update.answer(...)`, same as a normal inline keyboard.
|
|
238
|
+
|
|
155
239
|
## Plugins
|
|
156
240
|
|
|
157
241
|
Split handlers into modules under a folder; pass `types.Plugins` into `Client`.
|