ASGI请求和响应

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

import falcon.asgi


class Resource:

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


# -- snip --


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

请求

class falcon.asgi.Request(scope, receive, first_event=None, options=None)[源代码]

表示客户端的HTTP请求。

备注

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

参数:

  • scope (dict) -- 从服务器传入的ASGI HTTP连接作用域(另请参阅： Connection Scope )。

  • receive (awaitable) -- Asgi可等待调用，它将在新的事件字典可用时生成一个新的事件字典。

关键字参数:

  • first_event (dict) -- 从客户端接收的第一个ASGI事件(如果已预加载)(默认 None )。

  • options (falcon.request.RequestOptions) -- 从应用处理程序传递的一组全局请求选项。

scope

对从服务器传入的ASGI HTTP连接作用域的引用(另请参阅： Connection Scope )。

类型:

双关语

context

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

备注

当使用默认上下文类型时，传递特定于请求的数据的首选方式是直接在 context 对象。例如：：

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

对象

context_type

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

备注

当覆盖时 context_type 对于工厂函数(与类相对)，该函数的调用方式类似于当前 Request 实例。因此第一自变量是请求实例本身(即， self )。

类型:

类

scheme

用于请求的URL方案。其中之一 'http' ， 'https' ， 'ws' ，或 'wss' 。默认为 'http' 对于 http 作用域，或 'ws' 对于 websocket 范围，当ASGI服务器不将方案包括在连接范围中时。

备注

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

类型:

STR

is_websocket

设置为 True 如果此请求是作为WebSocket握手的一部分发出的。

类型:

布尔

forwarded_scheme

用户代理请求的原始URL方案(如果请求经过代理)。典型值有 'http' 或 'https' 。

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

  • Forwarded

  • X-Forwarded-For

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

（另见： RFC 7239, Section 1 ）

类型:

STR

method

HTTP方法被请求、升序(例如， 'GET' ， 'POST' 等)

类型:

STR

host

主机请求标头字段(如果存在)。如果缺少Host标头，此属性将解析为ASGI服务器的侦听主机名或IP地址。

类型:

STR

forwarded_host

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

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

  • Forwarded

  • X-Forwarded-Host

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

备注

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

（另见： RFC 7239, Section 4 ）

类型:

STR

port

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

类型:

利息

netloc

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

类型:

STR

subdomain

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

备注

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

类型:

STR

root_path

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

(对应于“ROOT_PATH”ASGI HTTP Scope字段。)

类型:

STR

uri

请求的完全限定的URI。

类型:

STR

url

的别名 uri 。

类型:

STR

forwarded_uri

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

类型:

STR

relative_uri

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

类型:

STR

prefix

请求URI的前缀，包括方案、主机和APP root_path (如有的话)。

类型:

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

距ASGI服务器最近的已知客户端或代理的IP地址，或者 '127.0.0.1' 如果未知的话。

此属性的值等效于 access_route 财产。

类型:

STR

access_route

原始客户端的IP地址(如果已知)，以及ASGI服务器前面的代理的任何已知地址。

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

  • Forwarded

  • X-Forwarded-For

  • X-Real-IP

此外，如果ASGI连接范围中的“Client”字段的值尚未包含在上述标头之一中，则会将其追加到列表的末尾。如果“client”字段不可用，则默认为 '127.0.0.1' 。

备注

每 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.asgi.BoundedStream

类型:

falcon.asgi.BoundedStream

media

充当的别名的可等待属性 get_media() 。这可以用来简化将WSGI应用程序移植到ASGI的过程，尽管 await 引用属性时仍必须添加关键字：：

deserialized_media = await req.media
类型:

对象

expect

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

类型:

STR

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标头。

备注

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

警告

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

类型:

双关语

headers_lower

的别名 headers 提供了一种统一的方式来获取WSGI和ASGI应用程序的低位标头。

类型:

双关语

params

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

类型:

双关语

options

从App处理程序传入的一组全局选项。

类型:

falcon.request.RequestOptions

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 -- 头包含格式不正确/无效的值。

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

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

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

