Release Notes¶
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 Esmeraldesmerald.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 inStaticFilesConfig
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 toextensions
. The old name is still available but deprecated. - Breaking: The
add_pluggable
method is now renamed toadd_extension
. The old name is still available but deprecated. - The documentation will refer now to extensions with
Pluggable
as a setup wrapper.
- Breaking: The
Fixed¶
- Directive
runserver
now allows the use of ASGI middlewares. - Remove the dependency of an app being an
esmerald
instance forrunserver
. - 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
orlist
types. This was due to the internal evaluation of theNone
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 thehandler
.
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 toCORSMiddleware
.
Changed¶
Gateway
now allows to pass also an optionaloperation_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 uniqueoperation_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
andDict
automatically parses the values to the declared type. - OpenAPI understands the native types, objects and lists (arrays).
3.3.4¶
Added¶
- Missing documentation for Query Parameters and Path Parameters.
Changed¶
- Documentation for
Extra, Advanced && Useful
is now renamedAdvanced & Useful
and its located in theFeatures
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 aloc[-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 ofBaseModel
causing the dependency injection to fail for those specific types
Added¶
- Esmerald is ow using
python-slugify
instead ofawesome-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 forcreateproject
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
andscheduler_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 therunserver
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 theTransformerModel
. The class methods are now normal python functions. - Unifying the transformers in the signature model.
- Rename
EsmeraldSignature
toSignatureModel
.
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 aMakefile
. - 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¶
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 theESMERALD_SETTINGS_MODULE
.ApplicationSettingsMiddleware
as internal that handles with thesettings_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
directiveviews.py
file generated renamed tocontrollers.py
.- Make the
EsmeraldAPISettings
hashable. - Remove
settings_config
in favor of thesettings_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 toDefineMiddleware
,
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 dropStarlette
.
Changed¶
CSRFConfig
cookie_secure
renamed tosecure
.CSRFConfig
httponly
renamed tohttponly
.CSRFConfig
cookie_samesite
renamed tosamesite
.CSRFConfig
cookie_domain
renamed todomain
.CSRFConfig
cookie_secure
renamed tosecure
.- 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 toPlainText
.
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 theInclude
.
Changed¶
- Internal code for lazy objects.
- Make
a2wsgi
optional forWSGIMiddleware
. 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 forsettings_config
.- Deprecation warning for
settings_config
in favour ofsettings_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 aclassmethod
. This allows to subclass theToken
and add extra fields into the model allowing operations likeencode()
with extra claims. This can be useful for situations like claiming arefresh
oraccess
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 thecreateproject
directive generating the minimum requirements for an Esmerald project.
Fixed¶
BaseAuthentication
forself.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 fromParam
(base) and callinclude_in_schema
. - Missing
nest_asyncio
dependency when usingesmerald 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 thesecrets
library instead. - Contrib documentation updates regarding the Authorization headers.
2.3.1¶
Fixed¶
Middleware
as an independent ASGI app on anInclude
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 theOpenAPIConfig
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¶
- Allow importing from from string into
Factory
. #179 by @tarsil. - New security objects for OpenAPI documentation.
- New OpenAPI documentation describing the ways of using it and what is available with examples.
- New SimpleAPIView supported.
- New CreateAPIView supported.
- New ReadAPIView supported.
- New DeleteAPIView supported.
- New ListAPIView supported.
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 fromopenapi-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
orHTTPHandler
. 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¶
- Interactive shell support directive for any Esmerald application.
2.0.2¶
Changed¶
- Updated Field, Form and Body from
esmerald.params
with current defaults. - Removed redundant cast from
File
toBody
as it is a subclass.
Added¶
- Added
strict
andmax_digits
esmerald paramsesmerald.params
. - Deprecate
example
as OpenAPI 3.10 supportsexamples
. Use examples instead ofexample
.
Fixed¶
- UploadFile sending as a list and as normal. This got broken when the migration to pydantic 2.0 happened.
File
andForm
fromesmerald.params
now acceptannotation
.- 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¶
- OpenAPIResponse now allows proper parse of lists as definition. More details.
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 toOpenAPIResponse
,from esmerald.openapi.datastructures import OpenAPIResponse
.- Changed deprecated functions such as
validator
androot_validator
tofield_validator
andmodel_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 Streamiterator
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 ofpyfactories
. - Dropped support for Tortoise ORM natively.
Fixed¶
- Rename
scripts/format
toscripts/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¶
- Upgrade Starlette version to >=0.27.0 for a security release. Details on Starlette's security
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 ofdirectives
. #83. - Deprecate
esmerald-admin
. Now you can simply callesmerald
with the same directives as before. Simplification via command line #86.- Example:
esmerald createproject <NAME>
esmerald createpapp <NAME>
- Example:
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
andmiddleware
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
andUJSONResponse
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
andORJSONResponse
to be optional dependencies #45. - Changed the imports for
ORJSONResponse
tofrom esmerald.responses.encoders import ORJSONResponse
#45. - Changed the imports for
UJSONResponse
tofrom esmerald.responses.encoders import UJSONResponse
#45. - Changed the imports for
OrJSON
tofrom esmerald.datastructures.encoders import OrJSON
#45. - Changed the imports for
UJSON
tofrom 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 extraalternative_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 anddependencies
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
andForm
params to Esmerald. - Add new
Injects
as parameter function. - Add new
ArbitraryHashableBaseModel
to handle theInject
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 fromRequestSettingsMiddleware
.
Fixed¶
- Error messages being thrown.
- Fix
enable_openapi
boolean for ChildEsmerald and submodules andinclude_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¶
- Request now has a
settings
property that can be accessed upon the installation of the RequestSettingsMiddleware.
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 toAuthorization
.
Fixed¶
- JWT Token encoding and decoding #26.
- JWT middleware handling the headers
0.6.0¶
Added¶
- Added support to the new Interceptors. #25
Changed¶
- Added support to httpx 0.23.3
- Updated document references pointing to Interceptors.
Fixed¶
JWTAuthMiddleware
fromesmerald.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 ofname
.
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
anditsdangerous
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 theinclude
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.