WSGI请求和响应

的实例 falcon.Requestfalcon.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) -- 从API处理程序传递的全局选项集。

env

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

类型

双关语

context

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

注解

2.0中的新功能: 默认值 context_type (见下文)已从dict更改为bare类,现在传递请求特定数据的首选方法是直接在 context 对象,例如:

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

对象

context_type

类变量,确定用于初始化的工厂或类型 context 属性。默认情况下,框架将实例化裸机对象(裸机的实例 falcon.Context 类)。但是,可以通过创建自定义子类 falcon.Request 然后将新类传递给 falcon.API() 通过后者 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

用于请求的端口。如果请求URI未指定端口,则返回给定架构的默认端口(HTTP为80,HTTPS为443)。

类型

利息

netloc

返回请求URL的“host:port”部分。如果端口是URL模式的默认端口(HTTP为80,HTTPS为443),则可能会发出命令。

类型

STR

subdomain

主机名中最左边的(即最具体的)子域。如果只给出一个域名, subdomainNone .

注解

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

类型

STR

app

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

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

类型

STR

uri

请求的完全限定的URI。

类型

STR

url

Alias uri .

类型

STR

forwarded_uri

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

类型

STR

relative_uri

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

类型

STR

prefix

请求URI的前缀,包括方案、主机和wsgi应用程序(如果有)。

类型

STR

forwarded_prefix

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

类型

STR

path

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

注解

req.path 可以设置为新值 process_request() 中间件方法以影响路由。如果原始请求路径是URL编码的,则将在该属性返回之前对其进行解码。如果应用程序要将此属性用于任何上游请求,则在发出请求之前,必须对路径中的任何非URL安全字符进行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

接受头的值,或' / '如果缺少标题。

类型

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

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

类型

利息

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)
expect

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

类型

STR

media

返回请求流的反序列化形式。调用时,它将尝试使用Content-Type头和通过配置的媒体类型处理程序反序列化请求流。 falcon.RequestOptions .

媒体 有关媒体处理的更多信息。

警告

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

类型

对象

range

2人制 tuple 从范围头的值分析。

这两个成员对应于请求资源的第一个和最后一个字节位置,包括。负索引表示从资源末尾开始的偏移量,其中-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头具有规范的短划线分隔名称。在第一次访问该属性时,解析所有头以创建该dict,并且返回的对象应被视为只读对象。请注意,这种解析可能代价高昂,因此除非您需要这种格式的所有头,否则应该使用 get_header() 方法或便利属性之一,以获取特定头的值。

类型

双关语

params

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

类型

双关语

options

从API处理程序传递的全局选项集。

类型

双关语

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_param(name, required=False, store=None, default=None)

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

注解

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

注解

