多部分形式

Falcon通过以下方式轻松高效地访问已提交的多部分表单 MultipartFormHandler 来处理 multipart/form-data media 键入。此处理程序默认情况下处于启用状态，允许您使用 req.get_media() 要遍历 body parts 在一种形式中：

WSGIASGI

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

备注

请求流不是一次被读入和缓冲，而是在表单中遍历主体部分时按需使用。

对于每个部件，您可以选择是将整个部件读入内存，还是将其写入文件，或者 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() 。

WSGIASGI

# Equivalent to: content = part.get_data()
content = 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)，分别为：

WSGIASGI

阅读全文内容：

data = part.stream.read()

这也是安全的：

doc = yaml.safe_load(part.stream)

media

属性，该属性充当 get_media() 。

WSGIASGI

# Equivalent to: deserialized_media = part.get_media()
deserialized_media = req.media

类型:

对象

text

属性，该属性充当 get_text() 。

WSGIASGI

# Equivalent to: decoded_text = part.get_text()
decoded_text = part.text

类型:

STR

get_data()

返回正文部分内容字节。

可以读取的最大字节数可通过配置 MultipartParseOptions ，和一个 MultipartParseError 如果身体部位大于此大小，则引发。

大小限制可防止通过引用将意外的大量数据读取到内存中 data 和 text 基于此方法构建的属性。对于大型主体(如附加文件)，请使用输入 stream 直接去吧。

备注

第一次调用此方法将消耗部件的输入流。结果被缓存以供后续访问，后续调用将仅检索缓存的内容。

返回:

身体部位的内容。

返回类型:

bytes

get_media()

返回多部分主体部分的反序列化形式。

调用时，此方法将尝试使用Content-Type标头和通过以下方式配置的媒体类型处理程序来反序列化正文部分流 MultipartParseOptions 。

WSGIASGI

结果将被缓存并在后续调用中返回：：

deserialized_media = part.get_media()

返回:

反序列化的媒体表示形式。

返回类型:

object

get_text()

返回解码为文本字符串的Body部分内容。

从部件内容解码文本(由返回 get_data() )中指定的字符集 Content-Type header, or, if omitted, the default charset. The charset must be supported by Python's bytes.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 不然的话。

返回类型:

str

解析器配置

类似于 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 在新的版本中：

WSGIASGI

app = falcon.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) -- 导致此事件的源异常。