Note

This is an exception deployment as the some internals were in conflict

Changed

• Query Parameters documentation updated with generics (list, dict) examples.

Fixed

• Parsing query parameters with multiple datastructures was not parsing it properly

Added

• Support for the new AuthenticationMiddleware from Lilya.
• Extensive documentation for the AuthenticationMiddleware with examples and guides.

Changed

• Deprecate BasicAuthMiddleware in favour of the new
  AuthenticationMiddleware from Lilya and it will be removed from
  version 0.4.0.
• Updated the documentation for Edgy with the new AuthenticationMiddleware.
• Updated the documentation for MongoZ with the new AuthenticationMiddleware.

Fixed

• Overriding the status_code for custom encoder types (Pydantic, msgspec...).

Added

• Add response parameter to exception initialization.

Changed

• Simplified Factory internals for cleaner nested provider handling and async consistency.
• The Dependency Injection system now supports async providers in nested dependencies.
• GenericAlias was changed since Python 3.9+ to types.GenericAlias.

Fixed

• Exception handler for HTTPException was not properly handling the response from the shortcuts.

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.