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

Philosophy

Core Principles

Flaxon is built around a set of principles that guide its design, development, and long-term direction.

The goal is to create a full-stack framework that is:

  • Simple to start
  • Powerful when applications grow
  • Technology-neutral
  • Easy to debug
  • Designed for modern async applications

1. Simple Applications Remain Simple

Small applications should be easy to create without generators, complex configuration, or mandatory architecture.

Flaxon provides a minimal entry point that allows developers to build quickly.

Example:

from flaxon import Flaxon

app = Flaxon("my-app")


@app.get("/")
async def home():
    return {
        "message": "Hello"
    }
````

A simple application should remain simple.

---

# 2. Large Applications Gain Structure

As applications grow, Flaxon provides optional structure without forcing developers into a specific architecture.

Developers can gradually introduce:

* Routers
* Services
* Middleware
* Plugins
* Dependency management

Example:

```python
from flaxon import Router


api = Router(prefix="/api/v1")


@api.get("/users")
async def list_users():
    return [
        {
            "id": 1,
            "name": "Alice"
        }
    ]


app.include_router(api)

The framework should grow with the application.

3. HTML Rendering is Optional

Flaxon treats APIs and backend services as a first-class use case.

HTML rendering through Jinax is optional and loaded only when needed.

API Only

No template dependencies are required:

@app.get("/api/users")
async def get_users():
    return [
        {
            "id": 1,
            "name": "Alice"
        }
    ]

Using Templates

Templates can be added when required:

from flaxon.jinax import Jinax


app.use_templates(
    Jinax("templates")
)

Developers can choose between API-only applications or server-rendered applications.

4. Technology Neutrality

Flaxon does not force developers to use a specific frontend, database, ORM, or client technology.

You can use:

Frontend

  • React
  • Vue
  • Angular
  • Svelte
  • Flutter
  • Native mobile applications
  • Custom clients

Databases

  • PostgreSQL
  • MySQL
  • MongoDB
  • Redis
  • SQLite
  • Custom storage solutions

ORMs and Data Tools

  • SQLAlchemy
  • SQLModel
  • Tortoise ORM
  • PyMongo
  • Custom solutions

The framework should adapt to your technology choices, not restrict them.

5. Explicit and Debuggable

Framework behavior should be clear and understandable.

Flaxon avoids unnecessary hidden behavior and focuses on:

  • Clear APIs
  • Useful error messages
  • Debugging information
  • Request context visibility

Example:

raise HTTPException(
    404,
    "User not found.",
    code="FX-USER-404"
)

Errors should help developers understand what happened and how to fix it.

Design Decisions

Why ASGI?

ASGI (Asynchronous Server Gateway Interface) is the modern Python standard for asynchronous web servers.

It provides support for:

  • HTTP requests
  • WebSockets
  • Application lifecycle events

This makes it a strong foundation for async-first applications.

Why Flask-Style Routes?

Flask-style decorators are familiar to many Python developers.

They provide:

  • Simple syntax
  • High readability
  • Easy learning curve
  • Clear application structure

Example:

@app.get("/users")
async def users():
    return []

Why Async-First?

Modern applications often depend on external resources:

  • Databases
  • APIs
  • File storage
  • WebSocket connections

Async programming allows applications to efficiently handle many concurrent operations.

This is useful for:

  • Real-time applications
  • Chat systems
  • Dashboards
  • Mobile backends
  • API platforms

Why No Built-in ORM?

Flaxon is technology-neutral.

Different projects require different database approaches, so developers should choose the tools that fit their application.

Flaxon supports using:

  • SQL databases
  • NoSQL databases
  • ORMs
  • Query builders
  • Custom database layers

What Flaxon Is Not

Flaxon is designed with a specific purpose.

It is:

  • Not a full-stack framework with every feature built in.
  • Not a replacement for Node.js, Go, Rust, or other ecosystems.
  • Not designed to claim absolute performance superiority.
  • Not a compiled language.

Flaxon is Python with the advantages and tradeoffs that come with Python.

When to Use Flaxon

Flaxon is a good choice for:

  • Building APIs for React, Vue, Angular, or other frontends
  • Developing mobile application backends
  • Creating real-time applications with WebSockets
  • Building Python microservices
  • Creating scalable backend systems
  • Projects that value technology freedom
  • Teams that want clear debugging
  • Applications that start small and grow over time

When Not to Use Flaxon

Flaxon may not be the best choice when:

  • You are creating only a simple static website.
  • You require maximum CPU performance from a compiled language.
  • You need an ecosystem with decades of existing packages and integrations.

The Flaxon Vision

Flaxon aims to provide a modern Python backend experience:

Simple enough for beginners. Powerful enough for production. Flexible enough for any technology stack.

Integrated interfaces, explicit choices

Teloce is Flaxon's integrated component/compiler path. Python routes, UI pages and scoped components can live in a single feature module. Jinax remains the server-template path, and external frontends remain possible. Full-stack here means an integrated application workflow, not automatic hosting, SSR or accounts. See the ten lessons.