dashgen 0.3.1

Gere dashboards visuais como imagens.

Dashgen

📊 Gere dashboards visuais como imagens (PNG) diretamente do Python com HTML, Tailwind CSS e Chart.js.

---

✨ O que é?

dashgen é um micro-framework que permite criar dashboards dinâmicos e exportá-los como imagens de alta qualidade.

Ideal para gerar relatórios diários, KPIs, resumos visuais e compartilhar automaticamente via e-mail, WhatsApp, sistemas internos etc.

---

🛠 Instalação

pip install dashgen
playwright install

---

🚀 Exemplo Completo

from dashgen import (
    Dashboard,
    Row,
    Column,
    Text,
    Image,
    ProgressBar,
    Chart,
    Table,
)

# Criar o dashboard com altura automática, título estilizado e tema
db = Dashboard(
    title="📊 Relatório de Desempenho Comercial",
    title_style="text-3xl font-bold text-emerald-700",
    logo_path="logo.png",
    size=(1080, None),
    auto_size=True,
    theme={
        "primary": "#0f766e",
        "accent": "#22d3ee",
        "bg": "#f0fdfa",
        "text": "#082f49"
    }
)

# Linha com dois cards
db.add(Row(
    Column(6).add_card("Receita Acumulada", 9000000, 10000000),
    Column(6).add_card("Unidades Vendidas", 430, 500)
))

# Linha com tabela e gráfico de barras
dados = [
    {"Nome": "Projeto A", "Meta": "R$ 3M", "Realizado": "R$ 2.4M", "Variação": "-20%"},
    {"Nome": "Projeto B", "Meta": "R$ 5M", "Realizado": "R$ 5.2M", "Variação": "+4%"}
]

db.add(Row(
    Column(6).add_table("Desempenho por Projeto", dados, ["Nome", "Meta", "Realizado", "Variação"]),
    Column(6).add_chart(
        "bar",
        "Vendas por Mês",
        [
            {"label": "Jan", "value": 120},
            {"label": "Fev", "value": 135},
            {"label": "Mar", "value": 160},
            {"label": "Abr", "value": 110},
            {"label": "Mai", "value": 190}
        ],
        options={
            "height": 300,
            "show_data_labels": True,
            "data_label_color": "#ef4444",
            "data_label_format": "value + ' unidades'",
            "show_legend": False,
            "show_x_axis": True,
            "show_y_axis": True,
            "autosize_x": True,
            "bar_color": "#0f766e"
        }
    )
))

# Linha com gráfico de linha (largura total)
db.add(Row(
    Column(12).add_chart(
        "line",
        "Receita Total (R$)",
        [
            {"label": "Jan", "value": 1200000},
            {"label": "Fev", "value": 1450000},
            {"label": "Mar", "value": 1600000},
            {"label": "Abr", "value": 1800000},
            {"label": "Mai", "value": 2100000}
        ],
        options={
            "height": 460,
            "show_legend": False,
            "show_x_axis": True,
            "show_y_axis": True,
            "autosize_x": True,
            "tension": 0.4,
            "fill": False,
            "border_color": "#22d3ee"
        }
    )
))

# Gerar imagem
db.generate("output_dashboard.png")
print("✅ Dashboard gerado com sucesso!")

Mais scripts de exemplo podem ser encontrados em examples/.

---

🧱 Componentes Disponíveis

📐 Layout

• Row(..., align={...}, margin="...", padding="...")
• Column(width=..., order=..., breakpoints={...}, align={...})

🌿 Elementos Declarativos

• Box(content, style={...})
• Text(text, style={...})
• Image(path, style={...})
• ProgressBar(percent, style={...})
• Chart(type, title, data, options={...})
• Table(title, data, headers, progress_columns=None)

Exemplo com breakpoints e ordem customizada:

Row(
    Column(6, breakpoints={"md": 4}, order=2).add_text("A"),
    Column(6, breakpoints={"md": 8}, order=1).add_text("B"),
    align={"horizontal": "center"},
    margin="my-4"
)

📦 Card (KPI)

Column(6).add_card("Título", valor, meta, style={ ... })

Suporta personalização com:

• title_color, title_size, text_size
• bar_color, card_class

📊 Tabela

Column(6).add_table("Título", data, headers)

• data: lista de dicionários
• headers: nomes das colunas a exibir

📈 Gráfico (Chart.js)

Column(6).add_chart("bar" ou "line" ou "pie" ou "scatter" ou "doughnut" ou "radar", "Título", data, options={...})

• data: lista com label e value (ou x/y para scatter)

