feat: optional photos.filename_format: simple (boredazfcuk migration support)

[epheterson]

Summary

Enables zero-redownload migration from boredazfcuk/docker-icloudpd by
producing the same plain IMG_1234.HEIC filenames that boredazfcuk
writes. Since check_photo_exists compares by file size (not filename
suffix), an existing tree of boredazfcuk-format files is correctly
recognised as already-present when this container points at it.

Also includes a collision-safe fallback: when simple format would put
two distinct iCloud photos at the same path (rare but happens when the
same human filename appears on multiple photos), the colliding photo
routes to the metadata-suffix path so both files coexist on disk.

Features

photos.filename_format (new optional config, default metadata)

• metadata (default): name__filesize__base64id.extension — historical
  mandarons format. Backward-compatible, no behaviour change for existing
  users.
• simple: name.extension — boredazfcuk/Apple convention.

Collision fallback (active automatically when filename_format is simple)

In collect_download_task, when the plain simple-format path already
exists and the existing file has a DIFFERENT size from the current photo's
CloudKit versions[file_size].size, the colliding photo's destination is
switched to the metadata-suffix form. First photo keeps its plain name;
subsequent colliders get unique suffixes. Cross-sync stable.

Implementation

• Module-level _DEFAULT_FILENAME_FORMAT in photo_path_utils.py set
  once per sync run by sync_photos.sync_photos() via the new
  set_default_filename_format() setter. Avoids threading filename_format
  through every collect_download_task / generate_photo_path signature
  call.
• generate_photo_filename_with_metadata branches on the format.
• Collision detection in collect_download_task uses os.path.isfile
  • the check_photo_exists size comparison.

Tests

20 new tests total:

• tests/test_filename_format.py (15 tests): config helper defaults /
  normalisation / fallback on unknown value, generator branching, the
  module-default singleton, end-to-end via generate_photo_path.
• tests/test_collision_fallback.py (5 tests): no collision uses plain
  path, same photo re-sync skips, collision falls back to suffix (with
  the first file untouched), collision + suffix already downloaded skips,
  metadata mode bypasses the collision logic entirely.

Notes

• filename_format cannot be safely changed mid-flight on an existing
  install — switching means mandarons won't match previously-downloaded
  files and will re-download. Documented in the config helper docstring.
• Simple-format collect_download_task recompiles the suffix path with
  explicit filename_format="metadata" so the fallback works regardless
  of the module-level default.

[Copilot]

Pull request overview

Adds an optional photos.filename_format config (metadata default vs simple) that lets users migrate from boredazfcuk/docker-icloudpd's plain IMG_1234.HEIC naming without re-downloading, with a fallback that routes filename-collisions in simple mode to the existing metadata-suffix path.

Changes:

• New get_photos_filename_format() config helper and a module-level _DEFAULT_FILENAME_FORMAT state in photo_path_utils.py set once per sync run.
• generate_photo_filename_with_metadata() branches on format; collect_download_task() adds a collision fallback that switches to the metadata-suffix filename when the plain path is occupied by a different photo (size mismatch).
• 20 new tests covering the config helper, generator branching, end-to-end path generation, and the collision fallback scenarios.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/config_parser.py	Adds get_photos_filename_format() returning "metadata"/"simple" with normalization and fallback.
src/photo_path_utils.py	Introduces _DEFAULT_FILENAME_FORMAT and set_default_filename_format(); generate_photo_filename_with_metadata now branches by format.
src/photo_download_manager.py	In collect_download_task, reorders the files set update around check_photo_exists and adds the simple-mode collision fallback to the suffix path.
src/sync_photos.py	Calls set_default_filename_format() at sync start with the configured value.
tests/test_filename_format.py	Covers config helper, generator branching, module-default behavior, and end-to-end generate_photo_path.
tests/test_collision_fallback.py	Covers no-collision, same-photo resync, collision-to-suffix, suffix-already-downloaded, and metadata-mode bypass.

[olfway]

I guess everyone have different preferences about filenames, so maybe we can make them configurable?

Simple one like this:

file_format: "${photo.filename}__${photo.id}__.${photo.ext}"

or something more advanced like:

file_formats:
  original: "${photo.year}.${photo.month}.${photo.day} ${photo.filename}.${photo.ext}"
  original_alt: "${photo.year}.${photo.month}.${photo.day} ${photo.filename}.bak"

@epheterson what do you think?

[epheterson]

Hey @olfway, good point I was trying to match the file structure from iCloudPD to avoid re-downloading but we can do that while making it more flexible. I also favor the simple map for all types over defining per type. I think this commit is an elegant way to do it, take a look and let me know what you think.