new os.path function to extract common prefix based on path components

Doc/library/os.path.rst

 :mod:`os.path` --- Common pathname manipulations
 ================================================
 
 .. module:: os.path
    :synopsis: Operations on pathnames.
 
 .. index:: single: path; operations
 
 This module implements some useful functions on pathnames. To read or
 write files see :func:`open`, and for accessing the filesystem see the
@@ skipping 41 matching lines @@
    from the Unix :program:`basename` program; where :program:`basename` for
    ``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an
    empty string (``''``).
 
 
 .. function:: commonprefix(list)
 
    Return the longest path prefix (taken character-by-character) that is a prefix
    of all paths in  *list*.  If *list* is empty, return the empty string (``''``).
    Note that this may return invalid paths because it works a character at a time.
+
+.. function:: commonpath(paths)
+
+   Return the longest common sub-path of each pathname in the sequence
+   *paths*.  The paths must be absolute, otherwise a ValueError is raised.
+   If *paths* is empty, return ``None``.  If each path ends with a path
+   separator, the returned sub-path will also end with a separator, otherwise
+   it will not.  Unlike :func:`commonprefix`, this returns a valid path.
+
+   Availability:  Unix.
+
+   .. versionadded:: 3.4
 
 
 .. function:: dirname(path)
 
    Return the directory name of pathname *path*.  This is the first half of the
    pair returned by ``split(path)``.
 
 
 .. function:: exists(path)
 
@@ skipping 248 matching lines @@
    the path (such as  ``r'\path\file.ext'``).  For paths containing drive letters,
    *unc* will always be the empty string.
 
    Availability:  Windows.
 
 
 .. data:: supports_unicode_filenames
 
    True if arbitrary Unicode strings can be used as file names (within limitations
    imposed by the file system).