change: Make signatures formatting more consistent?

[pawamoy]

Reported on Matrix.

One rather small nit with signatures, when using separate signatures formatted by Black, is that the formatting varies depending on how many arguments there are and how long they and their possible types and default valus are. All these formats are possible:

compact(arg: int) -> bool

semi_compact(
    first_arg: int, second_arg: int
) -> int

verbose(
    first_arg: int = 1,
    second_arg: int = 2,
    third_arg: int = 3
) -> int

I undertand why the format changes and it isn't a big problem, but it is still somewhat confusing and inconsistent if two functions in same module have different signature formats. It would be great if there was a way to force the verbose style to be used always or, perhaps better, always when there's more than one parameter. Unless Black has a such configuration option this may be too hard to implement, though, and Black isn't known for supporting much configuration.

[pawamoy]

My answer there:

You're right, won't be possible if black doesn't allow it. The second and third examples are bothering me in that they don't append trailing commas. I think Black has a setting for that? But even then, formatting once will append the trailing comma, but it would need a second formatting to actually break each param on its own line. I think that's one of the things Ruff does differently, exactly to avoid the need for double-formatting. Anyway I'll see what we can do :)

I'd like to switch to Ruff at some point, but we'll need a Python binding to avoid spawning tons of subprocesses.

[pekkaklarck]

As I wrote in the discussion, I wouldn't like trailing commas be added to signatures if they aren't in the source code already. They have a benefit that they make diffs smaller if items are added at the end, but at least less technical users could be confused. Ideally there could be an option to control this behavior, but even then the default should be respecting what's in the source.

[pawamoy]

Respecting the source will be tough, as we would have to reimplement parts of Griffe to use CSTs instead of ASTs. That's kinda of a goal though, as it would unlock nice use-cases, but it's just tough to achieve, so will need time :slightly_smiling_face: