{"record":{"id":"e7fff85d208b2dba","repo":"jackwener/OpenCLI","slug":"pypi-downloads","errorCode":null,"errorMessage":"pypi downloads","messagePattern":"pypi downloads","errorType":"exception","errorClass":"EmptyResultError","httpStatus":null,"severity":"warning","filePath":"clis/pypi/downloads.js","lineNumber":45,"sourceCode":"    name: 'downloads',\n    access: 'read',\n    description: 'PyPI download stats for a package (recent totals or full daily history)',\n    domain: 'pypistats.org',\n    strategy: Strategy.PUBLIC,\n    browser: false,\n    args: [\n        { name: 'name', positional: true, required: true, help: 'PyPI package name (e.g. \"requests\", \"pandas\")' },\n        { name: 'period', default: 'recent', help: 'recent (default — 1 row, last day/week/month) or overall (1 row per day)' },\n    ],\n    columns: ['rank', 'package', 'period', 'date', 'downloads'],\n    func: async (args) => {\n        const name = requirePackageName(args.name);\n        const period = requirePeriod(args.period);\n        if (period === 'recent') {\n            const body = await pypiFetch(`${PYPISTATS_BASE}/api/packages/${encodeURIComponent(name)}/recent`, `pypi downloads ${name}`);\n            const data = body?.data;\n            if (!data || (data.last_day == null && data.last_week == null && data.last_month == null)) {\n                throw new EmptyResultError('pypi downloads', `pypistats has no recent download data for \"${name}\".`);\n            }\n            return [\n                { rank: 1, package: String(body.package ?? name), period: 'last_day', date: '', downloads: data.last_day != null ? Number(data.last_day) : null },\n                { rank: 2, package: String(body.package ?? name), period: 'last_week', date: '', downloads: data.last_week != null ? Number(data.last_week) : null },\n                { rank: 3, package: String(body.package ?? name), period: 'last_month', date: '', downloads: data.last_month != null ? Number(data.last_month) : null },\n            ];\n        }\n        const body = await pypiFetch(`${PYPISTATS_BASE}/api/packages/${encodeURIComponent(name)}/overall?mirrors=false`, `pypi downloads ${name}`);\n        const days = Array.isArray(body?.data) ? body.data : [];\n        if (!days.length) {\n            throw new EmptyResultError('pypi downloads', `pypistats has no overall download history for \"${name}\".`);\n        }\n        return days.map((row, i) => ({\n            rank: i + 1,\n            package: String(body.package ?? name),\n            period: 'daily',\n            date: String(row.date ?? ''),\n            downloads: row.downloads != null ? Number(row.downloads) : null,","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/pypi/downloads.js#L27-L63","documentation":"When period is 'recent', the downloads command fetches pypistats /api/packages/<name>/recent and throws EmptyResultError 'pypi downloads' with detail `pypistats has no recent download data for \"<name>\"` if `body.data` is missing or all of last_day/last_week/last_month are null. The library throws this instead of rendering empty rows because there is genuinely no data to show.","triggerScenarios":"Querying a very new, unpublished, or near-zero-download package where pypistats has no recent totals; also triggered by a malformed response body lacking `data`.","commonSituations":"Checking a brand-new package minutes after publishing; a private/renamed package; typos in the package name hitting a package with no stats; pypistats lagging behind PyPI.","solutions":["Verify the package name is spelled correctly and exists on pypi.org","Try --period overall to see if any daily history exists","Wait and retry — pypistats aggregates on a delay for new packages","Treat it as an expected empty result and handle EmptyResultError in your script"],"exampleFix":"// before\nconst rows = downloads('my-brand-new-pkg'); // EmptyResultError\n// after\ntry {\n  const rows = downloads('my-brand-new-pkg');\n} catch (e) {\n  if (e instanceof EmptyResultError) return []; // no data yet\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"// Check the package exists on PyPI first\nconst res = await fetch('https://pypi.org/pypi/<name>/json');\nif (!res.ok) throw new Error('Package does not exist on PyPI');","typeGuard":"function hasRecentData(body) {\n  const d = body?.data;\n  return Boolean(d) && ['last_day','last_week','last_month'].some(k => d[k] != null);\n}","tryCatchPattern":"try {\n  const rows = await downloads({ name, period: 'recent' });\n} catch (e) {\n  if (e instanceof EmptyResultError) {\n    return []; // no data yet — treat as empty, not fatal\n  }\n  throw e;\n}","preventionTips":["Verify the package name on pypi.org before querying stats","Expect empty stats for very new or zero-download packages","Fall back to --period overall when recent data is missing","Handle EmptyResultError explicitly in scripts rather than crashing"],"tags":["pypi","empty-result","no-data","pypistats"],"backgroundTag":"empty-result-set","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}