Docs should clearly describe `pyright` interaction patterns.

[asford]

Having users directed to the attrs issue tracker with pyright type-checking issues described as bugs in attrs doesn't feel great.

Originally posted by @hynek in #1170 (comment)

There are variety of issues redirected into the attrs issue tracker describing what are (essentially) issues with PEP681's description of attrs and resulting inconsistencies with pyright-based static type checking of attrs classes.

These aren't issues with attrs, which supports PEP681 and pyright on a best-effort basis. Absent an explicit dataclass-compatible namespace, these deviations are (at most) a documentation issue for attrs.

[asford]

This is how documentation suggests to use the default decorator, with the example provided causing the same message to be reported for attrs 23.2.0 and pyright 1.1.351.

Originally posted by @Stealthii in #795 (comment)

Another instance of an interaction pattern that's correct runtime behavior, but actually a pyright issue.

[asford]

@hynek I totally appreciate how frustrating some of these redirects from pyright can be, as you mention in the issue referenced above. I think it would be useful to expand the public-facing attrs docs to include specific examples of some pyright/attrs interaction patterns, including a description of the the intended semantics of the PEP681/pyright interaction.

Then, hopefully, redirects coming in from the pyright issue tracker can start there and be filed as doc-requests rather than attrs issues.

As the "one who opened the box" on some of this in #795 I'd happily step-up to write this if you're keen.
I'll also volunteer to triage (and address) doc issues of this type in the attrs issue tracker.

[hynek]

I've been thinking about it for a while, but I kinda didn't come up with anything how to do it. Do you already have something more concrete on your mind?

[A5rocks]

It might be useful to point out that attrs issues w/ the PEP are intentional from the part of the PEP (#795 (comment)) and then talk about workarounds necessary for libraries (because those have to adapt too)? For instance, putting alias="name_without_underscore" for all fields on constructable classes.