Skip to content

Release Notes

3.6.1

Added

  • Allow passing extensions as string.

Changed

  • Change media_type parameter of Response from MediaType.JSON to None to match the default of the underlying lilya Response.

Fixed

  • OpenAPI responses.
  • Enum definitions.

3.6.0

Added

  • New Security section with all the explanations how to use the internals of Esmerald.
  • Added new Security object used for security dependencies using Esmerald esmerald.security package.

Changed

  • Updates from python-jose to PyJWT as dependency contrib library.
  • Remove OpenAPI security as they where redundant and not 100% compliant with OpenAPI security.
  • Allow the new Lilya StaticFiles allowing to provide multiple directories with fallthrough behaviour.
  • Deprecate support for Mako.
  • Internal code organisation and cleaning.

Fixed

  • Fix cli detection of wrapped esmerald instances or different ASGI servers.
  • Allow passing multiple StaticFilesConfig configurations in a tuple.
  • Allow passing multiple directories to StaticFiles by removing the stringification in StaticFilesConfig so a fallthrough behavior can be established. Note: this requires a newer lilya version.

3.5.1

Changed

  • Use assigned encoders at requests for json_encoder.
  • Allow overwriting the LILYA_ENCODER_TYPES for different encoder sets or tests.
  • Use more OrJSON for encoding requests.

3.5.0

Added

  • Allow passing HTTP/WebSocket handlers directly to routes. They are automatically wrapped in Gateways-
  • Allow passing HTTP/WebSocket handlers directly to routes as alternative to defining a Gateway/WebsocketGateway.

Changed

  • Esmerald is now under the License BSD-3. This aims to protect the maintainers and contributors and the license will be now the final.
  • Pluggables can now receive plain Extensions and Extension classes.
  • Rename of Pluggables to Extensions:
    • Breaking: The pluggables attribute and parameter are now renamed to extensions. The old name is still available but deprecated.
    • Breaking: The add_pluggable method is now renamed to add_extension. The old name is still available but deprecated.
    • The documentation will refer now to extensions with Pluggable as a setup wrapper.

Fixed

  • Directive runserver now allows the use of ASGI middlewares.
  • Remove the dependency of an app being an esmerald instance for runserver.
  • Check the environment variables instead of settings variable for esmerald settings in the runserver.

3.4.4

Added

  • Support for Taskfile when generating a project via directive.
  • Add taskfile for development mode.

Changed

  • Internal JSONResponse is now natively supporting ORJSON.

3.4.3

Changed

  • PydanticEncoder now tries mode json first as default.
  • Stop ignoring warnings in the tests.
  • Stop shadowing the BaseDirective help from Lilya.
  • Asyncz settings for empty tasks.
  • Update the docs for the templates.

3.4.2

Changed

  • OpenAPI for inheritance models using pydantic or any type of encoders.
  • Stop supporting Python 3.8.
  • Changed internal schema location in the helpers.

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})

3.4.0

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": "john.doe@example.com",
    },
    "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).

3.3.7

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.

3.3.6

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.

3.3.5

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).

3.3.4

Added

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.

3.3.3

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].

3.3.2

Changed

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

3.3.1

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.

3.3.0

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.

3.2.7

This was missed from version 3.2.6.

Changed

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

Fixed

  • Performance issues caused by AppSettingsModule.

3.2.6

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 Esmerald 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.

3.2.5

Fixed

  • Added missing options into get_scheduler of AsynczConfig.

3.2.4

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.

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.

3.2.3

Changed

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

3.2.2

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.

3.2.1

Changed

  • Context is not inheriting directly from Lilya.

Fixed

  • The default scheduler_class internal settings validation.

3.2.0

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.

3.1.5

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.

3.1.4

Fixed

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

3.1.3

Changed

  • Internal support for hatch and removed the need for a Makefile.
  • Internals for Directives. #308 by @devkral.
  • Documentation references and refinements #311 by @paolodina.
  • WSGIMiddleware is now pointing to Lilya.

3.1.2

