discord-wizard 0.1.0__tar.gz

discord_wizard-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include src/discord/wizard/simulate/web/*

discord_wizard-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: discord-wizard
+Version: 0.1.0
+Summary: A unified Discord.py utility library — events, rate limiting, UI, permissions, tasks, errors, simulation, and recording.
+Author: Muneeb
+License: MIT
+Project-URL: Homepage, https://github.com/draganoxfool/discord-wizard
+Project-URL: Repository, https://github.com/draganoxfool/discord-wizard
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: discord.py>=2.0
+Provides-Extra: postgres
+Requires-Dist: asyncpg; extra == "postgres"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# discord-wizard
+
+A unified Discord.py utility library — events, rate limiting, UI, permissions, tasks, errors, simulation, and recording.
+
+```python
+from discord.wizard import wizard
+
+wizard.events       # Human-friendly event namespace
+wizard.rateguard    # Automatic rate limit protection
+wizard.ui           # Declarative UI components
+wizard.permissions  # Decorator-based permission layer
+wizard.tasks        # Cron jobs & scheduled tasks
+wizard.errors       # Human-readable error formatting
+wizard.simulate     # Run your bot without Discord
+wizard.recorder     # Record & export everything
+```
+
+## Install
+
+```bash
+pip install discord-wizard
+```
+
+## Docs
+
+See the `/docs` folder for full planning documentation.
+
+## License
+
+MIT

discord_wizard-0.1.0/README.md

@@ -0,0 +1,30 @@
+# discord-wizard
+
+A unified Discord.py utility library — events, rate limiting, UI, permissions, tasks, errors, simulation, and recording.
+
+```python
+from discord.wizard import wizard
+
+wizard.events       # Human-friendly event namespace
+wizard.rateguard    # Automatic rate limit protection
+wizard.ui           # Declarative UI components
+wizard.permissions  # Decorator-based permission layer
+wizard.tasks        # Cron jobs & scheduled tasks
+wizard.errors       # Human-readable error formatting
+wizard.simulate     # Run your bot without Discord
+wizard.recorder     # Record & export everything
+```
+
+## Install
+
+```bash
+pip install discord-wizard
+```
+
+## Docs
+
+See the `/docs` folder for full planning documentation.
+
+## License
+
+MIT

discord_wizard-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "discord-wizard"
+version = "0.1.0"
+description = "A unified Discord.py utility library — events, rate limiting, UI, permissions, tasks, errors, simulation, and recording."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Muneeb"},
+]
+classifiers = [
+    "Development Status :: 1 - Planning",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Communications :: Chat",
+]
+dependencies = [
+    "discord.py>=2.0",
+]
+
+[project.optional-dependencies]
+postgres = ["asyncpg"]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/draganoxfool/discord-wizard"
+Repository = "https://github.com/draganoxfool/discord-wizard"
+
+[project.scripts]
+discord-wizard = "discord.wizard.simulate.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["discord.*"]
+exclude = ["discord.__pycache__*", "discord.wizard.__pycache__*"]
+
+[tool.setuptools.package-data]
+"discord.wizard.simulate" = ["web/*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "D"]

discord_wizard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

discord_wizard-0.1.0/src/discord/wizard/__init__.py

@@ -0,0 +1,28 @@
+from . import events, rateguard, ui, permissions, tasks, errors, simulate, recorder, commands
+
+__all__ = [
+    "events",
+    "rateguard",
+    "ui",
+    "permissions",
+    "tasks",
+    "errors",
+    "simulate",
+    "recorder",
+    "commands",
+]
+
+
+class _Wizard:
+    events = events
+    rateguard = rateguard
+    ui = ui
+    permissions = permissions
+    tasks = tasks
+    errors = errors
+    simulate = simulate
+    recorder = recorder
+    commands = commands
+
+
+wizard = _Wizard()

discord_wizard-0.1.0/src/discord/wizard/commands/__init__.py

@@ -0,0 +1,10 @@
+from discord.ext import commands as ext
+from discord import app_commands as app
+
+from .wrapper import BotWrapper
+
+__all__ = ["bot", "BotWrapper", "ext", "app"]
+
+
+def bot(**kwargs):
+    return BotWrapper(**kwargs)

discord_wizard-0.1.0/src/discord/wizard/commands/wrapper.py

@@ -0,0 +1,85 @@
+from discord.ext import commands as _commands
+from discord import app_commands as _app_commands
+
+
+class BotWrapper:
+    def __init__(self, **kwargs):
+        self._bot = _commands.Bot(**kwargs)
+
+    def cmd(self, **kwargs):
+        return self._bot.command(**kwargs)
+
+    def slash(self, **kwargs):
+        return self._bot.tree.command(**kwargs)
+
+    def context_menu(self, **kwargs):
+        return self._bot.tree.context_menu(**kwargs)
+
+    def group(self, **kwargs):
+        return self._bot.group(**kwargs)
+
+    def slash_group(self, **kwargs):
+        def decorator(cls):
+            group = _app_commands.Group(**kwargs)
+            for attr_name in dir(cls):
+                if attr_name.startswith("_"):
+                    continue
+                attr = getattr(cls, attr_name)
+                if isinstance(attr, _app_commands.Command):
+                    group.command(attr)
+            self._bot.tree.add_command(group)
+            return cls
+        return decorator
+
+    async def sync(self, **kwargs):
+        return await self._bot.tree.sync(**kwargs)
+
+    def add_command(self, cmd):
+        self._bot.add_command(cmd)
+
+    def remove_command(self, name):
+        self._bot.remove_command(name)
+
+    def get_command(self, name):
+        return self._bot.get_command(name)
+
+    def add_cog(self, cog, **kwargs):
+        return self._bot.add_cog(cog, **kwargs)
+
+    def remove_cog(self, name, **kwargs):
+        return self._bot.remove_cog(name, **kwargs)
+
+    def get_cog(self, name):
+        return self._bot.get_cog(name)
+
+    def event(self, coro):
+        self._bot.event(coro)
+        return coro
+
+    def listen(self, name=None):
+        return self._bot.listen(name)
+
+    def run(self, *args, **kwargs):
+        self._bot.run(*args, **kwargs)
+
+    def dispatch(self, event_name, *args, **kwargs):
+        self._bot.dispatch(event_name, *args, **kwargs)
+
+    @property
+    def tree(self):
+        return self._bot.tree
+
+    @property
+    def user(self):
+        return self._bot.user
+
+    @property
+    def commands(self):
+        return self._bot.commands
+
+    @property
+    def cogs(self):
+        return self._bot.cogs
+
+    def __getattr__(self, name):
+        return getattr(self._bot, name)

discord_wizard-0.1.0/src/discord/wizard/errors/__init__.py

@@ -0,0 +1,10 @@
+from .formatter import format_terminal, format_embed
+from .handlers import enable, register, set_embed_mode
+
+__all__ = [
+    "enable",
+    "register",
+    "set_embed_mode",
+    "format_terminal",
+    "format_embed",
+]

discord_wizard-0.1.0/src/discord/wizard/errors/formatter.py

@@ -0,0 +1,142 @@
+import datetime
+import traceback
+
+import discord
+
+
+_UTC = datetime.timezone.utc
+
+
+def _timestamp():
+    return datetime.datetime.now(_UTC).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+
+def _extract_context(ctx_or_args):
+    ctx = None
+    if ctx_or_args:
+        if isinstance(ctx_or_args[0], discord.ext.commands.Context):
+            ctx = ctx_or_args[0]
+        elif isinstance(ctx_or_args[0], discord.Interaction):
+            ctx = ctx_or_args[0]
+    return ctx
+
+
+def _guild_name(ctx):
+    if hasattr(ctx, "guild") and ctx.guild:
+        return f"{ctx.guild.name} ({ctx.guild.id})"
+    if hasattr(ctx, "guild_id") and ctx.guild_id:
+        return f"guild {ctx.guild_id}"
+    return "N/A"
+
+
+def _channel_name(ctx):
+    if hasattr(ctx, "channel") and ctx.channel:
+        return f"#{ctx.channel.name} ({ctx.channel.id})"
+    if hasattr(ctx, "channel_id") and ctx.channel_id:
+        return f"channel {ctx.channel_id}"
+    return "N/A"
+
+
+def _user_name(ctx):
+    if isinstance(ctx, discord.Interaction):
+        u = ctx.user
+        return f"{u} ({u.id})"
+    if hasattr(ctx, "author"):
+        u = ctx.author
+        return f"{u} ({u.id})"
+    return "N/A"
+
+
+def _error_label(error):
+    name = type(error).__name__
+    hint = ""
+    if isinstance(error, discord.Forbidden):
+        code = getattr(error, "code", 403)
+        hint = f" ({code} Forbidden)"
+    elif isinstance(error, discord.NotFound):
+        code = getattr(error, "code", 404)
+        hint = f" ({code} Not Found)"
+    elif isinstance(error, discord.HTTPException):
+        code = getattr(error, "code", 400)
+        hint = f" ({code})"
+    elif isinstance(error, discord.RateLimited):
+        hint = " (429 Rate Limited)"
+    return f"{name}{hint}"
+
+
+def _error_message(error):
+    return str(error) or str(type(error))
+
+
+def _error_code(error):
+    if isinstance(error, discord.HTTPException):
+        return error.code
+    if isinstance(error, discord.Forbidden):
+        return error.code
+    if isinstance(error, discord.NotFound):
+        return error.code
+    return getattr(error, "code", None)
+
+
+def format_terminal(error, *args, **kwargs):
+    ctx = _extract_context(args) if args else None
+    label = _error_label(error)
+    msg = _error_message(error)
+    ts = _timestamp()
+    guild = _guild_name(ctx) if ctx else "N/A"
+    channel = _channel_name(ctx) if ctx else "N/A"
+    user = _user_name(ctx) if ctx else "N/A"
+
+    w = max(len(label) + 4, 50)
+    top = "┌" + "─" * (w - 2) + "┐"
+    bot = "└" + "─" * (w - 2) + "┘"
+    gap = " " * (w - 2)
+
+    lines = [
+        top,
+        f"│  ERROR  {label:<{w - 10}}│",
+        f"│{gap}│",
+        f"│  Guild:   {guild:<{w - 12}}│",
+        f"│  Channel: {channel:<{w - 12}}│",
+        f"│  User:    {user:<{w - 12}}│",
+        f"│  Time:    {ts:<{w - 12}}│",
+        f"│{gap}│",
+    ]
+
+    for line in msg.split("\n"):
+        for chunk in [line[i:i + w - 6] for i in range(0, len(line), w - 6)]:
+            lines.append(f"│  {chunk:<{w - 4}}│")
+
+    lines.append(bot)
+    return "\n".join(lines)
+
+
+def format_embed(error, *args, **kwargs):
+    ctx = _extract_context(args) if args else None
+    label = _error_label(error)
+    msg = _error_message(error)
+
+    color = discord.Color.red()
+    if isinstance(error, discord.RateLimited):
+        color = discord.Color.gold()
+    elif isinstance(error, discord.Forbidden):
+        color = discord.Color.dark_red()
+
+    embed = discord.Embed(title=f"\u26a0 Error: {label}", description=msg, color=color, timestamp=datetime.datetime.now(_UTC))
+    if ctx:
+        embed.add_field(name="Guild", value=_guild_name(ctx), inline=True)
+        embed.add_field(name="Channel", value=_channel_name(ctx), inline=True)
+        embed.add_field(name="User", value=_user_name(ctx), inline=True)
+
+    if isinstance(error, discord.Forbidden):
+        embed.add_field(name="Fix", value="Grant the bot the required permission(s) in the guild or channel settings.", inline=False)
+    elif isinstance(error, discord.NotFound):
+        embed.add_field(name="Fix", value="The resource may have been deleted or the ID is incorrect. Check the ID and try again.", inline=False)
+    elif isinstance(error, discord.RateLimited):
+        retry = getattr(error, "retry_after", None)
+        txt = f"Slow down! Wait {retry:.1f}s before the next request." if retry else "Slow down and wait before sending more requests."
+        embed.add_field(name="Fix", value=txt, inline=False)
+    elif isinstance(error, discord.HTTPException):
+        embed.add_field(name="Fix", value="Check the request parameters. The payload may be malformed or too large.", inline=False)
+
+    return embed

discord_wizard-0.1.0/src/discord/wizard/errors/handlers.py

@@ -0,0 +1,81 @@
+import asyncio
+import logging
+import traceback
+
+import discord
+
+from .formatter import format_terminal, format_embed
+
+
+_log = logging.getLogger("wizard.errors")
+
+_handlers = {}
+_embed_mode = False
+_bot_ref = None
+
+
+def register(error_type, handler):
+    _handlers[error_type] = handler
+
+
+def set_embed_mode(enabled=True):
+    global _embed_mode
+    _embed_mode = enabled
+
+
+async def _send_owner_embed(bot, embed):
+    try:
+        owner_id = bot.owner_id
+        owner = bot.get_user(owner_id)
+        if owner:
+            await owner.send(embed=embed)
+    except Exception:
+        pass
+
+
+def _default_handler(error, *args):
+    term = format_terminal(error, *args)
+    print(term, flush=True)
+    if _embed_mode and _bot_ref:
+        try:
+            embed = format_embed(error, *args)
+            asyncio.create_task(_send_owner_embed(_bot_ref, embed))
+        except Exception:
+            pass
+    _log.error("Unhandled error: %s: %s", type(error).__name__, error)
+
+
+def _make_on_error(bot):
+    async def on_error(event, *args, **kwargs):
+        error = args[-1] if args else kwargs.get("exception", None)
+        if not isinstance(error, BaseException):
+            return
+        _route_error(error, event, *args)
+
+    return on_error
+
+
+def _make_tree_on_error(bot):
+    async def on_error(interaction, error):
+        _route_error(error, "tree", interaction)
+
+    return on_error
+
+
+def _route_error(error, event, *args):
+    for err_type, handler in _handlers.items():
+        if isinstance(error, err_type):
+            try:
+                handler(error, *args)
+                return
+            except Exception:
+                pass
+    _default_handler(error, *args)
+
+
+def enable(bot, *, embed_mode=False):
+    global _bot_ref, _embed_mode
+    bot.on_error = _make_on_error(bot)
+    bot.tree.on_error = _make_tree_on_error(bot)
+    _bot_ref = bot
+    _embed_mode = embed_mode

discord_wizard-0.1.0/src/discord/wizard/events/__init__.py

@@ -0,0 +1,117 @@
+__all__ = ["member", "message", "voice", "role", "reaction", "group", "enable"]
+
+
+class _EventRegistry:
+    def __init__(self):
+        self._handlers = []
+        self._bot = None
+        self._active_listeners = set()
+
+    def decorator(self, event_name, raw_event, *, arg_transform=None, condition=None):
+        return _EventDecorator(self, event_name, raw_event, arg_transform, condition)
+
+    def register(self, event_name, func, *, filters=None, group=None):
+        self._handlers.append({
+            "event": event_name,
+            "func": func,
+            "filters": filters or {},
+            "group": group,
+        })
+        if self._bot is not None:
+            self._wire(event_name)
+
+    def enable(self, bot):
+        self._bot = bot
+        for entry in self._handlers:
+            self._wire(entry["event"])
+
+    def _wire(self, event_name):
+        raw_event = None
+        for entry in self._handlers:
+            if entry["event"] == event_name:
+                raw_event = getattr(entry["func"], "_wizard_raw_event", None)
+                if raw_event is not None:
+                    break
+        if raw_event is None:
+            return
+        if raw_event not in self._active_listeners:
+            self._active_listeners.add(raw_event)
+            self._bot.add_listener(self._dispatch(raw_event), raw_event)
+
+    def _dispatch(self, raw_event):
+        registry = self
+
+        async def listener(*args):
+            for entry in registry._handlers:
+                func = entry["func"]
+                ev_raw = getattr(func, "_wizard_raw_event", None)
+                if ev_raw != raw_event:
+                    continue
+
+                transform = getattr(func, "_wizard_transform", None)
+                condition = getattr(func, "_wizard_condition", None)
+
+                if condition is not None and not condition(*args):
+                    continue
+
+                dispatch_args = transform(*args) if transform is not None else args
+
+                from .filters import check_filters
+                if not check_filters(entry["filters"], *dispatch_args):
+                    continue
+
+                await func(*dispatch_args)
+
+        return listener
+
+    def handlers(self, event_name=None, group=None):
+        result = []
+        for entry in self._handlers:
+            if event_name is not None and entry["event"] != event_name:
+                continue
+            if group is not None and entry["group"] != group:
+                continue
+            result.append(entry)
+        return result
+
+
+_registry = _EventRegistry()
+
+
+class _EventDecorator:
+    def __init__(self, registry, event_name, raw_event, arg_transform, condition):
+        self._registry = registry
+        self._event_name = event_name
+        self._raw_event = raw_event
+        self._arg_transform = arg_transform
+        self._condition = condition
+
+    def __call__(self, func=None, **filters):
+        if func is not None:
+            self._mark(func)
+            self._registry.register(self._event_name, func, filters=filters)
+            return func
+
+        def wrapper(f):
+            self._mark(f)
+            self._registry.register(self._event_name, f, filters=filters)
+            return f
+        return wrapper
+
+    def _mark(self, func):
+        func._wizard_event = self._event_name
+        func._wizard_raw_event = self._raw_event
+        func._wizard_transform = self._arg_transform
+        func._wizard_condition = self._condition
+
+
+def enable(bot):
+    _registry.enable(bot)
+
+
+from .member import member
+from .message import message
+from .voice import voice
+from .role import role
+from .reaction import reaction
+from .groups import group

discord_wizard-0.1.0/src/discord/wizard/events/filters.py

@@ -0,0 +1,48 @@
+def check_filters(filters, *args, **kwargs):
+    if not filters:
+        return True
+
+    if "ignore_bots" in filters and filters["ignore_bots"]:
+        if args and hasattr(args[0], "bot") and args[0].bot:
+            return False
+        if args and hasattr(args[0], "author") and getattr(args[0].author, "bot", False):
+            return False
+
+    if "guild_id" in filters:
+        guild_id = filters["guild_id"]
+        for arg in args:
+            g = _get_guild(arg)
+            if g is not None and g.id != guild_id:
+                return False
+
+    if "channels" in filters:
+        channel_ids = filters["channels"]
+        channel = _get_channel(args)
+        if channel is not None and channel.id not in channel_ids:
+            return False
+
+    if "has_role" in filters:
+        role_name = filters["has_role"]
+        for arg in args:
+            if hasattr(arg, "roles"):
+                if not any(r.name == role_name for r in arg.roles):
+                    return False
+
+    return True
+
+
+def _get_guild(obj):
+    if hasattr(obj, "guild"):
+        return obj.guild
+    if hasattr(obj, "guild_id"):
+        return type("GuildRef", (), {"id": obj.guild_id})()
+    return None
+
+
+def _get_channel(args):
+    for arg in args:
+        if hasattr(arg, "channel"):
+            return arg.channel
+        if hasattr(arg, "id") and hasattr(arg, "name"):
+            return arg
+    return None