discomposer 0.1.0__py3-none-any.whl

discomposer/__init__.py

@@ -0,0 +1,72 @@
+"""discomposer: validate, fetch and send Discord message templates with discord.py."""
+
+from discomposer.editor import (
+    DEFAULT_URL,
+    EditorClient,
+    EditorError,
+    components_to_blocks,
+    emoji_text,
+    guild_context,
+    parse_code,
+)
+from discomposer.format import (
+    TemplateError,
+    chosen_options,
+    clean_emoji,
+    find_select,
+    selects_for,
+    validate,
+    validate_design,
+)
+from discomposer.media import MediaError, MediaStore, image_extension
+from discomposer.render import (
+    button_emoji,
+    button_style,
+    outside_text,
+    render,
+    render_message,
+    select_rows,
+)
+from discomposer.tickets import (
+    category_roles,
+    chosen_category,
+    missing_roles,
+    ticket_categories,
+    ticket_overwrites,
+    transcript_markdown,
+)
+from discomposer.variables import VARIABLES, fill_variables
+
+__all__ = [
+    "DEFAULT_URL",
+    "VARIABLES",
+    "EditorClient",
+    "EditorError",
+    "MediaError",
+    "MediaStore",
+    "TemplateError",
+    "button_emoji",
+    "button_style",
+    "category_roles",
+    "chosen_category",
+    "chosen_options",
+    "clean_emoji",
+    "components_to_blocks",
+    "emoji_text",
+    "fill_variables",
+    "find_select",
+    "guild_context",
+    "image_extension",
+    "missing_roles",
+    "parse_code",
+    "outside_text",
+    "render",
+    "render_message",
+    "select_rows",
+    "selects_for",
+    "ticket_categories",
+    "ticket_overwrites",
+    "transcript_markdown",
+    "validate",
+    "validate_design",
+]

discomposer/editor.py

