Python FastHTML: Um guia para iniciantes com exemplos

Os argumentos posicionais passados para as funções de elemento Python são renderizados como elementos filhos na estrutura HTML resultante. Por exemplo,

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

produzirá esse resultado em HTML: 

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

Os argumentos da palavra-chave se tornam atributos HTML. Por exemplo, o código Python

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

é renderizado em

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

Observe que a palavra-chave cls mapeia o atributo class em HTML. Os sublinhados nos nomes de atributos (hx_get) são convertidos em hífens (hx-get). 

O FastHTML adia a serialização, o que permite que as rotas retornem objetos Python em vez de strings HTML brutas. A estrutura só converte a árvore de objetos Python em HTML na etapa final, pouco antes de enviar a resposta. Esse design mantém a lógica limpa e livre de manipulação manual de strings.

O FastHTML oferece os benefícios da manipulação de modelos e atributos com segurança de tipo, resultando em um código mais claro e de melhor manutenção. As APIs e os atributos dos elementos aparecem nas definições de funções ou classes, tornando o código autoexplicativo. Os nomes seguros para Python (hx-post a hx_post) evitam a necessidade de manipulação manual de strings.

A refatoração é mais segura e confiável. A renomeação de um parâmetro atualiza os usos automaticamente. Além disso, os testes de unidade podem instanciar e validar diretamente os objetos do componente, o que evita a necessidade de depender de regexes em relação ao HTML renderizado.

Integração da interface de gateway de servidor assíncrono (ASGI)

O FastHTML se integra ao ASGI, um padrão orientado pela comunidade para Python que permite a comunicação sem bloqueio e orientada por eventos entre servidores da Web e aplicativos. O ASGI potencializa as estruturas modernas da Web em Python, oferecendo suporte a operações assíncronas no núcleo da pilha da Web.

Servidores da Web como o Uvicorn aderem à especificação ASGI, garantindo compatibilidade e escalabilidade. Estruturas como Starlette e FastHTML se baseiam em ASGI para fornecer roteamento robusto, middleware e APIs de alto nível.

Essa arquitetura oferece alta simultaneidade, suporte integrado a HTTP, WebSocket e eventos enviados pelo servidor, além de tratamento eficiente de solicitações orientadas por eventos. Ao usar um loop de eventos asyncio, os aplicativos ASGI evitam a sobrecarga de um thread do sistema operacional por conexão, o que permite que alguns threads lidem com milhares de clientes. O objeto de escopo padronizado e o design sem bloqueio permitem que os manipuladores façam pausas para E/S sem diminuir a velocidade de outras solicitações.

Interatividade orientada por HTMX

Com a biblioteca HTMX, você pode adicionar atributos HTML padrão estendidos com atributos hx-*. Esses elementos permitem que você envie solicitações HTTP e substitua dinamicamente o conteúdo da página por fragmentos retornados pelo servidor. Você não precisa de JavaScript personalizado. 

Primeiros passos com o FastHTML

Para começar a usar o FastHTML, você precisa apenas de um simples clique. Descrevemos as principais etapas nas seções abaixo. 

Instalação e configuração

Para instalar o FastHTML, use pip install python-fasthtml.

Primeiro aplicativo

Vamos criar um aplicativo simples para exibir um cabeçalho e uma mensagem.

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()

Para executar o arquivo, digite python app.py no terminal. 

Clique com o botão direito do mouse no link para abrir o aplicativo. Você verá uma página:

Definição de uma rota

Vamos adicionar uma página Sobre ao nosso aplicativo. Use o código a seguir:

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()

A linha A("About", href="/about") cria um link da página inicial para a página sobre. O decorador @app.get("/about") define a rota para a página sobre.

Implementação básica

No FastHTML, os padrões de interface do usuário reutilizáveis são encapsulados em funções simples do Python. Essas funções retornam objetos de componentes aninhados, permitindo que você trate widgets como Card ou Navbar como objetos chamáveis. 

A definição da marcação, dos atributos e do estilo em um único local garante a consistência em todo o aplicativo. Quando você importa e usa essas funções, todas as alterações visuais ou comportamentais se propagam automaticamente. 

Essa abordagem reduz o código repetido, tornando seu frontend tão fácil de testar e refatorar quanto qualquer módulo Python.

