WSGI请求和响应

的实例 falcon.Request 和 falcon.Response 类分别作为第二个和第三个参数传递给WSGI应用程序响应程序：

import falcon


class Resource:

    def on_get(self, req, resp):
        resp.media = {'message': 'Hello world!'}
        resp.status = falcon.HTTP_200


# -- snip --


app = falcon.App()
app.add_route('/', Resource())

请求

class falcon.Request(env, options=None)[源代码]

表示客户端的HTTP请求。

备注

Request 不打算由响应程序直接实例化。

参数:

env (dict) -- 从服务器传入的wsgi环境dict。另见PEP-3333。

关键字参数:

options (dict) -- 从应用处理程序传递的一组全局选项。

env

对wsgi环境的引用 dict 从服务器传入。（另见PEP-3333。）

类型:

双关语

context

空对象用于保存特定于应用程序的请求的任何数据（在其属性中）（例如，会话对象）。falcon本身在初始化后不会与该属性交互。

备注

2.0中的新功能： 默认设置 context_type (见下文)已从 dict 传递特定于请求的数据的首选方式是现在直接在 context 对象。例如：：

req.context.role = 'trial'
req.context.user = 'guest'
类型:

对象

context_type

类变量，该变量确定用于初始化 context 属性。默认情况下，框架将实例化裸对象(裸对象的实例 falcon.Context 类)。但是，您可以通过创建自定义子类 falcon.Request ，然后将该新类传递给 falcon.App() 通过后者的方式 request_type 参数。

备注

当超越 context_type 使用工厂函数（与类相反），该函数的调用方式与当前请求实例的方法类似。因此，第一个参数是请求实例本身（self）。

类型:

类

scheme

用于请求的URL方案。“http”或“https”。

备注

如果请求是代理的，则方案可能与客户机最初请求的方案不匹配。 forwarded_scheme 可以用来处理这种情况。

类型:

STR

forwarded_scheme

用户代理请求的原始URL方案（如果请求是代理的）。典型值为“http”或“https”。

按优先顺序检查以下请求头，以确定转发方案：

  • Forwarded

  • X-Forwarded-For

如果这些头都不可用，或者如果转发头可用，但在第一个跃点中不包含“proto”参数，则为 scheme 而是返回。

（另见： RFC 7239, Section 1 ）

类型:

STR

method

请求的HTTP方法（例如“get”、“post”等）

类型:

STR

host

主机请求头字段

类型:

STR

forwarded_host

由应用服务器前面的第一个代理接收的原始主机请求头。

按优先顺序检查以下请求头，以确定转发方案：

  • Forwarded

  • X-Forwarded-Host

如果上述头都不可用，或者如果转发头可用，但第一个跃点中不包含“host”参数，则为 host 而是返回。

备注

反向代理通常配置为将主机头直接设置为用户代理最初请求的主机头；在这种情况下，使用 host 就足够了。

（另见： RFC 7239, Section 4 ）

类型:

STR

port

用于请求的端口。如果请求中存在Host报头，但没有指定端口，则返回给定模式的默认报头(对于HTTP为80，对于HTTPS为443)。如果请求不包括Host Header，则返回WSGI服务器的侦听端口。

类型:

利息

netloc

返回请求URL的host：port部分。如果端口是URL模式的默认端口(HTTP为80，HTTPS为443)，则可以省略该端口。

类型:

STR

subdomain

主机名中最左边的（即最具体的）子域。如果只给出一个域名， subdomain 将 None .

备注

如果请求中的主机名是IP地址，则 subdomain 未定义。

类型:

STR

root_path

请求URI路径的初始部分，对应于应用程序对象，以便应用程序知道其虚拟“位置”。如果应用程序对应于服务器的“根”，则这可能是一个空字符串。

（对应于PEP-3333定义的“script_name”环境变量。）

类型:

STR

app

的别名已弃用 root_path 。

类型:

STR

uri

请求的完全限定的URI。

类型:

STR

url

的别名 uri 。

类型:

STR

forwarded_uri

代理请求的原始URI。使用 forwarded_scheme 和 forwarded_host 以便重建用户代理请求的原始URI。

类型:

STR

relative_uri

请求URI的路径和查询字符串部分，省略了方案和主机。

类型:

STR

prefix

请求URI的前缀，包括方案、主机和wsgi应用程序（如果有）。

类型:

STR

forwarded_prefix

代理请求的原始URI的前缀。使用 forwarded_scheme 和 forwarded_host 以便重建原始URI。

类型:

STR

path

请求URI的路径部分（不包括查询字符串）。

警告

如果应用程序要将此属性用于任何上游请求，则必须在发出请求之前对路径中的任何非URL安全字符进行URL编码。

备注

req.path 属性可以设置为新值。 process_request() 中间件方法，以影响路由。如果原始请求路径是URL编码的，则在由该属性返回之前将对其进行解码。

类型:

STR

query_string

请求URI的查询字符串部分，不带前面的“？”性格。

类型:

STR

uri_template

与此请求匹配的路由的模板。可能是 None 如果请求尚未路由，则会出现这种情况 process_request() 中间件方法。也可能是 None 如果您的应用程序使用自定义路由引擎，并且引擎在解析路由时不提供URI模板。

类型:

STR

remote_addr

最接近wsgi服务器的客户端或代理的IP地址。

此属性由以下值确定： REMOTE_ADDR 在wsgi环境中，dict.由于此地址不是从HTTP头派生的，因此客户端和代理无法伪造它。

备注

如果应用程序位于一个或多个反向代理之后，则可以使用 access_route 以检索客户端的实际IP地址。

类型:

STR

access_route

原始客户机的IP地址，以及wsgi服务器前面的任何已知代理地址。

按优先顺序检查以下请求头以确定地址：

  • Forwarded

  • X-Forwarded-For

  • X-Real-IP

如果这些头都不可用，则 remote_addr 而是使用。

备注

每 RFC 7239 除了IPv4和IPv6地址之外，访问路由还可能包含“未知”和模糊标识符。

警告

头可以由任何客户端或代理伪造。小心使用此属性，并在使用前验证所有值。不要依赖访问路由来授权请求。

类型:

列表

