feat: add API decorators (#2755)

Author: rchl

plugin/__init__.py

@@ -1,3 +1,5 @@
+from .api import notification_handler
+from .api import request_handler
 from .core.collections import DottedDict
 from .core.css import css
 from .core.edit import apply_text_edits
@@ -6,6 +8,7 @@
 from .core.file_watcher import FileWatcherEventType
 from .core.file_watcher import FileWatcherProtocol
 from .core.file_watcher import register_file_watcher_implementation
+from .core.promise import Promise
 from .core.protocol import Notification
 from .core.protocol import Request
 from .core.protocol import Response
@@ -47,10 +50,13 @@
     'MarkdownLangMap',
     'matches_pattern',
     'Notification',
+    'notification_handler',
     'parse_uri',
+    'Promise',
     'register_file_watcher_implementation',
     'register_plugin',
     'Request',
+    'request_handler',
     'Response',
     'Session',
     'SessionBufferProtocol',

plugin/api.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+from ..protocol import LSPAny
+from .core.protocol import Response
+from .core.types import method2attr
+from functools import wraps
+from typing import Any, Callable, TypeVar, TYPE_CHECKING
+import inspect
+
+if TYPE_CHECKING:
+    from .core.promise import Promise
+
+__all__ = [
+    'APIHandler',
+    'notification_handler',
+    'request_handler',
+]
+
+HANDLER_MARKER = '__HANDLER_MARKER'
+
+# P represents the parameters *after* the 'self' argument
+P = TypeVar('P', bound=LSPAny)
+R = TypeVar('R', bound=LSPAny)
+
+
+class APIHandler:
+    """Trigger initialization of decorated API methods."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        for _, method in inspect.getmembers(self, inspect.ismethod):
+            if hasattr(method, HANDLER_MARKER):
+                # Set method with transformed name on the class instance.
+                setattr(self, method2attr(getattr(method, HANDLER_MARKER)), method)
+
+
+def notification_handler(method: str) -> Callable[[Callable[[Any, P], None]], Callable[[Any, P], None]]:
+    """Decorator to mark a method as a handler for a specific LSP notification.
+
+    Usage:
+        ```py
+        @notification_handler('eslint/status')
+        def on_eslint_status(self, params: str) -> None:
+            ...
+        ```
+
+    The decorated method will be called with the notification parameters whenever the specified
+    notification is received from the language server. Notification handlers do not return a value.
+
+    :param      method:             The LSP notification method name (e.g., 'eslint/status').
+    :returns:   A decorator that registers the function as a notification handler.
+    """
+
+    def decorator(func: Callable[[Any, P], None]) -> Callable[[Any, P], None]:
+        setattr(func, HANDLER_MARKER, method)
+        return func
+
+    return decorator
+
+
+def request_handler(
+    method: str
+) -> Callable[[Callable[[Any, P], Promise[R]]], Callable[[Any, P, int], Promise[Response[R]]]]:
+    """Decorator to mark a method as a handler for a specific LSP request.
+
+    Usage:
+        ```py
+        @request_handler('eslint/openDoc')
+        def on_open_doc(self, params: TextDocumentIdentifier) -> Promise[bool]:
+            ...
+        ```
+
+    The decorated method will be called with the request parameters whenever the specified
+    request is received from the language server. The method must return a Promise that resolves
+    to the response value. The framework will automatically send it back to the server.
+
+    :param      method:             The LSP request method name (e.g., 'eslint/openDoc').
+    :returns:   A decorator that registers the function as a request handler.
+    """
+
+    def decorator(func: Callable[[Any, P], Promise[R]]) -> Callable[[Any, P, int], Promise[Response[R]]]:
+
+        @wraps(func)
+        def wrapper(self: Any, params: P, request_id: int) -> Promise[Response[Any]]:
+            promise = func(self, params)
+            return promise.then(lambda result: Response(request_id, result))
+
+        setattr(wrapper, HANDLER_MARKER, method)
+        return wrapper
+
+    return decorator

plugin/core/message_request_handler.py

@@ -1,11 +1,10 @@
 from __future__ import annotations
+from ...protocol import MessageActionItem
 from ...protocol import MessageType
 from ...protocol import ShowMessageRequestParams
-from .protocol import Response
-from .sessions import Session
+from .promise import PackagedTask, Promise, ResolveFunc
 from .views import show_lsp_popup
 from .views import text2html
-from typing import Any
 import sublime
 
 
@@ -19,20 +18,18 @@
 
 
 class MessageRequestHandler:
-    def __init__(
-        self, view: sublime.View, session: Session, request_id: Any, params: ShowMessageRequestParams, source: str
-    ) -> None:
-        self.session = session
-        self.request_id = request_id
-        self.request_sent = False
+    def __init__(self, view: sublime.View, params: ShowMessageRequestParams, source: str) -> None:
         self.view = view
         self.actions = params.get("actions", [])
         self.action_titles = list(action.get("title") for action in self.actions)
         self.message = params['message']
         self.message_type = params.get('type', 4)
         self.source = source
+        self._response_handled = False
 
-    def show(self) -> None:
+    def show(self) -> Promise[MessageActionItem | None]:
+        task: PackagedTask[MessageActionItem | None] = Promise.packaged_task()
+        promise, resolve = task
         formatted: list[str] = []
         formatted.append(f"<h2>{self.source}</h2>")
         icon = ICONS.get(self.message_type, '')
@@ -48,15 +45,14 @@ def show(self) -> None:
             location=self.view.layout_to_text(self.view.viewport_position()),
             css=sublime.load_resource("Packages/LSP/notification.css"),
             wrapper_class='notification',
-            on_navigate=self._send_user_choice,
-            on_hide=self._send_user_choice)
+            on_navigate=lambda href: self._send_user_choice(resolve, href),
+            on_hide=lambda: self._send_user_choice(resolve))
+        return promise
 
-    def _send_user_choice(self, href: int = -1) -> None:
-        if self.request_sent:
+    def _send_user_choice(self, resolve: ResolveFunc[MessageActionItem | None], href: int = -1) -> None:
+        if self._response_handled:
             return
-        self.request_sent = True
+        self._response_handled = True
         self.view.hide_popup()
         index = int(href)
-        param = self.actions[index] if index != -1 else None
-        response = Response(self.request_id, param)
-        self.session.send_response(response)
+        resolve(self.actions[index] if index != -1 else None)

plugin/core/rpc.py

@@ -1,3 +1,3 @@
 # only used for LSP-* packages out in the wild that now import from "private" modules
 # TODO: Announce removal and remove this import
-from .sessions import method2attr  # noqa
+from .types import method2attr  # noqa