A Python library for building reactive web dashboards 100% in Python

These details have not been verified by PyPI

Project description

tupyx logo

TUPYX - Toolkit for Unified Python eXperiences

Framework Python para criar dashboards e aplicações web reativos 100% em Python — sem JavaScript, sem HTML manual, sem templates.

Acesse o repositório no github

PyPI version Python versions License

Instalação

pip install tupyx

Com suporte a pandas:

pip install tupyx[pandas]

Início rápido

tupyx init meu-dashboard
cd meu-dashboard
tupyx run app.py

Abra http://localhost:8000 no browser. O servidor tem hot-reload — salve o arquivo e a página atualiza automaticamente.

Índice

Instalação
Início rápido
Índice
Estrutura do projeto
Tags HTML
Estilos com .sx()
Pseudo-estilos
Eventos
Reactive
Roteamento com @page
NavLink
Input e Select reativos
- Input
- Select
Medidas com @measure
Gráficos
CLI
Licença

Estrutura do projeto

meu-dashboard/
├── app.py          ← ponto de entrada (define o app e chama run)
├── pages/
│   ├── home.py     ← páginas com @page("/rota")
│   └── dash.py
└── pyproject.toml

app.py mínimo:

from tupyx.ui import *
from tupyx.server import run

def app():
    return Html(
        Head(Title("Meu App")),
        Body(Router()).sx(margin="0", background="#f8fafc"),
    )

run(app)

Tags HTML

Todos os elementos HTML estão disponíveis como funções Python:

from tupyx.ui import *

# Uso básico: Tag(filhos, atributos)
Div("conteúdo")
P("Parágrafo de texto")
H1("Título principal")
Span("texto inline")
A("Link", href="https://exemplo.com")
Img(src="/logo.png", alt="Logo")
Button("Clique aqui")

# Aninhamento
Div(
    H1("Título"),
    P("Subtítulo"),
    Button("Ação"),
)

# Atributos HTML
A("Documentação", href="/docs", target="_blank")
Img(src="/foto.jpg", alt="Foto", width="200")

Tags disponíveis:

Categoria	Tags
Layout	`Div`, `Span`, `P`, `A`, `Img`, `Button`, `Form`, `Label`, `Textarea`
Títulos	`H1`, `H2`, `H3`, `H4`, `H5`, `H6`
Listas	`Ul`, `Ol`, `Li`
Semântica	`Header`, `Footer`, `Main`, `Section`, `Article`, `Nav`, `Aside`
Tabelas	`Table`, `Thead`, `Tbody`, `Tfoot`, `Tr`, `Th`, `Td`, `Caption`
Mídia	`Video`, `Audio`, `Source`, `Canvas`, `Svg`
Documento	`Html`, `Head`, `Body`, `Title`, `Meta`, `Link`, `Script`, `Style`
Inline	`Strong`, `Em`, `Small`, `Br`, `Hr`, `Code`, `Pre`
Formulário	`Input`, `Select`, `Option`
Navegação	`NavLink`

Estilos com .sx()

.sx() aplica CSS inline usando Python snake_case (convertido automaticamente para kebab-case):

Div("Olá").sx(
    background="#f0f7ff",
    border_radius="12px",
    padding="16px 24px",
    font_size="14px",
    font_weight="600",
    color="#0f172a",
    display="flex",
    align_items="center",
    gap="8px",
    box_shadow="0 2px 8px rgba(0,0,0,0.08)",
)

Encadeamento:

Button("Salvar").sx(
    background="#2563eb",
    color="white",
    border="none",
    border_radius="8px",
    padding="10px 20px",
    cursor="pointer",
    font_size="14px",
)

Pseudo-estilos

Aplique estilos para :hover, :focus e :active:

Button("Hover aqui").sx(
    background="#2563eb",
    color="white",
    padding="10px 20px",
    border_radius="8px",
    border="none",
    cursor="pointer",
).on_hover(
    background="#1d4ed8",  # escurece no hover
    transform="translateY(-1px)",
)

Input(type="text").sx(
    border="1px solid #dbeafe",
    border_radius="8px",
    padding="8px 12px",
    outline="none",
).on_focus(
    border="1px solid #2563eb",
    box_shadow="0 0 0 3px rgba(37,99,235,0.15)",
)

Eventos

Vincule qualquer função Python a eventos do browser:

def home():
    def ao_clicar():
        print("Clicou!")

    def ao_digitar():
        pass  # o estado já é atualizado automaticamente

    return Div(
        Button("Clique").on_click(ao_clicar),
        Button("Duplo clique").on_dblclick(ao_clicar),
        Input(type="text").on_input(ao_digitar),
        Input(type="text").on_change(ao_digitar),
        Div("Hover").on_mouseover(ao_clicar),
    )

Eventos disponíveis:

Método	Quando dispara
`.on_click(fn)`	clique simples
`.on_dblclick(fn)`	duplo clique
`.on_mouseover(fn)`	mouse entra
`.on_mouseout(fn)`	mouse sai
`.on_mouseenter(fn)`	mouse entra (sem propagar para filhos)
`.on_mouseleave(fn)`	mouse sai (sem propagar para filhos)
`.on_keydown(fn)`	tecla pressionada
`.on_keyup(fn)`	tecla solta
`.on_input(fn)`	a cada caractere digitado
`.on_change(fn)`	valor muda e perde foco
`.on_submit(fn)`	formulário enviado
`.on_focus_event(fn)`	elemento recebe foco
`.on_blur(fn)`	elemento perde foco
`.on_js(evento, js)`	JS puro sem passar pelo servidor

