xtr-telegram-notifier 5.0.0__py3-none-any.whl

xtr_telegram_notifier/.agents/skills/xtr-telegram-notifier/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: xtr-telegram-notifier
+description: How to send chat messages to Telegram with xtr-telegram-notifier, the Telegram provider of xtr-notifier — a telegram DSN served with no wiring, TelegramOptions for keyboards, photos and other media, file uploads, locations, venues, contacts, editing a sent message and answering a callback query, with MarkdownV2 escaping. Use when an application must notify a Telegram chat or channel through a bot, configure TELEGRAM_DSN, build Telegram message options or reply keyboards, upload a file to a chat, edit or answer a Telegram message, or test code that sends to Telegram.
+---
+
+# xtr-telegram-notifier
+
+The Telegram provider of xtr-notifier. Installed beside it, a `telegram://` DSN is served by
+`TelegramTransportFactory`, found through its entry point. For notifications, channels and the
+bundle, load the `xtr-notifier` skill.
+
+## Quick reference
+
+- DSN — `telegram://BOT_ID:SECRET@default?channel=CHAT_ID`; `default` is `api.telegram.org`;
+  `ssl=false` (or `sslmode=disable`) for plain HTTP. No token: `Missing token.`; half: `Malformed token.`
+- `TelegramTransport(token, channel, http_client, event_dispatcher=None)`; its string form never
+  shows the token.
+- `TelegramOptions()` — fluent builder; `.to_options()` renders the `MessageOptions` a
+  `ChatMessage` carries. `chat_id(...)` wins over the DSN's channel.
+- One kind per message: `photo`, `video`, `audio`, `document`, `animation`, `sticker`,
+  `location`, `venue`, `contact`, `edit`, `answer_callback_query` — two raise
+  `MultipleExclusiveOptionsUsedError`.
+- Text is MarkdownV2 by default, escaped (markup kept); `parse_mode(TelegramOptions.PARSE_MODE_HTML)`
+  sends it as written.
+- Keyboards — `xtr_telegram_notifier.reply.markup`: `InlineKeyboardMarkup`,
+  `ReplyKeyboardMarkup`, `ReplyKeyboardRemove`, `ForceReply`; buttons in `.button`:
+  `InlineKeyboardButton`, `KeyboardButton`.
+
+## Send a message with a keyboard
+
+```python
+from xtr_notifier.message import ChatMessage
+from xtr_telegram_notifier import TelegramOptions
+from xtr_telegram_notifier.reply.markup import InlineKeyboardMarkup
+from xtr_telegram_notifier.reply.markup.button import InlineKeyboardButton
+
+options = TelegramOptions().reply_markup(
+    InlineKeyboardMarkup().inline_keyboard(
+        [InlineKeyboardButton("Approve").callback_data("approve:42")]
+    )
+)
+await chatter.send(ChatMessage("Deploy *42* is waiting.", options.to_options()))
+```
+
+## Send media, a place or a contact
+
+```python
+TelegramOptions().photo("https://example.com/chart.png")  # the text is the caption
+TelegramOptions().upload_document("/var/reports/daily.pdf")  # opened, sent and closed at send
+TelegramOptions().location(48.8566, 2.3522)  # the text is not sent
+TelegramOptions().contact("+33100000000", "Ops", "Team")
+```
+
+An upload keeps its path, so the message can be queued; the transport sends the fields as a
+form body the HTTP client turns into `multipart/form-data`.
+
+## Edit or answer
+
+```python
+TelegramOptions().edit(message_id)  # editMessageText
+TelegramOptions().edit(message_id).photo("https://example.com/new.png")  # editMessageMedia
+TelegramOptions().edit_caption(message_id)  # editMessageCaption
+TelegramOptions().answer_callback_query(query_id, show_alert=True, cache_time=5)
+```
+
+`SentMessage.message_id` is the id the bot API gave the message, as text — keep it to edit it.
+
+## Testing
+
+```python
+from xtr_http_client import JsonMockResponse, MockHttpClient
+from xtr_notifier.message import ChatMessage
+from xtr_telegram_notifier import TelegramTransport
+
+
+def answer(method, url, options):
+    assert url == "https://api.telegram.org/bot1:T/sendMessage"
+    assert options["json"] == {"chat_id": "ops", "text": "Hi", "parse_mode": "MarkdownV2"}
+    return JsonMockResponse({"ok": True, "result": {"message_id": 7}})
+
+
+sent = await TelegramTransport("1:T", "ops", MockHttpClient(answer)).send(ChatMessage("Hi"))
+assert sent.message_id == "7"
+```
+
+An upload reaches the script as an open file under `options["body"]`.
+
+## Use in an application
+
+`uv run xtr-recipes recipes:sync` applies the recipe: it writes `TELEGRAM_DSN` in `.env` and
+prints the configuration step.
+
+1. **Install** — `uv add xtr-telegram-notifier`, beside xtr-notifier set up as the
+   `xtr-notifier` skill says.
+2. **Configure** — add `telegram=env("TELEGRAM_DSN")` to `chatter_transports` in
+   `<app>/config/notifier.py`.
+3. **Environment** — `TELEGRAM_DSN`, `telegram://TOKEN@default?channel=CHAT_ID`.
+4. **Check** — `debug:config notifier` lists `telegram` under `chatter_transports`.
+5. **Remove** — drop the entry and `TELEGRAM_DSN`, then `uv remove xtr-telegram-notifier`.
+
+There is no bundle to activate.
+
+## Errors
+
+| Error | When |
+|---|---|
+| `IncompleteDsnError` | `Missing token.` / `Malformed token.` |
+| `MultipleExclusiveOptionsUsedError` | Two kinds of message picked at once |
+| `LogicError` | Editing a media with a file to upload — use a URL or a file id |
+| `TransportError` | `Unable to post the Telegram message: <description> (code <n>).` (or `edit`, `answer callback query`); `Could not reach the remote Telegram server.` |
+| `UnsupportedMessageTypeError` | A message that is not a `ChatMessage` |
+
+## Do not
+
+- Do not write the bot token into code or configuration; read the DSN with `env("TELEGRAM_DSN")`.
+- Do not pass open files in options; use the `upload_*` methods, which keep a path.
+- Do not escape MarkdownV2 yourself; the transport does, and keeps what is already escaped.
+- Do not combine `edit` with an `upload_*` media; the bot API refuses it.

