[3.13] GH-119054: Add "Permissions and ownership" section to pathlib docs. (GH-120505) (#120967)

Add dedicated subsection for `pathlib.owner()`, `group()`, `chmod()` and
`lchmod()`.

(cherry picked from commit e4a97a7fb1c03d3b6ec6efbeff553a0230e003c7)

1 files changed, 51 insertions, 48 deletions

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index ebed9d5..3b48d25 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1475,30 +1475,39 @@ Renaming and deleting
    Remove this directory.  The directory must be empty.
 
 
-Other methods
-^^^^^^^^^^^^^
+Permissions and ownership
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. classmethod:: Path.cwd()
+.. method:: Path.owner(*, follow_symlinks=True)
 
-   Return a new path object representing the current directory (as returned
-   by :func:`os.getcwd`)::
+   Return the name of the user owning the file. :exc:`KeyError` is raised
+   if the file's user identifier (UID) isn't found in the system database.
 
-      >>> Path.cwd()
-      PosixPath('/home/antoine/pathlib')
+   This method normally follows symlinks; to get the owner of the symlink, add
+   the argument ``follow_symlinks=False``.
 
+   .. versionchanged:: 3.13
+      Raises :exc:`UnsupportedOperation` if the :mod:`pwd` module is not
+      available. In earlier versions, :exc:`NotImplementedError` was raised.
 
-.. classmethod:: Path.home()
+   .. versionchanged:: 3.13
+      The *follow_symlinks* parameter was added.
 
-   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.
 
-   ::
+.. method:: Path.group(*, follow_symlinks=True)
 
-      >>> Path.home()
-      PosixPath('/home/antoine')
+   Return the name of the group owning the file. :exc:`KeyError` is raised
+   if the file's group identifier (GID) isn't found in the system database.
 
-   .. versionadded:: 3.5
+   This method normally follows symlinks; to get the group of the symlink, add
+   the argument ``follow_symlinks=False``.
+
+   .. versionchanged:: 3.13
+      Raises :exc:`UnsupportedOperation` if the :mod:`grp` module is not
+      available. In earlier versions, :exc:`NotImplementedError` was raised.
+
+   .. versionchanged:: 3.13
+      The *follow_symlinks* parameter was added.
 
 
 .. method:: Path.chmod(mode, *, follow_symlinks=True)
@@ -1522,57 +1531,51 @@ Other methods
       The *follow_symlinks* parameter was added.
 
 
-.. method:: Path.expanduser()
-
-   Return a new path with expanded ``~`` and ``~user`` constructs,
-   as returned by :meth:`os.path.expanduser`. If a home directory can't be
-   resolved, :exc:`RuntimeError` is raised.
+.. method:: Path.lchmod(mode)
 
-   ::
+   Like :meth:`Path.chmod` but, if the path points to a symbolic link, the
+   symbolic link's mode is changed rather than its target's.
 
-      >>> p = PosixPath('~/films/Monty Python')
-      >>> p.expanduser()
-      PosixPath('/home/eric/films/Monty Python')
 
-   .. versionadded:: 3.5
+Other methods
+^^^^^^^^^^^^^
 
+.. classmethod:: Path.cwd()
 
-.. method:: Path.group(*, follow_symlinks=True)
+   Return a new path object representing the current directory (as returned
+   by :func:`os.getcwd`)::
 
-   Return the name of the group owning the file. :exc:`KeyError` is raised
-   if the file's gid isn't found in the system database.
+      >>> Path.cwd()
+      PosixPath('/home/antoine/pathlib')
 
-   This method normally follows symlinks; to get the group of the symlink, add
-   the argument ``follow_symlinks=False``.
 
-   .. versionchanged:: 3.13
-      Raises :exc:`UnsupportedOperation` if the :mod:`grp` module is not
-      available. In previous versions, :exc:`NotImplementedError` was raised.
+.. classmethod:: Path.home()
 
-   .. versionchanged:: 3.13
-      The *follow_symlinks* parameter was added.
+   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.
 
+   ::
 
-.. method:: Path.lchmod(mode)
+      >>> Path.home()
+      PosixPath('/home/antoine')
 
-   Like :meth:`Path.chmod` but, if the path points to a symbolic link, the
-   symbolic link's mode is changed rather than its target's.
+   .. versionadded:: 3.5
 
 
-.. method:: Path.owner(*, follow_symlinks=True)
+.. method:: Path.expanduser()
 
-   Return the name of the user owning the file. :exc:`KeyError` is raised
-   if the file's uid isn't found in the system database.
+   Return a new path with expanded ``~`` and ``~user`` constructs,
+   as returned by :meth:`os.path.expanduser`. If a home directory can't be
+   resolved, :exc:`RuntimeError` is raised.
 
-   This method normally follows symlinks; to get the owner of the symlink, add
-   the argument ``follow_symlinks=False``.
+   ::
 
-   .. versionchanged:: 3.13
-      Raises :exc:`UnsupportedOperation` if the :mod:`pwd` module is not
-      available. In previous versions, :exc:`NotImplementedError` was raised.
+      >>> p = PosixPath('~/films/Monty Python')
+      >>> p.expanduser()
+      PosixPath('/home/eric/films/Monty Python')
 
-   .. versionchanged:: 3.13
-      The *follow_symlinks* parameter was added.
+   .. versionadded:: 3.5
 
 
 .. method:: Path.readlink()