DEV Community

Prabanjan R
Prabanjan R

Posted on

From a Flask Surprise to a PyPI Package: How I Built pipulse

#python #security #showdev #tooling

Every Python project has a requirements.txt. But here's the thing — most of us never really look at it. We install packages, add them to the file, and move on. We trust that everything in there is safe, maintained, and up to date.

Until it isn't.

The Problem That Started It All

A while back, I was working on a project using Flask. Everything was running fine locally — or so I thought. It was only later that I discovered the version I had installed was outdated. No warning. No indication. Just a silent, outdated dependency sitting in my project.

That got me thinking: how many developers are shipping projects with outdated or vulnerable packages without even knowing it?

The reality is:

  • Python packages go unmaintained all the time
  • Vulnerabilities get discovered in old versions regularly
  • A requirements.txt with 20 packages could have 5 problems you don't know about
  • Manually checking each package on PyPI is tedious and nobody actually does it

There are some tools out there, but nothing that gave me a complete picture in one shot — version status, vulnerability data, GitHub activity, and an overall health score, all from a single command.

So I built one.

Introducing pipulse

pipulse is a Python CLI tool that scans your requirements.txt and gives you a full dependency health report.

pip install pipulse
pipulse scan requirements.txt
Enter fullscreen mode Exit fullscreen mode

That's it. One command, and you get:

  • Whether each package is up to date, outdated, or ahead
  • Known vulnerabilities from the OSV database
  • GitHub activity — is the repo still maintained?
  • A health score (0–100) per package and an overall project score
  • Output in terminal, HTML, or JSON

Terminal Output 

                         pipulse Report
┌──────────┬─────────┬────────┬────────────┬───────┬───────┬──────────┬────────┐
│ Package  │ Current │ Latest │ Status     │ Vulns │ Stars │ Activity │ Health │
├──────────┼─────────┼────────┼────────────┼───────┬───────┼──────────┼────────┤
│ requests │ 2.28.0  │ 2.31.0 │ Outdated   │ 2     │ 51k   │ ACTIVE   │ 70     │
│ flask    │ 3.0.0   │ 3.0.0  │ Up-to-Date │ 0     │ 67k   │ ACTIVE   │ 100    │
│ pyjwt    │ 1.7.1   │ 2.8.0  │ Outdated   │ 3     │ 5k    │ ACTIVE   │ 55     │
└──────────┴─────────┴────────┴────────────┴───────┴───────┴──────────┴────────┘

Project pipulse Score: 75/100
Enter fullscreen mode Exit fullscreen mode

You can also generate a full HTML report:

pipulse scan requirements.txt --html
pipulse scan requirements.txt --json
pipulse scan requirements.txt --html --json
Enter fullscreen mode Exit fullscreen mode

The HTML report gives a dark-themed dashboard with summary cards, per-package badges, and color-coded health scores. The JSON output is useful if you want to plug the results into a CI pipeline or process them programmatically.

How It Works — The Architecture

The tool is built in Python and follows a straightforward pipeline:

requirements.txt
      │
      ▼
   Parser
      │
      ├──────────────────────────────────────┐
      ▼                                      ▼
 PyPI API                             OSV Database
 (latest version,                  (vulnerability
  repo URL)                           lookup)
      │                                      │
      ▼                                      │
 GitHub API                                  │
 (stars, last                                │
  commit date)                               │
      │                                      │
      └──────────────┬───────────────────────┘
                     ▼
             Scoring Engine
                     │
                     ▼
        ┌────────────┼────────────┐
        ▼            ▼            ▼
   Rich CLI      HTML Report   JSON Report
Enter fullscreen mode Exit fullscreen mode

APIs Used

1. PyPI JSON API
For every package in requirements.txt, we hit https://pypi.org/pypi/{package}/json to get the latest version and the repository URL.

2. OSV (Open Source Vulnerability) Database
We send the package name and installed version to https://api.osv.dev/v1/query. OSV returns any known CVEs or security advisories for that exact version. This is free, open, and requires no API key.

3. GitHub API
Using the repository URL from PyPI, we extract the owner and repo name and call the GitHub REST API to get star count and last updated date. From the date, we classify the repo as:

  • ACTIVE — updated within 90 days
  • STALE — updated within a year
  • ABANDONED — not updated in over a year

The Health Score

Each package starts at 100 and gets scored like this:

Factor Impact
Each vulnerability found −5
Package is outdated −15
Repository is stale −10
Repository is abandoned −30
10k+ GitHub stars +5
50k+ GitHub stars +10

The overall project score is the average across all packages.

Challenges I Faced

1. The Name Problem

My original project name was pyhealth — which turned out to be already taken on PyPI by a healthcare ML library. I had to rename everything. This sounds simple but it caused a chain of issues: virtual environment conflicts, import errors, cached egg-info pointing to the old name, and version comparison bugs that only showed up after the rename. Lesson learned — check PyPI for name availability before writing a single line of code.

2. GitHub API Rate Limiting

The GitHub unauthenticated API allows only 60 requests per hour. For a requirements.txt with more than 60 packages, the tool starts returning N/A for GitHub data silently. This is a known limitation in v0.1.0. The fix — adding GitHub token support — is planned for the next version. For now, the tool still works fully for version checking and vulnerability scanning even without GitHub data.

3. Packaging and pyproject.toml

First time publishing to PyPI taught me a lot about modern Python packaging. Things like the difference between license = "MIT" and license = {text = "MIT"}, the importance of classifiers for discoverability, and that a missing README.md gives you a blank PyPI page. Small things, but important when you're shipping something public.

What I Learned

  • APIs are powerful when combined. Three free APIs — PyPI, OSV, GitHub — together give you a surprisingly complete picture of a package's health.
  • Naming matters in open source. A good package name is short, memorable, and available. It took longer than expected to find one.
  • Ship the first version. It doesn't have to be perfect. GitHub token support, better error handling, CI integration — these can all come in v0.2.0. Getting something useful out there is more important than waiting for it to be complete.
  • Modern Python packaging is cleaner than it used to be. pyproject.toml alone is all you need — no setup.py, no setup.cfg, no extra files.

What's Next — v0.2.0

  • GitHub token support — pass a token to bypass the 60 req/hour limit and get reliable GitHub data for larger projects
  • CI/CD integration — exit with a non-zero code when health score drops below a threshold, so pipulse can block a failing build
  • More output options — badge generation, Markdown report
  • Support for pyproject.toml and poetry.lock — not just requirements.txt

Try It Yourself 

pip install pipulse
pipulse scan requirements.txt
Enter fullscreen mode Exit fullscreen mode

Run it on your project and see what comes up. If you find a bug, have a feature request, or just want to share what score your project got — drop it in the comments or open a GitHub issue.

Every piece of feedback helps shape what v0.2.0 looks like. 🚀

Built by Prabanjan R — first open source Python package, definitely not the last.

Top comments (0)