zynko 0.1.0__py3-none-any.whl

zynko/__init__.py

@@ -0,0 +1,74 @@
+"""zynko: the official library for Zynko bots (docs.zynko.org/bots).
+
+API and gateway on asyncio and aiohttp; voice through the ``livekit`` package, installed with
+``pip install "zynko[voice]"`` and loaded only when a bot joins a voice room.
+"""
+
+from .bits import ALL_PERMISSIONS, Intents, Permissions, id_time
+from .client import Client
+from .gateway import GatewayClosed
+from .interaction import Interaction
+from .message import Message
+from .models import (
+    Attachment,
+    Button,
+    ButtonStyle,
+    Card,
+    CardField,
+    Channel,
+    ChannelType,
+    Command,
+    CommandOption,
+    Components,
+    Emoji,
+    Guild,
+    Member,
+    Overwrite,
+    Role,
+    User,
+    VoiceState,
+)
+from .permissions import compute_permissions
+from .player import PCM, AudioInput, AudioPlayer, Stream, Track, tone
+from .rest import File, Rest, ZynkoError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ALL_PERMISSIONS",
+    "Attachment",
+    "AudioInput",
+    "AudioPlayer",
+    "Button",
+    "ButtonStyle",
+    "Card",
+    "CardField",
+    "Channel",
+    "ChannelType",
+    "Client",
+    "Command",
+    "CommandOption",
+    "Components",
+    "Emoji",
+    "File",
+    "GatewayClosed",
+    "Guild",
+    "Intents",
+    "Interaction",
+    "Member",
+    "Message",
+    "Overwrite",
+    "PCM",
+    "Permissions",
+    "Rest",
+    "Role",
+    "Stream",
+    "Track",
+    "User",
+    "VoiceState",
+    "ZynkoError",
+    "compute_permissions",
+    "id_time",
+    "tone",
+    "__version__",
+]

zynko/_events.py

