yapper-bot 0.1.0__py3-none-any.whl

yapper_bot-0.1.0.dist-info/METADATA

@@ -0,0 +1,280 @@
+Metadata-Version: 2.5
+Name: yapper-bot
+Version: 0.1.0
+Summary: Python bot framework and typed client for the Yapper Bot API
+Project-URL: Homepage, https://www.yapper.website/developers
+Project-URL: Documentation, https://www.yapper.website/developers/api
+Project-URL: Source, https://github.com/yapperpy/yapperpy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,bot,chat,discord,sdk,yapper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# yapperpy
+
+A Python package for the [Yapper](https://www.yapper.website) Bot API: a full bot framework with a
+typed REST client, sync and async, and **no runtime dependencies**.
+
+```bash
+pip install yapper-bot
+```
+
+The distribution is `yapper-bot`; the import name is `yapperpy`.
+
+Requires Python 3.10 or newer.
+
+## A bot in ten lines
+
+```python
+import yapperpy
+
+bot = yapperpy.Bot()  # token from YAPPER_BOT_TOKEN
+
+
+@bot.command("ping", "Is the bot alive?")
+def ping(msg):
+    msg.reply("pong")
+
+
+bot.run()
+```
+
+The same bot with asyncio:
+
+```python
+import asyncio
+import yapperpy
+
+bot = yapperpy.AsyncBot()
+
+
+@bot.command("ping", "Is the bot alive?")
+async def ping(msg):
+    await msg.reply("pong")
+
+
+asyncio.run(bot.run())
+```
+
+A callback may be a plain function or a coroutine function: the async runtime awaits whatever it is
+gets, so one cog works in both.
+
+## What a bot can do
+
+| Call | What it does |
+| --- | --- |
+| `@bot.command(name, description)` | Registers a command. People type `/name` or `!name`. |
+| `@bot.on(event)` | Listens for an event: `message`, `command`, `member_join`, `member_leave`, `reaction_add`, `reaction_remove`, `voice_join`, `voice_leave`, `interaction`, `test`, `ready`, `error`. |
+| `@bot.button("vote:")` | Handles clicks on buttons whose `custom_id` starts with `vote:`. A regular expression works too. |
+| `msg.reply(text)` | Answers the message, quoting it. `msg.say(text)` posts in the same channel without a quote. |
+| `msg.args`, `msg.argv` | The rest of the command line, and the same split on spaces. |
+| `i.reply()`, `i.ephemeral()`, `i.update()`, `i.ack()` | Answers a button click: a new message, one only the clicker sees, an edit of the clicked message, or nothing visible. |
+| `bot.add_cog(Cog)` | Groups commands, listeners and buttons in one class. |
+| `bot.load_extensions("cogs")` | Loads every `.py` file in a folder. `bot.unload_extension` and `bot.reload_extension` work while the bot runs. |
+| `bot.send(channel_id, text)` | Posts a message. |
+
+## Cogs
+
+A cog is a class with commands, listeners and buttons in it:
+
+```python
+# cogs/fun.py
+import yapperpy
+
+
+class Fun(yapperpy.Cog):
+    @yapperpy.command("joke", "Tell a joke")
+    async def joke(self, msg):
+        await msg.reply("I know a UDP joke, but you might not get it")
+
+    @yapperpy.listener("member_join")
+    async def hello(self, ev):
+        print(ev.username, "joined")
+
+    def check(self, msg):  # optional: return False to skip this cog
+        return True
+```
+
+```python
+# bot.py
+import yapperpy
+
+bot = yapperpy.AsyncBot()
+bot.load_extensions("cogs")
+asyncio.run(bot.run())
+```
+
+## The API client
+
+The framework is built on a plain API client you can use on its own.
+
+```python
+import yapperpy
+
+with yapperpy.Yapper("yb_...") as client:
+    print(client.bot.get().username)
+    for server in client.servers.list():
+        print(server.name, server.member_count)
+    for channel in client.channels.list(type="text"):
+        print(channel.name)
+    message = client.messages.send(channel.id, "hello", embeds=[yapperpy.Embed().title("Hi")])
+    client.messages.react(channel.id, message.id, "👍")
+```
+
+Every call returns a typed model: `BotProfile`, `User`, `Server`, `Channel`, `Category`, `Message`,
+`Member`, `MemberDetail`, `Role`, `Ban`, `Reaction`, `Command`, `Event`, `VoiceChannel`, `Image`,
+`Embed`, `ActionRow`, `Button`, `Ok`.
+
+Namespaces: `client.bot`, `client.events`, `client.servers`, `client.channels`, `client.messages`,
+`client.interactions`, `client.voice`, `client.users`.
+
+Anything the API does that this package does not cover yet is one call away:
+
+```python
+client.api("GET", "/servers")  # returns plain JSON
+await async_client.api("GET", "/servers")
+```
+
+## Events
+
+The bot long-polls `GET /events` and hands each event to the right listeners. The payload of a
+message event is a `MessageContext`, which has every field of the message plus `reply`, `say` and
+`author_mention`. Other events give you a typed payload: `MemberJoinPayload`, `MemberLeavePayload`,
+`ReactionPayload`, `InteractionPayload`, `VoicePayload`, `TestPayload`.
+
+The last event id is kept in `bot.last_event_id`, so a bot that restarts can pick up where it left
+off. Events are kept by Yapper for one day.
+
+## Buttons and embeds
+
+```python
+import yapperpy
+
+
+@bot.command("vote", "Pizza or not")
+def vote(msg):
+    msg.reply(
+        "Pizza tonight?",
+        components=[
+            yapperpy.row(
+                yapperpy.btn("Yes", "vote:yes", "success", emoji="🍕"),
+                yapperpy.btn("No", "vote:no", "danger"),
+                yapperpy.link_button("Menu", "https://example.com/menu"),
+            )
+        ],
+    )
+
+
+@bot.button("vote:")
+def on_vote(interaction):
+    interaction.ephemeral("You voted " + interaction.custom_id[5:])
+```
+
+A Components V2 layout, where the components are the whole message:
+
+```python
+import yapperpy
+
+bot.send_layout(
+    channel_id,
+    [
+        yapperpy.container(
+            "## Game night",
+            yapperpy.section("**Minecraft**", accessory=yapperpy.btn("Vote", "poll:mc", "primary")),
+            yapperpy.separator(),
+            yapperpy.gallery("https://example.com/a.png"),
+            accent="blue",
+        )
+    ],
+)
+```
+
+## Errors
+
+```
+YapperError
+  YapperValidationError      400
+  YapperAuthError            401
+  YapperPermissionError      403
+  YapperNotFoundError        404
+  YapperConflictError        409
+  YapperRateLimitError       429   .retry_after
+  YapperServiceError         503   .retry_after
+  YapperServerError          other 5xx
+  YapperConnectionError      the network failed
+  YapperTimeoutError         the request timed out
+```
+
+A 429 or a 503 with a `Retry-After` header is waited out and retried automatically. A 429 without
+one is raised right away, because waiting does not help. A failing command goes to the `error`
+listeners, or is printed with a traceback when there are none.
+
+## Configuration
+
+| Setting | How |
+| --- | --- |
+| Token | `YAPPER_BOT_TOKEN`, or `Yapper("yb_...")` |
+| Base URL | `Yapper(base_url=...)`, for a test server |
+| Prefixes | `Bot(prefixes=("/", "!"))` |
+| Bot messages | `Bot(ignore_bots=False)` to answer other bots too |
+| Retries | `Yapper(retry=RetryPolicy(attempts=5))` |
+
+## Development
+
+```bash
+python -m venv .venv
+.venv\Scripts\python.exe -m pip install --editable ".[dev]"
+.venv\Scripts\python.exe -m pytest
+.venv\Scripts\python.exe -m mypy
+.venv\Scripts\python.exe -m ruff check .
+```
+
+`start.bat` sets up the environment and runs `examples/echo_bot.py`.
+
+## Publishing
+
+`publish.bat` builds the wheel and the source archive, checks the metadata and uploads them.
+
+```bat
+publish.bat                  :: upload to PyPI
+publish.bat test             :: upload to TestPyPI instead
+publish.bat --dry-run        :: build and check everything, do not upload
+```
+
+The token comes from a file called `pypi.tkn` in this folder. One line, the whole token:
+
+```
+pypi-AgEIcHlwaS5vcmMFAKEtoken1234567890abcdef
+```
+
+`pypi.tkn` is in `.gitignore` and is never uploaded. If you would rather not keep a file around,
+set the `PYPI_TOKEN` environment variable instead.
+
+The token needs the `pypi` scope for the project `yapper-bot`. The script refuses to upload a
+version that is already on the index, so bump `__version__` in `src/yapperpy/_version.py` first.
+
+## Links
+
+- API reference: https://www.yapper.website/developers/api
+- OpenAPI file: https://www.yapper.website/openapi.json
+- Developer guide: https://www.yapper.website/developers
+
+## License
+
+MIT

yapper_bot-0.1.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+yapperpy/__init__.py,sha256=ZcVzvvVt1tU39hM3oTtj2nrQxWy1tH_7aEjEm6M-BKk,2873
+yapperpy/__main__.py,sha256=iqKmCOGMnFObr5EUI8DdsFqMPizuzyTeDWl-DtN5tzc,1585
+yapperpy/_core.py,sha256=5fFD-bIq7iptmiUbqFKKqblGWmjELZNtapmPiU1NMbs,1736
+yapperpy/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+yapperpy/aio_bot.py,sha256=jlBGbyBjc6jpT7QE-xMinqWpWfvspIVOUSZKaYLEpEY,6121
+yapperpy/aio_client.py,sha256=nrv2Eir_M5yjqDXYdC9nPbqXyFAo2xCqVKV3iDnFJBQ,15417
+yapperpy/bot.py,sha256=ZIMjhuBOvCAaeiQBNcwCWI-lyERFC0ccLYu-ezi9_6Y,5634
+yapperpy/client.py,sha256=f17xBVro6rGhN7LQRjbOqAJOzUgePG_CGEf22geXGTQ,14618
+yapperpy/cogs.py,sha256=ovvdPrnp5v-LzRGt1AIG-HmxclklvhB_GDeait1S9Cc,10085
+yapperpy/components.py,sha256=S3VnGDQWpZhlSf4z__8kJe3jXMuLI8xnQbQlQZoMrYs,3663
+yapperpy/context.py,sha256=U4xnPEm3A_EqKbUjmTinZmABAM9kft7jCL8u1Vf_AHc,3070
+yapperpy/embeds.py,sha256=QMT_dSEUEzzJ6aMOmqCxcCEX3kF0VPexYPTqurqiJv4,2754
+yapperpy/endpoints.py,sha256=Iodrcot-hXie1nDkBgzevdV4LjuFhtBzuVY2vl0hiBk,21260
+yapperpy/enums.py,sha256=gvuyNP7HkhOsoPuZpp5Q_05NBAqwYfKP0w_zcvTkuAk,973
+yapperpy/errors.py,sha256=wjgt-z3Cm7Jw8KsPl3q1_DsrbjF79fnbx7I8upHuCdA,1973
+yapperpy/event_models.py,sha256=pBoTmCJJOi_2qMiRoNurXEOhSIbrXtnzPEGmTOe8Y1U,7916
+yapperpy/events.py,sha256=kufxwGlGwRQthMdXwX3nfbZC5kB45wcaTdScAMJ19UU,2224
+yapperpy/framework.py,sha256=IdWK6J1-AxXJhW4gSlCcoBcD6jbgu-C7SkCVyyyq3is,5837
+yapperpy/models.py,sha256=qPkj6qG1ignzV74SIIFvMrQMfRhEkn_pOf-JMr-xiXA,23734
+yapperpy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+yapperpy/registry.py,sha256=eff1BUxaBbJzNaLnuMhapYhnzXLrQFolPFebV4vEfN0,5844
+yapperpy/retry.py,sha256=UtWBcrjcLMqV9wVOItUOlKr74JKI8xBOKExjqz8KRnM,3170
+yapperpy/_http/__init__.py,sha256=nK0DOlL3nDZ2AB4Efy9r1X8EEFXqyi-8Nb99r4_v7yQ,461
+yapperpy/_http/aio.py,sha256=hQUYjjNS0t4zx37K58_DiYNszYzS64oyGLTQvUjDoc4,6845
+yapperpy/_http/base.py,sha256=PtH2xDh2_jIIxY8lyiVSy_QsnY-oTvK2kep58kUnh4s,2546
+yapperpy/_http/sync.py,sha256=7qUr5U41L0wo0JW7XnrV5OasRrud3r9PEnki0NRoFZM,2994
+yapper_bot-0.1.0.dist-info/METADATA,sha256=vj1MclNpjkRE8UsYtwtnILdksDKUibo7AMcuDYVVDCg,8661
+yapper_bot-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+yapper_bot-0.1.0.dist-info/licenses/LICENSE,sha256=D-u-pnCVEDkVELns6oG0Z9q2RNgUbg0jUJM9oZbDLDY,1078
+yapper_bot-0.1.0.dist-info/RECORD,,

yapper_bot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

yapper_bot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yapperpy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yapperpy/__init__.py

@@ -0,0 +1,153 @@
+from ._version import __version__
+from .aio_bot import AsyncBot
+from .aio_client import AsyncYapper
+from .bot import Bot
+from .client import Yapper
+from .cogs import Cog, button, command, listener
+from .components import (
+    IS_COMPONENTS_V2,
+    btn,
+    container,
+    gallery,
+    layout,
+    link_button,
+    row,
+    section,
+    separator,
+    text,
+    thumbnail,
+)
+from .context import InteractionContext, MessageContext
+from .embeds import Embed
+from .enums import BotStatus, ButtonStyle, CallbackType, ChannelType, EventType
+from .errors import (
+    YapperAuthError,
+    YapperConflictError,
+    YapperConnectionError,
+    YapperError,
+    YapperNotFoundError,
+    YapperPermissionError,
+    YapperRateLimitError,
+    YapperServerError,
+    YapperServiceError,
+    YapperTimeoutError,
+    YapperValidationError,
+)
+from .event_models import (
+    EventPayload,
+    InteractionPayload,
+    MemberJoinPayload,
+    MemberLeavePayload,
+    MessagePayload,
+    ReactionPayload,
+    TestPayload,
+    VoicePayload,
+)
+from .models import (
+    ActionRow,
+    Ban,
+    BotProfile,
+    BulkDeleteResult,
+    Button,
+    Category,
+    Channel,
+    ChannelRow,
+    Command,
+    Event,
+    EventPage,
+    Image,
+    Member,
+    MemberDetail,
+    Message,
+    Ok,
+    PinResult,
+    Reaction,
+    Role,
+    Server,
+    StatusResult,
+    TimeoutResult,
+    User,
+    VoiceChannel,
+    VoiceDisconnectResult,
+    VoiceMoveResult,
+)
+from .models import (
+    Embed as EmbedModel,
+)
+
+__all__ = [
+    "IS_COMPONENTS_V2",
+    "ActionRow",
+    "AsyncBot",
+    "AsyncYapper",
+    "Ban",
+    "Bot",
+    "BotProfile",
+    "BotStatus",
+    "BulkDeleteResult",
+    "Button",
+    "ButtonStyle",
+    "CallbackType",
+    "Category",
+    "Channel",
+    "ChannelRow",
+    "ChannelType",
+    "Cog",
+    "Command",
+    "Embed",
+    "EmbedModel",
+    "Event",
+    "EventPage",
+    "EventPayload",
+    "EventType",
+    "Image",
+    "InteractionContext",
+    "InteractionPayload",
+    "Member",
+    "MemberDetail",
+    "MemberJoinPayload",
+    "MemberLeavePayload",
+    "Message",
+    "MessageContext",
+    "MessagePayload",
+    "Ok",
+    "PinResult",
+    "Reaction",
+    "ReactionPayload",
+    "Role",
+    "Server",
+    "StatusResult",
+    "TestPayload",
+    "TimeoutResult",
+    "User",
+    "VoiceChannel",
+    "VoiceDisconnectResult",
+    "VoiceMoveResult",
+    "VoicePayload",
+    "Yapper",
+    "YapperAuthError",
+    "YapperConflictError",
+    "YapperConnectionError",
+    "YapperError",
+    "YapperNotFoundError",
+    "YapperPermissionError",
+    "YapperRateLimitError",
+    "YapperServerError",
+    "YapperServiceError",
+    "YapperTimeoutError",
+    "YapperValidationError",
+    "__version__",
+    "btn",
+    "button",
+    "command",
+    "container",
+    "gallery",
+    "layout",
+    "link_button",
+    "listener",
+    "row",
+    "section",
+    "separator",
+    "text",
+    "thumbnail",
+]

yapperpy/__main__.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from .aio_client import AsyncYapper
+from .client import Yapper
+from .errors import YapperError
+
+
+def show(client: Yapper) -> None:
+    profile = client.bot.get()
+    print(f"bot:     {profile.username} (id {profile.id})")
+    if profile.display_name:
+        print(f"name:    {profile.display_name}")
+    if profile.bio:
+        print(f"bio:     {profile.bio}")
+    print(f"servers: {len(client.servers.list())}")
+    for server in client.servers.list():
+        print(f"  - {server.name} ({server.id})")
+
+
+async def show_async(client: AsyncYapper) -> None:
+    profile = await client.bot.get()
+    print(f"bot:     {profile.username} (id {profile.id})")
+    if profile.display_name:
+        print(f"name:    {profile.display_name}")
+    if profile.bio:
+        print(f"bio:     {profile.bio}")
+    servers = await client.servers.list()
+    print(f"servers: {len(servers)}")
+    for server in servers:
+        print(f"  - {server.name} ({server.id})")
+
+
+def main(argv: list[str]) -> int:
+    try:
+        if "--async" in argv:
+
+            async def runner() -> None:
+                async with AsyncYapper() as client:
+                    await show_async(client)
+
+            asyncio.run(runner())
+            return 0
+        with Yapper() as client:
+            show(client)
+    except ValueError as exc:
+        print(exc)
+        return 1
+    except YapperError as exc:
+        print(f"{type(exc).__name__}: {exc}")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

yapperpy/_core.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Generic, TypeVar
+
+from ._http.base import USER_AGENT, RawRequest, RawResponse, build_url
+from .endpoints import Request
+from .errors import YapperError, error_for_status
+from .retry import retry_after_from
+
+C = TypeVar("C")
+
+
+class Resource(Generic[C]):
+    def __init__(self, client: C) -> None:
+        self._client = client
+
+
+def prepare(
+    request: Request[Any],
+    *,
+    base_url: str,
+    token: str,
+    user_agent: str = USER_AGENT,
+) -> RawRequest:
+    headers = {
+        "Authorization": f"Bot {token}",
+        "User-Agent": user_agent,
+        "Accept": "application/json",
+    }
+    body: bytes | None = None
+    if request.raw_body is not None:
+        body = request.raw_body
+        headers["Content-Type"] = request.content_type or "application/octet-stream"
+    elif request.json_body is not None:
+        body = json.dumps(request.json_body, separators=(",", ":")).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    return RawRequest(
+        method=request.method,
+        url=build_url(base_url, request.path, request.query),
+        headers=headers,
+        body=body,
+    )
+
+
+def error_from_response(raw: RawResponse) -> YapperError:
+    body: Any
+    try:
+        body = raw.json()
+    except ValueError:
+        body = raw.body[:200].decode("utf-8", "replace")
+    message = f"the request failed with status {raw.status}"
+    if isinstance(body, dict):
+        detail = body.get("error") or body.get("message")
+        if isinstance(detail, str) and detail:
+            message = detail
+    wait = retry_after_from(raw.headers, body)
+    return error_for_status(raw.status, message, body=body, retry_after=wait)

yapperpy/_http/__init__.py

@@ -0,0 +1,27 @@
+from .base import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    USER_AGENT,
+    AsyncTransport,
+    RawRequest,
+    RawResponse,
+    SyncTransport,
+    TransportError,
+    TransportTimeout,
+    build_url,
+    segment,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "USER_AGENT",
+    "AsyncTransport",
+    "RawRequest",
+    "RawResponse",
+    "SyncTransport",
+    "TransportError",
+    "TransportTimeout",
+    "build_url",
+    "segment",
+]