Remove the hook, implement formatters natively

Author: krassowski

pylsp/_utils.py

@@ -57,7 +57,7 @@ def run():
 
 
 def throttle(seconds=1):
-    """Throttles calls to a function evey `seconds` seconds."""
+    """Throttles calls to a function every `seconds` seconds."""
 
     def decorator(func):
         @functools.wraps(func)
@@ -209,15 +209,93 @@ def choose_markup_kind(client_supported_markup_kinds: List[str]):
     return "markdown"
 
 
-def convert_signatures_to_markdown(signatures: List[str]) -> str:
+class Formatter:
+    command: List[str]
+
+    @property
+    def is_installed(self) -> bool:
+        """Returns whether formatter is available"""
+        if not hasattr(self, "_is_installed"):
+            self._is_installed = self._is_available_via_cli()
+        return self._is_installed
+
+    def format(self, code: str, line_length: int) -> str:
+        """Formats code"""
+        return subprocess.check_output(
+            [
+                sys.executable,
+                "-m",
+                *self.command,
+                "--line-length",
+                str(line_length),
+                "-",
+            ],
+            input=code,
+            text=True,
+        ).strip()
+
+    def _is_available_via_cli(self) -> bool:
+        try:
+            subprocess.check_output(
+                [
+                    sys.executable,
+                    "-m",
+                    *self.command,
+                    "--help",
+                ],
+            )
+            return True
+        except CalledProcessError:
+            return False
+
+
+class RuffFormatter:
+    command = ["ruff", "format"]
+
+
+class BlackFormatter:
+    command = ["black"]
+
+
+formatters = {"ruff": RuffFormatter(), "black": BlackFormatter()}
+
+
+def format_signature(signature: str, signature_formatter: str) -> str:
+    """Formats signature using ruff or black if either is available."""
+    as_func = f"def {signature.strip()}:\n    pass"
+    line_length = config.get("line_length", 88)
+    formatter = formatters[signature_formatter]
+    if formatter.is_installed:
+        try:
+            return (
+                formatter.format(as_func, line_length=line_length)
+                .removeprefix("def ")
+                .removesuffix(":\n    pass")
+            )
+        except subprocess.CalledProcessError as e:
+            log.warning("Signature formatter failed %s", e)
+    else:
+        log.warning(
+            "Formatter %s was requested but it does not appear to be installed",
+            signature_formatter,
+        )
+    return signature
+
+
+def convert_signatures_to_markdown(signatures: List[str], config: dict) -> str:
+    signature_formatter = config.get("format", "black")
+    if signature_formatter:
+        signatures = [
+            format_signature(signature, config=config) for signature in signatures
+        ]
     return wrap_signature("\n".join(signatures))
 
 
 def format_docstring(
     contents: str,
     markup_kind: str,
     signatures: Optional[List[str]] = None,
-    signatures_to_markdown: Optional[Callable[[List[str]], str]] = None,
+    signature_config: Optional[dict] = None,
 ):
     """Transform the provided docstring into a MarkupContent object.
 
@@ -239,10 +317,8 @@ def format_docstring(
             value = escape_markdown(contents)
 
         if signatures:
-            wrapped_signatures = (
-                signatures_to_markdown(signatures)
-                if signatures_to_markdown
-                else convert_signatures_to_markdown(signatures)
+            wrapped_signatures = convert_signatures_to_markdown(
+                signatures, config=signature_config or {}
             )
             value = wrapped_signatures + "\n\n" + value
 

pylsp/config/schema.json

@@ -511,6 +511,26 @@
       },
       "uniqueItems": true,
       "description": "The name of the folder in which rope stores project configurations and data.  Pass `null` for not using such a folder at all."
-    }
+    },
+    "pylsp.signature.formatter": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "enum": [
+        "black",
+        "ruff",
+        null
+      ]
+      "default": "black",
+      "description": "Formatter to use for reformatting signatures in docstrings."
+    },
+    "pylsp.signature.line_length": {
+      "type": [
+        "number",
+      ],
+      "default": 88,
+      "description": "Maximum line length in signatures."
+    },
   }
 }

pylsp/hookspecs.py

@@ -24,16 +24,12 @@ def pylsp_commands(config, workspace) -> None:
 
 
 @hookspec
-def pylsp_completions(
-    config, workspace, document, position, ignored_names, signatures_to_markdown
-) -> None:
+def pylsp_completions(config, workspace, document, position, ignored_names) -> None:
     pass
 
 
 @hookspec(firstresult=True)
-def pylsp_completion_item_resolve(
-    config, workspace, document, completion_item, signatures_to_markdown
-) -> None:
+def pylsp_completion_item_resolve(config, workspace, document, completion_item) -> None:
     pass
 
 
@@ -93,12 +89,7 @@ def pylsp_format_range(config, workspace, document, range, options) -> None:
 
 
 @hookspec(firstresult=True)
-def pylsp_hover(config, workspace, document, position, signatures_to_markdown) -> None:
-    pass
-
-
-@hookspec(firstresult=True)
-def pylsp_signatures_to_markdown(signatures) -> None:
+def pylsp_hover(config, workspace, document, position) -> None:
     pass
 
 

pylsp/plugins/hover.py

@@ -9,7 +9,8 @@
 
 
 @hookimpl
-def pylsp_hover(config, document, position, signatures_to_markdown):
+def pylsp_hover(config, document, position):
+    signature_config = config.settings.get("signatures", {})
     code_position = _utils.position_to_jedi_linecolumn(document, position)
     definitions = document.jedi_script(use_document_path=True).infer(**code_position)
     word = document.word_at_position(position)
@@ -46,6 +47,6 @@ def pylsp_hover(config, document, position, signatures_to_markdown):
             definition.docstring(raw=True),
             preferred_markup_kind,
             signatures=[signature] if signature else None,
-            signatures_to_markdown=signatures_to_markdown,
+            signature_config=signature_config,
         )
     }

pylsp/plugins/jedi_completion.py

@@ -37,12 +37,13 @@
 
 
 @hookimpl
-def pylsp_completions(config, document, position, signatures_to_markdown):
+def pylsp_completions(config, document, position):
     """Get formatted completions for current code position"""
     settings = config.plugin_settings("jedi_completion", document_path=document.path)
     resolve_eagerly = settings.get("eager", False)
-    code_position = _utils.position_to_jedi_linecolumn(document, position)
+    signature_config = config.settings.get("signatures", {})
 
+    code_position = _utils.position_to_jedi_linecolumn(document, position)
     code_position["fuzzy"] = settings.get("fuzzy", False)
     completions = document.jedi_script(use_document_path=True).complete(**code_position)
 
@@ -89,7 +90,7 @@ def pylsp_completions(config, document, position, signatures_to_markdown):
             resolve=resolve_eagerly,
             resolve_label_or_snippet=(i < max_to_resolve),
             snippet_support=snippet_support,
-            signatures_to_markdown=signatures_to_markdown,
+            signature_config=signature_config,
         )
         for i, c in enumerate(completions)
     ]
@@ -105,7 +106,7 @@ def pylsp_completions(config, document, position, signatures_to_markdown):
                     resolve=resolve_eagerly,
                     resolve_label_or_snippet=(i < max_to_resolve),
                     snippet_support=snippet_support,
-                    signatures_to_markdown=signatures_to_markdown,
+                    signature_config=signature_config,
                 )
                 completion_dict["kind"] = lsp.CompletionItemKind.TypeParameter
                 completion_dict["label"] += " object"
@@ -121,7 +122,7 @@ def pylsp_completions(config, document, position, signatures_to_markdown):
                     resolve=resolve_eagerly,
                     resolve_label_or_snippet=(i < max_to_resolve),
                     snippet_support=snippet_support,
-                    signatures_to_markdown=signatures_to_markdown,
+                    signature_config=signature_config,
                 )
                 completion_dict["kind"] = lsp.CompletionItemKind.TypeParameter
                 completion_dict["label"] += " object"
@@ -142,7 +143,9 @@ def pylsp_completions(config, document, position, signatures_to_markdown):
 
 @hookimpl
 def pylsp_completion_item_resolve(
-    config, completion_item, document, signatures_to_markdown
+    config,
+    completion_item,
+    document,
 ):
     """Resolve formatted completion for given non-resolved completion"""
     shared_data = document.shared_data["LAST_JEDI_COMPLETIONS"].get(
@@ -162,7 +165,7 @@ def pylsp_completion_item_resolve(
             completion,
             data,
             markup_kind=preferred_markup_kind,
-            signatures_to_markdown=signatures_to_markdown,
+            signature_config=config.settings.get("signatures", {}),
         )
     return completion_item
 
@@ -218,19 +221,14 @@ def use_snippets(document, position):
     return expr_type not in _IMPORTS and not (expr_type in _ERRORS and "import" in code)
 
 
-def _resolve_completion(
-    completion,
-    d,
-    markup_kind: str,
-    signatures_to_markdown: Optional[Callable[[List[str]], str]] = None,
-):
+def _resolve_completion(completion, d, markup_kind: str, signature_config: dict):
     completion["detail"] = _detail(d)
     try:
         docs = _utils.format_docstring(
             d.docstring(raw=True),
             signatures=[signature.to_string() for signature in d.get_signatures()],
             markup_kind=markup_kind,
-            signatures_to_markdown=signatures_to_markdown,
+            signature_config=signature_config,
         )
     except Exception:
         docs = ""
@@ -245,7 +243,7 @@ def _format_completion(
     resolve=False,
     resolve_label_or_snippet=False,
     snippet_support=False,
-    signatures_to_markdown=None,
+    signature_config=None,
 ):
     completion = {
         "label": _label(d, resolve_label_or_snippet),
@@ -256,7 +254,7 @@ def _format_completion(
 
     if resolve:
         completion = _resolve_completion(
-            completion, d, markup_kind, signatures_to_markdown
+            completion, d, markup_kind, signature_config=signature_config
         )
 
     # Adjustments for file completions

pylsp/python_lsp.py

@@ -399,21 +399,14 @@ def completions(self, doc_uri, position):
             notebook_document = workspace.get_maybe_document(document.notebook_uri)
             ignored_names = notebook_document.jedi_names(doc_uri)
         completions = self._hook(
-            "pylsp_completions",
-            doc_uri,
-            position=position,
-            ignored_names=ignored_names,
-            signatures_to_markdown=self._signatures_to_markdown,
+            "pylsp_completions", doc_uri, position=position, ignored_names=ignored_names
         )
         return {"isIncomplete": False, "items": flatten(completions)}
 
     def completion_item_resolve(self, completion_item):
         doc_uri = completion_item.get("data", {}).get("doc_uri", None)
         return self._hook(
-            "pylsp_completion_item_resolve",
-            doc_uri,
-            completion_item=completion_item,
-            signatures_to_markdown=self._signatures_to_markdown,
+            "pylsp_completion_item_resolve", doc_uri, completion_item=completion_item
         )
 
     def definitions(self, doc_uri, position):
@@ -441,12 +434,7 @@ def highlight(self, doc_uri, position):
         )
 
     def hover(self, doc_uri, position):
-        return self._hook(
-            "pylsp_hover",
-            doc_uri,
-            position=position,
-            signatures_to_markdown=self._signatures_to_markdown,
-        ) or {"contents": ""}
+        return self._hook("pylsp_hover", doc_uri, position=position) or {"contents": ""}
 
     @_utils.debounce(LINT_DEBOUNCE_S, keyed_by="doc_uri")
     def lint(self, doc_uri, is_saved) -> None:
@@ -900,11 +888,6 @@ def m_workspace__did_change_watched_files(self, changes=None, **_kwargs):
     def m_workspace__execute_command(self, command=None, arguments=None):
         return self.execute_command(command, arguments)
 
-    def _signatures_to_markdown(self, signatures):
-        return self._hook(
-            "pylsp_signatures_to_markdown", signatures=signatures
-        ) or _utils.convert_signatures_to_markdown(signatures=signatures)
-
 
 def flatten(list_of_lists):
     return [item for lst in list_of_lists for item in lst]

test/plugins/test_completion.py

@@ -19,8 +19,6 @@
 from pylsp.plugins.rope_completion import pylsp_completions as pylsp_rope_completions
 from pylsp.workspace import Document
 
-pylsp_jedi_completions = partial(pylsp_jedi_completions, signatures_to_markdown=None)
-
 PY2 = sys.version[0] == "2"
 LINUX = sys.platform.startswith("linux")
 CI = os.environ.get("CI")
@@ -165,10 +163,7 @@ def test_jedi_completion_item_resolve(config, workspace) -> None:
     assert "detail" not in documented_hello_item
 
     resolved_documented_hello = pylsp_jedi_completion_item_resolve(
-        doc._config,
-        completion_item=documented_hello_item,
-        document=doc,
-        signatures_to_markdown=None,
+        doc._config, completion_item=documented_hello_item, document=doc
     )
     expected_doc = {
         "kind": "markdown",
@@ -541,9 +536,7 @@ def test_jedi_completion_environment(workspace) -> None:
     completions = pylsp_jedi_completions(doc._config, doc, com_position)
     assert completions[0]["label"] == "loghub"
 
-    resolved = pylsp_jedi_completion_item_resolve(
-        doc._config, completions[0], doc, signatures_to_markdown=None
-    )
+    resolved = pylsp_jedi_completion_item_resolve(doc._config, completions[0], doc)
     assert "changelog generator" in resolved["documentation"]["value"].lower()
 
 

test/plugins/test_hover.py

@@ -103,13 +103,7 @@ def test_hover_custom_signature(workspace) -> None:
         "value": "```python\nmain(\n    a: float,\n    b: float\n)\n```\n\n\nhello world",
     }
 
-    def signatures_to_markdown(signatures: list):
-        # dummy implementation for tests
-        return "```python\nmain(\n    a: float,\n    b: float\n)\n```\n"
-
-    assert {"contents": contents} == pylsp_hover(
-        doc._config, doc, hov_position, signatures_to_markdown=signatures_to_markdown
-    )
+    assert {"contents": contents} == pylsp_hover(doc._config, doc, hov_position)
 
 
 def test_document_path_hover(workspace_other_root_path, tmpdir) -> None: