[Python-checkins] r82002 - in python/branches/release31-maint: Doc/c-api/file.rst

[antoine.pitrou]

Author: antoine.pitrou
Date: Tue Jun 15 19:31:05 2010
New Revision: 82002

Log:
Merged revisions 82000-82001 via svnmerge from 
svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r82000 | antoine.pitrou | 2010-06-15 19:00:21 +0200 (mar., 15 juin 2010) | 3 lines
  
  Fixes to the PyFile_FromFd() doc, by Renato Cunha.
........
  r82001 | antoine.pitrou | 2010-06-15 19:30:16 +0200 (mar., 15 juin 2010) | 3 lines
  
  Further refinements to the C file API.
........


Modified:
   python/branches/release31-maint/   (props changed)
   python/branches/release31-maint/Doc/c-api/file.rst

Modified: python/branches/release31-maint/Doc/c-api/file.rst
==============================================================================
--- python/branches/release31-maint/Doc/c-api/file.rst	(original)
+++ python/branches/release31-maint/Doc/c-api/file.rst	Tue Jun 15 19:31:05 2010
@@ -7,24 +7,29 @@
 
 .. index:: object: file
 
-Python's built-in file objects are implemented entirely on the :ctype:`FILE\*`
-support from the C standard library.  This is an implementation detail and may
-change in future releases of Python.  The ``PyFile_`` APIs are a wrapper over
-the :mod:`io` module.
-
-
-.. cfunction:: PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *newline, int closefd)
-
-   Create a new :ctype:`PyFileObject` from the file descriptor of an already
-   opened file *fd*. The arguments *name*, *encoding* and *newline* can be
-   *NULL* to use the defaults; *buffering* can be *-1* to use the default.
-   Return *NULL* on failure.
+These APIs are a minimal emulation of the Python 2 C API for built-in file
+objects, which used to rely on the buffered I/O (:ctype:`FILE\*`) support
+from the C standard library.  In Python 3, files and streams use the new
+:mod:`io` module, which defines several layers over the low-level unbuffered
+I/O of the operating system.  The functions described below are
+convenience C wrappers over these new APIs, and meant mostly for internal
+error reporting in the interpreter; third-party code is advised to access
+the :mod:`io` APIs instead.
+
+
+.. cfunction:: PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *errors, char *newline, int closefd)
+
+   Create a Python file object from the file descriptor of an already
+   opened file *fd*.  The arguments *name*, *encoding*, *errors* and *newline*
+   can be *NULL* to use the defaults; *buffering* can be *-1* to use the
+   default.  Return *NULL* on failure.  For a more comprehensive description of
+   the arguments, please refer to the :func:`io.open` function documentation.
 
    .. warning::
 
-     Take care when you are mixing streams and descriptors! For more
-     information, see `the GNU C Library docs
-     <http://www.gnu.org/software/libc/manual/html_node/Stream_002fDescriptor-Precautions.html#Stream_002fDescriptor-Precautions>`_.
+     Since Python streams have their own buffering layer, mixing them with
+     OS-level file descriptors can produce various issues (such as unexpected
+     ordering of data).
 
 
 .. cfunction:: int PyObject_AsFileDescriptor(PyObject *p)