Para demonstrar isso, vamos criar uma página que exibe dois cartões 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"
    )

A função Card usa uma string title e uma body como argumentos e retorna um elemento de cartão com estilo básico. Na rota home, esse widget é usado duas vezes sem duplicar o código. Definimos o Card uma vez e o reutilizamos conforme necessário, garantindo marcação e estilo consistentes em todo o aplicativo.

Há várias vantagens em criar widgets de interface do usuário dessa maneira.

• Redução da duplicação: Defina a marcação e o estilo uma vez e reutilize o componente sempre que necessário. As atualizações ou correções de bugs se propagam automaticamente.
• Design consistente da interface do usuário: Cada instância do seu componente mantém a mesma estrutura, as mesmas classes e o mesmo comportamento. Isso reforça uma aparência uniforme em todo o aplicativo.
• Manutenção simplificada: Uma base de código menor e DRY significa menos arquivos para gerenciar, menos boilerplate e um desenvolvimento mais eficiente.

Uso avançado

Esta seção explora técnicas avançadas no FastHTML, incluindo manipulação de formulários, validação e padrões de feedback de erros. Ao aproveitar as classes Python e os componentes estruturados, você pode criar formulários robustos e fáceis de usar, mantendo o código limpo e testável.

Manuseio e validação de formulários

O FastHTML simplifica o manuseio de formulários, gerando automaticamente formulários HTML a partir de classes Python e fornecendo uma vinculação de dados direta para o processamento de envios de formulários. 

Por exemplo, considere o código a seguir.

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}")
    )

Esse código gera o seguinte HTML para o formulário. O FastHTML analisa automaticamente os dados do formulário no objeto Profile, assumindo nomes de campo compatíveis. Na parte interna, isso pode depender da análise de formulários no estilo Starlette e de uma camada de validação personalizada.

<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>

Depois que o formulário é enviado, o FastHTML analisa os dados do formulário no objeto Profile. A rota profile retorna uma página de confirmação, exibindo os valores enviados diretamente do objeto data. Essa abordagem simplifica o manuseio de formulários, reduz o boilerplate e garante uma forte digitação de dados em todo o aplicativo.

É sempre uma boa ideia validar as entradas do formulário. Adicione a lógica de validação reescrevendo a rota /profile da seguinte forma.

@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}")
    )

Se o name estiver ausente, o email estiver ausente ou o age estiver negativo, o usuário receberá uma mensagem de erro clara. Ao abrir um HTTPException com um código de status 400, o aplicativo comunica o erro de validação específico, o que ajuda o usuário a corrigir a entrada antes de reenviar o formulário.

Uma maneira mais robusta de lidar com dados ausentes ou inválidos é realizar a verificação explícita de erros e fornecer feedback amigável ao usuário. Por exemplo, reescreva o código da seguinte forma.

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()

Se o usuário ignorar um campo obrigatório ou fornecer uma entrada inválida, ele verá o formulário ser renderizado novamente com os valores enviados e as mensagens de erro apropriadas exibidas ao lado de cada campo. Essa abordagem melhora a experiência do usuário ao indicar claramente o que precisa ser corrigido.

Depois de preencher todos os campos e enviar, você verá uma tela semelhante à seguinte.

Autenticação e gerenciamento de sessões

Implementação de fluxos de autenticação

No FastHTML, os dados da sessão são gerenciados por meio do objeto request.session, que se comporta como um dicionário Python. Você pode armazenar dados na sessão definindo pares de valores-chave, como session['user_id'] = 123. Para recuperar os dados da sessão, use read (user_id = session.get('user_id')). To clear all session data, call session.clear().

Nos bastidores, o FastHTML serializa o dicionário de sessão em um cookie assinado, que persiste entre as solicitações. Essa abordagem permite que você gerencie a autenticação do usuário e o estado da sessão usando padrões familiares do Python.

Esboço da criação de fluxos de trabalho de autenticação

Para criar um fluxo de trabalho de autenticação, siga estas etapas.

