Allow to format signatures in docstrings (#631)

Author: krassowski

CONFIGURATION.md

@@ -75,5 +75,7 @@ This server can be configured using the `workspace/didChangeConfiguration` metho
 |`pylsp.plugins.yapf.enabled`|`boolean`| Enable or disable the plugin. |`true`|
 |`pylsp.rope.extensionModules`|`string`| Builtin and c-extension modules that are allowed to be imported and inspected by rope. |`null`|
 |`pylsp.rope.ropeFolder`|`array` of unique `string` items | The name of the folder in which rope stores project configurations and data. Pass `null` for not using such a folder at all. |`null`|
+|`pylsp.signature.formatter`|`string` (one of: `'black'`, `'ruff'`, `None`) | Formatter to use for reformatting signatures in docstrings. |`"black"`|
+|`pylsp.signature.line_length`|`number`| Maximum line length in signatures. |`88`|
 
 This documentation was generated from `pylsp/config/schema.json`. Please do not edit this file directly.

pylsp/_utils.py

@@ -7,6 +7,8 @@
 importos
 importpathlib
 importre
+importsubprocess
+importsys
 importthreading
 importtime
 fromtypingimportOptional
@@ -57,7 +59,7 @@ def run():
 
 
 defthrottle(seconds=1):
-"""Throttles calls to a function evey `seconds` seconds."""
+"""Throttles calls to a function every `seconds` seconds."""
 
 defdecorator(func):
 @functools.wraps(func)
@@ -209,8 +211,96 @@ def choose_markup_kind(client_supported_markup_kinds: list[str]):
 return"markdown"
 
 
+classFormatter:
+command: list[str]
+
+@property
+defis_installed(self) ->bool:
+"""Returns whether formatter is available"""
+ifnothasattr(self, "_is_installed"):
+self._is_installed=self._is_available_via_cli()
+returnself._is_installed
+
+defformat(self, code: str, line_length: int) ->str:
+"""Formats code"""
+returnsubprocess.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",
+ ],
+ )
+returnTrue
+exceptsubprocess.CalledProcessError:
+returnFalse
+
+
+classRuffFormatter(Formatter):
+command= ["ruff", "format"]
+
+
+classBlackFormatter(Formatter):
+command= ["black"]
+
+
+formatters={"ruff": RuffFormatter(), "black": BlackFormatter()}
+
+
+defformat_signature(signature: str, config: dict, 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]
+ifformatter.is_installed:
+try:
+return (
+formatter.format(as_func, line_length=line_length)
+ .removeprefix("def ")
+ .removesuffix(":\n pass")
+ )
+exceptsubprocess.CalledProcessErrorase:
+log.warning("Signature formatter failed %s", e)
+else:
+log.warning(
+"Formatter %s was requested but it does not appear to be installed",
+signature_formatter,
+ )
+returnsignature
+
+
+defconvert_signatures_to_markdown(signatures: list[str], config: dict) ->str:
+signature_formatter=config.get("formatter", "black")
+ifsignature_formatter:
+signatures= [
+format_signature(
+signature, signature_formatter=signature_formatter, config=config
+ )
+forsignatureinsignatures
+ ]
+returnwrap_signature("\n".join(signatures))
+
+
 defformat_docstring(
-contents: str, markup_kind: str, signatures: Optional[list[str]] =None
+contents: str,
+markup_kind: str,
+signatures: Optional[list[str]] =None,
+signature_config: Optional[dict] =None,
 ):
 """Transform the provided docstring into a MarkupContent object.
 
@@ -232,7 +322,10 @@ def format_docstring(
 value=escape_markdown(contents)
 
 ifsignatures:
-value=wrap_signature("\n".join(signatures)) +"\n\n"+value
+wrapped_signatures=convert_signatures_to_markdown(
+signatures, config=signature_configor{}
+ )
+value=wrapped_signatures+"\n\n"+value
 
 return{"kind": "markdown", "value": value}
 value=contents

pylsp/config/schema.json

@@ -511,6 +511,24 @@
  },
 "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/plugins/hover.py

@@ -10,6 +10,7 @@
 
 @hookimpl
 defpylsp_hover(config, document, position):
+signature_config=config.settings().get("signature",{})
 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,5 +47,6 @@ def pylsp_hover(config, document, position):
 definition.docstring(raw=True),
 preferred_markup_kind,
 signatures=[signature] ifsignatureelseNone,
+signature_config=signature_config,
  )
  }

pylsp/plugins/jedi_completion.py

@@ -40,8 +40,9 @@ 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("signature",{})
 
+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)
 
@@ -88,6 +89,7 @@ def pylsp_completions(config, document, position):
 resolve=resolve_eagerly,
 resolve_label_or_snippet=(i<max_to_resolve),
 snippet_support=snippet_support,
+signature_config=signature_config,
  )
 fori, cinenumerate(completions)
  ]
@@ -103,6 +105,7 @@ def pylsp_completions(config, document, position):
 resolve=resolve_eagerly,
 resolve_label_or_snippet=(i<max_to_resolve),
 snippet_support=snippet_support,
+signature_config=signature_config,
  )
 completion_dict["kind"] =lsp.CompletionItemKind.TypeParameter
 completion_dict["label"] +=" object"
@@ -118,6 +121,7 @@ def pylsp_completions(config, document, position):
 resolve=resolve_eagerly,
 resolve_label_or_snippet=(i<max_to_resolve),
 snippet_support=snippet_support,
+signature_config=signature_config,
  )
 completion_dict["kind"] =lsp.CompletionItemKind.TypeParameter
 completion_dict["label"] +=" object"
@@ -137,7 +141,11 @@ def pylsp_completions(config, document, position):
 
 
 @hookimpl
-defpylsp_completion_item_resolve(config, completion_item, document):
+defpylsp_completion_item_resolve(
+config,
+completion_item,
+document,
+):
 """Resolve formatted completion for given non-resolved completion"""
 shared_data=document.shared_data["LAST_JEDI_COMPLETIONS"].get(
 completion_item["label"]
@@ -152,7 +160,12 @@ def pylsp_completion_item_resolve(config, completion_item, document):
 
 ifshared_data:
 completion, data=shared_data
-return_resolve_completion(completion, data, markup_kind=preferred_markup_kind)
+return_resolve_completion(
+completion,
+data,
+markup_kind=preferred_markup_kind,
+signature_config=config.settings().get("signature",{}),
+ )
 returncompletion_item
 
 
@@ -207,13 +220,14 @@ def use_snippets(document, position):
 returnexpr_typenotin_IMPORTSandnot (expr_typein_ERRORSand"import"incode)
 
 
-def_resolve_completion(completion, d, markup_kind: str):
+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() forsignatureind.get_signatures()],
 markup_kind=markup_kind,
+signature_config=signature_config,
  )
 exceptException:
 docs=""
@@ -228,6 +242,7 @@ def _format_completion(
 resolve=False,
 resolve_label_or_snippet=False,
 snippet_support=False,
+signature_config=None,
 ):
 completion={
 "label": _label(d, resolve_label_or_snippet),
@@ -237,7 +252,9 @@ def _format_completion(
  }
 
 ifresolve:
-completion=_resolve_completion(completion, d, markup_kind)
+completion=_resolve_completion(
+completion, d, markup_kind, signature_config=signature_config
+ )
 
 # Adjustments for file completions
 ifd.type=="path":

pyproject.toml

@@ -19,6 +19,7 @@ dependencies = [
 "pluggy>=1.0.0",
 "python-lsp-jsonrpc>=1.1.0,<2.0.0",
 "ujson>=3.0.0",
+"black"
 ]
 dynamic = ["version"]
 

test/plugins/test_hover.py

@@ -10,7 +10,7 @@
 DOC_URI=uris.from_fs_path(__file__)
 DOC="""
 
