FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

GH-110109: pathlib docs: bring `from_uri()` and `as_uri()` together. by barneygale · Pull Request #110312 · python/cpython · GitHub

/ cpython Public

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
barneygale merged 6 commits into from
Jan 16, 2024
Conversation 2 Commits 6 Checks 0 Files changed
Merged

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

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ae5cc1b
GH-110109: pathlib docs: bring `from_uri()` and `as_uri()` together.
barneygale Oct 3, 2023
600bb17
Indentation
barneygale Oct 5, 2023
cae0964
Merge branch 'main' into gh-110109-pathlib-uri-docs
barneygale Nov 17, 2023
d3ba6f5
Exclude from doctest
barneygale Nov 17, 2023
112823e
Update Doc/library/pathlib.rst
barneygale Jan 13, 2024
e07e5e8
Merge branch 'main' into gh-110109-pathlib-uri-docs
barneygale Jan 16, 2024
File filter

Filter by extension

Filter by extension .rst  (1) All 1 file type selected
Viewed files
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Unified
Split
Hide whitespace
Diff view
Unified
Split
Hide whitespace
110 changes: 61 additions & 49 deletions Doc/library/pathlib.rst
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
^^^^^^^

Expand Down Expand Up @@ -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`.
Expand Down
Back | FazBrowse Home | New Git URL