公用事业

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 ,尽管是以更快、更直接的方式。

参数:

encoded_uri (str) -- 编码的URI(完整或部分)。

关键字参数:

unquote_plus (bool) -- 设置为 False 保留给定字符串中的任何加号(‘+’)字符,而不是将它们转换为空格(默认 True )。通常,您应该将其设置为 False 在对查询字符串以外的URI的任何部分进行解码时。

返回:

已解码的URL。如果URL包含转义的非ASCII字符,则根据RFC 3986假定为UTF-8。

返回类型:

str

falcon.uri.encode(uri: str) str

根据RFC3986对完整或相对的URI进行编码。

RFC3986定义了一组“未保留”字符以及一组用作分隔符的“保留”字符。此函数通过对所有其他“不允许”字符进行百分比编码来对其进行转义。

备注

在一般情况下,此实用程序比类似程序更快 quote 在中找到函数 urlib .它还通过假定允许的字符是合理的默认值,力求更容易使用。

参数:

uri (str) -- 要编码的URI或URI的一部分。

返回:

的转义版本 uri ,其中所有不允许的字符都进行了百分比编码。

返回类型:

str

falcon.uri.encode_check_escaped(uri: str) str

根据RFC3986对完整或相对的URI进行编码。

RFC 3986定义了一组“非保留”字符以及一组用作分隔符的“保留”字符。此函数按百分比转义所有其他“不允许”的字符-对它们进行编码,除非它们看起来以前已经编码过。例如, '%26' 将不会再次编码,因为它遵循编码值的格式。

备注

在一般情况下,此实用程序比类似程序更快 quote 在中找到函数 urlib .它还通过假定允许的字符是合理的默认值,力求更容易使用。

参数:

uri (str) -- 要编码的URI或URI的一部分。

返回:

的转义版本 uri ,其中所有不允许的字符都进行了百分比编码。

返回类型:

str

falcon.uri.encode_value(uri: str) str

根据RFC 3986对值字符串进行编码。

不允许的字符按百分比编码方式 urllib.parse.quote(safe="~") .然而,在一般情况下,Falcon功能比类似功能更快。 quote 在URLIB中找到函数。它还通过假定允许的字符是合理的默认值,力求更容易使用。

所有保留字符被集中到一组“分隔符”中,该组中的所有内容都被转义。

备注

RFC3986定义了一组“未保留”字符以及一组用作分隔符的“保留”字符。

参数:

uri (str) -- 要编码的URI片段。假设不跨越分隔符边界,因此其中包括的任何保留URI分隔符字符都将以百分比编码。

返回:

的转义版本 uri ,其中所有不允许的字符都进行了百分比编码。

返回类型:

str

falcon.uri.encode_value_check_escaped(uri: str) str

根据RFC 3986对值字符串进行编码。

RFC 3986定义了一组“非保留”字符以及一组用作分隔符的“保留”字符。不允许的字符以百分比编码的方式进行建模 urllib.parse.quote(safe="~") 除非它们看起来是先前编码过的。例如, '%26' 将不会再次编码,因为它遵循编码值的格式。

所有保留字符被集中到一组“分隔符”中,该组中的所有内容都被转义。

备注

在一般情况下,此实用程序比类似程序更快 quote 在中找到函数 urlib .它还通过假定允许的字符是合理的默认值,力求更容易使用。

参数:

uri (str) -- 要编码的URI片段。假设不跨越分隔符边界,因此其中包括的任何保留URI分隔符字符都将以百分比编码。

返回:

的转义版本 uri ,其中所有不允许的字符都进行了百分比编码。

返回类型:

str

falcon.uri.parse_host(host: str, default_port: Optional[int] = None) Tuple[str, Optional[int]][源代码]

解析规范'主机:端口'串成部分。

考虑到主机字符串可能包含域名或IP地址,将主机字符串(可能包含端口,也可能不包含端口)分为多个部分。在后一种情况下,支持IPv4和IPv6地址。

参数:

host (str) -- 要分析的主机字符串,可以选择包含端口号。

关键字参数:

