QPyPack/docs/readme/README_PT.md

QPyPack

简体中文 | English | 繁體中文 | 日本語 | 한국어 | Français | Deutsch | Español | Русский | Português

---

Ferramenta GUI moderna e pronta para uso para empacotar aplicações Python multiplataforma
_{Alimentada pelos motores PyInstaller e Nuitka, com configuração visual, análise estática de dependências e fluxo de compilação automatizado.}

📌 Visão Geral do Projeto (Overview)

O QPyPack é uma ferramenta gráfica multiplataforma desenvolvida para simplificar o empacotamento de aplicações Python. Ao integrar perfeitamente os motores PyInstaller (agrupamento de bytecode) e Nuitka (compilação nativa C/C++), transforma cadeias de ferramentas complexas, análise de dependências implícitas, isolamento de ambientes e coleta de recursos em uma interface de usuário intuitiva.

Seja para distribuir scripts de automação simples ou aplicações complexas com dependências pesadas (como PySide6/PyQt, Playwright, CustomTkinter, FastAPI, etc.), o QPyPack oferece uma experiência de compilação estável, reproduzível e com alta taxa de sucesso no Windows, macOS e Linux.

---

📸 Capturas de Tela (Screenshots)

---

🛠️ Arquitetura e Principais Recursos

1. Compilação por Motor Duplo e Otimização Binária

• Alternância fluida entre motores:
  • PyInstaller: Compilação rápida, sem dependência de compiladores C externos, excelente compatibilidade.
  • Nuitka: Traduz código Python diretamente para binários C/C++ nativos para alto desempenho, forte proteção contra engenharia reversa e tamanho compacto.
• Otimização LTO e poda de submódulos: Suporte a LTO (--lto=yes) no modo Lite. Identificação e exclusão automática de submódulos Qt pesados não utilizados (WebEngine, 3D, Quick, etc.) para evitar inchaço binário.
• Formatos de distribuição flexíveis: Compatível com modo de Arquivo único (--onefile) e modo Diretório (--onedir), com personalização do diretório interno de dependências (--contents-directory).

2. Análise Estática e Proteção de Dependências

• Varredura AST recursiva nativa: Analisador estático de árvore de sintaxe abstrata (AST) em Python puro que descobre importações explícitas e implícitas sem executar o código.
• Mapeamento inteligente de pacotes: Tabela de correspondência integrada entre nomes de importação e pacotes PyPI (ex: cv2 \to opencv-python, PIL \to pillow, win32com \to pywin32), modular e extensível.
• Isolamento dinâmico de bibliotecas obsoletas (Backport Isolation): Detecta e bloqueia pacotes de retrocompatibilidade obsoletos que entram em conflito com a biblioteca padrão moderna (ex: isolando pathlib ou typing no Python 3.10+).

3. Gerenciamento Automatizado de Ambiente e Autorrecuperação

• Provisionamento automático de compiladores C/C++: Detecta MSVC, Clang (LLVM) e GCC locais. Caso nenhum compilador seja encontrado, o Nuitka baixa e gerencia automaticamente a toolchain MinGW-w64.
• Gerenciamento do ciclo de vida de ambientes virtuais: Suporte para sandboxes isoladas e ambientes compartilhados com utilitário de limpeza integrado.
• Gerenciamento adaptativo de recursos e autorrecuperação:
  • Avalia RAM e espaço em disco antes da compilação, ajustando a concorrência de threads (Adaptive Concurrency).
  • Captura falhas de memória saturada (ZstdError / OOM) e reinicia a compilação no modo mono-thread de baixo consumo.
  • Evita bloqueios exclusivos de arquivos causados por antivírus ou serviços de sincronização em nuvem.

4. Assinatura de Código e Predefinições de Projeto

• Assinatura digital inteligente: Aplica assinaturas digitais Authenticode em binários Windows (compatível com Signtool e PowerShell com carimbo de data/hora RFC 3161) e assinatura runtime codesign no macOS.
• Suite de certificados: Gerador integrado de certificados autoassinados (.pfx) e suporte para certificados comerciais.
• Importação/Exportação de predefinições: Salva todos os parâmetros de compilação, listas de recursos e regras em arquivos .qpypack.

