Rozwiązywanie problemów
Na tej stronie znajdziesz rozwiązania najczęstszych problemów, które możesz napotkać podczas pracy z projektem Trass Recommendation.
Problemy z instalacją
ModuleNotFoundError: No module named 'PyQt6'
Problem: Po instalacji, przy próbie uruchomienia aplikacji pojawia się błąd związany z brakiem modułu PyQt6.
Rozwiązanie:
- Upewnij się, że masz aktywne środowisko wirtualne
- Zainstaluj ponownie PyQt6:
pip install PyQt6==6.6.1
- Jeśli używasz Windows, może być konieczne zainstalowanie dodatkowo:
pip install PyQt6-Qt6==6.6.1
pip install PyQt6-sip==13.6.0
Błąd przy instalacji PyQt6 na Linux
Problem: Podczas instalacji PyQt6 na systemie Linux pojawiają się błędy kompilacji.
Rozwiązanie:
- Zainstaluj wymagane pakiety systemowe:
# Ubuntu/Debian
sudo apt-get install python3-dev libxcb-xinerama0 libxcb-xinerama0-dev libxkbcommon-x11-0 libxkbcommon-dev
# Fedora
sudo dnf install python3-devel libxkbcommon-x11 libxkbcommon-devel
- Spróbuj ponownie zainstalować PyQt6
Niekompatybilna wersja Node.js lub pnpm
Problem: Podczas instalacji lub uruchamiania pojawia się błąd związany z wersją Node.js lub pnpm.
Rozwiązanie:
- Sprawdź wymagane wersje:
node -v # Powinno być 20.0.0 lub nowsze
pnpm -v # Powinno być 9.12.3 lub nowsze
- Zaktualizuj Node.js za pomocą NVM:
# Instalacja NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Instalacja i użycie wymaganej wersji
nvm install 20
nvm use 20
- Zaktualizuj pnpm:
npm install -g pnpm@latest
Problemy z uruchamianiem
Aplikacja uruchamia się, ale nie wyświetla interfejsu
Problem: Aplikacja uruchamia się bez błędów, ale nie pojawia się okno interfejsu.
Rozwiązanie:
- Sprawdź, czy nie występują błędy w konsoli
- Upewnij się, że używasz właściwej wersji PyQt6
- Na systemach Unix-like sprawdź, czy masz poprawnie skonfigurowany serwer X11:
echo $DISPLAY
# Powinno zwrócić np. :0
Błędy podczas importowania modułów
Problem: Podczas uruchamiania aplikacji pojawiają się błędy importu.
Rozwiązanie:
- Upewnij się, że zainstalowałeś pakiet w trybie edycyjnym:
pip install -e .
- Sprawdź strukturę projektu i poprawność importów
- Upewnij się, że uruchamiasz aplikację z głównego katalogu projektu
Problemy z PYTHONPATH przy budowaniu EXE
Problem: Podczas budowania pliku EXE pojawiają się błędy związane z importem modułów z pakietu src
.
Rozwiązanie:
- Dodaj katalog główny projektu do zmiennej środowiskowej PYTHONPATH:
# Windows (PowerShell)
$env:PYTHONPATH = $env:PYTHONPATH + ";C:\ścieżka\do\projektu"
# Windows (CMD)
set PYTHONPATH=%PYTHONPATH%;C:\ścieżka\do\projektu
# Linux/MacOS
export PYTHONPATH=$PYTHONPATH:/ścieżka/do/projektu
- Upewnij się, że pakiet jest poprawnie skonfigurowany w pliku
setup.py
:
setup(
# ...
packages=find_packages(include=["src", "src.*"]),
include_package_data=True,
# ...
)
- Po wprowadzeniu zmian w
setup.py
, przeinstaluj pakiet w trybie edycyjnym:
pip install -e . --no-warn-script-location
Problemy z wydajnością
Aplikacja działa wolno
Problem: Interfejs aplikacji reaguje z opóźnieniem lub przetwarza dane zbyt wolno.
Rozwiązanie:
- Sprawdź obciążenie systemu podczas działania aplikacji
- Zoptymalizuj algorytmy przetwarzania danych
- Rozważ użycie wielowątkowości dla ciężkich operacji:
from PyQt6.QtCore import QThread, pyqtSignal
class WorkerThread(QThread):
finished = pyqtSignal(object)
def __init__(self, function, *args, **kwargs):
super().__init__()
self.function = function
self.args = args
self.kwargs = kwargs
def run(self):
result = self.function(*self.args, **self.kwargs)
self.finished.emit(result)
Problemy z testami
Testy nie znajdują modułów
Problem: Podczas uruchamiania testów pojawiają się błędy importu modułów.
Rozwiązanie:
- Upewnij się, że zainstalowałeś pakiet w trybie edycyjnym
- Sprawdź, czy struktura importów w testach jest poprawna
- Dodaj katalog główny projektu do
PYTHONPATH
:
# Windows
set PYTHONPATH=.
# Linux/MacOS
export PYTHONPATH=.
Testy UI się nie uruchamiają
Problem: Testy interfejsu użytkownika nie uruchamiają się lub kończą się błędami.
Rozwiązanie:
- Upewnij się, że masz zainstalowany pakiet
pytest-qt
:
pip install pytest-qt
- Na systemach bez interfejsu graficznego, użyj wirtualnego serwera X:
# Instalacja na Ubuntu/Debian
sudo apt-get install xvfb
# Uruchamianie testów
xvfb-run pytest tests/test_ui/
Problemy z dokumentacją
Błędy przy uruchamianiu dokumentacji VitePress
Problem: Podczas uruchamiania lub budowania dokumentacji VitePress występują błędy.
Rozwiązanie:
- Upewnij się, że masz zainstalowane wymagane pakiety:
pnpm install
- Sprawdź, czy używasz wymaganej wersji Node.js i pnpm:
node -v # Powinno być 20.0.0 lub nowsze
pnpm -v # Powinno być 9.12.3 lub nowsze
- Wyczyść pamięć podręczną i zainstaluj ponownie zależności:
pnpm cache clean
rm -rf node_modules
pnpm install
Błędy związane z TypeScript
Problem: Występują błędy kompilacji TypeScript podczas uruchamiania lub budowania dokumentacji.
Rozwiązanie:
- Sprawdź, czy pliki TypeScript mają poprawną składnię:
pnpm exec tsc --noEmit
- Upewnij się, że masz prawidłowo skonfigurowane pliki tsconfig.json
- Sprawdź, czy zależności TypeScript są zainstalowane:
pnpm install typescript@5.3.3 @types/node@20.11.5
- Jeśli problem dotyczy konkretnego importu, sprawdź czy masz zainstalowany odpowiedni pakiet @types
Problemy z hot-reloadingiem dokumentacji
Problem: Zmiany w plikach dokumentacji nie są automatycznie odświeżane w przeglądarce.
Rozwiązanie:
- Upewnij się, że serwer deweloperski działa poprawnie
- Spróbuj ponownie uruchomić serwer:
pnpm docs:dev
- Sprawdź, czy twoja przeglądarka nie blokuje websocket używanego do hot-reloadingu
- Sprawdź, czy w systemie nie ma oprogramowania blokującego komunikację na portach używanych przez VitePress (domyślnie 5173)
Problemy z danymi
Aplikacja nie może załadować danych
Problem: Aplikacja wyświetla błędy związane z ładowaniem lub brakiem danych.
Rozwiązanie:
- Sprawdź, czy pliki danych istnieją w oczekiwanej lokalizacji
- Upewnij się, że format danych jest poprawny
- Dodaj obsługę błędów w kodzie, aby zapewnić bardziej informacyjne komunikaty:
try:
data = load_data(path)
except FileNotFoundError:
print(f"Nie znaleziono pliku danych: {path}")
# Utwórz dane domyślne lub poproś użytkownika o podanie ścieżki
except ValueError as e:
print(f"Nieprawidłowy format danych: {e}")
# Obsłuż błędny format
Kontakt i zgłaszanie problemów
Jeśli napotkałeś problem, który nie został opisany w tej sekcji:
- Sprawdź istniejące zgłoszenia problemów w repozytorium projektu
- Utwórz nowe zgłoszenie, zawierające:
- Dokładny opis problemu
- Kroki umożliwiające odtworzenie problemu
- Logi i komunikaty błędów
- Informacje o środowisku (system operacyjny, wersja Python, Node.js, pnpm, itp.)
- Skontaktuj się z zespołem wsparcia