deserialized_media = await 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可以通过以下方式自动解析请求正文中的参数 get_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请求类，但ASGI应用程序不支持此方法。请改用标准库日志记录框架。

class falcon.asgi.BoundedStream(receive, first_event=None, content_length=None)[源代码]

用于读取请求正文(如果有)的类似文件的输入对象。

此类实现了用于异步读取或迭代的协程函数，但在其他方面提供了类似于 io.IOBase 。

如果请求包含Content-Length报头，则流中的字节数将被截断为报头指定的长度。否则，流将生成数据，直到ASGI服务器指示没有更多字节可用。

对于大型请求体，使用流对象的首选方法是作为异步迭代器。在此模式中，当从ASGI服务器接收每个正文块时，将简单地生成其完整的正文块。由于框架不缓冲任何数据，因此这是读取请求正文的最节省内存的方式：

# If the request body is empty or has already be consumed, the iteration
#   will immediately stop without yielding any data chunks. Otherwise, a
#   series of byte #   strings will be yielded until the entire request
#   body has been yielded or the client disconnects.
async for data_chunk in req.stream
    pass

流对象还支持异步 read() 和 readall() 方法：

# Read all of the data at once; use only when you are confident
#   that the request body is small enough to not eat up all of
#   your memory. For small bodies, this is the most performant
#   option.
data = await req.stream.readall()

# ...or call read() without arguments
data = await req.stream.read()

# ...or read the data in chunks. You may choose to read more
#   or less than 32 KiB as shown in this example. But note that
#   this approach will generally be less efficient as compared
#   to async iteration, resulting in more usage and
#   copying of memory.
while True:
    data_chunk = await req.stream.read(32 * 1024)
    if not data_chunk:
        break

警告

应用程序可能不能同时使用两者 read() 和异步迭代器接口使用相同的请求正文；只有在使用其中一种方法完全读取整个正文时，这样做才是安全的。 在此之前 甚至还尝试了另一种方法。因此，重要的是要始终调用 exhaust() 或 close() 如果正文仅被部分读取，其余数据将被忽略。

备注

流对象为应用程序接收的任何ASGI“http.request”事件中包含的一系列主体块提供了方便的抽象。因此，一些请求体数据可以在调用期间和调用之间临时缓冲在内存中以从流中读取。该框架旨在最大限度地减少必须以此方式缓冲的数据量。

参数:

receive (awaitable) -- Asgi可等待调用，它将在新的请求事件字典可用时生成一个新的请求事件字典。

关键字参数:

  • first_event (dict) -- 从客户端接收的第一个ASGI事件(如果已预加载)(默认 None )。

  • content_length (int) -- 流的预期内容长度，派生自请求中的Content-Length标头(如果可用)。

close()[源代码]

清除所有缓冲的数据并关闭此流。

流关闭后，对其执行的任何操作都将引发 ValueError 。

为方便起见，允许多次调用此方法；但是，只有第一次调用才会生效。

async exhaust()[源代码]

消耗并立即丢弃流中的任何剩余数据。

fileno()[源代码]

引发OSError实例，因为未使用文件描述符。

isatty()[源代码]

返回 False 一直都是。

async read(size=None)[源代码]

读取请求正文中的部分或全部剩余字节。

警告

应始终指定大小，除非您可以确定您有足够的空闲内存来容纳整个请求正文，并且您已将Web服务器配置为将请求正文限制为合理的大小(以防止恶意请求)。

警告

应用程序可能不能同时使用两者 read() 和异步迭代器接口使用相同的请求正文；只有在使用其中一种方法完全读取整个正文时，这样做才是安全的。 在此之前 甚至还尝试了另一种方法。因此，重要的是要始终调用 exhaust() 或 close() 如果正文仅被部分读取，其余数据将被忽略。

关键字参数:

size (int) -- 要读取的最大字节数。可以读取的实际数据量将取决于可用的数据量，并且可能小于请求的数据量。如果大小为-1或未指定，则读取并返回所有剩余数据。

返回:

请求正文数据，或者 b'' 如果身体是空的或已经被吃掉了。

