Updated dependencies, added CLAUDE.md, added more ruff rulesets, fixed beanie statements using 'and' instead of proper joins

Author: Taaku18

.pre-commit-config.yaml

@@ -27,12 +27,12 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/pycqa/isort
-    rev: 7.0.0
+    rev: 8.0.1
     hooks:
       - id: isort
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.10
+    rev: v0.15.6
     hooks:
       - id: ruff-check
         args: [ --fix ]

CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Modmail v5 is a complete rewrite of the Modmail Discord bot (alpha/WIP). It manages support tickets between users and Discord server staff via DM-based modmail. Requires Python 3.14+, uses `uv` as the package manager.
+
+## Commands
+
+### Setup
+```bash
+# Install with SQLite backend
+uv sync --locked --compile-bytecode --no-default-groups --extra speed --extra sqlite
+
+# Install with MongoDB backend
+uv sync --locked --compile-bytecode --no-default-groups --extra speed --extra mongodb
+```
+
+### Run
+```bash
+uv run python start.py
+# or
+python -m modmail
+```
+
+### Lint & Format
+```bash
+uv run pre-commit run --all-files   # Run all pre-commit hooks
+uv run ruff check --fix modmail tests
+uv run ruff format modmail tests
+uv run isort modmail tests
+```
+
+### Type Check
+```bash
+uv run pyright
+```
+
+### Tests (Not Yet Implemented)
+```bash
+uv run pytest
+uv run pytest tests/test_utils.py   # Run a single test file
+uv run pytest -k "test_name"        # Run a specific test
+uv run pytest --cov=modmail --cov-report html
+uv run tox                          # Run all tox environments (lint, type, py3.14)
+```
+
+## Architecture
+
+### Module Structure
+```
+modmail/
+├── backends/          # Database abstraction layer
+│   ├── common/        # Abstract base class & shared models
+│   ├── mongodb/       # Beanie ODM implementation
+│   └── sql/           # SQLAlchemy + aiosqlite implementation
+├── config/            # Pydantic config models + YAML loader
+├── core/              # Bot class, translator, permissions
+│   └── internals/     # Cog base, command types, UI views, embeds
+├── cogs/
+│   ├── modmail/       # Core ticket logic (commands + listeners)
+│   └── utility/       # about, status, profile commands
+└── locales/           # Fluent FTL translation files (en, de)
+```
+
+### Key Design Patterns
+
+**Database Abstraction**: `DBClientBase` in `backends/common/client_base.py` defines the interface. Both SQL and MongoDB clients implement this. The active backend is selected via `config.yaml`.
+
+**Ticket Flow**:
+1. User DMs bot → `cogs/modmail/listeners/dm_receive.py` intercepts
+2. `core/internals/staff_guild.py` creates a channel or forum thread in the staff server
+3. Database stores ticket state via the active backend client
+4. Staff reply via commands in `cogs/modmail/commands/`
+
+**Localization**: Fluent FTL format (`locales/en/main.ftl`). All user-facing strings go through `core/translator.py`. Commands use `LazyHybridCommand` (`core/internals/command.py`) supporting both prefix and slash commands.
+
+**Cog Base**: Custom `Cog` class in `core/internals/cog.py` with enhanced send/reply helpers and access to the translator.
+
+### Config
+Copy `config.yaml.example` → `config.yaml`. Required fields: `bot.token`, `bot.staff_server_id`, `log_url`. Database backend is configured under the `database` key.
+
+### Testing Notes
+Tests are currently undergoing a rewrite. Pyright runs in strict mode but excludes the `tests/` directory. Pre-commit hooks enforce isort + ruff formatting on every commit.

modmail/__init__.py

@@ -86,8 +86,10 @@ def run_bot() -> NoReturn:
     modmail_text_lines += [""]
     modmail_text_lines += [f"Starting at {current_time_text}"]
     modmail_text_lines += [
-        f"Version: {__version__} | Python: {python_version} | "
-        f"Language{'s' if len(CONFIG.allowed_locales) != 1 else ''}: {enabled_locales}"
+        (
+            f"Version: {__version__} | Python: {python_version} | "
+            f"Language{'s' if len(CONFIG.allowed_locales) != 1 else ''}: {enabled_locales}"
+        )
     ]
     modmail_text_lines += [""]
     modmail_text_width = len(max(modmail_text_lines, key=len)) + 10

modmail/backends/common/models/activity_model.py

@@ -5,11 +5,15 @@
 
 from __future__ import annotations
 
-from discord import app_commands
+from typing import TYPE_CHECKING
+
 from pydantic import BaseModel, ConfigDict
 
 from modmail.enum import ActivityType
 
