> For the complete documentation index, see [llms.txt](https://wedocs.gitbook.io/wedocs-5.1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wedocs.gitbook.io/wedocs-5.1/cliente-desktop/criacao-e-edicao-de-dashboards/componente-python.md).

# Componente Python

O Componente Python permite desenvolver componentes visuais personalizados utilizando scripts Python. Por meio desse recurso, é possível processar os dados retornados pelos metadados e gerar visualizações próprias, como gráficos, cartões, indicadores e outros elementos gráficos renderizados em formato SVG.

Esse recurso amplia as possibilidades de personalização da plataforma, permitindo utilizar bibliotecas Python para construir visualizações específicas de acordo com as necessidades da instituição.

<figure><img src="/files/kxSS3uu5HgK5TZTYT3bb" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Caso o componente não esteja habilitado, acesse **Administração > Acesso ao Menu Principal**, localize o **Componente Python** e conceda permissão aos usuários desejados.
{% endhint %}

### 📌 Como criar um Componente Python

O desenvolvimento de um Componente Python consiste em receber os dados fornecidos pelo metadado, processá-los utilizando um script Python e gerar uma imagem SVG que será exibida no dashboard.

#### Regras obrigatórias

**Resultado obrigatório**

O script deve finalizar atribuindo o conteúdo SVG à variável `result`.

Exemplo:

```python
result = svg.getvalue()
```

**Dados disponíveis**

Durante a execução do script, o Weknow disponibiliza automaticamente as seguintes variáveis:

| Variável            | Descrição                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `df_internalvalues` | Dados originais retornados pelo metadado.                                                                        |
| `df_displayvalues`  | Dados formatados para exibição. Quando não existir formatação, possuirá o mesmo conteúdo de `df_internalvalues`. |

Ambas são objetos do tipo **DataFrame** da biblioteca Pandas.

**Dimensões da área de exibição**

O sistema também disponibiliza as variáveis:

* `width`
* `height`

Esses valores representam a largura e a altura disponíveis para renderização do componente, em pixels.

Algumas bibliotecas gráficas, como o Matplotlib, utilizam polegadas como unidade de medida. Nesses casos, converta os valores utilizando o DPI da figura.

```python
fig_height = height / rcParams['figure.dpi']
fig_width = width / rcParams['figure.dpi']
```

**Formato da saída**

O conteúdo atribuído à variável `result` deve estar no formato SVG (Scalable Vector Graphics).

O formato SVG é utilizado por oferecer imagens vetoriais escaláveis, garantindo excelente qualidade de renderização e integração nativa com a interface do Weknow.

***

### Bibliotecas Python

O Componente Python pode utilizar bibliotecas Python instaladas no ambiente do Weknow.

Entre as bibliotecas mais utilizadas para criação de componentes visuais estão:

* Matplotlib;
* Plotly;
* Seaborn;
* Pandas.

Caso seja necessário utilizar bibliotecas adicionais, elas poderão ser instaladas diretamente pela interface do componente.

<figure><img src="/files/Ozm5JCXMHXMLUMgpZX7m" alt=""><figcaption></figcaption></figure>

***

#### Exemplo prático – Gráfico de linhas com Matplotlib

Neste exemplo, o metadado retorna duas colunas:

* `product_category_name`: nomes das categorias de produtos.
* `product_name_cnt`: quantidade de produtos em cada categoria.

O objetivo é gerar um gráfico de linhas demonstrando a quantidade de produtos por categoria.

```python
# 📚 Importa bibliotecas necessárias
from matplotlib import rcParams
from matplotlib.figure import Figure
from matplotlib.backends.backend_svg import FigureCanvasSVG
from io import StringIO

# 🎯 Passo 1 – Converter pixels para polegadas
fig_height = height / rcParams['figure.dpi']
fig_width = width / rcParams['figure.dpi']

# 🎯 Passo 2 – Criar figura e "canvas" para SVG
fig = Figure(figsize=(fig_width, fig_height))
canvas = FigureCanvasSVG(fig)

# 🎯 Passo 3 – Adicionar e plotar os dados
ax = fig.add_subplot()
ax.plot(
    df_displayvalues['product_category_name'],  # Eixo X (formatado)
    df_internalvalues['product_name_cnt']       # Eixo Y (valor original)
)

# 🎯 Passo 4 – Exportar para SVG
svg = StringIO()
canvas.print_svg(svg)

# 🎯 Passo 5 – Retornar o SVG para o sistema
result = svg.getvalue()
```

***

#### Fluxo de desenvolvimento

O processo de criação de um Componente Python segue, de forma geral, as seguintes etapas:

1. Receber os dados disponibilizados pelo metadado (`df_internalvalues` e `df_displayvalues`).
2. Ajustar o tamanho do componente utilizando as variáveis `width` e `height`.
3. Criar a visualização utilizando a biblioteca Python desejada.
4. Exportar o resultado para o formato SVG.
5. Atribuir o conteúdo SVG à variável `result`.

***

### Exemplo completo

O exemplo a seguir demonstra a utilização de um metadado criado via script Python para gerar um componente visual que identifica o hospital com maior taxa de ocupação.

<figure><img src="/files/c8mf3YUoLKwnFE9e4Wu4" alt=""><figcaption></figcaption></figure>

O script utiliza os dados retornados pelo metadado para identificar o hospital com maior percentual de ocupação e gerar um componente visual personalizado em formato SVG.

```python
from matplotlib import rcParams
from matplotlib.figure import Figure
from matplotlib.backends.backend_svg import FigureCanvasSVG
from io import StringIO

# --- Busca o índice do hospital com maior taxa de ocupação ---
idx = df_internalvalues['ocupacao_%'].idxmax()

# --- Recupera dados formatados (display) ---
hospital = df_displayvalues.loc[idx, 'hospital']
cidade = df_displayvalues.loc[idx, 'cidade']
tipo = df_displayvalues.loc[idx, 'tipo']

# --- Recupera dados originais (internal) ---
ocupacao = df_internalvalues.loc[idx, 'ocupacao_%']
leitos = df_internalvalues.loc[idx, 'leitos']
pacientes = df_internalvalues.loc[idx, 'pacientes_atendidos']
avaliacao = df_internalvalues.loc[idx, 'avaliacao']

# --- Define tamanho da figura em polegadas ---
fig_height = height / rcParams['figure.dpi']
fig_width = width / rcParams['figure.dpi']

# --- Cria figura e canvas ---
fig = Figure(figsize=(fig_width, fig_height))
canvas = FigureCanvasSVG(fig)
ax = fig.add_subplot()
ax.axis('off')  # Remove eixos
fig.patch.set_facecolor('white')

# --- Fundo colorido para destaque ---
ax.fill_between([0, 1], 0, 1, color='#f0f4f8')

# --- Título e informações ---
ax.text(0.05, 0.85, "Hospital com Maior Ocupação", fontsize=16, weight='bold', color='#2c3e50')
ax.text(0.05, 0.75, hospital, fontsize=14, weight='bold', color='#34495e')
ax.text(0.05, 0.70, f"Cidade: {cidade} | Tipo: {tipo}", fontsize=11, color='#7f8c8d')

# --- Indicadores principais ---
ax.text(0.05, 0.60, f"Leitos: {leitos}", fontsize=13, color='#2980b9')
ax.text(0.05, 0.53, f"Pacientes Atendidos: {pacientes:,}", fontsize=13, color='#27ae60')
ax.text(0.05, 0.46, f"Avaliação: {avaliacao:.2f} / 5", fontsize=13, color='#f39c12')
ax.text(0.05, 0.39, f"Ocupação: {ocupacao:.1f} %", fontsize=13, color='#c0392b')

# --- Fonte dos dados ---
ax.text(0.05, 0.10, "Fonte: Dados simulados do metadado", fontsize=8, color='gray')

# --- Exporta para SVG ---
svg = StringIO()
canvas.print_svg(svg)
result = svg.getvalue()

```

***

#### O exemplo acima demonstra como:

* localizar o hospital com maior taxa de ocupação;
* combinar dados originais (`df_internalvalues`) e dados formatados (`df_displayvalues`);
* gerar uma visualização personalizada utilizando Matplotlib;
* exportar o resultado para o formato SVG;
* disponibilizar a imagem para exibição no componente.

<figure><img src="/files/xJRST5O5GZyk4D8cFvNo" alt=""><figcaption></figcaption></figure>

#### Boas práticas

* Utilize nomes de campos consistentes entre o metadado e o script.
* Organize o código em blocos lógicos e utilize comentários quando necessário.
* Sempre valide o resultado do script antes de disponibilizá-lo em produção.
* Reutilize bibliotecas amplamente conhecidas sempre que possível.

{% hint style="danger" %} <mark style="color:red;">**IMPORTANTE**</mark>**:** Os campos utilizados no Script Python devem ser previamente configurados na seção 'Campos' para que o script possa ser executado corretamente.
{% endhint %}

***

### 📋 Detalhamento

O **Componente Python** passou a oferecer suporte ao recurso **Detalhamento**, permitindo consultar os registros relacionados ao componente da mesma forma que ocorre nos demais componentes baseados em metadados.

Para configurar o recurso:

1. Abra a edição do **Componente Python**.
2. Acesse a seção **Detalhamento**.
3. Ative a opção **Ativo**.
4. Defina os campos que serão exibidos.

<figure><img src="/files/Kg06q9apkG4v1OqbqyTn" alt=""><figcaption></figcaption></figure>

5. Para finalizar, clique em **Concluir**.

***

#### **Abrir detalhes da seleção**

Após a configuração, ao acionar o botão **Abrir detalhes da seleção**, será aberta a janela detalhes, apresentando os registros relacionados ao componente.

<div><figure><img src="/files/iX0Z2Mu6uOtA4Ug5CoIa" alt=""><figcaption></figcaption></figure> <figure><img src="/files/wpx6tdLYn86jUVyYij1d" alt=""><figcaption></figcaption></figure></div>

Nessa janela é possível:

* visualizar os dados em formato de grade;
* aplicar filtros aos registros;
* utilizar filtros por coluna;
* navegar pelos resultados utilizando paginação;
* selecionar as colunas que serão exibidas;
* exportar os dados.

{% hint style="info" %}
**Importante:** O recurso **Detalhamento** utiliza os campos configurados na respectiva seção do componente. Apenas os campos adicionados nessa configuração serão disponibilizados na janela de detalhes.
{% endhint %}