forwarded

转发头的值，作为 falcon.Forwarded 对象，或 None 如果缺少标题。如果header值格式不正确，falcon将尽最大努力分析它所能。

（另见： RFC 7239, Section 4 ）

类型:

列表

date

日期标题的值，已转换为 datetime 实例。假定头值符合RFC 1123。

类型:

日期时间

auth

授权头的值，或 None 如果缺少标题。

类型:

STR

user_agent

用户代理头的值，或 None 如果缺少标题。

类型:

STR

referer

引用头的值，或 None 如果缺少标题。

类型:

STR

accept

Accept标头的值，或 '*/*' 如果标头丢失，则返回。

类型:

STR

client_accepts_json

True 如果accept头表明客户机愿意接收JSON，否则 False .

类型:

布尔

client_accepts_msgpack

True 如果accept头指示客户端愿意接收messagepack，否则 False .

类型:

布尔

client_accepts_xml

True 如果accept头表明客户机愿意接收XML，否则 False .

类型:

布尔

cookies

名称/值cookie对的dict。返回的对象应被视为只读，以避免意外的副作用。如果一个cookie在请求中出现多次，则只有遇到的第一个值才会在此处可用。

另请参阅： get_cookie_values()

类型:

双关语

content_type

内容类型标题的值，或 None 如果缺少标题。

类型:

STR

content_length

内容长度头的值已转换为 int 或 None 如果缺少标题。

类型:

利息

stream

类似文件的输入对象，用于读取请求体（如果有）。此对象提供对服务器数据流的直接访问，不可查找。为了避免意外的副作用，并为应用程序提供最大的灵活性，Falcon本身不会以任何方式缓冲或假脱机数据。

因为这个对象是由wsgi服务器本身提供的，而不是由falcon提供的，所以根据您的应用程序宿主的方式，它的行为可能会有所不同。例如，尝试读取超过预期的字节（由内容长度头决定）可能会或可能不会无限期阻塞。测试您的wsgi服务器以了解它的行为是一个好主意。

当需要请求正文，但没有提供时，这可能会特别有问题。在这种情况下，以下调用在某些WSGI服务器下被阻止：

# Blocks if Content-Length is 0
data = req.stream.read()

解决方法相当简单，如果详细的话：

# If Content-Length happens to be 0, or the header is
# missing altogether, this will not block.
data = req.stream.read(req.content_length or 0)

或者，当直接将流传递给使用者时，可能需要分支内容长度头的值：

if req.content_length:
    doc = json.load(req.stream)

如果性能成本较低，您可能希望使用 bounded_stream ，它包装本机wsgi输入对象以规范化其行为。

备注

如果使用 application/x-www-form-urlencoded 媒体类型，以及 auto_parse_form_urlencoded 设置了选项，框架将使用 stream 以便分析参数并将它们合并到查询字符串参数中。在这种情况下，流将留在EOF。

bounded_stream

文件式包装 stream 规范化不同wsgi服务器使用的本机输入对象之间的某些差异。特别地， bounded_stream 知道主体的预期内容长度，并且永远不会阻止越界读取，假定客户端在将数据传输到服务器时不会停止。

例如，当内容长度为0或标题完全丢失时，以下内容不会阻塞：

data = req.bounded_stream.read()

这也是安全的：

doc = json.load(req.bounded_stream)
media

属性，该属性充当 get_media() 。此别名为为3.0：：之前版本的框架构建的应用程序提供向后兼容性

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

对象

expect

Expect头的值，或 None 如果缺少标题。

类型:

STR

range

A两人组 tuple 从Range标头的值分析，或 None 如果标头丢失，则返回。

这两个成员对应于请求资源的第一个和最后一个字节位置，包括。负索引表示从资源末尾开始的偏移量，其中-1是最后一个字节，-2是第二个到最后一个字节，依此类推。

仅支持连续范围(例如，当访问属性时，“bytes=0-0，-1”将导致HTTPBadRequest异常。)

类型:

整数元组

range_unit

从范围标题值分析的范围单位，或 None 如果缺少标题

类型:

STR

if_match

if-match头的值，作为 falcon.ETag 对象或 None 如果缺少标题或其值为空。

此属性提供所有 entity-tags 在头段中，强和弱的顺序与头段中列出的顺序相同。

（另见： RFC 7232, Section 3.1 ）

类型:

列表

if_none_match

if none的值与头匹配，作为 falcon.ETag 对象或 None 如果缺少标题或其值为空。

此属性提供所有 entity-tags 在头段中，强和弱的顺序与头段中列出的顺序相同。

（另见： RFC 7232, Section 3.2 ）

类型:

列表

if_modified_since

if-modified-since头的值，或 None 如果缺少标题。

类型:

日期时间

if_unmodified_since

if-unmodified-since头的值，或 None 如果缺少标题。

类型:

日期时间

if_range

if范围标题的值，或 None 如果缺少标题。

类型:

STR

headers

请求中以短划线分隔的名称标准化为大写的原始HTTP标头。

备注

此属性与的ASGI版本不同 Request.headers 因为后者返回了 lowercase 名字。需要与WSGI和ASGI应用程序兼容的中间件，如跟踪和日志记录组件，应使用 headers_lower 取而代之的是。

警告

解析所有头文件以创建此字典是在第一次访问此属性时完成的，返回的对象应被视为只读。请注意，这种解析的代价可能很高，因此除非您需要此格式的所有标头，否则您应该改用 get_header() 方法或其中一个便利性属性来获取特定标头的值。

类型:

双关语

headers_lower

相同于 headers 只是标头名称被规范化为小写。

类型:

双关语

params

请求查询参数名称与其值的映射。如果参数在查询字符串中出现多次，则映射到该参数键的值将是按所看到的顺序排列的所有值的列表。

类型:

双关语

options

从应用处理程序传递的一组全局选项。

类型:

双关语

client_accepts(media_type)[源代码]

确定客户端是否接受给定的媒体类型。

参数:

media_type (str) -- 要检查的Internet媒体类型。

返回:

True 如果客户端在接受头中指示它接受指定的媒体类型。否则，返回 False .

返回类型:

bool

client_prefers(media_types)[源代码]

