{"record":{"id":"2f06be88770cc9b1","repo":"pypa/pip","slug":"unexpected-file-name-derived-from-url-name-r","errorCode":null,"errorMessage":"Unexpected file name derived from URL: {name!r}","messagePattern":"Unexpected file name derived from URL: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/models/link.py","lineNumber":61,"sourceCode":"    ``os.path.basename`` drops any directory part, drive letter, or separator;\n    a ``.``, ``..``, or empty result is not a component and becomes ``\"\"``.\n    \"\"\"\n    name = os.path.basename(name)\n    if name in (\"\", os.curdir, os.pardir):\n        return PathComponent(\"\")\n\n    return PathComponent(name)\n\n\ndef as_path_component(name: str) -> PathComponent:\n    \"\"\"Like ``_to_path_component`` but reject the empty result.\n\n    Use where a file is about to be written, so a missing name is an error\n    rather than a silent fallback to the directory itself.\n    \"\"\"\n    component = _to_path_component(name)\n    if not component:\n        raise ValueError(f\"Unexpected file name derived from URL: {name!r}\")\n\n    return component\n\n\ndef join_within_directory(directory: str, component: PathComponent) -> str:\n    \"\"\"Join a single path ``component`` onto ``directory``.\n\n    ``component`` is a :data:`PathComponent`, so by type it has no separator and\n    is not a ``.`` or ``..`` reference; the result can never escape ``directory``.\n    Requiring ``PathComponent`` rather than ``str`` lets the type checker enforce\n    at the call site that the name was reduced to a safe component beforehand.\n    \"\"\"\n    return os.path.join(directory, component)\n\n\n# Order matters, earlier hashes have a precedence over later hashes for what\n# we will pick to use.\n_SUPPORTED_HASHES = (\"sha512\", \"sha384\", \"sha256\", \"sha224\", \"sha1\", \"md5\")","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/models/link.py#L43-L79","documentation":"Raised as ValueError from as_path_component in link.py:53-63. as_path_component reduces a name to a single safe filesystem component (via os.path.basename) and is meant to reject names that would collapse to empty/./.. before writing a file. If after basename reduction the result is empty (e.g. the URL-derived name is empty, '.', '..', or only a separator), it raises ValueError because writing under such a name would be unsafe (it could escape or overwrite the target directory).","triggerScenarios":"Calling as_path_component(name) where name, after os.path.basename, is '', '.', or '..' — e.g. a Link whose URL yields an empty/relative file name component when pip derives a cache/download path.","commonSituations":"A malformed Link URL that produces no usable file name (trailing slash, directory-only URL, drive-letter-only on Windows); a crafted/edge-case URL that basename reduces to '.' or '..'; a bug in URL-to-filename derivation.","solutions":["Ensure the source URL resolves to a concrete file name with a real basename component.","Validate/sanitize the link's URL-derived name before passing to as_path_component.","Report the offending URL to pip maintainers if it is a legitimate index link."],"exampleFix":"// before: URL yields empty basename\nname = ''  # derived from a directory-only URL\ncomponent = as_path_component(name)\n// after: guard against empty names\nif not name or os.path.basename(name) in ('', '.', '..'):\n    raise ValueError(f'No usable file name in URL')\ncomponent = as_path_component(name)","handlingStrategy":"validation","validationCode":"// Before calling as_path_component, ensure the URL yields a real basename:\nimport os\nbase = os.path.basename(name)\nif base in ('', os.curdir, os.pardir):\n    raise ValueError(f'URL produces no usable file name: {name!r}')\ncomponent = as_path_component(name)","typeGuard":null,"tryCatchPattern":"try:\n    component = as_path_component(name)\nexcept ValueError:\n    # synthesize a safe name or reject the link\n    ...","preventionTips":["Sanitize URL-derived file names before using them as path components.","Reject directory-only or empty file-name URLs at link construction time.","Treat basename reduction to '.'/'..' as a security-relevant failure."],"tags":["link","url","filesystem","validation","security"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}