mizuki 0.1.0__tar.gz

mizuki-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sora Takemi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mizuki-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: mizuki
+Version: 0.1.0
+Summary: A modern async-based API wrapper for Discord API.
+Author: Sora
+License-Expression: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.13.5
+Provides-Extra: docs
+Requires-Dist: shibuya>=2026.5.19; extra == "docs"
+Requires-Dist: sphinx>=9.1.0; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
+Dynamic: license-file
+
+# Mizuki
+
+A modern async-based discord API wrapper written for Python. Currently in early development, not meant to be used in production as of now.  
+I aim for this library to closely mirror the discord API.
+
+## Installation
+
+```
+pip install git+https://github.com/TakemiSora/mizuki
+```
+
+## Quick Example
+
+```python
+import mizuki
+
+bot = mizuki.Bot(
+     intents=mizuki.IntentFlags.standard()
+)
+
+@bot.command(name="ping", description="Send a ping to the bot")
+async def ping(interaction: mizuki.Interaction):
+    await interaction.response.send_response("Pong!")
+
+bot.run("TOKEN-HERE")
+```
+
+## Documentation
+
+There is no current hosted documentation (yet), but a local version of the documentation can be viewed by doing the following steps:
+
+```
+# 1. Clone the repository
+git clone https://github.com/TakemiSora/mizuki
+
+# 2. Navigate into the docs directory
+cd mizuki/docs/
+
+# 3. Build the HTML documentation
+## Linux/Mac
+make html
+
+## Windows
+make.bat html
+
+# 4. Start a local server to view them
+cd build/html
+python -m http.server 8000
+```
+
+Then open `https://localhost:8000/` to open the documentation.

mizuki-0.1.0/README.md

@@ -0,0 +1,51 @@
+# Mizuki
+
+A modern async-based discord API wrapper written for Python. Currently in early development, not meant to be used in production as of now.  
+I aim for this library to closely mirror the discord API.
+
+## Installation
+
+```
+pip install git+https://github.com/TakemiSora/mizuki
+```
+
+## Quick Example
+
+```python
+import mizuki
+
+bot = mizuki.Bot(
+     intents=mizuki.IntentFlags.standard()
+)
+
+@bot.command(name="ping", description="Send a ping to the bot")
+async def ping(interaction: mizuki.Interaction):
+    await interaction.response.send_response("Pong!")
+
+bot.run("TOKEN-HERE")
+```
+
+## Documentation
+
+There is no current hosted documentation (yet), but a local version of the documentation can be viewed by doing the following steps:
+
+```
+# 1. Clone the repository
+git clone https://github.com/TakemiSora/mizuki
+
+# 2. Navigate into the docs directory
+cd mizuki/docs/
+
+# 3. Build the HTML documentation
+## Linux/Mac
+make html
+
+## Windows
+make.bat html
+
+# 4. Start a local server to view them
+cd build/html
+python -m http.server 8000
+```
+
+Then open `https://localhost:8000/` to open the documentation.

mizuki-0.1.0/mizuki/__init__.py

@@ -0,0 +1,11 @@
+from .cache import *
+from .objects import *
+from .flags import *
+from .bot import *
+from .parameter import *
+from .enums import *
+from .errors import *
+
+import logging
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())

