Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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>
This commit is contained in:
Barney Gale 2024-06-24 20:05:24 +01:00 committed by GitHub
parent 375b723d58
commit e4a97a7fb1
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 62 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
Doc/library/pathlib.rst
View File

@ -1543,6 +1543,68 @@ Copying, renaming and deleting
Remove this directory. The directory must be empty. Remove this directory. The directory must be empty.
Permissions and ownership
^^^^^^^^^^^^^^^^^^^^^^^^^
.. method:: Path.owner(*, follow_symlinks=True)
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.
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.
.. versionchanged:: 3.13
The *follow_symlinks* parameter was added.
.. method:: Path.group(*, follow_symlinks=True)
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.
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)
Change the file mode and permissions, like :func:`os.chmod`.
This method normally follows symlinks. Some Unix flavours support changing
permissions on the symlink itself; on these platforms you may add the
argument ``follow_symlinks=False``, or use :meth:`~Path.lchmod`.
::
>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060
.. versionchanged:: 3.10
The *follow_symlinks* parameter was added.
.. 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.
Other methods Other methods
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
@ -1569,26 +1631,6 @@ Other methods
.. versionadded:: 3.5 .. versionadded:: 3.5
.. method:: Path.chmod(mode, *, follow_symlinks=True)
Change the file mode and permissions, like :func:`os.chmod`.
This method normally follows symlinks. Some Unix flavours support changing
permissions on the symlink itself; on these platforms you may add the
argument ``follow_symlinks=False``, or use :meth:`~Path.lchmod`.
::
>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060
.. versionchanged:: 3.10
The *follow_symlinks* parameter was added.
.. method:: Path.expanduser() .. method:: Path.expanduser()
Return a new path with expanded ``~`` and ``~user`` constructs, Return a new path with expanded ``~`` and ``~user`` constructs,
@ -1604,44 +1646,6 @@ Other methods
.. versionadded:: 3.5 .. versionadded:: 3.5
.. method:: Path.group(*, follow_symlinks=True)
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.
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.
.. versionchanged:: 3.13
The *follow_symlinks* parameter was added.
.. 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.
.. method:: Path.owner(*, follow_symlinks=True)
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.
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.
.. versionchanged:: 3.13
The *follow_symlinks* parameter was added.
.. method:: Path.readlink() .. method:: Path.readlink()
Return the path to which the symbolic link points (as returned by Return the path to which the symbolic link points (as returned by