From 81d63362302187e5cb838c9a7cd857181142e530 Mon Sep 17 00:00:00 2001 From: Barney Gale Date: Fri, 24 May 2024 20:35:13 +0100 Subject: [PATCH] GH-119054: Add "Querying file type and status" section to pathlib docs (#119055) Add a dedicated subsection for `Path.stat()`-related methods, specifically `stat()`, `lstat()`, `exists()`, `is_*()`, and `samefile()`. --- Doc/library/pathlib.rst | 338 ++++++++++++++++++++-------------------- 1 file changed, 171 insertions(+), 167 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 27ed0a32e801cc..71e2e5452d1754 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. Some 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 @@ -895,29 +891,6 @@ call fails (for example because the path doesn't exist). status without suppressing exceptions. -.. 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`. @@ -937,25 +910,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() - >>> p = Path('setup.py') - >>> p.stat().st_mode - 33277 - >>> p.chmod(0o444) - >>> p.stat().st_mode - 33060 + Like :meth:`Path.stat` but, if the path points to a symbolic link, return + the symbolic link's information rather than its target's. - .. versionchanged:: 3.10 - The *follow_symlinks* parameter was added. .. method:: Path.exists(*, follow_symlinks=True) @@ -980,6 +940,170 @@ 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`` will be + returned if the path is invalid, inaccessible or missing, or if it points + to something other than a regular file. Use :meth:`Path.stat` to + distinguish between these cases. + + 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`` will be + returned if the path is invalid, inaccessible or missing, or if it points + to something other than a directory. Use :meth:`Path.stat` to distinguish + between these cases. + + 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, even if that symlink + is broken. ``False`` will be returned if the path is invalid, inaccessible + or missing, or if it points to something other than a symbolic link. Use + :meth:`Path.stat` to distinguish between these cases. + + +.. 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. ``False`` will be + returned if the path is invalid, inaccessible or missing, or if it points + to something other than a Unix socket. Use :meth:`Path.stat` to + distinguish between these cases. + + +.. method:: Path.is_fifo() + + Return ``True`` if the path points to a FIFO. ``False`` will be returned if + the path is invalid, inaccessible or missing, or if it points to something + other than a FIFO. Use :meth:`Path.stat` to distinguish between these + cases. + + +.. method:: Path.is_block_device() + + Return ``True`` if the path points to a block device. ``False`` will be + returned if the path is invalid, inaccessible or missing, or if it points + to something other than a block device. Use :meth:`Path.stat` to + distinguish between these cases. + + +.. method:: Path.is_char_device() + + Return ``True`` if the path points to a character device. ``False`` will be + returned if the path is invalid, inaccessible or missing, or if it points + to something other than a character device. Use :meth:`Path.stat` to + distinguish between these cases. + + +.. 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, @@ -1076,99 +1200,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`` will be - returned if the path is invalid, inaccessible or missing, or if it points - to something other than a directory. Use :meth:`Path.stat` to distinguish - between these cases. - - 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`` will be - returned if the path is invalid, inaccessible or missing, or if it points - to something other than a regular file. Use :meth:`Path.stat` to - distinguish between these cases. - - 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, even if that symlink - is broken. ``False`` will be returned if the path is invalid, inaccessible - or missing, or if it points to something other than a symbolic link. Use - :meth:`Path.stat` to distinguish between these cases. - - -.. method:: Path.is_socket() - - Return ``True`` if the path points to a Unix socket. ``False`` will be - returned if the path is invalid, inaccessible or missing, or if it points - to something other than a Unix socket. Use :meth:`Path.stat` to - distinguish between these cases. - - -.. method:: Path.is_fifo() - - Return ``True`` if the path points to a FIFO. ``False`` will be returned if - the path is invalid, inaccessible or missing, or if it points to something - other than a FIFO. Use :meth:`Path.stat` to distinguish between these - cases. - - -.. method:: Path.is_block_device() - - Return ``True`` if the path points to a block device. ``False`` will be - returned if the path is invalid, inaccessible or missing, or if it points - to something other than a block device. Use :meth:`Path.stat` to - distinguish between these cases. - - -.. method:: Path.is_char_device() - - Return ``True`` if the path points to a character device. ``False`` will be - returned if the path is invalid, inaccessible or missing, or if it points - to something other than a character device. Use :meth:`Path.stat` to - distinguish between these cases. - - .. method:: Path.iterdir() When the path points to a directory, yield path objects of the directory @@ -1291,12 +1322,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 @@ -1486,27 +1511,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*.