Reactive

Reactive cria uma variável de estado que persiste entre renders:

@page("/")
def home():
    contador = Reactive(0)       # valor inicial: 0
    nome     = Reactive("mundo") # string
    itens    = Reactive([])      # lista

    def incrementar():
        contador.update(lambda v: v + 1)

    def zerar():
        contador.set(0)

    return Div(
        H1("Contador: ", contador),       # exibe o valor automaticamente
        P(f"Nome: {nome.get()}"),          # lê o valor
        Button("+1").on_click(incrementar),
        Button("Zerar").on_click(zerar),
    )

Métodos:

r = Reactive(10)

r.get()                        # → 10
r.set(20)                      # → define 20
r.update(lambda v: v + 5)      # → aplica função ao valor atual
r.subscribe(lambda v: print(v))# → callback chamado em toda atualização
str(r)                         # → "20" (para usar em strings)
r()                            # → 20 (equivale a .get())

Roteamento com @page

from tupyx.ui import *
from tupyx.server import run

@page("/", redirect=True)   # redirect=True → redireciona "/" para esta rota
def home():
    return Div(H1("Home"))

@page("/sobre")
def sobre():
    return Div(H1("Sobre"))

@page("/produto/{id}")       # parâmetro dinâmico na URL
def produto(id):
    return Div(H1(f"Produto #{id}"))

def app():
    return Html(
        Head(Title("Meu App")),
        Body(Router()),
    )

run(app)

Arquivos em pages/ são descobertos automaticamente — basta criar o arquivo com @page(...).

NavLink

Navegação entre rotas sem recarregar a página (atualiza apenas o conteúdo):

NavLink("Ir para o dashboard", to="/dashboard")

# Com estilo
NavLink("Dashboard", to="/dashboard").sx(
    color="#2563eb",
    text_decoration="none",
    font_weight="500",
)

# Com aparência de botão
NavLink("Ver relatório", to="/relatorio").sx(
    background="#2563eb",
    color="white",
    padding="8px 16px",
    border_radius="8px",
    text_decoration="none",
    display="inline-block",
)

# Barra de navegação completa
Nav(
    NavLink("Home", to="/").sx(color="#0f172a", text_decoration="none"),
    NavLink("Dashboard", to="/dash").sx(color="#0f172a", text_decoration="none"),
    NavLink("Relatórios", to="/relatorios").sx(color="#0f172a", text_decoration="none"),
).sx(display="flex", gap="24px", padding="16px 32px", border_bottom="1px solid #dbeafe")

O botão voltar/avançar do browser funciona corretamente com NavLink.

Input e Select reativos

Use .bind(reactive) para sincronização bidirecional automática:

Input

@page("/")
def home():
    nome = Reactive("tupyx")

    return Div(
        Input(type="text", placeholder="Digite seu nome").bind(nome),
        P("Olá, ", nome),  # atualiza automaticamente ao digitar
    )

Select

@page("/")
def home():
    ano = Reactive("2024")

    return Div(
        Select(
            Option("2024", value="2024"),
            Option("2023", value="2023"),
            Option("2022", value="2022"),
        ).bind(ano),
        P(f"Mostrando dados de {ano.get()}"),
    )

@page("/")
def home():
    ano = Reactive("2024")

    anos = [2024, 2025, 2026]

    return Div(
        Select(
            anos
        ).bind(ano),
        P(f"Mostrando dados de {ano.get()}"),
    )

Medidas com @measure

Transforma funções em KPI cards reativos:

dados = [
    {"ano": "2024", "val": 320},
    {"ano": "2024", "val": 480},
    {"ano": "2023", "val": 180},
]

@page("/")
def home():
    ano = Reactive("2024")

    def filtrado():
        return [d for d in dados if d["ano"] == ano.get()]

    @measure(label="Total", prefix="R$ ", color="blue")
    def total():
        return sum(d["val"] for d in filtrado())

    @measure(label="Média", prefix="R$ ", color="green")
    def media():
        d = filtrado()
        return round(sum(i["val"] for i in d) / len(d)) if d else 0

    @measure(label="Melhor", suffix=" pts", color="purple")
    def melhor():
        d = filtrado()
        return max(i["val"] for i in d) if d else 0

    return Div(
        Select(
            Option("2024", value="2024"),
            Option("2023", value="2023"),
        ).bind(ano),
        Div(total, media, melhor).sx(display="flex", gap="16px"),
    )

Parâmetros:

Parâmetro	Descrição	Padrão
`label`	título do card	`""`
`prefix`	texto antes do valor (ex: `"R$ "`)	`""`
`suffix`	texto depois do valor (ex: `" kg"`)	`""`
`color`	cor: `"blue"`, `"green"`, `"yellow"`, `"red"`, `"purple"`, `"gray"`	`"blue"`

Usar a medida em expressões:

total()             # valor numérico puro
BarChart(y=total)   # passar para gráfico

Gráficos

Todos os gráficos aceitam:

Listas Python diretamente
@measure (MeasureCard)
Callables (funções que retornam dados)
pandas.DataFrame e pandas.Series (requer pip install tupyx[pandas])

Opções comuns via .sx():

chart.sx(width="100%")           # largura relativa
chart.sx(width="600px")          # largura fixa
chart.sx(height="300px")         # altura
chart.sx(hide_tooltip=True)      # desativa tooltip
chart.sx(hide_legend=True)       # desativa legenda
chart.sx(legend_position="top")  # "top", "bottom", "left", "right"
chart.sx(legend_align="start")   # "start", "center", "end"