Curl() -> New Curl object
Creates a new Curl Object which corresponds to a CURL handle in libcurl. Curl objects automatically set CURLOPT_VERBOSE to 0, CURLOPT_NOPROGRESS to 1, provide a default CURLOPT_USERAGENT and setup CURLOPT_ERRORBUFFER to point to a private error buffer.
Implicitly calls pycurl.global_init() if the latter has not yet been called.
Curl objects have the following methods:
Close handle and end curl session.
Corresponds to curl_easy_cleanup in libcurl. This method is automatically called by pycurl when a Curl object no longer has any references to it, but can also be called explicitly.
Set curl session option. Corresponds to curl_easy_setopt in libcurl.
option specifies which option to set. PycURL defines constants corresponding to CURLOPT_* constants in libcurl, except that the CURLOPT_ prefix is removed. For example, CURLOPT_URL is exposed in PycURL as pycurl.URL. For convenience, CURLOPT_* constants are also exposed on the Curl objects themselves:
import pycurl
c = pycurl.Curl()
c.setopt(pycurl.URL, "http://www.python.org/")
# Same as:
c.setopt(c.URL, "http://www.python.org/")
In order to distinguish between similarly-named CURLOPT and CURLINFO constants, some have CURLOPT constants have OPT_ prefixes. These are OPT_FILETIME and OPT_CERTINFO. As an exception to the exception, COOKIELIST does not have an OPT_ prefix but the corresponding CURLINFO option is INFO_COOKIELIST.
value specifies the value to set the option to. Different options accept values of different types:
Options specified by curl_easy_setopt as accepting 1 or an integer value accept Python integers, long integers (on Python 2.x) and booleans:
c.setopt(pycurl.FOLLOWLOCATION, True)
c.setopt(pycurl.FOLLOWLOCATION, 1)
# Python 2.x only:
c.setopt(pycurl.FOLLOWLOCATION, 1L)
Options specified as accepting strings by curl_easy_setopt accept byte strings (str on Python 2, bytes on Python 3) and Unicode strings with ASCII code points only. For more information, please refer to String And Unicode Handling. Example:
c.setopt(pycurl.URL, "http://www.python.org/")
c.setopt(pycurl.URL, u"http://www.python.org/")
# Python 3.x only:
c.setopt(pycurl.URL, b"http://www.python.org/")
HTTP200ALIASES, HTTPHEADER, POSTQUOTE, PREQUOTE and QUOTE accept a list or tuple of strings. The same rules apply to these strings as do to string option values. Example:
c.setopt(pycurl.HTTPHEADER, ["Accept:"])
c.setopt(pycurl.HTTPHEADER, ("Accept:",))
READDATA accepts a file object or any Python object which has a read method. On Python 2, a file object will be passed directly to libcurl and may result in greater transfer efficiency, unless PycURL has been compiled with AVOID_STDIO option. On Python 3 and on Python 2 when the value is not a true file object, READDATA is emulated in PycURL via READFUNCTION. The file should generally be opened in binary mode. Example:
f = open('file.txt', 'rb')
c.setopt(c.READDATA, f)
WRITEDATA and WRITEHEADER accept a file object or any Python object which has a write method. On Python 2, a file object will be passed directly to libcurl and may result in greater transfer efficiency, unless PycURL has been compiled with AVOID_STDIO option. On Python 3 and on Python 2 when the value is not a true file object, WRITEDATA is emulated in PycURL via WRITEFUNCTION. The file should generally be opened in binary mode. Example:
f = open('/dev/null', 'wb')
c.setopt(c.WRITEDATA, f)
*FUNCTION options accept a function. Supported callbacks are documented in Callbacks. Example:
# Python 2
import StringIO
b = StringIO.StringIO()
c.setopt(pycurl.WRITEFUNCTION, b.write)
SHARE option accepts a CurlShare Object.
It is possible to set integer options - and only them - that PycURL does not know about by using the numeric value of the option constant directly. For example, pycurl.VERBOSE has the value 42, and may be set as follows:
c.setopt(42, 1)
setopt can reset an option to its default value, performing the job of pycurl.Curl.unsetopt(), if None is passed for the option value. The following two calls are equivalent:
c.setopt(c.URL, None) c.unsetopt(c.URL)
Raises TypeError when the option value is not of a type accepted by the respective option, and pycurl.error exception when libcurl rejects the option or its value.
Perform a file transfer.
Corresponds to curl_easy_perform in libcurl.
Raises pycurl.error exception upon failure.
Extract and return information from a curl session.
Corresponds to curl_easy_getinfo in libcurl, where option is the same as the CURLINFO_* constants in libcurl, except that the CURLINFO_ prefix has been removed. (See below for exceptions.) Result contains an integer, float or string, depending on which option is given. The getinfo method should not be called unless perform has been called and finished.
In order to distinguish between similarly-named CURLOPT and CURLINFO constants, some have OPT_ and INFO_ prefixes. These are INFO_FILETIME, OPT_FILETIME, INFO_COOKIELIST (but setopt uses COOKIELIST!), INFO_CERTINFO, and OPT_CERTINFO.
The value returned by getinfo(INFO_CERTINFO) is a list with one element per certificate in the chain, starting with the leaf; each element is a sequence of (key, value) tuples.
Example usage:
import pycurl
c = pycurl.Curl()
c.setopt(pycurl.URL, "http://sf.net")
c.setopt(pycurl.FOLLOWLOCATION, 1)
c.perform()
print c.getinfo(pycurl.HTTP_CODE), c.getinfo(pycurl.EFFECTIVE_URL)
...
--> 200 "http://sourceforge.net/"
Raises pycurl.error exception upon failure.
Reset all options set on curl handle to default values, but preserves live connections, session ID cache, DNS cache, cookies, and shares.
Corresponds to curl_easy_reset in libcurl.
Reset curl session option to its default value.
Only some curl options may be reset via this method.
libcurl does not provide a way to reset a single option to its default value; pycurl.Curl.reset() resets all options to their default values, otherwise pycurl.Curl.setopt() must be called with whatever value is the default. For convenience, PycURL provides this unsetopt method to reset some of the options to their default values.
Raises pycurl.error exception on failure.
c.unsetopt(option) is equivalent to c.setopt(option, None).
Pause or unpause a curl handle. Bitmask should be a value such as PAUSE_RECV or PAUSE_CONT.
Corresponds to curl_easy_pause in libcurl. The argument should be derived from the PAUSE_RECV, PAUSE_SEND, PAUSE_ALL and PAUSE_CONT constants.
Raises pycurl.error exception upon failure.
Return the internal libcurl error buffer of this handle as a string.
Return value is a str instance on all Python versions.