Metadata-Version: 2.4
Name: qpypack
Version: 2.8.3
Summary: A cross-platform GUI packaging and compilation suite based on PyInstaller and Nuitka.
Author: QwejayHuang
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/qwejay/QPyPack
Project-URL: Bug Tracker, https://github.com/qwejay/QPyPack/issues
Project-URL: Source Code, https://github.com/qwejay/QPyPack
Project-URL: Documentation, https://github.com/Qwejay/QPyPack/blob/main/README_EN.md
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: User Interfaces
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6>=6.0.0
Requires-Dist: Pillow>=9.0.0
Provides-Extra: engines
Requires-Dist: pyinstaller; extra == "engines"
Requires-Dist: nuitka; extra == "engines"
Requires-Dist: pipreqs; extra == "engines"
Requires-Dist: zstandard; extra == "engines"
Dynamic: license-file

# QPyPack

<p align="center">
  <a href="README.md">简体中文</a> |
  <a href="README_EN.md">English</a> |
  <a href="docs/readme/README_TW.md">繁體中文</a> |
  <a href="docs/readme/README_JA.md">日本語</a> |
  <a href="docs/readme/README_KO.md">한국어</a> |
  <a href="docs/readme/README_FR.md">Français</a> |
  <a href="docs/readme/README_DE.md">Deutsch</a> |
  <a href="docs/readme/README_ES.md">Español</a> |
  <a href="docs/readme/README_RU.md">Русский</a> |
  <a href="docs/readme/README_PT.md">Português</a>
</p>

<p align="center">
  <!-- PyPI Version -->
  <a href="https://pypi.org/project/qpypack/">
    <img src="https://img.shields.io/pypi/v/qpypack.svg?color=blue&logo=pypi&logoColor=white" alt="PyPI version" />
  </a>
  <!-- Python Versions -->
  <a href="https://pypi.org/project/qpypack/">
    <img src="https://img.shields.io/pypi/pyversions/qpypack.svg?logo=python&logoColor=white" alt="Python versions" />
  </a>
  <!-- PyPI Downloads -->
  <a href="https://pypistats.org/packages/qpypack">
    <img src="https://img.shields.io/pypi/dm/qpypack?color=orange&logo=pypi&logoColor=white" alt="PyPI Downloads" />
  </a>
  <!-- Supported Platforms -->
  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-informational" alt="Platform Support" />
  <br>
  <!-- Release Date -->
  <a href="https://github.com/Qwejay/QPyPack/releases">
    <img src="https://img.shields.io/github/release-date/Qwejay/QPyPack?color=brightgreen&logo=github" alt="Release Date" />
  </a>
  <!-- Last Commit -->
  <a href="https://github.com/Qwejay/QPyPack/commits/main">
    <img src="https://img.shields.io/github/last-commit/Qwejay/QPyPack" alt="Last Commit" />
  </a>
  <!-- GitHub License -->
  <a href="https://github.com/Qwejay/QPyPack/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/Qwejay/QPyPack.svg" alt="License" />
  </a>
  <!-- GitHub Stars -->
  <a href="https://github.com/Qwejay/QPyPack/stargazers">
    <img src="https://img.shields.io/github/stars/Qwejay/QPyPack.svg?logo=github&color=gold" alt="GitHub stars" />
  </a>
</p>

---

<p align="center">
  <strong>A Modern, Cross-Platform Python Packaging GUI</strong><br>
  <sub>Powered by PyInstaller and Nuitka, featuring visual configuration, static dependency analysis, and automated build workflows.</sub>
</p>

## 📌 Overview

**QPyPack** is a cross-platform graphical packaging tool designed for Python developers. By integrating both **PyInstaller** (bytecode bundling) and **Nuitka** (C/C++ native compilation) core engines, QPyPack abstracts low-level compiler toolchains, complex dependency tracking, sandbox isolation, and resource collection into an intuitive, reliable desktop interface.

Whether you are distributing simple automation scripts or complex enterprise applications (built with PySide6/PyQt, Playwright, CustomTkinter, FastAPI, etc.), QPyPack delivers a reproducible, high-success build experience across Windows, macOS, and Linux.

---

## 📸 Screenshots

