Metadata-Version: 2.4
Name: pyqt6-scaffold-cookbook
Version: 0.2.0
Summary: Cookbook and examples for pyqt6-scaffold
Author-email: Daniel Haus <daniel.haus@protonmail.com>
Keywords: pyqt6,qt,examples,cookbook
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Education
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pyqt6-scaffold>=0.1
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.12; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]; extra == "postgres"
Provides-Extra: all
Requires-Dist: pytest>=8; extra == "all"
Requires-Dist: ruff>=0.12; extra == "all"
Requires-Dist: mkdocs>=1.6; extra == "all"
Requires-Dist: mkdocs-material; extra == "all"
Requires-Dist: psycopg[binary]; extra == "all"

# PyQt6 Scaffold Cookbook

A curated collection of practical examples for building applications using **PyQt6 Scaffold**.

This repository demonstrates how to structure real-world applications using:
- Database abstraction layer
- Navigation and window composition
- Role-based access control (RBAC)
- Declarative UI patterns
- Card-based UI architecture
- CRUD-driven interfaces

It is designed as both:
- a learning resource
- a reference implementation
- a playground for architectural experimentation

---

# Installation

Install the package from PyPI:

```bash
pip install pyqt6-scaffold-cookbook
```

Or install locally from source:

```bash
python -m build
pip install dist/*.whl
```

---

# CLI Usage

After installation, the following command becomes available:

```bash
pyqt6-scaffold-cookbook
```

### List all recipes

Running without arguments prints all available examples:

```
Recipe 01: Database Layer
Recipe 02: First Window
Recipe 03: Navigation
Recipe 04: RBAC UI
Recipe 05: Complete System
```

### View a file from a recipe

You can print any source file directly:

```bash
pyqt6-scaffold-cookbook 01_database_layer database
```

This will output the contents of:

```
examples/01_database_layer/database.py
```

---

# Project Structure

Each example is self-contained and follows a consistent structure:

```
examples/
  01_database_layer/
  02_first_window/
  03_navigation/
  04_rbac_ui/
  05_complete_system/
```

Each recipe typically includes:
- `README.md` – explanation of the concept
- `main.py` – entry point (if applicable)
- `windows.py` – UI layer
- `database.py` – data layer (when relevant)
- additional modules depending on complexity

---

# Design Philosophy

This project is built around a few core principles:

### 1. Layered Architecture
UI, business logic, and database access are separated.

### 2. Declarative UI
UI is described through reusable components instead of imperative construction.

### 3. Composition over inheritance
Windows and components are composed via a central `Composer`.

### 4. Minimal external dependencies
The examples focus on PyQt6 and the scaffold framework itself.

### 5. Educational clarity
Code is intentionally verbose and heavily documented.

---

# Database Layer

The project uses an abstract database layer:

- `AbstractDatabase` defines a unified interface
- Backends:
  - PostgreSQL
  - MySQL
  - SQLite

Example:

```python
db = PostgresqlDatabase()
db.connect()

with db.execute("SELECT * FROM users") as cursor:
    print(cursor.fetchall())
```

---

# Authentication & RBAC

Role-based access control is implemented via:

- `Role`
- `RoleLevel`
- `RBACMixin`

Example roles:
- Guest
- User
- Manager
- Admin

Access to UI components is dynamically controlled based on role level.

---

# Navigation System

Navigation is handled by a central `Composer`:

- Registers windows
- Manages lifecycle
- Handles navigation events
- Maintains shared context

Example flow:

```
LoginWindow -> MainWindow -> Tabs -> CRUD Views
```

---

# UI Architecture

The UI system is built around:

### Cards
Used for list rendering

### Delegates
Define how data is displayed visually

### Tabs
Encapsulate application features

### Forms
Declarative field system for CRUD operations

---

# Important Note

Some examples in this cookbook intentionally simplify or omit production concerns (such as external configuration or full deployment-ready database setup) to focus on architectural clarity and learning value.

---

# Author

Daniel Haus