返回客户端的首选媒体类型，并给出几个选项。

参数:

media_types (iterable of str) -- 从中选择客户端首选类型的一个或多个Internet媒体类型。这个值 must 是字符串的可重复集合。

返回:

基于接受头的客户端首选媒体类型。退换商品 None 如果客户机不接受任何给定的类型。

返回类型:

str

返回在cookie头中为命名cookie提供的所有值。

（另见： Getting Cookies ）

参数:

name (str) -- cookie名称，区分大小写。

返回:

在已命名cookie的cookie头中指定的所有值的有序列表，或 None 如果请求中没有包含cookie。如果在头中多次指定cookie，则返回的值列表将保留单个值的顺序。 cookie-pair 在标题中。

返回类型:

list

get_header(name, required=False, default=None)[源代码]

检索给定头的原始字符串值。

参数:

name (str) -- 头名称，不区分大小写（例如，“内容类型”）。

关键字参数:

  • required (bool) -- 设置为 True 提高 HTTPBadRequest 而不是在找不到头时优雅地返回（默认 False ）

  • default (any) -- 如果找不到头，则返回的值（默认值 None ）

返回:

指定头的值（如果存在），或者如果找不到该头且不需要该头，则为默认值。

返回类型:

str

抛出:

HTTPBadRequest -- 在请求中找不到头，但它是必需的。

get_header_as_datetime(header, required=False, obs_date=False)[源代码]

返回以HTTP日期值作为日期时间的HTTP头。

参数:

name (str) -- 标题名称，不区分大小写（例如，“日期”）。

关键字参数:

  • required (bool) -- 设置为 True 提高 HTTPBadRequest 而不是在找不到头时优雅地返回（默认 False ）

  • obs_date (bool) -- 根据RFC7231支持OBS日期格式，例如：“星期日，1994年11月6日08:49:37 GMT”（默认 False ）

返回:

指定头的值（如果存在），或者 None 如果找不到头并且不需要。

返回类型:

datetime

抛出:

  • HTTPBadRequest -- 在请求中找不到头，但它是必需的。

  • HttpInvalidHeader -- 头包含格式不正确/无效的值。

get_header_as_int(header, required=False)[源代码]

检索给定头的int值。

参数:

name (str) -- 标头名称，不区分大小写(例如，‘Content-Long’)

关键字参数:

required (bool) -- 设置为 True 提高 HTTPBadRequest 而不是在找不到头时优雅地返回（默认 False ）

返回:

指定头的值（如果存在），或者 None 如果找不到头并且不需要。

返回类型:

int

抛出:

  • HTTPBadRequest -- 在请求中找不到头，但它是必需的。

  • HttpInvalidHeader -- 头包含格式不正确/无效的值。

get_media(default_when_empty=<object object>)[源代码]

返回请求流的反序列化形式。

第一次调用此方法时，将使用Content-Type标头和通过以下方式配置的媒体类型处理程序来反序列化请求流 falcon.RequestOptions 。结果将被缓存并在后续调用中返回：：

deserialized_media = req.get_media()

如果匹配的媒体处理程序在尝试反序列化请求正文时引发错误，则异常将向上传播到调用方。

另请参阅 媒体 有关媒体处理的详细信息，请参阅。

备注

什么时候 get_media 在具有空体的请求上调用时，Falcon将允许媒体处理程序尝试反序列化正文，并返回处理程序返回的值或传播处理程序引发的异常。要在处理程序出现异常时返回不同的值，请指定参数 default_when_empty 。

警告

此操作将在第一次调用请求流时使用该请求流并缓存结果。后续调用将只检索对象的缓存版本。

参数:

default_when_empty -- 当请求中没有正文并且媒体处理程序引发错误时返回的回退值(与默认JSON媒体处理程序的情况类似)。默认情况下，Falcon使用媒体处理程序返回的值或传播引发的异常(如果有)。该值不会缓存，并且将仅用于当前调用。

返回:

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

返回类型:

media (object)

get_param(name, required=False, store=None, default=None)[源代码]

以字符串形式返回查询字符串参数的原始值。

备注

如果使用 application/x-www-form-urlencoded 媒体类型，Falcon可以自动解析请求正文中的参数，并将它们合并到查询字符串参数中。要启用此功能，请设置 auto_parse_form_urlencoded 至 True 通过 App.req_options 。

但是，请注意， auto_parse_form_urlencoded 选项被认为在Falcon3.0版本中已被弃用，支持通过以下方式访问URL编码的表单 media ，并且可能会在将来的版本中将其删除。

另请参阅： 如何访问已发布的表单参数？

备注

与处理表单数据中多个键的方式类似，如果一个查询参数多次包含在查询字符串中，则只返回其中一个值，并且未定义是哪个值。此警告也适用于以下情况 auto_parse_qs_csv 并且将给定参数分配给逗号分隔的值列表(例如， foo=a,b,c )。

当一个参数预期有多个值时， get_param_as_list() 可以用来一次检索所有它们。

参数:

name (str) -- 参数名称，区分大小写（例如“sort”）。

关键字参数:

  • required (bool) -- 设置为 True 提高 HTTPBadRequest 而不是返回 None 当找不到参数时（默认 False ）

  • store (dict) -- A dict -类似于要在其中放置参数值的对象，但仅当存在该参数时。

  • default (any) -- 如果找不到参数，则返回给定值，而不是 None

返回:

作为字符串的参数值，或 None 如果找不到参数且不需要。

返回类型:

str

抛出:

HTTPBadRequest -- 请求中缺少必需的参数。

get_param_as_bool(name, required=False, store=None, blank_as_true=True, default=None)[源代码]

以布尔值的形式返回查询字符串参数的值。

此方法将无值参数视为标志。默认情况下，如果查询字符串中的参数没有提供值， True 假定并返回。如果参数完全丢失， None 与其他人一样返回 get_param_*() 方法，调用方可以根据需要轻松地将其视为不稳定。

支持以下布尔字符串：：

TRUE_STRINGS = ('true', 'True', 't', 'yes', 'y', '1', 'on')
FALSE_STRINGS = ('false', 'False', 'f', 'no', 'n', '0', 'off')
参数:

