Metadata-Version: 2.4
Name: pyqtrapid
Version: 1.0.0
Summary: A modern CLI scaffolding framework and architecture boilerplate generator for PyQt and PySide applications.
Author-email: Eden Iyanda <edeniyanda@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/edeniyanda/pyqtrapid
Project-URL: Documentation, https://github.com/edeniyanda/pyqtrapid#readme
Project-URL: Repository, https://github.com/edeniyanda/pyqtrapid.git
Project-URL: Issues, https://github.com/edeniyanda/pyqtrapid/issues
Keywords: pyqt,pyqt6,pyside6,pyqt5,qt,gui,scaffold,boilerplate,cli,mvp,mvvm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-qt>=4.0.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: pyqt6
Requires-Dist: PyQt6>=6.0.0; extra == "pyqt6"
Provides-Extra: pyside6
Requires-Dist: PySide6>=6.0.0; extra == "pyside6"
Provides-Extra: pyqt5
Requires-Dist: PyQt5>=5.15.0; extra == "pyqt5"
Dynamic: license-file

# pyqtrapid

[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/edeniyanda/pyqtrapid)
[![PyPI Version](https://img.shields.io/pypi/v/pyqtrapid.svg)](https://pypi.org/project/pyqtrapid/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python Versions](https://img.shields.io/pypi/pyversions/pyqtrapid.svg)](https://pypi.org/project/pyqtrapid/)

`pyqtrapid` is a CLI scaffolding framework and architecture generator for Python desktop applications built with PyQt and PySide.

It streamlines the creation of maintainable, testable, and production-ready GUI applications by establishing architectural separation of concerns, multi-binding abstraction, threading utilities, theme management, component generation, and standard packaging out of the box.

---

## Key Features

- **Multi-Binding Compatibility**: Native support for **PyQt6**, **PySide6** (Official Qt for Python 6), and **PyQt5**.
- **Architecture Scaffolds**:
  - **MVP (Model-View-Presenter)**: Decoupled presentation logic, ideal for enterprise desktop applications.
  - **MVVM (Model-View-ViewModel)**: Reactive view-model binding pattern for data-driven UIs.
  - **Minimal**: Lightweight structure for rapid prototyping.
- **Component Generators**: CLI commands to scaffold individual Views, Models (with unit tests), Dialogs, and Presenters on demand.
- **Executable Packaging Scaffolds**: Instant setup for **PyInstaller** (`.spec`) and **Nuitka** C++ standalone executable builds.
- **Asynchronous Thread Pool**: Built-in non-blocking background task runner utilizing `QThreadPool` and `QRunnable`.
- **Theme System**: Integrated QSS styling engine supporting light/dark theme switching and QSettings persistence.
- **Testing & Diagnostics**: Pre-configured `pytest` suite and structured logging infrastructure.

---

## Installation

Install `pyqtrapid` using `pip`:

```bash
pip install pyqtrapid
```

To install from source for development:

```bash
git clone https://github.com/edeniyanda/pyqtrapid.git
cd pyqtrapid
pip install -e .
```

---

## CLI Command Reference

### 1. Project Scaffolding (`startproject`)

Scaffold a complete application directory:

```bash
pyqtrapid startproject <project_name> [options]
```

| Option | Short | Default | Description |
| :--- | :--- | :--- | :--- |
| `--binding` | `-b` | `pyqt6` | Qt Python binding (`pyqt6`, `pyside6`, `pyqt5`) |
| `--template` | `-t` | `mvp` | Architectural template (`mvp`, `mvvm`, `minimal`) |
| `--force` | `-f` | `false` | Overwrite target directory if it already exists |

### 2. Component Scaffolding (`generate`)

Generate modular components inside an existing project:

```bash
pyqtrapid generate <type> <name> [options]
```

| Component Type | Description | Output Files |
| :--- | :--- | :--- |
| `view` | Qt Widget View | `src/views/<name>_view.py` |
| `model` | Domain Model & Unit Test | `src/models/<name>_model.py`<br>`tests/test_<name>_model.py` |
| `dialog` | Modal Dialog (`QDialog`) | `src/views/<name>_dialog.py` |
| `presenter` | Presenter Controller | `src/presenters/<name>_presenter.py` |

### 3. Packaging Configuration (`build-config`)

Scaffold production build files for single-file executable bundling:

```bash
# Generate PyInstaller build specification
pyqtrapid build-config --tool pyinstaller --name my_app

# Generate Nuitka C++ standalone build script
pyqtrapid build-config --tool nuitka --name my_app
```

---

## Quick Start Examples

### Scaffold an MVP Project with PyQt6 (Default)

```bash
pyqtrapid startproject desktop_app
```

### Scaffold an MVVM Project with PySide6

```bash
pyqtrapid startproject analytics_dashboard --binding pyside6 --template mvvm
```

### Generate Components Inside Existing Project

```bash
cd desktop_app

# Generate a User Profile Model with tests
pyqtrapid generate model user_profile

# Generate a Settings View
pyqtrapid generate view settings

# Generate a Custom Login Dialog
pyqtrapid generate dialog login
```

---

## Directory Structure Overview

Generated projects adhere to clean separation of concerns:

```text
desktop_app/
├── main.py                   # Application entry point & Qt event loop
├── pyproject.toml            # Package metadata & test configuration
├── src/
│   ├── app.py                # Dependency injection & view factory
│   ├── core/                 # App config, logging, and async worker pool
│   │   ├── config.py
│   │   ├── logger.py
│   │   └── worker.py
│   ├── models/               # Domain state & business logic (pure Python)
│   ├── views/                # Qt Widgets & UI layout definitions
│   ├── presenters/           # Presentation logic connecting Views & Models
│   └── resources/            # Stylesheets (QSS) and static assets
│       └── styles/
│           ├── dark.qss
│           └── light.qss
├── ui/                       # Qt Designer (.ui) XML files
└── tests/                    # Unit tests and view suite (pytest)
```

---

## Running and Testing Scaffolded Applications

Navigate to your generated project directory and run the application:

```bash
cd desktop_app
pip install -e .
python main.py
```

Run the automated test suite:

```bash
pytest
```

---

## Contributing

Contributions, issue reports, and feature suggestions are welcome. Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) to get started.

---

## License

`pyqtrapid` is released under the [MIT License](LICENSE).
