python-trio / python-trio/trio

Describe our attrs usage in contributor guide

Open
#3,116 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

docs project meta
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:

  1. why we use attrs in the first place(?)
  2. that we prefer underscored attribute names, with an alias (and why pyright makes the alias needed)
  3. when to use slots=False
  4. when to use eq=False
  5. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.