python-yappy 0.1.0__tar.gz

python_yappy-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.3
+Name: python-yappy
+Version: 0.1.0
+Summary: API Bindings for Yapper!
+Author: H1387Lmao
+Requires-Dist: aiohttp>=3.14.5
+Requires-Dist: load-dotenv>=0.1.0
+Requires-Dist: uv-build>=0.13.1
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# YapPy
+
+**A Python API binding for Yapper.**
+
+YapPy brings a Python-friendly interface to [Yapper](https://yapper.website), a chat platform similar to Discord. It provides familiar models, event handlers, and command decorators so you can build Yapper bots with straightforward asynchronous Python.
+
+> **Project status:** Early development. The current implementation includes `Context`, `Message`, `Channel`, and `User` models, along with bot event and command handling. The API may change as development continues.
+
+## Features
+
+- **Python-first API** — build bot logic using async functions and decorators.
+- **Event handlers** — respond to Yapper events such as incoming messages.
+- **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.
+
+## 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
+```
+
+## Quick start
+
+Create a file named `bot.py`:
+
+```python
+import os
+
+from dotenv import load_dotenv
+from yappy import App
+
+load_dotenv()
+
+bot = App(verbose=True)
+
+
+@bot.event("message")
+async def on_message(ctx):
+    if ctx.is_bot:
+        return
+
+    await ctx.reply("Hi!")
+
+
+@bot.command(
+    name="ping",
+    description="replies with 'Pong!'",
+)
+async def ping(ctx):
+    await ctx.reply("Pong!")
+
+
+bot.run(os.getenv("TOKEN"))
+```
+
+Create a `.env` file beside `bot.py`:
+
+```dotenv
+TOKEN=your_yapper_bot_token
+```
+
+Then run the bot:
+
+```bash
+python bot.py
+```
+
+This example registers a `message` event that replies with `Hi!` to messages not sent by bots, and a `ping` command that replies with `Pong!`.
+
+**Keep your token private.** Do not commit your `.env` file or publish your bot token.
+
+## Core concepts
+
+### `App`
+
+`App` is the main entry point for creating and running a YapPy bot.
+
+```python
+from yappy import App
+
+bot = App(verbose=True)
+bot.run("YOUR_TOKEN")
+```
+
+Set `verbose=True` to enable verbose output while developing. Keep credentials in environment variables rather than hard-coding them in source files.
+
+### Events
+
+Register an event handler with `@bot.event(...)`. Event handlers are asynchronous functions.
+
+```python
+@bot.event("message")
+async def on_message(ctx):
+    if ctx.is_bot:
+        return
+
+    await ctx.reply("Hello!")
+```
+
+The event name and handler arguments should match the event interface supported by the installed YapPy version.
+
+### Commands
+
+Register a command using `@bot.command(...)`:
+
+```python
+@bot.command(
+    name="ping",
+    description="replies with 'Pong!'",
+)
+async def ping(ctx):
+    await ctx.reply("Pong!")
+```
+
+The `name` identifies the command, and `description` describes its purpose. Command registration and invocation behavior depend on the current implementation.
+
+### Context and models
+
+YapPy currently provides these core models:
+
+| Model | Purpose |
+| --- | --- |
+| `Context` | Context for handling an interaction or message event. |
+| `Message` | Represents a message. |
+| `Channel` | Represents a channel. |
+| `User` | Represents a user. |
+
+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.
+
+## Project status
+
+YapPy is under active development. Current implemented areas include:
+
+- `Context`, `Message`, `Channel`, and `User` models
+- Bot event registration and handling
+- Command registration
+- Message replies through the context API
+
+Other features may be planned, incomplete, or unsupported. Check the source code and release notes for the actual capabilities of the version you are using.
+
+## Contributing
+
+Contributions, bug reports, and suggestions are welcome. Before opening a pull request, describe the change clearly and include a minimal reproduction or test where appropriate.
+
+## License
+
+This project is licensed under the MIT License.

python_yappy-0.1.0/README.md

@@ -0,0 +1,165 @@
+# YapPy
+
+**A Python API binding for Yapper.**
+
+YapPy brings a Python-friendly interface to [Yapper](https://yapper.website), a chat platform similar to Discord. It provides familiar models, event handlers, and command decorators so you can build Yapper bots with straightforward asynchronous Python.
+
+> **Project status:** Early development. The current implementation includes `Context`, `Message`, `Channel`, and `User` models, along with bot event and command handling. The API may change as development continues.
+
+## Features
+
+- **Python-first API** — build bot logic using async functions and decorators.
+- **Event handlers** — respond to Yapper events such as incoming messages.
+- **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.
+
+## 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
+```
+
+## Quick start
+
+Create a file named `bot.py`:
+
+```python
+import os
+
+from dotenv import load_dotenv
+from yappy import App
+
+load_dotenv()
+
+bot = App(verbose=True)
+
+
+@bot.event("message")
+async def on_message(ctx):
+    if ctx.is_bot:
+        return
+
+    await ctx.reply("Hi!")
+
+
+@bot.command(
+    name="ping",
+    description="replies with 'Pong!'",
+)
+async def ping(ctx):
+    await ctx.reply("Pong!")
+
+
+bot.run(os.getenv("TOKEN"))
+```
+
+Create a `.env` file beside `bot.py`:
+
+```dotenv
+TOKEN=your_yapper_bot_token
+```
+
+Then run the bot:
+
+```bash
+python bot.py
+```
+
+This example registers a `message` event that replies with `Hi!` to messages not sent by bots, and a `ping` command that replies with `Pong!`.
+
+**Keep your token private.** Do not commit your `.env` file or publish your bot token.
+
+## Core concepts
+
+### `App`
+
+`App` is the main entry point for creating and running a YapPy bot.
+
+```python
+from yappy import App
+
+bot = App(verbose=True)
+bot.run("YOUR_TOKEN")
+```
+
+Set `verbose=True` to enable verbose output while developing. Keep credentials in environment variables rather than hard-coding them in source files.
+
+### Events
+
+Register an event handler with `@bot.event(...)`. Event handlers are asynchronous functions.
+
+```python
+@bot.event("message")
+async def on_message(ctx):
+    if ctx.is_bot:
+        return
+
+    await ctx.reply("Hello!")
+```
+
+The event name and handler arguments should match the event interface supported by the installed YapPy version.
+
+### Commands
+
+Register a command using `@bot.command(...)`:
+
+```python
+@bot.command(
+    name="ping",
+    description="replies with 'Pong!'",
+)
+async def ping(ctx):
+    await ctx.reply("Pong!")
+```
+
+The `name` identifies the command, and `description` describes its purpose. Command registration and invocation behavior depend on the current implementation.
+
+### Context and models
+
+YapPy currently provides these core models:
+
+| Model | Purpose |
+| --- | --- |
+| `Context` | Context for handling an interaction or message event. |
+| `Message` | Represents a message. |
+| `Channel` | Represents a channel. |
+| `User` | Represents a user. |
+
+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.
+
+## Project status
+
+YapPy is under active development. Current implemented areas include:
+
+- `Context`, `Message`, `Channel`, and `User` models
+- Bot event registration and handling
+- Command registration
+- Message replies through the context API
+
+Other features may be planned, incomplete, or unsupported. Check the source code and release notes for the actual capabilities of the version you are using.
+
+## Contributing
+
+Contributions, bug reports, and suggestions are welcome. Before opening a pull request, describe the change clearly and include a minimal reproduction or test where appropriate.
+
+## License
+
+This project is licensed under the MIT License.

python_yappy-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "python-yappy"
+version = "0.1.0"
+description = "API Bindings for Yapper!"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "aiohttp>=3.14.5",
+    "load-dotenv>=0.1.0",
+    "uv-build>=0.13.1",
+]
+
+[[project.authors]]
+name = "H1387Lmao"
+
+[tool.uv.build-backend]
+module-name = "yappy"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.1"]
+build-backend = "uv_build"

