From ae5cc1bae8e9b6d6b53b6c51635cd9ad54c3d078 Mon Sep 17 00:00:00 2001 From: barneygale Date: Tue, 3 Oct 2023 21:32:46 +0100 Subject: [PATCH 1/4] GH-110109: pathlib docs: bring `from_uri()` and `as_uri()` together. This is a very soft deprecation of `PurePath.as_uri()`. We instead document it as a `Path` method, and add a couple of sentences mentioning that it's also available in `PurePath`. --- Doc/library/pathlib.rst | 108 ++++++++++++++++++++++------------------ 1 file changed, 59 insertions(+), 49 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 8ee89a003a339a..3566a21a91522d 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -485,19 +485,6 @@ Pure paths provide the following methods and properties: 'c:/windows' -.. method:: PurePath.as_uri() - - Represent the path as a ``file`` URI. :exc:`ValueError` is raised if - the path isn't absolute. - - >>> p = PurePosixPath('/etc/passwd') - >>> p.as_uri() - 'file:///etc/passwd' - >>> p = PureWindowsPath('c:/Windows') - >>> p.as_uri() - 'file:///c:/Windows' - - .. method:: PurePath.is_absolute() Return whether the path is absolute or not. A path is considered absolute @@ -810,6 +797,65 @@ bugs or failures in your application):: UnsupportedOperation: cannot instantiate 'WindowsPath' on your system +File URIs +^^^^^^^^^ + +Concrete path objects can be created from, and represented as, 'file' URIs +conforming to :rfc:`8089`. + +.. note:: + + File URIs are not portable across machines with different + :ref:`filesystem encodings `. + +.. classmethod:: Path.from_uri(uri) + + Return a new path object from parsing a 'file' URI. For example:: + + >>> p = PosixPath.from_uri('file:///etc/hosts') + PosixPath('/etc/hosts') + + On Windows, DOS device and UNC paths may be parsed from URIs:: + + >>> p = WindowsPath.from_uri('file:///c:/windows') + WindowsPath('c:/windows') + >>> p = WindowsPath.from_uri('file://server/share') + WindowsPath('//server/share') + + Several variant forms are supported:: + + >>> p = WindowsPath.from_uri('file:////server/share') + WindowsPath('//server/share') + >>> p = WindowsPath.from_uri('file://///server/share') + WindowsPath('//server/share') + >>> p = WindowsPath.from_uri('file:c:/windows') + WindowsPath('c:/windows') + >>> p = WindowsPath.from_uri('file:/c|/windows') + WindowsPath('c:/windows') + + :exc:`ValueError` is raised if the URI does not start with ``file:``, or + the parsed path isn't absolute. + + .. versionadded:: 3.13 + + +.. method:: Path.as_uri() + + Represent the path as a 'file' URI. :exc:`ValueError` is raised if + the path isn't absolute. + + >>> p = PosixPath('/etc/passwd') + >>> p.as_uri() + 'file:///etc/passwd' + >>> p = WindowsPath('c:/Windows') + >>> p.as_uri() + 'file:///c:/Windows' + + For historical reasons, this method is also available from + :class:`PurePath` objects. However, its use of :func:`os.fsencode` makes + it strictly impure. + + Methods ^^^^^^^ @@ -850,42 +896,6 @@ call fails (for example because the path doesn't exist). .. versionadded:: 3.5 -.. classmethod:: Path.from_uri(uri) - - Return a new path object from parsing a 'file' URI conforming to - :rfc:`8089`. For example:: - - >>> p = Path.from_uri('file:///etc/hosts') - PosixPath('/etc/hosts') - - On Windows, DOS device and UNC paths may be parsed from URIs:: - - >>> p = Path.from_uri('file:///c:/windows') - WindowsPath('c:/windows') - >>> p = Path.from_uri('file://server/share') - WindowsPath('//server/share') - - Several variant forms are supported:: - - >>> p = Path.from_uri('file:////server/share') - WindowsPath('//server/share') - >>> p = Path.from_uri('file://///server/share') - WindowsPath('//server/share') - >>> p = Path.from_uri('file:c:/windows') - WindowsPath('c:/windows') - >>> p = Path.from_uri('file:/c|/windows') - WindowsPath('c:/windows') - - :exc:`ValueError` is raised if the URI does not start with ``file:``, or - the parsed path isn't absolute. - - :func:`os.fsdecode` is used to decode percent-escaped byte sequences, and - so file URIs are not portable across machines with different - :ref:`filesystem encodings `. - - .. versionadded:: 3.13 - - .. method:: Path.stat(*, follow_symlinks=True) Return a :class:`os.stat_result` object containing information about this path, like :func:`os.stat`. From 600bb172f737420d9aaf5ca8108cbb0421e407c4 Mon Sep 17 00:00:00 2001 From: barneygale Date: Thu, 5 Oct 2023 20:56:15 +0100 Subject: [PATCH 2/4] Indentation --- Doc/library/pathlib.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 3566a21a91522d..c94208c7b59bfb 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -812,26 +812,26 @@ conforming to :rfc:`8089`. Return a new path object from parsing a 'file' URI. For example:: - >>> p = PosixPath.from_uri('file:///etc/hosts') - PosixPath('/etc/hosts') + >>> p = Path.from_uri('file:///etc/hosts') + PosixPath('/etc/hosts') On Windows, DOS device and UNC paths may be parsed from URIs:: - >>> p = WindowsPath.from_uri('file:///c:/windows') - WindowsPath('c:/windows') - >>> p = WindowsPath.from_uri('file://server/share') - WindowsPath('//server/share') + >>> p = Path.from_uri('file:///c:/windows') + WindowsPath('c:/windows') + >>> p = Path.from_uri('file://server/share') + WindowsPath('//server/share') Several variant forms are supported:: - >>> p = WindowsPath.from_uri('file:////server/share') - WindowsPath('//server/share') - >>> p = WindowsPath.from_uri('file://///server/share') - WindowsPath('//server/share') - >>> p = WindowsPath.from_uri('file:c:/windows') - WindowsPath('c:/windows') - >>> p = WindowsPath.from_uri('file:/c|/windows') - WindowsPath('c:/windows') + >>> p = Path.from_uri('file:////server/share') + WindowsPath('//server/share') + >>> p = Path.from_uri('file://///server/share') + WindowsPath('//server/share') + >>> p = Path.from_uri('file:c:/windows') + WindowsPath('c:/windows') + >>> p = Path.from_uri('file:/c|/windows') + WindowsPath('c:/windows') :exc:`ValueError` is raised if the URI does not start with ``file:``, or the parsed path isn't absolute. From d3ba6f59056dbfaf33b7834e49aa300d4b20088f Mon Sep 17 00:00:00 2001 From: barneygale Date: Fri, 17 Nov 2023 13:04:45 +0000 Subject: [PATCH 3/4] Exclude from doctest --- Doc/library/pathlib.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index c94208c7b59bfb..c0d569d5350a3f 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -844,6 +844,8 @@ conforming to :rfc:`8089`. Represent the path as a 'file' URI. :exc:`ValueError` is raised if the path isn't absolute. + :: + >>> p = PosixPath('/etc/passwd') >>> p.as_uri() 'file:///etc/passwd' From 112823e6f34030295b80e97a02b3753404a84130 Mon Sep 17 00:00:00 2001 From: Barney Gale Date: Sat, 13 Jan 2024 10:05:03 +0000 Subject: [PATCH 4/4] Update Doc/library/pathlib.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/pathlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index c0d569d5350a3f..cb6c5cd5635900 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -844,7 +844,7 @@ conforming to :rfc:`8089`. Represent the path as a 'file' URI. :exc:`ValueError` is raised if the path isn't absolute. - :: + .. code-block:: pycon >>> p = PosixPath('/etc/passwd') >>> p.as_uri()