Python FastHTML : Guide du débutant avec exemples

Les arguments positionnels transmis aux fonctions d'éléments Python sont rendus comme des éléments enfants dans la structure HTML résultante. Par exemple,

Div(
	P("Hello, world!"),
	Ul(Li("one"), Li("two"))
)

produira cette sortie HTML : 

<div>
  <p>Hello, world!</p>
  <ul>
    <li>one</li>
    <li>two</li>
  </ul>
</div>

Les arguments des mots-clés deviennent des attributs HTML. Par exemple, le code Python

A("Docs", href="/docs", cls="button", hx_get="/info")

est rendu en

<a href="/docs" class="button" hx-get="/info">Docs</a>

Notez que le mot-clé cls correspond à l'attribut class en HTML. Les soulignés dans les noms d'attributs (hx_get) sont convertis en traits d'union (hx-get). 

FastHTML diffère la sérialisation, ce qui permet aux routes de renvoyer des objets Python plutôt que des chaînes HTML brutes. Le cadre ne convertit l'arbre d'objets Python en HTML qu'à l'étape finale, juste avant l'envoi de la réponse. Cette conception permet de conserver une logique propre et de ne pas avoir à manipuler manuellement les chaînes de caractères.

FastHTML offre les avantages d'une gestion sûre des templates et des attributs, ce qui permet d'obtenir un code plus clair et plus facile à maintenir. Les API et les attributs des éléments apparaissent dans les définitions des fonctions ou des classes, ce qui rend le code explicite. Les noms sûrs pour Python (hx-post à hx_post) évitent la nécessité d'une manipulation manuelle des chaînes de caractères.

Le remaniement est plus sûr et plus fiable. Renommer un paramètre met automatiquement à jour les usages. En outre, les tests unitaires peuvent directement instancier et valider les objets des composants, ce qui évite d'avoir à recourir à des expressions rationnelles pour le rendu HTML.

Intégration de l'interface ASGI (Asynchronous Server Gateway Interface)

FastHTML s'intègre à ASGI, un standard communautaire pour Python qui permet une communication non bloquante et pilotée par les événements entre les serveurs web et les applications. ASGI alimente les frameworks web Python modernes en prenant en charge les opérations asynchrones au cœur de la pile web.

Les serveurs web comme Uvicorn adhèrent à la spécification ASGI, ce qui garantit la compatibilité et l'évolutivité. Des frameworks tels que Starlette et FastHTML s'appuient sur ASGI pour fournir un routage robuste, des intergiciels et des API de haut niveau.

Cette architecture offre un haut niveau de concurrence, une prise en charge intégrée des événements HTTP, WebSocket et envoyés par le serveur, ainsi qu'un traitement efficace des requêtes axé sur les événements. En utilisant une boucle d'événements asyncio, les applications ASGI évitent la surcharge d'un thread OS par connexion, ce qui permet à quelques threads de gérer des milliers de clients. L'objet scope normalisé et la conception non bloquante permettent aux gestionnaires de faire une pause pour les E/S sans ralentir les autres demandes.

Interactivité pilotée par HTMX

Avec la bibliothèque HTMX, vous pouvez étendre les attributs HTML standard avec les attributs hx-*. Ces éléments vous permettent d'envoyer des requêtes HTTP et de remplacer dynamiquement le contenu de la page par des fragments renvoyés par le serveur. Vous n'avez pas besoin de JavaScript personnalisé. 

Démarrer avec FastHTML

La prise en main de FastHTML est simple. Les principales étapes sont décrites dans les sections ci-dessous. 

Installation et configuration

Pour installer FastHTML, utilisez pip install python-fasthtml.

Première application

Construisons une application simple pour afficher un en-tête et un message.

from fasthtml.common import FastHTML, serve, Div, H1, P

app = FastHTML()

@app.get("/")
def home():
    return Div(
        H1("Welcome to FastHTML"),
        P("Hello, world!")
    )

if __name__ == "__main__":
    serve()

Exécutez le fichier en tapant python app.py dans le terminal. 

Contrôlez le lien pour ouvrir votre application. Vous verrez une page :

Définir un itinéraire

Ajoutons une page "A propos" à notre application. Utilisez le code suivant :