python_yappy-0.1.0/pyproject.toml.orig

@@ -0,0 +1,21 @@
+[project]
+name = "python-yappy"
+version = "0.1.0"
+description = "API Bindings for Yapper!"
+readme = "README.md"
+authors = [
+    { name = "H1387Lmao"}
+]
+requires-python = ">=3.14"
+dependencies = [
+    "aiohttp>=3.14.5",
+    "load-dotenv>=0.1.0",
+    "uv-build>=0.13.1",
+]
+
+[tool.uv.build-backend]
+module-name = "yappy"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.1"]
+build-backend = "uv_build"

python_yappy-0.1.0/src/yappy/__init__.py

@@ -0,0 +1 @@
+from .app import App

python_yappy-0.1.0/src/yappy/api.py

@@ -0,0 +1,44 @@
+from .consts import BASE_URL
+import aiohttp
+
+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"
+    }
+
+    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()
+    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:
+            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)
+                    
+        raise RuntimeError(f"{method} {path} failed ({e.status}): {msg or e.message}") from None
+        
+class api:
+    @staticmethod
+    async def put(session, path="", body=None, tries=3):
+        await api_push(session, "PUT", path, body, tries)
+    @staticmethod
+    async def get(session, path="", body=None, tries=3):
+        return await api_push(session, "GET", path, body, tries)
+    @staticmethod
+    async def post(session, path="", body=None, tries=3):
+        await api_push(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)

