tdelegram 0.1.0__py3-none-any.whl

tdelegram/__init__.py

@@ -0,0 +1,42 @@
+"""TDelegram: a full-featured Telegram client library + CLI backed by TDLib."""
+
+from importlib import metadata as _metadata
+
+from tdelegram.client import TelegramClient
+from tdelegram.config import ClientConfig
+from tdelegram.errors import (
+    AuthError,
+    FloodWait,
+    InvalidRequest,
+    NotFoundError,
+    TelegramError,
+    TelegramPermissionError,
+    TransportError,
+)
+
+__all__ = [
+    "TelegramClient",
+    "ClientConfig",
+    "TelegramError",
+    "AuthError",
+    "TelegramPermissionError",
+    "NotFoundError",
+    "InvalidRequest",
+    "FloodWait",
+    "TransportError",
+]
+
+
+def _installed_version() -> str:
+    # pyproject.toml is the only place the version is written. A second copy
+    # here had to be bumped by hand and nothing checked that it was, so a
+    # release that bumped only pyproject.toml would have reported the version
+    # before it. Reinstall after a bump for a dev checkout to see it.
+    try:
+        return _metadata.version("tdelegram")
+    except _metadata.PackageNotFoundError:
+        # Imported from a source tree that was never installed.
+        return "0+unknown"
+
+
+__version__ = _installed_version()

tdelegram/api/__init__.py

@@ -0,0 +1,47 @@
+"""Domain APIs over TelegramClient."""
+
+from tdelegram.api import (
+    account,
+    admin,
+    bots,
+    chats,
+    contacts,
+    drafts,
+    export,
+    folders,
+    inbox,
+    media,
+    messages,
+    polls,
+    proxies,
+    reactions,
+    search,
+    secret,
+    stories,
+    topics,
+    updates,
+    users,
+)
+
+__all__ = [
+    "account",
+    "admin",
+    "bots",
+    "chats",
+    "contacts",
+    "drafts",
+    "export",
+    "folders",
+    "inbox",
+    "media",
+    "messages",
+    "polls",
+    "proxies",
+    "reactions",
+    "search",
+    "secret",
+    "stories",
+    "topics",
+    "updates",
+    "users",
+]

tdelegram/api/account.py

