xincord-plugins 1.0.0__py3-none-any.whl

xincord/plugins/__init__.py

@@ -0,0 +1 @@
+"""The official xincord plugins, one subpackage per plugin."""

xincord/plugins/auto_role/__init__.py

@@ -0,0 +1,25 @@
+"""AutoRole: members who join a configured guild get that guild's roles."""
+
+from typing import TYPE_CHECKING
+
+import discord
+
+from .cog import AutoRole
+from .config import Config
+
+if TYPE_CHECKING:
+    from xincord.core.bot import Bot
+
+DEPENDS: tuple[str, ...] = ()
+SOFT_DEPENDS: tuple[str, ...] = ()
+# Member joins need the privileged members intent.
+INTENTS = discord.Intents(members=True)
+
+
+async def setup(bot: Bot) -> None:
+    """Load the config and add the cog.
+
+    The plugin has no lang files: it has no text.
+    """
+    context = bot.plugin_context(__name__)
+    await bot.add_cog(AutoRole(bot, context.config(Config)))

xincord/plugins/auto_role/cog.py

@@ -0,0 +1,115 @@
+"""The listeners that give members who join a configured guild its roles."""
+
+import logging
+from typing import TYPE_CHECKING, override
+
+import discord
+from discord.ext import commands
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from .config import Config
+
+logger = logging.getLogger(__name__)
+
+
+class AutoRole(commands.Cog):
+    """The plugin's state and listeners; ``setup`` adds them."""
+
+    def __init__(self, bot: commands.Bot, config: Config) -> None:
+        """Keep the bot and each configured guild's role IDs.
+
+        A reload builds a new cog, so the guilds and their roles change together.
+        """
+        self.bot = bot
+        self.roles = config.roles_by_guild()
+
+    @override
+    async def cog_load(self) -> None:
+        """Check the config at once when the plugin loads into a ready bot, as on a reload."""
+        if self.bot.is_ready():
+            self.check()
+
+    @commands.Cog.listener()
+    async def on_ready(self) -> None:
+        """Check the config once the guilds are known; discord.py fires this per session."""
+        self.check()
+
+    def check(self) -> None:
+        """Log what keeps each configured guild's roles from being given."""
+        for guild_id, role_ids in self.roles.items():
+            guild = self.bot.get_guild(guild_id)
+            if guild is None:
+                logger.warning(
+                    "AutoRole gives no roles in guild %s: the bot is not in it", guild_id
+                )
+                continue
+            if guild.unavailable:  # an outage: no roles or members are known, and none can join
+                continue
+            _can_manage_roles(guild)
+            _givable(guild, role_ids)
+
+    @commands.Cog.listener()
+    async def on_member_join(self, member: discord.Member) -> None:
+        """Give a member who joined a configured guild that guild's roles, one by one.
+
+        discord.py builds the member from the join event, so no member cache is needed.
+        """
+        guild = member.guild
+        role_ids = self.roles.get(guild.id)
+        if role_ids is None or not _can_manage_roles(guild):
+            return
+        for role in _givable(guild, role_ids):
+            try:
+                # discord.py's atomic add sends one add-role request, which keeps the member's
+                # other roles.
+                await member.add_roles(role)
+            except discord.HTTPException as error:
+                logger.warning(
+                    "AutoRole could not give role %s (%s) to %s (%s) in %s (%s): %s",
+                    role.name,
+                    role.id,
+                    member.name,
+                    member.id,
+                    guild.name,
+                    guild.id,
+                    error,
+                )
+
+
+def _can_manage_roles(guild: discord.Guild) -> bool:
+    """Whether the bot has Manage Roles in ``guild``; log a warning if it does not."""
+    if guild.me.guild_permissions.manage_roles:
+        return True
+    logger.warning(
+        "AutoRole gives no roles in %s (%s): the bot lacks Manage Roles", guild.name, guild.id
+    )
+    return False
+
+
+def _givable(guild: discord.Guild, role_ids: Iterable[int]) -> list[discord.Role]:
+    """Return the roles of ``role_ids`` that the bot can give in ``guild``, each once.
+
+    Roles are looked up in ``guild`` at each call. Each role that is missing or that the bot
+    cannot give is logged and left out; the others are still given.
+    """
+    roles: list[discord.Role] = []
+    for role_id in dict.fromkeys(role_ids):
+        role = guild.get_role(role_id)
+        if role is None:
+            logger.warning(
+                "AutoRole skips role %s: it is not in %s (%s)", role_id, guild.name, guild.id
+            )
+        elif not role.is_assignable():  # Discord's rules, checked before any request
+            logger.warning(
+                "AutoRole skips role %s (%s) in %s (%s): it is managed, @everyone or not below "
+                "the bot's highest role",
+                role.name,
+                role.id,
+                guild.name,
+                guild.id,
+            )
+        else:
+            roles.append(role)
+    return roles

xincord/plugins/auto_role/config.py

