Formatter: Beta feedback

[charliermarsh]

This discussion aimed to collect feedback on the formatter alpha and beta. Now that the formatter is stable, we ask you to create a new discussion or issue if you have feedback that you want to share.

The Ruff formatter is out now as a Beta release, as of Ruff v0.1.2.

This Discussion exists to collate open-ended feedback on the formatter beta. (Bugs and undocumented deviations should instead be filed in the issue tracker.)

Are there capabilities that preventing you from migrating? Formatting deviations that don't work for your project? Is the formatter the greatest piece of software you've ever used? Let us know -- we'd love to hear from you.

---

The Ruff formatter is designed as a drop-in replacement for Black, with an excessive focus on performance and direct integration with Ruff. At present, it achieves over > 99.9% compatibility on Black-formatted projects like Django and Zulip.

We consider the Beta production-ready. Between the Beta and Stable release, we'll be focused on:

• Support for Black’s preview style. (The Beta release is limited to supporting Black’s stable style.)
• Support for range formatting in our language server and editor integrations.
• Support for formatting within f-strings.

During the Beta, we are especially interested in feedback on (1) formatter configuration, and (2)
deeper integrations between the formatter and the linter. We'd love to hear from you.

For more on the formatter's design goals, and instructions on using it from the CLI or VS Code, see the documentation.

P.S. This Discussion was previously used for feedback on the Alpha release.

[alkatar21]

Great work you guys are doing here. I would like to try it, but since all the projects I am involved always use black with skip-string-normalization = true, I would be happy if this could be added?

[charliermarsh]

Do you mind chiming in on #7305? There's some discussion of --skip-string-normalization. In short, the formatter already supports using single or double quotes, but haven't wired up that setting to the configuration file yet.

[vastbluesky]

This looks fantastic!

It would be great if the Ruff formatter supported an option equivalent to --skip-magic-trailing-comma / -C in Black. When collections or function calls are shortened to the point where they would fit on a single line, I prefer for the formatter to automatically collapse them. For example, in Black the following:

x = [
    1,
    2,
]

will be formatted as:

x = [1, 2]

if --skip-magic-trailing-comma is used. Here's a Black playground link showing this behavior.

[konstin]

Internally, this is already implemented (https://github.com/astral-sh/ruff/blob/2d9b39871febdef1c5db75a2c9673dabcb86fbc1/crates/ruff_python_formatter/resources/test/fixtures/ruff/skip_magic_trailing_comma.py), we still need to figure out how to best expose the configuration.

[santigandolfo]

Is the formatter enabled by default or is there a rule code?

[zanieb]

If you have a preference this is a good place to leave some thoughts :)

[santigandolfo]

It would be nice to have it integrated into ruff check and have a rule code. BLK for Black or AF for auto-formattercome into mind)

[daveisfera]

Currently, we run ruff check and then black to apply formatting on save in our IDE. We'd love to switch to just doing it all with ruff, but currently we have to run ruff check --fix and then ruff format. It would be nice if there was a way to turn on format when running ruff check --fix.

[zanieb]

We are planning to integrate ruff format and ruff check into a single command but the design is still being decided.

[zanieb]

Progress for that feature can be tracked at #8232

[vmgustavo]

There is a big problem (imo) in black formatting fluent interfaces right now that could be a great improvement and argument in favor of ruff formatter if it is well impelemented. It is documented in this issue in the black repository and this comment has a good list of examples that could be used as reference.

Original Code

# no args, no assignment
foo_____________________________().bar_____________________________().etc_____________________________()
(foo_____________________________().bar_____________________________().etc_____________________________())

# args, no assignment
foo_____________________________(1).bar_____________________________(1).etc_____________________________(1)
(foo_____________________________(1).bar_____________________________(1).etc_____________________________(1))

# no args, assignment
x = foo_____________________________().bar_____________________________().etc_____________________________()
x = (foo_____________________________().bar_____________________________().etc_____________________________())

# args, assignment
x = foo_____________________________(1).bar_____________________________(1).etc_____________________________(1)
x = (foo_____________________________(1).bar_____________________________(1).etc_____________________________(1))

# args with trailing comma
foo_____________________________(1,).bar_____________________________(1,).etc_____________________________(1,)
(foo_____________________________(1,).bar_____________________________(1,).etc_____________________________(1,))
x = foo_____________________________(1,).bar_____________________________(1,).etc_____________________________(1,)
x = (foo_____________________________(1,).bar_____________________________(1,).etc_____________________________(1,))

Formatted Code

# no args, no assignment
foo_____________________________().bar_____________________________().etc_____________________________()
(
    foo_____________________________()
    .bar_____________________________()
    .etc_____________________________()
)

# args, no assignment
foo_____________________________(1).bar_____________________________(
    1
).etc_____________________________(1)
(
    foo_____________________________(1)
    .bar_____________________________(1)
    .etc_____________________________(1)
)

# no args, assignment
x = (
    foo_____________________________()
    .bar_____________________________()
    .etc_____________________________()
)
x = (
    foo_____________________________()
    .bar_____________________________()
    .etc_____________________________()
)

# args, assignment
x = (
    foo_____________________________(1)
    .bar_____________________________(1)
    .etc_____________________________(1)
)
x = (
    foo_____________________________(1)
    .bar_____________________________(1)
    .etc_____________________________(1)
)

# args with trailing comma
foo_____________________________(
    1,
).bar_____________________________(
    1,
).etc_____________________________(
    1,
)
(
    foo_____________________________(
        1,
    )
    .bar_____________________________(
        1,
    )
    .etc_____________________________(
        1,
    )
)
x = (
    foo_____________________________(
        1,
    )
    .bar_____________________________(
        1,
    )
    .etc_____________________________(
        1,
    )
)
x = (
    foo_____________________________(
        1,
    )
    .bar_____________________________(
        1,
    )
    .etc_____________________________(
        1,
    )
)

