esmerald

3.4.1

Changed

• OpenAPI now if no description is provided from the handlers, it will read directly from
  the docstrings.
• Internal code cleaning and organisation.

Fixed

• OpenAPI query parameters were not rendering properly for optional dict or list types. This
  was due to the internal evaluation of the None field which is now skipping for OpenAPI purposes.

Example

Now it is possible to do something like this:

from typing import Dict, List, Union, Optional

from esmerald import Gateway, JSONResponse, Query, get


@get("/item")
async def check_item(q: Union[List[str], None]) -> JSONResponse:
    return JSONResponse({"value": q})


@get("/another-item")
async def check_item(q: Optional[Dict[str, str]]) -> JSONResponse:
    return JSONResponse({"value": q})

Added

• New ways of providing the request data allowing to pass a more complex body
  using also the encoders. The complex body is explained
  and how to achieve this result.

!!! Warning
This is an additional functionality to the existing one and it does not represent any replacement. Be sure
you read the documentation and if you understand it.

Example

As per some examples of the documentation:

from pydantic import BaseModel, EmailStr

from esmerald import Esmerald, Gateway, post


class User(BaseModel):
    name: str
    email: EmailStr


class Address(BaseModel):
    street_name: str
    post_code: str


@post("/create")
async def create_user(user: User, address: Address) -> None:
    """
    Creates a user in the system and does not return anything.
    Default status_code: 201
    """


app = Esmerald(routes=[Gateway(handler=create_user)])

You can expect to send a payload like this:

{
    "user": {
        "name": "John",
        "email": "[email protected]",
    },
    "address": {
        "street_name": "123 Queens Park",
        "post_code": "90241"
    }
}

More details can and must be read in the request data section.

Changed

• Overriding the status_code in any response is now possible directly by specifying the intended response and ignoring
  the default from the handler.

Example

@get()
def create(name: Union[str, None]) -> Response:
    if name is None:
        return Response("Ok")
    if name == "something":
        return Response("Ok", status_code=status.HTTP_401_UNAUTHORIZED)
    if name == "something-else":
        return Response("Ok", status_code=status.HTTP_300_MULTIPLE_CHOICES)

If none of the conditions are met, then it will always default to the status_code of the handler which in the get case,
its 200.

Fixed

• Internal parsing of the encoders for OpenAPI representation and removed unused code (deprecated).

Added

• New application generator using --context allowing to generate application scaffolds containing
  more complex structures.

Changed

• jinja2 templating is now 100% delegated to its base, Lilya.
• Added examples in the documentation for windows users.

Fixed

• Lookup for summary in the handler for OpenAPI.

Added

• allow_private_networks property to CORSMiddleware.

Changed

• Gateway now allows to pass also an optional operation_id as parameter for OpenAPI documentation allowing
  multiple gateways to use the same handler and being recognised automatically by OpenAPI documentation.
• OpenAPI documentation when multiple gateways use the same handler and no operation_id is declared,
  automatically tries to generate a unique operation_id for it.
• Internal code organisation for class based View to generate the routes in one place and reducing
  code duplication.
• Updated internal testing requirements for Edgy and Saffier and Lilya.

This was missed from the release 3.3.4 and it was supposed to be included.

Added

• Native types for Esmerald transformer models/
• Hashing list internally for the signature allowing lists to be declared for OpenAPI representation.

Changed

• Query parameters when declared as list, List, dict and Dict automatically parses the values
  to the declared type.
• OpenAPI understands the native types, objects and lists (arrays).

Added

• Missing documentation for Query Parameters and Path Parameters.

Changed

• Documentation for Extra, Advanced && Useful is now renamed Advanced & Useful and its located in the Features
  section.
• Removed unused internal functions for validations now used by Esmerald encoders.

Fixed

• Regression caused by the introduction of the dynamic encoders when diplaying the query parameters in the OpenAPI
  documentation.
• Annotation discovery for the Signature.

Changed

• Internal implementation of the exceptions.
• Removed redundant exception declaration and delegate the internals to Lilya.
• Internal code cleaning.

Added

• ValidationError for custom independent raising exceptions within any Esmerald application

Fixed

• is_server_error for dependencies was causing an exception to be raised in a loc[-1].

Changed

• Update the internals of contrib for Asyncz to match the new Asyncz specifications and API.

Changed

