Add Sample Project With Boilerplate

Adds a bare-bones discord.py bot using features from bot-core, to be
used for quickly prototyping and testing out bot-core features.

Signed-off-by: Hassan Abouelela <[email protected]>

4 files changed, 136 insertions, 0 deletions

diff --git a/dev/README.rst b/dev/README.rst
new file mode 100644
index 00000000..b1535962
--- /dev/null
+++ b/dev/README.rst
@@ -0,0 +1,45 @@
+Local Development & Testing
+===========================
+
+To test your features locally, there are a few possible approaches:
+
+1. Install your local copy of botcore into a pre-existing project such as bot
+2. Use the provided template from the :repo-file:`dev/bot <dev/bot>` folder
+
+See below for more info on both approaches.
+
+What's going to be common between them is you'll need to write code to test your feature.
+This might mean adding new commands, modifying existing ones, changing utilities, etc.
+The steps below should provide most of the groundwork you need, but the exact requirements will
+vary by the feature you're working on.
+
+
+Option 1
+--------
+1. Navigate to the project you want to install bot-core in, such as bot or sir-lancebot
+2. Run ``pip install /path/to/botcore`` in the project's environment
+
+   - The path provided to install should be the root directory of this project on your maching.
+     That is, the folder which contains the ``pyproject.toml`` file.
+   - Make sure to install in the correct environment. Most Python Discord projects use
+     poetry, so you can run ``poetry run pip install /path/to/botcore``.
+
+3. You can now use features from your local bot-core changes.
+   To load new changes, run the install command again.
+
+
+Option 2
+--------
+1. Copy the :repo-file:`bot template folder <dev/bot>` to the root of your project.
+   This copy is going to be git-ignored, so you're free to modify it however you like.
+2. Run the project
+
+   - Locally: You can run it on your system using ``python -m bot``
+   - Docker: You can run on docker using ``docker compose up -d bot``.
+
+3. You can now test your changes. You do not need to do anything to reinstall the
+   library if you modify your code.
+
+.. tip::
+   The docker-compose included contains services from our other applications
+   to help you test out certain features. Use them as needed.
diff --git a/dev/bot/__init__.py b/dev/bot/__init__.py
new file mode 100644
index 00000000..71871209
--- /dev/null
+++ b/dev/bot/__init__.py
@@ -0,0 +1,24 @@
+import asyncio
+import logging
+import os
+import sys
+
+import botcore
+
+if os.name == "nt":
+    # Change the event loop policy on Windows to avoid exceptions on exit
+    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+# Some basic logging to get existing loggers to show
+logging.getLogger().addHandler(logging.StreamHandler())
+logging.getLogger().setLevel(logging.DEBUG)
+logging.getLogger("discord").setLevel(logging.ERROR)
+
+
+class Bot(botcore.BotBase):
+    """Sample Bot implementation."""
+
+    async def setup_hook(self) -> None:
+        """Load extensions on startup."""
+        await super().setup_hook()
+        asyncio.create_task(self.load_extensions(sys.modules[__name__]))
diff --git a/dev/bot/__main__.py b/dev/bot/__main__.py
new file mode 100644
index 00000000..00ebdefc
--- /dev/null
+++ b/dev/bot/__main__.py
@@ -0,0 +1,34 @@
+import asyncio
+import os
+
+import aiohttp
+import discord
+import dotenv
+from discord.ext import commands
+
+import botcore
+from . import Bot
+
+dotenv.load_dotenv()
+botcore.utils.apply_monkey_patches()
+
+roles = os.getenv("ALLOWED_ROLES")
+roles = [int(role) for role in roles.split(",")] if roles else []
+
+bot = Bot(
+    guild_id=int(os.getenv("GUILD_ID")),
+    http_session=None,  # type: ignore # We need to instantiate the session in an async context
+    allowed_roles=roles,
+    command_prefix=commands.when_mentioned_or(os.getenv("PREFIX", "!")),
+    intents=discord.Intents.all(),
+    description="Bot-core test bot.",
+)
+
+
+async def main() -> None:
+    """Run the bot."""
+    bot.http_session = aiohttp.ClientSession()
+    async with bot:
+        await bot.start(os.getenv("TOKEN"))
+
+asyncio.run(main())
diff --git a/dev/bot/cog.py b/dev/bot/cog.py
new file mode 100644
index 00000000..7746c54e
--- /dev/null
+++ b/dev/bot/cog.py
@@ -0,0 +1,33 @@
+from discord.ext import commands
+
+from . import Bot
+
+
+class Cog(commands.Cog):
+    """A simple discord.py cog."""
+
+    def __init__(self, _bot: Bot):
+        self.bot = _bot
+
+    @commands.Cog.listener()
+    async def on_ready(self) -> None:
+        """Print a message when the client (re)connects."""
+        print("Client is ready.")
+
+    @commands.command()
+    async def reload(self, ctx: commands.Context) -> None:
+        """Reload all available cogs."""
+        message = await ctx.send(":hourglass_flowing_sand: Reloading")
+        for ext in list(self.bot.extensions):
+            await self.bot.reload_extension(ext)
+        await message.edit(content=":white_check_mark: Done")
+
+    @commands.command()
+    async def ping(self, ctx: commands.Context) -> None:
+        """Test if the bot is online."""
+        await ctx.send("We are live!")
+
+
+async def setup(_bot: Bot) -> None:
+    """Install the cog."""
+    await _bot.add_cog(Cog(_bot))