pipscout 0.1.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 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

🐍 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

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 and raw.githubusercontent.com (for the download stats). 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. 🔭