yarno 0.2.0__py3-none-any.whl

yarno/__init__.py

@@ -0,0 +1,20 @@
+"""yarno — write bots for we.yarno.
+
+    from yarno import Bot, ui
+
+    bot = Bot()
+
+    @bot.command("hi", "says hi")
+    async def hi(ctx):
+        return "hi"
+
+    bot.run()
+
+Get a token at https://dev.we.yarno.lol, docs at https://dev.we.yarno.lol/docs.
+"""
+
+from . import ui
+from .bot import Bot, CommandError, Context, RateLimited, mention
+
+__all__ = ["Bot", "Context", "CommandError", "RateLimited", "mention", "ui"]
+__version__ = "0.2.0"

yarno/bot.py

@@ -0,0 +1,658 @@
+"""The Bot client.
+
+Design goal, stated plainly: the shortest complete bot should be six lines,
+and nothing in those six lines should be ceremony.
+
+    from yarno import Bot
+
+    bot = Bot()
+
+    @bot.command("hi", "says hi")
+    async def hi(ctx):
+        return "hi"
+
+    bot.run()
+
+No intents object. No command tree. No sync() step — the decorator IS the
+registration, pushed the moment the socket connects. No 3-second deadline, no
+defer(), no followup: the connection is already open, so a handler can take as
+long as it likes and still answer on the same path it was called through.
+"""
+
+import asyncio
+import inspect
+import os
+import shlex
+import sys
+import traceback
+import typing
+
+import socketio
+
+from . import ui
+
+DEFAULT_BASE = "https://we.yarno.lol"
+
+
+def log(*a):
+    print("[yarno]", *a, flush=True, file=sys.stderr)
+
+
+class CommandError(Exception):
+    """Raise this in a handler to show the caller a message instead of a
+    stack trace. The SDK also raises it for bad arguments."""
+
+
+class RateLimited(RuntimeError):
+    """The server said slow down and told us for how long. The SDK already
+    waited and retried twice before raising this — catching it means you're
+    sustaining more than the limit, not just bursting."""
+
+    def __init__(self, retry_after: float):
+        super().__init__(f"rate limited — retry in {retry_after}s")
+        self.retry_after = retry_after
+
+
+# --- argument binding --------------------------------------------------------
+#
+# A command's Python signature is the single source of truth: it generates the
+# usage string shown in the composer AND parses what the user typed. There is
+# no second place to declare options and therefore no way for the two to drift.
+
+_TRUE = {"1", "true", "yes", "y", "on"}
+_FALSE = {"0", "false", "no", "n", "off"}
+
+
+def _convert(value: str, kind, name: str):
+    if kind in (str, inspect.Parameter.empty, None):
+        return value
+    if kind is int:
+        try:
+            return int(value)
+        except ValueError:
+            raise CommandError(f"{name} should be a whole number, got {value!r}")
+    if kind is float:
+        try:
+            return float(value)
+        except ValueError:
+            raise CommandError(f"{name} should be a number, got {value!r}")
+    if kind is bool:
+        low = value.lower()
+        if low in _TRUE:
+            return True
+        if low in _FALSE:
+            return False
+        raise CommandError(f"{name} should be yes or no, got {value!r}")
+    origin = typing.get_origin(kind)
+    if origin is typing.Literal:
+        choices = [str(c) for c in typing.get_args(kind)]
+        if value not in choices:
+            raise CommandError(f"{name} should be one of: {', '.join(choices)}")
+        return value
+    return value
+
+
+class Command:
+    def __init__(self, name: str, description: str, fn):
+        self.name = name
+        self.description = description
+        self.fn = fn
+        sig = inspect.signature(fn)
+        # Drop ctx, which is always first.
+        self.params = list(sig.parameters.values())[1:]
+
+    def usage(self) -> str:
+        out = []
+        for p in self.params:
+            required = p.default is inspect.Parameter.empty
+            out.append(f"<{p.name}>" if required else f"[{p.name}]")
+        return " ".join(out)
+
+    def wire(self) -> dict:
+        params = []
+        for p in self.params:
+            kind = p.annotation
+            origin = typing.get_origin(kind)
+            params.append({
+                "name": p.name,
+                "type": (
+                    "choice" if origin is typing.Literal
+                    else getattr(kind, "__name__", "str")
+                ),
+                "required": p.default is inspect.Parameter.empty,
+                "choices": (
+                    [str(c) for c in typing.get_args(kind)]
+                    if origin is typing.Literal else []
+                ),
+            })
+        return {
+            "name": self.name,
+            "description": self.description,
+            "args": self.usage(),
+            "params": params,
+        }
+
+    def bind(self, argstr: str) -> list:
+        """Turn the raw argument string into positional values.
+
+        The last string parameter slurps the remainder, so `/play never gonna
+        give you up` works without anyone having to remember quotes. That one
+        rule removes most of the friction of typed options."""
+        if not self.params:
+            return []
+        try:
+            tokens = shlex.split(argstr)
+        except ValueError:
+            tokens = argstr.split()
+        values, last = [], len(self.params) - 1
+        for i, p in enumerate(self.params):
+            annotation = p.annotation
+            slurp = i == last and annotation in (str, inspect.Parameter.empty)
+            if i >= len(tokens):
+                if p.default is inspect.Parameter.empty:
+                    raise CommandError(f"usage: /{self.name} {self.usage()}".strip())
+                values.append(p.default)
+                continue
+            raw = " ".join(tokens[i:]) if slurp else tokens[i]
+            values.append(_convert(raw, annotation, p.name))
+        return values
+
+
+# --- context -----------------------------------------------------------------
+
+
+class Context:
+    """What a handler is handed. One object for both commands and clicks, so
+    there's nothing to learn twice."""
+
+    def __init__(self, bot: "Bot", data: dict, *, action=False):
+        self._bot = bot
+        self.raw = data
+        self.is_action = action
+        self.user = data.get("user") or {}
+        self.channel_id = data.get("channel_id")
+        self.server_id = data.get("server_id")
+        self.args = data.get("args", "")
+        self.command = data.get("command")
+        # Message events (DMs) only: what they said.
+        self.content = data.get("content", "")
+        # Action-only. `card` and `store` come down with the click, so a bot
+        # that just booted can service a button it drew before it restarted.
+        self.message_id = data.get("message_id")
+        self.on = data.get("on")
+        self.arg = data.get("arg")
+        self.card = data.get("card")
+        self.store = data.get("store") or {}
+        # Current values of the card's form fields, keyed by name. Any click
+        # submits the whole card, so a submit button plus ui.input/select/
+        # toggle/slider is a form with no modal in sight.
+        self.values = data.get("values") or {}
+
+    @property
+    def username(self) -> str:
+        return self.user.get("username", "?")
+
+    async def send(self, body=None, *, card=None, store=None, reply_to=None,
+                   dock=False) -> int:
+        """Post into the channel this came from. Returns the message id."""
+        return await self._bot.send(
+            self.channel_id, body, card=card, store=store, reply_to=reply_to,
+            dock=dock,
+        )
+
+    async def update(self, body=None, *, card=None, store=None) -> None:
+        """Edit the card that was clicked. Only meaningful for actions."""
+        if not self.message_id:
+            raise RuntimeError("update() needs a message — use send() instead")
+        await self._bot.edit(self.message_id, body, card=card, store=store)
+
+    async def delete(self) -> None:
+        if self.message_id:
+            await self._bot.delete(self.message_id)
+
+    async def private(self, body=None, *, card=None) -> None:
+        """Reply so that only the person who acted can see it.
+
+        It's a real message in the channel — rendered with an "only you can
+        see this" footer and a dismiss — not a system notification. Bots don't
+        get to fire the app's own toasts. Nothing is written to the database,
+        so it's gone on reload.
+        """
+        content, card = _split_body(body, card)
+        payload = {
+            "user_id": self.user.get("id"),
+            "channel_id": self.channel_id,
+        }
+        if content is not None:
+            payload["content"] = content
+        if card is not None:
+            payload["card"] = card
+        await self._bot.emit("bot_private", payload)
+
+
+# --- the bot -----------------------------------------------------------------
+
+
+class Bot:
+    def __init__(self, token: str = "", base: str = ""):
+        self.token = token or os.environ.get("YARNO_TOKEN", "")
+        self.base = (base or os.environ.get("YARNO_BASE") or DEFAULT_BASE).rstrip("/")
+        if not self.token:
+            raise SystemExit(
+                "no token — pass Bot(token=...) or set YARNO_TOKEN.\n"
+                "make one at https://dev.we.yarno.lol"
+            )
+        self.commands: dict[str, Command] = {}
+        self.actions: dict[str, callable] = {}
+        self._events: dict[str, list] = {}
+        self._message_handlers: list = []
+        self._autocompleters: dict[tuple[str, str], callable] = {}
+        # Filled from the bot_ready ack: {"id", "username", ...}.
+        self.user: dict | None = None
+        self.can_voice = False
+        self.sio = socketio.AsyncClient(reconnection=True, reconnection_delay_max=20)
+        self._wire()
+
+    # -- registration --
+
+    def command(self, name: str, description: str = ""):
+        def wrap(fn):
+            self.commands[name] = Command(name, description, fn)
+            return fn
+
+        return wrap
+
+    def on(self, action: str):
+        """Handle a button press. `action` matches ui.button(on=...)."""
+
+        def wrap(fn):
+            self.actions[action] = fn
+            return fn
+
+        return wrap
+
+    def event(self, name: str):
+        """Lifecycle hooks: 'ready', 'disconnect'."""
+
+        def wrap(fn):
+            self._events.setdefault(name, []).append(fn)
+            return fn
+
+        return wrap
+
+    def autocomplete(self, command: str, param: str):
+        """Suggest values while someone is still typing an argument. The
+        handler gets (ctx, partial) and returns up to 12 choices — strings,
+        (value, label) pairs, or dicts. The round trip is your socket, so
+        aim for instant.
+
+            @bot.autocomplete("play", "query")
+            async def suggest(ctx, partial):
+                return search_titles(partial)
+        """
+
+        def wrap(fn):
+            self._autocompleters[(command, param)] = fn
+            return fn
+
+        return wrap
+
+    def on_message(self, fn):
+        """Handle a DM sent to the bot. DMs are the only messages that reach
+        a bot — channel chatter structurally doesn't. The handler gets a ctx
+        with .content, .user, .channel_id; returning a string (or card)
+        replies in the DM.
+
+            @bot.on_message
+            async def dm(ctx):
+                return f"you said: {ctx.content}"
+        """
+        self._message_handlers.append(fn)
+        return fn
+
+    async def _fire(self, name: str, *a):
+        for fn in self._events.get(name, []):
+            try:
+                await fn(*a) if inspect.iscoroutinefunction(fn) else fn(*a)
+            except Exception:
+                traceback.print_exc()
+
+    # -- outbound --
+
+    async def emit(self, event: str, data: dict):
+        await self.sio.emit(event, data)
+
+    async def _call(self, event: str, data: dict, timeout: int = 15):
+        for attempt in range(3):
+            res = await self.sio.call(event, data, timeout=timeout)
+            if isinstance(res, dict) and res.get("error"):
+                wait = res.get("retry_after")
+                if wait is not None:
+                    # Back off exactly as long as the server asked, twice,
+                    # before making it the caller's problem.
+                    if attempt < 2 and wait <= 10:
+                        await asyncio.sleep(float(wait) + 0.05)
+                        continue
+                    raise RateLimited(wait)
+                raise RuntimeError(res["error"])
+            return res or {}
+
+    async def send(self, channel_id, body=None, *, card=None, store=None,
+                   reply_to=None, dock=False, files=None) -> int:
+        """Post a message. `dock=True` pins the card to the top of the
+        channel — the one slot every channel has for a live surface.
+        `files` is a list of paths / bytes / file objects (or attachment ids
+        from a prior upload); they're uploaded and attached for you."""
+        payload = {"channel_id": channel_id}
+        content, card = _split_body(body, card)
+        if content is not None:
+            payload["content"] = content
+        if card is not None:
+            payload["card"] = card
+        if store is not None:
+            payload["store"] = store
+        if reply_to:
+            payload["reply_to"] = reply_to
+        if dock:
+            payload["dock"] = True
+        if files:
+            ids = []
+            for f in files:
+                if isinstance(f, int):
+                    ids.append(f)
+                else:
+                    ids.append((await self.upload(channel_id, f))["id"])
+            payload["attachment_ids"] = ids
+        return (await self._call("bot_send", payload)).get("message_id")
+
+    async def edit(self, message_id, body=None, *, card=None, store=None) -> None:
+        payload = {"message_id": message_id}
+        content, card = _split_body(body, card)
+        if content is not None:
+            payload["content"] = content
+        if card is not None:
+            payload["card"] = card
+        if store is not None:
+            payload["store"] = store
+        await self._call("bot_edit", payload)
+
+    async def delete(self, message_id) -> None:
+        await self._call("bot_delete", {"message_id": message_id})
+
+    async def dock(self, message_id, dock: bool = True) -> None:
+        """Pin one of your cards to the top of its channel (or unpin it).
+        A channel has one dock slot; docking replaces whatever held it."""
+        await self._call("bot_dock", {"message_id": message_id, "dock": dock})
+
+    async def react(self, message_id, emoji: str, *, remove=False) -> None:
+        """Toggle a reaction on a DM message or one of your own."""
+        await self._call(
+            "bot_react", {"message_id": message_id, "emoji": emoji, "remove": remove}
+        )
+
+    async def history(self, channel_id, *, before=None, limit=50) -> list:
+        """Messages from a DM the bot is part of, oldest first. DMs only —
+        channel history is structurally out of reach."""
+        payload = {"channel_id": channel_id, "limit": limit}
+        if before:
+            payload["before"] = before
+        return (await self._call("bot_history", payload)).get("messages", [])
+
+    async def fetch_message(self, message_id) -> dict:
+        """One message: a DM the bot is in, or a message the bot wrote."""
+        return (await self._call("bot_fetch_message", {"message_id": message_id}))[
+            "message"
+        ]
+
+    async def fetch_user(self, user=None, *, username=None) -> dict:
+        """Look up someone the bot shares a server or DM with."""
+        payload = {"username": username} if username else {"user_id": user}
+        return (await self._call("bot_fetch_user", payload))["user"]
+
+    async def fetch_channel(self, channel_id) -> dict:
+        """A channel the bot can see: name, type, and whether it can post."""
+        return (await self._call("bot_fetch_channel", {"channel_id": channel_id}))[
+            "channel"
+        ]
+
+    async def fetch_server(self, server_id) -> dict:
+        """A server the bot is in: channels it can see, the member list."""
+        return (await self._call("bot_fetch_server", {"server_id": server_id}))[
+            "server"
+        ]
+
+    async def servers(self) -> list:
+        """The servers this bot has been invited into."""
+        return (await self._call("bot_servers", {})).get("servers", [])
+
+    # -- http (files ride over http; everything else is the socket) --
+
+    def _http_headers(self):
+        return {"Authorization": f"Bearer {self.token}"}
+
+    async def upload(self, channel_id, file, *, filename=None) -> dict:
+        """Park a file for sending: a path, bytes, or a file object. Returns
+        the attachment dict; pass its id in send(..., files=[...]) — or just
+        hand send() the file directly and it does both steps."""
+        import aiohttp
+
+        if isinstance(file, (str, os.PathLike)):
+            name = filename or os.path.basename(str(file))
+            with open(file, "rb") as f:
+                payload = f.read()
+        elif isinstance(file, bytes):
+            name = filename or "file"
+            payload = file
+        else:
+            name = filename or getattr(file, "name", "file")
+            payload = file.read()
+        form = aiohttp.FormData()
+        form.add_field("file", payload, filename=os.path.basename(name))
+        async with aiohttp.ClientSession() as http:
+            async with http.post(
+                f"{self.base}/api/bot/upload",
+                params={"channel_id": str(channel_id)},
+                data=form,
+                headers=self._http_headers(),
+            ) as resp:
+                body = await resp.json()
+                if resp.status != 200:
+                    raise RuntimeError(body.get("detail") or f"upload failed ({resp.status})")
+                return body["attachment"]
+
+    async def set_avatar(self, file) -> str:
+        """Give the bot a face — a path, bytes, or a file object."""
+        import aiohttp
+
+        if isinstance(file, (str, os.PathLike)):
+            with open(file, "rb") as f:
+                payload = f.read()
+        elif isinstance(file, bytes):
+            payload = file
+        else:
+            payload = file.read()
+        form = aiohttp.FormData()
+        form.add_field("file", payload, filename="avatar")
+        async with aiohttp.ClientSession() as http:
+            async with http.post(
+                f"{self.base}/api/bot/avatar", data=form, headers=self._http_headers()
+            ) as resp:
+                body = await resp.json()
+                if resp.status != 200:
+                    raise RuntimeError(body.get("detail") or f"avatar failed ({resp.status})")
+                return body["avatar"]
+
+    async def voice_join(self, channel_id):
+        """Join a voice channel and get a VoiceSession (play/stop/leave).
+        Needs the voice extra (pip install 'yarno[voice]') and ffmpeg, and
+        the bot must have been granted can_voice by the instance operator."""
+        from . import voice
+
+        return await voice.join(self, channel_id)
+
+    async def tallies(self, message_id) -> dict:
+        """Counts behind a card's collect buttons: {key: [{"id", "username"}]}.
+        The server recorded these — they accrued even while you were down."""
+        return (await self._call("bot_tallies", {"message_id": message_id})).get(
+            "tallies", {}
+        )
+
+    # -- inbound --
+
+    def _wire(self):
+        @self.sio.event
+        async def connect():
+            declared = [c.wire() for c in self.commands.values()]
+            # Mark which params answer autocomplete, so the composer knows
+            # to ask as the person types.
+            for cmd in declared:
+                for p in cmd["params"]:
+                    if (cmd["name"], p["name"]) in self._autocompleters:
+                        p["autocomplete"] = True
+            res = await self.sio.call("bot_ready", {"commands": declared}, timeout=15)
+            self.user = (res or {}).get("you") or self.user
+            self.can_voice = bool((res or {}).get("can_voice"))
+            names = (res or {}).get("registered") or []
+            who = f"@{self.user['username']}" if self.user else "connected"
+            log(f"{who} — {len(names)} command(s): " + ", ".join("/" + n for n in names))
+            for bad in (res or {}).get("skipped") or []:
+                log(f"rejected command name {bad!r} (a-z 0-9 _ - only)")
+            await self._fire("ready")
+
+        @self.sio.event
+        async def disconnect():
+            log("disconnected")
+            await self._fire("disconnect")
+
+        @self.sio.on("bot_error")
+        async def bot_error(data):
+            log("server said:", (data or {}).get("text"))
+
+        @self.sio.on("bot_command")
+        async def bot_command(data):
+            ctx = Context(self, data)
+            cmd = self.commands.get(data.get("command"))
+            if not cmd:
+                return await ctx.private(f"/{data.get('command')} isn't a thing anymore")
+            await self._run(ctx, lambda: cmd.fn(ctx, *cmd.bind(ctx.args)))
+
+        @self.sio.on("bot_action")
+        async def bot_action(data):
+            ctx = Context(self, data, action=True)
+            fn = self.actions.get(data.get("on"))
+            if not fn:
+                return await ctx.private("that button isn't wired up")
+            await self._run(ctx, lambda: fn(ctx))
+
+        @self.sio.on("bot_autocomplete")
+        async def bot_autocomplete(data):
+            fn = self._autocompleters.get(
+                ((data or {}).get("command"), (data or {}).get("param"))
+            )
+            if not fn:
+                return {"choices": []}
+            try:
+                res = fn(Context(self, data), (data or {}).get("partial", ""))
+                if inspect.isawaitable(res):
+                    res = await res
+                return {"choices": list(res or [])[:12]}
+            except Exception:
+                traceback.print_exc()
+                return {"choices": []}
+
+        @self.sio.on("message_new")
+        async def message_new(data):
+            # Only DMs reach a bot's socket — the server guarantees it. Skip
+            # our own sends and other bots (no two bots ping-ponging forever).
+            if not self._message_handlers:
+                return
+            author = (data or {}).get("author") or {}
+            if self.user and author.get("id") == self.user.get("id"):
+                return
+            if author.get("is_bot"):
+                return
+            ctx = Context(self, {
+                "user": {"id": author.get("id"), "username": author.get("username")},
+                "channel_id": data.get("channel_id"),
+                "server_id": None,
+                "message_id": data.get("id"),
+                "content": data.get("content", ""),
+            })
+            for fn in self._message_handlers:
+                await self._run(ctx, lambda fn=fn: fn(ctx))
+
+    async def _run(self, ctx: Context, thunk):
+        """Run a handler and turn whatever it returns into output.
+
+        Returning a string sends a message. Returning a card sends a card. On
+        an action, returning either edits the clicked message instead — which
+        is nearly always what you meant.
+        """
+        try:
+            result = thunk()
+            if inspect.isawaitable(result):
+                result = await result
+            if result is None:
+                return
+            if ctx.is_action:
+                await ctx.update(result)
+            else:
+                await ctx.send(result)
+        except CommandError as e:
+            await ctx.private(str(e))
+        except Exception as e:
+            traceback.print_exc()
+            await ctx.private(f"that broke: {type(e).__name__}: {e}"[:180])
+
+    # -- lifecycle --
+
+    async def start(self):
+        try:
+            await self.sio.connect(
+                self.base,
+                headers={"Authorization": f"Bearer {self.token}"},
+                transports=["websocket"],
+                wait_timeout=15,
+            )
+        except socketio.exceptions.ConnectionError:
+            # The server refuses the handshake outright for a bad token —
+            # turn the library's shrug into the actual likely cause.
+            raise SystemExit(
+                f"couldn't connect to {self.base} — if it's up, the token is"
+                " wrong or was rotated. check YARNO_TOKEN against the console"
+                " at https://dev.we.yarno.lol"
+            )
+        await self.sio.wait()
+
+    def run(self):
+        try:
+            asyncio.run(self.start())
+        except KeyboardInterrupt:
+            pass
+
+
+def mention(user) -> str:
+    """Ping someone from a message: `f"{mention(ctx.user)} it's ready"`.
+
+    Takes a user dict or a raw id. Ids rather than names, because you already
+    have the id and it survives a rename — the server expands it to the
+    person's current @name when the message lands, and only if they can
+    actually see the channel.
+
+    Pings live in plain message content, not in cards. If you want to get
+    someone's attention, say it in words.
+    """
+    uid = user.get("id") if isinstance(user, dict) else user
+    return f"<@{int(uid)}>"
+
+
+def _split_body(body, card):
+    """Accept send('text'), send(card=...), or send(ui.card(...)) — one
+    argument that does the obvious thing with whatever you hand it."""
+    if body is None:
+        return None, card
+    if isinstance(body, dict):
+        if card is not None:
+            raise ValueError("pass a card positionally or as card=, not both")
+        return None, body
+    return str(body), card

