Falcon 2.0.0的更改日志

总结

非常感谢我们所有的优秀贡献者（如下所列），他们使这个版本成为可能！

在2.0中，我们添加了许多新的方便方法和属性。我们还使通过后缀响应程序将多个路由分配给同一个资源类变得更干净、更不容易出错。

值得注意的是，我们在提高文档的准确性、清晰度和广度方面投入了巨大的努力。我们希望这些变化将有助于使新成员更容易学习框架。

中间件方法现在可以短路请求处理，我们改进了cookie和etag处理。另外，测试框架得到了一些改进，使模拟某些类型的请求更容易。

由于这是我们在很长一段时间内获得的第一个主要版本，因此我们利用这个机会清理了框架的许多部分。已删除不推荐使用的变量、方法和类，以及旧方法签名的所有向后兼容性垫片。我们还根据社区反馈更改了许多请求选项的默认值。

请仔细查看下面的破坏性更改列表，查看您可能需要在应用程序中进行哪些调整，以使其与此版本兼容。

对支持平台的更改

  • 现在完全支持CPython 3.7。

  • Falcon2.x系列是最后一个支持Python语言版本2的。因此，对CPython2.7和Pypy2.7的支持将在Falcon3.0中移除。

  • 对CPython 3.4的支持现在已被弃用，将在Falcon 3.0中删除。

  • 对cpython 2.6、cpython 3.3和jython 2.7的支持已被放弃。

正在中断更改

  • 以前，在 Response 类可用于尝试设置原始cookie头。但是，由于设置的cookie头值不能组合为逗号分隔的列表，这导致在设置多个cookie的情况下，为用户代理构造的响应不正确。因此，以下方法 falcon.Response 现在举出一个 ValueError 如果试图将它们用于set cookie： set_header() ， delete_header() ， get_header() ， set_headers() .

  • falcon.testing.Result.json 现在回报 None 当响应主体为空时，而不是引发错误。

  • get_param_as_bool() 现在默认将没有价值的参数视为真实的，而不是错误的。 None 当参数完全丢失时，仍默认返回。

  • get_param_as_bool() 当 blank_as_true 关键字参数为 False . 相反， False 在这种情况下只需返回。

  • keep_blank_qs_values 现在默认为 True 而不是 False .

  • auto_parse_qs_csv 现在默认为 False 而不是 True .

  • independent_middleware 克沃格 falcon.API 现在默认为 True 而不是 False .

  • 这个 stream_len 性质 Response 类已更改为新的 content_length 属性。请使用 set_stream() 或 content_length 相反，继续前进， stream_len 现已弃用。

  • 请求 context_type 已从dict更改为实现映射接口的裸类。（另见： 如何使代码适应Falcon2.0中的默认上下文类型更改？ ）

  • 响应 context_type 已从dict更改为实现映射接口的裸类。（另见： 如何使代码适应Falcon2.0中的默认上下文类型更改？ ）

  • JSONHandler 和 HTTPError 不再使用 ujson 代替标准 json 类库（当 ujson 在环境中可用）。相反， JSONHandler 现在可以配置为使用任意 dumps() 和 loads() 功能。如果您还需要自定义 HTTPError 序列化，您可以通过 set_error_serializer() .

  • 这个 find() 现在需要自定义路由器的方法来接受 req 在以前版本中添加的关键字参数。拆下向后兼容的垫片。

  • 所有 middleware 方法和 hooks 现在必须接受falcon 2.0相关接口定义中指定的参数。所有向后兼容的垫片都已拆下。

  • 自定义错误序列化程序现在需要接受由指定的参数 set_error_serializer() 对于过去的几个版本。向后兼容的垫片已拆下。

  • 内部功能， make_router_search() ，已从中删除 api_helpers 模块。

  • 内部功能， wrap_old_error_serializer() ，已从中删除 api_helpers 模块。

  • 为了提高性能， falcon.Request.headers 和 falcon.Request.cookies 属性现在返回对内部缓存对象的直接引用，而不是每次都进行一次复制。这通常不会导致现有应用程序出现任何问题，因为调用程序通常将这些对象视为只读。

  • 这个 falcon.Request.stream 当falcon检测到属性正在wsgiref服务器上运行时，该属性不再包装在有界流中。如果需要规范化wsgiref和生产wsgi服务器之间的流语义， bounded_stream 可以代替。

  • falcon.Request.cookies 现在优先于在给定cookie名称的cookie头中遇到的第一个值，而不是最后一个值。

  • 将传递给自定义错误处理程序的参数的顺序调整为更直观和与框架的其余部分一致：

    # Before
