pythonGH-119054: Add "Querying file type and status" section to pathl…

…ib docs (python#119055)

Add a dedicated subsection for `Path.stat()`-related methods, specifically
`stat()`, `lstat()`, `exists()`, `is_*()`, and `samefile()`.

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*.