From 590fd9ccd4443b991f7b01134fb8486cf5f5a79c Mon Sep 17 00:00:00 2001 From: Barney Gale Date: Sun, 2 Jun 2024 20:37:01 +0100 Subject: [PATCH] [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) --- Doc/library/pathlib.rst | 351 ++++++++++++++++++++-------------------- 1 file changed, 178 insertions(+), 173 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 15e9eaa5190..598d3dfb2ed 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,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*.