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 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 指定要将该选项设置为的值。不同的选项接受不同类型的值:
由指定的选项 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,这可能会提高传输效率,除非已使用编译了PycURLAVOID_STDIO
选择。在Python3和Python2上当值不是真正的文件对象时,READDATA
在PycURL中通过以下方式模拟READFUNCTION
。该文件通常应以二进制模式打开。示例::f = open('file.txt', 'rb') c.setopt(c.READDATA, f)
WRITEDATA
和WRITEHEADER
接受文件对象或任何具有write
方法。在Python2上,文件对象将直接传递给libcurl,这可能会提高传输效率,除非已使用编译了PycURLAVOID_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 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
返回值的类型取决于选项,如下所示:
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 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
返回值的类型取决于选项,如下所示:
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/")