Add dog command with random picture feature (#347)

* Add dog command with random picture feature

* Remove close method

* Add alt text description to dog embed

* Add channel restriction, cooldown, and embed description to dog command

* Remove fixture from tests

* Add pet-appreciation channel

---------

Co-authored-by: Niklas Mertsch <49114330+NMertsch@users.noreply.github.com>

Author: nekeal

prod-config.toml

@@ -27,7 +27,12 @@ pretix_cache_file = "pretix_cache.json"
 # speakers
 "Presenter" = ["Participants", "Onsite Participants", "Speakers"]
 # onsite volunteers
-"On-site Volunteer" = ["Participants", "Onsite Participants", "Volunteers", "Onsite Volunteers"]
+"On-site Volunteer" = [
+    "Participants",
+    "Onsite Participants",
+    "Volunteers",
+    "Onsite Volunteers",
+]
 # beginners' day
 "Beginners’ Day Unconference / Humble Data Access" = ["Beginners Day"]
 
@@ -58,3 +63,12 @@ main_notification_channel_name = "programme-notifications"
 
 [guild_statistics]
 required_role = "Organizers"
+
+[dog]
+cooldown_seconds = 10
+error_messages = [
+    "The dogs are on strike today! Try again later. 🐾🪧",
+    "A wild error appeared! The dog got away... 🐕💨",
+    "Dog API is fetching a stick. Throw it again! 🦴",
+    "404: Dog not found. Have you checked under the couch? 🛋️",
+]

scripts/configure-guild.py

@@ -542,6 +542,10 @@ def verify_permission_roles(self) -> Self:
                         "Please bring found items to the registration desk."
                     ),
                 ),
