https://github.com/python/cpython/commit/590fd9ccd4443b991f7b01134fb8486cf5f5a79c
commit: 590fd9ccd4443b991f7b01134fb8486cf5f5a79c
branch: 3.13
author: Barney Gale <barney.g...@gmail.com>
committer: barneygale <barney.g...@gmail.com>
date: 2024-06-02T20:37:01+01:00
summary:
[3.13] GH-119054: Add "Querying file type and status" section to pathlib docs
(GH-119055) (#119951)
Add a dedicated subsection for `Path.stat()`-related methods, specifically
`stat()`, `lstat()`, `exists()`, `is_*()`, and `samefile()`.
(cherry picked from commit 81d63362302187e5cb838c9a7cd857181142e530)
files:
M Doc/library/pathlib.rst
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 15e9eaa5190256..598d3dfb2eda42 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -808,8 +808,8 @@ bugs or failures in your application)::
UnsupportedOperation: cannot instantiate 'WindowsPath' on your system
-File URIs
-^^^^^^^^^
+Parsing and generating URIs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
Concrete path objects can be created from, and represented as, 'file' URIs
conforming to :rfc:`8089`.
@@ -869,12 +869,8 @@ conforming to :rfc:`8089`.
it strictly impure.
-Methods
-^^^^^^^
-
-Concrete paths provide the following methods in addition to pure paths
-methods. Many of these methods can raise an :exc:`OSError` if a system
-call fails (for example because the path doesn't exist).
+Querying file type and status
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionchanged:: 3.8
@@ -886,29 +882,6 @@ call fails (for example because the path doesn't exist).
unrepresentable at the OS level.
-.. classmethod:: Path.cwd()
-
- Return a new path object representing the current directory (as returned
- by :func:`os.getcwd`)::
-
- >>> Path.cwd()
- PosixPath('/home/antoine/pathlib')
-
-
-.. classmethod:: Path.home()
-
- Return a new path object representing the user's home directory (as
- returned by :func:`os.path.expanduser` with ``~`` construct). If the home
- directory can't be resolved, :exc:`RuntimeError` is raised.
-
- ::
-
- >>> Path.home()
- PosixPath('/home/antoine')
-
- .. versionadded:: 3.5
-
-
.. method:: Path.stat(*, follow_symlinks=True)
Return a :class:`os.stat_result` object containing information about this
path, like :func:`os.stat`.
@@ -928,25 +901,12 @@ call fails (for example because the path doesn't exist).
.. versionchanged:: 3.10
The *follow_symlinks* parameter was added.
-.. method:: Path.chmod(mode, *, follow_symlinks=True)
-
- Change the file mode and permissions, like :func:`os.chmod`.
- This method normally follows symlinks. Some Unix flavours support changing
- permissions on the symlink itself; on these platforms you may add the
- argument ``follow_symlinks=False``, or use :meth:`~Path.lchmod`.
+.. method:: Path.lstat()
- ::
+ Like :meth:`Path.stat` but, if the path points to a symbolic link, return
+ the symbolic link's information rather than its target's.
- >>> p = Path('setup.py')
- >>> p.stat().st_mode
- 33277
- >>> p.chmod(0o444)
- >>> p.stat().st_mode
- 33060
-
- .. versionchanged:: 3.10
- The *follow_symlinks* parameter was added.
.. method:: Path.exists(*, follow_symlinks=True)
@@ -969,6 +929,177 @@ call fails (for example because the path doesn't exist).
.. versionchanged:: 3.12
The *follow_symlinks* parameter was added.
+
+.. method:: Path.is_file(*, follow_symlinks=True)
+
+ Return ``True`` if the path points to a regular file, ``False`` if it
+ points to another kind of file.
+
+ ``False`` is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
+
+ This method normally follows symlinks; to exclude symlinks, add the
+ argument ``follow_symlinks=False``.
+
+ .. versionchanged:: 3.13
+ The *follow_symlinks* parameter was added.
+
+
+.. method:: Path.is_dir(*, follow_symlinks=True)
+
+ Return ``True`` if the path points to a directory, ``False`` if it points
+ to another kind of file.
+
+ ``False`` is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
+
+ This method normally follows symlinks; to exclude symlinks to directories,
+ add the argument ``follow_symlinks=False``.
+
+ .. versionchanged:: 3.13
+ The *follow_symlinks* parameter was added.
+
+
+.. method:: Path.is_symlink()
+
+ Return ``True`` if the path points to a symbolic link, ``False`` otherwise.
+
+ ``False`` is also returned if the path doesn't exist; other errors (such
+ as permission errors) are propagated.
+
+
+.. method:: Path.is_junction()
+
+ Return ``True`` if the path points to a junction, and ``False`` for any
other
+ type of file. Currently only Windows supports junctions.
+
+ .. versionadded:: 3.12
+
+
+.. method:: Path.is_mount()
+
+ Return ``True`` if the path is a :dfn:`mount point`: a point in a
+ file system where a different file system has been mounted. On POSIX, the
+ function checks whether *path*'s parent, :file:`path/..`, is on a different
+ device than *path*, or whether :file:`path/..` and *path* point to the same
+ i-node on the same device --- this should detect mount points for all Unix
+ and POSIX variants. On Windows, a mount point is considered to be a drive
+ letter root (e.g. ``c:\``), a UNC share (e.g. ``\\server\share``), or a
+ mounted filesystem directory.
+
+ .. versionadded:: 3.7
+
+ .. versionchanged:: 3.12
+ Windows support was added.
+
+
+.. method:: Path.is_socket()
+
+ Return ``True`` if the path points to a Unix socket (or a symbolic link
+ pointing to a Unix socket), ``False`` if it points to another kind of file.
+
+ ``False`` is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
+
+
+.. method:: Path.is_fifo()
+
+ Return ``True`` if the path points to a FIFO (or a symbolic link
+ pointing to a FIFO), ``False`` if it points to another kind of file.
+
+ ``False`` is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
+
+
+.. method:: Path.is_block_device()
+
+ Return ``True`` if the path points to a block device (or a symbolic link
+ pointing to a block device), ``False`` if it points to another kind of file.
+
+ ``False`` is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
+
+
+.. method:: Path.is_char_device()
+
+ Return ``True`` if the path points to a character device (or a symbolic link
+ pointing to a character device), ``False`` if it points to another kind of
file.
+
+ ``False`` is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
+
+
+.. method:: Path.samefile(other_path)
+
+ Return whether this path points to the same file as *other_path*, which
+ can be either a Path object, or a string. The semantics are similar
+ to :func:`os.path.samefile` and :func:`os.path.samestat`.
+
+ An :exc:`OSError` can be raised if either file cannot be accessed for some
+ reason.
+
+ ::
+
+ >>> p = Path('spam')
+ >>> q = Path('eggs')
+ >>> p.samefile(q)
+ False
+ >>> p.samefile('spam')
+ True
+
+ .. versionadded:: 3.5
+
+
+Other methods
+^^^^^^^^^^^^^
+
+Some of these methods can raise an :exc:`OSError` if a system call fails (for
+example because the path doesn't exist).
+
+.. classmethod:: Path.cwd()
+
+ Return a new path object representing the current directory (as returned
+ by :func:`os.getcwd`)::
+
+ >>> Path.cwd()
+ PosixPath('/home/antoine/pathlib')
+
+
+.. classmethod:: Path.home()
+
+ Return a new path object representing the user's home directory (as
+ returned by :func:`os.path.expanduser` with ``~`` construct). If the home
+ directory can't be resolved, :exc:`RuntimeError` is raised.
+
+ ::
+
+ >>> Path.home()
+ PosixPath('/home/antoine')
+
+ .. versionadded:: 3.5
+
+
+.. method:: Path.chmod(mode, *, follow_symlinks=True)
+
+ Change the file mode and permissions, like :func:`os.chmod`.
+
+ This method normally follows symlinks. Some Unix flavours support changing
+ permissions on the symlink itself; on these platforms you may add the
+ argument ``follow_symlinks=False``, or use :meth:`~Path.lchmod`.
+
+ ::
+
+ >>> p = Path('setup.py')
+ >>> p.stat().st_mode
+ 33277
+ >>> p.chmod(0o444)
+ >>> p.stat().st_mode
+ 33060
+
+ .. versionchanged:: 3.10
+ The *follow_symlinks* parameter was added.
+
+
.. method:: Path.expanduser()
Return a new path with expanded ``~`` and ``~user`` constructs,
@@ -1065,105 +1196,6 @@ call fails (for example because the path doesn't exist).
The *follow_symlinks* parameter was added.
-.. method:: Path.is_dir(*, follow_symlinks=True)
-
- Return ``True`` if the path points to a directory, ``False`` if it points
- to another kind of file.
-
- ``False`` is also returned if the path doesn't exist or is a broken symlink;
- other errors (such as permission errors) are propagated.
-
- This method normally follows symlinks; to exclude symlinks to directories,
- add the argument ``follow_symlinks=False``.
-
- .. versionchanged:: 3.13
- The *follow_symlinks* parameter was added.
-
-
-.. method:: Path.is_file(*, follow_symlinks=True)
-
- Return ``True`` if the path points to a regular file, ``False`` if it
- points to another kind of file.
-
- ``False`` is also returned if the path doesn't exist or is a broken symlink;
- other errors (such as permission errors) are propagated.
-
- This method normally follows symlinks; to exclude symlinks, add the
- argument ``follow_symlinks=False``.
-
- .. versionchanged:: 3.13
- The *follow_symlinks* parameter was added.
-
-
-.. method:: Path.is_junction()
-
- Return ``True`` if the path points to a junction, and ``False`` for any
other
- type of file. Currently only Windows supports junctions.
-
- .. versionadded:: 3.12
-
-
-.. method:: Path.is_mount()
-
- Return ``True`` if the path is a :dfn:`mount point`: a point in a
- file system where a different file system has been mounted. On POSIX, the
- function checks whether *path*'s parent, :file:`path/..`, is on a different
- device than *path*, or whether :file:`path/..` and *path* point to the same
- i-node on the same device --- this should detect mount points for all Unix
- and POSIX variants. On Windows, a mount point is considered to be a drive
- letter root (e.g. ``c:\``), a UNC share (e.g. ``\\server\share``), or a
- mounted filesystem directory.
-
- .. versionadded:: 3.7
-
- .. versionchanged:: 3.12
- Windows support was added.
-
-
-.. method:: Path.is_symlink()
-
- Return ``True`` if the path points to a symbolic link, ``False`` otherwise.
-
- ``False`` is also returned if the path doesn't exist; other errors (such
- as permission errors) are propagated.
-
-
-.. method:: Path.is_socket()
-
- Return ``True`` if the path points to a Unix socket (or a symbolic link
- pointing to a Unix socket), ``False`` if it points to another kind of file.
-
- ``False`` is also returned if the path doesn't exist or is a broken symlink;
- other errors (such as permission errors) are propagated.
-
-
-.. method:: Path.is_fifo()
-
- Return ``True`` if the path points to a FIFO (or a symbolic link
- pointing to a FIFO), ``False`` if it points to another kind of file.
-
- ``False`` is also returned if the path doesn't exist or is a broken symlink;
- other errors (such as permission errors) are propagated.
-
-
-.. method:: Path.is_block_device()
-
- Return ``True`` if the path points to a block device (or a symbolic link
- pointing to a block device), ``False`` if it points to another kind of file.
-
- ``False`` is also returned if the path doesn't exist or is a broken symlink;
- other errors (such as permission errors) are propagated.
-
-
-.. method:: Path.is_char_device()
-
- Return ``True`` if the path points to a character device (or a symbolic link
- pointing to a character device), ``False`` if it points to another kind of
file.
-
- ``False`` is also returned if the path doesn't exist or is a broken symlink;
- other errors (such as permission errors) are propagated.
-
-
.. method:: Path.iterdir()
When the path points to a directory, yield path objects of the directory
@@ -1286,12 +1318,6 @@ call fails (for example because the path doesn't exist).
symbolic link's mode is changed rather than its target's.
-.. method:: Path.lstat()
-
- Like :meth:`Path.stat` but, if the path points to a symbolic link, return
- the symbolic link's information rather than its target's.
-
-
.. method:: Path.mkdir(mode=0o777, parents=False, exist_ok=False)
Create a new directory at this given path. If *mode* is given, it is
@@ -1481,27 +1507,6 @@ call fails (for example because the path doesn't exist).
Remove this directory. The directory must be empty.
-.. method:: Path.samefile(other_path)
-
- Return whether this path points to the same file as *other_path*, which
- can be either a Path object, or a string. The semantics are similar
- to :func:`os.path.samefile` and :func:`os.path.samestat`.
-
- An :exc:`OSError` can be raised if either file cannot be accessed for some
- reason.
-
- ::
-
- >>> p = Path('spam')
- >>> q = Path('eggs')
- >>> p.samefile(q)
- False
- >>> p.samefile('spam')
- True
-
- .. versionadded:: 3.5
-
-
.. method:: Path.symlink_to(target, target_is_directory=False)
Make this path a symbolic link pointing to *target*.
_______________________________________________
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
