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
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 @@
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