pyyapper 1.0.0__py3-none-any.whl

pyyapper/buttons.py

@@ -0,0 +1,117 @@
+"""Button and Row builders for PyYapper.
+
+Buttons are attached to messages via ``components`` (a list of :class:`Row`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class Button:
+    """A clickable button.
+
+    Use the class-method shortcuts for the common cases::
+
+        Button.primary("Go", "go")
+        Button.link("Rules", "https://example.com")
+    """
+
+    STYLES = ("primary", "secondary", "success", "danger", "link")
+
+    def __init__(self, data: dict[str, Any] | None = None) -> None:
+        self.data: dict[str, Any] = {"type": "button", "style": "secondary"}
+        if data:
+            self.data.update(data)
+
+    # -- shortcuts ---------------------------------------------------------
+    @classmethod
+    def primary(cls, label: str, custom_id: str) -> "Button":
+        return cls({"style": "primary", "label": label, "custom_id": custom_id})
+
+    @classmethod
+    def secondary(cls, label: str, custom_id: str) -> "Button":
+        return cls({"style": "secondary", "label": label, "custom_id": custom_id})
+
+    @classmethod
+    def success(cls, label: str, custom_id: str) -> "Button":
+        return cls({"style": "success", "label": label, "custom_id": custom_id})
+
+    @classmethod
+    def danger(cls, label: str, custom_id: str) -> "Button":
+        return cls({"style": "danger", "label": label, "custom_id": custom_id})
+
+    @classmethod
+    def link(cls, label: str, url: str) -> "Button":
+        return cls({"style": "link", "label": label, "url": url})
+
+    # -- chainable setters -------------------------------------------------
+    def style(self, s: str) -> "Button":
+        if s not in self.STYLES:
+            raise ValueError(f"Unknown button style: {s!r}")
+        self.data["style"] = s
+        return self
+
+    def label(self, text: str) -> "Button":
+        self.data["label"] = str(text)
+        return self
+
+    def emoji(self, e: str) -> "Button":
+        self.data["emoji"] = str(e)
+        return self
+
+    def id(self, custom_id: str) -> "Button":  # noqa: A003 - mirrors JS
+        self.data["custom_id"] = str(custom_id)
+        if "url" in self.data:
+            del self.data["url"]
+        return self
+
+    def url(self, u: str) -> "Button":  # noqa: A003
+        self.data["style"] = "link"
+        self.data["url"] = str(u)
+        self.data.pop("custom_id", None)
+        return self
+
+    def disabled(self, on: bool = True) -> "Button":
+        self.data["disabled"] = bool(on)
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self.data)
+
+    def toJSON(self) -> dict[str, Any]:
+        return self.to_dict()
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"Button({self.data!r})"
+
+
+class Row:
+    """A row of up to 5 buttons."""
+
+    def __init__(self, *buttons: Any) -> None:
+        self.buttons: list[Any] = []
+        for b in buttons:
+            self.buttons.extend(b if isinstance(b, list) else [b])
+
+    def add(self, *buttons: Any) -> "Row":
+        for b in buttons:
+            self.buttons.extend(b if isinstance(b, list) else [b])
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        out = []
+        for b in self.buttons:
+            if hasattr(b, "to_dict"):
+                out.append(b.to_dict())
+            elif hasattr(b, "toJSON"):
+                out.append(b.toJSON())
+            else:
+                out.append(b)
+        return {"type": "row", "components": out}
+
+    def toJSON(self) -> dict[str, Any]:
+        return self.to_dict()
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"Row({self.buttons!r})"

pyyapper/embeds.py

@@ -0,0 +1,124 @@
+"""Embed (card) builder for PyYapper.
+
+Mirrors the JS SDK's ``Embed`` class: every setter returns ``self`` so calls
+chain, and :meth:`to_dict` produces the JSON payload Yapper expects.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+_NAMED_COLORS = {
+    "red": 0xED4245,
+    "green": 0x57F287,
+    "blue": 0x5865F2,
+    "yellow": 0xFEE75C,
+    "purple": 0x9B59B6,
+    "orange": 0xE67E22,
+    "grey": 0x95A5A6,
+    "gray": 0x95A5A6,
+    "blurple": 0x5865F2,
+}
+
+
+class Embed:
+    """A card that can be attached to a message.
+
+    Example::
+
+        embed = (
+            Embed()
+            .title("Match result")
+            .description("**Blue** won 3-1.")
+            .color("#5865f2")
+            .field("MVP", "<@user-id>", inline=True)
+            .footer("Season 2")
+        )
+    """
+
+    def __init__(self, data: dict[str, Any] | None = None) -> None:
+        self.data: dict[str, Any] = dict(data) if data else {}
+
+    # -- chainable setters -------------------------------------------------
+    def title(self, text: str) -> "Embed":
+        self.data["title"] = str(text)
+        return self
+
+    def description(self, text: str) -> "Embed":
+        self.data["description"] = str(text)
+        return self
+
+    def url(self, url: str) -> "Embed":
+        self.data["url"] = str(url)
+        return self
+
+    def color(self, color: int | str) -> "Embed":
+        if isinstance(color, bool):
+            raise TypeError("color must be an int or str")
+        if isinstance(color, int):
+            self.data["color"] = color
+            return self
+        name = str(color).strip().lower()
+        if name in _NAMED_COLORS:
+            self.data["color"] = _NAMED_COLORS[name]
+            return self
+        hexed = name.lstrip("#").lstrip("0x").lstrip("x")
+        # handle 0x prefix already stripped above loosely
+        if name.startswith("0x"):
+            hexed = name[2:]
+        try:
+            self.data["color"] = int(hexed, 16)
+        except ValueError:
+            raise ValueError(f"Unknown color: {color!r}")
+        return self
+
+    def field(self, name: str, value: str, inline: bool = False) -> "Embed":
+        self.data.setdefault("fields", []).append(
+            {"name": str(name), "value": str(value), "inline": bool(inline)}
+        )
+        return self
+
+    def author(self, name: str, *, url: str | None = None, icon: str | None = None) -> "Embed":
+        payload: dict[str, Any] = {"name": str(name)}
+        if url is not None:
+            payload["url"] = str(url)
+        if icon is not None:
+            payload["icon_url"] = str(icon)
+        self.data["author"] = payload
+        return self
+
+    def footer(self, text: str, icon: str | None = None) -> "Embed":
+        payload: dict[str, Any] = {"text": str(text)}
+        if icon is not None:
+            payload["icon_url"] = str(icon)
+        self.data["footer"] = payload
+        return self
+
+    def thumbnail(self, url: str) -> "Embed":
+        self.data["thumbnail"] = {"url": str(url)}
+        return self
+
+    def image(self, url: str) -> "Embed":
+        self.data["image"] = {"url": str(url)}
+        return self
+
+    def timestamp(self, when: datetime | str | None = None) -> "Embed":
+        if when is None:
+            when = datetime.now(timezone.utc)
+        if isinstance(when, datetime):
+            if when.tzinfo is None:
+                when = when.replace(tzinfo=timezone.utc)
+            self.data["timestamp"] = when.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+        else:
+            self.data["timestamp"] = str(when)
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self.data)
+
+    def toJSON(self) -> dict[str, Any]:  # parity with JS
+        return self.to_dict()
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"Embed({self.data!r})"