python_yappy-0.1.0/src/yappy/app.py

@@ -0,0 +1,204 @@
+from .core import *
+from .consts import BASE_URL
+from .api import *
+from .errors import ImproperToken, InvalidSignature
+
+import inspect
+import asyncio
+import aiohttp
+from functools import wraps
+from typing import Callable
+
+class App:
+    def __init__(self, verbose=False):
+        self.__commands = {}
+        self.__event_handlers = {}
+
+        self.user  = None
+        self._token = None
+
+        self._verbose = verbose
+
+        self.__cache = {"users":{}}
+
+    async def _load_bot_info(self):
+        my_info = await api.get(self.session, "/me")
+
+        if self._verbose:
+            print(my_info)
+
+        return Bot(
+            name=my_info["username"],
+            display_name=my_info["display_name"],
+            id=my_info["id"],
+            profile=Profile(
+                avatar=my_info["avatar_url"],
+                banner=my_info["banner_url"],
+            ),
+            bio=my_info["bio"],
+            created_at=my_info["created_at"],
+            
+            owner_id=my_info["bot"]["owner_id"],
+            is_bot=True
+        )
+
+    def get_user(
+        self,
+        id,
+        _data
+    ):
+        if id in self.__cache["users"]:
+            return self.__cache["users"]
+        user = User(
+            name=_data["author"],
+            id=id
+        )
+
+        self.__cache[id]=user
+        return user
+
+    def _build_context(self, ev):
+        d = ev["data"]
+        
+        channel=Channel(
+            self,
+            id=d["channel_id"],
+            name=d["channel_name"]
+        )
+
+        return Context(
+            self,
+            is_bot=ev.get("author_bot", False),
+            message=Message(
+                self,
+                id=d["id"],
+                author=self.get_user(
+                    d["author_id"], d
+                ),
+                channel=channel,
+                created_at=d["created_at"],
+                content=d["content"]
+            ),
+            channel=channel
+        )
+
+    async def _handle_event(self, session: aiohttp.ClientSession, ev):
+        if self._verbose:
+            print(ev)
+        d = ev["data"]
+
+        if ev["type"] in self.__event_handlers:
+            if (cmd_name:=d.get("command")):
+                if cmd_name in self.__commands:
+                    await self.__commands[cmd_name].func(
+                        self._build_context(
+                            ev
+                        )
+                    )
+                elif cmd_name in self.__aliases:
+                    await self.__aliases[cmd_name](
+                        self._build_context(
+                            ev
+                        )
+                    )
+                else:
+                    raise UnknownCommand(
+                        f"Unhandled command '{cmd_name}'!"
+                    )
+            else:
+                await self.__event_handlers[ev["type"]](
+                    self._build_context(
+                        ev
+                    )
+                )
+
+    async def _init_commands(self):
+        _commands = []
+        for name, func in self.__commands.items():
+            _commands.append(
+                {"name": name, "description": func.description}
+            )
+            
+        await api.put(
+            self.session,
+            "/commands",
+            {"commands": _commands}
+        )
+
+    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()
+            await self._init_commands()
+
+            events_init = await api.get(self.session, "/events?after=0&wait=0")
+            last = events_init["last"]
+            fails = 0
+
+            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:
+                        await self._handle_event(self.session, ev)
+                    except Exception as e: 
+                        print("error handling", ev["type"], "event:", e)
+                                        
+
+    def event(self, event_type: str):
+        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 wrapper
+
+    def command(
+        self,
+        name, *,
+        aliases=[],
+        description=""
+    ):
+        def wrapper(
+            func
+        ):
+           if not inspect.iscoroutinefunction(func):
+                raise InvalidSignature(f"Expected command handler for '{name}' to be a coroutine!")
+           self.__commands[name]=Command(
+                name=name,
+                aliases=aliases,
+                description=description,
+                func=func
+            )
+
+           for alias in aliases:
+               self.__aliases[alias] = self.__commands[name]
+
+        return wrapper
+
+    def run(self, token: str):
+        self._token = token
+
+        self._yappy_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._yappy_loop)
+
+        try:
+            self._yappy_loop.run_until_complete(self._event_loop())
+        finally:
+            self._yappy_loop.close()

