Some more notes about bytes/string filename APIs.
This commit is contained in:
parent
bcbfa64539
commit
76e5538749
|
@ -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.
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
Loading…
Reference in New Issue