Manual básico de Streamlit

Frontend simples para coletar textos, números e imagens em uma aplicação

Python

Foco: formulário Streamlit -> backend Python -> processamento -> relatório/arquivo final

Versão: 1.0 | Data: 05/07/2026

Manual básico de Streamlit - Frontend simples para aplicações Python

Sumário
 1. Visão geral
 2. Estrutura recomendada do projeto
 3. Instalação e execução
 4. Componentes básicos de input
 5. Formulários com [Link]
 6. Upload de imagens com st.file_uploader
 7. Passando os dados para o backend
 8. Exemplo completo [Link] + [Link]
 9. Integração com docxtpl
 10. Estado da aplicação com st.session_state
 11. Boas práticas
 12. Problemas comuns
 13. Checklist final
 14. Referências

Manual básico de Streamlit - Frontend simples para aplicações Python

1. Visão geral
Streamlit é uma biblioteca Python para criar aplicações web interativas de forma rápida. Para o seu caso,
ele pode funcionar como uma interface simples para coletar informações e imagens, sem exigir que você
escreva HTML, CSS ou JavaScript.

Ideia principal
O Streamlit fica responsável pela tela. O backend continua sendo Python: funções, classes, geração de
relatório, análise de imagem, docxtpl ou qualquer outra lógica que você já esteja construindo.

Fluxo geral:
Usuário preenche a tela no Streamlit
↓
Streamlit coleta inputs textuais, numéricos e imagens
↓
Você organiza tudo em um dicionário Python
↓
O backend processa os dados
↓
O sistema gera saída: relatório .docx, PDF, pasta de imagens, análise etc.

Quando usar Streamlit:

 Quando você precisa de uma interface interna simples para rodar scripts Python.
 Quando o usuário precisa preencher campos e enviar arquivos.
 Quando o objetivo é prototipar rápido, sem desenvolver um frontend tradicional.
 Quando a aplicação será usada por poucas pessoas ou em ambiente controlado.

Quando talvez não seja a melhor opção:

 Quando você precisa de um sistema web grande, com muitas telas, login avançado, permissões
complexas e alta customização visual.
 Quando precisa de frontend profissional com layout totalmente personalizado.
 Quando o backend será uma API separada consumida por muitos clientes diferentes.

2. Estrutura recomendada do projeto

Uma boa separação é manter a interface Streamlit em um arquivo e a lógica de processamento em outro.

meu_projeto/
│
├── [Link] # interface Streamlit
├── [Link] # funções de processamento
├── templates/
│ └── [Link] # template do relatório, se usar docxtpl
├── uploads/ # imagens recebidas
├── relatorios/ # relatórios gerados
└── [Link] # dependências do projeto

Manual básico de Streamlit - Frontend simples para aplicações Python

Função de cada parte:
 [Link]: mostra campos na tela, recebe inputs e chama o backend.
 [Link]: recebe os dados, salva imagens, monta dicionários, processa e gera saídas.
 uploads/: armazena imagens enviadas pelo usuário.
 relatorios/: armazena arquivos gerados, como .docx ou .pdf.
 templates/: guarda modelos de relatório para docxtpl.

3. Instalação e execução
Crie um ambiente virtual e instale o Streamlit.

python -m venv .venv

# Windows
.venv\Scriptsctivate

# Linux/Mac
source .venv/bin/activate

pip install streamlit pillow python-docx docxtpl

Crie um arquivo [Link] simples:

import streamlit as st

[Link]("Minha primeira aplicação")

[Link]("Interface funcionando")

Execute com:

streamlit run [Link]

O Streamlit abrirá uma página local no navegador. Normalmente será algo como [Link]

4. Componentes básicos de input

Os widgets são os campos de entrada usados para coletar informações do usuário.

Tipo de dado Widget Uso comum

