Tornado 6.4 Documentation

• 语言: 英语
• 格式: .epub
• 来源: www.tornadoweb.org

摘要

本文档是Tornado 6.4的官方文档，介绍了Tornado的安装前提、支持平台和核心功能。Tornado 6.3需要Python 3.8或更新版本，可选依赖包括pycurl和pycares。Tornado设计用于Unix类平台，在支持epoll、kqueue或/dev/poll的系统上具有最佳性能和可扩展性，Windows上部分功能缺失且不推荐生产使用。文档涵盖用户指南（异步非阻塞I/O、协程、Web应用结构）、Web框架（tornado.web、tornado.websocket等）、HTTP服务器和客户端（tornado.httpserver、tornado.httpclient）、异步网络（tornado.ioloop、tornado.iostream）以及与其他服务的集成（tornado.auth、tornado.wsgi）。版本6.4.0新增了对Python 3.12的支持，并标记了多项弃用（如IOLoop.add_callback from signal、TwitterMixin等）。

AI总结

Tornado 6.4 文档总结如下：

**核心要求与平台支持**
- Tornado 6.3 及以上版本需 Python 3.8 或更新版本。
- 可选依赖包括 `pycurl`（需 libcurl 7.22+）和 `pycares`（非阻塞 DNS 解析器）。
- 主要面向 Unix-like 平台（Linux、BSD/macOS、Solaris），在 Windows 上运行但官方不推荐用于生产，且缺少多进程模式，扩展性有限。

**Tornado 6.4.0 新特性（2023年11月28日）**
- **通用变更**：正式支持 Python 3.12。
- **弃用通知**：
- `IOLoop.add_callback` 在信号处理中已损坏，将在 7.0 版本移除，建议改用 `asyncio.loop.add_signal_handler`。
- `OAuth2Mixin.authorize_redirect` 的 `client_secret` 参数被弃用，将在 7.0 版本移除。
- `TwitterMixin` 被弃用，将在未来版本移除。

**Tornado 4.0 重要更新（2014年7月15日）**
- **亮点**：
- 新增 `stream_request_body` 装饰器，支持大文件上传且内存占用低。
- 协程性能提升，并广泛用于 Tornado 内部；更多方法返回 `Future` 对象。
- HTTP 相关代码（`httpserver`、`simple_httpclient`、`wsgi`）共享，使分块编码和 gzip 压缩支持更一致。
- 新增 `tornado.tcpclient` 模块，支持非阻塞 DNS、SSL 握手和 IPv6。
- **向后兼容性**：
- `tornado.concurrent.Future` 不再线程安全，需使用 `concurrent.futures.Future`。
- 默认拒绝跨域 WebSocket 连接；需重写 `WebSocketHandler.check_origin` 以允许。
- 不再支持旧的 WebSocket draft 76 协议（主要影响 Safari 5.x）。

**关键模块与功能**
- **Web 框架**：`tornado.web`（RequestHandler、Application）、`tornado.template`（模板）、`tornado.websocket`（双向通信）。
- **HTTP 服务器与客户端**：`tornado.httpserver`（非阻塞 HTTP 服务器）、`tornado.httpclient`（异步 HTTP 客户端）。
- **异步网络**：`tornado.ioloop`（主事件循环）、`tornado.iostream`（非阻塞 socket 封装）、`tornado.tcpclient`（TCP 连接工厂）。
- **协程与并发**：`tornado.gen`（基于生成器的协程）、`tornado.locks`（同步原语）、`tornado.queues`（队列）。
- **集成**：`tornado.auth`（第三方登录）、`tornado.wsgi`（与其他框架互操作）、`tornado.platform.asyncio`（asyncio 桥接）。
- **工具**：`tornado.autoreload`（自动重载）、`tornado.testing`（异步单元测试）。

**重要弃用与移除（部分针对 6.0 版本）**
- **模块/函数**：`tornado.stack_context`、`tornado.platform.twisted` 中的 `TornadoReactor` 和 `TwistedIOLoop`、`tornado.gen` 中的 `engine`、`YieldPoint` 等。
- **参数**：`AsyncHTTPClient.fetch` 的 `callback` 参数、`BaseIOStream` 的 `streaming_callback` 参数、`run_on_executor` 的 `callback` 参数。
- **行为变更**：`raise_error=False` 在 6.0 将仅抑制非 200 状态码的错误；`HTTPError` 已重命名为 `HTTPClientError`。

**其他关键修复与改进**
- **性能与内存**：修复了 `tornado.concurrent` 中的引用循环问题，减少内存占用。
- **HTTP 处理**：`simple_httpclient` 和 `curl_httpclient` 的 `request_time` 行为一致化，均排除 `max_clients` 队列等待时间；支持非 ASCII 字符的用户名和密码。
- **Web 框架**：`RedirectHandler` 现在复制请求中的查询参数；`StaticFileHandler` 返回正确的 `Content-Type` 给 `.gz`、`.bz2`、`.xz` 文件；默认 gzip 压缩级别从 9 降至 6。
- **测试**：`AsyncHTTPTestCase.fetch` 支持绝对 URL，并默认连接 `127.0.0.1` 以避免 IPv6 配置问题。
- **其他**：`PeriodicCallback` 新增 `jitter` 参数以随机化超时；`Queue` 支持 `async for` 语句；模板引擎新增 `whitespace` 配置选项。