
File Objects
************

Python's built-in file objects are implemented entirely on the
``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 ``io`` module.

PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *newline, int closefd)

   Create a new ``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.

   Warning: Take care when you are mixing streams and descriptors! For more
     information, see the GNU C Library docs.

int PyObject_AsFileDescriptor(PyObject *p)

   Return the file descriptor associated with *p* as an ``int``.  If
   the object is an integer, its value is returned.  If not, the
   object's ``fileno()`` method is called if it exists; the method
   must return an integer, which is returned as the file descriptor
   value.  Sets an exception and returns ``-1`` on failure.

PyObject* PyFile_GetLine(PyObject *p, int n)
    Return value: New reference.

   Equivalent to ``p.readline([n])``, this function reads one line
   from the object *p*.  *p* may be a file object or any object with a
   ``readline()`` method.  If *n* is ``0``, exactly one line is read,
   regardless of the length of the line.  If *n* is greater than
   ``0``, no more than *n* bytes will be read from the file; a partial
   line can be returned.  In both cases, an empty string is returned
   if the end of the file is reached immediately.  If *n* is less than
   ``0``, however, one line is read regardless of length, but
   ``EOFError`` is raised if the end of the file is reached
   immediately.

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)

   Write object *obj* to file object *p*.  The only supported flag for
   *flags* is ``Py_PRINT_RAW``; if given, the ``str()`` of the object
   is written instead of the ``repr()``.  Return ``0`` on success or
   ``-1`` on failure; the appropriate exception will be set.

int PyFile_WriteString(const char *s, PyObject *p)

   Write string *s* to file object *p*.  Return ``0`` on success or
   ``-1`` on failure; the appropriate exception will be set.