Fixed

  • Regression with typing_extensions.

3.1.1

Added

  • --with-basic-controller flag in createapp directive. #PR 284 by @tarsil.

Changed

  • Documentation improvements.

Fixed

  • Typo in the create project directive urls file descripton.
  • operation_id being generated to include the class based view name when coming from class based views handlers. #PR 289 by @tarsil.

3.1.0

Added

  • settings_module when passed in the instance of Esmerald will take precedence over the global settings, removing the need of using constantly the ESMERALD_SETTINGS_MODULE.
  • ApplicationSettingsMiddleware as internal that handles with the settings_module provided and maps the context of the settings.

Example of the way the settings are evaluated

from esmerald import Esmerald, EsmeraldAPISettings, Gateway, Include, JSONResponse, get, settings


@get()
async def home() -> JSONResponse:
    return JSONResponse({"title": settings.title})


class NewSettings(EsmeraldAPISettings):
    title: str = "Main app"


class NestedAppSettings(EsmeraldAPISettings):
    title: str = "Nested app"


app = Esmerald(
    settings_module=NewSettings,
    routes=[
        Gateway("/home", handler=home),
        Include(
            "/child",
            app=Esmerald(
                settings_module=NestedAppSettings,
                routes=[
                    Gateway("/home", handler=home),
                ],
            ),
        ),
    ],
)

In the context of the controller home, based on the path being called, it should return the corresponding value of the title according to the settings of the app that is included.

Changed

  • createapp directive views.py file generated renamed to controllers.py.
  • Make the EsmeraldAPISettings hashable.
  • Remove settings_config in favor of the settings_module.
  • Bump Lilya version to 0.3.3.

Fixed

3.0.0

Changed

  • Moved from beta v3 version to the official v3 of Esmerald fully supporting Lilya.

3.0.0-beta2

Added

  • Allow the use from lilya.middleware import Middleware as alternative to DefineMiddleware,

Changed

  • Cleaned the ServerErrorMiddleware from the lilya import.

3.0.0-beta1

Warning

This is a major release and it will be under the the version 3 of Esmerald. You should not be affected but in case you are, please report any issues so we can correct it.

Added

  • Support for Lilya and drop Starlette.

Changed

  • CSRFConfig cookie_secure renamed to secure.
  • CSRFConfig httponly renamed to httponly.
  • CSRFConfig cookie_samesite renamed to samesite.
  • CSRFConfig cookie_domain renamed to domain.
  • CSRFConfig cookie_secure renamed to secure.
  • Removed support for the BasicMiddleware as this can be imported from any other ASGI application.

Internal

In the past, Middleware was being used but with the introduction of Lilya, now is DefineMiddleware that is applied.

from lilya.middleware import DefineMiddleware
  • The PlainTextResponse was renamed to PlainText.

2.7.4

Fixed

  • WSGIMiddleware optional was being called in the core middlewares.

2.7.3

Added

  • Allowing app to load as a string as alternative to an object inside the Include.

Changed

  • Internal code for lazy objects.
  • Make a2wsgi optional for WSGIMiddleware.
  • httpx is now only a depedency for testing.
  • Cleared some core dependencies.

2.7.2

Changed

  • Security update for python multipart.
  • Update minimum Starlette requirement.

2.7.1

Added

  • settings_module as replacement for settings_config.
  • Deprecation warning for settings_config in favour of settings_module parameter.

Changed

  • Added improvements to the scaffold generated by esmerald createproject in the tests.
  • Added extra origin type for when a MsgSpec Struct is passed in the payload of a handler.

Fixed

  • OpenAPI Tags not loading from top down if handler had tags=None.
  • TestClient to allow passing pluggables inside create_client.

2.7.0

Changed

  • Token.decode() is now a classmethod. This allows to subclass the Token and add extra fields into the model allowing operations like encode() with extra claims. This can be useful for situations like claiming a refresh or access token.
  • Internal handlers decorators are now wrapped in a function decorator. This does not affect anything but allows more control over the middleware calls to async ASGI applications.

