Skip to content

Release Notes

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.