-def main():
+def main(a: float, b: float):
 \"\"\"hello world\"\"\"
  pass
 """
@@ -79,13 +79,47 @@ def test_hover(workspace) -> None:
 
 doc=Document(DOC_URI, workspace, DOC)
 
-contents={"kind": "markdown", "value": "```python\nmain()\n```\n\n\nhello world"}
+contents={
+"kind": "markdown",
+"value": "```python\nmain(a: float, b: float)\n```\n\n\nhello world",
+ }
 
 assert{"contents": contents} ==pylsp_hover(doc._config, doc, hov_position)
 
 assert{"contents": ""} ==pylsp_hover(doc._config, doc, no_hov_position)
 
 
+deftest_hover_signature_formatting(workspace) ->None:
+# Over 'main' in def main():
+hov_position={"line": 2, "character": 6}
+
+doc=Document(DOC_URI, workspace, DOC)
+# setting low line length should trigger reflow to multiple lines
+doc._config.update({"signature":{"line_length": 10}})
+
+contents={
+"kind": "markdown",
+"value": "```python\nmain(\n a: float,\n b: float,\n)\n```\n\n\nhello world",
+ }
+
+assert{"contents": contents} ==pylsp_hover(doc._config, doc, hov_position)
+
+
+deftest_hover_signature_formatting_opt_out(workspace) ->None:
+# Over 'main' in def main():
+hov_position={"line": 2, "character": 6}
+
+doc=Document(DOC_URI, workspace, DOC)
+doc._config.update({"signature":{"line_length": 10, "formatter": None}})
+
+contents={
+"kind": "markdown",
+"value": "```python\nmain(a: float, b: float)\n```\n\n\nhello world",
+ }
+
+assert{"contents": contents} ==pylsp_hover(doc._config, doc, hov_position)
+
+
 deftest_document_path_hover(workspace_other_root_path, tmpdir) ->None:
 # Create a dummy module out of the workspace's root_path and try to get
 # a definition on it in another file placed next to it.