def handle_error(ex, req, resp, params):
  pass

# Falcon 2.0
def handle_error(req, resp, ex, params):
  pass

    参见： add_error_handler()

  • strip_url_path_trailing_slash 现在默认为 False 而不是 True .

  • 被蔑视的 falcon.testing.TestCase.api 属性已删除。

  • 被蔑视的 falcon.testing.TestCase.api_class 类变量已删除。

  • 被蔑视的 falcon.testing.TestBase 类已删除。

  • 被蔑视的 falcon.testing.TestResource 类已删除。

  • 被蔑视的 protocol 属性已从中删除 Request 班级。

  • 被蔑视的 get_param_as_dict() 方法别名已从 Request 类。请使用 get_param_as_json() 相反。

  • 以前允许路由器接受其他参数和关键字参数，并且不需要使用variadic格式。现在，只允许它们接受其他选项作为variadic关键字参数，并忽略它们不支持的任何参数。这有助于被覆盖的路由器逻辑在接口契约方面不那么脆弱，这也使得Falcon在未来的任何变化面前更容易保持向后兼容。

  • add_route() 以前接受过 *args 但现在不再是了。

  • 这个 add_route() 自定义路由器的方法不再需要 method_map 参数。相反，自定义路由器应该调用 map_http_methods() 直接从他们的 add_route() 方法，如果它们需要此映射。

  • 这个 serialize() 媒体处理程序方法现在收到一个额外的 content_type 参数，而 deserialize() 方法现在采用 stream ， content_type 和 content_length 参数，而不是单个 raw 参数。原始数据仍然可以通过执行 raw = stream.read() .

    参见： BaseHandler

  • 被蔑视的 falcon.routing.create_http_method_map() 方法已删除。

  • 的关键字参数 parse_query_string() 已重命名为更简洁：

    # Before
parsed_values = parse_query_string(
    query_string, keep_blank_qs_values=True, parse_qs_csv=False
)

# Falcon 2.0
parsed_values = parse_query_string(
    query_string, keep_blank=True, csv=False
)

  • auto_parse_qs_csv 现在默认为 False 而不是 True .

  • 这个 HTTPRequestEntityTooLarge 类已重命名为 HTTPPayloadTooLarge .

  • 的两个关键字参数 get_param_as_int() 已重命名以避免隐藏内置的python名称：

    # Before
dpr = req.get_param_as_int('dpr', min=0, max=3)

# Falcon 2.0
dpr = req.get_param_as_int('dpr', min_value=0, max_value=3)

  • 这个 falcon.media.validators.jsonschema.validate() 装饰器现在使用 functools.wraps() 使装饰方法看起来像原来的方法。

  • 以前， HTTPError 实例的 has_representation 属性计算为 False 未传递给自定义错误序列化程序（例如，对于子类 NoRepresentation ）。现在已修复此问题，因此将为的所有实例调用自定义错误序列化程序。 HTTPError .

  • 请求cookie解析不再对大多数解析逻辑使用标准库。由于新的实现是基于RFC6265的，这可能会导致旧cookie头格式的结果略有不同。

  • 这个 if_match 和 if_none_match 属性现在返回 falcon.ETag 对象，而不是if-match或if-none的原始值。

  • 当设置 etag 头属性，该值现在将用双引号包装（如果尚未存在），以确保符合RFC7232。

  • 默认错误序列化程序不再设置 charset 内容类型头中返回的媒体类型的参数，因为utf-8是JSON和XML媒体类型的默认编码。这不应该破坏行为良好的客户机，但可能会影响应用程序中断言内容类型头的确切值的测试用例。

  • 与对默认错误序列化程序所做的更改类似，通常用于成功响应的默认JSON媒体类型也被修改为不再指定 charset 参数。这一变化影响到 falcon.DEFAULT_MEDIA_TYPE 和 falcon.MEDIA_JSON constants 以及 media_type 为指定的关键字参数 falcon.API 初始值设定项。此更改还影响 RequestOptions.default_media_type 和 ResponseOptions.default_media_type 选项。