Expected Code

# no args, no assignment
(
    foo_____________________________()
    .bar_____________________________()
    .etc_____________________________()
)
(
    foo_____________________________()
    .bar_____________________________()
    .etc_____________________________()
)

# args, no assignment
(
    foo_____________________________(1)
    .bar_____________________________(1)
    .etc_____________________________(1)
)
(
    foo_____________________________(1)
    .bar_____________________________(1)
    .etc_____________________________(1)
)

# no args, assignment
x = (
    foo_____________________________()
    .bar_____________________________()
    .etc_____________________________()
)
x = (
    foo_____________________________()
    .bar_____________________________()
    .etc_____________________________()
)

# args, assignment
x = (
    foo_____________________________(1)
    .bar_____________________________(1)
    .etc_____________________________(1)
)
x = (
    foo_____________________________(1)
    .bar_____________________________(1)
    .etc_____________________________(1)
)

# args with trailing comma
(
    foo_____________________________(
        1,
    )
    .bar_____________________________(
        1,
    )
    .etc_____________________________(
        1,
    )
)
(
    foo_____________________________(
        1,
    )
    .bar_____________________________(
        1,
    )
    .etc_____________________________(
        1,
    )
)
x = (
    foo_____________________________(
        1,
    )
    .bar_____________________________(
        1,
    )
    .etc_____________________________(
        1,
    )
)
x = (
    foo_____________________________(
        1,
    )
    .bar_____________________________(
        1,
    )
    .etc_____________________________(
        1,
    )
)

[MichaReiser]

@vmgustavo this is an interesting proposal and I do find it more readable over all. Thanks for sharing. We have some ideas for improving the formatting too, but we intentionally defer implementing them for now to make it easier to migrate to ruff. This gives us the time to build the necessary tooling and processes to assess formatting changes: Some changes look good for a selected set of examples, but the formatting decreases readability for other, maybe even common, patterns. It then becomes necessary to tune the formatting or decide that the existing formatting is as good as we can do for now (not referring to your example, this applies in general).

[vmgustavo]

I agree. And I see ruff is already close to the best format, there are only 3 examples that the ruff formatter didn't do it so well and the only reason for it was that there were no parenthesis around the instruction.

[washeck]

