公用事业

URI

URI实用程序。

此模块提供实用程序函数来解析、编码、解码和以其他方式操作URI。这些功能不能直接在 falcon 必须显式导入模块和so::

from falcon import uri

name, port = uri.parse_host('example.org:8080')
falcon.uri.decode(encoded_uri, unquote_plus=True)

解码URI或查询字符串中的百分比编码字符。

此函数模拟 urllib.parse.unquote_plus 以更快、更直接的方式。

参数

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

关键字参数

unquote_plus (bool) -- 设置为 False 保留给定字符串中的任何加号(“+”)字符,而不是将其转换为空格(默认值 True )。通常应将此设置为 False 解码除查询字符串之外的任何URI部分时。

返回

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

返回类型

str

falcon.uri.encode(uri)

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

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

注解

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

参数

uri (str) -- 要编码的URI或其一部分。如果这是一个宽字符串(即, compat.text_type ,它将被编码为一个UTF-8字节数组,任何多字节序列将按原样进行百分比编码。

返回

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

返回类型

str

falcon.uri.encode_value(uri)

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

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

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

注解

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

参数

uri (str) -- 要编码的URI片段。假定不跨越分隔符边界,因此将转义其中包含的任何保留URI分隔符字符。如果 value 是一个宽字符串(即, compat.text_type ,它将被编码为一个UTF-8字节数组,任何多字节序列将按原样进行百分比编码。

返回

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

返回类型

str

falcon.uri.parse_host(host, default_port=None)

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

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

参数

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

关键字参数

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

返回

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

返回类型

tuple

falcon.uri.parse_query_string(query_string, keep_blank=False, csv=True)

将查询字符串解析为dict。

假设查询字符串参数使用标准格式编码。只返回具有值的参数。例如,给定“foo=bar&flag”,此函数将忽略“flag”,除非 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 将导致框架在每个发生的参数值中将逗号视为文本字符。

返回

字典( name价值 )对,每个查询参数一个。注意 价值 可能是单身 str ,或者 list 属于 str .

返回类型

dict

引发

TypeError -- query_string 不是一个 str .

falcon.uri.unquote_string(quoted)

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

参数

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

返回

未加引号的字符串

返回类型

str

引发

TypeError -- quoted 不是一个 str .

日期和时间

falcon.http_now()

以imf fixdate返回当前的UTC时间。

返回

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

返回类型

str

falcon.dt_to_http(dt)

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

参数

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

返回

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

返回类型

str

falcon.http_date_to_dt(http_date, obs_date=False)

将HTTP日期字符串转换为日期时间实例。

参数

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)

返回夏令时(DST)调整。

参数

dt (datetime.datetime) -- 忽略

返回

格林尼治标准时间的DST调整,始终为0。

返回类型

datetime.timedelta

tzname(dt)

获取此时区的名称。

参数

dt (datetime.datetime) -- 忽略

返回

“格林尼治标准时间”

返回类型

str

utcoffset(dt)

从UTC获取偏移量。

参数

dt (datetime.datetime) -- 忽略

返回

格林尼治标准时间偏移量,相当于UTC,因此是Aways 0。

返回类型

datetime.timedelta

状态码

falcon.get_http_status(status_code, default_reason='Unknown')

仅从代码中获取HTTP状态代码和说明

参数
  • status_code -- 可转换为整数的整数或字符串

  • default_reason -- 如果查找未找到结果,将附加到状态代码的默认文本

返回

状态代码,例如“404未找到”

返回类型

str

引发

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

异步

别名

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

适配器

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

其他

falcon.deprecated(instructions)

将方法标记为已弃用。

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

参数

instructions (str) -- 开发人员的具体指导,例如:“请迁移到添加代理服务器(…)”

falcon.to_query_str(params, comma_delimited_lists=True, prefix=True)

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

参数
  • 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, method_name)

按名称获取给定对象的绑定方法。

参数
  • obj -- 要在其上查找方法的对象。

  • method_name -- 要检索的方法的名称。

返回

绑定方法,或 None 如果对象上不存在该方法。

引发

AttributeError -- 方法存在,但没有绑定(很可能是传递了一个类,而不是该类的实例)。

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

注解

python 2特定 dict 但是,不管Python语言版本如何,方法都是公开的,因为它们被委托给底层 __dict__ ,会出现类似的错误,就好像试图对通常的python 3 dict使用这些方法一样。

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

    # ...

    resp.etag = content_etag
    resp.status = falcon.HTTP_200

(另见:RFC 7232)

is_weak

True 如果实体标记较弱,则为 False .

类型

布尔

dumps()

将etag序列化为适合在前置条件头中使用的字符串。

(另见: RFC 7232, Section 2.3

返回

一个不透明的带引号的字符串,可能有一个弱点指示符作为前缀。 W/ .

返回类型

str

classmethod loads(etag_str)

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

注解

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

(另见: RFC 7232, Section 2.3

参数

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

返回

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

返回类型

ETag

strong_compare(other)

执行强实体标记比较。

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

(另见: RFC 7232, Section 2.3.2

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

  • one. (this) --

返回

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

返回类型

bool