nestra-py 1.2.2__py3-none-any.whl

nestra/__init__.py

@@ -0,0 +1,77 @@
+"""Nestra-PY - oficjalne SDK Pythona dla API i Gateway Nestra.
+
+Pakiet nie ma zaleznosci zewnetrznych: REST korzysta z urllib, Gateway z
+asyncio streams i wlasnej implementacji WebSocket.
+"""
+
+from __future__ import annotations
+
+from .commands import Command, CommandContext, CommandHandler, ParsedCommand, parse_command
+from .embed import (
+    COLORS,
+    EMBED_MAX_COUNT,
+    EMBED_MAX_TOTAL_CHARS,
+    Embed,
+    EmbedBuilder,
+    parse_color,
+    total_characters,
+    validate_embeds,
+)
+from .gateway import GatewayClient, GatewayError, GatewayFatalError, ReconnectBackoff
+from .rest import (
+    DEFAULT_API_URL,
+    NestraAPIError,
+    NestraREST,
+    RateLimitBucket,
+    RateLimitQueue,
+)
+from .types import (
+    Attachment,
+    Channel,
+    Guild,
+    GuildDetail,
+    Member,
+    Message,
+    MessagePage,
+    Role,
+    User,
+    Webhook,
+)
+
+__version__ = "1.2.2"
+
+__all__ = [
+    "Attachment",
+    "COLORS",
+    "Channel",
+    "Command",
+    "CommandContext",
+    "CommandHandler",
+    "DEFAULT_API_URL",
+    "EMBED_MAX_COUNT",
+    "EMBED_MAX_TOTAL_CHARS",
+    "Embed",
+    "EmbedBuilder",
+    "GatewayClient",
+    "GatewayError",
+    "GatewayFatalError",
+    "Guild",
+    "GuildDetail",
+    "Member",
+    "Message",
+    "MessagePage",
+    "NestraAPIError",
+    "NestraREST",
+    "ParsedCommand",
+    "RateLimitBucket",
+    "RateLimitQueue",
+    "ReconnectBackoff",
+    "Role",
+    "User",
+    "Webhook",
+    "__version__",
+    "parse_color",
+    "parse_command",
+    "total_characters",
+    "validate_embeds",
+]

nestra/_ws.py