name (str) -- 参数名称，区分大小写（例如“detailed”）。

关键字参数:

  • required (bool) -- 设置为 True 提高 HTTPBadRequest 而不是返回 None 当找不到参数或参数不是可识别的布尔字符串时（默认 False ）

  • store (dict) -- A dict -类似于要在其中放置参数值的对象，但仅当找到该参数时（默认 None ）

  • blank_as_true (bool) -- 无值查询字符串参数被视为标志，从而 True 当存在此类参数时返回，并且 False 否则。要要求客户明确选择一个真实的值，请通过 blank_as_true=False 归来 False 当查询字符串中未指定值时。

  • default (any) -- 如果找不到参数，则返回该值，而不是 None .

返回:

参数的值（如果找到并可以转换为 bool .如果找不到参数，则返回 None 除非 required 是 True .

返回类型:

bool

抛出:

HTTPBadRequest -- 请求中缺少必需的参数，或无法转换为 bool .

get_param_as_date(name, format_string='%Y-%m-%d', required=False, store=None, default=None)[源代码]

返回查询字符串参数的值作为日期。

参数:

name (str) -- 参数名称，区分大小写（例如“id”）。

关键字参数:

  • format_string (str) -- 用于将参数值解析为日期的字符串。支持strptime（）识别的任何格式（默认 "%Y-%m-%d" ）

  • required (bool) -- 设置为 True 提高 HTTPBadRequest 而不是返回 None 当找不到参数时（默认 False ）

  • store (dict) -- A dict -类似于要在其中放置参数值的对象，但仅当找到该参数时（默认 None ）

  • default (any) -- 如果找不到参数，则返回给定值，而不是 None

返回:

参数的值（如果找到并可以转换为 date 根据提供的格式字符串。如果找不到参数，则返回 None 除非有要求 True .

返回类型:

datetime.date

抛出:

HTTPBadRequest -- 请求中缺少必需的参数，或者该值无法转换为 date .

get_param_as_datetime(name, format_string='%Y-%m-%dT%H:%M:%SZ', required=False, store=None, default=None)[源代码]

返回查询字符串参数的值作为日期时间。

参数:

name (str) -- 参数名称，区分大小写（例如“id”）。

关键字参数:

  • format_string (str) -- 用于将参数值解析为 datetime .支持strptime（）识别的任何格式（默认 '%Y-%m-%dT%H:%M:%SZ' ）

  • required (bool) -- 设置为 True 提高 HTTPBadRequest 而不是返回 None 当找不到参数时（默认 False ）

  • store (dict) -- A dict -类似于要在其中放置参数值的对象，但仅当找到该参数时（默认 None ）

  • default (any) -- 如果找不到参数，则返回给定值，而不是 None

返回:

参数的值（如果找到并可以转换为 datetime 根据提供的格式字符串。如果找不到参数，则返回 None 除非有要求 True .

返回类型:

datetime.datetime

抛出:

HTTPBadRequest -- 请求中缺少必需的参数，或者该值无法转换为 datetime .

get_param_as_float(name, required=False, min_value=None, max_value=None, store=None, default=None)[源代码]

以浮点形式返回查询字符串参数的值。

参数:

name (str) -- 参数名称，区分大小写（例如“limit”）。

关键字参数:

  • required (bool) -- 设置为 True 提高 HTTPBadRequest 而不是返回 None 当参数未找到或不是浮点值时（默认 False ）

  • min_value (float) -- 设置为此参数允许的最小值。如果找到参数且小于最小值，则 HTTPError 提高了。

  • max_value (float) -- 设置为此参数允许的最大值。如果找到参数且其值大于max_值，则 HTTPError 提高了。

  • store (dict) -- A dict -类似于要在其中放置参数值的对象，但仅当找到该参数时（默认 None ）

  • default (any) -- 如果找不到参数，则返回给定值，而不是 None

返回:

参数的值（如果找到并可以转换为 float .如果找不到参数，则返回 None 除非 required 是 True .

返回类型:

float

加薪
httpbadRequest:在请求中找不到参数，即使

它被要求在那里，或者被找到但无法转换为 float .如果参数值落在给定间隔之外，即该值必须在间隔内，则也会引发此问题：最小值<=值<=最大值，以避免触发错误。

get_param_as_int(name, required=False, min_value=None, max_value=None, store=None, default=None)[源代码]

以int形式返回查询字符串参数的值。

参数:

name (str) -- 参数名称，区分大小写（例如“limit”）。

关键字参数:

  • required (bool) -- 设置为 True 提高 HTTPBadRequest 而不是返回 None 当找不到参数或参数不是整数时（默认 False ）

  • min_value (int) -- 设置为此参数允许的最小值。如果找到参数且小于最小值，则 HTTPError 提高了。

  • max_value (int) -- 设置为此参数允许的最大值。如果找到参数且其值大于max_值，则 HTTPError 提高了。

  • store (dict) -- A dict -类似于要在其中放置参数值的对象，但仅当找到该参数时（默认 None ）

  • default (any) -- 如果找不到参数，则返回给定值，而不是 None

返回:

参数的值（如果找到并可以转换为 int .如果找不到参数，则返回 None 除非 required 是 True .

返回类型:

int

加薪
httpbadRequest:在请求中找不到参数，即使

它被要求在那里，或者被找到但无法转换为 int .如果参数值落在给定间隔之外，即该值必须在间隔内，则也会引发此问题：最小值<=值<=最大值，以避免触发错误。

get_param_as_json(name, required=False, store=None, default=None)[源代码]

返回查询字符串参数的解码JSON值。

给定一个JSON值，将其解码为适当的python类型（例如， dict ， list ， str ， int ， bool 等）

警告

如果 auto_parse_qs_csv 选项设置为 True (默认 False )时，框架将错误解释任何包含文字(非百分比编码)逗号的JSON值。如果查询字符串可能包含JSON，您可以使用JSON数组语法代替CSV作为解决办法。

参数:

name (str) -- 参数名称，区分大小写（例如“有效负载”）。