• options:

  • height: altura do canvas
  • fill: preencher área sob a linha
  • tension: suavidade das curvas
  • autosize_x / autosize_y: expandir horizontal/vertical
  • show_legend: mostrar legenda
  • show_x_axis / show_y_axis: mostrar eixos
  • show_data_labels: mostrar valores sobre as barras
  • data_label_color: cor dos rótulos
  • data_label_font: fonte dos rótulos (dict Chart.js)
  • data_label_anchor: posição do rótulo
  • data_label_format: função/expressão para formatar o valor
  • legend_position: posição da legenda
  • x_axis_title / y_axis_title: títulos dos eixos

Exemplos rápidos:

Column(6).add_chart("bar", "Vendas", [{"label": "A", "value": 10}])
Column(6).add_chart("line", "Tendência", [{"label": "A", "value": 5}])
Column(6).add_chart("pie", "Participação", [
    {"label": "A", "value": 30, "color": "#ff0000"},
    {"label": "B", "value": 70, "color": "#00ff00"}
])
Column(6).add_chart("scatter", "Correlação", [
    {"x": 1, "y": 2},
    {"x": 2, "y": 3}
])
Column(6).add_chart("doughnut", "Rosca", [
    {"label": "A", "value": 40},
    {"label": "B", "value": 60}
])
Column(6).add_chart("radar", "Radar", [
    {"label": "A", "value": 50},
    {"label": "B", "value": 80}
])

Veja o script completo em examples/chartjs_extra_options.py.

🎯 Data Labels Personalizados

O template base já carrega automaticamente o plugin chartjs-plugin-datalabels, permitindo exibir e estilizar rótulos sobre as barras ou pontos.

• data_label_color – cor do texto
• data_label_font – fonte dos rótulos (dict Chart.js)
• data_label_anchor – posição do rótulo (start, center, end)
• data_label_format – expressão ou função para formatar o valor

Exemplo rápido de formatação customizada:

from dashgen import Dashboard, Row, Column

db = Dashboard(title="Labels", size=(600, 300))

dados = [
    {"label": "Jan", "value": 15000},
    {"label": "Fev", "value": 22000},
]

db.add(
    Row(
        Column(12).add_chart(
            "bar",
            "Receita",
            dados,
            options={
                "show_data_labels": True,
                "data_label_color": "#16a34a",
                "data_label_anchor": "end",
                "data_label_font": {"size": 12, "weight": "bold"},
                "data_label_format": "'R$ ' + value.toFixed(2)",
            },
        )
    )
)

db.generate("custom_label_format.png")

Veja o script completo em examples/custom_label_format.py.

🌱 API Declarativa

Componha diretamente elementos de forma simples:

from dashgen import Dashboard, Row, Column, Text, Image, ProgressBar

db = Dashboard(title="Demo")
db.add(
    Row(
        Column(6, Text("Progresso"), ProgressBar(75)),
        Column(6, Image("logo.png", style={"width": "80px"})),
    )
)
db.generate("demo.png")

### Rodando no Jupyter Notebook

Para exibir a imagem diretamente em uma célula do Jupyter use:

```python
db.generate("demo.png", jupyter=True)

---

## 🎨 Tema Personalizado

```python
theme = {
    "primary": "#005f73",  # Barras e títulos
    "accent": "#94d2bd",   # Detalhes
    "bg": "#fefae0",       # Fundo da imagem
    "text": "#001219"      # Cor do texto
}

♻️ Temas Reutilizáveis

db.save_theme("tema.json")
novo = Dashboard()
novo.load_theme("tema.json")

📄 Múltiplas Páginas

Finalize uma página com generate_page() e depois informe uma lista de caminhos para generate:

db.generate_page()
db.add(Row(Column(12).add_text("Segunda página")))
db.generate(["pagina1.png", "pagina2.png"])

---

🧠 Funcionalidades Especiais

• auto_size=True: ajusta altura da imagem com base no conteúdo
• Layout com alinhamento e breakpoints
• Componentes Box, Text, Image e ProgressBar
• Gráficos bar, line, pie, scatter, doughnut e radar via Chart.js
• Responsivo com Tailwind e rótulos (chartjs-plugin-datalabels)
• Estilização por componente (style, options)

---

📚 API Referência

📘 Dashboard(...)

Parâmetro	Tipo	Descrição
title	str	Título do dashboard
logo_path	str (opcional)	Caminho da logo
size	(int, int)	Tamanho fixo da imagem
auto_size	bool	Ajuste automático de altura
theme	dict	Cores do tema

---

✅ Requisitos

• Python 3.7+
• playwright
• jinja2

pip install dashgen
playwright install

---

🖼 Gere imagens de dashboards com visual moderno, responsivo e exportável – em uma linha de código.