Falcon 3.0.0更改日志

总结

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

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

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

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

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

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

再次感谢所有支持这个版本的人！多年来，我们愿意认为我们的小框架对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.HTTPStatus 或 falcon.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' ，而不是简单地返回 None 为 falcon.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.body 和 falcon.HTTPStatus.body 至 text. 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响应正文，同时考虑到 text ， data ，以及 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 _)

新的和改进的

固定的

杂项

此版本的贡献者

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