关键字参数:

  • required (bool) -- 设置为 True 提高 HTTPBadRequest 而不是返回 None 当找不到参数时（默认 False ）

  • store (dict) -- A dict -类似于要在其中放置参数值的对象，但仅当找到该参数时（默认 None ）

  • default (any) -- 如果找不到参数，则返回给定值，而不是 None

返回:

参数值（如果找到）。否则，返回 None 除非有要求 True .

返回类型:

dict

抛出:

HTTPBadRequest -- 请求中缺少必需的参数，或者无法将该值分析为JSON。

get_param_as_list(name, transform=None, required=False, store=None, default=None)[源代码]

以列表形式返回查询字符串参数的值。

列表项必须以逗号分隔，或者必须作为查询字符串ala中相同参数的多个实例提供 application/x-www-form-urlencoded .

备注

若要启用逗号分隔参数值的解释， auto_parse_qs_csv 选项必须设置为 True (默认 False )。

参数:

name (str) -- 参数名称，区分大小写（例如“id”）。

关键字参数:

  • transform (callable) -- 一个可选的转换函数，将列表中的每个元素作为输入 str 并输出一个转换后的元素以包含在将返回的列表中。例如，通过 int 将列表项转换为数字。

  • required (bool) -- 设置为 True 提高 HTTPBadRequest 而不是返回 None 当找不到参数时（默认 False ）

  • store (dict) -- A dict -类似于要在其中放置参数值的对象，但仅当找到该参数时（默认 None ）

  • default (any) -- 如果找不到参数，则返回给定值，而不是 None

返回:

参数的值(如果找到)。否则，返回 None 除非 必填项 是 True 。默认情况下将包括空列表元素，但此行为可以通过设置 keep_blank_qs_values 选项。例如，默认情况下，以下查询字符串都会导致 ['1', '', '3'] ：：Things=1&Things=&Things=3 Things=1，，3但是请注意，对于要解释为列表的上面的第二个示例字符串， auto_parse_qs_csv 选项必须设置为 True 。

返回类型:

list

抛出:

HTTPBadRequest -- 请求中缺少必需的参数，或者转换函数引发了 ValueError .

get_param_as_uuid(name, required=False, store=None, default=None)[源代码]

将查询字符串参数的值作为UUID返回。

要转换的值必须符合RFC 4122的标准UUID字符串表示形式。例如，以下字符串都是有效的：

# Lowercase
'64be949b-3433-4d36-a4a8-9f19d352fee8'

# Uppercase
'BE71ECAA-F719-4D42-87FD-32613C2EEB60'

# Mixed
'81c8155C-D6de-443B-9495-39Fa8FB239b5'
参数:

name (str) -- 参数名称，区分大小写（例如“id”）。

关键字参数:

  • required (bool) -- 设置为 True 提高 HTTPBadRequest 而不是返回 None 当找不到参数或参数不是UUID时（默认 False ）

  • store (dict) -- A dict -类似于要在其中放置参数值的对象，但仅当找到该参数时（默认 None ）

  • default (any) -- 如果找不到参数，则返回给定值，而不是 None

返回:

参数的值（如果找到并可以转换为 UUID .如果找不到参数，则返回 default （默认） None ）除非 required 是 True .

返回类型:

UUID

加薪
httpbadRequest:在请求中找不到参数，即使

它必须在那里，或者找到它，但无法转换为 UUID .

has_param(name)[源代码]

确定查询字符串参数是否已存在。

参数:

name (str) -- 参数名称，区分大小写（例如“sort”）。

返回:

True 如果找到参数，或 False 如果找不到参数。

返回类型:

bool

log_error(message)[源代码]

将错误消息写入服务器日志。