yarno/ui.py

@@ -0,0 +1,278 @@
+"""Card components.
+
+Every function here returns a plain dict, so a card is just data — printable,
+diffable, testable, and storable. There's no widget object holding a callback
+in memory, which is exactly why a yarno bot's buttons don't die when it
+restarts.
+
+Falsy children are dropped, so conditionals go inline:
+
+    ui.col(
+        ui.title(name),
+        ui.bar(indeterminate=True) if loading else None,
+    )
+
+Lists are flattened, so comprehensions do too:
+
+    ui.col([ui.text(t) for t in tracks])
+"""
+
+
+def _kids(children):
+    out = []
+    for child in children:
+        if child is None or child is False:
+            continue
+        if isinstance(child, (list, tuple)):
+            out.extend(_kids(child))
+        else:
+            out.append(child)
+    return out
+
+
+def _container(kind, children, align=None, grow=False, **extra):
+    node = {"type": kind, "children": _kids(children)}
+    if align:
+        node["align"] = align
+    if grow:
+        node["grow"] = True
+    node.update({k: v for k, v in extra.items() if v})
+    return node
+
+
+def card(*children, accent=None):
+    """The outer surface. Everything a bot draws lives in one of these."""
+    return _container("card", children, accent=accent)
+
+
+def row(*children, align=None, grow=False):
+    """Left-to-right. `align` is start / center / end / between."""
+    return _container("row", children, align, grow)
+
+
+def col(*children, align=None, grow=False):
+    """Top-to-bottom."""
+    return _container("col", children, align, grow)
+
+
+def text(value, *, style="body", href=None, scroll=False, grow=False):
+    node = {"type": "text", "value": str(value), "style": style}
+    if href:
+        node["href"] = href
+    if scroll:
+        # Marquee long values instead of truncating them.
+        node["scroll"] = True
+    if grow:
+        node["grow"] = True
+    return node
+
+
+def title(value, **kw):
+    return text(value, style="title", **kw)
+
+
+def dim(value, **kw):
+    return text(value, style="dim", **kw)
+
+
+def mono(value, **kw):
+    return text(value, style="mono", **kw)
+
+
+def image(src, *, size="thumb", alt=""):
+    """size: thumb (square, inline) / banner (wide strip) / full."""
+    return {"type": "image", "src": src, "size": size, "alt": alt}
+
+
+def bar(value=None, *, indeterminate=False, label=None, rate=None):
+    """A progress bar. `value` is 0..1; pass indeterminate=True when you don't
+    know how long it'll take. Discord has no equivalent — people fake it with
+    block characters in an embed description.
+
+    With `rate` (units/sec) the bar advances client-side from `value` — a
+    playhead is bar(value=elapsed/length, rate=1/length), edited once per
+    track instead of once per second."""
+    node = {"type": "bar"}
+    if indeterminate or value is None:
+        node["indeterminate"] = True
+    else:
+        node["value"] = value
+        if rate is not None:
+            node["rate"] = rate
+    if label:
+        node["label"] = label
+    return node
+
+
+def ticker(value, *, rate=1, format="clock", prefix=None, suffix=None,
+           style="dim", min=None, max=None):
+    """A number that advances by itself: elapsed time, a countdown, anything
+    with a steady rate. You push state changes; every viewer's client renders
+    the frames. `format` is clock (1:23), number, or percent. A countdown is
+    ticker(seconds_left, rate=-1, min=0)."""
+    node = {"type": "ticker", "value": value, "rate": rate, "format": format,
+            "style": style}
+    if prefix:
+        node["prefix"] = prefix
+    if suffix:
+        node["suffix"] = suffix
+    if min is not None:
+        node["min"] = min
+    if max is not None:
+        node["max"] = max
+    return node
+
+
+def button(on=None, label=None, *, icon=None, style=None, arg=None,
+           disabled=False, collect=None):
+    """`on` names the @bot.on handler this click runs. `arg` is a small scalar
+    that rides along — anything bigger belongs in the message's store, which
+    the server keeps for you.
+
+    `collect` makes it a counted button: the SERVER records who's pressed it
+    (toggling), so it keeps working while your bot is offline. Keys shaped
+    `group:key` are exclusive per person within the group — that's a poll.
+    Read the counts with ui.tally(key) in the card, or bot.tallies(id)."""
+    node = {"type": "button"}
+    if on:
+        node["on"] = on
+    if collect:
+        node["collect"] = collect
+    if label:
+        node["label"] = label
+    if icon:
+        node["icon"] = icon
+    if style:
+        node["style"] = style
+    if arg is not None:
+        node["arg"] = arg
+    if disabled:
+        node["disabled"] = True
+    return node
+
+
+def tally(key, label=None):
+    """The live count behind a collect key. Renders as a chip; updates for
+    everyone the moment anyone presses the matching collect button."""
+    node = {"type": "tally", "key": key}
+    if label:
+        node["label"] = label
+    return node
+
+
+def only(*children, user=None, perm=None):
+    """Wrap components so only some viewers receive them — stripped
+    server-side for everyone else, not hidden client-side. `user` is a user
+    id; `perm` is a permission name checked in the card's server.
+
+        ui.only(ui.button("reveal", "your hand"), user=ctx.user["id"])
+    """
+    node = _container("col", children)
+    if user is not None:
+        node["for_user"] = user
+    if perm:
+        node["for_perm"] = perm
+    return node
+
+
+def kv(k, v):
+    """A labelled value — the one genuinely useful thing embed fields gave us."""
+    return {"type": "kv", "k": str(k), "v": str(v)}
+
+
+# --- form fields --------------------------------------------------------------
+#
+# A card is also a form. Give a field a name and its current value arrives in
+# ctx.values on EVERY action from that card — so one submit button reads the
+# whole form, no modal required. A field with on= additionally submits itself:
+# inputs on Enter, selects on pick, toggles on flip, sliders on release.
+
+
+def input(name, *, placeholder=None, value=None, on=None, grow=False):
+    """An inline text field. This is the thing Discord needs a modal for."""
+    node = {"type": "input", "name": name}
+    if placeholder:
+        node["placeholder"] = placeholder
+    if value is not None:
+        node["value"] = str(value)
+    if on:
+        node["on"] = on
+    if grow:
+        node["grow"] = True
+    return node
+
+
+def select(name, options, *, value=None, placeholder=None, on=None, grow=False):
+    """A dropdown. `options` can be plain strings, (value, label) pairs, or
+    {"value", "label"} dicts."""
+    opts = []
+    for opt in options:
+        if isinstance(opt, dict):
+            opts.append({"value": str(opt.get("value")),
+                         "label": str(opt.get("label") or opt.get("value"))})
+        elif isinstance(opt, (list, tuple)) and len(opt) == 2:
+            opts.append({"value": str(opt[0]), "label": str(opt[1])})
+        else:
+            opts.append({"value": str(opt), "label": str(opt)})
+    node = {"type": "select", "name": name, "options": opts}
+    if value is not None:
+        node["value"] = str(value)
+    if placeholder:
+        node["placeholder"] = placeholder
+    if on:
+        node["on"] = on
+    if grow:
+        node["grow"] = True
+    return node
+
+
+def toggle(name, *, value=False, label=None, on=None):
+    """An on/off switch."""
+    node = {"type": "toggle", "name": name}
+    if value:
+        node["value"] = True
+    if label:
+        node["label"] = label
+    if on:
+        node["on"] = on
+    return node
+
+
+def slider(name, *, min=0, max=1, step=None, value=None, label=None, on=None,
+           grow=False):
+    """A drag control. With on= it submits when released, so a volume slider
+    is one line: ui.slider("vol", max=100, value=80, on="set_volume")."""
+    node = {"type": "slider", "name": name, "min": min, "max": max}
+    if step is not None:
+        node["step"] = step
+    if value is not None:
+        node["value"] = value
+    if label:
+        node["label"] = label
+    if on:
+        node["on"] = on
+    if grow:
+        node["grow"] = True
+    return node
+
+
+def section(label, *children, open=False, name=None):
+    """A collapsible group — long tails (queues, logs, extra settings) fold
+    away instead of making the card scroll. Viewers' open/closed choices
+    survive your re-renders."""
+    node = _container("section", children)
+    node["label"] = str(label)
+    if open:
+        node["open"] = True
+    if name:
+        node["name"] = name
+    return node
+
+
+def divider():
+    return {"type": "divider"}
+
+
+def spacer():
+    """Eats the free space in a row — put one before trailing buttons."""
+    return {"type": "spacer"}

