From 021ae5626fd9fa93b88e442a19589854b2bd6705 Mon Sep 17 00:00:00 2001
From: Alex Root Junior <jroot.junior@gmail.com>
Date: Sun, 5 Feb 2023 16:13:06 +0200
Subject: [PATCH] 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                         |  2 ++
 aiogram/dispatcher/event/telegram.py          | 20 +++++++++++++++----
 aiogram/exceptions.py                         |  5 +++++
 .../test_event/test_telegram.py               |  7 +++++++
 4 files changed, 30 insertions(+), 4 deletions(-)
 create mode 100644 CHANGES/1114.misc.rst

diff --git a/CHANGES/1114.misc.rst b/CHANGES/1114.misc.rst
new file mode 100644
index 00000000..ba1661ae
--- /dev/null
+++ b/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.
diff --git a/aiogram/dispatcher/event/telegram.py b/aiogram/dispatcher/event/telegram.py
index 8dd56a71..8005c418 100644
--- a/aiogram/dispatcher/event/telegram.py
+++ b/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
diff --git a/aiogram/exceptions.py b/aiogram/exceptions.py
index 96d0c0db..dcf433c6 100644
--- a/aiogram/exceptions.py
+++ b/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,
diff --git a/tests/test_dispatcher/test_event/test_telegram.py b/tests/test_dispatcher/test_event/test_telegram.py
index 37f66357..1f892de0 100644
--- a/tests/test_dispatcher/test_event/test_telegram.py
+++ b/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