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.

When running PycURL 7.19.3 and above on Python 2, the old behavior of passing FILE pointers to libcurl remains when a true file object is given to CURLOPT_READDATA, CURLOPT_WRITEDATA and CURLOPT_WRITEHEADER options. For consistency with Python 3 behavior these options also accept file-like objects implementing a read or write method, as appropriate, as arguments, in which case the Python 3 code path is used converting these options to CURLOPT_*FUNCTION option calls.

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.