[Python-checkins] cpython (2.7): Issue #15414: Clean and correct the os.path.join docs.

[zach.ware]

https://hg.python.org/cpython/rev/05274a517b37
changeset:   92937:05274a517b37
branch:      2.7
parent:      92929:9cee201388c9
user:        Zachary Ware <zachary.ware at gmail.com>
date:        Fri Oct 10 16:03:14 2014 -0500
summary:
  Issue #15414: Clean and correct the os.path.join docs.

In particular, correctly describe the behavior of ntpath.join.

Based on a patch by Dave Sawyer.

files:
  Doc/library/os.path.rst |  25 +++++++++++++++----------
  1 files changed, 15 insertions(+), 10 deletions(-)


diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -197,17 +197,22 @@
    device --- this should detect mount points for all Unix and POSIX variants.
 
 
-.. function:: join(path1[, path2[, ...]])
+.. function:: join(path, *paths)
 
-   Join one or more path components intelligently.  If any component is an absolute
-   path, all previous components (on Windows, including the previous drive letter,
-   if there was one) are thrown away, and joining continues.  The return value is
-   the concatenation of *path1*, and optionally *path2*, etc., with exactly one
-   directory separator (``os.sep``) following each non-empty part except the last.
-   (This means that an empty last part will result in a path that ends with a
-   separator.)  Note that on Windows, since there is a current directory for
-   each drive, ``os.path.join("c:", "foo")`` represents a path relative to the
-   current directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`.
+   Join one or more path components intelligently.  The return value is the
+   concatenation of *path* and any members of *\*paths* with exactly one
+   directory separator (``os.sep``) following each non-empty part except the
+   last, meaning that the result will only end in a separator if the last
+   part is empty.  If a component is an absolute path, all previous
+   components are thrown away and joining continues from the absolute path
+   component.
+
+   On Windows, the drive letter is not reset when an absolute path component
+   (e.g., ``r'\foo'``) is encountered.  If a component contains a drive
+   letter, all previous components are thrown away and the drive letter is
+   reset.  Note that since there is a current directory for each drive,
+   ``os.path.join("c:", "foo")`` represents a path relative to the current
+   directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`.
 
 
 .. function:: normcase(path)

-- 
Repository URL: https://hg.python.org/cpython