5. Experiência de Usuário e Internacionalização (i18n)

• Arrastar e soltar intuitivo: Ao soltar um script Python, extrai metadados (__version__, __author__), deduz o ponto de entrada e mapeia o ícone da aplicação.
• Interface vetorial com suporte HiDPI: Construída com ícones vetoriais Google Material SVG, com dimensionamento perfeito em monitores 4K. Traduzida para 17 idiomas (português, inglês, chinês, japonês, coreano, alemão, francês, espanhol, etc.).

---

📊 Comparativo de Motores (PyInstaller vs. Nuitka)

Critério	PyInstaller	Nuitka
Princípio	Empacota interpretador Python + bytecode (.pyc)	Compila código Python para binários C/C++ nativos
Velocidade de compilação	Muito rápida (geralmente 10 – 60 s)	Mais lenta (requer geração de código C++ e otimizações)
Compilador C/C++	Não necessário	Necessário (gestão automática de MSVC / GCC / Clang / MinGW-w64)
Nível de proteção	Básico (código recuperável via descompiladores)	Extremamente alto (código de máquina nativo, alta proteção)
Desempenho de execução	Velocidade padrão do Python	Inicialização mais rápida, laços e computação otimizados
Recomendado para	Prototipagem rápida, ferramentas internas, projetos dinâmicos	Software comercial, proteção de algoritmos, otimização de tamanho

---

⚡ Início Rápido (Quick Start)

💡 Primeira vez usando o QPyPack? Consulte nosso 📖 Guia de Início Rápido (QUICKSTART.md) para um tutorial passo a passo e configurações recomendadas.

Método 1: Instalação via pip / pipx (Recomendado)

Requer Python >= 3.8:

# Instalar via pip
pip install qpypack

# Iniciar a aplicação gráfica
qpypack

Com gerenciadores de pacotes modernos:

# Executar isolado via pipx
pipx run qpypack

# Inicialização ultrarrápida via uv
uvx qpypack

Método 2: Versão binária pré-compilada independente

Sem necessidade de configurar o Python localmente, baixe os executáveis pré-compilados diretamente na página de lançamentos:

👉 Baixar versões pré-compiladas (GitHub Releases)

---

📋 Resolução de Caminhos de Recursos (sys._MEIPASS)

No modo de arquivo único (--onefile), os recursos estáticos (imagens, arquivos de configuração, modelos) são extraídos temporariamente durante a execução. Utilize o seguinte padrão padrão para resolver caminhos:

import sys
import os
from pathlib import Path

def get_asset_path(relative_path: str) -> Path:
    """Obtém o caminho absoluto para recursos empacotados."""
    if hasattr(sys, "_MEIPASS"):
        # Diretório de extração temporária do PyInstaller
        base_path = Path(sys._MEIPASS)
    elif "__compiled__" in globals():
        # Diretório de execução do binário Nuitka
        base_path = Path(sys.argv[0]).resolve().parent
    else:
        # Ambiente de desenvolvimento local
        base_path = Path(__file__).resolve().parent
    return base_path / relative_path

---

📅 Registro de Alterações (Changelog)

Para notas de versão detalhadas e correções de bugs, consulte o arquivo CHANGELOG.md.

---

💖 Contribuição e Patrocínio

O QPyPack é um projeto de código aberto mantido no meu tempo livre. Se esta ferramenta foi útil para você, agradecemos seu apoio voluntário:

• 🌟 Estrela no GitHub: Deixe uma estrela no repositório no GitHub.
• 🐛 Feedback e Sugestões: Envie relatórios de bugs e melhorias no GitHub Issues.
• ⚡ Patrocínio: Apoie o autor através do Afdian (爱发电) (compatível com WeChat Pay / Alipay).

---

📄 Licença (License)

Este projeto está licenciado sob a GNU General Public License v3.0 (GPL-3.0).

Important

Direitos autorais sobre binários gerados: Os direitos de propriedade intelectual e termos de licença das aplicações criadas com o QPyPack pertencem integralmente ao usuário. A licença GPL-3.0 do QPyPack não impõe restrições ao seu software compilado.

Copyright (C) 2026 QwejayHuang.