Tornado框架官方文档：Python异步网络库与Web框架

需积分: 12 70 浏览量更新于2024-07-16 收藏 885KB PDF 举报

"tornado docs.pdf 是一份关于 Python 的 Tornado 框架的官方文档，包含用户指南、Web 框架、HTTP 服务器和客户端、异步网络编程等内容，适用于学习和参考 Tornado 框架的开发工作。" Tornado 是一个用 Python 编写的 Web 框架和异步网络库，最初在 FriendFeed 公司被开发。它通过非阻塞的网络 I/O 能力，可以在处理大量并发连接时展现出优秀的性能，特别适合长轮询、WebSocket 及其他需要与每个用户保持长期连接的应用场景。文档内容分为多个章节，包括： 1. **快速链接**：提供了当前版本信息（6.1.dev1）、源代码仓库（GitHub）、邮件列表等资源，便于开发者获取最新更新和讨论问题。 2. **Hello, world**：通常介绍 Tornado 的基本应用，如何快速创建一个简单的 Web 服务。 3. **线程和 WSGI**：讨论了 Tornado 如何与线程交互，以及它不使用传统的 WSGI（Web Server Gateway Interface）的原因，因为 Tornado 自带了异步能力。 4. **asyncio 集成**：Tornado 支持 asyncio 库，可以与 Python 的异步生态无缝集成，提升程序的并发性能。 5. **安装**：详述了如何安装 Tornado，包括从 PyPI 下载和依赖项管理。 6. **文档**：这一部分详细介绍了 Tornado 的各个方面： - **用户指南**：提供 Tornado 的基础使用方法，包括路由、请求处理、模板渲染等。 - **Web 框架**：讲解如何构建 Web 应用，包括 HTTP 方法、中间件、会话管理等。 - **HTTP 服务器和客户端**：涵盖 Tornado 提供的 HTTP 客户端和服务器实现，以及如何进行请求和响应处理。 - **异步网络编程**：深入探讨异步 I/O，如非阻塞套接字和异步回调。 - **协程和并发**：解释如何利用 Python 的协程来实现并发处理，提高效率。 - **与其他服务的集成**：介绍如何将 Tornado 与其他服务（如数据库、缓存系统）结合。 - **工具**：列举了一些 Tornado 提供的实用工具函数和类。 - **常见问题**：解答了用户在使用 Tornado 过程中可能遇到的问题。 - **发行说明**：记录了每个版本的变更和改进。 7. **讨论和支持**：提供了社区交流的平台，包括邮件列表，用于讨论和发布公告。这份文档是学习和精通 Tornado 的重要参考资料，无论你是初学者还是有经验的开发者，都可以从中找到所需的信息。通过阅读这份文档，你可以了解到如何利用 Tornado 实现高性能的异步 Web 应用，并掌握其背后的原理和最佳实践。

Tornado Documentation, Release 6.1.dev1

12 Chapter 5. Installation

CHAPTER

SIX

DOCUMENTATION

This documentation is also available in PDF and Epub formats.

6.1 User’s guide

6.1.1 Introduction

Tornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed. By

using non-blocking network I/O, Tornado can scale to tens of thousands of open connections, making it ideal for long

polling, WebSockets, and other applications that require a long-lived connection to each user.

Tornado can be roughly divided into four major components:

• A web framework (including RequestHandler which is subclassed to create web applications, and various

supporting classes).

• Client- and server-side implementions of HTTP (HTTPServer and AsyncHTTPClient).

• An asynchronous networking library including the classes IOLoop and IOStream, which serve as the building

blocks for the HTTP components and can also be used to implement other protocols.

• A coroutine library (tornado.gen) which allows asynchronous code to be written in a more straightforward

way than chaining callbacks. This is similar to the native coroutine feature introduced in Python 3.5 (async

def). Native coroutines are recommended in place of the tornado.gen module when available.

The Tornado web framework and HTTP server together offer a full-stack alternative to WSGI. While it is possible to

use the Tornado HTTP server as a container for other WSGI frameworks (WSGIContainer), this combination has

limitations and to take full advantage of Tornado you will need to use Tornado’s web framework and HTTP server

together.

6.1.2 Asynchronous and non-Blocking I/O

Real-time web features require a long-lived mostly-idle connection per user. In a traditional synchronous web server,

this implies devoting one thread to each user, which can be very expensive.

To minimize the cost of concurrent connections, Tornado uses a single-threaded event loop. This means that all

application code should aim to be asynchronous and non-blocking because only one operation can be active at a time.

The terms asynchronous and non-blocking are closely related and are often used interchangeably, but they are not

quite the same thing.

Tornado Documentation, Release 6.1.dev1

Blocking

A function blocks when it waits for something to happen before returning. A function may block for many reasons:

network I/O, disk I/O, mutexes, etc. In fact, every function blocks, at least a little bit, while it is running and using

the CPU (for an extreme example that demonstrates why CPU blocking must be taken as seriously as other kinds of

blocking, consider password hashing functions like bcrypt, which by design use hundreds of milliseconds of CPU

time, far more than a typical network or disk access).

A function can be blocking in some respects and non-blocking in others. In the context of Tornado we generally talk

about blocking in the context of network I/O, although all kinds of blocking are to be minimized.

Asynchronous

An asynchronous function returns before it is ﬁnished, and generally causes some work to happen in the background

before triggering some future action in the application (as opposed to normal synchronous functions, which do every-

thing they are going to do before returning). There are many styles of asynchronous interfaces:

• Callback argument

• Return a placeholder (Future, Promise, Deferred)

• Deliver to a queue

• Callback registry (e.g. POSIX signals)

Regardless of which type of interface is used, asynchronous functions by deﬁnition interact differently with their

