# Flask-Exceptional
Flask-Exceptional 为 [Flask](http://flask.pocoo.org/) 添加了 [Exceptional](http://www.exceptional.io/) 支持。Exceptional 会捕获到你的应用程序中的错误，实时地报告它们，并且会收集你需要快速地修复它们的一些信息。访问 [http://www.exceptional.io](http://www.exceptional.io) 去试试。
## 安装
接下来的文档是假设你拥有一个 Exceptional 账号。用 pip 安装这个扩展是简单的:
```
$ pip install Flask-Exceptional
```
或者用 easy_install 安装它:
```
$ easy_install Flask-Exceptional
```
## 快速入门
在安装 Flask-Exceptional 后，所有你必须要做的就是创建一个 Flask 应用程序，配置 Exceptional API 密钥，接着创建 [`Exceptional`](#flask.ext.exceptional.Exceptional "flask.ext.exceptional.Exceptional") 对象。正是这样的简单:
```
from flask import Flask
from flask.ext.exceptional import Exceptional
app = Flask(__name__)
app.config["EXCEPTIONAL_API_KEY"] = "exceptional_forty_character_unique_key"
exceptional = Exceptional(app)
```
你的应用程序是被配置成基于云的错误监控！你可以通过调用 [`Exceptional.test()`](#flask.ext.exceptional.Exceptional.test "flask.ext.exceptional.Exceptional.test") 方法来验证配置是否正常工作:
```
Exceptional.test(app.config)
```
请翻阅接下来的章节获取更多关于 Flask-Exceptional 可用的配置项的细节。
## 配置
Flask-Exceptional 中存在如下的配置项:
| | |
| --- | --- |
| `EXCEPTIONAL_API_KEY` | 你的应用程序的Exceptional API 密钥。 登录到 Exceptional，选择你的应用程序， 点击 _APP SETTINGS_ 链接。显示的 API 密钥就是这里要用到的。试图不提供 API 密钥而创建扩展将导致 登录警告，但应用程序将继续正常运行。 |
| `EXCEPTIONAL_DEBUG_URL` | 如果你的应用程序以调式模式运行的话， Exceptional 将不会捕获错误。配置这个值 是为了在调试模式中捕获错误数据。 比如，你可能使用一个 [RequestBin](http://requestb.in/) 网址 调试你的应用程序。JSON 错误数据会被以压缩形式 POSTed 到这个网址， 而 Exceptional 需要解压这些数据。 |
| `EXCEPTIONAL_HTTP_CODES` | 用 Exceptional 追踪的 HTTP 错误码列表。默认为标准的 HTTP 4xx 错误码。 |
| `EXCEPTIONAL_PARAMETER_FILTER` | 列表值，用来过滤发给 Exceptional 的参数数据。 参数数据包括 `request.form` 和 `request.files` 中的所有。例如，为了过滤密码你可以使用：`['password', 'password_confirm']` |
| `EXCEPTIONAL_ENVIRONMENT_FILTER` | 列表值，用来过滤发给 Exceptional 的环境数据。 环境数据包含 Flask 应用程序配置以及目前 OS 环境。OS 环境值前缀是 `'os.'`。例如，为了过滤SQLAlchemy 数据库 URL以及 所有的 OS 环境值，使用：`['SQLALCHEMY_DATABASE_URI', 'os.*']`默认值是 `['SECRET_KEY']`。 |
| `EXCEPTIONAL_SESSION_FILTER` | 列表值，用来过滤发给 Exceptional 的会话数据。 |
| `EXCEPTIONAL_HEADER_FILTER` | 列表值，用来过滤发给 Exceptional 的 HTTP 头数据。 |
| `EXCEPTIONAL_COOKIE_FILTER` | 名称的列表，用来过滤发给 Exceptional 的 HTTP Cookie 头数据。 |
Note
所有配置中的过滤列表接受字符串以及正则表达式。
## API
`class flask.ext.exceptional.Exceptional(app=None)`
Extension for tracking application errors with Exceptional. Errors are not tracked if DEBUG is True. The application will log a warning if no `EXCEPTIONAL_API_KEY` has been configured.
Parameters:
**app** – Default None. The Flask application to track errors for. If the app is not provided on creation, then it can be provided later via [`init_app()`](#flask.ext.exceptional.Exceptional.init_app "flask.ext.exceptional.Exceptional.init_app").
`static context(data=None, **kwargs)`
Add extra context data to the current tracked exception. The context data is only valid for the current request. Multiple calls to this method will update any existing context with new data.
Parameters:
* **data** – Default `None`. A dictionary of context data.
* **\*\*kwargs** – A series of keyword arguments to use as context data.
`init_app(app)`
Initialize this Exceptional extension.
Parameters:
**app** – The Flask application to track errors for.
`static publish(config, traceback)`
Publish the given traceback directly to Exceptional. This method is useful for tracking errors that occur outside the context of a Flask request. For example, this may be called from an asynchronous queue.
Parameters:
* **config** – A Flask application configuration object. Accepts either `flask.Config` or the object types allowed by `flask.Config.from_object()`.
* **traceback** – A `werkzeug.debug.tbtools.Traceback` instance to publish.
`static test(config)`
Test the given Flask configuration. If configured correctly, an error will be tracked by Exceptional for your app. Unlike the initialized extension, this test will post data to Exceptional, regardless of the configured `DEBUG` setting.
Parameters:
**config** – The Flask application configuration object to test. Accepts either `flask.Config` or the object types allowed by `flask.Config.from_object()`.
## Changelog
### Version 0.5.4
* Updated JSON implementation import to work with Flask 0.10.
### Version 0.5.3
* Fixed [`Exceptional.publish()`](#flask.ext.exceptional.Exceptional.publish "flask.ext.exceptional.Exceptional.publish") to no longer dereference a request context.
### Version 0.5.2
* Unwind broken _app_ctx_stack usage.
### Version 0.5.1
* Handle malformed HTTP response status-line from Exceptional.
### Version 0.5
* Updated with Flask 0.8 extension structure recommendations and 0.9 _app_ctx_stack.
* Added `{'application_environment': 'loaded_libraries': {...}}` API data.
### Version 0.4.9
* Added the [`Exceptional.context()`](#flask.ext.exceptional.Exceptional.context "flask.ext.exceptional.Exceptional.context") method to support Exceptional’s extra context data API.
* Updated to reference the new exceptional.io domain.
### Version 0.4.8
* Updated to publish UTF-8 encoded data to Exceptional.
* Added support for `request.json` data.
### Version 0.4.7
* Added the [`Exceptional.publish()`](#flask.ext.exceptional.Exceptional.publish "flask.ext.exceptional.Exceptional.publish") method to support Exceptional tracking outside the context of a request.
### Version 0.4.6
* Corrected `occurred_at` timestamp to be formatted as Zulu.
* Fixed JSON serialization issue by coercing all environment variables to strings.
### Version 0.4.5
* Updated to log a warning on repeated extension initialization attempts.
### Version 0.4.4
* Fixed to workaround Python 2.5 issue where `urlopen()` raises a `HTTPError` even though the HTTP response code indicates success.
### Version 0.4.3
* Changed so that `app.extensions['exceptional']` targets the [`Exceptional`](#flask.ext.exceptional.Exceptional "flask.ext.exceptional.Exceptional") extension instance.
### Version 0.4.2
* Updated to support Python 2.5.
### Version 0.4.1
* Updated to support Flask 0.7 blueprints.
### Version 0.4
* Updated to support Python 2.6.
* Added `EXCEPTIONAL_DEBUG_URL` testing environment variable override.
### Version 0.3
* Updated to handle unreachable Exceptional service API.
### Version 0.2
* Added [`Exceptional.test()`](#flask.ext.exceptional.Exceptional.test "flask.ext.exceptional.Exceptional.test") method.
### Version 0.1
* Initial public release.
