telekit 2.3.0b2__tar.gz → 2.3.0b3__tar.gz

{telekit-2.3.0b2/telekit.egg-info → telekit-2.3.0b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.3.0b2
+Version: 2.3.0b3
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -379,148 +379,6 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.3.0b2
+# Changes in version 2.3.0b3
 
-## Inline Buttons
-
-| **Name**         | **Description**                                                                 |
-| ---------------- | ------------------------------------------------------------------------------- |
-| `StaticButton`   | A non-interactive inline button that performs no action when pressed.           |
-| `AnswerButton`   | A button that responds to a callback query with a notification or alert without executing custom logic. |
-
-- `AnswerButton` and its subclasses (`AlertButton`, `NotificationButton`) now support the `persistent` parameter (Defauts to `True`):
-  - `True` — non-blocking hint (does not affect further interactions)
-  - `False` — terminates interaction after click
-
-## Traits
-
-| **Name**                   | **Description**                                                       |
-| -------------------------- | --------------------------------------------------------------------- |
-| `TrackHandoffOrigin`  | Tracks which handler transferred control to this one via `handoff()`.      |
-| `PaginatedChoice`    | Adds a paginated inline keyboard for choosing from a list of items.        |
-
-### TrackHandoffOrigin
-
-`TrackHandoffOrigin` adds three members to any handler that inherits it:
-
-| **Member**          | **Description**                                                                  |
-| ------------------- | -------------------------------------------------------------------------------- |
-| `handoff_origin`    | The handler instance that handed off to this one, or `None` if invoked directly. |
-| `is_handed_off`     | `True` if this handler was reached via `handoff()`, `False` otherwise.           |
-| `handoff_back()`    | Transfer control back to the origin handler via `self.handoff_origin.handle()`   |
-| `handoff_back_or(handler)` | Like `handoff_back()`, but falls back to `handler` on fail.               |
-
-Set `TRACK_HANDOFF_ORIGIN = False` on any subclass to opt out of tracking.
-
-```python
-class MyHandler(TrackHandoffOrigin, telekit.Handler):
-
-    def handle(self):
-        ...
-        self.chain.set_inline_keyboard({
-            "« Back": self.handoff_back_or(StartHandler)
-        })
-        self.chain.edit()
-```
-
-### PaginatedChoice
-
-Renders a paginated inline keyboard from any dict or iterable.
-Navigation buttons (`« Back`, `Next »`) are added automatically.
-
-| **Member**           | **Description**                                                              |
-| -------------------- | ---------------------------------------------------------------------------- |
-| `paginated_choice(choices, on_choice, ...)` | Display a paginated choice keyboard. |
-| `PAGINATED_CHOICE_BACK_LABEL` | Label for the back navigation button. Defaults to `« Back`. |
-| `PAGINATED_CHOICE_NEXT_LABEL` | Label for the next navigation button. Defaults to `Next »`. |
-| `PAGINATED_CHOICE_PAGE_LABEL` | Label template for the page indicator button. Supports `{page}` and `{pages}` placeholders. Set to `None` to hide. Defaults to `{page} / {pages}`. |
-
-
-```python
-self.chain.sender.set_title("🔤 What is your initial?")
-self.chain.sender.set_message("Pick the first letter of your name")
-self.chain.sender.set_remove_text(False)
-
-self.paginated_choice(
-    choices="ABCDEFGHIJKLMNOPQRSTUVWXYZ",
-    on_choice=self.handle_letter,
-    row_width=5
-)
-```
-
-Override labels per handler to localise or restyle navigation:
-
-```python
-class MyHandler(PaginatedChoice, telekit.Handler):
-    PAGINATED_CHOICE_BACK_LABEL = "⬅️ Назад"
-    PAGINATED_CHOICE_NEXT_LABEL = "Далі ➡️"
-    PAGINATED_CHOICE_PAGE_LABEL = None  # hide page indicator
-```
-
-<details>
-  <summary>(Click to see the result)</summary>
-  <table>
-    <tr>
-      <td><img src="https://github.com/Romashkaa/telekit/blob/main/docs/images/paginated_choice.png?raw=true" alt="Example" width="300"></td>
-    </tr>
-  </table>
-</details>
-
-`choices` accepts a `dict[str, T]`, or any `Iterable[T]`.
-If only one item is present, `on_choice` is called immediately without rendering a keyboard.
-
-## Utils
-
-| **Name**           | **Description**                                                    |
-| ------------------ | ------------------------------------------------------------------ |
-| `load_env`         | Load all key-value pairs from a `.env` file into a dictionary.     |
-| `read_env_var`     | Read a single variable by name from a `.env` file.                 |
-| `compose_keyboard` | Merge multiple button groups into a single inline keyboard with computed `row_width`. |
-
-### Environment Utils
-
-- `read_token` and `read_canvas_path` now support reading from `.env` files.
-  Pass `".env"` to use the default key, or `".env:KEY"` to specify a custom one:
-
-```python
-read_token(".env")                 # reads TOKEN
-read_token(".env:BOT_TOKEN")       # reads BOT_TOKEN
-
-read_canvas_path(".env")           # reads CANVAS_PATH
-read_canvas_path(".env:MY_CANVAS") # reads MY_CANVAS
-```
-
-### Inline Keyboard Utils
-
-`compose_keyboard` combines multiple button groups into a single keyboard and automatically calculates `row_width` for each group.
-
-Each group is laid out independently using its corresponding width from `widths`.
-A width of `-1` means "all buttons in one row" (i.e. ``len(group)``).
-
-| **Param** | **Type**         | **Description**                             |
-|-----------|------------------|---------------------------------------------|
-| `groups`  | `dict[str, Any]` | One or more button groups                   |
-| `widths`  | `Iterable[int]`  | Row width per group or single value for all |
-
-| **Returns** | **Type** |
-|------------|----------|
-| `keyboard` | `dict[str, Any]` |
-| `row_width` | `tuple[int, ...]` |
-
-```py
-# row_width → (1, 3, 3, 3, 2)
-# layout:
-#   |    🆕 Create    |
-#   |  1  |  2  |  3  |
-#   |  4  |  5  |  6  |
-#   |  7  |  8  |  9  |
-#   | « Back | Next » |
-
-keyboard, row_width = compose_keyboard(
-    {"🆕 Create": "create"},
-    {str(n): str(n) for n in range(1, 10)},
-    {"« Back": "back", "Next »": "next"},
-    widths=(-1, 3, -1), # or (1, 3, 2)
-)
-self.chain.set_inline_choice(keyboard, row_width)
-```
+[View changelog on GitHub](https://github.com/Romashkaa/telekit/blob/main/CHANGELOG.md)

{telekit-2.3.0b2 → telekit-2.3.0b3}/setup.py

@@ -28,8 +28,7 @@ def readme():
         return f.read()
   
 def changelog():
-    with open('CHANGELOG.md', 'r') as f:
-        return f.read()
+    return f"[View changelog on GitHub](https://github.com/Romashkaa/telekit/blob/main/CHANGELOG.md)"
 
 def install_requires():
     with open('telekit/requirements.txt', 'r') as f:

{telekit-2.3.0b2 → telekit-2.3.0b3}/telekit/__init__.py

@@ -18,6 +18,7 @@
 # 
 
 from ._handler import Handler
+from ._trait import Trait
 from ._chain import Chain
 from ._callback_query_handler import CallbackQueryHandler
 from .server import Server, example
@@ -36,6 +37,7 @@ from . import inline_buttons
 from . import dices
 from . import utils
 from . import traits
+from . import debug
 
 Styles = styles.Styles
 
@@ -56,6 +58,7 @@ __all__ = [
 
     "Server", 
     "Chain", 
+    "Trait",
     "Handler", 
     "CallbackQueryHandler",
 
@@ -66,4 +69,5 @@ __all__ = [
     "enable_file_logging",
     "chapters",
     "example",
+    "debug",
 ]

{telekit-2.3.0b2 → telekit-2.3.0b3}/telekit/_chain.py

@@ -26,6 +26,7 @@ from telebot.types import Message
 
 # Local modules
 from . import senders
+from .debug import Debug
 from .styles import TextEntity
 
 # Chain modules
@@ -154,7 +155,7 @@ class Chain(ChainInlineKeyboardLogic, ChainEntryLogic):
         self.sender.set_edit_message(None)
         self._previous_message = message
 
-        if self._timeout_warnings_enabled and _handler and not _timeout:
+        if Debug.timeout_warnings and _handler and not _timeout:
             library.warning(
                 "Next-message handler is active, but no timeout was set for the chain. "
                 "This may cause the bot to wait indefinitely."

{telekit-2.3.0b2 → telekit-2.3.0b3}/telekit/_chain_base.py

@@ -31,14 +31,13 @@ from . import _input_handler
 from . import _timeout
 
 # Logging
+from .debug import Debug
 from ._logger import logger
 library = logger.library
 
 class ChainBase:
 
     bot: telebot.TeleBot
-
-    _timeout_warnings_enabled: bool = True
     
     @classmethod
     def _init(cls, bot: telebot.TeleBot):
@@ -206,4 +205,5 @@ class ChainBase:
     # Timeout API
 
     def disable_timeout_warnings(self, value: bool = True) -> None:
-        self._timeout_warnings_enabled = not value
+        """.. deprecated:: Set ``Debug.timeout_warnings`` directly."""
+        Debug.timeout_warnings = not value

{telekit-2.3.0b2 → telekit-2.3.0b3}/telekit/_init.py

@@ -31,7 +31,7 @@ import telebot
 __all__ = ["init"]
 
 def init(bot: telebot.TeleBot) -> None:
-    TelekitState.init(bot)
+    TelekitState._init(bot)
     BaseSender._init(bot)
     Handler._init(bot)
     Chain._init(bot)

{telekit-2.3.0b2 → telekit-2.3.0b3}/telekit/_inline_buttons.py

@@ -26,6 +26,8 @@ from telebot.types import InlineKeyboardButton, CallbackQuery
 from telebot import TeleBot
 from ._callback_query_handler import CallbackQueryHandler
 
+from ._state import TelekitState
+
 __all__ = [
     "InlineButton",
 
@@ -122,6 +124,15 @@ class InlineButton:
             raise ValueError(f"Unknown style: {style!r}. Must be one of {_BUTTON_STYLES_LIST}")
         raise TypeError(f"Style must be str, ButtonStyle, or None, got {type(style)}")
     
+    def _normalize_custom_emoji_id(self, custom_emoji_id: int | str | None) -> str | None:
+        if not custom_emoji_id:
+            return None
+        
+        if not TelekitState.is_premium():
+            return None
+
+        return str(custom_emoji_id)
+    
 class StaticButton(InlineButton):
 
     def __init__(self, *, style: str | None | ButtonStyle = None, **kwargs):

{telekit-2.3.0b2 → telekit-2.3.0b3}/telekit/_state.py

@@ -1,16 +1,27 @@
 from telebot import TeleBot
 
 
+class DebugLevel:
+    NONE:      int = 0
+    INFO:      int = 1
+    DEBUG:     int = 2
+
+
 class TelekitState:
 
     __bot: TeleBot
 
     @classmethod
-    def init(cls, bot: TeleBot) -> None:
+    def _init(cls, bot: TeleBot) -> None:
         if hasattr(cls, "_TelekitState__bot"):
             raise RuntimeError("TelekitState is already initialized")
 
         cls.__bot = bot
+        cls._update()
+
+    @classmethod
+    def _update(cls):
+        cls.__info = cls.__bot.get_me()
 
     @classmethod
     def get_bot(cls) -> TeleBot:
@@ -19,4 +30,6 @@ class TelekitState:
 
         return cls.__bot
     
-    DEBUG: bool = False
+    @classmethod
+    def is_premium(cls) -> bool:
+        return cls.__info.is_premium or False

telekit-2.3.0b3/telekit/_trait.py

@@ -0,0 +1,10 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from telekit import Handler as _Base
+else:
+    _Base = object
+
+class Trait(_Base):
+    """Base for all traits."""
+    pass

{telekit-2.3.0b2 → telekit-2.3.0b3}/telekit/_version.py

@@ -3,4 +3,4 @@
 # PyPI history: https://pypi.org/project/telekit/#history
 # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
-__version__ = "2.3.0b2"
+__version__ = "2.3.0b3"

telekit-2.3.0b3/telekit/debug.py

@@ -0,0 +1,8 @@
+class Debug:
+    timeout_warnings: bool = False
+    deletion_warnings: bool = False
+
+    @classmethod
+    def set_all(cls, value: bool) -> None:
+        for key in cls.__annotations__:
+            setattr(cls, key, value)

{telekit-2.3.0b2 → telekit-2.3.0b3}/telekit/example/example_handlers/__init__.py

@@ -12,5 +12,6 @@ from . import (
     hotel,
     complete_hotel,
     text_document,
-    qr
+    qr,
+    calendar,
 )

telekit-2.3.0b3/telekit/example/example_handlers/calendar.py

@@ -0,0 +1,223 @@
+"""
+Event distance bot — pick any date and find out how far it is from today.
+Works for both past events ("it was X ago") and future events ("it will be in X").
+Uses the Calendar trait for date selection; no database required.
+"""
+from __future__ import annotations
+
+import datetime
+
+import telekit
+import telekit.traits
+
+from telekit.styles import Bold, Code, Group, Italic, Quote
+
+
+# ---------------------------------------------------------------------------
+# Time-distance helpers
+# ---------------------------------------------------------------------------
+
+def _diff(a: datetime.date, b: datetime.date) -> tuple[int, int, int]:
+    """
+    Return the absolute difference between *a* and *b* as (years, months, days).
+
+    Always returns non-negative values; direction is determined by the caller.
+
+    :param a: First date.
+    :param b: Second date (order does not matter).
+    :returns: Tuple ``(years, months, days)`` with all values >= 0.
+    """
+    if a > b:
+        a, b = b, a
+
+    years  = b.year  - a.year
+    months = b.month - a.month
+    days   = b.day   - a.day
+
+    if days < 0:
+        months -= 1
+        prev_month_last = (datetime.date(b.year, b.month, 1) - datetime.timedelta(days=1)).day
+        days += prev_month_last
+
+    if months < 0:
+        years  -= 1
+        months += 12
+
+    return years, months, days
+
+
+def _fmt(years: int, months: int, days: int) -> str:
+    """
+    Format a duration, omitting zero components.
+
+    Examples::
+
+        _fmt(0, 0, 1)  -> "1 day"
+        _fmt(2, 3, 0)  -> "2 years and 3 months"
+        _fmt(1, 0, 5)  -> "1 year and 5 days"
+
+    :param years: Number of whole years.
+    :param months: Number of remaining whole months.
+    :param days: Number of remaining days.
+    :returns: Human-readable duration string.
+    """
+    parts: list[str] = []
+    if years:
+        parts.append(f"{years} year{'s' if years != 1 else ''}")
+    if months:
+        parts.append(f"{months} month{'s' if months != 1 else ''}")
+    if days:
+        parts.append(f"{days} day{'s' if days != 1 else ''}")
+
+    if not parts:
+        return "today"
+    if len(parts) == 1:
+        return parts[0]
+    return ", ".join(parts[:-1]) + " and " + parts[-1]
+
+
+def _describe(chosen: datetime.date) -> str:
+    """
+    Build a human-readable distance string from *chosen* to today.
+
+    :param chosen: The date selected by the user.
+    :returns: Sentence describing how far the date is from today.
+    """
+    today    = datetime.date.today()
+    y, mo, d = _diff(chosen, today)
+    duration = _fmt(y, mo, d)
+
+    if chosen == today:
+        return "That's today! 🎉"
+    elif chosen < today:
+        return f"That was {duration} ago."
+    else:
+        return f"That will be in {duration}."
+
+
+# ---------------------------------------------------------------------------
+# In-memory store  (no DB)
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# Help text
+# ---------------------------------------------------------------------------
+
+_HELP_TEXT = Group(
+    Bold("Buttons"),
+    Group(
+        Group(Bold("MAY"), " — tap the month name to switch to month picker"),
+        Group(Bold("2025"), " — tap the year to switch to year picker"),
+        Group(Bold("This month"), " — jump back to the current month"),
+        sep="\n",
+    ),
+    Bold("Keyboard input"),
+    Group(
+        "Type a date and send it as a message:",
+        Group(Code("YYYY"),        " — jump to that year"),
+        Group(Code("YYYY.MM"),     " — jump to that month"),
+        Group(Code("YYYY.MM.DD"),  " — select that date immediately"),
+        Quote("Separator: . or -", end=""),
+        sep="\n",
+    ),
+    Italic("Values outside the allowed range are silently ignored."),
+    sep="\n\n",
+)
+
+
+# ---------------------------------------------------------------------------
+# Handler
+# ---------------------------------------------------------------------------
+
+class CalendarHandler(
+    telekit.traits.CalendarPick,
+    telekit.Handler,
+):
+    @classmethod
+    def init_handler(cls) -> None:
+        cls.on.command("calendar").invoke(cls.handle)
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._date: datetime.date | None = None
+
+    # -----------------------------------------------------------------------
+    # Step 1 — welcome screen
+    # -----------------------------------------------------------------------
+
+    def handle(self) -> None:
+        """Entry point: welcome message with Help and Begin buttons side by side."""
+        self._date = None
+
+        self.chain.sender.set_title("📅 Event Distance")
+        self.chain.sender.set_message(
+            "Pick any date and find out how far it is from today — "
+            "whether it happened long ago or is still coming"
+        )
+        self.chain.set_inline_keyboard(
+            {
+                "？Help":  self.show_help,
+                "Begin »": self.entry_date,
+            },
+            row_width=2,
+        )
+        self.chain.edit()
+
+    # -----------------------------------------------------------------------
+    # Help screen
+    # -----------------------------------------------------------------------
+
+    def show_help(self) -> None:
+        """Show calendar navigation tips; a Back button returns to the welcome screen."""
+        self.chain.sender.set_title("📖 How to use the calendar")
+        self.chain.sender.set_message(_HELP_TEXT)
+        self.chain.set_inline_keyboard({"✓ Okay": self.handle}, row_width=1)
+        self.chain.edit()
+
+    # -----------------------------------------------------------------------
+    # Step 2 — calendar
+    # -----------------------------------------------------------------------
+
+    def entry_date(self) -> None:
+        """
+        Open the calendar picker.
+
+        Restores the previously chosen date as the initial view so the user
+        lands on a familiar position when changing their answer.
+        """
+        self.chain.sender.set_title("📅 Choose a date")
+        self.chain.sender.set_message("Select any date — past or future:")
+        self.chain.sender.set_remove_text(False)
+
+        self.calendar_pick(
+            self.handle_date,
+            initial=self._date,
+            show_nav_hints=True,
+        )
+
+    # -----------------------------------------------------------------------
+    # Step 3 — result
+    # -----------------------------------------------------------------------
+
+    def handle_date(self, date: datetime.date) -> None:
+        """
+        Display the distance result for *date*.
+
+        :param date: The date chosen by the user in the calendar.
+        """
+        self._date = date
+
+        self.chain.sender.set_title(f"🗓 {date.strftime('%d %B %Y')}")
+        self.chain.sender.set_message(
+            _describe(date)
+        )
+        # «Change reopens the calendar at the previously selected month.
+        self.chain.set_inline_keyboard(
+            {
+                "« Change":   self.entry_date,
+                "↺ New date": self.handle,
+            },
+            row_width=2,
+        )
+        self.chain.edit()

{telekit-2.3.0b2 → telekit-2.3.0b3}/telekit/example/example_handlers/start.py

@@ -30,7 +30,8 @@ class StartHandler(telekit.Handler):
                 "📄 File Info":     "TextDocumentHandler",
                 
                 "🖼️ QR Editor":               "QRHandler",
-            }, row_width=[3, 1, 3, 1]
+                "📆 Calendar":          "CalendarHandler",
+            }, row_width=[3, 1, 3, 2]
         )
         def handle_response(handler: str):
             self.handoff(handler).handle()

{telekit-2.3.0b2 → telekit-2.3.0b3}/telekit/senders.py

@@ -30,6 +30,7 @@ from telebot.types import (
     InputMediaVideo, InputMediaAnimation
 )
 
+from telekit.debug import Debug
 from telekit.styles import TextEntity, Escape, Raw, Group, Bold, Italic
 from telekit.types import ParseMode, Effect as _Effect, ChatAction as _ChatAction
 from telekit import dices
@@ -1143,7 +1144,8 @@ class BaseSender:
         try:
             return self.bot.delete_message(chat_id=self.chat_id, message_id=message_id)
         except Exception as exception:
-            library.warning(f"Failed to delete message {message_id}. Maybe the user deleted it. Exception: {exception}")
+            if Debug.deletion_warnings:
+                library.warning(f"Failed to delete message {message_id}. Maybe the user deleted it. Exception: {exception}")
             return False
         
     def delete_message(self, message: Message | None, only_user_messages: bool=False) -> bool:

{telekit-2.3.0b2 → telekit-2.3.0b3}/telekit/server.py

@@ -22,7 +22,7 @@ import traceback
 import sys
 from typing import Optional
 
-from . import _init, _state
+from . import _init, _state, debug as _debug
 import telebot
 
 from ._logger import logger
@@ -49,7 +49,7 @@ class Server:
     ):
         
         self._auto_restart = auto_restart
-        _state.TelekitState.DEBUG = debug
+        _debug.Debug.set_all(debug)
 
         if isinstance(bot, str):
             bot = telebot.TeleBot(bot)
@@ -133,6 +133,7 @@ class Server:
                     raise exception
             finally:
                 time.sleep(10)
+                _state.TelekitState._update()
 
     def long_polling(self, *, timeout: int = 60):
         """Long `bot.polling(none_stop=True, timeout=timeout)` polling with custom timeout"""
@@ -150,6 +151,7 @@ class Server:
                     raise exception
             finally:
                 time.sleep(5)
+                _state.TelekitState._update()
 
 
 # Example

telekit-2.3.0b3/telekit/traits/__init__.py

@@ -0,0 +1,3 @@
+from .track_handoff_origin import TrackHandoffOrigin
+from .paginated_choice import PaginatedChoice
+from .calendar_pick import CalendarPick