Allow to format signatures in docstrings #631

krassowski · 2025-03-31T13:37:23Z

This is a proposal for #630. Initially this PR proposed adding pylsp_signatures_to_markdown hook, but currently it modifies the format_docstring directly without use of the hook.

Using a list → str approach allows the hook to modify how alternative signatures are displayed.

~~There are no user-facing changes out of the box, however users can now install pylsp-ruff-signature~~

Users see much more readable function signatures in hover and in completion documentation, for example:

Without `pylsp-ruff-signature`	With `pylsp-ruff-signature`

krassowski · 2025-04-04T13:44:21Z

Any thoughts @ccordoba12 ? It would be amazing to get it in to allow downstreams to customize.

krassowski · 2025-04-11T13:31:49Z

A gentle ping :)

pylsp/plugins/hover.py

as these are not supported by pluggy

@mscolnick

## 📝 Summary - formats signatures using ruff so that they are easier to read - depends on python-lsp/python-lsp-server#631 ## 🔍 Description of Changes Adds `pylsp_signatures_to_markdown` hook, re-using existing `ruff` formatting utility. | Before | After | |--|--| | ![image](https://github.com/user-attachments/assets/2ffb4e27-6a26-4f69-ae7a-ed51faa5afc2) | ![Screenshot from 2025-05-09 22-01-22](https://github.com/user-attachments/assets/56bde23c-193d-4800-a2c6-81b80ab72025) | Note: this does not help with `pd.read_csv`; I am not sure why it is not hitting this code path, but notably it happens on the completion items which do not have a docstring either. ## 📋 Checklist - [x] I have read the [contributor guidelines](https://github.com/marimo-team/marimo/blob/main/CONTRIBUTING.md). - [ ] For large changes, or changes that affect the public API: this change was discussed or approved through an issue, on [Discord](https://marimo.io/discord?ref=pr), or the community [discussions](https://github.com/marimo-team/marimo/discussions) (Please provide a link if applicable). - [ ] I have added tests for the changes made. - [x] I have run the code and verified that it works as expected. ## 📜 Reviewers @mscolnick

ccordoba12 · 2025-05-12T15:24:28Z

Any thoughts @ccordoba12 ? It would be amazing to get it in to allow downstreams to customize.

Sorry for the delay in replying @krassowski. For now I only have one question for you: instead of using a hook for this (pylsp_signatures_to_markdown), why not adding the functionality to format signatures to markdown to the server itself?

The problem with your current approach is that only users that know that they need to install pylsp-ruff-signature (or a similar plugin), will be able to get better signatures. That would be ok for JupyterLab-LSP users because you could add that plugin as a new dependency. But it wouldn't be easily discoverable for users from other editors/IDEs.

I know that would add a new dependency in either Ruff or Black, but I'm ok with that. I'd prefer Black because it's pure Python, but we could look for Ruff being on PATH and use it first if found. Another option would be to create a new package (similar to docstring_to_markdown) and use it for this purpose. Then, Black/Ruff would be its dependency.

krassowski · 2025-05-12T15:33:27Z

instead of using a hook for this (pylsp_signatures_to_markdown), why not adding the functionality to format signatures to markdown to the server itself?

I think there are two cons:

it adds a new dependency (say ruff or black) - you addressed this point
users may want to configure it (e.g. max line length, how to present typing, etc)

If you are ok with having this in pylsp and including the config options then I think would be fine.

I think we could even get away with having ruff/black as optional dependencies by introducing this plugin as disabled by default (and sniffing if ruff/black are installed).

ccordoba12 · 2025-05-12T15:43:07Z

users may want to configure it (e.g. max line length, how to present typing, etc)

Right, I didn't thought about it.

If you are ok with having this in pylsp and including the config options then I think would be fine.

Sure, no problem about it if that'd benefit more users.

I think we could even get away with having ruff/black as optional dependencies by introducing this plugin as disabled by default (and sniffing if ruff/black are installed).

That'd be inconsistent to users because with no ruff/black they'd get different results than without them and it'd be hard for them to understand why. So, I'd say let's go with black and leave ruff as optional. In that case, the UX would be practically indistinguishable since both give pretty much the same result.

dalthviz · 2025-05-12T19:33:53Z

Just in case, gave a check to the implementation and current approach (using Jupyterlab + this PR + pylsp-ruff-signature) and I think things are working as expected 👍

Regarding the implementation approach to follow, the idea then is to include python-ruff-signature as a bundled plugin for python-lsp-server (leaving it enabled by default) + allowing it to be configurable to work with either black or ruff and other configs that could be useful (max line length, typing represetation, etc) + add black as a required dependency for python-lsp-server while ruff would be optional, right?

ccordoba12 · 2025-05-12T19:49:08Z

Regarding the implementation approach to follow, the idea then is to include python-ruff-signature as a bundled plugin for python-lsp-server

Nop, it's to implement the functionality of that plugin directly in _utils/format_docstring. Then a new hook, changes to existing hooks and a new plugin won't be necessary.

allowing it to be configurable to work with either black or ruff and other configs that could be useful (max line length, typing represetation, etc)

Yep, although I think that's a bit overkill.

add black as a required dependency for python-lsp-server while ruff would be optional, right?

Right.

krassowski · 2025-05-25T10:43:14Z

@ccordoba12 @dalthviz when you get a chance this is ready for another round of review - as per the request above I removed the hook and implemented the functionality directly, adding a black dependency and allowing for opting out or choosing ruff instead.

