PycURL 中文版官方文档

PycURL中文版官方文档pycurl—APythoninterfacetothecURLlibraryPycurl包是一个libcurl的Python接口.pycurl已经成功的在Python2.2到Python2.5版编译测试过了.Libcurl是一个支持FTP,FTPS,HTTP,HTTPS,GOPHER,TELNET,DICT,FILE和LDAP的客户端URL传输库.libcurl也支持HTTPS认证,HTTPPOST,HTTPPUT,FTP上传,代理,Cookies,基本身份验证,FTP文件断点继传,HTTP代理通道等等.Libcurl提供的所有功能都可以通过pycurl接口来使用.接下来的子章节概述怎么使用pycurl接口,并且假定已经知道了libcurl如何工作的.libcurl如何工作的更多信息,请参考curl库的web页面().ModuleFunctionalitypycurl.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()方法.用法举例:importpycurlpycurl.version'libcurl/7.12.3OpenSSL/0.9.7ezlib/1.2.2.1libidn/0.5.12'pycurl.version_info()-Tuple相对应的是libcurl中的curl_version_info()方法.返回一个序列信息就像liburl的curl_version_info()方法返回的curl_version_info_data结构化数据.用法举例:importpycurlpycurl.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()-Curlobject这个函数创建一个同libcurl中的CURL处理器相对应的Curl对象.Curl对象自动的设置CURLOPT_VERBOSE为0,CURLOPT_NOPROGRESS为1,提供一个默认的CURLOPT_USERAGENT和设置CURLOPT_ERRORBUFFER指向一个私有的错误缓冲区.pycurl.CurlMulti()-CurlMultiobject这个函数创建一个新的与libcurl中的CURLM处理器相对应的CurlMulti对象.pycurl.CurlShare()-CurlShareobject这个函数创建一个新的与libcurl中的CURLSH处理器相对应的CurlShare对象.CurlShare对象可以在Curl对象上传递SHARE选项参数SubsectionsCurlobjectsCurlMultiobjectsCurlShareobjectsCallbacksCurlObjectCurl对象具有以下方法: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,它可以是一个字符串,整型,长整型,文件对象,列表或是函数.用法举例:importpycurlc=pycurl.Curl()c.setopt(pycurl.URL,)c.setopt(pycurl.HTTPHEADER,[Accept:])importStringIOb=StringIO.StringIO()c.setopt(pycurl.WRITEFUNCTION,b.write)c.setopt(pycurl.FOLLOWLOCATION,1)c.setopt(pycurl.MAXREDIRS,5)c.perform()printb.getvalue()getinfo(option)-Result对应于libcurl中的curl_easy_getinfo方法,option同样使用libcurl中的CURLOPT_*常量来指定,只可惜CURLOPT_前缀现在已经被去掉了.Result包含一个整数,浮点数或字符串,这都信赖于给定的option.getinfo方法不能在perform方法未调用或完成之前进行调用.用法举例:errstr()-String返回这个处理器中内部libcurl错误缓冲区的字符串表示.CurlMultiObjectCurlMulti对象具有以下方法:close()-None对应于libcurl中的curl_multi_cleanup()方法.当CurlMulti对象不再被引用时pycurl会自动调用该方法,也可显示调用该方法.perform()-tupleofstatusandthenumberofactiveCurlobjects对应于libcurl中的curl_multi_perform()方法.add_handle(Curlobject)-None对应于libcurl中的curl_multi_add_handle()方法.这个方法添加一个有效的Curl对象到CurlMulti对象.重要提示:add_handle没有隐式的增加对Curl对象的引用(因而也没有增加Curl对象的引用次数)remove_handle(Curlobject)-None对应于libcurl中的curl_multi_remove_handle()方法.这个方法从CurlMulti对象中移除一个现有的Curl对象.重要提示:remove_handle不会隐式的移除Curl对象的引用(因而不会减少Curl对象的引用次数).fdset()-tripleoflistswithactivefiledescriptors,readable,writeable,exceptions.对应于libcurl中的curl_multi_fdset()方法.这个方法从CurlMulti对象中提取文件描述信息.返回的列表可以被用于select模块topollforevents.用法举例:importpycurlc=pycurl.Curl()c.setopt(pycurl.URL,)m=pycurl.CurlMulti()m.add_handle(c)while1:ret,num_handles=m.perform()ifret!=pycurl.E_CALL_MULTI_PERFORM:breakwhilenum_handles:apply(select.select,m.fdset()+(1,))while1:ret,num_handles=m.perform()ifret!=pycurl.E_CALL_MULTI_PERFORM:breakselect(timeout)-numberofreadyfiledescriptorsor-1ontimeout这是一个有用的函数,它简化了fdest()和select模块的组合使用.用法举例:importpycurlc=pycurl.Curl()c.setopt(pycurl.URL,)m=pycurl.CurlMulti()m.add_handle(c)while1:ret,num_handles=m.perform()ifret!=pycurl.E_CALL_MULTI_PERFORM:breakwhilenum_handles:ret=m.select(1.0)ifret==-1:continuewhile1:ret,num_handles=m.perform()ifret!=pycurl.E_CALL_MULTI_PERFORM:breakinfo_read([max])-numberofqueuedmessages,alistofsuccessfulobjects,alistoffailedobjects对应于libcurl中的curl_multi_info_read()方法.这个方法从多重栈中提取至多max个信息然后返回两个列表.第一个列表包含成功完成的操作第二个列表包含每一个失败的curl对象的curl对象,curl错误代码,curl错误信息序列CurlShareObjectCurlShare对象具有以下方法:setopt(option,value)-None对应于libcurl中的curl_share_setopt方法,option使用libcurl中的CURLOPT_*常量来指定,只可惜CURLOPT_前缀现在改成SH_了.通常value必须是LOCK_DATA_COOKIE或者说LOCK_DATA_DNS.用法举例:importpycurlcurl=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,')curl.setopt(pycurl.SHARE,s)curl.perform()curl.close()Callbacks为了更好的控制,libcurl允许把一些回调函数关联到每个连接中.在pycurl中,回调函数通过Curl对象调用setopt为sWRITEFUNCTION,READFUNCTION,HEADERFUNCTION,PROGRESSFUNCTION,IOCTLFUNCTION,或DEBUGFUNCTION这些选项设置.这些选项对应着libcurl中CURLOPT_*前缀被移除的选项.在pycurl中回调函数必须是一个正规的Python函数,或者一个类的方法或是一个扩展的函数类型.这儿有些局限性就是这些选项的回调函数有可能同时发生.它允许不同的回调函数对应到不同的Curl对象.更多明确的是,WRITEDATA的回调函数不能用于WRITEFUNCTION,READDATA的回调函数不能用于READFUNCTION,WRITEHEADER的回调函数不能用于HEADERFUNCTION,PROGRESSDATA回调函数不能用于PROGRESSFUNCTION,IOCTLDATA回调函数不能用于IOCTLFUNCTION,DEBUGDATA回调函数不能用于DEBUGFUNCTION.实际上,可以通过把一个类的实例方法来当作回调函数并且使用类实例属性像文件对象那样存储每