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

Getting started with Flaxon

Build a complete application with Python APIs, Teloce HTML components, TypeScript, scoped styles, and a protected admin in one project.

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.

Create your first application with published 0.3.0

Use Python 3.11 or newer. Install Flaxon in a virtual environment, then generate the starter:

python -m venv .venv
# Linux/macOS:
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install "flaxon[standard]"
flaxon new my-project
cd my-project
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

Open http://127.0.0.1:8000/. The welcome page's Try your Python API button calls /api/welcome/status through a TypeScript helper. Open /admin/login to sign in with the account you created.

There is no preset administrator or password. setup-admin (also createsuperuser) accepts your chosen nonempty password, up to 128 characters. With DEBUG=True, no strength warning is shown. With DEBUG=False, a weak password produces a recommendation for a long, unique production password but is still accepted. Confirmation must match. Other Admin account creation, password changes, and resets retain their existing validation policy. Password entry is hidden; passwords are hashed before storage. Create accounts before starting the server, or restart it after adding an account from the command line.

flaxon new my-project --template basic keeps the smaller Python API starter available. The default fullstack template includes the interface, module, database, and admin.

Choose your interface

Flaxon supports complete websites with Jinax (server-rendered HTML templates) and interactive applications with Teloce (compiled HTML components and TypeScript). The starter demonstrates both: / uses Teloce and /server-page uses Jinax. You can choose either for your whole application or combine them.

For a Jinax-only application, keep app.use_templates(...), remove app.use_teloce(...), and change the root route to return app.jinax.render_response("welcome.html", {"project_name": PROJECT_NAME}). Your Python modules, API routes, database, and admin remain available.

Understand the generated project

Teloce compiles the browser code; Flaxon handles requests, Python modules, persistence, and administration. The welcome example does not need a separate Node development server.

Run and extend module-owned commands

From the generated project directory, run:

flaxon welcome
flaxon welcome-status

These commands live in modules/welcome/module.py, using @welcome.cli_command(...). The first is synchronous; the second awaits the module's async status helper. flaxon_cli.py exposes them with welcome.install_cli_commands(globals()). They work without starting the web server or connecting to a database. Add commands to another feature module and install them in flaxon_cli.py; use unique names that do not conflict with built-in commands. See the module guide and CLI guide.

The welcome page links to the documentation website and uses its hosted logo. The logo and external documentation require internet access; local routes and commands work offline.

Change the application

1. Edit modules/welcome/module.py to add a Python endpoint.
2. Update api.ts to call that endpoint and describe its response with a TypeScript interface.
3. Update Welcome.html to show the result. Its scoped styles belong to the component.
4. Add a module for each feature and mount it in app.py. Keep its UI beside its Python routes.
5. Edit models, run python management.py makemigrations, review the generated Python migration, then run python management.py migrate.

Check migration status with python management.py migrate --status. python management.py createsuperuser is an alias for setup-admin; existing usernames are never overwritten. Run python management.py --help for command help.

Learn the rest of Flaxon

Follow the ten full-stack lessons in order, from your first application through TypeScript, navigation, modules, persistence, live updates, and deployment.

Before deployment, set FLAXON_DEBUG=0, use HTTPS, review permissions, back up data/, and follow the deployment and production-admin guides. The starter uses local SQLite and local uploads for a single application instance. Deploy the project sources or an editable installation; packaging your own application as a wheel requires including its UI and public files.

See ORM and settings for the complete management workflow and legacy migration transition.