from fasthtml.common import FastHTML, serve, Div, H1, P, A

app = FastHTML()

@app.get("/")
def home():
    return Div(
        H1("Welcome to FastHTML"),
        P("Hello, world!"),
        A("About", href="/about")
    )

@app.get("/about")
def about():
    return Div(
        H1("About"),
        P("This is the about page."),
        A("Home", href="/")
    )

if __name__ == "__main__":
    serve()

La ligne A("About", href="/about") crée un lien entre la page d'accueil et la page "à propos". Le décorateur @app.get("/about") définit l'itinéraire de la page "about".

Mise en œuvre de base

Dans FastHTML, les modèles d'interface utilisateur réutilisables sont encapsulés dans de simples fonctions Python. Ces fonctions renvoient des objets composants imbriqués, ce qui vous permet de traiter des widgets tels que Card ou Navbar comme des objets appelables. 

Le fait de définir le balisage, les attributs et le style en un seul endroit garantit la cohérence de l'application. Lorsque vous importez et utilisez ces fonctions, toute modification visuelle ou comportementale se propage automatiquement. 

Cette approche réduit le code répété, ce qui rend votre frontend aussi facile à tester et à remanier que n'importe quel module Python.

Pour le démontrer, créons une page qui affiche deux cartes simples.

from fasthtml.common import *

def Card(title: str, body: str):
    children = [
        H2(title, cls="card-title"),
        P(body, cls="card-body")
    ]
    return Div(
        *children,
        cls="card",
        style="background- border-radius: 0.5rem;"
    )

app = FastHTML()

@app.get("/")
def home():
    return Div(
        Card("Welcome", "A welcome card."),
        P(''),
        Card("A Second Card", "This is another card."),
        cls="page"
    )

La fonction Card prend comme arguments une chaîne title et une chaîne body et renvoie un élément de carte avec un style de base. Dans l'itinéraire home, ce widget est utilisé deux fois sans duplication de code. Nous définissons le site Card une fois pour toutes et nous le réutilisons en fonction des besoins, ce qui garantit la cohérence du balisage et du style dans l'ensemble de l'application.

Il y a plusieurs avantages à créer des widgets d'interface utilisateur de cette manière.

• Réduction de la duplication: Définissez le balisage et le style une fois pour toutes et réutilisez le composant partout où vous en avez besoin. Les mises à jour ou les corrections de bogues se propagent automatiquement.
• Conception cohérente de l'interface utilisateur: Chaque instance de votre composant conserve la même structure, les mêmes classes et le même comportement. Cela renforce l'uniformité de l'aspect et de la sensation dans l'ensemble de l'application.
• Entretien simplifié : Une base de code plus petite et DRY signifie moins de fichiers à gérer, moins d'éléments superflus et un développement plus efficace.

Utilisation avancée

Cette section explore les techniques avancées de FastHTML, y compris la gestion des formulaires, la validation et les modèles de retour d'erreur. En tirant parti des classes Python et des composants structurés, vous pouvez construire des formulaires robustes et conviviaux tout en conservant un code propre et testable.

Traitement et validation des formulaires

FastHTML simplifie la gestion des formulaires en générant automatiquement des formulaires HTML à partir de classes Python et en fournissant une liaison de données directe pour le traitement des soumissions de formulaires. 

Par exemple, considérez le code suivant.

from fasthtml.common import *
from dataclasses import dataclass

@dataclass
class Profile:
    name:str;
    email:str;
    age:int

profile_form = Form(method="post", action="/profile")(
        Fieldset(
            Label("Name", Input(name="name")),
            Label("Email", Input(name="email")),
            Label("Age", Input(name="age")),
        ),
        Button("Submit", type="submit"),
    )

# Instantiate app
app = FastHTML()

# GET / serves the form (FastHTML will serialize the component to HTML)
@app.get("/")
def home():
    return profile_form

# Simple POST handler to echo back submitted data
@app.post("/profile")
def profile(data: Profile):
    return Div(
        H1("Profile Submitted"),
        P(f"Name: {data.name}"),
        P(f"Email: {data.email}"),
        P(f"Age: {data.age}")
    )

