公用事业¶
URI¶
URI实用程序。
此模块提供实用程序函数来解析、编码、解码和以其他方式操作URI。这些功能不能直接在 falcon 必须显式导入模块和so:：
from falcon import uri
name, port = uri.parse_host('example.org:8080')
- falcon.uri.decode(encoded_uri: str, unquote_plus: bool = True) str[源代码]¶
解码URI或查询字符串中的百分比编码字符。
此函数用于模拟 urllib.parse.unquote_plus ，尽管是以更快、更直接的方式。
- falcon.uri.encode(uri: str) str¶
根据RFC3986对完整或相对的URI进行编码。
RFC3986定义了一组“未保留”字符以及一组用作分隔符的“保留”字符。此函数通过对所有其他“不允许”字符进行百分比编码来对其进行转义。
备注
在一般情况下，此实用程序比类似程序更快 quote 在中找到函数
urlib.它还通过假定允许的字符是合理的默认值，力求更容易使用。
- falcon.uri.encode_check_escaped(uri: str) str¶
根据RFC3986对完整或相对的URI进行编码。
RFC 3986定义了一组“非保留”字符以及一组用作分隔符的“保留”字符。此函数按百分比转义所有其他“不允许”的字符-对它们进行编码，除非它们看起来以前已经编码过。例如,
'%26'将不会再次编码，因为它遵循编码值的格式。备注
在一般情况下，此实用程序比类似程序更快 quote 在中找到函数
urlib.它还通过假定允许的字符是合理的默认值，力求更容易使用。
- falcon.uri.encode_value(uri: str) str¶
根据RFC 3986对值字符串进行编码。
不允许的字符按百分比编码方式
urllib.parse.quote(safe="~").然而，在一般情况下，Falcon功能比类似功能更快。 quote 在URLIB中找到函数。它还通过假定允许的字符是合理的默认值，力求更容易使用。所有保留字符被集中到一组“分隔符”中，该组中的所有内容都被转义。
备注
RFC3986定义了一组“未保留”字符以及一组用作分隔符的“保留”字符。
- falcon.uri.encode_value_check_escaped(uri: str) str¶
根据RFC 3986对值字符串进行编码。
RFC 3986定义了一组“非保留”字符以及一组用作分隔符的“保留”字符。不允许的字符以百分比编码的方式进行建模
urllib.parse.quote(safe="~")除非它们看起来是先前编码过的。例如,'%26'将不会再次编码，因为它遵循编码值的格式。所有保留字符被集中到一组“分隔符”中，该组中的所有内容都被转义。
备注
在一般情况下，此实用程序比类似程序更快 quote 在中找到函数
urlib.它还通过假定允许的字符是合理的默认值，力求更容易使用。
- falcon.uri.parse_host(host: str, default_port: Optional[int] = None) Tuple[str, Optional[int]][源代码]¶
解析规范'主机：端口'串成部分。
考虑到主机字符串可能包含域名或IP地址，将主机字符串（可能包含端口，也可能不包含端口）分为多个部分。在后一种情况下，支持IPv4和IPv6地址。
- falcon.uri.parse_query_string(query_string: str, keep_blank: bool = False, csv: bool = True) Dict[str, Union[str, List[str]]][源代码]¶
将查询字符串解析为词典。
假定查询字符串参数使用标准表单编码。只返回带有值的参数。例如，在给定‘foo=bar&lag’的情况下，此函数将忽略‘tag’，除非 keep_blank_qs_values 选项已设置。
备注
除了用于通过多次重复给定参数来指定列表的标准的基于HTML表单的方法外，Falcon还支持一种更紧凑的形式，在这种形式中，参数可以被赋予一次，但设置为
list逗号分隔的元素(例如，‘foo=a，b，c’)。使用此格式时，Falcon不会将所有以逗号uri编码的字符视为分隔符。如果客户端希望以列表形式发送值，则不能使用值对逗号进行编码。
指定列表的两种不同方式不能混合在同一参数的单个查询字符串中。
- 参数:
- 返回:
一本关于(的词典 name ， value )对，每个查询参数一个。请注意 value 可能是一个单一的
str，或一个list的str。- 返回类型:
- 抛出:
TypeError -- query_string 不是一个
str。
日期和时间¶
- falcon.http_now() str[源代码]¶
以imf固定日期的形式返回当前UTC时间。
- 返回:
当前作为imf固定日期的UTC时间，例如“周二，1994年11月15日12:45:26 GMT”。
- 返回类型:
- falcon.dt_to_http(dt: datetime) str[源代码]¶
转换为
datetime实例转换为HTTP日期字符串。- 参数:
dt (datetime) -- A
datetime要转换的实例，假定为UTC。- 返回:
一个RFC 1123日期字符串，例如：“1994年11月15日星期二12:45:26 GMT”。
- 返回类型:
- falcon.http_date_to_dt(http_date: str, obs_date: bool = False) datetime[源代码]¶
将HTTP日期字符串转换为DateTime实例。
- 参数:
http_date (str) -- 一个RFC 1123日期字符串，例如：“1994年11月15日星期二12:45:26 GMT”。
- 关键字参数:
obs_date (bool) -- 根据RFC7231支持OBS日期格式，例如：“星期日，1994年11月6日08:49:37 GMT”（默认
False）- 返回:
与给定HTTP日期对应的UTC日期时间实例。
- 返回类型:
datetime
- 抛出:
ValueError -- HTTP日期与任何可用的时间格式都不匹配
- class falcon.TimezoneGMT[源代码]¶
GMT时区类实现
datetime.tzinfo接口。- dst(dt: Optional[datetime]) timedelta[源代码]¶
返回夏令时（DST）调整。
- 参数:
dt (datetime.datetime) -- 忽略
- 返回:
格林尼治标准时间的DST调整，始终为0。
- 返回类型:
- tzname(dt: Optional[datetime]) str[源代码]¶
获取此时区的名称。
- 参数:
dt (datetime.datetime) -- 忽略
- 返回:
“格林尼治标准时间”
- 返回类型:
状态码¶
- falcon.http_status_to_code(status: Union[HTTPStatus, int, bytes, str]) int[源代码]¶
将HTTP状态规范化为整数代码。
此函数接受
http.HTTPStatusHTTP状态行串或字节串(例如，'200 OK')，或一个int并返回相应的整数代码。LRU用于最小化查找时间。
- 参数:
status -- 要规范化的状态代码或枚举。
- 返回:
HTTP状态的整数代码(例如，200)
- 返回类型:
- falcon.code_to_http_status(status: Union[int, HTTPStatus, bytes, str]) str[源代码]¶
将HTTP状态规范化为HTTP状态行字符串。
此函数接受
http.HTTPStatus，一个int状态代码、HTTP状态行串或字节串(例如，'200 OK')，并返回相应的HTTP状态行字符串。LRU用于最小化查找时间。
备注
与已弃用的
get_http_status()假设字符串已经表示HTTP状态行，则此函数不会尝试将字符串状态强制转换为整数代码。- 参数:
status -- 要规范化的状态代码或枚举。
- 返回:
与给定代码对应的HTTP状态行。字符串末尾不包括换行符。
- 返回类型:
- falcon.get_http_status(status_code: Union[str, int], default_reason: str = 'Unknown') str[源代码]¶
仅从代码中获取http状态代码和描述。
警告
从Falcon 3.0开始，此方法已弃用，取而代之的是
code_to_http_status()。- 参数:
status_code -- 可转换为整数的整数或字符串
default_reason -- 如果查找未找到结果，将附加到状态代码的默认文本
- 返回:
状态代码，例如“404未找到”
- 返回类型:
- 抛出:
ValueError -- 无法将输入的值转换为整数
异步¶
别名¶
这些函数为中实现的函数提供了简单的别名 asyncio ，其中包含旧版本Python的回退。
- falcon.get_running_loop()¶
返回正在运行的事件循环。如果没有运行错误，则引发运行错误。
此函数是特定于线程的。
适配器¶
这些函数有助于跨越同步和异步代码之间的障碍。
- async falcon.sync_to_async(func: Callable[[...], Any], *args: Any, **kwargs: Any) Callable[[...], Awaitable[Any]][源代码]¶
在默认的Executor上调度一个同步Callable，并等待结果。
此帮助器使调用不能移植到本地使用的函数(例如，由尚不支持异步的数据库库导出的函数)变得更容易。
为了安全地执行阻塞操作，而不会使异步循环停滞，包装的可调用对象计划在调用包装时在后台的单独线程上运行。
正在运行的循环的默认执行器用于调度同步可调用对象。
警告
此帮助器只能用于执行线程安全的可调用代码。如果可调用对象不是线程安全的，则可以通过首先用
wrap_sync_to_async()，然后直接执行包装器。警告
从异步事件循环安全地调用同步函数会给函数调用增加相当大的开销，并且应该仅在本机异步库不可用于要执行的操作时使用。
- 参数:
func (callable) -- 函数、方法或其他可调用包装
*args -- 所有附加参数都传递给可调用的。
- 关键字参数:
**kwargs -- 所有关键字参数都传递给Callable。
- 返回:
包装同步可调用对象的可等待协程函数。
- 返回类型:
function
- falcon.wrap_sync_to_async(func: Callable[[...], Any], threadsafe: Optional[bool] = None) Callable[[...], Any][源代码]¶
将可调用对象包装在在后台执行该可调用对象的协程中。
此帮助器使调用不能移植到本地使用的函数(例如，由尚不支持异步的数据库库导出的函数)变得更容易。
为了安全地执行阻塞操作，而不会使异步循环停滞，包装的可调用对象计划在调用包装时在后台的单独线程上运行。
通常，运行循环的默认执行器用于调度同步可调用对象。如果可调用对象不是线程安全的，则可以在全局单线程执行器中串行调度它。
警告
安全地包装同步函数会给函数调用增加相当大的开销，并且只有在本机异步库不可用于您希望执行的操作时才应该使用。
- 参数:
func (callable) -- 函数、方法或其他可调用包装
- 关键字参数:
threadsafe (bool) -- 设置为
False当可调用对象不是线程安全的(默认True)。当此参数为False，包装的可调用对象将被调度为在全局单线程执行器中串行运行。- 返回:
包装同步可调用对象的可等待协程函数。
- 返回类型:
function
- falcon.wrap_sync_to_async_unsafe(func: Callable[[...], Any]) Callable[[...], Any][源代码]¶
将可调用对象包装在直接执行可调用对象的协程中。
这个帮助器使得在ASGI应用程序中使用同步可调用程序变得更容易。但是，它被认为是“不安全的”，因为它直接在异步循环所在的同一线程中调用包装函数。通常，您应该使用
wrap_sync_to_async()取而代之的是。警告
此帮助器仅用于不执行任何阻塞I/O或冗长的CPU限制操作的函数，因为在执行包装函数时，整个异步循环将被阻塞。要获得在线程池执行器中运行函数的更安全、非阻塞的替代方案，请使用
sync_to_async()取而代之的是。- 参数:
func (callable) -- 函数、方法或其他可调用包装
- 返回:
包装同步可调用对象的可等待协程函数。
- 返回类型:
function
- falcon.async_to_sync(coroutine: Callable[[...], Awaitable[Result]], *args: Any, **kwargs: Any) Result[源代码]¶
从同步调用方调用协同例程函数。
此方法可用于从同步上下文调用异步任务。协同例程将被调度为在当前OS线程的当前事件循环上运行。如果事件循环尚未运行，则会创建一个。
警告
这种方法效率很低，主要用于测试和原型制作。
- 参数:
coroutine -- 要调用的协同例程函数。
*args -- 其他参数传递给协程函数。
- 关键字参数:
**kwargs -- 其他参数传递给协程函数。
- falcon.runs_sync(coroutine: Callable[[...], Awaitable[Result]]) Callable[[...], Result][源代码]¶
将协程函数转换为同步方法。
这是通过始终通过以下方式调用修饰过的协程函数来实现的
async_to_sync()。警告
此修饰符的效率非常低，应该仅用于调整异步测试函数，以便与同步测试运行器配合使用，例如
pytest或者unittest模块。如果当前线程尚未运行，它将为当前线程创建一个事件循环。
- 参数:
coroutine -- 伪装成同步函数的协同例程函数。
- 返回:
同步功能。
- 返回类型:
callable
其他¶
- falcon.util.deprecated(instructions: str, is_property: bool = False, method_name: Optional[str] = None) Callable[[Callable[[...], Any]], Any][源代码]¶
将方法标记为已弃用。
此函数返回一个修饰符，可用于标记不推荐使用的函数。应用此修饰符将导致在使用函数时发出警告。
- falcon.util.deprecated_args(*, allowed_positional: int, is_method: bool = True) Callable[[...], Callable[[...], Any]][源代码]¶
将带有位置参数的方法调用标记为已弃用。
- falcon.to_query_str(params: dict, comma_delimited_lists: bool = True, prefix: bool = True) str[源代码]¶
将参数字典转换为查询字符串。
- 参数:
- 返回:
一个URI查询字符串，包括“？”前缀（除非 prefix 是
False）或空字符串，如果没有给定参数dict是空的）。- 返回类型:
- falcon.get_bound_method(obj: object, method_name: str) Union[None, Callable[[...], Any]][源代码]¶
按名称获取给定对象的绑定方法。
- 参数:
obj -- 要在其上查找方法的对象。
method_name -- 要检索的方法的名称。
- 返回:
绑定方法，或
None如果对象上不存在该方法。- 抛出:
AttributeError -- 方法存在，但没有绑定（很可能是传递了一个类，而不是该类的实例）。
- falcon.secure_filename(filename: str) str[源代码]¶
清理提供的 filename 仅包含ASCII字符。
只有ASCII字母数字，
'.'，'-'和'_'允许使用此名称作为常规文件系统上的文件名，以实现最大的可移植性和安全性。所有其他字符都将替换为下划线 ('_')。备注
这个 filename 被规范化为Unicode
NKFD在ASCII转换之前的表格，以便在可以分解的地方提取更多的字母数字。例如：>>> secure_filename('Bold Digit 𝟏') 'Bold_Digit_1' >>> secure_filename('Ångström unit physics.pdf') 'A_ngstro_m_unit_physics.pdf'
- 参数:
filename (str) -- 从请求输入的任意文件名，如多部分表单文件名字段。
- 返回:
已清理的文件名。
- 返回类型:
- 抛出:
ValueError -- 提供的文件名为空字符串。
- falcon.is_python_func(func: Union[Callable, Any]) bool[源代码]¶
确定函数或方法是否使用标准Python类型。
此帮助器可用于检查函数或方法，以确定它是否使用标准Python类型，而不是特定于实现的本机扩展类型。
例如，由于Cython函数不是标准Python函数，
is_python_func(f)会回来的False当f是对胞元化函数或方法的引用时。- 参数:
func -- 要检查的函数对象。
- 返回:
True如果函数或方法使用标准Python类型；False不然的话。- 返回类型:
- class falcon.Context[源代码]¶
方便类在其属性中保存上下文信息。
此类用作默认值
Request和Response上下文类型（请参见Request.context_type和Response.context_type，分别）。在2.0之前的Falcon版本中，默认上下文类型为
dict.为了便于迁移到基于属性的上下文对象方法，这个类还实现了映射接口；也就是说，对象属性链接到字典项，反之亦然。例如：>>> context = falcon.Context() >>> context.cache_strategy = 'lru' >>> context.get('cache_strategy') 'lru' >>> 'cache_strategy' in context True
- class falcon.ETag[源代码]¶
表示已分析的HTTP实体标记的便利类。
这个类只是
str使用一些辅助方法和一个额外的属性来指示实体标记是弱的还是强的。字符串的值相当于RFC7232所称的“不透明标记”，即实体标记没有引号和弱点指示器。备注
假设弱实体标记比较可以通过使用
==运算符（根据下面的示例），只有一个strong_compare()提供了方法。下面是一个例子
on_get()演示如何使用此类实例的方法：def on_get(self, req, resp): content_etag = self._get_content_etag() for etag in (req.if_none_match or []): if etag == '*' or etag == content_etag: resp.status = falcon.HTTP_304 return # -- snip -- resp.etag = content_etag resp.status = falcon.HTTP_200
（另见：RFC 7232）
- is_weak¶
True如果实体标记较弱，则为False.- 类型:
布尔
- dumps() str[源代码]¶
将etag序列化为适合在前置条件头中使用的字符串。
（另见： RFC 7232, Section 2.3 ）
- 返回:
一个不透明的带引号的字符串，可能有一个弱点指示符作为前缀。
W/.- 返回类型:
- classmethod loads(etag_str: str) ETag[源代码]¶
从前置条件标头反序列化单个实体标记字符串。
备注
此方法仅用于分析单个实体标记。它不能用于解析以逗号分隔的值列表。
（另见： RFC 7232, Section 2.3 ）
