Refactored quotes module into layered architecture with typed domain objects and comprehensive tests.

owlbot/builtin_modules/quotes/__init__.py

@@ -17,167 +17,48 @@
 Allows moderators to store quotes and anyone to recall random quotes.
 """
 
-from datetime import UTC, datetime
+from owlbot.api import ModuleContext, on_setup, on_teardown
 
-from aiohttp import web
-
-from owlbot.api import (
-    CommandContext,
-    ModuleContext,
-    RouteContext,
-    on_command,
-    on_route,
-    on_setup,
+# Re-export decorated handlers so the module loader discovers them.
+from .commands import (
+    addquote_command,
+    deletequote_command,
+    listquotes_command,
+    quote_command,
 )
+from .manager import QuoteManager
+from .repository import QuoteRepository
+from .routes import quotes_list_page
+
+__all__ = [
+    "addquote_command",
+    "deletequote_command",
+    "listquotes_command",
+    "quote_command",
+    "quotes_list_page",
+    "setup",
+    "teardown",
+]
 
 
 @on_setup
 async def setup(ctx: ModuleContext) -> None:
     """Initialize the quotes module.
 
-    Creates the database schema.
+    Creates the database schema and instantiates the QuoteManager.
 
     :param ctx: Module context with config, storage, and other services.
     """
-    await ctx.storage.execute("""
-        CREATE TABLE IF NOT EXISTS quotes (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            text TEXT NOT NULL,
-            added_by TEXT NOT NULL,
-            created_at TEXT NOT NULL
-        )
-    """)
-
-    count = await ctx.storage.fetch_value("SELECT COUNT(*) FROM quotes")
-    ctx.logger.info(f"Loaded {count} quote(s) from database.")
+    repo = QuoteRepository(ctx.storage)
+    await repo.setup()
+    manager = QuoteManager(ctx, repo)
+    ctx.state["manager"] = manager
 
 
-@on_route("/list", methods=["GET"])
-async def quotes_list_page(ctx: RouteContext) -> web.Response:
-    """Serve an HTML page listing all quotes in a table.
+@on_teardown
+async def teardown(ctx: ModuleContext) -> None:
+    """Clean up the quotes module.
 
-    Columns: #, Quote, Added By, Date Added.
-    Accessible at /owlbot/quotes/list.
-
-    :param ctx: The route context.
-    :return: HTML response with the quotes list table.
+    :param ctx: Module context.
     """
