Edit on GitHub

Quick Start

Generate a fully functional RESTful modular template using Aura's CLI tool.

Initial Scaffolding

$ aura new meu-projeto
$ cd meu_projeto
$ pip install -e ".[dev]"
$ aura run --reload
Registry Verification
Point a browser to http://localhost:8000/docs for Swagger docs.

Installation

Aura uses conditional extras packaging to minimize bundle size.

Target Selection Packages

# Standard REST API
pip install "aura-web[uvicorn]"

# With Jinja2 templates
pip install "aura-web[uvicorn,templates]"

# With SQLAlchemy
pip install "aura-web[uvicorn,sqlalchemy]"

# All extras
pip install "aura-web[all]"

Project Layout

Aura strictly separates localized domains using cohesive modular folders.

meu_projeto/
  main.py
  aura.toml
  modules/users/
    schemas.py, service.py, controller.py
    repository.py, model.py, module.py
  tests/test_users.py

Modules & DI

Isolate context domains with Singletons, Scoped, or Transient lifetimes.

@Module(providers=[PostService], controllers=[PostsController], prefix="/posts")
class PostsModule: pass

@injectable
class PostService:
    def __init__(self, repo: PostRepository):
        self.repo = repo

Controllers & Routing

Bind routes with declarative decorators.

class PostsController:
    @get("/")
    async def list(self, page: Query[int] = 1) -> list[PostResponse]:
        return await self.service.list(page)

    @post("/", status=201)
    async def create(self, body: Body[CreatePostDTO]) -> PostResponse:
        return await self.service.create(body)

Models & Repository

Non-blocking async ORM with built-in CRUD.

class Post(AuraModel):
    __tablename__ = "posts"
    title: Mapped[str] = CharField(max_length=200)

class PostRepository(Repository[Post]):
    model = Post
    async def list_published(self, limit=10):
        return await Post.objects.filter(published=True).limit(limit).all()

Factories & Seeders

Generate test records with Faker integration.

class UserFactory(Factory[User]):
    model = User
    def definition(self):
        return {"name": lambda: self.faker.name(), "email": lambda: self.faker.unique.email(), "active": True}

JWT & Guards

Guard chains for endpoint security.

class UserController:
    @get("/me", guards=[JWTGuard(secret="your-key")])
    async def get_me(self, request: AuraRequest) -> dict:
        return request.state.user

Sessions Control

Encrypted cookie-based sessions.

app = Aura(modules=[UsersModule], middleware=[SessionMiddleware(secret_key="key")])

Background Jobs

SAQ-powered async task queue.

@task(queue="emails")
async def send_welcome_email(email: str):
    await mailer.send(email, "Welcome!")

@periodic(cron="0 8 * * *")
async def daily_cleanup(): pass

Async Logging

Non-blocking structured logging.

Log.info("Transaction initialized")
Log.warning("Unauthorized access", ip="192.168.1.1")