telekit 2.5.3__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.
Files changed (98) hide show
  1. telekit-2.6.0/CHANGELOG.md +77 -0
  2. telekit-2.6.0/MANIFEST.in +4 -0
  3. {telekit-2.5.3 → telekit-2.6.0}/PKG-INFO +129 -97
  4. {telekit-2.5.3 → telekit-2.6.0}/README.md +44 -44
  5. {telekit-2.5.3 → telekit-2.6.0}/setup.cfg +0 -3
  6. telekit-2.6.0/setup.py +70 -0
  7. {telekit-2.5.3 → telekit-2.6.0}/telekit/__init__.py +8 -4
  8. telekit-2.5.3/telekit/_version.py → telekit-2.6.0/telekit/__version__.py +1 -2
  9. {telekit-2.5.3 → telekit-2.6.0}/telekit/_buildtext/styles.py +484 -1
  10. {telekit-2.5.3 → telekit-2.6.0}/telekit/_chain.py +5 -3
  11. {telekit-2.5.3 → telekit-2.6.0}/telekit/_chain_base.py +6 -3
  12. {telekit-2.5.3 → telekit-2.6.0}/telekit/_chain_inline_keyboards_logic.py +10 -8
  13. telekit-2.6.0/telekit/_file_cache.py +136 -0
  14. {telekit-2.5.3 → telekit-2.6.0}/telekit/_handler.py +36 -1
  15. {telekit-2.5.3 → telekit-2.6.0}/telekit/_inline_keyboard.py +93 -0
  16. telekit-2.6.0/telekit/_logger.py +206 -0
  17. {telekit-2.5.3 → telekit-2.6.0}/telekit/_on.py +154 -26
  18. {telekit-2.5.3 → telekit-2.6.0}/telekit/_reply_keyboard.py +34 -3
  19. telekit-2.6.0/telekit/_rich.py +381 -0
  20. {telekit-2.5.3 → telekit-2.6.0}/telekit/_telekit_dsl/mixin.py +1 -1
  21. telekit-2.6.0/telekit/_timeout.py +424 -0
  22. telekit-2.6.0/telekit/example/example_handlers/__init__.py +9 -0
  23. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/complete_hotel.py +1 -1
  24. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/hotel.py +1 -1
  25. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/qr.py +1 -1
  26. telekit-2.6.0/telekit/example/example_handlers/rich.py +555 -0
  27. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/start.py +3 -1
  28. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_server.py +3 -20
  29. {telekit-2.5.3 → telekit-2.6.0}/telekit/reply_buttons.py +1 -1
  30. telekit-2.6.0/telekit/requirements.txt +3 -0
  31. {telekit-2.5.3 → telekit-2.6.0}/telekit/senders.py +413 -34
  32. telekit-2.6.0/telekit/server.py +540 -0
  33. {telekit-2.5.3 → telekit-2.6.0}/telekit/styles.py +31 -6
  34. {telekit-2.5.3 → telekit-2.6.0}/telekit/traits/track_handoff_origin.py +63 -25
  35. {telekit-2.5.3 → telekit-2.6.0}/telekit/utils.py +531 -74
  36. {telekit-2.5.3 → telekit-2.6.0}/telekit.egg-info/PKG-INFO +129 -97
  37. {telekit-2.5.3 → telekit-2.6.0}/telekit.egg-info/SOURCES.txt +7 -2
  38. {telekit-2.5.3 → telekit-2.6.0}/telekit.egg-info/requires.txt +1 -1
  39. telekit-2.5.3/setup.py +0 -73
  40. telekit-2.5.3/telekit/_logger.py +0 -129
  41. telekit-2.5.3/telekit/_timeout.py +0 -73
  42. telekit-2.5.3/telekit/example/example_handlers/__init__.py +0 -19
  43. telekit-2.5.3/telekit/server.py +0 -160
  44. {telekit-2.5.3 → telekit-2.6.0}/LICENSE +0 -0
  45. {telekit-2.5.3 → telekit-2.6.0}/telekit/_buildtext/__init__.py +0 -0
  46. {telekit-2.5.3 → telekit-2.6.0}/telekit/_buildtext/formatter.py +0 -0
  47. {telekit-2.5.3 → telekit-2.6.0}/telekit/_callback_query_handler.py +0 -0
  48. {telekit-2.5.3 → telekit-2.6.0}/telekit/_chain_entry_logic.py +0 -0
  49. {telekit-2.5.3 → telekit-2.6.0}/telekit/_chapters/__init__.py +0 -0
  50. {telekit-2.5.3 → telekit-2.6.0}/telekit/_chapters/chapters.py +0 -0
  51. {telekit-2.5.3 → telekit-2.6.0}/telekit/_init.py +0 -0
  52. {telekit-2.5.3 → telekit-2.6.0}/telekit/_inline_buttons.py +0 -0
  53. {telekit-2.5.3 → telekit-2.6.0}/telekit/_input_handler.py +0 -0
  54. {telekit-2.5.3 → telekit-2.6.0}/telekit/_snapvault/__init__.py +0 -0
  55. {telekit-2.5.3 → telekit-2.6.0}/telekit/_snapvault/snapcode.py +0 -0
  56. {telekit-2.5.3 → telekit-2.6.0}/telekit/_snapvault/snapvault.py +0 -0
  57. {telekit-2.5.3 → telekit-2.6.0}/telekit/_state.py +0 -0
  58. {telekit-2.5.3 → telekit-2.6.0}/telekit/_telekit_dsl/__init__.py +0 -0
  59. {telekit-2.5.3 → telekit-2.6.0}/telekit/_telekit_dsl/parser/__init__.py +0 -0
  60. {telekit-2.5.3 → telekit-2.6.0}/telekit/_telekit_dsl/parser/builder.py +0 -0
  61. {telekit-2.5.3 → telekit-2.6.0}/telekit/_telekit_dsl/parser/canvas_parser.py +0 -0
  62. {telekit-2.5.3 → telekit-2.6.0}/telekit/_telekit_dsl/parser/lexer.py +0 -0
  63. {telekit-2.5.3 → telekit-2.6.0}/telekit/_telekit_dsl/parser/nodes.py +0 -0
  64. {telekit-2.5.3 → telekit-2.6.0}/telekit/_telekit_dsl/parser/parser.py +0 -0
  65. {telekit-2.5.3 → telekit-2.6.0}/telekit/_telekit_dsl/parser/token.py +0 -0
  66. {telekit-2.5.3 → telekit-2.6.0}/telekit/_telekit_dsl/telekit_dsl.py +0 -0
  67. {telekit-2.5.3 → telekit-2.6.0}/telekit/_telekit_dsl/telekit_orm.py +0 -0
  68. {telekit-2.5.3 → telekit-2.6.0}/telekit/_text_builder.py +0 -0
  69. {telekit-2.5.3 → telekit-2.6.0}/telekit/_trait.py +0 -0
  70. {telekit-2.5.3 → telekit-2.6.0}/telekit/_user.py +0 -0
  71. {telekit-2.5.3 → telekit-2.6.0}/telekit/chat.py +0 -0
  72. {telekit-2.5.3 → telekit-2.6.0}/telekit/debug.py +0 -0
  73. {telekit-2.5.3 → telekit-2.6.0}/telekit/dices.py +0 -0
  74. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/__init__.py +0 -0
  75. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/article.py +0 -0
  76. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/calendar.py +0 -0
  77. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/counter.py +0 -0
  78. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/dsl.py +0 -0
  79. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/entry.py +0 -0
  80. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/faq.py +0 -0
  81. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/on_text.py +0 -0
  82. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/pages.py +0 -0
  83. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/pyapi.py +0 -0
  84. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/quiz.py +0 -0
  85. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/spells.py +0 -0
  86. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/style.py +0 -0
  87. {telekit-2.5.3 → telekit-2.6.0}/telekit/example/example_handlers/text_document.py +0 -0
  88. {telekit-2.5.3 → telekit-2.6.0}/telekit/html_text.py +0 -0
  89. {telekit-2.5.3 → telekit-2.6.0}/telekit/inline_buttons.py +0 -0
  90. {telekit-2.5.3 → telekit-2.6.0}/telekit/parameters.py +0 -0
  91. {telekit-2.5.3 → telekit-2.6.0}/telekit/scheduler.py +0 -0
  92. {telekit-2.5.3 → telekit-2.6.0}/telekit/traits/__init__.py +0 -0
  93. {telekit-2.5.3 → telekit-2.6.0}/telekit/traits/calendar_pick.py +0 -0
  94. {telekit-2.5.3 → telekit-2.6.0}/telekit/traits/paginated_choice.py +0 -0
  95. {telekit-2.5.3 → telekit-2.6.0}/telekit/traits/paginated_text.py +0 -0
  96. {telekit-2.5.3 → telekit-2.6.0}/telekit/types.py +0 -0
  97. {telekit-2.5.3 → telekit-2.6.0}/telekit.egg-info/dependency_links.txt +0 -0
  98. {telekit-2.5.3 → 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`
@@ -0,0 +1,4 @@
1
+ include README.md
2
+ include CHANGELOG.md
3
+ include LICENSE
4
+ include telekit/requirements.txt
@@ -1,26 +1,26 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: telekit
3
- Version: 2.5.3
4
- Summary: Declarative, developer-friendly library for building Telegram bots
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: GPLv3
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.31.0
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 library 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 library also handles inline keyboards and callback routing automatically, letting you focus on the bot's behavior instead of repetitive tasks.
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.Server("BOT_TOKEN").polling()
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**, emoji **game results** for `🎲 🎯 🏀 ⚽ 🎳 🎰`, and much more out of the box. Its declarative design makes bots easier to read, maintain, and extend.
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
- - Declarative bot logic with **chains** for effortless handling of complex conversations
84
- - [Ready-to-use DSL](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial/11_telekit_dsl.md) for FAQs and other interactive scripts
85
- - Automatic handling of [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**
86
- - **Deep Linking** support with type-checked [Command Parameters](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/command_trigger_parameters.md) for flexible user input
87
- - Built-in **Permission** and **Logging** system for user management
88
- - Reusable **Traits** system for pluggable, self-contained behavior modules
89
- - Seamless integration with [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI)
90
- - Fast to develop and easy-to-extend code
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** is a library for building Telegram bots where dialogs look like normal method calls. No bulky state machines. No scattered handlers.
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
- The `handle` method sends a message and registers `handle_name` as the next step using `set_entry_text`. When the user replies, Telekit automatically calls `handle_name` and passes the user's message as a plain `str` argument.
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 plain `dict` where each key is the button label and each value is the callback to invoke when pressed:
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
- **Need more control?**
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
- Unlike inline keyboards, reply keyboards replace the user's system keyboard with buttons shown at the bottom of the chat. Tapping a button either sends its text as a regular message or triggers a system action, such as sharing a phone number or location.
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 64 "Alice Reingold"` or `/greet 128 Dracula` are parsed automatically.
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", "hi", or "hey" (lowercase, UPPERCASE, or mixed).
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` completes the flow and adds a `"↺ Restart"` button that routes back to the beginning.
282
+ - `handle_feeling` closes the flow and adds a "↺ Restart" button that routes back to the start.
284
283
 
285
- It looks like regular Python. And reads like it too.
284
+ It reads like regular Python because it is regular Python.
286
285
 
287
286
  ### Sender
288
287
 
289
- Want to add an image, document or an effect in a single line?
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 automatically decides whether to use `bot.send_message` or `bot.send_photo` based on the content
301
+ > Telekit picks `bot.send_message` or `bot.send_photo` based on the content you attach.
301
302
 
302
303
  ### Styles
303
304
 
304
- Telekit lets you describe formatting as objects instead of writing raw HTML or Markdown.
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 generates HTML or MarkdownV2 automatically:
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
- No manual escaping. No broken formatting because of one missing character.
338
+ You skip manual escaping and the broken formatting one stray character causes.
338
339
 
339
340
  ### Telekit DSL
340
341
 
341
- If you prefer not to write dialog logic in Python, you can use the built-in DSL with Jinja support.
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
- This example demonstrates the simplest way to use the built-in CalendarPick trait. It allows a user to pick a date from an inline calendar and handles the result via a callback.
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
- You can launch an example bot by **running the following code**:
451
+ Run this to launch an example bot:
451
452
 
452
453
  ```py
453
454
  import telekit
@@ -459,69 +460,100 @@ It includes example commands, dialogs, keyboards, and style usage.
459
460
 
460
461
  ## Why Telekit
461
462
 
462
- - No FSM — just **chains**.
463
+ - Chains instead of an FSM.
463
464
  - Declarative, behavior-focused bot logic with minimal boilerplate.
464
- - Automatic **callback routing** and **input handling**.
465
- - **Styles API** for rich text (`Bold`, `Italic`, `Links`) with **automatic escaping**.
466
- - Deep linking and **typed command parameters**.
467
- - **Built-in DSL** for menus, FAQs, and simple bots.
468
- - Reusable **Traits** for composable, plug-and-play behavior (for example, a built-in declarative calendar picker).
469
- - **Zero-code** [Obsidian Canvas](https://github.com/Romashkaa/telekit/blob/main/docs/examples/canvas_faq.md) mode.
470
- - Seamless integration with **pyTelegramBotAPI**.
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 doesn't try to be everything.
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
- > If you're interested and want to learn more, check out the [Tutorial](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/0_tutorial.md)
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
- # Changes in version 2.5.3
481
-
482
- ### v2.5.3
483
- - Fix: Remove `_` parameters from `_filter_entry` and `_handle_entry` methods in `DSLHandler`
484
-
485
- ### v2.5.2
486
- - Add `random_` variable prefix in `DSLHandler` — resolves to a random choice from a `list`/`tuple`/`str` static variable
487
-
488
- ### v2.5.1 `(bug-fix)`
489
- - Implement `TelegramMarkdownV2Sanitizer` for improved `MarkdownV2` handling
490
-
491
- ### v2.5.0 `(final)`
492
- - Refactor `CalendarPick` trait to use `set_keyboard`
493
-
494
- ### v2.5.0`b3`
495
- - Added `utils.Markers` class
496
- - Added `HTMLText` class for handling Telegram HTML strings with tag-aware indexing and slicing.
497
- - Added `PaginatedText` trait for displaying long HTML text in a paginated format, supporting navigation and smart splitting.
498
- - Added `__radd__` to `TextEntity`: `"Regular" + Bold(" and Bold")`
499
- - Added `__mul__` to `TextEntity`: `Bold("Text") * 3`
500
- - Added `enabled=` parameter to `TextEntity`: `Bold("bold text", enabled=is_text_bold)`
501
- - Added `TextBuilder` class – a fluent message composition API mirroring `InlineKeyboard`'s builder pattern
502
- - Added styles to `telekit.types`
503
- - Added `utils.CyclicList`
504
- - Fixed `_answer_callback_query` to always call `bot.answer_callback_query()`, even without a popup text
505
-
506
- ### v2.5.0`b2`
507
- - Added the `escape` parameter to `telekit.utils.*`:
508
- - `make_user_link`
509
- - `make_bot_link`
510
- - `Handler.handlers_dict` now excludes private handlers (classes whose names start with `_`).
511
- - Added `Debug.duplicate_handler_warnings` to warn about duplicate handler names during initialization.
512
- - Added `Handler.chat` object (BETA)
513
-
514
- ### v2.5.0`b1`
515
- - Added `Sender.send_message` method.
516
- - Added `utils.make_mention` utility for generating `tg://user?id=` mention links.
517
- - Added new inline button types to `inline_buttons`:
518
- - `ContactButton` — mentions a user by Telegram ID via `tg://user?id=`.
519
- - `UserLinkButton` — opens a user profile by username; supports pre-filled message text.
520
- - `BotLinkButton` — opens a bot by username; supports deep-link `?start=` payload.
521
- - Added new methods to `InlineKeyboard`:
522
- - `add_contact` — adds a `ContactButton`.
523
- - `add_user_link` — adds a `UserLinkButton`.
524
- - `add_bot_link` — adds a `BotLinkButton`.
525
-
526
- ### v2.5.0`b0`
527
- - Added support for t-strings (PEP 750, Python 3.14+) in `TextEntity`.
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`