多部分形式¶
Falcon通过以下方式轻松高效地访问已提交的多部分表单 MultipartFormHandler
来处理 multipart/form-data
media 键入。此处理程序默认情况下处于启用状态,允许您使用 req.get_media()
要遍历 body parts
在一种形式中:
form = req.get_media()
for part in form:
if part.content_type == 'application/json':
# Body part is a JSON document, do something useful with it
resp.media = part.get_media()
elif part.name == 'datafile':
while True:
# Do something with the uploaded data (file)
chunk = part.stream.read(8192)
if not chunk:
break
feed_data(chunk)
elif part.name == 'imagedata':
# Store this body part in a file.
filename = os.path.join(UPLOAD_PATH, part.secure_filename)
with open(filename, 'wb') as dest:
part.stream.pipe(dest)
else:
# Do something else
form_data[part.name] = part.text
form = await req.get_media()
async for part in form:
if part.content_type == 'application/json':
# Body part is a JSON document, do something useful with it
resp.media = await part.get_media()
elif part.name == 'datafile':
# Do something with the uploaded data (file)
async for chunk in part.stream:
await feed_data(chunk)
elif part.name == 'imagedata':
# Store this body part in a file.
filename = os.path.join(UPLOAD_PATH, part.secure_filename)
async with aiofiles.open(filename, 'wb') as dest:
await part.stream.pipe(dest)
else:
# Do something else
form_data[part.name] = await part.text
备注
请求流不是一次被读入和缓冲,而是在表单中遍历主体部分时按需使用。
对于每个部件,您可以选择是将整个部件读入内存,还是将其写入文件,或者 upload it to the cloud . Falcon为所有这些场景提供了直接的支持。
身体部位类型¶
- class falcon.media.multipart.BodyPart(stream, headers, parse_options)[源代码]¶
表示多部分形式的身体部位。
备注
BodyPart
意味着只能由MultipartFormHandler
解析器。- content_type¶
Content-Type标头的值,或多部分表单的默认值
text/plain
如果标头丢失,则返回。- 类型:
STR
- data¶
属性,该属性充当
get_data()
。# Equivalent to: content = part.get_data() content = part.data
这个
await
引用属性时仍必须添加关键字::# Equivalent to: content = await part.get_data() content = await part.data
- 类型:
字节
- name¶
Content-Disposition标头的Name参数。“name”参数的值是提交的HTML表单中的原始字段名。
备注
根据 RFC 7578, section 4.2 ,每个部件都必须包括“Form-Data”类型的Content-Disposition标头字段,其中name参数是必需的。
但是,如果缺少此参数,Falcon将不会引发任何错误;属性值将为
None
那样的话。- 类型:
STR
- filename¶
如果正文部分是附加文件,则为文件名
None
不然的话。- 类型:
STR
- secure_filename¶
经过净化的版本 filename 仅使用最常用的ASCII字符,以实现最大的可移植性和安全性WRT将此名称用作常规文件系统上的文件名。
如果 filename 引用此属性时为空或未设置,则
MultipartParseError
将会被唤醒。另请参阅:
secure_filename()
- 类型:
STR
- stream¶
用于读取多部分表单请求的正文部分(如果有)的类似文件的输入对象。此对象提供对服务器数据流的直接访问,并且是不可查找的。根据多部分流边界自动分隔流。
除了被缓冲以跟踪边界之外,包装的身体部位流接口和行为模拟
Request.bounded_stream
(WSGI)和Request.stream
(Asgi),分别为:阅读全文内容:
data = part.stream.read()
这也是安全的:
doc = yaml.safe_load(part.stream)
类似于
BoundedStream
,读取正文部分内容的最有效方式是对部分数据块进行异步迭代:async for data_chunk in part.stream: pass
- media¶
属性,该属性充当
get_media()
。# Equivalent to: deserialized_media = part.get_media() deserialized_media = req.media
这个
await
引用属性时仍必须添加关键字::# Equivalent to: deserialized_media = await part.get_media() deserialized_media = await part.media
- 类型:
对象
- text¶
属性,该属性充当
get_text()
。# Equivalent to: decoded_text = part.get_text() decoded_text = part.text
这个
await
引用属性时仍必须添加关键字::# Equivalent to: decoded_text = await part.get_text() decoded_text = await part.text
- 类型:
STR
- get_data()[源代码]¶
返回正文部分内容字节。
可以读取的最大字节数可通过配置
MultipartParseOptions
,和一个MultipartParseError
如果身体部位大于此大小,则引发。大小限制可防止通过引用将意外的大量数据读取到内存中
data
和text
基于此方法构建的属性。对于大型主体(如附加文件),请使用输入stream
直接去吧。备注
第一次调用此方法将消耗部件的输入流。结果被缓存以供后续访问,后续调用将仅检索缓存的内容。
- 返回:
身体部位的内容。
- 返回类型:
- get_media()[源代码]¶
返回多部分主体部分的反序列化形式。
调用时,此方法将尝试使用Content-Type标头和通过以下方式配置的媒体类型处理程序来反序列化正文部分流
MultipartParseOptions
。结果将被缓存并在后续调用中返回::
deserialized_media = part.get_media()
结果将被缓存并在后续调用中返回::
deserialized_media = await part.get_media()
- 返回:
反序列化的媒体表示形式。
- 返回类型:
- get_text()[源代码]¶
返回解码为文本字符串的Body部分内容。
从部件内容解码文本(由返回
get_data()
)中指定的字符集 Content-Type header, or, if omitted, thedefault charset
. The charset must be supported by Python'sbytes.decode()
function. The list of standard encodings (charsets) supported by the Python 3 standard library can be found here 。如果由于无效而导致解码失败 data 字节(用于指定的编码),或指定的编码本身不受支持,则
MultipartParseError
在引用此属性时将引发。备注
因为此方法基于
get_data()
,它将以相同的方式使用部件的输入流。- 返回:
解码为文本字符串的部分,前提是该部分编码为
text/plain
,None
不然的话。- 返回类型:
解析器配置¶
类似于 falcon.App
‘的 req_options
和 resp_options
,实例化一个 MultipartFormHandler
还填充了其 parse_options
属性具有一组适用于许多开箱即用的用例的合理的缺省值。如果您需要定制应用程序的某些表单解析方面,首选的方法是直接在相关的媒体处理程序(解析器)上修改该属性的属性:
import falcon
import falcon.media
handler = falcon.media.MultipartFormHandler()
# Assume text fields to be encoded in latin-1 instead of utf-8
handler.parse_options.default_charset = 'latin-1'
# Allow an unlimited number of body parts in the form
handler.parse_options.max_body_part_count = 0
# Afford parsing msgpack-encoded body parts directly via part.get_media()
extra_handlers = {
falcon.MEDIA_MSGPACK: falcon.media.MessagePackHandler(),
}
handler.parse_options.media_handlers.update(extra_handlers)
要在应用程序中使用您的自定义处理程序,只需将默认处理程序替换为 multipart/form-data
在新的版本中:
app = falcon.App()
# handler is instantiated and configured as per the above snippet
app.req_options.media_handlers[falcon.MEDIA_MULTIPART] = handler
app = falcon.asgi.App()
# handler is instantiated and configured as per the above snippet
app.req_options.media_handlers[falcon.MEDIA_MULTIPART] = handler
小技巧
有关自定义媒体处理程序的更多信息,另请参阅: 替换默认处理程序 。
正在分析选项¶
- class falcon.media.multipart.MultipartParseOptions[源代码]¶
定义一组可配置的多部分表单解析器选项。
类的一个实例通过
MultipartFormHandler.parse_options
属性。处理程序的选项也会向下传递给每个BodyPart
它实例化了。另请参阅: 解析器配置 。
- default_charset¶
的默认字符编码
text fields
(默认值:utf-8
)。- 类型:
STR
- max_body_part_count¶
表单中身体部位的最大数量(默认为64)。如果表单包含的部件多于此数量,则
MultipartParseError
将会被唤醒。如果将此选项设置为0,解析器将不会施加任何限制。- 类型:
利息
- max_body_part_buffer_size¶
时要缓冲和返回的最大字节数。
BodyPart.get_data()
方法被调用(默认为1 MiB)。如果正文部分大小超过此值,则MultipartParseError
将会被唤醒。- 类型:
利息
- max_body_part_headers_size¶
正文部分标头结构的最大大小(以字节为单位)(默认为8192)。如果正文部分标头大小超过此值,则
MultipartParseError
将会被唤醒。- 类型:
利息
- media_handlers¶
用于配置要处理的媒体类型的类字典对象。默认情况下,为
application/json
和application/x-www-form-urlencoded
媒体类型。- 类型:
处理程序
分析错误¶
- class falcon.MultipartParseError(description=None, **kwargs)[源代码]¶
表示多部分表单分析错误。
此错误可能是指表单格式错误或被截断、使用了不推荐使用或不受支持的功能,或者表单参数超过了中配置的限制
MultipartParseOptions
。MultipartParseError
本模块中引发的实例始终包含人类可读的简短错误描述。此异常的原因(如果有)存储在
__cause__
属性,在引发时使用“RAISE.FROM”表单。- 参数:
source_error (Exception) -- 导致此事件的源异常。