zynko 0.1.0__tar.gz

zynko-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv*/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

zynko-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: zynko
+Version: 0.1.0
+Summary: Biblioteca oficial para bots do Zynko: API, gateway e voz.
+Project-URL: Documentation, https://docs.zynko.org/bots/python
+Project-URL: Homepage, https://zynko.org
+License-Expression: MIT
+Keywords: asyncio,bot,chat,voice,zynko
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aiohttp<4,>=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Provides-Extra: voice
+Requires-Dist: livekit==1.2.1; extra == 'voice'
+Description-Content-Type: text/markdown
+
+# zynko
+
+A biblioteca oficial para bots do [Zynko](https://zynko.org) em Python: gateway com
+reconexão, cache de servidores, canais e membros, a API inteira, comandos com "/", cartões e
+botões, e voz (tocar e ouvir áudio nas salas). Feita com asyncio.
+
+```sh
+pip install zynko
+pip install "zynko[voice]"   # com voz
+```
+
+```python
+import os
+import zynko
+
+client = zynko.Client(intents=zynko.Intents.GUILDS | zynko.Intents.MESSAGES)
+
+@client.on("message_create")
+async def ping(msg: zynko.Message):
+    if not msg.mine and msg.content == "!ping":
+        await msg.reply("pong")
+
+client.run(os.environ["ZYNKO_TOKEN"])
+```
+
+Voz:
+
+```python
+voice = await client.join_voice(channel_id)
+voice.player.enqueue("https://exemplo.com/musica.mp3")
+```
+
+Python 3.10 ou mais novo. Para tocar arquivos e links, o ffmpeg precisa estar instalado.
+Exemplos em [`examples/`](examples): `ping.py`, `dado.py` (comandos, cartão e botões) e
+`musica.py`.
+
+Documentação: https://docs.zynko.org/bots/python · Crie seu bot: https://dev.zynko.org
+
+Licença MIT.

zynko-0.1.0/README.md

@@ -0,0 +1,39 @@
+# zynko
+
+A biblioteca oficial para bots do [Zynko](https://zynko.org) em Python: gateway com
+reconexão, cache de servidores, canais e membros, a API inteira, comandos com "/", cartões e
+botões, e voz (tocar e ouvir áudio nas salas). Feita com asyncio.
+
+```sh
+pip install zynko
+pip install "zynko[voice]"   # com voz
+```
+
+```python
+import os
+import zynko
+
+client = zynko.Client(intents=zynko.Intents.GUILDS | zynko.Intents.MESSAGES)
+
+@client.on("message_create")
+async def ping(msg: zynko.Message):
+    if not msg.mine and msg.content == "!ping":
+        await msg.reply("pong")
+
+client.run(os.environ["ZYNKO_TOKEN"])
+```
+
+Voz:
+
+```python
+voice = await client.join_voice(channel_id)
+voice.player.enqueue("https://exemplo.com/musica.mp3")
+```
+
+Python 3.10 ou mais novo. Para tocar arquivos e links, o ffmpeg precisa estar instalado.
+Exemplos em [`examples/`](examples): `ping.py`, `dado.py` (comandos, cartão e botões) e
+`musica.py`.
+
+Documentação: https://docs.zynko.org/bots/python · Crie seu bot: https://dev.zynko.org
+
+Licença MIT.

zynko-0.1.0/examples/dado.py

@@ -0,0 +1,70 @@
+"""Slash commands, a card and buttons: /dado rolls a die and offers to roll again.
+
+    ZYNKO_TOKEN=bot_... python dado.py
+"""
+
+import os
+import random
+
+import zynko
+
+LAVENDER = 0xA594F9
+
+client = zynko.Client(intents=zynko.Intents.GUILDS, api=os.environ.get("ZYNKO_API"))
+
+COMMANDS: list[zynko.Command] = [
+    {
+        "name": "dado",
+        "description": "Rola um dado",
+        "options": [{"name": "lados", "description": "Quantos lados", "type": "integer", "min_value": 2, "max_value": 100}],
+    },
+    {"name": "ping", "description": "Responde pong"},
+]
+
+
+def roll(sides: int, who: str) -> tuple[list[zynko.Card], zynko.Components]:
+    """The card with a roll, and the buttons under it."""
+    card: zynko.Card = {
+        "title": f"🎲 {random.randint(1, sides)}",
+        "description": f"Dado de {sides} lados, rolado por **{who}**.",
+        "color": LAVENDER,
+    }
+    buttons: zynko.Components = [
+        [
+            {"style": "primary", "emoji": "🎲", "label": "De novo", "custom_id": f"dado:{sides}"},
+            {"style": "secondary", "label": "Pronto", "custom_id": "dado:fim"},
+        ]
+    ]
+    return [card], buttons
+
+
+@client.event
+async def on_ready(user: zynko.User) -> None:
+    await client.set_commands(COMMANDS)
+    print(f"{user.display_name} pronto, com {len(COMMANDS)} comandos")
+
+
+@client.event
+async def on_interaction(i: zynko.Interaction) -> None:
+    who = i.member.name if i.member else i.user.display_name
+    if i.type == "command":
+        if i.command == "ping":
+            await i.reply("pong", ephemeral=True)
+        elif i.command == "dado":
+            cards, buttons = roll(int(i.option("lados", 6)), who)
+            await i.reply(cards=cards, components=buttons)
+        return
+    # A click on one of the buttons.
+    if i.custom_id == "dado:fim":
+        await i.update(components=[])
+    elif i.custom_id and i.custom_id.startswith("dado:"):
+        cards, buttons = roll(int(i.custom_id.split(":")[1]), who)
+        await i.update(cards=cards, components=buttons)
+
+
+@client.event
+async def on_error(error: Exception) -> None:
+    print("erro:", error)
+
+
+client.run(os.environ["ZYNKO_TOKEN"])

zynko-0.1.0/examples/musica.py

@@ -0,0 +1,293 @@
+"""A small music bot: joins your voice room and plays links (mp3, ogg, radio streams, anything
+ffmpeg opens), with a queue. Use it with "/" commands (/tocar, /fila...) or the "!" ones
+(!tocar <link>...); what is playing shows as a card with buttons.
+
+    pip install "zynko[voice]"
+    ZYNKO_TOKEN=bot_... python musica.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import unquote, urlparse
+
+import zynko
+from zynko import Intents, Permissions
+
+PREFIX = os.environ.get("PREFIX", "!")
+LAVENDER = 0xA594F9
+
+client = zynko.Client(
+    intents=Intents.GUILDS | Intents.MESSAGES | Intents.VOICE_STATES,
+    api=os.environ.get("ZYNKO_API"),
+)
+
+
+@dataclass
+class Song:
+    url: str
+    title: str
+    #: Who asked for it, and where to talk about it.
+    by: str
+    channel_id: str
+
+
+@dataclass
+class Ctx:
+    """Where a command came from: a "!" message or a "/" command, answered the same way."""
+
+    user_id: str
+    name: str
+    guild_id: str | None
+    channel_id: str
+    #: Answers; ``quiet`` ones only the person sees, when the command came by "/".
+    say: Callable[..., Awaitable[Any]]
+
+
+def title_of(url: str) -> str:
+    """A title for the queue: the link's last part."""
+    u = urlparse(url)
+    last = [p for p in u.path.split("/") if p]
+    return unquote(last[-1]) if last else u.netloc or url
+
+
+def now_playing() -> dict[str, Any]:
+    """The "Tocando agora" card, with the queue's next ones and the buttons."""
+    p = client.voice.player if client.voice else None
+    song: Song | None = p.current.meta if p and p.current else None
+    if not p or not song:
+        return {"cards": [{"title": "Nada tocando", "color": LAVENDER}], "components": []}
+    nxt = [f"{n}. {t.meta.title if t.meta else '?'}" for n, t in enumerate(p.queue[:5], 1)]
+    fields: list[zynko.CardField] = [
+        {"name": "Pedido por", "value": song.by, "inline": True},
+        {"name": "Volume", "value": f"{round(p.volume * 100)}%", "inline": True},
+    ]
+    if nxt:
+        fields.append({"name": f"Próximas ({len(p.queue)})", "value": "\n".join(nxt)})
+    card: zynko.Card = {
+        "author": {"name": "Pausado" if p.paused else "Tocando agora"},
+        "title": song.title,
+        "color": LAVENDER,
+        "fields": fields,
+    }
+    if song.url:
+        card["url"] = song.url
+    buttons: zynko.Components = [
+        [
+            {
+                "style": "secondary",
+                "emoji": "▶️" if p.paused else "⏸️",
+                "label": "Continuar" if p.paused else "Pausar",
+                "custom_id": "pausar",
+            },
+            {"style": "primary", "emoji": "⏭️", "label": "Pular", "custom_id": "pular"},
+            {"style": "danger", "emoji": "⏹️", "label": "Parar", "custom_id": "parar"},
+        ]
+    ]
+    return {"cards": [card], "components": buttons}
+
+
+async def voice_for(ctx: Ctx) -> Any:
+    """Joins the author's voice room, or says why not."""
+    state = client.voice_states.get(ctx.user_id)
+    where = state.channel_id if state else None
+    room = client.channels.get(where) if where else None
+    if not where or not room or room.guild_id != ctx.guild_id:
+        await ctx.say("Entre numa sala de voz deste servidor primeiro.", True)
+        return None
+    if client.voice and client.voice.channel_id == where:
+        return client.voice
+    assert client.user is not None
+    if not client.can(where, client.user.id, Permissions.CONNECT | Permissions.SPEAK):
+        await ctx.say("Não tenho permissão para entrar e falar nessa sala.", True)
+        return None
+    voice = await client.join_voice(where)
+
+    @voice.player.on("start")
+    async def started(track: zynko.Track[Song]) -> None:
+        if track.meta:
+            await client.send(track.meta.channel_id, **now_playing())
+
+    @voice.player.on("error")
+    async def failed(error: Exception, track: zynko.Track[Song]) -> None:
+        if track.meta:
+            await client.send(track.meta.channel_id, f"Não consegui tocar **{track.meta.title}**: {error}")
+
+    voice.on("disconnect", lambda reason: print(f"saiu da voz: {reason}"))
+    return voice
+
+
+async def tocar(ctx: Ctx, arg: str) -> Any:
+    if not re.fullmatch(r"https?://\S+", arg, re.I):
+        return await ctx.say(f"Use: {PREFIX}tocar <link de áudio>", True)
+    voice = await voice_for(ctx)
+    if not voice:
+        return None
+    song = Song(arg, title_of(arg), ctx.name, ctx.channel_id)
+    playing = voice.player.current is not None
+    voice.player.enqueue(arg, song)
+    if playing:
+        return await ctx.say(f"Na fila ({len(voice.player.queue)}): **{song.title}**")
+    return await ctx.say(f"Vai tocar: **{song.title}**", True)
+
+
+async def teste(ctx: Ctx, arg: str) -> Any:
+    voice = await voice_for(ctx)
+    if voice:
+        voice.player.play(zynko.tone(440, 3), Song("", "um lá de 440 Hz", ctx.name, ctx.channel_id))
+        return await ctx.say("Tocando um tom de 3 segundos.", True)
+    return None
+
+
+async def pular(ctx: Ctx, arg: str) -> Any:
+    if not client.voice or not client.voice.player.current:
+        return await ctx.say("Nada tocando.", True)
+    client.voice.player.skip()
+    return await ctx.say("⏭️ Pulei.", True)
+
+
+async def parar(ctx: Ctx, arg: str) -> Any:
+    if client.voice:
+        client.voice.player.stop()
+    return await ctx.say("⏹️ Parei e esvaziei a fila.", True)
+
+
+async def pausar(ctx: Ctx, arg: str) -> Any:
+    if client.voice:
+        client.voice.player.pause()
+    return await ctx.say("⏸️ Pausado.", True)
+
+
+async def continuar(ctx: Ctx, arg: str) -> Any:
+    if client.voice:
+        client.voice.player.resume()
+    return await ctx.say("▶️ Continuando.", True)
+
+
+async def fila(ctx: Ctx, arg: str) -> Any:
+    return await ctx.say(now_playing())
+
+
+async def volume(ctx: Ctx, arg: str) -> Any:
+    if not client.voice:
+        return await ctx.say("Não estou em nenhuma sala.", True)
+    p = client.voice.player
+    try:
+        v = float(arg)
+    except ValueError:
+        v = -1
+    if not 0 <= v <= 200:
+        return await ctx.say(f"Volume atual: {round(p.volume * 100)}%.", True)
+    p.volume = v / 100
+    return await ctx.say(f"🔊 Volume em {v:g}%.", True)
+
+
+async def sair(ctx: Ctx, arg: str) -> Any:
+    if client.voice:
+        await client.voice.leave()
+    return await ctx.say("👋 Saí da sala.", True)
+
+
+COMMANDS: dict[str, Callable[[Ctx, str], Awaitable[Any]]] = {
+    "tocar": tocar,
+    "teste": teste,
+    "pular": pular,
+    "parar": parar,
+    "pausar": pausar,
+    "continuar": continuar,
+    "fila": fila,
+    "volume": volume,
+    "sair": sair,
+}
+
+#: The "/" commands, as the apps show them.
+SLASH: list[zynko.Command] = [
+    {
+        "name": "tocar",
+        "description": "Toca um link, ou põe na fila",
+        "options": [{"name": "link", "description": "Link de áudio (mp3, ogg, rádio...)", "type": "string", "required": True}],
+    },
+    {"name": "pular", "description": "Vai para a próxima da fila"},
+    {"name": "parar", "description": "Para e esvazia a fila"},
+    {"name": "pausar", "description": "Pausa a música"},
+    {"name": "continuar", "description": "Continua a música pausada"},
+    {"name": "fila", "description": "O que está tocando e as próximas"},
+    {
+        "name": "volume",
+        "description": "Muda o volume",
+        "options": [{"name": "porcentagem", "description": "0 a 200", "type": "integer", "min_value": 0, "max_value": 200}],
+    },
+    {"name": "sair", "description": "Sai da sala de voz"},
+    {"name": "teste", "description": "Toca um tom de 3 segundos"},
+]
+
+
+@client.event
+async def on_message_create(msg: zynko.Message) -> None:
+    if msg.mine or msg.author.bot or not msg.guild_id or not msg.content.startswith(PREFIX):
+        return
+    name, _, arg = msg.content[len(PREFIX) :].strip().partition(" ")
+    command = COMMANDS.get(name.lower())
+    if not command:
+        return
+    member = msg.member
+
+    async def say(answer: str | dict[str, Any], quiet: bool = False) -> Any:
+        return await (msg.reply(answer) if isinstance(answer, str) else msg.reply(**answer))
+
+    await command(Ctx(msg.author.id, member.name if member else msg.author.display_name, msg.guild_id, msg.channel_id, say), arg.strip())
+
+
+@client.event
+async def on_interaction(i: zynko.Interaction) -> None:
+    # The buttons on the "Tocando agora" card: act, then refresh that card.
+    if i.type == "button":
+        p = client.voice.player if client.voice else None
+        if p and i.custom_id == "pausar":
+            p.resume() if p.paused else p.pause()
+        elif p and i.custom_id == "pular":
+            p.skip()
+        elif p and i.custom_id == "parar":
+            p.stop()
+        if i.custom_id != "pausar":
+            await asyncio.sleep(0.3)  # a skip only shows the next song once it starts
+        await i.update(**now_playing())
+        return
+
+    async def say(answer: str | dict[str, Any], quiet: bool = False) -> Any:
+        if isinstance(answer, str):
+            return await i.reply(answer, ephemeral=quiet)
+        return await i.reply(**answer, ephemeral=quiet)
+
+    command = COMMANDS.get(i.command or "")
+    if not command:
+        await i.reply("Não conheço esse comando.", ephemeral=True)
+        return
+    who = i.member.name if i.member else i.user.display_name
+    value = i.option("link", i.option("porcentagem"))
+    arg = "" if value is None else str(value)
+    await command(Ctx(i.user.id, who, i.guild_id, i.channel_id, say), arg)
+
+
+@client.event
+async def on_ready(user: zynko.User) -> None:
+    await client.set_commands(SLASH)
+    print(f"{user.display_name} conectado em {len(client.guilds)} servidores, com {len(SLASH)} comandos")
+
+
+@client.event
+async def on_reconnecting(info: dict[str, Any]) -> None:
+    print(f"gateway caiu, reconectando em {info['wait']:.0f}s")
+
+
+@client.event
+async def on_error(error: Exception) -> None:
+    print("erro:", repr(error))
+
+
+client.run(os.environ["ZYNKO_TOKEN"])

zynko-0.1.0/examples/ping.py

@@ -0,0 +1,29 @@
+"""The smallest bot: answers !ping with pong.
+
+    ZYNKO_TOKEN=bot_... python ping.py
+"""
+
+import os
+
+import zynko
+
+client = zynko.Client(
+    intents=zynko.Intents.GUILDS | zynko.Intents.MESSAGES,
+    api=os.environ.get("ZYNKO_API"),  # another server; https://zynko.org/api by default
+)
+
+
+@client.event
+async def on_ready(user: zynko.User) -> None:
+    print(f"{user.display_name} conectado em {len(client.guilds)} servidores")
+
+
+@client.event
+async def on_message_create(msg: zynko.Message) -> None:
+    if msg.mine:
+        return
+    if msg.content == "!ping":
+        await msg.reply("pong")
+
+
+client.run(os.environ["ZYNKO_TOKEN"])

zynko-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling==1.29.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zynko"
+version = "0.1.0"
+description = "Biblioteca oficial para bots do Zynko: API, gateway e voz."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["zynko", "bot", "chat", "voice", "asyncio"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = ["aiohttp>=3.11,<4"]
+
+[project.optional-dependencies]
+voice = ["livekit==1.2.1"]
+dev = ["pytest>=8.3", "pytest-asyncio>=0.24", "mypy>=1.13"]
+
+[project.urls]
+Documentation = "https://docs.zynko.org/bots/python"
+Homepage = "https://zynko.org"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zynko"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/zynko", "README.md", "tests", "examples"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true

zynko-0.1.0/src/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__",
+]