illest 2.2.0__py3-none-any.whl

illest/__init__.py

@@ -0,0 +1,169 @@
+"""illest: the Python library for ILLEST, for bots and Rich Presence.
+
+    from illest.ext import commands
+
+    bot = commands.Bot(command_prefix="/", token="illb_...")
+
+    @bot.command(name="ping")
+    async def ping(ctx):
+        await ctx.reply("pong")
+
+    bot.run()
+
+## The everyday names
+
+`Client`, `Intents`, `Embed`, `ButtonStyle`, `ui.Button`, `ext.commands.Bot`,
+`Context`, `@bot.event`, `@bot.command()`, `ctx.send/reply`,
+`message.reply`, `embed=`, `view=`, `ephemeral=True`. Moving a bot written
+for another library: the migration guide on the developer site.
+
+## What is different, and why
+
+This network is end-to-end encrypted. The server stores ciphertext and holds
+no keys, so:
+
+* **A bot is a real device.** Its token ENROLs it; its device key (generated
+  once, kept under `~/.illest/bots/`) is what proves it at sign-in. Losing
+  that file is losing the device, which is losing history only it held.
+* **A bot joins groups like a member.** Invite it to your server; somebody's
+  client lets it into each channel's group. "Invited" and "able to read" are
+  different moments: usually seconds apart while it is online.
+* **A bot that was stopped catches up by itself.** While it is away its groups move on (members join and leave, keys are
+  replaced). When it starts, and when it signs in again after the server no longer held its session, it brings every group it
+  holds up to the server's epoch, a channel at a time and unhurried, before it handles anything; a channel it cannot catch up is
+  logged by its id and the rest go on. A message that arrives sealed at an epoch ahead of the bot's makes it catch that channel up
+  once and try the message again; if that fails too the message is dropped, and logged without its content. Messages sent while the
+  bot was away are not fetched: it reads what arrives while it is connected.
+* **Who sent it is what their device proves, not what the server says.** Every message and every button press carries
+  `author_id` (`sender_id` on an `Interaction`) from the server, and the library checks it against the sender's leaf in the group:
+  a frame that names an account other than the one the leaf proves is dropped. A sender whose leaf proves no account (a bot, or
+  a device with no certificate) is still delivered, but `Message.author_verified` (`Interaction.sender_verified`,
+  `Context.author_verified`) is False, and `author_id` is then only the server's word: do not authorise anything by it.
+* **An account is the key it first showed.** A certificate proves that some account key vouched for a device, and anybody can
+  make a key. So the library remembers the first key each account shows (in `pins.json`, in its state folder) and holds the
+  account to it: an invitation written by a device under another key is turned down, a member the server lists who lets
+  themselves in under another key is not taken in, and a message from a device under another key is delivered with
+  `author_verified` False and `author_key_changed` True. The change is said once in the log and to `on_key_change(user_id)`.
+  It happens when a person sets their account up again, and when somebody else writes as them: ask them another way, then call
+  `client.accept_key_change(user_id)`. An invitation is opened only from a device the channel lists.
+* **A button answers only to who could see it.** `@bot.on_button` runs only for a press on a message this bot sent, naming a
+  button that message carried and left enabled, from somebody who could see it (and, for a message meant for one reader, who is
+  proven to be that reader). The library remembers its buttons in its state folder, so they survive a restart.
+* **Ephemeral is a rendering rule.** `ephemeral=True` marks a message
+  visible only to its one reader on every client that honours the rule. It
+  is not cryptography against other members of the group (no such thing
+  exists inside an MLS group), and this library says so rather than implying
+  otherwise.
+"""
+
+from ._version import __version__
+from . import abc, app_commands, ui, utils
+from .activity import Activity, BaseActivity, CustomActivity, Game, Streaming
+from .attachment import AttachmentError
+from .client import Client
+from .colour import Color, Colour
+from .content import Button, ContentError
+from .embeds import Embed
+from .enums import *  # noqa: F401,F403
+from .enums import __all__ as _enums
+from .errors import (
+    AuthFailed,
+    BadRequest,
+    BotForbidden,
+    ClientException,
+    ConnectionClosed,
+    DiscordException,
+    DiscordServerError,
+    Forbidden,
+    GatewayError,
+    GatewayNotFound,
+    HTTPException,
+    IllestException,
+    InteractionResponded,
+    InvalidData,
+    LoginFailure,
+    MissingScope,
+    NotFound,
+    PrivilegedIntentsRequired,
+    RateLimited,
+    ServerError,
+    StaleEpoch,
+    UnknownAction,
+)
+from .file import File
+from .replies import AskReply
+from .ui.layout import MediaGalleryItem, SeparatorSpacing, UnfurledMediaItem
+from .intents import Intents
+from .interactions import Interaction, InteractionCallbackResponse, InteractionResponse, Webhook, WebhookMessage
+from .mentions import AllowedMentions
+from .models import *  # noqa: F401,F403
+from .models import __all__ as _models
+from .object import Object
+from .permissions import PermissionOverwrite, Permissions
+from .ui.select import SelectOption
+from .utils import setup_logging
+
+#: The scopes a bot token can hold, as the server names them (`actions::bots::SCOPES`).
+SCOPES = ("messages.read", "messages.write", "guilds.read", "members.read", "moderate", "guilds.manage")
+
+__all__ = [
+    "SCOPES",
+    "AllowedMentions",
+    "Activity",
+    "AttachmentError",
+    "AuthFailed",
+    "BadRequest",
+    "BaseActivity",
+    "BotForbidden",
+    "Button",
+    "Client",
+    "ClientException",
+    "Color",
+    "Colour",
+    "ConnectionClosed",
+    "ContentError",
+    "CustomActivity",
+    "DiscordException",
+    "DiscordServerError",
+    "AskReply",
+    "Embed",
+    "MediaGalleryItem",
+    "SeparatorSpacing",
+    "UnfurledMediaItem",
+    "File",
+    "Forbidden",
+    "Game",
+    "GatewayError",
+    "GatewayNotFound",
+    "HTTPException",
+    "IllestException",
+    "Intents",
+    "Interaction",
+    "InteractionCallbackResponse",
+    "InteractionResponded",
+    "InteractionResponse",
+    "InvalidData",
+    "LoginFailure",
+    "MissingScope",
+    "NotFound",
+    "Object",
+    "PermissionOverwrite",
+    "Permissions",
+    "SelectOption",
+    "PrivilegedIntentsRequired",
+    "RateLimited",
+    "ServerError",
+    "StaleEpoch",
+    "Streaming",
+    "UnknownAction",
+    "Webhook",
+    "WebhookMessage",
+    "__version__",
+    "abc",
+    "app_commands",
+    "setup_logging",
+    "ui",
+    "utils",
+    *_enums,
+    *_models,
+]