+                TextChannel(
+                    name="pet-appreciation",
+                    topic="A place to share pictures and stories about your pets!",
+                ),
             ],
             permission_overwrites=[
                 PermissionOverwrite(roles=[ROLE_EVERYONE], deny=["view_channel"]),

src/europython_discord/bot.py

@@ -15,6 +15,8 @@
 
 from europython_discord.cogs.guild_statistics import GuildStatisticsCog, GuildStatisticsConfig
 from europython_discord.cogs.ping import PingCog
+from europython_discord.dog.cog import DogCog
+from europython_discord.dog.config import DogConfig
 from europython_discord.program_notifications.cog import ProgramNotificationsCog
 from europython_discord.program_notifications.config import ProgramNotificationsConfig
 from europython_discord.registration.cog import RegistrationCog
@@ -32,6 +34,7 @@ class Config(BaseModel):
     registration: RegistrationConfig
     program_notifications: ProgramNotificationsConfig
     guild_statistics: GuildStatisticsConfig
+    dog: DogConfig = DogConfig()
 
 
 async def run_bot(config: Config, auth_token: str) -> None:
@@ -44,6 +47,7 @@ async def run_bot(config: Config, auth_token: str) -> None:
 
     async with commands.Bot(intents=intents, command_prefix="$") as bot:
         await bot.add_cog(PingCog(bot))
+        await bot.add_cog(DogCog(bot, config.dog))
         await bot.add_cog(RegistrationCog(bot, config.registration))
         await bot.add_cog(ProgramNotificationsCog(bot, config.program_notifications))
         await bot.add_cog(GuildStatisticsCog(bot, config.guild_statistics))

src/europython_discord/dog/__init__.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import logging
+import random
+import time
+from collections import OrderedDict
+
+import discord
+from discord.ext import commands
+
+from europython_discord.dog.config import DogConfig
+from europython_discord.dog.dogclient import DogClient
+
+_logger = logging.getLogger(__name__)
+
+_MAX_COOLDOWN_TRACKING = 100
+
+
+class DogCog(commands.Cog):
+    def __init__(
+        self,
+        bot: commands.Bot,
+        config: DogConfig,
+        client: DogClient | None = None,
+    ) -> None:
+        self.bot = bot
+        self.config = config
+        self._client = client or DogClient()
+        self._last_used: OrderedDict[int, float] = OrderedDict()
+        _logger.info("Cog 'Dog' has been initialized")
+
+    @commands.hybrid_command(name="dog", description="Get a random dog picture")
+    async def dog_command(self, ctx: commands.Context) -> None:
+        if ctx.channel.name != self.config.channel_name:
+            return
+
+        if self._is_rate_limited(ctx.author.id):
+            return
+
+        if (image_url := await self._client.fetch_random_dog()) is None:
+            message = random.choice(self.config.error_messages)  # noqa: S311
+            await ctx.send(message)
+            return
+
+        embed = discord.Embed()
+        embed.description = "A random dog image"
+        embed.set_image(url=image_url)
+        embed.set_footer(text="Powered by dog.ceo")
+
+        self._update_rate_limit_cache(ctx.author.id)
+        await ctx.send(embed=embed)
+
+    def _is_rate_limited(self, user_id: int) -> bool:
+        last = self._last_used.get(user_id)
+        return bool(last is not None and time.time() - last < self.config.cooldown_seconds)
+
+    def _update_rate_limit_cache(self, user_id: int) -> None:
+        self._last_used[user_id] = time.time()
+        self._last_used.move_to_end(user_id)
+        if len(self._last_used) > _MAX_COOLDOWN_TRACKING:
+            self._last_used.popitem(last=False)

src/europython_discord/dog/cog.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel
+
+
+class DogConfig(BaseModel):
+    channel_name: str = "pet-appreciation"
+    cooldown_seconds: int = 10
+    error_messages: list[str] = ["404: Dog not found. Have you checked under the couch? 🛋️"]

src/europython_discord/dog/config.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import logging
+
+import aiohttp
+
+_logger = logging.getLogger(__name__)
+
+DOG_API_URL = "https://dog.ceo/api/breeds/image/random"
+
+
+class DogClient:
+    def __init__(self) -> None:
+        self._session = aiohttp.ClientSession()
+
+    async def fetch_random_dog(self) -> str | None:
+        try:
+            async with self._session.get(DOG_API_URL) as response:
+                response.raise_for_status()
+                data = await response.json()
+        except Exception:
+            _logger.exception("Failed to fetch dog image")
+            return None
+
+        return data["message"]

src/europython_discord/dog/dogclient.py

@@ -27,7 +27,12 @@ pretix_cache_file = "pretix_cache.json"
 # speakers
 "Presenter" = ["Participants", "Onsite Participants", "Speakers"]
 # onsite volunteers
-"On-site Volunteer" = ["Participants", "Onsite Participants", "Volunteers", "Onsite Volunteers"]
+"On-site Volunteer" = [
+    "Participants",
+    "Onsite Participants",
+    "Volunteers",
+    "Onsite Volunteers",
+]
 # beginners' day
 "Beginners’ Day Unconference / Humble Data Access" = ["Beginners Day"]
 
@@ -59,3 +64,12 @@ fast_mode = true
 
 [guild_statistics]
 required_role = "Organizers"
+
+[dog]
+cooldown_seconds = 10
+error_messages = [
+    "The dogs are on strike today! Try again later. 🐾🪧",
+    "A wild error appeared! The dog got away... 🐕💨",
+    "Dog API is fetching a stick. Throw it again! 🦴",
+    "404: Dog not found. Have you checked under the couch? 🛋️",
+]

test-config.toml

@@ -0,0 +1,71 @@
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from discord.ext import commands
+
+from europython_discord.dog.cog import DogCog
+from europython_discord.dog.config import DogConfig
+from europython_discord.dog.dogclient import DogClient
+
+
+@pytest.fixture
+def config() -> DogConfig:
+    return DogConfig()
+
+
+@pytest.fixture
+def bot() -> MagicMock:
+    return MagicMock(spec=commands.Bot)
+
+
+@pytest.fixture
+def mock_client() -> DogClient:
+    client = MagicMock(spec=DogClient)
+    client.fetch_random_dog.return_value = "https://images.dog.ceo/dog.jpg"
+    return client
+
+
+@pytest.fixture
+def cog(bot: MagicMock, config: DogConfig, mock_client: DogClient) -> DogCog:
+    return DogCog(bot, config, client=mock_client)
+
+
+@pytest.fixture
+def ctx() -> AsyncMock:
+    mock = AsyncMock(spec=commands.Context)
+    mock.channel.name = "pet-appreciation"
+    mock.send = AsyncMock()
+    return mock
+
+
+async def test_dog_command_success(cog: DogCog, ctx: AsyncMock) -> None:
+    await cog.dog_command.callback(cog, ctx)
+
+    ctx.send.assert_awaited_once()
+    embed = ctx.send.call_args.kwargs["embed"]
+    assert embed.image.url == "https://images.dog.ceo/dog.jpg"
+
+
+async def test_dog_command_api_error(cog: DogCog, ctx: AsyncMock, mock_client: DogClient) -> None:
+    mock_client.fetch_random_dog.return_value = None
+
+    await cog.dog_command.callback(cog, ctx)
+
+    ctx.send.assert_awaited_once()
+    text = ctx.send.call_args.args[0]
+
+    assert text in cog.config.error_messages
+
+
+@pytest.mark.parametrize(
+    "channel_name",
+    ["wrong-channel", "general", ""],
+)
+async def test_dog_command_wrong_channel(cog: DogCog, channel_name: str) -> None:
+    ctx = AsyncMock(spec=commands.Context)
+    ctx.channel.name = channel_name
+    ctx.send = AsyncMock()
+
+    await cog.dog_command.callback(cog, ctx)
+
+    ctx.send.assert_not_awaited()