outnoise 0.3.0__tar.gz

outnoise-0.3.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: outnoise
+Version: 0.3.0
+Summary: Outnoise - the official Python library for the Outnoise Developer Platform
+Keywords: outnoise,sdk,api,social
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0,>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"

outnoise-0.3.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "outnoise"
+version = "0.3.0"
+description = "Outnoise - the official Python library for the Outnoise Developer Platform"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = ["httpx>=0.24,<1.0"]
+keywords = ["outnoise", "sdk", "api", "social"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+outnoise = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]

outnoise-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

outnoise-0.3.0/src/outnoise/__init__.py

@@ -0,0 +1,17 @@
+"""Official Python SDK for the Outnoise Developer Platform."""
+from ._version import __version__
+from .async_client import AsyncOutnoise
+from .client import Outnoise
+from .exceptions import (APIConnectionError, APIStatusError, APITimeoutError, AuthenticationError,
+                         ConfigurationError, InvalidRequestError, MissingScopeError, NotFoundError,
+                         OutnoiseError, PermissionDeniedError, RateLimitError, ServerError)
+from .commands import Command, Option
+from .components import ActionRow, Button
+from .models import AttrDict, Page
+
+__all__ = [
+    "Outnoise", "AsyncOutnoise", "Page", "AttrDict", "Button", "ActionRow", "Command", "Option", "__version__",
+    "OutnoiseError", "ConfigurationError", "APIConnectionError", "APITimeoutError", "APIStatusError",
+    "InvalidRequestError", "AuthenticationError", "PermissionDeniedError", "MissingScopeError",
+    "NotFoundError", "RateLimitError", "ServerError",
+]

outnoise-0.3.0/src/outnoise/_base.py