Fixed

  • OpenAPI when overriding the response for the default status codes of the handlers.

2.6.0

Added

  • New createdeployment directive allowing the generation of deployment scaffolds for any Esmerald project.

Changed

  • Added requirements to the createproject directive generating the minimum requirements for an Esmerald project.

Fixed

  • BaseAuthentication for self.app when its of the type of HTTPHandler and WebSocketHandler.

2.5.0

Changed

  • Upgraded internal dependencies.
  • The internals for the middleware are now delegated to Starlette directly.
  • Middlewares of Gateway and WebSocket Gateways are now delegated to Starlette.

Fixed

  • Internals to be compliant with new version of Starlette.
  • Building middleware stack for the Middleware object.
  • Internal testing to reflect the new way of the Include to be compliant with the ASGI spec.

2.4.3

Fixed

  • OpenAPI contact it was not parsing properly on transformation.
  • Rename include attribute from Param (base) and call include_in_schema.
  • Missing nest_asyncio dependency when using esmerald shell.

2.4.2

Changed

  • Pin starlette version to 0.32.0.post1

2.4.1

Fix

  • Regression when performing a model_dump of pydantic models in the responses.
  • Re-enable orjson for generic response parsing.

2.4.0

Changed

  • Updated SwaggerUI version.
  • Updated responses with a msgspec response example.

Added

  • Support for payload as alternative to data. This aims to make the process more intuitive and easy to implement. #199.
  • Context - The new context object for the handlers.
  • Support for msgspec natively allowing to have more than just Pydantic.

Note

Esmerald is not fully tight with Pydantic which means it's more flexible and extendible and allows more versatility.

Fixed

  • Missing Request document.
  • Removed the use of random for the secrets in favour of the secrets library instead.
  • Contrib documentation updates regarding the Authorization headers.

2.3.1

Fixed

  • Middleware as an independent ASGI app on an Include level.

Warning

This was supposed to go in the release 2.3.0 but it was not merged on time to make the release.

2.3.0

Changed

  • OpenAPI fields are permanently moved to OpenAPIConfig making the codebase cleaner. The options are still available via settings in case of wanting to override the defaults but not via instantiation parameters. Via instantiation the OpenAPIConfig is the one to be used.

Warning

This is a breaking change. The functionality itself still works as it is supposed to but from now on instead of passing via Esmerald instance, you need to pass the variables via OpenAPIConfig. object instead.

Added

  • Annotated for documentation generators.
  • Add new documentation structure for Esmerald base.
  • Add API Reference . #196

Fixed

  • Allow tags for levels. When a tag is added to an Include, Gateway, or any other level, the tags are appended to the final handler. This allows inheriting from existing tags for OpenAPI.
  • Middleware on levels treating each level as an independent ASGI app.

2.2.0

Changed

  • Updated OpenAPIConfig documentation.
  • Deprecate v1. Esmerald prior to version 2.0 is no longer supported.

Added

Fixed

  • OpenAPI security was not working as intended.

2.1.0

Changed

  • Update base requirements and pydantic to 2.4.

Added

  • New Factory added for dependency injection allowing to pass any time via Factory instantiation. PR #163 by @ShahriyarR.
  • Support for Mongoz showcasing how to integrate Esmerald with an ODM (MongoDB).
  • Documentation about how to use Esmerald contrib with Mongoz.

Fixed

  • Typos in the documentation.
  • Pydantic 2.4 compatibility and updating to new names for the functions.

2.0.6

Changed

  • Updated requirements for Pydantic and Starlette.
  • Removed unnecessary dependencies.

Added

  • Support for async has_permission on Permissions.
  • Add new landing page.

Fixed

  • email-validator error being thrown from openapi-schemas-pydantic requirement.

2.0.5

Changed

  • Updated the way esmerald client operates internally.
  • Updated internal minimum requirements.

Fix

  • Regression in OpenAPI when adding middleware to Gateway or HTTPHandler. When a middleware was added, the OpenAPI would not generate the docs for it. The API would still work but not OpenAPI docs.

