Flask-ApiExceptions 1.1.2

安装

您可以使用pip：

$ pip install flask_apiexceptions

或者，您可以克隆存储库：

$ git clone https://github.com/jperras/flask_apiexceptions.git

运行测试

Tox用于运行测试， 是用PyTest写的。 要运行它们，请克隆存储库（如上所示），确保tox 已安装并可用，运行：

$ cd path/to/flask_apiexceptions
$ tox

用法

此包包含名为JSONExceptionHandler的扩展名，该扩展名 可按常规方式添加到应用程序中：

from flask import Flask
from flask_apiexceptions import JSONExceptionHandler

app = Flask(__name__)
exception_handler = JSONExceptionHandler(app)

如果 您正在使用应用程序工厂：

exception_handler = JSONExceptionHandler()
exception_hander.init_app(app)

一旦初始化，扩展实际上在默认情况下不会执行任何操作。 您必须将其配置为处理Werkzeug HTTP错误代码或 自定义Exception类。

classMissingUserError(Exception):status_code=404message='No such user exists.'@app.route('/not-found')deftesting():raiseMissingUserError()ext=JSONExceptionHandler(app)ext.register(code_or_exception=MissingUserError)withapp.app_context():withapp.test_client()asc:rv=c.get('/not-found')assertrv.status_code==404assertrv.headers['content-type']=='application/json'assertjson.loads(rv.data)['message']=='No such user exists.'

fromflask_apiexceptionsimportJSONExceptionHandlerapp=Flask(__name__)ext=JSONExceptionHandler(app)classCaffeineError(Exception):teapot_code=418special={'foo':'bar'}defcaffeine_handler(error):response=jsonify(data=error.special)response.status_code=error.teapot_codereturnresponse@app.route('/testing')deftesting():raiseCaffeineError()ext.register(code_or_exception=CaffeineError,handler=caffeine_handler)withapp.app_context():withapp.test_client()asc:rv=c.get('/testing')assertrv.status_code==418assertrv.headers['content-type']=='application/json'assertjson.loads(rv.data)['data']==CaffeineError.special

使用ApiException和ApiError对象

Flask-ApiExceptions包括一些便利类和一个处理程序 用于设置结构化API错误响应的方法。他们完全 可选，但提供一些正常的默认值 情况。

一个ApiException实例包装一个或多个ApiError实例。 从这个意义上讲，ApiException只是 实际错误消息。ApiError实例接受可选 code、message和info属性。

其思想是code应该是 错误，例如invalid-data或does-not-exist。这个 message字段应该提供更详细和精确的描述 错误的。info字段可用于任何其他元数据 或可能需要的非结构化信息。

如果使用info字段，则该字段应包含json数据 可序列化。

要使用这些结构，需要注册适当的异常 类以及为 目的：

fromflask_apiexceptionsimport(JSONExceptionHandler,ApiException,ApiError,api_exception_handler)app=Flask(__name__)ext=JSONExceptionHandler(app)ext.register(code_or_exception=ApiException,handler=api_exception_handler)@app.route('/custom')deftesting():error=ApiError(code='teapot',message='I am a little teapot.')raiseApiException(status_code=418,error=error)withapp.app_context():withapp.test_client()asc:rv=c.get('/custom')# JSON response looks like...# {"errors": [{"code": "teapot", "message": "I am a little teapot."}]}assertrv.status_code==418assertrv.headers['content-type']=='application/json'json_data=json.loads(rv.data)assertjson_data['errors'][0]['message']=='I am a little teapot.'assertjson_data['errors'][0]['code']=='teapot'assertjson_data['errors'][0]['info']isNone

请注意，当使用ApiException和ApiError类时， 在ApiException实例上设置了状态代码。这会使更多 当您可以将多个ApiError对象设置为同一对象时进行检测 ApiException：

fromflask_apiexceptionsimportApiException,ApiError# ...@app.route('/testing')deftesting():exc=ApiException(status_code=400)invalid_address_error=ApiError(code='invalid-data',message='The address provided is invalid.')invalid_phone_error=ApiError(code='invalid-data',message='The phone number does not exist.',info={'area_code':'555'})exc.add_error(invalid_address_error)exc.add_error(invalid_phone_error)raiseexc# JSON response format:# {"errors": [#     {"code": "invalid-data", "message": "The address provided is invalid."},#     {"code": "invalid-data", "message": "The phone number does not exist.", "info": {"area_code": "444"}}# ]}

如果您只想在 ApiException，这可以通过后者的构造函数作为 速记：

exc=ApiException(status_code=400,code='invalid-data',message='The address provided is invalid',info={'zip_code':'90210'})

相当于：

exc=ApiException(status_code=400)error=ApiError(code='invalid-data',message='The address provided is invalid',info={'zip_code':'90210'}))exc.add_error(error)

一个有用的模式是将ApiException子类化为明显有用的 异常类型，在此类型上可以定义 将用于在instantial上填充正确的error对象打开。为了 示例：

classMissingResourceError(ApiException):status_code=404message="No such resource exists."code='not-found'# ...@app.route('/posts/<int:post_id>')defpost_by_id(post_id):"""Fetch a single post by ID from the database."""post=Post.query.filter(Post.id==post_id).one_or_none()ifpostisNone:raiseMissingResourceError()# 404 response, wiht JSON body:# {"errors": [#     {"code": "not-found", "message": "No such resource exists."}# ]}

这个特殊模式的好处是你可以 语义上更正代码库中的异常，并可以选择 在调用堆栈中处理它们。如果你不处理它们，它们就会冒出来 到异常处理程序（如果您配置了 flask_apiexceptions.api_exception_handler或类似）注册 烧瓶，然后转换为请求客户端的有用响应。

classMissingResourceError(ApiException):status_code=404message="No such resource exists."code='not-found'classPost(db.Model):# ...@classmethoddefquery_by_id(cls,post_id):"""Query Post by ID, raise exception if not found."""result=cls.query.filter(cls.id==post_id).one_or_none()ifresultisNone:raiseMissingResourceError()returnresult@app.route('/posts/<int:post_id>')defpost_by_id(post_id):"""Fetch a single post by ID from the database."""try:post=Post.query_by_id(post_id)exceptMissingResourceErrorase:# We can do whatever we want now that we've caught the exception.# For the sake of illustration, we're just going to log it.app.logger.exception("Could not locate post!")# Will bubble up the exception until it is rendered to JSON# for the client.raisee