Merge branch 'develop' into fixInlineComments

Author: ccordoba12

.github/workflows/release.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        PYTHON_VERSION: ['3.8']
+        PYTHON_VERSION: ['3.9']
     timeout-minutes: 10
     steps:
       - uses: actions/cache@v1

.github/workflows/static.yml

@@ -30,9 +30,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          # TODO: check with Python 3, but need to fix the
-          # errors first
-          python-version: '3.8'
+          python-version: '3.9'
           architecture: 'x64'
       - run: python -m pip install --upgrade pip setuptools jsonschema
       # If we don't install pycodestyle, pylint will throw an unused-argument error in pylsp/plugins/pycodestyle_lint.py:72

.github/workflows/test-linux.yml

@@ -24,7 +24,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        PYTHON_VERSION: ['3.10', '3.9', '3.8']
+        PYTHON_VERSION: ['3.11', '3.10', '3.9']
     timeout-minutes: 10
     steps:
       - uses: actions/cache@v4

.github/workflows/test-mac.yml

@@ -24,7 +24,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        PYTHON_VERSION: ['3.10', '3.9', '3.8']
+        PYTHON_VERSION: ['3.11', '3.10', '3.9']
     timeout-minutes: 10
     steps:
       - uses: actions/cache@v4

.github/workflows/test-win.yml

@@ -24,7 +24,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        PYTHON_VERSION: ['3.10', '3.9', '3.8']
+        PYTHON_VERSION: ['3.11', '3.10', '3.9']
     timeout-minutes: 10
     steps:
       - uses: actions/cache@v4

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/__main__.py

@@ -20,7 +20,7 @@
     start_ws_lang_server,
 )
 
-LOG_FORMAT = "%(asctime)s {0} - %(levelname)s - %(name)s - %(message)s".format(
+LOG_FORMAT = "%(asctime)s {} - %(levelname)s - %(name)s - %(message)s".format(
     time.localtime().tm_zone
 )
 
@@ -98,7 +98,7 @@ def _configure_logger(verbose=0, log_config=None, log_file=None) -> None:
     root_logger = logging.root
 
     if log_config:
-        with open(log_config, "r", encoding="utf-8") as f:
+        with open(log_config, encoding="utf-8") as f:
             logging.config.dictConfig(json.load(f))
     else:
         formatter = logging.Formatter(LOG_FORMAT)

pylsp/_utils.py

@@ -7,9 +7,11 @@
 import os
 import pathlib
 import re
+import subprocess
+import sys
 import threading
 import time
-from typing import List, Optional
+from typing import Optional
 
 import docstring_to_markdown
 import jedi
@@ -57,7 +59,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)
@@ -78,7 +80,7 @@ def find_parents(root, path, names):
 
     Args:
         path (str): The file path to start searching up from.
-        names (List[str]): The file/directory names to look for.
+        names (list[str]): The file/directory names to look for.
         root (str): The directory at which to stop recursing upwards.
 
     Note:
@@ -198,7 +200,7 @@ def wrap_signature(signature):
 SERVER_SUPPORTED_MARKUP_KINDS = {"markdown", "plaintext"}
 
 
-def choose_markup_kind(client_supported_markup_kinds: List[str]):
+def choose_markup_kind(client_supported_markup_kinds: list[str]):
     """Choose a markup kind supported by both client and the server.
 
     This gives priority to the markup kinds provided earlier on the client preference list.
@@ -209,8 +211,96 @@ def choose_markup_kind(client_supported_markup_kinds: List[str]):
     return "markdown"
 
 
+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 subprocess.CalledProcessError:
+            return False
+
+
+class RuffFormatter(Formatter):
+    command = ["ruff", "format"]
+
+
+class BlackFormatter(Formatter):
+    command = ["black"]
+
+
+formatters = {"ruff": RuffFormatter(), "black": BlackFormatter()}
+
+
+def format_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]
+    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("formatter", "black")
+    if signature_formatter:
+        signatures = [
+            format_signature(
+                signature, signature_formatter=signature_formatter, 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
+    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)
 
         if signatures:
-            value = wrap_signature("\n".join(signatures)) + "\n\n" + value
+            wrapped_signatures = convert_signatures_to_markdown(
+                signatures, config=signature_config or {}
+            )
+            value = wrapped_signatures + "\n\n" + value
 
         return {"kind": "markdown", "value": value}
     value = contents

pylsp/config/config.py

@@ -3,8 +3,9 @@
 
 import logging
 import sys
+from collections.abc import Mapping, Sequence
 from functools import lru_cache
-from typing import List, Mapping, Sequence, Union
+from typing import Union
 
 import pluggy
 from pluggy._hooks import HookImpl
@@ -32,7 +33,7 @@ def _hookexec(
         methods: Sequence[HookImpl],
         kwargs: Mapping[str, object],
         firstresult: bool,
-    ) -> Union[object, List[object]]:
+    ) -> Union[object, list[object]]:
         # called from all hookcaller instances.
         # enable_tracing will set its own wrapping function at self._inner_hookexec
         try:

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."
     }
   }
 }