Refactor mention system for cleaner API and better encapsulation

- Add explicit kwargs to mention() decorator (pattern, username, scope)
- Pass context as explicit parameter instead of mutating kwargs
- Create MentionEvent.from_event() generator to encapsulate all mention
  processing logic (parsing, filtering, context creation)
- Rename MentionContext to MentionEvent for clarity
- Simplify router code from ~30 lines to 4 lines per wrapper

This creates a much cleaner API where the mention decorator's wrappers
simply iterate over MentionEvent instances yielded by the generator.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: joshuadavidthomas

src/django_github_app/mentions.py

@@ -133,11 +133,53 @@ def from_event(cls, event: sansio.Event) -> Comment:
 
 
 @dataclass
-class MentionContext:
+class MentionEvent:
     comment: Comment
     triggered_by: Mention
     scope: MentionScope | None
 
+    @classmethod
+    def from_event(
+        cls,
+        event: sansio.Event,
+        *,
+        username: str | re.Pattern[str] | None = None,
+        pattern: str | re.Pattern[str] | None = None,
+        scope: MentionScope | None = None,
+    ):
+        """Generate MentionEvent instances from a GitHub event.
+
+        Yields MentionEvent for each mention that matches the given criteria.
+        """
+        # Check scope match first
+        event_scope = MentionScope.from_event(event)
+        if scope is not None and event_scope != scope:
+            return
+
+        # Parse mentions
+        mentions = parse_mentions_for_username(event, username)
+        if not mentions:
+            return
+
+        # Create comment
+        comment = Comment.from_event(event)
+        comment.mentions = mentions
+
+        # Yield contexts for matching mentions
+        for mention in mentions:
+            # Check pattern match if specified
+            if pattern is not None:
+                match = check_pattern_match(mention.text, pattern)
+                if not match:
+                    continue
+                mention.match = match
+
+            yield cls(
+                comment=comment,
+                triggered_by=mention,
+                scope=event_scope,
+            )
+
 
 CODE_BLOCK_PATTERN = re.compile(r"```[\s\S]*?```", re.MULTILINE)
 INLINE_CODE_PATTERN = re.compile(r"`[^`]+`")

src/django_github_app/routing.py

@@ -17,11 +17,8 @@
 from ._typing import override
 from .github import AsyncGitHubAPI
 from .github import SyncGitHubAPI
-from .mentions import Comment
-from .mentions import MentionContext
+from .mentions import MentionEvent
 from .mentions import MentionScope
-from .mentions import check_pattern_match
-from .mentions import parse_mentions_for_username
 
 AsyncCallback = Callable[..., Awaitable[None]]
 SyncCallback = Callable[..., None]
@@ -73,71 +70,32 @@ def decorator(func: CB) -> CB:
 
         return decorator
 
-    def mention(self, **kwargs: Any) -> Callable[[CB], CB]:
+    def mention(
+        self,
+        *,
+        pattern: str | re.Pattern[str] | None = None,
+        username: str | re.Pattern[str] | None = None,
+        scope: MentionScope | None = None,
+        **kwargs: Any,
+    ) -> Callable[[CB], CB]:
         def decorator(func: CB) -> CB:
-            pattern = kwargs.pop("pattern", None)
-            username = kwargs.pop("username", None)
-            scope = kwargs.pop("scope", None)
-
             @wraps(func)
             async def async_wrapper(
                 event: sansio.Event, gh: AsyncGitHubAPI, *args: Any, **kwargs: Any
             ) -> None:
-                event_scope = MentionScope.from_event(event)
-                if scope is not None and event_scope != scope:
-                    return
-
-                mentions = parse_mentions_for_username(event, username)
-                if not mentions:
-                    return
-
-                comment = Comment.from_event(event)
-                comment.mentions = mentions
-
-                for mention in mentions:
-                    if pattern is not None:
-                        match = check_pattern_match(mention.text, pattern)
-                        if not match:
-                            continue
-                        mention.match = match
-
-                    kwargs["context"] = MentionContext(
-                        comment=comment,
-                        triggered_by=mention,
-                        scope=event_scope,
-                    )
-
-                    await func(event, gh, *args, **kwargs)  # type: ignore[func-returns-value]
+                for context in MentionEvent.from_event(
+                    event, username=username, pattern=pattern, scope=scope
+                ):
+                    await func(event, gh, *args, context=context, **kwargs)  # type: ignore[func-returns-value]
 
             @wraps(func)
             def sync_wrapper(
                 event: sansio.Event, gh: SyncGitHubAPI, *args: Any, **kwargs: Any
             ) -> None:
-                event_scope = MentionScope.from_event(event)
-                if scope is not None and event_scope != scope:
-                    return
-
-                mentions = parse_mentions_for_username(event, username)
-                if not mentions:
-                    return
-
-                comment = Comment.from_event(event)
-                comment.mentions = mentions
-
-                for mention in mentions:
-                    if pattern is not None:
-                        match = check_pattern_match(mention.text, pattern)
-                        if not match:
-                            continue
-                        mention.match = match
-
-                    kwargs["context"] = MentionContext(
-                        comment=comment,
-                        triggered_by=mention,
-                        scope=event_scope,
-                    )
-
-                    func(event, gh, *args, **kwargs)
+                for context in MentionEvent.from_event(
+                    event, username=username, pattern=pattern, scope=scope
+                ):
+                    func(event, gh, *args, context=context, **kwargs)
 
             wrapper: MentionHandler
             if iscoroutinefunction(func):

tests/test_routing.py

@@ -582,10 +582,10 @@ def deploy_handler(event, *args, **kwargs):
 
 
 class TestUpdatedMentionContext:
-    """Test the updated MentionContext structure with comment and triggered_by fields."""
+    """Test the updated MentionEvent structure with comment and triggered_by fields."""
 
     def test_mention_context_structure(self, test_router, get_mock_github_api_sync):
-        """Test that MentionContext has the new structure with comment and triggered_by."""
+        """Test that MentionEvent has the new structure with comment and triggered_by."""
         handler_called = False
         captured_mention = None
 
@@ -725,7 +725,7 @@ def general_handler(event, *args, **kwargs):
     async def test_async_mention_context_structure(
         self, test_router, get_mock_github_api
     ):
-        """Test async handlers get the same updated MentionContext structure."""
+        """Test async handlers get the same updated MentionEvent structure."""
         handler_called = False
         captured_mention = None