@@ -0,0 +1,28 @@
+"""The plugin's ``config.yaml``."""
+
+from typing import Annotated
+
+from pydantic import Field, PositiveInt
+
+from xincord.core.config import Model
+
+
+class GuildRoles(Model):
+    """A guild and the roles that its new members get."""
+
+    guild_id: PositiveInt
+    # Any integers: an ID that names no role is skipped at the join.
+    role_ids: Annotated[tuple[int, ...], Field(min_length=1)]
+
+
+class Config(Model):
+    """``plugins/AutoRole/config.yaml``; the bundled ``config.yaml`` lists no guilds.
+
+    The core config's ``plugins`` list enables the plugin; an ``enabled`` key here only warns.
+    """
+
+    guilds: tuple[GuildRoles, ...]  # required
+
+    def roles_by_guild(self) -> dict[int, tuple[int, ...]]:
+        """Map each guild ID to its role IDs; a guild listed twice keeps its last entry."""
+        return {entry.guild_id: entry.role_ids for entry in self.guilds}

xincord/plugins/auto_role/config.yaml

@@ -0,0 +1,9 @@
+# AutoRole: list it under `plugins` in the core config.yaml to enable it. The bot then needs the
+# Server Members intent, allowed for it in the Discord developer portal.
+
+# Members who join one of these guilds get its roles. In each guild, the bot needs the Manage Roles
+# permission, and its highest role must be above these roles.
+# Example:
+#   - guild_id: 111111111111111111
+#     role_ids: [222222222222222222, 333333333333333333]
+guilds: []

xincord/plugins/bot_info/__init__.py

@@ -0,0 +1,31 @@
+"""BotInfo: ``/bot-info`` shows the bot's guild and member counts and a link to its source code."""
+
+from typing import TYPE_CHECKING
+
+import discord
+
+from xincord.core.templates import Templates
+
+from .cog import BotInfo
+from .config import Config
+
+if TYPE_CHECKING:
+    from xincord.core.bot import Bot
+
+DEPENDS: tuple[str, ...] = ()
+SOFT_DEPENDS: tuple[str, ...] = ()
+# discord.py keeps each guild's member count current from member join and leave events, which need
+# the privileged members intent.
+INTENTS = discord.Intents(members=True)
+# Replies use the user's locale and fall back to this one.
+DEFAULT_LOCALE = "zh-TW"
+
+
+async def setup(bot: Bot) -> None:
+    """Load the config, the lang files and the templates, then add the cog and its command."""
+    context = bot.plugin_context(__name__)
+    lang = context.lang(DEFAULT_LOCALE)
+    cog = BotInfo(context.config(Config), lang, Templates.load(lang))
+    await bot.add_cog(cog)
+    # A global command; discord.py removes it when the plugin unloads.
+    bot.tree.add_command(cog.command())

xincord/plugins/bot_info/cog.py

@@ -0,0 +1,84 @@
+"""The /bot-info command and its reply."""
+
+from typing import TYPE_CHECKING, Any, Protocol
+
+import discord
+from discord import app_commands
+from discord.ext import commands
+
+from xincord.core.placeholders import global_values
+from xincord.core.templates import render_message
+
+if TYPE_CHECKING:
+    from collections.abc import Collection
+
+    from xincord.core.i18n import Lang
+    from xincord.core.templates import Templates
+
+    from .config import Config
+
+
+class Counted(Protocol):
+    """A guild as the counts see it; ``discord.Guild`` is one."""
+
+    @property
+    def member_count(self) -> int | None:
+        """The guild's member count, or None when Discord has not sent it."""
+        ...
+
+
+class BotInfo(commands.Cog):
+    """The plugin's state and handlers; ``setup`` registers them."""
+
+    def __init__(self, config: Config, lang: Lang, templates: Templates) -> None:
+        """Keep what ``setup`` loaded."""
+        self.config = config
+        self.lang = lang
+        self.templates = templates
+
+    def command(self) -> app_commands.Command[Any, ..., None]:
+        """Build the global ``/bot-info``, localized from ``register.yaml``.
+
+        The command is usable in guilds and in the bot's DMs, and installed with guilds.
+        discord.py sends no contexts or install types unless they are set, which would leave them
+        to Discord, so the command sets them.
+        """
+        lang = self.lang
+        command: app_commands.Command[Any, ..., None] = app_commands.Command(
+            name=lang.command("bot-info", "bot-info.name"),
+            description=lang.command("show about the bot data", "bot-info.description"),
+            callback=self.bot_info,
+            allowed_contexts=app_commands.AppCommandContext(
+                guild=True, dm_channel=True, private_channel=False
+            ),
+            allowed_installs=app_commands.AppInstallationType(guild=True, user=False),
+            extras={"global": True},  # a global command
+        )
+        return command
+
+    async def bot_info(self, interaction: discord.Interaction) -> None:
+        """Turn the deferred response into the ``bot-info`` embed, with the counts as they are now.
+
+        The counts belong to this render only, not to placeholders that every plugin shares.
+        """
+        guild_count, member_count = counts(interaction.client.guilds)
+        values = global_values(interaction.client) | {
+            "guild_counts": str(guild_count),
+            "member_counts": str(member_count),
+            "source_url": self.config.source_url,
+        }
+        message = self.templates.message("bot-info", interaction.locale.value)
+        reply = render_message(message, values)
+        # The command tree deferred the response ephemerally.
+        await interaction.edit_original_response(
+            content=reply.content, embeds=reply.embeds, view=reply.view
+        )
+
+
+def counts(guilds: Collection[Counted]) -> tuple[int, int]:
+    """Return the number of ``guilds`` and the sum of their member counts.
+
+    A user in several guilds counts once per guild, and bots count. An unknown member
+    count (a guild unavailable since the bot connected) adds nothing.
+    """
+    return len(guilds), sum(guild.member_count or 0 for guild in guilds)

