[3.12] GH-119054: Add "Permissions and ownership" section to pathlib docs. (GH-120505...

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

(cherry picked from commit e4a97a7fb1c03d3b6ec6efbeff553a0230e003c7)

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 4a62f6e77103e248dbfc72168af7c37f558732a2..29d289aa533f6d84fbec8f4fd2fac07e584eba35 100644 (file)
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1380,30 +1380,19 @@ Renaming and deleting
    Remove this directory.  The directory must be empty.
 
 
-Other methods
-^^^^^^^^^^^^^
-
-.. classmethod:: Path.cwd()
-
-   Return a new path object representing the current directory (as returned
-   by :func:`os.getcwd`)::
-
-      >>> Path.cwd()
-      PosixPath('/home/antoine/pathlib')
-
+Ownership and permissions
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. classmethod:: Path.home()
+.. method:: Path.owner()
 
-   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.
+   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.home()
-      PosixPath('/home/antoine')
+.. method:: Path.group()
 
-   .. versionadded:: 3.5
+   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.
 
 
 .. method:: Path.chmod(mode, *, follow_symlinks=True)
@@ -1427,37 +1416,51 @@ Other methods
       The *follow_symlinks* parameter was added.
 
 
-.. method:: Path.expanduser()
+.. method:: Path.lchmod(mode)
 
-   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.
+   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')
+Other methods
+^^^^^^^^^^^^^
 
-   .. versionadded:: 3.5
+.. classmethod:: Path.cwd()
 
+   Return a new path object representing the current directory (as returned
+   by :func:`os.getcwd`)::
 
-.. method:: Path.group()
+      >>> Path.cwd()
+      PosixPath('/home/antoine/pathlib')
 
-   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.
 
+.. classmethod:: Path.home()
 
-.. method:: Path.lchmod(mode)
+   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.
 
-   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.
+   ::
+
+      >>> Path.home()
+      PosixPath('/home/antoine')
 
+   .. versionadded:: 3.5
 
-.. method:: Path.owner()
 
-   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.
+.. 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.
+
+   ::
+
+      >>> p = PosixPath('~/films/Monty Python')
+      >>> p.expanduser()
+      PosixPath('/home/eric/films/Monty Python')
+
+   .. versionadded:: 3.5
 
 
 .. method:: Path.readlink()