@@ -0,0 +1,126 @@
+"""Configuration, request building and response handling shared by the sync and async clients."""
+import json
+import os
+import random
+import time  # noqa: F401  (patched in tests)
+from typing import Any, Dict, Optional, Tuple
+
+import httpx
+
+from ._version import __version__
+from .exceptions import APIStatusError, ConfigurationError, OutnoiseError, error_for_status
+from .models import Page, wrap
+
+# The beta deployment. Override with base_url=... or OUTNOISE_BASE_URL once you use another host.
+DEFAULT_BASE_URL = "https://beta-chatx.hostmybotprojects.net/api/v1"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+MAX_RETRY_WAIT = 30.0           # never sleep longer than this for a single retry
+_RETRY_STATUS = (502, 503, 504)  # transient server errors; retried for GET only
+
+
+class ClientConfig:
+    def __init__(self, api_key, access_token, base_url, timeout, max_retries, max_retry_wait):
+        api_key = api_key or os.environ.get("OUTNOISE_API_KEY") or None
+        access_token = access_token or os.environ.get("OUTNOISE_ACCESS_TOKEN") or None
+        if api_key and access_token:
+            raise ConfigurationError("Pass either api_key (bot token) or access_token (OAuth2), not both.")
+        if not api_key and not access_token:
+            raise ConfigurationError(
+                "No credentials. Pass api_key=... (bot token) or access_token=... (OAuth2), "
+                "or set OUTNOISE_API_KEY / OUTNOISE_ACCESS_TOKEN.")
+        base_url = (base_url or os.environ.get("OUTNOISE_BASE_URL") or DEFAULT_BASE_URL).strip().rstrip("/")
+        if not base_url.startswith(("http://", "https://")):
+            raise ConfigurationError(f"base_url must start with http:// or https:// (got {base_url!r}).")
+        if timeout is not None and timeout <= 0:
+            raise ConfigurationError("timeout must be positive.")
+        if max_retries < 0:
+            raise ConfigurationError("max_retries must be 0 or greater.")
+        self.base_url = base_url
+        self.timeout = DEFAULT_TIMEOUT if timeout is None else timeout
+        self.max_retries = max_retries
+        self.max_retry_wait = max_retry_wait
+        self.headers = {
+            "Authorization": ("Bot " + api_key) if api_key else ("Bearer " + access_token),
+            "Accept": "application/json",
+            "User-Agent": f"outnoise-python/{__version__}",
+        }
+
+    def __repr__(self):  # never print credentials
+        return f"<ClientConfig base_url={self.base_url!r}>"
+
+
+def clean_params(params: Optional[Dict[str, Any]]) -> Dict[str, str]:
+    out = {}
+    for k, v in (params or {}).items():
+        if v is None:
+            continue
+        out[k] = ("1" if v else "0") if isinstance(v, bool) else str(v)
+    return out
+
+
+def retry_delay(attempt: int, retry_after: Optional[float], max_wait: float) -> Optional[float]:
+    """Seconds to wait before retry number `attempt` (0-based), or None if we should give up."""
+    if retry_after is not None:
+        return None if retry_after > max_wait else max(0.0, retry_after)
+    return min(max_wait, 0.5 * (2 ** attempt)) * (0.75 + random.random() / 2)
+
+
+def parse_retry_after(headers) -> Optional[float]:
+    raw = headers.get("Retry-After") if headers is not None else None
+    try:
+        return float(raw) if raw is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def build_error(resp: "httpx.Response") -> APIStatusError:
+    body: Any = None
+    try:
+        body = resp.json()
+    except ValueError:
+        pass
+    message, code = None, None
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict):                     # tolerate {"error": {"message": ...}}
+            message, code = err.get("message"), err.get("code")
+        else:
+            message = err if isinstance(err, str) else body.get("message")
+            code = body.get("code")
+        if not code and isinstance(err, str) and body.get("error_description"):   # OAuth2 style
+            code, message = err, body["error_description"]
+    if not message:
+        snippet = (resp.text or "").strip().replace("\n", " ")[:200]
+        message = snippet or f"HTTP {resp.status_code}"
+    return error_for_status(resp.status_code, message, code, body, resp.headers, parse_retry_after(resp.headers))
+
+
+def parse_success(resp: "httpx.Response") -> Any:
+    try:
+        body = resp.json()
+    except ValueError:
+        raise OutnoiseError(f"The API returned a non-JSON response (HTTP {resp.status_code}).") from None
+    if not isinstance(body, dict) or "data" not in body:
+        raise OutnoiseError("Unexpected API response shape (missing 'data').")
+    data = wrap(body["data"])
+    if isinstance(body.get("paging"), dict) and isinstance(data, list):
+        return Page(data, body["paging"])
+    return data
+
+
+def request_kwargs(method: str, path: str, params, json_body) -> Tuple[str, Dict[str, Any]]:
+    kw: Dict[str, Any] = {}
+    q = clean_params(params)
+    if q:
+        kw["params"] = q
+    if json_body is not None:
+        kw["json"] = json_body
+    return method.upper(), kw
+
+
+def validate_page_args(limit: int, offset: int):
+    if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= 50:
+        raise ValueError("limit must be an integer between 1 and 50.")
+    if not isinstance(offset, int) or isinstance(offset, bool) or offset < 0:
+        raise ValueError("offset must be an integer of 0 or greater.")

outnoise-0.3.0/src/outnoise/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

outnoise-0.3.0/src/outnoise/async_client.py

