pypi-winnow-downloads 0.1.0

Self-hosted PyPI download badge service that winnows CI traffic out of download counts.

pypi-winnow-downloads

Self-hosted PyPI download badge service that winnows CI traffic out of download counts. Produces shields.io-compatible endpoint badges filtered by BigQuery's details.ci flag and an interactive-installer allowlist (pip, uv, poetry, pdm, pipenv, pipx) — more honest than any existing alternative for small or young Python packages.

The pip*/uv/poetry/pdm badge above is served by this project itself — eating our own dogfood. The endpoint went live with milestone M3 deployment on 2026-04-24 and currently shows 0 until the first release lands on PyPI; after that the count climbs automatically.

What the badge actually counts

The hero badge — labelled pip*/uv/poetry/pdm (Nd) — counts downloads that meet all of these conditions over the configured rolling window:

• details.ci != True (BigQuery's CI-detection flag is not set)
• details.installer.name is one of the interactive Python packaging tools: pip, uv, poetry, pdm, pipenv, or pipx (the asterisk in pip* covers pip itself plus pipenv and pipx, which delegate to pip and inherit its installer telemetry pattern)

Excluded (the things that inflate other badges):

• Mirrors: bandersnatch, Nexus, devpi, Artifactory, z3c.pypimirror
• Browser fetches via the PyPI web UI (installer_name == "Browser")
• Generic HTTP UAs used by scrapers and scanners (requests, curl, etc.)
• Unknown installer (installer_name == "None") — uncategorised traffic that in practice is dominated by automated scanners

For context on how much these can dwarf real installs: at v1 deploy time, one of the seed packages had 2,771 "non-CI" downloads in 30 days under a naïve mirror-and-all-installers query, of which 1,325 (48%) was bandersnatch alone and only 14 came from pip + uv + poetry + pdm. The honest signal is the 14.

The filter is fail-closed: a future pypinfo emitting a new mainstream installer will be excluded until the allowlist in src/pypi_winnow_downloads/collector.py is updated explicitly. That's a feature for a project whose pitch is honesty.

Install

pip install pypi-winnow-downloads

Run with a YAML config — copy config.example.yaml and edit:

winnow-collect --config /path/to/config.yaml

To deploy as a daily systemd timer plus a Caddy HTTPS service serving the output directory, see deploy/README.md.

Status

Alpha. Self-hosted reference deployment running at pypi-badges.intfar.com, producing daily badges for four target packages (the three seed packages in config.example.yaml plus pypi-winnow-downloads itself for the dogfood badge). Expect rough edges and possible breaking changes in the 0.x series.