Formatter: Allow configurable soft-indent width (vs. hard/block indent)

[jeremy-hiatt]

Consider the indentation of the following example function, taken from the documentation, as produced by ruff format:

def _make_ssl_transport(
    rawsock,
    protocol,
    sslcontext,
    waiter=None,
    *,
    server_side=False,
    server_hostname=None,
    extra=None,
    server=None,
    ssl_handshake_timeout=None,
    call_connection_made=True,
):
    """Make an SSL transport."""
    if waiter is None:
        waiter = Future(loop=loop)

    if extra is None:
        extra = {}

The formatter uses a "soft indent" of 4 spaces to allow the parameter list to span multiple lines, which also aligns with the "block indent" used for the function body. The if statements introduce a further block indent to increase the indent level.

In my opinion, the "soft indent," which may be optionally used to wrap within parentheses and brackets, should be easily visually distinguishable from the mandatory hard indent, which affects control flow.

Would the ruff maintainers be interested in merging a PR that would introduce a new option (something along the lines of soft-indent-multiple) that would allow the user to specify an alternate indentation width for soft indents?

For example, setting the soft-indent-multiple = 2 would produce the following output:

def _make_ssl_transport(
        rawsock,
        protocol,
        sslcontext,
        waiter=None,
        *,
        server_side=False,
        server_hostname=None,
        extra=None,
        server=None,
        ssl_handshake_timeout=None,
        call_connection_made=True,
):
    """Make an SSL transport."""
    if waiter is None:
        waiter = Future(loop=loop)

    if extra is None:
        extra = {}

Obviously a personal preference, but I think it's valuable to see a clear visual difference between the parameters list and the function body itself. It makes it easier for me to skip past the parameters (there are a lot for this function!) and get to the code itself. In the default-formatted output, the only visual break is from the closing paren and colon.

If this is something that could be merged, I'm happy to open a pull request with all necessary code and tests to add this as a configurable option.

[yoann9344]

So if I understand well, this :

class Ssl(
    rawsock,
    protocol,
):
    def _make_ssl_transport(
        rawsock,
        protocol,
    ):
        def _make_ssl_transport(
            rawsock,
            protocol,
        ):
            if plop(
                rawsock,
                protocol,
            ):
                ...

Will become, with soft-indent-multiple = 2 :

class Ssl(
        rawsock,
        protocol,
):
    def _make_ssl_transport(
            rawsock,
            protocol,
    ):
        def _make_ssl_transport(
                rawsock,
                protocol,
        ):
            if plop(
                    rawsock,
                    protocol,
            ):
                ...

Or is it only for private functions ?

class Ssl(
    rawsock,
    protocol,
):
    def _make_ssl_transport(
            rawsock,
            protocol,
    ):
        def _make_ssl_transport(
                rawsock,
                protocol,
        ):
            if plop(
                rawsock,
                protocol,
            ):
                ...

But the the option naming seems ambiguous (soft-indent-multiple). It is like full indent will be multiply, this way :

class Ssl(
        rawsock,
        protocol,
):
    def _make_ssl_transport(
                rawsock,
                protocol,
    ): 
        def _make_ssl_transport(
                        rawsock,
                        protocol,
        ):
            ...

PS : To distinguish better functions parameters, did you try to change your highlight colours for functions definitions ? 🙄 You can use pygments or for more config you can use Tree Sitter by example for nvim. With tree sitter you can, by example, put a brighter colour for functions parameters.

[jeremy-hiatt]

Hi @yoann9344 , your first example matches my expectation. Yes, I agree that syntax highlighting may help with readability here, but I still think deployment of whitespace is an extremely important tool.

As for your comment about the option name, my intent was to make it orthogonal to the chosen indent width or method, but I do understand why it could be confusing. The idea is to multiply the specified factor against the indent width to compute the additional indent required. For instance, with an indent-width of 4, and a current indent depth of 2, then each line at the current indentation level is indented in by 8 spaces. When beginning a new soft indent, it would add indent-width * soft-indent-multiple = 4 * 2 = 8, so 8 additional spaces for the soft-indented lines. Do you have any ideas on a name that captures the intended behavior?

[yoann9344]

@jeremy-hiatt I'm can of perplexe, more indentation is only useful on a code where you don't have any colour and traversal control. It is also easy to jump method to method at desired level. Anyway, possibly a matter of taste than a question of settings.

I still don't see a multiplication, I see an addition. It adds one indent to functions parameters. So maybe add-indent-parameters and then we could even imagine another setting for function calls arguments add-indent-arguments (for functions calls on multiple lines).

[MichaReiser]

Would the ruff maintainers be interested in merging a PR that would introduce a new option (something along the lines of soft-indent-multiple) that would allow the user to specify an alternate indentation width for soft indents?

I don't think that we would add such an option today. We consider adding more option in the future but our primary aim for now is black compatibility. There's a similar request that we track in #8360, except that it requests to add more indentation rather than less.

There's also a technical question where it's unclear to me how this style would be implemented when using indent-style=tab.

[jeremy-hiatt]

Hi @MichaReiser , thanks for your prompt and candid reply. I did not realize there was already a similar issue raised. Unfortunately when talking about indentation there seems to be different terminology used, and I missed that this topic had already been discussed. I used the term "soft indent" because that seemed to be the term used within the formatter, but it looks like PEP8 calls it a "hanging Indent," and that issue just refers to the function parameter indentation alone.

I'm a bit confused by your statement here:

[...] it requests to add more indentation rather than less.

I think my proposal actually tracks closely to what's discussed there: add more indentation on function parameters. There's one additional piece to mine though which is that it would treat all hanging/soft indent cases similarly, and not have a special case just for functions.

Regarding the use of tabs, it looks straightforward to me at first blush, but maybe there's some complexity I'm overlooking? E.g. indent by an additional tab within the soft-indent block.

From reading the discussion in #8360, it sounds like the team was willing to consider a change that would implement that behavior, though I certainly understand the cost of maintaining features within the codebase. If I were to open a PR do you think you could commit to a good-faith review?

[MichaReiser]

I liked the terminology because it clarified that it applies to all indent and isn't function-specific.

I'm a bit confused by your statement here:

Yeah sorry, your correct. Both request to add more indent.

Regarding the use of tabs, it looks straightforward to me at first blush, but maybe there's some complexity I'm overlooking? E.g. indent by an additional tab within the soft-indent block.

Again, I misread your option. I read it as allowing different indent widths, which wouldn't work because a tab only has one specific width. So the solution would be use a different number of tabs.

From reading the discussion in #8360, it sounds like the team was willing to consider a change that would implement that behavior, though I certainly understand the cost of maintaining features within the codebase. If I were to open a PR do you think you could commit to a good-faith review?

At the moment, I consider it unlikely that we merge any such PR. The main value proposition that many see in Black/Ruff is that it removes the formatting discussions. But having only few configuration options means that the formatter can't be used by many that don't agree with every the decision the formatter makes. We haven't yet decided on what the right balance is and, therefore, are leaning towards fewer options for now. We intentionally keep style requests open to track the interest in them and use that information to make a decision.