Texto curto st.text_input Nome da análise, referência,
código
Texto longo st.text_area Descrição, observações,
conclusão
Número st.number_input Quantidade de cortes,
temperatura, tempo
Lista única [Link] Tipo de análise, operador, status
Múltipla escolha [Link] Selecionar vários
componentes/opções
Arquivo/imagem st.file_uploader Enviar JPG, PNG, PDF, CSV etc.
Botão [Link] ou Iniciar processamento

Manual básico de Streamlit - Frontend simples para aplicações Python

 st.form_submit_button
Exemplo básico de inputs:

import streamlit as st

[Link]("Cadastro de análise")

nome = st.text_input("Nome da análise")

referencia = st.text_input("Referência do componente")
observacao = st.text_area("Observações")
quantidade = st.number_input("Quantidade de cortes", min_value=1, step=1)

[Link]("Nome:", nome)
[Link]("Referência:", referencia)
[Link]("Quantidade:", quantidade)

5. Formulários com [Link]

Use [Link] quando você quiser que vários campos sejam preenchidos e enviados juntos. Isso evita que o
processamento rode a cada alteração de campo.

import streamlit as st

with [Link]("formulario_analise"):
nome = st.text_input("Nome da análise")
componente = st.text_input("Componente")
quantidade = st.number_input("Quantidade de cortes", min_value=1, step=1)

enviar = st.form_submit_button("Processar")

if enviar:
[Link]("Formulário enviado")
[Link](nome, componente, quantidade)

Regras importantes do [Link]:

 Todo formulário precisa ter um st.form_submit_button.
 O processamento principal deve ficar depois do if enviar:.
 Campos dentro do formulário são enviados juntos quando o botão é pressionado.
 Evite colocar [Link] comum dentro de [Link]; use st.form_submit_button.

6. Upload de imagens com st.file_uploader

Para receber imagens, use st.file_uploader com filtros de extensão.

import streamlit as st

imagem = st.file_uploader(
"Envie uma imagem",
type=["png", "jpg", "jpeg"]
)

if imagem is not None:

Manual básico de Streamlit - Frontend simples para aplicações Python

 [Link](imagem, caption="Imagem enviada")

Para receber várias imagens:

imagens = st.file_uploader(
"Envie uma ou mais imagens",
type=["png", "jpg", "jpeg"],
accept_multiple_files=True
)

if imagens:
for img in imagens:
[Link](img, caption=[Link])

Salvando imagens em uma pasta:

from pathlib import Path

pasta_uploads = Path("uploads")
pasta_uploads.mkdir(exist_ok=True)

for img in imagens:

caminho = pasta_uploads / [Link]

with open(caminho, "wb") as arquivo:

[Link]([Link]())

Atenção
O arquivo enviado pelo st.file_uploader fica disponível para o Python como um objeto em memória. Para
usar depois, salve em disco ou converta para o formato que seu backend precisa.

7. Passando os dados para o backend

O padrão mais simples é montar um dicionário com os dados coletados e enviar para uma função do
backend.

# [Link]
import streamlit as st
from backend import processar_dados

with [Link]("formulario"):
nome = st.text_input("Nome da análise")
componente = st.text_input("Componente")
quantidade = st.number_input("Quantidade de cortes", min_value=1, step=1)
imagens = st.file_uploader(
"Imagens",
type=["png", "jpg", "jpeg"],
accept_multiple_files=True
)

enviar = st.form_submit_button("Processar")

Manual básico de Streamlit - Frontend simples para aplicações Python

 if enviar:
dados = {
"nome": nome,
"componente": componente,
"quantidade": quantidade,
"imagens": imagens
}

resultado = processar_dados(dados)
[Link](resultado)

No backend:

# [Link]
from pathlib import Path

def processar_dados(dados):
pasta_uploads = Path("uploads")
pasta_uploads.mkdir(exist_ok=True)

caminhos = []

for imagem in dados["imagens"]:

caminho = pasta_uploads / [Link]

with open(caminho, "wb") as arquivo:

[Link]([Link]())

[Link](str(caminho))

contexto = {
"nome": dados["nome"],
"componente": dados["componente"],
"quantidade": dados["quantidade"],
"imagens": caminhos
}

