gh-101000: Add os.path.splitroot() (#101002)

Co-authored-by: Eryk Sun <eryksun@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

2 files changed, 41 insertions, 3 deletions

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 42bbe24..786c2fd 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -488,6 +488,39 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
+.. function:: splitroot(path)
+
+   Split the pathname *path* into a 3-item tuple ``(drive, root, tail)`` where
+   *drive* is a device name or mount point, *root* is a string of separators
+   after the drive, and *tail* is everything after the root. Any of these
+   items may be the empty string. In all cases, ``drive + root + tail`` will
+   be the same as *path*.
+
+   On POSIX systems, *drive* is always empty. The *root* may be empty (if *path* is
+   relative), a single forward slash (if *path* is absolute), or two forward slashes
+   (implementation-defined per `IEEE Std 1003.1-2017; 4.13 Pathname Resolution
+   <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>`_.)
+   For example::
+
+      >>> splitroot('/home/sam')
+      ('', '/', 'home/sam')
+      >>> splitroot('//home/sam')
+      ('', '//', 'home/sam')
+      >>> splitroot('///home/sam')
+      ('', '/', '//home/sam')
+
+   On Windows, *drive* may be empty, a drive-letter name, a UNC share, or a device
+   name. The *root* may be empty, a forward slash, or a backward slash. For
+   example::
+
+      >>> splitroot('C:/Users/Sam')
+      ('C:', '/', 'Users/Sam')
+      >>> splitroot('//Server/Share/Users/Sam')
+      ('//Server/Share', '/', 'Users/Sam')
+
+   .. versionadded:: 3.12
+
+
 .. function:: splitext(path)
 
    Split the pathname *path* into a pair ``(root, ext)``  such that ``root + ext ==
diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
index 2f9ca11..a071159 100644
--- a/Doc/whatsnew/3.12.rst
+++ b/Doc/whatsnew/3.12.rst
@@ -288,13 +288,18 @@ os
   for a process with :func:`os.pidfd_open` in non-blocking mode.
   (Contributed by Kumar Aditya in :gh:`93312`.)
 
-* Add :func:`os.path.isjunction` to check if a given path is a junction.
-  (Contributed by Charles Machalow in :gh:`99547`.)
-
 * :class:`os.DirEntry` now includes an :meth:`os.DirEntry.is_junction`
   method to check if the entry is a junction.
   (Contributed by Charles Machalow in :gh:`99547`.)
 
+os.path
+-------
+
+* Add :func:`os.path.isjunction` to check if a given path is a junction.
+  (Contributed by Charles Machalow in :gh:`99547`.)
+
+* Add :func:`os.path.splitroot` to split a path into a triad
+  ``(drive, root, tail)``. (Contributed by Barney Gale in :gh:`101000`.)
 
 shutil
 ------