@@ -0,0 +1,322 @@
+"""Minimalny klient WebSocket (RFC 6455) na asyncio streams.
+
+Obsluguje tekstowe ramki, ping/pong, close, fragmentacje i TLS. Celowo nie ma
+zaleznosci zewnetrznych. To warstwa transportowa dla :mod:`nestra.gateway`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import os
+import ssl
+import struct
+from typing import Mapping
+from urllib.parse import urlsplit
+
+WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+DEFAULT_MAX_PAYLOAD = 1024 * 1024
+
+OP_CONTINUATION = 0x0
+OP_TEXT = 0x1
+OP_BINARY = 0x2
+OP_CLOSE = 0x8
+OP_PING = 0x9
+OP_PONG = 0xA
+
+
+class WebSocketError(Exception):
+    """Bazowy blad transportu WebSocket."""
+
+
+class WebSocketClosed(WebSocketError):
+    """Serwer (lub klient) zamknal polaczenie."""
+
+    def __init__(self, code: int = 1000, reason: str = "") -> None:
+        self.code = code
+        self.reason = reason
+        super().__init__(f"WebSocket zamkniety ({code}): {reason or 'bez powodu'}")
+
+
+class WebSocketProtocolError(WebSocketError):
+    """Niepoprawna ramka lub naruszenie protokolu."""
+
+
+def _apply_mask(data: bytes, mask: bytes) -> bytes:
+    return bytes(byte ^ mask[index % 4] for index, byte in enumerate(data))
+
+
+def encode_frame(opcode: int, payload: bytes = b"", *, fin: bool = True, mask: bool = True) -> bytes:
+    """Koduje pojedyncza ramke. Klient zawsze powinien uzywac mask=True."""
+    if not 0 <= opcode <= 0xF:
+        raise ValueError("Nieprawidlowy opcode")
+    first = (0x80 if fin else 0) | opcode
+    length = len(payload)
+    header = bytearray([first])
+    mask_bit = 0x80 if mask else 0
+    if length <= 125:
+        header.append(mask_bit | length)
+    elif length <= 0xFFFF:
+        header.append(mask_bit | 126)
+        header.extend(struct.pack("!H", length))
+    else:
+        header.append(mask_bit | 127)
+        header.extend(struct.pack("!Q", length))
+    if not mask:
+        return bytes(header) + payload
+    mask_key = os.urandom(4)
+    header.extend(mask_key)
+    return bytes(header) + _apply_mask(payload, mask_key)
+
+
+async def read_frame(
+    reader: asyncio.StreamReader,
+    *,
+    max_payload: int = DEFAULT_MAX_PAYLOAD,
+) -> tuple[bool, int, bytes]:
+    """Czyta jedna ramke z serwera. Serwer nie moze masowac ramek."""
+    header = await reader.readexactly(2)
+    first, second = header[0], header[1]
+    fin = bool(first & 0x80)
+    opcode = first & 0x0F
+    masked = bool(second & 0x80)
+    if masked:
+        raise WebSocketProtocolError("Serwer nie moze wysylac zamaskowanych ramek")
+    length = second & 0x7F
+    if length == 126:
+        length = struct.unpack("!H", await reader.readexactly(2))[0]
+    elif length == 127:
+        raw_length = await reader.readexactly(8)
+        if raw_length[0] & 0x80:
+            raise WebSocketProtocolError("Nieprawidlowa dlugosc ramki")
+        length = struct.unpack("!Q", raw_length)[0]
+    if length > max_payload:
+        raise WebSocketProtocolError(f"Ramka przekracza limit {max_payload} bajtow")
+    payload = await reader.readexactly(length) if length else b""
+    return fin, opcode, payload
+
+
+def _parse_close(payload: bytes) -> tuple[int, str]:
+    if len(payload) == 1:
+        return 1002, ""
+    if len(payload) >= 2:
+        code = struct.unpack("!H", payload[:2])[0]
+        try:
+            reason = payload[2:].decode("utf-8")
+        except UnicodeDecodeError:
+            reason = ""
+        return code, reason
+    return 1005, ""
+
+
+class WebSocketConnection:
+    """Polaczenie WebSocket z prostym API tekstowym."""
+
+    def __init__(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+        *,
+        max_payload: int = DEFAULT_MAX_PAYLOAD,
+    ) -> None:
+        self._reader = reader
+        self._writer = writer
+        self._max_payload = max_payload
+        self._closed = False
+        self._close_code: int | None = None
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    @property
+    def close_code(self) -> int | None:
+        return self._close_code
+
+    @classmethod
+    async def connect(
+        cls,
+        url: str,
+        *,
+        origin: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        timeout: float = 15.0,
+        ssl_context: ssl.SSLContext | None = None,
+        max_payload: int = DEFAULT_MAX_PAYLOAD,
+    ) -> WebSocketConnection:
+        parsed = urlsplit(url)
+        if parsed.scheme not in {"ws", "wss"}:
+            raise ValueError("URL WebSocket musi miec schemat ws albo wss")
+        if not parsed.hostname:
+            raise ValueError("URL WebSocket musi zawierac host")
+        port = parsed.port or (443 if parsed.scheme == "wss" else 80)
+        context = ssl_context
+        if parsed.scheme == "wss" and context is None:
+            context = ssl.create_default_context()
+        connection_timeout = max(0.1, timeout)
+        reader, writer = await asyncio.wait_for(
+            asyncio.open_connection(
+                parsed.hostname,
+                port,
+                ssl=context,
+                server_hostname=parsed.hostname if context is not None else None,
+            ),
+            timeout=connection_timeout,
+        )
+        try:
+            key = base64.b64encode(os.urandom(16)).decode("ascii")
+            path = parsed.path or "/"
+            if parsed.query:
+                path = f"{path}?{parsed.query}"
+            default_port = 443 if parsed.scheme == "wss" else 80
+            host_header = parsed.hostname if port == default_port else f"{parsed.hostname}:{port}"
+            request_headers = {
+                "Host": host_header,
+                "Upgrade": "websocket",
+                "Connection": "Upgrade",
+                "Sec-WebSocket-Key": key,
+                "Sec-WebSocket-Version": "13",
+            }
+            if origin:
+                request_headers["Origin"] = origin
+            if headers:
+                request_headers.update(headers)
+            for name, value in request_headers.items():
+                if any(character in name for character in ("\r", "\n", ":")):
+                    raise WebSocketProtocolError("Nieprawidlowa nazwa naglowka WebSocket")
+                if any(character in value for character in ("\r", "\n")):
+                    raise WebSocketProtocolError("Nieprawidlowa wartosc naglowka WebSocket")
+            if "\r" in path or "\n" in path or " " in path:
+                raise WebSocketProtocolError("Nieprawidlowa sciezka WebSocket")
+            request = f"GET {path} HTTP/1.1\r\n"
+            request += "".join(f"{name}: {value}\r\n" for name, value in request_headers.items())
+            request += "\r\n"
+            writer.write(request.encode("latin-1"))
+            await writer.drain()
+            response = await asyncio.wait_for(reader.readuntil(b"\r\n\r\n"), timeout=connection_timeout)
+            lines = response.decode("latin-1").split("\r\n")
+            status_parts = lines[0].split(" ", 2)
+            if len(status_parts) < 2 or status_parts[1] != "101":
+                raise WebSocketProtocolError(f"Serwer odrzucil handshake: {lines[0]}")
+            response_headers: dict[str, str] = {}
+            for line in lines[1:]:
+                if ":" not in line:
+                    continue
+                name, value = line.split(":", 1)
+                response_headers[name.strip().lower()] = value.strip()
+            expected = base64.b64encode(hashlib.sha1((key + WS_GUID).encode("ascii")).digest()).decode("ascii")
+            if response_headers.get("sec-websocket-accept") != expected:
+                raise WebSocketProtocolError("Nieprawidlowy naglowek Sec-WebSocket-Accept")
+            return cls(reader, writer, max_payload=max_payload)
+        except BaseException:
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except OSError:
+                pass
+            raise
+
+    async def send_text(self, text: str) -> None:
+        await self._send_frame(OP_TEXT, text.encode("utf-8"))
+
+    async def send_json(self, value: object) -> None:
+        import json
+
+        await self.send_text(json.dumps(value, separators=(",", ":"), ensure_ascii=False))
+
+    async def ping(self, payload: bytes = b"") -> None:
+        if len(payload) > 125:
+            raise ValueError("Ping moze miec maksymalnie 125 bajtow")
+        await self._send_frame(OP_PING, payload)
+
+    async def pong(self, payload: bytes = b"") -> None:
+        await self._send_frame(OP_PONG, payload)
+
+    async def _send_frame(self, opcode: int, payload: bytes = b"") -> None:
+        if self._closed:
+            raise WebSocketClosed(self._close_code or 1000, "Polaczenie jest zamkniete")
+        self._writer.write(encode_frame(opcode, payload, mask=True))
+        await self._writer.drain()
+
+    async def receive_text(self, *, timeout: float | None = None) -> str:
+        if timeout is None:
+            return await self._receive_text()
+        return await asyncio.wait_for(self._receive_text(), timeout=timeout)
+
+    async def _receive_text(self) -> str:
+        fragments: list[bytes] = []
+        fragmented = False
+        while True:
+            try:
+                fin, opcode, payload = await read_frame(self._reader, max_payload=self._max_payload)
+            except asyncio.IncompleteReadError as error:
+                self._closed = True
+                raise WebSocketClosed(1006, "Nieoczekiwane zamkniecie polaczenia") from error
+            except (ConnectionError, OSError) as error:
+                self._closed = True
+                raise WebSocketClosed(1006, str(error)) from error
+
+            if opcode == OP_TEXT:
+                if fragmented:
+                    raise WebSocketProtocolError("Nowa ramka tekstowa w trakcie fragmentacji")
+                if not fin:
+                    fragments = [payload]
+                    fragmented = True
+                    continue
+                return self._decode_text(payload)
+            if opcode == OP_CONTINUATION:
+                if not fragmented:
+                    raise WebSocketProtocolError("Ramka kontynuacji bez poczatku wiadomosci")
+                fragments.append(payload)
+                if sum(len(part) for part in fragments) > self._max_payload:
+                    raise WebSocketProtocolError("Wiadomosc przekracza limit bajtow")
+                if not fin:
+                    continue
+                fragmented = False
+                return self._decode_text(b"".join(fragments))
+            if opcode == OP_BINARY:
+                await self.close(1003, "Nieobslugiwane ramki binarne")
+                raise WebSocketProtocolError("Serwer wyslal ramke binarna")
+            if opcode == OP_CLOSE:
+                code, reason = _parse_close(payload)
+                self._close_code = code
+                # Kody 1005/1006/1015 sa zarezerwowane i nie moga trafic na wire.
+                echo_code = 1000 if code in {1005, 1006, 1015} else code
+                await self._send_close(echo_code, reason)
+                self._writer.close()
+                raise WebSocketClosed(code, reason)
+            if opcode == OP_PING:
+                await self.pong(payload)
+                continue
+            if opcode == OP_PONG:
+                continue
+            raise WebSocketProtocolError(f"Nieznany opcode: {opcode}")
+
+    def _decode_text(self, payload: bytes) -> str:
+        try:
+            return payload.decode("utf-8")
+        except UnicodeDecodeError as error:
+            raise WebSocketProtocolError("Tekst nie jest poprawnym UTF-8") from error
+
+    async def _send_close(self, code: int = 1000, reason: str = "") -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._close_code = code
+        payload = struct.pack("!H", code) + reason.encode("utf-8")[:123]
+        try:
+            self._writer.write(encode_frame(OP_CLOSE, payload, mask=True))
+            await self._writer.drain()
+        except (ConnectionError, OSError):
+            pass
+
+    async def close(self, code: int = 1000, reason: str = "") -> None:
+        if self._closed:
+            return
+        await self._send_close(code, reason)
+        self._writer.close()
+        try:
+            await self._writer.wait_closed()
+        except (ConnectionError, OSError):
+            pass

nestra/commands.py

@@ -0,0 +1,247 @@
+"""Komendy prefiksowe dla botow Nestra.
+
+Przyklad::
+
+    commands = CommandHandler(prefix="!")
+
+    @commands.command("ping", description="Odpowiada pongiem")
+    async def ping(ctx: CommandContext) -> None:
+        await ctx.reply("pong")
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import shlex
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable, Sequence
+
+from .embed import EmbedBuilder
+from .rest import NestraREST
+from .types import Message, User
+
+logger = logging.getLogger("nestra.commands")
+
+CommandFunc = Callable[["CommandContext"], Any]
+ErrorFunc = Callable[["CommandContext", Exception], Any]
+
+
+@dataclass(slots=True)
+class ParsedCommand:
+    name: str
+    args: str = ""
+    argv: list[str] | None = None
+
+
+def parse_command(content: str, prefix: str = "!") -> ParsedCommand | None:
+    """Parsuje ``prefix`` + nazwa + argumenty. Zwraca None dla zwyklego tekstu."""
+    if not prefix:
+        raise ValueError("Prefix nie moze byc pusty")
+    if not content or not content.startswith(prefix):
+        return None
+    rest = content[len(prefix) :].strip()
+    if not rest:
+        return None
+    parts = rest.split(None, 1)
+    name = parts[0]
+    args = parts[1].strip() if len(parts) > 1 else ""
+    try:
+        argv = shlex.split(args, posix=True) if args else []
+    except ValueError:
+        argv = args.split()
+    return ParsedCommand(name=name, args=args, argv=argv)
+
+
+@dataclass(slots=True)
+class Command:
+    name: str
+    func: CommandFunc
+    aliases: tuple[str, ...] = ()
+    description: str = ""
+    usage: str | None = None
+
+
+@dataclass(slots=True)
+class CommandContext:
+    """Kontekst wywolania komendy przekazywany do handlera."""
+
+    message: Message
+    command: Command
+    args: str
+    argv: list[str]
+    rest: NestraREST | None = None
+
+    @property
+    def author(self) -> User | None:
+        return self.message.author
+
+    @property
+    def channel_id(self) -> str:
+        return self.message.channel_id
+
+    @property
+    def guild_id(self) -> str | None:
+        return self.message.guild_id
+
+    @property
+    def author_name(self) -> str:
+        return self.author.name if self.author is not None else "nieznany"
+
+    async def reply(
+        self,
+        content: str | None = None,
+        *,
+        embeds: EmbedBuilder | dict[str, Any] | Iterable[EmbedBuilder | dict[str, Any]] | None = None,
+        reply_to: bool = True,
+    ) -> Message:
+        """Wysyla odpowiedz na kanale wiadomosci (domyslnie jako reply)."""
+        if self.rest is None:
+            raise RuntimeError("Brak klienta REST w CommandContext")
+        return await self.rest.send_message(
+            self.channel_id,
+            content,
+            embeds=embeds,
+            reply_to_id=self.message.id if reply_to else None,
+        )
+
+    async def send(
+        self,
+        content: str | None = None,
+        *,
+        embeds: EmbedBuilder | dict[str, Any] | Iterable[EmbedBuilder | dict[str, Any]] | None = None,
+    ) -> Message:
+        """Wysyla wiadomosc bez reply."""
+        return await self.reply(content, embeds=embeds, reply_to=False)
+
+
+class CommandHandler:
+    """Rejestr komend prefiksowych i dispatcher wiadomosci."""
+
+    def __init__(
+        self,
+        prefix: str = "!",
+        *,
+        case_sensitive: bool = False,
+        ignore_bots: bool = True,
+        rest: NestraREST | None = None,
+        on_error: ErrorFunc | None = None,
+    ) -> None:
+        if not prefix:
+            raise ValueError("Prefix nie moze byc pusty")
+        self.prefix = prefix
+        self.case_sensitive = case_sensitive
+        self.ignore_bots = ignore_bots
+        self.rest = rest
+        self.on_error = on_error
+        self._commands: dict[str, Command] = {}
+
+    def __len__(self) -> int:
+        return len(self._commands)
+
+    @property
+    def commands(self) -> list[Command]:
+        return list(self._commands.values())
+
+    def _key(self, name: str) -> str:
+        return name if self.case_sensitive else name.lower()
+
+    def command(
+        self,
+        name: str,
+        *,
+        aliases: Sequence[str] = (),
+        description: str = "",
+        usage: str | None = None,
+    ) -> Callable[[CommandFunc], CommandFunc]:
+        """Dekorator rejestrujacy komende."""
+        if not name or any(character.isspace() for character in name):
+            raise ValueError("Nazwa komendy nie moze byc pusta ani zawierac spacji")
+        alias_tuple = tuple(aliases)
+        for alias in alias_tuple:
+            if not alias or any(character.isspace() for character in alias):
+                raise ValueError("Alias komendy nie moze byc pusty ani zawierac spacji")
+        candidates = (name, *alias_tuple)
+        keys = [self._key(candidate) for candidate in candidates]
+        if len(set(keys)) != len(keys):
+            raise ValueError("Nazwa komendy i aliasy musza byc unikalne")
+
+        def decorator(func: CommandFunc) -> CommandFunc:
+            command = Command(
+                name=name,
+                func=func,
+                aliases=alias_tuple,
+                description=description,
+                usage=usage,
+            )
+            for candidate in (name, *alias_tuple):
+                key = self._key(candidate)
+                if key in self._commands:
+                    raise ValueError(f"Komenda lub alias juz istnieje: {candidate}")
+            for candidate in (name, *alias_tuple):
+                self._commands[self._key(candidate)] = command
+            return func
+
+        return decorator
+
+    def get(self, name: str) -> Command | None:
+        return self._commands.get(self._key(name))
+
+    def parse(self, content: str) -> ParsedCommand | None:
+        return parse_command(content, self.prefix)
+
+    async def handle_message(self, message: Message) -> bool:
+        """Wywoluje komende, jesli wiadomosc ja zawiera. Zwraca True gdy dopasowano."""
+        author = message.author
+        if author is None:
+            return False
+        if self.ignore_bots and author.is_bot:
+            return False
+        parsed = self.parse(message.content)
+        if parsed is None:
+            return False
+        command = self.get(parsed.name)
+        if command is None:
+            return False
+        context = CommandContext(
+            message=message,
+            command=command,
+            args=parsed.args,
+            argv=parsed.argv or [],
+            rest=self.rest,
+        )
+        try:
+            result = command.func(context)
+            if inspect.isawaitable(result):
+                await result
+        except Exception as error:  # noqa: BLE001 - blad komendy nie moze ubic bota
+            await self._handle_error(context, error)
+        return True
+
+    async def _handle_error(self, context: CommandContext, error: Exception) -> None:
+        if self.on_error is None:
+            logger.exception("Blad komendy %s: %s", context.command.name, error)
+            return
+        try:
+            result = self.on_error(context, error)
+            if inspect.isawaitable(result):
+                await result
+        except Exception:  # noqa: BLE001
+            logger.exception("Blad w handlerze bledow komend")
+
+    def help_text(self) -> str:
+        """Tekst pomocy generowany z opisow komend (bez duplikatow aliasow)."""
+        lines = []
+        seen: set[int] = set()
+        for command in self._commands.values():
+            if id(command) in seen:
+                continue
+            seen.add(id(command))
+            usage = command.usage or command.name
+            line = f"{self.prefix}{usage}"
+            if command.description:
+                line += f" - {command.description}"
+            if command.aliases:
+                line += f" (aliasy: {', '.join(command.aliases)})"
+            lines.append(line)
+        return "\n".join(lines)