@@ -0,0 +1,266 @@
+import copy
+import json
+import re
+from pathlib import PurePosixPath
+from urllib.parse import urlsplit
+
+import aiohttp
+
+from discomposer.format import validate, validate_design
+from discomposer.media import MAX_IMAGE, MediaError
+
+DEFAULT_URL = "https://editor.caneabi.dev"
+# Only the editor and Discord's CDN are fetched, so templates can't reach internal URLs.
+DISCORD_MEDIA = frozenset({"cdn.discordapp.com", "media.discordapp.net"})
+CODE = re.compile(r"[0-9A-HJKMNP-TV-Z]{5}-[0-9A-HJKMNP-TV-Z]{5}")
+MAX_RESPONSE = 70 * 1024
+OFFLINE = "The editor is unavailable right now. Please try again later."
+
+
+class EditorError(Exception):
+    """Talking to the editor failed. The message is meant for end users."""
+
+
+async def read_all(response, limit):
+    # response.content.read(n) returns whatever has arrived so far, which truncates large images.
+    data = bytearray()
+    async for chunk in response.content.iter_chunked(64 * 1024):
+        data.extend(chunk)
+        if len(data) > limit:
+            raise EditorError("The response is too large.")
+    return bytes(data)
+
+
+def parse_code(value):
+    """Return the code from a code or an editor link."""
+    code = str(value).strip().rstrip("/").rsplit("/", 1)[-1].upper()
+    if not CODE.fullmatch(code):
+        raise EditorError("That is not a valid code. It looks like this: K7F3M-9QX2A")
+    return code
+
+
+def components_to_blocks(items, on_row_item=None):
+    """Convert sent Components V2 back into blocks.
+
+    on_row_item(child, blocks) may turn your own buttons or menus into blocks and returns True.
+    Returns (blocks, color, has_actions); has_actions means interactive components were left over.
+    """
+    blocks, color, has_actions = [], None, False
+
+    def walk(parts):
+        nonlocal color, has_actions
+        for part in parts:
+            kind = part.get("type")
+            if kind == 17:
+                color = part.get("accent_color", color)
+                walk(part.get("components", []))
+            elif kind == 9:
+                accessory = part.get("accessory", {})
+                if accessory.get("type") == 11:
+                    blocks.append({"image": accessory.get("media", {}).get("url")})
+                elif accessory.get("type") == 2:
+                    walk([{"type": 1, "components": [accessory]}])
+                walk(part.get("components", []))
+            elif kind == 10:
+                blocks.append({"text": part.get("content", "")})
+            elif kind == 12:
+                blocks.extend(
+                    {"gallery": item.get("media", {}).get("url")} for item in part.get("items", [])
+                )
+            elif kind == 14:
+                blocks.append({"separator": True})
+            elif kind == 1:
+                for child in part.get("components", []):
+                    if on_row_item and on_row_item(child, blocks):
+                        continue
+                    if child.get("type") == 2 and child.get("style") == 5:
+                        link = {"label": child.get("label") or "Link", "url": child.get("url")}
+                        if emoji_text(child.get("emoji")):
+                            link["emoji"] = emoji_text(child.get("emoji"))
+                        blocks.append({"link": link})
+                    else:
+                        has_actions = True
+
+    walk(items)
+    return blocks, color, has_actions
+
+
+def emoji_text(emoji):
+    """Emoji of a component in template notation."""
+    if emoji and emoji.get("id"):
+        prefix = "a" if emoji.get("animated") else ""
+        return f"<{prefix}:{emoji.get('name')}:{emoji['id']}>"
+    return emoji.get("name") if emoji else None
+
+
+def guild_context(guild):
+    """Channels, roles and emojis for the editor. Codes aren't secret, so only public ones."""
+    everyone = guild.default_role
+    channels = [
+        channel for channel in guild.text_channels if channel.permissions_for(everyone).view_channel
+    ]
+    roles = [r for r in guild.roles if not r.is_default() and not r.managed]
+    emojis = [e for e in guild.emojis if e.available]
+    return {
+        "channels": [{"id": str(c.id), "name": c.name} for c in channels[:200]],
+        "roles": [{"id": str(r.id), "name": r.name} for r in reversed(roles[-200:])],
+        "emojis": [{"id": str(e.id), "name": e.name, "animated": e.animated} for e in emojis[:200]],
+    }
+
+
+class EditorClient:
+    """Client for the template editor. Pass a MediaStore to keep copies of images."""
+
+    def __init__(self, base_url=DEFAULT_URL, media=None, *, timeout=30):
+        self.base_url = base_url.rstrip("/")
+        self.media = media
+        self.timeout = timeout
+        self.image_url = re.compile(re.escape(self.base_url) + r"/api/images/[0-9a-f]{64}")
+
+    async def _request(self, method, path, *, limit=MAX_RESPONSE, parse=True, **kwargs):
+        timeout = aiohttp.ClientTimeout(total=self.timeout)
+        try:
+            async with (
+                aiohttp.ClientSession(timeout=timeout) as session,
+                session.request(
+                    method, self.base_url + path, allow_redirects=False, **kwargs
+                ) as response,
+            ):
+                raw = await read_all(response, limit)
+                return response.status, json.loads(raw) if parse else raw
+        except (aiohttp.ClientError, TimeoutError, ValueError):
+            raise EditorError(OFFLINE) from None
+
+    async def open(self, document):
+        """Store a document and return the link to edit it."""
+        document = validate(document)
+        status, body = await self._request("POST", "/api/templates", json=document)
+        if status != 201 or not isinstance(body, dict) or not isinstance(body.get("code"), str):
+            raise EditorError((body or {}).get("error") if isinstance(body, dict) else OFFLINE)
+        return f"{self.base_url}/e/{body['code']}"
+
+    async def upload(self, raw):
+        """Upload an image and return its URL."""
+        status, body = await self._request(
+            "POST", "/api/images", data=raw, headers={"content-type": "application/octet-stream"}
+        )
+        if status != 201 or not isinstance(body, dict) or not isinstance(body.get("path"), str):
+            raise EditorError((body or {}).get("error") if isinstance(body, dict) else OFFLINE)
+        return self.base_url + body["path"]
+
+    async def fetch_document(self, code):
+        """Fetch and validate a document by code or link."""
+        status, body = await self._request("GET", f"/api/templates/{parse_code(code)}")
+        if status == 404:
+            raise EditorError("This code doesn't exist or has expired.")
+        if status != 200 or not isinstance(body, dict):
+            raise EditorError(OFFLINE)
+        return validate(body)
+
+    async def fetch(self, code, *, adopt_images=True):
+        """Fetch the design of a template; images are adopted if a MediaStore is set."""
+        design = (await self.fetch_document(code))["design"]
+        if adopt_images and self.media is not None:
+            design = await self.adopt_images(design)
+        return design
+
+    async def _download(self, url):
+        timeout = aiohttp.ClientTimeout(total=self.timeout)
+        try:
+            async with (
+                aiohttp.ClientSession(timeout=timeout) as session,
+                session.get(url, allow_redirects=False) as response,
+            ):
+                if response.status != 200:
+                    raise EditorError(
+                        "A Discord image has expired. Please upload it again in the editor."
+                    )
+                return await read_all(response, MAX_IMAGE)
+        except (aiohttp.ClientError, TimeoutError):
+            raise EditorError(
+                "An image could not be loaded. Please upload it in the editor."
+            ) from None
+
+    async def adopt_images(self, design):
+        """Store editor and Discord images and point the blocks at attachment:// names.
+
+        The result has attachments: {filename: stored name}. Editor images expire after 30 days.
+        """
+        if self.media is None:
+            raise EditorError("The client needs a MediaStore to adopt images.")
+        design = copy.deepcopy(design)
+        attachments = dict(design.get("attachments", {}))
+        for block in design["blocks"]:
+            for key in ("image", "gallery"):
+                value = block.get(key)
+                if not isinstance(value, str):
+                    continue
+                if self.image_url.fullmatch(value):
+                    status, raw = await self._request(
+                        "GET", urlsplit(value).path, limit=MAX_IMAGE, parse=False
+                    )
+                    if status != 200:
+                        raise EditorError("An uploaded image has expired. Please upload it again.")
+                elif value.startswith("https://") and urlsplit(value).hostname in DISCORD_MEDIA:
+                    raw = await self._download(value)
+                else:
+                    continue
+                try:
+                    stored = self.media.save(raw)
+                except MediaError as error:
+                    raise EditorError(str(error)) from None
+                filename = self.media.attachment_name(stored, raw)
+                attachments[filename] = stored
+                block[key] = f"attachment://{filename}"
+        if attachments:
+            design["attachments"] = attachments
+        return design
+
+    async def expose_attachments(self, design):
+        """Reverse of adopt_images: upload stored attachments so the editor can show them."""
+        design = copy.deepcopy(design)
+        stored = design.pop("attachments", {})
+        for block in design.get("blocks", []):
+            for key in ("image", "gallery"):
+                value = block.get(key)
+                if isinstance(value, str) and value.startswith("attachment://"):
+                    name = stored.get(value.removeprefix("attachment://"))
+                    if name is None or self.media is None:
+                        raise EditorError("An image of this template is missing.")
+                    block[key] = await self.upload(self.media.read(name))
+        return validate_design(design)
+
+    async def open_message(self, message, *, on_row_item=None, **document):
+        """Open a sent message in the editor. Returns None if it has components nobody handles."""
+        items = [component.to_dict() for component in message.components]
+        blocks, color, has_actions = components_to_blocks(items, on_row_item)
+        if has_actions:
+            return None
+        if message.content:
+            blocks.insert(0, {"text": message.content})
+        for embed in message.embeds:
+            parts = [f"## {embed.title}" if embed.title else None, embed.description]
+            text = "\n".join(part for part in parts if part)
+            if text:
+                blocks.append({"text": text})
+            if embed.image and embed.image.url:
+                blocks.append({"gallery": embed.image.url})
+            if color is None and embed.colour:
+                color = embed.colour.value
+        files = {attachment.filename: attachment for attachment in message.attachments}
+        for block in blocks:
+            for key in ("image", "gallery"):
+                value = block.get(key)
+                if not isinstance(value, str):
+                    continue
+                name = (
+                    value.removeprefix("attachment://")
+                    if value.startswith("attachment://")
+                    else PurePosixPath(urlsplit(value).path).name
+                )
+                if name in files:
+                    block[key] = await self.upload(await files[name].read())
+        design = {"blocks": blocks}
+        if color is not None:
+            design["color"] = color
+        return await self.open({**document, "design": design})

