Modernize os.makedirs for Python 3.15: Add parent_mode parameter

- Replace recursive_mode with more intuitive parent_mode parameter
- parent_mode=None (default): intermediate dirs use default permissions
- parent_mode=<mode>: intermediate dirs use specified permissions
- parent_mode=mode: matches Python 3.6 behavior
- Update documentation with version markers and usage examples
- Add comprehensive test coverage with separate focused test functions
- Fix test permissions to avoid cleanup issues (0o555 → 0o705)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: gpshead

Doc/library/os.rst

@@ -2524,7 +2524,7 @@ features:
 
 
 .. function:: makedirs(name, mode=0o777, exist_ok=False, *, \
-                       recursive_mode=False)
+                       parent_mode=None)
 
    .. index::
       single: directory; creating
@@ -2542,8 +2542,9 @@ features:
    If *exist_ok* is ``False`` (the default), a :exc:`FileExistsError` is
    raised if the target directory already exists.
 
-   If *recursive_mode* is ``True``, the *mode* argument will affect the file
-   permission bits of any newly-created, intermediate-level directories.
+   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).
 
    .. note::
 
@@ -2571,8 +2572,10 @@ features:
       The *mode* argument no longer affects the file permission bits of
       newly created intermediate-level directories.
 
-   .. versionadded:: 3.10
-      The *recursive_mode* parameter.
+   .. versionadded:: next
+      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``.
 
 
 .. function:: mkfifo(path, mode=0o666, *, dir_fd=None)

Doc/whatsnew/3.15.rst

@@ -358,6 +358,15 @@ math
   (Contributed by Bénédikt Tran in :gh:`135853`.)
 
 
+os
+--
+
+* :func:`os.makedirs` function now has a *parent_mode* parameter that allows
+  specifying the mode for intermediate directories. This can be used to match
+  the behavior from Python 3.6 and earlier by passing ``parent_mode=mode``.
+  (Contributed by Zackery Spytz in :gh:`86533`.)
+
+
 os.path
 -------
 

Lib/os.py

@@ -208,26 +208,27 @@ def _add(str, fn):
 # Super directory utilities.
 # (Inspired by Eric Raymond; the doc strings are mostly his)
 
-def makedirs(name, mode=0o777, exist_ok=False, *, recursive_mode=False):
-    """makedirs(name [, mode=0o777][, exist_ok=False][, recursive_mode=False])
+def makedirs(name, mode=0o777, exist_ok=False, *, parent_mode=None):
+    """makedirs(name [, mode=0o777][, exist_ok=False][, parent_mode=None])
 
     Super-mkdir; create a leaf directory and all intermediate ones.  Works like
     mkdir, except that any intermediate path segment (not just the rightmost)
     will be created if it does not exist. If the target directory already
     exists, raise an OSError if exist_ok is False. Otherwise no exception is
-    raised.  If recursive_mode is True, the mode argument will affect the file
-    permission bits of any newly-created, intermediate-level directories.  This
-    is recursive.
+    raised.  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).
+    This is recursive.
 
     """
     head, tail = path.split(name)
     if not tail:
         head, tail = path.split(head)
     if head and tail and not path.exists(head):
         try:
-            if recursive_mode:
-                makedirs(head, mode=mode, exist_ok=exist_ok,
-                         recursive_mode=True)
+            if parent_mode is not None:
+                makedirs(head, mode=parent_mode, exist_ok=exist_ok,
+                         parent_mode=parent_mode)
             else:
                 makedirs(head, exist_ok=exist_ok)
         except FileExistsError:

Lib/test/test_os.py

@@ -1924,16 +1924,68 @@ def test_mode(self):
         parent = os.path.join(os_helper.TESTFN, 'dir1')
         path = os.path.join(parent, 'dir2')
         with os_helper.temp_umask(0o002):
-            for mode, recursive_mode, path_mode, parent_mode in \
-                    (0o555, False, 0o555, 0o775), (0o770, True, 0o770, 0o770):
-                os.makedirs(path, mode, recursive_mode=recursive_mode)
-                self.assertTrue(os.path.exists(path))
-                self.assertTrue(os.path.isdir(path))
-                if os.name != 'nt':
-                    self.assertEqual(os.stat(path).st_mode & 0o777, path_mode)
-                    self.assertEqual(os.stat(parent).st_mode & 0o777,
-                                     parent_mode)
-                shutil.rmtree(parent)
+            os.makedirs(path, 0o705)
+            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(parent).st_mode & 0o777, 0o775)
+
+    @unittest.skipIf(
+        support.is_wasi,
+        "WASI's umask is a stub."
+    )
+    def test_mode_with_parent_mode(self):
+        # Test the parent_mode parameter
+        parent = os.path.join(os_helper.TESTFN, 'dir1')
+        path = os.path.join(parent, 'dir2')
+        with os_helper.temp_umask(0o002):
+            # Specify mode for both leaf and parent directories
+            os.makedirs(path, 0o770, parent_mode=0o750)
+            self.assertTrue(os.path.exists(path))
+            self.assertTrue(os.path.isdir(path))
+            if os.name != 'nt':
+                # Leaf directory gets the mode parameter
+                self.assertEqual(os.stat(path).st_mode & 0o777, 0o770)
+                # Parent directory gets the parent_mode parameter
+                self.assertEqual(os.stat(parent).st_mode & 0o777, 0o750)
+
+    @unittest.skipIf(
+        support.is_wasi,
+        "WASI's umask is a stub."
+    )
+    def test_parent_mode_deep_hierarchy(self):
+        # Test parent_mode with deep directory hierarchy
+        base = os.path.join(os_helper.TESTFN, 'dir1', 'dir2', 'dir3')
+        with os_helper.temp_umask(0o002):
+            os.makedirs(base, 0o755, parent_mode=0o700)
+            self.assertTrue(os.path.exists(base))
+            if os.name != 'nt':
+                # Check that all parent directories have parent_mode
+                level1 = os.path.join(os_helper.TESTFN, 'dir1')
+                level2 = os.path.join(level1, 'dir2')
+                self.assertEqual(os.stat(level1).st_mode & 0o777, 0o700)
+                self.assertEqual(os.stat(level2).st_mode & 0o777, 0o700)
+                # Leaf directory has the regular mode
+                self.assertEqual(os.stat(base).st_mode & 0o777, 0o755)
+
+    @unittest.skipIf(
+        support.is_wasi,
+        "WASI's umask is a stub."
+    )
+    def test_parent_mode_same_as_mode(self):
+        # Test emulating Python 3.6 behavior by setting parent_mode=mode
+        parent = os.path.join(os_helper.TESTFN, 'dir1')
+        path = os.path.join(parent, 'dir2')
+        with os_helper.temp_umask(0o002):
+            os.makedirs(path, 0o705, parent_mode=0o705)
+            self.assertTrue(os.path.exists(path))
+            if os.name != 'nt':
+                # Both directories should have the same mode
+                self.assertEqual(os.stat(path).st_mode & 0o777, 0o705)
+                self.assertEqual(os.stat(parent).st_mode & 0o777, 0o705)
 
     @unittest.skipIf(
         support.is_wasi,

Misc/NEWS.d/next/Library/2020-12-22-16-55-59.bpo-42367.IGICm2.rst

@@ -1 +1,3 @@
-The :func:`os.makedirs` function now has a *recursive_mode* parameter.
+The :func:`os.makedirs` function now has a *parent_mode* parameter to specify
+the mode for intermediate directories, allowing one to match the behavior from
+Python 3.6 and earlier.