pydis_core 10.3.0__tar.gz

pydis_core-10.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Python Discord
+
+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.

pydis_core-10.3.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.1
+Name: pydis_core
+Version: 10.3.0
+Summary: PyDis core provides core functionality and utility to the bots of the Python Discord community.
+Home-page: https://pythondiscord.com/
+License: MIT
+Keywords: bot,discord,discord.py
+Author: Python Discord
+Author-email: info@pythondiscord.com
+Requires-Python: >=3.10.dev0,<3.12.dev0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Provides-Extra: async-rediscache
+Requires-Dist: aiodns (==3.0.0)
+Requires-Dist: async-rediscache[fakeredis] (==1.0.0rc2) ; extra == "async-rediscache"
+Requires-Dist: discord.py (==2.3.2)
+Requires-Dist: pydantic (>=1.7.4,<3.0.0)
+Requires-Dist: statsd (==4.0.1)
+Project-URL: Documentation, https://bot-core.pythondiscord.com/
+Project-URL: Repository, https://github.com/python-discord/bot-core
+Description-Content-Type: text/markdown
+
+# bot-core ![Version]
+
+[Version]: https://img.shields.io/github/v/tag/python-discord/bot-core?label=latest&logo=version
+

pydis_core-10.3.0/README.md

@@ -0,0 +1,3 @@
+# bot-core ![Version]
+
+[Version]: https://img.shields.io/github/v/tag/python-discord/bot-core?label=latest&logo=version

pydis_core-10.3.0/pydis_core/__init__.py

@@ -0,0 +1,15 @@
+"""Useful utilities and tools for Discord bot development."""
+
+from pydis_core import async_stats, exts, site_api, utils
+from pydis_core._bot import BotBase, StartupError
+
+__all__ = [
+    async_stats,
+    BotBase,
+    exts,
+    utils,
+    site_api,
+    StartupError,
+]
+
+__all__ = [module.__name__ for module in __all__]

pydis_core-10.3.0/pydis_core/_bot.py