返回类型:

bytes

readable()[源代码]

返回 True 一直都是。

async readall()[源代码]

读取并返回请求正文中的所有剩余数据。

警告

仅当您可以确定有足够的空闲内存用于整个请求正文，并且已将Web服务器配置为将请求正文限制为合理大小(以防止恶意请求)时，才使用此方法。

返回:

请求正文数据，或者 b'' 如果身体是空的或已经被吃掉了。

返回类型:

bytes

seekable()[源代码]

返回 False 一直都是。

tell()[源代码]

返回到目前为止从流中读取的字节数。

writable()[源代码]

返回 False 一直都是。

响应

class falcon.asgi.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

产生一系列字节字符串的异步迭代器或生成器，这些字符串将作为一系列“http.response.body”事件流式传输到ASGI服务器。Falcon将在迭代器耗尽时或在其屈服后立即假定主体是完整的 None 而不是 bytes ：：

async def producer():
    while True:
        data_chunk = await read_data()
        if not data_chunk:
            break

        yield data_chunk

resp.stream = producer

或者，可以使用类似文件的对象，只要它实现了可等待的 read() 方法：

resp.stream = await aiofiles.open('resp_data.bin', 'rb')

如果分配给的对象 stream 保存必须显式释放的任何资源(如文件句柄)，则对象必须实现 close() 方法。这个 close() 方法将在耗尽可迭代或类似文件的对象后调用。

备注

为了与Python 3.7+和PEP 479兼容，异步迭代器必须返回 None 与其提高 StopIteration 。此要求不适用于异步发生器(PEP 525)。

备注

如果事先知道流长度，您可能还希望在响应上设置Content-Length标头。

sse

服务器发送的事件(SSE)发射器，实现为异步迭代器或生成器，该迭代器或生成器生成一系列 falcon.asgi.SSEvent 实例。每个事件都将被序列化并作为HTML5服务器发送的事件发送到客户端：：

async def emitter():
    while True:
        some_event = await get_next_event()

        if not some_event:
            # Send an event consisting of a single "ping"
            #   comment to keep the connection alive.
            yield SSEvent()

            # Alternatively, one can simply yield None and
            #   a "ping" will also be sent as above.

            # yield

            continue

        yield SSEvent(json=some_event, retry=5000)

        # ...or

        yield SSEvent(data=b'something', event_id=some_id)

        # Alternatively, you may yield anything that implements
        #   a serialize() method that returns a byte string
        #   conforming to the SSE event stream format.

        # yield some_event

resp.sse = emitter()

备注

当 sse 属性设置后，它将同时取代 text 和 data 属性。

备注

当托管发出服务器发送的事件的应用程序时，Web服务器应设置相对较长的保活TTL，以最大限度地减少连接重新协商的开销。

类型:

协程程序

context

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

备注

当使用默认上下文类型时，传递特定于响应的数据的首选方式是直接在 context 对象。例如：：

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

对象

context_type

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

备注

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

类型:

类

options

从App处理程序传入的一组全局选项。

类型:

双关语

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方法手动设置头。

async render_body()[源代码]

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

此协同例程可以等待以获取HTTP响应体的原始数据，同时考虑到 text ， data ，以及 media 属性。

备注

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

返回:

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

返回类型:

bytes

property retry_after

设置“重试后”头。

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

schedule(callback)[源代码]

安排异步回调在发送HTTP响应后立即运行。

此方法可用于在响应返回给客户端后执行后台作业。

回调被假定为异步协同例程函数。它将被安排尽快在事件循环上运行。

将在不带参数的情况下调用回调。使用 functools.partial 根据需要将参数传递给回调。

备注

如果在处理请求时引发未处理的异常，则不会计划运行回调。

备注

在响应上设置SSE发射器后，将在第一次调用发射器之前安排回调。

警告

因为协同例程在主请求线程上运行，所以应该注意确保它们是非阻塞的。长时间运行的操作必须使用异步库或委托给 Executor 池，以避免阻塞后续请求的处理。

参数:

callback (object) -- 一种异步协同程序函数。该回调将在没有参数的情况下被调用。

schedule_sync(callback)[源代码]

安排同步回调在发送HTTP响应后立即运行。

此方法可用于在响应返回给客户端后执行后台作业。

回调被假定为同步(非协程)函数。它将安排在事件循环的默认设置上 Executor (可通过以下方式覆盖 asyncio.AbstractEventLoop.set_default_executor() )。

将在不带参数的情况下调用回调。使用 functools.partial 根据需要将参数传递给回调。

备注

如果在处理请求时引发未处理的异常，则不会计划运行回调。

备注

在响应上设置SSE发射器后，将在第一次调用发射器之前安排回调。

警告

同步可调用在事件循环的缺省值上运行 Executor ，它使用 ThreadPoolExecutor 除非 asyncio.AbstractEventLoop.set_default_executor() 用于将其更改为其他内容。由于GIL，受cpu限制的作业将通过挡路请求处理当前进程，除非默认情况下 Executor 更改为基于进程而不是基于线程的实例(例如， concurrent.futures.ProcessPoolExecutor )。

参数:

callback (object) -- 异步协同例程函数或同步可调用函数。将在不带参数的情况下调用回调。

设置响应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服务器可以选择对HTTP/1.1使用分块编码

参数:

  • stream -- 返回字节字符串的可读、可等待的类似文件的对象或异步迭代。如果对象实现了Close()方法，则将在读取所有数据后调用它。

  • 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 版本加入.

class falcon.asgi.SSEvent(data=None, text=None, json=None, event=None, event_id=None, retry=None, comment=None)[源代码]

表示服务器发送的事件(SSE)。

类的实例可以由异步生成器生成，以便发送一系列 Server-Sent Events 发送到用户代理。

(另请参阅： falcon.asgi.Response.sse )

关键字参数:

  • data (bytes) -- 要用作 data 事件消息的字段。优先于两者 text 和 json 。

  • text (str) -- 要用于 data 消息中的字段。在事件中将被编码为UTF-8。优先于 json 。

  • json (object) -- 要转换为JSON并用作 data 事件消息中的字段。

  • event (str) -- 标识事件类型的字符串(AKA事件名称)。

  • event_id (str) -- 用户代理应用于 EventSource 对象的最后一个事件ID值。

  • retry (int) -- 尝试发送事件时使用的重新连接时间。这必须是一个整数，以毫秒为单位指定重新连接时间。

  • comment (str) -- 要包括在事件消息中的注释；这通常会被用户代理忽略，但在编写周期性的“ping”消息以保持连接处于活动状态时很有用。由于这是一种常见用例，因此任何原本为空的事件(即，在初始化时不指定任何字段的事件)中都将包含默认的“ping”注释 SSEvent 实例。)

data

要用作 data 事件消息的字段。优先于两者 text 和 json 。

类型:

字节

text

要用于 data 消息中的字段。在事件中将被编码为UTF-8。优先于 json 。

类型:

STR

json

要转换为JSON并用作 data 事件消息中的字段。

类型:

对象

event

标识事件类型的字符串(AKA事件名称)。

类型:

STR

event_id

用户代理应用于 EventSource 对象的最后一个事件ID值。

类型:

STR

retry

尝试发送事件时使用的重新连接时间。这必须是一个整数，以毫秒为单位指定重新连接时间。

类型:

利息

comment

要包括在事件消息中的注释；这通常会被用户代理忽略，但在编写周期性的“ping”消息以保持连接处于活动状态时很有用。由于这是一个常见的用例，默认的“ping”注释将包含在任何原本为空的事件中(即，在初始化时不指定这些字段中的任何字段的事件 SSEvent 实例。)

类型:

STR

serialize(handler=None)[源代码]

将此事件序列化为字符串。

参数:

handler -- 处理程序对象，该处理程序对象将用于序列化 json 属性设置为字符串。如果未提供，将使用使用内置JSON库的默认处理程序(默认 None )。

返回:

此事件的字符串表示形式。

返回类型:

bytes