zynko 0.1.0__py3-none-any.whl

zynko/interaction.py

@@ -0,0 +1,106 @@
+"""Someone used one of the bot's "/" commands, or clicked a button on one of its messages."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from .message import Message
+from .models import Card, Channel, Components, Member, User
+
+if TYPE_CHECKING:
+    from .client import Client
+
+__all__ = ["Interaction"]
+
+
+class Interaction:
+    """A command or a click. Answer within 15 minutes.
+
+    :meth:`reply` posts a message (or one only they see), :meth:`update` changes the message
+    whose button was clicked::
+
+        @client.on("interaction")
+        async def on_interaction(i: zynko.Interaction):
+            if i.command == "dado":
+                await i.reply(f"🎲 {random.randint(1, i.option('lados', 6))}")
+    """
+
+    def __init__(self, client: Client, data: dict[str, Any]) -> None:
+        self.client = client
+        self.raw = data
+        self.id: str = str(data["id"])
+        self.token: str = data["token"]
+        self.type: Literal["command", "button"] = data.get("type", "command")
+        self.channel_id: str = str(data["channel_id"])
+        self.guild_id: str | None = data.get("guild_id")
+        #: Who used it.
+        self.user = User.from_dict(data["user"])
+        self.member = Member.from_dict(data["member"]) if data.get("member") else None
+        command = data.get("command") or {}
+        #: The command's name, for commands.
+        self.command: str | None = command.get("name")
+        #: What was typed for each option, by name.
+        self.options: dict[str, str | int | float | bool] = {o["name"]: o.get("value") for o in command.get("options") or []}
+        #: The clicked button's ``custom_id``, for buttons.
+        self.custom_id: str | None = data.get("custom_id")
+        #: The message whose button was clicked.
+        self.message = Message(client, data["message"]) if data.get("message") else None
+        #: Whether it was answered already.
+        self.replied = False
+
+    def __repr__(self) -> str:
+        what = f"command={self.command!r}" if self.type == "command" else f"custom_id={self.custom_id!r}"
+        return f"<Interaction id={self.id} type={self.type} {what} user={self.user.username!r}>"
+
+    def option(self, name: str, default: Any = None) -> Any:
+        """One option's value; ``default`` when it was left out. User, channel and role options are ids."""
+        return self.options.get(name, default)
+
+    @property
+    def channel(self) -> Channel | None:
+        return self.client.channels.get(self.channel_id)
+
+    async def reply(
+        self,
+        content: str | None = None,
+        *,
+        cards: list[Card] | None = None,
+        components: Components | None = None,
+        ephemeral: bool = False,
+    ) -> Message:
+        """Answers with a message in the channel, or only for that person with ``ephemeral=True``.
+
+        May be called again for follow-ups.
+        """
+        body: dict[str, Any] = {"type": "message"}
+        if content is not None:
+            body["content"] = content
+        if cards is not None:
+            body["cards"] = cards
+        if components is not None:
+            body["components"] = components
+        if ephemeral:
+            body["ephemeral"] = True
+        msg = await self.client.rest.interaction_callback(self.id, self.token, body)
+        self.replied = True
+        return Message(self.client, msg)
+
+    async def update(
+        self, content: str | None = None, *, cards: list[Card] | None = None, components: Components | None = None
+    ) -> Message:
+        """Changes the message whose button was clicked: whatever is given (text, cards, buttons).
+
+        ``components=[]`` removes the buttons.
+        """
+        if self.type != "button":
+            raise RuntimeError("update() é só para cliques em botões")
+        body: dict[str, Any] = {"type": "update"}
+        if content is not None:
+            body["content"] = content
+        if cards is not None:
+            body["cards"] = cards
+        if components is not None:
+            body["components"] = components
+        msg = await self.client.rest.interaction_callback(self.id, self.token, body)
+        self.replied = True
+        return Message(self.client, msg)

zynko/message.py