预先向消息发送时间戳和请求信息，并将结果写入WSGi服务器的错误流 (wsgi.error ）

参数:

message (str) -- 问题描述。

class falcon.Forwarded[源代码]

表示已分析的转发头。

（另见： RFC 7239, Section 4 ）

src

“for”参数的值，或 None 如果参数不存在。标识向代理发出请求的节点。

类型:

STR

dest

“by”参数的值，或 None 如果参数不存在。标识代理的面向客户端的接口。

类型:

STR

host

“主机”参数的值，或 None 如果参数不存在。提供代理接收到的主机请求头字段。

类型:

STR

scheme

“proto”参数的值，或 None 如果参数不存在。指示用于向代理发出请求的协议。

类型:

STR

class falcon.stream.BoundedStream(stream: BinaryIO, stream_len: int)[源代码]

包装 wsgi.input 流，以使它们更健壮。

socket._fileobject 和 io.BufferedReader 有时用于实现 wsgi.input 。然而，应用程序开发人员经常被这样一个事实所灼伤，即 read() 如果没有传递大小，或者传递给这些对象的大小大于请求的内容长度，则挡路方法会无限期地使用该方法。

这个类将正常化 wsgi.input 在上述情况下，通过实现非阻塞行为来实现WSGI服务器之间的行为。调用方不允许读取超过请求中Content-Length标头指定的字节数。

参数:

  • stream -- 实例 socket._fileobject 从… environ['wsgi.input']

  • stream_len -- 流的预期内容长度。

eof

True 如果没有更多数据可从流中读取，则为 False 。

类型:

布尔

is_exhausted

的别名已弃用 eof 。

类型:

布尔

exhaust(chunk_size: int = 65536) → None[源代码]

排干这条小溪。

这将消耗剩余的所有数据，直到达到限制。

参数:

chunk_size (int) -- 区块的大小(默认值：64 KB)。它将读取该块，直到流耗尽。

next() → bytes

实施下一步(自我)。

read(size: Optional[int] = None) → bytes[源代码]

从小溪上读。

参数:

size (int) -- 要读取的最大字节数/字符数。默认为读取到EOF为止。

返回:

从流中读取的数据。

返回类型:

bytes

readable() → bool[源代码]

返回 True 一直都是。

readline(limit: Optional[int] = None) → bytes[源代码]

从小溪里读一句话。

参数:

limit (int) -- 要读取的最大字节数/字符数。默认为读取到EOF为止。

返回:

从流中读取的数据。

返回类型:

bytes

readlines(hint: Optional[int] = None) → List[bytes][源代码]

从小溪中读行。

参数:

hint (int) -- 要读取的最大字节数/字符数。默认为读取到EOF为止。

返回:

从流中读取的数据。

返回类型:

bytes

seekable() → bool[源代码]

返回 False 一直都是。

writable() → bool[源代码]

返回 False 一直都是。

write(data: bytes) → None[源代码]

始终引发ioerror；不支持写入。

响应

class falcon.Response(options=None)[源代码]

表示对客户端请求的HTTP响应。

备注

Response 并不意味着由响应者直接实例化。

关键字参数:

options (dict) -- 从应用处理程序传递的一组全局选项。

status

HTTP状态代码或行(例如， '200 OK' )。可以将其设置为以下项的成员 http.HTTPStatus HTTP状态行串或字节串(例如， '200 OK' )，或一个 int 。

备注

Falcon框架本身为通用状态代码提供了许多常量。它们都以 HTTP_ 前缀，如： falcon.HTTP_204 。(另请参阅： 状态代码 。)

类型:

友联市 [str,int]

status_code

标准化的HTTP状态代码 status 。当将代码分配给该属性时， status 更新，反之亦然。当需要在中间件中签入属于某一类的代码时，状态代码非常有用，例如：：

if resp.status_code >= 400:
    log.warning(f'returning error response: {resp.status_code}')
类型:

利息

media

通过配置的媒体处理程序支持的可序列化对象 falcon.RequestOptions .

备注

另请参阅 媒体 有关媒体处理的详细信息，请参阅。

类型:

对象

text

表示响应内容的字符串。

备注

Falcon将在响应中将给定文本编码为UTF-8。如果内容已经是字节字符串，请使用 data 属性来代替(这样速度更快)。

类型:

STR

data

表示响应内容的字节字符串。

使用此属性代替 text 当您的内容已经是字节字符串(类型为 bytes )。另请参阅下面的注释。

警告

始终使用 text 属性，或先将其编码为 bytes 在使用 data 属性，以确保在HTTP响应中正确编码Unicode字符。

类型:

字节

stream

一个类似文件的对象 read() 方法，该方法采用可选的大小参数并返回一个字节块或一个iterable对象，表示响应内容，并将块作为字节字符串生成。Falcon将使用 wsgi.file_wrapper 如果由wsgi服务器提供，为了有效地提供类似文件的对象。

备注

如果将流设置为需要资源清理的可ITerable对象，则可以实现close（）方法。完成请求后将调用close（）方法。

context

空对象，用于保存特定于应用程序的响应的任何数据（在其属性中）（例如，会话对象）。falcon本身在初始化后不会与该属性交互。

备注

2.0中的新功能： 默认设置 context_type (见下文)已从 dict 传递特定于响应的数据的首选方式是现在直接在 context 对象。例如：：

resp.context.cache_strategy = 'lru'
类型:

对象

context_type

类变量，该变量确定用于初始化 context 属性。默认情况下，框架将实例化裸对象(裸对象的实例 falcon.Context 类)。但是，您可以通过创建自定义子类 falcon.Response ，然后将该新类传递给 falcon.App() 通过后者的方式 response_type 参数。

备注

当超越 context_type 使用工厂函数（与类相反），该函数的调用方式与当前响应实例的方法类似。因此，第一个参数是响应实例本身（self）。

类型:

类

options

从应用处理程序传递的一组全局选项。

类型:

双关语

headers

为响应设置的所有头文件的副本，无cookie。请注意，每次引用此属性时都会创建并返回一个新副本。

类型:

双关语

complete

设置为 True 从中间件方法内部向框架发出信号，表示请求处理应该短路（另请参见 Middleware ）

类型:

布尔

property accept_ranges

设置“接受范围”标题。

“接受范围”头字段向客户端指示目标资源支持哪些范围单位（例如“字节”）。

如果目标资源不支持范围请求，则可以将头设置为“无”，以建议客户端不要尝试任何此类请求。

备注

“none”是文本字符串，而不是python的内置字符串 None 类型。

append_header(name, value)[源代码]

设置或附加此响应的头。

如果头已经存在，新值通常会附加到头上，用逗号分隔。此规则的显著例外是set cookie，在这种情况下，响应中将包含每个值的单独标题行。

备注

虽然可以使用此方法有效地将原始集cookie头附加到响应中，但您可能会发现 set_cookie() 更方便。

参数:

  • name (str) -- 标头名称(不区分大小写)。名称只能包含US-ASCII字符。

  • value (str) -- 标头的值。与标头的名称一样，该值只能包含US-ASCII字符。

将链接标头附加到响应。

（另见： RFC 5988, Section 1 ）

备注

重复调用此方法将使每个链接附加到链接头值，用逗号分隔。

参数:
关键字参数:

  • title (str) -- 链接目标的可读标签（默认 None ）。如果标题包含非ASCII字符，则需要使用 title_star 相反，或者使用 title 和Unicode版本使用 title_star .

  • title_star (tuple of str) -- 描述链接目标的本地化标题(默认 None )。该值必须是具有两个成员的元组，其形式为( language-tag ， text )，其中 language-tag 中定义的标准语言标识符。 RFC 5646, Section 2.1 ，以及 text 是Unicode字符串。。。注：： language-tag 可以是空字符串，在这种情况下，客户端将从当前请求的一般上下文中采用该语言。。。注：： text 将始终编码为UTF-8。

  • anchor (str) -- 用不同的URI重写上下文IRI（默认为无）。默认情况下，链接的上下文IRI只是请求资源的IRI。提供的值可能是相对URI。

  • hreflang (str or iterable) -- 一个单人间 language-tag ，或者 list 或 tuple 为客户机提供一个提示，提示客户机跟踪链接的结果所使用的语言。可以给出标记列表，以向客户机指示目标资源可以使用多种语言。

  • type_hint (str) -- 提供取消链接引用结果的媒体类型提示（默认 None ）。如RFC5988中所述，这只是一个提示，不会覆盖在链接之后返回的内容类型头。

  • crossorigin (str) -- 确定如何处理跨域请求。可以接受“”匿名“”或“”Use-Credentials“”或“None”的值。“”(请参阅：https://www.w3.org/TR/html50/infrastructure.html#cors-settings-attribute)

  • link_extension (iterable) -- 提供其他自定义属性，如中所述 RFC 8288, Section 3.4.2. 可迭代对象的每个成员都必须是两个元组，形式为( param ， value )。(请参阅：https://datatracker.ietf.org/doc/html/rfc8288#section-3.4.2)

property cache_control

设置缓存控制头。

用于设置用作缓存控制头值的缓存指令列表。列表将与“”联接，以生成标题的值。

property content_length

设置内容长度标题。

此属性可用于在您实际没有提供响应正文时或在流式传输响应时响应HEAD请求。如果 text 属性或 data 属性，则框架将强制Content-Length为给定文本字节的长度。因此，只有在不使用这些属性时才需要手动设置内容长度。

备注

在响应内容是流(可读的类似文件的对象)的情况下，Falcon不会向服务器提供Content-Length标头，除非 content_length 是显式设置的。因此，在这种情况下，服务器可以选择使用分块编码。

property content_location

设置内容位置标题。

该值将按照RFC 3986进行URI编码。如果正在设置的值已经是uri编码的，则应首先对其进行解码，或者应使用set_header方法手动设置头。

property content_range

用于构造内容范围标题值的元组。

元组的形式是（ 开始 ， end ， 长度 ， [unit] 在哪里 开始 和 end 指定范围（包括），以及 长度 是总长度，或' * '如果未知。你可以通过 int 对于这些数字（不需要转换为 str 事先）。可选值 unit 描述范围单位并默认为“字节”

备注

您只需要使用替代形式'bytes' * /1234”，用于使用状态“416 range not satisfable”的响应。在这种情况下，提高 falcon.HTTPRangeNotSatisfiable 会做正确的事。

（另见： RFC 7233, Section 4.2 ）

property content_type

设置内容类型标题。

这个 falcon 模块为常见的媒体类型提供许多常量，包括 falcon.MEDIA_JSON ， falcon.MEDIA_MSGPACK ， falcon.MEDIA_YAML ， falcon.MEDIA_XML ， falcon.MEDIA_HTML ， falcon.MEDIA_JS ， falcon.MEDIA_TEXT ， falcon.MEDIA_JPEG ， falcon.MEDIA_PNG 和 falcon.MEDIA_GIF .

delete_header(name)[源代码]

删除以前为此响应设置的头。

如果之前未设置头，则不执行任何操作（不会引发任何错误）。否则，将从响应中删除为头设置的所有值。

请注意，调用此方法等同于将相应的头属性（当所述属性可用时）设置为 None . 例如：：

resp.etag = None

警告

此方法不能与set cookie头一起使用。相反，使用 unset_cookie() 删除一个cookie并确保用户代理的数据副本也过期。

参数:

name (str) -- 标头名称(不区分大小写)。名称只能包含US-ASCII字符。

抛出:

ValueError -- name 不能 'Set-Cookie' .

property downloadable_as

使用给定的文件名设置内容处置头。

该值将用于 filename 指令。例如，给定 'report.pdf' ，则Content-Disposition标头将设置为： 'attachment; filename="report.pdf"' 。

按规定 RFC 6266 建议，非ASCII文件名将使用 filename* 指令，而 filename 将遏制美国的ASCII退路。

property etag

设置etag头。

etag头将用双引号括起来 "value" 以防用户未通过。

property expires

设置Expires头。设置为A datetime （UTC）实例。

备注

Falcon将格式化 datetime 作为HTTP日期字符串。

get_header(name, default=None)[源代码]

检索给定头的原始字符串值。

通常，当一个头有多个值时，它们将作为一个逗号分隔的字符串返回。但是，set cookie头不支持此格式，因此尝试检索它将引发错误。

参数:

name (str) -- 头名称，不区分大小写。必须是类型 str 或 StringType ，并且只能在使用宽字符的平台上使用字符值0x00到0xFF。

关键字参数:

default -- 如果找不到头，则返回的值（默认值 None ）

抛出:

ValueError -- 已请求“set cookie”头的值。

返回:

指定头的值（如果设置）或默认值（如果未设置）。

返回类型:

str

property last_modified

设置上次修改的标题。设置为A datetime （UTC）实例。

备注

Falcon将格式化 datetime 作为HTTP日期字符串。

property location

设置位置标题。

该值将按照RFC 3986进行URI编码。如果正在设置的值已经是uri编码的，则应首先对其进行解码，或者应使用set_header方法手动设置头。

render_body()[源代码]

获取响应正文的原始字节串内容。

此方法返回HTTP响应正文的原始数据，同时考虑 text ， data ，以及 media 属性。

备注

此方法忽略 stream ；调用方必须直接检查和处理该属性。

返回:

属性的UTF-8编码值 text 属性(如果设置)。否则， data 属性(如果设置)，或者最终返回 media 属性。如果没有设置这些属性， None 返回。

返回类型:

bytes

property retry_after

设置“重试后”头。

预期值是秒的整数，用作头的值。不支持HTTP日期语法。

设置响应cookie。

备注

可以多次调用此方法以向响应中添加一个或多个cookie。

参见

要了解有关设置cookie的更多信息，请参阅 Setting Cookies .下面列出的参数与中定义的参数相对应。 RFC 6265 .

参数:

  • name (str) -- cookie名称

  • value (str) -- cookie值

关键字参数:

  • expires (datetime) -- 指定cookie应在何时过期。默认情况下，当用户代理退出时，cookie将过期。（另见： RFC 6265, Section 4.1.2.1 ）

  • max_age (int) -- 定义cookie的生存期（秒）。默认情况下，当用户代理退出时，cookie将过期。如果两者都是 max_age and expires are set, the latter is ignored by the user agent. .. note:: Coercion to int is attempted if provided with float or str. (See also: RFC 6265, Section 4.1.2.2 ）

  • domain (str) -- 将Cookie限制为特定域和该域的任何子域。默认情况下，用户代理只向源站返回cookie。覆盖此默认行为时，指定的域必须包括源站。否则，用户代理将拒绝该cookie。。。注意：：Cookie不提供端口隔离，因此域不应该提供端口隔离。(另请参阅： RFC 6265, Section 8.5 )(另请参阅： RFC 6265, Section 4.1.2.3 )

  • path (str) -- 将cookie定位到给定的路径以及该路径下的任何子目录（将“/”字符解释为目录分隔符）。如果cookie未指定路径，则用户代理将默认为请求的URI的路径组件。我是说…警告：：用户代理接口并不总是按路径隔离cookie，因此不应将其视为有效的安全措施。（另见： RFC 6265, Section 4.1.2.4 ）

  • secure (bool) -- 如果后续请求是通过HTTPS发出的，则指示客户端仅在后续请求中返回Cookie(默认值： True )。这可以防止攻击者读取敏感的Cookie数据。。。注意：：此参数的默认值通常为 True ，但可以通过设置 secure_cookies_by_default 通过 App.resp_options 。。。警告：：对于 secure cookie attribute to be effective, your application will need to enforce HTTPS. (See also: RFC 6265, Section 4.1.2.5 )

  • http_only (bool) -- HttpOnly属性将Cookie的范围限制为HTTP请求。具体地说，该属性指示用户代理在通过“非HTTP”API提供对cookie的访问时省略cookie。这旨在减少某些形式的跨站点脚本编写。(默认值： True )..注意：：浏览器中的javascript脚本看不到HttpOnly Cookie。它们通过javascript自动发送到服务器 XMLHttpRequest 或 Fetch 请求。(另请参阅： RFC 6265, Section 4.1.2.6 )

  • same_site (str) -- 通过限制用户代理将Cookie附加到请求的时间来帮助抵御CSRF攻击。当设置为时 'Strict' ，Cookie将只随“同站点”请求一起发送。如果值为 'Lax' ，Cookie将随同站点请求和“跨站点”顶级导航一起发送。如果值为 'None' ，Cookie将随同站点和跨站点请求一起发送。最后，如果未在Cookie上设置此属性，则该属性将被视为已设置为 'None' 。(另请参阅： Same-Site RFC Draft )

抛出:

  • KeyError -- name 不是有效的cookie名称。

  • ValueError -- value 不是有效的cookie值。

set_header(name, value)[源代码]

将此响应的头设置为给定值。

警告

调用此方法将覆盖已为此头设置的任何值。若要附加此头的附加值，请使用 append_header() 相反。

警告

此方法不能用于设置cookie；相反，请使用 append_header() 或 set_cookie() .

参数:

  • name (str) -- 标头名称(不区分大小写)。名称只能包含US-ASCII字符。

  • value (str) -- 标头的值。与标头的名称一样，该值只能包含US-ASCII字符。

抛出:

ValueError -- name 不能 'Set-Cookie' .

set_headers(headers)[源代码]

一次设置多个标题。

此方法可用于同时设置原始头名称和值的集合。

警告

调用此方法将覆盖给定头的任何现有值。如果提供了包含同一头的多个实例的列表，则只使用最后一个值。要为给定头的响应添加多个值，请参见 append_header() .

警告

此方法不能用于设置cookie；相反，请使用 append_header() 或 set_cookie() .

参数:

headers (Iterable[[str, str]]) -- 一个可迭代的 [name, value] 两个成员的可迭代对象，或实现 items() 方法。两者都有 name 和 价值 必须是类型 str 并且仅包含US-ASCII字符。。。注意：：Falcon处理可迭代的元组的速度比DICT略快。

抛出:

ValueError -- headers 不是一个 dict 或 list 的 tuple 或 Iterable[[str, str]] 。

set_stream(stream, content_length)[源代码]

两者都设置 stream 和 content_length 。

尽管 stream 和 content_length 可以直接设置属性，使用此方法可确保 content_length 当预先知道流的长度时，不会意外地忽略。与单独设置属性相比，使用此方法的性能也略高一些。

备注

如果流长度未知，可以设置 stream 直接，然后忽略 content_length 。在这种情况下，ASGI服务器可以选择使用分块编码或PEP-3333建议的其他策略之一。

参数:

  • stream -- 类似对象的可读文件。

  • content_length (int) -- 流的长度，用于响应中的Content-Length头。

取消设置响应中的cookie。

清除cookie的内容，并指示用户代理立即终止其自己的cookie副本。

备注

现代浏览器对没有设置“Same-site”Cookie属性的Cookie进行限制。为此，此属性设置为 'Lax' 用这种方法。

(另请参阅： Same-Site warnings )

警告

为了成功删除cookie，路径和域必须与创建cookie时使用的值匹配。

参数:

name (str) -- cookie名称

关键字参数:

  • samesite (str) -- 允许覆盖未设置Cookie的默认‘lax’Same_Site设置。

  • domain (str) -- 将Cookie限制为特定域和该域的任何子域。默认情况下，用户代理只向源站返回cookie。覆盖此默认行为时，指定的域必须包括源站。否则，用户代理将拒绝该cookie。。。注意：：Cookie不提供端口隔离，因此域不应该提供端口隔离。(另请参阅： RFC 6265, Section 8.5 )(另请参阅： RFC 6265, Section 4.1.2.3 )

  • path (str) -- 将cookie定位到给定的路径以及该路径下的任何子目录（将“/”字符解释为目录分隔符）。如果cookie未指定路径，则用户代理将默认为请求的URI的路径组件。我是说…警告：：用户代理接口并不总是按路径隔离cookie，因此不应将其视为有效的安全措施。（另见： RFC 6265, Section 4.1.2.4 ）

property vary

用于vary头的值。

将此属性设置为头名称的ITerable。对于单个星号或字段值，只需传递一个元素 list 或 tuple .

响应中的“vary”头字段描述除了方法、主机头字段和请求目标之外，请求消息的哪些部分可能影响源服务器选择和表示此响应的过程。该值由单个星号（“*”）或头字段名称列表（不区分大小写）组成。

（另见： RFC 7231, Section 7.1.4 ）

property viewable_as

使用给定的文件名设置内联Content-Disposal头。

该值将用于 filename 指令。例如，给定 'report.pdf' ，则Content-Disposition标头将设置为： 'inline; filename="report.pdf"' 。

按规定 RFC 6266 建议，非ASCII文件名将使用 filename* 指令，而 filename 将遏制美国的ASCII退路。

在 3.1 版本加入.