2.0.4

Changed

  • Updated functional internal crypto to only use the system random.
  • Cleaner codebase for the application settings.
  • Updated version of Asyncz to be at least 0.5.0.

Added

  • Custom exception handlers, from esmerald.exception_handlers import value_error_handler.
  • New native exception handler for pydantic v2 Validation errors in general.
  • Dataclasses (normal and Pydantic dataclases) are now supported as Esmerald Responses.
  • Support for OpenAPI Webhooks.
  • Improved Responses documentation with examples using Pydantic BaseModel and dataclasses.
  • OpenAPI Spotlight Elements documentation. When starting the application, accesing the default /docs/elements.
  • Support for Edgy ORM. Docs here.

Fixed

  • Removed old pydantic v1 syntax from tests and applications.
  • add_include() that wasn't generating signature models upon import.
  • OpenAPI query params with defaults weren't loading properly.

2.0.3

Note

This addition was supposed to go in the release 2.0.2 but somehow it was missed in the merge of the pull requests. It is not a bug fix but instead is a simple new directive that can be useful for those who like using the command-line.

It is important to understand that this support won't be available on releases of Esmerald 1.X.

Added

2.0.2

Changed

  • Updated Field, Form and Body from esmerald.params with current defaults.
  • Removed redundant cast from File to Body as it is a subclass.

Added

  • Added strict and max_digits esmerald params esmerald.params.
  • Deprecate example as OpenAPI 3.10 supports examples. Use examples instead of example.

Fixed

  • UploadFile sending as a list and as normal. This got broken when the migration to pydantic 2.0 happened.
  • File and Form from esmerald.params now accept annotation.
  • OpenAPI for UploadFile as single and list now being parsed as a model.

2.0.1

This is a small fix into the parser of lists for the OpenAPI specification.

Fixed

2.0.0

Warning

When upgrading Esmerald to version 2, this also means the use of Pydantic 2.0 at its core as well as corresponsing technologies already updated to version 2 of Pydantic (Saffier, Asyncz...). If you still wish to continue to use Pydantic 1 with Esmerald, it is recommended to use Esmerald prior to version 2.0 which it will be maintained for a shor period but we strongly recommend to always use the latest version.

Changed

  • Major update of the core of Esmerald from Pydantic v1 to Pydantic v2.
  • ResponseSpecification renamed to OpenAPIResponse, from esmerald.openapi.datastructures import OpenAPIResponse.
  • Changed deprecated functions such as validator and root_validator to field_validator and model_validator.
  • Transformers no longer support custom fields. Pydantic natively handles that.
  • EsmeraldSignature updated for the new version of the FieldInfo.
  • params reflect the new Pydantic FieldInfo.
  • Deprecated OpenAPIView in favour of the new OpenAPI documentation generator.
  • Changed OpenAPI config to reflect the new generation of OpenAPI documentation.
  • Internal data field is now returning Body type parameter making it easier to integrate with Pydantic 2.0.
  • General codebase cleanup.
  • Removed old OpenAPI document generator in favour to the newest, fastest, simplest and more effective approach in v2.
  • Remove the support of pydantic 1.0. Esmerald 2+ will only support pydantic 2+.

Added

  • OpenAPI support for OAuth2.

Fixed

  • FileResponse stat_result and Stream iterator typing.
  • Fix typing across the whole codebase.
  • Transformers are now generating Param fields directly.
  • Updated fields in favour of the new pydantic model_fields approach.

1.3.0

Changed

  • OpenAPI imports and removed unused dependencies.
  • Deprecate pydantic_factories in favour of pyfactories.
  • Dropped support for Tortoise ORM natively.

Fixed

  • Rename scripts/format to scripts/lint for consistency.
  • get_hasher from contrib fixed with the return value of the algorithm.
  • Typing of the codebase updated.

1.2.5

Fixed

  • Removed deprecated functions allowing the mount and host.
  • Fixed show_urls for openapi specification.

1.2.4

Changed

  • Updated pyproject.toml keywords.
  • Updated to the latest Starlette 0.28.0.
  • Exception handler logic refactored.