callers; there is no free way to make a synchronous function asynchronous in a way that is transparent to its callers

(systems like gevent use lightweight threads to offer performance comparable to asynchronous systems, but they do

not actually make things asynchronous).

Asynchronous operations in Tornado generally return placeholder objects (Futures), with the exception of some

low-level components like the IOLoop that use callbacks. Futures are usually transformed into their result with

the await or yield keywords.

Examples

Here is a sample synchronous function:

from tornado.httpclient import HTTPClient

def synchronous_fetch(url):

http_client = HTTPClient()

response = http_client.fetch(url)

return response.body

And here is the same function rewritten asynchronously as a native coroutine:

from tornado.httpclient import AsyncHTTPClient

async def asynchronous_fetch(url):

http_client = AsyncHTTPClient()

response = await http_client.fetch(url)

return response.body

Or for compatibility with older versions of Python, using the tornado.gen module:

14 Chapter 6. Documentation

Tornado Documentation, Release 6.1.dev1

from tornado.httpclient import AsyncHTTPClient

from tornado import gen

@gen.coroutine

def async_fetch_gen(url):

http_client = AsyncHTTPClient()

response = yield http_client.fetch(url)

raise gen.Return(response.body)

Coroutines are a little magical, but what they do internally is something like this:

from tornado.concurrent import Future

def async_fetch_manual(url):

http_client = AsyncHTTPClient()

my_future = Future()

fetch_future = http_client.fetch(url)

def on_fetch(f):

my_future.set_result(f.result().body)

fetch_future.add_done_callback(on_fetch)

return my_future

Notice that the coroutine returns its Future before the fetch is done. This is what makes coroutines asynchronous.

Anything you can do with coroutines you can also do by passing callback objects around, but coroutines provide an

important simpliﬁcation by letting you organize your code in the same way you would if it were synchronous. This is

especially important for error handling, since try/except blocks work as you would expect in coroutines while this

is difﬁcult to achieve with callbacks. Coroutines will be discussed in depth in the next section of this guide.

6.1.3 Coroutines

Coroutines are the recommended way to write asynchronous code in Tornado. Coroutines use the Python await

or yield keyword to suspend and resume execution instead of a chain of callbacks (cooperative lightweight threads

as seen in frameworks like gevent are sometimes called coroutines as well, but in Tornado all coroutines use explicit

context switches and are called as asynchronous functions).

Coroutines are almost as simple as synchronous code, but without the expense of a thread. They also make concurrency

easier to reason about by reducing the number of places where a context switch can happen.

Example:

async def fetch_coroutine(url):

http_client = AsyncHTTPClient()

response = await http_client.fetch(url)

return response.body

Native vs decorated coroutines

Python 3.5 introduced the async and await keywords (functions using these keywords are also called “native

coroutines”). For compatibility with older versions of Python, you can use “decorated” or “yield-based” coroutines

using the tornado.gen.coroutine decorator.

Native coroutines are the recommended form whenever possible. Only use decorated coroutines when compatibility

with older versions of Python is required. Examples in the Tornado documentation will generally use the native form.

Translation between the two forms is generally straightforward:

6.1. User’s guide 15

Tornado Documentation, Release 6.1.dev1

# Decorated: # Native:

# Normal function declaration

# with decorator # "async def" keywords

@gen.coroutine

def a(): async def a():

# "yield" all async funcs # "await" all async funcs

b = yield c() b = await c()

# "return" and "yield"

# cannot be mixed in

# Python 2, so raise a

# special exception. # Return normally

raise gen.Return(b) return b

Other differences between the two forms of coroutine are outlined below.

• Native coroutines:

– are generally faster.

– can use async for and async with statements which make some patterns much simpler.

– do not run at all unless you await or yield them. Decorated coroutines can start running “in the

background” as soon as they are called. Note that for both kinds of coroutines it is important to use

await or yield so that any exceptions have somewhere to go.

• Decorated coroutines:

– have additional integration with the concurrent.futures package, allowing the result of

executor.submit to be yielded directly. For native coroutines, use IOLoop.run_in_executor

instead.

– support some shorthand for waiting on multiple objects by yielding a list or dict. Use tornado.gen.

multi to do this in native coroutines.

– can support integration with other packages including Twisted via a registry of conversion functions. To

access this functionality in native coroutines, use tornado.gen.convert_yielded.

– always return a Future object. Native coroutines return an awaitable object that is not a Future. In

Tornado the two are mostly interchangeable.

How it works

This section explains the operation of decorated coroutines. Native coroutines are conceptually similar, but a little

more complicated because of the extra integration with the Python runtime.

A function containing yield is a generator. All generators are asynchronous; when called they return a generator

object instead of running to completion. The @gen.coroutine decorator communicates with the generator via the

yield expressions, and with the coroutine’s caller by returning a Future.

Here is a simpliﬁed version of the coroutine decorator’s inner loop:

# Simplified inner loop of tornado.gen.Runner

def run(self):

# send(x) makes the current yield return x.

# It returns when the next yield is reached

future = self.gen.send(self.next)

def callback(f):

self.next = f.result()

(continues on next page)

16 Chapter 6. Documentation

剩余238页未读，继续阅读

m0_37446983

粉丝: 0
资源: 1

Tornado框架官方文档：Python异步网络库与Web框架

tornado项目模板

深入解析Python的Tornado框架中内置的模板引擎

《Python高效开发实战：Django、Tornado、Flask、Twisted》_sample.pdf

tornado使用@tornado.web.authenticated鉴权以后怎么跳转到首页

tornado.netutil.bind_sockets

@tornado.web.asynchronous 版本

tornado.httpserver 与tornado.web的区别

module 'tornado.gen' has no attribute 'engine'

tornado.tcpserver.TCPServer

No module named 'tornado.web'

最新资源