Flaxon 0.3.0 and Teloce-Py 0.3.0 are available on PyPI. Release instructions are maintained on this site; source links identify the framework snapshot. Check version and upgrade guidance.

Framework source · Markdown

Full-stack quick start

For generated projects, use the shared settings.py, Flaxon.from_settings(), explicit mounts in app.py, and management.py workflow. See ORM and project management for Python migrations, model registration, permission hooks, relationship editing, and Admin/CMS metadata storage. Backend-only and legacy adapter examples remain supported.

Updated starter workflow (next release)

The changes in Flaxon PR #34 require a release containing that PR. They are not included in the published 0.3.0 package. Both the full-stack and basic starters generate requirements.txt instead of pyproject.toml.

After creating the project, use its interpreter directly; activation is optional:

cd my-project
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python management.py check
.venv/bin/python management.py runserver

On Windows PowerShell:

Set-Location -LiteralPath my-project
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe management.py check
.\.venv\Scripts\python.exe management.py runserver

Run the migrations and administrator setup from the main walkthrough before using the database or Admin. The basic template uses python -m flaxon run app:app --reload instead of management.py.

Slow or interrupted creation

Files appear before setup finishes. Wait for the completion message: Python still needs to create .venv and install its bundled pip. The updated CLI shows these as separate phases, with elapsed progress and a 120-second timeout per phase. Application dependencies download only when you run pip install -r requirements.txt. Disk speed and antivirus scanning may affect environment setup; the CLI cannot guarantee an instant finish.

If setup times out or you cancel it, keep your project files and retry from the parent directory:

python -m flaxon new my-project --resume-venv --venv-timeout 300

Recovery preserves edited sources, also supports older projects containing pyproject.toml, and prints the appropriate install command. Ctrl+C stops the setup process tree. For a new project using an environment you manage yourself:

flaxon new my-project --no-venv

The updated starter disables automatic background type checking; run python management.py typecheck explicitly when needed.

Start from the published 0.3.0 project CLI

python -m pip install "flaxon[standard,admin]"
flaxon new project_manager
cd project_manager
# Activate the generated .venv, then:
python -m pip install -e .
python management.py check
python management.py makemigrations
python management.py migrate
python management.py setup-admin
python management.py runserver

For unreleased ORM features, install the repository revision or the pinned course wheel rather than assuming those features are in the latest PyPI release. Follow getting started for activation commands and the complete project-manager ebook to build a real app, one complete file at a time.

A minimal hand-written full-stack example

Build a Python API and a Teloce interface in the same project. Python 3.11+ is required. Create a virtual environment and install compatible Flaxon/Teloce releases:

python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# PowerShell: .\.venv\Scripts\Activate.ps1
python -m pip install "flaxon[standard]"

For unreleased repository features, install your local Flaxon and teloce-py checkouts with pip install -e /path/to/teloce-py -e '/path/to/flaxon[standard]'.

Create app.py:

from pathlib import Path
from flaxon import Flaxon, Request

app = Flaxon("Taskboard", debug=True)
app.use_teloce(project_root=Path(__file__).parent, ui_dir="ui", title="Taskboard")

@app.get("/api/tasks")
async def tasks():
    return {"items": [{"id": 1, "title": "Try Flaxon"}]}

@app.get("/")
async def home(request: Request):
    return await request.compile("app.html")

Create ui/app.html:

<template>
  <main>
    <h1>Taskboard</h1>
    <p role="status">{{ status }}</p>
    <ul>
      <li v-for="task in tasks" :key="task.id">{{ task.title }}</li>
    </ul>
  </main>
</template>
<script>
export default {
  data() {
    return { tasks: [], status: "Loading…" };
  },
  async mounted() {
    try {
      const response = await fetch("/api/tasks");
      if (!response.ok) {
        throw new Error("Could not load tasks");
      }
      this.tasks = (await response.json()).items;
      this.status = "Ready";
    } catch {
      this.status = "Could not load tasks. Refresh to retry.";
    }
  }
};
</script>
<style scoped>main { max-width: 48rem; margin: auto; font-family: system-ui; }</style>

Run flaxon run app:app --reload and open http://127.0.0.1:8000. The startup build turns the component into JavaScript. The returned HTML shell mounts it, then the browser fetches the Python API. Changes trigger a server restart; refresh the browser afterward. This is not browser HMR.

The fixture has no persistence or accounts. Continue with the 10 full-stack lessons to add data, validation, modules, authorization, testing and deployment. See the runnable TypeScript/CDN converter for .vel and .ts.