Curl Object¶
- class pycurl.Curl New Curl object¶
Creates a new Curl Object which corresponds to a
CURLhandle 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.The
Curlobject can be used as a context manager. Exiting the context callsclose().Example:
with pycurl.Curl() as c: # perform operations
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.
A subclass overriding
__del__must callsuper().__del__(), otherwise the handle is closed without running any Python callback.
- closed¶
Whether this
Curlobject has been closed.
- setopt(option, value, *, use_memoryview=False) 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_URLis 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_FILETIMEis mapped aspycurl.OPT_FILETIMECURLOPT_CERTINFOis mapped aspycurl.OPT_CERTINFOCURLOPT_COOKIELISTis mapped aspycurl.COOKIELISTand, as of PycURL 7.43.0.2, also aspycurl.OPT_COOKIELISTCURLOPT_RTSP_CLIENT_CSEQis mapped aspycurl.OPT_RTSP_CLIENT_CSEQCURLOPT_RTSP_REQUESTis mapped aspycurl.OPT_RTSP_REQUESTCURLOPT_RTSP_SERVER_CSEQis mapped aspycurl.OPT_RTSP_SERVER_CSEQCURLOPT_RTSP_SESSION_IDis mapped aspycurl.OPT_RTSP_SESSION_IDCURLOPT_RTSP_STREAM_URIis mapped aspycurl.OPT_RTSP_STREAM_URICURLOPT_RTSP_TRANSPORTis 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
1or an integer value accept Python integers and booleans:c.setopt(pycurl.FOLLOWLOCATION, True) c.setopt(pycurl.FOLLOWLOCATION, 1)
Options specified as accepting strings by
curl_easy_setoptacceptbytesandstrwith 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, b"http://www.python.org/")
Blob options, that is the
*_BLOBoptions, accept the same values as string options, plus any object supporting the buffer protocol such asbytearray,memoryvieworarray.array. The value is copied, so it does not have to be kept alive. Example:c.setopt(pycurl.SSLCERT_BLOB, memoryview(certificate))
HTTP200ALIASES,HTTPHEADER,POSTQUOTE,PREQUOTE,PROXYHEADERandQUOTEaccept 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:",))
READDATAaccepts a file object or any Python object which has areadmethod.READDATAis emulated in PycURL viaREADFUNCTION. The file should generally be opened in binary mode. Example:f = open('file.txt', 'rb') c.setopt(c.READDATA, f)
WRITEDATAandWRITEHEADERaccept a file object or any Python object which has awritemethod.WRITEDATAis emulated in PycURL viaWRITEFUNCTION. The file should generally be opened in binary mode. Example:f = open('/dev/null', 'wb') c.setopt(c.WRITEDATA, f)
*FUNCTIONoptions accept a function. Supported callbacks are documented in Callbacks. Example:import io b = io.BytesIO() c.setopt(pycurl.WRITEFUNCTION, b.write)
The keyword-only
use_memoryviewargument is accepted forWRITEFUNCTIONandHEADERFUNCTION(see Callbacks); passing it with any other option raisesTypeError.SHAREoption accepts a CurlShare Object.STDERRoption is not currently supported.
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.VERBOSEhas 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(), ifNoneis 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 BytesIO instance, then invokes perform to perform the file transfer, then returns the value of the BytesIO instance which is a
bytesinstance. Errors during transfer raisepycurl.errorexceptions just like in perform.Use perform_rs to retrieve response body as a
str.Raises
pycurl.errorexception upon failure.Added in version 7.43.0.2.
- perform_rs() response_body¶
Perform a file transfer and return response body as a string.
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 (
strinstance). Note: decoding happens after the transfer finishes, thus an encoding error implies the transfer/network operation succeeded.Any transfer errors raise
pycurl.errorexception, just like in perform.Use perform_rb to retrieve response body as a byte string (
bytesinstance) without attempting to decode it.Raises
pycurl.errorexception 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
getinfomethod should not be called unlessperformhas 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_TYPEis accessible aspycurl.CONTENT_TYPE. Exceptions to this rule are as follows:CURLINFO_FILETIMEis mapped aspycurl.INFO_FILETIMECURLINFO_COOKIELISTis mapped aspycurl.INFO_COOKIELISTCURLINFO_CERTINFOis mapped aspycurl.INFO_CERTINFOCURLINFO_RTSP_CLIENT_CSEQis mapped aspycurl.INFO_RTSP_CLIENT_CSEQCURLINFO_RTSP_CSEQ_RECVis mapped aspycurl.INFO_RTSP_CSEQ_RECVCURLINFO_RTSP_SERVER_CSEQis mapped aspycurl.INFO_RTSP_SERVER_CSEQCURLINFO_RTSP_SESSION_IDis 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
int.