-    rows = await ctx.storage.fetch_all(
-        "SELECT id, text, added_by, created_at FROM quotes ORDER BY id"
-    )
-
-    quotes = [
-        {
-            "id": row["id"],
-            "text": row["text"],
-            "added_by": row["added_by"],
-            "date": datetime.fromisoformat(row["created_at"]).strftime("%Y-%m-%d"),
-        }
-        for row in rows
-    ]
-
-    page = ctx.templates.render("list.html", quotes=quotes)
-    return web.Response(text=page, content_type="text/html")
-
-
-@on_command("quote", aliases=["q"])
-async def quote_command(ctx: CommandContext) -> None:
-    """Display a quote. Random if no argument, specific if an ID is given.
-
-    :param ctx: The command context.
-    """
-    args = ctx.args_list
-
-    if not args:
-        row = await ctx.storage.fetch_one(
-            "SELECT id, text FROM quotes ORDER BY RANDOM() LIMIT 1"
-        )
-
-        if not row:
-            await ctx.owncast_client.send_message("No quotes have been added yet.")
-            return
-
-        await ctx.owncast_client.send_message(f'"{row["text"]}" (#{row["id"]})')
-        return
-
-    try:
-        quote_id = int(args[0])
-    except ValueError:
-        await ctx.owncast_client.send_message("Usage: !quote [id]")
-        return
-
-    row = await ctx.storage.fetch_one(
-        "SELECT id, text, added_by, created_at FROM quotes WHERE id = ?", (quote_id,)
-    )
-    if not row:
-        await ctx.owncast_client.send_message(f"Quote #{quote_id} not found.")
-        return
-
-    created_at = datetime.fromisoformat(row["created_at"])
-    date_str = created_at.strftime("%Y-%m-%d")
-
-    await ctx.owncast_client.send_message(
-        f'Quote #{row["id"]}: "{row["text"]}" '
-        f"- Added by {row['added_by']} on {date_str}"
-    )
-
-
-@on_command("addquote", requires_moderator=True)
-async def addquote_command(ctx: CommandContext) -> None:
-    """Add a new quote to the database. Moderator only.
-
-    :param ctx: The command context.
-    """
-    quote_text = ctx.args.strip()
-    if not quote_text:
-        await ctx.owncast_client.send_message("Usage: !addquote <quote text>")
-        return
-
-    now = datetime.now(UTC).isoformat()
-    cursor = await ctx.storage.execute(
-        "INSERT INTO quotes (text, added_by, created_at) VALUES (?, ?, ?)",
-        (quote_text, ctx.user.display_name, now),
-    )
-
-    ctx.logger.info(f"Quote #{cursor.lastrowid} added by {ctx.user.display_name}.")
-    await ctx.owncast_client.send_message(f"Quote #{cursor.lastrowid} added.")
-
-
-@on_command("deletequote", aliases=["delquote"], requires_moderator=True)
-async def deletequote_command(ctx: CommandContext) -> None:
-    """Delete a quote by ID. Moderator only.
-
-    :param ctx: The command context.
-    """
-    args = ctx.args_list
-    if not args:
-        await ctx.owncast_client.send_message("Usage: !deletequote <id>")
-        return
-
-    try:
-        quote_id = int(args[0])
-    except ValueError:
-        await ctx.owncast_client.send_message("Usage: !deletequote <id>")
-        return
-
-    existing = await ctx.storage.fetch_one(
-        "SELECT id FROM quotes WHERE id = ?", (quote_id,)
-    )
-    if not existing:
-        await ctx.owncast_client.send_message(f"Quote #{quote_id} not found.")
-        return
-
-    await ctx.storage.execute("DELETE FROM quotes WHERE id = ?", (quote_id,))
-
-    ctx.logger.info(f"Quote #{quote_id} deleted by {ctx.user.display_name}.")
-    await ctx.owncast_client.send_message(f"Quote #{quote_id} deleted.")
-
-
-@on_command("listquotes", cooldown=15)
-async def listquotes_command(ctx: CommandContext) -> None:
-    """Send the URL to the quotes list web page.
-
-    :param ctx: The command context.
-    """
-    url = ctx.routes.url_for("/list")
-    await ctx.owncast_client.send_message(f"Quotes: {url}")
+    ctx.state["manager"] = None

owlbot/builtin_modules/quotes/commands.py

