raycord 0.1.0__py3-none-any.whl

raycord/__init__.py

@@ -0,0 +1,310 @@
+"""raycord - a raylib-simple wrapper around discord.py.
+
+Quick start::
+
+    import raycord
+
+    raycord.init("YOUR_TOKEN", prefix="!")
+
+    @raycord.on_ready
+    def ready():
+        print("online as", raycord.user())
+
+    @raycord.command("ping")
+    def ping(ctx):
+        raycord.reply(ctx, "pong")
+
+    raycord.run()
+
+Everything is a plain function; nothing needs ``await`` unless you want to
+wait for a result (every helper returns a :class:`RayTask`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import discord
+from discord import app_commands
+from discord.ext import commands
+
+from ._callbacks import (
+    ensure_async,
+    is_context,
+    is_interaction,
+    resolve_channel,
+    resolve_guild,
+    resolve_member,
+    resolve_voice,
+)
+from ._task import RayTask
+from .bot import (
+    RaycordAutoShardedBot,
+    RaycordBot,
+    add_listener,
+    application,
+    bot,
+    get_channel,
+    get_guild,
+    get_member,
+    get_prefix,
+    get_user,
+    guilds,
+    init,
+    is_ready,
+    make_bot,
+    reset,
+    run,
+    set_status,
+    shutdown,
+    sync,
+    user,
+    wait_until_ready,
+)
+from .checks import (
+    bot_has_permissions,
+    check,
+    cooldown,
+    dm_only,
+    guild_only,
+    has_any_role,
+    has_guild_permissions,
+    has_permissions,
+    has_role,
+    is_owner,
+    nsfw_only,
+)
+from .cogs import Cog, add_cog, cog, cogs, reload_cog, remove_cog
+from .commands_api import (
+    SlashGroup,
+    autocomplete,
+    choices,
+    command,
+    describe,
+    group,
+    message_command,
+    rename,
+    slash,
+    slash_group,
+    user_command,
+)
+from .errors import (
+    AlreadyInitialized,
+    NotInitialized,
+    NotReady,
+    RaycordError,
+    TargetError,
+)
+from .events import *
+from .events import on, on_app_error
+from .guild import (
+    ban,
+    create_category,
+    create_channel,
+    create_emoji,
+    create_event,
+    create_forum,
+    create_forum_post,
+    create_role,
+    create_sticker,
+    create_text_channel,
+    create_thread,
+    create_voice_channel,
+    kick,
+    unban,
+)
+from .intents import PRESETS, intents
+from .messages import (
+    dm,
+    fetch_message,
+    pin,
+    react,
+    reply,
+    send,
+)
+from .ui import (
+    RayModal,
+    button,
+    field,
+    modal,
+    on_button,
+    on_modal,
+    on_select,
+    select,
+    show_modal,
+    view,
+)
+from .voice import (
+    is_playing,
+    join_voice,
+    leave_voice,
+    pause_voice,
+    play,
+    resume_voice,
+    stop_voice,
+)
+
+__version__ = "0.1.0"
+
+Intents = discord.Intents
+
+# ``edit`` and ``delete`` dispatch to the message helpers for messages and
+# interactions, and to the generic guild helpers for everything else.
+from . import guild as _guild  # noqa: E402
+from . import messages as _messages  # noqa: E402
+
+
+def edit(target: Any, **fields: Any) -> RayTask:
+    """Edit a message or interaction reply, or any other editable object."""
+    if isinstance(target, (discord.Message, discord.Interaction, commands.Context)):
+        return _messages.edit(target, **fields)
+    return _guild.edit(target, **fields)
+
+
+def delete(target: Any, *, reason: Any = None) -> RayTask:
+    """Delete a message or interaction reply, or any other deletable object."""
+    if isinstance(target, (discord.Message, discord.Interaction, commands.Context)):
+        return _messages.delete(target)
+    return _guild.delete(target, reason=reason)
+
+
+# Friendly aliases: raycord reads like a small game loop.
+start = run
+launch = run
+stop = shutdown
+
+
+__all__ = [
+    # modules and core types
+    "discord",
+    "commands",
+    "app_commands",
+    "RayTask",
+    "RaycordError",
+    "AlreadyInitialized",
+    "NotInitialized",
+    "NotReady",
+    "TargetError",
+    "__version__",
+    # lifecycle
+    "init",
+    "run",
+    "start",
+    "launch",
+    "shutdown",
+    "stop",
+    "reset",
+    "bot",
+    "make_bot",
+    "RaycordBot",
+    "RaycordAutoShardedBot",
+    "is_ready",
+    "wait_until_ready",
+    "sync",
+    "add_listener",
+    "set_status",
+    "user",
+    "application",
+    "guilds",
+    "get_guild",
+    "get_channel",
+    "get_user",
+    "get_member",
+    "get_prefix",
+    # intents
+    "intents",
+    "Intents",
+    "PRESETS",
+    # commands
+    "command",
+    "slash",
+    "slash_group",
+    "SlashGroup",
+    "group",
+    "user_command",
+    "message_command",
+    "describe",
+    "rename",
+    "autocomplete",
+    "choices",
+    # checks
+    "check",
+    "cooldown",
+    "has_permissions",
+    "has_guild_permissions",
+    "bot_has_permissions",
+    "has_role",
+    "has_any_role",
+    "is_owner",
+    "guild_only",
+    "dm_only",
+    "nsfw_only",
+    # events
+    "on",
+    "on_app_error",
+    # messages
+    "send",
+    "reply",
+    "edit",
+    "delete",
+    "react",
+    "pin",
+    "dm",
+    "fetch_message",
+    # ui
+    "view",
+    "button",
+    "select",
+    "field",
+    "modal",
+    "RayModal",
+    "show_modal",
+    "on_button",
+    "on_select",
+    "on_modal",
+    # voice
+    "join_voice",
+    "leave_voice",
+    "play",
+    "stop_voice",
+    "pause_voice",
+    "resume_voice",
+    "is_playing",
+    # guild
+    "create_channel",
+    "create_text_channel",
+    "create_voice_channel",
+    "create_category",
+    "create_forum",
+    "create_thread",
+    "create_forum_post",
+    "create_role",
+    "create_emoji",
+    "create_sticker",
+    "create_event",
+    "kick",
+    "ban",
+    "unban",
+    # cogs
+    "Cog",
+    "add_cog",
+    "remove_cog",
+    "reload_cog",
+    "cog",
+    "cogs",
+    # helpers
+    "ensure_async",
+    "resolve_member",
+    "resolve_guild",
+    "resolve_channel",
+    "resolve_voice",
+    "is_interaction",
+    "is_context",
+]
+
+# Pull the generated event decorators (on_ready, on_message, ...) into __all__.
+__all__ += [
+    name
+    for name in dir()
+    if name.startswith("on_") and name not in __all__ and not name.startswith("__")
+]

raycord/_callbacks.py

@@ -0,0 +1,141 @@
+"""Helpers that normalize user callbacks and resolve Discord targets."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import typing
+from typing import Any, Optional
+
+import discord
+from discord.ext import commands as dpy_commands
+
+from .errors import TargetError
+
+
+def ensure_async(fn: Any) -> Any:
+    """Return an async callable that behaves like ``fn``.
+
+    Works for plain functions, bound methods and already-async callables.  The
+    wrapper keeps ``fn``'s signature (via ``functools.wraps``) so discord.py's
+    converters and slash-command parameter extraction still work, and it hides
+    class membership so discord.py treats bound methods as plain callables.
+    """
+    @functools.wraps(fn)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        result = fn(*args, **kwargs)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+    # Resolve string annotations now, using the original module's globals.
+    try:
+        hints = typing.get_type_hints(fn, include_extras=True)
+    except Exception:  # pragma: no cover - exotic annotations
+        hints = {}
+    merged = dict(getattr(fn, "__annotations__", {}) or {})
+    merged.update(hints)
+    if merged:
+        wrapper.__annotations__ = merged
+
+    # Prevent discord.py from treating the wrapper as a class method.
+    wrapper.__qualname__ = wrapper.__name__
+
+    # Copy flags such as app_commands.describe metadata set on the original.
+    source = getattr(fn, "__dict__", None)
+    if source is None and hasattr(fn, "__func__"):
+        source = getattr(fn.__func__, "__dict__", None)
+    if source:
+        wrapper.__dict__.update(source)
+
+    return wrapper
+
+
+def is_interaction(obj: Any) -> bool:
+    return isinstance(obj, discord.Interaction)
+
+
+def is_context(obj: Any) -> bool:
+    return isinstance(obj, dpy_commands.Context)
+
+
+def is_class_method(fn: Any) -> bool:
+    """Return ``True`` for functions defined directly in a class body.
+
+    Nested functions (``outer.<locals>.fn``) are not class methods, so they can
+    be registered immediately just like module-level functions.
+    """
+    qualname = getattr(fn, "__qualname__", getattr(fn, "__name__", ""))
+    parts = qualname.split(".")
+    if len(parts) < 2:
+        return False
+    return parts[-2] != "<locals>"
+
+
+def resolve_member(obj: Any) -> Optional[discord.abc.User]:
+    """Best-effort "who triggered this": author, user or the user itself."""
+    if obj is None:
+        return None
+    if isinstance(obj, (discord.Member, discord.User)):
+        return obj
+    author = getattr(obj, "author", None)
+    if author is not None:
+        return author
+    user = getattr(obj, "user", None)
+    if user is not None:
+        return user
+    return None
+
+
+def resolve_guild(obj: Any) -> Optional[discord.Guild]:
+    """Best-effort guild lookup for contexts, interactions and messages."""
+    if obj is None:
+        return None
+    if isinstance(obj, discord.Guild):
+        return obj
+    guild = getattr(obj, "guild", None)
+    if guild is not None:
+        return guild
+    channel = getattr(obj, "channel", None)
+    if channel is not None:
+        return getattr(channel, "guild", None)
+    member = resolve_member(obj)
+    if member is not None:
+        return getattr(member, "guild", None)
+    return None
+
+
+def resolve_channel(obj: Any) -> Optional[Any]:
+    """Best-effort channel lookup for contexts, interactions and messages."""
+    if obj is None:
+        return None
+    if isinstance(obj, discord.abc.GuildChannel):
+        return obj
+    channel = getattr(obj, "channel", None)
+    if channel is not None:
+        return channel
+    return None
+
+
+def resolve_voice(obj: Any) -> Optional[Any]:
+    """Return the voice *channel* the target's author is sitting in."""
+    member = resolve_member(obj)
+    if member is None:
+        return None
+    voice = getattr(member, "voice", None)
+    if voice is None:
+        return None
+    return getattr(voice, "channel", None)
+
+
+def require_bot(obj: Any = None) -> Any:
+    """Return a bot instance from ``obj`` or from the global state."""
+    from . import _state
+
+    if obj is not None:
+        bot = getattr(obj, "bot", None) or getattr(obj, "client", None)
+        if bot is not None:
+            return bot
+    if _state.state.bot is None:
+        raise TargetError("no bot yet; call raycord.init(token) first")
+    return _state.state.bot