@@ -0,0 +1,314 @@
+import asyncio
+import socket
+import types
+import warnings
+from contextlib import suppress
+
+import aiohttp
+import discord
+from discord.ext import commands
+
+from pydis_core.async_stats import AsyncStatsClient
+from pydis_core.site_api import APIClient
+from pydis_core.utils import scheduling
+from pydis_core.utils._extensions import walk_extensions
+from pydis_core.utils.logging import get_logger
+
+try:
+    from async_rediscache import RedisSession
+    REDIS_AVAILABLE = True
+except ImportError:
+    RedisSession = object
+    REDIS_AVAILABLE = False
+
+log = get_logger()
+
+
+class StartupError(Exception):
+    """Exception class for startup errors."""
+
+    def __init__(self, base: Exception):
+        super().__init__()
+        self.exception = base
+
+
+class BotBase(commands.Bot):
+    """A sub-class that implements many common features that Python Discord bots use."""
+
+    def __init__(
+        self,
+        *args,
+        guild_id: int,
+        allowed_roles: list,
+        http_session: aiohttp.ClientSession,
+        redis_session: RedisSession | None = None,
+        api_client: APIClient | None = None,
+        statsd_url: str | None = None,
+        **kwargs,
+    ):
+        """
+        Initialise the base bot instance.
+
+        Args:
+            guild_id: The ID of the guild used for :func:`wait_until_guild_available`.
+            allowed_roles: A list of role IDs that the bot is allowed to mention.
+            http_session (aiohttp.ClientSession): The session to use for the bot.
+            redis_session: The `async_rediscache.RedisSession`_ to use for the bot.
+            api_client: The :obj:`pydis_core.site_api.APIClient` instance to use for the bot.
+            statsd_url: The URL of the statsd server to use for the bot. If not given,
+                a dummy statsd client will be created.
+
+        .. _async_rediscache.RedisSession: https://github.com/SebastiaanZ/async-rediscache#creating-a-redissession
+        """
+        super().__init__(
+            *args,
+            allowed_roles=allowed_roles,
+            **kwargs,
+        )
+
+        self.guild_id = guild_id
+        self.http_session = http_session
+        self.api_client = api_client
+        self.statsd_url = statsd_url
+
+        if redis_session and not REDIS_AVAILABLE:
+            warnings.warn("redis_session kwarg passed, but async-rediscache not installed!", stacklevel=2)
+        elif redis_session:
+            self.redis_session = redis_session
+
+        self._resolver: aiohttp.AsyncResolver | None = None
+        self._connector: aiohttp.TCPConnector | None = None
+
+        self._statsd_timerhandle: asyncio.TimerHandle | None = None
+        self._guild_available: asyncio.Event | None = None
+        self._extension_loading_task: asyncio.Task | None = None
+
+        self.stats: AsyncStatsClient | None = None
+
+        self.all_extensions: frozenset[str] | None = None
+
+    def _connect_statsd(
+        self,
+        statsd_url: str,
+        loop: asyncio.AbstractEventLoop,
+        retry_after: int = 2,
+        attempt: int = 1
+    ) -> None:
+        """Callback used to retry a connection to statsd if it should fail."""
+        if attempt >= 8:
+            log.error(
+                "Reached 8 attempts trying to reconnect AsyncStatsClient to %s. "
+                "Aborting and leaving the dummy statsd client in place.",
+                statsd_url,
+            )
+            return
+
+        try:
+            self.stats = AsyncStatsClient(loop, statsd_url, 8125, prefix="bot")
+        except socket.gaierror:
+            log.warning(f"Statsd client failed to connect (Attempt(s): {attempt})")
+            # Use a fallback strategy for retrying, up to 8 times.
+            self._statsd_timerhandle = loop.call_later(
+                retry_after,
+                self._connect_statsd,
+                statsd_url,
+                retry_after * 2,
+                attempt + 1
+            )
+
+    async def _load_extensions(self, module: types.ModuleType) -> None:
+        """Load all the extensions within the given module and save them to ``self.all_extensions``."""
+        log.info("Waiting for guild %d to be available before loading extensions.", self.guild_id)
+
+        await self.wait_until_guild_available()
+        log.info("Loading extensions...")
+        self.all_extensions = walk_extensions(module)
+
+        for extension in self.all_extensions:
+            scheduling.create_task(self.load_extension(extension))
+
+    async def _sync_app_commands(self) -> None:
+        """Sync global & guild specific application commands after extensions are loaded."""
+        await self._extension_loading_task
+        await self.tree.sync()
+        await self.tree.sync(guild=discord.Object(self.guild_id))
+
+    async def load_extensions(self, module: types.ModuleType, sync_app_commands: bool = True) -> None:
+        """
+        Load all the extensions within the given ``module`` and save them to ``self.all_extensions``.
+
+        Args:
+            sync_app_commands: Whether to sync app commands after all extensions are loaded.
+        """
+        self._extension_loading_task = scheduling.create_task(self._load_extensions(module))
+        if sync_app_commands:
+            scheduling.create_task(self._sync_app_commands())
+
+    def _add_root_aliases(self, command: commands.Command) -> None:
+        """Recursively add root aliases for ``command`` and any of its subcommands."""
+        if isinstance(command, commands.Group):
+            for subcommand in command.commands:
+                self._add_root_aliases(subcommand)
+
+        for alias in getattr(command, "root_aliases", ()):
+            if alias in self.all_commands:
+                raise commands.CommandRegistrationError(alias, alias_conflict=True)
+
+            self.all_commands[alias] = command
+
+    def _remove_root_aliases(self, command: commands.Command) -> None:
+        """Recursively remove root aliases for ``command`` and any of its subcommands."""
+        if isinstance(command, commands.Group):
+            for subcommand in command.commands:
+                self._remove_root_aliases(subcommand)
+
+        for alias in getattr(command, "root_aliases", ()):
+            self.all_commands.pop(alias, None)
+
+    async def add_cog(self, cog: commands.Cog) -> None:
+        """Add the given ``cog`` to the bot and log the operation."""
+        await super().add_cog(cog)
+        log.info(f"Cog loaded: {cog.qualified_name}")
+
+    def add_command(self, command: commands.Command) -> None:
+        """Add ``command`` as normal and then add its root aliases to the bot."""
+        super().add_command(command)
+        self._add_root_aliases(command)
+
+    def remove_command(self, name: str) -> commands.Command | None:
+        """
+        Remove a command/alias as normal and then remove its root aliases from the bot.
+
+        Individual root aliases cannot be removed by this function.
+        To remove them, either remove the entire command or manually edit `bot.all_commands`.
+        """
+        command = super().remove_command(name)
+        if command is None:
+            # Even if it's a root alias, there's no way to get the Bot instance to remove the alias.
+            return None
+
+        self._remove_root_aliases(command)
+        return command
+
+    def clear(self) -> None:
+        """Not implemented! Re-instantiate the bot instead of attempting to re-use a closed one."""
+        raise NotImplementedError("Re-using a Bot object after closing it is not supported.")
+
+    async def on_guild_unavailable(self, guild: discord.Guild) -> None:
+        """Clear the internal guild available event when self.guild_id becomes unavailable."""
+        if guild.id != self.guild_id:
+            return
+
+        self._guild_available.clear()
+
+    async def on_guild_available(self, guild: discord.Guild) -> None:
+        """
+        Set the internal guild available event when self.guild_id becomes available.
+
+        If the cache appears to still be empty (no members, no channels, or no roles), the event
+        will not be set and `guild_available_but_cache_empty` event will be emitted.
+        """
+        if guild.id != self.guild_id:
+            return
+
+        if not guild.roles or not guild.members or not guild.channels:
+            msg = "Guild available event was dispatched but the cache appears to still be empty!"
+            await self.log_to_dev_log(msg)
+            return
+
+        self._guild_available.set()
+
+    async def log_to_dev_log(self, message: str) -> None:
+        """Log the given message to #dev-log."""
+        ...
+
+    async def wait_until_guild_available(self) -> None:
+        """
+        Wait until the guild that matches the ``guild_id`` given at init is available (and the cache is ready).
+
+        The on_ready event is inadequate because it only waits 2 seconds for a GUILD_CREATE
+        gateway event before giving up and thus not populating the cache for unavailable guilds.
+        """
+        await self._guild_available.wait()
+
+    async def process_commands(self, message: discord.Message) -> None:
+        """
+        Overwrite default Discord.py behaviour to process commands only after ensuring extensions are loaded.
+
+        This extension check is only relevant for clients that make use of :obj:`pydis_core.BotBase.load_extensions`.
+        """
+        if self._extension_loading_task:
+            await self._extension_loading_task
+        await super().process_commands(message)
+
+    async def setup_hook(self) -> None:
+        """
+        An async init to startup generic services.
+
+        Connects to statsd, and calls
+        :func:`AsyncStatsClient.create_socket <pydis_core.async_stats.AsyncStatsClient.create_socket>`
+        and :func:`ping_services`.
+        """
+        loop = asyncio.get_running_loop()
+
+        self._guild_available = asyncio.Event()
+
+        self._resolver = aiohttp.AsyncResolver()
+        self._connector = aiohttp.TCPConnector(
+            resolver=self._resolver,
+            family=socket.AF_INET,
+        )
+        self.http.connector = self._connector
+
+        if getattr(self, "redis_session", False) and not self.redis_session.valid:
+            # If the RedisSession was somehow closed, we try to reconnect it
+            # here. Normally, this shouldn't happen.
+            await self.redis_session.connect(ping=True)
+
+        # Create dummy stats client first, in case `statsd_url` is unreachable or None
+        self.stats = AsyncStatsClient(loop, "127.0.0.1")
+        if self.statsd_url:
+            self._connect_statsd(self.statsd_url, loop)
+
+        await self.stats.create_socket()
+
+        try:
+            await self.ping_services()
+        except Exception as e:
+            raise StartupError(e)
+
+    async def ping_services(self) -> None:
+        """Ping all required services on setup to ensure they are up before starting."""
+        ...
+
+    async def close(self) -> None:
+        """Close the Discord connection, and the aiohttp session, connector, statsd client, and resolver."""
+        # Done before super().close() to allow tasks finish before the HTTP session closes.
+        for ext in list(self.extensions):
+            with suppress(Exception):
+                await self.unload_extension(ext)
+
+        for cog in list(self.cogs):
+            with suppress(Exception):
+                await self.remove_cog(cog)
+
+        # Now actually do full close of bot
+        await super().close()
+
+        if self.api_client:
+            await self.api_client.close()
+
+        if self.http_session:
+            await self.http_session.close()
+
+        if self._connector:
+            await self._connector.close()
+
+        if self._resolver:
+            await self._resolver.close()
+
+        if getattr(self.stats, "_transport", False):
+            self.stats._transport.close()
+
+        if self._statsd_timerhandle:
+            self._statsd_timerhandle.cancel()

