pipscout 0.2.0

Stop googling “best python library for X”.
Tell pipscout what you're building. It combs through PyPI and hands you the package everyone actually uses — with receipts.

pip install pipscout
pipscout "pdf extraction"

That's it. 🔭 One command gets you the best pick, the runners-up, their monthly downloads, how fresh each release is, and the exact pip install line.

✨ Why you'll like it

🚀 Take it for a spin

pipscout "web scraping"                  # 🥇🥈🥉 top 5
pipscout "data validation" -n 10         # show me more
pipscout "http client" --json | jq       # pipe it anywhere
pipscout "pdf extraction" --deep         # also scan the names of all ~700k projects on PyPI
pipscout downloads pypdf pymupdf         # 📈 who's winning? downloads, rank, trend, chart
pipscout index                           # optional: pre-index the top 5,000 so READMEs are searchable too

👀 beautifulsoup4 won “web scraping” even though neither word is in its name — pipscout reads summaries and keywords (and, after pipscout index, READMEs), not just names.

Real results, fresh install, no index

📈 How many people use it?

Already have a package in mind? Get its download numbers straight away:

pipscout downloads pymupdf               # one package: the full card + a weekly chart
pipscout dl pypdf pymupdf pdfplumber     # several: a head-to-head table, 👑 for the leader
pipscout dl httpx --json                 # the raw numbers, incl. ~180 days of daily counts

One package gets a card:

• downloads yesterday, over the last 7 days and over the last 30 days
• its rank among PyPI's most-downloaded projects
• a ▲/▼ 30-day trend (compared with the 30 days before)
• a column chart of weekly downloads for the last ~6 months, plus the peak day

Several packages get a leaderboard with rank, week, month, share-of-the-leader bars, trend and a sparkline for each.

Daily numbers come from pypistats.org (mirrors excluded) and are cached for 12 hours. If pypistats can't be reached, pipscout still shows each package's 30-day total and rank from the top-15k download list.

🐍 From Python

from pipscout import recommend

for rec in recommend("pdf extraction", limit=2):
    print(f"{rec.name:<8} {rec.score:.2f}  {rec.downloads or 0:>12,} dl/mo")
    print("   ", rec.install, "|", "; ".join(rec.reasons))

pymupdf  0.46   101,779,570 dl/mo
    pip install pymupdf | summary matches 'pdf'; summary matches 'extract'; 101.8M downloads in the last 30 days
pypdf    0.30   151,277,866 dl/mo
    pip install pypdf | summary matches 'pdf'; description matches 'extract'; 151.3M downloads in the last 30 days

Download numbers are one call away too:

from pipscout import download_stats, download_stats_many

s = download_stats("pypdf")
s.last_day, s.last_week, s.last_month   # ints
s.rank                                   # position among the ~15k most-downloaded projects
s.trend                                  # last 30 days vs the 30 before, e.g. 0.12 == +12%
s.daily                                  # [("2026-04-01", 5123456), ...] ~180 days, oldest first
s.weekly                                 # the same, summed per week

for s in download_stats_many(["httpx", "aiohttp", "requests"]):
    print(s.name, s.last_month)

Each Recommendation has name, score, relevance, popularity, health, downloads, summary, version, last_release, homepage, install, reasons, warnings — plus .to_dict() for JSON.

🧠 How the magic works

PyPI's website search has no public API (and sits behind a bot wall), so pipscout brings its own brain:

  "i want pdf extraction"
          │
   1. 🗣️  understand ── drop filler · stem (extraction → extract) · add synonyms (extract ≈ parse ≈ read)
          │
   2. 🔎  shortlist ─── names of the ~15k most-downloaded projects
          │             + summaries & keywords from the bundled top-5k catalog
          │             + READMEs from your local index · + every name on PyPI with --deep
          │
   3. 📡  inspect ───── live metadata for the best 60 from PyPI's JSON API (parallel, cached 7 days)
          │
   4. 🏆  rank ──────── score = relevance² × popularity × √freshness

• relevance (0–1) — how many of your concepts a package covers, each weighted by how rare the word is on PyPI (so pdf outweighs data). A hit in the name or summary counts more than one buried in the README; a synonym counts a bit less than the real word. Anything under 0.5 is dropped.
• popularity — (monthly downloads ÷ 1B)^¼. A package used 10× more can beat a slightly more on-topic one… but never an off-topic one.
• freshness — 1.0 if released in the last year, sliding to 0.2 at five years, with an extra haircut for Inactive or Alpha status.

Download counts come from the excellent top-pypi-packages dataset (PyPI's public BigQuery stats, refreshed monthly).

🎛️ CLI reference

🤔 FAQ

Is it just sorting by downloads? Nope. Downloads only count once a package is on-topic — relevance is squared, so an off-topic giant (looking at you, requests) never wins a PDF query.

Why not just use PyPI search? It sorts by text match, not by what people actually use, has no API, and won't tell you a project died in 2017.

Does it phone home? Only to pypi.org, raw.githubusercontent.com (monthly download rankings) and, for pipscout downloads, pypistats.org. No telemetry, no accounts, no API keys.

It missed my favourite package! Try --deep, rephrase with the words the package would use to describe itself, or run pipscout index once so READMEs get searched too. PRs to the synonym list in text.py are very welcome.

🛠️ Hacking on it

git clone https://github.com/Meet2147/pythonLibraries && cd pythonLibraries/pipscout
pip install -e ".[dev]"
pytest                                                   # fully offline — PyPI is faked
python scripts/render_demo.py                            # re-shoot the terminal screenshots
pipscout index && python scripts/build_bundled_data.py   # refresh the bundled catalog

📜 License

MIT © Meet2147 — now go build something. 🔭