README

Core Framework Documentation

Comprehensive reference for the core namespace
Last updated: 2026-01-21

Overview

core namespace là nền tảng của framework, cung cấp các building blocks cơ bản cho ứng dụng PySide6:

• Application Lifecycle: QtAppContext quản lý khởi động, feature flags, và shutdown
• Dependency Injection: ServiceLocator với global và scoped services
• Event System: Observer pattern (Publisher/Subscriber) cho decoupled communication
• UI Architecture: BaseController + WidgetManager + Handler pattern
• Task System: Background task execution với scheduling, chaining, persistence
• Utilities: Logging, Config, Exception handling, Path management

Quick Start

Minimal Application

from core import QtAppContext

# 1. Get global instance
ctx = QtAppContext.globalInstance()

# 2. Bootstrap application
ctx.bootstrap()

# 3. Access core services
config = ctx.config
publisher = ctx.publisher
logger = ctx.logger

# 4. Run Qt event loop
ctx.run()

Creating a Controller

from core import BaseController, BaseCtlHandler
from PySide6.QtWidgets import QWidget

class MyController(BaseController, QWidget):
    slot_map = {
        'buttonClicked': ['myButton', 'clicked']
    }
    
    def setupUi(self, widget):
        # UI setup here
        pass

class MyControllerHandler(BaseCtlHandler):
    def onButtonClicked(self):
        self.widgetManager.get('myButton').setText('Clicked!')

Architecture Overview

graph TB
    App[Application] --> QtAppContext
    QtAppContext --> ServiceLocator
    QtAppContext --> Config
    QtAppContext --> Publisher
    QtAppContext --> NetworkManager
    QtAppContext --> TaskManager
    
    BaseController --> WidgetManager
    BaseController --> Handler[BaseCtlHandler]
    Handler --> Publisher
    
    TaskManager --> TaskQueue
    TaskManager --> TaskTracker
    TaskManager --> TaskScheduler
    
    ServiceLocator --> GlobalServices[Global Services]
    ServiceLocator --> ScopedServices[Scoped Services]
    
    style QtAppContext fill:#e1f5ff
    style ServiceLocator fill:#fff4e1
    style Publisher fill:#e8f5e9
    style TaskManager fill:#f3e5f5

Loading

Documentation Structure

Core Components

1. Application Context - QtAppContext lifecycle management
2. Dependency Injection - ServiceLocator patterns
3. Observer Pattern - Publisher/Subscriber event system
4. Controller Architecture - BaseController và slot_map
5. Widget Management - WidgetManager utilities
6. Configuration - Config singleton
7. Logging - Loguru-based logging
8. Network Manager - Qt network integration
9. Exceptions - Exception handling
10. Utilities - PathHelper, OsHelper, PythonHelper, WidgetUtils
11. Decorators - @singleton, @catchExceptInMsgBox, etc.

Task System

12. Task System Overview - Architecture và components
13. AbstractTask - Base task class
14. Task Chain - Sequential task execution
15. Task Manager - TaskManagerService API

Advanced Features

16. Acknowledgment System - ACK/NACK protocol
17. Contracts - Interfaces
18. Extends - Extensions
19. Model - Data models

Practical Guides

20. Common Use Cases - Recipes và examples
21. Improvement Suggestions - Đề xuất cải tiến
22. Pixi Guide - Hướng dẫn sử dụng Pixi vs Pip
23. CLI Scripts - Hướng dẫn sử dụng scripts tiện ích
24. Testing - Hướng dẫn chạy test và viết test

Key Concepts

Feature Flags

Core sử dụng environment variables để enable/disable features:

# .env file
PSA_ENABLE_NETWORK=true   # Enable NetworkManager
PSA_ENABLE_TASKS=true     # Enable TaskSystem

Service Lifecycle

Global Services (Singletons):

• Config, Publisher, NetworkManager, TaskManager
• Tồn tại suốt application lifetime

Scoped Services (Task-specific):

• Browser instances, temporary resources
• Tự động cleanup khi task hoàn thành

ctx = QtAppContext.globalInstance()

# Global service
config = ctx.config

# Scoped service
taskId = self.uuid
browser = ChromeBrowserService()
ctx.registerScopedService(taskId, browser)
try:
    # Use browser
    pass
finally:
    ctx.releaseScope(taskId)  # Auto cleanup

Event-Driven Architecture

# Publisher
publisher = ctx.publisher
publisher.notify('user.login', userId=123)

# Subscriber
class MyHandler(Subscriber):
    def __init__(self):
        super().__init__(events=['user.login'])
    
    def onUserLogin(self, userId: int):
        print(f'User {userId} logged in')

Design Principles

1. Separation of Concerns: Controller chỉ wire UI, Handler xử lý logic
2. Dependency Injection: Sử dụng ServiceLocator thay vì direct instantiation
3. Event-Driven: Components communicate qua Publisher, không direct coupling
4. Thread-Safe: QMutex cho critical sections
5. Resource Management: Scoped services với auto cleanup

Common Patterns

Controller + Handler Pattern

# Controller: UI wiring only
class MyController(BaseController, QWidget):
    slot_map = {
        'saveClicked': ['saveButton', 'clicked']
    }

# Handler: Business logic
class MyControllerHandler(BaseCtlHandler):
    def onSaveClicked(self):
        data = self.widgetManager.get('dataInput').text()
        # Process data...

Background Task Pattern

from core.taskSystem import AbstractTask

class MyTask(AbstractTask):
    def handle(self):
        for i in range(100):
            if self.isStopped():
                return
            # Do work...
            self.setProgress(i)

# Add to queue
ctx.taskManager.addTask(MyTask(name='My Task'))

Scoped Resource Pattern

def executeTask(self):
    ctx = QtAppContext.globalInstance()
    taskId = self.uuid
    
    # Register scoped resources
    browser = ChromeBrowserService()
    ctx.registerScopedService(taskId, browser)
    
    try:
        # Use resources
        browser.navigate('https://example.com')
    finally:
        # Auto cleanup all scoped services
        ctx.releaseScope(taskId)

Migration from Old Docs

Nếu bạn đang sử dụng docs cũ (docs/provided-by-base/), lưu ý:

• ✅ Architecture mindset vẫn đúng: Separation of concerns, Observer pattern
• ⚠️ API details đã thay đổi: Tham khảo docs mới cho chính xác
• ⚠️ Feature flags mới: PSA_ENABLE_* environment variables
• ⚠️ ServiceLocator API: registerScopedService thay vì cách cũ

Getting Help

• API Reference: Xem các file documentation cụ thể
• Examples: Tham khảo 20-common-use-cases.md
• Source Code: core/ directory với docstrings chi tiết
• Issues: Báo cáo qua improvement suggestions

Next Steps

• Đọc Application Context để hiểu bootstrap process
• Đọc Controller Architecture để tạo UI components
• Đọc Task System Overview để làm background tasks
• Đọc Common Use Cases cho practical examples