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.

The Curl object can be used as a context manager. Exiting the context calls close().

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 call super().__del__(), otherwise the handle is closed without running any Python callback.

closed

Whether this Curl object 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 the CURLOPT_ prefix is removed. For example, CURLOPT_URL is exposed in PycURL as pycurl.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 as pycurl.OPT_FILETIME

  • CURLOPT_CERTINFO is mapped as pycurl.OPT_CERTINFO

  • CURLOPT_COOKIELIST is mapped as pycurl.COOKIELIST and, as of PycURL 7.43.0.2, also as pycurl.OPT_COOKIELIST

  • CURLOPT_RTSP_CLIENT_CSEQ is mapped as pycurl.OPT_RTSP_CLIENT_CSEQ

  • CURLOPT_RTSP_REQUEST is mapped as pycurl.OPT_RTSP_REQUEST

  • CURLOPT_RTSP_SERVER_CSEQ is mapped as pycurl.OPT_RTSP_SERVER_CSEQ

  • CURLOPT_RTSP_SESSION_ID is mapped as pycurl.OPT_RTSP_SESSION_ID

  • CURLOPT_RTSP_STREAM_URI is mapped as pycurl.OPT_RTSP_STREAM_URI

  • CURLOPT_RTSP_TRANSPORT is mapped as pycurl.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 and booleans:

    c.setopt(pycurl.FOLLOWLOCATION, True)
    c.setopt(pycurl.FOLLOWLOCATION, 1)
    
  • Options specified as accepting strings by curl_easy_setopt accept bytes and str 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, b"http://www.python.org/")
    
  • Blob options, that is the *_BLOB options, accept the same values as string options, plus any object supporting the buffer protocol such as bytearray, memoryview or array.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, PROXYHEADER 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. 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. 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:

    import io
    b = io.BytesIO()
    c.setopt(pycurl.WRITEFUNCTION, b.write)
    

    The keyword-only use_memoryview argument is accepted for WRITEFUNCTION and HEADERFUNCTION (see Callbacks); passing it with any other option raises TypeError.

  • SHARE option accepts a CurlShare Object.

  • STDERR option 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.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(), 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() → 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 bytes instance. Errors during transfer raise pycurl.error exceptions just like in perform.

Use perform_rs to retrieve response body as a str.

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.

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) 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 unless perform has been called and finished.

option is a constant corresponding to one of the CURLINFO_* constants in libcurl. Most option constant names match the respective CURLINFO_* constant names with the CURLINFO_ prefix removed, for example CURLINFO_CONTENT_TYPE is accessible as pycurl.CONTENT_TYPE. Exceptions to this rule are as follows:

  • CURLINFO_FILETIME is mapped as pycurl.INFO_FILETIME

  • CURLINFO_COOKIELIST is mapped as pycurl.INFO_COOKIELIST

  • CURLINFO_CERTINFO is mapped as pycurl.INFO_CERTINFO

  • CURLINFO_RTSP_CLIENT_CSEQ is mapped as pycurl.INFO_RTSP_CLIENT_CSEQ

  • CURLINFO_RTSP_CSEQ_RECV is mapped as pycurl.INFO_RTSP_CSEQ_RECV

  • CURLINFO_RTSP_SERVER_CSEQ is mapped as pycurl.INFO_RTSP_SERVER_CSEQ

  • CURLINFO_RTSP_SESSION_ID is mapped as pycurl.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.