From 76e5538749947eaf5fbf6487805d004ea244b941 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 8 Oct 2008 16:34:57 +0000 Subject: Some more notes about bytes/string filename APIs. --- Doc/library/functions.rst | 11 +++++------ Doc/library/os.path.rst | 6 ++++++ Doc/library/os.rst | 39 +++++++++++++++++++++++---------------- 3 files changed, 34 insertions(+), 22 deletions(-) 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 @@ 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 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 @@ 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. +.. 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 @@ the :mod:`os` module, but using them is of course a threat to portability! .. 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 @@ 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. + 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 @@ Files and Directories .. 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 @@ Files and Directories 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. -- cgit v0.12