pydis_core-10.3.0/pydis_core/async_stats.py

@@ -0,0 +1,56 @@
+"""An async transport method for statsd communication."""
+
+import asyncio
+import socket
+
+from statsd.client.base import StatsClientBase
+
+from pydis_core.utils import scheduling
+
+
+class AsyncStatsClient(StatsClientBase):
+    """An async implementation of :obj:`statsd.client.base.StatsClientBase` that supports async stat communication."""
+
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop,
+        host: str = "localhost",
+        port: int = 8125,
+        prefix: str | None = None
+    ):
+        """
+        Create a new :obj:`AsyncStatsClient`.
+
+        Args:
+            loop (asyncio.AbstractEventLoop): The event loop to use when creating the
+                :obj:`asyncio.loop.create_datagram_endpoint`.
+            host: The host to connect to.
+            port: The port to connect to.
+            prefix: The prefix to use for all stats.
+        """
+        _, _, _, _, addr = socket.getaddrinfo(
+            host, port, socket.AF_INET, socket.SOCK_DGRAM
+        )[0]
+        self._addr = addr
+        self._prefix = prefix
+        self._loop = loop
+        self._transport: asyncio.DatagramTransport | None = None
+
+    async def create_socket(self) -> None:
+        """Use :obj:`asyncio.loop.create_datagram_endpoint` from the loop given on init to create a socket."""
+        self._transport, _ = await self._loop.create_datagram_endpoint(
+            asyncio.DatagramProtocol,
+            family=socket.AF_INET,
+            remote_addr=self._addr
+        )
+
+    def _send(self, data: str) -> None:
+        """Start an async task to send data to statsd."""
+        scheduling.create_task(self._async_send(data), event_loop=self._loop)
+
+    async def _async_send(self, data: str) -> None:
+        """Send data to the statsd server using the async transport."""
+        self._transport.sendto(data.encode("ascii"), self._addr)
+
+
+__all__ = ["AsyncStatsClient"]