@@ -0,0 +1,112 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Chat commands for managing quotes."""
+
+from owlbot.api import CommandContext, on_command
+
+from .manager import get_manager
+from .types import QuoteNotFoundError
+
+
+@on_command("quote", aliases=["q"])
+async def quote_command(ctx: CommandContext) -> None:
+    """Display a quote. Random if no argument, specific if an ID is given.
+
+    Usage: !quote [id]
+
+    :param ctx: The command context.
+    """
+    args = ctx.args_list
+
+    if not args:
+        quote = await get_manager(ctx.module).get_random_quote()
+        if quote is None:
+            await ctx.owncast_client.send_message("No quotes have been added yet.")
+            return
+        await ctx.owncast_client.send_message(f'"{quote.text}" (#{quote.id})')
+        return
+
+    try:
+        quote_id = int(args[0])
+    except ValueError:
+        await ctx.owncast_client.send_message("Usage: !quote [id]")
+        return
+
+    try:
+        quote = await get_manager(ctx.module).get_quote(quote_id)
+    except QuoteNotFoundError as e:
+        await ctx.owncast_client.send_message(f"Quote #{e.quote_id} not found.")
+        return
+
+    await ctx.owncast_client.send_message(
+        f'Quote #{quote.id}: "{quote.text}" - Added by {quote.added_by} on {quote.date}'
+    )
+
+
+@on_command("addquote", requires_moderator=True)
+async def addquote_command(ctx: CommandContext) -> None:
+    """Add a new quote to the database. Moderator only.
+
+    Usage: !addquote <quote text>
+
+    :param ctx: The command context.
+    """
+    quote_text = ctx.args.strip()
+    if not quote_text:
+        await ctx.owncast_client.send_message("Usage: !addquote <quote text>")
+        return
+
+    quote = await get_manager(ctx.module).add_quote(quote_text, ctx.user.display_name)
+    await ctx.owncast_client.send_message(f"Quote #{quote.id} added.")
+
+
+@on_command("deletequote", aliases=["delquote"], requires_moderator=True)
+async def deletequote_command(ctx: CommandContext) -> None:
+    """Delete a quote by ID. Moderator only.
+
+    Usage: !deletequote <id>
+
+    :param ctx: The command context.
+    """
+    args = ctx.args_list
+    if not args:
+        await ctx.owncast_client.send_message("Usage: !deletequote <id>")
+        return
+
+    try:
+        quote_id = int(args[0])
+    except ValueError:
+        await ctx.owncast_client.send_message("Usage: !deletequote <id>")
+        return
+
+    try:
+        await get_manager(ctx.module).delete_quote(quote_id)
+    except QuoteNotFoundError as e:
+        await ctx.owncast_client.send_message(f"Quote #{e.quote_id} not found.")
+        return
+
+    await ctx.owncast_client.send_message(f"Quote #{quote_id} deleted.")
+
+
+@on_command("listquotes", cooldown=15)
+async def listquotes_command(ctx: CommandContext) -> None:
+    """Send the URL to the quotes list web page.
+
+    Usage: !listquotes
+
+    :param ctx: The command context.
+    """
+    url = ctx.routes.url_for("/list")
+    await ctx.owncast_client.send_message(f"Quotes: {url}")

owlbot/builtin_modules/quotes/manager.py

@@ -0,0 +1,96 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Business logic coordinator for the quotes module."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from owlbot.api import ModuleContext
+
+    from .repository import QuoteRepository
+    from .types import Quote
+
+
+class QuoteManager:
+    """Coordinates between the repository and handlers."""
+
+    def __init__(self, ctx: ModuleContext, repo: QuoteRepository) -> None:
+        """Initialize the manager.
+
+        :param ctx: The module context.
+        :param repo: The quote repository for persistence.
+        """
+        self._ctx = ctx
+        self._repo = repo
+
+    async def add_quote(self, text: str, added_by: str) -> Quote:
+        """Add a new quote.
+
+        :param text: The quote text.
+        :param added_by: Display name of the user who added the quote.
+        :return: Snapshot of the newly created quote.
+        """
+        quote = await self._repo.create(text, added_by)
+        self._ctx.logger.info("Quote #%d added by %s.", quote.id, added_by)
+        return quote
+
+    async def delete_quote(self, quote_id: int) -> Quote:
+        """Delete a quote by ID.
+
+        :param quote_id: Database ID of the quote.
+        :return: Snapshot of the deleted quote.
+        :raises QuoteNotFoundError: If no quote matches the ID.
+        """
+        quote = await self._repo.delete(quote_id)
+        self._ctx.logger.info("Quote #%d deleted.", quote_id)
+        return quote
+
+    async def get_quote(self, quote_id: int) -> Quote:
+        """Fetch a quote by ID.
+
+        :param quote_id: Database ID of the quote.
+        :return: The matching Quote.
+        :raises QuoteNotFoundError: If no quote matches the ID.
+        """
+        return await self._repo.get(quote_id)
+
+    async def get_random_quote(self) -> Quote | None:
+        """Fetch a random quote.
+
+        :return: A random Quote, or None if no quotes exist.
+        """
+        return await self._repo.get_random()
+
+    async def list_quotes(self) -> list[Quote]:
+        """Return all quotes ordered by ID.
+
+        :return: List of Quote snapshots.
+        """
+        return await self._repo.list_all()
+
+
+def get_manager(ctx: ModuleContext) -> QuoteManager:
+    """Return the QuoteManager stored in the module context's state.
+
+    :param ctx: The module context.
+    :return: The active QuoteManager.
+    :raises RuntimeError: If the manager has not been initialized.
+    """
+    manager = ctx.state.get("manager")
+    if not isinstance(manager, QuoteManager):
+        raise RuntimeError("QuoteManager is not initialized.")
+    return manager

owlbot/builtin_modules/quotes/repository.py

@@ -0,0 +1,112 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Persistence layer for quote records."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from .types import Quote, QuoteNotFoundError
+
+if TYPE_CHECKING:
+    from owlbot.api.storage import ModuleStorage
+
+
+class QuoteRepository:
+    """Handles all database operations for quote records."""
+
+    def __init__(self, storage: ModuleStorage) -> None:
+        """Initialize with a module storage instance.
+
+        :param storage: The module's storage backend.
+        """
+        self._storage = storage
+
+    async def setup(self) -> None:
+        """Create the quotes table if it does not exist."""
+        await self._storage.execute("""
+            CREATE TABLE IF NOT EXISTS quotes (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                text TEXT NOT NULL,
+                added_by TEXT NOT NULL,
+                created_at TEXT NOT NULL
+            )
+        """)
+
+    async def create(self, text: str, added_by: str) -> Quote:
+        """Insert a new quote and return its snapshot.
+
+        :param text: The quote text.
+        :param added_by: Display name of the user who added the quote.
+        :return: Snapshot of the newly created quote.
+        """
+        now = datetime.now(UTC).isoformat()
+        row = await self._storage.fetch_one(
+            "INSERT INTO quotes (text, added_by, created_at) "
+            "VALUES (?, ?, ?) RETURNING *",
+            (text, added_by, now),
+        )
+        if row is None:
+            raise RuntimeError("INSERT RETURNING did not produce a row")
+        return Quote.from_row(row)
+
+    async def get(self, quote_id: int) -> Quote:
+        """Fetch a quote by its ID.
+
+        :param quote_id: Database ID of the quote.
+        :return: The matching Quote.
+        :raises QuoteNotFoundError: If no quote matches the ID.
+        """
+        row = await self._storage.fetch_one(
+            "SELECT * FROM quotes WHERE id = ?", (quote_id,)
+        )
+        if row is None:
+            raise QuoteNotFoundError(quote_id)
+        return Quote.from_row(row)
+
+    async def get_random(self) -> Quote | None:
+        """Fetch a random quote.
+
+        :return: A random Quote, or None if the table is empty.
+        """
+        row = await self._storage.fetch_one(
+            "SELECT * FROM quotes ORDER BY RANDOM() LIMIT 1"
+        )
+        if row is None:
+            return None
+        return Quote.from_row(row)
+
+    async def delete(self, quote_id: int) -> Quote:
+        """Delete a quote and return its snapshot.
+
+        :param quote_id: Database ID of the quote.
+        :return: Snapshot of the deleted quote.
+        :raises QuoteNotFoundError: If no quote matches the ID.
+        """
+        row = await self._storage.fetch_one(
+            "DELETE FROM quotes WHERE id = ? RETURNING *", (quote_id,)
+        )
+        if row is None:
+            raise QuoteNotFoundError(quote_id)
+        return Quote.from_row(row)
+
+    async def list_all(self) -> list[Quote]:
+        """Return all quotes ordered by ID.
+
+        :return: List of Quote snapshots.
+        """
+        rows = await self._storage.fetch_all("SELECT * FROM quotes ORDER BY id")
+        return [Quote.from_row(row) for row in rows]

owlbot/builtin_modules/quotes/routes.py

@@ -0,0 +1,33 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""HTTP route handlers for the quotes module."""
+
+from aiohttp import web
+
+from owlbot.api import RouteContext, on_route
+
+from .manager import get_manager
+
+
+@on_route("/list", methods=["GET"])
+async def quotes_list_page(ctx: RouteContext) -> web.Response:
+    """Serve an HTML page listing all quotes in a table.
+
+    :param ctx: The route context.
+    :return: HTML response with the quotes list table.
+    """
+    quotes = await get_manager(ctx.module).list_quotes()
+    page = ctx.templates.render("list.html", quotes=quotes)
+    return web.Response(text=page, content_type="text/html")