Thank you for the formatter effort, it looks fantastic. I ran ruff on our blacked code base and then black again to see how they differ and besides the documented differences (please add #7314 to the docs) I encountered difference on multiline strings with function calls.

Our test suite has large SOAP examples written as

f"""<?xml version="1.0" encoding="utf-8"?>
...
</soap:Envelope>""".encode("utf8")

and ruff prefers it this way, black moves the encode argument on a separate line like

    </soap:Envelope>""".encode(
    "utf8"
)

In fact it seems to me that the only other issue we have is similar, because it relates to chain of function calls like

         ).spawn(some_very_long_argument_name, some_kwarg="with_some_value").spawn(
             another_long_argument_name, convey="foo_bar_baz_foo_bar_baz"
         ).convey("foo_bar_baz")

where black prefers to add newlines to the convey function call

        ).convey(
            "foo_bar_baz"
        )

[MichaReiser]

Thanks for the kind words and reporting this deviation that we need to document. We decided to accept it because Black's preview style uses the same formatting as Ruff playground.

It felt like a wasted effort trying to force our formatter to implement black's current style (it would have been rather difficult to implement), only having to undo it when the preview style becomes stable. But we certainly should document the deviation.

[Avasam]

Other than a bug (which I've raised) this is looking great! I know that the first steps is to be (mostly) equivalent to Black to help users migrate over. But here's a gripe I have with Black (and prettier in the JS/TS ecosystem), that I'd like to bring forth:

Force-unwrapping can lead to less readable code and more git changes

See my comment there #1904 (comment) and this discussion point about fluent interfaces here #7310 (comment)

tl;dr: Splitting off strings, ternary conditions, comprehensions and method calls/multiple attribute access into multiple lines increases readability. Unwrapping those decreases readability. And "magic commas" are not usable here.

A workaround is to add a bunch of # fmt: skip, but that's not great (and black itself crashes with comment in comprehensions)
Two possible solutions that I can see:

1. An option to never unwrap conditions, comprehensions, etc. (those that can't use a magic comma).
2. to only unwrap if unwrapping would stay under a certain (configurable) line length (ie: we use 80 as a soft cap, and 120 as a hard cap)
   This is kinda close to black's idea of 80 characters line-length + 10% = 88: https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#labels-line-length Where line length would be 88 and unwrap-line length would be 80

I ran Ruff on one of my repos currently using autopep8 and split off undesirable formatting into a single commit here to make it easier to preview a bunch of examples: Toufool/AutoSplit@629f04a (#259)

[MichaReiser]

This is an interesting idea and may be worth investing eventually. The main challenge that I see is how to implement this efficiently because:

• It requires higher and lower priority split points. Some split at the 80 limit, and others split at a 120 limit.
• It would require more back-tracking, slowing down the whole formatting

Ruff's 88 line limit is a best-effort line limit already. What's your motivation for using 120 over 88? Also see Prettier's explanation on this

[Avasam]

Thanks for the response and consideration. I can imagine it would complexify the logic, and whilst a similar idea to what I mention would be nice. What I really want at the end of the day, is for a formatter to not constantly unwrap code making it less readable, or complexifying git diffs by [un]wrapping similar code blocks near the line-limit. Or for a python formatter to better support fluent-style/method chaining.

---

Generally our teams try to stay under 80 chars (ie: soft limit, arbitrary number, but seems to be generally agreed upon in multiple style guides in multiple languages) with a more vertical and fluent style of programming. But we allow ourselves to go up to 120 (ie: hard limit, completely arbitrary number) in cases when it can be more readable (long strings, or when we're a few chars over 80, which is the idea behind Black's 88). Where only going past the "hard limit" will the code be force-formatted in JS/TS/C#/PHP/HTML (or blocked on CI if it can't automatically be split).
Hence the idea of a soft limit vs hard limit. (and I just re-use the same presets as my work's for personal projects)

We've had more instances of devs agreeing that prettier made our code less consistent or less readable, than we had style disagreements by using a rule that auto-wraps past our hard limit.

---

As a last unrelated note about why 120 specifically: out of habit, we set it at some point and never changed it. But, I'm strongly considering reducing it to something like 100 because 120 does sometimes go out of view in side-by-side comparison with a sidebar open. Whilst 100 always fits on modern screens that we use, even zoomed in.

[elenakrittik]

Thanks for inventing your time into this! Is customisability of rufformat's (dummy name i am using until an "official" one appears, "ruff python formatter" is a little verbose haha) one of it's future goals (possibly with built-in presets like black, google, etc.)? I originally switched from black to yapf due to it's great customisability and ability to match the exact styling i prefer, so if you're asking what prevents concretely me from migrating, is lack of configuration options.

[serjflint]

What must or mustn't be done is decided by the user imo. Many people (like me) do want docstrings formatted automatically, just like the code.

I think the current issue can be solved by introducing an option to turn off formatting for docstrings or string literals.

[pekkaklarck]

I'd also prefer a bit more customization. I don't like individual developers fighting over style in code reviews or otherwise, but I don't think a general purpose language like Pyyhon can really have a single style decided and enforced by a tool. Having general and enforced rules is fine, but I believe customization should be allowed on team/repository level. That can lead to bikeshedding on that level, but at least it won't affect individual commits or PRs. The team can also decide to follow whatever the tool enforces and stop all discussions.

[pekkaklarck]

For me the biggest reason I haven't adopted Black in my projects is that I really like to have an empty line above methods while Black forces me to use

class Example:
    def method(self):
        ....

Kind of a minor thing, but I don't like the inconstency of not having an empty line here. I also don't like Black's decision to prefer double quotes when Python itself uses single quotes (e.g. in repr("xxx")), but at least that can be configured.

[serjflint]

class Example:\n def method(self):

Won't there be a line if you add a docstring?

[pekkaklarck]

Could be. But I don't think internal classes that often need docstrings. Public ones obviously do.

[Zerotask]

So far no complaints, it's great. I'm really looking forward for ruff's future as a one-stop dev tool for python :)
(kinda thinking about a static type checker 😁)

[pjv]

Sorry for the tiny-ness and pedestrian-ness of my comment / question here, but my giant gripe with black is the fixed 4-space indent. I’ve recently started using ruff’s vscode extension for linting which seems to work fantastically, and just flipped on the formatter. I’m happy with everything it did to my code except the damn 4-space indents.

I noted a merge from last week that deals with tab-size configurability and my questions are:

1. when will this be functional in the vscode extension?
2. is there any way for me to use this option via the extension now (like compiling a dev version of ruff on my system and pointing the extension to that binary or something)?

[MichaReiser]

I'm working on it but there it requires some changes to how we structure our linter settings and want to support the old structure for some time. Making this happen takes a bit more time. I hope to get configuration support (for ruff.toml / pyproject.toml) in one of the next releases. Stay tuned; we'll mention it in the release notes when it is ready

[MichaReiser]

I'm trying to decide on how to model the indentation configuration options for ruff. You mention that your preference is an indentation other than 4 spaces. Do you prefer tabs or a different number of spaces?

I'm bringing this up because the Python community seems to have mostly settled around 4 space indentation or using tabs (with a customizable width). That's why I'm wondering if a tab-width (or tab-spaces) setting is sufficient or if it should be possible to configure the number of spaces too.

[pjv]

Personally, I write all my own code with 2 spaces indentation. That’s across all languages. I have 2 spaces configured as the global default in Codium (VS Code). From my POV, first best would be for ruff to respect the global default setting. Second best would be for ruff to have its own separate setting that lets you choose either tabs or spaces and then if spaces, let you enter any arbitrary integer (within reason) as the number of spaces to use. Worst would be to give me no choice like black does.

However, if I’m hacking on someone else’s code or contributing to an open source project that uses a different indentation standard than me, it’s also important that ruff let me respect those formatting choices on a file by file basis. Codium seems to be able to parse and expose a given file’s indentation structure and if I’m working on something that uses tabs or 4 spaces or 8 spaces or whatever, I don’t want my formatter to re-format the whole file because I added one line somewhere.

Would also be excellent if ruff could parse and respect any indent-related settings in a project’s .editorconfig file.

[warsaw]

FWIW, python-mode for Emacs does a pretty good job of inferring the indentation in an existing source file. It's not foolproof of course. I forget whether it punts or complains when you have mixed indentation depths, which I think everyone can agree is not good. Even worse is mixing tabs and spaces.

IMHO, tabs are always problematic because they present inconsistently depending on your code editor. If you use tabs and set tab-width to 8 but I set it to 4, we see different layouts.

Historical fun fact: Way back in the day, the Python source in the repo was 4 space indented (and IIRC, Guido always preferred that, which is why I always use 4 space indents today), but the C source was 8 space indented (or was it tabbed? I forget!). We lived with that for a long time before a mass reformatting some time in the misty past.

[eli-schwartz]

I forget whether it punts or complains when you have mixed indentation depths, which I think everyone can agree is not good. Even worse is mixing tabs and spaces.

I would love an interpreter level SyntaxWarning for that. :P I was genuinely surprised when I discovered it was even legal to execute the latter case.

[vanchaxy]

I recently tested Ruff on your project, specifically in a scenario where we use the black formatter with the --skip-string-normalization option, and Ruff's autofix feature for formatting quotes. It appears that Ruff's formatter enforces the use of either single or double quotes uniformly throughout the codebase. However, I noticed that the flake8-quotes rules, which Ruff implements, offer more flexibility in configuration. They allow you to specify your preferred quotes for different contexts such as docstrings, inline code, and multiline code, and also provide an option to avoid escaping characters.

Is there any way we could align Ruff's quote formatting with the more flexible configuration options provided by flake8-quotes?

[alkatar21]

I opened #7615 for docstrings, as PEP 8 is relatively clear about what they should look like (""").