@@ -0,0 +1,69 @@
+"""Account: info, profile, privacy, sessions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tdelegram.client import TelegramClient
+
+
+def info(client: TelegramClient) -> dict[str, Any]:
+    return client.call("getMe", {})
+
+
+def full_info(client: TelegramClient, user_id: int) -> dict[str, Any]:
+    return client.call("getUserFullInfo", {"user_id": user_id})
+
+
+def set_profile(
+    client: TelegramClient,
+    *,
+    first_name: str | None = None,
+    last_name: str | None = None,
+    bio: str | None = None,
+    allow_write: bool = False,
+) -> dict[str, Any]:
+    results: dict[str, Any] = {}
+    if first_name is not None or last_name is not None:
+        results["name"] = client.call(
+            "setName",
+            {"first_name": first_name or "", "last_name": last_name or ""},
+            allow_write=allow_write,
+        )
+    if bio is not None:
+        results["bio"] = client.call("setBio", {"bio": bio}, allow_write=allow_write)
+    return results or {"@type": "ok"}
+
+
+def sessions(client: TelegramClient) -> dict[str, Any]:
+    return client.call("getActiveSessions", {})
+
+
+def terminate_session(
+    client: TelegramClient,
+    session_id: int,
+    *,
+    allow_write: bool = False,
+    allow_destructive: bool = False,
+) -> dict[str, Any]:
+    return client.call(
+        "terminateSession",
+        {"session_id": session_id},
+        allow_write=allow_write,
+        allow_destructive=allow_destructive,
+    )
+
+
+def terminate_others(
+    client: TelegramClient, *, allow_write: bool = False, allow_destructive: bool = False
+) -> dict[str, Any]:
+    return client.call(
+        "terminateAllOtherSessions",
+        {},
+        allow_write=allow_write,
+        allow_destructive=allow_destructive,
+    )
+
+
+def privacy(client: TelegramClient, setting: str) -> dict[str, Any]:
+    return client.call("getUserPrivacySettingRules", {"setting": {"@type": setting}})

tdelegram/api/admin.py

@@ -0,0 +1,225 @@
+"""Admin: promote/demote/ban/restrict/permissions/slowmode/invites."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from tdelegram.api.chats import resolve, resolve_id
+from tdelegram.client import TelegramClient
+
+# The least an administrator can hold, and what `promote` grants unless told
+# otherwise: every other right implies it.
+DEFAULT_RIGHTS = ("manage_chat",)
+
+
+def administrator_rights(rights: Iterable[str]) -> dict[str, Any]:
+    """chatAdministratorRights granting exactly `rights`, and nothing else.
+
+    Names are the schema's fields with or without the `can_` prefix, so
+    `delete_messages` and `can_delete_messages` both work; `is_anonymous` is
+    taken as it is.
+    """
+    from tdelegram import schema
+
+    entry = schema.constructor("chatAdministratorRights")
+    known = list(entry["fields"]) if entry else []
+    granted: dict[str, Any] = {"@type": "chatAdministratorRights"}
+    for right in rights:
+        name = right.strip().lower().replace("-", "_")
+        field = name if name in known else f"can_{name}"
+        if field not in known:
+            short = ", ".join(k.removeprefix("can_") for k in known)
+            raise ValueError(f"Unknown administrator right {right!r}; choose from: {short}.")
+        granted[field] = True
+    return granted
+
+
+def _set_status(
+    client: TelegramClient,
+    chat_id: int,
+    user_id: int,
+    status: dict[str, Any],
+    *,
+    allow_write: bool,
+    allow_destructive: bool,
+) -> dict[str, Any]:
+    return client.call(
+        "setChatMemberStatus",
+        {
+            "chat_id": chat_id,
+            "member_id": {"@type": "messageSenderUser", "user_id": user_id},
+            "status": status,
+        },
+        allow_write=allow_write,
+        allow_destructive=allow_destructive,
+    )
+
+
+def set_member_status(
+    client: TelegramClient,
+    chat_ref: str,
+    user_id: int,
+    status: dict[str, Any],
+    *,
+    allow_write: bool = False,
+    allow_destructive: bool = False,
+) -> dict[str, Any]:
+    """Set a member's status. Can ban, so it is gated like banChatMember."""
+    return _set_status(
+        client,
+        resolve_id(client, chat_ref),
+        user_id,
+        status,
+        allow_write=allow_write,
+        allow_destructive=allow_destructive,
+    )
+
+
+def promote(
+    client: TelegramClient,
+    chat_ref: str,
+    user_id: int,
+    *,
+    rights: Iterable[str] = DEFAULT_RIGHTS,
+    title: str = "",
+    allow_write: bool = False,
+    allow_destructive: bool = False,
+) -> dict[str, Any]:
+    """Make a member an administrator with exactly `rights`.
+
+    The status used to carry `custom_title` and no `rights`, neither of which
+    TDLib's administrator status takes any more, so the promotion granted
+    nothing. A title is now the member's tag, set by a second call -- which
+    channels do not have, so a title there is refused before anything changes
+    rather than failing after the promotion went through.
+    """
+    chat = resolve(client, chat_ref)
+    if title and (chat.get("type") or {}).get("is_channel"):
+        raise ValueError("Channels have no member titles; promote without --title.")
+    chat_id = int(chat["id"])
+    result = _set_status(
+        client,
+        chat_id,
+        user_id,
+        {"@type": "chatMemberStatusAdministrator", "rights": administrator_rights(rights)},
+        allow_write=allow_write,
+        allow_destructive=allow_destructive,
+    )
+    if title:
+        client.call(
+            "setChatMemberTag",
+            {"chat_id": chat_id, "user_id": user_id, "tag": title},
+            allow_write=allow_write,
+        )
+    return result
+
+
+def demote(
+    client: TelegramClient,
+    chat_ref: str,
+    user_id: int,
+    *,
+    allow_write: bool = False,
+    allow_destructive: bool = False,
+) -> dict[str, Any]:
+    return set_member_status(
+        client,
+        chat_ref,
+        user_id,
+        {"@type": "chatMemberStatusMember"},
+        allow_write=allow_write,
+        allow_destructive=allow_destructive,
+    )
+
+
+def ban(
+    client: TelegramClient,
+    chat_ref: str,
+    user_id: int,
+    *,
+    until: int = 0,
+    allow_write: bool = False,
+    allow_destructive: bool = False,
+) -> dict[str, Any]:
+    return client.call(
+        "banChatMember",
+        {
+            "chat_id": resolve_id(client, chat_ref),
+            "member_id": {"@type": "messageSenderUser", "user_id": user_id},
+            "banned_until_date": until,
+        },
+        allow_write=allow_write,
+        allow_destructive=allow_destructive,
+    )
+
+
+def restrict(
+    client: TelegramClient,
+    chat_ref: str,
+    user_id: int,
+    *,
+    permissions: dict[str, Any] | None = None,
+    allow_write: bool = False,
+    allow_destructive: bool = False,
+) -> dict[str, Any]:
+    return set_member_status(
+        client,
+        chat_ref,
+        user_id,
+        {
+            "@type": "chatMemberStatusRestricted",
+            "permissions": permissions
+            or {"@type": "chatPermissions", "can_send_basic_messages": False},
+            "is_member": True,
+        },
+        allow_write=allow_write,
+        allow_destructive=allow_destructive,
+    )
+
+
+def unrestrict(
+    client: TelegramClient,
+    chat_ref: str,
+    user_id: int,
+    *,
+    allow_write: bool = False,
+    allow_destructive: bool = False,
+) -> dict[str, Any]:
+    return demote(
+        client, chat_ref, user_id, allow_write=allow_write, allow_destructive=allow_destructive
+    )
+
+
+def slowmode(
+    client: TelegramClient, chat_ref: str, delay_seconds: int, *, allow_write: bool = False
+) -> dict[str, Any]:
+    return client.call(
+        "setChatSlowModeDelay",
+        {"chat_id": resolve_id(client, chat_ref), "slow_mode_delay": delay_seconds},
+        allow_write=allow_write,
+    )
+
+
+def create_invite(
+    client: TelegramClient, chat_ref: str, *, allow_write: bool = False
+) -> dict[str, Any]:
+    return client.call(
+        "createChatInviteLink", {"chat_id": resolve_id(client, chat_ref)}, allow_write=allow_write
+    )
+
+
+def revoke_invite(
+    client: TelegramClient,
+    chat_ref: str,
+    invite_link: str,
+    *,
+    allow_write: bool = False,
+    allow_destructive: bool = False,
+) -> dict[str, Any]:
+    return client.call(
+        "revokeChatInviteLink",
+        {"chat_id": resolve_id(client, chat_ref), "invite_link": invite_link},
+        allow_write=allow_write,
+        allow_destructive=allow_destructive,
+    )

