Skip to content

Commit ae5cc1b

Browse files
committed
pythonGH-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`.
1 parent 77e9aae commit ae5cc1b

1 file changed

Lines changed: 59 additions & 49 deletions

File tree

‎Doc/library/pathlib.rst‎

Lines changed: 59 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -485,19 +485,6 @@ Pure paths provide the following methods and properties:
485485
'c:/windows'
486486

487487

488-
.. method:: PurePath.as_uri()
489-
490-
Represent the path as a ``file`` URI. :exc:`ValueError` is raised if
491-
the path isn't absolute.
492-
493-
>>> p = PurePosixPath('/etc/passwd')
494-
>>> p.as_uri()
495-
'file:///etc/passwd'
496-
>>> p = PureWindowsPath('c:/Windows')
497-
>>> p.as_uri()
498-
'file:///c:/Windows'
499-
500-
501488
.. method:: PurePath.is_absolute()
502489

503490
Return whether the path is absolute or not. A path is considered absolute
@@ -810,6 +797,65 @@ bugs or failures in your application)::
810797
UnsupportedOperation: cannot instantiate 'WindowsPath' on your system
811798

812799

800+
File URIs
801+
^^^^^^^^^
802+
803+
Concrete path objects can be created from, and represented as, 'file' URIs
804+
conforming to :rfc:`8089`.
805+
806+
.. note::
807+
808+
File URIs are not portable across machines with different
809+
:ref:`filesystem encodings <filesystem-encoding>`.
810+
811+
.. classmethod:: Path.from_uri(uri)
812+
813+
Return a new path object from parsing a 'file' URI. For example::
814+
815+
>>> p = PosixPath.from_uri('file:///etc/hosts')
816+
PosixPath('/etc/hosts')
817+
818+
On Windows, DOS device and UNC paths may be parsed from URIs::
819+
820+
>>> p = WindowsPath.from_uri('file:///c:/windows')
821+
WindowsPath('c:/windows')
822+
>>> p = WindowsPath.from_uri('file://server/share')
823+
WindowsPath('//server/share')
824+
825+
Several variant forms are supported::
826+
827+
>>> p = WindowsPath.from_uri('file:////server/share')
828+
WindowsPath('//server/share')
829+
>>> p = WindowsPath.from_uri('file://///server/share')
830+
WindowsPath('//server/share')
831+
>>> p = WindowsPath.from_uri('file:c:/windows')
832+
WindowsPath('c:/windows')
833+
>>> p = WindowsPath.from_uri('file:/c|/windows')
834+
WindowsPath('c:/windows')
835+
836+
:exc:`ValueError` is raised if the URI does not start with ``file:``, or
837+
the parsed path isn't absolute.
838+
839+
.. versionadded:: 3.13
840+
841+
842+
.. method:: Path.as_uri()
843+
844+
Represent the path as a 'file' URI. :exc:`ValueError` is raised if
845+
the path isn't absolute.
846+
847+
>>> p = PosixPath('/etc/passwd')
848+
>>> p.as_uri()
849+
'file:///etc/passwd'
850+
>>> p = WindowsPath('c:/Windows')
851+
>>> p.as_uri()
852+
'file:///c:/Windows'
853+
854+
For historical reasons, this method is also available from
855+
:class:`PurePath` objects. However, its use of :func:`os.fsencode` makes
856+
it strictly impure.
857+
858+
813859
Methods
814860
^^^^^^^
815861

@@ -850,42 +896,6 @@ call fails (for example because the path doesn't exist).
850896
.. versionadded:: 3.5
851897

852898

853-
.. classmethod:: Path.from_uri(uri)
854-
855-
Return a new path object from parsing a 'file' URI conforming to
856-
:rfc:`8089`. For example::
857-
858-
>>> p = Path.from_uri('file:///etc/hosts')
859-
PosixPath('/etc/hosts')
860-
861-
On Windows, DOS device and UNC paths may be parsed from URIs::
862-
863-
>>> p = Path.from_uri('file:///c:/windows')
864-
WindowsPath('c:/windows')
865-
>>> p = Path.from_uri('file://server/share')
866-
WindowsPath('//server/share')
867-
868-
Several variant forms are supported::
869-
870-
>>> p = Path.from_uri('file:////server/share')
871-
WindowsPath('//server/share')
872-
>>> p = Path.from_uri('file://///server/share')
873-
WindowsPath('//server/share')
874-
>>> p = Path.from_uri('file:c:/windows')
875-
WindowsPath('c:/windows')
876-
>>> p = Path.from_uri('file:/c|/windows')
877-
WindowsPath('c:/windows')
878-
879-
:exc:`ValueError` is raised if the URI does not start with ``file:``, or
880-
the parsed path isn't absolute.
881-
882-
:func:`os.fsdecode` is used to decode percent-escaped byte sequences, and
883-
so file URIs are not portable across machines with different
884-
:ref:`filesystem encodings <filesystem-encoding>`.
885-
886-
.. versionadded:: 3.13
887-
888-
889899
.. method:: Path.stat(*, follow_symlinks=True)
890900

891901
Return a :class:`os.stat_result` object containing information about this path, like :func:`os.stat`.

0 commit comments

Comments
 (0)