python-yappy 0.1.1__tar.gz → 0.1.2__tar.gz

{python_yappy-0.1.1 → python_yappy-0.1.2}/PKG-INFO

@@ -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.1 → python_yappy-0.1.2}/README.md

@@ -13,7 +13,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
 
@@ -103,7 +104,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.
@@ -123,6 +124,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.1 → python_yappy-0.1.2}/pyproject.toml

@@ -1,12 +1,13 @@
 [project]
 name = "python-yappy"
-version = "0.1.1"
+version = "0.1.2"
 description = "API Bindings for Yapper!"
 readme = "README.md"
 requires-python = ">=3.14"
 dependencies = [
     "aiohttp>=3.14.5",
     "load-dotenv>=0.1.0",
+    "rich>=13.0",
     "uv-build>=0.13.1",
 ]
 

{python_yappy-0.1.1 → python_yappy-0.1.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-yappy"
-version = "0.1.1"
+version = "0.1.2"
 description = "API Bindings for Yapper!"
 readme = "README.md"
 authors = [
@@ -10,6 +10,7 @@ requires-python = ">=3.14"
 dependencies = [
     "aiohttp>=3.14.5",
     "load-dotenv>=0.1.0",
+    "rich>=13.0",
     "uv-build>=0.13.1",
 ]
 

python_yappy-0.1.2/src/yappy/__init__.py

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

{python_yappy-0.1.1 → python_yappy-0.1.2}/src/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