<p align="center">
  <img width="32%" alt="Main Interface (English)" src="https://github.com/user-attachments/assets/9d16c68e-d283-4020-86c1-9d4791756c29" />
  <img width="32%" alt="Main Interface (Chinese)" src="https://github.com/user-attachments/assets/0147460d-1e9e-4612-9b52-9d347d81b7c5" />
  <img width="32%" alt="Engine & Environment" src="https://github.com/user-attachments/assets/0ad4db6d-b008-4018-bd69-40a369a10b7d" />
  <br />
  <img width="32%" alt="Dependency Management" src="https://github.com/user-attachments/assets/c7fd1218-d079-4898-a97c-aa980c4d1375" />
  <img width="32%" alt="Optimization & Signing" src="https://github.com/user-attachments/assets/e5b7500e-2a0d-4c6d-b20b-7d8d2d3bac8d" />
  <img width="32%" alt="About & Diagnostics" src="https://github.com/user-attachments/assets/e652b222-49f5-44cd-ad3f-d93369ede26b" />
</p>

---

## 🛠️ Architecture & Key Features

### 1. Dual-Engine Compilation & Binary Optimization
* **Dual Packaging Engines**:
  * **PyInstaller**: Fast compilation, zero compiler dependencies, and extensive ecosystem hook compatibility.
  * **Nuitka**: Translates Python code into native C/C++ binaries, providing performance acceleration, compact size, and deep IP/reverse-engineering protection.
* **LTO & Submodule Pruning**: Lite Mode integrates `--lto=yes` (Link-Time Optimization) and automatically identifies and excludes unused heavy Qt submodules (e.g., `QtWebEngineCore`, `Qt3DCore`, `QtQuick`, `QtLocation`), preventing binary size bloat.
* **Flexible Binary Distribution**: Supports **Single-File (`--onefile`)** and **Directory (`--onedir`)** modes, with customizable internal asset directory paths (`--contents-directory`).

### 2. Static Dependency Analysis & Safety Net
* **Native AST Static Scanner**: Recursively parses Abstract Syntax Trees (AST) across source files and folders to discover explicit and hidden imports without executing the code.
* **Package Distribution Mapper**: Maps common import namespaces to their canonical PyPI distribution names (e.g., `cv2` $\to$ `opencv-python`, `PIL` $\to$ `pillow`, `win32com` $\to$ `pywin32`), with full user customization.
* **Obsolete Backport Isolation**: Automatically detects and shields legacy backport modules that conflict with modern standard libraries (e.g., isolating redundant `pathlib` or `typing` packages on Python 3.10+).

### 3. Toolchain Provisioning & Runtime Self-Healing
* **Automated Compiler Provisioning**: Detects local MSVC, Clang (LLVM), or GCC compilers. If no native C compiler is found, Nuitka automatically provisions a managed MinGW-w64 toolchain.
* **Virtual Environment Management**: Supports isolated sandboxes as well as reusable shared virtual environments, complete with a built-in clean-up utility for legacy project environments.
* **Resource-Aware Concurrency**:
  * Evaluates system RAM and disk space prior to compilation, adaptively adjusting thread concurrency to prevent out-of-memory errors.
  * Recovers from memory allocation failures (`ZstdError` / OOM) by automatically retrying in single-threaded low-memory mode.
  * Mitigates file-locking collisions caused by antivirus software or cloud sync drives during output assembly.

### 4. Code Signing & Project Presets
* **Smart Code Signing**: Automatically applies digital signatures to Windows binaries (supporting Signtool and PowerShell Authenticode engines with RFC 3161 timestamping) and handles macOS `codesign` runtime signing.
* **Certificate Suite**: Includes an integrated self-signed `.pfx` certificate generator and supports custom commercial certificate injection.
* **Preset Import / Export**: Saves complete build parameters, asset mappings, and exclusions into shareable `.qpypack` preset files for CI/CD and team workflows.

