Formatter: Handling of `# region` & `# endregion` comments

[Avasam]

Region block comments

Is it possible to keep the alignement of # region / # endregion code-folding comments? Or at least keep them consistent between open and close?

---

copied from https://github.com/astral-sh/ruff/discussions/7310#discussioncomment-7341829

[MichaReiser]

I'm afraid. This isn't supported today. The formatter doesn't support the concept of region comments and always indents the comments to the same level as the statements.

I hoped that you could make it work by suppressing the comment but Ruff normalizes the indentation even in that case:

def test(test: name):
    a_long_body

# fmt: off
# region test
# more
# fmt: on    
    some_region

# fmt: off
# endregion
# fmt: on
    after_region

Gets formatted to

def test(test: name):
    a_long_body

    # fmt: off
    # region test
    # more
    # fmt: on
    some_region

    # fmt: off
    # endregion
    # fmt: on
    after_region

And having to use fmt:off around each region is rather verbose.

The challenge with supporting a feature like this is that I've seen different preferences and styles when it comes to formatting region comments AND the notation starting and ending a region (beyond that, it further complicates the comment formatting logic to know of region concepts).

The first step to move this forward would be to come up with a style proposal that has wide support in the community. We could then explore how a feature like this gets implemented, considering that there's sufficient demand for it.

[kbd]

It would be nice if the position, both line and indentation, of region/endregion comments were generally untouched and ignored by the formatter.

I'm currently writing some FastAPI routes and their tests inline. So I want regions for each API method + test(s) combo.

Instead of getting to do:

# region create
@app.post...
def create("/users"...):
    ...

def test_create():
    ...
# endregion create

# region update
@app.post...
def update("/users/{user_id}"...
    ...

def test_update():
    ...
# endregion update

Ruff formats as:

# region create
@app.post...
def create("/users"...):
    ...

def test_create():
    ...


# endregion create


# region update
@app.post...
def update("/users/{user_id}"...
    ...

def test_update():
    ...


# endregion update

It works but it's a lot of extra whitespace.

[Avasam]

I don't remember if I was able to do so in previous Ruff versions, but in 0.6.1 I am able to move the #endregion comment up and indented into the end of the method. So I get consistent code folding comments and it's still working in VSCode.

[pfcodes]

The challenge with supporting a feature like this is that I've seen different preferences and styles when it comes to formatting region comments AND the notation starting and ending a region (beyond that, it further complicates the comment formatting logic to know of region concepts).

Since #region/#endregion is recognized out of the box by the major IDEs (JetBrains, VSCode, etc.) I think it could be considered a standardized way of doing it rather than a preference.

But for anyone who needs a workaround, adding an additional # will work:

##region Region name
...
##endregion