mizuki-0.1.0/mizuki/_event_dispatch.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+import asyncio
+import logging
+from typing import Any, TYPE_CHECKING
+
+from .objects.command import ApplicationCommandOption
+
+from .enums.channel import ChannelType
+from .enums.command import CommandOptionType
+from .enums.interaction import InteractionType
+from .objects.channel import ThreadChannel, ThreadMember, parse_channel_payload
+from .objects.guild import Guild, UnavailableGuild, parse_guild_payload
+from .objects.interaction import Interaction, ResolvedData, InvokedApplicationCommandOption
+from .payloads.channel import (
+    GuildChannelPayload,
+    PrivateChannelPayload,
+    ThreadCreatePayload,
+    ThreadDeletePayload,
+    ThreadPayload,
+)
+from .payloads.guild import GuildPayload, UnavailableGuildPayload
+from .payloads.interaction import InteractionPayload
+from ._utils import scls
+
+if TYPE_CHECKING:
+    from .bot import Bot
+
+_log = logging.getLogger(__name__)
+
+class EventDispatcher:
+    __slots__ = (
+        "_dispatch_handlers",
+        "bot"
+    )
+
+    def __init__(self, bot: Bot):
+        self.bot = bot
+        self._dispatch_handlers = {
+            # GUILDS 
+                "GUILD_CREATE": self._handle_guild_create,
+                "GUILD_UPDATE": self._handle_guild_update,
+                "GUILD_DELETE": self._handle_guild_delete,
+                "CHANNEL_CREATE": self._handle_channel_create,
+                "CHANNEL_UPDATE": self._handle_channel_update,
+                "CHANNEL_DELETE": self._handle_channel_delete,
+                "THREAD_CREATE": self._handle_thread_create,
+                "THREAD_UPDATE": self._handle_thread_update,
+                "THREAD_DELETE": self._handle_thread_delete,
+            "INTERACTION_CREATE": self._handle_interaction_create,
+            "READY": self._handle_ready
+        }
+
+    def _on_task_done(self, task: asyncio.Task, data: str):
+        if task.cancelled():
+            return
+        exc = task.exception()
+        if exc is not None:
+            _log.error("%s failed with exception", data, exc_info=exc)
+
+    async def _dispatch(self, key: str, *args: Any):
+        for f in self.bot._listeners.get(key, []):
+            asyncio.create_task(f(*args)).add_done_callback(lambda t: self._on_task_done(t, f"Function {f.__name__} listening to '{key}'"))
+            _log.debug("Dispatched %s to function '%s'.", key, f.__name__)
+    
+    def _parse_options(self, command_options: dict[str, ApplicationCommandOption], resolved: ResolvedData, options: list[InvokedApplicationCommandOption]) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {}
+        display_to_callback_keys: dict[str, str] = {o.name: p for p, o in command_options.items()}
+        for option in options:
+            match option.type:
+                case CommandOptionType.CHANNEL:
+                    assert isinstance(option.value, str)
+                    value = resolved.channels[int(option.value)]
+                case CommandOptionType.ROLE:
+                    assert isinstance(option.value, str)
+                    value = resolved.roles[int(option.value)]
+                case CommandOptionType.USER:
+                    assert isinstance(option.value, str)
+                    if (m := resolved.members.get(int(option.value))) is not None: value = m
+                    else: value = resolved.users[int(option.value)]
+                case CommandOptionType.MENTIONABLE:
+                    assert isinstance(option.value, str)
+                    val = int(option.value)
+                    if (r := resolved.roles.get(val)) is not None:
+                        value = r
+                    else:
+                        if (m := resolved.members.get(val)) is not None: value = m
+                        else: value = resolved.users[val]
+                case _:
+                    value = None
+            kwargs[display_to_callback_keys.get(option.name, option.name)] = value or option.value
+            #                      ^^^^^^^^^^^^^^^^^^^
+            #   Attempts to fjnd correct CallbackParameterName, if not defaults to DisplayParameterName
+        return kwargs
+            
+    async def _dispatch_commands(self, name: str, interaction: Interaction):
+        command_data = self.bot._commands_data.get(name)
+        callback = command_data[1]._callback if command_data else None
+        if callback and command_data:
+            assert interaction.type is InteractionType.APPLICATION_COMMAND and interaction.data is not None
+            kwargs = self._parse_options(
+                getattr(callback, "__command_options__", {}),
+                interaction.data.resolved,
+                interaction.data.options
+            ) if interaction.data.resolved else {}
+            task = asyncio.create_task(callback(interaction, **kwargs))
+            task.add_done_callback(lambda t: self._on_task_done(t, f"Handler Function {callback.__name__} for command '{name}'"))
+            _log.debug("Command %s (func=%s) dispatched.", name, callback.__name__)
+        else:
+            _log.warning("Recieved command %s, but no handler was found for it.", name)
+            
+    async def _handle_guild_create(self, data: GuildPayload | UnavailableGuildPayload):
+        guild = self.bot._storage.update_guilds(g) if isinstance((g := parse_guild_payload(data)), Guild) else g
+        await self._dispatch("on_guild_create", guild)
+        
+    async def _handle_guild_update(self, data: GuildPayload):
+        guild = self.bot._storage.update_guilds(Guild(data))
+        await self._dispatch("on_guild_update", guild)
+    
+    async def _handle_guild_delete(self, data: UnavailableGuildPayload):
+        guild = UnavailableGuild(data)
+        kicked = not guild.unavailable
+        await self._dispatch("on_guild_delete", guild, kicked)
+
+    async def _handle_channel_create(self, data: GuildChannelPayload | PrivateChannelPayload):
+        channel = self.bot._storage.update_channels(parse_channel_payload(data))
+        await self._dispatch("on_channel_create", channel)
+
+    async def _handle_channel_update(self, data: GuildChannelPayload | PrivateChannelPayload):
+        channel = self.bot._storage.update_channels(parse_channel_payload(data))
+        await self._dispatch("on_channel_update", channel)
+
+    async def _handle_channel_delete(self, data: GuildChannelPayload | PrivateChannelPayload):
+        channel = self.bot._storage.remove_channel(int(data["id"]))
+        await self._dispatch("on_channel_delete", channel or parse_channel_payload(data))
+
+    async def _handle_thread_create(self, data: ThreadCreatePayload):
+        newly_created = data.get("newly_created", False)
+        thread_member = scls(ThreadMember, data.get("member"))
+        channel = self.bot._storage.update_channels(ThreadChannel(data))
+        await self._dispatch("on_thread_create", channel, newly_created, thread_member)
+
+    async def _handle_thread_update(self, data: ThreadPayload):
+        channel = self.bot._storage.update_channels(ThreadChannel(data))
+        await self._dispatch("on_thread_update", channel)
+
+    async def _handle_thread_delete(self, data: ThreadDeletePayload):
+        id = int(data["id"])
+        guild_id = int(data["guild_id"])
+        parent_id = int(data["parent_id"])
+        type = ChannelType(data["type"])
+        self.bot._storage.remove_channel(id)
+        await self._dispatch("on_thread_delete", id, guild_id, parent_id, type)
+        
+    async def _handle_interaction_create(self, data: InteractionPayload):
+        guild = self.bot.guilds.get(int(g)) if (g := data.get("guild_id")) else None
+        interaction = Interaction(self.bot.http, data, guild=guild)
+        match interaction.type:
+            case InteractionType.APPLICATION_COMMAND:
+                if interaction.data: await self._dispatch_commands(interaction.data.name, interaction)
+
+        await self._dispatch("on_interaction_create", interaction)
+
+    async def _handle_ready(self, _):
+        await self._dispatch("on_ready")