tdelegram/api/bots.py

@@ -0,0 +1,134 @@
+"""Bots: inline queries, inline results, callback answers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tdelegram.api.chats import resolve_id
+from tdelegram.client import TelegramClient
+
+
+def start_bot(
+    client: TelegramClient,
+    bot_ref: str,
+    chat_ref: str,
+    *,
+    parameter: str = "",
+    allow_write: bool = False,
+) -> dict[str, Any]:
+    bot_id = resolve_id(client, bot_ref)
+    chat_id = resolve_id(client, chat_ref)
+    return client.call(
+        "sendBotStartMessage",
+        {"bot_user_id": bot_id, "chat_id": chat_id, "parameter": parameter},
+        allow_write=allow_write,
+    )
+
+
+def inline_results(
+    client: TelegramClient,
+    bot_user_id: int,
+    query: str,
+    *,
+    offset: str = "",
+    allow_write: bool = False,
+) -> dict[str, Any]:
+    """Send an inline query to a bot. The bot is notified, so this is a write."""
+    return client.call(
+        "getInlineQueryResults",
+        {"bot_user_id": bot_user_id, "chat_id": 0, "query": query, "offset": offset},
+        allow_write=allow_write,
+    )
+
+
+def send_inline_result(
+    client: TelegramClient,
+    chat_ref: str,
+    query_id: int | str,
+    result_id: str,
+    *,
+    allow_write: bool = False,
+) -> dict[str, Any]:
+    """Send one result of an inline query. `query_id` comes from inline_results()."""
+    return client.call(
+        "sendInlineQueryResultMessage",
+        {"chat_id": resolve_id(client, chat_ref), "query_id": query_id, "result_id": result_id},
+        allow_write=allow_write,
+    )
+
+
+def press_button(
+    client: TelegramClient,
+    chat_ref: str,
+    message_id: int,
+    label: str,
+    *,
+    allow_write: bool = False,
+) -> dict[str, Any]:
+    """Press the inline button labelled `label` under a bot's message.
+
+    The bot sees the press and acts on it, which is why getCallbackQueryAnswer
+    is a write. A URL button has nothing to press, so its link comes back
+    instead; a button that needs a password, a game or a payment is refused.
+    """
+    chat_id = resolve_id(client, chat_ref)
+    message = client.call("getMessage", {"chat_id": chat_id, "message_id": message_id})
+    markup = message.get("reply_markup") or {}
+    rows = markup.get("rows") if markup.get("@type") == "replyMarkupInlineKeyboard" else None
+    buttons = [button for row in rows or [] for button in row or []]
+    chosen = [b for b in buttons if b.get("text") == label] or [
+        b for b in buttons if str(b.get("text", "")).casefold() == label.casefold()
+    ]
+    if not chosen:
+        offered = ", ".join(repr(b.get("text")) for b in buttons) or "none"
+        raise ValueError(f"Message {message_id} has no button {label!r}; its buttons: {offered}.")
+    kind = chosen[0].get("type") or {}
+    found = {"chat_id": chat_id, "message_id": message_id, "button": chosen[0].get("text")}
+    if kind.get("@type") == "inlineKeyboardButtonTypeUrl":
+        return {**found, "pressed": False, "url": kind.get("url")}
+    if kind.get("@type") != "inlineKeyboardButtonTypeCallback":
+        raise ValueError(f"{label!r} is a {kind.get('@type')} button, which only an app can use.")
+    answer = client.call(
+        "getCallbackQueryAnswer",
+        {
+            "chat_id": chat_id,
+            "message_id": message_id,
+            "payload": {"@type": "callbackQueryPayloadData", "data": kind.get("data", "")},
+        },
+        allow_write=allow_write,
+    )
+    return {
+        **found,
+        "pressed": True,
+        "answer": answer.get("text") or None,
+        "show_alert": bool(answer.get("show_alert")),
+        "url": answer.get("url") or None,
+    }
+
+
+def answer_callback(
+    client: TelegramClient, query_id: int, *, text: str = "", allow_write: bool = False
+) -> dict[str, Any]:
+    """For bot accounts only: a user account cannot answer callback queries."""
+    return client.call(
+        "answerCallbackQuery",
+        {"callback_query_id": query_id, "text": text},
+        allow_write=allow_write,
+    )
+
+
+def answer_inline(
+    client: TelegramClient,
+    inline_query_id: int,
+    results: list[dict[str, Any]],
+    *,
+    allow_write: bool = False,
+) -> dict[str, Any]:
+    return client.call(
+        "answerInlineQuery",
+        {"inline_query_id": inline_query_id, "results": results},
+        allow_write=allow_write,
+    )
+
+
+# -- stories ----------------------------------------------------------