xtr_telegram_notifier/__init__.py

@@ -0,0 +1,15 @@
+"""Telegram for xtr-notifier: chat messages sent, edited and answered through a bot.
+
+Install it beside xtr-notifier and a ``telegram://BOT_ID:TOKEN@default?channel=CHAT_ID``
+DSN is served by :class:`TelegramTransportFactory` with no wiring. Build a message's
+options with :class:`TelegramOptions` — keyboards from :mod:`.reply.markup`, media, an
+edit of an earlier message, a callback query's answer.
+"""
+
+from __future__ import annotations
+
+from .telegram_options import TelegramOptions
+from .telegram_transport import TelegramTransport
+from .telegram_transport_factory import TelegramTransportFactory
+
+__all__ = ["TelegramOptions", "TelegramTransport", "TelegramTransportFactory"]

xtr_telegram_notifier/_markdown_v2.py

@@ -0,0 +1,24 @@
+"""Escaping a message for the MarkdownV2 parse mode."""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+__all__ = ["escape_markdown_v2"]
+
+# Matched in order: an already escaped character, kept; a spoiler marker, kept; a block
+# quotation (">" or "**>" opening a line), kept; a custom emoji ("!["), kept; and a reserved
+# character outside of those, the one group captured and escaped.
+_RESERVED: Final = re.compile(r"\\[\x01-\x7E]|\|\||^(?:\*\*)?>|!\[|([.!#+\-=|{}>])", re.MULTILINE)
+
+
+def escape_markdown_v2(text: str) -> str:
+    """Escape the characters the bot API rejects unescaped, leaving the markup alone.
+
+    Paired markers (``*bold*``, ``_italic_``, `` `code` ``, ``~strike~``,
+    ``||spoiler||``, ``[link](url)``), block quotations and custom emojis are
+    kept, so a message written in MarkdownV2 is sent as written, while a plain
+    sentence ending in ``.`` or ``!`` is no longer refused.
+    """
+    return _RESERVED.sub(lambda match: match[0] if match[1] is None else f"\\{match[1]}", text)

xtr_telegram_notifier/_payload.py