@@ -0,0 +1,121 @@
+"""A message, with shortcuts to answer it, react, edit and delete."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .models import Attachment, Card, Channel, Components, Member, User
+from .rest import FileInput
+
+if TYPE_CHECKING:
+    from .client import Client
+
+__all__ = ["Message"]
+
+
+class Message:
+    """A message as the API sends it. ``raw`` keeps the JSON."""
+
+    __slots__ = (
+        "client",
+        "raw",
+        "id",
+        "channel_id",
+        "author",
+        "content",
+        "timestamp",
+        "edited_timestamp",
+        "reply_to",
+        "attachments",
+        "reactions",
+        "embeds",
+        "cards",
+        "components",
+        "interaction",
+        "ephemeral",
+        "nonce",
+        "partial",
+    )
+
+    def __init__(self, client: Client, data: dict[str, Any]) -> None:
+        self.client = client
+        self.raw = data
+        self.id: str = str(data["id"])
+        self.channel_id: str = str(data["channel_id"])
+        #: A MESSAGE_UPDATE brings only what changed (``id``, ``channel_id``, ``content``,
+        #: ``edited_timestamp``, ``embeds``): then ``partial`` is True and ``author`` is empty.
+        self.partial = "author" not in data
+        self.author = User.from_dict(data["author"]) if not self.partial else User("", "", "", None, False)
+        self.content: str = data.get("content") or ""
+        self.timestamp: int = int(data.get("timestamp") or 0)
+        self.edited_timestamp: int | None = data.get("edited_timestamp")
+        #: The message this one answers: ``{id, author, content}``.
+        self.reply_to: dict[str, Any] | None = data.get("reply_to")
+        self.attachments = [Attachment.from_dict(a) for a in data.get("attachments") or []]
+        #: ``{emoji, count, me}`` each.
+        self.reactions: list[dict[str, Any]] = data.get("reactions") or []
+        #: Link previews.
+        self.embeds: list[dict[str, Any]] = data.get("embeds") or []
+        self.cards: list[Card] = data.get("cards") or []
+        self.components: Components = data.get("components") or []
+        #: The command or click this (bot) message answers: ``{id, name?, user}``.
+        self.interaction: dict[str, Any] | None = data.get("interaction")
+        #: Only its reader sees it, and it is not kept.
+        self.ephemeral = bool(data.get("ephemeral", False))
+        self.nonce: str | None = data.get("nonce")
+
+    def __repr__(self) -> str:
+        return f"<Message id={self.id} channel_id={self.channel_id} author={self.author.username!r} content={self.content[:40]!r}>"
+
+    @property
+    def channel(self) -> Channel | None:
+        """The channel, when the client has seen it."""
+        return self.client.channels.get(self.channel_id)
+
+    @property
+    def guild_id(self) -> str | None:
+        """The guild (servidor) the message is in; None in a DM."""
+        c = self.channel
+        return c.guild_id if c else None
+
+    @property
+    def member(self) -> Member | None:
+        """The author as a member of the guild (nickname, roles); None in DMs."""
+        g = self.guild_id
+        guild = self.client.guilds.get(g) if g else None
+        return guild.members.get(self.author.id) if guild else None
+
+    @property
+    def mine(self) -> bool:
+        """Whether the author is the bot itself."""
+        return self.client.user is not None and self.author.id == self.client.user.id
+
+    async def reply(
+        self,
+        content: str | None = None,
+        *,
+        files: list[FileInput] | None = None,
+        cards: list[Card] | None = None,
+        components: Components | None = None,
+        nonce: str | None = None,
+    ) -> Message:
+        """Answers in the same channel, as a reply to this message."""
+        return await self.client.send(
+            self.channel_id, content, reply_to=self.id, files=files, cards=cards, components=components, nonce=nonce
+        )
+
+    async def react(self, emoji: str) -> None:
+        await self.client.rest.react(self.channel_id, self.id, emoji)
+
+    async def unreact(self, emoji: str) -> None:
+        await self.client.rest.unreact(self.channel_id, self.id, emoji)
+
+    async def edit(
+        self, content: str | None = None, *, cards: list[Card] | None = None, components: Components | None = None
+    ) -> Message:
+        """Only the author edits: a bot edits its own messages (text, cards, buttons)."""
+        data = await self.client.rest.edit_message(self.channel_id, self.id, content, cards=cards, components=components)
+        return Message(self.client, data)
+
+    async def delete(self) -> None:
+        await self.client.rest.delete_message(self.channel_id, self.id)

zynko/models.py

@@ -0,0 +1,387 @@
+"""The Zynko API's objects, as the server sends them (docs.zynko.org/api/objetos).
+
+Ids are strings; times are milliseconds since 1970. Each model keeps the JSON it came from in
+``raw``, so fields this library does not know yet are still reachable.
+
+What a bot *sends* (cards, buttons, commands) is plain dicts, typed with ``TypedDict``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, TypedDict
+
+__all__ = [
+    "ChannelType",
+    "User",
+    "Overwrite",
+    "Channel",
+    "Member",
+    "Role",
+    "Emoji",
+    "Attachment",
+    "VoiceState",
+    "Guild",
+    "Card",
+    "CardAuthor",
+    "CardField",
+    "CardFooter",
+    "CardImage",
+    "Button",
+    "ButtonStyle",
+    "Components",
+    "Command",
+    "CommandOption",
+    "CommandChoice",
+    "OptionType",
+]
+
+JSON = dict[str, Any]
+
+
+class ChannelType:
+    TEXT = 0
+    DM = 1
+    VOICE = 2
+    CATEGORY = 4
+    POST = 11
+    FORUM = 15
+
+
+@dataclass(slots=True)
+class User:
+    id: str
+    username: str
+    display_name: str
+    avatar: str | None
+    bot: bool
+    raw: JSON = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, d: JSON) -> User:
+        return cls(
+            id=str(d["id"]),
+            username=d.get("username", ""),
+            display_name=d.get("display_name") or d.get("username", ""),
+            avatar=d.get("avatar"),
+            bot=bool(d.get("bot", False)),
+            raw=d,
+        )
+
+
+@dataclass(slots=True)
+class Overwrite:
+    """A channel's permission overwrite: ``type`` 0 is a role, 1 a member."""
+
+    id: str
+    type: int
+    allow: int
+    deny: int
+
+    @classmethod
+    def from_dict(cls, d: JSON) -> Overwrite:
+        return cls(id=str(d["id"]), type=int(d.get("type", 0)), allow=int(d.get("allow", 0)), deny=int(d.get("deny", 0)))
+
+
+@dataclass(slots=True)
+class Channel:
+    id: str
+    guild_id: str | None
+    type: int
+    name: str
+    topic: str | None = None
+    position: int = 0
+    parent_id: str | None = None
+    last_message_id: str | None = None
+    #: The voice server a room runs on, when someone picked one.
+    voice_server: str | None = None
+    #: In a DM: the other person.
+    recipients: list[User] = field(default_factory=list)
+    permission_overwrites: list[Overwrite] = field(default_factory=list)
+    raw: JSON = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, d: JSON) -> Channel:
+        return cls(
+            id=str(d["id"]),
+            guild_id=d.get("guild_id"),
+            type=int(d.get("type", 0)),
+            name=d.get("name") or "",
+            topic=d.get("topic"),
+            position=int(d.get("position") or 0),
+            parent_id=d.get("parent_id"),
+            last_message_id=d.get("last_message_id"),
+            voice_server=d.get("voice_server"),
+            recipients=[User.from_dict(u) for u in d.get("recipients") or []],
+            permission_overwrites=[Overwrite.from_dict(o) for o in d.get("permission_overwrites") or []],
+            raw=d,
+        )
+
+
+@dataclass(slots=True)
+class Member:
+    guild_id: str
+    user: User
+    nick: str | None
+    is_admin: bool
+    joined_at: int
+    #: Not including @everyone, which everybody has.
+    roles: list[str]
+    raw: JSON = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, d: JSON) -> Member:
+        return cls(
+            guild_id=str(d.get("guild_id", "")),
+            user=User.from_dict(d["user"]),
+            nick=d.get("nick"),
+            is_admin=bool(d.get("is_admin", False)),
+            joined_at=int(d.get("joined_at") or 0),
+            roles=[str(r) for r in d.get("roles") or []],
+            raw=d,
+        )
+
+    @property
+    def name(self) -> str:
+        """The nickname, or the account's display name."""
+        return self.nick or self.user.display_name
+
+
+@dataclass(slots=True)
+class Role:
+    id: str
+    guild_id: str
+    name: str
+    color: int | None
+    position: int
+    permissions: int
+    hoist: bool
+    raw: JSON = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, d: JSON) -> Role:
+        return cls(
+            id=str(d["id"]),
+            guild_id=str(d.get("guild_id", "")),
+            name=d.get("name", ""),
+            color=d.get("color"),
+            position=int(d.get("position") or 0),
+            permissions=int(d.get("permissions") or 0),
+            hoist=bool(d.get("hoist", False)),
+            raw=d,
+        )
+
+
+@dataclass(slots=True)
+class Emoji:
+    id: str
+    guild_id: str
+    name: str
+    url: str
+    animated: bool
+    raw: JSON = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, d: JSON) -> Emoji:
+        return cls(
+            id=str(d["id"]),
+            guild_id=str(d.get("guild_id", "")),
+            name=d.get("name", ""),
+            url=d.get("url", ""),
+            animated=bool(d.get("animated", False)),
+            raw=d,
+        )
+
+
+@dataclass(slots=True)
+class Attachment:
+    id: str
+    filename: str
+    content_type: str
+    size: int
+    #: ``/api/attachments/{id}``: needs the token to download.
+    url: str
+    raw: JSON = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, d: JSON) -> Attachment:
+        return cls(
+            id=str(d["id"]),
+            filename=d.get("filename", ""),
+            content_type=d.get("content_type", ""),
+            size=int(d.get("size") or 0),
+            url=d.get("url", ""),
+            raw=d,
+        )
+
+
+@dataclass(slots=True)
+class VoiceState:
+    user_id: str
+    guild_id: str | None
+    #: None when the account left voice.
+    channel_id: str | None
+    self_mute: bool = False
+    self_deaf: bool = False
+    self_stream: bool = False
+    self_video: bool = False
+    session_id: str = ""
+    raw: JSON = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, d: JSON) -> VoiceState:
+        return cls(
+            user_id=str(d["user_id"]),
+            guild_id=d.get("guild_id"),
+            channel_id=d.get("channel_id"),
+            self_mute=bool(d.get("self_mute", False)),
+            self_deaf=bool(d.get("self_deaf", False)),
+            self_stream=bool(d.get("self_stream", False)),
+            self_video=bool(d.get("self_video", False)),
+            session_id=d.get("session_id") or "",
+            raw=d,
+        )
+
+
+@dataclass(slots=True)
+class Guild:
+    """A guild (servidor) as the client keeps it, updated by the gateway's events."""
+
+    id: str
+    name: str
+    icon: str | None
+    owner_id: str
+    channels: dict[str, Channel] = field(default_factory=dict)
+    #: By user id.
+    members: dict[str, Member] = field(default_factory=dict)
+    roles: dict[str, Role] = field(default_factory=dict)
+    emojis: list[Emoji] = field(default_factory=list)
+    #: Ids of members online now (needs the PRESENCES intent to stay current).
+    online: set[str] = field(default_factory=set)
+    raw: JSON = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, d: JSON) -> Guild:
+        channels = [Channel.from_dict(c) for c in d.get("channels") or []]
+        members = [Member.from_dict(m) for m in d.get("members") or []]
+        roles = [Role.from_dict(r) for r in d.get("roles") or []]
+        return cls(
+            id=str(d["id"]),
+            name=d.get("name", ""),
+            icon=d.get("icon"),
+            owner_id=str(d.get("owner_id", "")),
+            channels={c.id: c for c in channels},
+            members={m.user.id: m for m in members},
+            roles={r.id: r for r in roles},
+            emojis=[Emoji.from_dict(e) for e in d.get("emojis") or []],
+            online={str(p) for p in d.get("presences") or []},
+            raw=d,
+        )
+
+
+# ---------- what a bot sends ----------
+
+
+class _CardAuthor(TypedDict):
+    name: str
+
+
+class CardAuthor(_CardAuthor, total=False):
+    url: str
+    icon_url: str
+
+
+class _CardField(TypedDict):
+    name: str
+    value: str
+
+
+class CardField(_CardField, total=False):
+    inline: bool
+
+
+class CardImage(TypedDict):
+    url: str
+
+
+class _CardFooter(TypedDict):
+    text: str
+
+
+class CardFooter(_CardFooter, total=False):
+    icon_url: str
+
+
+class Card(TypedDict, total=False):
+    """A bot's card: a title, text, fields and pictures with a colored edge."""
+
+    title: str
+    #: Markdown, like a message.
+    description: str
+    #: Where the title points.
+    url: str
+    #: The edge's color, 0xRRGGBB.
+    color: int
+    author: CardAuthor
+    fields: list[CardField]
+    #: Wide, under the text.
+    image: CardImage
+    #: Small, beside the text.
+    thumbnail: CardImage
+    footer: CardFooter
+    #: Shown in the footer, in ms.
+    timestamp: int
+
+
+ButtonStyle = Literal["primary", "secondary", "success", "danger", "link"]
+
+
+class _Button(TypedDict):
+    style: ButtonStyle
+
+
+class Button(_Button, total=False):
+    label: str
+    emoji: str
+    #: What the bot gets back when it is clicked (all but links).
+    custom_id: str
+    #: Link buttons only.
+    url: str
+    disabled: bool
+
+
+#: Rows of buttons, top to bottom: up to 5 rows of 5.
+Components = list[list[Button]]
+
+OptionType = Literal["string", "integer", "number", "boolean", "user", "channel", "role"]
+
+
+class CommandChoice(TypedDict):
+    name: str
+    value: str | int | float
+
+
+class _CommandOption(TypedDict):
+    name: str
+    description: str
+    type: OptionType
+
+
+class CommandOption(_CommandOption, total=False):
+    required: bool
+    #: The only values allowed.
+    choices: list[CommandChoice]
+    min_value: float
+    max_value: float
+
+
+class _Command(TypedDict):
+    #: 1 to 32 lowercase letters, digits, _ or -.
+    name: str
+    description: str
+
+
+class Command(_Command, total=False):
+    """A "/" command (docs.zynko.org/bots/comandos)."""
+
+    options: list[CommandOption]

