nextgram 0.9.0__py3-none-any.whl

nextgram/__init__.py

@@ -0,0 +1,34 @@
+"""nextgram: Telegram Bot API 10.3 rich messages and Bot API 10.4 HTML
+widgets, across six frameworks.
+
+Pyrogram, Pyrofork and Kurigram are one family (three distributions of
+the same ``pyrogram`` package name) and get full native support here, in
+``nextgram.rich_ui`` — importing ``nextgram`` itself needs none of them
+installed. Telethon, aiogram and python-telegram-bot are each supported
+through their own optional module, imported explicitly so a bot using
+only one framework never has to install the others:
+
+- ``nextgram.telethon`` — ``from nextgram import telethon``
+- ``nextgram.aiogram_rich`` — ``from nextgram import aiogram_rich``
+- ``nextgram.ptb_rich`` — ``from nextgram import ptb_rich``
+
+``nextgram.widgets`` (Bot API 10.4 widgets) is framework-agnostic by
+construction — it only ever needs a bot token — so every function in it
+already works the same from all six frameworks without a separate module
+per framework; see its own docstring.
+
+The content builders (``rich_heading``, ``rich_list``, ``rich_button``,
+``rich_table``, ...) are plain string functions with no framework
+dependency at all — the same HTML works everywhere; only how it gets
+*sent* differs per framework, which is what the modules above are for.
+"""
+
+from . import rich_ui
+from .rich_ui import *
+from .rich_ui import __all__ as _rich_all
+from . import widgets
+from .widgets import *
+from .widgets import __all__ as _widgets_all
+
+__version__ = "0.9.0"
+__all__ = list(_rich_all) + list(_widgets_all) + ["rich_ui", "widgets", "__version__"]

nextgram/aiogram_rich.py

@@ -0,0 +1,123 @@
+"""nextgram.aiogram_rich: rich messages and widgets for aiogram bots.
+
+aiogram is optional — importing ``nextgram`` never requires it, and this
+module has no import-time dependency on the ``aiogram`` package itself
+(it only reads a few attributes off whatever ``Bot``/``Message`` objects
+are passed in). Rich-message sending goes over the plain Bot HTTP API via
+``nextgram.http_rich`` (see that module's docstring for exactly what is
+confirmed vs. speculative); widgets go over the same HTTP API via
+``nextgram.widgets``, which already works with any client exposing a
+``.token`` attribute — aiogram's ``Bot`` does.
+"""
+from __future__ import annotations
+
+import logging
+
+from .http_rich import coerce_markup_to_dict, edit_rich_html_via_http, send_rich_html_via_http
+
+logger = logging.getLogger("nextgram.aiogram_rich")
+
+__all__ = [
+    "aiogram_bot_token",
+    "aiogram_rich_send",
+    "aiogram_rich_reply",
+    "aiogram_rich_edit",
+]
+
+
+def aiogram_bot_token(bot) -> str:
+    """Pull the bot token off an aiogram ``Bot`` instance."""
+    token = getattr(bot, "token", None)
+    if not token:
+        raise RuntimeError(
+            "aiogram_bot_token needs a Bot instance with a .token attribute"
+        )
+    return token
+
+
+async def aiogram_rich_send(
+    bot,
+    chat_id,
+    html_text: str,
+    *,
+    markdown: bool = False,
+    reply_markup=None,
+    reply_to_message_id=None,
+    message_thread_id=None,
+    disable_notification=None,
+    protect_content=None,
+):
+    """Send rich HTML/Markdown to ``chat_id`` with an aiogram ``Bot``.
+
+    ``reply_markup`` accepts an aiogram ``InlineKeyboardMarkup`` (or any
+    object with ``.model_dump``/``.to_dict``) as well as a plain dict.
+    Returns the Bot API ``result`` dict (not an aiogram ``Message``) —
+    use ``result["message_id"]`` for the sent message's id.
+    """
+    token = aiogram_bot_token(bot)
+    reply_parameters = (
+        {"message_id": reply_to_message_id} if reply_to_message_id else None
+    )
+    return await send_rich_html_via_http(
+        token,
+        chat_id,
+        html_text,
+        markdown=markdown,
+        reply_markup=coerce_markup_to_dict(reply_markup),
+        reply_parameters=reply_parameters,
+        message_thread_id=message_thread_id,
+        disable_notification=disable_notification,
+        protect_content=protect_content,
+    )
+
+
+async def aiogram_rich_reply(message, html_text: str, *, bot=None, **kwargs):
+    """Reply to an aiogram ``Message`` with rich HTML/Markdown.
+
+    ``bot`` defaults to ``message.bot`` (aiogram sets this on every
+    incoming message/update automatically).
+    """
+    app = bot or getattr(message, "bot", None)
+    chat = getattr(getattr(message, "chat", None), "id", None)
+    if app is None or chat is None:
+        logger.debug("[aiogram_rich_reply] missing bot/chat on message")
+        return None
+    return await aiogram_rich_send(
+        app, chat, html_text, reply_to_message_id=getattr(message, "message_id", None), **kwargs
+    )
+
+
+async def aiogram_rich_edit(
+    message,
+    html_text: str,
+    *,
+    bot=None,
+    chat_id=None,
+    message_id=None,
+    markdown: bool = False,
+    reply_markup=None,
+):
+    """Edit a message to rich HTML/Markdown with an aiogram ``Bot``.
+
+    ``message`` is an aiogram ``Message`` (``.chat.id``/``.message_id``
+    read automatically) or ``None``, in which case ``chat_id`` and
+    ``message_id`` are required.
+    """
+    if message is not None:
+        app = bot or getattr(message, "bot", None)
+        chat_id = getattr(getattr(message, "chat", None), "id", None)
+        message_id = getattr(message, "message_id", None)
+    else:
+        app = bot
+    if app is None or chat_id is None or message_id is None:
+        logger.debug("[aiogram_rich_edit] missing bot/chat_id/message_id")
+        return None
+    token = aiogram_bot_token(app)
+    return await edit_rich_html_via_http(
+        token,
+        chat_id,
+        message_id,
+        html_text,
+        markdown=markdown,
+        reply_markup=coerce_markup_to_dict(reply_markup),
+    )

