Repository Guidelines

Project Structure & Module Organization

navipy.py boots the PySide6 desktop client, wires logging, and discovers modules under src/.
src/api/ holds the Subsonic client, auth helpers, and data models that talk to your Navidrome server.
src/accessibility/ and src/widgets/ contain custom Qt widgets and dialogs with accessibility metadata; src/main_window.py composes them.
src/config/settings.py manages XDG-compliant config/data/cache dirs and persists settings.json and servers.json.
sounds/ ships UI audio assets; runtime logs land in ~/.local/share/navipy/navipy.log.

python3 -m venv .venv && source .venv/bin/activate — set up an isolated environment.
pip install -r requirements.txt — install PySide6 and other runtime deps.
python3 navipy.py — launch the app with logging to the data dir; exit cleanly with Ctrl+C.
pytest -q — run the automated test suite; run this after major code changes.

Follow PEP 8: 4-space indentation, snake_case modules/functions, and descriptive class names for Qt widgets/actions.
Keep accessibility in mind: set setAccessibleName on interactive widgets, and keep shortcuts consistent with existing ones in MainWindow.
Prefer type hints for public APIs in api/ and configuration helpers; keep JSON keys predictable and lowercase.

Automated pytest suite lives under tests/; keep new tests named test_<feature>.py and prefer fixtures/fakes over live Navidrome.
Run pytest -q after major code changes; set QT_QPA_PLATFORM=offscreen if adding Qt-dependent tests.
Manual checks still matter: verify keyboard-only navigation, high-DPI rendering, and that logs/config are written under the XDG directories.

Write imperative, scoped commit subjects (e.g., "Add server dialog validation"), keep to ~72 chars, and describe user-facing impact in the body when needed.
PRs should list the change summary, test results or manual checks, linked issues, and UI screenshots/GIFs for visible tweaks.
Call out accessibility-affecting changes, config migrations, or new dependencies so reviewers can double-check regressions.

Never log server credentials; servers.json under ~/.config/navipy/ stores secrets—treat it as sensitive and avoid committing it.
Respect XDG_* overrides in tests and scripts to avoid polluting real user data; prefer temporary dirs when experimenting.
Keep error messages informative but redacted; sanitize Navidrome responses before logging.