pycurl — A Python interface to the cURL library
Pycurl包是一個libcurl的Python接口.pycurl已經成功的在Python2.2到Python2.5版編譯測試過了.
Libcurl是一個支持FTP, FTPS, HTTP, HTTPS, GOPHER, TELNET, DICT, FILE 和 LDAP的客戶端URL傳輸庫.libcurl也支持HTTPS認證,HTTP POST,HTTP PUT,FTP上傳,代理,Cookies,基本身份驗證,FTP文件斷點繼傳,HTTP代理通道等等.
Libcurl提供的所有功能都可以通過pycurl接口來使用.接下來的子章節概述怎麼使用pycurl接口,並且假定已經知道了libcurl如何工作的.libcurl如何工作的更多信息,請參考curl庫的web頁面(http://curl.haxx.se/libcurl/c/).
Module Functionality
pycurl.global_init(option) ->None
選項是以下常量之一:pycurl.GLOBAL_SSL, pycurl.GLOBAL_WIN32, pycurl.GLOBAL_ALL, pycurl.GLOBAL_NOTHING, pycurl.GLOBAL_DEFAULT. 相應的是libcurl的 curl_global_init() 方法.
pycurl.global_cleanup() -> None
相應的是libcurl的curl_global_cleanup()方法.
pycurl.version
這是liburl當前版本的信息,相應的是liburl的curl_version()方法.
用法舉例:
>>> import pycurl
>>> pycurl.version
'libcurl/7.12.3 OpenSSL/0.9.7e zlib/1.2.2.1 libidn/0.5.12'
pycurl.version_info() -> Tuple
相對應的是libcurl中的 curl_version_info() 方法. 返回一個序列信息就像liburl的curl_version_info()方法返回的 curl_version_info_data 結構化數據.
用法舉例:
>>> import pycurl
>>> pycurl.version_info()
(2, '7.12.3', 461827, 'i586-pc-linux-gnu', 1565, 'OpenSSL/0.9.7e', 9465951,
'1.2.2.1', ('ftp', 'gopher', 'telnet', 'dict', 'ldap', 'http', 'file',
'https', 'ftps'), None, 0, '0.5.12')
pycurl.Curl() -> Curl object
這個函數創建一個同libcurl中的CURL處理器相對應的Curl對象.Curl對象自動的設置CURLOPT_VERBOSE爲0, CURLOPT_NOPROGRESS爲1,提供一個默認的CURLOPT_USERAGENT和設置CURLOPT_ERRORBUFFER指向一個私有的錯誤緩衝區.
pycurl.CurlMulti() -> CurlMulti object
這個函數創建一個新的與libcurl中的CURLM處理器相對應的CurlMulti對象.
pycurl.CurlShare() -> CurlShare object
這個函數創建一個新的與libcurl中的CURLSH處理器相對應的CurlShare對象.CurlShare對象可以在Curl對象上傳遞SHARE選項參數
Subsections
Curl Object
Curl對象具有以下方法:
close() -> None
對應的是libcurl中的curl_easy_cleanup方法.當Curl對象不再被引用時pycurl會自動調用這個方法,但也可直接地調用這個方法.
perform() -> None
對應於libcurl中的curl_easy_perform方法.
setopt(option, value) -> None
對應於libcurl中的curl_easy_setopt方法, option使用libcurl中的CURLOPT_*常量來指定,只可惜CURLOPT_前綴現在已經被去掉了.value的數據類型依賴於option,它可以是一個字符串,整型,長整型,文件對象,列表或是函數.
用法舉例:
import pycurl
c = pycurl.Curl()
c.setopt(pycurl.URL, "http://www.python.org/")
c.setopt(pycurl.HTTPHEADER, ["Accept:"])
import StringIO
b = StringIO.StringIO()
c.setopt(pycurl.WRITEFUNCTION, b.write)
c.setopt(pycurl.FOLLOWLOCATION, 1)
c.setopt(pycurl.MAXREDIRS, 5)
c.perform()
print b.getvalue()
getinfo(option) -> Result
對應於libcurl中的curl_easy_getinfo方法, option同樣使用libcurl中的CURLOPT_*常量來指定,只可惜CURLOPT_前綴現在已經被去掉了. Result包含一個整數,浮點數或字符串,這都信賴於給定的option.getinfo方法不能在perform方法未調用或完成之前進行調用.
用法舉例:
errstr() -> String
返回這個處理器中內部libcurl錯誤緩衝區的字符串表示.
CurlMulti Object
CurlMulti對象具有以下方法:
close() -> None
對應於libcurl中的curl_multi_cleanup()方法.當CurlMulti對象不再被引用時pycurl會自動調用該方法,也可顯示調用該方法.
perform() -> tuple of status and the number of active Curl objects
對應於libcurl中的curl_multi_perform()方法.
add_handle(Curl object) -> None
對應於libcurl中的curl_multi_add_handle()方法.這個方法添加一個有效的Curl對象到CurlMulti對象.
重要提示:add_handle沒有隱式的增加對Curl對象的引用(因而也沒有增加Curl對象的引用次數)
remove_handle(Curl object) -> None
對應於libcurl中的curl_multi_remove_handle()方法.這個方法從CurlMulti對象中移除一個現有的Curl對象.
重要提示:remove_handle不會隱式的移除Curl對象的引用(因而不會減少Curl對象的引用次數).
fdset() -> triple of lists with active file descriptors, readable, writeable, exceptions.
對應於libcurl中的curl_multi_fdset()方法.這個方法從CurlMulti對象中提取文件描述信息.返回的列表可以被用於select模塊to poll for events.
用法舉例:
import pycurl
c = pycurl.Curl()
c.setopt(pycurl.URL, "http://curl.haxx.se")
m = pycurl.CurlMulti()
m.add_handle(c)
while 1:
ret, num_handles = m.perform()
if ret != pycurl.E_CALL_MULTI_PERFORM: break
while num_handles:
apply(select.select, m.fdset() + (1,))
while 1:
ret, num_handles = m.perform()
if ret != pycurl.E_CALL_MULTI_PERFORM: break
select(timeout) -> number of ready file descriptors or -1 on timeout
這是一個有用的函數,它簡化了fdest()和select模塊的組合使用.
用法舉例:
import pycurl
c = pycurl.Curl()
c.setopt(pycurl.URL, "http://curl.haxx.se")
m = pycurl.CurlMulti()
m.add_handle(c)
while 1:
ret, num_handles = m.perform()
if ret != pycurl.E_CALL_MULTI_PERFORM: break
while num_handles:
ret = m.select(1.0)
if ret == -1: continue
while 1:
ret, num_handles = m.perform()
if ret != pycurl.E_CALL_MULTI_PERFORM: break
info_read([max]) -> numberof queued messages, a list of successful objects, a list of failed objects
對應於libcurl中的curl_multi_info_read()方法.這個方法從多重棧中提取至多max個信息然後返回兩個列表.第一個列表包含成功完成的操作第二個列表包含每一個失敗的curl對象的<curl對象,curl錯誤代碼,curl錯誤信息>序列
CurlShare Object
CurlShare對象具有以下方法:
setopt(option, value) -> None
對應於libcurl中的curl_share_setopt方法, option使用libcurl中的CURLOPT_*常量來指定,只可惜CURLOPT_前綴現在改成SH_了.通常value必須是LOCK_DATA_COOKIE 或者說LOCK_DATA_DNS.
用法舉例:
import pycurl
curl = pycurl.Curl()
s = pycurl.CurlShare()
s.setopt(pycurl.SH_SHARE, pycurl.LOCK_DATA_COOKIE)
s.setopt(pycurl.SH_SHARE, pycurl.LOCK_DATA_DNS)
curl.setopt(pycurl.URL, 'http://curl.haxx.se')
curl.setopt(pycurl.SHARE, s)
curl.perform()
curl.close()
Callbacks
爲了更好的控制,libcurl允許把一些回調函數關聯到每個連接中.在pycurl中,回調函數通過Curl對象調用setopt爲s WRITEFUNCTION, READFUNCTION, HEADERFUNCTION, PROGRESSFUNCTION, IOCTLFUNCTION, 或DEBUGFUNCTION這些選項設置.這些選項對應着libcurl中CURLOPT_*前綴被移除的選項.在pycurl中回調函數必須是一個正規的Python函數,或者一個類的方法或是一個擴展的函數類型.
這兒有些侷限性就是這些選項的回調函數有可能同時發生.它允許不同的回調函數對應到不同的Curl對象.更多明確的是,WRITEDATA的回調函數不能用於WRITEFUNCTION,READDATA的回調函數不能用於READFUNCTION,WRITEHEADER的回調函數不能用於HEADERFUNCTION,PROGRESSDATA回調函數不能用於PROGRESSFUNCTION,IOCTLDATA回調函數不能用於IOCTLFUNCTION,DEBUGDATA回調函數不能用於DEBUGFUNCTION.實際上,可以通過把一個類的實例方法來當作回調函數並且使用類實例屬性像文件對象那樣存儲每個對象的數據來克服這種侷限性.
Pycurl中的每個回調函數的簽名如下:
WRITEFUNCTION(string) -> number of characters written
READFUNCTION(number of characters to read)-> string
HEADERFUNCTION(string) -> number of characters written
PROGRESSFUNCTION(download total, downloaded, upload total, uploaded) -> status
DEBUGFUNCTION(debug message type, debug message string) -> None
IOCTLFUNCTION(ioctl cmd) -> status
Example: Callbacks for document header and body
這個例子打印頭數據到stderr打印內容數據到stdout.同樣注意它們都不返回寫入的字節數. WRITEFUNCTION和HEADERFUNCTION回調,寫入所有字節時返回None.
## Callback function invoked when body data is ready
def body(buf):
# Print body data to stdout
import sys
sys.stdout.write(buf)
# Returning None implies that all bytes were written
## Callback function invoked when header data is ready
def header(buf):
# Print header data to stderr
import sys
sys.stderr.write(buf)
# Returning None implies that all bytes were written
c = pycurl.Curl()
c.setopt(pycurl.URL, "http://www.python.org/")
c.setopt(pycurl.WRITEFUNCTION, body)
c.setopt(pycurl.HEADERFUNCTION, header)
c.perform()
Example: Download/upload progress callback
這個例子演示如何使用進度回調.當下載一個文檔時,uploads參數都將是0,反之亦然.
## Callback function invoked when download/upload has progress
def progress(download_t, download_d, upload_t, upload_d):
print "Total to download", download_t
print "Total downloaded", download_d
print "Total to upload", upload_t
print "Total uploaded", upload_d
c.setopt(c.URL, "http://slashdot.org/")
c.setopt(c.NOPROGRESS, 0)
c.setopt(c.PROGRESSFUNCTION, progress)
c.perform()
Example: Debug callbacks
這個例子演示如何使用調試回調.調試信息類型是一個調試信息的整數標示類型.在這個回調被調用時VERBOSE選項必須可用.
def test(debug_type, debug_msg):
print "debug(%d): %s" % (debug_type, debug_msg)
c = pycurl.Curl()
c.setopt(pycurl.URL, "http://curl.haxx.se/")
c.setopt(pycurl.VERBOSE, 1)
c.setopt(pycurl.DEBUGFUNCTION, test)
c.perform()
Other examples
Pycrul也包含一些用於演示如何在libcurl中使用不同的回調的測試腳本和事例.例如,文件examples/file_upload.py包含如何使用READFUNCTION的事例代碼, 'tests/test_cb.py'演示WRITEFUNCTION和HEADERFUNCTION, 'tests/test_debug.py'演示DEBUGFUNCTION, 'tests/test_getinfo.py'演示PROGRESSFUNCTION.
