Developer Tools

For those of you interested in extending osxphotos, using osxphotos to build your own tools, or just wanting to dig deeper into the Photos database, I've added some simple but useful tools I've been using to help develop osxphotos to the osxphotos CLI. The following commands are things I found useful as I work on adding new features or debugging osxphotos:

• osxphotos repl
• osxphotos uuid
• osxphotos snap
• osxphotos diff
• osxphotos grep
• osxphotos install
• osxphotos uninstall

Some of these are hidden commands and can be viewed using the command:

OSXPHOTOS_SHOW_HIDDEN=1 osxphotos help

repl

The repl (read-eval-print loop) command has been part of osxphotos since v0.42.41. It loads the Photos database then opens an interactive python REPL that allows you to easily explore the underlying data or quickly prototype code. The osxphotos repl uses ptpython to provide an interactive experience and includes objexplorer to allow you to interactively explore the osxphotos data structures.

Try launching the repl with a photo selected in Photos then try explore(selected[0])

uuid

This is a simple command that simply prints out the unique ID (UUID) which Photos uses to identify each asset in the library. To use this command, select one or more photos in Photos then type osxphotos uuid. You can use the -f flag to also print out the filename in a format usable by the --uuid-from-file and --skip-uuid-from-file options.

$ osxphotos uuid
7783E8E6-9CAC-40F3-BE22-81FB7051C266
$ osxphotos uuid -f
# IMG_3092.heic
7783E8E6-9CAC-40F3-BE22-81FB7051C266

snap, diff

osxphotos snap creates a snapshot copy of the Photos database. It copies only the database files, not the entire library. When combined with osxphotos diff, which does a diff of the current database to the most recent snapshot, this is a very useful tool for understanding how Photos stores data in the library. For example:

Make a change (rename a photo), then:

grep

Search all columns in all tables in a Photos database to find a value. This is useful for understanding where Photos stores specific information. For example, change a photo title to "Palm Tree" then:

[I] ➜ osxphotos grep "Palm Tree"
Using last opened Photos library: /Users/rhet/Pictures/Test-10.15.7.photoslibrary
ZADDITIONALASSETATTRIBUTES, ZTITLE, 26, Palm Tree

install / uninstall

The final two commands install or uninstall python packages into the same virtual environment that osxphotos is running in. These are primarily used for developing plugins when you've installed osxphotos via pipx which is the recommended approach. pipx handles creating a virtual environment for you but if you are developing a custom plugin function to use with the --query-function, --post-function or {function} template, and you need to install an external dependency, you'll need to inject those dependencies into the virtual environment set up by pipx. You can use pipx inject for this but many people don't know about that feature so I added the ability for osxphotos to do this itself.