Repository Guidelines

Project Structure & Modules

• opentiler/: Core app (Qt/PySide6 GUI, dialogs, exporter, settings, utils, viewer). Assets in opentiler/assets/.
• main.py: CLI/GUI entry; calls opentiler.main_app.main().
• tests/: Pytest suite (unit, plugins, integration). Uses markers: gui, integration, slow.
• plugins/: Plugin system (manager, hooks, builtins) and plugin docs.
• docs/: User/dev docs and images. See docs/developer/DEVELOPER_MANUAL.md.
• tools/: Utilities (screen capture, validation helpers).
• Other: requirements*.txt, setup.py, BUILD_INSTRUCTIONS.md.

Build, Test, Run

• Install dev deps: pip install -r requirements-dev.txt (optional features via requirements-optional.txt).
• Editable install: pip install -e . (adds opentiler / opentiler-gui).
• Run app locally: python main.py or opentiler.
• Test fast: pytest -q.
• Test with markers: pytest -m "not slow", pytest -m gui.
• Coverage: pytest --cov=opentiler --cov-report=term-missing.
• Build dist: python -m build or python setup.py sdist bdist_wheel (see BUILD_INSTRUCTIONS.md).

Coding Style & Naming

• Python 3.10+; 4-space indent; PEP 8.
• Format: black .; Imports: isort .; Lint: flake8; Types: mypy opentiler.
• Names: modules/functions snake_case, classes CamelCase, constants UPPER_SNAKE.
• UI resources live under opentiler/assets/.

Testing Guidelines

• Framework: pytest; files tests/test_*.py; classes start with Test*; test funcs test_*.
• GUI tests set QT_QPA_PLATFORM=offscreen (handled in conftest.py).
• Use markers (gui, integration, slow) and fixtures (qapp, temp_dir, mock_main_window).
• Aim for meaningful unit tests around utils, exporters, and plugins; add integration tests for workflows.

Commit & Pull Requests

• Commit style: short imperative subject with component scope, e.g. print: set first-page orientation or fix(preview): import QSize.
• Include why when relevant; group related changes; keep diffs focused.
• PRs: clear description, linked issues (e.g., Closes #123), steps to test, screenshots/GIFs for UI changes, and notes on risks/rollout.
• CI hygiene: pass lint/format/type/tests locally before opening PR.

Security & Configuration

• Optional features: CAD (ezdxf), RAW (rawpy, numpy), automation (mss, pywinctl). Install only as needed.
• Avoid committing large binaries; place assets under opentiler/assets/.