pyyapper/errors.py

@@ -0,0 +1,90 @@
+"""Exception types raised by PyYapper.
+
+All exceptions derive from :class:`YapperError` so callers can catch the whole
+family with a single ``except``. HTTP failures are represented by
+:class:`HTTPException` (and its subclasses) which carry the response ``status``,
+the parsed ``error`` message and, when the server provides one, ``retry_after``.
+"""
+
+from __future__ import annotations
+
+
+class YapperError(Exception):
+    """Base class for every error raised by PyYapper."""
+
+
+class ConfigurationError(YapperError):
+    """Raised when the bot is configured incorrectly (e.g. a bad token)."""
+
+
+class HTTPException(YapperError):
+    """An HTTP request to the Yapper API failed.
+
+    Attributes:
+        status: HTTP status code returned by the server.
+        error: Human readable error message from the server (or a fallback).
+        retry_after: Seconds to wait before retrying, when the server sent one.
+        method: HTTP method of the failed request.
+        path: API path of the failed request.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        error: str = "",
+        *,
+        method: str = "",
+        path: str = "",
+        retry_after: float | None = None,
+    ) -> None:
+        self.status = status
+        self.error = error or f"HTTP {status}"
+        self.method = method
+        self.path = path
+        self.retry_after = retry_after
+        super().__init__(f"{method} {path} failed ({status}): {self.error}".strip())
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"{type(self).__name__}(status={self.status}, error={self.error!r})"
+
+
+class BadRequest(HTTPException):
+    """400 - the request body was invalid."""
+
+
+class Unauthorized(HTTPException):
+    """401 - missing or wrong token."""
+
+
+class Forbidden(HTTPException):
+    """403 - the bot is not in that server, or its roles do not allow it."""
+
+
+class NotFound(HTTPException):
+    """404 - no such thing, or the bot cannot see it."""
+
+
+class RateLimited(HTTPException):
+    """429 - slow down. ``retry_after`` says how many seconds to wait."""
+
+
+class ServerError(HTTPException):
+    """5xx - something went wrong on Yapper's side."""
+
+
+# Status code -> exception class mapping used by the HTTP layer.
+STATUS_TO_EXC: dict[int, type[HTTPException]] = {
+    400: BadRequest,
+    401: Unauthorized,
+    403: Forbidden,
+    404: NotFound,
+    429: RateLimited,
+}
+
+
+def exception_for_status(status: int) -> type[HTTPException]:
+    if status in STATUS_TO_EXC:
+        return STATUS_TO_EXC[status]
+    if 500 <= status < 600:
+        return ServerError
+    return HTTPException

