]> git.ipfire.org Git - thirdparty/Python/cpython.git/commit
Improve `pathname2url()` and `url2pathname()` docs (#127125)
authorBarney Gale <barney.gale@gmail.com>
Sun, 24 Nov 2024 17:33:46 +0000 (17:33 +0000)
committerGitHub <noreply@github.com>
Sun, 24 Nov 2024 17:33:46 +0000 (17:33 +0000)
commit307c63358681d669ae39e5ecd814bded4a93443a
tree0a2e480940794672300b2ff0680fc76e4822ae93
parent97b2ceaaaf88a73a45254912a0e972412879ccbf
Improve `pathname2url()` and `url2pathname()` docs (#127125)

These functions have long sown confusion among Python developers. The
existing documentation says they deal with URL path components, but that
doesn't fit the evidence on Windows:

    >>> pathname2url(r'C:\foo')
    '///C:/foo'
    >>> pathname2url(r'\\server\share')
    '////server/share'  # or '//server/share' as of quite recently

If these were URL path components, they would imply complete URLs like
`file://///C:/foo` and `file://////server/share`. Clearly this isn't right.
Yet the implementation in `nturl2path` is deliberate, and the
`url2pathname()` function correctly inverts it.

On non-Windows platforms, the behaviour until quite recently is to simply
quote/unquote the path without adding or removing any leading slashes. This
behaviour is compatible with *both* interpretations -- 1) the value is a
URL path component (existing docs), and 2) the value is everything
following `file:` (this commit)

The conclusion I draw is that these functions operate on everything after
the `file:` prefix, which may include an authority section. This is the
only explanation that fits both the  Windows and non-Windows behaviour.
It's also a better match for the function names.
Doc/library/urllib.request.rst