illest/_limits.py

@@ -0,0 +1,240 @@
+"""Every action's rate limit, as the server enforces it: generated by `scripts/gen_limits.py` from the server's action table.
+
+Do not edit by hand. Each entry is `(rate, burst)`: a bucket of `burst` requests per account, refilled at `rate` a second. An
+action not listed takes `DEFAULT`, which is also what the server gives an action registered without a limit of its own.
+"""
+
+DEFAULT: tuple[float, int] = (2.0, 10)
+
+LIMITS: dict[str, tuple[float, int]] = {
+    "account.credential.move.begin": (0.5, 3),
+    "account.credential.move.complete": (0.5, 3),
+    "account.delete": (0.2, 3),
+    "account.delete.begin": (0.2, 3),
+    "account.delete.complete": (0.2, 3),
+    "account.identity.unlock.begin": (0.2, 3),
+    "account.identity.unlock.complete": (0.2, 3),
+    "account.opaque.upgrade.begin": (0.5, 3),
+    "account.opaque.upgrade.complete": (0.5, 3),
+    "account.password.change": (0.5, 3),
+    "account.password.change.begin": (0.5, 3),
+    "account.password.change.complete": (0.5, 3),
+    "account.recovery.begin": (0.5, 3),
+    "account.recovery.complete": (0.5, 3),
+    "account.retention.set": (10.0, 60),
+    "account.step_up": (1.0, 5),
+    "admin.ban": (2.0, 10),
+    "admin.config": (4.0, 10),
+    "admin.config_set": (4.0, 10),
+    "admin.disconnect": (2.0, 10),
+    "admin.log": (2.0, 10),
+    "admin.role_set": (2.0, 10),
+    "admin.roster": (2.0, 10),
+    "admin.unban": (2.0, 10),
+    "auth.credential": (1.0, 10),
+    "auth.device.enroll": (0.2, 3),
+    "auth.device.enroll.verify": (0.2, 3),
+    "auth.login.begin": (1.0, 5),
+    "auth.login.complete": (1.0, 5),
+    "auth.login.verify": (1.0, 5),
+    "auth.recover.begin": (1.0, 5),
+    "auth.recover.complete": (0.5, 3),
+    "auth.recover.verify": (0.2, 3),
+    "auth.register.begin": (0.2, 3),
+    "auth.register.complete": (1.0, 5),
+    "auth.register.work": (0.5, 5),
+    "auth.reset.begin": (1.0, 5),
+    "auth.reset.complete": (0.2, 3),
+    "badge.elite": (4.0, 60),
+    "badge.grant": (4.0, 60),
+    "badge.revoke": (4.0, 60),
+    "bot.commands.get": (2.0, 20),
+    "bot.commands.set": (0.5, 5),
+    "bot.create": (0.5, 5),
+    "bot.delete": (1.0, 10),
+    "bot.identify": (1.0, 10),
+    "bot.identity.publish": (1.0, 5),
+    "bot.token.create": (1.0, 10),
+    "bot.update": (1.0, 10),
+    "channel.devices": (8.0, 40),
+    "channel.disappear.set": (10.0, 60),
+    "channel.dm.open": (1.0, 10),
+    "channel.get": (8.0, 40),
+    "channel.group.add": (10.0, 60),
+    "channel.group.create": (4.0, 60),
+    "channel.group.leave": (10.0, 60),
+    "channel.group.update": (10.0, 60),
+    "channel.messages.list": (8.0, 40),
+    "channel.messages.purge": (10.0, 30),
+    "channel.typing": (6.0, 10),
+    "friend.request": (0.5, 10),
+    "guild.application.submit": (1.0, 5),
+    "guild.audit": (4.0, 10),
+    "guild.create": (1.0, 30),
+    "guild.insights": (1.0, 5),
+    "guild.invite.create": (2.0, 20),
+    "guild.invite.preview": (3.0, 20),
+    "guild.join": (2.0, 30),
+    "guild.members": (3.0, 15),
+    "guild.onboarding.answer": (3.0, 20),
+    "guild.onboarding.preview": (3.0, 20),
+    "guild.onboarding.seen": (3.0, 20),
+    "guild.order.set": (1.0, 10),
+    "guild.overrides": (4.0, 10),
+    "guild.profile.get": (3.0, 15),
+    "guild.template.apply": (0.2, 2),
+    "guild.template.export": (1.0, 5),
+    "guild.vanity.check": (4.0, 30),
+    "guild.vanity.resolve": (3.0, 30),
+    "identity.certify": (1.0, 5),
+    "identity.publish": (1.0, 5),
+    "link.preview": (0.5, 10),
+    "links.add": (0.2, 6),
+    "links.mine": (2.0, 10),
+    "links.order": (1.0, 10),
+    "links.remove": (1.0, 10),
+    "links.services": (1.0, 5),
+    "links.update": (1.0, 10),
+    "links.verify": (0.1, 4),
+    "links.view": (2.0, 12),
+    "market.attach": (0.1, 6),
+    "market.attachment": (2.0, 20),
+    "market.browse": (2.0, 20),
+    "market.mine": (1.0, 10),
+    "market.name": (2.0, 20),
+    "market.status": (2.0, 20),
+    "market.voucher.convert": (0.05, 6),
+    "market.voucher.receive": (0.1, 10),
+    "market.voucher.recovery": (0.01, 3),
+    "market.wallet.unlink": (0.1, 6),
+    "media.ticket": (1.0, 10),
+    "message.pin": (10.0, 30),
+    "message.redact": (10.0, 30),
+    "message.send": (5.0, 20),
+    "message.unpin": (10.0, 30),
+    "mls.commit.submit": (5.0, 20),
+    "mls.commits.since": (12.0, 60),
+    "mls.grant.clear": (1.0, 5),
+    "mls.grant.issue": (5.0, 20),
+    "mls.grant.needed": (12.0, 60),
+    "mls.group.reset": (0.2, 2),
+    "mls.group_info.publish": (5.0, 20),
+    "mls.key_packages.claim": (6.0, 30),
+    "mls.key_packages.publish": (1.0, 5),
+    "mls.key_packages.purge": (1.0, 5),
+    "name.available": (2.0, 20),
+    "name.claim": (0.05, 4),
+    "name.keep": (0.1, 6),
+    "name.primary": (0.1, 6),
+    "name.release": (0.1, 6),
+    "name.resolve": (2.0, 20),
+    "names.list": (2.0, 20),
+    "page.create": (2.0, 20),
+    "page.preview": (1.0, 3),
+    "page.preview_inputs": (1.0, 3),
+    "page.publish": (3.0, 30),
+    "page.restore": (2.0, 20),
+    "page.save": (10.0, 20),
+    "page.stats": (1.0, 5),
+    "pins.get": (2.0, 20),
+    "pins.put": (0.5, 10),
+    "platform.account.find": (1.0, 8),
+    "platform.account.flag": (1.0, 6),
+    "platform.account.premium": (1.0, 6),
+    "platform.get": (2.0, 10),
+    "platform.market": (1.0, 6),
+    "platform.market.export": (0.5, 4),
+    "platform.market.keygen": (0.2, 6),
+    "platform.market.prepare": (0.5, 4),
+    "platform.market.refuse": (1.0, 6),
+    "platform.market.seen": (1.0, 6),
+    "platform.security": (1.0, 5),
+    "platform.set": (2.0, 14),
+    "platform.shop": (1.0, 6),
+    "platform.shop.allow": (0.5, 6),
+    "platform.shop.close": (0.5, 6),
+    "platform.shop.forbid": (0.5, 6),
+    "platform.shop.reopen": (0.5, 6),
+    "platform.shop.takedown": (0.5, 6),
+    "platform.test": (0.2, 3),
+    "presence.set": (1.0, 5),
+    "report.list": (1.0, 10),
+    "report.settle": (1.0, 10),
+    "shop.listing.create": (0.2, 8),
+    "shop.listing.get": (3.0, 30),
+    "shop.listing.list": (3.0, 30),
+    "shop.listing.report": (0.2, 6),
+    "shop.listing.takedown": (0.5, 10),
+    "shop.listing.update": (0.5, 10),
+    "shop.listing.withdraw": (0.5, 10),
+    "shop.order.cancel": (0.5, 10),
+    "shop.order.confirm": (0.3, 8),
+    "shop.order.create": (0.2, 8),
+    "shop.order.deliver": (0.5, 10),
+    "shop.order.get": (3.0, 30),
+    "shop.order.list": (2.0, 20),
+    "shop.order.look": (0.3, 8),
+    "shop.order.problem": (0.5, 10),
+    "shop.order.receive": (0.5, 10),
+    "shop.quote": (2.0, 20),
+    "shop.report.dismiss": (0.5, 10),
+    "shop.report.list": (1.0, 12),
+    "shop.settings.update": (0.2, 6),
+    "shop.status": (2.0, 20),
+    "shop.wallet.bind": (0.2, 6),
+    "shop.wallet.list": (2.0, 20),
+    "shop.wallet.unlink": (0.2, 6),
+    "staff.override.set": (2.0, 20),
+    "staff.overrides": (2.0, 10),
+    "stage.hand.raise": (1.0, 4),
+    "stage.open": (1.0, 5),
+    "subscription.confirm": (0.3, 8),
+    "subscription.gift": (0.1, 5),
+    "subscription.invoice": (0.05, 6),
+    "subscription.status": (2.0, 20),
+    "ticket.list": (1.0, 5),
+    "ticket.open": (0.1, 3),
+    "ticket.reopen": (0.2, 3),
+    "user.get": (4.0, 20),
+    "user.report": (0.2, 5),
+    "verify.complete": (0.2, 10),
+    "verify.start": (0.02, 5),
+    "verify.status": (2.0, 20),
+    "voice.call.start": (1.0, 3),
+    "voice.camera.start": (1.0, 5),
+    "voice.join": (2.0, 10),
+    "voice.member.deafen": (4.0, 12),
+    "voice.member.disconnect": (4.0, 12),
+    "voice.member.move": (4.0, 12),
+    "voice.member.mute": (4.0, 12),
+    "voice.mls.commit": (5.0, 20),
+    "voice.mls.join": (2.0, 10),
+    "voice.mls.ready": (5.0, 20),
+    "voice.resume": (1.0, 5),
+    "voice.share.start": (1.0, 5),
+    "voice.sound.play": (0.5, 3),
+    "voice.turn.refresh": (0.1, 3),
+    "voice.watch": (4.0, 12),
+    "wallet.allowance": (1.0, 6),
+    "wallet.balances": (0.5, 5),
+    "wallet.broadcast": (0.2, 4),
+    "wallet.coin": (1.0, 6),
+    "wallet.fee": (1.0, 5),
+    "wallet.find_coins": (2.0, 8),
+    "wallet.forget_address": (0.5, 10),
+    "wallet.networks": (1.0, 5),
+    "wallet.nfts": (0.3, 4),
+    "wallet.plan_bitcoin": (0.5, 6),
+    "wallet.portfolio": (0.2, 3),
+    "wallet.prepare": (0.5, 6),
+    "wallet.prices": (1.0, 10),
+    "wallet.rates": (1.0, 5),
+    "wallet.receipt": (1.0, 10),
+    "wallet.register_address": (0.5, 10),
+    "wallet.simulate": (0.5, 6),
+    "wallet.swap_build": (0.3, 4),
+    "wallet.swap_quote": (0.5, 6),
+    "wallet.swap_status": (1.0, 3),
+    "wallet.swap_targets": (1.0, 6),
+    "wallet.tokens": (1.0, 10),
+}

