Potential PR's: Save Favorite as selectable rating in Exif AND a plugin system with example Immich integration

[spmp]

Kia ora/Good day Team icloudpd,
I have been having some fun in your codebase on a few changes and want to discuss here before throwing PR's at you out of the blue. Apologies for my write first and PR later, I was excited and Claude code just fuelled that fire.

I have two changes - and maybe a bug fix

Metadata management

(From PR #1301 )
"As a iPhotos user I often favorite my photos days after I take them, yet sync my photos daily so need to be able to update the favorite status post downloading. Favoriting is an important piece of metadata and should be included in files where possible for completeness"

"As a user I make changes to both EXIF and XMP metadata and need to ensure that syncing Favorites and other metadata from icloudpd will not overwrite the metadata changes I have made"
Add user facing CLI options:

• --favorite-to-rating: Specify how isFavorite is expressed in the EXIF and XMP rating tag,
• --process-existing-favorites : Whether to process favorites on existing downloads, best if used in combination with --until-found using a sensible window which accounts for the number of photos between taking and rating
• --metadata-overwrite: Whether to overwrite existing metadata or not. Defaults to not overwriting metadata. For example if I use --favorite-to-rating 1 and update the rating to 3 (I really like the photo), then a following run with --process-existing-favorites will not overwrite it. Wheras if the rating is unset then it is safe to set.

I have combined the xmp_sidecar.py and exif_datetime.py functionality (and tests) into metadata_management.py (and associated test_metadata_management.py to keep the metadata concerns together (XMP and EXIF are just i/o implementations of the same thing essentially), and cleaned up some of the calling logic in base.py, moving it into metadata_management.py to keep the concerns more distinct.

Plugin framework

See PR: #1302
"As an Ai enabled power user I want to be able to write custom hooks at various stages during the download process, with the context available to icloudpd to support various functions such as adding assets to my favorite media management system."

"As an Ai enabled power user and open source believer I want my changes to be available to the world to use and to be able to maintain my code as a non invasive addition to icloudpd or as a standalone project`

I have added a plugin system to icloudpd with hooks at various points in basy.py, together with a fully working Immich integration plugin.
I played around with different ways of registering the plugins and thought it is still simplest to keep it/them in the codebase under a separate directory (./plugins) as all other ways created dependency hell especially when releasing as Docker images (which is how I use icloudpd).
I have made changes to the testing to include coverage in the plugins directory and done my best to have high coverage for the plugins.
Multiple plugins can be used at once.

The included Immich plugin stacks, favorites, associates further live photos, and adds media to albums. It can process existing images, and adjust favorites after the fact for already downloaded media.

I have linted/formatted the code using the tools provided (thank you), and have instructed my master coder Claude Code to use TDD, so there are a ton of tests. Most tests pass (some failed before I began so am hoping this is a my-machine vs yours).

The plugin infra is a big change which really supported the use case I was looking for without having to have a janky fork of your project with my edits inside it. I am in no way married to the implementation, it was important for me to get the functionality out before the obsessive streak ruined my life. I can talk to some decisions (as architect) and maybe not others (as project-manager, not coder). I hope this is can be a positive contribution to your project, and looking forward to discussing and hopefully merging soon!

I have done my best with documentation, but unsure at what level to document the plugin infra and Immich plugin in the docs/plugin.md. Feedback and advice please!

Nga mihi/chur