yarno/voice.py

@@ -0,0 +1,118 @@
+"""Voice for bots.
+
+Optional extra: `pip install 'yarno[voice]'` (pulls the livekit sdk) and
+ffmpeg on PATH. The bot itself needs `can_voice`, which the instance
+operator grants — publishing audio is the one genuinely privileged thing a
+bot can do.
+
+    session = await bot.voice_join(channel_id)
+    await session.play("song.mp3")     # blocks until the track ends
+    await session.leave()
+
+play() decodes through ffmpeg, so anything ffmpeg reads works: files, urls,
+streams. Call stop() from another task to cut a running play() short.
+"""
+
+import asyncio
+import os
+
+SAMPLE_RATE = 48000
+CHANNELS = 2
+FRAME = 480  # samples per 10ms frame
+_FRAME_BYTES = FRAME * CHANNELS * 2  # s16le
+
+
+def _rtc():
+    try:
+        from livekit import rtc
+    except ImportError:
+        raise RuntimeError(
+            "voice needs the livekit sdk — pip install 'yarno[voice]'"
+        )
+    return rtc
+
+
+async def join(bot, channel_id) -> "VoiceSession":
+    rtc = _rtc()
+    res = await bot._call("bot_voice_join", {"channel_id": channel_id})
+    room = rtc.Room()
+    await room.connect(res["url"], res["token"])
+    source = rtc.AudioSource(SAMPLE_RATE, CHANNELS)
+    track = rtc.LocalAudioTrack.create_audio_track("audio", source)
+    await room.local_participant.publish_track(
+        track, rtc.TrackPublishOptions(source=rtc.TrackSource.SOURCE_MICROPHONE)
+    )
+    return VoiceSession(bot, channel_id, room, source)
+
+
+class VoiceSession:
+    def __init__(self, bot, channel_id, room, source):
+        self._bot = bot
+        self.channel_id = channel_id
+        self._room = room
+        self._source = source
+        self._proc = None
+        # Checked by the pump on every frame, set BEFORE any teardown starts.
+        # A session that's been left must not be resurrectable by a pump that
+        # was mid-await when it happened.
+        self._dead = False
+
+    @property
+    def playing(self) -> bool:
+        return self._proc is not None
+
+    async def play(self, source: str, *, volume: float = 1.0):
+        """Decode `source` (anything ffmpeg accepts — a path, a url) and
+        stream it into the channel. Returns when the track ends or stop()
+        is called. One track at a time; a second play() cuts the first."""
+        rtc = _rtc()
+        await self.stop()
+        if self._dead:
+            raise RuntimeError("this voice session has been left")
+        args = ["-loglevel", "quiet"]
+        if not os.path.exists(source):
+            # Network sources appreciate a nudge to reconnect on hiccups.
+            args += ["-reconnect", "1", "-reconnect_streamed", "1"]
+        args += ["-i", source]
+        if volume != 1.0:
+            args += ["-filter:a", f"volume={max(0.0, min(4.0, volume))}"]
+        args += ["-f", "s16le", "-ar", str(SAMPLE_RATE), "-ac", str(CHANNELS), "-"]
+        self._proc = await asyncio.create_subprocess_exec(
+            "ffmpeg", *args, stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        proc = self._proc
+        try:
+            while not self._dead and self._proc is proc:
+                try:
+                    chunk = await proc.stdout.readexactly(_FRAME_BYTES)
+                except asyncio.IncompleteReadError:
+                    break
+                frame = rtc.AudioFrame(
+                    data=chunk, sample_rate=SAMPLE_RATE,
+                    num_channels=CHANNELS, samples_per_channel=FRAME,
+                )
+                await self._source.capture_frame(frame)
+        finally:
+            if self._proc is proc:
+                self._proc = None
+            if proc.returncode is None:
+                proc.kill()
+
+    async def stop(self):
+        """Cut whatever is playing. The play() call that owned it returns."""
+        proc, self._proc = self._proc, None
+        if proc and proc.returncode is None:
+            proc.kill()
+
+    async def leave(self):
+        """Stop, disconnect from the room, release the voice slot."""
+        self._dead = True  # before any await — nothing may resurrect us
+        await self.stop()
+        try:
+            await self._room.disconnect()
+        finally:
+            try:
+                await self._bot._call("bot_voice_leave", {})
+            except Exception:
+                pass  # the server reaps on socket disconnect anyway

yarno-0.2.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: yarno
+Version: 0.2.0
+Summary: write bots for we.yarno — cards, inline forms, server-counted polls, live values, voice
+Author: alfa
+License-Expression: MIT
+Project-URL: docs, https://dev.we.yarno.lol/docs
+Project-URL: source, https://github.com/alfaoz/yarno-sdk
+Keywords: yarno,bot,chat,socketio
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-socketio[asyncio_client]>=5.11
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: voice
+Requires-Dist: livekit>=0.17; extra == "voice"
+Dynamic: license-file
+
+# yarno
+
+write bots for [we.yarno](https://we.yarno.lol) — the invite-only
+servers/channels/voice app.
+
+```bash
+pip install yarno
+```
+
+the shortest complete bot:
+
+```python
+from yarno import Bot
+
+bot = Bot()                    # reads $YARNO_TOKEN
+
+@bot.command("hi", "says hi")
+async def hi(ctx):
+    return f"hi {ctx.username}"
+
+bot.run()
+```
+
+no intents, no command tree, no `sync()` step, no 3-second deadline. your bot
+holds a live socket to the instance, so the decorator *is* the registration
+and a handler can take as long as it needs.
+
+## what you get
+
+- **cards** — compose rows, columns, progress bars, images, buttons instead
+  of filling in an embed
+- **inline forms** — `ui.input` / `ui.select` / `ui.toggle` / `ui.slider`
+  live in the card, in the channel; any click submits the whole form as
+  `ctx.values`. no modals.
+- **polls that outlive you** — `ui.button(collect="v:yes")` is counted by the
+  server, so votes land while your process is down; read them back with
+  `bot.tallies()`
+- **live values** — `ui.ticker` / `ui.bar(rate=...)` advance on every
+  viewer's screen; you push state changes, not frames
+- **docked cards** — pin one card above the channel's scroll (now playing,
+  scoreboards, countdowns)
+- **autocomplete** — suggest argument values as someone types, over your
+  already-open socket
+- **dms, files, reactions, avatars, voice** — `@bot.on_message`,
+  `send(files=[...])`, `bot.react()`, `bot.set_avatar()`, and
+  `bot.voice_join()` with the `yarno[voice]` extra
+- **buttons that survive restarts** — per-message state lives on the server
+  and rides back with every click
+
+## privacy, stated up front
+
+a bot sees nothing by default: commands aimed at it, clicks on its own
+cards, and dms it's part of. it does **not** receive channel messages, and
+there is no intent to flip on. the read apis hold the same line.
+
+## docs
+
+- [quickstart](https://dev.we.yarno.lol/docs/quickstart) — token to working
+  command in about two minutes
+- [cards & components](https://dev.we.yarno.lol/docs/cards)
+- [the full sdk reference](https://dev.we.yarno.lol/docs/sdk)
+- [wire protocol](https://dev.we.yarno.lol/docs/protocol) — for writing a
+  bot in another language
+
+examples live in [`examples/`](examples/): `pingpong.py` is the core loop,
+`lunchbot.py` is forms + polls + autocomplete + a docked countdown.
+
+tokens come from the [dev console](https://dev.we.yarno.lol). we.yarno is
+invite-only; the sdk is public so bots can be written for it.

yarno-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+yarno/__init__.py,sha256=8xBK4wrFf_dDkU3YMZxENXDbTaU-FY909EnDlilgyZI,448
+yarno/bot.py,sha256=JIviaIrfIlA7AStxtcu2UrwsUlr9MIdPaIPABSvGw2Q,25086
+yarno/ui.py,sha256=WZ1fe53ikUCpCLEgnz_KIu4Sdipj4s70E49T2r23mTw,8668
+yarno/voice.py,sha256=sMzb5NI4D6Ht6REgfyjPVOqgFL_luSRG6FcAIe8oXyY,4309
+yarno-0.2.0.dist-info/licenses/LICENSE,sha256=pTQEeW2P7zO0bpe01HFTkRzRnUF7bEl7-RSorPU9mus,1061
+yarno-0.2.0.dist-info/METADATA,sha256=17r_cJrgf_-R5shCdL18boAPURN6JNVMeJpEtLTVLlc,3496
+yarno-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+yarno-0.2.0.dist-info/top_level.txt,sha256=FoTXx9xAFAipSPpBJws4zk2jwgEyfUhFVeQHvhIgCsM,6
+yarno-0.2.0.dist-info/RECORD,,

yarno-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

yarno-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alfa
+
+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.

yarno-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+yarno