mizuki-0.1.0/mizuki/_utils.py

@@ -0,0 +1,39 @@
+from datetime import datetime
+from typing import Any, Protocol
+from collections.abc import Callable, Coroutine
+
+class Missing:
+    __slots__ = ()
+
+    def __bool__(self) -> bool:
+        return False
+
+_MISSING: Any = Missing()
+
+type CoroFunc = Callable[..., Coroutine[Any, Any, Any]]
+type CoroDecorator = Callable[[CoroFunc], CoroFunc]
+
+class SupportsToDict(Protocol):
+    def _to_dict(self) -> Any: ...
+
+def assign_val[T](obj: T, check_against: Any = _MISSING, /, **kwargs: Any) -> T:
+    for key, val in kwargs.items():
+        if val is not check_against: setattr(obj, key, val)
+    return obj
+
+def mtd[T: SupportsToDict](obj: T | None) -> T | None:
+    return obj._to_dict() if obj is not None else None
+
+def assign_val_dict[T](d: T, check_against: Any = None, /, **kwargs: Any) -> T:
+    for key, val in kwargs.items():
+        if val is not check_against: d[key] = val # type: ignore
+    return d
+
+def sint(txt: str | None) -> int | None:
+    return int(txt) if txt else None
+
+def siso(txt: str | None) -> datetime | None:
+    return datetime.fromisoformat(txt) if txt else None
+
+def scls[C](cls: Callable[..., C], data: Any, **kwargs: Any) -> C | None:
+    return cls(data, **kwargs) if data else None

mizuki-0.1.0/mizuki/bot.py