1.2.3

Fixed

1.2.2

Fixed

  • Exception handler message when run directive does not find custom directive properly.

1.2.1

Fixed

  • Lifespan generator for the run directive.

1.2.0

Changed

  • Updated native requirements of the project.
  • Removed old core management in favour of click.
  • Deprecated management package in favour of directives. #83.
  • Deprecate esmerald-admin. Now you can simply call esmerald with the same directives as before. Simplification via command line #86.
    • Example:
      • esmerald createproject <NAME>
      • esmerald createpapp <NAME>

Added

  • Support for Ruff.
  • New esmerald core admin management directives #83.
  • New directives client.
  • Added rich for command line colours, tables.
  • New native directives:

Fixed

  • Linting and formatting issues with Ruff.

1.1.0

Changed

  • Updated support for Starlette 0.26.1
  • Updated support for Lifespan [./lifespan.md] events
  • Requests url_for parsing the URL type to return string on parsing #69.
  • Esmerald official documentation also available on https://esmerald.dev #70.
  • Updated Github CI to deploy also to https://esmerald.dev #73

Added

  • Internal implementation of on_startup and on_shutdown. #74.
  • Added new internal implementation of on_event and add_event_handler functions. #74.
  • Missing documentation about the background tasks #71
  • Documentation for lifespan events #72
  • Added condition to allow cached_properties from the EsmeraldAPISettings and in the settings without raising an Exception.
  • New handlers. OPTIONS, HEAD and TRACE. Check out the handlers for more details.

Fixed

  • New Starlette Lifespan #75. This is now also available to be done in the same way Starlette does. Internally Esmerald also implements the on_startup and on_shutdown but that is an unique implementation. This implementation follows the same pattern as the official Starlette Bridge

1.0.0

Changed

  • ChildEsmerald now supports the parent which means it can share middlewares and interceptors across main application and children.

    Note

    Prior to version 1.0.0, sharing resources between Esmerald and ChildEsmerald was not allowed and it needed to be treated as completely isolated application. In the version 1.0.0 you can still isolate them but you can also share resources.

0.15.0

Added

  • Esmerald Pluggables #60.

    This is the feature for the esmerald ecosystem that allows you to create plugins and extensions for any application as well as distribute them as installable packages.

  • New add_child_esmerald allowing adding via function, ChildEsmerald #61.

    Add child esmeralds via functions once the application is created and dynamically.

0.14.0

Added

  • Brand new support for Saffier. A brand new ORM running on the top of SQLAlchemy in an async fashion.
  • New base_user and middleware support for Saffier with Esmerald.
  • New docs regarding the Saffier integration. Those include also an example how to use it.

Changed

  • Breaking change - Removed support for python 3.7. This was blocking the technology from evolving at a normal pace and blocking security patches from being properly applied.

Fixed

  • Old package versioning conflicts.

0.13.0

Changed

  • Added support for Starlette 0.25.0

Fixed

  • Internal mapping types #45

0.12.0

Changed

  • Added support for Starlette 0.24.0.

Fixed

  • debug parameter regression.

0.11.2

Changed

  • Code clean for responses and encoders.
  • JWTConfig leeway parameter to accept int and str.

Fixed

  • ujson dumps parameter error.

0.11.1

Changed

  • Improved OrJSON, UJSON, ORJSONResponse and UJSONResponse when importing dependency.

0.11.0

Added

To make esmerald more optional and feature modular, this release brings some backwards incompatibilities that should be addressed when moving to this version. Check out the dcumentation for more details if this release notes doesn't cover it all.

Changed

  • Moved UJSON, UJSONResponse, OrJSON and ORJSONResponse to be optional dependencies #45.
  • Changed the imports for ORJSONResponse to from esmerald.responses.encoders import ORJSONResponse #45.
  • Changed the imports for UJSONResponse to from esmerald.responses.encoders import UJSONResponse #45.
  • Changed the imports for OrJSON to from esmerald.datastructures.encoders import OrJSON #45.
  • Changed the imports for UJSON to from esmerald.datastructures.encoders import UJSON #45.
  • Moved the scheduler to optional installation with pip install esmerald[schedulers] #45.

