feat: add decorators for api handlers

st3/lsp_utils/__init__.py

@@ -1,4 +1,6 @@
 from ._client_handler import ClientHandler
+from ._client_handler import notification_handler
+from ._client_handler import request_handler
 from .api_wrapper_interface import ApiWrapperInterface
 from .generic_client_handler import GenericClientHandler
 from .npm_client_handler import NpmClientHandler
@@ -14,4 +16,7 @@
     'ServerResourceInterface',
     'ServerStatus'
     'ServerNpmResource',
+    # decorator-related
+    'notification_handler',
+    'request_handler',
 ]

st3/lsp_utils/_client_handler/__init__.py

@@ -1,3 +1,5 @@
+from .decorator import notification_handler
+from .decorator import request_handler
 from LSP.plugin import __version__ as lsp_version
 
 
@@ -8,4 +10,7 @@
 
 __all__ = [
     'ClientHandler',
+    # decorator-related
+    'notification_handler',
+    'request_handler',
 ]

st3/lsp_utils/_client_handler/abstract_plugin.py

@@ -1,5 +1,6 @@
 from ..api_wrapper_interface import ApiWrapperInterface
 from ..server_resource_interface import ServerStatus
+from .decorator import register_decorated_handlers
 from .interface import ClientHandlerInterface
 from LSP.plugin import AbstractPlugin
 from LSP.plugin import ClientConfig
@@ -158,4 +159,6 @@ def _upgrade_languages_list(cls, languages):
 
     def __init__(self, *args, **kwargs) -> None:
         super().__init__(*args, **kwargs)
-        self.on_ready(ApiWrapper(self))
+        api = ApiWrapper(self)
+        register_decorated_handlers(self, api)
+        self.on_ready(api)

st3/lsp_utils/_client_handler/decorator.py

@@ -0,0 +1,71 @@
+from ..api_wrapper_interface import ApiWrapperInterface
+from .interface import ClientHandlerInterface
+from LSP.plugin.core.typing import Any, Callable, List, Optional, Union
+import inspect
+
+__all__ = [
+    "notification_handler",
+    "request_handler",
+    "register_decorated_handlers",
+]
+
+# the first argument is always "self"
+T_HANDLER = Callable[[Any, Any], None]
+T_MESSAGE_METHODS = Union[str, List[str]]
+
+_HANDLER_MARKS = {
+    "notification": "__handle_notification_events",
+    "request": "__handle_request_events",
+}
+
+
+def notification_handler(notification_methods: T_MESSAGE_METHODS) -> Callable[[T_HANDLER], T_HANDLER]:
+    """ Marks the decorated function as a "notification" message handler. """
+
+    return _create_handler("notification", notification_methods)
+
+
+def request_handler(request_methods: T_MESSAGE_METHODS) -> Callable[[T_HANDLER], T_HANDLER]:
+    """ Marks the decorated function as a "request" message handler. """
+
+    return _create_handler("request", request_methods)
+
+
+def _create_handler(client_event: str, message_methods: T_MESSAGE_METHODS) -> Callable[[T_HANDLER], T_HANDLER]:
+    """ Marks the decorated function as a message handler. """
+
+    message_methods = [message_methods] if isinstance(message_methods, str) else message_methods
+
+    def decorator(func: T_HANDLER) -> T_HANDLER:
+        setattr(func, _HANDLER_MARKS[client_event], message_methods)
+        return func
+
+    return decorator
+
+
+def register_decorated_handlers(client_handler: ClientHandlerInterface, api: ApiWrapperInterface) -> None:
+    """
+    Register decorator-style custom message handlers.
+
+    This method works as following steps:
+
+    1. Scan through all methods of `client_handler`.
+    2. If a method is decorated, it will has a "handler mark" attribute which is set by the decorator.
+    3. Register the method with wanted message methods, which are stored in the "handler mark" attribute.
+
+    :param api: The API instance for interacting with the server.
+    """
+    for _, func in inspect.getmembers(client_handler, predicate=inspect.isroutine):
+        for client_event, handler_mark in _HANDLER_MARKS.items():
+            message_methods = getattr(func, handler_mark, None)  # type: Optional[List[str]]
+            if message_methods is None:
+                continue
+
+            event_registrator = getattr(api, "on_" + client_event, None)
+            if callable(event_registrator):
+                for message_method in message_methods:
+                    event_registrator(message_method, func)
+
+                # it makes no sense that a handler handlers both "notification" and "request"
+                # so we do early break once we've registered a handler
+                break

st3/lsp_utils/_client_handler/language_handler.py

@@ -1,6 +1,7 @@
 from ..api_wrapper_interface import ApiWrapperInterface
 from ..helpers import log_and_show_message
 from ..server_resource_interface import ServerStatus
+from .decorator import register_decorated_handlers
 from .interface import ClientHandlerInterface
 from LSP.plugin import ClientConfig
 from LSP.plugin import LanguageHandler
@@ -82,7 +83,9 @@ def on_start(cls, window: sublime.Window) -> bool:
         return True
 
     def on_initialized(self, client) -> None:
-        self.on_ready(ApiWrapper(client))
+        api = ApiWrapper(client)
+        register_decorated_handlers(self, api)
+        self.on_ready(api)
 
     # --- ClientHandlerInterface --------------------------------------------------------------------------------------