### 5. UI/UX & Global Localization
* **Drag-and-Drop Workflow**: Dropping a `.py`/`.pyw` script auto-parses metadata (`__version__`, `__author__`, `__title__`), initializes the workspace, and maps corresponding application icons.
* **Vector UI with HiDPI Support**: Built entirely with Google Material SVG vector icons with native multi-monitor DPI scaling.
* **Full Localization (i18n)**: Out-of-the-box support for 17 languages, including English, Simplified/Traditional Chinese, Japanese, Korean, German, French, Spanish, and Russian.

---

## 📊 Engine Comparison (PyInstaller vs. Nuitka)

| Metric | PyInstaller | Nuitka |
| :--- | :--- | :--- |
| **Mechanism** | Bundles Python interpreter + bytecode (`.pyc`) | Compiles Python code to native C/C++ binaries |
| **Build Time** | Fast (typically 10 – 60 seconds) | Slower (requires C++ code generation & optimization) |
| **C/C++ Compiler** | Not required | Required (MSVC / GCC / Clang / MinGW-w64) |
| **Source Protection** | Basic (can be unpacked via decompilers) | High (compiled machine code; resistant to reverse engineering) |
| **Execution Performance** | Standard Python runtime speed | Fast startup; improved loop and compute efficiency |
| **Ideal For** | Rapid prototyping, internal tools, dynamic import scripts | Commercial distribution, proprietary algorithms, optimized size |

---

## ⚡ Quick Start

> 💡 **First time using QPyPack?** Check out the [**📖 Quickstart Guide (QUICKSTART.md)**](QUICKSTART.md) for step-by-step instructions and recommended project configurations.

### Method 1: Install via pip / pipx (Recommended)

Requires Python >= 3.8:

```bash
# Install QPyPack
pip install qpypack

# Launch the application
qpypack
```

*Or run directly in an isolated environment via modern package managers:*
```bash
# Using pipx
pipx run qpypack

# Using uv
uvx qpypack
```

### Method 2: Standalone Executable

If you prefer not to install Python locally, download pre-built binary releases for Windows, macOS, or Linux:

👉 [**Download Standalone Release (GitHub Releases)**](https://github.com/Qwejay/QPyPack/releases)

---

## 📋 Best Practices: Asset Resolution (`sys._MEIPASS`)

In Single-File mode (`--onefile`), bundled static assets (images, configuration files, model weights) are extracted to a temporary runtime sandbox directory. Use the following helper pattern to reliably resolve paths across development and production:

```python
import sys
import os
from pathlib import Path

def get_asset_path(relative_path: str) -> Path:
    """Resolve asset paths across development, PyInstaller, and Nuitka."""
    if hasattr(sys, "_MEIPASS"):
        # PyInstaller temporary extraction directory
        base_path = Path(sys._MEIPASS)
    elif "__compiled__" in globals():
        # Nuitka native binary execution directory
        base_path = Path(sys.argv[0]).resolve().parent
    else:
        # Local development environment
        base_path = Path(__file__).resolve().parent
    return base_path / relative_path
```

---

## 📅 Changelog

For detailed release notes, new features, and bug fixes, please consult [CHANGELOG.md](CHANGELOG.md).

---

## 💖 Contributing & Sponsorship

QPyPack is an open-source project maintained during personal time. If QPyPack has helped streamline your deployment workflow, voluntary sponsorships are warmly welcomed to support continuous development:

- 🌟 **Star the Project**: Give us a star on [GitHub](https://github.com/Qwejay/QPyPack).
- 🐛 **Feedback & Issues**: Submit bug reports and feature requests via [GitHub Issues](https://github.com/Qwejay/QPyPack/issues).
- ⚡ **Sponsor**: Support the author via [Afdian (爱发电)](https://www.ifdian.net/a/qwejay) (WeChat Pay / Alipay).

> *Note: Sponsorship is voluntary and serves as encouragement for open-source maintenance without commercial service commitments. Thank you for your support!*

---

## 📄 License

This project is licensed under the [GNU General Public License v3.0 (GPL-3.0)](LICENSE).

> [!IMPORTANT]
> **Copyright of Compiled Binaries**:
> The ownership, licensing, and distribution rights of applications compiled using QPyPack **belong entirely to the user**. QPyPack's GPL-3.0 license does not apply copyleft restrictions to the software you package.

<p align="right">Copyright (C) 2026 QwejayHuang.</p>