@@ -0,0 +1,310 @@
+import asyncio
+
+import logging
+import inspect
+from typing import overload
+
+import aiohttp
+
+from .cache import CacheSettings, CacheStorage
+from .enums.event_dispatch import Event
+from .errors import ImproperToken, Unauthorized
+from .flags import IntentFlags
+from .gateway import GatewayClient
+from .http import HTTPClient
+from ._utils import _MISSING, CoroFunc, CoroDecorator
+
+from .enums.command import ApplicationCommandType
+from .enums.interaction import InteractionContextType, ApplicationIntegrationType
+
+from .objects.command import PartialApplicationCommand, Localization, ApplicationCommandOption
+from .objects.user import User
+from .objects.permissions import Permissions
+
+from .managers.channel import ChannelManager
+from .managers.guild import GuildManager
+from .managers.message import MessageManager
+from .managers.user import UserManager
+from .managers.command import CommandManager
+
+__all__ = (
+    "Bot",
+)
+
+_log = logging.getLogger(__name__)
+
+class Bot:
+    """
+    Represents a Discord Bot.
+    
+    Parameters
+    ----------
+    intents : :class:`IntentFlags <mizuki.flags.IntentFlags>`
+        The IntentFlags to be passed to the GatewayClient.
+    cache_settings : :class:`CacheSettings <mizuki.cache.CacheSettings>`, optional
+        The CacheSettings for managing the Cache System of the Bot instance. Defaults to ``CacheSettings()``
+    """
+    
+    intents: IntentFlags
+    "The IntentFlags to be passed to the :class:`GatewayClient <mizuki.gateway.GatewayClient>`."
+    
+    http: HTTPClient
+    "The HTTPClient used for the REST API."
+    
+    gateway: GatewayClient
+    "The GatewayClient that manages the Gateway Connection."
+    
+    users: UserManager
+    "The UserManager used to managers User objects."
+    
+    messages: MessageManager
+    "The MessageManager used to manage Message objects."
+    
+    channels: ChannelManager
+    "The ChannelManager used to manage Channel objects."
+    
+    guilds: GuildManager
+    "The GuildManager used to manage Guild objects."
+    
+    commands: CommandManager
+    "The CommandManager used to manage Commands."
+    
+    user: User
+    "The User object of the bot."
+    
+    __slots__ = (
+        "intents",
+        "http",
+        "gateway",
+        "_listeners",
+        "_setup_hook",
+        "_commands_data",
+        "_storage",
+        "users",
+        "messages",
+        "channels",
+        "guilds",
+        "commands",
+        "user",
+        "_session"
+    )
+    
+    def __init__(
+        self, *,
+        intents: IntentFlags,
+        cache_settings: CacheSettings = CacheSettings()
+    ):
+        self.intents = intents
+        self.http = HTTPClient()
+        self._listeners: dict[str, list[CoroFunc]] = {}
+        self._setup_hook: CoroFunc | None = None
+        self._commands_data: dict[str, tuple[int, PartialApplicationCommand]] = {}
+
+        self._storage = CacheStorage(cache_settings)
+        self.users = UserManager(self.http, self._storage)
+        self.messages = MessageManager(self.http, self._storage)
+        self.channels = ChannelManager(self.http, self._storage)
+        self.guilds = GuildManager(self.http, self._storage)
+        
+        self._session: aiohttp.ClientSession | None = None
+
+    def run(self, token: str) -> None:
+        """
+        A synchronous method to start a event loop and run the :meth:`Bot.start()` method.
+        
+        Parameters
+        ----------
+        token : :class:`str`
+            The bot token used to authenticate with discord. Do not prefix this, the library will handle prefixing.        
+
+        Raises
+        ------
+        :class:`ImproperToken`
+            An improper token was passed.
+        """
+        asyncio.run(self.start(token))
+        
+    async def _verify_token(self) -> User:
+        try:
+            return await self.users.fetch_me()
+        except Unauthorized:
+            raise ImproperToken(401, "Improper token has been passed.")
+
+    async def start(self, token: str) -> None:
+        """
+        Verifies the token and connects to the gateway.
+        
+        Parameters
+        ----------
+        token : :class:`str`
+            The bot token used to authenticate with discord. Do not prefix this, the library will handle prefixing.
+            
+        Raises
+        ------
+        :class:`ImproperToken`
+            An improper token was passed.
+        """
+        try:
+            if self._storage.settings.cache_invalidation: self._storage.start_cleanup_tasks()
+            self._session = aiohttp.ClientSession(
+                "https://discord.com/api/v10/",
+                headers={
+                    "Authorization": f"Bot {token}"
+                }
+            )
+            self.http._session = self._session
+            _log.debug("Attempting to verify token (length=%s)", len(token))
+            self.user = await self._verify_token()
+            _log.info("Verified token successfully.")
+            self.commands = CommandManager(self.http, self._storage, self.user.id, self._commands_data)
+            self.gateway = GatewayClient(self, self._session, token, self.intents)
+            await self.gateway.connect()
+            if self._setup_hook is not None:
+                await self._setup_hook()
+            await self.gateway.wait_until_closed()
+        except asyncio.CancelledError:
+            raise
+        finally:
+            await self.stop()
+
+    async def stop(self) -> None:
+        """
+        Disconnects the gateway and closes the session.
+        """
+        try:
+            if self.gateway:
+                await self.gateway.close()
+        finally:
+            if self._session:
+                await self._session.close()
+
+    def listen(self, event: Event | None = None) -> CoroDecorator:
+        """
+        This function is a decotstor.
+        
+        Registers an asynchronous listener for a gateway event.
+        
+        Parameters
+        ----------
+        event : :class:`Event <mizuki.enums.event_dispatch.Event>` | :class:`None`, optional
+            The Gateway Event to listen to. Defaults to name of function in format such as ``on_interaction_create``. Defaults to ``None``
+            
+        Raises
+        ------
+        :class:`TypeError`
+            The decorator was applied to a synchronous function.
+                    
+        Examples
+        --------
+        Registering based on the function name:
+        
+        .. code-block:: python
+        
+            @bot.listen()
+            async def on_message_create(message: mizuki.Message) -> None:
+                ...
+        
+        Explicitly passing event name:
+        
+        .. code-block:: python
+        
+            @bot.listen(mizuki.Event.MESSAGE_CREATE)
+            async def can_be_named_anything(message: mizuki.Message) -> None:
+                ...
+        """
+        def decorator(func: CoroFunc) -> CoroFunc:
+            if not inspect.iscoroutinefunction(func): raise TypeError(f"Event listener '{func.__name__}' has to be a coroutine function.")
+            self._listeners.setdefault(event.value if event is not None else func.__name__, []).append(func)
+            return func
+        return decorator
+        
+    def setup(self) -> CoroDecorator:
+        """
+        This function is a decorator.
+        
+        Registers a setup hook which runs once after connecting to the gateway.
+        
+        Raises
+        ------
+        :class:`TypeError`
+            The decorator was applied to a synchronous function.
+        """
+        def decorator(func: CoroFunc) -> CoroFunc:
+            if not inspect.iscoroutinefunction(func): raise TypeError(f"Setup hook '{func.__name__}' has to be a coroutine function.")
+            self._setup_hook = func
+            return func
+        return decorator
+
+    @overload
+    def command(
+        self, *,
+        guild_id: int,
+        name: str,
+        name_localizations: Localization = _MISSING,
+        description: str,
+        description_localizations: Localization = _MISSING,
+        default_member_permissions: Permissions = _MISSING,
+        nsfw: bool = False
+    ) -> CoroDecorator: ...
+
+    @overload
+    def command(
+        self, *,
+        name: str,
+        name_localizations: Localization = _MISSING,
+        description: str,
+        description_localizations: Localization = _MISSING,
+        default_member_permissions: Permissions = _MISSING,
+        integration_types: list[ApplicationIntegrationType] = _MISSING,
+        contexts: list[InteractionContextType] = _MISSING,
+        nsfw: bool = False
+    ) -> CoroDecorator: ...
+        
+    def command(
+        self, *,
+        guild_id: int | None = None,
+        name: str,
+        name_localizations: Localization = _MISSING,
+        description: str,
+        description_localizations: Localization = _MISSING,
+        default_member_permissions: Permissions = _MISSING,
+        integration_types: list[ApplicationIntegrationType] = _MISSING,
+        contexts: list[InteractionContextType] = _MISSING,
+        nsfw: bool = False
+    ) -> CoroDecorator:
+        """
+        This function is a decorator.
+        
+        Registers a command callback for a slash (application) command.
+
+        Parameters
+        ----------
+        name : :class:`str`
+            The name of the application command.
+        description : :class:`str`, optional
+            The description of the application command.
+            
+        Raises
+        ------
+        :class:`TypeError`
+            The decorator was applied to a synchronous function.
+        """
+        def decorator(func: CoroFunc) -> CoroFunc:
+            if not inspect.iscoroutinefunction(func): raise TypeError(f"Command callback for '{name}:{func.__name__}' has to be a coroutine function.")
+            
+            self._commands_data[name] = guild_id or 0, PartialApplicationCommand._from_command(
+                func,
+                name=name,
+                name_localizations=name_localizations,
+                description=description,
+                description_localizations=description_localizations,
+                default_member_permissions=default_member_permissions,
+                integration_types=integration_types,
+                contexts=contexts,
+                type=ApplicationCommandType.CHAT_INPUT,
+                nsfw=nsfw
+            )
+
+            return func
+
+        return decorator