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 CHANGED
@@ -13,7 +13,7 @@ __all__ = [
13
13
  "Client",
14
14
  ]
15
15
 
16
- __version__ = "0.10.2.dev2"
16
+ __version__ = "1.0.0b1"
17
17
  __copyright__ = "Copyright (c) 2022-2026 Pytdbot, AYMENJD"
18
18
  __license__ = "MIT License"
19
19
 
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 Python client).
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
- Async [TDLib](https://github.com/tdlib/td) wrapper for Telegram users/bots in Python. It is not the HTTP Bot API — use Pytdbot/TDLib names and types only.
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 | When to use | Example |
17
- | ------------------- | -------------------------------------------- | ------------------------------------------------ |
18
- | `search <query>` | Find symbols by keyword | `python -m pytdbot.docs search "send photo"` |
19
- | `function <name>` | Full TDLib method signature | `python -m pytdbot.docs function sendMessage` |
20
- | `type <name>` | Fields of a TDLib type | `python -m pytdbot.docs type message` |
21
- | `class <name>` | Abstract class → concrete types | `python -m pytdbot.docs class InputFile` |
22
- | `update <name>` | Update payload shape | `python -m pytdbot.docs update updateNewMessage` |
23
- | `helper [name]` | Pytdbot bound methods, Client helpers, utils | `python -m pytdbot.docs helper reply_text` |
24
- | `helper -q <query>` | Search helpers only | `python -m pytdbot.docs helper -q escape` |
25
- | `stats` | Counts / TDLib version | `python -m pytdbot.docs stats` |
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
- Flags: `--json` for machine-readable output; `search --kind function` (or `type`, `class`, `update`, `helper`) to narrow results.
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 (`paragraph`, `heading`, `image`, …) and `rich_message_to_html` for rich / `sendRichMessage` flows
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`.