Ce code génère le code HTML suivant pour le formulaire. FastHTML analyse automatiquement les données du formulaire dans l'objet Profile, en supposant que les noms des champs sont compatibles. Sous le capot, cela peut reposer sur une analyse de formulaire de type Starlette et une couche de validation personnalisée.

<form enctype="multipart/form-data" method="post" action="/profile">
	<fieldset>
	<label>Name<input name="name"></label>
	<label>Email<input name="email"></label>
	<label>Age<input name="age"></label>
</fieldset>

	<button type="submit">Submit</button>
</form>

Une fois le formulaire soumis, FastHTML analyse les données du formulaire dans l'objet Profile. La route profile renvoie ensuite une page de confirmation, affichant les valeurs soumises directement à partir de l'objet data. Cette approche simplifie la gestion des formulaires, réduit la paperasserie et garantit un typage solide des données dans l'ensemble de votre application.

C'est toujours une bonne idée de valider les entrées d'un formulaire. Ajoutez la logique de validation en réécrivant la route /profile comme suit.

@app.post("/profile")
def submit_profile(data: Profile):
    # Form validation
    if not data.name.strip():
        raise HTTPException(status_code=400, detail="Name is required")
    if not data.email.strip() or "@" not in data.email:
        raise HTTPException(status_code=400, detail="A valid email is required")
    if data.age < 0:
        raise HTTPException(status_code=400, detail="Age must be non-negative")
    
    # If validation passes, render the result
    return Div(
        H1("Profile Submitted"),
        P(f"Name: {data.name}"),
        P(f"Email: {data.email}"),
        P(f"Age: {data.age}")
    )

Si name est manquant, email est manquant ou age est négatif, l'utilisateur reçoit un message d'erreur clair. En envoyant un message HTTPException avec un code d'état 400, l'application communique l'erreur de validation spécifique, ce qui aide l'utilisateur à corriger sa saisie avant de soumettre à nouveau le formulaire.

Une manière plus robuste de traiter les données manquantes ou invalides consiste à effectuer un contrôle d'erreur explicite et à fournir un retour d'information convivial. Par exemple, réécrivez le code comme suit.

from fasthtml.common import *
from dataclasses import dataclass

@dataclass
class Profile:
    name: str
    email: str
    age: int

def profile_form(data=None, errors=None):
    data   = data   or {}
    errors = errors or {}
    return Form(
        Fieldset(
            Label(
                "Name",
                Input(
                    name="name",
                    value=data.get("name", ""),
                    placeholder="Your name"
                )
            ),
            Small(errors.get("name", ""), cls="error-text"),

            Label(
                "Email",
                Input(
                    name="email",
                    type="email",
                    value=data.get("email", ""),
                    placeholder="you@example.com"
                )
            ),
            Small(errors.get("email", ""), cls="error-text"),

            Label(
                "Age",
                Input(
                    name="age",
                    type="number",
                    value=str(data.get("age", "")),
                    placeholder="Age"
                )
            ),
            Small(errors.get("age", ""), cls="error-text"),
        ),
        Button("Submit", type="submit")
    , method="post", action="/profile", id="profile-form", hx_swap="outerHTML")

app = FastHTML()

@app.get("/")
def home():
    return Div(
        H1("Create Your Profile"),
        profile_form()
    )

@app.post("/profile")
async def submit_profile(request):
    form = await request.form()
    data = {
        "name":  form.get("name", "").strip(),
        "email": form.get("email", "").strip(),
    }
    errors = {}

    # Validate name
    if not data["name"]:
        errors["name"] = "Name is required. "

    # Validate email
    if not data["email"]:
        errors["email"] = "Email is required. "
    elif "@" not in data["email"]:
        errors["email"] = "Enter a valid email address."

    # Validate age
    age_raw = form.get("age", "").strip()
    try:
        age = int(age_raw)
        if age < 0:
            raise ValueError()
        data["age"] = age
    except ValueError:
        errors["age"] = "Age must be a non-negative integer. "

    if errors:
        # re-render form with submitted values and error messages
        return Div(
            H1("Create Your Profile"),
            profile_form(data, errors)
        )

    # Success path
    profile = Profile(**data)
    return Div(
        H1("Profile Submitted"),
        P(f"Name: {profile.name}"),
        P(f"Email: {profile.email}"),
        P(f"Age: {profile.age}")
    )

