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
• osxphotos exportdb

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

These 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.

exportdb

Provides utilities for working with or doing maintenance on the sqlite export database used osxphotos for maintaining state information for --update and --force-update. By default, the export database is located in /path/to/export/.osxphotos_export.db though this can be changed with the --exportdb option.

$ osxphotos help exportdb
Usage: osxphotos exportdb [OPTIONS] EXPORT_DATABASE

  Utilities for working with the osxphotos export database

Options:
  --version                  Print export database version and exit.
  --vacuum                   Run VACUUM to defragment the database.
  --check-signatures         Check signatures for all exported photos in the
                             database to find signatures that don't match.
  --update-signatures        Update signatures for all exported photos in the
                             database to match on-disk signatures.
  --touch-file               Touch files on disk to match created date in
                             Photos library and update export database
                             signatures
  --last-run                 Show last run osxphotos commands used with this
                             database.
  --save-config CONFIG_FILE  Save last run configuration to TOML file for use
                             by --load-config.
  --info FILE_PATH           Print information about FILE_PATH contained in
                             the database.
  --migrate                  Migrate (if needed) export database to current
                             version.
  --export-dir DIRECTORY     Optional path to export directory (if not parent
                             of export database).
  -V, --verbose              Print verbose output.
  --dry-run                  Run in dry-run mode (don't actually update
                             files), e.g. for use with --update-signatures.
  -h, --help                 Show this message and exit.