@@ -0,0 +1,186 @@
+"""Turning a message's options into the bot API method and the fields it is called with.
+
+Every function reads or returns the fields as a plain mapping. What a message
+is follows from which field is set: ``photo`` makes it ``sendPhoto``,
+``message_id`` makes it an edit, and so on down :data:`EXCLUSIVE_OPTIONS`.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from io import IOBase
+from typing import Final, cast
+
+from xtr_notifier.exception import LogicError, MultipleExclusiveOptionsUsedError
+
+__all__ = [
+    "EXCLUSIVE_OPTIONS",
+    "action_for",
+    "build_input_media",
+    "ensure_exclusive_options",
+    "expand_options",
+    "form_fields",
+    "method_for",
+    "non_empty",
+    "text_option_for",
+]
+
+#: The options that each pick what a message is; only one of them may be set.
+EXCLUSIVE_OPTIONS: Final = (
+    "message_id",
+    "callback_query_id",
+    "photo",
+    "location",
+    "audio",
+    "document",
+    "video",
+    "animation",
+    "venue",
+    "contact",
+    "sticker",
+)
+
+_MEDIA_TYPES: Final = ("photo", "video", "document", "audio", "animation")
+_SPOILER_MEDIA_TYPES: Final = ("photo", "video", "animation")
+# Checked in this order: the first one set names the method.
+_SEND_METHODS: Final = (
+    ("photo", "sendPhoto"),
+    ("location", "sendLocation"),
+    ("audio", "sendAudio"),
+    ("document", "sendDocument"),
+    ("video", "sendVideo"),
+    ("animation", "sendAnimation"),
+    ("venue", "sendVenue"),
+    ("contact", "sendContact"),
+    ("sticker", "sendSticker"),
+)
+# Checked in this order: the option a message's text goes in, None when it is not sent.
+_TEXT_OPTIONS: Final = (
+    ("edit_caption", "caption"),
+    ("photo", "caption"),
+    ("audio", "caption"),
+    ("document", "caption"),
+    ("video", "caption"),
+    ("animation", "caption"),
+    ("sticker", None),
+    ("location", None),
+    ("venue", None),
+    ("contact", None),
+)
+
+
+def _is_set(options: Mapping[str, object], key: str) -> bool:
+    """Tell whether ``key`` is set to something other than ``None``."""
+    return options.get(key) is not None
+
+
+def method_for(options: Mapping[str, object]) -> str:
+    """Return the bot API method a message with ``options`` is sent with."""
+    if _is_set(options, "message_id"):
+        return _edit_method_for(options)
+    if _is_set(options, "callback_query_id"):
+        return "answerCallbackQuery"
+    return next(
+        (method for option, method in _SEND_METHODS if _is_set(options, option)), "sendMessage"
+    )
+
+
+def _edit_method_for(options: Mapping[str, object]) -> str:
+    """Return the edit method: the media, the caption, or the text."""
+    if any(_is_set(options, media_type) for media_type in _MEDIA_TYPES):
+        return "editMessageMedia"
+    return "editMessageCaption" if _is_set(options, "edit_caption") else "editMessageText"
+
+
+def action_for(options: Mapping[str, object]) -> str:
+    """Return what sending ``options`` does, as an error message names it."""
+    if _is_set(options, "message_id"):
+        return "edit"
+    if _is_set(options, "callback_query_id"):
+        return "answer callback query"
+    return "post"
+
+
+def text_option_for(options: Mapping[str, object]) -> str | None:
+    """Return the field a message's text goes in, or ``None`` when its kind sends no text."""
+    return next(
+        (text_option for option, text_option in _TEXT_OPTIONS if _is_set(options, option)),
+        "text",
+    )
+
+
+def ensure_exclusive_options(options: Mapping[str, object]) -> None:
+    """Refuse options that pick more than one kind of message.
+
+    Editing a message replaces its media, so ``message_id`` goes with one media type.
+
+    Raises:
+        MultipleExclusiveOptionsUsedError: When more than one is set.
+    """
+    used = [key for key in options if key in EXCLUSIVE_OPTIONS]
+    if "message_id" in options and sum(key in _MEDIA_TYPES for key in options) == 1:
+        used.remove("message_id")
+    if len(used) > 1:
+        raise MultipleExclusiveOptionsUsedError(used, EXCLUSIVE_OPTIONS)
+
+
+def build_input_media(options: Mapping[str, object], text: str) -> dict[str, object]:
+    """Move the media of an edit, with its caption, parse mode and spoiler, into ``media``.
+
+    Raises:
+        LogicError: When the media is a file being uploaded: the bot API takes an
+            edit's new media as a URL or a file id only.
+    """
+    built = dict(options)
+    media_type = next((kind for kind in _MEDIA_TYPES if _is_set(built, kind)), None)
+    if media_type is None:
+        return built
+    if isinstance(built[media_type], IOBase):
+        raise LogicError(
+            "Editing a message with a locally uploaded media is not supported yet, "
+            "use a URL or a Telegram file ID instead."
+        )
+    media: dict[str, object] = {"type": media_type, "media": built[media_type], "caption": text}
+    if _is_set(built, "parse_mode"):
+        media["parse_mode"] = built["parse_mode"]
+    if _is_set(built, "has_spoiler") and media_type in _SPOILER_MEDIA_TYPES:
+        media["has_spoiler"] = built["has_spoiler"]
+    for key in (media_type, "caption", "parse_mode", "has_spoiler"):
+        _ = built.pop(key, None)
+    built["media"] = media
+    return built
+
+
+def expand_options(options: Mapping[str, object], *keys: str) -> dict[str, object]:
+    """Replace each of ``keys`` holding a mapping by that mapping's fields, at the top level."""
+    expanded = dict(options)
+    for key in keys:
+        if not _is_set(expanded, key):
+            continue
+        value = expanded[key]
+        if isinstance(value, Mapping):
+            expanded.update(cast("Mapping[str, object]", value))
+        del expanded[key]
+    return expanded
+
+
+def non_empty(options: Mapping[str, object]) -> dict[str, object]:
+    """Drop the fields left empty — ``None``, ``False``, ``0``, ``""``, an empty collection."""
+    return {key: value for key, value in options.items() if value}
+
+
+def form_fields(fields: Mapping[str, object]) -> dict[str, object]:
+    """Render ``fields`` for a multipart body: each nested value as JSON text.
+
+    A form part holds one scalar, so the bot API reads an object or a list sent
+    beside an upload — a reply markup, a media group — as JSON. Scalars and the
+    files are left as they are.
+    """
+    return {
+        key: json.dumps(value)
+        if isinstance(value, Mapping)
+        or (isinstance(value, Sequence) and not isinstance(value, (str, bytes)))
+        else value
+        for key, value in fields.items()
+    }