discomposer/format.py

@@ -0,0 +1,350 @@
+"""Validation and normalization of the template format (spec/FORMAT.md)."""
+
+import re
+from urllib.parse import urlsplit
+
+MAX_BLOCKS = 20
+MAX_TEXT = 3500
+IMAGE_VARIABLES = ("{server_icon}", "{server_banner}")
+BUTTON_STYLES = ("primary", "secondary", "success", "danger")
+SELECT_MODES = ("select", "buttons")
+ROLE_MODES = ("none", "optional", "single")
+SLUG = re.compile(r"[A-Za-z0-9_-]{1,64}")
+SNOWFLAKE = re.compile(r"\d{17,20}")
+CUSTOM_EMOJI = re.compile(r"<a?:\w{1,32}:\d{17,20}>")
+DOCUMENT_KEYS = {
+    "version",
+    "kind",
+    "title",
+    "template",
+    "note",
+    "returnHint",
+    "sender",
+    "messageType",
+    "context",
+    "design",
+}
+
+
+class TemplateError(ValueError):
+    """The template violates the format. The message is meant for end users."""
+
+
+def _text(value, limit, message, *, required=False):
+    if value is None and not required:
+        return None
+    if not isinstance(value, str) or len(value) > limit or (required and not value.strip()):
+        raise TemplateError(message)
+    return value
+
+
+def clean_emoji(value):
+    """A custom emoji (<:name:id>) or a short Unicode emoji without letters."""
+    if value is None or value == "":
+        return None
+    if isinstance(value, str) and CUSTOM_EMOJI.fullmatch(value):
+        return value
+    valid = (
+        isinstance(value, str)
+        and 0 < len(value) <= 16
+        and not any(char.isspace() or char.isalpha() or char in "<>" for char in value)
+    )
+    if not valid:
+        raise TemplateError("An emoji is invalid.")
+    return value
+
+
+def https_url(value):
+    if not isinstance(value, str) or len(value) > 2048:
+        raise TemplateError("Invalid URL.")
+    url = urlsplit(value)
+    if url.scheme != "https" or not url.hostname or url.username or url.password:
+        raise TemplateError("Images and links need a public HTTPS URL.")
+    return value
+
+
+def image_source(value):
+    return value if value in IMAGE_VARIABLES else https_url(value)
+
+
+def _slug(value, message):
+    if not isinstance(value, str) or not SLUG.fullmatch(value):
+        raise TemplateError(message)
+    return value
+
+
+def _roles(value, limit, message):
+    if not isinstance(value, list) or len(value) > limit:
+        raise TemplateError(message)
+    for role in value:
+        if not isinstance(role, str) or not SNOWFLAKE.fullmatch(role):
+            raise TemplateError(message)
+    return list(dict.fromkeys(value))
+
+
+def _optional(entry, source, key, cleaner):
+    value = source.get(key)
+    if value not in (None, ""):
+        entry[key] = cleaner(value)
+
+
+def clean_select(menu):
+    if not isinstance(menu, dict):
+        raise TemplateError("Invalid selection.")
+    select_id = _slug(menu.get("id"), "Invalid selection.")
+    purpose = _slug(menu.get("purpose"), "Invalid selection.")
+    if menu.get("mode") not in SELECT_MODES or not isinstance(menu.get("exclusive"), bool):
+        raise TemplateError("Invalid selection.")
+    options = menu.get("options")
+    if not isinstance(options, list) or not 1 <= len(options) <= 25:
+        raise TemplateError("A selection needs 1 to 25 options.")
+    cleaned, seen = [], set()
+    for option in options:
+        if not isinstance(option, dict):
+            raise TemplateError("Invalid option.")
+        value = _slug(option.get("value"), "Every option needs a unique value.")
+        if value in seen:
+            raise TemplateError("Every option needs a unique value.")
+        seen.add(value)
+        label = _text(option.get("label"), 80, "Every option needs a label.", required=True)
+        entry = {"value": value, "label": label}
+        _optional(entry, option, "emoji", clean_emoji)
+        _optional(
+            entry,
+            option,
+            "description",
+            lambda v: _text(v, 100, "The description is too long."),
+        )
+        if option.get("roles") is not None:
+            entry["roles"] = _roles(option["roles"], 10, "An option contains invalid roles.")
+        cleaned.append(entry)
+    result = {
+        "id": select_id,
+        "purpose": purpose,
+        "mode": menu["mode"],
+        "exclusive": menu["exclusive"],
+        "options": cleaned,
+    }
+    _optional(
+        result,
+        menu,
+        "placeholder",
+        lambda v: _text(v, 150, "The placeholder is too long."),
+    )
+    return result
+
+
+def _clean_button(item):
+    if not isinstance(item, dict):
+        raise TemplateError("Invalid button.")
+    button = {
+        "id": _slug(item.get("id"), "Invalid button."),
+        "label": _text(item.get("label"), 80, "Invalid button.", required=True),
+        "style": item.get("style") or "secondary",
+    }
+    if button["style"] not in BUTTON_STYLES:
+        raise TemplateError("Invalid button.")
+    _optional(button, item, "emoji", clean_emoji)
+    return button
+
+
+def _clean_link(item):
+    if not isinstance(item, dict):
+        raise TemplateError("Link buttons need a label and an HTTPS URL.")
+    link = {
+        "label": _text(item.get("label"), 80, "Link buttons need a label.", required=True),
+        "url": https_url(item.get("url")),
+    }
+    _optional(link, item, "emoji", clean_emoji)
+    return link
+
+
+def clean_block(block):
+    if not isinstance(block, dict) or len(block) != 1:
+        raise TemplateError("Invalid block.")
+    key, item = next(iter(block.items()))
+    if key == "text" and isinstance(item, str):
+        return {"text": item}
+    if key in ("image", "gallery"):
+        return {key: image_source(item)}
+    if key == "slot":
+        return {"slot": _slug(item, "Invalid dynamic block.")}
+    if key == "separator" and item is True:
+        return {"separator": True}
+    if key == "button":
+        return {"button": _clean_button(item)}
+    if key == "link":
+        return {"link": _clean_link(item)}
+    if key == "select":
+        return {"select": clean_select(item)}
+    raise TemplateError("Unknown block.")
+
+
+def validate_design(design):
+    """Validate a design and return a cleaned copy."""
+    if not isinstance(design, dict) or not isinstance(design.get("blocks"), list):
+        raise TemplateError("Invalid template.")
+    if len(design["blocks"]) > MAX_BLOCKS:
+        raise TemplateError(f"At most {MAX_BLOCKS} blocks.")
+    blocks, ids = [], set()
+    for block in design["blocks"]:
+        cleaned = clean_block(block)
+        if "select" in cleaned:
+            if cleaned["select"]["id"] in ids:
+                raise TemplateError("Every selection needs its own ID.")
+            ids.add(cleaned["select"]["id"])
+        blocks.append(cleaned)
+    content = _text(design.get("content"), 2000, "The outside text is too long.")
+    length = sum(len(block.get("text", "")) for block in blocks) + len(content or "")
+    if length > MAX_TEXT:
+        raise TemplateError(f"At most {MAX_TEXT} characters of text.")
+    result = {"blocks": blocks}
+    if content:
+        result["content"] = content
+    color = design.get("color")
+    if color is not None:
+        if type(color) is not int or not 0 <= color <= 0xFFFFFF:
+            raise TemplateError("Invalid accent color.")
+        result["color"] = color
+    keep = design.get("keepBotImage")
+    if keep is not None:
+        if keep not in ("large", "small"):
+            raise TemplateError("Invalid image setting.")
+        result["keepBotImage"] = keep
+    return result
+
+
+def _clean_footer(footer):
+    if not isinstance(footer, dict) or not isinstance(footer.get("rows"), list):
+        raise TemplateError("Invalid context.")
+    rows = footer["rows"]
+    if len(rows) > 5 or any(not isinstance(row, list) or len(row) > 5 for row in rows):
+        raise TemplateError("Invalid context.")
+    result = {"rows": [[https_url(url) for url in row] for row in rows]}
+    _optional(result, footer, "label", lambda v: _text(v, 100, "Invalid context."))
+    return result
+
+
+def _clean_context(context):
+    if not isinstance(context, dict):
+        raise TemplateError("Invalid context.")
+    result = {}
+    for key, items in context.items():
+        if key == "accessory":
+            result[key] = _slug(items, "Invalid context.")
+            continue
+        if key == "footer":
+            result[key] = _clean_footer(items)
+            continue
+        if key not in ("channels", "roles", "emojis", "buttons", "slots", "selects"):
+            raise TemplateError("Invalid context.")
+        if not isinstance(items, list) or len(items) > (20 if key == "selects" else 200):
+            raise TemplateError("Invalid context.")
+        cleaned = []
+        for item in items:
+            if not isinstance(item, dict):
+                raise TemplateError("Invalid context.")
+            if key == "selects":
+                entry = {
+                    "purpose": _slug(item.get("purpose"), "Invalid context."),
+                    "label": _text(item.get("label"), 80, "Invalid context.", required=True),
+                    "roles": item.get("roles") or "none",
+                }
+                modes = item.get("modes")
+                if entry["roles"] not in ROLE_MODES:
+                    raise TemplateError("Invalid context.")
+                if modes is not None:
+                    if (
+                        not isinstance(modes, list)
+                        or not modes
+                        or any(mode not in SELECT_MODES for mode in modes)
+                    ):
+                        raise TemplateError("Invalid context.")
+                    entry["modes"] = modes
+                if item.get("exclusive") is not None:
+                    if not isinstance(item["exclusive"], bool):
+                        raise TemplateError("Invalid context.")
+                    entry["exclusive"] = item["exclusive"]
+                _optional(entry, item, "hint", lambda v: _text(v, 300, "Invalid context."))
+            elif key in ("buttons", "slots"):
+                entry = {
+                    "id": _slug(item.get("id"), "Invalid context."),
+                    "label": _text(item.get("label"), 80, "Invalid context.", required=True),
+                }
+                _optional(entry, item, "sample", lambda v: _text(v, 1000, "Invalid context."))
+                if item.get("icon") is not None:
+                    if key != "buttons":
+                        raise TemplateError("Invalid context.")
+                    entry["icon"] = https_url(item["icon"])
+            else:
+                ident, name = item.get("id"), item.get("name")
+                if not isinstance(ident, str) or not SNOWFLAKE.fullmatch(ident):
+                    raise TemplateError("Invalid context.")
+                _text(name, 100, "Invalid context.", required=True)
+                if key == "emojis" and not re.fullmatch(r"\w{2,32}", name):
+                    raise TemplateError("Invalid context.")
+                entry = {"id": ident, "name": name}
+                if key == "emojis" and item.get("animated") is True:
+                    entry["animated"] = True
+            cleaned.append(entry)
+        result[key] = cleaned
+    return result
+
+
+def validate(document):
+    """Validate a whole document and return a cleaned copy. Raises TemplateError."""
+    if not isinstance(document, dict) or set(document) - DOCUMENT_KEYS:
+        raise TemplateError("Invalid template.")
+    if document.get("version") not in (None, 1):
+        raise TemplateError("Unknown format version.")
+    result = {}
+    for key, limit in (
+        ("kind", 80),
+        ("title", 80),
+        ("template", 80),
+        ("note", 300),
+        ("returnHint", 300),
+    ):
+        if document.get(key) is not None:
+            result[key] = _text(document[key], limit, "Invalid template.")
+    if document.get("version") is not None:
+        result["version"] = 1
+    if document.get("messageType") not in (None, "general", "member"):
+        raise TemplateError("Invalid message type.")
+    if document.get("messageType"):
+        result["messageType"] = document["messageType"]
+    sender = document.get("sender")
+    if sender is not None:
+        if not isinstance(sender, dict):
+            raise TemplateError("Invalid sender.")
+        result["sender"] = {"name": _text(sender.get("name"), 80, "Invalid sender.", required=True)}
+        if sender.get("avatar") is not None:
+            result["sender"]["avatar"] = https_url(sender["avatar"])
+    if document.get("context") is not None:
+        result["context"] = _clean_context(document["context"])
+    result["design"] = validate_design(document.get("design"))
+    return result
+
+
+def find_select(design, select_id):
+    for block in design.get("blocks", []):
+        if block.get("select", {}).get("id") == select_id:
+            return block["select"]
+    return None
+
+
+def selects_for(design, purpose):
+    return [
+        block["select"]
+        for block in design.get("blocks", [])
+        if block.get("select", {}).get("purpose") == purpose
+    ]
+
+
+def chosen_options(design, select_id, values):
+    """Options matching the chosen values. Always pass the stored design, never interaction data."""
+    menu = find_select(design, select_id)
+    if menu is None:
+        return []
+    wanted = set(values)
+    return [option for option in menu["options"] if option["value"] in wanted]