pydis_core-10.3.0/pydis_core/exts/__init__.py

@@ -0,0 +1,4 @@
+"""Reusable Discord cogs."""
+__all__ = []
+
+__all__ = [module.__name__ for module in __all__]

pydis_core-10.3.0/pydis_core/site_api.py

@@ -0,0 +1,156 @@
+"""An API wrapper around the Site API."""
+
+import asyncio
+from urllib.parse import quote as quote_url
+
+import aiohttp
+
+from pydis_core.utils.logging import get_logger
+
+log = get_logger(__name__)
+
+
+class ResponseCodeError(ValueError):
+    """Raised in :meth:`APIClient.request` when a non-OK HTTP response is received."""
+
+    def __init__(
+        self,
+        response: aiohttp.ClientResponse,
+        response_json: dict | None = None,
+        response_text: str | None = None
+    ):
+        """
+        Initialize a new :obj:`ResponseCodeError` instance.
+
+        Args:
+            response (:obj:`aiohttp.ClientResponse`): The response object from the request.
+            response_json: The JSON response returned from the request, if any.
+            response_text: The text of the request, if any.
+        """
+        self.status = response.status
+        self.response_json = response_json or {}
+        self.response_text = response_text
+        self.response = response
+
+    def __str__(self):
+        """Return a string representation of the error."""
+        response = self.response_json or self.response_text
+        return f"Status: {self.status} Response: {response}"
+
+
+class APIClient:
+    """A wrapper for the Django Site API."""
+
+    session: aiohttp.ClientSession | None = None
+    loop: asyncio.AbstractEventLoop = None
+
+    def __init__(self, site_api_url: str, site_api_token: str, **session_kwargs):
+        """
+        Initialize a new :obj:`APIClient` instance.
+
+        Args:
+            site_api_url: The URL of the site API.
+            site_api_token: The token to use for authentication.
+            session_kwargs: Keyword arguments to pass to the :obj:`aiohttp.ClientSession` constructor.
+        """
+        self.site_api_url = site_api_url
+
+        auth_headers = {
+            "Authorization": f"Token {site_api_token}"
+        }
+
+        if "headers" in session_kwargs:
+            session_kwargs["headers"].update(auth_headers)
+        else:
+            session_kwargs["headers"] = auth_headers
+
+        # aiohttp will complain if APIClient gets instantiated outside a coroutine. Thankfully, we
+        # don't and shouldn't need to do that, so we can avoid scheduling a task to create it.
+        self.session = aiohttp.ClientSession(**session_kwargs)
+
+    def _url_for(self, endpoint: str) -> str:
+        return f"{self.site_api_url}/{quote_url(endpoint)}"
+
+    async def close(self) -> None:
+        """Close the aiohttp session."""
+        await self.session.close()
+
+    @staticmethod
+    async def maybe_raise_for_status(response: aiohttp.ClientResponse, should_raise: bool) -> None:
+        """
+        Raise :exc:`ResponseCodeError` for non-OK response if an exception should be raised.
+
+        Args:
+            response (:obj:`aiohttp.ClientResponse`): The response to check.
+            should_raise: Whether or not to raise an exception.
+
+        Raises:
+            :exc:`ResponseCodeError`:
+                If the response is not OK and ``should_raise`` is True.
+        """
+        if should_raise and response.status >= 400:
+            try:
+                response_json = await response.json()
+                raise ResponseCodeError(response=response, response_json=response_json)
+            except aiohttp.ContentTypeError:
+                response_text = await response.text()
+                raise ResponseCodeError(response=response, response_text=response_text)
+
+    async def request(self, method: str, endpoint: str, *, raise_for_status: bool = True, **kwargs) -> dict:
+        """
+        Send an HTTP request to the site API and return the JSON response.
+
+        Args:
+            method: The HTTP method to use.
+            endpoint: The endpoint to send the request to.
+            raise_for_status: Whether or not to raise an exception if the response is not OK.
+            **kwargs: Any extra keyword arguments to pass to :func:`aiohttp.request`.
+
+        Returns:
+            The JSON response the API returns.
+
+        Raises:
+            :exc:`ResponseCodeError`:
+                If the response is not OK and ``raise_for_status`` is True.
+        """
+        async with self.session.request(method.upper(), self._url_for(endpoint), **kwargs) as resp:
+            await self.maybe_raise_for_status(resp, raise_for_status)
+            return await resp.json()
+
+    async def get(self, endpoint: str, *, raise_for_status: bool = True, **kwargs) -> dict:
+        """Equivalent to :meth:`APIClient.request` with GET passed as the method."""
+        return await self.request("GET", endpoint, raise_for_status=raise_for_status, **kwargs)
+
+    async def patch(self, endpoint: str, *, raise_for_status: bool = True, **kwargs) -> dict:
+        """Equivalent to :meth:`APIClient.request` with PATCH passed as the method."""
+        return await self.request("PATCH", endpoint, raise_for_status=raise_for_status, **kwargs)
+
+    async def post(self, endpoint: str, *, raise_for_status: bool = True, **kwargs) -> dict:
+        """Equivalent to :meth:`APIClient.request` with POST passed as the method."""
+        return await self.request("POST", endpoint, raise_for_status=raise_for_status, **kwargs)
+
+    async def put(self, endpoint: str, *, raise_for_status: bool = True, **kwargs) -> dict:
+        """Equivalent to :meth:`APIClient.request` with PUT passed as the method."""
+        return await self.request("PUT", endpoint, raise_for_status=raise_for_status, **kwargs)
+
+    async def delete(self, endpoint: str, *, raise_for_status: bool = True, **kwargs) -> dict | None:
+        """
+        Send a DELETE request to the site API and return the JSON response.
+
+        Args:
+            endpoint: The endpoint to send the request to.
+            raise_for_status: Whether or not to raise an exception if the response is not OK.
+            **kwargs: Any extra keyword arguments to pass to :func:`aiohttp.request`.
+
+        Returns:
+            The JSON response the API returns, or None if the response is 204 No Content.
+        """
+        async with self.session.delete(self._url_for(endpoint), **kwargs) as resp:
+            if resp.status == 204:
+                return None
+
+            await self.maybe_raise_for_status(resp, raise_for_status)
+            return await resp.json()
+
+
+__all__ = ["APIClient", "ResponseCodeError"]