Backwards compatibility

This is only applied for those who have esmerald prior to 0.11.0. If you already had template configurations, jwt, schedulers or all the features you need to update the imports to:

  • TemplateConfig: 

    from esmerald.config.template import TemplateConfig

  • JWTConfig: 

    from esmerald.config.jwt import JWTConfig

  • Scheduler class is now imported directly from asyncz: 
    from asyncz.schedulers import AsyncIOScheduler # for the Scheduler class
from asyncz.contrib.esmerald.decorator import scheduler # for the decorator

0.10.0

Added

Changed

  • Template now accepts an extra alternative_template for the cases of raising TemplateNotFound #44.
  • Removed handle_status_code internal functionality as it is no longer used.

Fixed

  • handler type for Gateway and WebsocketGateway.
  • The split bytes intead of b''.

0.9.0

Added

  • DirectInjects object for the direct dependency injection without using Inject and dependencies from the handler #42.

Fixed

  • include_in_schema on a Gateway level for OpenAPI specification #42.
  • redirect_slashes when instantiating an Esmerald/ChildEsmerald application wasn't validating the value properly.
  • TemplateNotFound raised when a template is not found #42.
  • jinja2 Environment to have autoescape by default #43

0.8.1

Added

  • Added Template and Redirect to app imports. This was supposed to go in the release 0.8.0 but somehow it was missed.

0.8.0

January 22, 2023

Added

  • New File and Form params to Esmerald.
  • Add new Injects as parameter function.
  • Add new ArbitraryHashableBaseModel to handle the Inject with arbitrary types.
  • Add new settings_config parameter. #40.

Changed

  • Removed unused internal parameters for old functions.
  • scheduler_class is now a property in the EsmeraldSettings. This allows to override fields without issues.
  • Deprecate settings parameter from RequestSettingsMiddleware.

Fixed

  • Error messages being thrown.
  • Fix enable_openapi boolean for ChildEsmerald and submodules and include_in_schema for Include #37
  • Fix types for OpenAPI for applications that are subclasses of Esmerald or ChildEsmerald #38

0.7.0

Added

  • New RequestSettingsMiddleware allowing accessing the settings of the application from the request.
  • Settings resolution for the whole application #30.

Changed

Fixed

  • license reference upon instantiation from the settings.

0.6.2

Changed

  • Add support for kwargs in the Dao and AsyncDAO #28

Fixed

  • Mypy references for the Gateway and WebsocketGateway being added to the handler.
  • References to the Esmerald types causing the IDE to misread them.

0.6.1

Changed

  • Include now supports its own middleware handling and loading #26. This hange make sure that the parent level doesn't get affected and do not influence the middleware of other includes.
  • JWTConfig api_key_header now defaults to Authorization.

Fixed

  • JWT Token encoding and decoding #26.
  • JWT middleware handling the headers

0.6.0

Added

Changed

  • Added support to httpx 0.23.3
  • Updated document references pointing to Interceptors.

Fixed

  • JWTAuthMiddleware from esmerald.contrib.auth.tortoise.middleware raising exception on invalid token.
  • Fixed code references to the Void.

0.5.4

Changed

  • Updated version of asyncz to support 0.1.4.
  • Fixed dependencies when installing Esmerald based on Asyncz requirements.
  • Minor fixes.

0.5.3

Changed

  • Added support to httpx 0.23.2

0.5.2

Changed

  • Support for Asyncz 0.1.3

0.5.1

Changed

  • Add support for Asyncz 0.1.2

0.5.0

Warning

This changes might contain some backward incompatibilities if you are already using the previous scheduler.

Changed

  • Deprecated the integration with APScheduler in favour of Asyncz. #15
  • Upgraded the Esmerald official symbol.

Warning

If you are using the @scheduler with the func and identifier params, please check the documentation to understand how to upgrade to the new scheduler. It is almost the same but with some minor changes to the parameters