@@ -0,0 +1,116 @@
+"""Asynchronous client (same API as :class:`outnoise.Outnoise`, use with ``await`` / ``async for``)."""
+import asyncio
+from typing import Any, AsyncIterator, Dict, Optional
+
+import httpx
+
+from . import _base, resources
+from .exceptions import APIConnectionError, APITimeoutError
+
+
+class AsyncOutnoise:
+    """Asynchronous Outnoise API client.
+
+    >>> async with AsyncOutnoise(api_key="YOUR_BOT_TOKEN") as client:
+    ...     me = await client.users.me()
+    ...     async for post in client.posts.iter(max_items=100):
+    ...         print(post.content)
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, access_token: Optional[str] = None,
+                 base_url: Optional[str] = None, timeout: Optional[float] = None,
+                 max_retries: int = _base.DEFAULT_MAX_RETRIES, max_retry_wait: float = _base.MAX_RETRY_WAIT,
+                 http_client: Optional[httpx.AsyncClient] = None):
+        self._cfg = _base.ClientConfig(api_key, access_token, base_url, timeout, max_retries, max_retry_wait)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=self._cfg.timeout)
+        self._explicit_timeout = timeout if (timeout is not None or http_client is None) else None
+        resources.attach(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._cfg.base_url
+
+    def __repr__(self):
+        return f"<AsyncOutnoise base_url={self._cfg.base_url!r}>"
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def _call(self, method: str, path: str, params: Optional[Dict[str, Any]] = None,
+                    json_body: Optional[Any] = None) -> Any:
+        method, kw = _base.request_kwargs(method, path, params, json_body)
+        if self._explicit_timeout is not None:
+            kw["timeout"] = self._explicit_timeout
+        url = self._cfg.base_url + path
+        idempotent = method in ("GET", "HEAD")
+        attempt = 0
+        while True:
+            try:
+                resp = await self._http.request(method, url, headers=self._cfg.headers, **kw)
+            except httpx.TimeoutException as exc:
+                if idempotent and attempt < self._cfg.max_retries:
+                    await self._wait(attempt)
+                    attempt += 1
+                    continue
+                raise APITimeoutError(f"Request to {path} timed out.") from exc
+            except httpx.TransportError as exc:
+                if idempotent and attempt < self._cfg.max_retries:
+                    await self._wait(attempt)
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"Could not connect to {self._cfg.base_url}: {exc}") from exc
+            if 200 <= resp.status_code < 300:
+                return _base.parse_success(resp)
+            retryable = resp.status_code == 429 or (idempotent and resp.status_code in _base._RETRY_STATUS)
+            if retryable and attempt < self._cfg.max_retries:
+                delay = _base.retry_delay(attempt, _base.parse_retry_after(resp.headers), self._cfg.max_retry_wait)
+                if delay is not None:
+                    await asyncio.sleep(delay)
+                    attempt += 1
+                    continue
+            raise _base.build_error(resp)
+
+    async def _wait(self, attempt: int) -> None:
+        delay = _base.retry_delay(attempt, None, self._cfg.max_retry_wait)
+        if delay:
+            await asyncio.sleep(delay)
+
+    async def _iterate(self, path: str, params: Dict[str, Any], page_size: int,
+                       max_items: Optional[int]) -> AsyncIterator[Any]:
+        _base.validate_page_args(page_size, 0)
+        offset, yielded = 0, 0
+        while True:
+            page = await self._call("GET", path, params=dict(params, limit=page_size, offset=offset))
+            for item in page:
+                yield item
+                yielded += 1
+                if max_items is not None and yielded >= max_items:
+                    return
+            if not page.has_more:
+                return
+            offset = page.next_offset
+
+    async def _poll_interactions(self, interval: float, after: int, limit: int, include_responded: bool,
+                                 max_items: Optional[int]) -> AsyncIterator[Any]:
+        cursor, yielded = after, 0
+        while True:
+            page = await self.interactions.list(after=cursor, limit=limit)
+            for it in page:
+                cursor = max(cursor, it["id"])
+                if it.get("responded") and not include_responded:
+                    continue
+                yield it
+                yielded += 1
+                if max_items is not None and yielded >= max_items:
+                    return
+            cursor = max(cursor, page.paging.get("next_after") or 0)
+            if not page.has_more:
+                await asyncio.sleep(interval)

outnoise-0.3.0/src/outnoise/client.py

@@ -0,0 +1,118 @@
+"""Synchronous client."""
+import time
+from typing import Any, Dict, Iterator, Optional
+
+import httpx
+
+from . import _base, resources
+from .exceptions import APIConnectionError, APITimeoutError
+
+
+class Outnoise:
+    """Synchronous Outnoise API client.
+
+    >>> client = Outnoise(api_key="YOUR_BOT_TOKEN")
+    >>> client.users.me()
+
+    Pass ``api_key`` (a bot token) **or** ``access_token`` (an OAuth2 token). Both can also come from the
+    ``OUTNOISE_API_KEY`` / ``OUTNOISE_ACCESS_TOKEN`` environment variables, and the API address from
+    ``OUTNOISE_BASE_URL``.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, access_token: Optional[str] = None,
+                 base_url: Optional[str] = None, timeout: Optional[float] = None,
+                 max_retries: int = _base.DEFAULT_MAX_RETRIES, max_retry_wait: float = _base.MAX_RETRY_WAIT,
+                 http_client: Optional[httpx.Client] = None):
+        self._cfg = _base.ClientConfig(api_key, access_token, base_url, timeout, max_retries, max_retry_wait)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(timeout=self._cfg.timeout)
+        self._explicit_timeout = timeout if (timeout is not None or http_client is None) else None
+        resources.attach(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._cfg.base_url
+
+    def __repr__(self):
+        return f"<Outnoise base_url={self._cfg.base_url!r}>"
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    # ── request machinery ────────────────────────────────────────────────────
+    def _call(self, method: str, path: str, params: Optional[Dict[str, Any]] = None,
+              json_body: Optional[Any] = None) -> Any:
+        method, kw = _base.request_kwargs(method, path, params, json_body)
+        if self._explicit_timeout is not None:
+            kw["timeout"] = self._explicit_timeout
+        url = self._cfg.base_url + path
+        idempotent = method in ("GET", "HEAD")
+        attempt = 0
+        while True:
+            try:
+                resp = self._http.request(method, url, headers=self._cfg.headers, **kw)
+            except httpx.TimeoutException as exc:
+                if idempotent and attempt < self._cfg.max_retries:
+                    self._wait(attempt, None)
+                    attempt += 1
+                    continue
+                raise APITimeoutError(f"Request to {path} timed out.") from exc
+            except httpx.TransportError as exc:
+                if idempotent and attempt < self._cfg.max_retries:
+                    self._wait(attempt, None)
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"Could not connect to {self._cfg.base_url}: {exc}") from exc
+            if 200 <= resp.status_code < 300:
+                return _base.parse_success(resp)
+            retryable = resp.status_code == 429 or (idempotent and resp.status_code in _base._RETRY_STATUS)
+            if retryable and attempt < self._cfg.max_retries:
+                delay = _base.retry_delay(attempt, _base.parse_retry_after(resp.headers), self._cfg.max_retry_wait)
+                if delay is not None:
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+            raise _base.build_error(resp)
+
+    def _wait(self, attempt: int, retry_after: Optional[float]) -> None:
+        delay = _base.retry_delay(attempt, retry_after, self._cfg.max_retry_wait)
+        if delay:
+            time.sleep(delay)
+
+    def _iterate(self, path: str, params: Dict[str, Any], page_size: int, max_items: Optional[int]) -> Iterator[Any]:
+        _base.validate_page_args(page_size, 0)
+        offset, yielded = 0, 0
+        while True:
+            page = self._call("GET", path, params=dict(params, limit=page_size, offset=offset))
+            for item in page:
+                yield item
+                yielded += 1
+                if max_items is not None and yielded >= max_items:
+                    return
+            if not page.has_more:
+                return
+            offset = page.next_offset
+
+    def _poll_interactions(self, interval: float, after: int, limit: int, include_responded: bool,
+                           max_items: Optional[int]) -> Iterator[Any]:
+        cursor, yielded = after, 0
+        while True:
+            page = self.interactions.list(after=cursor, limit=limit)
+            for it in page:
+                cursor = max(cursor, it["id"])
+                if it.get("responded") and not include_responded:
+                    continue
+                yield it
+                yielded += 1
+                if max_items is not None and yielded >= max_items:
+                    return
+            cursor = max(cursor, page.paging.get("next_after") or 0)
+            if not page.has_more:
+                time.sleep(interval)

