[Python-3000-checkins] r66853 - in python/branches/py3k/Doc/library: functions.rst os.path.rst os.rst

georg.brandl python-3000-checkins at python.org
Wed Oct 8 18:34:57 CEST 2008


Author: georg.brandl
Date: Wed Oct  8 18:34:57 2008
New Revision: 66853

Log:
Some more notes about bytes/string filename APIs.


Modified:
   python/branches/py3k/Doc/library/functions.rst
   python/branches/py3k/Doc/library/os.path.rst
   python/branches/py3k/Doc/library/os.rst

Modified: python/branches/py3k/Doc/library/functions.rst
==============================================================================
--- python/branches/py3k/Doc/library/functions.rst	(original)
+++ python/branches/py3k/Doc/library/functions.rst	Wed Oct  8 18:34:57 2008
@@ -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.

Modified: python/branches/py3k/Doc/library/os.path.rst
==============================================================================
--- python/branches/py3k/Doc/library/os.path.rst	(original)
+++ python/branches/py3k/Doc/library/os.path.rst	Wed Oct  8 18:34:57 2008
@@ -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.

Modified: python/branches/py3k/Doc/library/os.rst
==============================================================================
--- python/branches/py3k/Doc/library/os.rst	(original)
+++ python/branches/py3k/Doc/library/os.rst	Wed Oct  8 18:34:57 2008
@@ -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.
 


More information about the Python-3000-checkins mailing list