owlbot/builtin_modules/quotes/types.py

@@ -0,0 +1,69 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Data containers and domain errors for the quotes module."""
+
+from __future__ import annotations
+
+import dataclasses
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import aiosqlite
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Quote:
+    """Immutable snapshot of a quote record."""
+
+    id: int
+    text: str
+    added_by: str
+    created_at: str
+
+    @property
+    def date(self) -> str:
+        """Return the creation date formatted as YYYY-MM-DD."""
+        return datetime.fromisoformat(self.created_at).strftime("%Y-%m-%d")
+
+    @classmethod
+    def from_row(cls, row: aiosqlite.Row) -> Quote:
+        """Build a Quote from a database row.
+
+        :param row: A row from the quotes table (must include all columns).
+        :return: A Quote snapshot.
+        """
+        return cls(
+            id=row["id"],
+            text=row["text"],
+            added_by=row["added_by"],
+            created_at=row["created_at"],
+        )
+
+
+class QuoteError(Exception):
+    """Base class for quote domain errors."""
+
+
+class QuoteNotFoundError(QuoteError):
+    """No quote matches the given ID."""
+
+    def __init__(self, quote_id: int) -> None:
+        """Initialize with the quote ID that was not found.
+
+        :param quote_id: The ID that was not found.
+        """
+        self.quote_id = quote_id
+        super().__init__(f"quote not found: {quote_id}")