Curl物体¶

class pycurl.Curl¶

创建一个新的 Curl物体它对应于一个 CURL Libcurl中的句柄。CURL对象自动将CURLOPT_VERBOSE设置为0，将CURLOPT_NOPROGRESS设置为1，提供默认的CURLOPT_USERAGENT并将CURLOPT_ERRORBUFFER设置为指向专用错误缓冲区。

隐式调用 pycurl.global_init() 如果后者还没有被调用的话。

Curl对象具有以下方法：

close() → None¶

关闭手柄并结束Curl会话。

对应于 curl_easy_cleanup 在libcurl。当Curl对象不再具有对它的任何引用时，此方法由pycurl自动调用，但也可以显式调用。

setopt(option, value) → None¶

设置cURL会话选项。对应于 curl_easy_setopt 在libcurl。

option 指定要设置的选项。PycURL定义了与 CURLOPT_* Libcurl中的常量，除了 CURLOPT_ 前缀已删除。例如, CURLOPT_URL 在PycURL中公开为 pycurl.URL ，但有一些例外情况如下所述。为了方便起见， CURLOPT_* 常量也在Curl对象本身上公开：：

import pycurl
c = pycurl.Curl()
c.setopt(pycurl.URL, "http://www.python.org/")
# Same as:
c.setopt(c.URL, "http://www.python.org/")

以下是选项常量命名约定的例外：

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 指定要将该选项设置为的值。不同的选项接受不同类型的值：

由指定的选项 curl_easy_setopt 作为接受 1 或一个整数值，接受Python整数、长整型(在Python2.x上)和布尔值：

c.setopt(pycurl.FOLLOWLOCATION, True)
c.setopt(pycurl.FOLLOWLOCATION, 1)
# Python 2.x only:
c.setopt(pycurl.FOLLOWLOCATION, 1L)