zynko/permissions.py

@@ -0,0 +1,52 @@
+"""What someone may do in a channel, computed the way the server does."""
+
+from __future__ import annotations
+
+from .bits import ALL_PERMISSIONS, Permissions
+from .models import Channel, Guild
+
+__all__ = ["compute_permissions"]
+
+
+def compute_permissions(guild: Guild | None, channel: Channel | None, user_id: str) -> Permissions:
+    """@everyone and the member's roles, then the channel's overwrites.
+
+    Owners and admins may do everything. Without VIEW_CHANNEL nothing is left; without
+    SEND_MESSAGES no ATTACH_FILES; without CONNECT no SPEAK or STREAM.
+    """
+    P = Permissions
+    if channel is None or guild is None:
+        return P(0)
+    member = guild.members.get(user_id)
+    if member is None:
+        return P(0)
+    if guild.owner_id == user_id or member.is_admin:
+        return P(ALL_PERMISSIONS)
+    everyone_role = guild.roles.get(guild.id)
+    base = everyone_role.permissions if everyone_role else 0
+    for r in member.roles:
+        role = guild.roles.get(r)
+        base |= role.permissions if role else 0
+    if base & P.ADMINISTRATOR:
+        return P(ALL_PERMISSIONS)
+    overwrites = channel.permission_overwrites
+    p = base
+    everyone = next((o for o in overwrites if o.type == 0 and o.id == guild.id), None)
+    if everyone is not None:
+        p = (p & ~everyone.deny) | everyone.allow
+    allow = deny = 0
+    for o in overwrites:
+        if o.type == 0 and o.id != guild.id and o.id in member.roles:
+            allow |= o.allow
+            deny |= o.deny
+    p = (p & ~deny) | allow
+    own = next((o for o in overwrites if o.type == 1 and o.id == user_id), None)
+    if own is not None:
+        p = (p & ~own.deny) | own.allow
+    if not p & P.VIEW_CHANNEL:
+        return P(0)
+    if not p & P.SEND_MESSAGES:
+        p &= ~P.ATTACH_FILES
+    if not p & P.CONNECT:
+        p &= ~(P.SPEAK | P.STREAM)
+    return P(p)