File Handling
=============

In PycURL 7.19.0.3 and below, ``CURLOPT_READDATA``, ``CURLOPT_WRITEDATA`` and
``CURLOPT_WRITEHEADER`` options accepted file objects and directly passed
the underlying C library ``FILE`` pointers to libcurl.

Python 3 no longer implements files as C library ``FILE`` objects.
In PycURL 7.19.3 and above, when running on Python 3, these options
are implemented as calls to ``CURLOPT_READFUNCTION``, ``CURLOPT_WRITEFUNCTION``
and ``CURLOPT_HEADERFUNCTION``, respectively, with the write method of the
Python file object as the parameter. As a result, any Python file-like
object implementing a ``read`` method can be passed to ``CURLOPT_READDATA``,
and any Python file-like object implementing a ``write`` method can be
passed to ``CURLOPT_WRITEDATA`` or ``CURLOPT_WRITEHEADER`` options.

Files given to PycURL as arguments to ``CURLOPT_READDATA``,
``CURLOPT_WRITEDATA`` or ``CURLOPT_WRITEHEADER`` must be opened for reading or
writing in binary mode. Files opened in text mode (without ``"b"`` flag to
``open()``) expect string objects and reading from or writing to them from
PycURL will fail. Similarly when passing ``f.write`` method of an open file to
``CURLOPT_WRITEFUNCTION`` or ``CURLOPT_HEADERFUNCTION``, or ``f.read`` to
``CURLOPT_READFUNCTION``, the file must have been be opened in binary mode.
