python-yappy 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

{python_yappy-0.1.1.dist-info → python_yappy-0.1.2.dist-info}/METADATA

@@ -1,10 +1,11 @@
 Metadata-Version: 2.3
 Name: python-yappy
-Version: 0.1.1
+Version: 0.1.2
 Summary: API Bindings for Yapper!
 Author: H1387Lmao
 Requires-Dist: aiohttp>=3.14.5
 Requires-Dist: load-dotenv>=0.1.0
+Requires-Dist: rich>=13.0
 Requires-Dist: uv-build>=0.13.1
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -24,7 +25,8 @@ YapPy brings a Python-friendly interface to [Yapper](https://yapper.website), a
 - **Commands** — register named commands with descriptions.
 - **Context-based interactions** — reply to messages through a context object.
 - **Core models** — work with `Context`, `Message`, `Channel`, and `User` objects.
-- **Optional logging** — enable verbose output when creating the application.
+- **Argument validation** — type-hinted command parameters are converted for you, and mistakes get a helpful reply.
+- **Rich logging** — coloured logs and readable tracebacks; `verbose=True` adds debug output.
 
 ## Installation
 
@@ -114,7 +116,7 @@ async def on_message(ctx):
     if ctx.is_bot:
         return
 
-    await ctx.process.command(ctx)
+    await bot.process_command(ctx)
 ```
 
 The event name and handler arguments should match the event interface supported by the installed YapPy version.
@@ -134,6 +136,66 @@ async def ping(ctx):
 
 The `name` identifies the command, and `description` describes its purpose. Command registration and invocation behavior depend on the current implementation.
 
+### Command arguments
+
+Arguments from the message are matched to your function's parameters. Add type hints and YapPy converts them for you:
+
+```python
+@bot.command(name="add", description="Adds two numbers")
+async def add(ctx, a: int, b: int = 0):
+    await ctx.reply(f"{a} + {b} = {a + b}")
+```
+
+| Annotation | Accepts |
+| --- | --- |
+| `str` | the text exactly as typed (use `"quotes"` for spaces) |
+| `int`, `float` | numbers |
+| `bool` | `true`/`false`, `yes`/`no`, `on`/`off`, `1`/`0` |
+| `User`, `Channel`, `Role` | a mention such as `<@123>` |
+| *(none)* | guessed: whole numbers become `int`, decimals `float`, mentions are resolved, anything else is `str` |
+
+Parameters with a default are optional, and `*args` collects any remaining arguments.
+
+### Command errors
+
+If someone uses a command the wrong way, the bot tells them instead of failing silently:
+
+```text
+!add
+Missing required argument 'a'.
+Usage: `!add <a> [b]`
+```
+
+Too many arguments and values of the wrong type are handled the same way. Unknown commands are ignored, and an exception raised inside a command is logged rather than sent to chat.
+
+To handle these yourself, register a `command_error` handler. It replaces the default replies:
+
+```python
+from yappy import UnknownCommand
+
+@bot.event("command_error")
+async def on_command_error(ctx, error):
+    if isinstance(error, UnknownCommand):
+        return
+    await ctx.reply(str(error))
+```
+
+`error` is one of `UnknownCommand`, `MissingArgument`, `TooManyArguments`, `BadArgument` or `CommandInvokeError` (all subclasses of `yappy.CommandError`). For `CommandInvokeError`, the exception your command raised is `error.original`, and `error.command` is the command involved.
+
+### Logging
+
+YapPy logs through Python's `logging` module under the name `yappy` and prints it with [Rich](https://github.com/Textualize/rich). Exceptions appear as readable tracebacks. `App(verbose=True)` also shows debug output: events, HTTP requests and command invocations.
+
+To configure logging yourself, create the app with `configure_logging=False`:
+
+```python
+import logging
+from yappy import App, setup_logging
+
+bot = App(configure_logging=False)
+setup_logging(level=logging.WARNING, show_locals=True)  # or attach your own handlers to logging.getLogger("yappy")
+```
+
 ### Context and models
 
 YapPy currently provides these core models:

python_yappy-0.1.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+yappy/__init__.py,sha256=sfTl69d_NnVtVVLFQbQRmnsTqv8xjC4swCBL-FGxSjc,197
+yappy/api.py,sha256=1j99nfK7n5FBl-vSZy98xtZqh5oBtZZEcFKY4cbHTSs,2854
+yappy/app.py,sha256=-vn22pj5pUBxSLZPiqGZfeJDjmrG44Pu5NTLXQBESec,17300
+yappy/consts.py,sha256=0pIUIY1Ayo6_q3XhWr9hvKLgOT7TC9RgsjPZNVYy8QQ,51
+yappy/core.py,sha256=Z_Yc6cNqN_1qThGVZZ94bpjwMnWHaPlRqhYS3GGRRf0,11104
+yappy/errors.py,sha256=x-CHCU1s4lhZVYqK9EwULYJBbIll8Bt09cC7dZ7Y8oI,2297
+yappy/logger.py,sha256=IVjOwvFtaYLwWGHNurTk7SVcthT8gi02ztuuayBlyIY,2295
+yappy/parser.py,sha256=yOp74Ch8RZ6nAadFVrRxKt5U4VF5rqIClSjWRXmcPAI,5468
+yappy/utils.py,sha256=s7wmPTflqTAIgeAtf0a-gWgEfkQaZGKWYEqm2i4MsUM,129
+python_yappy-0.1.2.dist-info/WHEEL,sha256=lrO5MD1WVAWzcbNy_L2BwtfPrcM3KfUFpbKYXLkJX4A,80
+python_yappy-0.1.2.dist-info/METADATA,sha256=hEgEHzEIx6QaNLAP0uzt1qxaAsYdxaOqKzxXeiDxJMY,7103
+python_yappy-0.1.2.dist-info/RECORD,,

yappy/__init__.py

@@ -1 +1,6 @@
 from .app import App
+from .errors import (
+    BadArgument, CommandError, CommandInvokeError, MissingArgument,
+    TooManyArguments, UnknownCommand, YappyError,
+)
+from .logger import setup_logging

yappy/api.py

@@ -1,7 +1,11 @@
 from .consts import BASE_URL
 import aiohttp
+import logging
 import random
 import asyncio
+import time
+
+log = logging.getLogger(__name__)
 
 async def api_push(session: aiohttp.ClientSession, method: str, path: str, body=None, tries=3):
     headers = {
@@ -9,10 +13,17 @@ async def api_push(session: aiohttp.ClientSession, method: str, path: str, body=
         "Content-Type": "application/json"
     }
 
+    started = time.perf_counter()
     try:
         async with session.request(method, BASE_URL + path, json=body, headers=headers, timeout=40) as r:
             r.raise_for_status()
-            return await r.json()
+            data = await r.json()
+        if not path.startswith("/events"):  # the long poll would be noise
+            log.debug(
+                "%s %s -> %s (%.0f ms)", method, path, r.status,
+                (time.perf_counter() - started) * 1000
+            )
+        return data
     except aiohttp.ClientResponseError as e:
         try:
             err = await e.history[-1].json() if e.history else {}
@@ -25,8 +36,12 @@ async def api_push(session: aiohttp.ClientSession, method: str, path: str, body=
         wait = int(e.headers.get("Retry-After") or 0) if e.status == 429 or busy else 0
                 
         if 0 < wait <= 60 and tries > 1:
-            print(f"{'busy' if busy else 'rate limited'}, retrying in {wait}s")
-            await asyncio.sleep(wait * (1 + random.random() * 0.5))
+            delay = wait * (1 + random.random() * 0.5)
+            log.warning(
+                "%s on %s %s, retrying in %.1fs",
+                "Server busy" if busy else "Rate limited", method, path, delay
+            )
+            await asyncio.sleep(delay)
             return await api_push(session, method, path, body, tries - 1)
                     
         raise RuntimeError(f"{method} {path} failed ({e.status}): {msg or e.message}") from None

yappy/app.py

@@ -1,20 +1,27 @@
 from .core import *
 from .consts import BASE_URL
 from .api import *
-from .errors import ImproperToken, InvalidSignature, UnknownCommand
+from .errors import (
+    CommandError, CommandInvokeError, ImproperToken, InvalidSignature,
+    UnknownCommand,
+)
+from .logger import setup_logging
 from .parser import parser
 
 import inspect
 import asyncio
 import aiohttp
-import traceback
+import logging
 from functools import wraps
 from typing import Callable
 
+log = logging.getLogger(__name__)
+
 class App:
     def __init__(
         self, verbose=False,
-        prefix = "!"
+        prefix = "!",
+        configure_logging = True
     ):
         self.__commands = {}
         self.__event_handlers = {
@@ -28,12 +35,30 @@ class App:
         self._token = None
 
         self._verbose = verbose
+        self._configure_logging = configure_logging
 
         self.__cache = {
             "users":{}, "channels":{},
             "guilds": {}, "roles": {}
         }
 
+        # in-flight lookups, so concurrent events share one request
+        self.__inflight = {}
+        # running event-handler tasks (kept so they aren't garbage collected)
+        self.__tasks = set()
+
+    def _once(self, key, fn, *args):
+        """Run ``fn(*args)`` once per ``key`` at a time; concurrent callers
+        with the same key all wait on the same request."""
+        task = self.__inflight.get(key)
+        if task is None:
+            task = asyncio.ensure_future(fn(*args))
+            self.__inflight[key] = task
+            task.add_done_callback(
+                lambda _t, k=key: self.__inflight.pop(k, None)
+            )
+        return asyncio.shield(task)
+
     async def _load_bot_info(self):
         my_info = await API.get(self.session, "/me")
 
@@ -52,16 +77,10 @@ class App:
             is_bot=True
         )
 
-    async def _cache_members(
-        self, id
-    ):
-        _members_data = (await API.get(
-            self.session, f"/servers/{id}/members"
-        ))["members"]
-
+    def _build_members(self, data):
         members = []
 
-        for _user_data in _members_data:
+        for _user_data in data["members"]:
             roles = [
                 self.__cache["roles"][role_id]
                 for role_id in _user_data["roles"]
@@ -72,7 +91,7 @@ class App:
                 Member(
                     bot=self,
                     guild=None, roles=roles,
-                    id=id,
+                    id=_user_data.get("id", _user_data.get("user_id")),
                     name = _user_data["username"],
                     display_name = _user_data["display_name"],
                     badges = _user_data["badges"],
@@ -87,13 +106,7 @@ class App:
 
         return members
 
-    async def _cache_roles(
-        self, id
-    ):
-        _roles_data = (await API.get(
-            self.session, f"/servers/{id}/roles"
-        ))
-
+    def _build_roles(self, id, _roles_data):
         roles = []
 
         for role in _roles_data["roles"]:
@@ -120,20 +133,37 @@ class App:
     async def fetch_guild(
         self, id
     ) -> Guild:
-        _guild_data = (await API.get(
-            self.session, f"/servers/{id}"
-        ))["server"]
+        # The server, roles and members endpoints don't depend on each other,
+        # so request them together (one round trip instead of three), and
+        # look up the owner as soon as the server payload is in.
+        server_t = asyncio.ensure_future(
+            API.get(self.session, f"/servers/{id}")
+        )
+        roles_t = asyncio.ensure_future(
+            API.get(self.session, f"/servers/{id}/roles")
+        )
+        members_t = asyncio.ensure_future(
+            API.get(self.session, f"/servers/{id}/members")
+        )
+        try:
+            _guild_data = (await server_t)["server"]
+            owner, roles_data, members_data = await asyncio.gather(
+                self.find_user(_guild_data["owner_id"]),
+                roles_t, members_t
+            )
+        except BaseException:
+            for t in (server_t, roles_t, members_t):
+                t.cancel()
+            raise
 
-        roles = await self._cache_roles(id)
-        members = await self._cache_members(id)
+        roles = self._build_roles(id, roles_data)
+        members = self._build_members(members_data)
 
         return Guild(
             self,
             id = id,
             name=_guild_data["name"],
-            owner=await self.find_user(
-                _guild_data["owner_id"]
-            ),
+            owner=owner,
             member_count = _guild_data["member_count"],
             discoverable = _guild_data["discoverable"],
             created_at = _guild_data["created_at"],
@@ -149,8 +179,12 @@ class App:
     ):
         guild = self.get_guild(id)
         if guild is None:
-            guild = await self.fetch_guild(id)
-            self.__cache["guilds"]=guild
+            guild = await self._once(("guild", id), self._load_guild, id)
+        return guild
+
+    async def _load_guild(self, id):
+        guild = await self.fetch_guild(id)
+        self.__cache["guilds"][id] = guild
         return guild
 
     def get_guild(
@@ -184,8 +218,12 @@ class App:
     ):
         channel = self.get_channel(id)
         if channel is None:
-            channel = await self.fetch_channel(id)
-            self.__cache["channels"][id] = channel
+            channel = await self._once(("channel", id), self._load_channel, id)
+        return channel
+
+    async def _load_channel(self, id):
+        channel = await self.fetch_channel(id)
+        self.__cache["channels"][id] = channel
         return channel
 
     def get_channel(
@@ -223,11 +261,12 @@ class App:
         user = self.get_user(id)
 
         if user is None:
-            user = await self.fetch_user(
-                id
-            )
+            user = await self._once(("user", id), self._load_user, id)
+        return user
 
-            self.__cache["users"][id]=user
+    async def _load_user(self, id):
+        user = await self.fetch_user(id)
+        self.__cache["users"][id] = user
         return user
 
     def get_user(
@@ -256,45 +295,96 @@ class App:
             channel=channel
         )
 
-    async def _parse_arguments(self, content):
-        return await parser.parse_args(self, content)
+    async def _parse_arguments(self, content, command=None):
+        return await parser.parse_args(self, content, command)
 
     async def _handle_prefix_command(self, ctx):
-        if ctx.message.content.startswith(self.prefix):
-            if " " in ctx.message.content:
-                name, raw = ctx.message.content.removeprefix(self.prefix).split(" ", maxsplit=1)
-            else:
-                name = ctx.message.content.removeprefix(self.prefix)
-                raw = ""
-            arguments = await self._parse_arguments(
-                raw
-            )
+        content = ctx.message.content
+        if not content.startswith(self.prefix):
+            return False
+
+        parts = content[len(self.prefix):].split(None, 1)
+        if not parts:
+            return False  # nothing but the prefix
+        name = parts[0].lower()
+        raw = parts[1] if len(parts) > 1 else ""
+
+        cmd = self.__commands.get(name) or self.__aliases.get(name)
+        if cmd is None:
+            raise UnknownCommand(f"Unknown command '{name}'.")
+
+        # Arguments are parsed per the command's signature, so this is also
+        # where bad types are caught (BadArgument) and, right after, wrong
+        # counts (MissingArgument / TooManyArguments).
+        arguments = await self._parse_arguments(raw, cmd)
+        cmd.check_arguments(arguments)
+
+        log.debug(
+            "Command '%s' invoked by %s",
+            cmd.name, getattr(ctx.message.author, "name", "?")
+        )
+        try:
+            await cmd.func(ctx, *arguments)
+        except CommandError:
+            raise
+        except Exception as e:
+            raise CommandInvokeError(e, command=cmd) from e
 
-            cmd = None
-            if name in self.__commands:
-                cmd = self.__commands[name.lower()]
-            elif name in self.__aliases:
-                cmd = self.__aliases[name.lower()]
-            else:
-                raise UnknownCommand(
-                    f"Unhandled command '{name.lower()}'!"
-                )
-                
-            await cmd.func(
-                ctx, *arguments
+        return True
+
+    async def process_command(self, ctx):
+        """Run the command in ``ctx.message`` if it is one.
+
+        Returns whether a command ran. Problems (unknown command, wrong
+        arguments, an exception inside the command) don't propagate: they go
+        to the ``command_error`` event handler if you registered one, or are
+        handled by :meth:`_default_command_error` otherwise.
+        """
+        try:
+            return await self._handle_prefix_command(ctx)
+        except CommandError as e:
+            await self._on_command_error(ctx, e)
+            return False
+
+    async def _on_command_error(self, ctx, error):
+        handler = self.__event_handlers.get("command_error")
+        if handler is None:
+            await self._default_command_error(ctx, error)
+            return
+        try:
+            await handler(ctx, error)
+        except Exception:
+            log.exception("Exception in the 'command_error' handler")
+
+    async def _default_command_error(self, ctx, error):
+        if isinstance(error, UnknownCommand):
+            # people type "!!!" or "!lol" all the time; don't answer those
+            log.debug("%s", error)
+            return
+
+        if isinstance(error, CommandInvokeError):
+            cmd = error.command
+            log.error(
+                "Command '%s' failed", cmd.name if cmd else "?",
+                exc_info=error.original
             )
+            return
 
-            return True
-        return False
+        # The person used the command wrong, so tell them how to use it.
+        author = getattr(ctx.message.author, "name", "?")
+        log.info("%s: %s (from %s)", type(error).__name__, error, author)
 
-    async def process_command(self, ctx):
-        await self._handle_prefix_command(
-            ctx
-        )
+        reply = str(error)
+        if error.command is not None:
+            reply += f"\nUsage: `{error.command.usage(self.prefix)}`"
+        try:
+            await ctx.reply(reply)
+        except Exception:
+            log.exception("Couldn't send the command error message")
 
     async def on_message(self, ctx):
         if ctx.is_bot: return
-        await process_command(ctx)
+        await self.process_command(ctx)
 
     async def _handle_event(self, session: aiohttp.ClientSession, ev):
         d = ev["data"]
@@ -306,6 +396,13 @@ class App:
                 )
             )
 
+    async def _dispatch(self, ev):
+        log.debug("Event '%s' (id %s)", ev["type"], ev["id"])
+        try:
+            await self._handle_event(self.session, ev)
+        except Exception:
+            log.exception("Unhandled exception in event '%s'", ev["type"])
+
     async def _init_commands(self):
         _commands = []
         for name, func in self.__commands.items():
@@ -318,12 +415,17 @@ class App:
             "/commands",
             {"commands": _commands}
         )
+        log.info(
+            "Registered %d command(s): %s",
+            len(_commands), ", ".join(c["name"] for c in _commands) or "-"
+        )
 
     async def _event_loop(self):
         async with aiohttp.ClientSession() as self.session:
             self.session._bearer_token=self._token
 
             self.user = await self._load_bot_info()
+            log.info("Logged in as %s (id %s)", self.user.name, self.user.id)
             await self._init_commands()
 
             events_init = await API.get(self.session, "/events?after=0&wait=0")
@@ -333,37 +435,58 @@ class App:
             if "ready" in self.__event_handlers:
                 await self.__event_handlers["ready"]()
 
-            while True:
-                try:
-                    out = await API.get(self.session, f"/events?after={last}&wait=25")
-                    fails = 0
-                except Exception as e:
-                    fails += 1
-                    if "(401)" in str(e):
-                        raise ImproperToken("Please check if your token is correctly used!")
-                    wait = min(30, 2 ** fails)
-                    
-                    print(f"retrying in {wait}s:", e)
-                    
-                    await asyncio.sleep(wait)
-                    continue
-                for ev in out["events"]:
-                    if ev["id"] <= last:
-                        continue
-                    last = ev["id"]
+            try:
+                while True:
                     try:
-                        await self._handle_event(self.session, ev)
-                    except Exception as e: 
-                        traceback.print_exc()
-                                        
+                        out = await API.get(self.session, f"/events?after={last}&wait=25")
+                        if fails:
+                            log.info("Connection to Yapper restored")
+                        fails = 0
+                    except Exception as e:
+                        fails += 1
+                        if "(401)" in str(e):
+                            raise ImproperToken("Please check if your token is correctly used!")
+                        wait = min(30, 2 ** fails)
+
+                        log.warning("Problem reaching Yapper: %s. Retrying in %ss", e, wait)
+
+                        await asyncio.sleep(wait)
+                        continue
+                    for ev in out["events"]:
+                        if ev["id"] <= last:
+                            continue
+                        last = ev["id"]
+                        # Run each event in its own task so one slow handler
+                        # doesn't hold up the others or the next poll.
+                        task = asyncio.create_task(self._dispatch(ev))
+                        self.__tasks.add(task)
+                        task.add_done_callback(self.__tasks.discard)
+            finally:
+                # let in-flight handlers finish cancelling before the
+                # session is closed underneath them
+                tasks = list(self.__tasks)
+                for task in tasks:
+                    task.cancel()
+                if tasks:
+                    await asyncio.gather(*tasks, return_exceptions=True)
+
 
     def event(self, event_type: str):
+        """Register a coroutine as the handler for ``event_type``.
+
+        Besides Yapper's own events (``"message"``, ``"ready"``) there is
+        ``"command_error"``: ``async def handler(ctx, error)``, called when a
+        command is unknown, given bad arguments, or raises. ``error`` is a
+        :class:`yappy.errors.CommandError`. Registering it replaces the
+        default behaviour (replying with the problem and a usage line).
+        """
         def wrapper(func):
             if not inspect.iscoroutinefunction(func):
                 raise InvalidSignature(f"Expected event handler for '{event_type}' to be a coroutine!")
             self.__event_handlers[
                 event_type
             ] = func
+            return func
         return wrapper
 
     def command(
@@ -386,16 +509,19 @@ class App:
 
            for alias in aliases:
                self.__aliases[alias.lower()] = self.__commands[name.lower()]
+           return func
         return wrapper
 
     def run(self, token: str):
         self._token = token
 
-        self._yappy_loop = asyncio.new_event_loop()
-        asyncio.set_event_loop(self._yappy_loop)
+        if self._configure_logging:
+            setup_logging(verbose=self._verbose)
 
+        # asyncio.run turns Ctrl+C into a cancellation of the main task, so
+        # _event_loop unwinds normally and the HTTP session gets closed.
         try:
-            self._yappy_loop.run_until_complete(self._event_loop())
-        finally:
-            self._yappy_loop.close()
+            asyncio.run(self._event_loop())
+        except KeyboardInterrupt:
+            log.info("Shutting down")
 __all__=["App"]

yappy/core.py

@@ -1,8 +1,15 @@
 from .api import *
 from typing import Callable
+import inspect
+import logging
+import typing
 import urllib.parse
+from dataclasses import dataclass
+from .errors import InvalidSignature, MissingArgument, TooManyArguments
 from .utils import get_asset_url
 
+log = logging.getLogger(__name__)
+
 class Assets:
     def __init__(self,
         avatar: str = "",
@@ -39,6 +46,13 @@ class Bot(User):
         super().__init__(**kwargs)
         self.owner_id = owner_id
 
+@dataclass(frozen=True)
+class CommandParam:
+    """One argument a command accepts (not counting ``ctx``)."""
+    name: str
+    annotation: object = inspect.Parameter.empty
+    required: bool = True
+
 class Command:
     def __init__(self,
         name: str,
@@ -51,6 +65,65 @@ class Command:
         self.description = description
         self.func = func
 
+        self.params: list[CommandParam] = []
+        self.var_positional: CommandParam | None = None
+        if func is not None:
+            self._inspect_signature()
+
+    def _inspect_signature(self):
+        P = inspect.Parameter
+        params = list(inspect.signature(self.func).parameters.values())
+
+        if not params or params[0].kind not in (
+            P.POSITIONAL_ONLY, P.POSITIONAL_OR_KEYWORD
+        ):
+            raise InvalidSignature(
+                f"Command '{self.name}' must accept 'ctx' as its first argument!"
+            )
+
+        try:
+            hints = typing.get_type_hints(self.func)
+        except Exception:
+            # unresolvable annotations: treat them as "no annotation"
+            hints = {}
+
+        for p in params[1:]:
+            ann = hints.get(p.name, p.annotation)
+            if p.kind in (P.POSITIONAL_ONLY, P.POSITIONAL_OR_KEYWORD):
+                self.params.append(
+                    CommandParam(p.name, ann, p.default is P.empty)
+                )
+            elif p.kind is P.VAR_POSITIONAL:
+                self.var_positional = CommandParam(p.name, ann, False)
+            elif p.kind is P.KEYWORD_ONLY and p.default is P.empty:
+                raise InvalidSignature(
+                    f"Command '{self.name}' has a required keyword-only "
+                    f"argument '{p.name}', which can't be filled from chat!"
+                )
+
+    def param_for(self, index: int) -> CommandParam | None:
+        """The parameter that the argument at ``index`` is bound to."""
+        if index < len(self.params):
+            return self.params[index]
+        return self.var_positional
+
+    def check_arguments(self, args: list):
+        """Raise if ``args`` doesn't fit this command's parameters."""
+        required = sum(1 for p in self.params if p.required)
+        if len(args) < required:
+            raise MissingArgument(self.params[len(args)].name, command=self)
+        if self.var_positional is None and len(args) > len(self.params):
+            raise TooManyArguments(len(self.params), len(args), command=self)
+
+    def usage(self, prefix: str = "") -> str:
+        parts = [
+            f"<{p.name}>" if p.required else f"[{p.name}]"
+            for p in self.params
+        ]
+        if self.var_positional is not None:
+            parts.append(f"[{self.var_positional.name}...]")
+        return " ".join([f"{prefix}{self.name}", *parts])
+
 class Permissions:
     def __init__(self, **perms):
         self._perms = perms
@@ -104,42 +177,50 @@ class Guild:
         }}
 
         for m in members:
-            self._cache[m.id] = m
+            if m.id is not None:
+                self._cache["members"][m.id] = m
             m. guild = self
     async def find_member(self, mid):
         member = self.get_member(mid)
         if member is None:
-            _user_data = (await API.get(
-                self.bot.session,
-                f"/servers/{self.id}/members/{mid}"
-            ))["member"]
-
-            roles = [
-                self._cache["roles"][role_id]
-                for role_id in _user_data["roles"]
-                if role_id in self._cache["roles"]
-            ]
-            
-            member = Member(
-                bot=self.bot,
-                guild=self, roles=roles,
-                id=id,
-                name = _user_data["username"],
-                display_name = _user_data["display_name"],
-                badges = _user_data["badges"],
-                joined_at = _user_data["joined_at"],
-                nickname = _user_data["nickname"],
-                assets = Assets(
-                    avatar = "https://files.yapper.website/avatars/"+_user_data.get("avatar_path",""),
-                    banner = "https://files.yapper.website/banners/"+_user_data.get("banner_path", "")
-                ),
+            # concurrent lookups of the same member share one request
+            member = await self.bot._once(
+                ("member", self.id, mid), self._load_member, mid
             )
+        return member
+
+    async def _load_member(self, mid):
+        _user_data = (await API.get(
+            self.bot.session,
+            f"/servers/{self.id}/members/{mid}"
+        ))["member"]
 
-            self._cache["members"][mid] = member
-            
+        roles = [
+            self._cache["roles"][role_id]
+            for role_id in _user_data["roles"]
+            if role_id in self._cache["roles"]
+        ]
+
+        member = Member(
+            bot=self.bot,
+            guild=self, roles=roles,
+            id=mid,
+            name = _user_data["username"],
+            display_name = _user_data["display_name"],
+            badges = _user_data["badges"],
+            joined_at = _user_data["joined_at"],
+            nickname = _user_data["nickname"],
+            assets = Assets(
+                avatar = "https://files.yapper.website/avatars/"+_user_data.get("avatar_path",""),
+                banner = "https://files.yapper.website/banners/"+_user_data.get("banner_path", "")
+            ),
+        )
+
+        self._cache["members"][mid] = member
         return member
+
     def get_member(self, mid):
-        return self._cache.get(mid, None)
+        return self._cache["members"].get(mid, None)
 
 class Channel:
     def __init__(self,

yappy/errors.py

@@ -1,8 +1,79 @@
-class ImproperToken(Exception):
+class YappyError(Exception):
+    """Base class for all YapPy errors."""
+
+
+class ImproperToken(YappyError):
     pass
 
-class InvalidSignature(Exception):
+
+class InvalidSignature(YappyError):
     pass
-    
-class UnknownCommand(Exception):
+
+
+class CommandError(YappyError):
+    """Base class for errors raised while handling a command.
+
+    ``str(error)`` is a message that is safe to show to the person who ran
+    the command. ``command`` is the :class:`~yappy.core.Command` involved
+    (``None`` if the command couldn't be found).
+    """
+
+    def __init__(self, message: str = "", *, command=None):
+        super().__init__(message)
+        self.command = command
+
+
+class UnknownCommand(CommandError):
     pass
+
+
+class MissingArgument(CommandError):
+    """A required argument was not given."""
+
+    def __init__(self, param: str, *, command=None):
+        super().__init__(
+            f"Missing required argument '{param}'.", command=command
+        )
+        self.param = param
+
+
+class TooManyArguments(CommandError):
+    """More arguments were given than the command accepts."""
+
+    def __init__(self, expected: int, given: int, *, command=None):
+        noun = "argument" if expected == 1 else "arguments"
+        super().__init__(
+            f"Too many arguments: expected at most {expected} {noun}, "
+            f"got {given}.",
+            command=command,
+        )
+        self.expected = expected
+        self.given = given
+
+
+class BadArgument(CommandError):
+    """An argument couldn't be converted to what the command expects."""
+
+    def __init__(self, param: str, value, expected: str, *, command=None):
+        shown = str(value)
+        if len(shown) > 40:
+            shown = shown[:37] + "..."
+        super().__init__(
+            f"Invalid value {shown!r} for '{param}': expected {expected}.",
+            command=command,
+        )
+        self.param = param
+        self.value = value
+        self.expected = expected
+
+
+class CommandInvokeError(CommandError):
+    """The command itself raised an exception. The original is ``original``."""
+
+    def __init__(self, original: BaseException, *, command=None):
+        name = command.name if command is not None else "?"
+        super().__init__(
+            f"Command '{name}' raised {type(original).__name__}: {original}",
+            command=command,
+        )
+        self.original = original

yappy/logger.py

@@ -0,0 +1,69 @@
+"""Logging for YapPy.
+
+YapPy logs through the standard :mod:`logging` module under the ``"yappy"``
+logger (``yappy.app``, ``yappy.api``, ...). :func:`setup_logging` attaches a
+`Rich <https://rich.readthedocs.io>`_ handler so output is coloured and
+exceptions are printed as readable tracebacks.
+
+``App.run()`` calls it for you. To take over logging yourself, create the app
+with ``App(configure_logging=False)`` and add your own handlers to
+``logging.getLogger("yappy")``.
+"""
+
+import asyncio
+import logging
+
+import aiohttp
+from rich.console import Console
+from rich.logging import RichHandler
+
+LOGGER_NAME = "yappy"
+_MARKER = "_yappy_rich_handler"
+
+
+def setup_logging(
+    level: int | str | None = None,
+    *,
+    verbose: bool = False,
+    console: Console | None = None,
+    show_locals: bool = False,
+) -> logging.Logger:
+    """Send YapPy's logs to the terminal using Rich.
+
+    :param level: a ``logging`` level. Defaults to ``DEBUG`` if ``verbose``
+        else ``INFO``.
+    :param verbose: also show debug output (events, HTTP calls, command
+        invocations) and prefix each line with the module it came from.
+    :param console: a ``rich.console.Console`` to print to.
+    :param show_locals: include local variables in exception tracebacks.
+
+    Safe to call more than once; it replaces the handler it added before.
+    """
+    if level is None:
+        level = logging.DEBUG if verbose else logging.INFO
+
+    logger = logging.getLogger(LOGGER_NAME)
+    for handler in list(logger.handlers):
+        if getattr(handler, _MARKER, False):
+            logger.removeHandler(handler)
+
+    handler = RichHandler(
+        console=console,
+        show_path=False,
+        markup=False,  # chat content in log messages must not be parsed as markup
+        rich_tracebacks=True,
+        tracebacks_show_locals=show_locals,
+        tracebacks_suppress=[aiohttp, asyncio],
+        log_time_format="[%H:%M:%S]",
+        omit_repeated_times=False,
+    )
+    handler.setFormatter(
+        logging.Formatter("%(name)s  %(message)s" if verbose else "%(message)s")
+    )
+    setattr(handler, _MARKER, True)
+
+    logger.addHandler(handler)
+    logger.setLevel(level)
+    # we own the output; don't print every line a second time via the root logger
+    logger.propagate = False
+    return logger

yappy/parser.py

@@ -1,6 +1,34 @@
+import inspect
+import logging
+import math
 import re
 from typing import Any, List, Union
 
+from .core import Channel, Role, User
+from .errors import BadArgument
+
+log = logging.getLogger(__name__)
+
+# What a person sees when an argument doesn't fit the annotation.
+_EXPECTED = {
+    int: "a whole number",
+    float: "a number",
+    bool: "true or false",
+    User: "a user mention like <@123>",
+    Channel: "a channel mention like <#123>",
+    Role: "a role mention like <@&123>",
+}
+_NOT_FOUND = {
+    User: "a user that exists",
+    Channel: "a channel that exists",
+    Role: "a role that exists",
+}
+_MODELS = (User, Channel, Role)
+_INT = re.compile(r'^[+-]?[0-9]+$')
+_TRUE = {"true", "yes", "y", "on", "1"}
+_FALSE = {"false", "no", "n", "off", "0"}
+
+
 class CommandParser:
     def __init__(self):
         self.token_regex = re.compile(
@@ -13,41 +41,98 @@ class CommandParser:
         self.channel_regex = re.compile(r'^<#([0-9\-]+)>$|^<#(.+)>$')
         self.role_regex = re.compile(r'^<@&([0-9\-]+)>$|^<@&(.+)>$')
 
-    async def parse_args(self, bot, text: str) -> List[Any]:
+    async def parse_args(self, bot, text: str, command=None) -> List[Any]:
+        """Split ``text`` into arguments.
+
+        When ``command`` is given, each argument is converted according to
+        the annotation of the parameter it will be passed to (``str``,
+        ``int``, ``float``, ``bool``, ``User``, ``Channel`` or ``Role``) and
+        a :class:`~yappy.errors.BadArgument` is raised if it doesn't fit.
+        Without annotations the type is guessed, as before.
+        """
         parsed_arguments = []
-        
-        for match in self.token_regex.finditer(text):
+
+        for index, match in enumerate(self.token_regex.finditer(text)):
             dq_str, sq_str, _raw, unquoted = match.groups()
-            
+
             if dq_str is not None:
-                parsed_arguments.append(dq_str.encode().decode('unicode_escape'))
-                continue
-            if sq_str is not None:
-                parsed_arguments.append(sq_str.encode().decode('unicode_escape'))
-                continue
-                
-            if _raw is not None:
-                parsed_arguments.append(await self._process_mentions(bot, _raw))
-                continue
-                
-            if unquoted is not None:
-                parsed_arguments.append(self._parse_primitive(unquoted))
-                
+                kind, token = "quoted", dq_str.encode().decode('unicode_escape')
+            elif sq_str is not None:
+                kind, token = "quoted", sq_str.encode().decode('unicode_escape')
+            elif _raw is not None:
+                kind, token = "mention", _raw
+            else:
+                kind, token = "bare", unquoted
+
+            param = command.param_for(index) if command is not None else None
+            parsed_arguments.append(
+                await self._convert(bot, kind, token, param, index, command)
+            )
+
         return parsed_arguments
 
+    async def _convert(self, bot, kind, token, param, index, command):
+        hint = param.annotation if param is not None else inspect.Parameter.empty
+        name = param.name if param is not None else f"argument {index + 1}"
+
+        def bad(expected):
+            return BadArgument(name, token, expected, command=command)
+
+        if hint is str:
+            return token
+
+        if hint is int:
+            if kind == "mention" or not _INT.match(token):
+                raise bad(_EXPECTED[int])
+            return int(token)
+
+        if hint is float:
+            try:
+                value = float(token) if kind != "mention" else math.nan
+            except ValueError:
+                value = math.nan
+            if not math.isfinite(value):
+                raise bad(_EXPECTED[float])
+            return value
+
+        if hint is bool:
+            word = token.lower()
+            if kind != "mention" and word in _TRUE:
+                return True
+            if kind != "mention" and word in _FALSE:
+                return False
+            raise bad(_EXPECTED[bool])
+
+        # No annotation (or one we don't convert): same behaviour as before.
+        if kind == "quoted":
+            value = token
+        elif kind == "mention":
+            try:
+                value = await self._process_mentions(bot, token)
+            except RuntimeError as e:
+                # the API said no (404 etc.); don't leak its message to chat
+                log.debug("Couldn't resolve mention %r: %s", token, e)
+                raise bad(_NOT_FOUND.get(hint, "a mention of something that exists"))
+        else:
+            value = self._parse_primitive(token)
+
+        if hint in _MODELS and not isinstance(value, hint):
+            raise bad(_EXPECTED[hint])
+        return value
+
     async def _process_mentions(self, bot, token: str) -> Any:
         if user_match := self.user_regex.match(token):
             user_id = user_match.group(1) or user_match.group(2)
             return await self._parse_user(bot, user_id)
-            
+
         if channel_match := self.channel_regex.match(token):
             channel_id = channel_match.group(1) or channel_match.group(2)
             return await self._parse_channel(bot, channel_id)
-            
+
         if role_match := self.role_regex.match(token):
             role_id = role_match.group(1) or role_match.group(2)
             return await self._parse_role(bot, role_id)
-            
+
         return token
 
     def _parse_primitive(self, token: str) -> Union[int, float, str]:

python_yappy-0.1.1.dist-info/RECORD

@@ -1,11 +0,0 @@
-yappy/__init__.py,sha256=BZU8ktPMVc9XeJ5YJeeCAPCjRyaxYIU_zusvjiSi5_Q,21
-yappy/api.py,sha256=_v1r9xPqrqmNwiz7ESnIsrRrzXNrm34eem7XUa4UAWU,2392
-yappy/app.py,sha256=vT4MKygpFmZoc6yu8Uu16hxldNjt5cE2NB-EgFvhifc,11651
-yappy/consts.py,sha256=0pIUIY1Ayo6_q3XhWr9hvKLgOT7TC9RgsjPZNVYy8QQ,51
-yappy/core.py,sha256=quCOfJPjVzUbwdK2NeH3IN3Yr8sNOaQ6JZoMVtELPDk,8110
-yappy/errors.py,sha256=BZ42Du8XWA_SY9tR5Ye8gVWWVKAvRDZZ8Grt_CoOOZs,133
-yappy/parser.py,sha256=XgMXkXHyuL_-oH6rpsbQcnmO5KQrNADIT20GH4-C1LM,2583
-yappy/utils.py,sha256=s7wmPTflqTAIgeAtf0a-gWgEfkQaZGKWYEqm2i4MsUM,129
-python_yappy-0.1.1.dist-info/WHEEL,sha256=lrO5MD1WVAWzcbNy_L2BwtfPrcM3KfUFpbKYXLkJX4A,80
-python_yappy-0.1.1.dist-info/METADATA,sha256=gNceBXMHD6CuuMQO07gR6nTMTINHeVP98VmGIG7la98,4663
-python_yappy-0.1.1.dist-info/RECORD,,