Formatter: Specify indentation for function parameters

[LeonarddeR]

The current indentation behavior for function parameters is: 4-space indentation at function definitions, like this:

def my_function(
    my_function_arg_1,
    my_function_arg_2,
    my_function_arg_3,
    my_function_arg_4,
):
    pass

This leads to reduced readability, because the function name and the argument names become harder to distinguish.

Adding one more level of indentation greatly improves readability:

def my_function(
        my_function_arg_1,
        my_function_arg_2,
        my_function_arg_3,
        my_function_arg_4,
):
    pass

PEP8 also has the same suggestion: https://peps.python.org/pep-0008/#indentation

Originally posted by @jsh9 in #7310 (comment)

[T-256]

def my_function(
    my_function_arg_1,
    my_function_arg_2,
    my_function_arg_3,
    my_function_arg_4,
):
    pass

This leads to reduced readability, because the function name and the argument names become harder to distinguish.

I don't agree with this because it's rare in the wild to all parameters starts with fullname of function/class name.
BTW, in my view it's not reducing readability (this may differ for you).

[MichaReiser]

I think this is the same as #8360

[dhruvmanila]

I think this is the same as #8360

@MichaReiser Can you update the comment to link the correct issue? Currently, it's referring to itself ;)

[MichaReiser]

Why do I always do this... 🤦 I'm trying to find the issue again but can't for some reason. I saw it before. I'll re-open this in the meantime.

[rwightman]

I don't see why there is any need to downvote this, this a contentious issue based on numerous heated issues in black, etc that you can look up. The question is not whether you like it but whether there are enough who do.

The proposal is not to change the default, or force one way or another, but hopefully have a configuration option so that those of use who much prefer combining the PEP-8 recommendation of an extra indent level for function args with sad-face can do so.

Also, it is not just about readability in the contrived case where the args happen to match the function name, I feel the different alignment aids readbility regardless.

[jsh9]

def my_function(
    my_function_arg_1,
    my_function_arg_2,
    my_function_arg_3,
    my_function_arg_4,
):
    pass

This leads to reduced readability, because the function name and the argument names become harder to distinguish.

I don't agree with this because it's rare in the wild to all parameters starts with fullname of function/class name. BTW, in my view it's not reducing readability (this may differ for you).

@T-256 you might be missing my main point there.

Even with different names, it's still not very readable:

def perform_some_tasks(
    data: List[float],
    arg2: Union[int, str, bool],
    hello: Optional[int],
    good: Dict[str, Any],
    morning: float,
) -> None:
    ...

Look at this instead (much more readable):

def perform_some_tasks(
        data: List[float],
        arg2: Union[int, str, bool],
        hello: Optional[int],
        good: Dict[str, Any],
        morning: float,
) -> None:
    ...

[LeonarddeR]

@rwightman wrote:

The proposal is not to change the default, or force one way or another, but hopefully have a configuration option so that those of use who much prefer combining the PEP-8 recommendation of an extra indent level for function args with sad-face can do so.

Thanks for highlighting this. Indeed, it was not my intention to advocate for this to become the default in any way.

[jankatins]

Just FYI: I downvoted this issue because I find any config for the format a negative thing, because it leads to longwinded bikesheding discussions and I really love the way black handled it: have some guiding principles (make diffs as short as possible, which means the indent should be as short as possible to not result in line breaks) and then take a decision and be done with it. The amount of time spent on discussing and/or tweaking styles (both on these issues/PRs or your own projects when you change some config) will (in my opinion) never be outweighed by any gains you have because some formatting is a tiny bit more readable than what black or now ruff does.

(and yes: been there, done it, will never get the time back I spent on making intelij format SQL the way I wanted it to... And also not the time I spend on resolving merge conflicts because I thought aligned AS was a good thing...)

[T-256]

Even with different names, it's still not very readable:

Still, it's readable into my eyes, I think it's a personalization choose but perhaps modern editors with syntax highlighting solve your problem:

def perform_some_tasks(
    data: List[float],
    arg2: Union[int, str, bool],
    hello: Optional[int],
    good: Dict[str, Any],
    morning: float,
) -> None:
    ...

def perform_some_tasks(
        data: List[float],
        arg2: Union[int, str, bool],
        hello: Optional[int],
        good: Dict[str, Any],
        morning: float,
) -> None:
    ...

I disliked because I'd not like to encounter codebases with this option enabled, the reason is that going to show lines fat, and in syntax colorized editor it's uglier. (This is my taste, maybe it is different for youً!)

[josephsl]

Hi,

While indenting function arguments one extra level may not be readable for some, it may help programmers who must use alternatives to sight to program - several screen reading technologies include a feature to announce indentation level (one of them provides an option to announce indentation with audio). For example:

def my_function():
var1 = some_value

Versus:
def my_function(
var1 = some_value,
):

To most of us, the presence of comma at the end makes it clear that we are passing a keyword argument to this function. However, for people relying on assistive technologies (especially screen readers), programmers must infer from surrounding code (or subtle changes to output by text-to-speech engine as configured by the screen reading technology), unless they listen to speech output carefully, they may not know where function body starts and ends. A counterargument could be that blind programmers can ask the screen reader to announce all punctuation, and some would cite productivity as a reason to not take up that alternative. Another alternative is to ask people to use type hints in function definitions, but not all developers may heed that advice (type hints do inform programmers that we are reading function signature, not the body itself, quite useful if arguments are written on the same indentation as rest of the function body).

I understand that what I wrote above opens up a can of possibly unnecessary discussions, but I think it is also important to think about readability from the perspective of those who may not see what we wrote and must rely on alternative modes to figure out what's going on.

Thanks.

[rwightman]

Still, it's readable into my eyes, I think it's a personalization choose but perhaps modern editors with syntax highlighting solve your problem:

I use a 'modern editor', PyCharm, and it defaults to the extra indent level (continuation indent 8) for formatting because it's following PEP-8. Again, the extra indent is PEP-8. Sadface is not, but I do prefer sadface in combo with this.