xtr_telegram_notifier/recipe/__init__.py

@@ -0,0 +1,15 @@
+"""This directory holds the package's recipe: its manifest.
+
+The recipe is what *Use in an application* in the README lists, written as
+data: the DSN to set, and the step adding the transport to the notifier's
+configuration, which a recipe prints rather than makes. An application
+applies it with ``xtr-recipes recipes:sync``, which finds this module through
+the ``xtr_recipes`` entry point.
+
+Nothing is importable from here. The manifest is read as a file, so a recipe
+is the same from a wheel as from a working tree.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_telegram_notifier/recipe/manifest.toml

@@ -0,0 +1,23 @@
+# The recipe for xtr-telegram-notifier: what *Use in an application* in the README takes,
+# as data. Keep the two in step — the README is the source.
+#
+# No [bundles] and no [files]: the package ships no bundle — the notifier's discovers its
+# factory by the DSN scheme — and the notifier's configuration module is the application's.
+
+[env]
+# The bot's DSN. TOKEN is the token the bot API hands out, BOT_ID:SECRET; CHAT_ID is the chat
+# a message naming none goes to.
+TELEGRAM_DSN = "telegram://TOKEN@default?channel=CHAT_ID"
+
+[gitignore]
+# Nothing of its own: a message is sent, never written to disk.
+lines = []
+
+[notes]
+steps = [
+  "Set TELEGRAM_DSN to the bot's DSN: telegram://BOT_ID:SECRET@default?channel=CHAT_ID.",
+  "Add the transport to chatter_transports in config/notifier.py: telegram=env(\"TELEGRAM_DSN\").",
+]
+check = [
+  "<script> debug:config notifier — telegram is listed under chatter_transports",
+]

xtr_telegram_notifier/reply/__init__.py

@@ -0,0 +1,5 @@
+"""Ways for a message to ask for an answer; the markups live in :mod:`.markup`."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_telegram_notifier/reply/markup/__init__.py