discomposer/media.py

@@ -0,0 +1,67 @@
+import hashlib
+import re
+from pathlib import Path
+
+import discord
+
+MAX_IMAGE = 8 * 1024 * 1024
+ATTACHMENT_NAME = re.compile(r"pb-[0-9a-f]{16}\.(?:png|jpg|gif|webp)")
+STORED_NAME = re.compile(r"[0-9a-f]{64}")
+
+
+class MediaError(ValueError):
+    """An image can't be stored. The message is meant for end users."""
+
+
+def image_extension(raw):
+    """Detect the format from the bytes. Anything else, including SVG, is rejected."""
+    if raw.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "png"
+    if raw.startswith(b"\xff\xd8\xff"):
+        return "jpg"
+    if raw.startswith((b"GIF87a", b"GIF89a")):
+        return "gif"
+    if raw[:4] == b"RIFF" and raw[8:12] == b"WEBP":
+        return "webp"
+    return None
+
+
+class MediaStore:
+    """Stores images by SHA-256 in a folder with a size limit."""
+
+    def __init__(self, path, quota=128 * 1024 * 1024):
+        self.path = Path(path)
+        self.quota = quota
+
+    def save(self, raw):
+        if len(raw) > MAX_IMAGE or not image_extension(raw):
+            raise MediaError("Please use a PNG, JPEG, GIF or WebP image up to 8 MB.")
+        self.path.mkdir(parents=True, exist_ok=True)
+        name = hashlib.sha256(raw).hexdigest()
+        target = self.path / name
+        if not target.exists():
+            used = sum(p.stat().st_size for p in self.path.iterdir() if p.is_file())
+            if used + len(raw) > self.quota:
+                raise MediaError("The image store is full. Please clean up old template images.")
+            target.write_bytes(raw)
+        return name
+
+    def file(self, stored):
+        if not isinstance(stored, str) or not STORED_NAME.fullmatch(stored):
+            raise MediaError("Invalid stored image name.")
+        return self.path / stored
+
+    def read(self, stored):
+        return self.file(stored).read_bytes()
+
+    def attachment_name(self, stored, raw):
+        return f"pb-{stored[:16]}.{image_extension(raw)}"
+
+    def files_for(self, design):
+        """discord.File objects for all adopted images of a design."""
+        files = []
+        for filename, stored in design.get("attachments", {}).items():
+            if not ATTACHMENT_NAME.fullmatch(filename):
+                raise MediaError("Invalid stored image name.")
+            files.append(discord.File(self.file(stored), filename=filename))
+        return files

