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-Turner@users.noreply.github.com>

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 084d8bf4d3ca2beaba73d72114e394e04f6f8edd..be207ca222274e81840cc8241526f8b5ac25f6ca 100644 (file)
--- 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`.