Merge pull request #3288 from vinta/refactor/shortlist-reform

Reposition awesome-python as a shortlist, not a catalog
This commit is contained in:
Vinta Chen 2026-08-16 19:31:51 +08:00 • committed by GitHub
commit b7e12cfcad
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
28 changed files with 1325 additions and 556 deletions

View file

@ -0,0 +1,39 @@
---
name: audit-the-list
description: Audit README.md sections against the shortlist rules — re-verify every entry's verdict with live data, promote or demote challengers, restructure oversized use cases, prune, and evaluate proposed additions. Fire when the maintainer asks to audit, sweep, prune, re-check, or maintain sections, or asks whether an entry (or a proposed one) deserves its slot.
argument-hint: [all or specific sections]
---
# Audit the list
An Audit re-runs the admission test over live sections of README.md: every entry re-verified against current data, tiers reassessed, structure reconsidered, then the maintainer adjudicates and the result is committed. The rules live in CONTRIBUTING.md (Admission, Evidence, Entry Ordering) and CONTEXT.md (vocabulary) — this skill is the process that applies them, not a second copy of them. Entry changes land only on the maintainer's explicit go.
## 1. Scope
Resolve the scope from the arguments. Named sections mean exactly those, whether or not they were audited before (a re-run is how a past verdict gets rechecked). `all` is ambiguous — `AskUserQuestion` whether it means every section or only never-audited ones; prior audits are recorded in git history (`git log --oneline --grep="sweep\|audit"`). With no arguments, AskUserQuestion listing the never-audited Thematic Groups. Batch the work one Thematic Group per sitting. Done when the section list is settled.
## 2. Evidence
Fetch live evidence for every entry in scope before judging anything (CLAUDE.md verification rule):
- **Downloads/month**: `cd website && UV_PYTHON=3.13 uv run python fetch_pypi_downloads_via_clickpy.py` — free keyless ClickPy sweep of the full README, sole writer of `data/pypi_downloads.tsv` (rewritten from scratch each run; header row, every row stamped with its `fetched_at` date). A cache whose `fetched_at` is within the last 7 days is current enough for verdicts — skip the sweep; older than that, re-run it (costs ~1s). Cross-checks print to stdout, take explicit names, and never touch the cache: `fetch_pypi_downloads_via_bigquery.py <name> ...` (canonical source, maintainer's own GCP account, `--dry-run` first — the docstring carries the cost constraints; full-README sweeps exceed the free tier, keep name lists small), `fetch_pypi_downloads_via_pepy.py <name> ...` (needs `PEPY_TECH_API_KEY` in repo-root `.env`, throttled to 5 requests/minute), or `https://pypistats.org/api/packages/{name}/recent` paced 8s or slower. pypistats excludes mirror/CI traffic; ClickPy, BigQuery, and pepy include it — never mix sources within one comparison.
- **Repo state**: archived flag, last push, created date, stars, description — `gh api repos/{owner}/{repo}`, GitLab API for GitLab-hosted projects.
- **PyPI metadata** (`https://pypi.org/pypi/{name}/json`) wherever a name might not be the canonical package — ownership collisions and wrong display names surface here. Wrong-package cache rows are common: the sweep looks up README display names, so when the display name differs from the canonical package, the row silently measures an unrelated squatter or a dead predecessor. When a famous entry shows a count that looks off (too small, or absurdly round), verify identity before citing it, and fetch the canonical package's count via pepy.
Done when every entry in scope has downloads (or a stated no-signal reason), repo state, and a confirmed PyPI name.
## 3. Verdicts
Draft a verdict and reason for every entry, restructure before cap: decide Splits, mints, and re-homes first — cutting before restructuring destroys entries — then apply the cap tier by tier, including promotions and demotions between obvious choice and challenger. Ground every reason in the fetched evidence; label anything unverifiable as a judgment call. Where fresh evidence contradicts the standing verdict, say so in the reason instead of silently keeping the seed.
## 4. Review and go
Run the `preview-verdicts` skill: it generates the interactive review page and defines how the maintainer's feedback JSON comes back and gets processed. Their verdicts are final. Before touching README.md, surface what the feedback implies but does not decide — cap overflows, homeless entries after a Split, tier for a tierless flip — as named assumptions or questions, then get an explicit go.
## 5. Execute
One commit per section: body lists each removal with its reason and downloads figure; restructures, tier moves, and reorders ride the same commit. Format-only outcomes (no removals) are a single style commit. `UV_PYTHON=3.13 make test` before every commit, `UV_PYTHON=3.13 make build` after the last one. Generic commit helpers tend to split a section audit into structural and per-subcategory commits — if that happens, squash back to one commit per section. Done when the tree is clean, tests passed before each commit, and the build count reconciles with the adjudicated changes.
## 6. Record
A conclusion that outlives the sitting goes into the repo before the audit ends: admission or evidence rules into CONTRIBUTING.md, repo process and environment facts into CLAUDE.md and AGENTS.md (kept in sync), vocabulary into CONTEXT.md. Done when nothing the next audit needs is stranded in conversation.

View file

@ -0,0 +1,24 @@
---
name: preview-verdicts
description: Generate the interactive keep/drop verdict preview (HTML page with per-row feedback controls) whenever a prune sweep, batch entry edit, or restructure needs maintainer review before touching README.md — and process the feedback JSON the maintainer pastes back.
---
# Verdict preview
Maintainer review happens through an interactive HTML page: one row per entry with your seeded verdict and reason, a Keep/Drop toggle and a reason field for the maintainer, and a **Copy feedback** button that exports only changed or commented rows as JSON. Generate the page, wait for the pasted JSON, then apply it. Entry changes land in README.md only after the review — and only on an explicit go.
## Generate the preview
1. Build the `DATA` array. A group is `[section, subcategory, rows]`; a row is `[entry, url, downloads, verdict, reason]`.
- `subcategory` may carry a note after ` — ` (rendered muted): use it for proposed splits, re-homes, or anything the maintainer should weigh for the whole group.
- `downloads` is PyPI last-month as a comma-formatted string; use `—` when no signal exists (e.g. agent skill packs), `stdlib` for standard-library modules, `fetch failed` when the lookup failed. State the fetch date in the sub-header.
- `verdict` is `keep` or `drop`, seeded from the current adjudication or dry-run.
- `reason` is plain language the maintainer reads cold — no invented shorthand. When fresh evidence contradicts the seeded verdict (a big download count on a drop, a dead repo on a keep), say so in that row's reason instead of silently changing the seed.
2. Copy `template.html` (sibling of this file) and replace the placeholders: `__TITLE__` (page title), `__SUB__` (sub-header: scope, seed provenance, fetch date, and the standing instruction to flip/comment then Copy feedback), `__KEY__` (localStorage key), `__DATA__` (the array). `__KEY__` must be unique per review — slug plus date, e.g. `awesome-python-science-2026-09-01` — because saved state under a reused key bleeds a previous review's flips into rows with the same section and entry name.
3. Write the page to `tmp/awesome-python-<slug>-preview.html` in the repo root (git-ignored; create the directory if needed), `open` it, and tell the maintainer the path and the return path: flip or comment rows (they highlight yellow), press **Copy feedback**, paste the JSON into the chat. Done when the page is open and the return path is stated.
## Process the pasted feedback
Each JSON row is `{section, subcategory, entry, my_verdict, your_verdict, reason}`. The maintainer's verdict is final — apply it, never re-argue it. An empty reason means the verdict stands unexplained; that is enough.
Before executing, surface anything the flips imply that the maintainer has not decided: a use case pushed past its cap, an entry left homeless by a proposed split, a request that is already satisfied (a no-op). Ask, then execute on their go. Done when every pasted row is either applied or surfaced back — none silently dropped.

View file

@ -0,0 +1,160 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>__TITLE__</title>
<style>
:root {
--ink: #1c1917; --paper: #faf9f7; --muted: #78716c; --line: #e7e5e4;
--keep: #1d4ed8; --keep-bg: #eff4ff; --drop: #b42318; --drop-bg: #fdf1ef;
--changed: #fffbeb; --changed-line: #f5c518;
}
* { box-sizing: border-box; }
body { margin: 0; background: var(--paper); color: var(--ink); font: 16px/1.5 -apple-system, "SF Pro Text", "Helvetica Neue", Arial, sans-serif; }
.wrap { padding: 2rem 2.5rem 6rem; }
h1 { font-size: 1.7rem; margin: 0 0 .3rem; }
.sub { color: var(--muted); margin: 0 0 1.6rem; font-size: 1rem; }
.sub b { color: var(--ink); }
.sub code { background: #f0eeec; padding: .1em .35em; border-radius: 4px; font-size: .92em; }
h2 { font-size: 1.35rem; margin: 2.2rem 0 .2rem; border-bottom: 2px solid var(--ink); padding-bottom: .3rem; }
h3 { font-size: 1.05rem; margin: 1.3rem 0 .4rem; color: var(--ink); }
h3 .note { font-weight: 400; color: var(--muted); font-size: .92rem; }
table { width: 100%; border-collapse: collapse; }
th { text-align: left; font-size: .82rem; text-transform: uppercase; letter-spacing: .04em; color: var(--muted); padding: .35rem .6rem; border-bottom: 1px solid var(--line); }
td { padding: .5rem .6rem; border-bottom: 1px solid var(--line); vertical-align: top; }
tr.changed td { background: var(--changed); border-bottom-color: var(--changed-line); }
td.name { white-space: nowrap; font-weight: 600; }
td.name a { color: var(--ink); text-decoration: none; border-bottom: 1px solid #c8c4c0; }
td.name a:hover { border-bottom-color: var(--ink); }
td.dl { white-space: nowrap; font-variant-numeric: tabular-nums; color: var(--muted); text-align: right; }
td.mine { white-space: nowrap; }
.badge { display: inline-block; font-size: .78rem; font-weight: 700; letter-spacing: .03em; padding: .12em .5em; border-radius: 4px; }
.badge.keep { color: var(--keep); background: var(--keep-bg); }
.badge.drop { color: var(--drop); background: var(--drop-bg); }
td.reason { color: #44403c; font-size: .95rem; max-width: 34rem; }
td.yours { white-space: nowrap; }
.seg { display: inline-flex; border: 1px solid var(--line); border-radius: 6px; overflow: hidden; }
.seg button { border: 0; background: #fff; padding: .3rem .8rem; font: inherit; font-size: .88rem; cursor: pointer; color: var(--muted); }
.seg button + button { border-left: 1px solid var(--line); }
.seg button.on.k { background: var(--keep); color: #fff; font-weight: 700; }
.seg button.on.d { background: var(--drop); color: #fff; font-weight: 700; }
td.fb input { width: 100%; min-width: 14rem; font: inherit; font-size: .92rem; padding: .3rem .5rem; border: 1px solid var(--line); border-radius: 6px; background: #fff; }
td.fb input:focus { outline: 2px solid var(--keep); outline-offset: 0; }
.bar { position: fixed; bottom: 0; left: 0; right: 0; background: var(--ink); color: #fafaf9; display: flex; align-items: center; gap: 1.4rem; padding: .7rem 2.5rem; font-size: .95rem; }
.bar .counts b { font-variant-numeric: tabular-nums; }
.bar button { font: inherit; font-weight: 700; padding: .45rem 1.1rem; border: 0; border-radius: 6px; background: #fafaf9; color: var(--ink); cursor: pointer; }
.bar button:hover { background: #e7e5e4; }
.bar .hint { color: #a8a29e; }
#out { display: none; width: 100%; height: 9rem; margin-top: 1rem; font: 13px/1.4 ui-monospace, monospace; }
</style>
</head>
<body>
<div class="wrap">
<h1>__TITLE__</h1>
<p class="sub">__SUB__</p>
<div id="app"></div>
<textarea id="out" readonly></textarea>
</div>
<div class="bar">
<span class="counts" id="counts"></span>
<button onclick="copyFeedback()">Copy feedback</button>
<span class="hint" id="hint">Copies only rows you changed or commented, as JSON.</span>
</div>
<script>
const DATA = __DATA__;
const KEY = "__KEY__";
let state = {};
try { state = JSON.parse(localStorage.getItem(KEY) || "{}"); } catch (e) {}
function rowId(section, name) { return section + "::" + name; }
function render() {
const app = document.getElementById("app");
let html = "", lastSection = "";
for (const [section, subcat, rows] of DATA) {
if (section !== lastSection) { html += `<h2>${section}</h2>`; lastSection = section; }
const parts = subcat.split(" — ");
html += `<h3>${parts[0]}${parts[1] ? ` <span class="note">— ${parts[1]}</span>` : ""}</h3>`;
html += `<table><tr><th>Entry</th><th style="text-align:right">Downloads/mo</th><th>My verdict</th><th>My reason</th><th>Yours</th><th>Your reason (optional)</th></tr>`;
for (const [name, url, dl, mine, reason] of rows) {
const id = rowId(section, name);
const s = state[id] || {};
const yours = s.verdict || mine;
const changed = yours !== mine || (s.feedback || "").trim() !== "";
html += `<tr id="${cssId(id)}" class="${changed ? "changed" : ""}">
<td class="name"><a href="${url}" target="_blank" rel="noopener">${name}</a></td>
<td class="dl">${dl}</td>
<td class="mine"><span class="badge ${mine}">${mine.toUpperCase()}</span></td>
<td class="reason">${reason}</td>
<td class="yours"><span class="seg">
<button class="k ${yours === "keep" ? "on" : ""}" onclick="setV('${esc(id)}','keep')">Keep</button>
<button class="d ${yours === "drop" ? "on" : ""}" onclick="setV('${esc(id)}','drop')">Drop</button>
</span></td>
<td class="fb"><input value="${(s.feedback || "").replace(/"/g, "&quot;")}" oninput="setF('${esc(id)}', this.value)" placeholder="why…"></td>
</tr>`;
}
html += `</table>`;
}
app.innerHTML = html;
updateCounts();
}
function cssId(id) { return "r-" + id.replace(/[^a-zA-Z0-9]/g, "_"); }
function esc(id) { return id.replace(/'/g, "\\'"); }
function setV(id, v) { state[id] = state[id] || {}; state[id].verdict = v; save(); render(); }
function setF(id, f) {
state[id] = state[id] || {}; state[id].feedback = f; save();
const [section, name] = id.split("::");
const mine = findMine(section, name);
const yours = state[id].verdict || mine;
document.getElementById(cssId(id)).className = (yours !== mine || f.trim() !== "") ? "changed" : "";
updateCounts();
}
function findMine(section, name) {
for (const [s, , rows] of DATA) if (s === section) for (const r of rows) if (r[0] === name) return r[3];
}
function save() { localStorage.setItem(KEY, JSON.stringify(state)); }
function collect() {
const out = [];
for (const [section, subcat, rows] of DATA) {
for (const [name, , , mine] of rows) {
const id = rowId(section, name);
const s = state[id] || {};
const yours = s.verdict || mine;
const fb = (s.feedback || "").trim();
if (yours !== mine || fb) out.push({ section, subcategory: subcat.split(" — ")[0], entry: name, my_verdict: mine, your_verdict: yours, reason: fb });
}
}
return out;
}
function updateCounts() {
let keeps = 0, total = 0, changed = 0;
for (const [section, , rows] of DATA) for (const [name, , , mine] of rows) {
total++;
const s = state[rowId(section, name)] || {};
const yours = s.verdict || mine;
if (yours === "keep") keeps++;
if (yours !== mine) changed++;
}
document.getElementById("counts").innerHTML = `<b>${keeps}</b> keep · <b>${total - keeps}</b> drop of <b>${total}</b> &nbsp;|&nbsp; <b>${changed}</b> verdicts flipped`;
}
function copyFeedback() {
const fb = collect();
const text = fb.length ? JSON.stringify(fb, null, 1) : "(no changes — all verdicts accepted as-is)";
const hint = document.getElementById("hint");
navigator.clipboard.writeText(text).then(
() => { hint.textContent = `Copied ${fb.length ? fb.length + " row(s)" : "acceptance note"} — paste into the chat.`; },
() => { const o = document.getElementById("out"); o.style.display = "block"; o.value = text; o.select(); hint.textContent = "Clipboard blocked — select & copy the box above."; }
);
}
render();
</script>
</body>
</html>

View file

@ -1,24 +1,26 @@
## Project
[Project Name](url)
[project-name](url)
## Checklist
- [ ] I read [CONTRIBUTING.md](https://github.com/vinta/awesome-python/blob/master/CONTRIBUTING.md) - awesome-python is a shortlist, not a catalog
- [ ] One project per PR
- [ ] PR title format: `Add project-name`
- [ ] Entry format: `- [project-name](url) - Description ending with period.`
- [ ] Description is concise and short
- [ ] Entry format: `- [pypi-name](https://github.com/owner/repo) - Description ending with period.`
- [ ] Display name is the PyPI package name
- [ ] Placed in an existing use case (new sections and subcategories are maintainer-only)
- [ ] Meets all Quality Requirements: active, stable, documented, at least 1 month old
## Why This Project Is Awesome
## Which Tier
Which criterion does it meet? (pick one)
Pick one:
- [ ] **Industry Standard** - The go-to tool for a specific use case
- [ ] **Rising Star** - 5000+ stars in < 2 years, significant adoption
- [ ] **Hidden Gem** - Exceptional quality, solves niche problems elegantly
- [ ] **Obvious choice** - a tool an experienced Python developer would name when asked "what do I use for this?"
- [ ] **Challenger** - not yet the obvious choice, but a credible successor to one. Give adoption-trajectory evidence, not popularity alone.
Explain:
## How It Differs
## Displacement
If similar entries exist, what makes this one unique?
If the use case is at its cap, name the entry your project replaces and argue that yours does that entry's job better. One in, one out.

View file

@ -71,6 +71,25 @@ jobs:
fi
python -m json.tool website/data/github_stars.json > /dev/null
- name: Restore PyPI download data cache
uses: actions/cache/restore@v4
with:
path: website/data/pypi_downloads.tsv
key: pypi-downloads-${{ steps.date.outputs.today }}
restore-keys: pypi-downloads-
- name: Fetch PyPI downloads
id: fetch-downloads
continue-on-error: true
run: make fetch_pypi_downloads
- name: Save PyPI download data cache
if: steps.fetch-downloads.outcome == 'success'
uses: actions/cache/save@v4
with:
path: website/data/pypi_downloads.tsv
key: pypi-downloads-${{ steps.date.outputs.today }}
- name: Build website
run: make build

11
.gitignore vendored
View file

@ -11,14 +11,9 @@ __pycache__/
# website
website/output/
website/data/
# docs
docs/
website/data/*
!website/data/pypi_name_overrides.json
# agents
.agents/
.claude/skills/
.superpowers/
.playwright-cli/
skills-lock.json
tmp/

View file

@ -1,31 +1,13 @@
# AGENTS.md
## Repository Overview
An opinionated guide to the best Python frameworks, libraries, tools, and resources.
An opinionated list of Python frameworks, libraries, tools, and resources. Published at [awesome-python.com](https://awesome-python.com/).
[README.md](README.md) is the single source of truth for catalog entries and README sponsor placements; `website/` renders it into the static site: [awesome-python.com](https://awesome-python.com/).
## Entry Guidelines
## Entry Rules
**Refer to [CONTRIBUTING.md](CONTRIBUTING.md)** for acceptance criteria, quality requirements, rejection rules, and entry format. Apply these rules whenever adding or removing an entry, whether reviewing a PR or committing directly.
[CONTRIBUTING.md](CONTRIBUTING.md) holds the admission rules, quality requirements, rejection rules, entry format, and ordering. Apply it whenever adding or removing an entry — direct commits included, not only PR reviews.
## Structure
- **README.md**: Source of truth for catalog entries and README sponsor placements. Hierarchical categories with alphabetically ordered entries.
- **CONTRIBUTING.md**: Submission guidelines and review criteria.
- **SPONSORSHIP.md**: Sponsor tiers, placement rules, and the editorial-independence policy. `website/templates/sponsorship.html` separately defines which sponsorship content appears on the published website page.
- **website/**: Static site generator that builds awesome-python.com from README.md.
- `build.py`: Parses README.md and renders HTML via Jinja2 templates.
- `fetch_github_stars.py`: Fetches star counts into `website/data/`.
- `readme_parser.py`: Markdown-to-structured-data parser.
- `templates/`, `static/`: Jinja2 templates and CSS/JS assets.
- `tests/`: Pytest tests for the build pipeline.
- **Makefile**: `make install`, `make build`, `make preview`, `make test`, `make lint`, `make format`, `make typecheck`, `make fetch_github_stars`.
- **pyproject.toml**: Uses `uv` for dependency management. Python >=3.13.
## Key Rules
- Alphabetical ordering within categories is mandatory.
- Quality over quantity. Only "awesome" projects.
- One project per PR.
- One entry per commit when adding or deleting entries. Format, wording, or categorization changes across multiple entries may be bundled in a single commit.
- README.md is the source of truth for catalog entries and README sponsor placements; treat `SPONSORSHIP.md` and `website/templates/sponsorship.html` as separate sponsorship content surfaces.
- Every keep/drop reason must be verified against current online data at decision time — download counts, repo activity and archived status, PyPI metadata, project docs. Judging tiers — obvious choice vs challenger — also requires WebSearch evidence (adoption trajectory, community sentiment), not download counts alone. Training-data recollections are not evidence; label anything unverifiable as a judgment call.
- One entry per commit when adding or deleting entries. Exceptions: a prune sweep is one commit per section, its body listing each removal with its reason; format, wording, or categorization changes may be bundled.
- Sponsor placement never influences which projects get listed — see [SPONSORSHIP.md](SPONSORSHIP.md). `website/templates/sponsorship.html` separately defines the sponsorship content on the published website page.

View file

@ -1,31 +1,14 @@
# CLAUDE.md
## Repository Overview
An opinionated guide to the best Python frameworks, libraries, tools, and resources.
An opinionated list of Python frameworks, libraries, tools, and resources. Published at [awesome-python.com](https://awesome-python.com/).
[README.md](README.md) is the single source of content truth; `website/` renders it into the static site: [awesome-python.com](https://awesome-python.com/).
## Entry Guidelines
## Entry Rules
**Refer to [CONTRIBUTING.md](CONTRIBUTING.md)** for acceptance criteria, quality requirements, rejection rules, and entry format. Apply these rules whenever adding or removing an entry, whether reviewing a PR or committing directly.
[CONTRIBUTING.md](CONTRIBUTING.md) holds the admission rules, quality requirements, rejection rules, entry format, and ordering. Apply it whenever adding or removing an entry — direct commits included, not only PR reviews.
## Structure
- **README.md**: Source of truth. Hierarchical categories with alphabetically ordered entries.
- **CONTRIBUTING.md**: Submission guidelines and review criteria.
- **SPONSORSHIP.md**: Sponsor tiers, placement rules, and the editorial-independence policy. Sponsor content sits in the README header and must never influence which projects get listed.
- **website/**: Static site generator that builds awesome-python.com from README.md.
- `build.py`: Parses README.md and renders HTML via Jinja2 templates.
- `fetch_github_stars.py`: Fetches star counts into `website/data/`.
- `readme_parser.py`: Markdown-to-structured-data parser.
- `templates/`, `static/`: Jinja2 templates and CSS/JS assets.
- `tests/`: Pytest tests for the build pipeline.
- **Makefile**: `make install`, `make build`, `make preview`, `make test`, `make fetch_github_stars`.
- **pyproject.toml**: Uses `uv` for dependency management. Python >=3.13.
## Key Rules
- Alphabetical ordering within categories is mandatory.
- Quality over quantity. Only "awesome" projects.
- One project per PR.
- One entry per commit when adding or deleting entries. Format, wording, or categorization changes across multiple entries may be bundled in a single commit.
- README.md is the single source of content truth.
- Every keep/drop reason must be verified against current online data at decision time — download counts, repo activity and archived status, PyPI metadata, project docs. Judging tiers — obvious choice vs challenger — also requires WebSearch evidence (adoption trajectory, community sentiment), not download counts alone. Training-data recollections are not evidence; label anything unverifiable as a judgment call.
- One entry per commit when adding or deleting entries. Exceptions: a prune sweep is one commit per section, its body listing each removal with its reason; format, wording, or categorization changes may be bundled. Cross-section re-homes ride the originating audit's commit (both sides of the move in one diff).
- Resources sections are not project entries: out of audit scope, and the website never parses them.
- Sponsor placement never influences which projects get listed — see [SPONSORSHIP.md](SPONSORSHIP.md).

63
CONTEXT.md Normal file
View file

@ -0,0 +1,63 @@
# 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: `- [name](url) - Description.` The unit that is admitted, displaced, or pruned. Named by PyPI package name when one exists, else by repository name.
**Sub-item**:
An indented awesome-* also-see link under an Entry (awesome-django under django, awesome-pytest under pytest). Not an Entry: it holds no slot, does not count against the Cap, and rides its parent — re-homed or removed with it. Maintainer-only placement, and only for awesome-* lists: a companion project either earns a full Entry in its proper Use Case or is not listed.
**Thematic Group**:
A bold group line (e.g. "AI & ML", "Web Development") that clusters Sections in the TOC and the Projects body.
**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. "Mock" 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 structure — each Subcategory is a Use Case; a flat Section is a single Use Case. Submitters cannot define Use Cases; only the maintainer changes the structure (see Split).
_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 and packaging are 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; judgment overrides the signal's known failure modes (CI-inflated counts, model releases consumed as weights rather than pip installs — extended to any project consumed outside pip: SDK downloads like renpy, deployed services like thumbor — and large-but-specific audiences misread as "niche"). 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 — and a ceiling, not a floor: a minted Use Case may hold a single entry.
**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. Marked by ordering, not description: within a Use Case, Obvious Choices are listed first, then Challengers, each tier by PyPI downloads/month descending (standard-library modules first in the Use Case outright — always Obvious Choices by the stdlib rule — other no-signal entries last in tier, alphabetically). Admission requires adoption-trajectory evidence, not popularity alone.
_Avoid_: Rising Star (old lane name), Hidden Gem (old lane name — concept removed entirely)
**Second Tier**:
A Challenger slot holding a demoted incumbent instead of a rising successor — a former Obvious Choice or fading community standard an Audit kept below the current Obvious Choices (clickhouse-driver behind the official client, dogpile.cache and django-cacheops behind cachetools and diskcache, django-haystack in Search). It counts against the two Challenger slots and is marked by position like any Challenger; the adoption-trajectory bar gates only new admissions, not demotions.
**Override**:
A maintainer decision, made in an Audit and explicitly recorded, that keeps an entry or use-case shape past a written limit — the activity line, the stability bar, a cap, or a structure rule. Case-by-case: an Override never loosens the written rule for any other entry, and submitters cannot cite one.
**Split**:
Maintainer-only restructuring of an oversized Use Case into finer Use Cases (new Subcategories), considered before any trimming when the size reflects genuinely distinct jobs. A submitter's entry PR can never perform a Split.
### Maintenance
**Audit**:
The recurring maintenance pass over one or more Sections: every Entry's verdict re-verified against current evidence, Challengers promoted or demoted, oversized Use Cases Split, drops and admissions re-decided. The maintainer adjudicates through an interactive preview, and entry changes land only on their explicit go. The 2026-08 shortlist-reform sweeps were the first Audits.
_Avoid_: Sweep (reform-era name for a Section's first Audit)

View file

@ -1,41 +1,39 @@
# Contributing
awesome-python is a shortlist, not a catalog. Each use case lists only its obvious choices, and most rejections mean "the use case is full", not "your project is bad". Read this whole page before opening a PR.
## Quality Requirements
All submissions must satisfy **ALL** of these:
1. **Python-first**: Primarily written in Python (>50% of codebase)
1. **Serves Python Developers**: Python developers use it in their Python work. Implementation language and packaging are irrelevant — uv and ty are written in Rust, and agent skill packs are markdown, yet all belong; a pure-Python project nobody uses in Python work does not.
2. **Active**: Commits within the last 12 months
3. **Stable**: Production-ready, not alpha/beta/experimental
4. **Documented**: Clear README with examples and use cases
5. **Unique**: Adds distinct value, not "yet another X"
6. **Established**: Repository at least 1 month old
5. **Established**: Repository at least 1 month old
## Acceptance Criteria
## Admission
Your submission must meet **ONE** of the following criteria:
A **use case** is one distinct job a reader needs done. Use cases are defined by the list's structure: each subcategory is a use case, and a section without subcategories is a single use case. Structure changes — new sections, new subcategories, splitting an oversized use case into finer ones — are made only by the maintainer; an entry PR can never create the subcategory it needs.
### 1. Industry Standard
Each use case lists at most:
- The go-to tool that almost everyone uses for a specific use case
- Examples: requests, flask, pandas, numpy
- Limit: 1-3 tools per category
- **Up to 3 obvious choices** — tools an experienced Python developer would name when asked "what do I use for this?"
- **Up to 2 challengers** — tools that are not yet the obvious choice but are credible successors to one. Admission as a challenger requires adoption-trajectory evidence, not popularity alone.
### 2. Rising Star
Hard maximum: 5 entries per use case. This is a qualitative bar first and a numeric backstop second — most use cases should carry fewer.
- Rapid growth: 5,000+ GitHub stars in less than 1 year
- Significant community buzz and adoption
- Solving problems in new or better ways
- Examples: fastapi, ruff, uv
**Overrides**: the maintainer may exceed any limit on this page — the caps, the activity requirement, the stability requirement — for a specific entry or use case by explicit decision. An override is case-by-case; it does not loosen these rules for submissions, and citing one in a PR carries no weight.
### 3. Hidden Gem
**Displacement**: once a use case is at its cap, the only way in is to name the entry your project replaces and argue that yours does that entry's job better. One in, one out.
- Exceptional quality despite fewer stars (100-500 stars preferred; < 100 requires strong justification)
- Solves niche problems elegantly
- Strong recommendation from experienced developers
- **Must demonstrate real-world usage** (not a project published last week)
- Repository must be at least 3 months old with consistent activity
- Must include compelling justification in PR description
**Dual-listing**: a tool may hold entries in multiple use cases, but only when it earns its slot in each independently. List the full entry in each home with identical lines; never a "see X above" note, since the website only renders list items. Description edits update every copy in the same commit. Each slot is audited on its own: dropping one home keeps the other, and dropping the tool entirely removes all copies in one commit. Dual-listing is a maintainer decision; a PR adding a second home for an existing entry is treated as a duplicate.
**Standard library**: a standard-library module is listed only where the stdlib is itself the obvious choice for the use case (tomllib yes, unittest no).
**Evidence**: admission is decided by maintainer editorial judgment, informed primarily by PyPI download counts rather than GitHub stars. Judgment overrides the signal's known failure modes (CI-inflated counts, model releases consumed as weights rather than pip installs, large-but-specific audiences misread as "niche"). The maintainer's decision is final.
Looking for an exhaustive catalog instead? Follow the awesome-\* lists linked under individual entries (for example awesome-python-testing) — they exist precisely so this list doesn't have to be one.
## Entry Format Reference
@ -77,22 +75,28 @@ Use the **PyPI package name** as the display name so developers can copy it dire
- [project](url) - Description.
```
## Adding a New Section
### Entry Ordering
1. Add section description in italics: `*Libraries for doing X.*`
Within a use case, the obvious choices are listed first, ordered by PyPI downloads per month from high to low; challengers follow, in the same order. Standard-library modules sort first in the use case — built-ins lead, before everything else — alphabetically when there are several. (This never conflicts with tier order: a standard-library module is only listed where it is itself the obvious choice, so it always belongs to the first tier.) Other entries without a download signal (agent skill packs, projects distributed outside PyPI) sort last within their tier, alphabetically. There is no marker in the entry text — position is the marker, so the last entries of a use case may be its challengers.
## Changing the Structure
Adding sections or subcategories is maintainer-only (see Admission). For maintainer reference:
1. Add the section description in italics: `*Libraries for doing X.*`
2. Add the section under the appropriate thematic group (e.g., **AI & ML**, **Web**, **Data & Science**)
3. Add the section title to the Table of Contents under its group
4. Keep entries in alphabetical order within each category
4. Order entries per Entry Ordering above
## Review Process
PRs are reviewed by automated tools and maintainers:
1. **Format Check**: Entry follows the correct format
2. **Category Check**: Placed in the appropriate category/subcategory
2. **Category Check**: Placed in the appropriate use case
3. **Duplicate Check**: Not already listed or previously rejected
4. **Activity Check**: Project shows recent activity
5. **Quality Check**: Meets acceptance criteria
5. **Admission Check**: Meets the Admission rules above, including Displacement when the use case is at its cap
Search previous Pull Requests and Issues before submitting, as yours may be a duplicate.
@ -101,10 +105,12 @@ Search previous Pull Requests and Issues before submitting, as yours may be a du
PRs will be **closed** if:
- Adding multiple projects in one PR
- The use case is at its cap and the PR makes no Displacement argument
- The PR creates a new section or subcategory and fills it (structure changes are maintainer-only)
- Coordinated multi-entry self-promotion: multiple related projects from the same organization or author, across one or several PRs
- Duplicate of existing entry or recently-closed PR
- Empty or placeholder PR descriptions
- Placed under an inappropriate category
- Project is archived or abandoned (no commits in 12+ months)
- No documentation or unclear use case
- Less than 100 GitHub stars without Hidden Gem justification
- Repository less than 1 months old
- Repository less than 1 month old

View file

@ -7,6 +7,9 @@ install:
fetch_github_stars:
uv run python website/fetch_github_stars.py
fetch_pypi_downloads:
uv run python website/fetch_pypi_downloads_via_clickpy.py
test:
uv run pytest website/tests/ -v
@ -23,10 +26,7 @@ build:
uv run python website/build.py
preview: build
uv run watchmedo shell-command \
--patterns='*.md;*.html;*.css;*.js;*.py' \
--recursive \
--wait --drop \
--command='uv run python website/build.py' \
uv run watchfiles \
'uv run python website/build.py' \
README.md website/templates website/static website/data & \
python -m http.server -b 127.0.0.1 -d website/output/ 8000

729
README.md

File diff suppressed because it is too large Load diff

View file

@ -0,0 +1,26 @@
---
status: accepted
---
# awesome-python is a shortlist of obvious choices, not a catalog
By mid-2026 the list held 576 entries across 75 sections, with entry inflow up 24x year over year (96 additions in the trailing 12 months vs 4 the year before), concentrated in sections like AI and Agents (41 entries). The old acceptance model — three lanes (Industry Standard, Rising Star, Hidden Gem), only the first capped — admitted any project good enough in isolation, so categories grew without bound and stopped answering the reader's actual question: "what do I use for X?" We decided to reposition the list as a curated shortlist, per the Zen of Python: there should be one — and preferably only one — obvious way to do it.
## The decision
The list's scope test is "serves Python developers", replacing the old "primarily written in Python (>50%)" requirement: implementation language and packaging are irrelevant when Python developers use the thing in their Python work (uv and ty are Rust; agent skill packs are markdown), while a pure-Python project nobody uses in Python work does not belong. Each Use Case (a subcategory, or a flat section) lists at most its Obvious Choices — up to 3, plus up to 2 marked Challengers, hard maximum 5 (numbers provisional, to be reviewed after the prune). Admission is by maintainer editorial judgment, informed primarily by PyPI download counts rather than GitHub stars, and stated as final; judgment overrides the signal's known failure modes (CI/dependency-inflated counts, model releases consumed as weights rather than pip installs, large-but-specific audiences misread as "niche"). Once a Use Case is at cap, the only way in is Displacement: the PR names the entry it replaces and argues the newcomer does that job better. Use Cases are defined by the list's existing structure; an entry PR can never create the subcategory it needs. Standard-library entries hold a slot only where the stdlib module is itself the obvious choice. The existing stock gets the same test retroactively: a staged, worst-first prune (per-section sweep commits), with removed entries deleted outright — git history is the archive. Resources sections (Newsletters, Podcasts, Websites) are out of scope for now.
## Considered options
- Keep the three-lane model with caps on every lane: rejected because the lanes answer the wrong question ("is this good enough to enter?") once admission is comparative; rising-star momentum becomes evidence for a Challenger slot or a Displacement rather than an admission ticket of its own, and Hidden Gem is definitionally incompatible with "obvious".
- Rules-only, no retroactive prune: rejected because every rejection would face "but X is listed" precedent arguments, and readers would see no change.
- Archive removed entries in a separate file: rejected because it recreates the catalog one click away and dilutes the identity the change exists to restore.
## Consequences
- The list shrinks substantially: the maintainer-reviewed preview of the three largest sections kept 45 of 80 entries. Most future PRs will be rejected for fullness, not badness.
- awesome-python.com loses long-tail search traffic for the hundreds of niche tool names it will no longer carry. Accepted deliberately: reader trust over search surface.
- Fast-moving domains (e.g. AI and Agents) list current leaders by usage and absorb churn through Displacement; an oversized Use Case is either trimmed or Split into finer Use Cases by the maintainer.
- Linked awesome-* lists (e.g. awesome-python-testing) remain as the escape valve for readers who want exhaustive catalogs.
See CONTEXT.md for the vocabulary (Use Case, Obvious Choice, Challenger, Displacement, Split).

33
docs/audit-logs.md Normal file
View file

@ -0,0 +1,33 @@
# Audit Log
awesome-python is audited section by section. Every entry gets re-verified against live data, and every removal lands in a commit whose body carries the reason. Git history is the archive. This file is the at-a-glance register of maintainer decisions that a single commit can't show.
## Overrides
[CONTRIBUTING.md](../CONTRIBUTING.md) allows the maintainer to exceed any limit for a specific entry or use case. Each override is recorded here.
### Naming Exceptions
Display names follow the canonical PyPI package name. These entries keep a different name by maintainer decision:
- autobahn-python -- `autobahn`.
- django-rest-framework -- `djangorestframework`.
- django-rules -- `rules`.
- fasthtml -- `python-fasthtml`.
- jinja -- `Jinja2`.
- mem0 -- `mem0ai`.
- pangu.py -- `pangu`.
- playwright-python -- `playwright`.
- pytorch -- `torch`.
- strawberry -- `strawberry-graphql`.
- strawberry-django -- `strawberry-graphql-django`.
### Mature-stable Keeps
These entries sit past the 12-month activity requirement without an override. Each one is kept by editorial judgment: mature, stable, and no successor exists.
- ftfy
- itsdangerous
- jieba
- jinja
- sortedcontainers

View file

@ -5,7 +5,7 @@ description = "An opinionated list of awesome Python frameworks, libraries, soft
authors = [{ name = "Vinta Chen", email = "vinta.chen@gmail.com" }]
readme = "README.md"
license = "MIT"
requires-python = ">=3.13"
requires-python = ">=3.14"
dependencies = []
[project.urls]
@ -13,14 +13,15 @@ Homepage = "https://awesome-python.com/"
Repository = "https://github.com/vinta/awesome-python"
[dependency-groups]
build = ["httpx==0.28.1", "jinja2==3.1.6", "markdown-it-py==4.0.0"]
lint = ["ruff==0.15.6", "ty==0.0.33"]
test = ["pytest==9.0.3"]
build = ["httpx>=0.28.1", "jinja2>=3.1.6", "markdown-it-py>=4.0.0"]
lint = ["ruff>=0.15.6", "ty>=0.0.33"]
test = ["pytest>=9.0.3"]
preview = ["watchfiles>=1.2.0"]
dev = [
{ include-group = "build" },
{ include-group = "lint" },
{ include-group = "test" },
"watchdog==6.0.0",
{ include-group = "preview" },
]
[tool.uv]
@ -34,7 +35,7 @@ only-binary = [":all:"]
line-length = 200
[tool.ty.environment]
python-version = "3.13"
python-version = "3.14"
root = ["website"]
[tool.ty.terminal]

116
uv.lock generated
View file

@ -1,6 +1,6 @@
version = 1
revision = 3
requires-python = ">=3.13"
requires-python = ">=3.14"
[options]
exclude-newer = "0001-01-01T00:00:00Z" # This has no effect and is included for backwards compatibility when using relative exclude-newer values.
@ -36,12 +36,15 @@ dev = [
{ name = "pytest" },
{ name = "ruff" },
{ name = "ty" },
{ name = "watchdog" },
{ name = "watchfiles" },
]
lint = [
{ name = "ruff" },
{ name = "ty" },
]
preview = [
{ name = "watchfiles" },
]
test = [
{ name = "pytest" },
]
@ -50,24 +53,25 @@ test = [
[package.metadata.requires-dev]
build = [
{ name = "httpx", specifier = "==0.28.1" },
{ name = "jinja2", specifier = "==3.1.6" },
{ name = "markdown-it-py", specifier = "==4.0.0" },
{ name = "httpx", specifier = ">=0.28.1" },
{ name = "jinja2", specifier = ">=3.1.6" },
{ name = "markdown-it-py", specifier = ">=4.0.0" },
]
dev = [
{ name = "httpx", specifier = "==0.28.1" },
{ name = "jinja2", specifier = "==3.1.6" },
{ name = "markdown-it-py", specifier = "==4.0.0" },
{ name = "pytest", specifier = "==9.0.3" },
{ name = "ruff", specifier = "==0.15.6" },
{ name = "ty", specifier = "==0.0.33" },
{ name = "watchdog", specifier = "==6.0.0" },
{ name = "httpx", specifier = ">=0.28.1" },
{ name = "jinja2", specifier = ">=3.1.6" },
{ name = "markdown-it-py", specifier = ">=4.0.0" },
{ name = "pytest", specifier = ">=9.0.3" },
{ name = "ruff", specifier = ">=0.15.6" },
{ name = "ty", specifier = ">=0.0.33" },
{ name = "watchfiles", specifier = ">=1.2.0" },
]
lint = [
{ name = "ruff", specifier = "==0.15.6" },
{ name = "ty", specifier = "==0.0.33" },
{ name = "ruff", specifier = ">=0.15.6" },
{ name = "ty", specifier = ">=0.0.33" },
]
test = [{ name = "pytest", specifier = "==9.0.3" }]
preview = [{ name = "watchfiles", specifier = ">=1.2.0" }]
test = [{ name = "pytest", specifier = ">=9.0.3" }]
[[package]]
name = "certifi"
@ -172,28 +176,6 @@ version = "3.0.3"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/7e/99/7690b6d4034fffd95959cbe0c02de8deb3098cc577c67bb6a24fe5d7caa7/markupsafe-3.0.3.tar.gz", hash = "sha256:722695808f4b6457b320fdc131280796bdceb04ab50fe1795cd540799ebe1698", size = 80313, upload-time = "2025-09-27T18:37:40.426Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/38/2f/907b9c7bbba283e68f20259574b13d005c121a0fa4c175f9bed27c4597ff/markupsafe-3.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e1cf1972137e83c5d4c136c43ced9ac51d0e124706ee1c8aa8532c1287fa8795", size = 11622, upload-time = "2025-09-27T18:36:41.777Z" },
{ url = "https://files.pythonhosted.org/packages/9c/d9/5f7756922cdd676869eca1c4e3c0cd0df60ed30199ffd775e319089cb3ed/markupsafe-3.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:116bb52f642a37c115f517494ea5feb03889e04df47eeff5b130b1808ce7c219", size = 12029, upload-time = "2025-09-27T18:36:43.257Z" },
{ url = "https://files.pythonhosted.org/packages/00/07/575a68c754943058c78f30db02ee03a64b3c638586fba6a6dd56830b30a3/markupsafe-3.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:133a43e73a802c5562be9bbcd03d090aa5a1fe899db609c29e8c8d815c5f6de6", size = 24374, upload-time = "2025-09-27T18:36:44.508Z" },
{ url = "https://files.pythonhosted.org/packages/a9/21/9b05698b46f218fc0e118e1f8168395c65c8a2c750ae2bab54fc4bd4e0e8/markupsafe-3.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ccfcd093f13f0f0b7fdd0f198b90053bf7b2f02a3927a30e63f3ccc9df56b676", size = 22980, upload-time = "2025-09-27T18:36:45.385Z" },
{ url = "https://files.pythonhosted.org/packages/7f/71/544260864f893f18b6827315b988c146b559391e6e7e8f7252839b1b846a/markupsafe-3.0.3-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:509fa21c6deb7a7a273d629cf5ec029bc209d1a51178615ddf718f5918992ab9", size = 21990, upload-time = "2025-09-27T18:36:46.916Z" },
{ url = "https://files.pythonhosted.org/packages/c2/28/b50fc2f74d1ad761af2f5dcce7492648b983d00a65b8c0e0cb457c82ebbe/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:a4afe79fb3de0b7097d81da19090f4df4f8d3a2b3adaa8764138aac2e44f3af1", size = 23784, upload-time = "2025-09-27T18:36:47.884Z" },
{ url = "https://files.pythonhosted.org/packages/ed/76/104b2aa106a208da8b17a2fb72e033a5a9d7073c68f7e508b94916ed47a9/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:795e7751525cae078558e679d646ae45574b47ed6e7771863fcc079a6171a0fc", size = 21588, upload-time = "2025-09-27T18:36:48.82Z" },
{ url = "https://files.pythonhosted.org/packages/b5/99/16a5eb2d140087ebd97180d95249b00a03aa87e29cc224056274f2e45fd6/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:8485f406a96febb5140bfeca44a73e3ce5116b2501ac54fe953e488fb1d03b12", size = 23041, upload-time = "2025-09-27T18:36:49.797Z" },
{ url = "https://files.pythonhosted.org/packages/19/bc/e7140ed90c5d61d77cea142eed9f9c303f4c4806f60a1044c13e3f1471d0/markupsafe-3.0.3-cp313-cp313-win32.whl", hash = "sha256:bdd37121970bfd8be76c5fb069c7751683bdf373db1ed6c010162b2a130248ed", size = 14543, upload-time = "2025-09-27T18:36:51.584Z" },
{ url = "https://files.pythonhosted.org/packages/05/73/c4abe620b841b6b791f2edc248f556900667a5a1cf023a6646967ae98335/markupsafe-3.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:9a1abfdc021a164803f4d485104931fb8f8c1efd55bc6b748d2f5774e78b62c5", size = 15113, upload-time = "2025-09-27T18:36:52.537Z" },
{ url = "https://files.pythonhosted.org/packages/f0/3a/fa34a0f7cfef23cf9500d68cb7c32dd64ffd58a12b09225fb03dd37d5b80/markupsafe-3.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:7e68f88e5b8799aa49c85cd116c932a1ac15caaa3f5db09087854d218359e485", size = 13911, upload-time = "2025-09-27T18:36:53.513Z" },
{ url = "https://files.pythonhosted.org/packages/e4/d7/e05cd7efe43a88a17a37b3ae96e79a19e846f3f456fe79c57ca61356ef01/markupsafe-3.0.3-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:218551f6df4868a8d527e3062d0fb968682fe92054e89978594c28e642c43a73", size = 11658, upload-time = "2025-09-27T18:36:54.819Z" },
{ url = "https://files.pythonhosted.org/packages/99/9e/e412117548182ce2148bdeacdda3bb494260c0b0184360fe0d56389b523b/markupsafe-3.0.3-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:3524b778fe5cfb3452a09d31e7b5adefeea8c5be1d43c4f810ba09f2ceb29d37", size = 12066, upload-time = "2025-09-27T18:36:55.714Z" },
{ url = "https://files.pythonhosted.org/packages/bc/e6/fa0ffcda717ef64a5108eaa7b4f5ed28d56122c9a6d70ab8b72f9f715c80/markupsafe-3.0.3-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4e885a3d1efa2eadc93c894a21770e4bc67899e3543680313b09f139e149ab19", size = 25639, upload-time = "2025-09-27T18:36:56.908Z" },
{ url = "https://files.pythonhosted.org/packages/96/ec/2102e881fe9d25fc16cb4b25d5f5cde50970967ffa5dddafdb771237062d/markupsafe-3.0.3-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8709b08f4a89aa7586de0aadc8da56180242ee0ada3999749b183aa23df95025", size = 23569, upload-time = "2025-09-27T18:36:57.913Z" },
{ url = "https://files.pythonhosted.org/packages/4b/30/6f2fce1f1f205fc9323255b216ca8a235b15860c34b6798f810f05828e32/markupsafe-3.0.3-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:b8512a91625c9b3da6f127803b166b629725e68af71f8184ae7e7d54686a56d6", size = 23284, upload-time = "2025-09-27T18:36:58.833Z" },
{ url = "https://files.pythonhosted.org/packages/58/47/4a0ccea4ab9f5dcb6f79c0236d954acb382202721e704223a8aafa38b5c8/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:9b79b7a16f7fedff2495d684f2b59b0457c3b493778c9eed31111be64d58279f", size = 24801, upload-time = "2025-09-27T18:36:59.739Z" },
{ url = "https://files.pythonhosted.org/packages/6a/70/3780e9b72180b6fecb83a4814d84c3bf4b4ae4bf0b19c27196104149734c/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:12c63dfb4a98206f045aa9563db46507995f7ef6d83b2f68eda65c307c6829eb", size = 22769, upload-time = "2025-09-27T18:37:00.719Z" },
{ url = "https://files.pythonhosted.org/packages/98/c5/c03c7f4125180fc215220c035beac6b9cb684bc7a067c84fc69414d315f5/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:8f71bc33915be5186016f675cd83a1e08523649b0e33efdb898db577ef5bb009", size = 23642, upload-time = "2025-09-27T18:37:01.673Z" },
{ url = "https://files.pythonhosted.org/packages/80/d6/2d1b89f6ca4bff1036499b1e29a1d02d282259f3681540e16563f27ebc23/markupsafe-3.0.3-cp313-cp313t-win32.whl", hash = "sha256:69c0b73548bc525c8cb9a251cddf1931d1db4d2258e9599c28c07ef3580ef354", size = 14612, upload-time = "2025-09-27T18:37:02.639Z" },
{ url = "https://files.pythonhosted.org/packages/2b/98/e48a4bfba0a0ffcf9925fe2d69240bfaa19c6f7507b8cd09c70684a53c1e/markupsafe-3.0.3-cp313-cp313t-win_amd64.whl", hash = "sha256:1b4b79e8ebf6b55351f0d91fe80f893b4743f104bff22e90697db1590e47a218", size = 15200, upload-time = "2025-09-27T18:37:03.582Z" },
{ url = "https://files.pythonhosted.org/packages/0e/72/e3cc540f351f316e9ed0f092757459afbc595824ca724cbc5a5d4263713f/markupsafe-3.0.3-cp313-cp313t-win_arm64.whl", hash = "sha256:ad2cf8aa28b8c020ab2fc8287b0f823d0a7d8630784c31e9ee5edea20f406287", size = 13973, upload-time = "2025-09-27T18:37:04.929Z" },
{ url = "https://files.pythonhosted.org/packages/33/8a/8e42d4838cd89b7dde187011e97fe6c3af66d8c044997d2183fbd6d31352/markupsafe-3.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:eaa9599de571d72e2daf60164784109f19978b327a3910d3e9de8c97b5b70cfe", size = 11619, upload-time = "2025-09-27T18:37:06.342Z" },
{ url = "https://files.pythonhosted.org/packages/b5/64/7660f8a4a8e53c924d0fa05dc3a55c9cee10bbd82b11c5afb27d44b096ce/markupsafe-3.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c47a551199eb8eb2121d4f0f15ae0f923d31350ab9280078d1e5f12b249e0026", size = 12029, upload-time = "2025-09-27T18:37:07.213Z" },
{ url = "https://files.pythonhosted.org/packages/da/ef/e648bfd021127bef5fa12e1720ffed0c6cbb8310c8d9bea7266337ff06de/markupsafe-3.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f34c41761022dd093b4b6896d4810782ffbabe30f2d443ff5f083e0cbbb8c737", size = 24408, upload-time = "2025-09-27T18:37:09.572Z" },
@ -320,22 +302,48 @@ wheels = [
]
[[package]]
name = "watchdog"
version = "6.0.0"
name = "watchfiles"
version = "1.2.0"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/db/7d/7f3d619e951c88ed75c6037b246ddcf2d322812ee8ea189be89511721d54/watchdog-6.0.0.tar.gz", hash = "sha256:9ddf7c82fda3ae8e24decda1338ede66e1c99883db93711d8fb941eaa2d8c282", size = 131220, upload-time = "2024-11-01T14:07:13.037Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/68/98/b0345cabdce2041a01293ba483333582891a3bd5769b08eceb0d406056ef/watchdog-6.0.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:490ab2ef84f11129844c23fb14ecf30ef3d8a6abafd3754a6f75ca1e6654136c", size = 96480, upload-time = "2024-11-01T14:06:42.952Z" },
{ url = "https://files.pythonhosted.org/packages/85/83/cdf13902c626b28eedef7ec4f10745c52aad8a8fe7eb04ed7b1f111ca20e/watchdog-6.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:76aae96b00ae814b181bb25b1b98076d5fc84e8a53cd8885a318b42b6d3a5134", size = 88451, upload-time = "2024-11-01T14:06:45.084Z" },
{ url = "https://files.pythonhosted.org/packages/fe/c4/225c87bae08c8b9ec99030cd48ae9c4eca050a59bf5c2255853e18c87b50/watchdog-6.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a175f755fc2279e0b7312c0035d52e27211a5bc39719dd529625b1930917345b", size = 89057, upload-time = "2024-11-01T14:06:47.324Z" },
{ url = "https://files.pythonhosted.org/packages/a9/c7/ca4bf3e518cb57a686b2feb4f55a1892fd9a3dd13f470fca14e00f80ea36/watchdog-6.0.0-py3-none-manylinux2014_aarch64.whl", hash = "sha256:7607498efa04a3542ae3e05e64da8202e58159aa1fa4acddf7678d34a35d4f13", size = 79079, upload-time = "2024-11-01T14:06:59.472Z" },
{ url = "https://files.pythonhosted.org/packages/5c/51/d46dc9332f9a647593c947b4b88e2381c8dfc0942d15b8edc0310fa4abb1/watchdog-6.0.0-py3-none-manylinux2014_armv7l.whl", hash = "sha256:9041567ee8953024c83343288ccc458fd0a2d811d6a0fd68c4c22609e3490379", size = 79078, upload-time = "2024-11-01T14:07:01.431Z" },
{ url = "https://files.pythonhosted.org/packages/d4/57/04edbf5e169cd318d5f07b4766fee38e825d64b6913ca157ca32d1a42267/watchdog-6.0.0-py3-none-manylinux2014_i686.whl", hash = "sha256:82dc3e3143c7e38ec49d61af98d6558288c415eac98486a5c581726e0737c00e", size = 79076, upload-time = "2024-11-01T14:07:02.568Z" },
{ url = "https://files.pythonhosted.org/packages/ab/cc/da8422b300e13cb187d2203f20b9253e91058aaf7db65b74142013478e66/watchdog-6.0.0-py3-none-manylinux2014_ppc64.whl", hash = "sha256:212ac9b8bf1161dc91bd09c048048a95ca3a4c4f5e5d4a7d1b1a7d5752a7f96f", size = 79077, upload-time = "2024-11-01T14:07:03.893Z" },
{ url = "https://files.pythonhosted.org/packages/2c/3b/b8964e04ae1a025c44ba8e4291f86e97fac443bca31de8bd98d3263d2fcf/watchdog-6.0.0-py3-none-manylinux2014_ppc64le.whl", hash = "sha256:e3df4cbb9a450c6d49318f6d14f4bbc80d763fa587ba46ec86f99f9e6876bb26", size = 79078, upload-time = "2024-11-01T14:07:05.189Z" },
{ url = "https://files.pythonhosted.org/packages/62/ae/a696eb424bedff7407801c257d4b1afda455fe40821a2be430e173660e81/watchdog-6.0.0-py3-none-manylinux2014_s390x.whl", hash = "sha256:2cce7cfc2008eb51feb6aab51251fd79b85d9894e98ba847408f662b3395ca3c", size = 79077, upload-time = "2024-11-01T14:07:06.376Z" },
{ url = "https://files.pythonhosted.org/packages/b5/e8/dbf020b4d98251a9860752a094d09a65e1b436ad181faf929983f697048f/watchdog-6.0.0-py3-none-manylinux2014_x86_64.whl", hash = "sha256:20ffe5b202af80ab4266dcd3e91aae72bf2da48c0d33bdb15c66658e685e94e2", size = 79078, upload-time = "2024-11-01T14:07:07.547Z" },
{ url = "https://files.pythonhosted.org/packages/07/f6/d0e5b343768e8bcb4cda79f0f2f55051bf26177ecd5651f84c07567461cf/watchdog-6.0.0-py3-none-win32.whl", hash = "sha256:07df1fdd701c5d4c8e55ef6cf55b8f0120fe1aef7ef39a1c6fc6bc2e606d517a", size = 79065, upload-time = "2024-11-01T14:07:09.525Z" },
{ url = "https://files.pythonhosted.org/packages/db/d9/c495884c6e548fce18a8f40568ff120bc3a4b7b99813081c8ac0c936fa64/watchdog-6.0.0-py3-none-win_amd64.whl", hash = "sha256:cbafb470cf848d93b5d013e2ecb245d4aa1c8fd0504e863ccefa32445359d680", size = 79070, upload-time = "2024-11-01T14:07:10.686Z" },
{ url = "https://files.pythonhosted.org/packages/33/e8/e40370e6d74ddba47f002a32919d91310d6074130fe4e17dabcafc15cbf1/watchdog-6.0.0-py3-none-win_ia64.whl", hash = "sha256:a1914259fa9e1454315171103c6a30961236f508b9b623eae470268bbcc6a22f", size = 79067, upload-time = "2024-11-01T14:07:11.845Z" },
dependencies = [
{ name = "anyio" },
]
sdist = { url = "https://files.pythonhosted.org/packages/cd/41/5e1a4bb12aac5f1493fa1bdc11154eca3b258ca4eba65d39c473fe19d8e9/watchfiles-1.2.0.tar.gz", hash = "sha256:c995fba777f1ea992f090f9236e9284cf7a5d1a0130dd5a3d82c598cacd76838", size = 108252, upload-time = "2026-05-18T04:32:04.251Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/e7/54/a9c7ea9a82a4ac65e7004c0a03920b5cdd2f9c3b678757d9cd425aa51d53/watchfiles-1.2.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:b8c8358484d5fa12ef34f05b7f4168eaf1932f408725ff6d023c33ec17bd79d4", size = 400205, upload-time = "2026-05-18T04:32:05.153Z" },
{ url = "https://files.pythonhosted.org/packages/aa/5d/c9ab3534374a4a67450696905d6ef16a04405448b8dc52bd752ae50423d4/watchfiles-1.2.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:9f04b092229ad2c50126dd3c922c8822e51e605993764a33058d4a791ab42281", size = 392508, upload-time = "2026-05-18T04:30:54.849Z" },
{ url = "https://files.pythonhosted.org/packages/26/ca/1ad30103535cf0cecd7b993e8d50edc5351b1820e38f2d22e3df58962feb/watchfiles-1.2.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:7a7ce236284f002a156f70add88efe5c70879cccbb658be0822c54b1306fc09d", size = 452448, upload-time = "2026-05-18T04:30:53.727Z" },
{ url = "https://files.pythonhosted.org/packages/37/a1/ceee2cdf2afbd715fa07758d39c9859513eae411b23196f7fd039e5feedd/watchfiles-1.2.0-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:b9909cc2b48468b575eefa944919e1fe8a36c5849d5c7c168f80a8c1db69398e", size = 459605, upload-time = "2026-05-18T04:30:23.312Z" },
{ url = "https://files.pythonhosted.org/packages/e8/f6/421e30fd1cb3907a84ed92ab3f1983e37ba2dca015e9a894a048418417a2/watchfiles-1.2.0-cp314-cp314-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:0a37faaed405c67e28e6be45a1fa4f206ef5a2860f27c237db9fa30704c38242", size = 490757, upload-time = "2026-05-18T04:30:47.358Z" },
{ url = "https://files.pythonhosted.org/packages/41/b0/55ed1b97ed08be7bba6f9a541cac15f2a858e1d74d2b07b6da70a82aab00/watchfiles-1.2.0-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9649193aa27bd9ff2e80ff29bfaa93085496c7a3a377592823cc58b77ee88add", size = 568672, upload-time = "2026-05-18T04:30:38.915Z" },
{ url = "https://files.pythonhosted.org/packages/d1/cf/d8ae8a80dd7bafab395ea7681c10237311bbf34d37704a8c744e7cf31fc7/watchfiles-1.2.0-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:4e4ff8e37f99cf1da89e255e07c9c4b37c214038c4283707bdec308cb1b0ea1f", size = 464197, upload-time = "2026-05-18T04:30:09.914Z" },
{ url = "https://files.pythonhosted.org/packages/7c/8a/3076c496ca8dafe0e8cd03fcebdfc47be4b1174b4e5b24ff6e396e6b3af2/watchfiles-1.2.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:054dc20fd2e3132b4c3883b4a00d72fd6e1f56fdaf89fccd12e8057d74cd74d7", size = 453181, upload-time = "2026-05-18T04:30:14.829Z" },
{ url = "https://files.pythonhosted.org/packages/e5/10/9745e17c98e7b8a86454df0a3c7b5686bd650383f1e9f26e4ebcbd6cc0c0/watchfiles-1.2.0-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:e140ed30ebde76796b686e67c182cff10ea2fbab186fafd1560f74bb5a473a6e", size = 465109, upload-time = "2026-05-18T04:30:28.123Z" },
{ url = "https://files.pythonhosted.org/packages/8f/95/8ef4a95481d3e0cb52d62a06fa6e972e81424be2d9698b91a2fecca9904c/watchfiles-1.2.0-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:bb7e52ecf68ba46d22df23467b87cffeb2146908aa523ebfe803019618cfda06", size = 630653, upload-time = "2026-05-18T04:31:49.304Z" },
{ url = "https://files.pythonhosted.org/packages/fd/e4/3b3bf36b0f829b50c6ebcb8d031583863c59f923d6a6af3d485e470d0fac/watchfiles-1.2.0-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:23282a321c8baf9b3a3c4afff673f9fe65eb7fdc2338d765ccad9d3d1916a5ba", size = 657838, upload-time = "2026-05-18T04:31:06.497Z" },
{ url = "https://files.pythonhosted.org/packages/21/b1/6cbbb50c1f3002ab568777d44aa21206dfb8807a840990c4037523b51812/watchfiles-1.2.0-cp314-cp314-win32.whl", hash = "sha256:c0db965c5f79aa49fe672d297cf1febc5ad149b658594944f49a54a2b96270a7", size = 275108, upload-time = "2026-05-18T04:30:06.891Z" },
{ url = "https://files.pythonhosted.org/packages/92/45/190ce6db8dcb4536682cf75d3889ff1a27182a58cb519d343cb6d9ea63d8/watchfiles-1.2.0-cp314-cp314-win_amd64.whl", hash = "sha256:71283b39fd17e5408eb123bd37aeecfd9d54c81fc184421943208aadb879d103", size = 288441, upload-time = "2026-05-18T04:32:12.901Z" },
{ url = "https://files.pythonhosted.org/packages/74/0d/3eae1c2313ab08378431d907c3f8095ecca00f3eda33111cf4f0f2591799/watchfiles-1.2.0-cp314-cp314-win_arm64.whl", hash = "sha256:c5c19526f4e54a00f2666a6c0e9e40d582c09e865055ea7378bf0009aab857b3", size = 280684, upload-time = "2026-05-18T04:31:26.902Z" },
{ url = "https://files.pythonhosted.org/packages/b1/75/fb64e6c25d6b5ca636d03df34ffb1c6e9873303e76d27967e045f8df088f/watchfiles-1.2.0-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:d73a585accffa5ae39c17264c36ec3166d2fad7000c780f5ef83b2722afb9dd2", size = 398857, upload-time = "2026-05-18T04:32:17.108Z" },
{ url = "https://files.pythonhosted.org/packages/73/4e/9f7adf01754cbf81843722ccfec169d8f26c69778281a302855cecd2ee08/watchfiles-1.2.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:ae99b14c5f21e026e0e9d96f40e07d8570ebee6cafd9d8fc318354606daa7a28", size = 392413, upload-time = "2026-05-18T04:31:07.911Z" },
{ url = "https://files.pythonhosted.org/packages/47/c8/bec626bcc2d69f44b9acb24ce7d60ed7b16b73628eea747fcbd169d8edda/watchfiles-1.2.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4429f3b105524a10b72c3a819b091c495d2811d419c1e1e8df773a5a5974f831", size = 452409, upload-time = "2026-05-18T04:31:20.142Z" },
{ url = "https://files.pythonhosted.org/packages/00/b7/b6362068e81e7c556d155a34c35d40ac3ef42d747b06d7f6e5bf58e359c2/watchfiles-1.2.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:43d818978d06062d9b22c4fab2ebe44cf5213d42dc8e62bda8c2760cfa2eeb33", size = 458827, upload-time = "2026-05-18T04:32:06.219Z" },
{ url = "https://files.pythonhosted.org/packages/67/f8/9a813fa42afb1e0b4625e75f0479826644d3ee8dc287e093799bc01f390c/watchfiles-1.2.0-cp314-cp314t-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:b9f732dc58b2dbe69e464ccf8fff7a03b0dd0be439da4c0720d3558527d3d6b4", size = 490104, upload-time = "2026-05-18T04:31:56.034Z" },
{ url = "https://files.pythonhosted.org/packages/2f/bf/27dfb6094ca4c9aad21298b5525b6c53cb36121ee454331d05161e58d130/watchfiles-1.2.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:8f200104103feb097de4cab8fe4f5dd18a2026934c7dea98c55a2f5fd6d5a33b", size = 571360, upload-time = "2026-05-18T04:31:57.133Z" },
{ url = "https://files.pythonhosted.org/packages/fb/39/44a096d67270ea93df91d33877dbe91fbda3aa4f8ec2edf799d93eda8736/watchfiles-1.2.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:63ac26eefbf4af1741247d6fb68b11c49a25b2f7413fbd318a83a12aaa9cf666", size = 464644, upload-time = "2026-05-18T04:30:57.33Z" },
{ url = "https://files.pythonhosted.org/packages/0e/80/c7472203bad6268e3ef1ad260739704847898938ad7ea8b63a5131f46b50/watchfiles-1.2.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0c4997d4e4a55f0d02b6cde327322daf3a0400e5df6c6b15948994bf72497925", size = 454771, upload-time = "2026-05-18T04:30:48.736Z" },
{ url = "https://files.pythonhosted.org/packages/51/cf/3b10b268b4b7f0fc26e9debb5eef1998b515887840f444cd3ec80c688755/watchfiles-1.2.0-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:4c887eba18b7945ac73067a8b4a66f21cd46c2539b2bc68588f7be6c7eb6d26b", size = 463494, upload-time = "2026-05-18T04:31:33.826Z" },
{ url = "https://files.pythonhosted.org/packages/3d/3e/a4302545cd589262a0dc7d140e86f7688eba3f9c72776c27f7e23b8864c4/watchfiles-1.2.0-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:3416ff151bb6b5a8d8d11664974fbef4d9305b9b2957839ab5a270468fd8df30", size = 629383, upload-time = "2026-05-18T04:31:15.596Z" },
{ url = "https://files.pythonhosted.org/packages/db/99/d5649df0a9a410d45b7c882304d0b790903ac9b6e8f2cfd12114e0c6b9f2/watchfiles-1.2.0-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:0e831a271c035d89789cffc386b6aa1375f39f1cd25eb7ca0997e4970d152fc5", size = 656093, upload-time = "2026-05-18T04:31:58.707Z" },
{ url = "https://files.pythonhosted.org/packages/92/b9/362702539275019a54dd2e94511b31a9b89c5f9e6a21966de7eb692549fc/watchfiles-1.2.0-cp315-cp315-macosx_10_12_x86_64.whl", hash = "sha256:37a6721cdf3f65dbb13aa9503510ccb4451603ac837e44d265d7992a597e1374", size = 400109, upload-time = "2026-05-18T04:31:16.879Z" },
{ url = "https://files.pythonhosted.org/packages/8f/75/71d5ba62db781e5587bded1d944c675374bc4aa37ff33d5018d98e8b6538/watchfiles-1.2.0-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:2b37d10b5a63bd4d87e18472d80fa525bd670586fae62e5dd580452764879b65", size = 392167, upload-time = "2026-05-18T04:31:28.058Z" },
{ url = "https://files.pythonhosted.org/packages/3c/01/c66dd95d0423fe30d31820e2d1d5bda773764131bbb6ac0cb1cf303ac328/watchfiles-1.2.0-cp315-cp315-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0a105bc2283f67e8fbec74253ec2d94925de92ed72c0393f1206bf326b7b7b69", size = 452372, upload-time = "2026-05-18T04:31:00.836Z" },
{ url = "https://files.pythonhosted.org/packages/91/15/2fe99557e72f85627c6a8eed50d889e8d101623e060a22ad75b875cb932d/watchfiles-1.2.0-cp315-cp315-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:5327989a465505f05cfe06f04fa9d0c2fd5432bb243e10e6f012b1bdca3c8579", size = 459596, upload-time = "2026-05-18T04:31:34.96Z" },
{ url = "https://files.pythonhosted.org/packages/ed/23/d4acfa0023367428ed48351b3b9b267893037b6cadae55620c61c24bcfd4/watchfiles-1.2.0-cp315-cp315-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:ecb47f183a8025b2aa18b546725c3657e542112ae9c0613a2af79b4fa8d04ad7", size = 490869, upload-time = "2026-05-18T04:31:59.923Z" },
{ url = "https://files.pythonhosted.org/packages/a4/5f/3164cbdce06c9fb95c4f7b9e2f9760b5e2797af43a9ecc317ef42a23a278/watchfiles-1.2.0-cp315-cp315-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:8520a4ab0e37f770afc34459c4f8f7019e153f9124dc101c15538365875d1ab2", size = 571641, upload-time = "2026-05-18T04:32:00.948Z" },
{ url = "https://files.pythonhosted.org/packages/41/e6/85d3731c55e65cd7690f3f803d24c139588aaf863e4bf2148fe7a7fa1a19/watchfiles-1.2.0-cp315-cp315-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:71cd71740ed2c15211ebb237ced4e39a1cdf6f80566e5fe95428da1626f4fde6", size = 464444, upload-time = "2026-05-18T04:30:34.298Z" },
{ url = "https://files.pythonhosted.org/packages/f4/7d/562641012b8b09872742c3b8adf9629ec479fd78f8d68ae4a0c13da8add6/watchfiles-1.2.0-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f88af53d6ddaf72179ef613ddc905e6f4785f712b49b80b3bef9f3525e6194b4", size = 453593, upload-time = "2026-05-18T04:31:23.464Z" },
{ url = "https://files.pythonhosted.org/packages/56/fe/cb8ef3d6f929d14158fdaaad9925985b7310abc9384dcd4d82dd0016fb59/watchfiles-1.2.0-cp315-cp315-manylinux_2_31_riscv64.whl", hash = "sha256:cee9d5efd929efdac5f7e58f72b3376f676b64050a91c5b99a7094c5b2317488", size = 465096, upload-time = "2026-05-18T04:31:30.384Z" },
{ url = "https://files.pythonhosted.org/packages/25/91/80908e835e100527a9267147b08c0eee1fa6ab0ffec15edc04d1d44885f7/watchfiles-1.2.0-cp315-cp315-musllinux_1_1_aarch64.whl", hash = "sha256:b718bf356bbc15e559bd8ef41782b573b8ae0e3f177ab244b440568d7ea02cfb", size = 630638, upload-time = "2026-05-18T04:30:49.89Z" },
{ url = "https://files.pythonhosted.org/packages/46/4b/95ab2f256bb4af3cb2eb23b9317bda984ee6e0f11733a5c004a6c95b06e3/watchfiles-1.2.0-cp315-cp315-musllinux_1_1_x86_64.whl", hash = "sha256:922c0e019fe68b3ae392965a766b02a71ba1168c932cebc3733cd52c5fe5b377", size = 657684, upload-time = "2026-05-18T04:31:32.027Z" },
]

View file

@ -11,6 +11,7 @@ from datetime import UTC, datetime
from pathlib import Path
from typing import TypedDict
from fetch_pypi_downloads_via_clickpy import normalize
from jinja2 import Environment, FileSystemLoader
from readme_parser import AlsoSee, ParsedGroup, ParsedSection, parse_readme, parse_sponsors, slugify
@ -52,6 +53,7 @@ class TemplateEntry(TypedDict):
groups: list[str]
subcategories: list[TemplateSubcategory]
stars: int | None
downloads: int | None
owner: str | None
last_commit_at: str | None
source_type: str | None
@ -96,21 +98,41 @@ def load_stars(path: Path) -> dict[str, dict]:
return {}
def sort_entries(entries: Sequence[TemplateEntry]) -> list[TemplateEntry]:
"""Sort entries by stars descending, then name ascending.
def load_downloads(path: Path) -> dict[str, int]:
"""Load last-30-day download counts from the TSV cache, keyed by normalized README name.
Three tiers: starred entries first, stdlib second, other non-starred last.
Columns: name, package, downloads, fetched_at. Skips the header and
NOT_FOUND rows. Returns empty dict if the file doesn't exist.
"""
if not path.exists():
return {}
downloads: dict[str, int] = {}
for line in path.read_text(encoding="utf-8").splitlines()[1:]:
parts = line.split("\t")
if len(parts) >= 3 and parts[2].isdigit():
downloads[parts[0]] = int(parts[2])
return downloads
def sort_entries(entries: Sequence[TemplateEntry]) -> list[TemplateEntry]:
"""Sort entries by downloads descending, then name ascending.
Four tiers: entries with download counts first, then starred entries by
stars descending, then stdlib, then the rest.
"""
def sort_key(entry: TemplateEntry) -> tuple[int, int, int, str]:
downloads = entry["downloads"]
stars = entry["stars"]
name = entry["name"].lower()
if downloads is not None:
return (0, -downloads, 0, name)
if stars is not None:
builtin = 1 if entry.get("source_type") == "Built-in" else 0
return (0, -stars, builtin, name)
return (1, -stars, builtin, name)
if entry.get("source_type") == "Built-in":
return (1, 0, 0, name)
return (2, 0, 0, name)
return (2, 0, 0, name)
return (3, 0, 0, name)
return sorted(entries, key=sort_key)
@ -481,6 +503,7 @@ def extract_entries(
groups=[],
subcategories=[],
stars=None,
downloads=None,
owner=None,
last_commit_at=None,
source_type=detect_source_type(entry["url"]),
@ -535,6 +558,7 @@ def build(repo_root: Path) -> None:
build_date = datetime.now(UTC)
stars_data = load_stars(website / "data" / "github_stars.json")
downloads_data = load_downloads(website / "data" / "pypi_downloads.tsv")
repo_self = stars_data.get("vinta/awesome-python", {})
repo_stars = None
@ -551,6 +575,9 @@ def build(repo_root: Path) -> None:
entry["stars"] = sd["stars"]
entry["owner"] = sd["owner"]
entry["last_commit_at"] = sd.get("last_commit_at", "")
# Built-in entries would hit same-named PyPI backports (e.g. asyncio), not the stdlib.
if entry.get("source_type") != "Built-in":
entry["downloads"] = downloads_data.get(normalize(entry["name"]))
entries = sort_entries(entries)
category_urls = {cat["name"]: category_path(cat) for cat in categories}

View file

@ -0,0 +1,42 @@
{
"autobahn-python": { "package": "autobahn", "reason": null },
"azure-sdk-for-python": { "package": null, "reason": "monorepo umbrella; ships as many azure-* packages, no single package represents it" },
"cloud-init": { "package": null, "reason": "installed via distro images, not pip" },
"concurrent-futures": { "package": null, "reason": "stdlib module" },
"cpython": { "package": null, "reason": "not pip-installable; the cpython PyPI name was squatted" },
"devpi": { "package": "devpi-server", "reason": "devpi is a deprecated metapackage; the server package carries real usage" },
"difflib": { "package": null, "reason": "stdlib module" },
"django-ai-plugins": { "package": null, "reason": "GitHub-only so far; young project, remap if it publishes" },
"django-db-models": { "package": null, "reason": "part of Django, not a package" },
"django-rest-framework": { "package": "djangorestframework", "reason": "django-rest-framework is a dead alias package" },
"django-rules": { "package": "rules", "reason": "PyPI django-rules is an abandoned unrelated fork; dfunckt's project publishes as rules" },
"fasthtml": { "package": "python-fasthtml", "reason": null },
"geodjango": { "package": null, "reason": "part of Django (django.contrib.gis), not a package" },
"google-cloud-python": { "package": null, "reason": "monorepo umbrella; ships as many google-cloud-* packages" },
"graphify": { "package": null, "reason": "GitHub-only so far; young project, remap if it publishes" },
"httpx-url": { "package": null, "reason": "class in the httpx package, not a package" },
"jinja": { "package": "jinja2", "reason": "PyPI jinja is Jinja1; current releases publish as jinja2" },
"mem0": { "package": "mem0ai", "reason": null },
"micropython": { "package": null, "reason": "interpreter distributed as firmware builds, not pip" },
"mimetypes": { "package": null, "reason": "stdlib module" },
"odoo": { "package": null, "reason": "self-hosted suite installed from odoo.com, not pip" },
"pangu-py": { "package": "pangu", "reason": null },
"playwright-python": { "package": "playwright", "reason": null },
"pyenv": { "package": null, "reason": "installed via git/homebrew; PyPI pyenv is a defunct shim" },
"pypy": { "package": null, "reason": "interpreter distributed via pypy.org, not pip" },
"python-patterns": { "package": null, "reason": "reference repo, not a package; PyPI name held by unrelated 2012 project" },
"pytorch": { "package": "torch", "reason": "PyPI pytorch is a squatter; real package is torch" },
"renpy": { "package": null, "reason": "distributed via renpy.org; PyPI name was squatted, now 404" },
"sentry-skills": { "package": null, "reason": "agent skills repo, not a package" },
"social-engineer-toolkit": { "package": null, "reason": "GitHub-only, installed from source" },
"sqlite3": { "package": null, "reason": "stdlib module" },
"strawberry": { "package": "strawberry-graphql", "reason": "PyPI strawberry is an unrelated bookmarking service" },
"strawberry-django": { "package": "strawberry-graphql-django", "reason": null },
"thealgorithms": { "package": null, "reason": "educational monorepo, not a package" },
"tkinter": { "package": null, "reason": "stdlib module" },
"tomllib": { "package": null, "reason": "stdlib module" },
"trailofbits-skills": { "package": null, "reason": "agent skills repo, not a package" },
"warehouse": { "package": null, "reason": "the PyPI server itself; deployed, not pip-installed" },
"winpython": { "package": null, "reason": "distribution with its own installer; PyPI name is a 2012 relic" },
"zoneinfo": { "package": null, "reason": "stdlib module" }
}

View file

@ -1,5 +1,10 @@
#!/usr/bin/env python3
"""Fetch GitHub star counts and owner info for all GitHub repos in README.md."""
"""Fetch GitHub star counts and owner info for all GitHub repos in README.md.
The output file (data/github_stars.json) is gitignored; CI fetches it at
deploy time, so local runs are for previews only — never commit the data.
Entries removed from README.md leave harmless orphan keys behind.
"""
import json
import os

View file

@ -0,0 +1,82 @@
#!/usr/bin/env python3
"""Cross-check last-30-day PyPI download counts for given names via BigQuery.
Queries the canonical source ClickPy mirrors —
`bigquery-public-data.pypi.file_downloads` via the `bq` CLI — and prints
name<TAB>count TSV to stdout. Names resolve through
data/pypi_name_overrides.json, matching the cache sweep. Maintainer-local (needs a personal GCP
account) and print-only: data/pypi_downloads.tsv is written solely by
fetch_pypi_downloads_via_clickpy.py.
Targeted cross-checks only — full-README sweeps belong to ClickPy. The
dry-run scan estimate scales with the IN list (measured 2026-08-16:
~38 GB for 2 names, ~275 GB for 53, ~1.2 TB for the full README — past
both MAX_BYTES_BILLED and the 1 TiB/month free tier), and BigQuery
enforces MAX_BYTES_BILLED against that pre-run estimate, so oversized
name lists fail before billing. Actual billed bytes come in far lower
via cluster pruning (33.7 GB for a single name). The table is
partitioned on timestamp and clustered on the top-level `project`
column — filter on `project`, never `file.project`: both hold identical
values (verified 2026-08-16, 408M rows on one day, zero mismatches), but
only a `project` filter gets cluster pruning, and the `file` record
costs ~4x more to scan. Always --dry-run first to check the estimate.
Usage: python fetch_pypi_downloads_via_bigquery.py [--dry-run] NAME [NAME ...]
"""
import subprocess
import sys
from json import loads
from fetch_pypi_downloads_via_clickpy import resolve
MAX_BYTES_BILLED = 400_000_000_000
def fetch_bigquery(names: list[str], dry_run: bool) -> dict[str, int]:
in_list = ", ".join(f"'{name}'" for name in names)
query = (
"SELECT project, COUNT(*) AS downloads "
"FROM `bigquery-public-data.pypi.file_downloads` "
"WHERE DATE(timestamp) BETWEEN DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY) "
"AND CURRENT_DATE() "
f"AND project IN ({in_list}) "
"GROUP BY project"
)
cmd = ["bq", "query", "--use_legacy_sql=false", "--format=json", f"--maximum_bytes_billed={MAX_BYTES_BILLED}"]
if dry_run:
cmd.append("--dry_run")
cmd.append(query)
result = subprocess.run(cmd, capture_output=True, text=True)
if result.returncode != 0:
print(result.stderr, file=sys.stderr)
sys.exit(1)
if dry_run:
print(result.stdout.strip() or result.stderr.strip())
sys.exit(0)
rows = loads(result.stdout)
return {row["project"]: int(row["downloads"]) for row in rows}
def main() -> None:
dry_run = "--dry-run" in sys.argv
names = set()
for arg in sys.argv[1:]:
if arg == "--dry-run":
continue
pkg = resolve(arg)
if pkg is None:
print(f"{arg}: not pip-installable per pypi_name_overrides.json, skipping", file=sys.stderr)
else:
names.add(pkg)
names = sorted(names)
if not names:
print("Usage: python fetch_pypi_downloads_via_bigquery.py [--dry-run] NAME [NAME ...]", file=sys.stderr)
sys.exit(1)
counts = fetch_bigquery(names, dry_run)
for name in names:
print(f"{name}\t{counts.get(name, 'NOT_FOUND')}")
if __name__ == "__main__":
main()

View file

@ -0,0 +1,110 @@
#!/usr/bin/env python3
"""Fetch last-30-day PyPI download counts for all README entries via ClickPy.
ClickPy is ClickHouse's public mirror of the PyPI download dataset
(sql-clickhouse.clickhouse.com, user `demo`, no key, no personal
account): one batched query covers the full README in under a second.
Playground limits — 60 queries/hour/IP, 1000 result rows — sit far above
a full-README sweep. The per-day table is a SummingMergeTree, so the
query must sum(count) GROUP BY, never count raw rows. Counts include
mirror/CI traffic; never mix these figures with pypistats.org, which
excludes mirrors by default.
This script is the sole writer of data/pypi_downloads.tsv and rewrites it
from scratch each run, so entries removed from README.md drop out
naturally; names with no PyPI rows are written as NOT_FOUND. Counts are
looked up by README display name; when the display name differs from the
canonical PyPI package (a squatter or a dead predecessor would be
measured otherwise), add the mapping to the curated
data/pypi_name_overrides.json — normalized README name to
{"package": ..., "reason": ...}, where package is the real PyPI name
or null for projects that are not pip-installable so their row is
never queried, and reason records why. The file starts with a header row (name, package,
downloads, fetched_at) — package is the PyPI package the row actually
measured ("-" for null overrides) — and every row carries the sweep
date: a cache fetched within the last 7 days is current enough for
audit verdicts, so only re-run when older. Cross-checks against other
sources (fetch_pypi_downloads_via_bigquery.py,
fetch_pypi_downloads_via_pepy.py) print to stdout and never touch the
cache.
Usage: python fetch_pypi_downloads_via_clickpy.py
"""
import json
import re
from datetime import date
from pathlib import Path
import httpx
from readme_parser import parse_readme
DATA_DIR = Path(__file__).parent / "data"
OUT_FILE = DATA_DIR / "pypi_downloads.tsv"
OVERRIDES_FILE = DATA_DIR / "pypi_name_overrides.json"
README_PATH = Path(__file__).parent.parent / "README.md"
CLICKPY_URL = "https://sql-clickhouse.clickhouse.com/?user=demo"
# PyPI normalizes names to lowercase with runs of -, _, . collapsed to -.
PYPI_NAME_RE = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
def normalize(name: str) -> str:
return re.sub(r"[-_.]+", "-", name.lower())
def load_overrides() -> dict[str, str | None]:
"""Load curated overrides: normalized README name -> PyPI package to measure (None = never query).
Each file entry is {"package": str | null, "reason": str | null}; the reason is
documentation only — required for null packages, optional for remaps.
"""
raw = json.loads(OVERRIDES_FILE.read_text())
return {name: entry["package"] for name, entry in raw.items()}
def resolve(name: str) -> str | None:
"""Map a README display name to the PyPI package to measure. None = not pip-installable."""
normalized = normalize(name)
return load_overrides().get(normalized, normalized)
def collect_names(readme_text: str) -> list[str]:
names = set()
for group in parse_readme(readme_text):
for section in group["categories"]:
for entry in section["entries"]:
normalized = normalize(entry["name"])
if PYPI_NAME_RE.match(normalized):
names.add(normalized)
return sorted(names)
def fetch_clickpy(names: list[str]) -> dict[str, int]:
in_list = ", ".join(f"'{name}'" for name in names)
query = (
"SELECT project, sum(count) AS downloads "
"FROM pypi.pypi_downloads_per_day "
f"WHERE project IN ({in_list}) AND date >= today() - 30 "
"GROUP BY project FORMAT JSON"
)
resp = httpx.post(CLICKPY_URL, content=query, timeout=60)
resp.raise_for_status()
return {row["project"]: int(row["downloads"]) for row in resp.json()["data"]}
def main() -> None:
names = collect_names(README_PATH.read_text())
overrides = load_overrides()
packages = {name: overrides.get(name, name) for name in names}
query_names = sorted({pkg for pkg in packages.values() if pkg})
print(f"Querying {len(query_names)} package names...")
counts = fetch_clickpy(query_names)
fetched_at = date.today().isoformat()
rows = "\n".join(f"{name}\t{pkg or '-'}\t{counts.get(pkg, 'NOT_FOUND') if pkg else 'NOT_FOUND'}\t{fetched_at}" for name, pkg in packages.items())
OUT_FILE.write_text(f"name\tpackage\tdownloads\tfetched_at\n{rows}\n")
print(f"Done. {len(counts)}/{len(query_names)} names found on PyPI. Cached to {OUT_FILE}")
if __name__ == "__main__":
main()

View file

@ -0,0 +1,75 @@
#!/usr/bin/env python3
"""Spot-check last-30-day PyPI download counts via the pepy.tech API.
Cross-check for a handful of packages during audits — not for full-README
sweeps: the free API key is throttled to 5 requests/minute (10 burst), so
this script sleeps 12s between requests and 530 names would take ~2 hours
(use fetch_pypi_downloads_via_clickpy.py for bulk). Reads PEPY_TECH_API_KEY from the
environment, falling back to the repo-root .env. The v2 endpoint returns
~90 days of per-day per-version counts; this script sums the most recent
30 days present in the response across all versions. Names resolve
through data/pypi_name_overrides.json, matching the cache sweep. pepy counts include
mirror/CI traffic (CI filtering is a paid pepy feature), matching the
ClickPy/BigQuery figures; pypistats.org excludes mirrors, so never mix
the two in one comparison. Results print to stdout as TSV and are not
cached — data/pypi_downloads.tsv stays single-source.
Usage: python fetch_pypi_downloads_via_pepy.py NAME [NAME ...]
"""
import os
import sys
import time
from pathlib import Path
import httpx
from fetch_pypi_downloads_via_clickpy import resolve
ENV_FILE = Path(__file__).parent.parent / ".env"
PEPY_URL = "https://api.pepy.tech/api/v2/projects/{name}"
SECONDS_BETWEEN_REQUESTS = 12
def load_api_key() -> str:
key = os.environ.get("PEPY_TECH_API_KEY", "")
if not key and ENV_FILE.exists():
for line in ENV_FILE.read_text().splitlines():
name, sep, value = line.partition("=")
if sep and name.strip() == "PEPY_TECH_API_KEY":
key = value.strip()
if not key:
print("Error: PEPY_TECH_API_KEY not set (environment or repo-root .env).", file=sys.stderr)
sys.exit(1)
return key
def last_30_day_total(downloads_per_day: dict[str, dict[str, int]]) -> int:
recent_days = sorted(downloads_per_day)[-30:]
return sum(sum(downloads_per_day[day].values()) for day in recent_days)
def main() -> None:
if len(sys.argv) < 2:
print("Usage: python fetch_pypi_downloads_via_pepy.py NAME [NAME ...]", file=sys.stderr)
sys.exit(1)
names = []
for arg in sys.argv[1:]:
pkg = resolve(arg)
if pkg is None:
print(f"{arg}: not pip-installable per pypi_name_overrides.json, skipping", file=sys.stderr)
else:
names.append(pkg)
with httpx.Client(headers={"X-API-Key": load_api_key()}, timeout=30) as client:
for i, name in enumerate(names):
if i:
time.sleep(SECONDS_BETWEEN_REQUESTS)
resp = client.get(PEPY_URL.format(name=name))
if resp.status_code == 404:
print(f"{name}\tNOT_FOUND")
continue
resp.raise_for_status()
print(f"{name}\t{last_30_day_total(resp.json()['downloads'])}")
if __name__ == "__main__":
main()

View file

@ -1,4 +1,13 @@
"""Parse README.md into structured section data using markdown-it-py AST."""
"""Parse README.md into structured section data using markdown-it-py AST.
Empirically verified behavior worth knowing before editing README.md:
everything above `## Projects` is ignored; new subcategories need no
parser change (a bullet without a leading link plus indented entries);
a standalone all-bold paragraph inside the Projects region becomes a
Thematic Group marker; prose placed right after `## Categories` leaks
into llms.txt; the build's "Total entries" figure counts sub-items
(indented links under an entry), not just entries.
"""
from __future__ import annotations

View file

@ -5,7 +5,7 @@ function getScrollBehavior() {
}
let activeFilter = null;
let activeSort = { col: "stars", order: "desc" };
let activeSort = { col: "downloads", order: "desc" };
const searchInput = document.querySelector(".search");
const filterBar = document.querySelector(".filter-bar");
const filterValue = document.querySelector(".filter-value");
@ -211,7 +211,7 @@ function buildQueryString() {
const params = new URLSearchParams();
const query = searchInput ? searchInput.value.trim() : "";
if (query) params.set("q", query);
if (activeSort.col !== "stars" || activeSort.order !== "desc") {
if (activeSort.col !== "downloads" || activeSort.order !== "desc") {
params.set("sort", activeSort.col);
params.set("order", activeSort.order);
}
@ -238,6 +238,14 @@ function getSortValue(row, col) {
const num = parseInt(text, 10);
return isNaN(num) ? -1 : num;
}
if (col === "downloads") {
const text = row
.querySelector(".col-downloads")
.textContent.trim()
.replace(/,/g, "");
const num = parseInt(text, 10);
return isNaN(num) ? -1 : num;
}
if (col === "commit-time") {
const attr = row.querySelector(".col-commit").getAttribute("data-commit");
return attr ? new Date(attr).getTime() : 0;
@ -384,7 +392,7 @@ sortHeaders.forEach(function (th) {
if (activeSort.col === col) {
if (activeSort.order === defaultOrder)
activeSort = { col: col, order: altOrder };
else activeSort = { col: "stars", order: "desc" };
else activeSort = { col: "downloads", order: "desc" };
} else {
activeSort = { col: col, order: defaultOrder };
}
@ -467,7 +475,10 @@ if (backToTop) {
const order = params.get("order");
if (q && searchInput) searchInput.value = q;
if (
(sort === "name" || sort === "stars" || sort === "commit-time") &&
(sort === "name" ||
sort === "stars" ||
sort === "downloads" ||
sort === "commit-time") &&
(order === "desc" || order === "asc")
) {
activeSort = { col: sort, order: order };

View file

@ -893,6 +893,14 @@ th[data-sort].sort-asc::after {
letter-spacing: 0.02em;
}
.col-downloads {
width: 9.5rem;
text-align: right;
white-space: nowrap;
font-variant-numeric: tabular-nums;
color: var(--ink-soft);
}
.col-commit {
width: 9rem;
white-space: nowrap;
@ -1041,7 +1049,8 @@ th[data-sort].sort-asc::after {
color: var(--line-strong);
}
.expand-commit {
.expand-commit,
.expand-downloads {
display: none;
}
@ -1606,11 +1615,13 @@ th[data-sort].sort-asc::after {
justify-self: start;
}
.col-commit {
.col-commit,
.col-downloads {
display: none;
}
.expand-commit {
.expand-commit,
.expand-downloads {
display: inline;
}

View file

@ -117,6 +117,9 @@
<th class="col-name" data-sort="name">
<button type="button" class="sort-btn">Project Name</button>
</th>
<th class="col-downloads" data-sort="downloads">
<button type="button" class="sort-btn">PyPI Downloads</button>
</th>
<th class="col-stars" data-sort="stars">
<button type="button" class="sort-btn">GitHub Stars</button>
</th>
@ -150,6 +153,13 @@
else %}{{ category.name }}{% endif %}</span
>
</td>
<td class="col-downloads">
{% if entry.downloads is not none %}{{
"{:,}".format(entry.downloads) }}{% else %}<span
class="source-badge"
>Not on PyPI</span
>{% endif %}
</td>
<td class="col-stars">
{% if entry.stars is not none %}{{ "{:,}".format(entry.stars) }}{%
elif entry.source_type %}<span class="source-badge"
@ -213,14 +223,14 @@
{% if entry.description %}
<tr class="desc-row" aria-hidden="true">
<td class="col-num"></td>
<td colspan="5">
<td colspan="6">
<div class="desc-text">{{ entry.description | safe }}</div>
</td>
</tr>
{% endif %}
<tr class="expand-row" id="expand-{{ loop.index }}">
<td></td>
<td colspan="4">
<td colspan="5">
<div class="expand-content">
{% if entry.also_see %}
<div class="expand-also-see">
@ -249,6 +259,10 @@
><time datetime="{{ entry.last_commit_at }}"
>{{ entry.last_commit_at[:10] }}</time
></span
>{% endif %} {% if entry.downloads is not none %}<span
class="expand-downloads"
><span class="expand-sep">/</span>{{
"{:,}".format(entry.downloads) }} downloads/month</span
>{% endif %}
</div>
</div>

View file

@ -168,6 +168,9 @@
<th class="col-name" data-sort="name">
<button type="button" class="sort-btn">Project Name</button>
</th>
<th class="col-downloads" data-sort="downloads">
<button type="button" class="sort-btn">PyPI Downloads</button>
</th>
<th class="col-stars" data-sort="stars">
<button type="button" class="sort-btn">GitHub Stars</button>
</th>
@ -201,6 +204,13 @@
else %}{{ entry.categories[0] }}{% endif %}</span
>
</td>
<td class="col-downloads">
{% if entry.downloads is not none %}{{
"{:,}".format(entry.downloads) }}{% else %}<span
class="source-badge"
>Not on PyPI</span
>{% endif %}
</td>
<td class="col-stars">
{% if entry.stars is not none %}{{ "{:,}".format(entry.stars) }}{%
elif entry.source_type %}<span class="source-badge"
@ -260,14 +270,14 @@
{% if entry.description %}
<tr class="desc-row" aria-hidden="true" hidden>
<td class="col-num"></td>
<td colspan="5">
<td colspan="6">
<div class="desc-text">{{ entry.description | safe }}</div>
</td>
</tr>
{% endif %}
<tr class="expand-row" id="expand-{{ loop.index }}">
<td></td>
<td colspan="4">
<td colspan="5">
<div class="expand-content">
{% if entry.description %}
<div class="expand-desc">{{ entry.description | safe }}</div>
@ -298,6 +308,10 @@
><time datetime="{{ entry.last_commit_at }}"
>{{ entry.last_commit_at[:10] }}</time
></span
>{% endif %} {% if entry.downloads is not none %}<span
class="expand-downloads"
><span class="expand-sep">/</span>{{
"{:,}".format(entry.downloads) }} downloads/month</span
>{% endif %}
</div>
</div>

View file

@ -17,6 +17,7 @@ from build import (
detect_source_type,
extract_entries,
extract_github_repo,
load_downloads,
load_stars,
sort_entries,
subcategory_path,
@ -429,6 +430,42 @@ class TestBuild:
# Expand content present
assert "expand-content" in html
def test_build_with_downloads_renders_column(self, tmp_path):
readme = textwrap.dedent("""\
# T
## Projects
## Stuff
- [My-Lib](https://github.com/org/mylib) - On PyPI.
- [no-pypi](https://example.com/none) - Not on PyPI.
- [asyncio](https://docs.python.org/3/library/asyncio.html) - Built-in.
# Contributing
Done.
""")
(tmp_path / "README.md").write_text(readme, encoding="utf-8")
self._copy_real_templates(tmp_path)
data_dir = tmp_path / "website" / "data"
data_dir.mkdir(parents=True)
# Keyed by normalized README display name, like fetch_pypi_downloads_via_clickpy.py writes it
(data_dir / "pypi_downloads.tsv").write_text(
"name\tpackage\tdownloads\tfetched_at\nasyncio\tasyncio\t26305454\t2026-08-16\nmy-lib\tmy-lib\t1234567\t2026-08-16\n",
encoding="utf-8",
)
build(tmp_path)
html = (tmp_path / "website" / "output" / "index.html").read_text(encoding="utf-8")
assert "1,234,567" in html
# Built-in entries never show PyPI counts: the asyncio row is the backport package
assert "26,305,454" not in html
# Default sort: entries with download counts come first
assert html.index("My-Lib") < html.index("no-pypi")
def test_build_fails_when_group_and_category_slug_collide(self, tmp_path):
readme = textwrap.dedent("""\
# T
@ -974,6 +1011,7 @@ def _template_entry(name: str, stars: int | None, source_type: str | None = None
groups=[],
subcategories=[],
stars=stars,
downloads=None,
owner=None,
last_commit_at=None,
source_type=source_type,
@ -1199,3 +1237,16 @@ class TestAnnotateEntriesWithStars:
markdown = "- [foo](https://github.com/owner/foo) - A foo."
stars = {"owner/foo": {"stars": 5, "owner": "owner"}}
assert annotate_entries_with_stars(markdown, stars) == ("- [foo](https://github.com/owner/foo) - A foo. (5 GitHub stars)")
class TestLoadDownloads:
def test_parses_tsv_and_skips_not_found(self, tmp_path):
tsv = tmp_path / "pypi_downloads.tsv"
tsv.write_text(
"name\tpackage\tdownloads\tfetched_at\naiohttp\taiohttp\t649105404\t2026-08-16\npytorch\ttorch\t50000000\t2026-08-16\ndead-pkg\t-\tNOT_FOUND\t2026-08-16\n",
encoding="utf-8",
)
assert load_downloads(tsv) == {"aiohttp": 649105404, "pytorch": 50000000}
def test_missing_file_returns_empty(self, tmp_path):
assert load_downloads(tmp_path / "nope.tsv") == {}