From: Martin v. Löwis <martin@v.loewis.de>
Date: Tue, 7 Oct 2008 07:03:04 +0000 (+0000)
Subject: More bytes vs. strings documentation.
X-Git-Tag: v3.0rc2~88
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=651423c1eb91a7e5a0ff346d2f52a654b765344a;p=thirdparty%2FPython%2Fcpython.git

More bytes vs. strings documentation.
---

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 1fdbeec2421f..7fe925847cee 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -710,10 +710,11 @@ are always available.  They are listed here in alphabetical order.
 
    Open a file.  If the file cannot be opened, :exc:`IOError` is raised.
    
-   *file* is either a string giving the name (and the path if the file isn't in
-   the current working directory) of the file to be opened or an integer file
-   descriptor of the file to be wrapped.  (If a file descriptor is given, it is
-   closed when the returned I/O object is closed, unless *closefd* is set to
+   *file* is either a string or bytes object giving the name (and the
+   path if the file isn't in the current working directory) of the
+   file to be opened or an integer file descriptor of the file to be
+   wrapped.  (If a file descriptor is given, it is closed when the
+   returned I/O object is closed, unless *closefd* is set to
    ``False``.)
 
    *mode* is an optional string that specifies the mode in which the file is
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 9bf5ae75fc81..71eeb533bc98 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -10,7 +10,14 @@
 
 This module implements some useful functions on pathnames. To read or
 write files see :func:`open`, and for accessing the filesystem see the
-:mod:`os` module.
+:mod:`os` module. The path parameters can be passed as either strings,
+or bytes. Applications are encouraged to represent file names as
+(Unicode) character strings. Unfortunately, some file names may not be
+representable as strings on Unix, so applications that need to support
+arbitrary file names on Unix should use bytes objects to represent
+path names. Vice versa, using bytes objects cannot represent all file
+names on Windows (in the standard ``mbcs`` encoding), hence Windows
+applications should use string objects to access all files.
 
 .. warning::
 
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 0fd4094e9ef0..14ad8f92d61f 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -694,6 +694,8 @@ Files and Directories
 .. function:: getcwd()
 
    Return a string representing the current working directory.
+   May raise UnicodeDecodeError if the current directory path fails
+   to decode in the file system encoding.
    Availability: Unix, Windows.