@@ -0,0 +1,17 @@
+"""What a message shows the user to reply with: keyboards, their removal, a forced reply."""
+
+from __future__ import annotations
+
+from .abstract_telegram_reply_markup import AbstractTelegramReplyMarkup
+from .force_reply import ForceReply
+from .inline_keyboard_markup import InlineKeyboardMarkup
+from .reply_keyboard_markup import ReplyKeyboardMarkup
+from .reply_keyboard_remove import ReplyKeyboardRemove
+
+__all__ = [
+    "AbstractTelegramReplyMarkup",
+    "ForceReply",
+    "InlineKeyboardMarkup",
+    "ReplyKeyboardMarkup",
+    "ReplyKeyboardRemove",
+]

xtr_telegram_notifier/reply/markup/abstract_telegram_reply_markup.py

@@ -0,0 +1,25 @@
+"""The base of every reply markup a message can carry."""
+
+from __future__ import annotations
+
+import copy
+from abc import ABC
+
+__all__ = ["AbstractTelegramReplyMarkup"]
+
+
+class AbstractTelegramReplyMarkup(ABC):  # noqa: B024 -- abstract by role: only its subclasses mean anything to the bot API
+    """What the chat shows under a message: a keyboard, its removal, or a forced reply.
+
+    A subclass fills :attr:`_options` with the bot API's fields;
+    :meth:`~xtr_telegram_notifier.TelegramOptions.reply_markup` renders it into
+    the message's options.
+    """
+
+    def __init__(self) -> None:
+        """Start with no field set."""
+        self._options: dict[str, object] = {}
+
+    def to_array(self) -> dict[str, object]:
+        """Render the markup as the bot API reads it — a copy, so it stays as it was."""
+        return copy.deepcopy(self._options)

xtr_telegram_notifier/reply/markup/button/__init__.py

@@ -0,0 +1,9 @@
+"""The buttons a keyboard is made of."""
+
+from __future__ import annotations
+
+from .abstract_keyboard_button import AbstractKeyboardButton
+from .inline_keyboard_button import InlineKeyboardButton
+from .keyboard_button import KeyboardButton
+
+__all__ = ["AbstractKeyboardButton", "InlineKeyboardButton", "KeyboardButton"]

xtr_telegram_notifier/reply/markup/button/abstract_keyboard_button.py

@@ -0,0 +1,23 @@
+"""The base of every keyboard button."""
+
+from __future__ import annotations
+
+import copy
+from abc import ABC
+
+__all__ = ["AbstractKeyboardButton"]
+
+
+class AbstractKeyboardButton(ABC):  # noqa: B024 -- abstract by role: only its subclasses mean anything to the bot API
+    """One button of a keyboard, rendered into the keyboard's rows.
+
+    A subclass fills :attr:`_options` with the bot API's fields.
+    """
+
+    def __init__(self) -> None:
+        """Start with no field set."""
+        self._options: dict[str, object] = {}
+
+    def to_array(self) -> dict[str, object]:
+        """Render the button as the bot API reads it — a copy, so it stays as it was."""
+        return copy.deepcopy(self._options)

xtr_telegram_notifier/reply/markup/button/inline_keyboard_button.py

