telekit 2.5.4__tar.gz → 2.6.0__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.0/CHANGELOG.md +77 -0
- telekit-2.6.0/MANIFEST.in +4 -0
- {telekit-2.5.4 → telekit-2.6.0}/PKG-INFO +129 -98
- {telekit-2.5.4 → telekit-2.6.0}/README.md +44 -44
- {telekit-2.5.4 → telekit-2.6.0}/setup.cfg +0 -3
- telekit-2.6.0/setup.py +70 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/__init__.py +8 -4
- telekit-2.5.4/telekit/_version.py → telekit-2.6.0/telekit/__version__.py +1 -2
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_buildtext/styles.py +484 -1
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_chain.py +5 -3
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_chain_base.py +6 -3
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_chain_inline_keyboards_logic.py +10 -8
- telekit-2.6.0/telekit/_file_cache.py +136 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_handler.py +36 -1
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_inline_keyboard.py +93 -0
- telekit-2.6.0/telekit/_logger.py +206 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_on.py +154 -26
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_reply_keyboard.py +34 -3
- telekit-2.6.0/telekit/_rich.py +381 -0
- telekit-2.6.0/telekit/_timeout.py +424 -0
- telekit-2.6.0/telekit/example/example_handlers/__init__.py +9 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/complete_hotel.py +1 -1
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/hotel.py +1 -1
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/qr.py +1 -1
- telekit-2.6.0/telekit/example/example_handlers/rich.py +555 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/start.py +3 -1
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_server.py +3 -20
- {telekit-2.5.4 → telekit-2.6.0}/telekit/reply_buttons.py +1 -1
- telekit-2.6.0/telekit/requirements.txt +3 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/senders.py +413 -34
- telekit-2.6.0/telekit/server.py +540 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/styles.py +31 -6
- {telekit-2.5.4 → telekit-2.6.0}/telekit/traits/track_handoff_origin.py +63 -25
- {telekit-2.5.4 → telekit-2.6.0}/telekit/utils.py +531 -74
- {telekit-2.5.4 → telekit-2.6.0}/telekit.egg-info/PKG-INFO +129 -98
- {telekit-2.5.4 → telekit-2.6.0}/telekit.egg-info/SOURCES.txt +7 -2
- {telekit-2.5.4 → telekit-2.6.0}/telekit.egg-info/requires.txt +1 -1
- telekit-2.5.4/setup.py +0 -73
- telekit-2.5.4/telekit/_logger.py +0 -129
- telekit-2.5.4/telekit/_timeout.py +0 -73
- telekit-2.5.4/telekit/example/example_handlers/__init__.py +0 -19
- telekit-2.5.4/telekit/server.py +0 -160
- {telekit-2.5.4 → telekit-2.6.0}/LICENSE +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_buildtext/__init__.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_buildtext/formatter.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_callback_query_handler.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_chain_entry_logic.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_chapters/__init__.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_chapters/chapters.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_init.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_inline_buttons.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_input_handler.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_snapvault/__init__.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_snapvault/snapcode.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_snapvault/snapvault.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_state.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_telekit_dsl/__init__.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_telekit_dsl/mixin.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_telekit_dsl/parser/__init__.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_telekit_dsl/parser/builder.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_telekit_dsl/parser/canvas_parser.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_telekit_dsl/parser/lexer.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_telekit_dsl/parser/nodes.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_telekit_dsl/parser/parser.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_telekit_dsl/parser/token.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_telekit_dsl/telekit_dsl.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_telekit_dsl/telekit_orm.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_text_builder.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_trait.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/_user.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/chat.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/debug.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/dices.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/__init__.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/article.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/calendar.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/counter.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/dsl.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/entry.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/faq.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/on_text.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/pages.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/pyapi.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/quiz.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/spells.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/style.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/example/example_handlers/text_document.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/html_text.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/inline_buttons.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/parameters.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/scheduler.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/traits/__init__.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/traits/calendar_pick.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/traits/paginated_choice.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/traits/paginated_text.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit/types.py +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit.egg-info/dependency_links.txt +0 -0
- {telekit-2.5.4 → telekit-2.6.0}/telekit.egg-info/top_level.txt +0 -0
|
@@ -0,0 +1,77 @@
|
|
|
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.0
|
|
15
|
+
- Stable release. See the `a0`–`a9` entries below for the full list of changes.
|
|
16
|
+
|
|
17
|
+
### v2.6.0 `a9` – Keyboards in Senders
|
|
18
|
+
- 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()`
|
|
19
|
+
- Added `ReplyKeyboard.to_markup()`: a public counterpart of the internal `_compile()` that returns a `ReplyKeyboardMarkup`
|
|
20
|
+
- 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
|
|
21
|
+
|
|
22
|
+
### v2.6.0 `a7` – Sender, Server, Logging
|
|
23
|
+
#### Sender: automatic `file_id` caching
|
|
24
|
+
- 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
|
|
25
|
+
- Added `BaseSender.configure_file_cache()`: a class method that sets the database path, table name and global on/off switch
|
|
26
|
+
- Added `Sender.set_use_file_cache()`: a per-sender override of the global setting (`None` restores it)
|
|
27
|
+
- Changed missing local files to raise on `send()` instead of in the setter
|
|
28
|
+
- A rejected cached `file_id` is dropped and the send is retried with the original file
|
|
29
|
+
- 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
|
|
30
|
+
#### Server: restarts and network protection
|
|
31
|
+
- Added `restart` parameter to `Server`: `"always"` (default), `"network"` or `"never"`; accepts `RestartMode` or the matching string
|
|
32
|
+
- 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`)
|
|
33
|
+
- 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`
|
|
34
|
+
- Added `restart="network"`: survives only network errors and Bot API `429`, `500`, `502`, `503`, `504`; any other error (bad token, `409` conflict, bugs) is re-raised. `retry_after` from Telegram is respected
|
|
35
|
+
- Changed `Server.__init__()` to wait for the Bot API to become reachable before calling `getMe` (skipped for `restart="never"` and when `apihelper.proxy` is set)
|
|
36
|
+
- Fixed `Server.polling()` and `Server.long_polling()` restarting after `stop_polling()`: they now return instead
|
|
37
|
+
- Fixed a failed `getMe` in the restart cycle killing the server and hiding the original error
|
|
38
|
+
- Fixed bot tokens leaking into logs through request URLs: they are now masked as `bot<hidden>`
|
|
39
|
+
- Changed log levels in `Server`: network errors are logged as `WARNING` (without traceback), unexpected errors as `ERROR` (with traceback), `FATAL` is kept for `[server dead]`.
|
|
40
|
+
#### Logging
|
|
41
|
+
- Added Rich output for logs when `rich` is installed; set `TELEKIT_NO_RICH=1` to disable it
|
|
42
|
+
- Added direct exports `server_logger`, `library_logger`, `user_logger` and `get_user_logger()` to `_logger.py`. `logger.server`, `logger.library`, `logger.users()`, `_server` and `_library` still work
|
|
43
|
+
- Added `set_level()`, `disable_user_logging()` and `UserLogger.exception()`
|
|
44
|
+
- 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")`
|
|
45
|
+
- 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`
|
|
46
|
+
- Fixed `UserLogger` reporting its own module as the log source
|
|
47
|
+
|
|
48
|
+
### v2.6.0 `a6` (fixes #6) – Timeout engine
|
|
49
|
+
- 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`
|
|
50
|
+
- Timeout callback exceptions are now logged
|
|
51
|
+
- 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)
|
|
52
|
+
|
|
53
|
+
### v2.6.0 `a4` – Handoff shortcuts
|
|
54
|
+
- 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
|
|
55
|
+
- Added `handle_handoff_back_or()` to `TrackHandoffOrigin`: a closure-free counterpart of `handoff_back_or()`
|
|
56
|
+
- Reworked `handoff_back_or()` as a thin `functools.partial` wrapper around `handle_handoff_back_or()`
|
|
57
|
+
- Fixed the `handoff_back_or()` docstring: the returned callable forwards its arguments to `handle()` instead of being zero-argument
|
|
58
|
+
- Converted the `handoff()` docstring to reST
|
|
59
|
+
|
|
60
|
+
### v2.6.0 `a3` – Rich HTML
|
|
61
|
+
- Added support for Rich HTML messages (Bot API 10.1+)
|
|
62
|
+
- Added the `_rich.py` module for Rich HTML parsing and serialization
|
|
63
|
+
- Added new rich tags to `styles.py` for enhanced text formatting
|
|
64
|
+
- Added the `rich.py` example handler demonstrating Rich HTML: inline styles, blocks, lists, tables, media, and sender integration
|
|
65
|
+
|
|
66
|
+
### v2.6.0 `a2` – Env parsing
|
|
67
|
+
- Reworked `.env` and token/canvas file reading in `utils`
|
|
68
|
+
- Added full `.env` syntax support: comments, `export`, quotes and escapes, multi-line values, `$VAR` interpolation
|
|
69
|
+
- Added the `cache` parameter (default `True`) and `clear_cache()`
|
|
70
|
+
- Added detailed errors with fix suggestions and creation commands, and new `Env*Error` exceptions
|
|
71
|
+
- Changed `load_env()` to raise `EnvFileNotFoundError` for a missing file instead of returning `{}`
|
|
72
|
+
|
|
73
|
+
### v2.6.0 `a1` – Module loader
|
|
74
|
+
- Added a module-loading utility to `utils`
|
|
75
|
+
|
|
76
|
+
### v2.6.0 `a0`
|
|
77
|
+
- Improved formatting in `_on.py`
|
|
@@ -1,26 +1,26 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: telekit
|
|
3
|
-
Version: 2.
|
|
4
|
-
Summary: Declarative, developer-friendly
|
|
3
|
+
Version: 2.6.0
|
|
4
|
+
Summary: Declarative, developer-friendly framework for building Telegram bots
|
|
5
5
|
Home-page: https://github.com/Romashkaa/telekit
|
|
6
6
|
Author: romashka
|
|
7
7
|
Author-email: notromashka@gmail.com
|
|
8
|
-
License:
|
|
8
|
+
License: GPL-3.0-or-later
|
|
9
9
|
Project-URL: GitHub, https://github.com/Romashkaa/telekit
|
|
10
10
|
Project-URL: Telegram, https://t.me/TelekitLib
|
|
11
11
|
Keywords: telegram bot api declarative tools bot-api
|
|
12
12
|
Classifier: Programming Language :: Python
|
|
13
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
13
14
|
Classifier: Programming Language :: Python :: 3.12
|
|
14
15
|
Classifier: Programming Language :: Python :: 3.13
|
|
15
16
|
Classifier: Programming Language :: Python :: 3.14
|
|
16
|
-
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
|
|
17
17
|
Classifier: Operating System :: OS Independent
|
|
18
18
|
Requires-Python: >=3.12
|
|
19
19
|
Description-Content-Type: text/markdown
|
|
20
20
|
License-File: LICENSE
|
|
21
21
|
Requires-Dist: charset_normalizer==3.4.2
|
|
22
22
|
Requires-Dist: Jinja2==3.1.6
|
|
23
|
-
Requires-Dist: pyTelegramBotAPI==4.
|
|
23
|
+
Requires-Dist: pyTelegramBotAPI==4.37.0
|
|
24
24
|
Dynamic: author
|
|
25
25
|
Dynamic: author-email
|
|
26
26
|
Dynamic: classifier
|
|
@@ -28,6 +28,7 @@ Dynamic: description
|
|
|
28
28
|
Dynamic: description-content-type
|
|
29
29
|
Dynamic: home-page
|
|
30
30
|
Dynamic: keywords
|
|
31
|
+
Dynamic: license
|
|
31
32
|
Dynamic: license-file
|
|
32
33
|
Dynamic: project-url
|
|
33
34
|
Dynamic: requires-dist
|
|
@@ -42,7 +43,7 @@ Dynamic: summary
|
|
|
42
43
|
|
|
43
44
|
# Telekit
|
|
44
45
|
|
|
45
|
-
**Telekit** is a declarative, developer-friendly
|
|
46
|
+
**Telekit** is a declarative, developer-friendly framework for building Telegram bots. It gives developers a dedicated Sender for composing and sending messages and a Chain for handling dialogue between the user and the bot. The framework also handles inline keyboards and callback routing automatically, letting you focus on the bot's behavior instead of repetitive tasks.
|
|
46
47
|
|
|
47
48
|
```py
|
|
48
49
|
import telekit
|
|
@@ -57,7 +58,9 @@ class MyStartHandler(telekit.Handler):
|
|
|
57
58
|
self.chain.sender.set_photo("robot.png")
|
|
58
59
|
self.chain.send()
|
|
59
60
|
|
|
60
|
-
telekit.
|
|
61
|
+
TOKEN: str = telekit.utils.read_token(".env")
|
|
62
|
+
|
|
63
|
+
telekit.Server(TOKEN).polling()
|
|
61
64
|
```
|
|
62
65
|
|
|
63
66
|
> Send "Hello!" with a photo on `/start`
|
|
@@ -77,17 +80,17 @@ Telekit comes with a [built-in DSL](https://github.com/Romashkaa/telekit/blob/ma
|
|
|
77
80
|
|
|
78
81
|
> See the [full example](https://github.com/Romashkaa/telekit/blob/main/docs/examples/complete_hotel.md)
|
|
79
82
|
|
|
80
|
-
Even in its beta stage, Telekit accelerates bot development, offering typed **command parameters**, **text styling** via `Bold()`, `Italic()`, a built-in declarative **calendar picker
|
|
83
|
+
Even in its beta stage, Telekit accelerates bot development, offering typed **command parameters**, **text styling** via `Bold()`, `Italic()`, a built-in declarative **calendar picker** (!), emoji **game results** for `🎲 🎯 🏀 ⚽ 🎳 🎰`, and much more out of the box. Its declarative design makes bots easier to read, maintain, and extend.
|
|
81
84
|
|
|
82
85
|
**Key features:**
|
|
83
|
-
-
|
|
84
|
-
- [Ready-to-use DSL](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial/11_telekit_dsl.md) for FAQs and
|
|
85
|
-
- Automatic
|
|
86
|
-
-
|
|
87
|
-
-
|
|
88
|
-
-
|
|
89
|
-
-
|
|
90
|
-
-
|
|
86
|
+
- **Chains** handle complex conversations without state machines
|
|
87
|
+
- [Ready-to-use DSL](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial/11_telekit_dsl.md) for FAQs and interactive scripts
|
|
88
|
+
- Automatic [message formatting](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/6_styles.md) via [Sender](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/5_senders.md) and **callback routing**
|
|
89
|
+
- Automatic **`file_id` caching**: local files are uploaded once and reused afterwards
|
|
90
|
+
- **Deep Linking** with type-checked [Command Parameters](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/command_trigger_parameters.md)
|
|
91
|
+
- Built-in **Permission** and **Logging** system
|
|
92
|
+
- Reusable **Traits** for pluggable behavior modules
|
|
93
|
+
- Works with [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI)
|
|
91
94
|
|
|
92
95
|
[GitHub](https://github.com/Romashkaa/telekit)
|
|
93
96
|
[PyPI](https://pypi.org/project/telekit/)
|
|
@@ -108,9 +111,7 @@ Even in its beta stage, Telekit accelerates bot development, offering typed **co
|
|
|
108
111
|
|
|
109
112
|
## Overview
|
|
110
113
|
|
|
111
|
-
**Telekit
|
|
112
|
-
|
|
113
|
-
The idea is simple: you point to the next step — Telekit calls it when the user replies.
|
|
114
|
+
In **Telekit**, dialogs read like normal method calls. You point to the next step. Telekit calls it when the user replies.
|
|
114
115
|
|
|
115
116
|
### Entries
|
|
116
117
|
|
|
@@ -127,13 +128,13 @@ def handle_name(self, name: str):
|
|
|
127
128
|
self.chain.send()
|
|
128
129
|
```
|
|
129
130
|
|
|
130
|
-
|
|
131
|
+
`handle` sends a message and registers `handle_name` as the next step with `set_entry_text`. When the user replies, Telekit calls `handle_name` and passes the reply as a plain `str`.
|
|
131
132
|
|
|
132
133
|
> That's it. No enums. No manual state tracking. No boilerplate.
|
|
133
134
|
|
|
134
135
|
### Inline Keyboards
|
|
135
136
|
|
|
136
|
-
The fastest way to add buttons to a message. Pass a
|
|
137
|
+
The fastest way to add buttons to a message. Pass a `dict` where each key is the button label and each value is the callback to run when pressed:
|
|
137
138
|
|
|
138
139
|
```python
|
|
139
140
|
self.chain.set_inline_keyboard(
|
|
@@ -167,9 +168,7 @@ self.chain.set_inline_keyboard(
|
|
|
167
168
|
╰─────────────┴──────────────────╯
|
|
168
169
|
```
|
|
169
170
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
When you need precise row layout or conditional buttons, use `InlineKeyboard` — a fluent builder that composes keyboards step by step:
|
|
171
|
+
For precise row layout or conditional buttons, use `InlineKeyboard`, a builder you compose step by step:
|
|
173
172
|
|
|
174
173
|
```python
|
|
175
174
|
self.chain.set_keyboard(
|
|
@@ -206,7 +205,7 @@ self.chain.set_keyboard(
|
|
|
206
205
|
|
|
207
206
|
### Reply Keyboards
|
|
208
207
|
|
|
209
|
-
|
|
208
|
+
Reply keyboards replace the system keyboard with buttons at the bottom of the chat. Tapping one sends its text as a message, or triggers a system action like sharing a phone number or location.
|
|
210
209
|
|
|
211
210
|
```python
|
|
212
211
|
self.chain.set_keyboard(
|
|
@@ -239,7 +238,7 @@ class GreetHandler(telekit.Handler):
|
|
|
239
238
|
self.chain.send()
|
|
240
239
|
```
|
|
241
240
|
|
|
242
|
-
Now `/greet
|
|
241
|
+
Now `/greet 128 Dracula` or even `/greet 64 "Alice Reingold"` are parsed automatically.
|
|
243
242
|
|
|
244
243
|
> [!NOTE]
|
|
245
244
|
> If arguments are invalid or missing, you simply receive `None` and decide how to respond.
|
|
@@ -276,17 +275,17 @@ class DialogueHandler(telekit.Handler):
|
|
|
276
275
|
|
|
277
276
|
How it works:
|
|
278
277
|
|
|
279
|
-
- The handler reacts to "hello"
|
|
280
|
-
- `handle_hello` asks for the user's name
|
|
278
|
+
- The handler reacts to `"hello"`, `"hi"`, or `"hey"` in any case.
|
|
279
|
+
- `handle_hello` asks for the user's name.ч
|
|
281
280
|
- `set_entry_suggestions` attaches the user's Telegram `first_name` as a suggestion button.
|
|
282
281
|
- `handle_name` stores the name in `self.user_name`.
|
|
283
|
-
- `handle_feeling`
|
|
282
|
+
- `handle_feeling` closes the flow and adds a "↺ Restart" button that routes back to the start.
|
|
284
283
|
|
|
285
|
-
It
|
|
284
|
+
It reads like regular Python because it is regular Python.
|
|
286
285
|
|
|
287
286
|
### Sender
|
|
288
287
|
|
|
289
|
-
Want to
|
|
288
|
+
Want to attach an image, document or add an effect in a single line?
|
|
290
289
|
|
|
291
290
|
```python
|
|
292
291
|
self.chain.sender.set_effect(Effect.HEART) # Add effect to message. Use enum or string
|
|
@@ -296,12 +295,14 @@ self.chain.sender.set_text_as_document("Hello, this is a text document!") # Conv
|
|
|
296
295
|
self.chain.sender.send_chat_action(ChatAction.TYPING) # Send chat action. Use enum or string
|
|
297
296
|
```
|
|
298
297
|
|
|
298
|
+
Local files are uploaded to Telegram once. Telekit stores the returned `file_id` in a database and reuses it on every next send, so repeated messages with the same photo, document or video go out almost instantly.
|
|
299
|
+
|
|
299
300
|
> [!NOTE]
|
|
300
|
-
> Telekit
|
|
301
|
+
> Telekit picks `bot.send_message` or `bot.send_photo` based on the content you attach.
|
|
301
302
|
|
|
302
303
|
### Styles
|
|
303
304
|
|
|
304
|
-
|
|
305
|
+
Describe formatting as objects instead of writing raw HTML or Markdown.
|
|
305
306
|
|
|
306
307
|
```py
|
|
307
308
|
from telekit.styles import *
|
|
@@ -322,7 +323,7 @@ def handle(self) -> None:
|
|
|
322
323
|
self.chain.send()
|
|
323
324
|
```
|
|
324
325
|
|
|
325
|
-
You describe structure. Telekit
|
|
326
|
+
You describe structure. Telekit turns that structure into HTML or MarkdownV2:
|
|
326
327
|
|
|
327
328
|
```html
|
|
328
329
|
<b>Text style examples:</b>
|
|
@@ -334,11 +335,11 @@ You describe structure. Telekit generates HTML or MarkdownV2 automatically:
|
|
|
334
335
|
- 5. <a href="https://t.me/MyBot?start=promo_42">Deep link</a>
|
|
335
336
|
```
|
|
336
337
|
|
|
337
|
-
|
|
338
|
+
You skip manual escaping and the broken formatting one stray character causes.
|
|
338
339
|
|
|
339
340
|
### Telekit DSL
|
|
340
341
|
|
|
341
|
-
|
|
342
|
+
Prefer not to write dialog logic in Python? Use the built-in DSL with Jinja support.
|
|
342
343
|
|
|
343
344
|
```py
|
|
344
345
|
import telekit
|
|
@@ -413,7 +414,7 @@ telekit.Server(BOT_TOKEN).polling()
|
|
|
413
414
|
|
|
414
415
|
Traits are reusable behavior modules you can mix into any handler.
|
|
415
416
|
|
|
416
|
-
|
|
417
|
+
Here's the built-in `CalendarPick` trait: a user picks a date from an inline calendar, and a callback handles the result.
|
|
417
418
|
|
|
418
419
|
```py
|
|
419
420
|
from telekit.traits import CalendarPick
|
|
@@ -447,7 +448,7 @@ class CalendarHandler(CalendarPick, telekit.Handler):
|
|
|
447
448
|
|
|
448
449
|
### Example Bot
|
|
449
450
|
|
|
450
|
-
|
|
451
|
+
Run this to launch an example bot:
|
|
451
452
|
|
|
452
453
|
```py
|
|
453
454
|
import telekit
|
|
@@ -459,70 +460,100 @@ It includes example commands, dialogs, keyboards, and style usage.
|
|
|
459
460
|
|
|
460
461
|
## Why Telekit
|
|
461
462
|
|
|
462
|
-
-
|
|
463
|
+
- Chains instead of an FSM.
|
|
463
464
|
- Declarative, behavior-focused bot logic with minimal boilerplate.
|
|
464
|
-
- Automatic
|
|
465
|
-
-
|
|
466
|
-
-
|
|
467
|
-
-
|
|
468
|
-
-
|
|
469
|
-
-
|
|
470
|
-
-
|
|
465
|
+
- Automatic callback routing and input handling.
|
|
466
|
+
- Automatic `file_id` caching for local files: no re-uploads, no manual bookkeeping.
|
|
467
|
+
- Styles API for rich text (`Bold`, `Italic`, links) with automatic escaping.
|
|
468
|
+
- Deep linking and typed command parameters.
|
|
469
|
+
- Built-in DSL for menus, FAQs, and simple bots.
|
|
470
|
+
- Reusable Traits for composable behavior, including a built-in calendar picker.
|
|
471
|
+
- Zero-code mode [Obsidian Canvas](https://github.com/Romashkaa/telekit/blob/main/docs/examples/canvas_faq.md) mode.
|
|
472
|
+
- Works with `pyTelegramBotAPI`.
|
|
471
473
|
|
|
472
|
-
Telekit
|
|
473
|
-
It tries to make Telegram bot development easier.
|
|
474
|
+
Telekit focuses on one job: making Telegram bot development easier.
|
|
474
475
|
|
|
475
476
|
> [!TIP]
|
|
476
|
-
>
|
|
477
|
+
> Interested? Start with the [Tutorial](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/0_tutorial.md).
|
|
477
478
|
|
|
478
479
|
---
|
|
479
480
|
|
|
480
|
-
#
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
### v2.
|
|
496
|
-
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
- Added `
|
|
500
|
-
- Added `
|
|
501
|
-
- Added `
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
- Added `
|
|
513
|
-
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
-
|
|
517
|
-
-
|
|
518
|
-
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
- Added
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
481
|
+
# Changelog
|
|
482
|
+
|
|
483
|
+
## File ID Caching, Rich HTML, New Timeout Engine
|
|
484
|
+
|
|
485
|
+
**Telekit 2.6** speeds up file sending, makes bots more resilient and adds Rich HTML messages. What's new:
|
|
486
|
+
|
|
487
|
+
1. **File ID caching.** Local files are uploaded to Telegram once and reused on every next send.
|
|
488
|
+
2. **Rich HTML messages** (Bot API 10.1+).
|
|
489
|
+
3. **New timeout engine.** No more `can't start new thread` with ~1000 active chats (#6).
|
|
490
|
+
4. **Smart restarts.** The new `restart` parameter (`"always"`, `"network"`, `"never"`) with exponential backoff keeps the server alive through network failures.
|
|
491
|
+
5. **Keyboards in senders.** `set_keyboard()` and `to_markup()` let you attach keyboards to a plain `sender` without a chain.
|
|
492
|
+
6. **Full `.env` support.** Comments, quotes, multi-line values and `$VAR` interpolation.
|
|
493
|
+
7. **Better logging.** Rich output when `rich` is installed, bot tokens masked in logs, no duplicated records.
|
|
494
|
+
8. **Handoff shortcuts.** `handle_handoff()` and `handle_handoff_back_or()` work without closures.
|
|
495
|
+
|
|
496
|
+
### v2.6.0
|
|
497
|
+
- Stable release. See the `a0`–`a9` entries below for the full list of changes.
|
|
498
|
+
|
|
499
|
+
### v2.6.0 `a9` – Keyboards in Senders
|
|
500
|
+
- 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()`
|
|
501
|
+
- Added `ReplyKeyboard.to_markup()`: a public counterpart of the internal `_compile()` that returns a `ReplyKeyboardMarkup`
|
|
502
|
+
- 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
|
|
503
|
+
|
|
504
|
+
### v2.6.0 `a7` – Sender, Server, Logging
|
|
505
|
+
#### Sender: automatic `file_id` caching
|
|
506
|
+
- 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
|
|
507
|
+
- Added `BaseSender.configure_file_cache()`: a class method that sets the database path, table name and global on/off switch
|
|
508
|
+
- Added `Sender.set_use_file_cache()`: a per-sender override of the global setting (`None` restores it)
|
|
509
|
+
- Changed missing local files to raise on `send()` instead of in the setter
|
|
510
|
+
- A rejected cached `file_id` is dropped and the send is retried with the original file
|
|
511
|
+
- 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
|
|
512
|
+
#### Server: restarts and network protection
|
|
513
|
+
- Added `restart` parameter to `Server`: `"always"` (default), `"network"` or `"never"`; accepts `RestartMode` or the matching string
|
|
514
|
+
- 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`)
|
|
515
|
+
- 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`
|
|
516
|
+
- Added `restart="network"`: survives only network errors and Bot API `429`, `500`, `502`, `503`, `504`; any other error (bad token, `409` conflict, bugs) is re-raised. `retry_after` from Telegram is respected
|
|
517
|
+
- Changed `Server.__init__()` to wait for the Bot API to become reachable before calling `getMe` (skipped for `restart="never"` and when `apihelper.proxy` is set)
|
|
518
|
+
- Fixed `Server.polling()` and `Server.long_polling()` restarting after `stop_polling()`: they now return instead
|
|
519
|
+
- Fixed a failed `getMe` in the restart cycle killing the server and hiding the original error
|
|
520
|
+
- Fixed bot tokens leaking into logs through request URLs: they are now masked as `bot<hidden>`
|
|
521
|
+
- Changed log levels in `Server`: network errors are logged as `WARNING` (without traceback), unexpected errors as `ERROR` (with traceback), `FATAL` is kept for `[server dead]`.
|
|
522
|
+
#### Logging
|
|
523
|
+
- Added Rich output for logs when `rich` is installed; set `TELEKIT_NO_RICH=1` to disable it
|
|
524
|
+
- Added direct exports `server_logger`, `library_logger`, `user_logger` and `get_user_logger()` to `_logger.py`. `logger.server`, `logger.library`, `logger.users()`, `_server` and `_library` still work
|
|
525
|
+
- Added `set_level()`, `disable_user_logging()` and `UserLogger.exception()`
|
|
526
|
+
- 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")`
|
|
527
|
+
- 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`
|
|
528
|
+
- Fixed `UserLogger` reporting its own module as the log source
|
|
529
|
+
|
|
530
|
+
### v2.6.0 `a6` (fixes #6) – Timeout engine
|
|
531
|
+
- 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`
|
|
532
|
+
- Timeout callback exceptions are now logged
|
|
533
|
+
- 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)
|
|
534
|
+
|
|
535
|
+
### v2.6.0 `a4` – Handoff shortcuts
|
|
536
|
+
- 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
|
|
537
|
+
- Added `handle_handoff_back_or()` to `TrackHandoffOrigin`: a closure-free counterpart of `handoff_back_or()`
|
|
538
|
+
- Reworked `handoff_back_or()` as a thin `functools.partial` wrapper around `handle_handoff_back_or()`
|
|
539
|
+
- Fixed the `handoff_back_or()` docstring: the returned callable forwards its arguments to `handle()` instead of being zero-argument
|
|
540
|
+
- Converted the `handoff()` docstring to reST
|
|
541
|
+
|
|
542
|
+
### v2.6.0 `a3` – Rich HTML
|
|
543
|
+
- Added support for Rich HTML messages (Bot API 10.1+)
|
|
544
|
+
- Added the `_rich.py` module for Rich HTML parsing and serialization
|
|
545
|
+
- Added new rich tags to `styles.py` for enhanced text formatting
|
|
546
|
+
- Added the `rich.py` example handler demonstrating Rich HTML: inline styles, blocks, lists, tables, media, and sender integration
|
|
547
|
+
|
|
548
|
+
### v2.6.0 `a2` – Env parsing
|
|
549
|
+
- Reworked `.env` and token/canvas file reading in `utils`
|
|
550
|
+
- Added full `.env` syntax support: comments, `export`, quotes and escapes, multi-line values, `$VAR` interpolation
|
|
551
|
+
- Added the `cache` parameter (default `True`) and `clear_cache()`
|
|
552
|
+
- Added detailed errors with fix suggestions and creation commands, and new `Env*Error` exceptions
|
|
553
|
+
- Changed `load_env()` to raise `EnvFileNotFoundError` for a missing file instead of returning `{}`
|
|
554
|
+
|
|
555
|
+
### v2.6.0 `a1` – Module loader
|
|
556
|
+
- Added a module-loading utility to `utils`
|
|
557
|
+
|
|
558
|
+
### v2.6.0 `a0`
|
|
559
|
+
- Improved formatting in `_on.py`
|