Curl Object¶
-
class
pycurl.
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
() → None¶ 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.
-
setopt
(option, value) → None¶ 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 theCURLOPT_
prefix is removed. For example,CURLOPT_URL
is exposed in PycURL aspycurl.URL
, with some exceptions as detailed below. 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/")
The following are exceptions to option constant naming convention:
CURLOPT_FILETIME
is mapped aspycurl.OPT_FILETIME
CURLOPT_CERTINFO
is mapped aspycurl.OPT_CERTINFO
CURLOPT_COOKIELIST
is mapped aspycurl.COOKIELIST
and, as of PycURL 7.43.0.2, also aspycurl.OPT_COOKIELIST
CURLOPT_RTSP_CLIENT_CSEQ
is mapped aspycurl.OPT_RTSP_CLIENT_CSEQ
CURLOPT_RTSP_REQUEST
is mapped aspycurl.OPT_RTSP_REQUEST
CURLOPT_RTSP_SERVER_CSEQ
is mapped aspycurl.OPT_RTSP_SERVER_CSEQ
CURLOPT_RTSP_SESSION_ID
is mapped aspycurl.OPT_RTSP_SESSION_ID
CURLOPT_RTSP_STREAM_URI
is mapped aspycurl.OPT_RTSP_STREAM_URI
CURLOPT_RTSP_TRANSPORT
is mapped aspycurl.OPT_RTSP_TRANSPORT
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
,PROXYHEADER
andQUOTE
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 aread
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 withAVOID_STDIO
option. On Python 3 and on Python 2 when the value is not a true file object,READDATA
is emulated in PycURL viaREADFUNCTION
. The file should generally be opened in binary mode. Example:f = open('file.txt', 'rb') c.setopt(c.READDATA, f)
WRITEDATA
andWRITEHEADER
accept a file object or any Python object which has awrite
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 withAVOID_STDIO
option. On Python 3 and on Python 2 when the value is not a true file object,WRITEDATA
is emulated in PycURL viaWRITEFUNCTION
. 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 some options to their default value, performing the job of
pycurl.Curl.unsetopt()
, ifNone
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
() → None¶ Perform a file transfer.
Corresponds to curl_easy_perform in libcurl.
Raises pycurl.error exception upon failure.
-
perform_rb
() → response_body¶ Perform a file transfer and return response body as a byte string.
This method arranges for response body to be saved in a StringIO (Python 2) or BytesIO (Python 3) instance, then invokes perform to perform the file transfer, then returns the value of the StringIO/BytesIO instance which is a
str
instance on Python 2 andbytes
instance on Python 3. Errors during transfer raisepycurl.error
exceptions just like in perform.Use perform_rs to retrieve response body as a string (
str
instance on both Python 2 and 3).Raises
pycurl.error
exception upon failure.Added in version 7.43.0.2.
-
perform_rs
() → response_body¶ Perform a file transfer and return response body as a string.
On Python 2, this method arranges for response body to be saved in a StringIO instance, then invokes perform to perform the file transfer, then returns the value of the StringIO instance. This behavior is identical to perform_rb.
On Python 3, this method arranges for response body to be saved in a BytesIO instance, then invokes perform to perform the file transfer, then decodes the response body in Python’s default encoding and returns the decoded body as a Unicode string (
str
instance). Note: decoding happens after the transfer finishes, thus an encoding error implies the transfer/network operation succeeded.Any transfer errors raise
pycurl.error
exception, just like in perform.Use perform_rb to retrieve response body as a byte string (
bytes
instance on Python 3) without attempting to decode it.Raises
pycurl.error
exception upon failure.Added in version 7.43.0.2.
-
getinfo
(option) → Result¶ Extract and return information from a curl session, decoding string data in Python’s default encoding at the time of the call. Corresponds to curl_easy_getinfo in libcurl. The
getinfo
method should not be called unlessperform
has been called and finished.option is a constant corresponding to one of the
CURLINFO_*
constants in libcurl. Most option constant names match the respectiveCURLINFO_*
constant names with theCURLINFO_
prefix removed, for exampleCURLINFO_CONTENT_TYPE
is accessible aspycurl.CONTENT_TYPE
. Exceptions to this rule are as follows:CURLINFO_FILETIME
is mapped aspycurl.INFO_FILETIME
CURLINFO_COOKIELIST
is mapped aspycurl.INFO_COOKIELIST
CURLINFO_CERTINFO
is mapped aspycurl.INFO_CERTINFO
CURLINFO_RTSP_CLIENT_CSEQ
is mapped aspycurl.INFO_RTSP_CLIENT_CSEQ
CURLINFO_RTSP_CSEQ_RECV
is mapped aspycurl.INFO_RTSP_CSEQ_RECV
CURLINFO_RTSP_SERVER_CSEQ
is mapped aspycurl.INFO_RTSP_SERVER_CSEQ
CURLINFO_RTSP_SESSION_ID
is mapped aspycurl.INFO_RTSP_SESSION_ID
The type of return value depends on the option, as follows:
- Options documented by libcurl to return an integer value return a
Python integer (
long
on Python 2,int
on Python 3). - Options documented by libcurl to return a floating point value
return a Python
float
. - Options documented by libcurl to return a string value
return a Python string (
str
on Python 2 and Python 3). On Python 2, the string contains whatever data libcurl returned. On Python 3, the data returned by libcurl is decoded using the default string encoding at the time of the call. If the data cannot be decoded using the default encoding,UnicodeDecodeError
is raised. Use getinfo_raw to retrieve the data asbytes
in these cases. SSL_ENGINES
andINFO_COOKIELIST
return a list of strings. The same encoding caveats apply; use getinfo_raw to retrieve the data as a list of byte strings.INFO_CERTINFO
returns a list with one element per certificate in the chain, starting with the leaf; each element is a sequence of (key, value) tuples where bothkey
andvalue
are strings. String encoding caveats apply; use getinfo_raw to retrieve certificate data as byte strings.
On Python 2,
getinfo
andgetinfo_raw
behave identically.Example usage:
import pycurl c = pycurl.Curl() c.setopt(pycurl.OPT_CERTINFO, 1) c.setopt(pycurl.URL, "https://python.org") c.setopt(pycurl.FOLLOWLOCATION, 1) c.perform() print(c.getinfo(pycurl.HTTP_CODE)) # --> 200 print(c.getinfo(pycurl.EFFECTIVE_URL)) # --> "https://www.python.org/" certinfo = c.getinfo(pycurl.INFO_CERTINFO) print(certinfo) # --> [(('Subject', 'C = AU, ST = Some-State, O = PycURL test suite, CN = localhost'), ('Issuer', 'C = AU, ST = Some-State, O = PycURL test suite, OU = localhost, CN = localhost'), ('Version', '0'), ...)]
Raises pycurl.error exception upon failure.
-
getinfo_raw
(option) → Result¶ Extract and return information from a curl session, returning string data as byte strings. Corresponds to curl_easy_getinfo in libcurl. The
getinfo_raw
method should not be called unlessperform
has been called and finished.option is a constant corresponding to one of the
CURLINFO_*
constants in libcurl. Most option constant names match the respectiveCURLINFO_*
constant names with theCURLINFO_
prefix removed, for exampleCURLINFO_CONTENT_TYPE
is accessible aspycurl.CONTENT_TYPE
. Exceptions to this rule are as follows:CURLINFO_FILETIME
is mapped aspycurl.INFO_FILETIME
CURLINFO_COOKIELIST
is mapped aspycurl.INFO_COOKIELIST
CURLINFO_CERTINFO
is mapped aspycurl.INFO_CERTINFO
CURLINFO_RTSP_CLIENT_CSEQ
is mapped aspycurl.INFO_RTSP_CLIENT_CSEQ
CURLINFO_RTSP_CSEQ_RECV
is mapped aspycurl.INFO_RTSP_CSEQ_RECV
CURLINFO_RTSP_SERVER_CSEQ
is mapped aspycurl.INFO_RTSP_SERVER_CSEQ
CURLINFO_RTSP_SESSION_ID
is mapped aspycurl.INFO_RTSP_SESSION_ID
The type of return value depends on the option, as follows:
- Options documented by libcurl to return an integer value return a
Python integer (
long
on Python 2,int
on Python 3). - Options documented by libcurl to return a floating point value
return a Python
float
. - Options documented by libcurl to return a string value
return a Python byte string (
str
on Python 2,bytes
on Python 3). The string contains whatever data libcurl returned. Use getinfo to retrieve this data as a Unicode string on Python 3. SSL_ENGINES
andINFO_COOKIELIST
return a list of byte strings. The same encoding caveats apply; use getinfo to retrieve the data as a list of potentially Unicode strings.INFO_CERTINFO
returns a list with one element per certificate in the chain, starting with the leaf; each element is a sequence of (key, value) tuples where bothkey
andvalue
are byte strings. String encoding caveats apply; use getinfo to retrieve certificate data as potentially Unicode strings.
On Python 2,
getinfo
andgetinfo_raw
behave identically.Example usage:
import pycurl c = pycurl.Curl() c.setopt(pycurl.OPT_CERTINFO, 1) c.setopt(pycurl.URL, "https://python.org") c.setopt(pycurl.FOLLOWLOCATION, 1) c.perform() print(c.getinfo_raw(pycurl.HTTP_CODE)) # --> 200 print(c.getinfo_raw(pycurl.EFFECTIVE_URL)) # --> b"https://www.python.org/" certinfo = c.getinfo_raw(pycurl.INFO_CERTINFO) print(certinfo) # --> [((b'Subject', b'C = AU, ST = Some-State, O = PycURL test suite, CN = localhost'), (b'Issuer', b'C = AU, ST = Some-State, O = PycURL test suite, OU = localhost, CN = localhost'), (b'Version', b'0'), ...)]
Raises pycurl.error exception upon failure.
Added in version 7.43.0.2.
-
reset
() → None¶ 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.
-
unsetopt
(option) → None¶ Reset curl session option to its default value.
Only some curl options may be reset via this method.
libcurl does not provide a general way to reset a single option to its default value;
pycurl.Curl.reset()
resets all options to their default values, otherwisepycurl.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 toc.setopt(option, None)
.
-
pause
(bitmask) → 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
andPAUSE_CONT
constants.Raises pycurl.error exception upon failure.
-
errstr
() → string¶ Return the internal libcurl error buffer of this handle as a string.
Return value is a
str
instance on all Python versions. On Python 3, error buffer data is decoded using Python’s default encoding at the time of the call. If this decoding fails,UnicodeDecodeError
is raised. Use errstr_raw to retrieve the error buffer as a byte string in this case.On Python 2,
errstr
anderrstr_raw
behave identically.
-
errstr_raw
() → byte string¶ Return the internal libcurl error buffer of this handle as a byte string.
Return value is a
str
instance on Python 2 andbytes
instance on Python 3. Unlike errstr_raw,errstr_raw
allows reading libcurl error buffer in Python 3 when its contents is not valid in Python’s default encoding.On Python 2,
errstr
anderrstr_raw
behave identically.Added in version 7.43.0.2.
-
setopt_string
(option, value) → None¶ Set curl session option to a string value.
This method allows setting string options that are not officially supported by PycURL, for example because they did not exist when the version of PycURL being used was released.
pycurl.Curl.setopt()
should be used for setting options that PycURL knows about.Warning: No checking is performed that option does, in fact, expect a string value. Using this method incorrectly can crash the program and may lead to a security vulnerability. Furthermore, it is on the application to ensure that the value object does not get garbage collected while libcurl is using it. libcurl copies most string options but not all; one option whose value is not copied by libcurl is CURLOPT_POSTFIELDS.
option would generally need to be given as an integer literal rather than a symbolic constant.
value can be a binary string or a Unicode string using ASCII code points, same as with string options given to PycURL elsewhere.
Example setting URL via
setopt_string
:import pycurl c = pycurl.Curl() c.setopt_string(10002, "http://www.python.org/")
-