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

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

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
---
 Doc/library/pathlib.rst | 98 +++++++++++++++++++++--------------------
 1 file changed, 51 insertions(+), 47 deletions(-)

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index e585bcef915fbf..28a006d9619bbc 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1543,30 +1543,39 @@ Copying, 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)
@@ -1589,57 +1598,52 @@ Other methods
    .. versionchanged:: 3.10
       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()