Add setting to allow folding function signature separately from body

[pedrorrivero]

Type: Bug

Behaviour

Expected vs. Actual

When the Python plugin is disabled, function/class bodies in .py files can be folded from the end of a multiline signature (i.e. at :); while the multiline signature can also be folded separetly at the same level. Enabling Python, breaks this nice behavior, only allwoing to fold the entire function from the first line of the signature (i.e. at def/class).

This is, enabling Python joins signtaures and the bodies in a single foldable, instead of keeping them separate.

Steps to reproduce:

1. Disable Python
2. Open .py file with a multiline function/class signature
3. Navigate with the cursor to the left edge of the file panel
4. Notice two arrows: one to fold the signature at def/class height, and another to fold the body at : height.
5. Enable Python
6. Close the .py file
7. Restart VS Code
8. Reopen the .py file
9. Notice that now there is only one arrow on the left edge of the file panel at def/class height which folds both the signature and body

Diagnostic data

• Python version (& distribution if applicable, e.g. Anaconda): 3.8.9
• Type of virtual environment used (e.g. conda, venv, virtualenv, etc.): Venv
• Value of the python.languageServer setting: Default

Output for Python in the Output panel (View→Output, change the drop-down the upper-right of the Output panel to Python)

XXX

User Settings

languageServer: "Pylance"

Extension version: 2022.14.0
VS Code version: Code 1.71.2 (Universal) (74b1f979648cc44d385a2286793c226e611f59e7, 2022-09-14T21:05:37.721Z)
OS version: Darwin x64 21.6.0
Modes:
Sandboxed: No

System Info

Item	Value
CPUs	Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz (16 x 2400)
GPU Status	2d_canvas: enabled canvas_oop_rasterization: disabled_off direct_rendering_display_compositor: disabled_off_ok gpu_compositing: enabled metal: disabled_off multiple_raster_threads: enabled_on opengl: enabled_on rasterization: enabled raw_draw: disabled_off_ok skia_renderer: enabled_on video_decode: enabled video_encode: enabled vulkan: disabled_off webgl: enabled webgl2: enabled webgpu: disabled_off
Load (avg)	2, 2, 2
Memory (System)	32.00GB (0.97GB free)
Process Argv
Screen Reader	no
VM	0%

[pedrorrivero]

Python disabled

Expanded

Collapse signature

Collapse body

Collapse all

Python enabled

Expanded

Collapse all

[debonte]

We previously discussed this in #2269. Take a look at the three options I described in this comment.

Option 1 is your preferred behavior.
Option 2 is the current behavior.
Option 3 is an approach that I think may make everyone happy.

Let me know what you think.

[pedrorrivero]

Thanks for the quick reply @debonte ! I agree with you, option 3 is a good intermediate approach.

The important thing imho is to be able to keep the signature visible. Only concern with option 3 really is that it would mess up the levels so that shortcuts will not be consistent (e.g. folding level 2 would mean folding the body in some functions, and folding something internal in other cases depending on whether the signature is multiline or not)

That is why I would personally advocate for option 1. Plus the overall underlying data structure seems more natural to me, so easier to understand as a user.

Thanks for putting all this together 😉

[debonte]

Only concern with option 3 really is that it would mess up the levels so that shortcuts will not be consistent (e.g. folding level 2 would mean folding the body in some functions, and folding something internal in other cases depending on whether the signature is multiline or not)

I'm not sure I understand.

To recap, option 3 means that in the following screenshot, folding line 22 collapses the body (leaving the parameter list visible) and folding line 18 collapses the entire function definition (arguments and body):

I think your concern is that with single-line function headers, users might think that the next > icon below the def will collapse the function body? In the example below, folding line 189 collapses the entire function. If we go with option 3, are you concerned that users will think that folding line 190 would collapse the body of the function, simply because it's the next folding icon below the def line?

If that's your concern, I'm not sure how to address it. That would have been a problem with the old (2021, aka option 1) behavior as well. Also, this would seem like an argument for sticking with the current behavior -- a single, consistent folding location for functions.

If I'm misunderstanding your point, could you show me some code snippets to explain what you're describing?

[debonte]

Some other thoughts:

1. What if we changed the text of the folding line when folding functions with multiline signatures? So if you folded line 18 of my_func above, and it folded the entire function, the text shown on line 18 would be def my_func(a, b, c) instead of def my_func(. This would require vscode to support LSP's FoldingRange.collapsedText field. See [folding] custom folding text for folded ranges vscode#70794.
2. We could have a config setting to switch between 2+ function folding behaviors.

[pedrorrivero]

Thanks so much for the detailed response!

This is what I mean. Take the following code snippet as an example, folding points are labeled alphabetically:

def single_line():          # A
    if 0 == 1:              # B
        pass

def multi_line(             # C
    *args,
):                          # D
    pass

Folding level 1 means:

• Under option 1 → #A, #C and #D (exposed)
• Under option 3 → #A and #C (#D is hidden)

Folding level 2 means:

• Under option 1 → #B
• Under option 3 → #B and #D

Notice how folding level 1 is roughly equivalent and equivalent; with the added choice of displaying the signature under option 1 afterwards.

However, folding level 2 under option 3 messes the structure of the document, since one function will get its body folded and the other only an internal if statement. And the situation gets worse if you start considering these as methods within a class (which, if the class is large, I like to fold automatically with a key binding for quickly looking through it).

You can toy around with this idea and notice that the real issue with option 3 is that it assigns different precedence levels to things which are structurally at the same "height": throwing the body under the signature instead of keeping them aligned in the hierarchy.

---

We could have a config setting to switch between 2+ function folding behaviors

This would be a nice way to end the controversy, let users choose what they want.

What if we changed the text of the folding line when folding functions with multiline signatures?

In which case this would help remind them what their selected choice is 🙂 but it is not a huge concern of mine. I think people can get a grasp of the behavior by simply clicking a few times

[debonte]

Thanks. I'm embarrassed to say that I wasn't familiar with the Fold Level # commands until now.

I'll need to think about this some more and play with the different behaviors. Thanks for educating me. :)

[debonte]

For future reference, here are some screenshots I captured using the three options on the following code:

def single_line():          # A
    if 0 == 1:              # B
        pass

def multi_line(             # C
    *args,
):                          # D
    if 0 == 1:
        pass

class Class:
    def single_line(self):  # A
        if 0 == 1:          # B
            pass

    def multi_line(         # C
        self,           
        *args,
    ):                      # D
        pass

def another():
    pass

Folding level 1 (option 1 on left, option 2 center, option 3 on right):

Folding level 2:

[debonte]

I agree that option 3's behavior with the Fold Level # commands is weird and I think it rules that out as an option.

If there's sufficient interest, we can add a setting to choose between options 1 and 2 for folding functions (and classes) with multi-line signatures/headers. However, given that no one else has upvoted or commented on this issue, it's not clear that it's broadly needed.

@pedrorrivero, can you try this setting to see if it is acceptable to you as a workaround in the meantime?

"[python]": {
    "editor.foldingStrategy": "indentation",
},

[debonte]

@pedrorrivero, ping? See my comment above.

[pedrorrivero]

Apologies, I've had very busy weeks. Let me take a look at this over the weekend! Thanks for pinging @debonte 🙂

[pedrorrivero]

This looks very nice indeed, for what I have been able to see it does exactly what we discussed for option 1, thanks a lot for taking a look and providing a solution @debonte.

Looking forward to that extra option in the future if there is interest 😄 Let me know if I can help in any other way

[pedrorrivero]

Quick update @debonte, the workaround you proposed fails for docstrings (i.e. they cannot be collapsed).

[debonte]

It's the default folding strategy provided by VS Code. We don't have any control over how it works. It's purely indentation based -- a line will be foldable if the line/lines below it are more indented.

[pedrorrivero]

Yeah, I figured... just wanted to let you know (and leave a record) that the solution does not work in general. In case someone else gets to this thread in the future.

[munael]

I think fine control on folding is not exactly what we're looking for when raising this issue.

At least, in my case it was the need to see function signatures while functions are collapsed.

So as an extension to the current behavior, how about adding a configuration for:

1. Current behavior: Folding indicator starts at def and folds the entire definition. Only the first line is visible in the collapsed text.
2. Optional behavior: Folding indicator starts at def OR the end of the signature and folds only the function body. There's one single folding arrow. If this option is activated, function signatures are never folded.

This configuration should be toggle-able in an open file without changing the global, workspace or folder settings json.

cc @debonte