+if TYPE_CHECKING:
+    from discord import app_commands
+
 __all__ = ["ActivityModel"]
 
 
@@ -38,7 +42,7 @@ def __str__(self) -> str:
             case ActivityType.playing:
                 return f"Playing {self.name}"
             case ActivityType.streaming:
-                return f"Streaming {self.name} ({self.url if self.url else 'No URL'})"
+                return f"Streaming {self.name} ({self.url or 'No URL'})"
             case ActivityType.listening:
                 return f"Listening to {self.name}"
             case ActivityType.watching:

modmail/backends/common/models/ticket_user_model.py

@@ -7,9 +7,13 @@
 
 from __future__ import annotations
 
-import discord
+from typing import TYPE_CHECKING
+
 from pydantic import BaseModel, ConfigDict
 
+if TYPE_CHECKING:
+    import discord
+
 __all__ = ["TicketUserModel"]
 
 

modmail/backends/mongodb/client.py

@@ -384,8 +384,8 @@ async def delete_profile(self, profile_id: int) -> None:
         """
         # Delete the profile from the database.
         await MongoDBProfileDocument.find(
-            MongoDBProfileDocument.bot_id == self._config.bot.bot_id
-            and MongoDBProfileDocument.profile_id == profile_id
+            MongoDBProfileDocument.bot_id == self._config.bot.bot_id,
+            MongoDBProfileDocument.profile_id == profile_id,
         ).delete()
 
         # Delete the profile from cache.
@@ -402,8 +402,8 @@ async def sync_open_tickets(self) -> None:
         open_tickets_cache = MultiKeyCollection[MongoDBTicketDocument]("key", "channel_id")
 
         async for ticket_document in MongoDBTicketDocument.find(
-            MongoDBTicketDocument.bot_id == self._config.bot.bot_id
-            and MongoDBTicketDocument.status == TicketStatus.open,
+            MongoDBTicketDocument.bot_id == self._config.bot.bot_id,
+            MongoDBTicketDocument.status == TicketStatus.open,
             fetch_links=True,
         ):
             open_tickets_cache.add(ticket_document, key=ticket_document.key, channel_id=ticket_document.channel_id)
@@ -448,7 +448,7 @@ async def create_ticket(self, ticket: TicketModel) -> None:
             if ticket_document.channel_id == ticket.channel_id:
                 raise TicketCreationError("Ticket with this channel ID already exists.")
             if any(
-                new_recipient.user_id == cast(MongoDBTicketUserDocument, old_recipient).id
+                new_recipient.user_id == cast("MongoDBTicketUserDocument", old_recipient).id
                 for old_recipient in ticket_document.recipients
                 for new_recipient in ticket.recipients
             ):
@@ -476,7 +476,8 @@ async def set_ticket_log_channel_message_id(self, ticket_key: str, message_id: i
             TicketNotFoundError: If the ticket is not found.
         """
         ticket_document = await MongoDBTicketDocument.find_one(
-            MongoDBTicketDocument.bot_id == self._config.bot.bot_id and MongoDBTicketDocument.key == ticket_key
+            MongoDBTicketDocument.bot_id == self._config.bot.bot_id,
+            MongoDBTicketDocument.key == ticket_key,
         )
         if ticket_document is None:
             raise TicketNotFoundError(f"Ticket with key {ticket_key} not found.")
