Quick Start Guide

Develop Python web applications quickly and efficiently!

What is Framefox?

Framefox is a modern Python web framework, designed to simplify the development of robust and maintainable web applications. Based on FastAPI, it adopts an object-oriented approach with a clear MVC architecture to improve developer productivity.

Key Features

MVC Architecture

Clear structure with separation of concerns: Models, Views, and Controllers.

Built on FastAPI

High performance with automatic type validation and OpenAPI documentation.

Interactive Terminal

Built-in commands to quickly generate controllers, entities, and forms.

Advanced Routing System

Simple route decorators with customizable names and HTTP methods.

Installation

Install Framefox via pip:
Terminal window
```
pip install framefox
```

Create a new project:

mkdir my-project
cd my-project
framefox init

Start the development server:
Terminal window
```
framefox run
```

Your application is now accessible at http://localhost:8000! 🎉

Project Structure

A Framefox project follows an organized structure:

Directorymy-project/
- Directorysrc/
  - Directorycontrollers/ User application controllers
    …
  - Directoryentity/ Database entities (models)
    …
  - Directoryrepository/ Custom repository classes
    …
- Directoryconfig/ Application configuration
  - application.yaml Main application configuration
  - debug.yaml Debug configuration
  - mail.yaml Email configuration
  - orm.yaml ORM configuration
  - parameter.yaml Application parameters
  - security.yaml Security configuration
  - services.yaml Services configuration
  - tasks.yaml Tasks configuration
- Directorypublic/ Static assets
  - …
- Directorymigrations/ Database migrations
  - …
- Directorytemplates/ Jinja2 templates
  - …
- Directoryvar/ Variable data (logs, cache)
  - …
- .env Environment variables
- requirements.txt Python dependencies
- main.py Application entry point

Your First Controller

Create a controller with the interactive terminal:

framefox create controller

Or manually create a src/controllers/home_controller.py file:

from framefox.core.routing.decorator.route import Route
from framefox.core.controller.abstract_controller import AbstractController

class HomeController(AbstractController):
    @Route("/", "home.index", methods=["GET"])
    async def index(self):
        return self.render("home/index.html", {
            "message": "Welcome to Framefox!"
        })

    @Route("/users/{id}", "home.user", methods=["GET"])
    async def show_user(self, id: int):
        return {"user_id": id, "name": f"User {id}"}

Route Decorators

The @Route decorator defines your application routes:

First parameter: The URL path (/, /users/{id})
Second parameter: The route name (home.index)
methods: Allowed HTTP methods (["GET", "POST"])

Template Rendering

Framefox uses Jinja2 for template rendering. Create src/templates/home/index.html:

<!DOCTYPE html>
<html>
<head>
    <title>My Framefox App</title>
    <link href="{{ asset('css/style.css') }}" rel="stylesheet">
</head>
<body>
    <h1>{{ message }}</h1>
    <p>URL to user: <a href="{{ url_for('home.user', id=123) }}">User 123</a></p>

    <!-- Automatic CSRF token -->
    <form method="POST">
        {{ get_csrf_token() }}
        <input type="text" name="username" placeholder="Username">
        <button type="submit">Submit</button>
    </form>
</body>
</html>

Built-in Template Functions

{{ url_for('route.name', param=value) }}: Generate URLs
{{ asset('path/file.css') }}: Links to static assets
{{ get_csrf_token() }}: Automatic CSRF protection
{{ get_current_user() }}: Authenticated user
{{ get_flash_messages() }}: Flash messages

Form Handling

Create typed forms with automatic validation:

from framefox.core.form.form_type import FormType
from framefox.core.form.field.text_type import TextType
from framefox.core.form.field.email_type import EmailType

class UserType(FormType):
    def build_form(self, form_builder):
        form_builder.add("name", TextType, {
            "required": True,
            "label": "Full Name"
        })
        form_builder.add("email", EmailType, {
            "required": True,
            "label": "Email Address"
        })

Use the form in your controller:

@Route("/register", "user.register", methods=["GET", "POST"])
async def register(self, request: Request):
    form = self.create_form(UserType)

    await form.handle_request(request)
    if form.is_submitted() and form.is_valid():
        # Process data
        data = form.get_data()
        self.flash("success", "Registration successful!")
        return self.redirect("user.success")

    return self.render("user/register.html", {"form": form})

Authentication and Security

Framefox includes a complete authentication system:

Firewall Configuration

In config/security.yaml:

security:
  firewalls:
    main:
      pattern: ^/
      authenticator: form_login
      login_path: /login
      check_path: /login_check
      default_target_path: /dashboard

  access_control:
    - path: ^/admin
      roles: [ROLE_USER, ROLE_ADMIN]
    - path: ^/profile
      roles: [ROLE_USER]

Authentication Controller

class SecurityController(AbstractController):
    @Route("/login", "security.login", methods=["GET", "POST"])
    async def login(self, request: Request):
        return self.render("security/login.html")

    @Route("/logout", "security.logout", methods=["GET"])
    async def logout(self):
        return self.redirect("security.login")

Database and ORM

Define your entities with the integrated ORM:

from sqlmodel import Field
from pydantic import EmailStr

from framefox.core.orm.abstract_entity import AbstractEntity

class User(AbstractEntity, table=True):
    id: int | None = Field(default=None, primary_key=True)
    username: str = Field(min_length=3, max_length=50)
    email: EmailStr = Field(nullable=False)

Repository Pattern

Create repositories for data access:

from framefox.core.orm.abstract_repository import AbstractRepository
from src.entity.user import User

class UserRepository(Repository):
    def __init__(self):
        super().__init__(User)

Terminal Commands

Framefox provides a powerful interactive terminal:

# Generate a controller
framefox create controller

# Generate an entity
framefox create entity

# Generate a user
framefox create user

# Generate a complete CRUD
framefox create crud

# List all routes
framefox debug router

# Clear cache
framefox cache clear

Middleware and Events

Framefox includes several built-in middlewares:

SessionMiddleware: Session management
CsrfMiddleware: CSRF protection
FirewallMiddleware: Authentication and authorization
RequestMiddleware: Request logs and profiling

Custom Events

from framefox.core.events.decorator.dispatch_event import DispatchEvent

class UserController(AbstractController):
    @Route("/users", "user.create", methods=["POST"])
    @DispatchEvent("user.before_create", "user.after_create")
    async def create_user(self, request: Request):
        # Creation logic
        return {"success": True}

Development Profiler

In development mode, access the web profiler at /_profiler to analyze:

Route information
Request performance
Logs and errors
Memory usage
Database queries

Next Steps

Build Your First App

Follow the complete tutorial to build a full application.

Explore the ORM

Learn to model your data with the integrated ORM.

Secure Your App

Configure authentication and authorization.

Deploy to Production

Deployment guide and best practices.

Ready to start? Framefox allows you to quickly develop modern and maintainable Python web applications. The framework philosophy prioritizes productivity without sacrificing flexibility!