discomposer/render.py

@@ -0,0 +1,210 @@
+import re
+
+import discord
+
+from discomposer.format import IMAGE_VARIABLES
+from discomposer.variables import fill_variables
+
+BUTTON_STYLES = {
+    "primary": discord.ButtonStyle.primary,
+    "secondary": discord.ButtonStyle.secondary,
+    "success": discord.ButtonStyle.success,
+    "danger": discord.ButtonStyle.danger,
+}
+SEPARATOR_TEXT = "────────"
+
+
+def button_emoji(value):
+    return discord.PartialEmoji.from_str(value) if value else None
+
+
+def button_style(name):
+    return BUTTON_STYLES.get(name or "secondary", discord.ButtonStyle.secondary)
+
+
+def select_rows(menu, custom_id):
+    """Default rendering of a select block.
+
+    Select menu: custom_id as given, values are the option values.
+    Buttons: custom_id + ":" + value. Resolve the choice with chosen_options.
+    """
+    if menu["mode"] == "select":
+        select = discord.ui.Select(
+            custom_id=custom_id,
+            placeholder=menu.get("placeholder"),
+            min_values=0 if not menu["exclusive"] else 1,
+            max_values=1 if menu["exclusive"] else len(menu["options"]),
+            options=[
+                discord.SelectOption(
+                    label=option["label"],
+                    value=option["value"],
+                    description=option.get("description"),
+                    emoji=button_emoji(option.get("emoji")),
+                )
+                for option in menu["options"]
+            ],
+        )
+        return [discord.ui.ActionRow(select)]
+    buttons = [
+        discord.ui.Button(
+            label=option["label"],
+            custom_id=f"{custom_id}:{option['value']}",
+            emoji=button_emoji(option.get("emoji")),
+            style=discord.ButtonStyle.secondary,
+        )
+        for option in menu["options"]
+    ]
+    return [
+        discord.ui.ActionRow(*buttons[start : start + 5]) for start in range(0, len(buttons), 5)
+    ]
+
+
+def render(
+    container,
+    design,
+    *,
+    member=None,
+    guild=None,
+    header=(),
+    thumbnail=None,
+    accessory=None,
+    buttons=None,
+    slots=None,
+    selects=None,
+    variables=None,
+):
+    """Fill a discord.ui.Container from a validated design.
+
+    header: items added first, e.g. a large image of your own.
+    thumbnail: top-right image if the design has no image block.
+    accessory: item next to the first text if there is no thumbnail.
+    buttons: {id: callable(button) -> discord.ui.Button}; unknown ids are skipped.
+    slots: {id: text}; missing slots are skipped.
+    selects: callable(select, guild) -> items; select blocks are skipped without it.
+    variables: extra variables, e.g. {"{level}": "3"}.
+    """
+    for item in header:
+        container.add_item(item)
+
+    def fill(text):
+        return fill_variables(text, member, guild, variables)
+
+    def resolved(url):
+        return fill(url) if url in IMAGE_VARIABLES else url
+
+    blocks = design.get("blocks", [])
+    image = thumbnail or next((block["image"] for block in blocks if "image" in block), None)
+    # {server_icon} resolves to an empty string if the server has no icon.
+    image = resolved(image) if image else None
+
+    texts, galleries, links = [], [], []
+
+    def flush_links():
+        for start in range(0, len(links), 5):
+            container.add_item(discord.ui.ActionRow(*links[start : start + 5]))
+        links.clear()
+
+    def flush_text():
+        nonlocal image, accessory
+        if not texts:
+            return
+        display = discord.ui.TextDisplay("\n".join(texts))
+        texts.clear()
+        if image:
+            container.add_item(discord.ui.Section(display, accessory=discord.ui.Thumbnail(image)))
+            image = None
+        elif accessory:
+            container.add_item(discord.ui.Section(display, accessory=accessory))
+            accessory = None
+        else:
+            container.add_item(display)
+
+    def flush_gallery():
+        if galleries:
+            container.add_item(
+                discord.ui.MediaGallery(*(discord.MediaGalleryItem(url) for url in galleries[:10]))
+            )
+            galleries.clear()
+
+    for block in blocks:
+        if "link" in block:
+            flush_text()
+            flush_gallery()
+            link = block["link"]
+            links.append(
+                discord.ui.Button(
+                    label=link["label"],
+                    url=link["url"],
+                    style=discord.ButtonStyle.link,
+                    emoji=button_emoji(link.get("emoji")),
+                )
+            )
+            continue
+        if "button" in block:
+            action = (buttons or {}).get(block["button"]["id"])
+            if action:
+                flush_text()
+                flush_gallery()
+                links.append(action(block["button"]))
+            continue
+        if "select" in block:
+            flush_text()
+            flush_gallery()
+            flush_links()
+            if selects:
+                for row in selects(block["select"], member.guild if member else guild) or ():
+                    container.add_item(row)
+            continue
+        if "slot" in block:
+            flush_links()
+            flush_gallery()
+            value = (slots or {}).get(block["slot"])
+            if value:
+                texts.append(value)
+            continue
+        if "image" not in block:
+            flush_links()
+        if "gallery" in block:
+            flush_text()
+            url = resolved(block["gallery"])
+            if url:
+                galleries.append(url)
+            continue
+        if "text" in block:
+            flush_gallery()
+            # Discord only renders headings with a space after the #.
+            texts.append(re.sub(r"(?m)^(#{1,3})(?=[^#\s])", r"\1 ", fill(block["text"])))
+        elif block.get("separator"):
+            flush_gallery()
+            texts.append(SEPARATOR_TEXT)
+    flush_text()
+    flush_gallery()
+    flush_links()
+    if image:
+        container.add_item(
+            discord.ui.Section(discord.ui.TextDisplay("​"), accessory=discord.ui.Thumbnail(image))
+        )
+    return container
+
+
+def outside_text(design, *, member=None, guild=None, variables=None):
+    """The design's content as a TextDisplay placed above the container, or None."""
+    content = design.get("content")
+    if not content:
+        return None
+    return discord.ui.TextDisplay(fill_variables(content, member, guild, variables))
+
+
+def render_message(design, **options):
+    """Top-level items of a message: the outside text (if any) and the filled container.
+
+    Takes the same options as render.
+    """
+    container = render(discord.ui.Container(accent_colour=design.get("color")), design, **options)
+    text = outside_text(
+        design,
+        member=options.get("member"),
+        guild=options.get("guild"),
+        variables=options.get("variables"),
+    )
+    return [text, container] if text else [container]

