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

Contributing changes

See Contributing for how to propose a change.