ezqt-app 5.0.1

Lightweight framework based on PySide6 to quickly build modern desktop applications, with integrated resource, theme, and reusable component management.

🚀 EzQt App

EzQt App is a lightweight Python framework based on PySide6 to quickly build modern desktop applications, with integrated resource, theme, translation, and reusable component management. Built on a hexagonal architecture for clean separation of concerns.

📦 Installation

pip install ezqt-app

Or from source:

git clone https://github.com/neuraaak/ezqt-app.git
cd ezqt-app && pip install .

🚀 Quick Start

import sys
from ezqt_app.app import EzQt_App
from ezqt_app.services.application.app_service import AppService

# Initialize and run the framework
app_service = AppService()
app_service.initialize()

# Create main window
window = EzQt_App(themeFileName="main_theme.qss")

# Add navigation menus
home_page = window.addMenu("Home", "🏠")
settings_page = window.addMenu("Settings", "⚙️")

# Show application
window.show()
app_service.exec()

🎯 Key Features

• ✅ PySide6 Compatible: Full support for the latest PySide6 versions
• ✅ Hexagonal Architecture: Clean domain/services/widgets separation
• ✅ Full Type Hints: Complete typing support for IDEs and linters
• ✅ Dynamic Themes: Light/dark themes with integrated toggle via QSS
• ✅ Global Translation: Multi-language support (EN, FR, ES, DE)
• ✅ Automatic Translation: Multi-provider system (LibreTranslate, MyMemory, Google)
• ✅ CLI Tools: Project initialization, template generation, and management
• ✅ Template System: Basic and advanced project scaffolding
• ✅ Standardized Logging: Consistent message formatting across all components
• ✅ Comprehensive Tests: Complete test suite (~176 tests)

📚 Documentation

Full documentation is available online: neuraaak.github.io/ezqt-app

• 📖 Getting Started – Installation and first steps
• 🎯 API Reference – Complete module reference (auto-generated)
• 🎨 QSS Style Guide – QSS customization and best practices
• 💡 Examples – Usage examples and demonstrations
• 🖥️ CLI – Command-line interface guide
• 🧪 Testing – Test suite documentation
• 🔧 Development – Environment setup and contribution

🏗️ Architecture

EzQt App follows a hexagonal architecture with three main layers:

src/ezqt_app/
├── domain/          # Contracts, ports, models, errors (no dependencies)
│   ├── ports/       # Abstract interfaces (AppPort, ConfigPort, etc.)
│   ├── models/      # Domain models
│   └── errors/      # Domain exceptions
├── services/        # Adapters implementing domain ports
│   ├── application/ # App lifecycle (AppService, InitService)
│   ├── config/      # Configuration (ConfigService, SettingsService)
│   ├── translation/ # i18n (TranslationService, AutoTranslator)
│   └── ui/          # UI coordination (ThemeService, MenuService)
├── widgets/         # PySide6 presentation layer
│   ├── core/        # Header, Menu, PageContainer
│   └── extended/    # SettingWidgets and advanced components
├── shared/          # Cross-cutting utilities
├── cli/             # Command-line interface
└── app.py           # Main EzQt_App entry point

🧩 Available Components

🔧 Application Services (ezqt_app.services)

Service	Description
AppService	Application lifecycle management
InitService	Startup initialization and bootstrap
ConfigService	Application configuration management
SettingsService	User settings persistence
RuntimeStateService	Runtime state tracking
TranslationService	Language management and switching
ThemeService	Theme loading and switching
MenuService	Navigation menu management
WindowService	Main window orchestration

🌍 Translation System (ezqt_app.services.translation)

Component	Description
TranslationManager	Central translation registry and dispatch
AutoTranslator	Multi-provider automatic translation
StringCollector	Automatic string discovery for translation

🎨 Widgets (ezqt_app.widgets)

Widget	Description
EzQt_App	Main application window with modern UI
Header	Top navigation bar with title and controls
Menu	Sidebar navigation menu
PageContainer	Content area manager
SettingWidgets	Settings UI components with validation

🧪 Testing

Comprehensive test suite with 176+ test cases covering services, widgets, and integration scenarios.

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest tests/

# Run by marker
pytest tests/ -m unit
pytest tests/ -m integration

# With coverage
pytest tests/ --cov=src/ezqt_app --cov-report=html

# Using CLI
ezqt test --unit
ezqt test --coverage

See the Testing Guide for complete details.

🖥️ CLI Commands

Project Management

# Initialize new project (assets, QRC, resources)
ezqt init [--force] [--verbose] [--no-main]

# Create project from template
ezqt create --template basic --name my_app
ezqt create --template advanced --name my_app

# Show project information
ezqt info

Development Tools

# Convert .ts translation files to .qm
ezqt convert [--verbose]
ezqt mkqm [--verbose]

# Run tests
ezqt test [--unit] [--integration] [--coverage]

# Serve documentation
ezqt docs [--serve] [--port <port>]

🌍 Translation System

from ezqt_app.shared.helpers import tr, set_tr

# Translate a string
text = tr("Hello World")  # Returns "Bonjour le monde" in French

# Bind a widget for auto-retranslation on language change
from PySide6.QtWidgets import QLabel
label = QLabel()
set_tr(label, "Hello World")

# Change active language
from ezqt_app.services.translation.translation_service import TranslationService
TranslationService.instance().set_language("Français")

Supported languages: English, Français, Español, Deutsch Translation providers: LibreTranslate, MyMemory, Google Translate

🛠️ Development Setup

# Clone and install in development mode
git clone https://github.com/neuraaak/ezqt-app.git
cd ezqt-app
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Verify CLI installation
ezqt --version
ezqt info

See the Development Guide for detailed instructions.

📦 Dependencies

Runtime

• PySide6>=6.7.3 – Qt for Python framework
• requests>=2.32.4 – HTTP requests (translation providers)
• click>=8.2.1 – CLI framework
• PyYAML>=6.0 – YAML configuration
• ruamel.yaml==0.18.6 – Advanced YAML processing

Development

• pytest>=7.0.0 – Testing framework
• pytest-cov>=4.0.0 – Coverage reporting
• black>=23.0.0 – Code formatting
• ruff>=0.1.0 – Linting
• mypy / pyright – Type checking

📄 License

MIT License – See LICENSE file for details.

🔗 Links

• Repository: https://github.com/neuraaak/ezqt-app
• Issues: GitHub Issues
• Documentation: neuraaak.github.io/ezqt-app
• PyPI: pypi.org/project/ezqt-app
• Changelog: CHANGELOG.md

---

EzQt App – Modern PySide6 application framework with hexagonal architecture. 🚀