dep-rank 0.2.0

Analyze GitHub repository dependents by star count.

dep-rank

Rank GitHub dependents by stars.

dep-rank finds the most popular repositories that depend on a given GitHub project. It scrapes GitHub's dependents page, enriches results via the GraphQL API, and works as a command-line tool.

Quick Start

pip install dep-rank
dep-rank deps https://github.com/django/django

CLI Reference

dep-rank deps — List top dependents

dep-rank deps https://github.com/django/django
dep-rank deps https://github.com/django/django --rows 20 --min-stars 100
dep-rank deps https://github.com/django/django --descriptions --format json
dep-rank deps https://github.com/django/django --packages

Option	Default	Description
--rows	10	Number of results
--min-stars	5	Minimum star count filter
--format	table	Output format: table or json
--descriptions	off	Fetch descriptions via GitHub API (requires token)
--packages	off	Search packages instead of repositories
--token	DEP_RANK_TOKEN	GitHub token
--max-pages	200	Maximum pages to scrape (ceiling 1000)
--concurrency	3	Max concurrent page fetches (1–10)
--no-adaptive-stop	off	Disable adaptive early-stop; scrape continues until exhaustion or --max-pages

dep-rank search — Search code in dependents

dep-rank search https://github.com/django/django "from django.db import"
dep-rank search https://github.com/django/django "middleware" --max-repos 20

Option	Default	Description
--max-repos	10	Maximum repos to search
--min-stars	50	Only search repos with this many stars
--token	DEP_RANK_TOKEN	GitHub token (required)
--max-pages	200	Maximum pages to scrape (ceiling 1000)
--concurrency	3	Max concurrent page fetches (1–10)

search always runs a bounded non-adaptive top-K scrape (--no-adaptive-stop is not exposed; adaptive early-stop is permanently disabled for this command).

Partial results

A scrape result (deps, and the search pre-pass) reports whether it finished: results include a complete flag and a reason. complete: false means the scrape stopped early — max_pages_reached (raise --max-pages), trend_converged (the adaptive heuristic judged the top-K stable; use --no-adaptive-stop to scrape until exhaustion or --max-pages), network_failure, or rate_limited. total_count/filtered_count are then lower bounds across the pages actually scraped, not population totals.

dep-rank cache — Manage cache

dep-rank cache stats    # Show cache size
dep-rank cache clear    # Clear all cached data

Authentication

Set the DEP_RANK_TOKEN environment variable with a GitHub personal access token:

export DEP_RANK_TOKEN=ghp_your_token_here

A token is effectively required for non-trivial use: unauthenticated GitHub HTML scraping is limited to ~60 requests/hour per IP, so unauthenticated runs are suitable only for small one-off scrapes. Set DEP_RANK_TOKEN to raise the limit.

What works without a token:

• dep-rank deps — core scraping and star ranking

What requires a token:

• --descriptions flag — fetches repo descriptions via GitHub GraphQL API
• dep-rank search — code search across dependents

Create a token at github.com/settings/tokens with public_repo scope.

How It Works

dep-rank uses a three-stage pipeline:

1. Scrape — fetches GitHub's /network/dependents HTML pages to discover all dependents and their approximate star counts
2. Enrich (optional) — one GraphQL batch query fetches accurate star counts and descriptions for the top N results (replaces 100 individual REST API calls)
3. Present — returns structured results as a Rich table

Responses are cached in a local SQLite database (~/.cache/dep-rank/) with ETag support for conditional requests. Expired pages are served immediately and refreshed in the background (stale-while-revalidate) on authenticated runs.

Development

# Prerequisites: Python 3.11+, uv
uv sync
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy dep_rank/

Acknowledgments

dep-rank is a full rewrite of ghtopdep by Andriy Orehov. The original project is licensed under MIT.

License

MIT — see LICENSE for details.