Aura is an elegant, NestJS-inspired Python web framework built on raw performance and structured modularity. Designed to eradicate Django's legacy blocking ORM and FastAPI's structureless file chaos, Aura brings production-grade architecture to the Python ecosystem.
Aura solves the core architectural problems of traditional Python web frameworks with native speed and strict typing.
Django's pseudo-async ORM forces blocking database calls into worker threads, causing massive context-switching overhead and event loop delay. Aura uses true asynchronous SQLAlchemy 2.x and asyncpg pooling, driving native non-blocking loops at scale.
FastAPI projects often collapse under circular imports and unstructured file layout. Aura introduces NestJS-inspired modules `@Module()`, explicitly binding controllers, services, and repositories inside clean boundaries that are highly testable.
Never leak administrative access in production. Aura's Admin Panel detects the production flag and actively prevents app startup if the admin password environment variable is missing, guaranteeing zero accidental exposure.
Four interconnected clean layers designed to preserve architectural boundaries and isolate side effects.
Registry declaration context that isolates, binds, and configures localized controllers, guards, and services.
Pure ASGI routing nodes executing parameters, guard pipelines, and serializing typed payloads.
Stateful business controllers resolved dynamically via robust, cross-thread Dependency Injection.
Layered database connectors driving native asynchronous transactions under unified connection pooling.
Compare actual production headaches against clean modern implementations.
| HEADACHE DEFINITION | LEGACY FRAMEWORKS | AURA FRAMEWORK REMEDY |
|---|---|---|
| Monolithic Configuration | Django settings.py files scaling to 800+ lines. | Declaring localized settings per module using typed models and aura.toml contexts. |
| Async-to-Sync Blocking ORM | Django ORM requiring blocking wrappers or causing threadpool exhaustion. | Native async SQLAlchemy 2.x database connections executing transparently in background loops. |
| Unstructured Routing Files | FastAPI systems developing in dozens of unstructured file formats. | NestJS-style modular architectures providing clear separation between request/response structures. |
| Restricted Dependency Injection | FastAPI Depends() injection that only resolves during HTTP request-response loops. | Global DIContainer resolving dependencies safely in jobs, CLI, workers, and background threads. |
| Blocking Background Tasks | Complex and heavy Celery frameworks running synchronous tasks. | Lightweight, modern async tasks triggered globally with the simple @task decorator. |
Search standard commands, view framework examples, and copy production ready snippets.
Generate a complete, fully functional Restful modular template using our custom CLI tool in seconds.
Launch the global generator utility to structure files, setup configurations, and write primary unit tests:
$ aura new meu-projeto
$ cd meu_projeto
$ pip install -e ".[dev]"
$ aura run --reloadAura uses conditional extras packaging to minimize bundle size, ensure high scalability, and avoid loading redundant backend packages into small microservices.
Install targeted components based on production needs:
# Standard REST API runtime (Uvicorn core wrapper)
pip install "aura-web[uvicorn]"
# Full template package incorporating Jinja2 engines
pip install "aura-web[uvicorn,templates]"
# Full SQL support with asynchronous SQLAlchemy pools
pip install "aura-web[uvicorn,sqlalchemy]"
# Production package incorporating all extras
pip install "aura-web[all]"Aura strictly separates localized domains using cohesive modular folders. Every single module contains everything it needs to function correctly.
A typical modular layout includes:
meu_projeto/
├── main.py # App initialization: app = Aura(modules=[UsersModule])
├── aura.toml # Strict typed configuration variables
├── modules/
│ └── users/
│ ├── schemas.py # Typed Pydantic DTO definitions
│ ├── service.py # Stateful business logic (@injectable)
│ ├── controller.py # Routing node decorators (@get, @post)
│ ├── repository.py # Asynchronous SQL repository
│ ├── model.py # SQLAlchemy 2.x Entity layout
│ └── module.py # Binds services, controllers, guards
└── tests/
└── test_users.py # Complete isolated async integration testsIsolate localized context domains cleanly. Aura dependencies are instantiated as Singletons, Scoped, or Transients globally, then injected into targets via clear constructor declarations.
Declare modular packages cleanly using decorators:
# modules/posts/module.py
from aura import Module
from .controller import PostsController
from .service import PostService
@Module(
providers=[PostService],
controllers=[PostsController],
prefix="/posts",
tags=["Posts"]
)
class PostsModule:
passDeclare clean state injectors that do not rely on standard HTTP contexts:
# service.py
from aura import injectable
from .repository import PostRepository
@injectable
class PostService:
def __init__(self, post_repository: PostRepository) -> None:
self.repo = post_repository # Auto-resolved from the container!Bind endpoint routes to actions smoothly using declarative decorators. Type conversions and query validations are checked transparently.
Map path routes to actions easily:
# controller.py
from aura import get, post, put, Body, Query
from .schemas import CreatePostDTO, PostResponse
from .service import PostService
class PostsController:
def __init__(self, service: PostService) -> None:
self.service = service
@get("/")
async def list_posts(self, page: Query[int] = 1) -> list[PostResponse]:
return await self.service.list_posts(page)
@post("/", status=201)
async def create_post(self, body: Body[CreatePostDTO]) -> PostResponse:
return await self.service.create_post(body)Drive database mutations safely using fully non-blocking asynchronous operations. The Repository abstraction exposes built-in pagination, bulk queries, and transaction control.
Map fields cleanly using standard types:
# models.py
from aura.orm import AuraModel, CharField, TextField, BooleanField
from sqlalchemy.orm import Mapped
class Post(AuraModel):
__tablename__ = "posts"
title: Mapped[str] = CharField(max_length=200)
body: Mapped[str] = TextField()
published: Mapped[bool] = BooleanField(default=False)Write robust operations using Aura's fluent query system:
# repository.py
from aura.orm import Repository
from .models import Post
class PostRepository(Repository[Post]):
model = Post
async def list_published(self, limit: int = 10) -> list[Post]:
return await (
Post.objects
.filter(published=True)
.order_by("-created_at")
.limit(limit)
.all()
)Generate highly realistic testing records and mock local databases smoothly using built-in model factories and seeders.
Build custom object structures easily:
# database/factories.py
from aura.orm import Factory
from modules.users.models import User
class UserFactory(Factory[User]):
model = User
def definition(self) -> dict:
return {
"name": lambda: self.faker.name(),
"email": lambda: self.faker.unique.email(),
"active": True
}Populate tables cleanly inside atomic transactions:
# database/seeders.py
from aura.orm import Seeder
from database.factories import UserFactory
class DatabaseSeeder(Seeder):
async def run(self) -> None:
# Create 50 active users inside database automatically
await UserFactory().create_many(50)Inject security controls, credential verification, and path permissions instantly using flexible Guard chains.
Apply guards to specialized endpoint routes instantly:
# controller.py
from aura import get, AuraRequest
from aura.guards import JWTGuard
class UserController:
@get("/me", guards=[JWTGuard(secret="sua-chave-secreta")])
async def get_me(self, request: AuraRequest) -> dict:
return request.state.user # JWT Decoded payload!Track client details and session parameters safely across requests using standard encrypted browser cookies.
Load configuration settings smoothly:
# main.py
from aura import Aura
from aura.middleware import SessionMiddleware
app = Aura(
modules=[UsersModule],
middleware=[
SessionMiddleware(secret_key="sua-chave-secreta-longa")
]
)Execute long-running actions, generate PDFs, and dispatch email queues safely using lightweight background tasks.
Declare non-blocking executions smoothly:
# jobs.py
from aura.jobs import task, periodic
@task(queue="emails")
async def send_welcome_email(email: str) -> None:
await mailer.send(email, "Welcome to Aura!")
@periodic(cron="0 8 * * *")
async def daily_cleanup() -> None:
await database.purge_expired_sessions()Protect performance loops using a high-throughput, asynchronous logging system built directly into the core engine framework.
Send messages, tracking IDs, and exceptions easily without stalling the ASGI loops:
from aura.logging import Log
# Simple info log
Log.info("Transaction initialized")
# Structured log incorporating sanitization
Log.warning(
"Unauthorized API access attempt",
api_key="api_xyz123", # Automatically redacted: ***REDACTED***
ip="192.168.1.1"
)