Ravyn

A next-generation async Python framework for building high-performance APIs, microservices, and web applications with type safety and elegance. 🚀

Documentation: https://ravyn.dev 📚

Source Code: https://github.com/dymmond/ravyn

The official supported version is always the latest released.

Coming from Esmerald?

If you came looking for Esmerald, you are in the right place. Esmerald was rebranded to Ravyn. All features remain and continue to grow.

Quick Start¶

Get your first Ravyn API running in minutes.

Installation¶

pip install ravyn[standard]

This installs Ravyn with recommended extras. You'll also need an ASGI server:

pip install uvicorn

Your First API¶

Create a file called app.py:

from ravyn import Ravyn, get, JSONResponse

app = Ravyn()

@app.get("/")
def welcome() -> JSONResponse:
    return JSONResponse({"message": "Welcome to Ravyn!"})

@app.get("/hello/{name}")
def greet(name: str) -> JSONResponse:
    return JSONResponse({"message": f"Hello, {name}!"})

Run It¶

uvicorn app:app --reload

Visit http://127.0.0.1:8000/hello/World and you'll see:

{"message": "Hello, World!"}

Explore the Docs¶

Ravyn automatically generates interactive API documentation:

Swagger UI: http://127.0.0.1:8000/docs/swagger
ReDoc: http://127.0.0.1:8000/docs/redoc
Stoplight Elements: http://127.0.0.1:8000/docs/elements

Congratulations! 🎉 You've built your first Ravyn API.

Why Ravyn?¶

Ravyn combines the best ideas from FastAPI, Django, Flask, and NestJS into a framework designed for real-world applications. from prototypes to enterprise systems.

Key Features¶

⚡ Fast: Built on Lilya and Pydantic, with async-first design
🎯 Type-Safe: Full Python 3.10+ type hints for better IDE support and fewer bugs
🧩 Flexible: Choose OOP (controllers) or functional style. or mix both
🔋 Batteries Included: Dependency injection, middleware, permissions, schedulers, and more
Database Ready: Native support for Edgy ORM and Mongoz ODM
🧪 Testable: Built-in test client for easy testing
📖 Auto-Documented: OpenAPI/Swagger docs generated automatically

Core Concepts¶

Routes and Handlers¶

Ravyn uses decorators or Gateway objects to define routes.

Critical Requirements

At least one route is required: An empty Ravyn() application does nothing. You must define routes to handle requests.
Return types are important: Always specify return type hints (e.g., -> dict, -> JSONResponse). Ravyn uses these to:
- Serialize your data correctly
- Generate accurate API documentation
- Validate responses

Decorator Style (Recommended for Simple APIs)¶

from ravyn import Ravyn, get, post

app = Ravyn()

@app.get("/users")
def list_users() -> dict:
    return {"users": ["Alice", "Bob"]}

@app.post("/users")
def create_user(name: str) -> dict:
    return {"created": name}

Gateway Style (Recommended for Larger Apps)¶

from ravyn import Ravyn, Gateway, get

@get()
def list_users() -> dict:
    return {"users": ["Alice", "Bob"]}

app = Ravyn(
    routes=[
        Gateway("/users", handler=list_users)
    ]
)

Tip

Use decorators for quick prototypes. Use Gateway + Include for scalable, organized applications.

Dependency Injection¶

Inject dependencies at any level. from application-wide to individual routes.

from ravyn import Ravyn, Gateway, Inject, Injects, get

def get_database():
    return {"db": "connected"}

@get()
def users(db: dict = Injects()) -> dict:
    return {"users": [], "db_status": db}

app = Ravyn(
    routes=[Gateway("/users", handler=users)],
    dependencies={"db": Inject(get_database)}
)

Learn more in the Dependencies guide.

Settings Management¶

Ravyn uses environment-based settings inspired by Django.

from ravyn import RavynSettings
from ravyn.conf.enums import EnvironmentType

