Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

[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 81d6336230)
This commit is contained in:
Barney Gale 2024-06-02 20:37:01 +01:00 committed by GitHub
parent cfec22ce19
commit 590fd9ccd4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 178 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

351
Doc/library/pathlib.rst
View File

@ -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,6 +882,180 @@ call fails (for example because the path doesn't exist).
unrepresentable at the OS level.
.. method:: Path.stat(*, follow_symlinks=True)
Return a :class:`os.stat_result` object containing information about this path, like :func:`os.stat`.
The result is looked up at each call to this method.
This method normally follows symlinks; to stat a symlink add the argument
``follow_symlinks=False``, or use :meth:`~Path.lstat`.
::
>>> p = Path('setup.py')
>>> p.stat().st_size
956
>>> p.stat().st_mtime
1327883547.852554
.. versionchanged:: 3.10
The *follow_symlinks* parameter was added.
.. 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.exists(*, follow_symlinks=True)
Return ``True`` if the path points to an existing file or directory.
This method normally follows symlinks; to check if a symlink exists, add
the argument ``follow_symlinks=False``.
::
>>> Path('.').exists()
True
>>> Path('setup.py').exists()
True
>>> Path('/etc').exists()
True
>>> Path('nonexistentfile').exists()
False
.. 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
@ -909,25 +1079,6 @@ call fails (for example because the path doesn't exist).
.. 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`.
The result is looked up at each call to this method.
This method normally follows symlinks; to stat a symlink add the argument
``follow_symlinks=False``, or use :meth:`~Path.lstat`.
::
>>> p = Path('setup.py')
>>> p.stat().st_size
956
>>> p.stat().st_mtime
1327883547.852554
.. 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`.
@ -948,26 +1099,6 @@ call fails (for example because the path doesn't exist).
.. versionchanged:: 3.10
The *follow_symlinks* parameter was added.
.. method:: Path.exists(*, follow_symlinks=True)
Return ``True`` if the path points to an existing file or directory.
This method normally follows symlinks; to check if a symlink exists, add
the argument ``follow_symlinks=False``.
::
>>> Path('.').exists()
True
>>> Path('setup.py').exists()
True
>>> Path('/etc').exists()
True
>>> Path('nonexistentfile').exists()
False
.. versionchanged:: 3.12
The *follow_symlinks* parameter was added.
.. method:: Path.expanduser()
@ -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*.