python-trio / python-trio/trio
Describe our attrs usage in contributor guide
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 7.3k
- Forks
- 431
- Avg merge
- 2d 17h
- Merged PRs (30d)
- 6
Description
#3114 made me think that we should have a short blurb in the contributors guide on our attrs usage. I remember it being very confusing when I started contributing, and #3114 adds another pitfall (though thankfully with a test), and tbh I'm still not fully sure myself when to use what.
Possible content:
- why we use attrs in the first place(?)
- that we prefer underscored attribute names, with an
alias(and why pyright makes thealiasneeded) - when to use
slots=False - when to use
eq=False - when to use
@frozen
The latter three are fairly common, but not universal, and I have a suspicion that we may not be fully consistent. Addressing the points could include pointing to official attrs docs, issues/PRs discussing pros/cons, or summarizing info that's happened in a lot of different places.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the contributor guide, current attrs usage, and issue #3114, including its test-related pitfall. Done means adding a concise explanation of why attrs is used, underscored names and aliases, and when to use slots=False, eq=False, and @frozen, with relevant official documentation or project discussions linked.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100