diff --git a/Doc/library/os.rst b/Doc/library/os.rst --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1521,6 +1521,9 @@ Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave one of the ids unchanged, set it to -1. + See :func:`shutil.chown` for a higher-level function that accepts names in + addition to numeric ids. + Availability: Unix. diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -165,6 +165,21 @@ Otherwise, copy src (with :func:`copy2`) to the dst and then remove src. +.. function:: chown(path, user=None, group=None) + + Change owner *user* and/or *group* of the given *path* (either a file or a + directory). + + *user* can be a system user name or a uid; the same applies to *group*. To + leave one of the two unchanged, set it to *None* or omit it. + + See also :func:`os.chown`, the underlying function. + + Availability: Unix. + + .. versionadded:: 3.3 + + .. exception:: Error This exception collects exceptions that raised during a multi-file operation. For diff --git a/Lib/shutil.py b/Lib/shutil.py --- a/Lib/shutil.py +++ b/Lib/shutil.py @@ -754,3 +754,37 @@ func = _UNPACK_FORMATS[format][1] kwargs = dict(_UNPACK_FORMATS[format][2]) func(filename, extract_dir, **kwargs) + +def chown(path, user=None, group=None): + """Change owner user and group of the given path (file or dir). + + user and group can be the uid/gid or the user/group names, and in that case, + they are converted to their respective uid/gid. + """ + + if user is None and group is None: + raise ValueError("user and/or group must be set") + + _user = user + _group = group + + # -1 means don't change it + if user is None: + _user = -1 + else: + # user can either be an int (the uid) or a string (the system username) + if not isinstance(user, int): + _user = _get_uid(user) + # it means we weren't able to get the uid from the name + if _user is None: + raise ValueError("no such user, %s" % user) + + if group is None: + _group = -1 + else: + if not isinstance(group, int): + _group = _get_gid(group) + if _group is None: + raise ValueError("no such group, %s" % group) + + os.chown(path, _user, _group) diff --git a/Lib/test/test_shutil.py b/Lib/test/test_shutil.py --- a/Lib/test/test_shutil.py +++ b/Lib/test/test_shutil.py @@ -729,6 +729,37 @@ unregister_unpack_format('Boo2') self.assertEqual(get_unpack_formats(), formats) + @unittest.skipUnless(UID_GID_SUPPORT, "Requires grp and pwd support") + def test_chown(self): + + # cleaned-up automatically by Test.Shutil.tearDown method + dirname = self.mkdtemp() + filename = tempfile.mktemp(dir=dirname) + self._write_data(filename, 'testing chown function') + + with self.assertRaises(ValueError): + shutil.chown(filename) + + with self.assertRaises(ValueError): + shutil.chown(filename, 'non-exising username') + + with self.assertRaises(ValueError): + shutil.chown(filename, group='non-exising groupname') + + shutil.chown(filename, os.getuid(), os.getgid()) + shutil.chown(filename, os.getuid()) + shutil.chown(filename, user=os.getuid()) + shutil.chown(filename, group=os.getgid()) + + shutil.chown(dirname, os.getuid(), os.getgid()) + shutil.chown(dirname, os.getuid()) + shutil.chown(dirname, user=os.getuid()) + shutil.chown(dirname, group=os.getgid()) + + _user = pwd.getpwuid(os.getuid())[0] + _group = grp.getgrgid(os.getgid())[0] + shutil.chown(filename, _user, _group) + shutil.chown(dirname, _user, _group) class TestMove(unittest.TestCase):