Skip to content

EzQt-App

PyPI version Python versions PyPI status License CI Docs uv linter type checker

EzQt-App logo

EzQt-App is a PySide6 framework to bootstrap and structure desktop applications with a ready-to-use shell, configuration workflow, translation support, and reusable UI components.

🚀 Quick start

uv add ezqt-app

pip install ezqt-app

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

Minimal application:

import sys
from ezqt_app import EzApplication, EzQt_App, init

init()
app = EzApplication(sys.argv)
window = EzQt_App()
window.show()
sys.exit(app.exec())

✨ Key features

  • Application bootstrap: init, assets generation, and project setup workflows
  • Modular services: config, settings, runtime, translation, and UI service layers
  • Hexagonal architecture: domain contracts with services adapters and explicit boundaries
  • Translation stack: .ts loading + on-the-fly .qm compilation, EzTranslator Qt interceptor, non-blocking auto-translation with in-app progress indicator
  • Built-in CLI: ezqt commands for init, tests, docs, and utility workflows
  • Test scopes: unit, integration, and robustness test suites

📚 Documentation

Section Description
Getting Started Installation, bootstrap, and first app
User Guides Development, testing, and styling guidance
API Reference Service- and architecture-oriented API documentation
CLI Reference Command-line utilities and command options
Examples Practical usage snippets for common scenarios
Concepts Architecture rationale and design decisions

🎯 Main components

EzQt-App is organized around architectural modules:

Domain module

  • domain/ports — service contracts (protocols)
  • domain/models — typed domain models and constants
  • domain/results — typed initialization/result payloads

Services module

  • services/bootstrap — initialization sequence and options
  • services/config — configuration load/save/path resolution
  • services/settings — mutable app/gui settings state
  • services/translation — language manager, helpers, auto-translation
  • services/ui — UI orchestration services (theme/menu/panel/window)

Widgets module

  • widgets/core — application containers (EzApplication, SettingsPanel, etc.)
  • widgets/extended — extended reusable controls

For detailed documentation, see API Reference.

🧪 Testing

Metric Value
Test types Unit, Integration, Robustness
Runner tests/run_tests.py
Output mode Real-time streamed output 
python tests/run_tests.py --type unit
python tests/run_tests.py --type integration
python tests/run_tests.py --type robustness

See the Testing Guide for complete details.

📋 Requirements

  • Python >= 3.11
  • PySide6 >= 6.7.3
  • PyYAML / ruamel.yaml — configuration management

⚖️ License

MIT License — see LICENSE for details.