@@ -0,0 +1,64 @@
+"""A button attached to a message."""
+
+from __future__ import annotations
+
+from typing import Self, final
+
+from .abstract_keyboard_button import AbstractKeyboardButton
+
+__all__ = ["InlineKeyboardButton"]
+
+
+@final
+class InlineKeyboardButton(AbstractKeyboardButton):
+    """A button under a message: it opens a link, logs in, calls the bot back, or pays.
+
+    The bot API wants exactly one action per button; which one is set is left
+    to the caller, as the API reports a button with none or several.
+    """
+
+    def __init__(self, text: str = "") -> None:
+        """Label the button ``text``."""
+        super().__init__()
+        self._options["text"] = text
+        self._login_url: dict[str, object] = {}
+
+    def url(self, url: str) -> Self:
+        """Open ``url`` when tapped."""
+        self._options["url"] = url
+        return self
+
+    def login_url(self, url: str) -> Self:
+        """Log the user in to ``url`` when tapped."""
+        self._login_option("url", url)
+        return self
+
+    def login_url_forward_text(self, text: str) -> Self:
+        """Label the button ``text`` in a forwarded copy of the message."""
+        self._login_option("forward_text", text)
+        return self
+
+    def request_write_access(self, request: bool) -> Self:
+        """Ask the user, on login, to let the bot message them."""
+        self._login_option("request_write_access", request)
+        return self
+
+    def callback_data(self, data: str) -> Self:
+        """Send ``data`` back to the bot as a callback query when tapped."""
+        self._options["callback_data"] = data
+        return self
+
+    def switch_inline_query(self, query: str) -> Self:
+        """Pick a chat and start an inline query for ``query`` in it when tapped."""
+        self._options["switch_inline_query"] = query
+        return self
+
+    def pay_button(self, pay: bool) -> Self:
+        """Make it the message's payment button."""
+        self._options["pay"] = pay
+        return self
+
+    def _login_option(self, key: str, value: object) -> None:
+        """Set one field of the login URL, placing the login URL where it was first set."""
+        self._login_url[key] = value
+        self._options["login_url"] = self._login_url

xtr_telegram_notifier/reply/markup/button/keyboard_button.py

@@ -0,0 +1,34 @@
+"""A button of a custom reply keyboard."""
+
+from __future__ import annotations
+
+from typing import Self, final
+
+from .abstract_keyboard_button import AbstractKeyboardButton
+
+__all__ = ["KeyboardButton"]
+
+
+@final
+class KeyboardButton(AbstractKeyboardButton):
+    """A reply button: tapped, it sends its text — or the user's contact, location or a poll."""
+
+    def __init__(self, text: str) -> None:
+        """Label the button ``text``, which is what a tap sends."""
+        super().__init__()
+        self._options["text"] = text
+
+    def request_contact(self, request: bool) -> Self:
+        """Send the user's phone contact when tapped."""
+        self._options["request_contact"] = request
+        return self
+
+    def request_location(self, request: bool) -> Self:
+        """Send the user's location when tapped."""
+        self._options["request_location"] = request
+        return self
+
+    def request_poll_type(self, poll_type: str) -> Self:
+        """Ask the user to create a poll of ``poll_type`` (``quiz`` or ``regular``) when tapped."""
+        self._options["request_poll"] = {"type": poll_type}
+        return self

xtr_telegram_notifier/reply/markup/force_reply.py

@@ -0,0 +1,26 @@
+"""Opening the reply box as if the user had chosen to reply."""
+
+from __future__ import annotations
+
+from typing import final
+
+from .abstract_telegram_reply_markup import AbstractTelegramReplyMarkup
+
+__all__ = ["ForceReply"]
+
+
+@final
+class ForceReply(AbstractTelegramReplyMarkup):
+    """Shows the user a reply box for this message, as if they had tapped *Reply*."""
+
+    def __init__(self, force_reply: bool = False, selective: bool = False) -> None:
+        """Force the reply, for everyone or only the users the message mentions.
+
+        Args:
+            force_reply: Whether the reply box is opened.
+            selective: Whether only the mentioned users, and the sender of the
+                message replied to, get it.
+        """
+        super().__init__()
+        self._options["force_reply"] = force_reply
+        self._options["selective"] = selective

xtr_telegram_notifier/reply/markup/inline_keyboard_markup.py

@@ -0,0 +1,30 @@
+"""Buttons shown right under a message."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Self, final
+
+from .abstract_telegram_reply_markup import AbstractTelegramReplyMarkup
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from .button.inline_keyboard_button import InlineKeyboardButton
+
+__all__ = ["InlineKeyboardMarkup"]
+
+
+@final
+class InlineKeyboardMarkup(AbstractTelegramReplyMarkup):
+    """Rows of buttons attached to the message itself: links, callbacks, payments."""
+
+    def __init__(self) -> None:
+        """Start with no row."""
+        super().__init__()
+        self._rows: list[list[dict[str, object]]] = []
+        self._options["inline_keyboard"] = self._rows
+
+    def inline_keyboard(self, buttons: Iterable[InlineKeyboardButton]) -> Self:
+        """Add a row of ``buttons`` below the rows added so far."""
+        self._rows.append([button.to_array() for button in buttons])
+        return self