Curl Object — PycURL 7.45.6 documentation (original) (raw)

class pycurl.Curl

Creates a new Curl Object which corresponds to aCURL 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 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:

value specifies the value to set the option to. Different options accept values of different types:

Python 2.x only:

c.setopt(pycurl.FOLLOWLOCATION, 1L)

Python 3.x only:

c.setopt(pycurl.URL, b"http://www.python.org/")

Python 2

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

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:

setopt can reset some options to their default value, performing the job ofpycurl.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 StringIO (Python 2) or BytesIO (Python 3) instance, then invokes performto perform the file transfer, then returns the value of the StringIO/BytesIO instance which is a str instance on Python 2 and bytes instance on Python 3. Errors during transfer raise pycurl.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 performto 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 performto 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 theCURLINFO_* 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 aspycurl.CONTENT_TYPE. Exceptions to this rule are as follows:

The type of return value depends on the option, as follows:

On Python 2, getinfo and getinfo_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 theCURLINFO_* 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 aspycurl.CONTENT_TYPE. Exceptions to this rule are as follows:

The type of return value depends on the option, as follows:

On Python 2, getinfo and getinfo_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, 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(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 and errstr_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 and bytes instance on Python 3. Unlike errstr_raw, errstr_rawallows reading libcurl error buffer in Python 3 when its contents is not valid in Python’s default encoding.

On Python 2, errstr and errstr_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/")