Replaced error TypeError: TelegramEventObserver.__call__() got an unexpected keyword argument '<name>' with a more understandable (#1114)

* Explain why keyword filters is not supported

* Added changelog

CHANGES/1114.misc.rst

@@ -0,0 +1,2 @@
+Replaced error :code:`TypeError: TelegramEventObserver.__call__() got an unexpected keyword argument '<name>'`
+with a more understandable one for developers and with a link to the documentation.

aiogram/dispatcher/event/telegram.py

@@ -3,11 +3,11 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional
 
 from aiogram.dispatcher.middlewares.manager import MiddlewareManager
-
-from ...filters.base import Filter
-from ...types import TelegramObject
 from .bases import REJECTED, UNHANDLED, MiddlewareType, SkipHandler
 from .handler import CallbackType, FilterObject, HandlerObject
+from ...exceptions import UnsupportedKeywordArgument
+from ...filters.base import Filter
+from ...types import TelegramObject
 
 if TYPE_CHECKING:
     from aiogram.dispatcher.router import Router
@@ -58,10 +58,21 @@ class TelegramEventObserver:
         callback: CallbackType,
         *filters: CallbackType,
         flags: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
     ) -> CallbackType:
         """
         Register event handler
         """
+        if kwargs:
+            raise UnsupportedKeywordArgument(
+                "Passing any additional keyword arguments to the registrar method "
+                "is not supported.\n"
+                "This error may be caused when you are trying to register filters like in 2.x "
+                "version of this framework, if it's true just look at correspoding "
+                "documentation pages.\n"
+                f"Please remove the {set(kwargs.keys())} arguments from this call.\n"
+            )
+
         if flags is None:
             flags = {}
 
@@ -118,13 +129,14 @@ class TelegramEventObserver:
         self,
         *filters: CallbackType,
         flags: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
     ) -> Callable[[CallbackType], CallbackType]:
         """
         Decorator for registering event handlers
         """
 
         def wrapper(callback: CallbackType) -> CallbackType:
-            self.register(callback, *filters, flags=flags)
+            self.register(callback, *filters, flags=flags, **kwargs)
             return callback
 
         return wrapper

aiogram/exceptions.py

@@ -2,6 +2,7 @@ from typing import Any, Optional
 
 from aiogram.methods import TelegramMethod
 from aiogram.methods.base import TelegramType
+from aiogram.utils.link import docs_url
 
 
 class AiogramError(Exception):
@@ -28,6 +29,10 @@ class CallbackAnswerException(AiogramError):
     pass
 
 
+class UnsupportedKeywordArgument(DetailedAiogramError):
+    url = docs_url("migration_2_to_3.html", fragment_="filtering-events")
+
+
 class TelegramAPIError(DetailedAiogramError):
     def __init__(
         self,

tests/test_dispatcher/test_event/test_telegram.py

@@ -9,9 +9,11 @@ from aiogram.dispatcher.event.bases import REJECTED, SkipHandler
 from aiogram.dispatcher.event.handler import HandlerObject
 from aiogram.dispatcher.event.telegram import TelegramEventObserver
 from aiogram.dispatcher.router import Router
+from aiogram.exceptions import UnsupportedKeywordArgument
 from aiogram.filters import Filter
 from aiogram.types import Chat, Message, User
 
+
 # TODO: Test middlewares in routers tree
 
 
@@ -82,6 +84,11 @@ class TestTelegramEventObserver:
         assert f2 in callbacks
         assert MyFilter1(test="PASS") in callbacks
 
+    def test_keyword_filters_is_not_supported(self):
+        router = Router()
+        with pytest.raises(UnsupportedKeywordArgument):
+            router.message.register(lambda e: True, commands=["test"])
+
     def test_register_decorator(self):
         router = Router()
         observer = router.message