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 https://github.com/python-attrs/attrs/issues/1170#issuecomment-1872498822

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 https://github.com/python-attrs/attrs/issues/795#issuecomment-1961244502

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?