BlackSheep Files

[!IMPORTANT]

This release, like the previous one, includes some breaking changes to the public code API of certain classes, hence the bump in version from 2.2.0 to 2.3.0. The breaking changes aim to improve the user experience (UX) when using Controllers and registering routes. In particular, they address issues #511 and #540.The scope of the breaking changes is relatively minor, as they affect built-in features that are likely not commonly modified: removes the prepare_controllers and the get_controller_handler_pattern from the Application class, transferring them to a dedicated ControllersManager class. Additionally, the Router class has been refactored to work consistently for request handlers defined as functions and those defined as Controllers' methods.

The Router now allows registering all request handlers without evaluating them immediately, postponing duplicate checks, and introduces an apply_routes method to make routes effective upon application startup. This change is necessary to support using the same functions for both functions and methods, addressing issue #540, improving UX, and eliminating potential confusion caused by having two sets of decorators (get, post, put, etc.) that behave differently. While the two sets of decorators are still maintained to minimize the impact of breaking changes, the framework now supports using them interchangeably.

While breaking changes may cause inconvenience for some users, I believe the new features in this release represent a significant step forward. Now Controllers support routes inheritance! This is an important feature that was missing so far in the web framework.

• Fix #511. Add support for inheriting endpoints from parent controller classes, when subclassing controllers. Example:

  :::python from blacksheep import Application from blacksheep.server.controllers import Controller, abstract, get

  app = Application()

  @abstract() class BaseController(Controller): @get("/hello-world") def index(self): # Note: the route /hello-world itself will not be registered in the router, # because this class is decorated with @abstract() return self.text(f"Hello, World! {self.class.name}")

  class ControllerOne(BaseController): route = "/one" # /one/hello-world

  class ControllerTwo(BaseController): route = "/two" # /two/hello-world

  @get("/specific-route")  # /two/specific-route
  def specific_route(self):
      return self.text("This is a specific route in ControllerTwo")
  

• Add a new @abstract() decorator that can be applied to controller classes to skip routes defined in them; so that only their subclasses will have the routes registered, prefixed by their own prefix).

• BREAKING CHANGE. Refactor the Application code to encapsulate in a dedicated class functions that prepare controllers' routes.
• BREAKING CHANGE. Refactor the Router class to handle consistently request handlers defined using functions and controllers' class methods (refer to the note above for more information).
• Fix #498: Buffer reuse and race condition in client.IncomingContent.stream(), by @ohait.
• Fix #365, adding support for Pydantic's @validate_call and @validate_arguments and other wrappers applied to functions before they are configured as request handlers. Contribution by @aldem, who reported the issue and provided the solution.
• To better support @validate_call, configure automatically a default exception handler for pydantic.ValidationError when Pydantic is installed.
• Fix #550. Ensure that all generated $ref values contain only allowed characters.
• Fix #484. Improve the implementation of Server-Sent Events (SSE) to support sending data in any shape, and not only as JSON. Add a TextServerSentEvent class to send plain text to the client (this still escapes new lines!).
• Modify the is_stopping function to emit a warning instead of raising a RuntimeError if the env variable APP_SIGNAL_HANDLER is not set to a truthy value.
• Improve the error message of the RouteDuplicate class.
• Fix #38 for notations that are available since Python 3.9 (e.g. list[str], set[str], tuple[str]).
• Fix a regression introduced in 2.2.0 that would prevent custom HTTPExceptionhandlers from being used when the user configured a catch-all Exception handler (this practice is not recommended; let the framework handle unhandled exceptions using InternalServerError exception handler).
• Add a Conflict HTTPException to blacksheep.exceptions for 409 response code.
• Improve the test code to make it less verbose.