outnoise-0.3.0/src/outnoise/commands.py

@@ -0,0 +1,118 @@
+"""Slash commands for your bot.
+
+    from outnoise import Command, Option
+
+    client.commands.sync([
+        Command("ping", "Check that the bot is alive"),
+        Command("poll", "Start a poll", options=[
+            Option("question", "What to ask", required=True),
+            Option("days", "How long it runs", type="integer", choices=[("1 day", 1), ("3 days", 3)]),
+            Option("anonymous", "Hide who voted", type="boolean"),
+        ]),
+    ])
+
+Members run them by typing ``/`` in a group DM your bot belongs to; you receive them as interactions
+(``click.type == "slash_command"``). Slash commands exist only in group DMs - not in posts, comments,
+one-to-one chats or auto posts.
+"""
+import re
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Union
+
+OPTION_TYPES = ("string", "integer", "boolean")
+MAX_COMMANDS = 25
+MAX_OPTIONS = 10
+MAX_CHOICES = 25
+_NAME = re.compile(r"^[a-z0-9_-]{1,32}$")
+
+Choice = Union[Tuple[str, Any], Dict[str, Any]]
+
+
+class Option:
+    """One argument of a command. ``choices`` may be ``[(label, value), ...]`` or ``[{"name":..., "value":...}]``."""
+
+    def __init__(self, name: str, description: str, *, type: str = "string", required: bool = False,
+                 choices: Optional[Sequence[Choice]] = None):
+        self.name = name
+        self.description = description
+        self.type = type
+        self.required = required
+        self.choices = choices
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {"name": self.name, "description": self.description, "type": self.type,
+                             "required": bool(self.required)}
+        if self.choices:
+            d["choices"] = [c if isinstance(c, dict) else {"name": c[0], "value": c[1]} for c in self.choices]
+        return d
+
+    def __repr__(self):
+        return f"<Option {self.name!r} {self.type}{' required' if self.required else ''}>"
+
+
+class Command:
+    """A slash command: ``/name`` plus an optional list of :class:`Option`."""
+
+    def __init__(self, name: str, description: str, options: Optional[Iterable[Any]] = None):
+        self.name = name
+        self.description = description
+        self.options = list(options or [])
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"name": self.name, "description": self.description,
+                "options": [o.to_dict() if isinstance(o, Option) else dict(o) for o in self.options]}
+
+    def __repr__(self):
+        return f"<Command /{self.name}>"
+
+
+def _check_name(value: Any, what: str) -> str:
+    name = str(value or "").strip().lower().lstrip("/") if what == "command" else str(value or "").strip().lower()
+    if not _NAME.match(name):
+        raise ValueError(f"A {what} name must be 1-32 characters: lowercase letters, numbers, _ and -.")
+    return name
+
+
+def normalize_one(command: Any) -> Dict[str, Any]:
+    d = command.to_dict() if isinstance(command, Command) else dict(command) if isinstance(command, dict) else None
+    if d is None:
+        raise ValueError("A command must be a Command or a dict.")
+    name = _check_name(d.get("name"), "command")
+    desc = " ".join(str(d.get("description") or "").split())
+    if not desc or len(desc) > 100:
+        raise ValueError(f"/{name}: the description must be 1-100 characters.")
+    raw_opts = d.get("options") or []
+    if len(raw_opts) > MAX_OPTIONS:
+        raise ValueError(f"/{name}: at most {MAX_OPTIONS} options are allowed.")
+    options, seen = [], set()
+    for o in raw_opts:
+        od = o.to_dict() if isinstance(o, Option) else dict(o)
+        oname = _check_name(od.get("name"), "option")
+        if oname in seen:
+            raise ValueError(f"/{name}: option {oname!r} is listed twice.")
+        seen.add(oname)
+        odesc = " ".join(str(od.get("description") or "").split())
+        if not odesc or len(odesc) > 100:
+            raise ValueError(f"/{name} {oname}: the description must be 1-100 characters.")
+        otype = od.get("type") or "string"
+        if otype not in OPTION_TYPES:
+            raise ValueError(f"/{name} {oname}: type must be one of: " + ", ".join(OPTION_TYPES))
+        item: Dict[str, Any] = {"name": oname, "description": odesc, "type": otype, "required": bool(od.get("required"))}
+        if od.get("choices"):
+            if otype == "boolean" or len(od["choices"]) > MAX_CHOICES:
+                raise ValueError(f"/{name} {oname}: choices are not allowed for boolean options, and at most {MAX_CHOICES} are allowed.")
+            item["choices"] = od["choices"]
+        options.append(item)
+    return {"name": name, "description": desc, "options": options}
+
+
+def normalize(commands: Iterable[Any]) -> List[Dict[str, Any]]:
+    out, seen = [], set()
+    for c in commands:
+        d = normalize_one(c)
+        if d["name"] in seen:
+            raise ValueError(f"The command /{d['name']} is listed twice.")
+        seen.add(d["name"])
+        out.append(d)
+    if len(out) > MAX_COMMANDS:
+        raise ValueError(f"At most {MAX_COMMANDS} commands are allowed.")
+    return out

