Some more notes about bytes/string filename APIs.

This commit is contained in:
Georg Brandl 2008-10-08 16:34:57 +00:00
parent bcbfa64539
commit 76e5538749
3 changed files with 34 additions and 22 deletions

View File

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

View File

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

View File

@ -22,6 +22,12 @@ interface).
Extensions peculiar to a particular operating system are also available through
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
@ -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.