• Automatic detection of a response for a default status code when using OpenAPI documentation.
• Addressing from __future__ import annotation when using the dependency injection defaulting to Any.

Fixed

• Fixes PydanticEncoder when checking for subclasses of BaseModel causing the dependency injection to fail
  for those specific types

Added

• Esmerald is ow using python-slugify instead of awesome-slugify for internals.
• OpenAPI Schemas Pydantic is now fully integrated with Esmerald OpenAPI.
• Esmerald now supports app as decorator prodiving another way of declaring the routing.

Example

#!/usr/bin/env python
import uvicorn

from esmerald import Esmerald, Gateway, JSONResponse, Request, get


app = Esmerald()


@app.get("/esmerald")
def welcome() -> JSONResponse:
    return JSONResponse({"message": "Welcome to Esmerald"})


@app.get("/esmerald/{user}")
def user(user: str) -> JSONResponse:
    return JSONResponse({"message": f"Welcome to Esmerald, {user}"})


@app.get("/esmerald/in-request/{user}")
def user_in_request(request: Request) -> JSONResponse:
    user = request.path_params["user"]
    return JSONResponse({"message": f"Welcome to Esmerald, {user}"})


if __name__ == "__main__":
    uvicorn.run(app, port=8000)

The same is also applied to the Router object.

Changed

• Removed unused middleware.
• Updated AppSettingsMiddleware for lazy loading
• Updated globalise_settings.

Fixed

• Performance issues caused by AppSettingsModule.

Added

• XFrameOptionsMiddleware to handle with options headers.
• SecurityMiddleware adding various security headers to the request/response lifecycle.
• override_settings as new decorator that allows to override the Lilya settings in any given test.
• New --simple flag for createproject directive generating simple structured projects.
• Integration with new rapidoc as another alternative to display the OpenAPI docs.

Changed

• Internal asyncz decorator inside a wrapper.
• Updated pydantic an lilya requirements.

Fixed

• Added missing options into get_scheduler of AsynczConfig.

Added

!!! danger
This new version deprecates an old style declaring the scheduler for Esmerald.
There is a new SchedulerConfig.

• New SchedulerConfig interface for Esmerald schedulers and
  custom schedulers.
• New AsynczConfig that implements the configuration for Asyncz scheduler.
• New scheduler_config parameter to Esmerald and EsmeraldAPISettings.

Changed

• Deprecate scheduler_class, scheduler_configurations and scheduler_tasks
  in favour of the new SchedulerConfig approach.
• Deprecate the use of the EsmeraldScheduler.
• Creation of multilingual documentation by @DJWOMS in https://github.com/dymmond/esmerald/pull/339

Breaking changes

You must update the imports to be:

From:

from asyncz.contrib.esmerald.decorator import scheduler

To:

from esmerald.contrib.schedulers.asyncz.decorator import scheduler

Check the documentation about the Scheduler, handlers and the SchedulerConfig to
see how to update your current project to the new version with the minimum disruption.

This change should not break existing functionality, instead, its just an update to make it more modular.
There is an example how to simply use this.

Fixed

• Added missing options --settings into the runserver directive.

Changed

• EsmeraldScheduler integration with Asyncz is not assembled before the configuration of the routing,
  allowing multiple events to be triggered without overriding.

These changes were missed from the version 3.2.1

Changed

• Updated the default scheduler class to be in the configuration.
• Internal Dispatcher implemented for the routing and response handlers update.

Changed

• Context is not inheriting directly from Lilya.

Fixed

• The default scheduler_class internal settings validation.

Added

• settings_module also supports import as string.
• New encoders to Esmerald settings and instance parameters.
• New register_encoder encoder in any Esmerald and ChildEsmerald instances.
• New encoders to Esmerald responses. This allows to use any Response as ASGI application.
  with unique custom encoders.
• Encoders documentation.

Changed

• Internal refactor of the classmethods of the TransformerModel. The class methods
  are now normal python functions.
• Unifying the transformers in the signature model.
• Rename EsmeraldSignature to SignatureModel.

Added

This change was supposed to be shipped in the version 3.1.4 but it missed the release.

• Printing the stack trace when an Esmerald application is in debug=True providing a deeper
  level of understanding the source of the errors.

Fixed

• AsyncExitMiddleware raising exception.
• OpenAPI error when generating the parameters with dependencies.
• OpenAPI security schemes.