outnoise-0.3.0/src/outnoise/components.py

@@ -0,0 +1,104 @@
+"""Message buttons for group DMs.
+
+    from outnoise import Button
+
+    client.group_dms.send(group_id, "Movie tonight?", components=[
+        Button("Yes", custom_id="vote_yes", style="success"),
+        Button("No", custom_id="vote_no", style="danger"),
+        Button("Docs", style="link", url="https://example.com/docs"),
+    ])
+
+A flat list of buttons is one row; pass a list of lists for several rows (max 5 rows x 5 buttons).
+Plain dicts work too: ``{"label": "Yes", "custom_id": "vote_yes", "style": "success"}``.
+"""
+import re
+from typing import Any, Dict, Iterable, List, Optional
+
+STYLES = ("primary", "secondary", "success", "danger", "link")
+MAX_ROWS = 5
+MAX_PER_ROW = 5
+_CUSTOM_ID = re.compile(r"^[A-Za-z0-9_:.\-]{1,64}$")
+
+
+class Button:
+    """A clickable button. Link buttons open a URL; every other style sends an interaction to your bot."""
+
+    def __init__(self, label: str, custom_id: Optional[str] = None, *, style: Optional[str] = None,
+                 url: Optional[str] = None, disabled: bool = False):
+        self.label = label
+        self.custom_id = custom_id
+        self.style = style or ("link" if url else "primary")
+        self.url = url
+        self.disabled = disabled
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {"label": self.label, "style": self.style}
+        if self.style == "link":
+            d["url"] = self.url
+        else:
+            d["custom_id"] = self.custom_id
+            if self.disabled:
+                d["disabled"] = True
+        return d
+
+    def __repr__(self):
+        return f"<Button {self.label!r} style={self.style!r}>"
+
+
+class ActionRow(list):
+    """A row of buttons (just a list, provided for readability)."""
+
+    def __init__(self, *buttons):
+        super().__init__(buttons)
+
+
+def _button_dict(b: Any) -> Dict[str, Any]:
+    d = b.to_dict() if isinstance(b, Button) else dict(b) if isinstance(b, dict) else None
+    if d is None:
+        raise ValueError("Every button must be a Button or a dict.")
+    label = " ".join(str(d.get("label") or "").split())
+    if not label or len(label) > 40:
+        raise ValueError("A button label must be 1-40 characters.")
+    style = d.get("style") or ("link" if d.get("url") else "primary")
+    if style not in STYLES:
+        raise ValueError("Button style must be one of: " + ", ".join(STYLES))
+    out: Dict[str, Any] = {"label": label, "style": style}
+    if style == "link":
+        url = str(d.get("url") or "")
+        if not url.startswith("https://"):
+            raise ValueError("A link button needs an https:// url.")
+        out["url"] = url
+    else:
+        cid = str(d.get("custom_id") or "")
+        if not _CUSTOM_ID.match(cid):
+            raise ValueError("A button needs a custom_id of 1-64 letters, numbers and _ : . -")
+        out["custom_id"] = cid
+        if d.get("disabled"):
+            out["disabled"] = True
+    return out
+
+
+def normalize(components: Optional[Iterable[Any]]) -> Optional[List[List[Dict[str, Any]]]]:
+    """Buttons / dicts / rows -> the list-of-rows the API expects. ``None`` stays ``None``; ``[]`` clears buttons."""
+    if components is None:
+        return None
+    items = list(components)
+    if items and all(isinstance(x, (Button, dict)) for x in items):
+        items = [items]                                   # flat list = one row
+    if len(items) > MAX_ROWS:
+        raise ValueError(f"At most {MAX_ROWS} rows of buttons are allowed.")
+    rows, seen = [], set()
+    for row in items:
+        if not isinstance(row, (list, tuple)) or not row:
+            raise ValueError("Every row must be a non-empty list of buttons.")
+        if len(row) > MAX_PER_ROW:
+            raise ValueError(f"At most {MAX_PER_ROW} buttons are allowed per row.")
+        out = [_button_dict(b) for b in row]
+        for b in out:
+            cid = b.get("custom_id")
+            if cid:
+                if cid in seen:
+                    raise ValueError(f"custom_id {cid!r} is used by more than one button.")
+                seen.add(cid)
+        rows.append(out)
+    return rows