PPG - Python Package Generator

PPG is a modern and powerful framework for building scalable desktop applications with Python and Qt. It offers a component-based architecture inspired by React, an advanced global state management system (Pydux), and seamless support for hybrid interfaces that combine native widgets with modern web UIs. With a comprehensive CLI and an innovative hot-reloading engine, PPG provides a complete and efficient workflow for developers.

Explore docs 📖 | View examples 💻

Explore v1.1.2 (classic) docs 🏛️

---

🔥 Key Features

• Reactive Component Architecture: Design your UI using a component-based React-style approach that guides each element through a lifecycle of initialization, rendering, and cleanup.
• Global State Management (Pydux): A robust, type-safe system (powered by Pydantic) for real-time communication between your components.
• Hybrid Support: Seamlessly combine native Qt widgets with modern web UIs (React, Vue, etc.) within the same application.
• Hot Reloading Engine: Boost your productivity with instant code reloads that let you see UI changes without restarting the app.
• Comprehensive CLI: A command-line interface that automates your entire app lifecycle, from initialization to compilation and installer creation.

---

🚀 Quick Start

The PPG workflow is simple and intuitive. Here’s how you can initialize, run, and compile your first application:

# 1. Install PPG using pip
pip install ppg

# 2. Initialize a new project with the CLI
ppg init

# 3. Run your application in development mode
ppg start

# 4. Compile your app into a standalone executable
ppg freeze

# 5. Create an installer for your application
ppg installer

📖 Guide

• Installation
• CLI Usage
• Component Architecture
• State Management with Pydux
• Hybrid Development (Web + Native)
• Changelog
• License

Installation

For best practices, we recommend using a virtual environment.

1. Create and activate your virtual environment:

# With conda
conda create -n my-env python=3.11 -y
conda activate my-env

# With virtualenv
python -m venv venv

# macOS/Linux:
source venv/bin/activate

# Windows:
.\venv\Scripts\activate.bat

2. Install PPG:

pip install ppg

Alternatively, you can install the latest development version directly from GitHub:

pip install git+https://github.com/neuri-ai/PPG.git

Or clone the repository and install it locally:

git clone https://github.com/neuri-ai/PPG

cd PPG

python setup.py install

CLI Usage

The PPG CLI allows you to manage your project efficiently.

Command	Description
ppg init	Initializes a new project in the current directory with an interactive setup.
ppg start	Runs your application from the source code in development mode.
ppg create	Creates a new component or view from templates, maintaining your project's structure.
ppg freeze	Compiles your code into a standalone executable for distribution.
ppg installer	Creates a user-friendly installer for your app (e.g., .exe on Windows, .dmg on macOS).
ppg test	Automatically runs the unit tests for your project.
ppg clean	Cleans up temporary and build files generated by PPG.

Component Architecture

Traditional Qt is event-driven, but it lacks a structured lifecycle for managing UI components at a high level. This can lead to complex, hard-to-maintain code as applications grow.

PPG solves this with a well-defined, React-inspired component lifecycle. It provides clear hooks for every stage of a component's life, from creation to destruction. This allows you to write clean, predictable code by providing specific moments to:

• Mounting: Set up a component and fetch initial data.
• Updating: React to data changes and re-render the UI.
• Unmounting: Clean up resources to prevent memory leaks.

This architecture brings a modern and robust development experience to both native Qt widgets and hybrid web components.

State Management with Pydux

Pydux is PPG's global state management system, inspired by JavaScript's Redux. It provides a type-safe, reactive way to manage application state across components. Pydux uses Pydantic for data validation and serialization, ensuring that your state is always consistent and reliable.

• Unified State: Maintains a single global state that is shared across all your components.
• Type Safety: Ensures that your state is always valid and adheres to defined schemas.
• Replaces PPGStore: PPGStore has been deprecated. It is highly recommended to migrate to Pydux to leverage all of its features.

Hybrid Development (Web + Native)

PPG supports hybrid development, allowing you to combine native Qt widgets with modern web UIs (like React or Vue) in the same application. This enables you to:

• Hybrid Interfaces: Use native widgets for performance-critical parts of your app.
• Fluid Communication: WebEngineBridge and BridgeManager provide a bidirectional messaging channel, allowing your web frontend and Python backend to communicate transparently.
• Total Synchronization: Both native widgets and web components can use the same Pydux state management system, ensuring a consistent and reactive user experience.

Changelog

Compatibility & Core Fixes

• Added compatibility with PySide6.2+ ✅
• Fixed compatibility issue with PySide2 (PySide6 and Qt5 use exec(), while PySide2 uses exec_()) ✅
• Fixed an issue that prevented maximizing the window when creating a new project ✅
• Added compatibility with PyInstaller 6.9.0+ ✅
• Fixed an issue where the QApplication singleton required destruction before creating a new instance of QApplication ✅
• Fixed the get_resource method, which previously could not be used normally ✅
• Fixed a compilation issue on macOS that prevented applications from compiling correctly due to Sparkle ✅
• Fixed installer compatibility to support Apple Silicon ✅

CLI & Project Management

• Fixed an issue with the CLI in the component/view generator that occurred when the "views" or "components" folder did not exist within the project ✅
• Updated icons ✅
• Fixed resources folder not being created when running ppg init ✅
• Fixed an issue where ppg init would fail due to a missing src/build/settings/base.json file on new projects ✅
• Fixed an issue where application names were not properly converted to CamelCase when generating new projects ✅
• Fixed an issue where build_settings could not be accessed in compiled applications and source projects ✅

🎉 Major New Features: Pydux State Management

• Revolutionary state management: Added Pydux, which manages a global state between components, allowing real-time communication between them 🎉
• Components integration: Components generated by the CLI now natively support Pydux 🎉

New! Advanced Pydux Features

• Type-safe state management: Full Pydantic integration with dynamic schema validation ✨
• Nested model support: Complex data structures with automatic validation ✨
• Partial updates: update_nested_model() method for efficient updates of nested objects ✨
• Dot notation access: get_nested() method for intuitive data retrieval (e.g., store.get_nested("user.name")) ✨
• Schema flexibility: Progressive typing - start with simple dicts, evolve to strict Pydantic models ✨
• Production-ready validation: Runtime type checking with clear error messages ✨

Deprecation Notice

• Deprecated: PPGStore is now marked as deprecated. Use Pydux instead. Backward compatibility is maintained for all v1.1.x versions, but PPGStore will be removed in a future major release.

🎉 Native & Web UI Hybrid Applications

New! Native and Web UI Integration

• WebEngineBridge: Added WebEngineBridge and BridgeManager classes to simplify communication between Python and web-based user interfaces built with React, Vue, or plain HTML/CSS/JS 🎉
• Native and Web UI design: With PPG, you can design fully native Qt user interfaces or create modern web-based interfaces that run inside your desktop app.
• Hybrid application support: First-class support for hybrid applications that seamlessly combine native Qt widgets and full web UIs in the same app ✅
• Web ↔ Python messaging: Built-in event-driven messaging API enables smooth communication between web frontends and the Python backend 🎉
• Unified lifecycle & state management: Both native and web UI components support the same component lifecycle and Pydux global state management, making your app consistent and reactive ✅

🔥 New! Hot Reloading Engine

• Real-time hot reloading: Instantly see code changes in components and views without restarting the app
• Automatic reloading: Changes to Python files trigger automatic reloads of affected components, views, and the entire app ✨
• Developer productivity boost: Shortens the feedback loop dramatically, enabling rapid iteration and testing ✅

Creators

Luis Alfredo Reyes

• https://twitter.com/Fredo_Dev
• https://github.com/runesc

Contributors

I would like to thank the following people for their contributions to this project, your pull requests, bug reports, and suggestions have been invaluable:

• Kastakin - https://github.com/Kastakin
• chenyulue - https://github.com/chenyulue
• Abhinavreddy-B - https://github.com/Abhinavreddy-B
• cccaballero - https://github.com/cccaballero
• mkodes - https://github.com/mkodes
• johnosbb - https://github.com/johnosbb

License

Code and documentation copyright 2020–2025. PPG Code released under the GPL v3 License. Docs released under Creative Commons.