Tinman 项目技术文档

1. 安装指南

安装 Tinman

Tinman 可以通过 pip 或 easy_install 进行安装：

pip install tinman

安装可选依赖

Tinman 支持多种可选依赖，可以通过以下命令安装特定依赖：

pip install 'tinman[Dependency Name]'

例如，安装 RabbitMQ 支持：

pip install 'tinman[RabbitMQ]'

2. 项目的使用说明

项目概述

Tinman 是一个为 Tornado 框架提供扩展的工具包，旨在加速 Tornado 应用程序的开发。它包括一个应用程序包装器和一系列装饰器及实用工具。

主要特性

• 全功能的应用程序包装器
• 标准化的应用程序配置
• 内置的可配置会话管理
• 轻量级的 NoSQL 系统模型
• GitHub 和 StackExchange 的认证 Mixins
• 命令行工具 tinman-init，用于创建骨架应用程序结构
• 网络地址白名单装饰器
• 方法/函数调试日志装饰器
• 支持 PostgreSQL、RabbitMQ 和 Redis 的自动连接设置
• 支持外部模板加载器，包括 Tinman 的 CouchDB 模板加载器
• 灵活的日志配置，支持自定义格式化器、过滤器和处理程序
• 内置支持 NewRelic 的 Python 代理库
• RequestHandler 输出缓存/记忆化

3. 项目API使用文档

模块描述

• tinman.application: 扩展了 tornado.web.Application，处理路由、日志、翻译等的自动加载配置。
• tinman.auth: 提供 GitHub、StackExchange 和 HTTP Digest 认证的 Mixins。
• tinman.controller: Tinman 应用程序的核心控制器。
• tinman.couchdb: 基于 CouchDB 的模板加载器模块。
• tinman.decorators: 认证、记忆化和白名单装饰器。
• tinman.exceptions: Tinman 特定的异常。
• tinman.handlers: 请求处理程序，可用作基础处理程序或 Mixins。
  • base: 基础请求处理程序，包括 SessionRequestHandler。
  • mixins: 请求处理程序 Mixins，支持 Redis、RabbitMQ 和模型 API 请求处理程序。
• tinman.model: 模型系统，包含基础模型类和各种支持存储后端的基础模型类。
• tinman.process: 由控制器调用，每个 Tinman 进程绑定到特定的 HTTP 服务器端口。
• tinman.session: 会话对象和存储 Mixins。
• tinman.utilities: 命令行实用工具。

示例处理程序

会话处理程序

会话会在 prepare 阶段自动加载，并在 finish 阶段保存。如果扩展了 SessionHandler 并需要使用 prepare 或 finish，请确保调用 super(YourClass, self).prepare() 和 super(YourClass, self).on_finish()。

from tinman.handlers import session
from tornado import web

class Handler(session.SessionHandler):

  @web.asynchronous
  def get(self, *args, **kwargs):
      self._session.username = 'foo'
      self._session.your_variable = 'bar'
      self.write({'session_id': self._session.id, 'your_variable': self._session.your_variable})
      self.finish()

  def prepare(self):
      super(Handler, self).on_finished()
      # 其他操作

  def prepare(self):
      super(Handler, self).prepare()
      # 其他操作

Heapy 处理程序

Heapy 处理程序使用 guppy 库检查运行中的 Tinman 应用程序的内存堆栈，返回 JSON 格式的结果。它非常慢且阻塞，可能需要几分钟才能完成，因此应谨慎使用。

- [/heapy, tinman.handlers.heapy.HeapyRequestHandler]

4. 项目安装方式

应用程序运行器

Tinman 应用程序运行器使用 YAML 配置文件格式，提供了一个方便的接口来交互式运行 Tornado 应用程序或作为守护进程运行。

命令行语法

tinman -c <configfile> [options]

选项

• -h, --help: 显示帮助信息并退出
• -c CONFIGURATION, --config=CONFIGURATION: 配置文件路径
• -f, --foreground: 在控制台中交互式运行
• -p PATH, --path=PATH: 预先添加到 Python 系统路径的路径

配置

应用程序选项

• cookie_secret: 用于签名安全 cookie 的盐
• debug: 切换 Tornado 应用程序的调试模式
• login_url: 使用 Tornado 的 @authenticated 装饰器时的登录 URL
• newrelic_ini: 启用 NewRelic 支持的 Python .ini 文件路径
• paths:
  • base: 应用程序文件的根目录
  • static: 静态文件路径
  • templates: 模板文件路径
  • translations: 翻译文件路径
• redis: 如果使用 tinman.handlers.redis.RedisRequestHandler 自动连接到 Redis
  • host: Redis 服务器 IP 地址
  • port: 端口号
  • db: 数据库编号
• rabbitmq:
  • host: 主机名
  • port: 服务器端口
  • virtual_host: 虚拟主机
  • username: 用户名
  • password: 密码
• session: 如果使用 tinman.handlers.session.SessionRequestHandler 的配置
  • adapter:
    • class: 适配器类名，如 FileSessionAdapter 或 RedisSessionAdapter
    • configuration: 适配器特定配置
  • cookie:
    • name: 会话 ID 的 cookie 名称
  • duration: 会话生命周期的持续时间（秒）
• template_loader: 覆盖默认模板加载器的 Python 模块.类
• transforms: 要添加到应用程序的转换对象列表，格式为 module.Class
• ui_modules: UI 模块类的模块，可以是单个模块、模块映射（字典）或模块列表
• xsrf_cookies: 启用 xsrf_cookie 模式以保护表单
• whitelist: 如果使用白名单装饰器，则列出 CIDR 表示法的 IP 地址

HTTP 服务器选项

• no_keep_alive: 启用/禁用 keep-alives
• ports: 要监听的端口，每个端口将生成一个进程
• ssl_options: 传递给 HTTP 服务器的 SSL 选项
  • certfile: 证书文件路径
  • keyfile: 密钥文件路径
  • cert_reqs: 是否需要证书
  • ca_certs: 可选值为 none、optional 或 required
• xheaders: 启用 Tornado HTTP 服务器的 X-Header 支持

日志选项

日志使用 dictConfig 格式，支持最小日志配置。以下是最小日志配置示例：

Logging:
    tinman:
      handlers: [console]
      propagate: True
      formatter: verbose
      level: DEBUG
    tornado:
      handlers: [console]
      propagate: True
      formatter: verbose
      level: INFO

路由列表

路由列表使用顶级 R 指定。