ravyn 0.4.3

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.

!!! Info "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 palfrey

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

palfrey 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.

!!! warning "Critical Requirements" 1. At least one route is required: An empty Ravyn() application does nothing. You must define routes to handle requests. 2. 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' palfrey app:app --reload

# Windows
$env:RAVYN_SETTINGS_MODULE="myapp.settings.DevelopmentSettings"; palfrey 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

Documentation Development

# Build all documentation languages
hatch run docs:build

# Build one language
hatch run docs:build_lang en

# Serve default language (English)
hatch run docs:serve

# Serve all languages
hatch run docs:serve --all

# Serve a specific language
hatch run docs:serve --lang ru

For contributor docs workflow and translation steps, see Contributing.

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.

Sponsors

Currently there are no sponsors of Ravyn but you can financially help and support the author though GitHub sponsors and become a Special one or a Legend.

Powered by

Worth mentioning who is helping us.

JetBrains