return contexto

8. Exemplo completo [Link] + [Link]

Este exemplo cria uma interface para cadastrar componentes e imagens, salva os arquivos e retorna um
contexto pronto para processamento.

Arquivo [Link]
import streamlit as st
from backend import processar_relatorio

st.set_page_config(page_title="Gerador de Relatório", layout="centered")

[Link]("Gerador de Relatório")
[Link]("Preencha os dados da análise e envie as imagens.")

Manual básico de Streamlit - Frontend simples para aplicações Python

with [Link]("formulario_relatorio"):
nome_analise = st.text_input("Nome da análise")
componente = st.text_input("Referência do componente")
descricao = st.text_area("Descrição da análise")
quantidade_cortes = st.number_input(
"Quantidade de cortes",
min_value=1,
step=1
)

imagens = st.file_uploader(
"Imagens dos cortes/análises",
type=["png", "jpg", "jpeg"],
accept_multiple_files=True
)

enviar = st.form_submit_button("Gerar relatório")

if enviar:
if not nome_analise:
[Link]("Preencha o nome da análise.")
elif not componente:
[Link]("Preencha a referência do componente.")
elif not imagens:
[Link]("Envie pelo menos uma imagem.")
else:
dados = {
"nome_analise": nome_analise,
"componente": componente,
"descricao": descricao,
"quantidade_cortes": int(quantidade_cortes),
"imagens": imagens
}

resultado = processar_relatorio(dados)

[Link]("Relatório processado com sucesso.")

[Link]("Contexto gerado:")
[Link](resultado)

Arquivo [Link]
from pathlib import Path
from datetime import datetime

def salvar_imagens(imagens, componente):

pasta_uploads = Path("uploads")
pasta_uploads.mkdir(exist_ok=True)

caminhos = []

for indice, imagem in enumerate(imagens, start=1):

extensao = Path([Link]).[Link]()
timestamp = [Link]().strftime("%Y%m%d_%H%M%S")
nome_arquivo = f"{componente}_img_{indice}_{timestamp}{extensao}"
caminho = pasta_uploads / nome_arquivo

Manual básico de Streamlit - Frontend simples para aplicações Python

 with open(caminho, "wb") as arquivo:
[Link]([Link]())

[Link](str(caminho))

return caminhos

def processar_relatorio(dados):
caminhos_imagens = salvar_imagens(
dados["imagens"],
dados["componente"]
)

contexto = {
"nome_analise": dados["nome_analise"],
"componente": dados["componente"],
"descricao": dados["descricao"],
"quantidade_cortes": dados["quantidade_cortes"],
"imagens": caminhos_imagens
}

# Aqui você pode chamar outras funções:

# gerar_docx(contexto)
# analisar_imagens(caminhos_imagens)
# salvar_json(contexto)

return contexto

9. Integração com docxtpl

Se o objetivo final for gerar relatórios Word, o backend pode montar o contexto e chamar o docxtpl.

# [Link]
from docxtpl import DocxTemplate, InlineImage
from [Link] import Mm
from pathlib import Path

def gerar_docx(contexto):
template = DocxTemplate("templates/[Link]")

imagens_docx = []
for caminho in contexto["imagens"]:
imagens_docx.append(
InlineImage(template, caminho, width=Mm(80))
)

contexto_docx = {
"nome_analise": contexto["nome_analise"],
"componente": contexto["componente"],
"descricao": contexto["descricao"],
"quantidade_cortes": contexto["quantidade_cortes"],
"imagens": imagens_docx
}

Manual básico de Streamlit - Frontend simples para aplicações Python

 pasta_relatorios = Path("relatorios")
pasta_relatorios.mkdir(exist_ok=True)

saida = pasta_relatorios / f"relatorio_{contexto['componente']}.docx"

[Link](contexto_docx)
[Link](saida)

return str(saida)

No template Word, você poderia usar algo como:

Nome da análise: {{ nome_analise }}

