- Pin starlette version to
- Regression when performing a
model_dumpof pydantic models in the responses.
orjsonfor generic response parsing.
- Updated SwaggerUI version.
- Updated responses with a
- 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.
Esmerald is not fully tight with Pydantic which means it's more flexible and extendible and allows more versatility.
- Missing Request document.
- Removed the use of
randomfor the secrets in favour of the
- Contrib documentation updates regarding the Authorization headers.
Middlewareas an independent ASGI app on an
This was supposed to go in the release 2.3.0 but it was not merged on time to make the release.
- OpenAPI fields are permanently moved to OpenAPIConfig
making the codebase cleaner. The options are still available via
settingsin case of wanting to override the defaults but not via instantiation parameters. Via instantiation the
OpenAPIConfigis the one to be used.
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.
- Annotated for documentation generators.
- Add new documentation structure for Esmerald base.
- Add API Reference . #196
- Allow tags for levels. When a tag is added to an
Gateway, or any other level, the tags are appended to the final handler. This allows inheriting from existing tags for OpenAPI.
Middlewareon levels treating each level as an independent ASGI app.
v1. Esmerald prior to version 2.0 is no longer supported.
- 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.
securitywas not working as intended.
- Update base requirements and pydantic to 2.4.
- 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.
- Typos in the documentation.
- Pydantic 2.4 compatibility and updating to new names for the functions.
- Updated requirements for Pydantic and Starlette.
- Removed unnecessary dependencies.
- Support for async
- Add new landing page.
email-validatorerror being thrown from
- Updated the way
esmeraldclient operates internally.
- Updated internal minimum requirements.
- Regression in OpenAPI when adding middleware to
HTTPHandler. When a middleware was added, the OpenAPI would not generate the docs for it. The API would still work but not OpenAPI docs.
- 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.
- 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
- Support for Edgy ORM. Docs here.
- 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.
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.
- Interactive shell support directive for any Esmerald application.
- Updated Field, Form and Body from
esmerald.paramswith current defaults.
- Removed redundant cast from
Bodyas it is a subclass.
exampleas OpenAPI 3.10 supports
examples. Use examples instead of
- UploadFile sending as a list and as normal. This got broken when the migration to pydantic 2.0 happened.
- OpenAPI for
UploadFileas single and list now being parsed as a model.
This is a small fix into the parser of lists for the OpenAPI specification.
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.
- Major update of the core of Esmerald from Pydantic v1 to Pydantic v2.
from esmerald.openapi.datastructures import OpenAPIResponse.
- Changed deprecated functions such as
- Transformers no longer support custom fields. Pydantic natively handles that.
- EsmeraldSignature updated for the new version of the FieldInfo.
paramsreflect 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+.
- OpenAPI support for OAuth2.
- Fix typing across the whole codebase.
- Transformers are now generating Param fields directly.
- Updated fields in favour of the new pydantic model_fields approach.
- OpenAPI imports and removed unused dependencies.
pydantic_factoriesin favour of
- Dropped support for Tortoise ORM natively.
get_hasherfrom contrib fixed with the return value of the algorithm.
- Typing of the codebase updated.
- Removed deprecated functions allowing the mount and host.
- Fixed show_urls for openapi specification.
- Updated pyproject.toml keywords.
- Updated to the latest Starlette 0.28.0.
- Exception handler logic refactored.
- Upgrade Starlette version to >=0.27.0 for a security release. Details on Starlette's security
- Exception handler message when
rundirective does not find custom directive properly.
- Lifespan generator for the
- Updated native requirements of the project.
- Removed old core management in favour of click.
managementpackage in favour of
esmerald-admin. Now you can simply call
esmeraldwith the same directives as before. Simplification via command line #86.
esmerald createproject <NAME>
esmerald createpapp <NAME>
- Support for Ruff.
- New esmerald core admin management directives #83.
- New directives client.
- Added rich for command line colours, tables.
- New native directives:
- Linting and formatting issues with Ruff.
- 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
- 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.
- 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
ChildEsmerald now supports the parent which means it can share middlewares and interceptors across main application and children.
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.
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.
Add child esmeralds via functions once the application is created and dynamically.
- Brand new support for Saffier. A brand new ORM running on the top of SQLAlchemy in an async fashion.
middlewaresupport for Saffier with Esmerald.
- New docs regarding the Saffier integration. Those include also an example how to use it.
- 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.
- Old package versioning conflicts.
- Added support for Starlette 0.25.0
- Internal mapping types #45
- Added support for Starlette 0.24.0.
- Code clean for responses and encoders.
- JWTConfig leeway parameter to accept int and str.
ujsondumps parameter error.
UJSONResponsewhen importing dependency.
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.
ORJSONResponseto be optional dependencies #45.
- Changed the imports for
from esmerald.responses.encoders import ORJSONResponse#45.
- Changed the imports for
from esmerald.responses.encoders import UJSONResponse#45.
- Changed the imports for
from esmerald.datastructures.encoders import OrJSON#45.
- Changed the imports for
from esmerald.datastructures.encoders import UJSON#45.
- Moved the scheduler to optional installation with
pip install esmerald[schedulers]#45.
This is only applied for those who have esmerald prior to
If you already had template configurations, jwt, schedulers or all the features you need to update the imports to:
from esmerald.config.template import TemplateConfig
from esmerald.config.jwt import JWTConfig
- Scheduler class is now imported directly from
from asyncz.schedulers import AsyncIOScheduler # for the Scheduler class from asyncz.contrib.esmerald.decorator import scheduler # for the decorator
Templatenow accepts an extra
alternative_templatefor the cases of raising TemplateNotFound #44.
handle_status_codeinternal functionality as it is no longer used.
handlertype for Gateway and WebsocketGateway.
- The split bytes intead of b''.
DirectInjectsobject for the direct dependency injection without using Inject and
dependenciesfrom the handler #42.
include_in_schemaon a Gateway level for OpenAPI specification #42.
redirect_slasheswhen 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
- Added Template and Redirect to app imports. This was supposed to go in the release 0.8.0 but somehow it was missed.
January 22, 2023
Formparams to Esmerald.
- Add new
Injectsas parameter function.
- Add new
ArbitraryHashableBaseModelto handle the
Injectwith arbitrary types.
- Add new settings_config parameter. #40.
- Removed unused internal parameters for old functions.
scheduler_classis now a property in the EsmeraldSettings. This allows to override fields without issues.
- Error messages being thrown.
enable_openapiboolean for ChildEsmerald and submodules and
include_in_schemafor Include #37
- Fix types for OpenAPI for applications that are subclasses of Esmerald or ChildEsmerald #38
- New RequestSettingsMiddleware allowing accessing the settings of the application from the request.
- Settings resolution for the whole application #30.
- Request now has a
settingsproperty that can be accessed upon the installation of the RequestSettingsMiddleware.
licensereference upon instantiation from the settings.
- Add support for kwargs in the Dao and AsyncDAO #28
- Mypy references for the Gateway and WebsocketGateway being added to the handler.
- References to the Esmerald types causing the IDE to misread them.
- 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.
api_key_headernow defaults to
- JWT Token encoding and decoding #26.
- JWT middleware handling the headers
- Added support to httpx 0.23.3
- Updated document references pointing to Interceptors.
esmerald.contrib.auth.tortoise.middlewareraising exception on invalid token.
- Fixed code references to the
- Updated version of asyncz to support 0.1.4.
- Fixed dependencies when installing Esmerald based on Asyncz requirements.
- Minor fixes.
- Added support to httpx 0.23.2
- Support for Asyncz 0.1.3
- Add support for Asyncz 0.1.2
This changes might contain some backward incompatibilities if you are already using the previous scheduler.
- Deprecated the integration with
APSchedulerin favour of Asyncz. #15
- Upgraded the Esmerald official symbol.
If you are using the
@scheduler with the
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
BaseModelExtraparser removing repetition of code across transformers.
- Configurations for scheduler being passed as params.
- Scheduler in the slots.
- Added support for Starlette 0.23.1.
- Updated support to Starlette 0.23.0
- Updated the EsmeraldTestClient to support headers.
- Token parameters being passed to
- Update internal references to the JWT.
- HashableBaseModel allowing the hash to be done via pydantic BaseModels.
- Update transformer model field and functions.
- Minor doc fixes.
- Deprecated kwargs and signature to give place to Esmerald transformers.
- Code cleaning and improved performance by applying pure pydantic models internally.
- When instantiating an
app_nameshould be passed instead of
- Supporting Starlette version 0.22.0.
max_agefrom SessionConfig allowing negative numbers being passed and can be used for testing purposes or to clear a session.
redirect_slashesproperty added to the main Esmerald object and settings options.
@routerallowing validation for Options for CORS middleware.
- Officially supporting python 3.11.
- Removed Tortoise ORM dependency from the main package.
asyncpgfrom the main package as dependency.
auth.pyfrom security package as is no longer used. This was supposed to go in the release 0.2.4.
settings.pyfrom permissions as it is no longer used.
- OpenAPI documentation rendering for the same path with different http methods.
- Removed unnecessary comments.
- Generation of projects and apps using
esmeraldby removing the clutter.
esmeraldentrypoint allowing generating projects and apps via directives.
- Namespace conflicts when importing the
add_route- Fixed the way the add_route was managing the paths and import to OpenAPI docs.
add_routes- Fixed the way the add_route was managing the paths and import to OpenAPI docs.
pyproject.toml- Added missing dependencies.
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.
- 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.