banterbotapi 0.2.1__tar.gz → 0.2.3__tar.gz

{banterbotapi-0.2.1 → banterbotapi-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: banterbotapi
-Version: 0.2.1
+Version: 0.2.3
 Summary: Python SDK for building bots on Banter (banterchat.org) — discord.py-style.
 Author-email: Banter <contact@banterchat.org>
 License-Expression: MIT

banterbotapi-0.2.3/banterapi/__init__.py

@@ -0,0 +1,69 @@
+"""banterapi — Python SDK for BanterChat bots.
+
+Quickstart:
+
+    import banterapi
+
+    bot = banterapi.Bot(
+        intents=banterapi.Intents.default() | banterapi.Intents.MESSAGE_CONTENT,
+        command_prefix="!",
+    )
+
+    @bot.event
+    async def on_ready():
+        print(f"logged in as {bot.user.username}")
+
+    @bot.command(slash=True, description="Ping the bot")
+    async def ping(ctx):
+        await ctx.reply("pong")
+
+    bot.run("YOUR_BOT_TOKEN")
+
+The library mirrors discord.py conventions where possible. See the Bot,
+Intents, Embed, and Permissions classes for the main entry points.
+"""
+
+__version__ = "0.2.3"
+
+from .client import Bot
+from .intents import Intents
+from .embed import Embed
+from .models import User, Guild, Channel, Member, Role, Message
+from .errors import BanterError, HTTPException, Forbidden, NotFound, RateLimited, GatewayError, LoginFailure, MissingPermissions
+from .permissions import Permissions
+from .commands import (
+    has_permissions,
+    SlashOption,
+    OPTION_STRING, OPTION_INTEGER, OPTION_BOOLEAN,
+    OPTION_USER, OPTION_CHANNEL, OPTION_ROLE,
+)
+from .interactions import Interaction
+
+__all__ = [
+    "__version__",
+    "Bot",
+    "Intents",
+    "Embed",
+    "User",
+    "Guild",
+    "Channel",
+    "Member",
+    "Role",
+    "Message",
+    "Permissions",
+    "has_permissions",
+    # Slash command support
+    "SlashOption",
+    "OPTION_STRING", "OPTION_INTEGER", "OPTION_BOOLEAN",
+    "OPTION_USER", "OPTION_CHANNEL", "OPTION_ROLE",
+    "Interaction",
+    # Errors
+    "BanterError",
+    "HTTPException",
+    "Forbidden",
+    "NotFound",
+    "RateLimited",
+    "GatewayError",
+    "LoginFailure",
+    "MissingPermissions",
+]

banterbotapi-0.2.3/banterapi/client.py

@@ -0,0 +1,561 @@
+"""High-level bot client — the main entry point of the SDK.
+
+:class:`Bot` wires everything together:
+
+* :class:`~banterapi.http.HTTPClient` for REST calls.
+* :class:`~banterapi.gateway.Gateway` for the WebSocket connection.
+* :class:`~banterapi.commands.CommandRegistry` for prefix/slash commands.
+* An event-handler map (``on_ready``, ``on_message``, ...) populated
+  via the :meth:`Bot.event` decorator.
+
+Typical usage::
+
+    bot = Bot(intents=Intents.default() | Intents.MESSAGE_CONTENT)
+
+    @bot.event
+    async def on_ready():
+        print("logged in")
+
+    @bot.command(slash=True, description="Say pong")
+    async def ping(ctx):
+        await ctx.reply("pong")
+
+    bot.run(TOKEN)
+
+:meth:`Bot.run` blocks until the bot disconnects (or ``KeyboardInterrupt``).
+It manages the reconnect loop internally when ``reconnect=True``.
+"""
+
+import asyncio
+import inspect
+import logging
+
+from .commands import Command, CommandRegistry, Context, CommandError, CommandNotFound
+from .gateway import Gateway
+from .http import HTTPClient
+from .intents import Intents
+from .models import User, Guild, Channel, Member, Message
+from .errors import GatewayError
+
+log = logging.getLogger("banterapi.client")
+
+
+# Default REST/gateway URL fragments. Kept as module constants so that
+# the URL derivation in __init__ is easy to trace and future API
+# version bumps only touch these lines.
+_DEFAULT_BASE_URL = "https://banterchat.org"
+_GATEWAY_PATH = "/api/v1/bot/gateway"
+
+
+class Bot:
+    """Main bot entry point.
+
+    Args:
+        intents: :class:`~banterapi.Intents` bitmask controlling which
+            gateway events the server will send. Defaults to
+            :meth:`Intents.default`. If you register a prefix command
+            you almost certainly need
+            ``Intents.default() | Intents.MESSAGE_CONTENT``.
+        base_url: HTTP origin (scheme + host) of the Banter instance.
+            Defaults to ``https://banterchat.org``. Trailing slash is
+            stripped.
+        ws_url: Override for the gateway URL. If ``None`` (default), the
+            SDK derives it from ``base_url`` by switching the scheme
+            (``http`` → ``ws``, ``https`` → ``wss``) and appending the
+            gateway path. Set this only for local/testing setups where
+            REST and gateway live on different hosts.
+        reconnect: If ``True`` (default), :meth:`run` sleeps 5s and
+            reconnects on any transient gateway error. Set ``False``
+            to have :meth:`run` return on the first disconnect.
+        command_prefix: Prefix for text commands (``!`` by default).
+            Messages beginning with this prefix are parsed and routed
+            to registered commands.
+        application_id: Your bot application's ID, used for slash
+            command registration. If empty, the SDK reads it off the
+            READY frame the gateway sends on connect — you usually
+            don't need to pass this explicitly.
+        help_enabled: Register a default ``help`` command that lists
+            registered commands in an embed. ``True`` by default.
+            Disable only if you're providing a custom help command of
+            your own; most users should leave this on.
+        help_color: RGB int (``0xRRGGBB``) used as the embed accent for
+            the default help command. Only applies when
+            ``help_enabled=True``.
+    """
+
+    def __init__(
+        self,
+        intents=None,
+        *,
+        base_url=_DEFAULT_BASE_URL,
+        ws_url=None,
+        reconnect=True,
+        command_prefix="!",
+        application_id="",
+        help_enabled=True,
+        help_color=0x5865f2,
+    ):
+        self.intents = intents if intents is not None else Intents.default()
+        self.base_url = base_url.rstrip("/")
+        # Derive gateway URL from base_url unless explicitly overridden.
+        # http: → ws:, https: → wss:. The path segment lives as a module
+        # constant so /api/v1/bot/* migration is a single-line edit.
+        self.ws_url = ws_url or (
+            self.base_url
+            .replace("http://", "ws://")
+            .replace("https://", "wss://")
+            + _GATEWAY_PATH
+        )
+        self.reconnect = reconnect
+        self.command_prefix = command_prefix
+        self.application_id = application_id
+        self.help_enabled = help_enabled
+        self.help_color = help_color
+        self.user = None
+        self.guilds = {}
+        self._http = None
+        self._gateway = None
+        self._handlers = {}
+        self._commands = CommandRegistry()
+        # _slash_commands stores registration metadata sent to the server
+        # at sync_commands() time: [{name, description, options}, ...].
+        # _slash_handlers maps command-name → coroutine invoked when the
+        # gateway delivers an interaction_create event for that command.
+        # Separate from _commands because slash handlers take an
+        # Interaction, not a (Context, *args) like prefix handlers.
+        self._slash_commands = []
+        self._slash_handlers = {}
+        self._loop = None
+        if self.help_enabled:
+            self._register_default_help()
+
+    def event(self, fn):
+        """Register ``fn`` as an event handler.
+
+        The handler's name must begin with ``on_`` and is looked up
+        against event types the gateway dispatches (``on_ready``,
+        ``on_message``, ``on_reaction_add``, ``on_member_join``, …). One
+        handler per event name — re-decorating with the same name
+        overwrites the previous handler.
+
+        Handlers may be sync or async. Exceptions raised inside a
+        handler are logged and swallowed so one bad handler can't take
+        the bot down.
+
+        Usage::
+
+            @bot.event
+            async def on_ready():
+                print("ready")
+
+        Raises:
+            ValueError: Handler name does not start with ``on_``.
+        """
+        name = fn.__name__
+        if not name.startswith("on_"):
+            raise ValueError("event handlers must be named on_<event>")
+        self._handlers[name] = fn
+        return fn
+
+    def command(self, name=None, aliases=None, help=None, slash=False, description="", options=None):
+        """Register a prefix command (optionally also as a slash command).
+
+        The decorated function is called as ``await fn(ctx, *args)`` —
+        positional arguments are parsed from the message text after the
+        prefix. Argument annotations (``int``, ``float``, ``bool``) are
+        applied automatically by :class:`~banterapi.commands.Command`;
+        ``*args`` and keyword-only (``*, text: str``) signatures are
+        supported.
+
+        Args:
+            name: Command name as typed (without prefix). Defaults to
+                the function name.
+            aliases: Iterable of additional names the command answers
+                to (e.g. ``aliases=["p"]`` for a ``ping`` command).
+            help: Short help text shown in the default ``help`` embed.
+                Defaults to the function's docstring's first line.
+            slash: If ``True``, also register as a slash command at
+                :meth:`sync_commands` time. The user sees it in the
+                ``/`` autocomplete dropdown.
+            description: Slash-command description. Ignored when
+                ``slash=False``. Falls back to ``help`` or the name.
+            options: Iterable of :class:`~banterapi.SlashOption` to
+                expose as typed slash-command arguments. Only
+                applies when ``slash=True``. When a user invokes the
+                slash command, the server parses the typed options
+                and delivers them to the slash handler as
+                ``interaction.options``. Prefix-invocation is
+                unaffected — prefix args continue to parse from the
+                message text via function-signature introspection.
+
+        Usage::
+
+            @bot.command(aliases=["p"], slash=True, description="Health check")
+            async def ping(ctx):
+                await ctx.reply("pong")
+
+        With typed slash options::
+
+            from banterapi import SlashOption, OPTION_INTEGER
+
+            @bot.command(
+                slash=True, description="Roll a die",
+                options=[SlashOption("sides", type=OPTION_INTEGER, required=False)],
+            )
+            async def roll(ctx, sides: int = 6):
+                await ctx.reply(f"🎲 {sides}")
+        """
+        def decorator(fn):
+            cmd = Command(fn, name=name, aliases=aliases, help=help)
+            self._commands.add(cmd)
+            if slash:
+                entry = {
+                    "name": cmd.name,
+                    "description": description or cmd.help or cmd.name,
+                }
+                if options:
+                    # Defer import to avoid a circular: commands.py is
+                    # loaded by client.py, and SlashOption lives there.
+                    from .commands import SlashOption as _SO
+                    entry["options"] = [
+                        (o.to_dict() if isinstance(o, _SO) else dict(o))
+                        for o in options
+                    ]
+                self._slash_commands.append(entry)
+            return fn
+        return decorator
+
+    def slash_command(self, name=None, description="", options=None):
+        """Register a standalone slash command (no prefix twin).
+
+        The decorated function takes a single argument — an
+        :class:`~banterapi.interactions.Interaction` — and responds
+        via ``await interaction.respond(...)``. This differs from
+        :meth:`command` (prefix commands) which takes a
+        :class:`~banterapi.commands.Context` and parses args from
+        message text.
+
+        Use this when the command has structured typed args and makes
+        no sense as a plain-text prefix command, or when you want the
+        command only accessible through the UI autocomplete.
+
+        Args:
+            name: Slash command name. Defaults to the function name.
+            description: Shown in the autocomplete dropdown.
+            options: Iterable of :class:`~banterapi.SlashOption`.
+
+        Usage::
+
+            from banterapi import SlashOption, OPTION_STRING, OPTION_INTEGER
+
+            @bot.slash_command(
+                name="greet",
+                description="Greet a user with a custom message",
+                options=[
+                    SlashOption("name", type=OPTION_STRING),
+                    SlashOption("times", type=OPTION_INTEGER, required=False),
+                ],
+            )
+            async def greet(interaction):
+                n = interaction.options["name"]
+                k = interaction.options.get("times", 1)
+                await interaction.respond(f"Hello {n}! " * k)
+        """
+        def decorator(fn):
+            cmd_name = name or fn.__name__
+            entry = {
+                "name": cmd_name,
+                "description": description or cmd_name,
+            }
+            if options:
+                from .commands import SlashOption as _SO
+                entry["options"] = [
+                    (o.to_dict() if isinstance(o, _SO) else dict(o))
+                    for o in options
+                ]
+            self._slash_commands.append(entry)
+            self._slash_handlers[cmd_name] = fn
+            return fn
+        return decorator
+
+    def _register_default_help(self):
+        from .embed import Embed
+
+        @self.command(name="help", slash=True, description="Show available commands")
+        async def _help(ctx):
+            visible = [c for c in self._commands.all() if not getattr(c, "_hidden", False)]
+            visible.sort(key=lambda c: c.name)
+            e = Embed(
+                title=f"{self.user.username if self.user else 'Bot'} — Commands",
+                description=f"Prefix: `{self.command_prefix}`  ·  {len(visible)} command(s)",
+                color=self.help_color,
+            )
+            lines = []
+            for cmd in visible:
+                aliases = f" · aliases: {', '.join(self.command_prefix + a for a in cmd.aliases)}" if cmd.aliases else ""
+                doc = (cmd.help or "").strip().split("\n", 1)[0]
+                lines.append(f"`{self.command_prefix}{cmd.name}`{aliases} — {doc}" if doc else f"`{self.command_prefix}{cmd.name}`{aliases}")
+            if lines:
+                chunk, chunks = "", []
+                for line in lines:
+                    if len(chunk) + len(line) + 1 > 1000:
+                        chunks.append(chunk)
+                        chunk = line
+                    else:
+                        chunk = f"{chunk}\n{line}" if chunk else line
+                if chunk:
+                    chunks.append(chunk)
+                for i, c in enumerate(chunks):
+                    e.add_field("Commands" if i == 0 else "\u200b", c, inline=False)
+            e.set_footer(f"Type {self.command_prefix}<command> or /<command>")
+            await ctx.reply(embed=e)
+
+    async def sync_commands(self):
+        """Push the bot's slash-command definitions to the server.
+
+        Called automatically on ``on_ready`` when any commands are
+        registered with ``slash=True``. Safe to call manually too — it
+        replaces the server's stored command list for this bot, so
+        calling it a second time with a shorter list deletes any
+        commands no longer present.
+
+        The target application is resolved server-side from the bot
+        token (``PUT /api/v1/bot/applications/@me/commands``) — the
+        ``application_id`` attribute on :class:`Bot` is populated by
+        the READY frame for reference but isn't used in this call.
+
+        Returns:
+            int: Number of commands the server acknowledged. Zero if
+            no slash commands are registered locally.
+        """
+        if not self._slash_commands:
+            return 0
+        result = await self._http.register_commands(self._slash_commands)
+        return result.get("registered", len(self._slash_commands)) if result else 0
+
+    @property
+    def commands(self):
+        return self._commands.all()
+
+    async def process_commands(self, message):
+        if self.user is not None and message.user_id == self.user.id:
+            return
+        content = message.content or ""
+        if not content.startswith(self.command_prefix):
+            return
+        stripped = content[len(self.command_prefix):]
+        if not stripped:
+            return
+        parts = stripped.split(maxsplit=1)
+        name = parts[0]
+        args_raw = parts[1] if len(parts) > 1 else ""
+        cmd = self._commands.get(name)
+        if cmd is None:
+            return
+        ctx = Context(self, message, name, args_raw)
+        try:
+            await cmd.invoke(ctx)
+        except CommandError as e:
+            await self._fire("on_command_error", ctx, e)
+        except Exception as e:
+            await self._fire("on_command_error", ctx, e)
+
+    async def _dispatch(self, event_type, payload):
+        if event_type == "ready":
+            user_data = payload.get("user", {})
+            self.user = User.from_dict(user_data)
+            for g in payload.get("guilds", []) or []:
+                guild = Guild.from_dict(g)
+                self.guilds[guild.id] = guild
+            app_id_from_ready = payload.get("application_id", "")
+            if app_id_from_ready and not self.application_id:
+                self.application_id = app_id_from_ready
+            if self._slash_commands:
+                try:
+                    await self.sync_commands()
+                except Exception as e:
+                    log.warning("command sync failed: %s", e)
+            await self._fire("on_ready")
+            return
+
+        if event_type in ("channel_message", "message_create"):
+            msg = Message.from_dict(payload, client=self)
+            await self._fire("on_message", msg)
+            await self.process_commands(msg)
+            return
+
+        if event_type == "message_edit":
+            await self._fire("on_message_edit", payload)
+            return
+
+        if event_type == "message_delete":
+            await self._fire("on_message_delete", payload)
+            return
+
+        if event_type == "reaction_add":
+            await self._fire("on_reaction_add", payload)
+            return
+
+        if event_type == "reaction_remove":
+            await self._fire("on_reaction_remove", payload)
+            return
+
+        if event_type == "guild_member_add":
+            await self._fire("on_member_join", payload)
+            return
+
+        if event_type == "guild_member_remove":
+            await self._fire("on_member_remove", payload)
+            return
+
+        if event_type == "error":
+            await self._fire("on_error", payload)
+            return
+
+        if event_type == "interaction_create":
+            # Route slash-command invocations to their registered
+            # handlers. Falls back to a no-op (plus on_raw_event) if
+            # the command name isn't known — that shouldn't normally
+            # happen because the server filters by command ownership,
+            # but we don't want to crash the dispatch loop on drift.
+            from .interactions import Interaction
+            interaction = Interaction(payload, client=self)
+            handler = self._slash_handlers.get(interaction.command_name)
+            if handler is not None:
+                try:
+                    result = handler(interaction)
+                    if inspect.isawaitable(result):
+                        await result
+                except Exception:
+                    log.exception("slash handler %r raised", interaction.command_name)
+            else:
+                log.warning(
+                    "received interaction for unknown slash command %r",
+                    interaction.command_name,
+                )
+            await self._fire("on_interaction", interaction)
+            return
+
+        await self._fire("on_raw_event", event_type, payload)
+
+    async def _fire(self, name, *args):
+        handler = self._handlers.get(name)
+        if handler is None:
+            return
+        try:
+            result = handler(*args)
+            if inspect.isawaitable(result):
+                await result
+        except Exception:
+            log.exception("handler %s raised", name)
+
+    async def send_message(self, channel_id, content="", embed=None, reply_to=""):
+        d = await self._http.send_message(channel_id, content=content, embed=embed, reply_to=reply_to)
+        return Message.from_dict(d, client=self) if d else None
+
+    async def get_user(self, user_id):
+        d = await self._http.get_user(user_id)
+        return User.from_dict(d) if d else None
+
+    async def get_guild(self, guild_id):
+        """Fetch a guild by ID. Returns a :class:`Guild` or ``None``."""
+        d = await self._http.get_guild(guild_id)
+        return Guild.from_dict(d) if d else None
+
+    async def get_member(self, guild_id, user_id):
+        """Fetch a guild member by user ID. Returns :class:`Member` or ``None``."""
+        d = await self._http.get_member(guild_id, user_id)
+        return Member.from_dict(d, guild_id=guild_id) if d else None
+
+    async def list_channels(self, guild_id):
+        """List channels in a guild the bot can see. Returns [Channel, ...]."""
+        d = await self._http.list_channels(guild_id)
+        return [Channel.from_dict(c, client=self) for c in (d or [])]
+
+    async def get_channel(self, channel_id):
+        """Fetch a single channel by ID. Returns :class:`Channel` or ``None``.
+
+        Use this when you have only a channel_id (e.g. from a message
+        event) and want the full Channel record with its name and
+        description, not just the stub from ``msg.channel``.
+        """
+        d = await self._http.get_channel(channel_id)
+        return Channel.from_dict(d, client=self) if d else None
+
+    async def list_roles(self, guild_id):
+        """List roles in a guild. Returns [Role, ...]."""
+        from .models import Role
+        d = await self._http.list_roles(guild_id)
+        return [Role.from_dict(r, client=self) for r in (d or [])]
+
+    async def create_channel(self, guild_id, name, **kwargs):
+        """Create a channel. Requires MANAGE_CHANNELS in the guild.
+
+        Keyword args are forwarded to
+        :meth:`HTTPClient.create_channel` (``description``,
+        ``category_id``, ``type``). Returns the created
+        :class:`Channel` or ``None``.
+        """
+        d = await self._http.create_channel(guild_id, name, **kwargs)
+        return Channel.from_dict(d, client=self) if d else None
+
+    async def create_role(self, guild_id, name, **kwargs):
+        """Create a role. Requires MANAGE_ROLES in the guild.
+
+        Keyword args are forwarded to :meth:`HTTPClient.create_role`
+        (``color``, ``permissions``, ...). Returns the created
+        :class:`Role` or ``None``.
+        """
+        from .models import Role
+        d = await self._http.create_role(guild_id, name, **kwargs)
+        return Role.from_dict(d, client=self) if d else None
+
+    async def _start(self, token):
+        """Async entry point driving the connect → run → reconnect loop.
+
+        Runs until cancelled (Ctrl-C from :meth:`run`) or until a
+        non-transient error breaks out. :class:`LoginFailure` from the
+        gateway connect step is NOT retried — the token is bad, no
+        amount of reconnecting will help.
+
+        Transient :class:`~banterapi.errors.GatewayError` failures are
+        logged and followed by a 5-second sleep before reconnecting
+        (when :attr:`reconnect` is truthy). The reconnect delay is
+        fixed, not exponential — good enough for a dev-scale bot; a
+        production client should layer backoff around this if it's
+        reconnecting dozens of times a day.
+        """
+        self._http = HTTPClient(token, base_url=self.base_url)
+        self._gateway = Gateway(token, self.intents, self.ws_url, self._dispatch)
+        try:
+            while True:
+                try:
+                    await self._gateway.connect()
+                    await self._gateway.run()
+                except GatewayError as e:
+                    log.warning("gateway error: %s", e)
+                if not self.reconnect:
+                    break
+                log.info("reconnecting in 5s")
+                await asyncio.sleep(5)
+        finally:
+            await self._gateway.close()
+            await self._http.close()
+
+    def run(self, token):
+        """Blocking entry point. Start the bot and run until disconnected.
+
+        This is the synchronous façade most scripts use:
+        ``bot.run(TOKEN)`` at the bottom of a file. Internally it spins
+        up an asyncio event loop and drives :meth:`_start`.
+
+        Ctrl-C (``KeyboardInterrupt``) is caught and swallowed on
+        purpose — it's the standard shutdown signal for a CLI-launched
+        bot, and rethrowing would produce a noisy traceback the user
+        can't act on. Non-``KeyboardInterrupt`` exceptions still
+        propagate.
+        """
+        try:
+            asyncio.run(self._start(token))
+        except KeyboardInterrupt:
+            pass