[johnthagen]

I haven't seen it discussed yet, but have you considered supporting optionally sorting imports within the ruff format command?

Many people that use black also use isort to sort their imports. And Ruff can already replace isort 🎉 .

One of the papercuts about this is that often you want to both format your code and sort your imports together (or validate that this is correct). Currently you need to do something like:

ruff check . --select I --fix
black .

And then this needs to be duplicated when you want to check just the formatting in CI:

ruff check . --select I
black --check .

Real world example:

• https://github.com/johnthagen/python-blueprint/blob/2c266cf4e851feca871998b4e6f2e069ae61740a/noxfile.py#L30

What if ruff format supported something like:

ruff format --sort-imports

which would also sort your imports based on the config in (optionally defaulting to the isort default if none is provided?)

[tool.ruff.isort]

Then users would only ever need to know a single command to change anything about their source code. I think it would also make import sorting more discoverable for new developers.

This would also allow IDEs to fully outsource all formatting (sorting and formatting) to Ruff.

[konstin]

In general, yes, sorting imports in the formatter would be great. Unfortunately, the import order can technically change the meaning of a program, while we see the formatter as something that never changes the semantics of your program. Imagine e.g. an __init__.py that change sys.path so that a subsequent import comes from a different directory.

Our goal is to go the direction and integrate the formatter into the linter, so you can do ruff check . --fix and have isort and the formatter applied :)

[johnthagen]

So in the hypothetical future, you are imagining we could have something like:

ruff check . --select I --select FMT --fix

To allow the user to fix only import sorting and formatting? That would be a nice solution (if not still a little wordy). Maybe an alias could help.

[zanieb]

There are ideas of that (and similarly ruff check . --select I --format --fix) or ruff fix --select I --format. We're definitely interested in usable single command interfaces but it's tough to get right so we're not rushing into it :) We have several options sketched out.

[zanieb]

Further updates for this will be tracked by #8232

[johnthagen]

Have you considered (I assume yes, since Ruff is written in Rust 😉) to instead of naming the command:

ruff format

To use:

ruff fmt

To make it shorter? This also matches the previous art in cargo fmt.

[zanieb]

We are considering supporting fmt as an alias but I think we're going to generally stick with a consistent form for command names, e.g. why is check unshortened?

[jsh9]

Hi, I'd like to open up a discussion thread on the indentation width at function definitions. My feedback/request is: can the Ruff Formatter implement a toggle to turn on/off the 8-space indentation? (Toggle on: 8 spaces; toggle off: 4 spaces)

Black's default behavior 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 would lead 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

There have been a lot of discussion on adding this feature (8-space indentation) in Black's issue board. Black's developers did not implement this.

Here are the feature requests that I can find:

• Continuation lines defined by extra indentation grantjenks/blue#89
• Comply with PEP-8 for indentation of parameters in function definition grantjenks/blue#90
• Black does not create pylint-compatible code psf/black#1127
• Adjusting to PEP8 Style for function with long list of parameters psf/black#2117
• Black violates pep8 recommendation with long argument list psf/black#1178

I'm also tagging the people who I think are in favor or this feature here: @jni, @flexatone, @Martmists-GH, @stefanoborini, @mintchkin, @nbievre, @veritas9872, @nilsbunger, @LeonarddeR. (This is not an exhaustive list by any means.)

[eli-schwartz]

I have typically found that incremental migration doesn't help a lot with review when done directory by directory, but does help a lot when done on the entire project, one lint rule at a time.

[stefanoborini]

Thank you for tagging me. I would actually put the frown on the last line, or at least make it configurable if it needs to go on a line on its own or not. Personally, I think that the additional diff line is a dumb argument. Is it that of a problem to have an additional diff line in that context?

[rwightman]

I would love love love support for this. Number 1 blocker re never adopting black.

Although do recognize the location of sadface is up for debate and should probably be configurable separately from the 4 vs 8 spaces for args. My preference of the below is 1 as per @jsh9 example.

def my_function(
        my_function_arg_1,
        my_function_arg_2,
        my_function_arg_3,
        my_function_arg_4,
):
    a = 1 + 2
    b = a * 3
    return b

def my_function(
        my_function_arg_1,
        my_function_arg_2,
        my_function_arg_3,
        my_function_arg_4,
    ):
    a = 1 + 2
    b = a * 3
    return b

def my_function(
        my_function_arg_1,
        my_function_arg_2,
        my_function_arg_3,
        my_function_arg_4):
    a = 1 + 2
    b = a * 3
    return b

def my_function(
    my_function_arg_1,
    my_function_arg_2,
    my_function_arg_3,
    my_function_arg_4,
):
    a = 1 + 2
    b = a * 3
    return b

[LeonarddeR]

Would it be best to create an issue for this request?

[LeonarddeR]

Filed #8360

[warsaw]

