Change proposed name of shutil.umask to shutil.umask_of

Author: jb2170

Doc/library/shutil.rst

@@ -892,7 +892,7 @@ High-level :term:`context managers <context manager>` for changing a process's e
    temporarily relinquished. Unless explicitly desired, you should not yield
    within these context managers.
 
-.. class:: umask(mask)
+.. class:: umask_of(mask)
 
    This is a simple wrapper around :func:`os.umask`. It changes the process's
    umask upon entering and restores the old one on exit.
@@ -901,13 +901,13 @@ High-level :term:`context managers <context manager>` for changing a process's e
 
    .. versionadded:: next
 
-In this example, we use a :class:`umask` context manager, within which we
+In this example, we use a :class:`umask_of` context manager, within which we
 create a file that only the user can access:
 
 .. code-block:: pycon
 
-   >>> from shutil import umask
-   >>> with umask(0o077):
+   >>> from shutil import umask_of
+   >>> with umask_of(0o077):
    ...     with open("my-secret-file", "w") as f:
    ...         f.write("I ate all the cake!\n")
 
@@ -918,7 +918,7 @@ The file's permissions are empty for anyone but the user:
     $ ls -l my-secret-file
     -rw------- 1 guest guest 20 Jan  1 23:45 my-secret-file
 
-Using :class:`umask` like this is better practice than first creating the file,
+Using :class:`umask_of` like this is better practice than first creating the file,
 and later changing its permissions with :func:`~os.chmod`, between which a
 period of time exists in which the file may have too lenient permissions.
 

Lib/shutil.py

@@ -62,7 +62,7 @@
            "get_unpack_formats", "register_unpack_format",
            "unregister_unpack_format", "unpack_archive",
            "ignore_patterns", "chown", "which", "get_terminal_size",
-           "SameFileError", "umask"]
+           "SameFileError", "umask_of"]
            # disk_usage is added later, if available on the platform
 
 class Error(OSError):
@@ -1583,7 +1583,7 @@ def which(cmd, mode=os.F_OK | os.X_OK, path=None):
     return None
 
 
-class umask(AbstractContextManager):
+class umask_of(AbstractContextManager):
     """Non thread-safe context manager to change the process's umask."""
 
     def __init__(self, mask):

Lib/test/test_shutil.py

@@ -21,7 +21,7 @@
                     get_archive_formats, Error, unpack_archive,
                     register_unpack_format, RegistryError,
                     unregister_unpack_format, get_unpack_formats,
-                    SameFileError, _GiveupOnFastCopy, umask)
+                    SameFileError, _GiveupOnFastCopy, umask_of)
 import tarfile
 import zipfile
 try:
@@ -3458,7 +3458,7 @@ def test_module_all_attribute(self):
                       'unregister_archive_format', 'get_unpack_formats',
                       'register_unpack_format', 'unregister_unpack_format',
                       'unpack_archive', 'ignore_patterns', 'chown', 'which',
-                      'get_terminal_size', 'SameFileError', 'umask']
+                      'get_terminal_size', 'SameFileError', 'umask_of']
         if hasattr(os, 'statvfs') or os.name == 'nt':
             target_api.append('disk_usage')
         self.assertEqual(set(shutil.__all__), set(target_api))
@@ -3468,7 +3468,7 @@ def test_module_all_attribute(self):
 
 @unittest.skipIf(os.name != "posix" or support.is_wasi or support.is_emscripten,
                  "need proper os.umask()")
-class TestUmask(unittest.TestCase):
+class TestUmaskOf(unittest.TestCase):
     # make target masks in here sufficiently exotic, away from 0o022
 
     mask_private = 0o777
@@ -3483,7 +3483,7 @@ def test_simple(self):
         target_mask = self.mask_private
         self.assertNotEqual(old_mask, target_mask)
 
-        with umask(target_mask):
+        with umask_of(target_mask):
             self.assertEqual(self.get_mask(), target_mask)
         self.assertEqual(self.get_mask(), old_mask)
 
@@ -3492,7 +3492,7 @@ def test_reentrant(self):
         target_mask_1 = self.mask_private
         target_mask_2 = self.mask_public
         self.assertNotIn(old_mask, (target_mask_1, target_mask_2))
-        umask1, umask2 = umask(target_mask_1), umask(target_mask_2)
+        umask1, umask2 = umask_of(target_mask_1), umask_of(target_mask_2)
 
         with umask1:
             self.assertEqual(self.get_mask(), target_mask_1)
@@ -3510,7 +3510,7 @@ def test_exception(self):
         self.assertNotEqual(old_mask, target_mask)
 
         try:
-            with umask(target_mask):
+            with umask_of(target_mask):
                 self.assertEqual(self.get_mask(), target_mask)
                 raise RuntimeError("boom")
         except RuntimeError as re:

Misc/NEWS.d/next/Library/2025-01-03-01-12-47.gh-issue-128432.8kg5DK.rst

@@ -1,2 +1,2 @@
-Add a :class:`~shutil.umask` context manager to :mod:`shutil`, to provide a
+Add a :class:`~shutil.umask_of` context manager to :mod:`shutil`, to provide a
 stdlib context manager for changing a process's umask