🚀 PyPI Package Stats — Example Workflows

Ready-to-use GitHub Actions workflows for integrating ysskrishna/pypi-package-stats-action into CI pipelines.

Quick Start

- uses: ysskrishna/pypi-package-stats-action@v1
  id: stats
  with:
    package-name: 'requests'

- run: echo "Downloads last month: ${{ steps.stats.outputs.last-month-downloads }}"

Note: The id field (e.g. id: stats) is required to reference step outputs. If you only need the JSON file or Job Summary, you can omit it.

Inputs

Input	Description	Required	Default
package-name	PyPI package name to fetch statistics for	Yes	—
output-path	File path to write the JSON stats output	No	stats.json

Outputs

Output	Description
stats-json	Full JSON string of package statistics
name	Package name
version	Current package version on PyPI
last-day-downloads	Downloads in the last day
last-week-downloads	Downloads in the last week
last-month-downloads	Downloads in the last month

Accessing Stats

There are three ways to access the fetched statistics:

1. Step outputs — Reference outputs like steps.<id>.outputs.last-month-downloads in subsequent steps. Requires id on the action step.
2. JSON file — Stats are written to the output-path file (default: stats.json). Useful for artifacts or downstream processing.
3. Job Summary — A Markdown stats table is automatically added to the workflow run's Summary page. No configuration needed.

JSON Output Schema

The stats-json output and the file written to output-path contain the following structure:

{
  "package": {
    "name": "requests",
    "version": "2.32.3",
    "upload_time": "2024-05-29",
    "description": "Python HTTP for Humans.",
    "author": "Kenneth Reitz",
    "license": "Apache-2.0",
    "home_page": "https://requests.readthedocs.io",
    "pypi_url": "https://pypi.org/project/requests/"
  },
  "downloads": {
    "last_day": 2500000,
    "last_week": 17500000,
    "last_month": 75000000,
    "last_180d": 450000000
  },
  "python_versions": [
    { "version": "3.12", "downloads": 5000000, "percentage": 35.0 },
    { "version": "3.11", "downloads": 4000000, "percentage": 28.0 }
  ],
  "operating_systems": [
    { "os": "Linux", "downloads": 12000000, "percentage": 68.0 },
    { "os": "Windows", "downloads": 3500000, "percentage": 20.0 },
    { "os": "Darwin", "downloads": 2000000, "percentage": 12.0 }
  ]
}

Example workflows

Master workflow

Workflow	Description
🚀 Run All Examples	Trigger all four example workflows at once from the Actions tab

Individual examples

Example	Description
Basic — Print Stats	Fetch and print download stats
Check Download Threshold	Warn if monthly downloads fall below a threshold
Custom Output Path	Write stats JSON to a custom file path
Save Stats as Artifact	Save stats as a downloadable GitHub Actions artifact

License

MIT © Y. Siva Sai Krishna — see LICENSE for details.

Credits

Examples for pypi-package-stats-action. Built on pypi-package-stats.

---

Author's GitHub • Author's LinkedIn • GitHub Marketplace • pypi-package-stats-action • pypi-package-stats Documentation