Ruff soon supports excluding files from the formatter.

That's very interesting for me because I am consolidating projects into a monorepo and each has a different set of formatting. Eventually I want consistency across all subpackages, but I want to do that incrementally. I've been trying to think of a way to do that, given that we share a global ruff.toml file and I can't specify formatting options on a per-directory basis.

[MichaReiser]

I can't specify formatting options on a per-directory basis

Do you mean you can't because of your project layout or because Ruff doesn't support it?

If it's the latter then you could make this work by having a pyproject.toml in each directory where you want to change the formatter settings and make it extend the default configuration (doc)

[warsaw]

At the top of my monorepo I have a libs/ directory and under that, one subdirectory per subpackage. Also at the top-level I have a hatch.toml, mypy.ini, and ruff.toml. I want the top level ruff.toml because I want a consistent set of linting rules across all subpackages, and ideally/eventually, a consistent set of formatting rules. I use a top-level ruff.toml because there is no actual package at the repo top, so a pyproject.toml doesn't make sense.

I like ruff's lookup rules for ruff.toml (for mypy, I have to symlink from libs/subdir/mypy.ini up to the top level). I generally don't like to repeat myself because that road leads to inconsistency and kind of defeats part of the monorepo purpose. I accept that ruff doesn't combine configuration files - that totally makes sense from a simplicity point of view.

What might be kind of nice is something akin to per-file-ignores which lets me handle special cases even in subpackage subdirs. Spitballing:

[tool.ruff.format]
quote-style = [
    '* = single',
    'libs/subpkg1/* = double',
]

I think I'd only need that during the transition phase.

My planned workarouind will be to put a ruff.toml in the libs/subpkg dirs that don't yet conform to the overall monorepo rules. That does mean duplication of all [tool.ruff.*] sections of course, but I can accept that for a short term solution (if I can get each subdir owner to commit to the overall rule set -- we'll see!).

[zanieb]

Ruff does support merging configurations e.g.

Ruff supports an extend field, which allows you to inherit the settings from another pyproject.toml file...

[warsaw]

Oh, that might do it! Thanks!

[MichaReiser]

For reference, the PR that adds support for excluding files from linting/formatting only: #8000

[KraXen72]

Hi, i've tried out the formatter, and it's great!
however, i am missing a few features / don't know how to achieve them, when using the VSCode extension of the formatter

• Format Selection doesen't work, with an ambiguous error, Extension 'Ruff' is configured as a default formatter but it cannot format 'Python'-files
• I don't know how to pass cli args to the ruff formatter, for example, line length. I disabled line length in my global ruff config, so i don't get nagged about it, but i would like the formatter to use a set line-length, because i usually run just Format Selection on some parts of the code.
• I would like to configure the formatter to use tabs instead of spaces. I know this is planned, and i can't wait! right now, i have to hit the hotkey for Convert Indentatoin to Tabs in VSCode after formatting.
  • i managed to achieve this by doing:

  # ruff.toml
  [format]
  indent-style = "tab"

• it would be also useful, if the formatter itself could convert singe/double quotes to their equivalent, but this is mostly handled by ruff's rules and auto-fix, so it's a non-issue for now.
  • i managed to achieve this by doing:

  # ruff.toml
  [format]
  quote-style = "double"

Please let me know if the way i'm currently configuring the formatter is incorrect/hacky. Thanks!

Apart from these, it works superb! I've been trying to find a good replacement for yapf, since VSCode is deprecating it soon. Thanks for all the awesome work on ruff!

[T-256]

• Format Selection doesen't work, with an ambiguous error, Extension 'Ruff' is configured as a default formatter but it cannot format 'Python'-files

