gh-86533: Clarify parent_mode umask docs and harden makedirs/mkdir tests

Address review feedback on the parent_mode addition:

- Docs (os.makedirs, Path.mkdir): state that parent_mode, like mode, is
  combined with the process umask; it does not bypass it.
- Mark the parameter as added in 3.15 (approved for the 3.15 backport)
  instead of "next", which on main would resolve to 3.16.
- Replace the misleading "parent_mode overrides umask" test with one
  that verifies umask IS applied to parent_mode (0o777 + umask 0o022 ->
  0o755); add the matching os.makedirs test.
- Make MakedirTests cleanup name-agnostic and robust via
  os_helper.rmtree() instead of a hard-coded dir1/.../dir6 walk.
- Align the new test_os skips with the pathlib tests
  (Emscripten/WASI/Android); restore the original 0o555 case in
  test_mode.
- Use os_helper.temp_umask() in the pathlib tests instead of a manual
  os.umask() try/finally.

Author: gpshead

Doc/library/os.rst

@@ -2568,9 +2568,11 @@ features:
    If *exist_ok* is ``False`` (the default), a :exc:`FileExistsError` is
    raised if the target directory already exists.
 
-   If *parent_mode* is not ``None``, it will be used as the mode for any
-   newly-created, intermediate-level directories. Otherwise, intermediate
-   directories are created with the default permissions (respecting umask).
+   If *parent_mode* is not ``None``, it is used as the mode for any
+   newly-created, intermediate-level directories.  Like *mode*, it is
+   combined with the process's umask value; see :ref:`the mkdir()
+   description <mkdir_modebits>`.  Otherwise, intermediate directories are
+   created with the default mode, which is also subject to the umask.
 
    .. note::
 
@@ -2598,7 +2600,7 @@ features:
       The *mode* argument no longer affects the file permission bits of
       newly created intermediate-level directories.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
       The *parent_mode* parameter. To match the behavior from Python 3.6 and
       earlier (where *mode* was applied to all created directories), pass
       ``parent_mode=mode``.

Doc/library/pathlib.rst

@@ -1530,10 +1530,11 @@ Creating files and directories
    as needed; they are created with the default permissions without taking
    *mode* into account (mimicking the POSIX ``mkdir -p`` command).
 
-   If *parent_mode* is not ``None``, it will be used as the mode for any
+   If *parent_mode* is not ``None``, it is used as the mode for any
    newly-created, intermediate-level directories when *parents* is true.
+   Like *mode*, it is combined with the process's ``umask`` value.
    Otherwise, intermediate directories are created with the default
-   permissions (respecting umask).
+   permissions (also subject to the umask).
 
    If *parents* is false (the default), a missing parent raises
    :exc:`FileNotFoundError`.
@@ -1548,7 +1549,7 @@ Creating files and directories
    .. versionchanged:: 3.5
       The *exist_ok* parameter was added.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
       The *parent_mode* parameter.
 
 

Lib/test/test_os/test_os.py

@@ -2128,21 +2128,24 @@ def test_makedir(self):
     def test_mode(self):
         # Note: in some cases, the umask might already be 2 in which case this
         # will pass even if os.umask is actually broken.
-        parent = os.path.join(os_helper.TESTFN, 'dir1')
-        path = os.path.join(parent, 'dir2')
         with os_helper.temp_umask(0o002):
-            os.makedirs(path, 0o705)
+            base = os_helper.TESTFN
+            parent = os.path.join(base, 'dir1')
+            path = os.path.join(parent, 'dir2')
+            os.makedirs(path, 0o555)
             self.assertTrue(os.path.exists(path))
             self.assertTrue(os.path.isdir(path))
             if os.name != 'nt':
-                # Leaf directory gets the specified mode
-                self.assertEqual(os.stat(path).st_mode & 0o777, 0o705)
-                # Parent directory uses default permissions (respecting umask)
+                self.assertEqual(os.stat(path).st_mode & 0o777, 0o555)
                 self.assertEqual(os.stat(parent).st_mode & 0o777, 0o775)
 
     @unittest.skipIf(
-        support.is_wasi,
-        "WASI's umask is a stub."
+        support.is_emscripten or support.is_wasi,
+        "umask is not implemented on Emscripten/WASI."
+    )
+    @unittest.skipIf(
+        sys.platform == "android",
+        "Android filesystem may not honor requested permissions."
     )
     def test_mode_with_parent_mode(self):
         # Test the parent_mode parameter
@@ -2160,8 +2163,12 @@ def test_mode_with_parent_mode(self):
                 self.assertEqual(os.stat(parent).st_mode & 0o777, 0o750)
 
     @unittest.skipIf(
-        support.is_wasi,
-        "WASI's umask is a stub."
+        support.is_emscripten or support.is_wasi,
+        "umask is not implemented on Emscripten/WASI."
+    )
+    @unittest.skipIf(
+        sys.platform == "android",
+        "Android filesystem may not honor requested permissions."
     )
     def test_parent_mode_deep_hierarchy(self):
         # Test parent_mode with deep directory hierarchy
@@ -2179,8 +2186,12 @@ def test_parent_mode_deep_hierarchy(self):
                 self.assertEqual(os.stat(base).st_mode & 0o777, 0o755)
 
     @unittest.skipIf(
-        support.is_wasi,
-        "WASI's umask is a stub."
+        support.is_emscripten or support.is_wasi,
+        "umask is not implemented on Emscripten/WASI."
+    )
+    @unittest.skipIf(
+        sys.platform == "android",
+        "Android filesystem may not honor requested permissions."
     )
     def test_parent_mode_same_as_mode(self):
         # Test emulating Python 3.6 behavior by setting parent_mode=mode
@@ -2194,6 +2205,28 @@ def test_parent_mode_same_as_mode(self):
                 self.assertEqual(os.stat(path).st_mode & 0o777, 0o705)
                 self.assertEqual(os.stat(parent).st_mode & 0o777, 0o705)
 
+    @unittest.skipIf(
+        support.is_emscripten or support.is_wasi,
+        "umask is not implemented on Emscripten/WASI."
+    )
+    @unittest.skipIf(
+        sys.platform == "android",
+        "Android filesystem may not honor requested permissions."
+    )
+    def test_parent_mode_combined_with_umask(self):
+        # parent_mode, like mode, is combined with the process umask; it does
+        # not bypass it.
+        parent = os.path.join(os_helper.TESTFN, 'dir1')
+        path = os.path.join(parent, 'dir2')
+        with os_helper.temp_umask(0o022):
+            os.makedirs(path, 0o777, parent_mode=0o777)
+            self.assertTrue(os.path.isdir(path))
+            if os.name != 'nt':
+                # 0o777 is masked down to 0o755 by the 0o022 umask, for both
+                # the leaf (mode) and the parent (parent_mode).
+                self.assertEqual(os.stat(path).st_mode & 0o777, 0o755)
+                self.assertEqual(os.stat(parent).st_mode & 0o777, 0o755)
+
     @unittest.skipIf(
         support.is_wasi,
         "WASI's umask is a stub."
@@ -2267,15 +2300,9 @@ def test_win32_mkdir_700(self):
         )
 
     def tearDown(self):
-        path = os.path.join(os_helper.TESTFN, 'dir1', 'dir2', 'dir3',
-                            'dir4', 'dir5', 'dir6')
-        # If the tests failed, the bottom-most directory ('../dir6')
-        # may not have been created, so we look for the outermost directory
-        # that exists.
-        while not os.path.exists(path) and path != os_helper.TESTFN:
-            path = os.path.dirname(path)
-
-        os.removedirs(path)
+        # Remove the whole tree regardless of which sub-directories a test
+        # created and regardless of their permission bits.
+        os_helper.rmtree(os_helper.TESTFN)
 
 
 @unittest.skipUnless(hasattr(os, "chown"), "requires os.chown()")

Lib/test/test_pathlib/test_pathlib.py

@@ -2505,16 +2505,13 @@ def test_mkdir_parents_umask(self):
         p = self.cls(self.base, 'umasktest', 'child')
         self.assertFalse(p.exists())
         if os.name != 'nt':
-            old_mask = os.umask(0o002)
-            try:
+            with os_helper.temp_umask(0o002):
                 p.mkdir(0o755, parents=True)
                 self.assertTrue(p.exists())
                 # Leaf directory gets the specified mode
                 self.assertEqual(p.stat().st_mode & 0o777, 0o755)
                 # Parent directory respects umask (0o777 & ~0o002 = 0o775)
                 self.assertEqual(p.parent.stat().st_mode & 0o777, 0o775)
-            finally:
-                os.umask(old_mask)
 
     @unittest.skipIf(
         is_emscripten or is_wasi,
@@ -2569,22 +2566,19 @@ def test_mkdir_parent_mode_deep_hierarchy(self):
         sys.platform == "android",
         "Android filesystem may not honor requested permissions."
     )
-    def test_mkdir_parent_mode_overrides_umask(self):
-        # Test that parent_mode overrides umask for parent directories
-        p = self.cls(self.base, 'overridetest', 'child')
+    def test_mkdir_parent_mode_combined_with_umask(self):
+        # parent_mode, like mode, is combined with the process umask; it does
+        # not bypass it.
+        p = self.cls(self.base, 'umaskPM', 'child')
         self.assertFalse(p.exists())
         if os.name != 'nt':
-            old_mask = os.umask(0o022)  # Restrictive umask
-            try:
-                # parent_mode should override umask for parents
-                p.mkdir(0o755, parents=True, parent_mode=0o700)
+            with os_helper.temp_umask(0o022):
+                p.mkdir(0o777, parents=True, parent_mode=0o777)
                 self.assertTrue(p.exists())
-                # Leaf directory gets the specified mode
+                # 0o777 is masked down to 0o755 by the 0o022 umask, for both
+                # the leaf (mode) and the parent (parent_mode).
                 self.assertEqual(p.stat().st_mode & 0o777, 0o755)
-                # Parent directory gets parent_mode, not affected by umask
-                self.assertEqual(p.parent.stat().st_mode & 0o777, 0o700)
-            finally:
-                os.umask(old_mask)
+                self.assertEqual(p.parent.stat().st_mode & 0o777, 0o755)
 
     @unittest.skipIf(
         is_emscripten or is_wasi,