mirror of https://github.com/vinta/awesome-python.git synced 2026-10-02 08:23:10 +08:00

Files

T

Vinta ChenandClaude 59cc42e2c3 docs: sync AGENTS.md with the shortlist reform rules

AGENTS.md still carried pre-reform Key Rules (mandatory alphabetical
ordering, "quality over quantity" lanes-era language, no prune-sweep
commit exception, no live-verification rule). Bring it in line with
CLAUDE.md and CONTRIBUTING.md: downloads-descending tier ordering,
3+2 cap, sweep-commit exception, verification rule. Also record the
UV_PYTHON=3.13 workaround for Python-3.14-only machines in both files'
Makefile notes, and complete CLAUDE.md's Makefile target list.

Co-Authored-By: Claude <noreply@anthropic.com>

2026-08-16 00:38:48 +08:00

2.5 KiB

Raw Blame History

CLAUDE.md

Repository Overview

An opinionated list of Python frameworks, libraries, tools, and resources. Published at awesome-python.com.

Entry Guidelines

Refer to CONTRIBUTING.md for admission rules, quality requirements, rejection rules, and entry format. Apply these rules whenever adding or removing an entry, whether reviewing a PR or committing directly.

Structure

README.md: Source of truth. Hierarchical categories; entries ordered per the Key Rules below.
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 lint, make format, make typecheck, make fetch_github_stars. On machines with only Python 3.14, prefix uv-based targets with UV_PYTHON=3.13 (watchdog 6.0.0 ships no 3.14 wheel and the project sets no-build).
pyproject.toml: Uses uv for dependency management. Python >=3.13.

Key Rules

Ordering within a use case: obvious choices first, then challengers, each tier by PyPI downloads/month descending; no-signal entries last in tier, alphabetically. See CONTRIBUTING.md.
A shortlist, not a catalog: per use case, up to 3 obvious choices plus up to 2 challengers, hard maximum 5.
One project per PR.
One entry per commit when adding or deleting entries. Exception: a prune sweep is one commit per section, its body listing each removal with its reason. Format, wording, or categorization changes across multiple entries may be bundled in a single commit.
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. Training-data recollections alone are not evidence; verify before stating, and label anything unverifiable as a judgment call.
README.md is the single source of content truth.