Range formatting is not supported yet (#7233)

[zanieb]

We're working on range formatting! It'd be ideal if we threw a better error message there though if possible cc @charliermarsh

I don't know how to pass cli args to the ruff formatter,

We're still considering a general API for overriding single settings via the CLI. I would expect something before too long but probably not until the formatter is stable.

[charliermarsh]

I can fix that tomorrow -- it looks like Black just does this:

I don't know how to pass cli args to the ruff formatter.

In your specific case, could you set the line length in your global config, but disable E501 so it isn't linted against, only used for formatting?

[charliermarsh]

Although there's a whole thread of people who really dislike this behavior: microsoft/vscode-black-formatter#176

[KraXen72]

well, it's probably fine not implementing an error message if range selection is gonna be supported in the future anyway.

Thanks everyone for the quick replies!

[daaniam]

Hello,
is or will be there an option in pyproject.toml to run formatter by default? Similar to fix=true. Something like formatter=true.

[MichaReiser]

We plan to integrate the formatter into ruff check, including ruff check --fix. See #8232

[zyv]

Hi @MichaReiser and @konstin ,

We are very excited to move to ruff formatter from black, but as we use it to reformat tons of auto-generated code among other things, lack of complete E501 auto-fixing is a deal breaker for us.

Currently we have identified following areas, where ruff format is still not able to autofix our auto-generated code:

1. Long docstring comments
2. Long string values
3. Long chained method calls
4. Inline comments

How do we go about it? Would it help to create issues for ruff formatter? Do you already have issues? Would you be up to fixing it, or your opinion is that you are not going to fix this in principle?

For now we are considering the workaround of adding file-level #noqa: E501 to our generated code until we see a way forward with that.

/cc @IamAbbey @haidarCheaito

[MichaReiser]

Hi.

Thanks for the kind words.

We plan to change the formatting in the stable release to wrap long string values automatically, but that will take some time to implement and only solves some incompatibilities with E501.

What's your motivation for using E501 alongside the formatter and in generated code?

I would use the formatter to make the generated code look prettier but disable E501 for the generated code by using per-file-ignores to avoid the inline noqa: comments.

[zyv]

Hey Micha,

Thanks for the quick reaction! We are very impressed by the professionalism of the ruff community, communication and quality of the tools.

Our motivation for using E501 for autogenerated code is readability. Of course, one can argue that it doesn't matter how the autogenerated code looks like, because it's not supposed to be edited by humans.

However, nice and clean looking auto-generated code (which is actually possible with Python) makes debugging a lot easier, and on top of that, you can read it while programming directly, instead of referring to the documentation.

Consider this class, which is automatically created from the OpenAPI specification:

class ProductRelatedField(rest_framework.serializers.Serializer):
    """ Eins der individuell für ein Prämienprodukt definierten Felder. Hat jeweils einen eindeutigen Namen, der Wert wird immer als String übergeben oder ist null. A field which is defined only for a certain product. Has a unique name, the value is always a string or null.  """
    feldname = rest_framework.serializers.CharField(required=True, allow_null=False, help_text=None, allow_blank=False, trim_whitespace=False, min_length=1)

If the docstring is nicely paragraph-wrapped, this becomes much more readable and clean. Of course, we can add some additional code for that in the generator, but it's hard and error-prone, and generally feels like the wrong level to operate upon.

Another example with a string value (can be solved with ("" "" "") with breaks on spaces):

class ContractPart(rest_framework.serializers.Serializer):
    versichertePerson = rest_framework.serializers.CharField(required=False, allow_null=True, help_text="Falls vom Versicherungsnehmer abweichernd, vollständiger Name der versicherten Person (Vor- und Nachname oder Firmenname). Kfz-Kennzeichen im Falle einer Kfz-Versicherung. If the policy holder is different from the insured person this field holds the full name (first name and last name) of the insured person. In case of a vehicle insurance this will hold the license plate. ", allow_blank=True, trim_whitespace=False)

This would also make the class clean and well-readable.

Anyways, we are going to implement your suggestion with ignoring the rule for directories where the generated code resides for now. For most of our generators it's a tenable solution and nicer than littering the generated code with per-file ignores.

[MichaReiser]

Thanks for explaining. That makes sense. I can't offer you a better solution today, but maybe, someday, ruff will support docstring formatting (and inline comments) to improve autogenerated code.

related issue for the improved string formatting: #6936

[konstin]

For the docstring formatting, i think this would more sense as a lint rule with an opt-in autofix then as a formatter rule. I would format your example as

class ProductRelatedField(rest_framework.serializers.Serializer):
    """Eins der individuell für ein Prämienprodukt definierten Felder. Hat jeweils einen
    eindeutigen Namen, der Wert wird immer als String übergeben oder ist null. A field
    which is defined only for a certain product. Has a unique name, the value is always
    a string or null.
    """

    feldname = rest_framework.serializers.CharField(
        required=True,
        allow_null=False,
        help_text=None,
        allow_blank=False,
        trim_whitespace=False,
        min_length=1,
    )

This is technically a different docstring (an AST change), which the formatter shouldn't do (but the linter is free to do. EDIT: I'm on the fence for this because we already change docstring whitespace mainly because cpython does that to, there's certainly an argument to be made reflowing long docstring lines is fine for the formatter to do). For the second string example, as micha said yep that's on the list for preview style.

[Giuzzilla]

I was checking the various options for tool.ruff.format and in particular I wanted to add additional exclusions to the formatter (in addition to the exclusions in tool.ruff.

The documentation of this option can be found at: https://docs.astral.sh/ruff/settings/#format-exclude

I found it a bit confusing to have exclude instead of extend-exclude (even if the additive behaviour is well-documented). I opened an issue (#8301) because there's a wrong mention of extend-exclude there, but maybe you could consider renaming this kind of additive exclude to extend-exclude?

[mrcljx]

Re E501 comment: Should the conflicting lint rules section have a call-out regarding E501 like the FAQ entry on Black? For example:

We also recommend disabling line-too-long (E501) which blindly enforces line length. Similar to Black, the Ruff formatter avoids line-wrapping in some cases (e.g. long strings, docstrings, and pragmas).

[charliermarsh]

Sounds good -- will add.

[q0w]

E203 also should be added?

chunks = [data[pos: pos + chunk_size] for pos in range(0, len(data), chunk_size)]

Linter removes whitespace and formatter adds it

[jab]

Just tried using ruff as a drop-in replacement for black, with which I use the "preview" style, but stopped to post here when I noticed that ruff is inserting unwanted blank lines between the @typing.overload-decorated variants of the same function, while black (with "preview" mode) does not.

Here is one example of changes that ruff format wants to make to my black-formatted code:

Can ruff add support for opting out of the blank lines between overload variants?

Ref: psf/black#1797

[ofek]

A new line between each is the correct behavior.

[MichaReiser]

Thanks for reporting this deviation. Ruff only has partial support for preview style yet. You can follow the implementation status of preview style in #6935

[jab]

@MichaReiser, thank you very much, and great to hear that support for this is planned.

I created a dedicated issue for this that the last list item in the umbrella issue can link to:

Hope this is helpful, and thanks again.

[q0w]

Does the ruff formatter respect settings in ruff.toml?

[format]
line-ending = "lf"
quote-style = "single"

This does not work, only in pyproject.toml

[MichaReiser]

Yes, configuration options should be respected in ruff.toml and pyproject.toml as far as I know. For pyproject.toml, the section must be tool.ruff.format. Could you open an issue with a sample configuration and file if using ruff.toml isn't working for you.

[q0w]

It was my fault, sorry.

[celynw]

I'd like a --line-length option for ruff format. I know that pyproject.toml and ruff.toml are respected, they will work for linting and formatting. But at the moment it's a bit asymmetrical between ruff check and ruff format?

Without the config files, had some confusion with the VSCode extension. My ruff linter would only complain when lines are over 120 characters long, but saving would wrap lines down to 80 characters. The only way to stop that from happening seems to be to add a config file.

Has this been omitted on purpose? I couldn't find any discussion about this in the issues (besides in a comment in this discussion)
Thanks for the amazing work!

[zanieb]

Thanks for commenting!

Would you expect of the other formatter settings to be available via the CLI? The format command is asymmetrical because we're being more cautious about what we expose, trying to stick to a consistent pattern. We intentionally removed --line-length #8131 although we are re-considering that choice.

Would a --setting format.line-length=... option work for you?

[celynw]

Thanks for linking that PR. I understand the intention.

Would you expect of the other formatter settings to be available via the CLI?

I guess not. And I see why it might seem like this would be an exception to a consistent pattern.
On the other hand, this setting is also a CLI setting for black.
Since the Ruff formatter is designed to be a drop-in replacement for black, I feel it ought to be possible for users to replicate the black experience without having to create a config file. I'm not suggesting the command arguments should be identical! Something like --setting format.line-length or whatever would be fine? No strong feelings!

[zanieb]

Discussion at #8363 and #8368

[Booplicate]

Just my 2c. I've read that adding configuration will increase complexity (totally makes sense), but it'd be really nice to have. If not a choice of styles, then at least an option to disable certain formatting features (like unwrapping). You can deal with it using a comma, but you can't use it in a statement and the comma is generally an annoyance to me.

I'll also say that while being compatible with black is great for black users, I'm one of the users that don't like black for its lack of configuration. The same reason I dislike gofmt, they often make code less clear without a proper and easy way to disable such behaviour. I had less fights with the team for style than I had fights with the formatters, people can be reasonable, machines (unless allowed to be configurable :)) cannot be.

[eli-schwartz]

This sounds substantially the same as #7310 (comment) -- the reply from the Ruff maintainers (and particularly to the remarks I made in defense of configurability) is:

I understand your need and yes, it means that ruff's formatter isn't a solution for everyone.

Supporting slightly different styles like pynk could be something we might want to support eventually. I don't think we'll ever support style guides that deviate fundamentally because of the effort it requires to build it and maintain multiple style guides. And I think that's fine. Ruff's goal isn't to replace every formatter. You should feel free to use the formatter that fits your needs best. We may even want to integrate other formatters in the future so that running ruff format or ruff check calls out to the other formatters (may not be as fast) but we present you the diagnostics in a unified way.

So at the moment it appears this is not on the immediate roadmap, but there will probably be a compromise (set of) option(s), and we shall see how things shake out down the line.

[Avasam]

I have made a similar comment about unwrapping here: #7310 (comment) . Even with magic commas it's not always possible as they are not usable everywhere.

[Booplicate]

Yeap, I think just a never unwrap option would do the trick without complicating the system too much.

[1024Adam]

If I have indent-style set to "tab", when I run ruff format it is still converting indentation within docstring comments to be spaces, which then causes ruff check to fail on rule E101: Indentation contains mixed spaces and tabs

Before:

After:

Is there a format setting I can add to fix this? or is this a bug/intentional?

[MichaReiser]

Effectively that we could replace 8 space with a tab inside docstrings. The problems is that if you have 10 spaces you get one tab and two spaces, i.e. inconsistent indentation.

I think that's fine, because the indentation was inconsistent before. I'm more worried about what happens if the indentation was mixed before in combination with tab-width with a value other than 8.

I think we have to fix this or we need to warn about E101 when using the formatter and tab indentation. @1024Adam do you want to create a new issue for this? Otherwise I can.

[1024Adam]

@MichaReiser you can create the issue, that's fine with me. Thank you!

[MichaReiser]

For reference #8430

[konstin]

Just so that we're on the same page, this is how python 3.13 treats docstrings:

>>> exec('def f():\n\t"""Computes the value.\n\tx = 1\n\t\ty = x + 1\n\t"""')
>>> f.__doc__
'Computes the value.\nx = 1\n        y = x + 1\n'

Notice how the tab gets implicitly converted to 8 spaces.

---

Re E101, i think we should ignore the contents of multiline strings: #8443

---

For docstring indentation, i see three options:
a) Do what black and cpython do and expand tabs to 8 spaces and dedent. This leads to consistently mixed indentation between the docstring and rest of the code.
b) Expand tabs to 8 spaces, dedent, convert 8 spaces back to tabs. This can lead to mixed indentation. CPython will still normalize your docstrings at runtime or when generating docs.
c) Don't normalize docstrings when using tab indentation. CPython will still normalize your docstrings at runtime or when generating docs.
Which of these would you prefer?

