More bytes vs. strings documentation.

3 files changed, 15 insertions, 5 deletions

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 1fdbeec..7fe9258 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 9bf5ae7..71eeb53 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 0fd4094..14ad8f9 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.