pydis_core-10.3.0/pydis_core/utils/__init__.py

@@ -0,0 +1,54 @@
+"""Useful utilities and tools for Discord bot development."""
+
+from pydis_core.utils import (
+    _monkey_patches,
+    caching,
+    channel,
+    commands,
+    cooldown,
+    error_handling,
+    function,
+    interactions,
+    logging,
+    members,
+    paste_service,
+    regex,
+    scheduling,
+)
+from pydis_core.utils._extensions import unqualify
+
+
+def apply_monkey_patches() -> None:
+    """
+    Applies all common monkey patches for our bots.
+
+    Patches :obj:`discord.ext.commands.Command` and :obj:`discord.ext.commands.Group` to support root aliases.
+        A ``root_aliases`` keyword argument is added to these two objects, which is a sequence of alias names
+        that will act as top-level groups rather than being aliases of the command's group.
+
+        It's stored as an attribute also named ``root_aliases``
+
+    Patches discord's internal ``send_typing`` method so that it ignores 403 errors from Discord.
+        When under heavy load Discord has added a CloudFlare worker to this route, which causes 403 errors to be thrown.
+    """
+    _monkey_patches._apply_monkey_patches()
+
+
+__all__ = [
+    apply_monkey_patches,
+    caching,
+    channel,
+    commands,
+    cooldown,
+    error_handling,
+    function,
+    interactions,
+    logging,
+    members,
+    paste_service,
+    regex,
+    scheduling,
+    unqualify,
+]
+
+__all__ = [module.__name__ for module in __all__]