discomposer/tickets.py

@@ -0,0 +1,95 @@
+"""Helpers for ticket bots. Creating and managing tickets stays in your bot."""
+
+import discord
+
+from discomposer.format import chosen_options, selects_for
+
+TICKET_PURPOSE = "ticket_categories"
+
+
+def ticket_categories(design, purpose=TICKET_PURPOSE):
+    """{value: option} for all ticket categories of a stored design."""
+    return {
+        option["value"]: option
+        for menu in selects_for(design, purpose)
+        for option in menu["options"]
+    }
+
+
+def chosen_category(design, select_id, value):
+    """The chosen category including its roles, looked up in the stored design."""
+    options = chosen_options(design, select_id, [value])
+    return options[0] if options else None
+
+
+def category_roles(guild, option):
+    """Existing roles of a category, without managed roles and @everyone."""
+    roles = []
+    for role_id in option.get("roles", []):
+        role = guild.get_role(int(role_id))
+        if role is not None and not role.is_default() and not role.managed:
+            roles.append(role)
+    return roles
+
+
+def missing_roles(guild, design, purpose=TICKET_PURPOSE):
+    """Labels of categories whose roles are missing or can't be used."""
+    problems = []
+    for option in ticket_categories(design, purpose).values():
+        if len(category_roles(guild, option)) != len(option.get("roles", [])):
+            problems.append(option["label"])
+    return problems
+
+
+def ticket_overwrites(guild, owner, roles=(), *, bot_member=None):
+    """Overwrites so that only the owner, the given roles and the bot see the channel."""
+    allowed = discord.PermissionOverwrite(
+        view_channel=True, send_messages=True, read_message_history=True, attach_files=True
+    )
+    overwrites = {
+        guild.default_role: discord.PermissionOverwrite(view_channel=False),
+        owner: allowed,
+    }
+    for role in roles:
+        overwrites[role] = allowed
+    me = bot_member or guild.me
+    if me is not None:
+        overwrites[me] = discord.PermissionOverwrite(
+            view_channel=True,
+            send_messages=True,
+            read_message_history=True,
+            attach_files=True,
+            manage_channels=True,
+        )
+    return overwrites
+
+
+def component_text(items):
+    for part in items:
+        if part.get("type") == 10:
+            yield part.get("content", "")
+        yield from component_text(part.get("components", []))
+        accessory = part.get("accessory")
+        if accessory:
+            yield from component_text([accessory])
+
+
+def transcript_markdown(title, messages, *, details=(), truncated=False):
+    """Markdown transcript. details are lines like ("Category", "Support")."""
+    lines = [f"# {title}", ""]
+    lines += [f"- {key}: {value}" for key, value in details]
+    if details:
+        lines.append("")
+    if truncated:
+        lines += ["> Incomplete.", ""]
+    for message in messages:
+        stamp = message.created_at.strftime("%d.%m.%Y %H:%M")
+        lines.append(f"## {message.author.display_name} · {stamp}")
+        text = [message.content] if message.content else []
+        text += list(component_text([c.to_dict() for c in message.components]))
+        for embed in message.embeds:
+            text += [part for part in (embed.title, embed.description) if part]
+        lines += text or ["*(no text)*"]
+        lines += [f"- Attachment: [{a.filename}]({a.url})" for a in message.attachments]
+        lines.append("")
+    return "\n".join(lines)

