Python Tornado 说明文档

一、下载安装

>>自动安装:

Tornado在PypI上，可以通过pip或者easy_install自动安装，前提是服务器上已经安装了libcurl库，当用pip或者easy_install安装的时候，不会自动安装例子程序
>>手工安装：
原始下载地址(本站也提供1.2.1的下载，原始地址要翻墙）：

tar xvzf tornado-1.2.1.tar.gz
cd tornado-1.2.1
python setup.py build
sudo python setup.py install

T的源代码托管在GitHub上，如果开发环境是py2.6+，也可以简单的把tornado目录添加到py的环境变量PYTHONPATH 中，这样就不需要编译setup.py(也就是不用安装的意思），既然标准库已经包含了epoll的支持(since the standard library includes epoll support.)

>>安装条件：
T 在py2.5 2.6 2.7上进行过测试，如果要使用t的全部功能，必须安装PycURL（版本7.18.2 或者以上），对py2.5必须安装JSON支持组件，py2.6+以上的JSON支持已经在标准库内实现。下面是Mac OS X和Ubuntu的安装例子：
Mac OS X 10.6 (Python 2.6+)

sudo easy_install setuptools pycurl

Ubuntu Linux (Python 2.6+)

sudo apt-get install python-pycurl

Ubuntu Linux (Python 2.5)

sudo apt-get install python-dev python-pycurl python-simplejson

二、模块列表和简介：
最重要的模块是web模块，他作为web框架包含了Tornado 包内大部分的有用的东西（meat of Tornado ，这里暂且不知道是使用了大部分T的功能，还是说T的大部分功能在web中实现），其他的工具和模块让web变的更有用

主模块

web – 用来创建FriendFeed的web框架，他集成（混合）了大部分T的重要功能特征
escape – XHTML, JSON, and URL 编解码方法
database -对MySQLdb的简单封装，让mysql的使用更方便
template – 基于python的模板渲染语言
httpclient – 一个非阻塞http客户端，设计它用来和web和httpserver协同工作
auth – 第三方认证和认证方案的实现 (Google OpenID/OAuth, Facebook Platform, Yahoo BBAuth, FriendFeed OpenID/OAuth, Twitter OAuth)
locale – 本地化和翻译支持
options – 命令行和配置文件解析工具，为了webserver环境做了优化

底层模块

httpserver – A very simple HTTP server built on which web is built（这个没法翻译，容易翻译错，除非很了解）
iostream – A simple wrapper around non-blocking sockets to aide common reading and writing patterns
ioloop – Core I/O loop（也不敢翻译，怕误解）

随机模块：

s3server – 一个实现了Amazon S3接口的web服务器，基于本地文件存储

三、Tornado使用概览
一个T应用会把URL或者URL模式映射到tornado.web.RequestHandler的子类，这些子类定义get和set方法来处理对应URL的GET和POST请求。
瞎蒙的代码把根URL /映射到MainHandler，把用正则表达式表达的URL/story/([0-9]+映射到StoryHandler,正则表达式的查找分组会作为StoryHandler方法的参数穿进去

class MainHandler(tornado.web.RequestHandler):    def get(self):        self.write("You requested the main page") class StoryHandler(tornado.web.RequestHandler):    def get(self, story_id):        self.write("You requested the story " + story_id) application = tornado.web.Application([    (r"/", MainHandler),    (r"/story/([0-9]+)", StoryHandler),])

你可以使用get_argument方法来获取query参数或者接卸post主体：

class MainHandler(tornado.web.RequestHandler):    def get(self):        self.write('

'                   ''                   ''                   '

 ')     def post(self):        self.set_header("Content-Type", "text/plain")        self.write("You wrote " + self.get_argument("message"))

上传文件
上传文件在 self.request.files，他会把html的input 标签的名字映射到一组文件上，每个文件是一个字典，形式如：

{"filename":..., "content_type":..., "body":...}

如果你想给客户端发送一个错误消息，比如403未认证错误，你只需要抛出一个如下的异常：

if not self.user_is_logged_in():    raise tornado.web.HTTPError(403)

处理函数可以用过self.request来访问当前请求相关的对象，HTTPRequest对象包含了一些有用的属性：
arguments – 所有GET and POST 参数
files – 所有上传过来的文件 (via multipart/form-data POST requests)
path – 请求的路径，？之前的所有内容
headers – 请求的头

HTTPRequest完整的定义信息在httpserver 中

重载RequestHandler方法
除了get()/post()/etc，RequestHandler 其他一些特定的方法设计就是用来被子类在必要的时候覆盖掉，
当一个请求到来以后，下面是完整的流程步骤：
1，每个请求会创建一个RequestHandler 对象
2，调用initialize()，并且把Application 配置作为关键参数传进去，该函数一般仅仅是把传进来的参数保存
成成员变量，并不会产生任何输出，比如错误信息：send_error
3，调用prepare().这是基类中对所有子类可以分享的最有用的部分，以为他不关心当前请求的具体方法，该函数可能
产生输出，如果他调用finish 或者send_error，那么处理到此结束
4，如下的一种HTTP方法会被调用：get，post，put等等，如果有URL正则表达式查询分组，则作为参数传进去
下面是一个initialize方法示例：

class ProfileHandler(RequestHandler):

    def initialize(self, database):

        self.database = database

 

    def get(self, username):

        ...

 

app = Application([

    (r'/user/(.*)', ProfileHandler, dict(database=database)),

    ])

其他被设计可以覆盖的方法包括：
get_error_html(self, status_code, exception=None, **kwargs) – returns HTML (as a string) for use on error pages.
get_current_user(self) – see User Authentication below
get_user_locale(self) – returns locale object to use for the current user
get_login_url(self) – returns login url to be used by the @authenticated decorator (default is in Application settings)
get_template_path(self) – returns location of template files (default is in Application settings)

模板
你可以使用任何基于python的模板语言，但是T ships with 他自己的模板语言，这个模板语言相对其他的模板系统他非常的快而且更灵活，具体产看模板部分的文档以便得到更详细的的完整描述
一个T模板就是一个HTML或者其他的基于文本的文件，其中会用一些特定标签包住Python控制语法和
表达式：

      {{ title }}

       {% for item in items %}

       

• {{ escape(item) }}

{% end %}

假如你把上面的模板保存为template.html，然后放在和python脚本同一个目录下，你就可以用如下的方式
把该模板渲染输出：

class MainHandler(tornado.web.RequestHandler):

    def get(self):

        items = ["Item 1", "Item 2", "Item 3"]

        self.render("template.html", title="My title", items=items)

T模板支持控制语法和表达式，前者用{%%}包围，后者用{{}}包围，比如：

{% if len(items) > 2 %}
{{ items[0] }}

控制语句或多或少的的精确对应了python的语法，我们支持if for while 和try，所有的语法都用
{% end %}结束。我们同时使用extends和block语法支持模板的继承，在模板模块的文档中有详细介绍。

表达式可以是任何py表达式，包括函数调用，模板代码的执行环境的名字空间包含如下的对象和函数（
注意，这个列表只是针对RequestHandler.render ，render_string这两种模板渲染方法，如果你使用
模板模块在RequestHandler 之外进行渲染，所有的条目都不复有效）

escape: alias for tornado.escape.xhtml_escape
xhtml_escape: alias for tornado.escape.xhtml_escape
url_escape: alias for tornado.escape.url_escape
json_encode: alias for tornado.escape.json_encode
squeeze: alias for tornado.escape.squeeze
linkify: alias for tornado.escape.linkify
datetime: the Python datetime module
handler: the current RequestHandler object
request: alias for handler.request
current_user: alias for handler.current_user
locale: alias for handler.locale
_: alias for handler.locale.translate
static_url: alias for handler.static_url
xsrf_form_html: alias for handler.xsrf_form_html
reverse_url: alias for Application.reverse_url
All entries from the ui_methods and ui_modules Application settings
Any keyword arguments passed to render or render_string

如果你正在创建一个实际的应用程序，你可能会使用所有的T模板特征，尤其是模板的继承。具体请阅读
模板模块的文档（部分特征在UIModules中，他在web模块中实现）

表面之下，T模板会被直接翻译成Python。模板的所有表达式会拷贝到一个代表你模板的函数中，我们不会
试图妨碍模块语言中的任何事情。我们精确明白的创造他，以便提供更灵活的模板渲染系统，这也是很多
其他模板系统所做不到的。因此，如果你在模板的表达式中写一些随机（意：乱的）的东西，你会得到相应的python语法
错误

Cookie和安全cookie
你可以通过set_cookie 方法在用户的浏览器端设置cookie：

class MainHandler(tornado.web.RequestHandler):

    def get(self):

        if not self.get_cookie("mycookie"):

            self.set_cookie("mycookie", "myvalue")

            self.write("Your cookie was not set yet!")

        else:

            self.write("Your cookie was set!")

cookie很容易被恶意客户端伪造，假如你想保存当前登录用户的ID在cookie中，你必须给cookie签名以便
防止伪造。T通过set_secure_cookie 和get_secure_cookie 来支持。为了使用这两个方法，你必须在创建应用
程序的时候给变量cookie_secret 赋一个有效的值，你可以通过关键字参数的方式给应用程序传递过去：

application = tornado.web.Application([

    (r"/", MainHandler),

], cookie_secret="61oETzKXQAGaYdkL5gEmGeJJFuYh7EQnp2XdTP1o/Vo=")

签名cookie包含了加密后的cookie值和时间戳以及一个HMAC 签名，如果cookie已经过期或者HMAC不匹配
get_secure_cookie 会简单的返回None，就当cookie根本不存在，上面cookie代码的安全版本示例：

class MainHandler(tornado.web.RequestHandler):

    def get(self):

        if not self.get_secure_cookie("mycookie"):

            self.set_secure_cookie("mycookie", "myvalue")

            self.write("Your cookie was not set yet!")

        else:

            self.write("Your cookie was set!")

用户认证
当前经过认证的用户在每个请求处理函数内都是有效的：self.current_user,并且在每个模板内current_user都是
有效的，在默认的情况下current_user 是一个None值

为了在你的应用程序中实现用户认证，你必须在你的请求处理产生中覆盖get_current_user() 方法以便决定
当前用户有效与否的根据，比如是通过cookie来确认。下面是一个例子：让用户通过昵称登录应用程序，然后保存
在cookie内(下面这段代码因为包含原生的html语法，所以插入的话会有问题，如果通过可见即可得的方式插入，换行全部没有了，如果通过html编辑简单插入，又会导致自动生成inut控件，form等，所以使用这种的方法，但是大于号小于号我也没工夫进行转义，那段代码的大概意义就是创建一个form和input，用来输入昵称，然后登录）

class BaseHandler(tornado.web.RequestHandler):   

           def get_current_user(self):       

              return self.get_secure_cookie("user")

class MainHandler(BaseHandler):   

          def get(self):       

                if not self.current_user:           

                     self.redirect("/login")  return       

                name = tornado.escape.xhtml_escape(self.current_user)       

                self.write("Hello, " + name)

class LoginHandler(BaseHandler):   

          def get(self):       

              self.write('<html><body><form action="/login"

                           method="post">'                   

                            'Name: <input type="text" name="name">'                 

                            '<input type="submit" value="Sign in">'                 

                             '</form></body></html>')

           def post(self):       

               self.set_secure_cookie("user", self.get_argument("name"))       

               self.redirect("/")

 

application = tornado.web.Application([    (r"/", MainHandler),   

 (r"/login", LoginHandler),],

 cookie_secret="61oETzKXQAGaYdkL5gEmGeJJFuYh7EQnp2XdTP1o/Vo=")

你可以使用tornado.web.authenticated修饰函数来强制坚持用户登录。如果一个请求到了被该修饰器修饰的方法，
并且用户并没有登录，那么用户会直接被导航到login_url （这也是一项应用程序的设置），基于斯，上面的
代码可以重写如下：

class MainHandler(BaseHandler):

    @tornado.web.authenticated

    def get(self):

        name = tornado.escape.xhtml_escape(self.current_user)

        self.write("Hello, " + name)

 

settings = {

    "cookie_secret": "61oETzKXQAGaYdkL5gEmGeJJFuYh7EQnp2XdTP1o/Vo=",

    "login_url": "/login",

}

application = tornado.web.Application([

    (r"/", MainHandler),

    (r"/login", LoginHandler),

], **settings)

如果你用修饰器修饰post函数，并且用户没有登录，服务器会发送一个403响应
T内建了第三方的认证方案，比如google OAuth，具体查看auth模块。可以check out T博客例子程序来看一看
完整的用户认证的例子

跨站伪造请求保护
跨站请求伪造或者叫XSRF，对于个性化的web应用来说是一个普遍问题，可以查看文章了解xsrf的工作机制。

一般可以接受的组织XSRF的方案是使用无法预知（猜测）的值来cookie每个用户，并且使用该值作为你的
整个站点的每个form请 求的额外参数。如果cookie和form中的这个值不匹配，说明请求是伪造的

T内建了XSRF保护，为了在你的站点内包含他，要设置应用程序的xsrf_cookies选项：

settings = {
“cookie_secret”: “61oETzKXQAGaYdkL5gEmGeJJFuYh7EQnp2XdTP1o/Vo=”,
“login_url”: “/login”,
“xsrf_cookies”: True,
}
application = tornado.web.Application([
(r"/", MainHandler),
(r"/login", LoginHandler),
], **settings)

如果xsrf_cookies 设置了，T应用程序会为所有的用户设置_xsrf ，并且拒绝所有不匹配_xsrf 值的put，post
和delete请求。如果你使用这项设置，你必须把你网站的所有post-form表单修改成如下的形式（添加xsrf_form_html
，该函数在所有的模板内都有效)

窗体顶端

{{ xsrf_form_html() }}
< input type=”text” name=”message”/>
< input type=”submit” value=”Post”/>

窗体底端

如果你发送ajax post请求，你必须在你的每个请求中让你的js代码包含 _xsrf 值，下面是我们在FriendFeed中
使用的自动添加该值的jquery代码：

function getCookie(name) {

    var r = document.cookie.match("\\b" + name + "=([^;]*)\\b");

    return r ? r[1] : undefined;

}

 

jQuery.postJSON = function(url, args, callback) {

    args._xsrf = getCookie("_xsrf");

    $.ajax({url: url, data: $.param(args), dataType: "text", type: "POST",

        success: function(response) {

        callback(eval("(" + response + ")"));

    }});

};

头的方式传递过来：

对put和delete请求（和没有使用form-encoded参数的post一样），XSRF 必须通过HTTP 头的方式传递过来：
头部变量名是X-XSRFToken

静态文件和文件缓存（Static files and aggressive file caching）
你可以通过在应用程序中设置static_path 选择来让Tornado 提供静态文件服务。
settings = {
“static_path”: os.path.join(os.path.dirname(__file__), “static”),
“cookie_secret”: “61oETzKXQAGaYdkL5gEmGeJJFuYh7EQnp2XdTP1o/Vo=”,
“login_url”: “/login”,
“xsrf_cookies”: True,
}
application = tornado.web.Application([
(r"/", MainHandler),
(r"/login", LoginHandler),
], **settings)

该设置会自动的让所有的一/static开始的请求从那个指定的静态目录获取，例如
请求会从指定的目录下获取foo.png。我们还会自动的在static目录下提供/robots.txt和/favicon.ico（即便
他们不是以/static开始）

为了提高性能，一般来说，浏览器（aggressively ）缓存静态资源是一个好主意，这样浏览器就就不需要
发送不需要的If-Modified-Since 或者 Etag请求，这些请求可能会阻塞页面的渲染。T通过static content versioning
来支持这项功能

为了使用这想功能，在模板中使用static_url() 方法，而不是直接把文件的没名字打在HTML文件中

< html>
< headl>
< titlel>FriendFeed – {{ _(“Home”) }}
< /headl>
< bodyl>
< divl>< img src=”{{ static_url(“images/logo.png”) }}”/l>
< /bodyl>
< /htmll>

static_url函数会把这个相对路径转成一个类似 /static/images/logo.png?v=aae54这样的URL，其中的v
是logo.png的散列值，他的出现会让T服务器发送cache头部给用户的浏览器，这样就会然浏览器无限期（indefinitely）
的缓存内容

因为v值基于文件的内容，所以如果你更新了文件并且重启了服务器，就会发送新的v值，这样浏览器就会
自动获取新文件，如果文件的内容并未改变，浏览器还是会继续使用本地缓存的副本，而不是不断的检查服务器上的
更新情况，这样就可以显著的提高渲染性能

你可以可以使用nginx这样的服务器来更高校的提供静态文件的输出，你同样可以配置大多数web服务器来支持
这些缓存机制，下面是ngnix的配置（FriendFeed中使用）：

location /static/ {
root /var/friendfeed/static;
if ($query_string) {
expires max;
}
}

本地化
当前用户的地域（登录或者不登陆）通过 self.locale 一直有效，可以在请求处理中使用，对应的模板变量是locale ,
本地的名称比如en_US变量是locale.name,同时你可以使用locale.translate 来翻译字符串，模板还有一个全局
函数call _()用来作字符串翻译，翻译函数有两种使用形式：
_(“Translate this string”)
上面的语句直接基于当前的locale来翻译字符串

_(“A person liked this”, “%(num)d people liked this”, len(people)) % {“num”: len(people)}

这条语句会根据第三个参数来决定翻译的字符串的单复数。根据len(people)的返回值，如果是1返回前一个字符串，
否则返回第二条字符串

最通用的模式是使用python占位符来代替变量，因为占位符can move around on translation
下面是一个可能的本地化的模板：