tornado中文文档

概览Overview下载和安装模块索引o主要模块o底层模块Tornado攻略o请求处理程序和请求参数o重写RequestHandler的方法函数o重定向(redirect)o模板oCookie和安全Cookieo用户认证o跨站伪造请求的防范o静态文件和主动式文件缓存o本地化oUI模块o非阻塞式异步请求o异步HTTP客户端o第三方认证o调试模式和自动重载性能生产环境下的部署WSGI和GoogleAppEngine注意事项和社区支持OverviewFriendFeed使用了一款使用Python编写的，相对简单的非阻塞式Web服务器。其应用程序使用的Web框架看起来有些像web.py或者Google的webapp，不过为了能有效利用非阻塞式服务器环境，这个Web框架还包含了一些相关的有用工具和优化。Tornado就是我们在FriendFeed的Web服务器及其常用工具的开源版本。Tornado和现在的主流Web服务器框架（包括大多数Python的框架）有着明显的区别：它是非阻塞式服务器，而且速度相当快。得利于其非阻塞的方式和对epoll的运用，Tornado每秒可以处理数以千计的连接，因此Tornado是实时Web服务的一个理想框架。我们开发这个Web服务器的主要目的就是为了处理FriendFeed的实时功能——在FriendFeed的应用里每一个活动用户都会保持着一个服务器连接。（关于如何扩容服务器，以处理数以千计的客户端的连接的问题，请参阅TheC10Kproblem）以下是经典的“Hello,world”示例：importtornado.ioloopimporttornado.webclassMainHandler(tornado.web.RequestHandler):defget(self):self.write(Hello,world)application=tornado.web.Application([(r/,MainHandler),])if__name__==__main__:application.listen(8888)tornado.ioloop.IOLoop.instance().start()查看下面的Tornado攻略以了解更多关于tornado.web包的细节。我们清理了Tornado的基础代码，减少了各模块之间的相互依存关系，所以理论上讲，你可以在自己的项目中独立地使用任何模块，而不需要使用整个包。下载和安装自动安装：Tornado已经列入PyPI，因此可以通过pip或者easy_install来安装。如果你没有安装libcurl的话，你需要将其单独安装到系统中。请参见下面的安装依赖一节。注意一点，使用pip或easy_install安装的Tornado并没有包含源代码中的demo程序。手动安装：下载tornado-1.2.1.tar.gztarxvzftornado-1.2.1.tar.gzcdtornado-1.2.1pythonsetup.pybuildsudopythonsetup.pyinstallTornado的代码托管在GitHub上面。对于Python2.6以上的版本，因为标准库中已经包括了对epoll的支持，所以你可以不用setup.py编译安装，只要简单地将tornado的目录添加到PYTHONPATH就可以使用了。安装需求Tornado在Python2.5,2.6,2.7中都经过了测试。要使用Tornado的所有功能，你需要安装PycURL(7.18.2或更高版本)以及simplejson(仅适用于Python2.5，2.6以后的版本标准库当中已经包含了对JSON的支持)。为方便起见，下面将列出MacOSX和Ubuntu中的完整安装方式：MacOSX10.6(Python2.6+)sudoeasy_installsetuptoolspycurlUbuntuLinux(Python2.6+)sudoapt-getinstallpython-pycurlUbuntuLinux(Python2.5)sudoapt-getinstallpython-devpython-pycurlpython-simplejson模块索引最重要的一个模块是web，它就是包含了Tornado的大部分主要功能的Web框架。其它的模块都是工具性质的，以便让web模块更加有用后面的Tornado攻略详细讲解了web模块的使用方法。主要模块web-FriendFeed使用的基础Web框架，包含了Tornado的大多数重要的功能escape-XHTML,JSON,URL的编码/解码方法database-对MySQLdb的简单封装，使其更容易使用template-基于Python的web模板系统httpclient-非阻塞式HTTP客户端，它被设计用来和web及httpserver协同工作auth-第三方认证的实现（包括GoogleOpenID/OAuth、FacebookPlatform、YahooBBAuth、FriendFeedOpenID/OAuth、TwitterOAuth）locale-针对本地化和翻译的支持options-命令行和配置文件解析工具，针对服务器环境做了优化底层模块httpserver-服务于web模块的一个非常简单的HTTP服务器的实现iostream-对非阻塞式的socket的简单封装，以方便常用读写操作ioloop-核心的I/O循环Tornado攻略请求处理程序和请求参数Tornado的Web程序会将URL或者URL范式映射到tornado.web.RequestHandler的子类上去。在其子类中定义了get()或post()方法，用以处理不同的HTTP请求。下面的代码将URL根目录/映射到MainHandler，还将一个URL范式/story/([0-9]+)映射到StoryHandler。正则表达式匹配的分组会作为参数引入的相应方法中：classMainHandler(tornado.web.RequestHandler):defget(self):self.write(Yourequestedthemainpage)classStoryHandler(tornado.web.RequestHandler):defget(self,story_id):self.write(Yourequestedthestory+story_id)application=tornado.web.Application([(r/,MainHandler),(r/story/([0-9]+),StoryHandler),])你可以使用get_argument()方法来获取查询字符串参数，以及解析POST的内容：classMainHandler(tornado.web.RequestHandler):defget(self):self.write('htmlbodyformaction=/method=post''inputtype=textname=message''inputtype=submitvalue=Submit''/form/body/html')defpost(self):self.set_header(Content-Type,text/plain)self.write(Youwrote+self.get_argument(message))上传的文件可以通过self.request.files访问到，该对象将名称（HTML元素inputtype=file的name属性）对应到一个文件列表。每一个文件都以字典的形式存在，其格式为{filename:...,content_type:...,body:...}。如果你想要返回一个错误信息给客户端，例如“403unauthorized”，只需要抛出一个tornado.web.HTTPError异常：ifnotself.user_is_logged_in():raisetornado.web.HTTPError(403)请求处理程序可以通过self.request访问到代表当前请求的对象。该HTTPRequest对象包含了一些有用的属性，包括：arguments-所有的GET或POST的参数files-所有通过multipart/form-dataPOST请求上传的文件path-请求的路径（?之前的所有内容）headers-请求的开头信息你可以通过查看源代码httpserver模组中HTTPRequest的定义，从而了解到它的所有属性。重写RequestHandler的方法函数除了get()/post()等以外，RequestHandler中的一些别的方法函数，这都是一些空函数，它们存在的目的是在必要时在子类中重新定义其内容。对于一个请求的处理的代码调用次序如下：1.程序为每一个请求创建一个RequestHandler对象2.程序调用initialize()函数，这个函数的参数是Application配置中的关键字参数定义。（initialize方法是Tornado1.1中新添加的，旧版本中你需要重写__init__以达到同样的目的）initialize方法一般只是把传入的参数存到成员变量中，而不会产生一些输出或者调用像send_error之类的方法。3.程序调用prepare()。无论使用了哪种HTTP方法，prepare都会被调用到，因此这个方法通常会被定义在一个基类中，然后在子类中重用。prepare可以产生输出信息。如果它调用了finish（或send_error`等函数），那么整个处理流程就此结束。4.程序调用某个HTTP方法：例如get()、post()、put()等。如果URL的正则表达式模式中有分组匹配，那么相关匹配会作为参数传入方法。下面是一个示范initialize()方法的例子：classProfileHandler(RequestHandler):definitialize(self,database):self.database=databasedefget(self,username):...app=Application([(r'/user/(.*)',ProfileHandler,dict(database=database)),])其它设计用来被复写的方法有：get_error_html(self,status_code,exception=None,**kwargs)-以字符串的形式返回HTML，以供错误页面使用。get_current_user(self)-查看下面的用户认证一节get_user_locale(self)-返回locale对象，以供当前用户使用。get_login_url(self)-返回登录网址，以供@authenticated装饰器使用（默认位置在Application设置中）get_template_path(self)-返回模板文件的路径（默认是Application中的设置）重定向(redirect)Tornado中的重定向有两种主要方法：self.redirect，或者使用RedirectHandler。你可以在使用RequestHandler（例如get）的方法中使用self.redirect，将用户重定向到别的地方。另外还有一个可选参数permanent，你可以用它指定这次操作为永久性重定向。该参数会激发一个301MovedPermanentlyHTTP状态，这在某些情况下是有用的，例如，你要将页面的原始链接重定向时，这种方式会更有利于搜索引擎优化（SEO）。permanent的默认值是False，这是为了适用于常见的操作，例如用户端在成功发送POST请求以后的重定向。self.redirect('/some-canonical-page',permanen