0.4.2

Changed

  • Created BaseModelExtra parser removing repetition of code across transformers.

Fix

  • Configurations for scheduler being passed as params.
  • Scheduler in the slots.

0.4.1

Changed

  • Added support for Starlette 0.23.1.

0.4.0

Changed

  • Updated support to Starlette 0.23.0
  • Updated the EsmeraldTestClient to support headers.

Fixed

  • Token parameters being passed to python-jose.
  • Update internal references to the JWT.

0.3.1

Added

  • HashableBaseModel allowing the hash to be done via pydantic BaseModels.

Changed

  • Update transformer model field and functions.

Fixed

  • Minor doc fixes.

0.3.0

Changed

  • Deprecated kwargs and signature to give place to Esmerald transformers.
  • Code cleaning and improved performance by applying pure pydantic models internally.

0.2.11

Fixed

  • When instantiating an Esmerald object, app_name should be passed instead of name.

0.2.10

Changed

  • Supporting Starlette version 0.22.0.

Fixed

  • max_age from SessionConfig allowing negative numbers being passed and can be used for testing purposes or to clear a session.

0.2.9

Fixed

  • redirect_slashes property added to the main Esmerald object and settings options.

0.2.8

Fixed

  • @router allowing validation for Options for CORS middleware.

0.2.7

Added

  • Officially supporting python 3.11.

0.2.6

Changed

  • Removed Tortoise ORM dependency from the main package.
  • Removed asyncpg from the main package as dependency.

0.2.5

Changed

  • Removed auth.py from security package as is no longer used. This was supposed to go in the release 0.2.4.

0.2.4

Changed

  • Removed settings.py from permissions as it is no longer used.

0.2.3

Fixed

  • OpenAPI documentation rendering for the same path with different http methods.

0.2.2

Added

  • httpx and itsdangerous dependencies.

0.2.1

Changed

  • Removed archive.
  • Removed unnecessary comments.

Fixed

  • Generation of projects and apps using esmerald by removing the clutter.

0.2.0

Added

  • esmerald entrypoint allowing generating projects and apps via directives.

Fixed

  • Namespace conflicts when importing the Include and the include internal function.

0.1.3

Changed

  • add_route - Fixed the way the add_route was managing the paths and import to OpenAPI docs.

0.1.2

Changed

  • add_routes - Fixed the way the add_route was managing the paths and import to OpenAPI docs.

0.1.1

Changed

  • pyproject.toml - Added missing dependencies.

0.1.0

This release is the first release of Esmerald and it contain all the essentials to start a project from the simplest version to the most advanced.

Added

  • Fluid and Fast: Thanks to Starlette and Pydantic.
  • Fast to develop: Thanks to the simplicity of design, the development times can be reduced exponentially.
  • Intuitive: If you are used to the other frameworks, Esmerald is a no brainer to develop.
  • Easy: Developed with design in mind and easy learning.
  • Short: With the OOP available natively there is no need for code duplication. SOLID.
  • Ready: Get your application up and running with production-ready code.
  • OOP and Functional: Design APIs in any desired way. OOP or Functional is available.
  • Async and Sync: Do you prefer sync or async? You can have both.
  • Middleware: Apply middlewares on the application level or API level.
  • Exception Handlers: Apply exception handlers on any desired level.
  • Permissions: Apply specific rules and permissions on each API.
  • DAO and AsyncDAO: Avoid database calls directly from the APIs. Use business objects instead.
  • Tortoise ORM: Native support for Tortoise ORM.
  • APIView: Class Based endpoints for your beloved OOP design.
  • JSON serialization/deserialization: Both UJSON and ORJON support.
  • Lifespan: Support for the newly lifespan and on_start/on_shutdown events.
  • Dependency Injection: Like any other great framework out there.
  • Scheduler: Yes, that's right, it comes with a scheduler for those automated tasks.
  • Simplicity from settings: Yes, we have a way to make the code even cleaner by introducing settings based systems.