新的和改进的

  • 对框架中的热代码路径进行了一些性能优化，以使Falcon2.0在某些情况下甚至比1.4更快。

  • 对文档进行了大量更改，以提高清晰度，并就如何最佳地使用框架的各个部分提供更好的建议。

  • 增加了一个新的 headers 的属性 Response 班级。

  • 移除 six 和 python-mimeparse 依赖关系。

  • 增加了一个新的 complete 的属性 Response 类。这可用于在预构造响应时进行短路请求处理。

  • 请求 context_type 现在默认为一个裸类，允许在请求上下文对象上设置属性：

    # Before
req.context['role'] = 'trial'
req.context['user'] = 'guest'

# Falcon 2.0
req.context.role = 'trial'
req.context.user = 'guest'

    为了简化迁移路径，通过以链接对象属性和映射项的方式实现映射接口，并设置一个设置另一个，支持以前的行为。但是，从Falcon2.0开始，dict上下文接口被认为是不推荐使用的，在将来的版本中可能会被删除。

    应用程序可以通过显式重写来绕过此更改。 context_type 听写（另见： 如何使代码适应Falcon2.0中的默认上下文类型更改？ ）

  • 响应 context_type 现在默认为一个裸类，允许在响应上下文对象上设置属性：

    # Before
resp.context['cache_strategy'] = 'lru'

# Falcon 2.0
resp.context.cache_strategy = 'lru'

    为了简化迁移路径，通过以链接对象属性和映射项的方式实现映射接口，并设置一个设置另一个，支持以前的行为。但是，从Falcon2.0开始，dict上下文接口被认为是不推荐使用的，在将来的版本中可能会被删除。

    应用程序可以通过显式重写来绕过此更改。 context_type 听写（另见： 如何使代码适应Falcon2.0中的默认上下文类型更改？ ）

  • JSONHandler 现在可以配置为使用任意 dumps() 和 loads() 功能。这不仅支持使用许多第三方JSON库中的任何一个，还支持自定义（取消）序列化对象时使用的关键字参数。

  • 添加了一个新方法， get_cookie_values() ，到 Request 类。新方法支持获取为给定cookie提供的所有值，现在是读取请求cookie的首选机制。

  • 优化的请求cookie分析。它现在大约快了一个数量级。

  • append_header() 现在支持附加原始集cookie头值。

  • 现在可以为同一个资源实例添加多个路由，使用后缀来区分应使用的响应程序集。这样，可以将多个密切相关的路由映射到同一个资源，同时保持可读性和一致性。

    参见： add_route()

  • 这个 falcon.media.validators.jsonschema.validate() decorator现在支持请求和响应验证。

  • 现在可以将静态路由配置为在找不到请求的文件路径时从默认文件返回数据。

    参见： add_static_route()

  • 将传递给自定义错误处理程序的参数的顺序调整为更直观和与框架的其余部分一致：

    # Before
def handle_error(ex, req, resp, params):
  pass