default_port (int) -- 主机字符串不包含时返回的端口号(默认值 None

返回:

解析的( hostport )来自给定主机字符串的元组,端口转换为 int .如果主机字符串未指定端口, default_port 而是使用。

返回类型:

tuple

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编码的字符视为分隔符。如果客户端希望以列表形式发送值,则不能使用值对逗号进行编码。

指定列表的两种不同方式不能混合在同一参数的单个查询字符串中。

参数:
  • query_string (str) -- 要分析的查询字符串。

  • keep_blank (bool) -- 设置为 True 返回字段,即使它们没有值(默认 False )。对于逗号分隔值,此选项还确定是否保留解析列表中的空元素。

  • csv -- 设置为 False 要禁用拆分查询参数,请在 , (默认 True )。根据用户代理的不同,将列表编码为同一参数的多次出现可能更可取。在本例中,设置 parse_qs_csvFalse 将导致框架将每个出现的参数值中的逗号视为文字字符。

返回:

一本关于(的词典 namevalue )对,每个查询参数一个。请注意 value 可能是一个单一的 str ,或一个 liststr

返回类型:

dict

抛出:

TypeError -- query_string 不是一个 str

falcon.uri.unquote_string(quoted: str) str[源代码]

取消引用RFC 7320“带引号的字符串”。

参数:

quoted (str) -- 原始带引号的字符串

返回:

未加引号的字符串

返回类型:

str

抛出:

TypeError -- quoted 不是一个 str .

日期和时间

falcon.http_now() str[源代码]

以imf固定日期的形式返回当前UTC时间。

返回:

当前作为imf固定日期的UTC时间,例如“周二,1994年11月15日12:45:26 GMT”。

返回类型:

str

falcon.dt_to_http(dt: datetime) str[源代码]

转换为 datetime 实例转换为HTTP日期字符串。

参数:

dt (datetime) -- A datetime 要转换的实例,假定为UTC。

返回:

一个RFC 1123日期字符串,例如:“1994年11月15日星期二12:45:26 GMT”。

返回类型:

str

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。

返回类型:

datetime.timedelta

tzname(dt: Optional[datetime]) str[源代码]

获取此时区的名称。

参数:

dt (datetime.datetime) -- 忽略

返回:

“格林尼治标准时间”

返回类型:

str

utcoffset(dt: Optional[datetime]) timedelta[源代码]

从UTC获取偏移量。

参数:

dt (datetime.datetime) -- 忽略

返回:

GMT偏移量,相当于UTC,因此始终为0。

返回类型:

datetime.timedelta

状态码

falcon.http_status_to_code(status: Union[HTTPStatus, int, bytes, str]) int[源代码]

将HTTP状态规范化为整数代码。

此函数接受 http.HTTPStatus HTTP状态行串或字节串(例如, '200 OK' ),或一个 int 并返回相应的整数代码。

LRU用于最小化查找时间。

参数:

status -- 要规范化的状态代码或枚举。

返回:

HTTP状态的整数代码(例如,200)

返回类型:

int

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状态行。字符串末尾不包括换行符。

返回类型:

str

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未找到”

返回类型:

str

抛出:

ValueError -- 无法将输入的值转换为整数

异步

别名

这些函数为中实现的函数提供了简单的别名 asyncio ,其中包含旧版本Python的回退。

falcon.get_running_loop()

返回正在运行的事件循环。如果没有运行错误,则引发运行错误。

此函数是特定于线程的。

falcon.create_task(coro, *, name=None, context=None)[源代码]

计划派生任务中协程对象的执行。

返回一个Task对象。

适配器

这些函数有助于跨越同步和异步代码之间的障碍。

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][源代码]

将方法标记为已弃用。

此函数返回一个修饰符,可用于标记不推荐使用的函数。应用此修饰符将导致在使用函数时发出警告。

参数:
  • instructions (str) -- 针对开发者的具体指导,例如:‘请迁移到ADD_PROXY(...)’。

  • is_property (bool) -- 如果不推荐使用的对象是属性。它将省略 (...) 从生成的文档中。

  • method_name (str, optional) -- 设置以覆盖生成的文档中不推荐使用的函数或属性的名称(默认 None )。在装饰带有目标的别名时,这很有用 __name__

falcon.util.deprecated_args(*, allowed_positional: int, is_method: bool = True) Callable[[...], Callable[[...], Any]][源代码]

将带有位置参数的方法调用标记为已弃用。

关键字参数:
  • allowed_positional (int) -- 允许的位置参数数量

  • is_method (bool, optional) -- 修饰后的函数是一种方法。将使要考虑的位置参数的数量增加1 self 。默认为True。

falcon.to_query_str(params: dict, comma_delimited_lists: bool = True, prefix: bool = True) str[源代码]

将参数字典转换为查询字符串。

参数:
  • params (dict) -- 参数字典,其中每个键都是参数名,每个值都是 str 或者可以转换成 str 或此类值的列表。如果A list ,该值将转换为逗号分隔的值字符串(例如,“thing=1,2,3”)。

  • comma_delimited_lists (bool) -- 设置为 False 通过指定参数的多个实例(例如“thing=1&thing=2&thing=3”)对列表值进行编码。否则,参数将被编码为逗号分隔值(例如,“thing=1,2,3”)。默认为 True .

  • prefix (bool) -- 设置为 False 排除“?”结果字符串中的前缀(默认 True

返回:

一个URI查询字符串,包括“?”前缀(除非 prefixFalse )或空字符串,如果没有给定参数 dict 是空的)。

返回类型:

str

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) -- 从请求输入的任意文件名,如多部分表单文件名字段。

返回:

已清理的文件名。

返回类型:

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 不然的话。

返回类型:

bool

class falcon.Context[源代码]

方便类在其属性中保存上下文信息。

此类用作默认值 RequestResponse 上下文类型(请参见 Request.context_typeResponse.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/ .

返回类型:

str

classmethod loads(etag_str: str) ETag[源代码]

从前置条件标头反序列化单个实体标记字符串。

备注

此方法仅用于分析单个实体标记。它不能用于解析以逗号分隔的值列表。

(另见: RFC 7232, Section 2.3

参数:

etag_str (str) -- 表示单个实体标记的ASCII字符串,由RFC7232定义。

返回:

的实例 ~.ETag 表示已分析的实体标记。

返回类型:

ETag

strong_compare(other: ETag) bool[源代码]

执行强实体标记比较。

如果两个实体标记都不是弱的,并且它们的不透明标记逐字符匹配,则两个实体标记是等效的。

(另见: RFC 7232, Section 2.3.2

参数:
  • other (ETag) -- 其他的 ETag 与之相比

  • one. (this) --

返回:

True 如果两个实体标记匹配,则为 False .

返回类型:

bool