Refactoring Import Guide¶

During the refactor: All refactored files must use imports exclusively from src/

Core Rule¶

When refactoring a file or module into the new src/ structure, that file must only use imports from the refactored src/ directory. Do not import from legacy locations like SharedServices/, QssHandler/, or other old module paths.

This ensures: - Clean separation between old and new code - No circular dependencies during migration - Ability to eventually remove legacy folders entirely - Consistent, predictable import patterns

Required Import Sources¶

All refactored files must import shared services from these locations:

Logging¶

# Correct - import locally where needed
from src.shared_services.logging.logger_factory import get_logger

logger = get_logger(__name__)

Path Management¶

from src.shared_services.constants.paths import Logging, Icons
from src.shared_services.path_management.api import get_path, get_path_str

# get_path() returns pathlib.Path, get_path_str() returns str (for Qt APIs)
log_dir = get_path(Logging.Directory)
icon_path = get_path_str(Icons.Logos.GitHub)

Icons and Rendering¶

from src.shared_services.rendering.icons.api import Icons, IconColors, IconRegistry

# Primary API: Register icons on widgets (theme-aware, auto-updates on theme change)
registry = IconRegistry.instance()
registry.register(my_button, Icons.Action.Info, color=IconColors.Primary)

# Low-level API: render_svg() for non-widget contexts (does NOT auto-update on theme change)
from src.shared_services.rendering.icons.api import render_svg
pixmap = render_svg(Icons.Action.Info, size=24)

Stylesheets¶

from src.shared_services.rendering.stylesheets.api import StylesheetManager

# Register widgets with stylesheet paths for theme-aware styling
manager = StylesheetManager.instance()
manager.register(my_widget, [SomeModule.Paths.Stylesheet])

Documents (HTML Views)¶

from src.shared_services.rendering.documents.api import create_html_view, render_html

# Create a themed HTML view widget
view = create_html_view(parent=self, object_name="myHtmlView")
render_html(view, "<h1>Hello</h1>")

Prompt Dialogs (Message Boxes)¶

# Convenience functions for common dialogs
from src.shared_services.prompt_dialogs.api import (
    show_info,
    show_warning,
    show_error,
    ask_question,
)

# Dialog classes for advanced use
from src.shared_services.prompt_dialogs.api import (
    ConfirmationDialog,
    InputDialog,
    LoadingDialog,
    LoadingSpinner,
)

File Operations¶

from src.shared_services.file_operations.api import (
    save_json,
    load_json,
    save_text,
    load_text,
    save_msgpack,
    load_msgpack,
)

Application State¶

from src.shared_services.state.app_state import AppState

state = AppState.instance()

Security¶

from src.shared_services.security.login_manager import LoginManager
from src.shared_services.security.oauth.authentication_manager import AuthenticationManager

Settings¶

from src.shared_services.settings.settings_manager import SettingsManager

Forbidden Imports in Refactored Files¶

Do NOT use these legacy import paths in any file under src/:

Import Migration Table¶

Old Import	New Import
`SharedServices.DebugLogging.logger_factory`	`src.shared_services.logging.logger_factory`
`SharedServices.Helpers.RessourceHandling.path_helper`	`src.shared_services.path_management.api`
`SharedServices.Helpers.RessourceHandling.ressource_path_helper`	`src.shared_services.path_management.api`
`SharedServices.MessageBoxes.m_message_boxes`	`src.shared_services.prompt_dialogs.api`
`SharedServices.MessageBoxes.loading_dialog.loading_dialogs`	`src.shared_services.prompt_dialogs.api`
`SharedServices.MessageBoxes.input_dialog.delete_dialog`	`src.shared_services.prompt_dialogs.api`
`QssHandler.load_qss`	`src.shared_services.rendering.stylesheets.api` (StylesheetManager)
`QssHandler.icon_manager`	`src.shared_services.rendering.icons.api` (IconRegistry)
Raw `json.load/dump` for app files	`src.shared_services.file_operations.api` (save_json, load_json)

Checklist Before Completing a File Refactor¶

Before considering a file fully refactored, verify:

[ ] File is located under src/
[ ] All imports use src. prefix (for shared services)
[ ] No imports from SharedServices/
[ ] No imports from QssHandler/
[ ] No imports from other legacy top-level modules
[ ] Logger is imported locally (not globally) using src.shared_services.logging.logger_factory
[ ] Icons use IconRegistry.register() from src.shared_services.rendering.icons.api for theme-aware icons
[ ] Message boxes use show_info(), show_warning(), show_error() from src.shared_services.prompt_dialogs.api
[ ] File I/O uses save_json(), load_json() etc. from src.shared_services.file_operations.api
[ ] Paths use PathDef constants from src.shared_services.constants.paths with get_path() / get_path_str()

Handling Dependencies on Non-Refactored Modules¶

If a refactored file needs functionality that has not yet been migrated to src/:

Prioritize migrating the dependency first - If feasible, migrate the required module before proceeding
Create a minimal interface - If full migration is not possible, create a thin wrapper in src/ that can later be replaced
Document the technical debt - Add a TODO comment noting the temporary dependency

# TODO: Remove after migrating SomeOldModule to src/
# Temporary bridge - this import will be replaced
from old_location import SomeOldClass

Why This Matters¶

Clean Migration Path: By enforcing src/-only imports, we can track migration progress and eventually remove legacy folders
No Circular Dependencies: Old modules may still import from old locations; new modules import only from new locations
Consistency: All new/refactored code follows the same patterns
Testability: Modules with clean imports are easier to test in isolation

Version: 1.1 Last Updated: 2026-02-06 Related Docs: docs/dev_docs/refactoring/shared_services_plan/