fracode 0.1.2

Fun Reliable Applications in Python

FraCode - Fun Reliable Applications in Python

FraCode is an opinionated FastAPI framework for teams that want controller-style organization, a clear project structure, and a batteries-included development workflow.

Full documentation

Features

• A framework-level app model built around controllers and explicit route modules
• FraCode router sugar that stays compatible with native FastAPI handlers
• CLI commands for scaffolding projects, controllers, models, and database setup
• Explicit route module loading from app/routes/__init__.py
• Async SQLAlchemy support for SQLite and PostgreSQL
• Built-in DB dependency helpers, CORS support, and JSON error responses
• Built on FastAPI and ASGI under the hood

Quick Start

# Install FraCode
pip install fracode

# Create a new project
fra new my-app
cd my-app

# Run the development server
fra serve

Your app is now running at http://127.0.0.1:8000.

FraCode adds structure on top of FastAPI. FastAPI still provides the typing, validation, dependency injection, background task, and OpenAPI model underneath it.

Route loading is explicit by default:

# app/routes/__init__.py
ROUTE_MODULES = (
    "app.routes.web",
    "app.routes.api",
)

Visit the documentation for detailed guides and examples.

Rule of thumb: FraCode can add structure, but it should not replace FastAPI's typing and validation model.

Both of these remain first-class:

from fastapi import Depends
from pydantic import BaseModel
from fracode.http import Router


class CreateUser(BaseModel):
    name: str
    email: str


async def get_current_user():
    return {"id": 1}


router = Router()


@router.post("/users")
async def create_user(payload: CreateUser, current_user=Depends(get_current_user)):
    return {"user": payload.model_dump(), "actor": current_user}

from fastapi import Depends
from pydantic import BaseModel
from fracode.http import Controller, Router


class CreateUser(BaseModel):
    name: str
    email: str


async def get_current_user():
    return {"id": 1}


class UserController(Controller):
    async def store(
        self,
        payload: CreateUser,
        current_user=Depends(get_current_user),
    ):
        return self.ok({"user": payload.model_dump(), "actor": current_user})


router = Router()
router.post("/users", UserController.store)

Documentation

For detailed documentation including:

• Complete CLI reference
• Routing and controllers guide
• Database and ORM usage
• Configuration options
• Testing guide
• API documentation

Visit fracode.com

Development And Testing

FraCode uses modern Python tooling to ensure code quality:

Code Quality Tools

• Ruff - Fun Python linter and formatter
• MyPy - Static type checker
• pytest - Testing framework with async support

Run Tests

# Run all tests with coverage
pytest

# Run specific test file
pytest tests/test_routing.py -v

# Generate HTML coverage report
pytest --cov=fracode --cov-report=html

Linting & Type Checking

# Run all checks
ruff check fracode/ tests/
ruff format fracode/ tests/
mypy fracode/

# Auto-fix issues
ruff check --fix fracode/ tests/
ruff format fracode/ tests/

CI Pipeline

All PRs and commits are automatically checked for:

• Code formatting and linting
• Type checking
• Test coverage
• Package building

View the CI status and coverage reports.

Contributing

We welcome contributions! Please ensure your code passes all quality checks:

# Clone and setup
git clone https://github.com/iamceeso/fracode.git
cd fracode
poetry install --with dev

# Run tests
pytest

# Run all quality checks
ruff check fracode/ tests/
ruff format --check fracode/ tests/
mypy fracode/

See CONTRIBUTING.md for details.

License

FraCode is open-source software licensed under the MIT license.

Acknowledgments

• Built on top of FastAPI
• Inspired by Laravel
• ORM powered by SQLAlchemy

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

---

Built by Chidi E.