ssort messes with class attribute docstrings

[and-semakin]

Before:

from dataclasses import dataclass

@dataclass
class User:
    id: int
    """User identifier."""

    email: str
    """E-mail address."""

    phone: str
    """Phone number in the international format."""

    age: int
    """Number of full years."""

After:

from dataclasses import dataclass

@dataclass
class User:
    id: int

    email: str

    phone: str

    age: int
    """User identifier."""
    """E-mail address."""
    """Phone number in the international format."""
    """Number of full years."""

There are two PEPs that describe such docstrings. Both of them were rejected.

• https://peps.python.org/pep-0224/
• https://peps.python.org/pep-0258/

I know that this is now a "real" docstring syntax but people still use it to document fields in their classes. Some tools support it as well (like sphinx).

It could be useful to recognise such docstrings and preserve their positions.

[bwhmather]

Interesting. I wasn't aware of that convention. It's always bugged me that documentation comments appear before the things they describe in code but after in the docs.

I don't think this conflicts with any of the other rules for how we sort class bodies so I don't see any harm in implementing it. With that said, it is unlikely to be a straightforward change as we have no precedent for pairing expressions with siblings.

I don't have the time to work on this myself, but I'm going to leave this open for you or anyone else to pick up. A PR which implements this behaviour without breaking anything else or tanking performance will be accepted. Happy to provide advice and however many reviews it takes to get something working.

In the interim, switching to #: comments is probably the only workaround.

(Linking to conversation in #11)

[pawamoy]

Hi @bwhmather, I don't think I have the time to work on this, but could give us some hints where/how this would be implemented, just in case? A quick overview of ssort's flow, with the corresponding modules holding the logic, would be a great start!