Metadata-Version: 2.4
Name: ppg
Version: 1.2.0
Summary: PPG: A powerful app generator simplifying development with Python and Qt.
Home-page: https://ppg.neuri.ai
Author: Neuri
Author-email: alfredo@neuri.ai
License: GPL-3.0-only
Keywords: ppg,python,pyqt,pyside,desktop,application,generator,cli,component,state management,pydux,fbs,react,redux,app development,modular,scalable,lifecycle,component-based,pyside6,pyqt6,pyqt5,pyqt6 generator,pyqt5 generator,pyside6 generator,pyside5 generator,pyqt6 app,pyqt5 app,pyside6 app,pyside5 app,app generator,redux
Platform: MacOS
Platform: Windows
Platform: Debian
Platform: Fedora
Platform: CentOS
Platform: Arch
Platform: Raspbian
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
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
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: PyInstaller>=6.9.0
Requires-Dist: pydantic>=2.11.7
Requires-Dist: questionary==2.1.0
Requires-Dist: rich==14.1.0
Requires-Dist: watchdog==6.0.0
Requires-Dist: astor==0.8.1
Requires-Dist: prompt_toolkit==3.0.39
Provides-Extra: licensing
Requires-Dist: rsa>=3.4.2; extra == "licensing"
Provides-Extra: sentry
Requires-Dist: sentry-sdk>=0.6.6; extra == "sentry"
Provides-Extra: upload
Requires-Dist: boto3; extra == "upload"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: platform
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: summary

<p align="center">
  <img src="https://ik.imagekit.io/kummiktgaiq/ppg/logo_OE3b6z79V.png?updatedAt=1635261532682" alt="PPG Logo" width="50%">
</p>

<h3 align="center">PPG - Python Package Generator</h3>

![GitHub Release](https://img.shields.io/github/v/release/runesc/PPG?include_prereleases&display_name=release&color=stable&link=https%3A%2F%2Fgithub.com%2Frunesc%2FPPG%2Freleases)
![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/runesc/PPG?color=%23ab7df8)
![GitHub Issues or Pull Requests](https://img.shields.io/github/issues-closed/runesc/PPG?color=green)
![GitHub forks](https://img.shields.io/github/forks/runesc/PPG)
![GitHub stars](https://img.shields.io/github/stars/runesc/PPG)
![GitHub licence](  https://img.shields.io/github/license/runesc/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.

<p align="center">
    <a href="https://ppg.neuri.ai/"><strong>Explore the docs »</strong></a>
</p>

---

### 🔥 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](https://github.com/neuri-ai/PPG.git)
```

Or clone the repository and install it locally:
```bash
git clone [https://github.com/neuri-ai/PPG](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>


### 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/).
