Pytdbot 0.10.1.dev0__py3-none-any.whl → 0.10.2.dev1__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 +215 -0
- pytdbot/ai/__init__.py +5 -0
- pytdbot/ai/helpers.json +5271 -0
- pytdbot/ai/lookup.py +326 -0
- pytdbot/docs.py +203 -0
- pytdbot/handlers/td_updates.py +133 -15
- pytdbot/methods/methods.py +179 -19
- pytdbot/methods/td_functions.py +431 -64
- pytdbot/td_api.json +55825 -0
- pytdbot/types/__init__.py +113 -25
- pytdbot/types/bound_methods/callback_query.py +10 -0
- pytdbot/types/bound_methods/message.py +43 -6
- pytdbot/types/td_types.py +3439 -894
- pytdbot/utils/__init__.py +6 -0
- pytdbot/utils/common.py +14 -0
- pytdbot/utils/rich_messages.py +29 -0
- {pytdbot-0.10.1.dev0.dist-info → pytdbot-0.10.2.dev1.dist-info}/METADATA +14 -2
- {pytdbot-0.10.1.dev0.dist-info → pytdbot-0.10.2.dev1.dist-info}/RECORD +23 -15
- {pytdbot-0.10.1.dev0.dist-info → pytdbot-0.10.2.dev1.dist-info}/WHEEL +1 -1
- pytdbot-0.10.2.dev1.dist-info/entry_points.txt +2 -0
- {pytdbot-0.10.1.dev0.dist-info → pytdbot-0.10.2.dev1.dist-info}/licenses/LICENSE +0 -0
- {pytdbot-0.10.1.dev0.dist-info → pytdbot-0.10.2.dev1.dist-info}/top_level.txt +0 -0
pytdbot/__init__.py
CHANGED
pytdbot/ai/SKILL.md
ADDED
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pytdbot
|
|
3
|
+
description: >
|
|
4
|
+
Write Telegram bots and userbots with Pytdbot (async TDLib Python client).
|
|
5
|
+
Use when the user works with Pytdbot, TDLib, or pytdbot.Client.
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Pytdbot
|
|
9
|
+
|
|
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
|
+
|
|
12
|
+
## `python -m pytdbot.docs` (use this for the API)
|
|
13
|
+
|
|
14
|
+
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
|
+
| 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` |
|
|
26
|
+
|
|
27
|
+
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.
|
|
29
|
+
Also available as `pytdbot-docs` after install. Same commands either way.
|
|
30
|
+
|
|
31
|
+
## Preference order
|
|
32
|
+
|
|
33
|
+
1. Bound methods — `message.reply_text`, `message.reply_photo`, `message.text`, …
|
|
34
|
+
2. Client helpers — `sendTextMessage`, `sendPhoto`, `sendAlbum`, `parseText`, …
|
|
35
|
+
3. `pytdbot.utils` — formatting, callback data, escapes, …
|
|
36
|
+
4. TDLib methods on `Client` — `sendMessage`, `getChat`, … (camelCase)
|
|
37
|
+
|
|
38
|
+
## Basic bot
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
import asyncio
|
|
42
|
+
from pytdbot import Client, types
|
|
43
|
+
|
|
44
|
+
client = Client(
|
|
45
|
+
token="BOT_TOKEN",
|
|
46
|
+
api_id=0,
|
|
47
|
+
api_hash="API_HASH",
|
|
48
|
+
files_directory="BotDB",
|
|
49
|
+
database_encryption_key="change-me",
|
|
50
|
+
)
|
|
51
|
+
|
|
52
|
+
@client.on_message()
|
|
53
|
+
async def on_msg(c: Client, message: types.Message):
|
|
54
|
+
if message.text:
|
|
55
|
+
await message.reply_text(message.text)
|
|
56
|
+
|
|
57
|
+
asyncio.run(client.run())
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Userbot: `user_bot=True` (no token) and handle authorization — see `examples/userbot.py`.
|
|
61
|
+
|
|
62
|
+
## Handlers
|
|
63
|
+
|
|
64
|
+
- `async def handler(client, update_or_message)`
|
|
65
|
+
- `@client.on_message()` → `types.Message`
|
|
66
|
+
- `@client.on_updateNewMessage()` / other `on_update…` → full update
|
|
67
|
+
- Filters: `from pytdbot import filters` → `filters.create(...)` then `@client.on_message(filters=my_filter)`
|
|
68
|
+
|
|
69
|
+
## Common patterns
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
@client.on_message()
|
|
73
|
+
async def echo(c: Client, message: types.Message):
|
|
74
|
+
if isinstance(message.content, types.MessageText):
|
|
75
|
+
await message.reply_text(message.text, entities=message.entities)
|
|
76
|
+
elif isinstance(message.content, types.MessagePhoto):
|
|
77
|
+
await message.reply_photo(message.remote_file_id, caption=message.caption)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Parse mode on helpers: `"html"`, `"markdown"`, `"markdownv2"` (or `default_parse_mode=` on `Client`).
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
await message.reply_text("<b>hi</b>", parse_mode="html")
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Inline keyboard + callback (with `utils.callback_data`):
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
from pytdbot import utils
|
|
90
|
+
|
|
91
|
+
await message.reply_text(
|
|
92
|
+
"Pick",
|
|
93
|
+
reply_markup=types.ReplyMarkupInlineKeyboard(
|
|
94
|
+
rows=[[
|
|
95
|
+
types.InlineKeyboardButton(
|
|
96
|
+
text="OK",
|
|
97
|
+
type=types.InlineKeyboardButtonTypeCallback(
|
|
98
|
+
data=utils.callback_data("ok", {"id": 1})
|
|
99
|
+
),
|
|
100
|
+
),
|
|
101
|
+
]]
|
|
102
|
+
),
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
@client.on_updateNewCallbackQuery()
|
|
106
|
+
async def on_cb(c: Client, update: types.UpdateNewCallbackQuery):
|
|
107
|
+
cb = utils.load_callback_data(update.payload.data)
|
|
108
|
+
# cb.action, cb.data
|
|
109
|
+
await update.answer(text="done")
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
async with message.action("typing"):
|
|
114
|
+
await asyncio.sleep(1)
|
|
115
|
+
await message.reply_text("Done")
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
await client.sendPhoto(chat_id, photo="path_or_remote_id", caption="Hi", parse_mode="html")
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Raw TDLib: look up with `function` / `type` first, then call; build objects with `types.*`.
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
chat = await client.getChat(chat_id=chat_id)
|
|
126
|
+
if not chat: # Error is falsy; success types are truthy
|
|
127
|
+
return
|
|
128
|
+
# use chat...
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## `pytdbot.utils`
|
|
132
|
+
|
|
133
|
+
Import: `from pytdbot import utils` (or `from pytdbot.utils import bold, escape_html, …`).
|
|
134
|
+
Signatures: `python -m pytdbot.docs helper bold` / `helper -q webapp`.
|
|
135
|
+
|
|
136
|
+
- **Text format** (HTML by default; MarkdownV2 with `html=False`): `bold`, `italic`, `underline`, `strikethrough`, `spoiler`, `code`, `pre`, `pre_code`, `hyperlink`, `mention`, `custom_emoji`, `quote`, `rtl`, `ltr`
|
|
137
|
+
- **Escape**: `escape_html`, `escape_markdown`
|
|
138
|
+
- **Callback buttons**: `callback_data(action, data=None)` → `bytes` (max 64); `load_callback_data(data)` → `.action` / `.data`
|
|
139
|
+
- **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
|
+
- **Flood / retry**: `get_retry_after_time(error_message)`
|
|
141
|
+
- **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
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
from pytdbot import utils
|
|
146
|
+
|
|
147
|
+
text = f"Hello {utils.bold(name)} — {utils.hyperlink('site', url)}"
|
|
148
|
+
await message.reply_text(text, parse_mode="html")
|
|
149
|
+
|
|
150
|
+
# Mini App initData validation
|
|
151
|
+
secret = utils.create_webapp_secret_key(bot_token)
|
|
152
|
+
data = utils.parse_webapp_data(secret, init_data)
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## Plugins
|
|
156
|
+
|
|
157
|
+
Split handlers into modules under a folder; pass `types.Plugins` into `Client`.
|
|
158
|
+
|
|
159
|
+
```python
|
|
160
|
+
from pytdbot import Client, types
|
|
161
|
+
|
|
162
|
+
client = Client(
|
|
163
|
+
token="BOT_TOKEN",
|
|
164
|
+
api_id=0,
|
|
165
|
+
api_hash="API_HASH",
|
|
166
|
+
files_directory="BotDB",
|
|
167
|
+
database_encryption_key="change-me",
|
|
168
|
+
plugins=types.Plugins(
|
|
169
|
+
folder="plugins/",
|
|
170
|
+
# optional: only these modules (dotted path = folder + file)
|
|
171
|
+
# include=["plugins.rules", "plugins.admin.ban"],
|
|
172
|
+
# optional: skip modules
|
|
173
|
+
# exclude=["plugins.experimental"],
|
|
174
|
+
),
|
|
175
|
+
)
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
**`Plugins`**
|
|
179
|
+
|
|
180
|
+
| Arg | Meaning |
|
|
181
|
+
| --------- | ------------------------------------------------------------------------------------------ |
|
|
182
|
+
| `folder` | Directory to scan for `*.py` (recursive) |
|
|
183
|
+
| `include` | If set, only load modules whose path matches (e.g. `plugins.rules` for `plugins/rules.py`) |
|
|
184
|
+
| `exclude` | If set (and no `include`), skip these module paths |
|
|
185
|
+
|
|
186
|
+
**Plugin module** (`plugins/ping.py`) — decorate with `Client.…` (no client instance); those handlers are picked up when the client starts with `plugins=…`:
|
|
187
|
+
|
|
188
|
+
```python
|
|
189
|
+
from pytdbot import Client, types, filters
|
|
190
|
+
|
|
191
|
+
private = filters.create(lambda _, m: m.chat_id > 0)
|
|
192
|
+
|
|
193
|
+
@Client.on_message(filters=private)
|
|
194
|
+
async def ping(c: Client, message: types.Message):
|
|
195
|
+
if message.text == "/ping":
|
|
196
|
+
await message.reply_text("pong")
|
|
197
|
+
|
|
198
|
+
@Client.on_updateNewCallbackQuery()
|
|
199
|
+
async def on_cb(c: Client, update: types.UpdateNewCallbackQuery):
|
|
200
|
+
await update.answer(text="ok")
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Same decorator API as on a live client: `on_message`, `on_updateNewMessage`, `on_updateNewCallbackQuery`, `initializer`, `finalizer`, other `on_update…`, plus `filters=`, `position=`, `timeout=`. Handlers must be `async`.
|
|
204
|
+
|
|
205
|
+
**Runtime**
|
|
206
|
+
|
|
207
|
+
- Loaded when `Client` is constructed with `plugins=…` (folder must be importable; usually run from project root so `plugins.*` imports work).
|
|
208
|
+
- `client.reload_plugins()` — reloads plugin modules (**dev only**, not for production). Handlers registered on the client instance itself are left alone.
|
|
209
|
+
- `client.remove_handler(func)` — remove a specific handler function.
|
|
210
|
+
|
|
211
|
+
## Details
|
|
212
|
+
|
|
213
|
+
- Types: `from pytdbot import Client, types` → `types.SomeType(...)`.
|
|
214
|
+
- Bots: `token=`; userbots: `user_bot=True` + authorization updates.
|
|
215
|
+
- `files_directory` + `database_encryption_key` required; one live client per directory.
|