yaafcli 2026.3.20.24240

Minimal ASGI app scaffold

yaaf

YAAF stands for "Yet Another ASGI Framework".

A minimal Python ASGI app scaffold that discovers routes from the filesystem. It includes a tiny router and a CLI wrapper around uvicorn.

Design Goals and Opinions

• Filesystem-first routing. Routes are inferred from the directory structure under consumers/**/api rather than declared with decorators. This keeps routing discoverable by looking at the tree.
• Explicit endpoint files. Each route has _server.py and _service.py to separate request handling from domain logic.
• Dependency injection without wiring. Services are registered automatically and injected by name/type, so handlers and services focus on behavior, not setup.
• Static-first routing precedence. Static routes always win over dynamic segments, with warnings when a dynamic route would overlap a static route.
• Minimal core. The framework is intentionally small and opinionated, leaving room for you to add auth, middleware, validation, etc.

Quickstart

python -m venv .venv
source .venv/bin/activate
pip install -e .

# Run the built-in example routes
yaaf --reload

Example routes:

• GET /api/hello
• GET /api/<name> (dynamic segment)

Routing Model

Routes are inferred from the directory structure under any consumers/**/api directory.

• Every route directory must contain _server.py and _service.py.
• The route path is /api/... plus the sub-path after api/.
• Dynamic segments use [param] directory names and are exposed as params/path_params.

Example layout:

consumers/
  api/
    users/
      _server.py
      _service.py
    hello/
      _server.py
      _service.py
    name_dynamic/
      _server.py
      _service.py

Services (_service.py)

Use the @service decorator to mark and register services:

from yaaf import service


@service("UsersService")
class UsersService:
    def get_user(self, user_id: str) -> dict:
        return {"id": user_id, "name": "User"}


service = UsersService

Decorator Options:

• name: Custom service name for DI resolution (defaults to class name)
• aliases: Additional names to resolve by

Handlers (_server.py)

Export lowercase HTTP method functions. Import services directly from their source modules:

from yaaf import Request
from yaaf.types import Params
from consumers.api.users._service import UsersService


async def get(request: Request, params: Params, service: UsersService) -> dict:
    user_id = params.get("id", "1")
    return service.get_user(user_id)

Injectable Parameters:

• request gives you the yaaf.Request object
• params or path_params provides dynamic route parameters
• Services are injected by type annotations

Service Dependencies

Services can depend on other services via constructor injection:

# users/_service.py
from yaaf import service


@service("UsersService")
class UsersService:
    def get_user(self, user_id: str) -> dict:
        return {"id": user_id, "name": "User"}


service = UsersService

# hello/_service.py
from yaaf import service
from consumers.api.users._service import UsersService


@service("HelloService")
class HelloService:
    def __init__(self, users: UsersService) -> None:
        self._users = users

    def message(self) -> str:
        user = self._users.get_user("1")
        return f"Hello, {user['name']}"


service = HelloService

Running Another App

yaaf --app your_package.app:app

Versioning

This project uses calendar-based versions with a timestamp (UTC). To bump the version:

python scripts/bump_version.py