[Mutantpenguin]

Will the value of indent-width be considered for this?

[kaddkaka]

I would love the formatter to allow more than one style and it will stay the way the programmer leaves the code. So a "non-opinionated" formatter. Sometimes style A is more readable, some other time style B. For example.

Let the programmer select whether the ending parenthesis should go on the same line or not. Could be configured to select allowed styles with a list, e.g.:

[tool.ruff.format]
arglist_closing_parenthesis_allowed_position = "same_line, separate_line" 

separate_line:

def perform_some_tasks(
        data: List[float],
        arg2: Union[int, str, bool]
) -> None:
    ...

same_line:

def perform_some_tasks(
        data: List[float],
        arg2: Union[int, str, bool]) -> None:
    ...

[kaddkaka]

To me, readability is the only goal of a formatter. "easy to edit" or "small diff" has low value in my book. Therefor I would like an option to let function call arguments be grouped on as few lines as possible. I will use a short line_length just for this examples sake:

def generate(
        rng: RandomGenerator, 
        configuration: Config, 
        style: str,
        num_pages: int, 
        language: str,
        include_pictures: bool) -> str:
    pass

# this call fits on two lines
generate(rng, config, cool_style, 10
         "romanian", include_pictures=True)

[eli-schwartz]

@konstin,

To the people such as myself that believe that black is a large collection of transformation rules for making code badly formatted with zero transformation rules for improving its format, and who look at black code and believe that in every conceivable point other than changes where black agrees with autopep8, that black has made the wrong choice and the bad tradeoff...