illest/_version.py

@@ -0,0 +1,3 @@
+"""The version, in one place: `pyproject.toml` reads it from here."""
+
+__version__ = "2.2.0"

illest/abc.py

@@ -0,0 +1,257 @@
+"""The abstract bases: `Snowflake`, `Messageable`, `GuildChannel`, `User`, and the typing indicator.
+
+What ILLEST does with each of `Messageable.send`'s keywords:
+
+- `content`, `embed`/`embeds`, `view`, `reference`, `mention_author`: as their names say.
+- `file`/`files`: each is sealed on this machine with a key of its own and uploaded as ciphertext; the key travels inside the
+  message, so only the conversation can open it.
+- `allowed_mentions`: `<@id>`, `<@&id>` and `<#id>` in the text are written out as the names ILLEST shows (`@name`, `#channel`),
+  and the people named are notified unless `allowed_mentions` says not to.
+- `delete_after`: the message is taken back after that many seconds, by this bot.
+- `silent`: nobody is notified.
+- `tts`, `stickers`, `nonce`, `suppress_embeds`, `poll`: `tts` and `stickers` are accepted and ignored (ILLEST has neither); `nonce`
+  is the message's own name for a retried send (`client_id`).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import datetime as _dt
+import re
+from typing import TYPE_CHECKING, Any, AsyncIterator, Protocol, Sequence, runtime_checkable
+
+from .object import as_id, snowflake_time, wire_id
+
+if TYPE_CHECKING:
+    from .client import Client
+    from .embeds import Embed
+    from .file import File
+    from .mentions import AllowedMentions
+    from .models import Message
+    from .ui.view import View
+
+__all__ = ("Snowflake", "Messageable", "Typing", "User", "GuildChannel", "PrivateChannel", "Connectable")
+
+
+@runtime_checkable
+class Snowflake(Protocol):
+    id: int
+
+
+@runtime_checkable
+class User(Protocol):
+    id: int
+    name: str
+    bot: bool
+
+
+@runtime_checkable
+class PrivateChannel(Protocol):
+    id: int
+
+
+class Connectable(Protocol):
+    """A voice channel. A bot has no microphone on ILLEST (calls are encrypted per device), so `connect` is not offered."""
+
+
+_USER = re.compile(r"<@!?(\d+)>")
+_ROLE = re.compile(r"<@&(\d+)>")
+_CHANNEL = re.compile(r"<#(\d+)>")
+
+
+class Typing:
+    """`async with channel.typing():` shows the bot as typing until the block ends; `await channel.typing()` shows it once."""
+
+    def __init__(self, messageable: "Messageable"):
+        self.messageable = messageable
+        self._task: asyncio.Task | None = None
+
+    async def _once(self) -> None:
+        client = self.messageable._state
+        await client.send_typing(self.messageable._channel_wire_id())
+
+    async def _keep(self) -> None:
+        while True:
+            await self._once()
+            await asyncio.sleep(5)
+
+    def __await__(self):
+        return self._once().__await__()
+
+    async def __aenter__(self) -> None:
+        await self._once()
+        self._task = asyncio.get_running_loop().create_task(self._keep_after_first())
+
+    async def _keep_after_first(self) -> None:
+        await asyncio.sleep(5)
+        await self._keep()
+
+    async def __aexit__(self, *exc: Any) -> None:
+        if self._task is not None:
+            self._task.cancel()
+
+
+class Messageable:
+    """Anything a message can be sent to: a channel, a thread, a direct conversation, a member or user (through their DM)."""
+
+    _state: "Client"
+
+    async def _get_channel(self) -> "Messageable":
+        return self
+
+    def _channel_wire_id(self) -> str:
+        return wire_id(self.id)  # type: ignore[attr-defined]
+
+    def _thread_root(self) -> str | None:
+        return None
+
+    async def send(
+        self,
+        content: Any = None,
+        *,
+        tts: bool = False,
+        embed: "Embed | None" = None,
+        embeds: Sequence["Embed"] | None = None,
+        file: "File | None" = None,
+        files: Sequence["File"] | None = None,
+        stickers: Sequence[Any] | None = None,
+        delete_after: float | None = None,
+        nonce: str | int | None = None,
+        allowed_mentions: "AllowedMentions | None" = None,
+        reference: Any = None,
+        mention_author: bool | None = None,
+        view: "View | None" = None,
+        suppress_embeds: bool = False,
+        silent: bool = False,
+        poll: Any = None,
+        ephemeral_for: Any = None,
+        ask_reply: Any = None,
+    ) -> "Message":
+        """Send a message here. `ask_reply` (True, a placeholder, or an `AskReply`) opens the reply box on it, so the answer comes
+        back as a reply."""
+        channel = await self._get_channel()
+        return await channel._state._send_to(
+            channel._channel_wire_id(),
+            content,
+            ask_reply=ask_reply,
+            thread_root=channel._thread_root(),
+            embed=embed,
+            embeds=embeds,
+            file=file,
+            files=files,
+            delete_after=delete_after,
+            nonce=nonce,
+            allowed_mentions=allowed_mentions,
+            reference=reference,
+            mention_author=mention_author,
+            view=view,
+            suppress_embeds=suppress_embeds,
+            silent=silent,
+            ephemeral_for=ephemeral_for,
+        )
+
+    def typing(self) -> Typing:
+        return Typing(self)
+
+    async def trigger_typing(self) -> None:
+        await self.typing()
+
+    async def fetch_message(self, id: int) -> "Message":  # noqa: A002
+        """A message this bot holds. An end-to-end encrypted message is readable only once, as it arrives; the bot keeps the newest
+        `max_messages` (and, with `Client(message_store=...)`, writes them to disk), and that is what it can fetch."""
+        channel = await self._get_channel()
+        found = channel._state._connection_message(as_id(id))
+        from .errors import NotFound
+
+        if found is None or found.channel.id != channel.id:
+            raise NotFound("NOT_FOUND", "this bot does not hold that message (it reads a message once, as it arrives)")
+        return found
+
+    def history(
+        self,
+        *,
+        limit: int | None = 100,
+        before: Any = None,
+        after: Any = None,
+        around: Any = None,
+        oldest_first: bool | None = None,
+    ) -> AsyncIterator["Message"]:
+        """The messages this bot holds for this channel, newest first (oldest first when `after` is given).
+
+        ILLEST's server holds only ciphertext, and a message can be opened once, by the devices that were in the conversation when it
+        was sent. So the history a bot can read is what it has read: kept in memory (`max_messages`) and, when the bot was made
+        with `message_store=`, on disk.
+        """
+        return _history(self, limit, before, after, around, oldest_first)
+
+    async def pins(self) -> list["Message"]:
+        channel = await self._get_channel()
+        answer = await channel._state.request("channel.pins.list", {"channel_id": channel._channel_wire_id()})
+        out = []
+        for raw in answer.get("pins") or answer.get("messages") or []:
+            message_id = raw.get("message_id") if isinstance(raw, dict) else raw
+            held = channel._state._connection_message(as_id(message_id)) if message_id else None
+            if held is not None:
+                out.append(held)
+        return out
+
+
+def _instant(value: Any) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, _dt.datetime):
+        return value.timestamp()
+    return snowflake_time(as_id(value)).timestamp()
+
+
+async def _history(channel: Messageable, limit, before, after, around, oldest_first) -> AsyncIterator["Message"]:
+    target = await channel._get_channel()
+    held = target._state._messages_in(as_id(target.id), target._thread_root())
+    before_t, after_t, around_t = _instant(before), _instant(after), _instant(around)
+    rows = [m for m in held if (before_t is None or m.created_at.timestamp() < before_t) and (after_t is None or m.created_at.timestamp() > after_t)]
+    if around_t is not None:
+        rows.sort(key=lambda m: abs(m.created_at.timestamp() - around_t))
+        rows = rows[: limit or len(rows)]
+    if oldest_first is None:
+        oldest_first = after is not None
+    rows.sort(key=lambda m: m.id, reverse=not oldest_first)
+    if limit is not None and around_t is None:
+        rows = rows[:limit]
+    for message in rows:
+        yield message
+
+
+class GuildChannel:
+    """Marker for a server's channel; the behaviour is `models.GuildChannel`'s."""
+
+
+def rewrite_mentions(client: "Client", text: str, guild: Any = None) -> tuple[str, list[int]]:
+    """Mention tokens written as ILLEST shows them, and who they name: `<@5>` becomes `@mira` (5 is notified),
+    `<@&9>` becomes `@Mods`, `<#12>` becomes `#general`. A token for somebody the bot cannot name is left as it is."""
+    named: list[int] = []
+
+    def user(match: re.Match) -> str:
+        uid = int(match.group(1))
+        known = client.get_user(uid)
+        if known is None:
+            return match.group(0)
+        if uid not in named:
+            named.append(uid)
+        return f"@{known.name}"
+
+    def role(match: re.Match) -> str:
+        rid = int(match.group(1))
+        for g in [guild] if guild is not None else client.guilds:
+            found = g.get_role(rid) if g is not None else None
+            if found is not None:
+                return f"@{found.name}"
+        return match.group(0)
+
+    def channel(match: re.Match) -> str:
+        found = client.get_channel(int(match.group(1)))
+        return f"#{found.name}" if found is not None and getattr(found, "name", None) else match.group(0)
+
+    text = _USER.sub(user, text)
+    text = _ROLE.sub(role, text)
+    text = _CHANNEL.sub(channel, text)
+    return text, named