[3.12] GH-119054: Add "Querying file type and status" section to pathlib docs (GH-119055) (#119952)

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

(cherry picked from commit 81d6336230)

Doc/library/pathlib.rst

@@ -790,12 +790,8 @@ bugs or failures in your application)::
    NotImplementedError: cannot instantiate 'WindowsPath' on your system
 
 
-Methods
+Querying file type and status
-^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-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).
 
 .. versionchanged:: 3.8
 
@@ -807,6 +803,169 @@ 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()
+
+   Return ``True`` if the path points to a regular file (or a symbolic link
+   pointing 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.
+
+
+.. method:: Path.is_dir()
+
+   Return ``True`` if the path points to a directory (or a symbolic link
+   pointing 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.
+
+
+.. 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
+^^^^^^^^^^^^^
+
+Many 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
@@ -830,25 +989,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`.
@@ -869,26 +1009,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()
 
@@ -955,93 +1075,6 @@ call fails (for example because the path doesn't exist).
    if the file's gid isn't found in the system database.
 
 
-.. method:: Path.is_dir()
-
-   Return ``True`` if the path points to a directory (or a symbolic link
-   pointing 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.
-
-
-.. method:: Path.is_file()
-
-   Return ``True`` if the path points to a regular file (or a symbolic link
-   pointing 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.
-
-
-.. 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
@@ -1164,12 +1197,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
@@ -1367,27 +1394,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*.