xincord/plugins/bot_info/config.py

@@ -0,0 +1,25 @@
+"""The plugin's ``config.yaml``."""
+
+from typing import Annotated
+
+from pydantic import StringConstraints
+
+from xincord.core.config import Model
+
+SOURCE_URL = "https://github.com/xinshoutw/xincord"  # the default source link: this repository
+# Discord's limit for a link button's URL, the strictest place a template can put the link.
+URL_MAX = 512
+
+# Checked when the plugin loads, so that a typo disables it with an error that names the key
+# instead of showing a broken link or making Discord refuse the reply.
+SourceUrl = Annotated[str, StringConstraints(pattern=r"^https?://\S+$", max_length=URL_MAX)]
+
+
+class Config(Model):
+    """``plugins/BotInfo/config.yaml``; the bundled ``config.yaml`` holds the same defaults.
+
+    The core config's ``plugins`` list enables the plugin; an ``enabled`` key here only warns.
+    """
+
+    # The link to the bot's source code that /bot-info shows (decision C3, AGPL section 13).
+    source_url: SourceUrl = SOURCE_URL

xincord/plugins/bot_info/config.yaml

@@ -0,0 +1,8 @@
+# BotInfo: list it under `plugins` in the core config.yaml to enable it. The bot then needs the
+# Server Members intent, allowed for it in the Discord developer portal, to keep the member count
+# of /bot-info up to date.
+
+# The link to the bot's source code that /bot-info shows (an http or https URL). The AGPL (section
+# 13) asks whoever runs a modified bot to offer its users the source of that version: point this
+# at it.
+source_url: "https://github.com/xinshoutw/xincord"

xincord/plugins/bot_info/lang/en-US/message/bot-info.yaml

@@ -0,0 +1,20 @@
+embeds:
+  - author:
+      name: "Info Query"
+      icon_url: "https://i.imgur.com/a7z4ch2.png"
+    title:
+      text: "☛ ORDERLY BOT's INFORMATION"
+    footer:
+      text: "❖ ORDERLY SERVER ❖"
+
+    fields:
+      - name: "Server Counts"
+        value: "%guild_counts%"
+
+      - name: "Member Counts"
+        value: "%member_counts%"
+
+      - name: "Source Code"
+        value: "%source_url%"
+
+    color_code: "#00FFFF"

xincord/plugins/bot_info/lang/en-US/register.yaml

@@ -0,0 +1,3 @@
+bot-info:
+  name: "bot-info"
+  description: "show about this Bot"

xincord/plugins/bot_info/lang/zh-TW/message/bot-info.yaml

@@ -0,0 +1,20 @@
+embeds:
+  - author:
+      name: "狀態查詢"
+      icon_url: "https://i.imgur.com/a7z4ch2.png"
+    title:
+      text: "☛ 序之徒的資訊"
+    footer:
+      text: "❖ ORDERLY SERVER ❖"
+
+    fields:
+      - name: "伺服器總數"
+        value: "%guild_counts%"
+
+      - name: "成員總數"
+        value: "%member_counts%"
+
+      - name: "原始碼"
+        value: "%source_url%"
+
+    color_code: "#00FFFF"

xincord/plugins/bot_info/lang/zh-TW/register.yaml

@@ -0,0 +1,3 @@
+bot-info:
+  name: "機器人資訊"
+  description: "顯示有關機器人的資訊"

xincord/plugins/calculator/__init__.py

@@ -0,0 +1,31 @@
+"""Calculator: ``/basic-calculate`` evaluates a formula exactly and posts the result."""
+
+from typing import TYPE_CHECKING
+
+import discord
+
+from xincord.core.templates import Templates
+
+from .cog import Calculator
+
+if TYPE_CHECKING:
+    from xincord.core.bot import Bot
+
+DEPENDS: tuple[str, ...] = ()
+SOFT_DEPENDS: tuple[str, ...] = ()
+INTENTS = discord.Intents.none()
+# Replies use the user's locale and fall back to this one.
+DEFAULT_LOCALE = "zh-TW"
+
+
+async def setup(bot: Bot) -> None:
+    """Load the lang files and the templates, then add the cog and its command.
+
+    The plugin has no config.
+    """
+    context = bot.plugin_context(__name__)
+    lang = context.lang(DEFAULT_LOCALE)
+    cog = Calculator(lang, Templates.load(lang))
+    await bot.add_cog(cog)
+    # A guild command; discord.py removes it when the plugin unloads.
+    bot.tree.add_command(cog.command())