Vinta ChenandClaude
63146cc863
Records the outcome of a grilling session with the maintainer that settled the redesign of awesome-python from a catalog into a curated shortlist of Obvious Choices per Use Case. Execution is held pending maintainer go-ahead, so these files let a fresh agent resume without re-litigating settled decisions: - CONTEXT.md: glossary of the editorial vocabulary (Use Case, Obvious Choice, Challenger, Displacement, Split, etc). - docs/adr/0001-shortlist-not-catalog.md: the ADR recording the decision, considered options, and consequences (status: proposed). - .gitignore: docs/ was wholesale-ignored; carve out docs/adr/ so the ADR can be tracked. Co-Authored-By: Claude <noreply@anthropic.com>
2.7 KiB
Awesome Python Curation
The editorial domain of awesome-python: which projects the list carries, how they are admitted, and how they are displaced. The list is a curated shortlist of obvious choices, not a catalog of everything good.
Language
List structure
Entry:
A single listed project: - [pypi-name](url) - Description. The unit that is admitted, displaced, or pruned.
Section:
A ### heading in README.md (e.g. "Testing", "AI and Agents"). Sections group entries and live under a Thematic Group.
Avoid: Category (overloaded — the TOC calls them categories, but rules bind to Use Cases, not Sections)
Subcategory: A named bullet inside a Section with indented entries under it (e.g. "Mocking" inside "Testing"). Where present, each Subcategory is one Use Case.
Use Case: The unit of "it" in "one obvious way to do it": one distinct job a reader needs done. Defined by the list's existing structure — each Subcategory is a Use Case; a flat Section is a single Use Case. Submitters cannot define Use Cases; only the list structure does. Avoid: Niche, micro-category
Admission
Serves Python Developers: The scope test for what belongs on the list at all: Python developers use it in their Python work. Implementation language is irrelevant — uv and ty are Rust and belong; a pure-Python library nobody uses in Python work does not. Avoid: Python-first, written-in-Python (old requirement — removed)
Obvious Choice: An entry an experienced Python developer would name unprompted when asked "what do I use for [Use Case]?". Certified by maintainer editorial judgment, informed primarily by PyPI download counts rather than GitHub stars. A standard-library module holds a slot only when it is itself the Obvious Choice for the Use Case, not merely relevant to it. Avoid: Industry Standard (old lane name), awesome (unfalsifiable)
Cap: The per-Use-Case entry limit: up to 3 Obvious Choices plus up to 2 Challengers, hard maximum 5. A qualitative bar first, a numeric backstop second.
Displacement: The only admission path into a full Use Case: the PR names the entry it replaces and argues the newcomer does that entry's job better. One in, one out. Avoid: One-in-one-out (informal alias)
Challenger: An entry (at most two per Use Case) that is not yet the Obvious Choice but is a credible successor to one. Its description must say so, and admission requires adoption-trajectory evidence, not popularity alone. Avoid: Rising Star (old lane name), Hidden Gem (old lane name — concept removed entirely)
Split: Maintainer-only restructuring of an oversized Use Case into finer Use Cases (new Subcategories), chosen over trimming when the size reflects genuinely distinct jobs. A submitter's entry PR can never perform a Split.