Some more notes about bytes/string filename APIs.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 7fe9258..ac25510 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -710,12 +710,11 @@
Open a file. If the file cannot be opened, :exc:`IOError` is raised.
- *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``.)
+ *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
opened. It defaults to ``'r'`` which means open for reading in text mode.
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 71eeb53..795c9bc 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -19,6 +19,12 @@
names on Windows (in the standard ``mbcs`` encoding), hence Windows
applications should use string objects to access all files.
+.. note::
+
+ All of these functions accept either only bytes or only string objects as
+ their parameters. The result is an object of the same type, if a path or
+ file name is returned.
+
.. warning::
On Windows, many of these functions do not properly support UNC pathnames.
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 14ad8f9..82a5b98 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -24,6 +24,12 @@
.. note::
+ All functions accepting path or file names accept both bytes and string
+ objects, and result in an object of the same type, if a path or file name is
+ returned.
+
+.. note::
+
If not separately noted, all functions that claim "Availability: Unix" are
supported on Mac OS X, which builds on a Unix core.
@@ -693,15 +699,16 @@
.. 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.
+ Return a string representing the current working directory. On Unix
+ platforms, this function may raise :exc:`UnicodeDecodeError` if the name of
+ the current directory is not decodable in the file system encoding. Use
+ :func:`getcwdb` if you need the call to never fail. Availability: Unix,
+ Windows.
.. function:: getcwdb()
- Return a bytestring representing the current working directory.
+ Return a bytestring representing the current working directory.
Availability: Unix, Windows.
@@ -798,15 +805,15 @@
.. function:: listdir(path)
- Return a list containing the names of the entries in the directory. The list is
- in arbitrary order. It does not include the special entries ``'.'`` and
- ``'..'`` even if they are present in the directory. Availability:
- Unix, Windows.
+ Return a list containing the names of the entries in the directory. The list
+ is in arbitrary order. It does not include the special entries ``.`` and
+ ``..`` even if they are present in the directory. Availability: Unix,
+ Windows.
- If *path* is a Unicode object, the result will be a list of Unicode objects.
- If a filename can not be decoded to unicode, it is skipped. If *path* is a
- bytes string, the result will be list of bytes objects included files
- skipped by the unicode version.
+ This function can be called with a bytes or string argument. In the bytes
+ case, all filenames will be listed as returned by the underlying API. In the
+ string case, filenames will be decoded using the file system encoding, and
+ skipped if a decoding error occurs.
.. function:: lstat(path)
@@ -920,9 +927,9 @@
be converted to an absolute pathname using ``os.path.join(os.path.dirname(path),
result)``.
- If the *path* is an Unicode object, the result will also be a Unicode object
- and may raise an UnicodeDecodeError. If the *path* is a bytes object, the
- result will be a bytes object.
+ If the *path* is a string object, the result will also be a string object,
+ and the call may raise an UnicodeDecodeError. If the *path* is a bytes
+ object, the result will be a bytes object.
Availability: Unix.