dalthviz

Thank you @krassowski for the updates here! I checked locally the changes here and seems like things are working as expected 👍

Left a comment regarding adding ruff as an optional dependency and another regarding the TODO about the removesuffix/removeprefix functions and Python 3.8 but besides that this LGTM so leaving it approved.

dalthviz · 2025-05-27T16:34:38Z

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"


Should ruff be added as an optional dependecy below?

I don't think so. The functionality to format signatures will be provided by Black and it'll be very similar to the one given by Ruff.

dalthviz · 2025-05-27T17:00:22Z

pylsp/_utils.py

+    if formatter.is_installed:
+        try:
+            return (
+                # TODO: replace with str.removeprefix and str.removesuffix


Should an issue be created to track this TODO @ccordoba12 ?

No, I think we should simply bump our Python version to 3.9 in another PR so we don't need those functions here.

Could you take care of that?

I opened #650

krassowski added 2 commits March 31, 2025 14:33

Allow to format signatures in docstrings

04cdb98

Add a test

0a3113e

krassowski marked this pull request as ready for review March 31, 2025 14:20

Merge branch 'develop' into docstring-hook

0fe6cf6

dalthviz self-requested a review April 23, 2025 18:24

krassowski marked this pull request as draft May 9, 2025 19:43

krassowski commented May 9, 2025

View reviewed changes

pylsp/plugins/hover.py Outdated Show resolved Hide resolved

krassowski added 3 commits May 9, 2025 21:18

Simplify hook usage, do not use default args

d469b6d

as these are not supported by pluggy

Fix tests

abace2c

One more test

8758d56

krassowski marked this pull request as ready for review May 9, 2025 20:34

krassowski mentioned this pull request May 9, 2025

Format signatures in LSP hover and completion documentation marimo-team/marimo#4864

Merged

4 tasks

mscolnick approved these changes May 13, 2025

View reviewed changes

krassowski added 8 commits May 24, 2025 18:05

Remove the hook, implement formatters natively

d5c1e8e

Add black as a dependency

da04672

Fixes

573eac0

Fix/update config

011882d

Fix opt-out, add a test

6a26eeb

Lint

728d61c

Python 3.8 support

9f0ef6f

Merge branch 'develop' into docstring-hook

eb3f843

dalthviz approved these changes May 27, 2025

View reviewed changes

ccordoba12 added this to the v1.13.0 milestone May 28, 2025

ccordoba12 assigned krassowski May 28, 2025

ccordoba12 added the enhancement New feature or request label May 28, 2025

Merge branch 'develop' into docstring-hook

8ed0fa9

krassowski force-pushed the docstring-hook branch from c93a9af to 8ed0fa9 Compare May 28, 2025 16:39

Remove code for Python 3.8 compatibility

875d8ca

krassowski merged commit c8e4e99 into python-lsp:develop May 29, 2025
10 checks passed

krassowski deleted the docstring-hook branch May 29, 2025 07:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Allow to format signatures in docstrings #631

Allow to format signatures in docstrings #631

Uh oh!

krassowski commented Mar 31, 2025 •

edited

Loading

Uh oh!

krassowski commented Apr 4, 2025 •

edited

Loading

Uh oh!

krassowski commented Apr 11, 2025

Uh oh!

Uh oh!

ccordoba12 commented May 12, 2025 •

edited

Loading

Uh oh!

krassowski commented May 12, 2025 •

edited

Loading

Uh oh!

ccordoba12 commented May 12, 2025 •

edited

Loading

Uh oh!

dalthviz commented May 12, 2025

Uh oh!

ccordoba12 commented May 12, 2025 •

edited

Loading

Uh oh!

krassowski commented May 25, 2025

Uh oh!

dalthviz left a comment

Uh oh!

dalthviz May 27, 2025

Uh oh!

ccordoba12 May 28, 2025 •

edited

Loading

Uh oh!

dalthviz May 27, 2025

Uh oh!

ccordoba12 May 27, 2025

Uh oh!

krassowski May 28, 2025

Uh oh!

Uh oh!

Uh oh!

Allow to format signatures in docstrings #631

Allow to format signatures in docstrings #631

Uh oh!

Conversation

krassowski commented Mar 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

krassowski commented Apr 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

krassowski commented Apr 11, 2025

Uh oh!

Uh oh!

ccordoba12 commented May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

krassowski commented May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ccordoba12 commented May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dalthviz commented May 12, 2025

Uh oh!

ccordoba12 commented May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

krassowski commented May 25, 2025

Uh oh!

dalthviz left a comment

Choose a reason for hiding this comment

Uh oh!

dalthviz May 27, 2025

Choose a reason for hiding this comment

Uh oh!

ccordoba12 May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dalthviz May 27, 2025

Choose a reason for hiding this comment

Uh oh!

ccordoba12 May 27, 2025

Choose a reason for hiding this comment

Uh oh!

krassowski May 28, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

krassowski commented Mar 31, 2025 •

edited

Loading

krassowski commented Apr 4, 2025 •

edited

Loading

ccordoba12 commented May 12, 2025 •

edited

Loading

krassowski commented May 12, 2025 •

edited

Loading

ccordoba12 commented May 12, 2025 •

edited

Loading

ccordoba12 commented May 12, 2025 •

edited

Loading

ccordoba12 May 28, 2025 •

edited

Loading