telekit 2.6.0a8__tar.gz → 2.6.1__tar.gz
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.
- {telekit-2.6.0a8 → telekit-2.6.1}/CHANGELOG.md +38 -14
- {telekit-2.6.0a8/telekit.egg-info → telekit-2.6.1}/PKG-INFO +72 -52
- {telekit-2.6.0a8 → telekit-2.6.1}/README.md +33 -37
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/__version__.py +1 -1
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_callback_query_handler.py +18 -3
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_inline_keyboard.py +93 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_reply_keyboard.py +34 -3
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_telekit_dsl/telekit_dsl.py +1 -1
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/reply_buttons.py +1 -1
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/senders.py +63 -7
- {telekit-2.6.0a8 → telekit-2.6.1/telekit.egg-info}/PKG-INFO +72 -52
- {telekit-2.6.0a8 → telekit-2.6.1}/LICENSE +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/MANIFEST.in +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/setup.cfg +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/setup.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/__init__.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_buildtext/__init__.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_buildtext/formatter.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_buildtext/styles.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_chain.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_chain_base.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_chain_entry_logic.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_chain_inline_keyboards_logic.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_chapters/__init__.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_chapters/chapters.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_file_cache.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_handler.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_init.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_inline_buttons.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_input_handler.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_logger.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_on.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_rich.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_snapvault/__init__.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_snapvault/snapcode.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_snapvault/snapvault.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_state.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_telekit_dsl/__init__.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_telekit_dsl/mixin.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_telekit_dsl/parser/__init__.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_telekit_dsl/parser/builder.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_telekit_dsl/parser/canvas_parser.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_telekit_dsl/parser/lexer.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_telekit_dsl/parser/nodes.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_telekit_dsl/parser/parser.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_telekit_dsl/parser/token.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_telekit_dsl/telekit_orm.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_text_builder.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_timeout.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_trait.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/_user.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/chat.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/debug.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/dices.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/__init__.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/__init__.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/article.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/calendar.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/complete_hotel.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/counter.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/dsl.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/entry.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/faq.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/hotel.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/on_text.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/pages.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/pyapi.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/qr.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/quiz.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/rich.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/spells.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/start.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/style.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_handlers/text_document.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/example/example_server.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/html_text.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/inline_buttons.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/parameters.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/requirements.txt +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/scheduler.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/server.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/styles.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/traits/__init__.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/traits/calendar_pick.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/traits/paginated_choice.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/traits/paginated_text.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/traits/track_handoff_origin.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/types.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit/utils.py +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit.egg-info/SOURCES.txt +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit.egg-info/dependency_links.txt +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit.egg-info/requires.txt +0 -0
- {telekit-2.6.0a8 → telekit-2.6.1}/telekit.egg-info/top_level.txt +0 -0
|
@@ -1,5 +1,36 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
## File ID Caching, Rich HTML, New Timeout Engine
|
|
2
|
+
|
|
3
|
+
**Telekit 2.6** speeds up file sending, makes bots more resilient and adds Rich HTML messages. What's new:
|
|
4
|
+
|
|
5
|
+
1. **File ID caching.** Local files are uploaded to Telegram once and reused on every next send.
|
|
6
|
+
2. **Rich HTML messages** (Bot API 10.1+).
|
|
7
|
+
3. **New timeout engine.** No more `can't start new thread` with ~1000 active chats (#6).
|
|
8
|
+
4. **Smart restarts.** The new `restart` parameter (`"always"`, `"network"`, `"never"`) with exponential backoff keeps the server alive through network failures.
|
|
9
|
+
5. **Keyboards in senders.** `set_keyboard()` and `to_markup()` let you attach keyboards to a plain `sender` without a chain.
|
|
10
|
+
6. **Full `.env` support.** Comments, quotes, multi-line values and `$VAR` interpolation.
|
|
11
|
+
7. **Better logging.** Rich output when `rich` is installed, bot tokens masked in logs, no duplicated records.
|
|
12
|
+
8. **Handoff shortcuts.** `handle_handoff()` and `handle_handoff_back_or()` work without closures.
|
|
13
|
+
|
|
14
|
+
### v2.6.1 – Fixes #7
|
|
15
|
+
- In groups, any chat member can now press the button (previously effectively broken for everyone).
|
|
16
|
+
|
|
17
|
+
### v2.6.0
|
|
18
|
+
- Stable release. See the `a0`–`a9` entries below for the full list of changes.
|
|
19
|
+
|
|
20
|
+
### v2.6.0 `a9` – Keyboards in Senders
|
|
21
|
+
- Added `InlineKeyboard.to_markup()`: compiles the keyboard into a ready-to-send `InlineKeyboardMarkup`. Only buttons that don't need a chain to register handlers are supported (`StaticButton`, `LinkButton` and its subclasses, `WebAppButton`, `SuggestButton`, `CopyTextButton`); callback-based buttons (`CallbackButton`, `InvokeButton`, `AnswerButton`, `AlertButton`, `NotificationButton`) raise `TypeError` and should be used via `chain.set_inline_keyboard()`
|
|
22
|
+
- Added `ReplyKeyboard.to_markup()`: a public counterpart of the internal `_compile()` that returns a `ReplyKeyboardMarkup`
|
|
23
|
+
- Added `set_keyboard()` to `BaseSender`: a shortcut for `set_reply_markup(keyboard.to_markup())` that accepts both `InlineKeyboard` and `ReplyKeyboard`, so keyboards can be passed to a plain `sender` without a chain
|
|
24
|
+
|
|
25
|
+
### v2.6.0 `a7` – Sender, Server, Logging
|
|
26
|
+
#### Sender: automatic `file_id` caching
|
|
27
|
+
- Added a `FileIdCache` that stores Telegram `file_id` for local files (photo, document, video, animation, audio, voice, video note), so repeated sends skip the upload
|
|
28
|
+
- Added `BaseSender.configure_file_cache()`: a class method that sets the database path, table name and global on/off switch
|
|
29
|
+
- Added `Sender.set_use_file_cache()`: a per-sender override of the global setting (`None` restores it)
|
|
30
|
+
- Changed missing local files to raise on `send()` instead of in the setter
|
|
31
|
+
- A rejected cached `file_id` is dropped and the send is retried with the original file
|
|
32
|
+
- Notes: URLs, `bytes` and file-like objects are not cached; rich messages and media groups are unaffected. A changed file is detected by `size/mtime`, with a `SHA-256` comparison as a fallback
|
|
33
|
+
#### Server: restarts and network protection
|
|
3
34
|
- Added `restart` parameter to `Server`: `"always"` (default), `"network"` or `"never"`; accepts `RestartMode` or the matching string
|
|
4
35
|
- Deprecated `Server(auto_restart=...)`: `True` is now `restart="always"`, `False` is `restart="never"`; emits `DeprecationWarning` and a log warning. Cannot be combined with `restart` (`TypeError`)
|
|
5
36
|
- Added network protection to `Server.polling()` and `Server.long_polling()`: restarts are now delayed by exponential backoff (5 s up to 60 s, reset after 120 s of stable work) instead of a fixed 10 s / 5 s. Tunable via `Server.RESTART_DELAY_MIN`, `RESTART_DELAY_MAX` and `STABLE_AFTER`
|
|
@@ -16,40 +47,33 @@
|
|
|
16
47
|
- Changed `telekit` loggers to `propagate=False`: records no longer reach the root logger, so they are not duplicated when the app configures it. Attach custom handlers to `logging.getLogger("telekit")`
|
|
17
48
|
- Changed `enable_file_logging()` to be idempotent, to create parent folders, and to use one format (with `filename:lineno`) for all files, including `server.log`
|
|
18
49
|
- Fixed `UserLogger` reporting its own module as the log source
|
|
19
|
-
#### Sender
|
|
20
|
-
- Added a `FileIdCache` that stores Telegram `file_id` for local files (photo, document, video, animation, audio, voice, video note), so repeated sends skip the upload
|
|
21
|
-
- Added `BaseSender.configure_file_cache()`: a class method that sets the database path, table name and global on/off switch
|
|
22
|
-
- Added `Sender.set_use_file_cache()`: a per-sender override of the global setting (`None` restores it)
|
|
23
|
-
- Changed missing local files to raise on `send()` instead of in the setter
|
|
24
|
-
- A rejected cached `file_id` is dropped and the send is retried with the original file
|
|
25
|
-
- Notes: URLs, `bytes` and file-like objects are not cached; rich messages and media groups are unaffected. A changed file is detected by `size/mtime`, with a `SHA-256` comparison as a fallback
|
|
26
50
|
|
|
27
|
-
### v2.6.0 `a6` (fixes #6)
|
|
51
|
+
### v2.6.0 `a6` (fixes #6) – Timeout engine
|
|
28
52
|
- Reworked the timeout engine to fix thread exhaustion with many concurrent chats (#6): every `set_timeout()` used to start its own `threading.Timer` (one OS thread per waiting chat), so ~1000 active users crashed the bot with `can't start new thread`
|
|
29
53
|
- Timeout callback exceptions are now logged
|
|
30
54
|
- Added `configure_timeouts(max_workers, *, idle_timeout, log_worker_changes, warn_on_max_workers)` to tune the worker pool, log worker start/stop, and control the "all workers busy" warning (enabled by default)
|
|
31
55
|
|
|
32
|
-
### v2.6.0 `a4`
|
|
56
|
+
### v2.6.0 `a4` – Handoff shortcuts
|
|
33
57
|
- Added `handle_handoff()` to `Handler`: a shortcut for `handoff(handler).handle()` that takes the target handler as an argument, so it can be passed to `add_callback()` without an extra closure
|
|
34
58
|
- Added `handle_handoff_back_or()` to `TrackHandoffOrigin`: a closure-free counterpart of `handoff_back_or()`
|
|
35
59
|
- Reworked `handoff_back_or()` as a thin `functools.partial` wrapper around `handle_handoff_back_or()`
|
|
36
60
|
- Fixed the `handoff_back_or()` docstring: the returned callable forwards its arguments to `handle()` instead of being zero-argument
|
|
37
61
|
- Converted the `handoff()` docstring to reST
|
|
38
62
|
|
|
39
|
-
### v2.6.0 `a3`
|
|
63
|
+
### v2.6.0 `a3` – Rich HTML
|
|
40
64
|
- Added support for Rich HTML messages (Bot API 10.1+)
|
|
41
65
|
- Added the `_rich.py` module for Rich HTML parsing and serialization
|
|
42
66
|
- Added new rich tags to `styles.py` for enhanced text formatting
|
|
43
67
|
- Added the `rich.py` example handler demonstrating Rich HTML: inline styles, blocks, lists, tables, media, and sender integration
|
|
44
68
|
|
|
45
|
-
### v2.6.0 `a2`
|
|
69
|
+
### v2.6.0 `a2` – Env parsing
|
|
46
70
|
- Reworked `.env` and token/canvas file reading in `utils`
|
|
47
71
|
- Added full `.env` syntax support: comments, `export`, quotes and escapes, multi-line values, `$VAR` interpolation
|
|
48
72
|
- Added the `cache` parameter (default `True`) and `clear_cache()`
|
|
49
73
|
- Added detailed errors with fix suggestions and creation commands, and new `Env*Error` exceptions
|
|
50
74
|
- Changed `load_env()` to raise `EnvFileNotFoundError` for a missing file instead of returning `{}`
|
|
51
75
|
|
|
52
|
-
### v2.6.0 `a1`
|
|
76
|
+
### v2.6.0 `a1` – Module loader
|
|
53
77
|
- Added a module-loading utility to `utils`
|
|
54
78
|
|
|
55
79
|
### v2.6.0 `a0`
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: telekit
|
|
3
|
-
Version: 2.6.
|
|
3
|
+
Version: 2.6.1
|
|
4
4
|
Summary: Declarative, developer-friendly framework for building Telegram bots
|
|
5
5
|
Home-page: https://github.com/Romashkaa/telekit
|
|
6
6
|
Author: romashka
|
|
@@ -134,41 +134,7 @@ def handle_name(self, name: str):
|
|
|
134
134
|
|
|
135
135
|
### Inline Keyboards
|
|
136
136
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
```python
|
|
140
|
-
self.chain.set_inline_keyboard(
|
|
141
|
-
{
|
|
142
|
-
"✏️ Change": self.change_name,
|
|
143
|
-
"❌ Delete": self.delete,
|
|
144
|
-
}
|
|
145
|
-
)
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
`row_width` controls how many buttons appear per row:
|
|
149
|
-
|
|
150
|
-
```python
|
|
151
|
-
self.chain.set_inline_keyboard(
|
|
152
|
-
{
|
|
153
|
-
"One": self.one,
|
|
154
|
-
"Two": self.two,
|
|
155
|
-
"Three": self.three,
|
|
156
|
-
"Four": self.four,
|
|
157
|
-
"Five": self.five,
|
|
158
|
-
},
|
|
159
|
-
row_width=(3, 2) # first row: 3 buttons, second row: 2
|
|
160
|
-
)
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
```
|
|
164
|
-
╭──────────┬──────────┬──────────╮
|
|
165
|
-
│ One │ Two │ Three │
|
|
166
|
-
├──────────┴──┬───────┴──────────┤
|
|
167
|
-
│ Four │ Five │
|
|
168
|
-
╰─────────────┴──────────────────╯
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
For precise row layout or conditional buttons, use `InlineKeyboard`, a builder you compose step by step:
|
|
137
|
+
Build a keyboard with `InlineKeyboard`, a fluent builder you compose step by step, and attach it with `set_keyboard`. Each `add_callback` takes a button label and the callback to run when it is pressed. Call `.row()` to start a new row:
|
|
172
138
|
|
|
173
139
|
```python
|
|
174
140
|
self.chain.set_keyboard(
|
|
@@ -190,6 +156,33 @@ self.chain.set_keyboard(
|
|
|
190
156
|
|
|
191
157
|
> `InlineKeyboard` is built by chaining method calls. Just call `.row()` to start a new row.
|
|
192
158
|
|
|
159
|
+
**Grid layout**
|
|
160
|
+
|
|
161
|
+
Wrap buttons in `.grid(width=...)` / `.grid_end()` to split them into rows of a fixed width automatically:
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
self.chain.set_keyboard(
|
|
165
|
+
InlineKeyboard()
|
|
166
|
+
.grid(width=3)
|
|
167
|
+
.add_callback("One", self.one)
|
|
168
|
+
.add_callback("Two", self.two)
|
|
169
|
+
.add_callback("Three", self.three)
|
|
170
|
+
.add_callback("Four", self.four)
|
|
171
|
+
.add_callback("Five", self.five)
|
|
172
|
+
.grid_end()
|
|
173
|
+
)
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
╭──────────┬──────────┬──────────╮
|
|
178
|
+
│ One │ Two │ Three │
|
|
179
|
+
├──────────┴──┬───────┴──────────┤
|
|
180
|
+
│ Four │ Five │
|
|
181
|
+
╰─────────────┴──────────────────╯
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Use `.column()` / `.column_end()` to put every button on its own row, and `.extend(...)` to add many buttons at once from a dict or list. Pass `when=...` to any method to add a button or row conditionally.
|
|
185
|
+
|
|
193
186
|
**Not just callback buttons**
|
|
194
187
|
|
|
195
188
|
| **Method** | **Description** |
|
|
@@ -269,14 +262,17 @@ class DialogueHandler(telekit.Handler):
|
|
|
269
262
|
|
|
270
263
|
def handle_feeling(self, feeling: str) -> None:
|
|
271
264
|
self.chain.sender.set_text(f"Got it, {self.user_name.title()}! You feel: {feeling}")
|
|
272
|
-
self.chain.
|
|
265
|
+
self.chain.set_keyboard(
|
|
266
|
+
InlineKeyboard()
|
|
267
|
+
.add_callback("↺ Restart", self.handle_hello)
|
|
268
|
+
)
|
|
273
269
|
self.chain.send()
|
|
274
270
|
```
|
|
275
271
|
|
|
276
272
|
How it works:
|
|
277
273
|
|
|
278
274
|
- The handler reacts to `"hello"`, `"hi"`, or `"hey"` in any case.
|
|
279
|
-
- `handle_hello` asks for the user's name
|
|
275
|
+
- `handle_hello` asks for the user's name.
|
|
280
276
|
- `set_entry_suggestions` attaches the user's Telegram `first_name` as a suggestion button.
|
|
281
277
|
- `handle_name` stores the name in `self.user_name`.
|
|
282
278
|
- `handle_feeling` closes the flow and adds a "↺ Restart" button that routes back to the start.
|
|
@@ -480,8 +476,39 @@ Telekit focuses on one job: making Telegram bot development easier.
|
|
|
480
476
|
|
|
481
477
|
# Changelog
|
|
482
478
|
|
|
483
|
-
|
|
484
|
-
|
|
479
|
+
## File ID Caching, Rich HTML, New Timeout Engine
|
|
480
|
+
|
|
481
|
+
**Telekit 2.6** speeds up file sending, makes bots more resilient and adds Rich HTML messages. What's new:
|
|
482
|
+
|
|
483
|
+
1. **File ID caching.** Local files are uploaded to Telegram once and reused on every next send.
|
|
484
|
+
2. **Rich HTML messages** (Bot API 10.1+).
|
|
485
|
+
3. **New timeout engine.** No more `can't start new thread` with ~1000 active chats (#6).
|
|
486
|
+
4. **Smart restarts.** The new `restart` parameter (`"always"`, `"network"`, `"never"`) with exponential backoff keeps the server alive through network failures.
|
|
487
|
+
5. **Keyboards in senders.** `set_keyboard()` and `to_markup()` let you attach keyboards to a plain `sender` without a chain.
|
|
488
|
+
6. **Full `.env` support.** Comments, quotes, multi-line values and `$VAR` interpolation.
|
|
489
|
+
7. **Better logging.** Rich output when `rich` is installed, bot tokens masked in logs, no duplicated records.
|
|
490
|
+
8. **Handoff shortcuts.** `handle_handoff()` and `handle_handoff_back_or()` work without closures.
|
|
491
|
+
|
|
492
|
+
### v2.6.1 – Fixes #7
|
|
493
|
+
- In groups, any chat member can now press the button (previously effectively broken for everyone).
|
|
494
|
+
|
|
495
|
+
### v2.6.0
|
|
496
|
+
- Stable release. See the `a0`–`a9` entries below for the full list of changes.
|
|
497
|
+
|
|
498
|
+
### v2.6.0 `a9` – Keyboards in Senders
|
|
499
|
+
- Added `InlineKeyboard.to_markup()`: compiles the keyboard into a ready-to-send `InlineKeyboardMarkup`. Only buttons that don't need a chain to register handlers are supported (`StaticButton`, `LinkButton` and its subclasses, `WebAppButton`, `SuggestButton`, `CopyTextButton`); callback-based buttons (`CallbackButton`, `InvokeButton`, `AnswerButton`, `AlertButton`, `NotificationButton`) raise `TypeError` and should be used via `chain.set_inline_keyboard()`
|
|
500
|
+
- Added `ReplyKeyboard.to_markup()`: a public counterpart of the internal `_compile()` that returns a `ReplyKeyboardMarkup`
|
|
501
|
+
- Added `set_keyboard()` to `BaseSender`: a shortcut for `set_reply_markup(keyboard.to_markup())` that accepts both `InlineKeyboard` and `ReplyKeyboard`, so keyboards can be passed to a plain `sender` without a chain
|
|
502
|
+
|
|
503
|
+
### v2.6.0 `a7` – Sender, Server, Logging
|
|
504
|
+
#### Sender: automatic `file_id` caching
|
|
505
|
+
- Added a `FileIdCache` that stores Telegram `file_id` for local files (photo, document, video, animation, audio, voice, video note), so repeated sends skip the upload
|
|
506
|
+
- Added `BaseSender.configure_file_cache()`: a class method that sets the database path, table name and global on/off switch
|
|
507
|
+
- Added `Sender.set_use_file_cache()`: a per-sender override of the global setting (`None` restores it)
|
|
508
|
+
- Changed missing local files to raise on `send()` instead of in the setter
|
|
509
|
+
- A rejected cached `file_id` is dropped and the send is retried with the original file
|
|
510
|
+
- Notes: URLs, `bytes` and file-like objects are not cached; rich messages and media groups are unaffected. A changed file is detected by `size/mtime`, with a `SHA-256` comparison as a fallback
|
|
511
|
+
#### Server: restarts and network protection
|
|
485
512
|
- Added `restart` parameter to `Server`: `"always"` (default), `"network"` or `"never"`; accepts `RestartMode` or the matching string
|
|
486
513
|
- Deprecated `Server(auto_restart=...)`: `True` is now `restart="always"`, `False` is `restart="never"`; emits `DeprecationWarning` and a log warning. Cannot be combined with `restart` (`TypeError`)
|
|
487
514
|
- Added network protection to `Server.polling()` and `Server.long_polling()`: restarts are now delayed by exponential backoff (5 s up to 60 s, reset after 120 s of stable work) instead of a fixed 10 s / 5 s. Tunable via `Server.RESTART_DELAY_MIN`, `RESTART_DELAY_MAX` and `STABLE_AFTER`
|
|
@@ -498,40 +525,33 @@ Telekit focuses on one job: making Telegram bot development easier.
|
|
|
498
525
|
- Changed `telekit` loggers to `propagate=False`: records no longer reach the root logger, so they are not duplicated when the app configures it. Attach custom handlers to `logging.getLogger("telekit")`
|
|
499
526
|
- Changed `enable_file_logging()` to be idempotent, to create parent folders, and to use one format (with `filename:lineno`) for all files, including `server.log`
|
|
500
527
|
- Fixed `UserLogger` reporting its own module as the log source
|
|
501
|
-
#### Sender
|
|
502
|
-
- Added a `FileIdCache` that stores Telegram `file_id` for local files (photo, document, video, animation, audio, voice, video note), so repeated sends skip the upload
|
|
503
|
-
- Added `BaseSender.configure_file_cache()`: a class method that sets the database path, table name and global on/off switch
|
|
504
|
-
- Added `Sender.set_use_file_cache()`: a per-sender override of the global setting (`None` restores it)
|
|
505
|
-
- Changed missing local files to raise on `send()` instead of in the setter
|
|
506
|
-
- A rejected cached `file_id` is dropped and the send is retried with the original file
|
|
507
|
-
- Notes: URLs, `bytes` and file-like objects are not cached; rich messages and media groups are unaffected. A changed file is detected by `size/mtime`, with a `SHA-256` comparison as a fallback
|
|
508
528
|
|
|
509
|
-
### v2.6.0 `a6` (fixes #6)
|
|
529
|
+
### v2.6.0 `a6` (fixes #6) – Timeout engine
|
|
510
530
|
- Reworked the timeout engine to fix thread exhaustion with many concurrent chats (#6): every `set_timeout()` used to start its own `threading.Timer` (one OS thread per waiting chat), so ~1000 active users crashed the bot with `can't start new thread`
|
|
511
531
|
- Timeout callback exceptions are now logged
|
|
512
532
|
- Added `configure_timeouts(max_workers, *, idle_timeout, log_worker_changes, warn_on_max_workers)` to tune the worker pool, log worker start/stop, and control the "all workers busy" warning (enabled by default)
|
|
513
533
|
|
|
514
|
-
### v2.6.0 `a4`
|
|
534
|
+
### v2.6.0 `a4` – Handoff shortcuts
|
|
515
535
|
- Added `handle_handoff()` to `Handler`: a shortcut for `handoff(handler).handle()` that takes the target handler as an argument, so it can be passed to `add_callback()` without an extra closure
|
|
516
536
|
- Added `handle_handoff_back_or()` to `TrackHandoffOrigin`: a closure-free counterpart of `handoff_back_or()`
|
|
517
537
|
- Reworked `handoff_back_or()` as a thin `functools.partial` wrapper around `handle_handoff_back_or()`
|
|
518
538
|
- Fixed the `handoff_back_or()` docstring: the returned callable forwards its arguments to `handle()` instead of being zero-argument
|
|
519
539
|
- Converted the `handoff()` docstring to reST
|
|
520
540
|
|
|
521
|
-
### v2.6.0 `a3`
|
|
541
|
+
### v2.6.0 `a3` – Rich HTML
|
|
522
542
|
- Added support for Rich HTML messages (Bot API 10.1+)
|
|
523
543
|
- Added the `_rich.py` module for Rich HTML parsing and serialization
|
|
524
544
|
- Added new rich tags to `styles.py` for enhanced text formatting
|
|
525
545
|
- Added the `rich.py` example handler demonstrating Rich HTML: inline styles, blocks, lists, tables, media, and sender integration
|
|
526
546
|
|
|
527
|
-
### v2.6.0 `a2`
|
|
547
|
+
### v2.6.0 `a2` – Env parsing
|
|
528
548
|
- Reworked `.env` and token/canvas file reading in `utils`
|
|
529
549
|
- Added full `.env` syntax support: comments, `export`, quotes and escapes, multi-line values, `$VAR` interpolation
|
|
530
550
|
- Added the `cache` parameter (default `True`) and `clear_cache()`
|
|
531
551
|
- Added detailed errors with fix suggestions and creation commands, and new `Env*Error` exceptions
|
|
532
552
|
- Changed `load_env()` to raise `EnvFileNotFoundError` for a missing file instead of returning `{}`
|
|
533
553
|
|
|
534
|
-
### v2.6.0 `a1`
|
|
554
|
+
### v2.6.0 `a1` – Module loader
|
|
535
555
|
- Added a module-loading utility to `utils`
|
|
536
556
|
|
|
537
557
|
### v2.6.0 `a0`
|
|
@@ -97,41 +97,7 @@ def handle_name(self, name: str):
|
|
|
97
97
|
|
|
98
98
|
### Inline Keyboards
|
|
99
99
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
```python
|
|
103
|
-
self.chain.set_inline_keyboard(
|
|
104
|
-
{
|
|
105
|
-
"✏️ Change": self.change_name,
|
|
106
|
-
"❌ Delete": self.delete,
|
|
107
|
-
}
|
|
108
|
-
)
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
`row_width` controls how many buttons appear per row:
|
|
112
|
-
|
|
113
|
-
```python
|
|
114
|
-
self.chain.set_inline_keyboard(
|
|
115
|
-
{
|
|
116
|
-
"One": self.one,
|
|
117
|
-
"Two": self.two,
|
|
118
|
-
"Three": self.three,
|
|
119
|
-
"Four": self.four,
|
|
120
|
-
"Five": self.five,
|
|
121
|
-
},
|
|
122
|
-
row_width=(3, 2) # first row: 3 buttons, second row: 2
|
|
123
|
-
)
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
```
|
|
127
|
-
╭──────────┬──────────┬──────────╮
|
|
128
|
-
│ One │ Two │ Three │
|
|
129
|
-
├──────────┴──┬───────┴──────────┤
|
|
130
|
-
│ Four │ Five │
|
|
131
|
-
╰─────────────┴──────────────────╯
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
For precise row layout or conditional buttons, use `InlineKeyboard`, a builder you compose step by step:
|
|
100
|
+
Build a keyboard with `InlineKeyboard`, a fluent builder you compose step by step, and attach it with `set_keyboard`. Each `add_callback` takes a button label and the callback to run when it is pressed. Call `.row()` to start a new row:
|
|
135
101
|
|
|
136
102
|
```python
|
|
137
103
|
self.chain.set_keyboard(
|
|
@@ -153,6 +119,33 @@ self.chain.set_keyboard(
|
|
|
153
119
|
|
|
154
120
|
> `InlineKeyboard` is built by chaining method calls. Just call `.row()` to start a new row.
|
|
155
121
|
|
|
122
|
+
**Grid layout**
|
|
123
|
+
|
|
124
|
+
Wrap buttons in `.grid(width=...)` / `.grid_end()` to split them into rows of a fixed width automatically:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
self.chain.set_keyboard(
|
|
128
|
+
InlineKeyboard()
|
|
129
|
+
.grid(width=3)
|
|
130
|
+
.add_callback("One", self.one)
|
|
131
|
+
.add_callback("Two", self.two)
|
|
132
|
+
.add_callback("Three", self.three)
|
|
133
|
+
.add_callback("Four", self.four)
|
|
134
|
+
.add_callback("Five", self.five)
|
|
135
|
+
.grid_end()
|
|
136
|
+
)
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
╭──────────┬──────────┬──────────╮
|
|
141
|
+
│ One │ Two │ Three │
|
|
142
|
+
├──────────┴──┬───────┴──────────┤
|
|
143
|
+
│ Four │ Five │
|
|
144
|
+
╰─────────────┴──────────────────╯
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Use `.column()` / `.column_end()` to put every button on its own row, and `.extend(...)` to add many buttons at once from a dict or list. Pass `when=...` to any method to add a button or row conditionally.
|
|
148
|
+
|
|
156
149
|
**Not just callback buttons**
|
|
157
150
|
|
|
158
151
|
| **Method** | **Description** |
|
|
@@ -232,14 +225,17 @@ class DialogueHandler(telekit.Handler):
|
|
|
232
225
|
|
|
233
226
|
def handle_feeling(self, feeling: str) -> None:
|
|
234
227
|
self.chain.sender.set_text(f"Got it, {self.user_name.title()}! You feel: {feeling}")
|
|
235
|
-
self.chain.
|
|
228
|
+
self.chain.set_keyboard(
|
|
229
|
+
InlineKeyboard()
|
|
230
|
+
.add_callback("↺ Restart", self.handle_hello)
|
|
231
|
+
)
|
|
236
232
|
self.chain.send()
|
|
237
233
|
```
|
|
238
234
|
|
|
239
235
|
How it works:
|
|
240
236
|
|
|
241
237
|
- The handler reacts to `"hello"`, `"hi"`, or `"hey"` in any case.
|
|
242
|
-
- `handle_hello` asks for the user's name
|
|
238
|
+
- `handle_hello` asks for the user's name.
|
|
243
239
|
- `set_entry_suggestions` attaches the user's Telegram `first_name` as a suggestion button.
|
|
244
240
|
- `handle_name` stores the name in `self.user_name`.
|
|
245
241
|
- `handle_feeling` closes the flow and adds a "↺ Restart" button that routes back to the start.
|
|
@@ -72,13 +72,28 @@ class CallbackQueryHandler:
|
|
|
72
72
|
# Inline Buttons Handling
|
|
73
73
|
# –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
|
|
74
74
|
|
|
75
|
+
@classmethod
|
|
76
|
+
def _get_chat_id(cls, call: CallbackQuery) -> int:
|
|
77
|
+
"""
|
|
78
|
+
Returns the chat id the callbacks are registered under.
|
|
79
|
+
|
|
80
|
+
Falls back to the user id when the callback has no message
|
|
81
|
+
(e.g. inline-mode messages, where only inline_message_id is set).
|
|
82
|
+
"""
|
|
83
|
+
message = call.message
|
|
84
|
+
if message is not None and getattr(message, "chat", None) is not None:
|
|
85
|
+
return message.chat.id
|
|
86
|
+
return call.from_user.id
|
|
87
|
+
|
|
75
88
|
@classmethod
|
|
76
89
|
def _handle_inline_button(cls, call: CallbackQuery):
|
|
77
90
|
if not call.data:
|
|
78
91
|
cls.bot.answer_callback_query(call.id, text=cls._invalid_data_answer[0], show_alert=cls._invalid_data_answer[1])
|
|
79
92
|
return
|
|
80
|
-
|
|
81
|
-
|
|
93
|
+
|
|
94
|
+
chat_id: int = cls._get_chat_id(call)
|
|
95
|
+
|
|
96
|
+
button_callbacks: dict[str, Callable] | None = cls.user_button_callbacks.get(chat_id)
|
|
82
97
|
|
|
83
98
|
if not button_callbacks:
|
|
84
99
|
cls.bot.answer_callback_query(call.id, text=cls._button_is_no_active_answer[0], show_alert=cls._button_is_no_active_answer[1])
|
|
@@ -91,7 +106,7 @@ class CallbackQueryHandler:
|
|
|
91
106
|
return
|
|
92
107
|
|
|
93
108
|
if not getattr(callback, "_persistent", False):
|
|
94
|
-
cls.remove_user_button_callbacks(
|
|
109
|
+
cls.remove_user_button_callbacks(chat_id)
|
|
95
110
|
|
|
96
111
|
callback(call)
|
|
97
112
|
|
|
@@ -1,8 +1,59 @@
|
|
|
1
1
|
from typing import Callable, Any, Literal
|
|
2
2
|
|
|
3
|
+
from telebot.types import InlineKeyboardMarkup, InlineKeyboardButton
|
|
4
|
+
|
|
3
5
|
from telekit.inline_buttons import *
|
|
4
6
|
|
|
7
|
+
|
|
5
8
|
class InlineKeyboard:
|
|
9
|
+
"""
|
|
10
|
+
A fluent builder for Telegram inline keyboards.
|
|
11
|
+
|
|
12
|
+
Supports all button types available in the Telegram Bot API for inline
|
|
13
|
+
keyboards, as well as row/column layout helpers and bulk-add methods.
|
|
14
|
+
|
|
15
|
+
The finished keyboard can be attached to a message in two ways: through
|
|
16
|
+
a chain, or directly through a sender. The difference is in which buttons
|
|
17
|
+
each of them supports.
|
|
18
|
+
|
|
19
|
+
Usage in a chain (callback buttons are supported)::
|
|
20
|
+
|
|
21
|
+
keyboard = (
|
|
22
|
+
InlineKeyboard()
|
|
23
|
+
.add_callback("✅ Confirm", self.on_confirm)
|
|
24
|
+
.add_callback("✕ Cancel", self.on_cancel)
|
|
25
|
+
.row()
|
|
26
|
+
.add_link("📖 Docs", "https://example.com")
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
self.chain.set_keyboard(keyboard)
|
|
30
|
+
|
|
31
|
+
Usage with a standalone sender (buttons without callbacks only)::
|
|
32
|
+
|
|
33
|
+
keyboard = (
|
|
34
|
+
InlineKeyboard()
|
|
35
|
+
.add_link("📖 Docs", "https://example.com")
|
|
36
|
+
.add_copy("📋 Copy", "hello")
|
|
37
|
+
.row()
|
|
38
|
+
.add_webapp("🚀 Open app", "https://example.com/app")
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
sender.set_keyboard(keyboard)
|
|
42
|
+
|
|
43
|
+
.. note::
|
|
44
|
+
A standalone sender has no chain to register button handlers, so
|
|
45
|
+
:meth:`to_markup` supports only :class:`StaticButton`,
|
|
46
|
+
:class:`LinkButton` (and its subclasses), :class:`WebAppButton`,
|
|
47
|
+
:class:`SuggestButton` and :class:`CopyTextButton`. Callback-based
|
|
48
|
+
buttons (:class:`CallbackButton`, :class:`InvokeButton`,
|
|
49
|
+
:class:`AnswerButton`, :class:`AlertButton`, :class:`NotificationButton`)
|
|
50
|
+
raise :class:`TypeError`; attach such a keyboard through
|
|
51
|
+
``chain.set_keyboard()`` instead.
|
|
52
|
+
|
|
53
|
+
:param inline_keyboard: Pre-built rows of ``(text, InlineButton)`` tuples
|
|
54
|
+
used to seed the builder.
|
|
55
|
+
:type inline_keyboard: list[list[tuple[str, InlineButton]]] or None
|
|
56
|
+
"""
|
|
6
57
|
def __init__(self, inline_keyboard: list[list[tuple[str, InlineButton]]] | None = None):
|
|
7
58
|
self._rows: list[list[tuple[str, InlineButton]]] = []
|
|
8
59
|
|
|
@@ -109,6 +160,48 @@ class InlineKeyboard:
|
|
|
109
160
|
def _compile(self) -> list[list[tuple[str, InlineButton]]]:
|
|
110
161
|
self.row()
|
|
111
162
|
return self._rows
|
|
163
|
+
|
|
164
|
+
def to_markup(self) -> InlineKeyboardMarkup:
|
|
165
|
+
"""
|
|
166
|
+
Compiles the keyboard into a ready-to-send `InlineKeyboardMarkup`.
|
|
167
|
+
|
|
168
|
+
The result can be passed directly to `sender.set_reply_markup(...)`.
|
|
169
|
+
|
|
170
|
+
Only buttons that don't need a chain/handler are supported:
|
|
171
|
+
`StaticButton`, `LinkButton` (and subclasses), `WebAppButton`,
|
|
172
|
+
`SuggestButton`, `CopyTextButton`.
|
|
173
|
+
|
|
174
|
+
Callback-based buttons (`CallbackButton`, `InvokeButton`,
|
|
175
|
+
`AnswerButton`, `AlertButton`, `NotificationButton`) require a chain
|
|
176
|
+
to register their handlers, so they raise `TypeError` here.
|
|
177
|
+
|
|
178
|
+
Example::
|
|
179
|
+
|
|
180
|
+
kb = (
|
|
181
|
+
InlineKeyboard()
|
|
182
|
+
.add_link("Docs", "https://example.com")
|
|
183
|
+
.add_copy("Copy", "hello")
|
|
184
|
+
)
|
|
185
|
+
sender.set_reply_markup(kb.to_markup())
|
|
186
|
+
sender.send()
|
|
187
|
+
"""
|
|
188
|
+
markup = InlineKeyboardMarkup()
|
|
189
|
+
|
|
190
|
+
for row in self._compile():
|
|
191
|
+
buttons: list[InlineKeyboardButton] = []
|
|
192
|
+
|
|
193
|
+
for caption, button in row:
|
|
194
|
+
if isinstance(button, CallbackButton):
|
|
195
|
+
raise TypeError(
|
|
196
|
+
f"{type(button).__name__} cannot be compiled via to_markup(): "
|
|
197
|
+
f"callback buttons need a chain to register handlers. "
|
|
198
|
+
f"Use chain.set_inline_keyboard(...) instead."
|
|
199
|
+
)
|
|
200
|
+
buttons.append(button._compile(caption))
|
|
201
|
+
|
|
202
|
+
markup.row(*buttons)
|
|
203
|
+
|
|
204
|
+
return markup
|
|
112
205
|
|
|
113
206
|
def add(self, text: str, inline_button: InlineButton | None = None, *, when: bool | int = True):
|
|
114
207
|
"""
|
|
@@ -22,16 +22,19 @@ class ReplyKeyboard:
|
|
|
22
22
|
|
|
23
23
|
Basic usage::
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
keyboard = (
|
|
26
26
|
ReplyKeyboard(resize_keyboard=True)
|
|
27
27
|
.add_contact("📱 Share phone")
|
|
28
28
|
.add_location("📍 My location")
|
|
29
29
|
.row()
|
|
30
30
|
.add_text("Option A")
|
|
31
31
|
.add_text("Option B")
|
|
32
|
-
.build()
|
|
33
32
|
)
|
|
34
|
-
|
|
33
|
+
# Attach the keyboard via a chain:
|
|
34
|
+
chain.set_keyboard(keyboard)
|
|
35
|
+
|
|
36
|
+
# Or attach it directly to a standalone sender:
|
|
37
|
+
sender.set_keyboard(keyboard)
|
|
35
38
|
|
|
36
39
|
:param keyboard: Pre-built rows of ``(text, ReplyButton)`` tuples to seed
|
|
37
40
|
the builder with. Useful for composing keyboards programmatically.
|
|
@@ -184,6 +187,34 @@ class ReplyKeyboard:
|
|
|
184
187
|
if self._grid_width and self._grid_count() >= self._grid_width:
|
|
185
188
|
self.row()
|
|
186
189
|
|
|
190
|
+
def to_markup(self) -> ReplyKeyboardMarkup:
|
|
191
|
+
"""
|
|
192
|
+
Compiles the keyboard into a ready-to-send :class:`telebot.types.ReplyKeyboardMarkup`.
|
|
193
|
+
|
|
194
|
+
The result can be passed directly to :meth:`Sender.set_reply_markup`,
|
|
195
|
+
or you can use :meth:`Sender.set_keyboard` as a shortcut.
|
|
196
|
+
|
|
197
|
+
Any pending row is flushed automatically, so calling :meth:`row`
|
|
198
|
+
at the end of the chain is not required.
|
|
199
|
+
|
|
200
|
+
:returns: The compiled reply keyboard markup.
|
|
201
|
+
:rtype: :class:`telebot.types.ReplyKeyboardMarkup`
|
|
202
|
+
|
|
203
|
+
Example::
|
|
204
|
+
|
|
205
|
+
markup = (
|
|
206
|
+
ReplyKeyboard(resize_keyboard=True)
|
|
207
|
+
.add_contact("📱 Share phone")
|
|
208
|
+
.add_location("📍 My location")
|
|
209
|
+
.row()
|
|
210
|
+
.add_text("Option A")
|
|
211
|
+
.add_text("Option B")
|
|
212
|
+
.to_markup()
|
|
213
|
+
)
|
|
214
|
+
sender.set_reply_markup(markup)
|
|
215
|
+
"""
|
|
216
|
+
return self._compile()
|
|
217
|
+
|
|
187
218
|
# ── Generic add ───────────────────────────────────────────────────────────
|
|
188
219
|
|
|
189
220
|
def add(
|
|
@@ -94,6 +94,7 @@ class LocationButton(ReplyButton):
|
|
|
94
94
|
"""
|
|
95
95
|
return KeyboardButton(text, request_location=True)
|
|
96
96
|
|
|
97
|
+
# Telebot API fix
|
|
97
98
|
class _FixedKeyboardButtonPollType(KeyboardButtonPollType):
|
|
98
99
|
def to_dict(self):
|
|
99
100
|
# FIX: Bad Request: can't parse keyboard button: Field "type" must be of type String.
|
|
@@ -123,7 +124,6 @@ class PollButton(ReplyButton):
|
|
|
123
124
|
:type text: str
|
|
124
125
|
:rtype: :class:`telebot.types.KeyboardButton`
|
|
125
126
|
"""
|
|
126
|
-
print(f"{self.poll_type=}")
|
|
127
127
|
return KeyboardButton(
|
|
128
128
|
text,
|
|
129
129
|
request_poll=_FixedKeyboardButtonPollType(type=self.poll_type),
|
|
@@ -19,12 +19,12 @@
|
|
|
19
19
|
|
|
20
20
|
from typing import Any, Literal, NoReturn, TYPE_CHECKING, Union
|
|
21
21
|
import textwrap
|
|
22
|
-
import json
|
|
23
22
|
import io
|
|
24
23
|
|
|
25
24
|
if TYPE_CHECKING:
|
|
26
25
|
from string.templatelib import Template # pyright: ignore[reportMissingImports]
|
|
27
|
-
|
|
26
|
+
from telekit._inline_keyboard import InlineKeyboard
|
|
27
|
+
from telekit._reply_keyboard import ReplyKeyboard
|
|
28
28
|
|
|
29
29
|
from telebot import TeleBot, apihelper
|
|
30
30
|
from telebot.types import (
|
|
@@ -33,7 +33,7 @@ from telebot.types import (
|
|
|
33
33
|
InputMediaPhoto, InputFile,
|
|
34
34
|
InputMediaAudio, InputMediaDocument,
|
|
35
35
|
InputMediaVideo, InputMediaAnimation,
|
|
36
|
-
ReplyKeyboardMarkup
|
|
36
|
+
ReplyKeyboardMarkup, InlineKeyboardMarkup
|
|
37
37
|
)
|
|
38
38
|
|
|
39
39
|
from telekit.debug import Debug
|
|
@@ -167,7 +167,7 @@ class BaseSender:
|
|
|
167
167
|
reply_markup = None,
|
|
168
168
|
|
|
169
169
|
is_temporary: bool = False,
|
|
170
|
-
|
|
170
|
+
delete_temporaries: bool = True,
|
|
171
171
|
|
|
172
172
|
parse_mode: Literal["html", "markdown"] | ParseMode | None = "html",
|
|
173
173
|
reply_to_message_id: int | None = None,
|
|
@@ -207,7 +207,7 @@ class BaseSender:
|
|
|
207
207
|
self.reply_markup = reply_markup
|
|
208
208
|
|
|
209
209
|
self.is_temporary = is_temporary
|
|
210
|
-
self.delele_temporaries =
|
|
210
|
+
self.delele_temporaries = delete_temporaries
|
|
211
211
|
|
|
212
212
|
self.set_parse_mode(parse_mode)
|
|
213
213
|
self.reply_to_message_id = reply_to_message_id
|
|
@@ -541,12 +541,68 @@ class BaseSender:
|
|
|
541
541
|
"""
|
|
542
542
|
self.text = text
|
|
543
543
|
|
|
544
|
-
def set_reply_markup(self, reply_markup):
|
|
544
|
+
def set_reply_markup(self, reply_markup: Union[ReplyKeyboardMarkup, InlineKeyboardMarkup]):
|
|
545
545
|
"""
|
|
546
|
-
Sets Inline keyboards, reply keyboards, or other markup objects
|
|
546
|
+
Sets Inline keyboards, reply keyboards, or other markup objects as-is.
|
|
547
|
+
|
|
548
|
+
This is a low-level method: ``reply_markup`` is stored without any
|
|
549
|
+
conversion, so it must already be a compiled Telegram markup object
|
|
550
|
+
(e.g. ``InlineKeyboardMarkup`` or ``ReplyKeyboardMarkup``).
|
|
551
|
+
|
|
552
|
+
.. tip::
|
|
553
|
+
In most cases use :meth:`set_keyboard` instead. It accepts
|
|
554
|
+
:class:`InlineKeyboard` and :class:`ReplyKeyboard` builders directly
|
|
555
|
+
and compiles them for you.
|
|
556
|
+
|
|
557
|
+
If you do want to pass a builder here, compile it first with
|
|
558
|
+
``to_markup()``::
|
|
559
|
+
|
|
560
|
+
keyboard = InlineKeyboard().add_link("Docs", "https://example.com")
|
|
561
|
+
|
|
562
|
+
sender.set_reply_markup(keyboard.to_markup())
|
|
563
|
+
|
|
564
|
+
# equivalent, and shorter:
|
|
565
|
+
sender.set_keyboard(keyboard)
|
|
566
|
+
|
|
567
|
+
:param reply_markup: A compiled markup object ready to be sent.
|
|
547
568
|
"""
|
|
548
569
|
self.reply_markup = reply_markup
|
|
549
570
|
|
|
571
|
+
def set_keyboard(self, keyboard: Union["InlineKeyboard", "ReplyKeyboard"]) -> None:
|
|
572
|
+
"""
|
|
573
|
+
Sets an inline or reply keyboard as the message's reply markup.
|
|
574
|
+
|
|
575
|
+
Compiles ``keyboard`` via its ``to_markup()`` method and stores the
|
|
576
|
+
result in :attr:`reply_markup`. This is a shortcut for
|
|
577
|
+
``sender.set_reply_markup(keyboard.to_markup())``.
|
|
578
|
+
|
|
579
|
+
.. note::
|
|
580
|
+
For :class:`InlineKeyboard`, only buttons that don't need a chain
|
|
581
|
+
to register handlers are supported: :class:`StaticButton`,
|
|
582
|
+
:class:`LinkButton` (and its subclasses), :class:`WebAppButton`,
|
|
583
|
+
:class:`SuggestButton` and :class:`CopyTextButton`.
|
|
584
|
+
Use ``chain.set_inline_keyboard(...)`` for callback-based buttons.
|
|
585
|
+
|
|
586
|
+
:param keyboard: The keyboard to attach to the message.
|
|
587
|
+
:type keyboard: :class:`InlineKeyboard` | :class:`ReplyKeyboard`
|
|
588
|
+
|
|
589
|
+
:raises TypeError: If an :class:`InlineKeyboard` contains a callback-based
|
|
590
|
+
button (:class:`CallbackButton`, :class:`InvokeButton`,
|
|
591
|
+
:class:`AnswerButton`, :class:`AlertButton`, :class:`NotificationButton`).
|
|
592
|
+
|
|
593
|
+
Example::
|
|
594
|
+
|
|
595
|
+
sender.set_keyboard(
|
|
596
|
+
InlineKeyboard().add_link("Docs", "https://example.com")
|
|
597
|
+
)
|
|
598
|
+
|
|
599
|
+
sender.set_keyboard(
|
|
600
|
+
ReplyKeyboard().add_text("Yes").add_text("No")
|
|
601
|
+
)
|
|
602
|
+
sender.send()
|
|
603
|
+
"""
|
|
604
|
+
self.reply_markup = keyboard.to_markup()
|
|
605
|
+
|
|
550
606
|
def set_temporary(self, is_temp: bool):
|
|
551
607
|
"""
|
|
552
608
|
Marks message as temporary; will be deleted later if `delete_temporaries` is True.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: telekit
|
|
3
|
-
Version: 2.6.
|
|
3
|
+
Version: 2.6.1
|
|
4
4
|
Summary: Declarative, developer-friendly framework for building Telegram bots
|
|
5
5
|
Home-page: https://github.com/Romashkaa/telekit
|
|
6
6
|
Author: romashka
|
|
@@ -134,41 +134,7 @@ def handle_name(self, name: str):
|
|
|
134
134
|
|
|
135
135
|
### Inline Keyboards
|
|
136
136
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
```python
|
|
140
|
-
self.chain.set_inline_keyboard(
|
|
141
|
-
{
|
|
142
|
-
"✏️ Change": self.change_name,
|
|
143
|
-
"❌ Delete": self.delete,
|
|
144
|
-
}
|
|
145
|
-
)
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
`row_width` controls how many buttons appear per row:
|
|
149
|
-
|
|
150
|
-
```python
|
|
151
|
-
self.chain.set_inline_keyboard(
|
|
152
|
-
{
|
|
153
|
-
"One": self.one,
|
|
154
|
-
"Two": self.two,
|
|
155
|
-
"Three": self.three,
|
|
156
|
-
"Four": self.four,
|
|
157
|
-
"Five": self.five,
|
|
158
|
-
},
|
|
159
|
-
row_width=(3, 2) # first row: 3 buttons, second row: 2
|
|
160
|
-
)
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
```
|
|
164
|
-
╭──────────┬──────────┬──────────╮
|
|
165
|
-
│ One │ Two │ Three │
|
|
166
|
-
├──────────┴──┬───────┴──────────┤
|
|
167
|
-
│ Four │ Five │
|
|
168
|
-
╰─────────────┴──────────────────╯
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
For precise row layout or conditional buttons, use `InlineKeyboard`, a builder you compose step by step:
|
|
137
|
+
Build a keyboard with `InlineKeyboard`, a fluent builder you compose step by step, and attach it with `set_keyboard`. Each `add_callback` takes a button label and the callback to run when it is pressed. Call `.row()` to start a new row:
|
|
172
138
|
|
|
173
139
|
```python
|
|
174
140
|
self.chain.set_keyboard(
|
|
@@ -190,6 +156,33 @@ self.chain.set_keyboard(
|
|
|
190
156
|
|
|
191
157
|
> `InlineKeyboard` is built by chaining method calls. Just call `.row()` to start a new row.
|
|
192
158
|
|
|
159
|
+
**Grid layout**
|
|
160
|
+
|
|
161
|
+
Wrap buttons in `.grid(width=...)` / `.grid_end()` to split them into rows of a fixed width automatically:
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
self.chain.set_keyboard(
|
|
165
|
+
InlineKeyboard()
|
|
166
|
+
.grid(width=3)
|
|
167
|
+
.add_callback("One", self.one)
|
|
168
|
+
.add_callback("Two", self.two)
|
|
169
|
+
.add_callback("Three", self.three)
|
|
170
|
+
.add_callback("Four", self.four)
|
|
171
|
+
.add_callback("Five", self.five)
|
|
172
|
+
.grid_end()
|
|
173
|
+
)
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
╭──────────┬──────────┬──────────╮
|
|
178
|
+
│ One │ Two │ Three │
|
|
179
|
+
├──────────┴──┬───────┴──────────┤
|
|
180
|
+
│ Four │ Five │
|
|
181
|
+
╰─────────────┴──────────────────╯
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Use `.column()` / `.column_end()` to put every button on its own row, and `.extend(...)` to add many buttons at once from a dict or list. Pass `when=...` to any method to add a button or row conditionally.
|
|
185
|
+
|
|
193
186
|
**Not just callback buttons**
|
|
194
187
|
|
|
195
188
|
| **Method** | **Description** |
|
|
@@ -269,14 +262,17 @@ class DialogueHandler(telekit.Handler):
|
|
|
269
262
|
|
|
270
263
|
def handle_feeling(self, feeling: str) -> None:
|
|
271
264
|
self.chain.sender.set_text(f"Got it, {self.user_name.title()}! You feel: {feeling}")
|
|
272
|
-
self.chain.
|
|
265
|
+
self.chain.set_keyboard(
|
|
266
|
+
InlineKeyboard()
|
|
267
|
+
.add_callback("↺ Restart", self.handle_hello)
|
|
268
|
+
)
|
|
273
269
|
self.chain.send()
|
|
274
270
|
```
|
|
275
271
|
|
|
276
272
|
How it works:
|
|
277
273
|
|
|
278
274
|
- The handler reacts to `"hello"`, `"hi"`, or `"hey"` in any case.
|
|
279
|
-
- `handle_hello` asks for the user's name
|
|
275
|
+
- `handle_hello` asks for the user's name.
|
|
280
276
|
- `set_entry_suggestions` attaches the user's Telegram `first_name` as a suggestion button.
|
|
281
277
|
- `handle_name` stores the name in `self.user_name`.
|
|
282
278
|
- `handle_feeling` closes the flow and adds a "↺ Restart" button that routes back to the start.
|
|
@@ -480,8 +476,39 @@ Telekit focuses on one job: making Telegram bot development easier.
|
|
|
480
476
|
|
|
481
477
|
# Changelog
|
|
482
478
|
|
|
483
|
-
|
|
484
|
-
|
|
479
|
+
## File ID Caching, Rich HTML, New Timeout Engine
|
|
480
|
+
|
|
481
|
+
**Telekit 2.6** speeds up file sending, makes bots more resilient and adds Rich HTML messages. What's new:
|
|
482
|
+
|
|
483
|
+
1. **File ID caching.** Local files are uploaded to Telegram once and reused on every next send.
|
|
484
|
+
2. **Rich HTML messages** (Bot API 10.1+).
|
|
485
|
+
3. **New timeout engine.** No more `can't start new thread` with ~1000 active chats (#6).
|
|
486
|
+
4. **Smart restarts.** The new `restart` parameter (`"always"`, `"network"`, `"never"`) with exponential backoff keeps the server alive through network failures.
|
|
487
|
+
5. **Keyboards in senders.** `set_keyboard()` and `to_markup()` let you attach keyboards to a plain `sender` without a chain.
|
|
488
|
+
6. **Full `.env` support.** Comments, quotes, multi-line values and `$VAR` interpolation.
|
|
489
|
+
7. **Better logging.** Rich output when `rich` is installed, bot tokens masked in logs, no duplicated records.
|
|
490
|
+
8. **Handoff shortcuts.** `handle_handoff()` and `handle_handoff_back_or()` work without closures.
|
|
491
|
+
|
|
492
|
+
### v2.6.1 – Fixes #7
|
|
493
|
+
- In groups, any chat member can now press the button (previously effectively broken for everyone).
|
|
494
|
+
|
|
495
|
+
### v2.6.0
|
|
496
|
+
- Stable release. See the `a0`–`a9` entries below for the full list of changes.
|
|
497
|
+
|
|
498
|
+
### v2.6.0 `a9` – Keyboards in Senders
|
|
499
|
+
- Added `InlineKeyboard.to_markup()`: compiles the keyboard into a ready-to-send `InlineKeyboardMarkup`. Only buttons that don't need a chain to register handlers are supported (`StaticButton`, `LinkButton` and its subclasses, `WebAppButton`, `SuggestButton`, `CopyTextButton`); callback-based buttons (`CallbackButton`, `InvokeButton`, `AnswerButton`, `AlertButton`, `NotificationButton`) raise `TypeError` and should be used via `chain.set_inline_keyboard()`
|
|
500
|
+
- Added `ReplyKeyboard.to_markup()`: a public counterpart of the internal `_compile()` that returns a `ReplyKeyboardMarkup`
|
|
501
|
+
- Added `set_keyboard()` to `BaseSender`: a shortcut for `set_reply_markup(keyboard.to_markup())` that accepts both `InlineKeyboard` and `ReplyKeyboard`, so keyboards can be passed to a plain `sender` without a chain
|
|
502
|
+
|
|
503
|
+
### v2.6.0 `a7` – Sender, Server, Logging
|
|
504
|
+
#### Sender: automatic `file_id` caching
|
|
505
|
+
- Added a `FileIdCache` that stores Telegram `file_id` for local files (photo, document, video, animation, audio, voice, video note), so repeated sends skip the upload
|
|
506
|
+
- Added `BaseSender.configure_file_cache()`: a class method that sets the database path, table name and global on/off switch
|
|
507
|
+
- Added `Sender.set_use_file_cache()`: a per-sender override of the global setting (`None` restores it)
|
|
508
|
+
- Changed missing local files to raise on `send()` instead of in the setter
|
|
509
|
+
- A rejected cached `file_id` is dropped and the send is retried with the original file
|
|
510
|
+
- Notes: URLs, `bytes` and file-like objects are not cached; rich messages and media groups are unaffected. A changed file is detected by `size/mtime`, with a `SHA-256` comparison as a fallback
|
|
511
|
+
#### Server: restarts and network protection
|
|
485
512
|
- Added `restart` parameter to `Server`: `"always"` (default), `"network"` or `"never"`; accepts `RestartMode` or the matching string
|
|
486
513
|
- Deprecated `Server(auto_restart=...)`: `True` is now `restart="always"`, `False` is `restart="never"`; emits `DeprecationWarning` and a log warning. Cannot be combined with `restart` (`TypeError`)
|
|
487
514
|
- Added network protection to `Server.polling()` and `Server.long_polling()`: restarts are now delayed by exponential backoff (5 s up to 60 s, reset after 120 s of stable work) instead of a fixed 10 s / 5 s. Tunable via `Server.RESTART_DELAY_MIN`, `RESTART_DELAY_MAX` and `STABLE_AFTER`
|
|
@@ -498,40 +525,33 @@ Telekit focuses on one job: making Telegram bot development easier.
|
|
|
498
525
|
- Changed `telekit` loggers to `propagate=False`: records no longer reach the root logger, so they are not duplicated when the app configures it. Attach custom handlers to `logging.getLogger("telekit")`
|
|
499
526
|
- Changed `enable_file_logging()` to be idempotent, to create parent folders, and to use one format (with `filename:lineno`) for all files, including `server.log`
|
|
500
527
|
- Fixed `UserLogger` reporting its own module as the log source
|
|
501
|
-
#### Sender
|
|
502
|
-
- Added a `FileIdCache` that stores Telegram `file_id` for local files (photo, document, video, animation, audio, voice, video note), so repeated sends skip the upload
|
|
503
|
-
- Added `BaseSender.configure_file_cache()`: a class method that sets the database path, table name and global on/off switch
|
|
504
|
-
- Added `Sender.set_use_file_cache()`: a per-sender override of the global setting (`None` restores it)
|
|
505
|
-
- Changed missing local files to raise on `send()` instead of in the setter
|
|
506
|
-
- A rejected cached `file_id` is dropped and the send is retried with the original file
|
|
507
|
-
- Notes: URLs, `bytes` and file-like objects are not cached; rich messages and media groups are unaffected. A changed file is detected by `size/mtime`, with a `SHA-256` comparison as a fallback
|
|
508
528
|
|
|
509
|
-
### v2.6.0 `a6` (fixes #6)
|
|
529
|
+
### v2.6.0 `a6` (fixes #6) – Timeout engine
|
|
510
530
|
- Reworked the timeout engine to fix thread exhaustion with many concurrent chats (#6): every `set_timeout()` used to start its own `threading.Timer` (one OS thread per waiting chat), so ~1000 active users crashed the bot with `can't start new thread`
|
|
511
531
|
- Timeout callback exceptions are now logged
|
|
512
532
|
- Added `configure_timeouts(max_workers, *, idle_timeout, log_worker_changes, warn_on_max_workers)` to tune the worker pool, log worker start/stop, and control the "all workers busy" warning (enabled by default)
|
|
513
533
|
|
|
514
|
-
### v2.6.0 `a4`
|
|
534
|
+
### v2.6.0 `a4` – Handoff shortcuts
|
|
515
535
|
- Added `handle_handoff()` to `Handler`: a shortcut for `handoff(handler).handle()` that takes the target handler as an argument, so it can be passed to `add_callback()` without an extra closure
|
|
516
536
|
- Added `handle_handoff_back_or()` to `TrackHandoffOrigin`: a closure-free counterpart of `handoff_back_or()`
|
|
517
537
|
- Reworked `handoff_back_or()` as a thin `functools.partial` wrapper around `handle_handoff_back_or()`
|
|
518
538
|
- Fixed the `handoff_back_or()` docstring: the returned callable forwards its arguments to `handle()` instead of being zero-argument
|
|
519
539
|
- Converted the `handoff()` docstring to reST
|
|
520
540
|
|
|
521
|
-
### v2.6.0 `a3`
|
|
541
|
+
### v2.6.0 `a3` – Rich HTML
|
|
522
542
|
- Added support for Rich HTML messages (Bot API 10.1+)
|
|
523
543
|
- Added the `_rich.py` module for Rich HTML parsing and serialization
|
|
524
544
|
- Added new rich tags to `styles.py` for enhanced text formatting
|
|
525
545
|
- Added the `rich.py` example handler demonstrating Rich HTML: inline styles, blocks, lists, tables, media, and sender integration
|
|
526
546
|
|
|
527
|
-
### v2.6.0 `a2`
|
|
547
|
+
### v2.6.0 `a2` – Env parsing
|
|
528
548
|
- Reworked `.env` and token/canvas file reading in `utils`
|
|
529
549
|
- Added full `.env` syntax support: comments, `export`, quotes and escapes, multi-line values, `$VAR` interpolation
|
|
530
550
|
- Added the `cache` parameter (default `True`) and `clear_cache()`
|
|
531
551
|
- Added detailed errors with fix suggestions and creation commands, and new `Env*Error` exceptions
|
|
532
552
|
- Changed `load_env()` to raise `EnvFileNotFoundError` for a missing file instead of returning `{}`
|
|
533
553
|
|
|
534
|
-
### v2.6.0 `a1`
|
|
554
|
+
### v2.6.0 `a1` – Module loader
|
|
535
555
|
- Added a module-loading utility to `utils`
|
|
536
556
|
|
|
537
557
|
### v2.6.0 `a0`
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|