search

python-attrs / attrs

Python Classes Without Boilerplate
https://www.attrs.org/
MIT License
5.2k stars 363 forks source link

Docs should clearly describe `pyright` interaction patterns. #1273

Open asford opened 5 months ago

asford commented 5 months ago

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 commented 5 months ago

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 commented 5 months ago

@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 commented 3 months ago

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?