Change proposed name to shutil.umask_context

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_of(mask)
+.. class:: umask_context(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_of` context manager, within which we
-create a file that only the user can access:
+In this example, we use a :class:`umask_context`, within which we create
+a file that only the user can access:
 
 .. code-block:: pycon
 
-   >>> from shutil import umask_of
-   >>> with umask_of(0o077):
+   >>> from shutil import umask_context
+   >>> with umask_context(0o077):
    ...     with open("my-secret-file", "w") as f:
    ...         f.write("I ate all the cake!\n")
 
@@ -918,28 +918,28 @@ 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_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.
+Using :class:`umask_context` 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.
 
 It also allows you to write code that creates files, in a way that is agnostic
 of permissions -- that is without the need to pass a custom ``mode`` keyword
 argument to :func:`open` every time.
 
 In this example we create files with a function ``touch_file`` which uses the
 :func:`open` built-in without setting ``mode``. Permissions are managed by
-:class:`!umask_of`:
+:class:`umask_context`:
 
 .. code-block:: pycon
 
-   >>> from shutil import umask_of
+   >>> from shutil import umask_context
    >>>
    >>> def touch_file(path):
    ...    with open(path, "a"):
    ...        pass
    ...
    >>> touch_file("normal-file")
-   >>> with umask_of(0o077):
+   >>> with umask_context(0o077):
    ...    touch_file("private-file")
 
 .. code-block:: shell-session

Doc/whatsnew/3.14.rst

@@ -591,7 +591,7 @@ pydoc
 shutil
 ------
 
-* Add a new context manager :class:`~shutil.umask_of`, within which a
+* Add a new context manager :class:`~shutil.umask_context`, within which a
   process's umask is temporarily changed
 
 

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_of"]
+           "SameFileError", "umask_context"]
            # 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_of(AbstractContextManager):
+class umask_context(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_of)
+                    SameFileError, _GiveupOnFastCopy, umask_context)
 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_of']
+                      'get_terminal_size', 'SameFileError', 'umask_context']
         if hasattr(os, 'statvfs') or os.name == 'nt':
             target_api.append('disk_usage')
         self.assertEqual(set(shutil.__all__), set(target_api))
@@ -3483,7 +3483,7 @@ def test_simple(self):
         target_mask = self.mask_private
         self.assertNotEqual(old_mask, target_mask)
 
-        with umask_of(target_mask):
+        with umask_context(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_of(target_mask_1), umask_of(target_mask_2)
+        umask1, umask2 = umask_context(target_mask_1), umask_context(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_of(target_mask):
+            with umask_context(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_of` context manager to :mod:`shutil`, to provide a
-stdlib context manager for changing a process's umask
+Add a :class:`~shutil.umask_context` context manager to :mod:`shutil`, to
+provide a stdlib context manager for changing a process's umask