Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/Neuri-AI/PPG

Create Powerful Python Apps with Qt5/Qt6
https://github.com/Neuri-AI/PPG

app pyqt5 pyqt6 pyside2 pyside6 qt5 qt6

Last synced: 2 months ago
JSON representation

Create Powerful Python Apps with Qt5/Qt6

Awesome Lists containing this project

README 

          


  PPG Logo




PPG - Python Package Generator



![GitHub Release](https://img.shields.io/github/v/release/Neuri-Ai/PPG?include_prereleases&display_name=tag&color=stable)

![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/Neuri-Ai/PPG?color=%23ab7df8)

![GitHub Issues or Pull Requests](https://img.shields.io/github/issues-closed/Neuri-Ai/PPG?color=green)

![GitHub forks](https://img.shields.io/github/forks/Neuri-Ai/PPG)

![GitHub stars](https://img.shields.io/github/stars/Neuri-Ai/PPG)

![GitHub licence](	https://img.shields.io/github/license/Neuri-Ai/PPG)

![PyPI Downloads](https://static.pepy.tech/badge/ppg)



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:



```bash

# 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](#installation)

- [CLI Usage](#cli-usage)

- [Component Architecture](#component-architecture)

- [State Management with Pydux](#state-management-with-pydux)

- [Hybrid Development (Web + Native)](#hybrid-development-web--native)

- [Changelog](#changelog)

- [License](#license)



### Installation

For best practices, we recommend using a virtual environment.



1. **Create and activate your virtual environment**:

```bash

# 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**:

```bash

pip install ppg

```



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

```bash

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

```



Or clone the repository and install it locally:

```bash

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**



- 

- 



### 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** - 

- **chenyulue** - 

- **Abhinavreddy-B** - 

- **cccaballero** - 

- **mkodes** - 

- **johnosbb** - 



### License



Code and documentation copyright 2020–2025. [PPG](#) Code released under the [GPL v3 License](#). Docs released under [Creative Commons](https://creativecommons.org/licenses/by/3.0/).