Falcon 3.0.0更改日志

总结

我们很高兴向您介绍Falcon 3.0,这是一个重要的新版本,它包括 ASGI-based asyncioWebSocket 支持,棒极了 multipart/form-data parsing 、更好的错误处理、对现有功能的增强以及常见的各种错误修复。

从自愿投入的时间和贡献的代码来看,这无疑是我们做过的最大的一次发布。我们真诚地感谢我们由38名贡献者组成的庞大团队,他们为这个版本提交了拉取请求,以及所有慷慨地为该项目提供资金支持的人。

当我们开始这个版本的工作时,我们知道我们不仅要改进框架的现有功能,而且要提供一流的、用户友好的 asyncio 支持与我们现有的 WSGI 功能集。

另一方面,我们一直在抵制扩大Falcon范围的诱惑,以便为社区项目和标准留出空间,围绕共同的、自给自足的能力进行创新。所以当 ASGI 到达现场时,我们认为这是交付长期要求的绝佳机会 asyncioWebSocket 特性,同时仍然鼓励在Python web社区内共享和重用。

将大型代码库迁移到框架的主要新版本可能会很痛苦。因此,在3.0中,我们竭尽全力将破坏性更改降至最低,尽管一些方法和属性已被弃用。也就是说,在下面的突破性更改列表中,每个人都可能会遇到至少一到两个项目。在部署到生产环境之前,请仔细查看更改列表,并使用Falcon 3.0彻底测试您的应用程序。

在此版本发布之前,核心维护人员团队的成员花费了许多小时(以及不少深夜和周末)进行原型测试、调优和测试,以维护Falcon以正确性和可靠性著称的高标准。这就是说,没有代码是完美的,所以请不要犹豫,请联系 falconry/userGitHub 如果你遇到任何问题。

再次感谢所有支持这个版本的人!多年来,我们愿意认为我们的小框架对Python社区产生了积极的影响,甚至帮助推动了艺术的发展。这都要感谢我们令人惊叹的支持者和贡献者。

对支持平台的更改

  • 现在完全支持Python3.8和3.9。

  • 只有在使用新的ASGI接口时才需要python3.6+。在python3.5+上仍然支持WSGI。

  • Python3.5支持已被弃用,在下一个主要版本中可能会被删除。

  • 不再支持Python3.4。

  • Falcon2.x系列是最后一个支持Python语言版本2的版本。因此,Falcon3.0中取消了对cpython2.7和PyPy2.7的支持。

