https://github.com/python/cpython/commit/45e527dfb553a5687aad828260cda85f02b9b6f8
commit: 45e527dfb553a5687aad828260cda85f02b9b6f8
branch: main
author: Barney Gale <barney.g...@gmail.com>
committer: barneygale <barney.g...@gmail.com>
date: 2024-01-16T22:51:57Z
summary:
GH-110109: pathlib docs: bring `from_uri()` and `as_uri()` together. (#110312)
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`.
Co-authored-by: Adam Turner <9087854+aa-tur...@users.noreply.github.com>
files:
M Doc/library/pathlib.rst
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 084d8bf4d3ca2b..be207ca222274e 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
@@ -813,6 +800,67 @@ 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 <filesystem-encoding>`.
+
+.. classmethod:: Path.from_uri(uri)
+
+ Return a new path object from parsing a 'file' URI. 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.
+
+ .. versionadded:: 3.13
+
+
+.. method:: Path.as_uri()
+
+ 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()
+ '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
^^^^^^^
@@ -853,42 +901,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 <filesystem-encoding>`.
-
- .. 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`.
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