python_yappy-0.1.0/src/yappy/consts.py

@@ -0,0 +1 @@
+BASE_URL = "https://www.yapper.website/api/bot/v1"

python_yappy-0.1.0/src/yappy/core.py

@@ -0,0 +1,105 @@
+from .api import *
+from typing import Callable
+
+class Profile:
+    def __init__(self,
+        avatar: str = "",
+        banner: str = ""
+    ):
+        self.avatar = avatar
+        self.banner = banner
+
+class User:
+    def __init__(self,
+        name: str ="",
+        display_name: str = "",
+        id=0,
+        profile: Profile | None = None,
+        created_at: str = "",
+        bio: str = "",
+        is_bot: bool = True
+    ):
+        self.name = name
+        self.id = id
+        self.profile = profile
+        self.display_name = display_name
+        self.is_bot = is_bot
+        self.bio = bio
+
+class Bot(User):
+    def __init__(self, owner_id=None, **kwargs):
+        super().__init__(**kwargs)
+        self.owner_id = owner_id
+
+class Command:
+    def __init__(self,
+        name: str,
+        aliases: list[str] = [],
+        description: str = "",
+        func: Callable = None,
+    ):
+        self.name = name
+        self.aliases = aliases
+        self.description = description
+        self.func = func
+
+class Channel:
+    def __init__(self,
+        bot,
+        id=0,
+        name: str = ""
+    ):
+        self.id = id
+        self.bot = bot
+        self.name = name
+
+class Message:
+    def __init__(self,
+        bot,
+        id=0,
+        channel: Channel | None = None,
+        author: User | None = None,
+        created_at: str = "",
+        content: str = ""
+    ):
+        self.id = id
+        self.channel = channel
+        self.bot = bot
+        self.created_at = created_at
+        self.content = content
+
+        self.author = author
+
+class Context:
+    def __init__(self,
+        bot,
+        is_bot: bool = False,
+        message: Message | None = None,
+        channel: Channel | None = None
+    ):
+        self.bot = bot
+        self.is_bot = is_bot
+        self.message = message
+        self.channel = channel
+        
+    async def reply(
+        self,
+        content: str = "Hi"
+    ):
+        await api.send(
+            self.bot.session, self.channel.id, data={
+                "content": content,
+                "reply_to": self.message.id
+            }
+        )
+
+    async def send(
+        self,
+        content: str = "Hi"
+    ):
+        await api.send(
+            self.bot.session, self.channel.id, data={
+                "content": content,
+                "reply_to": None
+            }
+        )

python_yappy-0.1.0/src/yappy/errors.py

@@ -0,0 +1,8 @@
+class ImproperToken(Exception):
+    pass
+
+class InvalidSignature(Exception):
+    pass
+    
+class UnknownCommand(Exception):
+    pass