# Falcon 2.0
def handle_error(req, resp, ex, params):
  pass

    参见： add_error_handler() .

  • 所有错误类现在接受 headers 自定义响应头的关键字参数。

  • 一种新的方法， get_param_as_float() ，已添加到 Request 班级。

  • 一种新的方法， has_param() ，已添加到 Request 班级。

  • 新的财产， content_length ，已添加到 Response 类。或者 set_stream() 或 content_length 应该向前使用，如 stream_len 现已弃用。

  • 所有 get_param_*() 方法 Request 班级现在接受 default 争论。

  • 新的头属性， expires ，已添加到 Response 班级。

  • 这个 CompiledRouter 类现在公开 map_http_methods 子类可以重写的方法，以便自定义HTTP方法到资源类方法的映射。

  • 这个 serialize() 媒体处理程序方法现在收到一个额外的 content_type 参数，而 deserialize() 方法现在采用 stream ， content_type 和 content_length 参数，而不是单个 raw 参数。原始数据仍然可以通过执行 raw = stream.read() .

    参见： BaseHandler

  • 这个 get_header() 方法现在接受 default 关键字参数。

  • 这个 simulate_request() 方法现在支持重写wsgi环境中的主机和远程IP地址，以及在wsgi环境中设置任意其他CGI变量。

  • 这个 simulate_request() 方法现在支持将查询字符串作为路径的一部分传递，作为使用 params 或 query_string 关键字参数。

  • 为Linux上的uwsgi和nginx文档添加了部署指南。

  • 这个 decode() 方法现在接受 unquote_plus 关键字参数。新参数默认为 False 为了避免一个突破性的改变。

  • 这个 if_match() 和 if_none_match() 属性现在返回 falcon.ETag 对象，而不是if-match或if-none的原始值。

  • add_error_handler() 现在支持指定要匹配的异常类型的ITerable。

  • 默认错误序列化程序不再设置 charset 内容类型头中返回的媒体类型的参数，因为utf-8是JSON和XML媒体类型的默认编码。

  • 与对默认错误序列化程序所做的更改类似，通常用于成功响应的默认JSON媒体类型也被修改为不再指定 charset 参数。这一变化影响到 falcon.DEFAULT_MEDIA_TYPE 和 falcon.MEDIA_JSON constants 以及 media_type 为指定的关键字参数 falcon.API 初始值设定项。此更改还影响 RequestOptions.default_media_type 和 ResponseOptions.default_media_type 选项。

固定的

  • 修复了一个文档问题，在较小的浏览器视区中，API文档将开始水平滚动。

  • 修改了文档的配色方案，以解决打印文档或生成PDF时对比度和可读性问题。

  • 这个 simulate_request() 方法现在强制头值为 str 按照PEP-3333的要求在python 2上。

  • 这个 HTTPRequestEntityTooLarge 类已重命名为 HTTPPayloadTooLarge 原因短语根据RFC7231更新。

  • 这个 falcon.CaseInsensitiveDict 类现在从继承 collections.abc.MutableMapping 在python 3下，而不是 collections.MutableMapping .

  • 这个 \ufffd 请求的静态文件路径中现在不允许使用字符。

  • 这个 falcon.media.validators.jsonschema.validate() 装饰器现在使用 functools.wraps() 使装饰方法看起来像原来的方法。

  • 这个 falcon-print-routes 当对falcon进行cythonize时，cli工具不再引发未处理的错误。

  • 加号字符 ('+' ）不再在请求路径中不加引号，而是只在查询字符串中加引号。

  • 以前， HTTPError 实例的 has_representation 属性计算为 False 未传递给自定义错误序列化程序（例如，对于子类 NoRepresentation ）。现在已修复此问题，因此将为的所有实例调用自定义错误序列化程序。 HTTPError .

  • 当设置 etag 头属性，该值现在将用双引号包装（如果尚未存在），以确保符合RFC7232。

  • 固定的 TypeError 在使用Falcon的测试框架模拟对基于生成器的WSGi应用程序的请求时引发。

此版本的贡献者

多亏了我们在本次发布中的所有才华横溢和时尚贡献者！