@@ -0,0 +1,123 @@
+"""A small event emitter: sync or async handlers, errors routed instead of raised."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar, overload
+
+log = logging.getLogger("zynko")
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class Emitter:
+    """Calls handlers by event name.
+
+    A handler may be a plain function or a coroutine function; coroutines run as their own
+    tasks, so a slow handler never holds up the next event. A handler that raises becomes an
+    ``error`` event (or a log line, when nobody listens to ``error``).
+    """
+
+    def __init__(self, name: str = "zynko") -> None:
+        self._name = name
+        self._handlers: dict[str, list[Callable[..., Any]]] = {}
+        self._once: set[tuple[str, Callable[..., Any]]] = set()
+        self._tasks: set[asyncio.Task[Any]] = set()
+
+    @overload
+    def on(self, event: str) -> Callable[[F], F]: ...
+    @overload
+    def on(self, event: str, handler: F) -> F: ...
+    def on(self, event: str, handler: F | None = None) -> Any:
+        """Registers a handler. Works as a call or as a decorator: ``@x.on("event")``."""
+        if handler is None:
+            return lambda f: self.on(event, f)
+        self._handlers.setdefault(event, []).append(handler)
+        return handler
+
+    def once(self, event: str, handler: F) -> F:
+        """Registers a handler that runs once."""
+        self.on(event, handler)
+        self._once.add((event, handler))
+        return handler
+
+    def off(self, event: str, handler: Callable[..., Any]) -> None:
+        handlers = self._handlers.get(event, [])
+        if handler in handlers:
+            handlers.remove(handler)
+        self._once.discard((event, handler))
+
+    def listeners(self, event: str) -> int:
+        return len(self._handlers.get(event, []))
+
+    def emit(self, event: str, *args: Any) -> None:
+        for handler in list(self._handlers.get(event, [])):
+            if (event, handler) in self._once:
+                self.off(event, handler)
+            self._call(event, handler, args)
+
+    def _call(self, event: str, handler: Callable[..., Any], args: tuple[Any, ...]) -> None:
+        try:
+            result = handler(*args)
+        except Exception as e:  # noqa: BLE001 - every handler error is reported, none raised
+            self._failed(event, e)
+            return
+        if inspect.isawaitable(result):
+            task = asyncio.ensure_future(_await(result))
+            self._tasks.add(task)
+            task.add_done_callback(lambda t: self._done(event, t))
+
+    def _done(self, event: str, task: asyncio.Task[Any]) -> None:
+        self._tasks.discard(task)
+        if task.cancelled():
+            return
+        e = task.exception()
+        if e is not None:
+            self._failed(event, e)
+
+    def _failed(self, event: str, error: BaseException) -> None:
+        if event != "error" and self.listeners("error"):
+            self.emit("error", error)
+        else:
+            log.error("%s: erro num handler de %r", self._name, event, exc_info=error)
+
+    async def wait_for(
+        self,
+        event: str,
+        check: Callable[..., bool] | None = None,
+        timeout: float | None = 30.0,
+    ) -> Any:
+        """Waits for the next ``event`` whose arguments pass ``check``.
+
+        Returns the single argument, or a tuple when the event has several. Raises
+        ``asyncio.TimeoutError`` after ``timeout`` seconds (None: wait forever).
+        """
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[Any] = loop.create_future()
+
+        def handler(*args: Any) -> None:
+            if future.done():
+                return
+            if check is not None:
+                try:
+                    if not check(*args):
+                        return
+                except Exception as e:  # noqa: BLE001
+                    future.set_exception(e)
+                    return
+            future.set_result(args[0] if len(args) == 1 else args)
+
+        self.on(event, handler)
+        try:
+            return await asyncio.wait_for(future, timeout)
+        except asyncio.TimeoutError:
+            raise asyncio.TimeoutError(f"Esperando {event}: tempo esgotado") from None
+        finally:
+            self.off(event, handler)
+
+
+async def _await(a: Awaitable[Any]) -> Any:
+    return await a

zynko/bits.py

@@ -0,0 +1,62 @@
+"""Intents, permission bits and snowflake times (docs.zynko.org/api/gateway#intents)."""
+
+from __future__ import annotations
+
+from enum import IntFlag
+
+__all__ = ["Intents", "Permissions", "ALL_PERMISSIONS", "id_time"]
+
+
+class Intents(IntFlag):
+    """The kinds of event a bot asks the gateway for.
+
+    READY, GUILD_CREATE, GUILD_DELETE, CHANNEL_CREATE and USER_UPDATE always arrive.
+    """
+
+    #: Guilds changing, and their channels, roles and emojis.
+    GUILDS = 1 << 0
+    #: Members joining, leaving or changing.
+    GUILD_MEMBERS = 1 << 1
+    #: Who is online.
+    PRESENCES = 1 << 2
+    #: Messages created, edited and deleted, in guilds and DMs.
+    MESSAGES = 1 << 3
+    REACTIONS = 1 << 4
+    TYPING = 1 << 5
+    #: Who is in which voice room. A bot that joins voice needs it.
+    VOICE_STATES = 1 << 6
+    ALL = (1 << 7) - 1
+
+
+class Permissions(IntFlag):
+    """Role permissions, as bits (docs.zynko.org/api/permissoes)."""
+
+    ADMINISTRATOR = 1 << 0
+    MANAGE_GUILD = 1 << 1
+    MANAGE_CHANNELS = 1 << 2
+    MANAGE_ROLES = 1 << 3
+    KICK_MEMBERS = 1 << 4
+    BAN_MEMBERS = 1 << 5
+    MANAGE_MESSAGES = 1 << 6
+    MANAGE_NICKNAMES = 1 << 7
+    CREATE_INVITE = 1 << 8
+    SEND_MESSAGES = 1 << 9
+    ATTACH_FILES = 1 << 10
+    CONNECT = 1 << 11
+    SPEAK = 1 << 12
+    MANAGE_EMOJIS = 1 << 13
+    VIEW_CHANNEL = 1 << 14
+    ADD_REACTIONS = 1 << 15
+    READ_MESSAGE_HISTORY = 1 << 16
+    STREAM = 1 << 17
+
+
+#: Every permission bit set: what owners and admins get.
+ALL_PERMISSIONS = (1 << 18) - 1
+
+_EPOCH_MS = 1_767_225_600_000
+
+
+def id_time(id: str | int) -> int:
+    """When an id was made, in milliseconds since 1970 (ids are snowflakes)."""
+    return (int(id) >> 22) + _EPOCH_MS