Teloce-Py

Build interactive Python apps with .vel components. No Node.js required.

Teloce-Py compiles a template, browser behavior, and scoped CSS from a single .vel file into plain browser assets. Your Python framework (Flask, FastAPI, Django, or Flaxon) keeps handling routes, APIs, databases, auth, and security.

Features

• Single-file components: template, script, and scoped style in one .vel file.
• Bring your own backend: works with Flask, FastAPI, Django, and Flaxon.
• No Node.js: production builds use MinifyJS, a native esbuild engine bundled in the wheel.
• Fast builds: tree shaking, mangling, code splitting, source maps, and hashed assets.

Getting Started

Install:

python -m pip install teloce-py Flask

Create static/js/App.vel:

<script>
export default {
  data() { return { count: 0 }; },
  methods: {
    increment() { this.count += 1; }
  }
};
</script>

<template>
  <button @click="increment">Clicked {{ count }} times</button>
</template>

Create app.py:

from pathlib import Path
from flask import Flask, render_template
from teloce.build import build_project

ROOT = Path(__file__).parent
build_project(ROOT, out_dir=ROOT / "dist", options={"dev": True})
app = Flask(__name__, static_folder="dist/static", static_url_path="/static")

@app.get("/")
def home():
    return render_template("app.html")

if __name__ == "__main__":
    app.run(debug=True)

Create templates/app.html:

<!doctype html>
<html>
  <body>
    <div id="app"></div>
    <script type="module">
      import { mount } from "{{ url_for('static', filename='js/App.js') }}";
      mount("#app");
    </script>
  </body>
</html>

Run it and open http://127.0.0.1:5000:

python app.py

Project Structure

my-app/
├── app.py
├── teloce.config.json
├── static/js/App.vel     # your source
├── templates/app.html    # HTML shell with #app mount
└── dist/                 # generated, never edit by hand

Production Build

teloce lint --strict
teloce build --source-map --hash-assets --bundle --report

Teloce strips common TypeScript syntax during compilation. The optional teloce typecheck command checks scripts and supported template expressions with PyTSCheck.

Documentation

• Documentation
• Project structure
• Examples: Flask chat, FastAPI CMS, Django Admin, Django scanner, Flaxon network, Gallery

Status

Teloce-Py is in beta. Pin your version and test generated assets on your target framework and platform.

License

MIT

Runtime contributor checks

The JavaScript runtime uses JSDoc types with a development-only checker:

npm ci --ignore-scripts
npm run typecheck

See coverage and workflow. Runtime files stay .js; Python application users do not need Node or TypeScript.

Optional component type checking

On Python 3.11+, install pip install "teloce-py[typecheck]", then run teloce typecheck ui (or teloce typecheck ui --json for CI). This checks TypeScript script blocks, .ts files/declarations, and supported template expressions using the bundled PyTSCheck compiler.

See type-checking guide for API examples, diagnostic locations, optional dependency handling, and prototype limits. Plain JavaScript components are skipped. Project tsconfig settings and dependency declarations are inherited automatically; object-style props infer supported constructor types. Props passed to statically imported TypeScript children are validated. Array-style prop values, dynamic children, and some import forms remain limited.