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

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

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

@@ -13,60 +13,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"))
 ```
@@ -112,7 +104,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.
@@ -132,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:
@@ -142,6 +194,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.0 → python_yappy-0.1.2}/pyproject.toml

@@ -1,12 +1,13 @@
 [project]
 name = "python-yappy"
-version = "0.1.0"
+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.0 → python_yappy-0.1.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-yappy"
-version = "0.1.0"
+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.2/src/yappy/api.py

@@ -0,0 +1,77 @@
+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 = {
+        "Authorization": f"Bot {session._bearer_token}",
+        "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()
+            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 {}
+        except Exception:
+            err = {}
+
+        msg = err.get("error") if isinstance(err, dict) else None
+        busy = e.status == 503 and isinstance(err, dict) and "retry_after" in err
+                
+        wait = int(e.headers.get("Retry-After") or 0) if e.status == 429 or busy else 0
+                
+        if 0 < wait <= 60 and 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:
+    @staticmethod
+    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._request(session, "GET", path, body, tries)
+
+    @staticmethod
+    async def post(session, path="", body=None, tries=3):
+        return await API._request(session, "POST", path, body, tries)
+
+    @staticmethod
+    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)
+