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

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

@@ -1,10 +1,11 @@
 Metadata-Version: 2.3
 Name: python-yappy
-Version: 0.1.0
+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,60 +25,52 @@ 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
 
-Install YapPy using your project's preferred method.
-
-If the package is available on PyPI:
-
-```bash
-pip install yappy
-```
-
-If you are working from a local checkout, install the project from its repository directory:
-
-```bash
-pip install .
-```
-
-The example below uses [`python-dotenv`](https://pypi.org/project/python-dotenv/) to load the bot token from a `.env` file:
 
 ```bash
-pip install python-dotenv
+pip install python-yappy
 ```
 
 ## Quick start
 
-Create a file named `bot.py`:
+This example uses the dotenv module from `pip install load_dotenv`
+Create a file named `main.py`:
 
 ```python
+from yappy import App
 import os
-
 from dotenv import load_dotenv
-from yappy import App
-
 load_dotenv()
-
 bot = App(verbose=True)
-
-
-@bot.event("message")
+@bot.event(
+	"message"
+)
 async def on_message(ctx):
-    if ctx.is_bot:
-        return
-
-    await ctx.reply("Hi!")
-
-
+	if ctx.is_bot:
+		return
+	await bot.process_command(ctx)
 @bot.command(
-    name="ping",
-    description="replies with 'Pong!'",
+	name="ping",
+    description="replies with 'Pong!'"
 )
 async def ping(ctx):
-    await ctx.reply("Pong!")
+	await ctx.reply("Pong!")	
 
+@bot.command(
+	name="react",
+	description="React your message with a certain emoji!"
+)
+async def react(ctx, emoji: str):
+	await ctx.message.react(emoji)
+@bot.event(
+	"ready"
+)
+async def on_ready():
+	print("Logged as", bot.user.name)
 
 bot.run(os.getenv("TOKEN"))
 ```
@@ -123,7 +116,7 @@ async def on_message(ctx):
     if ctx.is_bot:
         return
 
-    await ctx.reply("Hello!")
+    await bot.process_command(ctx)
 ```
 
 The event name and handler arguments should match the event interface supported by the installed YapPy version.
@@ -143,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:
@@ -153,6 +206,8 @@ YapPy currently provides these core models:
 | `Message` | Represents a message. |
 | `Channel` | Represents a channel. |
 | `User` | Represents a user. |
+| `Guild` | Represents a guild / server |
+| `Role` | Represents a role |
 
 The example uses the context object (`ctx`) to check `ctx.is_bot` and send a reply with `ctx.reply(...)`. Consult the source code for the currently available attributes and methods of each model.
 

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,5 +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 = {
@@ -7,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 {}
@@ -23,22 +36,42 @@ 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))
-            return await api(session, method, path, body, tries - 1)
+            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
-        
-class api:
+
+class API:
     @staticmethod
-    async def put(session, path="", body=None, tries=3):
-        await api_push(session, "PUT", path, body, tries)
+    async def _request(session, method, path="", body=None, tries=3):
+        return await api_push(session, method, path, body, tries)
+
     @staticmethod
     async def get(session, path="", body=None, tries=3):
-        return await api_push(session, "GET", path, body, tries)
+        return await API._request(session, "GET", path, body, tries)
+
     @staticmethod
     async def post(session, path="", body=None, tries=3):
-        await api_push(session, "POST", path, body, tries)
+        return await API._request(session, "POST", path, body, tries)
+
     @staticmethod
-    async def send(session, channel_id=0, data=None, tries=3):
-        await api_push(session, "POST", f"/channels/{channel_id}/messages", data, tries)
+    async def put(session, path="", body=None, tries=3):
+        return await API._request(session, "PUT", path, body, tries)
+
+    @staticmethod
+    async def patch(session, path="", body=None, tries=3):
+        return await API._request(session, "PATCH", path, body, tries)
+
+    @staticmethod
+    async def delete(session, path="", body=None, tries=3):
+        return await API._request(session, "DELETE", path, body, tries)
+
+    @staticmethod
+    async def send(session, channel_id=0, body=None, tries=3):
+        return await API._request(session, "POST", f"/channels/{channel_id}/messages", body, tries)
+