check-docstring-first false positive on attribute docstrings

[jaraco]

Attribute docstrings, as defined in PEP-257 are strings immediately following top level module names. For example:

name = "my variable"
"""the name used by the module for x, y, and z"""

The check-docstring-first incorrectly identifies this attribute docstring as a module docstring, indicating either Multiple module docstrings (first docstring on line N). or Module docstring appears after code (code seen on line N)..

In light of this issue, I'm not sure the check-docstring-first check has much value at all. At the very least, the check should not be failing when a docstring follows an assignment.

[asottile]

The goal of the hook was mostly to prevent imports-then-docstring (an especially common/easy mistake with future imports and docstrings), perhaps it can be adjusted to stop searching after it finds some non-import code (similar to the algorithm used in https://github.com/asottile/reorder_python_imports)

[sdouche]

Hey @asottile :)
Do you think is possible to resolve this issue?

[asottile]

Doubt it, unless you can come up with a good heuristic for differentiating the mistake and the intentional "attribute docstring"

[sdouche]

@asottile Understood. Maybe close this issue then?

[asottile]

It may be possible, I haven't invested any time into this particular issue as I don't use "attribute docstrings" - - normal comments work fine for me

[lukelbd]

@asottile People use "attribute docstrings" becuase the sphinx autosummary documentation generator looks for docstrings following class-level and module-level variables and uses them to generate website documentation. This would actually be a useful feature for a lot of people.

[asottile]

This issue is still open, if you can come up with a heuristic that properly identifies "attribute docstrings" vs the mistakes it currently catches then I'd happily entertain a tested patch. You'll notice I marked this as a bug and I haven't closed it, so please be careful of asserting that I'm being dismissive. I simply don't have any reason to work on this myself since I don't use that feature, but I'd be happy to guide you through implementing this :)

I'm pretty sure you can also use this as a workaround (or at least I've seen comments like this in the past):

attr = 1
#: comment about the attribute

(I might be misremembering the exact format, it's been a while!)

[lukelbd]

Sorry didn't mean to be rude; I corrected my tone! Obviously I'm super grateful for this project. I didn't know about #: -- maybe that ought to close this issue actually.

[ryanrhee]

I just ran into this. FWIW, #: is not a part of PEP-257, and (more importantly for me,) comments starting with #: are not picked up by vscode the way that attribute docstrings are.

just fyi, that there are use cases for which the #: workaround doesn't work.