diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index ebed9d50931..3b48d25f96d 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1475,6 +1475,68 @@ Renaming and deleting 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 ^^^^^^^^^^^^^ @@ -1501,27 +1563,6 @@ Other methods .. 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() Return a new path with expanded ``~`` and ``~user`` constructs, @@ -1537,44 +1578,6 @@ Other methods .. 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() Return the path to which the symbolic link points (as returned by