Componente: {{ componente }}
Descrição: {{ descricao }}
Quantidade de cortes: {{ quantidade_cortes }}

{% for imagem in imagens %}

{{ imagem }}
{% endfor %}

10. Estado da aplicação com st.session_state

O Streamlit reexecuta o script quando o usuário interage com widgets. Para guardar valores entre
execuções, use st.session_state.

import streamlit as st

if "contador" not in st.session_state:

st.session_state.contador = 0

if [Link]("Adicionar"):
st.session_state.contador += 1

[Link]("Contador:", st.session_state.contador)

Quando usar session_state:

 Quando precisa manter uma lista de componentes já cadastrados.
 Quando o usuário adiciona cortes um por um antes de gerar o relatório.
 Quando precisa controlar etapas: cadastro -> revisão -> geração.
 Quando a tela tem múltiplas seções e você não quer perder dados intermediários.

11. Boas práticas

11.1. Separe frontend e backend
Evite colocar toda a lógica dentro do [Link]. O [Link] deve coletar e exibir dados. O processamento deve
ficar em funções separadas.

# Ruim: tudo misturado no [Link]

Manual básico de Streamlit - Frontend simples para aplicações Python

 # Melhor:
# [Link] -> coleta campos e chama função
# [Link] -> processa dados e gera saída

11.2. Valide os campos antes de processar

if not nome_analise:
[Link]("Preencha o nome da análise.")
elif not imagens:
[Link]("Envie pelo menos uma imagem.")
else:
resultado = processar_relatorio(dados)

11.3. Evite nomes de arquivos repetidos

Se dois usuários enviarem [Link], um arquivo pode sobrescrever o outro. Use timestamp, UUID ou
nome baseado no componente.

from uuid import uuid4

from pathlib import Path

extensao = Path([Link]).suffix
nome_seguro = f"{uuid4().hex}{extensao}"

11.4. Use pastas organizadas

 uploads/ para arquivos recebidos.
 relatorios/ para arquivos gerados.
 templates/ para modelos Word.
 logs/ para registros de erros, se necessário.

12. Problemas comuns

Problema Causa provável Solução
A imagem some depois de trocar O arquivo estava só em memória Salvar em disco ou usar
de página session_state
O processamento roda antes do Campos fora de formulário Usar [Link] e
usuário terminar st.form_submit_button
Arquivo sobrescrito Mesmo nome de imagem Gerar nome único com
timestamp ou UUID
Erro no docxtpl com imagem Passou caminho direto em vez Converter imagem para
de InlineImage InlineImage antes do render
number_input retorna float Parâmetros definidos como float Usar step=1 e converter com int()
quando necessário
O relatório não encontra a Caminho relativo incorreto Salvar e passar caminho correto
imagem para o backend

13. Checklist final

 O [Link] só coleta dados e chama funções?
 O [Link] salva imagens e monta o contexto?
 Os campos obrigatórios são validados?

Manual básico de Streamlit - Frontend simples para aplicações Python

 As imagens recebem nomes únicos?
 As pastas uploads/ e relatorios/ são criadas automaticamente?
 O contexto gerado está no formato esperado pelo docxtpl?
 O usuário recebe mensagem de sucesso ou erro?
 O arquivo final fica disponível para download ou consulta?

Exemplo de botão para download de relatório:

with open(caminho_relatorio, "rb") as arquivo:
st.download_button(
label="Baixar relatório",
data=arquivo,
file_name="[Link]",
mime="application/[Link]"
)

14. Referências consultadas

As referências abaixo são da documentação oficial do Streamlit e foram usadas como base para os
conceitos do manual.

 Documentação geral do Streamlit - [Link]

 Instalação do Streamlit - [Link]
 Criar uma aplicação Streamlit - [Link]
 Widgets de input - [Link]
 [Link] - [Link]
 st.file_uploader - [Link]
 st.number_input - [Link]
 st.session_state - [Link]

Manual básico de Streamlit - Frontend simples para aplicações Python