@@ -509,8 +510,8 @@ async def get_ticket_by_channel(self, channel_id: int, *, only_open: bool = True
             return None
 
         ticket_document = await MongoDBTicketDocument.find_one(
-            MongoDBTicketDocument.bot_id == self._config.bot.bot_id
-            and MongoDBTicketDocument.channel_id == channel_id,
+            MongoDBTicketDocument.bot_id == self._config.bot.bot_id,
+            MongoDBTicketDocument.channel_id == channel_id,
             fetch_links=True,
         )
         if ticket_document is not None:
@@ -535,7 +536,8 @@ async def get_ticket_by_key(self, key: str, *, only_open: bool = True) -> Ticket
             return None
 
         ticket_document = await MongoDBTicketDocument.find_one(
-            MongoDBTicketDocument.bot_id == self._config.bot.bot_id and MongoDBTicketDocument.key == key,
+            MongoDBTicketDocument.bot_id == self._config.bot.bot_id,
+            MongoDBTicketDocument.key == key,
             fetch_links=True,
         )
         if ticket_document is not None:
@@ -555,7 +557,7 @@ async def get_ticket_by_recipient(self, recipient_id: int) -> TicketModel | None
             await ticket_document.fetch_all_links()
             # Check if the recipient ID is in the ticket's recipients.
             if any(
-                cast(MongoDBTicketUserDocument, recipient).id == recipient_id
+                cast("MongoDBTicketUserDocument", recipient).id == recipient_id
                 for recipient in ticket_document.recipients
             ):
                 return await ticket_document.get_model()
@@ -584,18 +586,18 @@ async def get_all_tickets_by_recipient(
         Returns:
             A list of ticket models associated with the recipient or the count of tickets if count is True.
         """
-        query = (
-            MongoDBTicketDocument.bot_id == self._config.bot.bot_id
-            and cast(MongoDBTicketUserDocument, MongoDBTicketDocument.recipients).id == recipient_id
-        )
+        conditions = [
+            MongoDBTicketDocument.bot_id == self._config.bot.bot_id,
+            cast("MongoDBTicketUserDocument", MongoDBTicketDocument.recipients).id == recipient_id,
+        ]
 
         if only_closed:
-            query = query and MongoDBTicketDocument.status != TicketStatus.open
+            conditions.append(MongoDBTicketDocument.status != TicketStatus.open)
 
         if count:
-            return await MongoDBTicketDocument.find(query, fetch_links=True).count()
+            return await MongoDBTicketDocument.find(*conditions, fetch_links=True).count()
 
-        ticket_documents = await MongoDBTicketDocument.find(query, fetch_links=True).to_list()
+        ticket_documents = await MongoDBTicketDocument.find(*conditions, fetch_links=True).to_list()
         return await asyncio.gather(*[ticket_document.get_model() for ticket_document in ticket_documents])
 
     async def save_message(self, ticket_message: TicketMessageModel) -> None:
@@ -645,7 +647,8 @@ async def close_ticket(
 
         # Find the ticket document
         ticket_document = await MongoDBTicketDocument.find_one(
-            MongoDBTicketDocument.bot_id == self._config.bot.bot_id and MongoDBTicketDocument.key == ticket_key,
+            MongoDBTicketDocument.bot_id == self._config.bot.bot_id,
+            MongoDBTicketDocument.key == ticket_key,
             fetch_links=True,
         )
 

modmail/backends/mongodb/convert.py

@@ -7,19 +7,22 @@
 
 from __future__ import annotations
 
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
 from beanie import Link, UpdateResponse
-from beanie.odm.queries.update import UpdateOne
 
-from ..common import TicketDMMessageModel, TicketMessageModel, TicketModel, TicketUserModel
 from .models import (
     MongoDBTicketDMMessageModel,
     MongoDBTicketDocument,
     MongoDBTicketMessageDocument,
     MongoDBTicketUserDocument,
 )
 
+if TYPE_CHECKING:
+    from beanie.odm.queries.update import UpdateOne
+
+    from ..common import TicketDMMessageModel, TicketMessageModel, TicketModel, TicketUserModel
+
 __all__ = [
     "get_or_create_ticket_user",
     "ticket_dm_message_model_to_document",
@@ -54,9 +57,9 @@ async def get_or_create_ticket_user(ticket_user: TicketUserModel) -> MongoDBTick
     """
     ticket_user_document = ticket_user_model_to_document(ticket_user)
     return cast(
-        MongoDBTicketUserDocument,
+        "MongoDBTicketUserDocument",
         await cast(
-            UpdateOne,
+            "UpdateOne",
             MongoDBTicketUserDocument.find_one(MongoDBTicketUserDocument.id == ticket_user.user_id).upsert(
                 {"$set": ticket_user_document.model_dump(exclude={"id"})},
                 on_insert=ticket_user_document,
@@ -86,19 +89,19 @@ async def ticket_model_to_document(ticket: TicketModel) -> MongoDBTicketDocument
     for recipient in ticket.recipients:
         if recipient.user_id not in ticket_users_cache:
             ticket_users_cache[recipient.user_id] = cast(
-                Link[MongoDBTicketUserDocument], await get_or_create_ticket_user(recipient)
+                "Link[MongoDBTicketUserDocument]", await get_or_create_ticket_user(recipient)
             )
         recipients.append(ticket_users_cache[recipient.user_id])
 
     if ticket.created_by.user_id not in ticket_users_cache:
         ticket_users_cache[ticket.created_by.user_id] = cast(
-            Link[MongoDBTicketUserDocument], await get_or_create_ticket_user(ticket.created_by)
+            "Link[MongoDBTicketUserDocument]", await get_or_create_ticket_user(ticket.created_by)
         )
     created_by = ticket_users_cache[ticket.created_by.user_id]
 
     if ticket.closed_by and ticket.closed_by.user_id not in ticket_users_cache:
         ticket_users_cache[ticket.closed_by.user_id] = cast(
-            Link[MongoDBTicketUserDocument], await get_or_create_ticket_user(ticket.closed_by)
+            "Link[MongoDBTicketUserDocument]", await get_or_create_ticket_user(ticket.closed_by)
         )
     closed_by = ticket_users_cache[ticket.closed_by.user_id] if ticket.closed_by else None
 
@@ -140,7 +143,7 @@ async def ticket_dm_message_model_to_document(
     # Ensure the recipient user exists in DB
     if ticket_dm_message.recipient.user_id not in ticket_users_cache:
         ticket_users_cache[ticket_dm_message.recipient.user_id] = cast(
-            Link[MongoDBTicketUserDocument], await get_or_create_ticket_user(ticket_dm_message.recipient)
+            "Link[MongoDBTicketUserDocument]", await get_or_create_ticket_user(ticket_dm_message.recipient)
         )
 
     return MongoDBTicketDMMessageModel(
@@ -162,27 +165,26 @@ async def ticket_message_model_to_document(ticket_message: TicketMessageModel) -
     """
     ticket_users_cache: dict[int, Link[MongoDBTicketUserDocument]] = {}
 
-    dm_messages: list[MongoDBTicketDMMessageModel] = []
-    for dm_message in ticket_message.dm_messages:
-        dm_messages.append(
-            await ticket_dm_message_model_to_document(dm_message, ticket_users_cache=ticket_users_cache),
-        )
+    dm_messages: list[MongoDBTicketDMMessageModel] = [
+        await ticket_dm_message_model_to_document(dm_message, ticket_users_cache=ticket_users_cache)
+        for dm_message in ticket_message.dm_messages
+    ]
 
     if ticket_message.author.user_id not in ticket_users_cache:
         ticket_users_cache[ticket_message.author.user_id] = cast(
-            Link[MongoDBTicketUserDocument], await get_or_create_ticket_user(ticket_message.author)
+            "Link[MongoDBTicketUserDocument]", await get_or_create_ticket_user(ticket_message.author)
         )
     author = ticket_users_cache[ticket_message.author.user_id]
 
     if ticket_message.edited_by and ticket_message.edited_by.user_id not in ticket_users_cache:
         ticket_users_cache[ticket_message.edited_by.user_id] = cast(
-            Link[MongoDBTicketUserDocument], await get_or_create_ticket_user(ticket_message.edited_by)
+            "Link[MongoDBTicketUserDocument]", await get_or_create_ticket_user(ticket_message.edited_by)
         )
     edited_by = ticket_message.edited_by and ticket_users_cache[ticket_message.edited_by.user_id]
 
     if ticket_message.deleted_by and ticket_message.deleted_by.user_id not in ticket_users_cache:
         ticket_users_cache[ticket_message.deleted_by.user_id] = cast(
-            Link[MongoDBTicketUserDocument], await get_or_create_ticket_user(ticket_message.deleted_by)
+            "Link[MongoDBTicketUserDocument]", await get_or_create_ticket_user(ticket_message.deleted_by)
         )
     deleted_by = ticket_message.deleted_by and ticket_users_cache[ticket_message.deleted_by.user_id]
 

modmail/backends/mongodb/models/ticket_model.py

@@ -86,10 +86,10 @@ async def get_model(self) -> TicketModel:
         await self.fetch_all_links()  # Make sure all links are fetched
 
         recipients = await asyncio.gather(*[
-            cast(MongoDBTicketUserDocument, recipient).get_model() for recipient in self.recipients
+            cast("MongoDBTicketUserDocument", recipient).get_model() for recipient in self.recipients
         ])
-        created_by = await cast(MongoDBTicketUserDocument, self.created_by).get_model()
-        closed_by = await cast(MongoDBTicketUserDocument, self.closed_by).get_model() if self.closed_by else None
+        created_by = await cast("MongoDBTicketUserDocument", self.created_by).get_model()
+        closed_by = await cast("MongoDBTicketUserDocument", self.closed_by).get_model() if self.closed_by else None
 
         return TicketModel(
             bot_id=self.bot_id,

modmail/backends/sql/client.py

@@ -9,7 +9,6 @@
 import asyncio
 import datetime
 import logging
-from collections.abc import Awaitable
 from concurrent.futures import ProcessPoolExecutor
 from typing import TYPE_CHECKING, Any, Literal, overload
 
@@ -41,6 +40,8 @@
 )
 
 if TYPE_CHECKING:
+    from collections.abc import Awaitable
+
     from sqlalchemy.engine.interfaces import DBAPIConnection
     from sqlalchemy.pool import ConnectionPoolEntry