class DevelopmentSettings(RavynSettings):
    app_name: str = "My App (Dev)"
    environment: str = EnvironmentType.DEVELOPMENT
    debug: bool = True

Load your settings via environment variable:

# MacOS/Linux
RAVYN_SETTINGS_MODULE='myapp.settings.DevelopmentSettings' uvicorn app:app --reload

# Windows
$env:RAVYN_SETTINGS_MODULE="myapp.settings.DevelopmentSettings"; uvicorn app:app --reload

If no RAVYN_SETTINGS_MODULE is set, Ravyn uses sensible defaults.

Learn more in Application Settings.

Organizing Larger Applications¶

As your app grows, use Include to organize routes into modules.

Project Structure¶

myapp/
├── app.py
├── urls.py
└── accounts/
    ├── controllers.py
    └── urls.py

accounts/controllers.py¶

from ravyn import get, post

@get()
def list_accounts() -> dict:
    return {"accounts": []}

@post()
def create_account(name: str) -> dict:
    return {"created": name}

accounts/urls.py¶

from ravyn import Gateway
from .controllers import list_accounts, create_account

route_patterns = [
    Gateway("/", handler=list_accounts),
    Gateway("/create", handler=create_account),
]

urls.py¶

from ravyn import Include

route_patterns = [
    Include("/accounts", namespace="myapp.accounts.urls"),
]

app.py¶

from ravyn import Ravyn

app = Ravyn(routes="myapp.urls")

Now your routes are organized:

GET /accounts/ → list_accounts
POST /accounts/create → create_account

Learn more in Routing.

Additional Installation Options¶

Testing Support¶

pip install ravyn[test]

Includes the RavynTestClient for testing your application.

JWT Support¶

pip install ravyn[jwt]

For JWT-based authentication.

Scheduler Support¶

pip install ravyn[schedulers]

For background task scheduling.

Interactive Shell¶

pip install ravyn[ipython]  # IPython shell
pip install ravyn[ptpython]  # ptpython shell

Learn more about the shell.

Start a Project with Scaffolding¶

Warning

This is for users comfortable with Python project structures. If you're new to Ravyn, continue learning the basics first.

Generate a simple project scaffold:

ravyn createproject myproject --simple

Or generate a complete scaffold (recommended for enterprise apps):

ravyn createproject myproject

This creates a ready-to-go structure with:

Pre-configured application
Sample routes
Test setup

Learn more in Directives.

Next Steps¶

Now that you have Ravyn running, explore these topics:

Essential Concepts¶

Dependencies - Master dependency injection
Routing - Advanced routing patterns
Responses - Different response types
Testing - Test your application

Building Features¶

Middleware - Add request/response processing
Permissions - Secure your endpoints
Database Integration - Connect to databases
Background Tasks - Run async tasks

Going to Production¶

Settings - Environment configuration
Deployment - Deploy your application
OpenAPI Configuration - Customize API docs

Requirements¶

Python 3.10+

Ravyn is built on:

Lilya - High-performance ASGI framework
Pydantic - Data validation

About Ravyn¶

History¶

Ravyn is the evolution of Esmerald, rebranded to align with a growing ecosystem of tools. Esmerald continues to exist for its specific use cases, while Ravyn represents the next generation with improved consistency and future-focused design.

Motivation¶

While frameworks like FastAPI, Flask, and Django solve 99% of common problems, they sometimes leave gaps in structure and business logic organization. Ravyn was built to fill those gaps while keeping the best features from:

FastAPI - API design and automatic documentation
Django - Permissions and settings management
Flask - Simplicity and flexibility
NestJS - Controllers and dependency injection
Starlite - Transformers and signature models

Learn more in About Ravyn.

Join the Community¶

Ravyn is an open source project and we love your contribution!

Star us on GitHub to show your support! ⭐️
Join our Discord to ask questions and share your projects.
Follow us on X (Twitter) for the latest updates.