Teloce-Py

Author: Aldane Hutchinson

Teloce-Py is a Python-native compiler for Teloce .vel Single File Components. It lets a Python team build a reactive browser interface without adding Node, npm, a JavaScript bundler, or a framework-specific frontend stack.

The result is ordinary browser JavaScript and CSS. Your backend remains Flask, FastAPI, Django, Flaxon, or another Python server.

The problem it solves

Python web applications are excellent at routing, data access, authentication, jobs, and APIs. The difficult part is usually the interactive browser layer: teams add a second toolchain, duplicate templates, or ship large amounts of hand-written DOM code.

Teloce gives that layer a small, inspectable component model:

• one .vel file can contain template, browser behavior, and styles;
• the compiler emits self-contained browser modules;
• signals update only the DOM that depends on changed state;
• scoped CSS prevents component styles leaking into the rest of the page;
• the server framework is still responsible for HTTP, sessions, databases, and security;
• development builds can watch files, reload components, emit source maps, and bundle local imports.

Quick start

git clone https://github.com/aldanedev-create/telonce-python.git
cd teloce-python
python -m venv .venv
# Windows: .venv\\Scripts\\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install -e .

Create static/js/App.vel:

<template>
  <main class="app">
    <h1>{{ title }}</h1>
    <button @click="increment">Clicked {{ count }} times</button>
  </main>
</template>

<script>
export default {
  data() {
    return { title: "Hello from Python", count: 0 };
  },
  methods: {
    increment() { this.count++; }
  }
};
</script>

<style scoped>
.app { max-width: 40rem; margin: 4rem auto; font-family: system-ui; }
</style>

Compile a file or a project:

teloce compile static/js/App.vel -o static/js/App.js
teloce build . --out-dir dist --source-map
teloce dev . --port 5173

The generated App.js is a browser module. Put a mount point in your server template:

<div id="app"></div>
<script type="module" src="/static/js/App.js"></script>

The complete framework examples are in examples/, and the walkthroughs are in docs/.

What .vel supports

Teloce keeps the original Teloce API and adds familiar aliases for users arriving from the npm package. These forms are additive; using v-if does not remove support for the original syntax.

TypeScript is not required. Script blocks are JavaScript consumed by the compiler; Python frameworks do not need a TypeScript build step.

Framework examples

Each example is intentionally small but exercises a real server boundary and a real .vel client:

These examples use in-memory data so they can be run locally without credentials. Production applications should add authentication, CSRF protection, rate limiting, database transactions, SSRF controls, logging, and deployment-specific configuration.

Production workflow

Use the compiler as a build step, not as a request-time compiler:

from teloce.build import build_project

result = build_project(
    ".",
    out_dir="dist",
    options={"source_maps": True, "hash_assets": True, "bundle": True},
)
print(result.files)

Serve dist/ from the Python application or a reverse proxy. Keep source maps private when your deployment policy requires it. Run teloce dev during development for watching and browser HMR.

The compiler also exposes a standalone runtime for server-rendered HTML. See docs/standalone-runtime.md.

VS Code support

The upstream Teloce repository includes a VS Code extension package for .vel files. It provides syntax highlighting, diagnostics, autocomplete, hover information, formatting, snippets, symbols, and debugger integration. See the extension source and installation instructions. It can be installed from the Marketplace when published or from a locally built .vsix:

code --install-extension teloce-vscode.vsix

The Python compiler does not replace that editor tooling; it replaces the Node-based compile step for Python projects.

Compatibility with npm Teloce

The Python compiler is designed for teams that already have .vel files from Teloce on npm. Start with docs/npm-migration.md, then compile a representative component and compare its behavior in a browser. The compatibility goal covers templates, reactivity, events, conditionals, loops, components, styles, router behavior, filters, plugins, and the public createApp runtime API.

Compatibility is a contract to test, not a claim that every third-party npm plugin is automatically portable. Plugins that execute Node-only code must be rewritten as Python compiler plugins or browser-side runtime plugins.

Documentation

• Getting started
• .vel language and SFC structure
• Framework integration
• Production deployment
• Components, imports, slots, and props
• Plugins, filters, and directives
• Router and runtime
• CSS and scoped styles
• VS Code extension
• Real-world examples
• Contributing

Status

This repository is actively developed. Run the test suite before upgrading a production application:

python -m pytest

The package is currently being prepared as beta release 0.2.0b1. Treat compiler output as a build artifact, pin versions, and use browser end-to-end tests for the flows your application depends on. The beta label is intentional: the compiler, framework examples, and local diagnostics dashboard are usable, but production teams should validate their own browser and deployment matrix.

License

MIT