标签：tom doc 又能 TE 链接 gen page ESS value
注意：Flask-RESTPlus的整个请求解析器部分将被移除，并将替换成关于集成其他更善于处理输入、输出的包（例如marshmallow）的说明文档。但是考虑到已经被废弃，它将一直维护到2.0版本。如果你现在有代码使用它，并希望继续这样做，那么也无需担心，因为它不会很快消失。
Flask-RESTPlus的请求解析接口reqparse是模仿argparse接口实现的。它的设计目的是对Flask中flask.request对象上的任何变量提供简单和统一的访问方式。
下面是一个请求解析器的简单示例。它在flask.Request.values字典中查找两个参数：一个整数和一个字符串：
from flask_restplus import reqparse parser = reqparse.RequestParser() parser.add_argument(‘rate‘, type=int, help=‘Rate cannot be converted‘) parser.add_argument(‘name‘) # Python3中默认类型为字符串 args = parser.parse_args()
注意：默认参数类型是unicode字符串。在Python3中为str类型，而在Python2中为unicode。
如果指定了help变量的值，那么在解析请求时，如果出现了类型错误，那么会将它渲染为错误信息。如果未指定help信息，那么默认的行为是返回类型错误信息本身。可以查看“11、错误信息”部分以了解更多细节。
注意：默认情况下，参数不是必需的。并且，如果请求中提供的某些参数不是RequestParser的部分内容，那么这些参数将会被忽略。
注意：请求解析器中声明的参数，如果在请求中并未设置这些参数值，那么它们将会默认设置为None。
如果需要确保某个参数必须提供，那么可以在调用add_argument()时传入required=True的参数项：
parser.add_argument(‘name‘, required=True, help="Name cannot be blank!")
此时，如果请求中未提供该参数，那么将会返回错误信息。
如果想为某个key接受多个值以构成列表，那么可以传入action=‘append‘：
parser.add_argument(‘name‘, action=‘append‘)
此时的查询格式如下所示：
curl http://api.example.com -d "name=bob" -d "name=sue" -d "name=joe"
而程序中获取到的参数如下所示：
args = parser.parse_args() args[‘name‘] # [‘bob‘, ‘sue‘, ‘joe‘]
如果期望一个逗号分隔的列表，那么可以使用action=‘split‘：
parser.add_argument(‘fruits‘, action=‘split‘)
此时的查询格式如下所示：
curl http://api.example.com -d "fruits=apple,lemon,cherry"
而程序中获取到的参数如下所示：
args = parser.parse_args() args[‘fruits‘] # [‘apple‘, ‘lemon‘, ‘cherry‘]
如果期望参数一旦被解析，就将其存储为其他名字，那么可以使用dest参数：
parser.add_argument(‘name‘, dest=‘public_name‘) args = parser.parse_args() args[‘public_name‘]
默认情况下，RequestParser尝试从flask.Request.values和flask.Request.json中解析值。
在add_argument()中使用location参数来指定获取值的其他位置。可以使用flask.Request上的任何变量，例如：
# 仅仅在POST body中查找 parser.add_argument(‘name‘, type=int, location=‘form‘) # 仅仅在querystring中查找 parser.add_argument(‘PageSize‘, type=int, location=‘args‘) # 从请求头中查找 parser.add_argument(‘User-Agent‘, location=‘headers‘) # 从http cookies中查找 parser.add_argument(‘session_id‘, location=‘cookies‘) # 从上传文件中查找 parser.add_argument(‘picture‘, type=werkzeug.datastructures.FileStorage, location=‘files‘)
注意：当location=‘json‘时只能使用type=list，点击此处查看更多。
注意：使用location=‘form‘既能验证表单数据，又能为表单字段文档化。
为location参数赋一个列表就能为参数指定多个位置：
parser.add_argument(‘text‘, location=[‘headers‘, ‘values‘])
当指定多个参数位置时，那么所有指定位置的参数将会组成一个MultiDict。其中，列表中最后位置处的参数将会优先存储在结果集中。
如果参数位置列表中包含headers位置，那么参数名将变成对大小写敏感，并且必须匹配它们的标题大小写名称（见str.title()）。
指定location=‘headers‘（而不是作为列表的某个元素）将保留大小写不敏感的特性。
有时，我们需要其他原始类型来处理输入验证问题。为此，inputs模块中提供了一些常用的类型处理方法，如下：
只需要使用它们作为type参数的值即可：
parser.add_argument(‘flag‘, type=inputs.boolean)
查看inputs文档以了解所有可用的输入类型。
另外，我们也可以编写自己的输入类型：
def my_type(value): ‘‘‘解析类型‘‘‘ if not condition: raise ValueError(‘This is not my type‘) return parse(value) # Swagger文档化 my_type.__schema__ = {‘type‘: ‘string‘, ‘format‘: ‘my-custom-format‘}
很多情况下，我们都需要为不同的资源指定不同的解析器。不过，如果这些不同的解析器之间存在大量相同的字段的话，将会存在大量重复编码的问题。为此，我们可以编写一个父解析器，父解析器中包含所有共同的参数，然后利用copy()方法来扩展解析器。另外，也可以利用replace_argument()来覆写父解析器中的任何参数，或者利用remove_argument()完全移除父解析器中的某个参数。例如：
from flask_restplus import reqparse parser = reqparse.RequestParser() parser.add_argument(‘foo‘, type=int) parser_copy = parser.copy() parser_copy.add_argument(‘bar‘, type=int) # 此时，parser_copy中同时包含‘foo‘和‘bar‘参数 parser_copy.replace_argument(‘foo‘, required=True, location=‘json‘) # 此时，‘foo‘参数变成了一个必需的str类型的参数，并且查找位置为json；而不再是父解析器中定义的int类型的可选参数 parser_copy.remove_argument(‘foo‘) # 此时，parser_copy中不再包含‘foo‘参数
为了利用RequestParser处理文件上传问题，我们需要将location变量值设置为files，并设置type值为FileStorage。如下所示：
from werkzeug.datastructures import FileStorage upload_parser = api.parser() upload_parser.add_argument(‘file‘, location=‘files‘, type=FileStorage, required=True) @api.route(‘/upload/‘) @api.expect(upload_parser) class Upload(Resource): def post(self): uploaded_file = args[‘file‘] # 这是FileStorage实例 url = do_something_with_file(uploaded_file) return {‘url‘: url}, 201
RequestParser处理错误的默认方式是在第一个错误产生时中断。当我们拥有需要花费一定时间来处理的参数时，这种方式是有好处的。然而，通常来说，将所有产生的错误都绑定在一起，然后同时一次性返回给客户端，这种方式则更加友好。这种方式既可以在Flask应用级别指定，也可以在特定的RequestParser实例级别指定。为了调用一个包含错误绑定选项的RequestParser，需要传入参数bundle_errors。例如：
from flask_restplus import reqparse parser = reqparse.RequestParser(bundle_errors=True) parser.add_argument(‘foo‘, type=int, required=True) parser.add_argument(‘bar‘, type=int, required=True) # 如果某个请求中同时不包含‘foo‘和‘bar‘，那么返回的错误将看起来如下所示： { "message": { "foo": "foo error message", "bar": "bar error message" } } # 默认操作将仅仅返回第一个错误 parser = RequestParser() parser.add_argument(‘foo‘, type=int, required=True) parser.add_argument(‘bar‘, type=int, required=True) { "message": { "foo": "foo error message" } }
应用级别的配置key为“BUNDLE_ERRORS”。例如：
from flask import Flask app = Flask(__name__) app.config[‘BUNDLE_ERRORS‘] = True
警告：BUNDLE_ERRORS是一个全局设置，它将覆盖每个RequestParser实例中的bundle_errors选项值。
每个字段的错误消息都可以通过在Argument（也包括RequestParser.add_argument）中使用help参数来自定义。
如果没有提供help参数，那么该字段的错误消息将会是类型错误本身的字符串表示。如果提供了help参数，那么错误消息将会是help参数的值。
help可能包含一个插入的符号{error_msg}，它将会替换成类型错误的字符串表示。这种方式能够实现自定义错误消息，同时保留原始的错误消息。如下所示：
from flask_restplus import reqparse parser = reqparse.RequestParser() parser.add_argument( ‘foo‘, choices=(‘one‘, ‘two‘), help=‘Bad choice: {error_msg}‘ ) # 如果请求中的‘foo‘参数值为‘three‘，那么错误信息将会如下所示： { "message": { "foo": "Bad choice: three is not a valid choice", } }
标签：tom doc 又能 TE 链接 gen page ESS value
原文地址：https://www.cnblogs.com/leejack/p/9164208.html