与处理表单数据中多个键的方式类似,如果为查询参数分配了一个以逗号分隔的值列表(例如, 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', 'yes', '1', 'on')
FALSE_STRINGS = ('false', 'False', 'no', '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 除非 requiredTrue .

返回类型

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 除非 requiredTrue .

返回类型

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 除非 requiredTrue .

返回类型

int

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

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

get_param_as_json(name, required=False, store=None, default=None)

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

给定一个JSON值,将其解码为适当的python类型(例如, dictliststrintbool 等)

参数

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 .

参数

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

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

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

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

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

返回

参数值(如果找到)。否则,返回 None 除非要求为真。将丢弃空列表元素。例如,以下查询字符串都会导致 ['1', '3'] ::things=1,,3 things=1&things=&things=3

返回类型

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 )除非 requiredTrue .

返回类型

UUID

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

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

has_param(name)

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

参数

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

返回

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

返回类型

bool

log_error(message)

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

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

参数

message (str or unicode) -- 问题的描述。在python 2上, unicode 将转换为UTF-8。

class falcon.Forwarded

表示已分析的转发头。

(另见: RFC 7239, Section 4

src

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

类型

STR

dest

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

类型

STR

host

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

类型

STR

scheme

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

类型

STR

响应

class falcon.Response(options=None)

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

注解

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

关键字参数

options (dict) -- 从API处理程序传递的全局选项集。

status

HTTP状态行(例如“200 OK”)。Falcon需要完整的状态行,而不仅仅是代码(例如200)。这种设计使得框架更高效,因为它在组成WSGi响应时不需要进行任何类型的转换或查找。

如果未显式设置,则状态默认为“200 OK”。

注解

Falcon为公共状态代码提供了许多常量。他们都是从 HTTP_ 前缀,如: falcon.HTTP_204 .

类型

STR

media

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

媒体 有关媒体处理的更多信息。

类型

对象

body

表示响应内容的字符串。

如果设置为Unicode类型 (unicode 在python 2中,或者 str 在python 3中,falcon将在响应中将文本编码为utf-8。如果内容已经是字节字符串,请使用 data 改为属性(更快)。

类型

STR或Unicode

data

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

使用此属性代替 body 当内容已经是字节字符串时 (strbytes 在python 2中,或者简单地 bytes 在python 3中)。另请参见下面的注释。

注解

在python 2.x下,如果您的内容是 str ,使用 data 属性而不是 body 是最有效的方法。但是,如果您的文本是类型 unicode ,您需要使用 body 改为属性。

在python 3.x下,另一方面,2.x str 可以认为类型已被以前的 unicode 类型,因此您需要始终使用 body 用于确保在HTTP响应中正确编码Unicode字符的字符串的属性。

类型

字节

stream

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

注解

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

stream_len

的别名已弃用 content_length .

类型

利息

context

字典,用于保存特定于应用程序的响应的任何数据。falcon本身在初始化后不会与该属性交互。

类型

双关语

context

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

注解

2.0中的新功能: 默认值 context_type (见下文)已从dict更改为裸类,现在传递响应特定数据的首选方法是直接在 context 对象,例如:

resp.context.cache_strategy = 'lru'
类型

对象

context_type

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

注解

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

类型

options

从API处理程序传递的全局选项集。

类型

双关语

headers

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

类型

双关语

complete

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

类型

布尔

property accept_ranges

设置“接受范围”标题。

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

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

注解

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

向响应添加链接头。

(另见: RFC 5988, Section 1

注解

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

注解

如RFC5988所定义,目前还不支持所谓的“链接扩展”元素。另见第288期。

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

  • title_star (tuple of str) -- 描述链接目标的本地化标题(默认 None )。值必须是两个成员的元组,其形式为( language-tagtext 在哪里 language-tag 是在中定义的标准语言标识符 RFC 5646, Section 2.1text 是Unicode字符串。我是说…注: language-tag 可能是空字符串,在这种情况下,客户机将采用当前请求的一般上下文中的语言。我是说…注: text 将始终编码为UTF-8。如果字符串包含非ASCII字符,则应将其作为 unicode 类型字符串(需要python 2中的“u”前缀)。

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

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

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

append_header(name, value)

设置或附加此响应的头。

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

注解

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

参数
  • name (str) -- 头名称(不区分大小写)。下面为标题值指出的限制也适用于此处。

  • value (str) -- 标题的值。必须可转换为 str 或属于类型 strStringType .字符串只能包含US-ASCII字符。在python 2.x下, unicode 也可以接受类型,尽管这样的字符串也仅限于US-ASCII。

property cache_control

设置缓存控制头。

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

property content_length

设置内容长度标题。

当您没有实际提供响应主体或流式处理响应时,此属性可用于响应头请求。如果 body 属性或 data 属性设置在响应上,框架将强制内容长度为给定正文字节的长度。因此,只有在不使用这些属性时才需要手动设置内容长度。

注解

如果响应内容是流(类似对象的可读文件),那么falcon将不会向wsgi服务器提供内容长度头,除非 content_length 是显式设置的。因此,服务器可以选择使用分块编码或PEP-3333建议的其他策略之一。

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_JSONfalcon.MEDIA_MSGPACKfalcon.MEDIA_YAMLfalcon.MEDIA_XMLfalcon.MEDIA_HTMLfalcon.MEDIA_JSfalcon.MEDIA_TEXTfalcon.MEDIA_JPEGfalcon.MEDIA_PNGfalcon.MEDIA_GIF .

delete_header(name)

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

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

请注意,调用此方法等同于将相应的头属性(当所述属性可用时)设置为 None . 例如::

resp.etag = None

警告

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

参数

name (str) -- 头名称(不区分大小写)。必须是类型 strStringType 并且只包含US-ASCII字符。在python 2.x下, unicode 也可以接受类型,尽管这样的字符串也仅限于US-ASCII。

引发

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

property downloadable_as

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

该值将用于 文件名 指令。例如,给定 'report.pdf' ,内容处置头将设置为: 'attachment; filename="report.pdf"' .

property etag

设置etag头。

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

property expires

设置Expires头。设置为A datetime (UTC)实例。

注解

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

get_header(name, default=None)

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

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

参数

name (str) -- 头名称,不区分大小写。必须是类型 strStringType ,并且只能在使用宽字符的平台上使用字符值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方法手动设置头。

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。(另见: 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 通过 API.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) -- 指示客户端仅使用未脚本化的HTTP请求传输cookie(默认: True )。这是为了减轻一些形式的跨站点脚本编写。(另见: RFC 6265, Section 4.1.2.6

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

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

set_header(name, value)

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

警告

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

警告

此方法不能用于设置cookie;相反,请使用 append_header()set_cookie() .

参数
  • name (str) -- 头名称(不区分大小写)。下面为标题值指出的限制也适用于此处。

  • value (str) -- 标题的值。必须可转换为 str 或属于类型 strStringType .字符串只能包含US-ASCII字符。在python 2.x下, unicode 也可以接受类型,尽管这样的字符串也仅限于US-ASCII。

引发

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

set_headers(headers)

一次设置多个标题。

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

警告

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

警告

此方法不能用于设置cookie;相反,请使用 append_header()set_cookie() .

参数

headers (dict or list) -- 要设置的标题名称和值的字典,或 list 的( name价值 )元组。两者都有 name价值 必须是类型 strStringType 并且只包含US-ASCII字符。在python 2.x下, unicode 也可以接受类型,尽管这样的字符串也仅限于US-ASCII。我是说…注意:falcon处理元组列表的速度比dict略快。

引发

ValueError -- headers 不是一个 dictlist 属于 tuple .

set_stream(stream, content_length)

设置两者的方便方法 streamcontent_length .

虽然 streamcontent_length 可以直接设置属性,使用此方法可以确保 content_length 当提前知道水流长度时,不会被意外忽略。与单独设置属性相比,使用此方法的性能也稍高一些。

注解

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

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

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

property stream_len

设置内容长度标题。

当您没有实际提供响应主体或流式处理响应时,此属性可用于响应头请求。如果 body 属性或 data 属性设置在响应上,框架将强制内容长度为给定正文字节的长度。因此,只有在不使用这些属性时才需要手动设置内容长度。

注解

如果响应内容是流(类似对象的可读文件),那么falcon将不会向wsgi服务器提供内容长度头,除非 content_length 是显式设置的。因此,服务器可以选择使用分块编码或PEP-3333建议的其他策略之一。

在响应中取消设置cookie

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

警告

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

property vary

用于vary头的值。

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

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

(另见: RFC 7231, Section 7.1.4