pyyapper/http.py

@@ -0,0 +1,200 @@
+"""HTTP client used by PyYapper.
+
+Wraps :mod:`aiohttp` with the Yapper-specific conventions:
+
+* ``Authorization: Bot <token>`` on every request.
+* JSON request/response bodies.
+* Automatic retry of ``429`` responses that carry a ``Retry-After`` header
+  (up to ``retries`` times).
+* Translation of HTTP error statuses into the exception types in
+  :mod:`pyyapper.errors`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+from typing import Any, Optional
+
+import aiohttp
+
+from .errors import (
+    HTTPException,
+    exception_for_status,
+)
+
+DEFAULT_BASE = "https://www.yapper.website/api/bot/v1"
+USER_AGENT = "pyyapper/1.0"
+
+
+def _backoff(n: int) -> float:
+    """Exponential backoff with jitter, capped at 30s."""
+    base = min(30_000, 1000 * (2 ** (n - 1))) / 1000.0
+    return base * (0.75 + random.random() * 0.5)
+
+
+class HTTPClient:
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = DEFAULT_BASE,
+        session: Optional[aiohttp.ClientSession] = None,
+        log: bool = True,
+    ) -> None:
+        if not token or not str(token).startswith("yb_"):
+            raise ValueError("Pass your bot token (starts with yb_). Get one in Settings -> Developer.")
+        self.token = str(token).strip()
+        self.base_url = base_url.rstrip("/")
+        self.log = log
+        self._session = session
+        self._owns_session = session is None
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+        return self._session
+
+    async def close(self) -> None:
+        if self._owns_session and self._session is not None and not self._session.closed:
+            await self._session.close()
+        self._session = None
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        headers: Optional[dict[str, str]] = None,
+        timeout: float = 30.0,
+        retries: int = 3,
+        content_type: Optional[str] = None,
+    ) -> Any:
+        session = await self._get_session()
+        url = self.base_url + path
+        hdrs = {
+            "Authorization": f"Bot {self.token}",
+            "User-Agent": USER_AGENT,
+        }
+        if headers:
+            hdrs.update(headers)
+        data = None
+        if body is not None and not isinstance(body, (bytes, bytearray)):
+            # JSON body unless caller already provided bytes
+            if content_type is None:
+                content_type = "application/json"
+            data = json.dumps(body)
+        elif body is not None:
+            data = body
+        if content_type:
+            hdrs.setdefault("Content-Type", content_type)
+
+        for attempt in range(retries + 1):
+            try:
+                async with session.request(
+                    method,
+                    url,
+                    data=data,
+                    headers=hdrs,
+                    timeout=aiohttp.ClientTimeout(total=timeout),
+                ) as res:
+                    raw = await res.read()
+                    text = raw.decode("utf-8", errors="replace") if raw else ""
+                    try:
+                        payload = json.loads(text) if text else {}
+                    except json.JSONDecodeError:
+                        payload = {}
+                    if res.status < 400:
+                        return payload
+                    # error path
+                    err_msg = ""
+                    if isinstance(payload, dict):
+                        err_msg = payload.get("error") or payload.get("message") or ""
+                    retry_after = None
+                    ra = res.headers.get("Retry-After")
+                    if ra is not None:
+                        try:
+                            retry_after = float(ra)
+                        except ValueError:
+                            retry_after = None
+                    # retry on 429 with Retry-After
+                    if res.status == 429 and retry_after and retry_after > 0 and retry_after <= 60 and attempt < retries:
+                        if self.log:
+                            print(f"[pyyapper] rate limited, retrying {method} {path} in {retry_after}s")
+                        await asyncio.sleep(retry_after)
+                        continue
+                    exc_cls = exception_for_status(res.status)
+                    raise exc_cls(
+                        res.status,
+                        err_msg or f"{method} {path} failed ({res.status})",
+                        method=method,
+                        path=path,
+                        retry_after=retry_after,
+                    )
+            except (aiohttp.ClientError, asyncio.TimeoutError) as e:
+                if attempt < retries:
+                    await asyncio.sleep(_backoff(attempt + 1))
+                    continue
+                raise HTTPException(0, f"network error: {e}", method=method, path=path)
+
+        # Should not reach here
+        raise HTTPException(0, "request failed", method=method, path=path)
+
+    async def upload(
+        self,
+        method: str,
+        path: str,
+        image: Any,
+        content_type: Optional[str] = None,
+        *,
+        timeout: float = 60.0,
+    ) -> Any:
+        """Upload an image (bytes, path, or Blob-like)."""
+        import os
+
+        bytes_data = image
+        ct = content_type
+        if isinstance(image, str):
+            # file path
+            with open(image, "rb") as f:
+                bytes_data = f.read()
+            if ct is None:
+                ext = os.path.splitext(image)[1].lstrip(".").lower()
+                ct = {
+                    "png": "image/png",
+                    "jpg": "image/jpeg",
+                    "jpeg": "image/jpeg",
+                    "gif": "image/gif",
+                    "webp": "image/webp",
+                }.get(ext)
+        elif hasattr(image, "read"):
+            bytes_data = image.read()
+            if hasattr(image, "seek"):
+                try:
+                    image.seek(0)
+                except Exception:
+                    pass
+            ct = ct or getattr(image, "content_type", None) or getattr(image, "type", None)
+        elif hasattr(image, "tobytes"):
+            bytes_data = image.tobytes() if callable(getattr(image, "tobytes")) else bytes(image)
+        else:
+            try:
+                bytes_data = bytes(image)
+            except Exception:
+                pass
+        if isinstance(bytes_data, str):
+            bytes_data = bytes_data.encode()
+        if not ct:
+            raise ValueError("Pass the image type too, like 'image/png'")
+        return await self.request(
+            method,
+            path,
+            body=bytes_data,
+            headers={"Content-Type": ct},
+            content_type=ct,
+            timeout=timeout,
+            retries=1,
+        )