正在中断更改

  • 这个班级 OptionalRepresentation 和属性 has_representation 都被弃用了。默认的错误序列化程序现在为派生自 falcon.HTTPError 。此外,Falcon现在确保在处理任何引发的异常之前清除之前设置的任何响应正文。 (#452 _)

  • 这个班级 NoRepresentation 已被弃用。的所有子类 falcon.HTTPError 现在有了媒体类型表示。 (#777 _)

  • 为了调和框架对WSGI和ASGI的支持之间的差异,进行了以下突破性的更改:

    • falcon.testing.create_environ() 如果没有提供默认的User-Agent标头,则以前将该标头设置为值 'curl/7.24.0 (x86_64-apple-darwin12.0)' 。从Falcon 3.0开始,默认的User-Agent字符串现在为 f'falcon-client/{{falcon.__version__}}' 。为了向后兼容,可以通过设置 falcon.testing.helpers.DEFAULT_UA

    • 这个 falcon.testing.create_environ() 函数的 protocol 关键字参数已重命名为 http_version 现在仅包括版本号(该值不再带有前缀 'HTTP/' )。

    • 这个 falcon.testing.create_environ() 函数的 app 关键字参数已重命名为 root_path

    • 这个 writeable 的属性 falcon.stream.BoundedStream 已重命名为 writable 根据标准的类似文件的I/O接口(旧名称拼写错误)

    • 如果错误处理程序引发的异常类型不是 falcon.HTTPStatusfalcon.HTTPError 、剩余的中间件 process_response 在将未处理的异常冒泡到Web服务器之前,将不再执行方法。

    • falcon.get_http_status() 不再接受浮点数,并且该方法本身已弃用。

    • falcon.app_helpers.prepare_middleware() 不再接受单个对象;传递的值必须是可迭代的。

    • falcon.Request.access_route 现在包括 remote_addr 属性作为路由中的最后一个元素(如果尚未出现在所检查的其中一个标头中)。

    • 'REMOTE_ADDR' 字段不存在于WSGI环境中,Falcon将假定 '127.0.0.1' ,而不是简单地返回 Nonefalcon.Request.remote_addr

    以上更改是作为ASGI+HTTP工作流的一部分实现的。 (#1358 _)

  • 类的与标头相关的方法。 Response 类不再通过强制将传递的标头名称转换为字符串 str(). (#1497 )

  • 未处理的异常将不再引发到Web服务器。相反,框架现在为 Exception 键入。这也意味着中间件 process_response methods will still be called in this case, rather than being skipped as previously. The new default error handler simply generates an HTTP 500 response. This behavior can be overridden by specifying your own error handler for Exception via add_error_handler(). (#1507 )

  • 异常现在由最具体的匹配异常类的注册处理程序处理,而不是按照注册的相反顺序进行处理。“特异性”由引发的异常类型的方法解析顺序确定。(请参阅 add_error_handler() 了解更多详细信息。) (#1514 _)

  • 已弃用的 stream_len property was removed from the Response class. Please use set_stream() or content_length instead. (#1517 )

  • If RequestOptions.strip_url_path_trailing_slash is enabled, routes should now be added without a trailing slash. Previously, the trailing slash was always removed as a side effect of a bug regardless of the strip_url_path_trailing_slash option value. See also: Falcon如何处理请求路径中的尾随斜杠? (#1544)

  • 重命名 falcon.Response.bodyfalcon.HTTPStatus.bodytext. The old name is deprecated, but still available. (#1578 )

  • 引用类 falcon.stream.BoundedStream 通过 falcon.request_helpers module is deprecated. It is now accessible from the module falcon.stream. (#1583 )

  • 内部媒体处理程序的通用重构:

    • 使用不支持空体的处理程序反序列化空体将引发 falcon.MediaNotFoundError ,并将呈现为 400 Bad Request 回应。通过将默认值传递给 get_media 当身体空空时使用。另请参阅 falcon.Request.get_media() 有关详细信息,请参阅。以前 None 在所有情况下都是在没有调用处理程序的情况下返回的。

    • 处理程序引发的异常包装为 falcon.MediaMalformedError ,并将呈现为 400 Bad Request 回应。

    • 后续调用 falcon.Request.get_media()falcon.Request.media 如果第一个调用以错误结束,则将重新引发相同的异常,除非该异常是 falcon.MediaNotFoundError 并将默认值传递给 default_when_empty 当前调用的属性。以前 None 被退回了。

    外部处理程序应更新其逻辑以与内部Falcon处理程序对齐。 (#1589 _)

  • 这个 falcon.Response.data 属性现在只返回它设置的相同数据对象(如果有的话),而不是检查并序列化 falcon.Response.media 财产。取而代之的是,一个新的 render_body() 方法,该方法可用于获取请求的HTTP响应正文,同时考虑到 textdata ,以及 media 属性。 (#1679 _)

  • 这个 params_csv parameter now defaults to False in falcon.testing.simulate_request(). The change was made to match the default value of the request option auto_parse_qs_csv (False since Falcon 2.0). (#1730 )

  • 这个 falcon.HTTPError.to_json() 现在返回 bytes instead of str. Importing json from falcon.util is deprecated. (#1767 )

  • 的私有属性 JSONHandler 已重命名,并且使用的私有属性 MessagePackHandler 都被替换了。引用这些变量的子类将需要更新。另外,无证无证的 falcon.media.Handlers.find_by_media_type() 方法已弃用,可能会在将来的版本中删除。 (#1822 _)

新的和改进的

固定的

  • 以前,默认设置为 CompiledRouter 错误地从URI模板中剥离尾随斜杠。此问题已修复,现在可以为具有和不具有尾随前向劈开的路径添加两条不同的路由(另请参阅: RequestOptions.strip_url_path_trailing_slash )。 (#1544 _)

  • falcon.uri.decode()falcon.uri.parse_query_string() 不再对大量百分比编码字符进行二次爆炸。这些效用函数的时间复杂度现在总是接近于 O ( n )。 (#1594 _)

  • 什么时候 auto_parse_qs_csv 启用后,框架现在可以正确解析查询字符串中同一参数的所有匹配项,而不是只拆分第一个匹配项中的值。例如,之前 t=1,2&t=3,4 would become ['1', '2', '3,4'], now the resulting list will be ['1', '2', '3', '4'] (#1597 )

  • 这个 parse_query_string() 实用程序函数现在可以正确地将空字符串解析为 {{}}. (#1600 )

  • 以前,响应序列化错误(例如在有故障的自定义媒体处理程序的情况下,或者因为 HTTPUnsupportedMediaType 是为不支持的响应内容类型引发的)意外地冒泡到应用程序服务器。此问题已修复,现在处理这些错误的方式与响应程序中引发的其他异常完全相同(另请参阅: 错误处理 )。 (#1607 _)

  • falcon.Request.forwarded_host 现在包含未设置代理头时的端口,以便在应用程序不在代理之后时正确重建URL。 (#1678 _)

  • 这个 Response.downloadable_as 属性现在可以正确编码非ASCII文件名(根据 RFC 6266 recommendations. (#1749 )

  • 这个 falcon.routing.CompiledRouter 在探索不匹配的路由时,不再错误地设置路由参数。 (#1779 _)

  • 这个 to_query_str() 方法现在可以正确编码参数值和键。因此, params parameter in simulate_request() will now correctly pass values containing special characters (such as '&') to the application. (#1871 )

  • falcon.uri.encodefalcon.uri.encode_value 现在,在默认情况下转义所有百分比字符,即使它们似乎已经转义。这个 falcon.uri.encode_check_escapedfalcon.uri.encode_value_check_escaped 添加了方法,使您可以选择在需要的地方保留以前的行为。这些新方法已被应用于 falcon.Response.locationfalcon.Response.content_locationfalcon.Response.append_link() 保留以前行为的属性和方法。 (#1872 _)

  • 以前,标记为 deprecated() 实用工具包装可能引发意外的 AttributeError when running under certain applications servers such as Meinheld. This has been fixed so that deprecated() no longer relies on the availability of interpreter-specific stack frame instrospection capabilites. (#1882 )

杂项