指定为接受字符串的选项 curl_easy_setopt 接受字节字符串 (str 在Python2上， bytes 在Python3上)和仅具有ASCII代码点的Unicode字符串。有关更多信息，请参阅字符串和Unicode处理。示例：：
```
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 和 QUOTE 接受字符串的列表或元组。适用于这些字符串的规则与适用于字符串选项值的规则相同。示例：：
```
c.setopt(pycurl.HTTPHEADER, ["Accept:"])
c.setopt(pycurl.HTTPHEADER, ("Accept:",))
```
READDATA 接受文件对象或任何具有 read 方法。在Python2上，文件对象将直接传递给libcurl，这可能会提高传输效率，除非已使用编译了PycURL AVOID_STDIO 选择。在Python3和Python2上当值不是真正的文件对象时， READDATA 在PycURL中通过以下方式模拟 READFUNCTION 。该文件通常应以二进制模式打开。示例：：
```
f = open('file.txt', 'rb')
c.setopt(c.READDATA, f)
```
WRITEDATA 和 WRITEHEADER 接受文件对象或任何具有 write 方法。在Python2上，文件对象将直接传递给libcurl，这可能会提高传输效率，除非已使用编译了PycURL AVOID_STDIO 选择。在Python3和Python2上当值不是真正的文件对象时， WRITEDATA 在PycURL中通过以下方式模拟 WRITEFUNCTION 。该文件通常应以二进制模式打开。示例：：
```
f = open('/dev/null', 'wb')
c.setopt(c.WRITEDATA, f)
```

*FUNCTION 选项接受一个函数。支持的回调记录在回调。示例：：

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

SHARE 选项接受一个 curlshare对象。

可以通过直接使用OPTION常量的数值来设置PycURL不知道的整数选项--并且只能设置它们。例如, pycurl.VERBOSE 值为42，可设置如下：

c.setopt(42, 1)

setopt 可以将某些选项重置为其缺省值，执行以下工作 pycurl.Curl.unsetopt() ，如果 None 是为选项值传递的。以下两个呼叫等效：

c.setopt(c.URL, None)
c.unsetopt(c.URL)

当选项值不是相应选项接受的类型时引发TypeError，当libcurl拒绝该选项或其值时引发pycurl.error异常。

perform() → None¶

执行文件传输。

对应于 curl_easy_perform 在libcurl。

失败时引发pycurl.error异常。

perform_rb() → response_body¶

执行文件传输并以字节字符串形式返回响应正文。

此方法安排将响应正文保存在StringIO(Python2)或BytesIO(Python3)实例中，然后调用 perform 要执行文件传输，则返回StringIO/BytesIO实例的值，该值是 str 实例，并安装在 bytes 实例。传输提升过程中出错 pycurl.error 与中类似的例外情况 perform 。

使用 perform_rs 以字符串形式检索响应正文 (str 实例)。

加薪 pycurl.error 失败时出现异常。

Added in version 7.43.0.2.

perform_rs() → response_body¶

执行文件传输并以字符串形式返回响应正文。

在Python2上，此方法安排将响应体保存在StringIO实例中，然后调用 perform 执行文件传输，然后返回StringIO实例的值。此行为与 perform_rb 。

在Python3上，此方法安排将响应体保存在BytesIO实例中，然后调用 perform 执行文件传输，然后以Python的默认编码对响应正文进行解码，并以Unicode字符串的形式返回已解码的正文 (str 实例)。 Note: 解码是在传输完成后进行的，因此编码错误意味着传输/网络操作成功。

任何传输错误都会引发 pycurl.error 异常，就像在 perform 。

使用 perform_rb 以字节字符串的形式检索响应正文 (bytes 实例)，而不尝试对其进行解码。

加薪 pycurl.error 失败时出现异常。

Added in version 7.43.0.2.

getinfo(option) → Result¶

从cURL会话中提取并返回信息，在调用时使用Python的默认编码对字符串数据进行解码。对应于 curl_easy_getinfo 在libcurl。这个 getinfo 方法不应被调用，除非 perform 已被调用并完成。

option 是一个常数，与 CURLINFO_* Libcurl中的常量。大多数选项常量名称与各自的 CURLINFO_* 属性的常量名称 CURLINFO_ 前缀已删除，例如 CURLINFO_CONTENT_TYPE 可以通过以下方式访问 pycurl.CONTENT_TYPE 。该规则的例外情况如下：

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

返回值的类型取决于选项，如下所示：

Libcurl记录的用于返回整数值的选项返回一个Python整数 (long 在Python2上， int 在Python3上)。
Libcurl记录的用于返回浮点值的选项返回一个Python float 。
Libcurl记录的用于返回字符串值的选项返回一个Python字符串 (str 在Python2和Python3上)。在Python2上，该字符串包含libcurl返回的任何数据。在Python3上，libcurl返回的数据在调用时使用默认字符串编码进行解码。如果不能使用默认编码对数据进行解码， UnicodeDecodeError 都被养大了。使用 getinfo_raw 要将数据检索为 bytes 在这种情况下。
SSL_ENGINES 和 INFO_COOKIELIST 返回字符串列表。同样的编码注意事项也适用；使用 getinfo_raw 以字节字符串列表的形式检索数据。
INFO_CERTINFO 返回一个列表，其中链中的每个证书都有一个元素，从叶子开始；每个元素都是 (key, value) 元组，其中既有 key 和 value 都是琴弦。字符串编码注意事项适用；使用 getinfo_raw 以字节字符串的形式检索证书数据。

在Python2上， getinfo 和 getinfo_raw 举止要一致。

示例用法：：

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'), ...)]

失败时引发pycurl.error异常。

getinfo_raw(option) → Result¶

从cURL会话提取并返回信息，以字节字符串的形式返回字符串数据。对应于 curl_easy_getinfo 在libcurl。这个 getinfo_raw 方法不应被调用，除非 perform 已被调用并完成。

option 是一个常数，与 CURLINFO_* Libcurl中的常量。大多数选项常量名称与各自的 CURLINFO_* 属性的常量名称 CURLINFO_ 前缀已删除，例如 CURLINFO_CONTENT_TYPE 可以通过以下方式访问 pycurl.CONTENT_TYPE 。该规则的例外情况如下：

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

返回值的类型取决于选项，如下所示：

Libcurl记录的用于返回整数值的选项返回一个Python整数 (long 在Python2上， int 在Python3上)。
Libcurl记录的用于返回浮点值的选项返回一个Python float 。
Libcurl记录的用于返回字符串值的选项返回一个Python字节字符串 (str 在Python2上， bytes 在Python3上)。该字符串包含libcurl返回的任何数据。使用 getinfo 在Python3上以Unicode字符串的形式检索此数据。
SSL_ENGINES 和 INFO_COOKIELIST 返回字节字符串列表。同样的编码注意事项也适用；使用 getinfo 将数据作为可能的Unicode字符串的列表进行检索。
INFO_CERTINFO 返回一个列表，其中链中的每个证书都有一个元素，从叶子开始；每个元素都是 (key, value) 元组，其中既有 key 和 value 是字节字符串。字符串编码注意事项适用；使用 getinfo 将证书数据作为可能的Unicode字符串进行检索。

在Python2上， getinfo 和 getinfo_raw 举止要一致。

示例用法：：

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'), ...)]

失败时引发pycurl.error异常。

Added in version 7.43.0.2.

reset() → None¶

将在cURL句柄上设置的所有选项重置为默认值，但保留活动连接、会话ID缓存、DNS缓存、Cookie和共享。

对应于 curl_easy_reset 在libcurl。

unsetopt(option) → None¶

将cURL会话选项重置为其缺省值。

只有某些Curl选项可以通过此方法重置。

Libcurl没有提供将单个选项重置为其缺省值的通用方法； pycurl.Curl.reset() 将所有选项重置为其缺省值，否则为 pycurl.Curl.setopt() 必须使用任何默认值调用。为方便起见，PycURL提供了这个unsetopt方法来将一些选项重置为其缺省值。

在失败时引发pycurl.error异常。

c.unsetopt(option) 相当于 c.setopt(option, None) 。

pause(bitmask) → None¶

暂停或取消暂停Curl手柄。位掩码应该是一个值，例如PAUSE_RECV或PAUSE_CONT。

对应于 curl_easy_pause 在libcurl。参数应派生自 PAUSE_RECV ， PAUSE_SEND ， PAUSE_ALL 和 PAUSE_CONT 常量。

失败时引发pycurl.error异常。

errstr() → string¶

以字符串形式返回该句柄的内部libcurl错误缓冲区。

返回值为 str 实例在所有的Python版本上。在Python3上，错误缓冲区数据在调用时使用Python默认编码进行解码。如果这个解码失败了， UnicodeDecodeError 都被养大了。使用 errstr_raw 在本例中以字节字符串的形式检索错误缓冲区。

在Python2上， errstr 和 errstr_raw 举止要一致。

errstr_raw() → byte string¶

以字节字符串的形式返回该句柄的内部libcurl错误缓冲区。

返回值为 str 实例，并安装在 bytes 实例。不同于 errstr_raw ， errstr_raw 当其内容在Python默认编码中无效时，允许读取Python3中的libcurl错误缓冲区。

在Python2上， errstr 和 errstr_raw 举止要一致。

Added in version 7.43.0.2.

setopt_string(option, value) → None¶

将cURL会话选项设置为字符串值。

此方法允许设置PycURL不正式支持的字符串选项，例如，因为在发布所使用的PycURL版本时这些选项不存在。 pycurl.Curl.setopt() 应该用于设置PycURL已知的选项。

Warning: 未执行任何检查 option 实际上，确实需要字符串值。不正确地使用此方法可能会使程序崩溃，并可能导致安全漏洞。此外，在应用程序上还需要确保 value 对象在libcurl使用它时不会被垃圾回收。Libcurl复制大多数字符串选项，但不是全部；libcurl没有复制值的一个选项是 CURLOPT_POSTFIELDS 。

option 通常需要作为整型文字而不是符号常量给出。

value 可以是二进制字符串或使用ASCII代码点的Unicode字符串，与其他地方提供给PycURL的字符串选项相同。

示例通过设置URL setopt_string **

import pycurl
c = pycurl.Curl()
c.setopt_string(10002, "http://www.python.org/")

Curl物体¶

目录

上一主题

下一主题