mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

GH-110109: pathlib docs: bring from_uri() and as_uri() together. (#110312)

Browse source 
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>
This commit is contained in:
Barney Gale 2024-01-16 22:51:57 +00:00 • committed by GitHub
parent 1d6989f9b0
commit 45e527dfb5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 61 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

110
Doc/library/pathlib.rst
View file

@ -485,19 +485,6 @@ Pure paths provide the following methods and properties:
'c:/windows' '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() .. method:: PurePath.is_absolute()
Return whether the path is absolute or not. A path is considered 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 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 Methods
^^^^^^^ ^^^^^^^
@ -853,42 +901,6 @@ call fails (for example because the path doesn't exist).
.. versionadded:: 3.5 .. 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) .. method:: Path.stat(*, follow_symlinks=True)
Return a :class:`os.stat_result` object containing information about this path, like :func:`os.stat`. Return a :class:`os.stat_result` object containing information about this path, like :func:`os.stat`.