telekit 2.6.0a2__tar.gz → 2.6.0a3__tar.gz

{telekit-2.6.0a2 → telekit-2.6.0a3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.6.0a2
-Summary: Declarative, developer-friendly library for building Telegram bots
+Version: 2.6.0a3
+Summary: Declarative, developer-friendly framework for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
 Author-email: notromashka@gmail.com
@@ -20,7 +20,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: charset_normalizer==3.4.2
 Requires-Dist: Jinja2==3.1.6
-Requires-Dist: pyTelegramBotAPI==4.31.0
+Requires-Dist: pyTelegramBotAPI==4.37.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -471,7 +471,13 @@ Telekit focuses on one job: making Telegram bot development easier.
 
 ---
 
-# Changes in version 2.6.0a2
+# Changes in version 2.6.0a3
+
+### v2.6.0 `a3`
+- Added support for Rich HTML messages (Bot API 10.1+) and enhance styles
+    - Introduced a new module `_rich.py` to handle Rich HTML parsing and serialization.
+    - Updated `styles.py` to include new rich tags for enhanced text formatting.
+    - Created `rich.py` example handler to demonstrate the usage of Rich HTML features, including inline styles, blocks, lists, tables, media, and sender integration.
 
 ### v2.6.0 `a2`
 - Reworked `.env` and token/canvas file reading in `utils`: full `.env` syntax support (comments, `export`, quotes and escapes, multi-line values, `$VAR` interpolation), a `cache` parameter (default `True`) with `clear_cache()`, detailed errors with fix suggestions and creation commands, and new `Env*Error` exceptions; `load_env` now raises `EnvFileNotFoundError` for a missing file instead of returning `{}`

{telekit-2.6.0a2 → telekit-2.6.0a3}/setup.py

@@ -45,7 +45,7 @@ def long_description():
 setup(
     name='telekit',
     version=version,
-    description='Declarative, developer-friendly library for building Telegram bots',
+    description='Declarative, developer-friendly framework for building Telegram bots',
     long_description=long_description(),
     long_description_content_type='text/markdown',
     keywords='telegram bot api declarative tools bot-api',
@@ -70,4 +70,4 @@ setup(
     }
 )
 
-print(f"TELEKIT VERSION: {version}")
+print(f"TELEKIT VERSION: {version}")

{telekit-2.6.0a2 → telekit-2.6.0a3}/telekit/_buildtext/styles.py

@@ -18,6 +18,7 @@
 # 
 from typing import Union, Literal, TYPE_CHECKING, Union, Any
 from urllib.parse import quote
+import html as _html
 
 if TYPE_CHECKING: # Union[str, "TextEntity", "Template"]
     from string.templatelib import Template # pyright: ignore[reportMissingImports]
@@ -728,6 +729,459 @@ class Stack(TextEntity):
         return f"\n{content}{end}\n"
 
 
+
+# ---------------------------------------------------------------------------------
+# Rich HTML styles (Bot API 10.1+). Use together with sender.set_rich_html(True)
+# ---------------------------------------------------------------------------------
+
+def _attrs(**attrs) -> str:
+    """Builds an HTML attribute string. `True` -> bare attribute, None/False -> skipped."""
+    parts = []
+    for key, value in attrs.items():
+        if value is None or value is False:
+            continue
+        key = key.replace("_", "-")
+        if value is True:
+            parts.append(key)
+        else:
+            parts.append(f'{key}="{_html.escape(str(value), quote=True)}"')
+    return (" " + " ".join(parts)) if parts else ""
+
+
+class RichEntity(EasyTextEntity):
+    """
+    ⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Base class for styles that exist only in Rich HTML.
+    Outside of rich mode the sender downgrades these tags to plain formatting
+    (or drops them) and prints a warning.
+    """
+
+
+# -- inline
+
+class Marked(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Highlighted text: ``<mark>``."""
+    def _render_html(self, content: str) -> str:
+        return f"<mark>{content}</mark>"
+
+
+class Subscript(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Subscript: ``<sub>``."""
+    def _render_html(self, content: str) -> str:
+        return f"<sub>{content}</sub>"
+
+
+class Superscript(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Superscript: ``<sup>``."""
+    def _render_html(self, content: str) -> str:
+        return f"<sup>{content}</sup>"
+
+
+class CustomEmoji(EasyTextEntity):
+    """
+    Custom emoji: ``<tg-emoji emoji-id="...">fallback</tg-emoji>``.
+    Works both in regular HTML and in Rich HTML. The content is the fallback emoji.
+
+    Example::
+
+        CustomEmoji("👍", emoji_id=5368324170671202286)
+    """
+    def __init__(self, *content, emoji_id: int | str, escape: bool = True, sep: Union[str, "TextEntity", "Template"] = "", enabled: bool | Any = True):
+        self._emoji_id = emoji_id
+        super().__init__(*content, escape=escape, sep=sep, enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        return f"<tg-emoji{_attrs(emoji_id=self._emoji_id)}>{content}</tg-emoji>"
+
+
+class DateTime(RichEntity):
+    """
+    ⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Formatted date and time: ``<tg-time unix="..." format="...">``.
+
+    Example::
+
+        DateTime("22:45 tomorrow", unix=1647531900, format="wDT")
+    """
+    def __init__(self, *content, unix: int, format: str | None = None, escape: bool = True, sep: Union[str, "TextEntity", "Template"] = "", enabled: bool | Any = True):
+        self._unix = unix
+        self._format = format
+        super().__init__(*content, escape=escape, sep=sep, enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        return f"<tg-time{_attrs(unix=self._unix, format=self._format)}>{content}</tg-time>"
+
+
+class Math(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Inline LaTeX formula: ``<tg-math>``. The content is treated as raw LaTeX."""
+    def _render_html(self, content: str) -> str:
+        return f"<tg-math>{content}</tg-math>"
+
+
+class MathBlock(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Block LaTeX formula: ``<tg-math-block>``."""
+    def _render_html(self, content: str) -> str:
+        return f"<tg-math-block>{content}</tg-math-block>"
+
+
+class Anchor(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Anchor definition: ``<a name="..."></a>``. Target for ``AnchorLink``."""
+    def __init__(self, name: str, *, enabled: bool | Any = True):
+        self._name = name
+        super().__init__(enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        return f"<a{_attrs(name=self._name)}></a>"
+
+
+class AnchorLink(RichEntity):
+    """
+    ⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Link to an anchor or to a reference: ``<a href="#name">``.
+    An empty ``name`` links back to the top of the message.
+    """
+    def __init__(self, *content, name: str = "", escape: bool = True, sep: Union[str, "TextEntity", "Template"] = "", enabled: bool | Any = True):
+        self._name = name
+        super().__init__(*content, escape=escape, sep=sep, enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        return f"<a{_attrs(href='#' + self._name)}>{content}</a>"
+
+
+class Reference(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Footnote definition: ``<tg-reference name="...">``. Link to it with ``AnchorLink``."""
+    def __init__(self, *content, name: str, escape: bool = True, sep: Union[str, "TextEntity", "Template"] = "", enabled: bool | Any = True):
+        self._name = name
+        super().__init__(*content, escape=escape, sep=sep, enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        return f"<tg-reference{_attrs(name=self._name)}>{content}</tg-reference>"
+
+
+# -- text blocks
+
+class Heading(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Heading ``<h1>``..``<h6>``; ``level=1`` is the largest."""
+    def __init__(self, *content, level: int = 1, escape: bool = True, sep: Union[str, "TextEntity", "Template"] = "", enabled: bool | Any = True):
+        if not 1 <= level <= 6:
+            raise ValueError("Heading level must be between 1 and 6")
+        self._level = level
+        super().__init__(*content, escape=escape, sep=sep, enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        return f"<h{self._level}>{content}</h{self._level}>"
+
+    def _render_markdown(self, content: str) -> str:
+        return telebot.formatting.mbold(content, escape=False) + "\n"
+
+
+class Paragraph(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Paragraph: ``<p>``."""
+    def _render_html(self, content: str) -> str:
+        return f"<p>{content}</p>"
+
+
+class Footer(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Footer: ``<footer>``."""
+    def _render_html(self, content: str) -> str:
+        return f"<footer>{content}</footer>"
+
+
+class Divider(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Horizontal divider: ``<hr/>``."""
+    def __init__(self, *, enabled: bool | Any = True):
+        super().__init__(enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        return "<hr/>"
+
+    def _render_markdown(self, content: str) -> str:
+        return "———\n"
+
+    def _render_none(self, content: str) -> str:
+        return "———\n"
+
+
+class Cite(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Author/credit line: ``<cite>``. Use inside ``Quote`` or ``PullQuote``."""
+    def _render_html(self, content: str) -> str:
+        return f"<cite>{content}</cite>"
+
+
+class PullQuote(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Centered pull quotation: ``<aside>`` with an optional credit."""
+    def __init__(self, *content, credit: Union[str, "TextEntity", "Template", None] = None, escape: bool = True, sep: Union[str, "TextEntity", "Template"] = "", enabled: bool | Any = True):
+        self._credit = credit
+        super().__init__(*content, escape=escape, sep=sep, enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        credit = ""
+        if self._credit is not None:
+            credit = f"<cite>{self._render_item(self._credit, 'html')}</cite>"
+        return f"<aside>{content}{credit}</aside>"
+
+
+class Details(RichEntity):
+    """
+    ⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Collapsible block: ``<details><summary>``.
+
+    Example::
+
+        Details("Hidden text", summary="Click me", is_open=False)
+    """
+    def __init__(self, *content, summary: Union[str, "TextEntity", "Template"], is_open: bool = False, escape: bool = True, sep: Union[str, "TextEntity", "Template"] = "", enabled: bool | Any = True):
+        self._summary = summary
+        self._is_open = is_open
+        super().__init__(*content, escape=escape, sep=sep, enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        summary = self._render_item(self._summary, "html")
+        return f"<details{_attrs(open=self._is_open)}><summary>{summary}</summary>{content}</details>"
+
+
+# -- lists
+
+class ListItem(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    List item ``<li>`` with optional explicit ``value`` and ``type`` (ordered lists)."""
+    def __init__(self, *content, value: int | None = None, type: str | None = None, escape: bool = True, sep: Union[str, "TextEntity", "Template"] = "", enabled: bool | Any = True):
+        self._value = value
+        self._type = type
+        super().__init__(*content, escape=escape, sep=sep, enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        return f"<li{_attrs(value=self._value, type=self._type)}>{content}</li>"
+
+
+class _RichList(RichEntity):
+    _ordered = False
+
+    def _render_content(self, parse_mode):
+        if parse_mode == "html":
+            return "".join(
+                self._render_item(item, parse_mode) if isinstance(item, ListItem)
+                else f"<li>{self._render_item(item, parse_mode)}</li>"
+                for item in self._content
+            )
+        lines = []
+        for index, item in enumerate(self._content, start=1):
+            marker = f"{index}. " if self._ordered else "• "
+            lines.append(self._escape(marker, parse_mode) + self._render_item(item, parse_mode))
+        return "\n".join(lines)
+
+
+class UnorderedList(_RichList):
+    """
+    ⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Bulleted list: ``<ul>``. Items are strings/entities or ``ListItem``.
+
+    Example::
+
+        UnorderedList("One", Bold("Two"), ListItem("Three"))
+    """
+    def _render_html(self, content: str) -> str:
+        return f"<ul>{content}</ul>"
+
+
+class OrderedList(_RichList):
+    """
+    ⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Numbered list: ``<ol>``.
+
+    :param start: First number.
+    :param type: ``"1"``, ``"a"``, ``"A"``, ``"i"`` or ``"I"``.
+    :param reversed: Count backwards.
+    """
+    _ordered = True
+
+    def __init__(self, *items, start: int | None = None, type: str | None = None, reversed: bool = False, escape: bool = True, enabled: bool | Any = True):
+        self._start = start
+        self._type = type
+        self._reversed = reversed
+        super().__init__(*items, escape=escape, enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        attrs = _attrs(start=self._start, type=self._type, reversed=self._reversed)
+        return f"<ol{attrs}>{content}</ol>"
+
+
+# -- tables
+
+class TableCell(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Table cell ``<td>`` / ``<th>`` (``header=True``). Cells may contain only inline formatting."""
+    def __init__(self, *content, header: bool = False, colspan: int | None = None, rowspan: int | None = None, align: Literal["left", "center", "right"] | None = None, valign: Literal["top", "middle", "bottom"] | None = None, escape: bool = True, sep: Union[str, "TextEntity", "Template"] = "", enabled: bool | Any = True):
+        self._header = header
+        self._span = {"colspan": colspan, "rowspan": rowspan, "align": align, "valign": valign}
+        super().__init__(*content, escape=escape, sep=sep, enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        tag = "th" if self._header else "td"
+        return f"<{tag}{_attrs(**self._span)}>{content}</{tag}>"
+
+
+class Table(RichEntity):
+    """
+    ⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Table: ``<table>``. Each row is a list/tuple of cells (strings, entities or ``TableCell``).
+
+    :param header: Render the first row as header cells.
+
+    Example::
+
+        Table(["Name", "Score"], ["Ann", "10"], ["Bob", "7"], header=True, bordered=True)
+    """
+    def __init__(self, *rows, header: bool = False, bordered: bool = False, striped: bool = False, caption: Union[str, "TextEntity", "Template", None] = None, escape: bool = True, enabled: bool | Any = True):
+        self._header = header
+        self._bordered = bordered
+        self._striped = striped
+        self._caption = caption
+        super().__init__(*rows, escape=escape, enabled=enabled)
+
+    def _render_content(self, parse_mode):
+        is_html = parse_mode == "html"
+        lines = []
+
+        if self._caption is not None:
+            caption = self._render_item(self._caption, parse_mode)
+            lines.append(f"<caption>{caption}</caption>" if is_html else caption)
+
+        for row_index, row in enumerate(self._content):
+            cells = []
+            for cell in row:
+                rendered = self._render_item(cell, parse_mode)
+                if is_html and not isinstance(cell, TableCell):
+                    tag = "th" if (self._header and row_index == 0) else "td"
+                    rendered = f"<{tag}>{rendered}</{tag}>"
+                cells.append(rendered)
+
+            if is_html:
+                lines.append("<tr>" + "".join(cells) + "</tr>")
+            else:
+                lines.append(self._escape(" | ", parse_mode).join(cells))
+
+        return ("" if is_html else "\n").join(lines)
+
+    def _render_html(self, content: str) -> str:
+        return f"<table{_attrs(bordered=self._bordered, striped=self._striped)}>{content}</table>"
+
+
+# -- media (http/https URLs only)
+
+class _RichMedia(RichEntity):
+    def __init__(self, url: str, *, caption: Union[str, "TextEntity", "Template", None] = None, credit: Union[str, "TextEntity", "Template", None] = None, spoiler: bool = False, enabled: bool | Any = True):
+        self._url = url
+        self._caption = caption
+        self._credit = credit
+        self._spoiler = spoiler
+        super().__init__(enabled=enabled)
+
+    def _media(self) -> str:
+        raise NotImplementedError
+
+    def _render_html(self, content: str) -> str:
+        media = self._media()
+        if self._caption is None and self._credit is None:
+            return media
+
+        caption = self._render_item(self._caption, "html") if self._caption is not None else ""
+        credit = f"<cite>{self._render_item(self._credit, 'html')}</cite>" if self._credit is not None else ""
+        return f"<figure>{media}<figcaption>{caption}{credit}</figcaption></figure>"
+
+    def _media_attrs(self) -> str:
+        return _attrs(src=self._url, **{"tg-spoiler": self._spoiler})
+
+
+class Image(_RichMedia):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Photo block: ``<img>``; with ``caption``/``credit`` it is wrapped into ``<figure>``."""
+    def _media(self) -> str:
+        return f"<img{self._media_attrs()}/>"
+
+
+class Video(_RichMedia):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Video block: ``<video>``."""
+    def _media(self) -> str:
+        return f"<video{self._media_attrs()}></video>"
+
+
+class Audio(_RichMedia):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Audio block: ``<audio>`` (.ogg is shown as a voice note)."""
+    def _media(self) -> str:
+        return f"<audio{self._media_attrs()}></audio>"
+
+
+class Map(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Map block: ``<tg-map>``. ``zoom`` must be 13–20."""
+    def __init__(self, lat: float, long: float, *, zoom: int = 15, enabled: bool | Any = True):
+        if not 13 <= zoom <= 20:
+            raise ValueError("Map zoom must be between 13 and 20")
+        self._lat, self._long, self._zoom = lat, long, zoom
+        super().__init__(enabled=enabled)
+
+    def _render_html(self, content: str) -> str:
+        return f"<tg-map{_attrs(lat=self._lat, long=self._long, zoom=self._zoom)}/>"
+
+
+class Collage(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Collage of media blocks: ``<tg-collage>``. Pass ``Image``/``Video`` entities."""
+    def _render_html(self, content: str) -> str:
+        return f"<tg-collage>{content}</tg-collage>"
+
+
+class Slideshow(RichEntity):
+    """⚠️ Works only in Rich mode (``sender.set_rich_html(True)``).
+
+    Slideshow of media blocks: ``<tg-slideshow>``."""
+    def _render_html(self, content: str) -> str:
+        return f"<tg-slideshow>{content}</tg-slideshow>"
+
+
 class Styles:
     """
     Namespace for message formatting styles:
@@ -757,4 +1211,33 @@ class Styles:
     Mention: type[TextEntity] = Mention
     UserLink: type[TextEntity] = UserLink
     BotLink: type[TextEntity] = BotLink
-    Group: type[TextEntity] = Group
+    Group: type[TextEntity] = Group
+    # Rich HTML
+    Marked: type[TextEntity] = Marked
+    Subscript: type[TextEntity] = Subscript
+    Superscript: type[TextEntity] = Superscript
+    CustomEmoji: type[TextEntity] = CustomEmoji
+    DateTime: type[TextEntity] = DateTime
+    Math: type[TextEntity] = Math
+    MathBlock: type[TextEntity] = MathBlock
+    Anchor: type[TextEntity] = Anchor
+    AnchorLink: type[TextEntity] = AnchorLink
+    Reference: type[TextEntity] = Reference
+    Heading: type[TextEntity] = Heading
+    Paragraph: type[TextEntity] = Paragraph
+    Footer: type[TextEntity] = Footer
+    Divider: type[TextEntity] = Divider
+    Cite: type[TextEntity] = Cite
+    PullQuote: type[TextEntity] = PullQuote
+    Details: type[TextEntity] = Details
+    ListItem: type[TextEntity] = ListItem
+    UnorderedList: type[TextEntity] = UnorderedList
+    OrderedList: type[TextEntity] = OrderedList
+    Table: type[TextEntity] = Table
+    TableCell: type[TextEntity] = TableCell
+    Image: type[TextEntity] = Image
+    Video: type[TextEntity] = Video
+    Audio: type[TextEntity] = Audio
+    Map: type[TextEntity] = Map
+    Collage: type[TextEntity] = Collage
+    Slideshow: type[TextEntity] = Slideshow

{telekit-2.6.0a2 → telekit-2.6.0a3}/telekit/_chain_inline_keyboards_logic.py

@@ -111,7 +111,7 @@ class ChainInlineKeyboardLogic(ChainBase):
                 )
 
         markup = InlineKeyboardMarkup()
-        markup.keyboard = self._build_keyboard_rows(buttons, row_width)
+        markup.inline_keyboard = self._build_keyboard_rows(buttons, row_width)
 
         self.sender.set_reply_markup(markup)
         self._handler.set_button_callbacks(button_callbacks)
@@ -173,7 +173,7 @@ class ChainInlineKeyboardLogic(ChainBase):
                     )
 
             markup = InlineKeyboardMarkup()
-            markup.keyboard = self._build_keyboard_rows(buttons, row_width)
+            markup.inline_keyboard = self._build_keyboard_rows(buttons, row_width)
 
             self.sender.set_reply_markup(markup)
             self._handler.set_button_callbacks(callback_functions)
@@ -281,7 +281,7 @@ class ChainInlineKeyboardLogic(ChainBase):
                 )
 
         markup = InlineKeyboardMarkup()
-        markup.keyboard = self._build_keyboard_rows(buttons, row_width)
+        markup.inline_keyboard = self._build_keyboard_rows(buttons, row_width)
 
         self.sender.set_reply_markup(markup)
         self._handler.set_button_callbacks(callback_functions)
@@ -333,7 +333,7 @@ class ChainInlineKeyboardLogic(ChainBase):
                 buttons.append(InlineButton.Suggest(suggestion)._compile(caption))
 
         markup = InlineKeyboardMarkup()
-        markup.keyboard = self._build_keyboard_rows(buttons, row_width)
+        markup.inline_keyboard = self._build_keyboard_rows(buttons, row_width)
 
         self.sender.set_reply_markup(markup)