raycord/_state.py

@@ -0,0 +1,74 @@
+"""Global, raylib-style state for raycord.
+
+raylib keeps one implicit context; raycord does the same.  There is a single
+:data:`state` object holding the bot, the event loop and every registration
+that has to be replayed once the bot is ready.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable, Dict, List, Optional
+
+
+class State:
+    """The implicit raycord context."""
+
+    def __init__(self) -> None:
+        self.bot: Any = None
+        self.loop: Any = None
+        self.token: Optional[str] = None
+        self.prefix: Any = None
+        self.config: Dict[str, Any] = {}
+        self.registrations: List[Callable[[Any], Any]] = []
+        self.flushed = False
+        self.ready = False
+        self.closed = False
+        # Global UI routing tables: custom_id -> handler.
+        self.ui_handlers: Dict[str, Dict[str, Callable[..., Any]]] = {
+            "button": {},
+            "select": {},
+            "modal": {},
+        }
+        # name -> record describing everything a loaded cog created.
+        self.cogs: Dict[str, Dict[str, Any]] = {}
+
+    def reset(self) -> None:
+        """Forget everything.  Mostly useful for tests and restarts."""
+        self.bot = None
+        self.loop = None
+        self.token = None
+        self.prefix = None
+        self.config = {}
+        self.registrations = []
+        self.flushed = False
+        self.ready = False
+        self.closed = False
+        self.ui_handlers = {"button": {}, "select": {}, "modal": {}}
+        self.cogs = {}
+
+
+state = State()
+
+
+def when_bot(fn: Callable[[Any], Any]) -> Any:
+    """Run ``fn(bot)`` now if the bot exists, otherwise when it is ready.
+
+    ``fn`` may return an awaitable; :func:`flush` will await it.
+    """
+    if state.flushed and state.bot is not None:
+        return fn(state.bot)
+    state.registrations.append(fn)
+    return None
+
+
+async def flush(bot: Any) -> None:
+    """Replay every pending registration against ``bot``."""
+    state.bot = bot
+    pending, state.registrations = state.registrations, []
+    for fn in pending:
+        result = fn(bot)
+        if inspect.isawaitable(result):
+            await result
+    state.flushed = True
+    state.closed = False

raycord/_task.py

@@ -0,0 +1,112 @@
+"""A tiny "started coroutine" object, so raycord functions never need ``await``.
+
+raylib never asks you to wait; you just call the function.  ``RayTask`` lets a
+raycord helper start an async discord.py call right away and still be usable
+from three situations:
+
+* fire and forget        ``raycord.send(channel, "hi")``
+* blocking sync code     ``raycord.send(channel, "hi").result()``
+* async code             ``await raycord.send(channel, "hi")``
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import inspect
+from typing import Any, Optional
+
+from . import _state
+
+
+class RayTask:
+    """Handle for a discord.py coroutine that already started running."""
+
+    def __init__(self, coro: Any, loop: Any = None) -> None:
+        self._coro = coro
+        self._async: Optional[asyncio.Future] = None
+        self._future: Optional[concurrent.futures.Future] = None
+
+        loop = loop or _state.state.loop
+
+        if not inspect.isawaitable(coro):
+            done: concurrent.futures.Future = concurrent.futures.Future()
+            done.set_result(coro)
+            self._future = done
+            return
+
+        try:
+            running = asyncio.get_running_loop()
+        except RuntimeError:
+            running = None
+
+        if running is not None:
+            # Called from inside the bot loop; use it directly.
+            self._async = asyncio.ensure_future(coro)
+        elif loop is not None and loop.is_running():
+            # Called from another thread; hand the work to the bot loop.
+            self._future = asyncio.run_coroutine_threadsafe(coro, loop)  # type: ignore[arg-type]
+        else:
+            # No bot around (yet).  Best effort: run it to completion now.
+            self._future = concurrent.futures.Future()
+            try:
+                self._future.set_result(asyncio.run(coro))  # type: ignore[arg-type]
+            except BaseException as exc:  # pragma: no cover - defensive
+                self._future.set_exception(exc)
+
+    # -- inspection ------------------------------------------------------
+    def done(self) -> bool:
+        """Return ``True`` when the underlying work has finished."""
+        if self._async is not None:
+            return self._async.done()
+        assert self._future is not None
+        return self._future.done()
+
+    def cancelled(self) -> bool:
+        """Return ``True`` if the work was cancelled."""
+        if self._async is not None:
+            return self._async.cancelled()
+        assert self._future is not None
+        return self._future.cancelled()
+
+    def cancel(self) -> bool:
+        """Attempt to cancel the work."""
+        if self._async is not None:
+            return self._async.cancel()
+        assert self._future is not None
+        return self._future.cancel()
+
+    def result(self, timeout: Optional[float] = None) -> Any:
+        """Block until the work finishes and return its value.
+
+        Only safe outside the event loop thread.  From async code use
+        ``await`` on the task instead.
+        """
+        if self._async is not None:
+            if not self._async.done():
+                raise RuntimeError(
+                    "result() cannot block the event loop; await the RayTask instead"
+                )
+            return self._async.result()
+        assert self._future is not None
+        return self._future.result(timeout)
+
+    def exception(self, timeout: Optional[float] = None) -> Optional[BaseException]:
+        """Return the exception raised by the work, if any."""
+        if self._async is not None:
+            if not self._async.done():
+                raise RuntimeError("task is not done; await the RayTask instead")
+            return self._async.exception()
+        assert self._future is not None
+        return self._future.exception(timeout)
+
+    # -- awaiting --------------------------------------------------------
+    def __await__(self):
+        if self._async is not None:
+            return self._async.__await__()
+        assert self._future is not None
+        return asyncio.wrap_future(self._future).__await__()
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        state = "pending" if not self.done() else "done"
+        return f"<RayTask {state}>"