discomposer/variables.py

@@ -0,0 +1,98 @@
+import re
+
+import discord
+
+MEMBER_KEYS = (
+    "{username}",
+    "{nickname}",
+    "{user}",
+    "{mention}",
+    "{member_since}",
+    "{member_number}",
+    "{early_bird}",
+)
+VARIABLES = {
+    "{user}": "Display name",
+    "{username}": "Username",
+    "{nickname}": "Server nickname",
+    "{mention}": "Mention",
+    "{member_since}": "Join date",
+    "{member_number}": "Member number by join date",
+    "{early_bird}": "Share of members who joined later",
+    "{server}": "Server name",
+    "{member_count}": "Member count",
+    "{timestamp}": "Time of sending",
+    "{server_icon}": "Server icon (image)",
+    "{server_banner}": "Server banner (image)",
+}
+
+
+def _safe(text):
+    return discord.utils.escape_mentions(discord.utils.escape_markdown(text))
+
+
+UNKNOWN = "unknown"
+
+
+def _number(value):
+    return f"{value:,}"
+
+
+def _percent(value):
+    return f"{value:.1f}%"
+
+
+def member_rank(member, guild):
+    """Position by join date, or None while the member list isn't fully cached."""
+    if member.joined_at is None or not guild.chunked:
+        return None
+    return 1 + sum(
+        1 for other in guild.members if other.joined_at and other.joined_at < member.joined_at
+    )
+
+
+def member_values(member, guild):
+    values = {
+        "{username}": _safe(member.name),
+        "{nickname}": _safe(member.display_name),
+        "{user}": _safe(member.display_name),
+        "{mention}": member.mention,
+    }
+    joined = member.joined_at
+    values["{member_since}"] = f"<t:{int(joined.timestamp())}:D>" if joined else UNKNOWN
+    rank = member_rank(member, guild)
+    total = len(guild.members)
+    if rank is None or not total:
+        values["{member_number}"] = values["{early_bird}"] = UNKNOWN
+    else:
+        values["{member_number}"] = _number(rank)
+        values["{early_bird}"] = _percent((total - rank) / total * 100)
+    return values
+
+
+def variable_values(member=None, guild=None):
+    server = member.guild if member else guild
+    values = dict.fromkeys(MEMBER_KEYS, "")
+    if server:
+        values.update(
+            {
+                "{server}": _safe(server.name),
+                "{member_count}": (
+                    _number(server.member_count) if server.member_count is not None else UNKNOWN
+                ),
+                "{timestamp}": f"<t:{int(discord.utils.utcnow().timestamp())}:f>",
+                "{server_icon}": str(server.icon.url) if server.icon else "",
+                "{server_banner}": str(server.banner.url) if server.banner else "",
+            }
+        )
+    if member:
+        values.update(member_values(member, server))
+    return values
+
+
+def fill_variables(text, member=None, guild=None, extra=None):
+    """Replace variables. Unknown values stay unknown instead of being guessed."""
+    values = variable_values(member, guild)
+    if extra:
+        values.update(extra)
+    return re.sub(r"\{\w+\}", lambda match: values.get(match[0], match[0]), text)

