From 6c6e5e278c046ba5c9f599798a8545d122b5aba2 Mon Sep 17 00:00:00 2001 From: barneygale Date: Fri, 22 Nov 2024 01:07:45 +0000 Subject: [PATCH 1/3] Improve `pathname2url()` and `url2pathname()` docs These functions have long sown confusion among Python developers. Even in the urllib implementation and tests, they seem to be used in contradictory ways. A test helper named `sanepathname2url()` has been with us since 2004! The existing documentation says that these functions 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. The conclusion I draw is that these functions operate on everything after the `file:` prefix, which may include an authority section. --- Doc/library/urllib.request.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index e0831bf7e65ad2..4ace55f68fb2f3 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -148,9 +148,9 @@ 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. For historical reasons, + the return value omits the ``file:`` scheme prefix. This function uses + :func:`~urllib.parse.quote` function to encode the path. .. versionchanged:: 3.14 On Windows, ``:`` characters not following a drive letter are quoted. In @@ -158,11 +158,12 @@ The :mod:`urllib.request` module defines the following functions: found in any position other than the second character. -.. function:: url2pathname(path) +.. function:: url2pathname(url) + + Convert the given ``file:`` URL to a local path. For historical reasons, + the given URL *must* omit the ``file:`` scheme prefix. This function uses + :func:`~urllib.parse.unquote` to decode the URL. - 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:: getproxies() From efc7c84226ae9b929d07b044647bf3873453df45 Mon Sep 17 00:00:00 2001 From: barneygale Date: Sat, 23 Nov 2024 15:22:53 +0000 Subject: [PATCH 2/3] Add examples --- Doc/library/urllib.request.rst | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index 4ace55f68fb2f3..83561fb774c1ea 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -148,9 +148,14 @@ The :mod:`urllib.request` module defines the following functions: .. function:: pathname2url(path) - Convert the given local path to a ``file:`` URL. For historical reasons, - the return value omits the ``file:`` scheme prefix. This function uses - :func:`~urllib.parse.quote` function to encode the path. + 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. For example:: + + >>> from urllib.request import pathname2url + >>> path = 'C:\\Windows' + >>> 'file:' + pathname2url(path) + 'file:///C:/Windows' .. versionchanged:: 3.14 On Windows, ``:`` characters not following a drive letter are quoted. In @@ -160,10 +165,14 @@ The :mod:`urllib.request` module defines the following functions: .. function:: url2pathname(url) - Convert the given ``file:`` URL to a local path. For historical reasons, - the given URL *must* omit the ``file:`` scheme prefix. This function uses - :func:`~urllib.parse.unquote` to decode the 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 URL *must* omit the ``file:`` scheme prefix. For example:: + >>> from urllib.request import url2pathname + >>> url = 'file:///C:/Windows' + >>> url2pathname(url.removeprefix('file:')) + 'C:\\Windows' .. function:: getproxies() From 4ae0e228887752ada650d6df763630073ce894a5 Mon Sep 17 00:00:00 2001 From: barneygale Date: Sun, 24 Nov 2024 17:07:37 +0000 Subject: [PATCH 3/3] Address review feedback --- Doc/library/urllib.request.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index 71c657665c6870..9055556a3703bb 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -150,12 +150,13 @@ The :mod:`urllib.request` module defines the following functions: 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. For example:: + 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:\\Windows' + >>> path = 'C:\\Program Files' >>> 'file:' + pathname2url(path) - 'file:///C:/Windows' + 'file:///C:/Program%20Files' .. versionchanged:: 3.14 Windows drive letters are no longer converted to uppercase. @@ -170,12 +171,13 @@ The :mod:`urllib.request` module defines the following functions: 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 URL *must* omit the ``file:`` scheme prefix. For example:: + 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:/Windows' + >>> url = 'file:///C:/Program%20Files' >>> url2pathname(url.removeprefix('file:')) - 'C:\\Windows' + 'C:\\Program Files' .. versionchanged:: 3.14 Windows drive letters are no longer converted to uppercase.