nextgram/http_rich.py

@@ -0,0 +1,190 @@
+"""nextgram.http_rich: raw Bot HTTP API rich-message sending.
+
+aiogram and python-telegram-bot have no MTProto layer at all — just a bot
+token and the plain Bot HTTP API — so ``nextgram.aiogram_rich`` and
+``nextgram.ptb_rich`` both build on this module instead of
+``nextgram.rich_ui``'s Pyrogram-native path. Sending calls the same
+``sendRichMessage`` HTTP endpoint ``nextgram.rich_ui._send_blocks_via_http``
+already uses for typed blocks, this time with a plain ``{"html": ...}``
+payload (the HTTP shape of ``InputRichMessage(html=...)``) instead of
+``blocks``. This is a real, already-used endpoint, not a new guess.
+
+Editing is less certain: there is no documented standalone
+``editRichMessage`` HTTP method, only Pyrogram's native, MTProto-level
+``edit_message_text(..., rich_message=...)``. :func:`edit_rich_html_via_http`
+tries the same ``rich_message`` field on the plain HTTP ``editMessageText``
+call — speculative, since it has never been confirmed against a live bot —
+and falls back to a plain-HTML edit on any failure, exactly as the send
+side falls back when ``sendRichMessage`` is rejected or unavailable.
+
+Buttons built with ``rich_button()``/``rich_button_row()`` are embedded
+*inside* the rich HTML and only become clickable when the rich payload is
+actually accepted and rendered that way by the Telegram client — if a send
+or edit falls back to plain HTML, those buttons degrade to plain text
+labels (via ``rich_ui._plain_fallback``), exactly as they do on the
+Pyrogram path when ``RICH_AVAILABLE`` is ``False``.
+"""
+from __future__ import annotations
+
+import logging
+
+from .rich_ui import _has_rich_only_tags, _normalize_html, _only_set, _plain_fallback
+from .widgets import WidgetAPIError, _call_bot_api
+
+logger = logging.getLogger("nextgram.http_rich")
+
+__all__ = ["send_rich_html_via_http", "edit_rich_html_via_http", "coerce_markup_to_dict"]
+
+
+def coerce_markup_to_dict(reply_markup):
+    """Turn a framework-native keyboard object into a plain JSON-able dict.
+
+    ``None``/dict pass through unchanged. aiogram v3's Pydantic models use
+    ``.model_dump(mode="json", exclude_none=True)``; python-telegram-bot's
+    use ``.to_dict()``; both are tried, in that order, before giving up and
+    returning the object as-is (letting the eventual JSON encode fail
+    loudly rather than silently dropping the keyboard).
+    """
+    if reply_markup is None or isinstance(reply_markup, dict):
+        return reply_markup
+    for method_name, kwargs in (
+        ("model_dump", {"mode": "json", "exclude_none": True}),
+        ("to_dict", {}),
+    ):
+        method = getattr(reply_markup, method_name, None)
+        if callable(method):
+            try:
+                return method(**kwargs)
+            except TypeError:
+                try:
+                    return method()
+                except Exception:
+                    continue
+            except Exception:
+                continue
+    return reply_markup
+
+
+async def send_rich_html_via_http(
+    token,
+    chat_id,
+    html_text: str,
+    *,
+    markdown: bool = False,
+    reply_markup: dict = None,
+    reply_parameters: dict = None,
+    message_thread_id=None,
+    disable_notification=None,
+    protect_content=None,
+    api_base=None,
+):
+    """POST ``sendRichMessage``, falling back to plain ``sendMessage``.
+
+    ``reply_markup``/``reply_parameters`` are plain JSON-able dicts (the
+    Bot API wire shape) — a caller holding a framework-native keyboard
+    object converts it first (aiogram: ``.model_dump(mode="json",
+    exclude_none=True)``; python-telegram-bot: ``.to_dict()``).
+
+    Returns the Bot API ``result`` dict (with ``message_id``) from
+    whichever call succeeds, or ``None`` if both fail.
+    """
+    if not html_text:
+        return None
+    wants_rich = bool(markdown or _has_rich_only_tags(html_text))
+    rich_message = (
+        {"markdown": html_text} if markdown else {"html": _normalize_html(html_text)}
+    )
+    shared = _only_set(
+        reply_markup=reply_markup,
+        reply_parameters=reply_parameters,
+        message_thread_id=message_thread_id,
+        disable_notification=disable_notification,
+        protect_content=protect_content,
+    )
+    if wants_rich:
+        try:
+            return await _call_bot_api(
+                None,
+                "sendRichMessage",
+                {"chat_id": chat_id, "rich_message": rich_message, **shared},
+                token=token,
+                api_base=api_base,
+            )
+        except WidgetAPIError as e:
+            logger.debug(f"[send_rich_html_via_http] rich send rejected, falling back: {e}")
+        except Exception as e:
+            logger.debug(f"[send_rich_html_via_http] rich send failed, falling back: {e}")
+
+    try:
+        return await _call_bot_api(
+            None,
+            "sendMessage",
+            {
+                "chat_id": chat_id,
+                "text": html_text if markdown else _plain_fallback(html_text),
+                "parse_mode": "Markdown" if markdown else "HTML",
+                **shared,
+            },
+            token=token,
+            api_base=api_base,
+        )
+    except Exception as e:
+        logger.debug(f"[send_rich_html_via_http] plain send failed: {e}")
+        return None
+
+
+async def edit_rich_html_via_http(
+    token,
+    chat_id,
+    message_id,
+    html_text: str,
+    *,
+    markdown: bool = False,
+    reply_markup: dict = None,
+    api_base=None,
+):
+    """POST ``editMessageText``, optimistically with ``rich_message`` set
+    first (see the module docstring: unconfirmed, may always fall
+    through), then a plain edit if that is rejected or fails outright.
+    """
+    if not html_text:
+        return None
+    wants_rich = bool(markdown or _has_rich_only_tags(html_text))
+    rich_message = (
+        {"markdown": html_text} if markdown else {"html": _normalize_html(html_text)}
+    )
+    shared = _only_set(reply_markup=reply_markup)
+    if wants_rich:
+        try:
+            return await _call_bot_api(
+                None,
+                "editMessageText",
+                {
+                    "chat_id": chat_id,
+                    "message_id": message_id,
+                    "rich_message": rich_message,
+                    **shared,
+                },
+                token=token,
+                api_base=api_base,
+            )
+        except Exception as e:
+            logger.debug(f"[edit_rich_html_via_http] rich edit rejected, falling back: {e}")
+
+    try:
+        return await _call_bot_api(
+            None,
+            "editMessageText",
+            {
+                "chat_id": chat_id,
+                "message_id": message_id,
+                "text": html_text if markdown else _plain_fallback(html_text),
+                "parse_mode": "Markdown" if markdown else "HTML",
+                **shared,
+            },
+            token=token,
+            api_base=api_base,
+        )
+    except Exception as e:
+        logger.debug(f"[edit_rich_html_via_http] plain edit failed: {e}")
+        return None

