https://github.com/python/cpython/commit/4619f892966cd393395db221f936340eadce17d2
commit: 4619f892966cd393395db221f936340eadce17d2
branch: 3.13
author: Barney Gale <[email protected]>
committer: barneygale <[email protected]>
date: 2024-06-24T20:32:08+01:00
summary:
[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)
files:
M Doc/library/pathlib.rst
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index ebed9d50931061..3b48d25f96ddbc 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()
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
