{"record":{"id":"c9881c1d121541ce","repo":"jackwener/OpenCLI","slug":"pypi-downloads-period-value-is-invalid","errorCode":null,"errorMessage":"pypi downloads period \"${value}\" is invalid","messagePattern":"pypi downloads period \"(.+?)\" is invalid","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"clis/pypi/downloads.js","lineNumber":17,"sourceCode":"// pypi downloads — fetch download counts for a single PyPI package via\n// pypistats.org's public JSON API.\n//\n// Default endpoint is `/api/packages/<pkg>/recent` which returns last-day /\n// last-week / last-month totals as a single row. Pass `--period overall` to\n// hit `/api/packages/<pkg>/overall` for the full daily history (one row per\n// day).\nimport { cli, Strategy } from '@jackwener/opencli/registry';\nimport { ArgumentError, EmptyResultError } from '@jackwener/opencli/errors';\nimport { PYPISTATS_BASE, pypiFetch, requirePackageName } from './utils.js';\n\nconst PERIODS = new Set(['recent', 'overall']);\n\nfunction requirePeriod(value) {\n    const s = String(value ?? 'recent').trim().toLowerCase();\n    if (!PERIODS.has(s)) {\n        throw new ArgumentError(\n            `pypi downloads period \"${value}\" is invalid`,\n            'Allowed values: recent (default — last day/week/month totals) or overall (full daily history).',\n        );\n    }\n    return s;\n}\n\ncli({\n    site: 'pypi',\n    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)' },","sourceCodeStart":1,"sourceCodeEnd":35,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/pypi/downloads.js#L1-L35","documentation":"requirePeriod validates the `period` argument of the `pypi downloads` command against the allowed set {recent, overall} (case-insensitive, whitespace-trimmed, default 'recent'). Anything else throws ArgumentError `pypi downloads period \"${value}\" is invalid`. The library throws this to reject unsupported period values before any network call.","triggerScenarios":"Calling the downloads command with period values other than 'recent' or 'overall' — e.g. 'daily', 'month', 'all', 'last_week', or an empty-but-nondefault string.","commonSituations":"Assuming pypistats supports other windows (day/week/month as separate periods); typos like 'overal' or 'recnet'; passing flags from a different CLI's vocabulary; users copying period names from other stats tools.","solutions":["Use 'recent' for last day/week/month totals (the default)","Use 'overall' for the full daily history","Check the --period help text and correct the spelling","Map any custom period your script uses to one of the two supported values before calling"],"exampleFix":"// before\nconst rows = await downloads({ name: 'requests', period: 'last_month' });\n// after\nconst rows = await downloads({ name: 'requests', period: 'recent' }); // recent includes last_month","handlingStrategy":"validation","validationCode":"// Validate period before invoking the command\nfunction checkPeriod(p) {\n  const s = String(p ?? 'recent').trim().toLowerCase();\n  if (!['recent', 'overall'].includes(s)) {\n    throw new Error(`period must be 'recent' or 'overall', got: ${p}`);\n  }\n  return s;\n}","typeGuard":"function isPyPiPeriod(v) {\n  return v === 'recent' || v === 'overall';\n}","tryCatchPattern":"try {\n  const rows = await downloads({ name, period });\n} catch (e) {\n  if (/period .* is invalid/.test(e.message)) {\n    return downloads({ name, period: 'recent' }); // sensible default\n  }\n  throw e;\n}","preventionTips":["Only use the documented values: 'recent' (default) or 'overall'","Normalize user input (trim + lowercase) before passing period","Don't copy period vocab from other stats tools (e.g. 'last_month' isn't valid)","Add CLI input validation in wrapper scripts"],"tags":["validation","argument-error","pypi","cli-input"],"backgroundTag":"invalid-parameter-value","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}