nextgram/ptb_rich.py

@@ -0,0 +1,137 @@
+"""nextgram.ptb_rich: rich messages and widgets for python-telegram-bot bots.
+
+python-telegram-bot is optional — importing ``nextgram`` never requires
+it, and this module has no import-time dependency on the ``telegram``
+package itself (it only reads a few attributes off whatever ``Bot``/
+``Message`` objects are passed in). Rich-message sending goes over the
+plain Bot HTTP API via ``nextgram.http_rich`` (see that module's docstring
+for exactly what is confirmed vs. speculative); widgets go over the same
+HTTP API via ``nextgram.widgets``, which already works with any client
+exposing a ``.token`` attribute — python-telegram-bot's ``Bot`` does.
+"""
+from __future__ import annotations
+
+import logging
+
+from .http_rich import coerce_markup_to_dict, edit_rich_html_via_http, send_rich_html_via_http
+
+logger = logging.getLogger("nextgram.ptb_rich")
+
+__all__ = [
+    "ptb_bot_token",
+    "ptb_rich_send",
+    "ptb_rich_reply",
+    "ptb_rich_edit",
+]
+
+
+def ptb_bot_token(bot) -> str:
+    """Pull the bot token off a python-telegram-bot ``Bot`` instance."""
+    token = getattr(bot, "token", None)
+    if not token:
+        raise RuntimeError(
+            "ptb_bot_token needs a Bot instance with a .token attribute"
+        )
+    return token
+
+
+async def ptb_rich_send(
+    bot,
+    chat_id,
+    html_text: str,
+    *,
+    markdown: bool = False,
+    reply_markup=None,
+    reply_to_message_id=None,
+    message_thread_id=None,
+    disable_notification=None,
+    protect_content=None,
+):
+    """Send rich HTML/Markdown to ``chat_id`` with a python-telegram-bot
+    ``Bot`` (or ``Bot``-like object — ``context.bot`` works the same way).
+
+    ``reply_markup`` accepts a python-telegram-bot ``InlineKeyboardMarkup``
+    (or any object with ``.to_dict``) as well as a plain dict. Returns the
+    Bot API ``result`` dict (not a ``telegram.Message``) — use
+    ``result["message_id"]`` for the sent message's id.
+    """
+    token = ptb_bot_token(bot)
+    reply_parameters = (
+        {"message_id": reply_to_message_id} if reply_to_message_id else None
+    )
+    return await send_rich_html_via_http(
+        token,
+        chat_id,
+        html_text,
+        markdown=markdown,
+        reply_markup=coerce_markup_to_dict(reply_markup),
+        reply_parameters=reply_parameters,
+        message_thread_id=message_thread_id,
+        disable_notification=disable_notification,
+        protect_content=protect_content,
+    )
+
+
+async def ptb_rich_reply(message, html_text: str, *, bot=None, **kwargs):
+    """Reply to a python-telegram-bot ``Message``/``Update`` with rich
+    HTML/Markdown.
+
+    Accepts either a ``telegram.Message`` or a ``telegram.Update`` (its
+    ``.effective_message`` is used). ``bot`` defaults to
+    ``message.get_bot()`` when the object exposes that (python-telegram-bot
+    messages do).
+    """
+    target = getattr(message, "effective_message", None) or message
+    app = bot
+    if app is None:
+        get_bot = getattr(target, "get_bot", None)
+        app = get_bot() if callable(get_bot) else getattr(target, "_bot", None)
+    chat = getattr(getattr(target, "chat", None), "id", None) or getattr(
+        target, "chat_id", None
+    )
+    if app is None or chat is None:
+        logger.debug("[ptb_rich_reply] missing bot/chat on message")
+        return None
+    return await ptb_rich_send(
+        app, chat, html_text, reply_to_message_id=getattr(target, "message_id", None), **kwargs
+    )
+
+
+async def ptb_rich_edit(
+    message,
+    html_text: str,
+    *,
+    bot=None,
+    chat_id=None,
+    message_id=None,
+    markdown: bool = False,
+    reply_markup=None,
+):
+    """Edit a message to rich HTML/Markdown with a python-telegram-bot
+    ``Bot``.
+
+    ``message`` is a ``telegram.Message`` (``.chat_id``/``.message_id``
+    read automatically) or ``None``, in which case ``chat_id`` and
+    ``message_id`` are required.
+    """
+    if message is not None:
+        if bot is None:
+            get_bot = getattr(message, "get_bot", None)
+            bot = get_bot() if callable(get_bot) else getattr(message, "_bot", None)
+        chat_id = getattr(getattr(message, "chat", None), "id", None) or getattr(
+            message, "chat_id", None
+        )
+        message_id = getattr(message, "message_id", None)
+    app = bot
+    if app is None or chat_id is None or message_id is None:
+        logger.debug("[ptb_rich_edit] missing bot/chat_id/message_id")
+        return None
+    token = ptb_bot_token(app)
+    return await edit_rich_html_via_http(
+        token,
+        chat_id,
+        message_id,
+        html_text,
+        markdown=markdown,
+        reply_markup=coerce_markup_to_dict(reply_markup),
+    )