Changelog for Falcon 3.0.0

Summary

We are pleased to present Falcon 3.0, a major new release that includes ASGI-based asyncio and WebSocket support, fantastic multipart/form-data parsing, better error handling, enhancements to existing features, and the usual assortment of bug fixes.

This is easily the biggest release—in terms of both hours volunteered and code contributed—that we have ever done. We sincerely thank our stupendous group of 38 contributors who submitted pull requests for this release, as well as all those who have generously provided financial support to the project.

When we began working on this release, we knew we wanted to not only evolve the framework’s existing features, but also to deliver first-class, user-friendly asyncio support alongside our existing WSGI feature set.

On the other hand, we have always fought the temptation to expand Falcon’s scope, in order to leave room for community projects and standards to innovate around common, self-contained capabilities. And so when ASGI arrived on the scene, we saw it as the perfect opportunity to deliver long-requested asyncio and WebSocket features while still encouraging sharing and reuse within the Python web community.

It can be painful to migrate a large code base to a major new version of a framework. Therefore, in 3.0 we went to great lengths to minimize breaking changes, although a number of methods and attributes were deprecated. That being said, everyone will likely run up against at least one or two items in the breaking changes list below. Please carefully review the list of changes and thoroughly test your apps with Falcon 3.0 before deploying to production.

Leading up to this release, members of the core maintainers team spent many hours (and not a few late nights and weekends) prototyping, tuning, and testing in order to uphold the high standards of correctness and reliability for which Falcon is known. That being said, no code is perfect, so please don’t hesitate to reach out on falconry/user or GitHub if you run into any issues.

Again, thanks so much to everyone who supported this release! Over the years we like to think that our little framework has had a positive impact on the Python community, and has even helped nudge the state of the art forward. And it is all thanks to our amazing supporters and contributors.

Changes to Supported Platforms

  • Python 3.8 and 3.9 are now fully supported.

  • Python 3.6+ is only required when using the new ASGI interface. WSGI is still supported on Python 3.5+.

  • Python 3.5 support is deprecated and may be removed in the next major release.

  • Python 3.4 is no longer supported.

  • The Falcon 2.x series was the last to support Python language version 2. As a result, support for CPython 2.7 and PyPy2.7 was removed in Falcon 3.0.

Breaking Changes

  • The class OptionalRepresentation and the attribute has_representation were deprecated. The default error serializer now generates a representation for every error type that derives from falcon.HTTPError. In addition, Falcon now ensures that any previously set response body is cleared before handling any raised exception. (#452)

  • The class NoRepresentation was deprecated. All subclasses of falcon.HTTPError now have a media type representation. (#777)

  • In order to reconcile differences between the framework’s support for WSGI vs. ASGI, the following breaking changes were made:

    • falcon.testing.create_environ() previously set a default User-Agent header, when one was not provided, to the value 'curl/7.24.0 (x86_64-apple-darwin12.0)'. As of Falcon 3.0, the default User-Agent string is now f'falcon-client/{falcon.__version__}'. This value can be overridden for the sake of backwards-compatibility by setting falcon.testing.helpers.DEFAULT_UA.

    • The falcon.testing.create_environ() function’s protocol keyword argument was renamed to http_version and now only includes the version number (the value is no longer prefixed with 'HTTP/').

    • The falcon.testing.create_environ() function’s app keyword argument was renamed to root_path.

    • The writeable property of falcon.stream.BoundedStream was renamed to writable per the standard file-like I/O interface (the old name was a misspelling)

    • If an error handler raises an exception type other than falcon.HTTPStatus or falcon.HTTPError, remaining middleware process_response methods will no longer be executed before bubbling up the unhandled exception to the web server.

    • falcon.get_http_status() no longer accepts floats, and the method itself is deprecated.

    • falcon.app_helpers.prepare_middleware() no longer accepts a single object; the value that is passed must be an iterable.

    • falcon.Request.access_route now includes the value of the remote_addr property as the last element in the route, if not already present in one of the headers that are checked.

    • When the 'REMOTE_ADDR' field is not present in the WSGI environ, Falcon will assume '127.0.0.1' for the value, rather than simply returning None for falcon.Request.remote_addr.

    The changes above were implemented as part of the ASGI+HTTP work stream. (#1358)

  • Header-related methods of the Response class no longer coerce the passed header name to a string via str(). (#1497)

  • An unhandled exception will no longer be raised to the web server. Rather, the framework now installs a default error handler for the Exception type. This also means that middleware 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)

  • Exceptions are now handled by the registered handler for the most specific matching exception class, rather than in reverse order of registration. “Specificity” is determined by the method resolution order of the raised exception type. (See add_error_handler() for more details.) (#1514)

  • The deprecated 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: How does Falcon handle a trailing slash in the request path? (#1544)

  • Rename falcon.Response.body and falcon.HTTPStatus.body to text. The old name is deprecated, but still available. (#1578)

  • Referencing the class falcon.stream.BoundedStream through the falcon.request_helpers module is deprecated. It is now accessible from the module falcon.stream. (#1583)

  • General refactoring of internal media handler:

    • Deserializing an empty body with a handler that does not support it will raise falcon.MediaNotFoundError, and will be rendered as a 400 Bad Request response. This error may be suppressed by passing a default value to get_media to be used in case of empty body. See also falcon.Request.get_media() for details. Previously None was returned in all cases without calling the handler.

    • Exceptions raised by the handlers are wrapped as falcon.MediaMalformedError, and will be rendered as a 400 Bad Request response.

    • Subsequent calls to falcon.Request.get_media() or falcon.Request.media will re-raise the same exception, if the first call ended in an error, unless the exception was a falcon.MediaNotFoundError and a default value is passed to the default_when_empty attribute of the current invocation. Previously None was returned.

    External handlers should update their logic to align to the internal Falcon handlers. (#1589)

  • The falcon.Response.data property now just simply returns the same data object that it was set to, if any, rather than also checking and serializing the value of the falcon.Response.media property. Instead, a new render_body() method has been implemented, which can be used to obtain the HTTP response body for the request, taking into account the text, data, and media attributes. (#1679)

  • The 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)

  • The falcon.HTTPError.to_json() now returns bytes instead of str. Importing json from falcon.util is deprecated. (#1767)

  • The private attributes for JSONHandler were renamed, and the private attributes used by MessagePackHandler were replaced. Subclasses that refer to these variables will need to be updated. In addition, the undocumented falcon.media.Handlers.find_by_media_type() method was deprecated and may be removed in a future release. (#1822)

New & Improved

Fixed

Misc