... pointing out that one bad choice may have been fixed is kind of missing the point.

Anyways, I don't trust black to be a good guardian of style so I would be entirely unsurprised if even this specific example is simply formatted a differently-bad way.

The underlying point is not that we want a specific style and "possibly black can be changed to provide that style" (I will believe it when I see it, which is to say: never) but rather that the mere act of creating a tool which tells people "you are a bad programmer if you believe it's valid for multiple styles to exist in multiple projects", has set computer programming back by ten years.

[tjkuson]

The underlying point is not that we want a specific style and "possibly black can be changed to provide that style" (I will believe it when I see it, which is to say: never) but rather that the mere act of creating a tool which tells people "you are a bad programmer if you believe it's valid for multiple styles to exist in multiple projects", has set computer programming back by ten years.

This seems like an unfair exaggeration; from what I have seen, opinionated formatters like Black's lack of customisation is less about calling people bad programmers for disagreeing with them and more about avoiding unproductive debates over which style is best.

The Ruff maintainers decided to support extra options in their formatter, despite the significant work it requires over just having one set style. I think it would be a real shame if they ended up regretting this descision.

[Booplicate]

I think that splitting function calls half way is terrible. It's hard to align what parameter is what, I prefer either keep it 1 line or 1 arg per line. However, I'd rather have the option than not. People should be able to format their code the way they like it, at least because they will maintain it in the future.

[Avasam]

@eli-schwartz small parenthesis on the note of autopep8, I've been tracking how close Ruff is to parity with it: #9057 (comment)

[eli-schwartz]

Nice! ❤️

[peterjc]

I note that the issue says "we are especially interested in feedback on (1) formatter configuration" but in the context of the formatter's design goals in the documentation which says:

The initial goal of the Ruff formatter is not to innovate on code style, but rather, to innovate on performance, and provide a unified toolchain across Ruff's linter, formatter, and any and all future tools.

If reading this with emphasis on initial, then a lot of the discussion above about changes to the black style are on off topic. Was that the intent?

Personally there are things in the black style I don't like, but accept as I don't want to get bogged down in style discussions - I would rather push for less style configuration options.

I interpreted this issue much more narrowly - configuration in the sense of non-style details like including/excluding files (e.g. what extensions to check, should it do automatic recursion into given directories), optionally confirming the AST didn't change, ways to apply the formatter to code blocks embedded in documentation (e.g docstrings, code blocks in RST, or verbatim code blocks in LaTex, as in the tool blacken-docs), or ways to run it as a server for integration into an editor.

[Edited as per comment below, on topic to off topic, see italics and strikeout]

[MichaReiser]

If reading this with emphasis on initial, then a lot of the discussion above about changes to the black style are on topic. Was that the intent?

Any chance you mean off topic instead of on? If so, then yes, this was the main feedback we were looking for. But the style feedback isn't entirely useless, it helped us identifying cases where black/ruff are still failing short today, even if it may not have been the original purpose of this discussion. This is also on us, because we didn't had/point users to a better place to report style innovation and it might be time to sunset this discussion and collect new feedback as regular issues instead.

[NeilGirdhar]

Personally, I think that the real future of code formatting is to make it significantly more intelligent. Think of something like latex that considers a badness for introducing line breaks in various places.

The ideal formatter would be something that considered the badness of various breaks in various places according to:

• extra vertical space—which is bad,
• making components of list/parameters more easily distinguished by virtue of being on different lines—which is good,
  • This is more important when the components are complex, which needs to be quantified by the algorithm.

The formatter should also consider vertical formatting as one of the options in my opinion. Vertical formatting uses less vertical space while maintaining separation. Because it uses more indentation, it's not always better; it can induce other unwanted breaks.

The line-breaking algorithm would need to be recursive since various break choices can affect other break choices. This can get quite complicated, so you may need to memoize results to maintain performance (dynamic programming).

In other words, I'm saying, the kinds of options we need are not just about what the formatter should allow itself to do, but about how it weighs the different options and chooses what to do.

[kaddkaka]

Both clang-format and yapf does this by setting a "penalty" for a lot of transformations.

[NeilGirdhar]

@kaddkaka Very cool. It appears that Ruff is doing something like this when formatting quotes for strings.

[tylerlaprade]

I just made the switch from Black to Ruff Formatter. This is so much nicer! I haven't been this excited since when I switched from Flake8 to Ruff Linter.

[charliermarsh]

Thank you @tylerlaprade :)

[Avasam]

I was gonna ask for help understanding this formatter edit (ran on 0.2.0), but I think I get it now.

Is Ruff trying to minimize escaped quotes? idk how helpful it really is if you still end up with escaped quotes anyway. Before, if I had to search for a string I knew that ' would never be escaped, but " could. Now either quotes could be.

With the current heuristics, maybe a triple-quoted string would be more appropriate for me here?

[MichaReiser]

Hy @Avasam Yes, you inferred the heuristic correctly. The idea is to pick the quote that requires the fewest escapes.

I like the idea of using a multiline string here. It removes the need for escapes altogether, making the code much more readable. It would be neat if ruff could detect this automatically but that's probably rather involved.