Guia Prático: Aplicações
Multiplataforma em Python com Flet
(com uv, ruff, pyright e CI/CD)
Este guia é voltado para o ecossistema multiplataforma em Python utilizando o Flet — o
framework moderno baseado no engine do Flutter que permite criar interfaces reativas nativas
para Desktop (Windows, macOS, Linux), Web e Mobile (iOS, Android) escrevendo apenas
código Python.
1. Visão Geral da Arquitetura Multiplataforma
O Flet funciona como uma ponte (bridge) entre a linguagem Python e o motor de renderização
do Flutter.
Plaintext
┌────────────────────────────────────────────────────────
──┐
│ Aplicação Python │
│ Lógica de Negócios + Estado + Eventos │
└────────────────────────────┬───────────────────────────
──┘
│ Protocolo Flet (WebSocket/IPC)
┌────────────────────────────▼──────────────────────────
───┐
│ Engine Flutter (C/C++) │
│ Renderização Canvas NAtiva (Desktop / Mobile / Web) │
└────────────────────────────────────────────────────────
──┘
Estrutura de Projeto Padronizada (src-layout)
Plaintext
meu_app_multi/
├── .github/
│ └── workflows/
│ ├── [Link]
│ └── build_desktop.yml
├── src/
│ └── meu_app/
│ ├── __init__.py
│ ├── [Link] # Ponto de entrada ([Link])
│ ├── core/
│ │ ├── __init__.py
│ │ ├── [Link]
│ │ └── [Link] # Gerenciamento de estado
│ ├── views/
│ │ ├── __init__.py
│ │ ├── home_view.py
│ │ └── settings_view.py
│ └── components/
│ ├── __init__.py
│ └── custom_button.py
├── tests/
│ └── test_state.py
├── [Link]
├── [Link]
└── [Link]
2. Configuração do Projeto e Ferramental
2.1. Inicialização com uv
Bash
# Criar o projeto e o ambiente virtual
uv init meu_app_multi --app
cd meu_app_multi
uv venv
# Ativar ambiente virtual
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate
# Adicionar Flet e dependências de produção
uv add flet pydantic
# Adicionar ferramentas de desenvolvimento e qualidade
uv add --dev ruff pyright pytest
3. Qualidade de Código ([Link])
Configuração unificada para Ruff (linting/formatação) e Pyright (checagem estática de tipos):
Ini, TOML
[project]
name = "meu-app-multi"
version = "0.1.0"
description = "Aplicação Multiplataforma Python com Flet"
readme = "[Link]"
requires-python = ">=3.12"
dependencies = [
"flet>=0.22.0",
"pydantic>=2.0.0",
]
[[Link]]
line-length = 88
target-version = "py312"
[[Link]]
select = [
"E", # pycodestyle erros
"W", # pycodestyle avisos
"F", # Pyflakes
"I", # isort (ordenação de imports)
"B", # flake8-bugbear
"UP", # pyupgrade (sintaxe moderna)
]
[[Link]]
quote-style = "double"
indent-style = "space"
[[Link]]
include = ["src"]
pythonVersion = "3.12"
typeCheckingMode = "standard"
4. Estrutura do Código da Aplicação Multiplataforma
Ponto de Entrada (src/meu_app/[Link])
O Flet permite rodar o mesmo código como aplicativo Desktop nativo ou Servidor Web
mudando apenas o argumento do parâmetro target.
Python
import flet as ft
from meu_app.views.home_view import HomeView
def main(page: [Link]) -> None:
[Link] = "Minha Aplicação Multiplataforma"
page.theme_mode = [Link]
[Link] = 900
[Link] = 700
[Link] = 20
# Adicionar view inicial
[Link](HomeView(page))
if __name__ == "__main__":
# Modo Desktop Nativo
[Link](target=main)
# Modo Web (descomente para rodar no navegador na porta 8080):
# [Link](target=main, view=[Link].WEB_BROWSER, port=8080)
Componente Reutilizável (src/meu_app/views/home_view.py)
Python
import flet as ft
class HomeView([Link]):
def __init__(self, page: [Link]) -> None:
super().__init__()
[Link] = page
[Link] = 0
self.txt_number = [Link](
value="0", size=40, weight=[Link]
)
[Link] = [
[Link](
"Bem-vindo ao App Multiplataforma!", style=[Link].HEADLINE_MEDIUM
),
[Link](),
[Link](
controls=[
[Link](
[Link], on_click=self._decrement
),
self.txt_number,
[Link]([Link], on_click=self._increment),
],
alignment=[Link],
),
]
def _increment(self, e: [Link]) -> None:
[Link] += 1
self.txt_number.value = str([Link])
[Link]()
def _decrement(self, e: [Link]) -> None:
[Link] -= 1
self.txt_number.value = str([Link])
[Link]()
5. Depuração no VS Code (.vscode/[Link])
JSON
{
"version": "0.2.0",
"configurations": [
{
"name": "Flet: Executar App Desktop",
"type": "debugpy",
"request": "launch",
"program": "${workspaceFolder}/src/meu_app/[Link]",
"console": "integratedTerminal",
"env": {
"PYTHONPATH": "${workspaceFolder}/src"
}
},
{
"name": "Flet: Executar Modo Web",
"type": "debugpy",
"request": "launch",
"module": "[Link]",
"args": ["run", "src/meu_app/[Link]", "--web"],
"console": "integratedTerminal",
"env": {
"PYTHONPATH": "${workspaceFolder}/src"
}
}
]
}
6. Empacotamento e Publicação por Plataforma
O Flet fornece sua própria CLI para empacotar a aplicação em executáveis nativos (.exe, .app,
.apk, .ipa) através da integração com o ecossistema Flutter.
6.1. Build para Desktop (Windows / Linux / macOS)
Bash
# Empacotar como executável standalone
uv run flet build windows --product-name "MeuApp"
uv run flet build linux
uv run flet build macos
6.2. Build para Mobile (Android / iOS)
Bash
# Gera pacote APK para Android
uv run flet build apk
# Gera arquivo IPA para iOS (Requer macOS com Xcode instalado)
uv run flet build ipa
6.3. Deploy como Web App (PWA)
Bash
# Compila a aplicação para estáticos web (HTML/JS/WASM)
uv run flet build web
# Os arquivos gerados na pasta build/web podem ser hospedados em qualquer CDN (Netlify,
Vercel, S3)
7. Integração Contínua (CI/CD Pipeline)
Pipeline para automação de testes e checagem de código no GitHub Actions
(.github/workflows/[Link]):
YAML
name: CI Multiplatform
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
quality-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Instalar uv
uses: astral-sh/setup-uv@v2
with:
enable-cache: true
- name: Configurar Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Instalar Dependências
run: uv sync
- name: Formatação e Lint (Ruff)
run: |
uv run ruff check .
uv run ruff format --check .
- name: Checagem de Tipos (Pyright)
run: uv run pyright
8. Outras Alternativas Multiplataforma em Python
Se precisar comparar o Flet com outras soluções do ecossistema:
Framework Engine / Backend Alvos Principais Pontos Fortes
Flet Flutter (Dart/C++) Desktop, Mobile, UI moderna reativa,
Web suporte a hot-reload
e código 100%
Python.
BeeWare (Toga) Widgets Nativos da Desktop, Mobile Usa os controles
OS visuais nativos de
cada sistema
operacional.
PyWebView + Webview / Rust Desktop Leveza extrema e
Tauri interface construída
com HTML/CSS/JS
ou Svelte.
Textual TUI (Terminal) Linux, macOS, Interfaces ricas em
Windows modo texto
executadas
diretamente no
terminal.
9. Check-list Diário de Desenvolvimento
1. Ativar o projeto: uv sync
2. Executar em modo Live Reload: uv run flet run src/meu_app/[Link] -r
3. Validar antes do commit:
○ uv run ruff check --fix .
○ uv run ruff format .
○ uv run pyright
4. Gerar binários: uv run flet build <plataforma>