if __name__ == "__main__":
    serve()

Si l'utilisateur saute un champ obligatoire ou fournit des données non valables, il verra le formulaire réaffiché avec les valeurs soumises et les messages d'erreur appropriés affichés à côté de chaque champ. Cette approche améliore l'expérience de l'utilisateur en indiquant clairement ce qui doit être corrigé.

Une fois que vous avez rempli tous les champs et que vous les avez soumis, vous obtenez un écran similaire à celui qui suit.

Authentification et gestion des sessions

Mise en œuvre des flux d'authentification

Dans FastHTML, les données de session sont gérées par l'objet request.session, qui se comporte comme un dictionnaire Python. Vous pouvez stocker des données dans la session en définissant des paires clé-valeur, telles que session['user_id'] = 123. Pour récupérer les données de session, utilisez read (user_id = session.get('user_id')). To clear all session data, call session.clear().

En coulisses, FastHTML sérialise le dictionnaire de session dans un cookie signé, qui persiste à travers les requêtes. Cette approche vous permet de gérer l'authentification des utilisateurs et l'état des sessions à l'aide de modèles Python familiers.

Aperçu de l'élaboration de flux de travail d'authentification

Pour créer un flux de travail d'authentification, suivez les étapes suivantes.

1. Configurez les sessions : Ajouter SessionMiddleware with a strong secret_key. Once configured, the request.session is available in every handler.
2. Modèle d'utilisateur et gestion des mots de passe : Définissez un schéma d'utilisateur (à l'aide d'une classe de données, d'un modèle pydantique ou d'un ORM) qui inclut un nom d'utilisateur and password_hash. Use a hashing function (e.g., hashlib, pbkdf2_hmac, bcrypt) to store and verify passwords.
3. Flux d'inscription* : Créez un GET /register route to render a signup form. * Utilisez un POST /register to validate form input, hash the password, save the user record, set the session['user_id'], and redirect to a protected page or dashboard.
4. Flux de connexion* : Créez un GET /login route to display login form. * Utilisez un POST /login to verify credentials. On success, write session['user_id'] and redirect; on failure, re-render the form with an error message.
5. Protéger les itinéraires : Créez une fonction d'aide ou un décorateur qui vérifie session.get('user_id'). If the user is not authenticated, redirect to /login; otherwise, allow access to the requested route.
6. Flux de déconnexion : Dans le GET /logout route, call session.clear()` pour supprimer les données de session et rediriger l'utilisateur vers la page de connexion ou la page d'accueil.

Intégration des bases de données

Un mappeur objet-relationnel (ORM) associe des classes à des tableaux de base de données, ce qui vous permet d'interroger les données à l'aide d'objets natifs plutôt qu'à l'aide d'un langage SQL brut. Les options les plus populaires sont SQLAlchemy et l'ORM de Django. 

FastHTML dispose d'une interface "ORM-like" qui s'intègre à n'importe quel ORM ou bibliothèque de requêtes Python asynchrone. Il utilise par défaut SQLite mais peut s'intégrer à n'importe quelle base de données. Par exemple, considérez le code suivant.

# Database setup (SQLite by default, but backend can change)
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker, declarative_base
from sqlalchemy import Column, Integer, String, select
from fasthtml.common import *

DATABASE_URL = "sqlite+aiosqlite:///./test.db"  # Change backend here (e.g., PostgreSQL)

engine = create_async_engine(DATABASE_URL, echo=True)
SessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
Base = declarative_base()

# ORM model
class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)

# FastHTML app
app = FastHTML()

@app.get("/")
async def list_users():
    async with SessionLocal() as session:
        result = await session.execute(select(User))
        users = result.scalars().all()
    
    return Div(
        H1("Users"),
        Ul(*[Li(user.name) for user in users])
    )

if __name__ == "__main__":
    import asyncio
    async def init_db():
        async with engine.begin() as conn:
            await conn.run_sync(Base.metadata.create_all)
    asyncio.run(init_db())
    serve()

Dans une application FastHTML, vous interrogez les données dans la couche de base de données que vous avez choisie, puis vous transmettez les résultats aux composants FastHTML pour le rendu. Par exemple, après avoir extrait des enregistrements de votre base de données, vous pouvez les parcourir en boucle dans un gestionnaire de route et construire des structures HTML telles que des tableaux, des listes ou des cartes personnalisées.

Les meilleures pratiques s'appliquent toujours : ne sélectionnez que les champs nécessaires, filtrez et triez au niveau de la base de données et paginez les grands ensembles de résultats. FastHTML vous aide à vous concentrer sur la construction d'interfaces propres et dynamiques tout en laissant le traitement des données aux meilleurs outils pour votre projet.

Stratégies d'optimisation des performances

Il y a plusieurs façons d'obtenir les meilleurs résultats en utilisant FastHTML. Nous vous présentons ci-dessous quelques-unes de ces recommandations. 

Mécanismes de mise en cache

La mise en cache améliore les performances en évitant le travail redondant à différents niveaux de votre application. Au niveau du navigateur et du CDN, utilisez les en-têtes de contrôle du cache pour conserver les ressources statiques telles que les images, les scripts et les feuilles de style. 

Vous pouvez mettre en cache des réponses entières ou des parties coûteuses dans votre cadre web. Dans votre application FastHTML, vous mettez en cache des réponses à des itinéraires entiers ou des composants coûteux, ce qui garantit que les requêtes répétées reviennent rapidement sans avoir à réinterroger la base de données ou à régénérer les modèles.

En Python, vous pouvez mettre en œuvre la mise en cache au niveau des fonctions à l'aide de décorateurs. Par exemple, le décorateur intégré functools.lru_cache peut mémoriser une fonction d'aide qui récupère les données de l'utilisateur. Par exemple, vous pouvez utiliser ce décorateur pour mettre en cache les appels à la base de données :

from functools import lru_cache

@lru_cache(maxsize=64)
def fetch_user_profile(user_id):
    # simulate an expensive database call
    return db.get_user(user_id)

@app.get("/profile/{user_id}")
def profile(user_id: int):
    profile = fetch_user_profile(user_id)
    return Div(P(profile.name), P(profile.email))

Files d'attente asynchrones

Les applications web restent réactives en se déchargeant des tâches fastidieuses du cycle de demande. Au lieu de bloquer le serveur pendant la génération de rapports, l'envoi de courriers électroniques ou le traitement de données, ces tâches sont mises en file d'attente et exécutées en arrière-plan. 

Avec cette approche, votre application envoie une réponse immédiate à l'utilisateur tandis que les travailleurs, qui s'exécutent dans des processus ou des threads distincts, traitent les tâches en attente de manière asynchrone.

FastHTML prend en charge l'exécution de tâches en arrière-plan en s'intégrant à l'application Starlette BackgroundTasks. Voici un exemple qui montre comment envoyer un courriel de bienvenue après l'inscription d'un utilisateur.

from fasthtml.common import FastHTML, serve, Div, Form, Input, Button
from starlette.background import BackgroundTasks

app = FastHTML()

def send_welcome_email(email: str):
    # expensive or time consuming work
    ...

@app.post("/signup")
def signup(background_tasks: BackgroundTasks, request):
    form = await request.form()
    email = form["email"]
    # schedule the email task
    background_tasks.add_task(send_welcome_email, email)
    return Div("Thanks for signing up! You will receive an email shortly.")

Applications dans le monde réel

FastHTML est un framework polyvalent qui peut alimenter une large gamme d'applications web. Voyons comment vous pourriez aborder la construction d'une plateforme de commerce électronique et d'un tableau de bord de données à l'aide de FastHTML.

Schéma directeur d'une plate-forme de commerce électronique

Construisons une plateforme de commerce électronique avec FastHTML. Commencez par modéliser vos données principales sous forme de classes ORM ou de classes de données Python : produits, utilisateurs et articles du panier. 

Créez une page de liste de produits qui parcourt en boucle les enregistrements de vos produits. Pour chaque produit, utilisez un composant Python réutilisable, tel que Card, pour afficher le produit, l'image, le nom, le prix et un bouton "Ajouter au panier". Ce bouton comprend des attributs HTMX tels que hx_post et hx_target, qui lui permettent d'envoyer une demande d'ajout de l'article au panier de la session de l'utilisateur sans recharger la page entière.

Le panier lui-même est stocké dans le dictionnaire session de l'utilisateur sur le serveur. Dans l'en-tête de votre site, incluez un composant de récapitulation du panier qui se met à jour dynamiquement à l'aide de HTMX lorsque des articles sont ajoutés ou supprimés. 

La page du panier lit les données de la session pour afficher chaque article du panier ainsi que le total général. Il propose également un formulaire de paiement qui se connecte à une classe Python pour la validation. Lorsque l'utilisateur soumet le formulaire, votre application crée un enregistrement de commande et vide le panier de la session.

Mise en place d'un tableau de bord de données

Un tableau de bord de données en FastHTML combine des composants Python avec vos sources de données, en utilisant HTMX pour l'interactivité et les mises à jour en temps réel. Votre logique d'arrière-plan (par exemple, des fonctions d'aide asynchrones, des utilitaires CRUD mis en cache ou des requêtes ORM) récupère les données nécessaires. 

À partir de là, vous concevez une page avec des widgets réutilisables. Il peut s'agir de contrôles de filtrage (comme des menus déroulants, des sélecteurs de date ou des champs de recherche) pour affiner les requêtes, de cartes KPI pour afficher les indicateurs clés, de tableaux de données pour répertorier les enregistrements ou de graphiques pour visualiser les tendances et les comparaisons. 

Chaque widget est écrit sous la forme d'un code Python natif, généralement un composant Div, Table, ou un composant personnalisé Card. FastHTML transforme automatiquement ces objets en HTML au moment de la réponse.

HTMX permet aux tableaux de bord d'être interactifs. Par exemple, les widgets de filtre peuvent utiliser hx_get et hx_post pour demander des données filtrées au serveur, mettant ainsi à jour dynamiquement un tableau ou un graphique sans nécessiter un rechargement complet de la page. 

Analyse comparative avec les cadres traditionnels

FastHTML se distingue des frameworks traditionnels comme Django et Flask en rationalisant à la fois le développement et les performances. Voyons comment il se situe par rapport à des facteurs clés tels que le temps d'installation, l'efficacité du code et les critères de performance.

Vitesse de développement

FastHTML présente deux avantages majeurs par rapport à des frameworks tels que Django et Flask : le temps d'installation et l'efficacité du code.

Temps de préparation

L'approche "batteries incluses" de Django nécessite plusieurs étapes avant que vous puissiez servir votre première page : installer le paquet, exécuter django-admin startproject, configurer les paramètres et définir une application. Cela implique souvent plusieurs fichiers et beaucoup de code de base avant que vous n'écriviez une véritable logique.

Le flacon est plus léger. Après pip install, vous pouvez écrire plusieurs itinéraires dans un seul fichier. Cependant, vous devez encore configurer les modèles Jinja, les dossiers statiques et ajouter du JavaScript pour l'interactivité.

Avec FastHTML, l'installation est minimale.

1. Exécutez pip install python-fasthtml uvicorn.
2. Définir les routes et les composants HTML Python. Vous pouvez le faire dans un seul fichier.
3. Appelez serve().

Il n'est pas nécessaire de disposer d'un moteur de modèles distinct ou d'une configuration de dossiers statiques. Vous pouvez commencer à construire immédiatement.

Efficacité du code

Avec Django, même une simple page "Hello, world" nécessite plusieurs fichiers : views.py, urls.py, settings.py, templates/hello.html, plus l'ORM et l'échafaudage d'administration.

Flask simplifie ce processus en un seul fichier, mais vous devez toujours écrire manuellement du HTML dans des modèles Jinja ou des chaînes en ligne, et du JavaScript pour l'interactivité.

FastHTML vous permet de définir votre interface utilisateur sous forme d'objets Python, de sorte qu'il n'est pas nécessaire de changer de fichier ou de langage. HTMX gère l'interactivité de manière déclarative, sans scripts personnalisés. Il en résulte un nombre réduit de lignes de code, l'absence de modèles distincts ou de pipelines de ressources statiques, et une surface testable unique pour le balisage et le comportement.

Critères de performance