1. Configurar sessões: Adicionar SessionMiddleware with a strong secret_key. Once configured, the request.session is available in every handler.
2. Modelo de usuário e manipulação de senha: Defina um esquema de usuário (usando classe de dados, modelo Pydantic ou ORM) que inclua um nome de usuário and password_hash. Use a hashing function (e.g., hashlib, pbkdf2_hmac, bcrypt) to store and verify passwords.
3. Fluxo de registro*: Crie um GET /register route to render a signup form. * Use o 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. Fluxo de login*: Criar um GET /login route to display login form. * Usar POST /login to verify credentials. On success, write session['user_id'] and redirect; on failure, re-render the form with an error message.
5. Proteção de rotas: Crie uma função auxiliar ou um decorador que verifique session.get('user_id'). If the user is not authenticated, redirect to /login; otherwise, allow access to the requested route.
6. Fluxo de logout: No GET /logout route, call session.clear()` para remover os dados da sessão e redirecionar o usuário para a página de login ou para a página inicial.

Integração de banco de dados

Um Mapeador Objeto-Relacional (ORM) mapeia classes para tabelas de banco de dados, permitindo que você consulte dados usando objetos nativos em vez de SQL bruto. As opções mais populares incluem o SQLAlchemy e o ORM do Django. 

O FastHTML tem uma interface "ORM-like" que se integra a qualquer biblioteca de consulta ou ORM Python com capacidade de assíncrono. O padrão é o SQLite, mas você pode integrá-lo a qualquer back-end de banco de dados. Por exemplo, considere o código a seguir.

# 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()

Em um aplicativo FastHTML, você consulta os dados na camada de banco de dados escolhida e, em seguida, passa os resultados para os componentes FastHTML para renderização. Por exemplo, depois de recuperar registros do seu banco de dados, você pode percorrê-los em um manipulador de rota e criar estruturas HTML como tabelas, listas ou cartões personalizados.

As práticas recomendadas ainda se aplicam: selecione apenas os campos necessários, filtre e classifique no nível do banco de dados e pagine grandes conjuntos de resultados. O FastHTML ajuda você a se concentrar na criação de front-ends limpos e dinâmicos, deixando o tratamento de dados para as melhores ferramentas do seu projeto.

Estratégias de otimização de desempenho

Há várias maneiras de você obter os melhores resultados ao usar o FastHTML. A seguir, descrevemos algumas dessas recomendações. 

Mecanismos de cache

O armazenamento em cache melhora o desempenho, evitando trabalho redundante em diferentes camadas do aplicativo. No nível do navegador e da CDN, use cabeçalhos de controle de cache para manter ativos estáticos, como imagens, scripts e folhas de estilo. 

Você pode armazenar em cache as respostas de rotas inteiras ou partes caras em sua estrutura da Web. No seu aplicativo FastHTML, você armazena em cache respostas de rotas inteiras ou componentes caros, garantindo que as solicitações repetidas retornem rapidamente sem consultar novamente o banco de dados ou gerar modelos novamente.

Em Python, você pode implementar o armazenamento em cache no nível da função usando decoradores. Por exemplo, o decorador incorporado functools.lru_cache pode memorizar uma função auxiliar que busca dados do usuário. Por exemplo, você pode usar esse decorador para armazenar em cache as chamadas ao banco de dados:

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))

Filas de tarefas assíncronas

Os aplicativos da Web permanecem responsivos ao transferir tarefas demoradas do ciclo de solicitação. Em vez de bloquear o servidor ao gerar relatórios, enviar e-mails ou processar dados, essas tarefas são enfileiradas e executadas em segundo plano. 

Com essa abordagem, seu aplicativo envia uma resposta imediata ao usuário enquanto os trabalhadores, executados em processos ou threads separados, processam tarefas enfileiradas de forma assíncrona.

O FastHTML oferece suporte à execução de tarefas em segundo plano, integrando-se ao BackgroundTasks. da Starlette. Aqui está um exemplo que demonstra como enviar um e-mail de boas-vindas após a inscrição do usuário.

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.")

Aplicativos do mundo real

O FastHTML é uma estrutura versátil que pode alimentar uma grande variedade de aplicativos da Web. Vamos ver como você pode abordar a criação de uma plataforma de comércio eletrônico e um painel de dados usando o FastHTML.

Modelo de plataforma de comércio eletrônico

Vamos criar uma plataforma de comércio eletrônico com o FastHTML. Comece modelando seus dados principais como classes ORM ou classes de dados Python: produtos, usuários e itens do carrinho. 

Crie uma página de listagem de produtos que percorra os registros de produtos. Para cada produto, use um componente Python reutilizável, como Card, para exibir o produto, a imagem, o nome, o preço e um botão "Add to Cart". Esse botão inclui atributos HTMX como hx_post e hx_target, que permitem que você envie uma solicitação para adicionar o item ao carrinho de compras da sessão do usuário sem recarregar a página inteira.

O carrinho de compras em si é armazenado no dicionário session do usuário no servidor. No cabeçalho do seu site, inclua um componente de resumo do carrinho que seja atualizado dinamicamente usando HTMX sempre que os itens forem de fato ou removidos. 

A página do carrinho lê os dados da sessão para renderizar cada item do carrinho junto com um total geral. Ele também oferece um formulário de checkout que se conecta a uma classe Python para validação. Quando o usuário envia o formulário, seu aplicativo cria um registro de pedido e limpa o carrinho da sessão.

Implementação do painel de dados

Um painel de dados no FastHTML combina componentes Python com suas fontes de dados, usando HTMX para interatividade e atualizações em tempo real. Sua lógica de backend (por exemplo, funções auxiliares assíncronas, utilitários CRUD armazenados em cache ou consultas ORM) recupera os dados necessários. 

A partir daí, você cria uma página com widgets reutilizáveis. Eles podem incluir controles de filtro (como menus suspensos, seletores de data ou caixas de pesquisa) para refinar as consultas, cartões de KPI para exibir as principais métricas, tabelas de dados para listar registros ou incorporação de gráficos para visualizar tendências e comparações. 

Cada widget é escrito como um código Python nativo, normalmente um componente Div, Table ou Card personalizado. O FastHTML transforma automaticamente esses objetos em HTML no momento da resposta.

O HTMX permite que os painéis sejam interativos. Por exemplo, os widgets de filtro podem usar hx_get e hx_post para solicitar dados filtrados do servidor, atualizando dinamicamente tabelas ou gráficos sem que você precise recarregar a página inteira. 

Análise comparativa com estruturas tradicionais

O FastHTML se destaca das estruturas tradicionais, como o Django e o Flask, simplificando o desenvolvimento e o desempenho. Vamos explorar a comparação entre os principais fatores, como tempo de configuração, eficiência do código e benchmarks de desempenho.

Velocidade de desenvolvimento

O FastHTML tem duas vantagens principais sobre estruturas como Django e Flask: tempo de configuração e eficiência de código.

Tempo de configuração

A abordagem "batteries-included" do Django requer várias etapas antes que você possa servir a sua primeira página: instalar o pacote, executar django-admin startproject, configurar as definições e definir um aplicativo. Isso geralmente envolve vários arquivos e muito código padrão antes de você escrever qualquer lógica real.

O Flask é mais enxuto. Depois de pip install, você pode escrever algumas rotas em um único arquivo. No entanto, você ainda precisa configurar os modelos Jinja, as pastas estáticas e adicionar JavaScript para interatividade.

Com o FastHTML, a configuração é mínima.

1. Execute pip install python-fasthtml uvicorn.
2. Defina rotas e componentes HTML Python. Você pode fazer isso em um único arquivo.
3. Ligue para serve().

Não é necessário nenhum mecanismo de modelo separado ou configuração de pasta estática. Você pode começar a construir imediatamente.

Eficiência do código

Com o Django, até mesmo uma simples página "Hello, world" requer vários arquivos: views.py, urls.py, settings.py, templates/hello.html, além do ORM e do scaffolding de administração.

O Flask simplifica esse processo para um único arquivo, mas você ainda precisa escrever manualmente o HTML em modelos Jinja ou em strings inline, e o JavaScript para interatividade.

O FastHTML permite que você defina sua interface do usuário como objetos Python, portanto, não há necessidade de alternar arquivos ou linguagens. O HTMX lida com a interatividade de forma declarativa, sem scripts personalizados. O resultado é menos linhas de código, sem modelos separados ou pipelines de ativos estáticos e uma única superfície testável para marcação e comportamento.

Referências de desempenho