discomposer-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: discomposer
+Version: 0.1.0
+Summary: Validate, fetch and send Discord message templates as Components V2 with discord.py.
+Project-URL: Homepage, https://github.com/caneabi/discomposer
+Project-URL: Editor, https://editor.caneabi.dev
+Project-URL: Documentation, https://github.com/caneabi/discomposer/tree/main/packages/python#readme
+Project-URL: Format, https://github.com/caneabi/discomposer/blob/main/spec/FORMAT.md
+Project-URL: Issues, https://github.com/caneabi/discomposer/issues
+Author: Cane
+License-Expression: MIT
+License-File: LICENSE
+Keywords: components-v2,discord,discord.py,embeds,message-builder,templates,tickets
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiohttp<4,>=3.9
+Requires-Dist: discord-py<3,>=2.6
+Provides-Extra: test
+Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'test'
+Requires-Dist: pytest<10,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+<h1 align="center">discomposer for discord.py</h1>
+
+<p align="center">
+  Validate, fetch and send Discord message templates as Components V2.<br>
+  Design the message in the <a href="https://editor.caneabi.dev">visual editor</a>, send it from your bot with a code.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/discomposer/"><img src="https://img.shields.io/pypi/v/discomposer?color=7b61ff" alt="PyPI"></a>
+  <a href="https://pypi.org/project/discomposer/"><img src="https://img.shields.io/pypi/pyversions/discomposer?color=7b61ff" alt="Python versions"></a>
+  <a href="https://github.com/caneabi/discomposer/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-ff7a59" alt="MIT license"></a>
+</p>
+
+discomposer only builds messages. What a button or selection does (open a ticket, hand out a role) stays in your bot.
+
+## Install
+
+```bash
+pip install discomposer
+```
+
+Requires Python 3.11+ and discord.py 2.6+.
+
+## Fetch a template and send it
+
+```python
+import discord
+from discomposer import EditorClient, MediaStore, render_message, select_rows
+
+editor = EditorClient(media=MediaStore("data/media"))
+
+async def send(channel, code):
+    design = await editor.fetch(code)  # validates and keeps a copy of every image
+    view = discord.ui.LayoutView(timeout=None)
+    for item in render_message(
+        design,
+        guild=channel.guild,
+        buttons={"ticket": lambda b: discord.ui.Button(label=b["label"], custom_id="mybot:ticket")},
+        slots={"online": "12 members online"},
+        selects=lambda menu, guild: select_rows(menu, f"mybot:{menu['id']}"),
+    ):
+        view.add_item(item)
+    await channel.send(view=view, files=editor.media.files_for(design))
+```
+
+`render_message` returns the text outside the box (if any) and the filled container. Use `render` to fill a container you created yourself.
+
+## Offer your bot's features in the editor
+
+```python
+from discomposer import guild_context
+
+link = await editor.open({
+    "title": "Ticket panel",
+    "context": {
+        **guild_context(guild),
+        "buttons": [{"id": "ticket", "label": "Open ticket"}],
+        "selects": [{"purpose": "ticket_categories", "label": "Ticket categories", "roles": "optional"}],
+    },
+    "design": {"blocks": [{"text": "## Support"}]},
+})
+```
+
+The person designs the message at `link` and gives your bot the new code.
+
+## Handle a selection
+
+Values and roles only ever come from the stored template, never from the interaction:
+
+```python
+from discomposer import category_roles, chosen_category, ticket_overwrites
+
+option = chosen_category(saved_design, "tickets", interaction.data["values"][0])
+if option:
+    roles = category_roles(guild, option)
+    channel = await guild.create_text_channel(
+        f"ticket-{interaction.user.name}",
+        overwrites=ticket_overwrites(guild, interaction.user, roles),
+    )
+```
+
+## API overview
+
+| Area | Functions |
+| --- | --- |
+| Format | `validate`, `validate_design`, `find_select`, `selects_for`, `chosen_options` |
+| Sending | `render`, `render_message`, `outside_text`, `select_rows`, `fill_variables`, `VARIABLES` |
+| Editor | `EditorClient` (`open`, `fetch`, `fetch_document`, `upload`, `adopt_images`, `expose_attachments`, `open_message`), `guild_context`, `parse_code` |
+| Images | `MediaStore` (`save`, `files_for`) |
+| Tickets | `ticket_categories`, `chosen_category`, `category_roles`, `missing_roles`, `ticket_overwrites`, `transcript_markdown` |
+
+Errors: `TemplateError` (format), `EditorError` (editor, network), `MediaError` (images). Messages are written for end users.
+
+The template format is specified in [spec/FORMAT.md](https://github.com/caneabi/discomposer/blob/main/spec/FORMAT.md). A JavaScript version for discord.js is available as [`discomposer` on npm](https://www.npmjs.com/package/discomposer).
+
+discomposer is not affiliated with or endorsed by Discord Inc.

discomposer-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+discomposer/__init__.py,sha256=8ZgeTYqxNawWjG5BTjxXFO04ySdeZR6I-7iZfOUXaRs,1500
+discomposer/editor.py,sha256=tOWPrvMsDDfbyrcmC7nDpNK4DJkcHyXlyKV9lJ6n3xQ,11889
+discomposer/format.py,sha256=xeiOXQfSokATFfMishHZOW63Z0JyZ9E-ua5IAZHxrRU,13172
+discomposer/media.py,sha256=ZwDu39_4EyoKELoOhKiNDZOeS_G5sBTr_3q5P0Z65Ns,2324
+discomposer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+discomposer/render.py,sha256=bcYx8y-UON2UizLMs7wC3LaFctKPcYCqYwQr9219G1w,6871
+discomposer/tickets.py,sha256=32R6I1H-YN48YENAiEeywyELPUTr1W2AWAGPW03Nk-s,3435
+discomposer/variables.py,sha256=JOkyTeNPMl2wslRuhuQjTuWJuLTG-zQOqC8A05y6ysc,2925
+discomposer-0.1.0.dist-info/METADATA,sha256=XRsRMYAjCVUoGYAfVP4v0qepWR--fEHND_uymCqX2VY,5224
+discomposer-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+discomposer-0.1.0.dist-info/licenses/LICENSE,sha256=4B1LJEjLK2TbWCnqS1KPKDsw3FDfJ_988OpCMhmlres,1061
+discomposer-0.1.0.dist-info/RECORD,,

discomposer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

discomposer-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.