Added

• Support for Python 3.14
• Support for contrib shortcuts provided by Lilya.

Added

• add_controller alternative to add_apiview.

Changed

• Update runserver directive to reflect the new Ravyn colour palette.

• Webhooks are now inside routing.webhooks and the handlers redundancy was removed.

• Routing apis is now called controllers. For importing reasons, this is the update:

  Before

  from ravyn.routing.apis

  After

  from ravyn.routing.controllers

• has_permission has changed signature.

  **Before

  def has_permission(request, apiview)

  After

  def has_permission(request, controller)

• The routing/apiview URL in the docs is now pointing to routing/controllers.

Why is this happening? Is Esmerald going away? No, absolutely not. Esmerald remains and will remain as is and will keep growing
as it has its own use cases but under a new name, Ravyn.

The reason for the rebranding its because the ecosystem has grown a lot and Esmerald was the first tool being created.
Since then it was released as version 3+.

This happened because of internal dependencies, and we already removed all of them but goes a bit off compared to the rest
of the ecosystem.

This is the reason for Ravyn to come into existence and to keep everything aligned with the future projects coming out.

Please check the migration guide for more details about how to migrate from Esmerald to Ravyn.

Official Ravyn release

We are proud to announce the first official release of Ravyn (0.1.0) —
the async web framework that builds on the strengths of Esmerald while embracing a new identity and future roadmap.

Highlights

• New Identity: Esmerald has been renamed to Ravyn. All imports, documentation, and branding now reflect this change.

Migration from Esmerald

This is not mandatory at all but if you want to start using Ravyn right away, you can simply do:

• Replace all esmerald imports with ravyn.
• No breaking changes in core APIs — projects built on Ravyn should run with minimal adjustments.

Please check the migration guide for more details about how to migrate from Esmerald to Ravyn.

Again, Ravyn is a rebrand of Esmerald with the same concepts, same everything.

Changed

• @directive(display_in_cli=True) discovery improved by showing errors and not throw directly
  an exception.
• Update minimum Sayer version to 0.6.0.
• Custom directives under @directive are now displayed in a "Custom directives" group.

Added

• Support for @directive to be display when calling esmerald client.
• display_in_cli to @directive.
• Relay documentation section.

Changed

• Allow minimum Lilya to be 0.20.5
• Esmerald cli now loses the name argument. This is now handled directly by the newest Sayer that
  was internal refactored for the @callback.

Added

• is_json and is_form properties for Request.
• Introduced esmerald.contrib.mail providing a full-featured, async-first email framework.
• Includes a high-level Mailer API for sending single, multiple, and templated messages.
• Supports multipart messages (text + HTML), custom headers, attachments (in-memory or files), and metadata.
• CLI integration, esmerald mail sendtest, for sending quick test emails via console backend.
• send_file to contrib.
• jsonify to contrib.

Built-in Backends

These backends are shared with Lilya as they are internally used.

• SMTPBackend: Async-friendly with connection pooling and TLS/authentication.
• ConsoleBackend: Writes messages to stdout for debugging.
• FileBackend: Saves emails as .eml files for inspection or archiving.
• InMemoryBackend: Stores emails in memory for development or testing scenarios.

Application Integration

• New setup_mail(app, backend, template_dir, attach_lifecycle=True) utility attaches a Mailer to app.state.mailer.
• Automatically opens/closes backend connections via startup/shutdown hooks.

Exception Hierarchy

• MailError: Base exception for all mail errors.
• BackendNotConfigured: Raised when no backend or template renderer is configured.
• InvalidMessage: Raised when an EmailMessage is incomplete or malformed.

Changed

• Simplify has_permission function calls from the internals.

Changed

• Morph path argument into path option and expose it for all commands.

Fixed

• Properly detect wrapped Esmerald instances.
• Fix double initialization of app in runserver.
• Fix crash in runserver when no autodiscovery.

Internal

• Add the new format in the Taskfile and pyproject.toml.

Breaking

• esmerald runserver loses its path argument. You can specify it via esmerald --path foo runserver.

Added

• --version attribute when running createapp directive allowing to generate a versioned scaffold.
• --location attribute when using createapp and createproject directive allowing to specify the location to be created.

Changed

• To make Esmerald lighter and simpler, the some minimal changes for the SessionMiddleware import were added.

Before

from esmerald.middleware import SessionMiddleware

After

from esmerald.middleware.sessions import SessionMiddleware

!!! Warning
Esmerald SessionMiddleware relies on itsdangerous Python package. You can install it by yourself or you can install
the esmerald[standard] package that brings all of the niceties of Esmerald.

In theory you don't need to worry ever about this as Esmerald injects this for you when using the session_config but if you
are importing directly, the previous change needs to happen.

• To make Esmerald cleaner in the installation we have now separated the installation. The Esmerald native client
  requires some additional packages and not everyone requires this or even desires but for those already using, the change is simple.

Before

$ pip install esmerald

After

$ pip install esmerald[standard]

This brings the current behaviour of Esmerald prior to version 3.8.11 and nothing changes at all.
**This is important if you are using the Form or request.form() as this comes with the standard packaging.

Changed

• Moved the security module imports down to use the Lilya contrib security.

Fixed

• Handlers were not preserving the original state.
• @cache decorator was not allowing proper serialization when used with handler.
• Fix cache key generator for classes.
• Typos in documentation.