Create os.fsdecode(): decode from the filesystem encoding with surrogateescape

error handler, or strict error handler on Windows.

 * Rewrite os.fsencode() documentation
 * Improve os.fsencode and os.fsdecode() tests using the new PYTHONFSENCODING
   environment variable

2 files changed, 24 insertions, 8 deletions

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 9ab5fb1..8df98cf 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -155,13 +155,26 @@ process and user.
    These functions are described in :ref:`os-file-dir`.
 
 
-.. function:: fsencode(value)
+.. function:: fsencode(filename)
 
-   Encode *value* to bytes for use in the file system, environment variables or
-   the command line. Use :func:`sys.getfilesystemencoding` and
-   ``'surrogateescape'`` error handler for strings and return bytes unchanged.
-   On Windows, use ``'strict'`` error handler for strings if the file system
-   encoding is ``'mbcs'`` (which is the default encoding).
+   Encode *filename* to the filesystem encoding with ``'surrogateescape'``
+   error handler, return :class:`bytes` unchanged. On Windows, use ``'strict'``
+   error handler if the filesystem encoding is ``'mbcs'`` (which is the default
+   encoding).
+
+   :func:`fsdencode` is the reverse function.
+
+   .. versionadded:: 3.2
+
+
+.. function:: fsdecode(filename)
+
+   Decode *filename* from the filesystem encoding with ``'surrogateescape'``
+   error handler, return :class:`str` unchanged. On Windows, use ``'strict'``
+   error handler if the filesystem encoding is ``'mbcs'`` (which is the default
+   encoding).
+
+   :func:`fsencode` is the reverse function.
 
    .. versionadded:: 3.2
 
diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
index 3927f4b..2ec93d2 100644
--- a/Doc/whatsnew/3.2.rst
+++ b/Doc/whatsnew/3.2.rst
@@ -237,13 +237,16 @@ Major performance enhancements have been added:
 * Stub
 
 
-Unicode
-=======
+Filenames and unicode
+=====================
 
 The filesystem encoding can be specified by setting the
 :envvar:`PYTHONFSENCODING` environment variable before running the interpreter.
 The value should be a string in the form ``<encoding>``, e.g. ``utf-8``.
 
+The :mod:`os` module has two new functions: :func:`os.fsencode` and
+:func:`os.fsdecode`.
+
 
 IDLE
 ====