From 52bc99743c0c915c023e39fd714eb56c20c22c18 Mon Sep 17 00:00:00 2001
From: Barney Gale <barney.gale@gmail.com>
Date: Mon, 24 Jun 2024 20:32:24 +0100
Subject: [PATCH] [3.12] GH-119054: Add "Permissions and ownership" section to
 pathlib docs. (GH-120505) (#120968)

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

(cherry picked from commit e4a97a7fb1c03d3b6ec6efbeff553a0230e003c7)
---
 Doc/library/pathlib.rst | 77 +++++++++++++++++++++--------------------
 1 file changed, 40 insertions(+), 37 deletions(-)

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 4a62f6e77103e2..29d289aa533f6d 100644
--- 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()