Development
Setup
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt -r requirements-ui.txt
Use .venv/bin/python for everything below. The system python3 has no Pillow. The code targets
Python 3.9, and CI runs 3.9, 3.11, 3.13 and 3.14 on macOS.
Repository layout
bin/ entry points: photo-offloader-import, -dashboard, -app, -menubar, -google-sync, -usb-backup
photo_offloader/
config every path and setting
importer the import command line
card media types, card scanning, card manifest
media_info EXIF and ExifTool, camera model, archive folder
transfer copy decisions, copying a card, USB backup
run_report what a run did with each file: its summary, saved report and debug package
catalog SQLite catalog, history, upload records
catalog_refresh, fileops, jsonfile, volumes, progress, logs
google_photos, usb_backup
dashboard/ core (state and actions), display (wording and cards), paths, server, launcher, web/index.html
menubar/ model, app
scripts/ trigger.sh (launchd), import_supervisor.sh, service.sh (start, stop, status)
tools/ benchmark and one-off migration scripts
tests/ the unittest suite; browser/ runs the dashboard page in Chromium
docs/ these pages, which GitHub Pages also publishes as the project website
index.html the website's landing page, which is not the dashboard page
_config.yml, _layouts/, assets/ the website's settings, page layout and styles
install.sh installs the same layout into ~/Library/Application Support/PhotoOffloader
macos/ launcher.c, AppIcon.png (drawn by draw_icon.py) and build_app.sh, which install.sh uses to build the two app bundles
Running the tests
tools/test.sh fast # about 35 s, without the slowest modules
tools/test.sh full # everything, about 2.5 min, as CI runs it
.venv/bin/python -m unittest tests.test_usb_backup # one module
.venv/bin/python -m ruff format . # format; CI fails on unformatted code
.venv/bin/python -m ruff check . # lint; maximum complexity is 15
bash -n install.sh uninstall.sh scripts/*.sh tools/*.sh
macOS ships bash 3.2, so write ${arr[@]+"${arr[@]}"} for an array that may be empty under set -u.
Coverage
.venv/bin/python -m coverage run -m unittest discover
.venv/bin/python -m coverage combine # merges the data from test subprocesses
.venv/bin/python -m coverage report # add -m to list the missed lines
.venv/bin/python -m coverage html # browsable report in htmlcov/
The Coverage workflow runs the same steps, shows the table in the run’s summary, keeps the HTML
report as an artifact, and fails below
fail_under in .coveragerc. Raise that number when you add tests. The number measures Python
only: the shell scripts and the JavaScript in web/index.html are tested but not counted, and
menubar/app.py is excluded because no test imports it.
The dashboard page
The browser tests need one extra download. Without it they skip, and the rest of the suite still runs.
.venv/bin/python -m playwright install chromium
.venv/bin/python -m unittest tests.browser.test_dashboard_page
To look at the page in every state, in light, dark and narrow, save screenshots to a folder:
PHOTO_OFFLOADER_TEST_SCREENSHOTS=/tmp/dashboard-shots \
.venv/bin/python -m unittest tests.browser.test_dashboard_page.TestScreenshots
A new page state gets a scenario in tests/browser/harness.py.
Rules
Tests never touch a real install. This project is often developed on a Mac where the app is
installed and running. Tests must not change the real install or data folders, start the real Google
sync or write the real status.json. Use tests/support.isolate_config(self, tmp), which refuses to
run if config gains a path it doesn’t cover. After changing fixtures, check nothing real changed:
touch m; .venv/bin/python -m unittest discover
find ~/Library/Application\ Support/PhotoOffloader* -type f -newer m ! -name '*-wal' ! -name '*-shm'
No output means no real file changed. The running service changes folder timestamps and the catalog’s
-wal and -shm files, so the check leaves those out.
A source checkout uses the real data. Only code paths follow the checkout. Archives, the catalog and
status.json always resolve to the real locations, so running bin/ programs from the repository acts
on the live install. tests/browser/harness.py runs the page against a sandbox.
Shell scripts can’t see config.py. They repeat its paths and accept PHOTO_OFFLOADER_* overrides, so
isolate_config doesn’t protect them. Tests pass those variables instead (see tests/test_trigger.py). If
a path changes, update both sides. trigger.sh reads backup_drive from settings.txt itself, the way
photo_offloader/settings.py does, so a change to that file’s format needs both too.
Don’t run install.sh or uninstall.sh to test a change. They re-register your real LaunchAgents. To
check the installed layout, copy bin scripts photo_offloader VERSION to a temp folder and run the
launchers from there.
Keep the safety invariants in How it works. The catalog and card manifest are caches, and the trigger and importer locks overlap on purpose.
No new required runtime dependencies without discussion. The dashboard is deliberately the standard
library plus one static page, and it builds the page with textContent, so text from a card never reaches
innerHTML.
Code conventions
- Code reads
config.NAMEat call time, neverfrom config import NAME. - Modules call each other qualified (
catalog.catalog_row(...)), imports only point downward, and tests patch a name in the module that owns it. install.shcopiesbin/,scripts/andphoto_offloader/. New top-level files must be added there.
Contributing changes
See Contributing for how to propose a change.