https://github.com/python/cpython/commit/a6e61fd9d8323072d962ec649075b63027c43745
commit: a6e61fd9d8323072d962ec649075b63027c43745
branch: 3.13
author: Miss Islington (bot) <[email protected]>
committer: barneygale <[email protected]>
date: 2024-11-24T17:46:54Z
summary:
[3.13] Improve `pathname2url()` and `url2pathname()` docs (GH-127125) (#127232)
Improve `pathname2url()` and `url2pathname()` docs (GH-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.
(cherry picked from commit 307c63358681d669ae39e5ecd814bded4a93443a)
Co-authored-by: Barney Gale <[email protected]>
files:
M Doc/library/urllib.request.rst
diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index ce82552a3ae4be..46e0f6275aee53 100644
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -149,16 +149,28 @@ The :mod:`urllib.request` module defines the following
functions:
.. function:: pathname2url(path)
- Convert the pathname *path* from the local syntax for a path to the form
used in
- the path component of a URL. This does not produce a complete URL. The
return
- value will already be quoted using the :func:`~urllib.parse.quote` function.
+ Convert the given local path to a ``file:`` URL. This function uses
+ :func:`~urllib.parse.quote` function to encode the path. For historical
+ reasons, the return value omits the ``file:`` scheme prefix. This example
+ shows the function being used on Windows::
+ >>> from urllib.request import pathname2url
+ >>> path = 'C:\\Program Files'
+ >>> 'file:' + pathname2url(path)
+ 'file:///C:/Program%20Files'
-.. function:: url2pathname(path)
- Convert the path component *path* from a percent-encoded URL to the local
syntax for a
- path. This does not accept a complete URL. This function uses
- :func:`~urllib.parse.unquote` to decode *path*.
+.. function:: url2pathname(url)
+
+ Convert the given ``file:`` URL to a local path. This function uses
+ :func:`~urllib.parse.unquote` to decode the URL. For historical reasons,
+ the given value *must* omit the ``file:`` scheme prefix. This example shows
+ the function being used on Windows::
+
+ >>> from urllib.request import url2pathname
+ >>> url = 'file:///C:/Program%20Files'
+ >>> url2pathname(url.removeprefix('file:'))
+ 'C:\\Program Files'
.. function:: getproxies()
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
