Release v0.60.4 (#1095)

* Updated tested OS versions

* Version bump

* Release v0.60.4

.all-contributorsrc

@@ -262,7 +262,8 @@
         "bug",
         "ideas",
         "test",
-        "code"
+        "code",
+        "doc"
       ]
     },
     {
@@ -464,8 +465,132 @@
       "contributions": [
         "doc"
       ]
+    },
+    {
+      "login": "djbeadle",
+      "name": "Daniel Beadle",
+      "avatar_url": "https://avatars.githubusercontent.com/u/6235378?v=4",
+      "profile": "https://danielbeadle.net",
+      "contributions": [
+        "ideas"
+      ]
+    },
+    {
+      "login": "eecue",
+      "name": "Dave Bullock",
+      "avatar_url": "https://avatars.githubusercontent.com/u/532536?v=4",
+      "profile": "http://eecue.com/",
+      "contributions": [
+        "ideas",
+        "userTesting",
+        "bug"
+      ]
+    },
+    {
+      "login": "pweaver",
+      "name": "Pweaver",
+      "avatar_url": "https://avatars.githubusercontent.com/u/611620?v=4",
+      "profile": "https://github.com/pweaver",
+      "contributions": [
+        "bug",
+        "ideas"
+      ]
+    },
+    {
+      "login": "aa599",
+      "name": "aa599",
+      "avatar_url": "https://avatars.githubusercontent.com/u/37746269?v=4",
+      "profile": "https://github.com/aa599",
+      "contributions": [
+        "bug",
+        "ideas"
+      ]
+    },
+    {
+      "login": "swduncan",
+      "name": "Steve Duncan",
+      "avatar_url": "https://avatars.githubusercontent.com/u/2053195?v=4",
+      "profile": "https://github.com/swduncan",
+      "contributions": [
+        "ideas"
+      ]
+    },
+    {
+      "login": "ianmmoir",
+      "name": "Ian Moir",
+      "avatar_url": "https://avatars.githubusercontent.com/u/15144745?v=4",
+      "profile": "http://www.projany.com",
+      "contributions": [
+        "bug"
+      ]
+    },
+    {
+      "login": "pekingduck",
+      "name": "Peking Duck",
+      "avatar_url": "https://avatars.githubusercontent.com/u/2597142?v=4",
+      "profile": "https://github.com/pekingduck",
+      "contributions": [
+        "ideas",
+        "bug"
+      ]
+    },
+    {
+      "login": "cclauss",
+      "name": "Christian Clauss",
+      "avatar_url": "https://avatars.githubusercontent.com/u/3709715?v=4",
+      "profile": "https://www.patreon.com/cclauss",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "dvdkon",
+      "name": "dvdkon",
+      "avatar_url": "https://avatars.githubusercontent.com/u/3526303?v=4",
+      "profile": "https://github.com/dvdkon",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "wernerzj",
+      "name": "wernerzj",
+      "avatar_url": "https://avatars.githubusercontent.com/u/130370930?v=4",
+      "profile": "https://github.com/wernerzj",
+      "contributions": [
+        "bug"
+      ]
+    },
+    {
+      "login": "rajscode",
+      "name": "rajscode",
+      "avatar_url": "https://avatars.githubusercontent.com/u/99123253?v=4",
+      "profile": "https://github.com/rajscode",
+      "contributions": [
+        "bug",
+        "doc"
+      ]
+    },
+    {
+      "login": "MaxLyt",
+      "name": "MaxLyt",
+      "avatar_url": "https://avatars.githubusercontent.com/u/136200430?v=4",
+      "profile": "https://github.com/MaxLyt",
+      "contributions": [
+        "bug"
+      ]
+    },
+    {
+      "login": "ces3001",
+      "name": "ces3001",
+      "avatar_url": "https://avatars.githubusercontent.com/u/23762610?v=4",
+      "profile": "https://github.com/ces3001",
+      "contributions": [
+        "bug"
+      ]
     }
   ],
   "contributorsPerLine": 7,
-  "skipCi": true
+  "skipCi": true,
+  "commitType": "docs"
 }

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.56.2
+current_version = 0.60.4
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)
 serialize = {major}.{minor}.{patch}
 

.github/workflows/tests.yml

@@ -3,21 +3,30 @@ name: Tests
 on: [push, pull_request]
 
 jobs:
+  ruff:  # https://beta.ruff.rs
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - run: pip install --user ruff  # Lint Python twice: 1. Whole repo, 2. Exclude tests/
+    - run: ruff --format=github --line-length=7228 --target-version=py39
+                --ignore=E402,E712,E721,E722,E741,F401,F403,F405,F541,F601,F811,F822,F841 .
+    - run: ruff --format=github --line-length=366 --target-version=py39
+                --exclude=tests/ --ignore=E402,E722,E741,F401,F403,F405,F541,F822,F841 .
   build:
     runs-on: ${{ matrix.os }}
-    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
     strategy:
       max-parallel: 4
       matrix:
-        os: [macos-latest]
+        os: [macos-latest, ubuntu-latest]
         python-version: ['3.9', '3.10', '3.11']
-
     steps:
     - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
+        cache: 'pip' # caching pip dependencies
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

README.md

@@ -7,10 +7,10 @@
 [![Downloads](https://static.pepy.tech/personalized-badge/osxphotos?period=month&units=international_system&left_color=black&right_color=brightgreen&left_text=downloads/month)](https://pepy.tech/project/osxphotos)
 [![subreddit](https://img.shields.io/reddit/subreddit-subscribers/osxphotos?style=social)](https://www.reddit.com/r/osxphotos/)
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-48-orange.svg?style=flat)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-61-orange.svg?style=flat)](#contributors)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
-OSXPhotos provides the ability to interact with and query Apple's Photos.app library on macOS. You can query the Photos library database — for example, file name, file path, and metadata such as keywords/tags, persons/faces, albums, etc. You can also easily export both the original and edited photos.
+OSXPhotos provides the ability to interact with and query Apple's Photos.app library on macOS and Linux. You can query the Photos library database — for example, file name, file path, and metadata such as keywords/tags, persons/faces, albums, etc. You can also easily export both the original and edited photos.
 
 <p align="center"><img src="docs/screencast/demo.gif?raw=true" width="713" height="430"/></p>
 
@@ -33,20 +33,24 @@ OSXPhotos provides the ability to interact with and query Apple's Photos.app lib
 
 ## Supported operating systems
 
-Only works on macOS (aka Mac OS X). Tested on macOS Sierra (10.12.6) through macOS Monterey (12.0.1).  Tested on both x86 and Apple silicon (M1).
+Tested on Ubuntu Linux and macOS. Many features are only available on macOS.
+
+On Linux, macOS-specific features of the CLI will not be available (these will not be shown in the help output).
+The export and query CLI commands as well as the Python API will work on Linux which enables you to export photos
+from a Photos library on a Linux machine.
+
+Tested on macOS Sierra (10.12.6) through macOS Ventura (13.3). Tested on both x86 and Apple silicon (M1).
 
 | macOS Version     | macOS name | Photos.app version |
 | ----------------- |------------|:-------------------|
-| 13.0              | Ventura    | 8.0 ✅ *           |
-| 12.0 - 12.6       | Monterey   | 7.0 ✅ *           |
+| 13.0 - 13.4       | Ventura    | 8.0 ✅             |
+| 12.0 - 12.6       | Monterey   | 7.0 ✅             |
 | 10.16, 11.0-11.4  | Big Sur    | 6.0 ✅             |
 | 10.15.1 - 10.15.7 | Catalina   | 5.0 ✅             |
 | 10.14.5, 10.14.6  | Mojave     | 4.0 ✅             |
 | 10.13.6           | High Sierra| 3.0 ✅             |
 | 10.12.6           | Sierra     | 2.0 ✅             |
 
-\* Some features may not be fully supported on Monterey and Ventura. Notably, `--use-photokit` and `--download-missing` may or may not work depending on your configuration; this is a known issue that will be fixed if I can find a solution.  Many users successfully use OSXPhotos on Monterey without problem.
-
 This package will read Photos databases for any supported version on any supported macOS version.  E.g. you can read a database created with Photos 5.0 on MacOS 10.15 on a machine running macOS 10.12 and vice versa.
 
 Requires python >= `3.9`.
@@ -112,56 +116,69 @@ If you have questions, would like to show off projects created with OSXPhotos, o
 
 This package will install a command line utility called `osxphotos` that allows you to query the Photos database.  Alternatively, you can also run the command line utility like this: `python3 -m osxphotos`
 
+<!--[[[cog
+from osxphotos.cli import cli_main
+from click.testing import CliRunner
+runner = CliRunner()
+result = runner.invoke(cli_main, ["--help"])
+help = result.output.replace("Usage: cli-main", "Usage: osxphotos")
+cog.out(
+    "```\n{}\n```".format(help)
+)
+]]] -->
 ```
-> osxphotos
 Usage: osxphotos [OPTIONS] COMMAND [ARGS]...
 
-  osxphotos: query and export your Photos library
+  osxphotos: the multi-tool for your Photos library
 
 Options:
-  --db PHOTOS_LIBRARY_PATH  Specify Photos database path. Path to Photos
-                            library/database can be specified using either
-                            --db or directly as PHOTOS_LIBRARY positional
-                            argument. If neither --db or PHOTOS_LIBRARY
-                            provided, will attempt to find the library to use
-                            in the following order: 1. last opened library, 2.
-                            system library, 3. ~/Pictures/Photos
-                            Library.photoslibrary
-  --json                    Print output in JSON format.
-  -v, --version             Show the version and exit.
-  -h, --help                Show this message and exit.
+  -v, --version                   Show the version and exit.
+  --library, --db PHOTOS_LIBRARY_PATH
+                                  Specify path to Photos library. If not
+                                  provided, will attempt to find the library to
+                                  use in the following order: 1. last opened
+                                  library, 2. system library, 3.
+                                  ~/Pictures/Photos Library.photoslibrary
+  --json                          Print output in JSON format.
+  -h, --help                      Show this message and exit.
 
 Commands:
-  about      Print information about osxphotos including license.
-  albums     Print out albums found in the Photos library.
-  diff       Compare two Photos databases and print out differences
-  docs       Open osxphotos documentation in your browser.
-  dump       Print list of all photos & associated info from the Photos...
-  exiftool   Run exiftool on previously exported files to update metadata.
-  export     Export photos from the Photos database.
-  exportdb   Utilities for working with the osxphotos export database
-  help       Print help; for help on commands: help <command>.
-  import     Import photos and videos into Photos.
-  info       Print out descriptive info of the Photos library database.
-  inspect    Interactively inspect photos selected in Photos.
-  install    Install Python packages into the same environment as osxphotos
-  keywords   Print out keywords found in the Photos library.
-  labels     Print out image classification labels found in the Photos...
-  list       Print list of Photos libraries found on the system.
-  orphans    Find orphaned photos in a Photos library
-  persons    Print out persons (faces) found in the Photos library.
-  places     Print out places found in the Photos library.
-  query      Query the Photos database using 1 or more search options; if...
-  repl       Run interactive osxphotos REPL shell (useful for debugging,...
-  run        Run a python file using same environment as osxphotos.
-  snap       Create snapshot of Photos database to use with diff command
-  theme      Manage osxphotos color themes.
-  timewarp   Adjust date/time/timezone of photos in Apple Photos.
-  tutorial   Display osxphotos tutorial.
-  uninstall  Uninstall Python packages from the osxphotos environment
-  uuid       Print out unique IDs (UUID) of photos selected in Photos
-  version    Check for new version of osxphotos.
+  about          Print information about osxphotos including license.
+  add-locations  Add missing location data to photos in Photos.app using...
+  albums         Print out albums found in the Photos library.
+  batch-edit     Batch edit photo metadata such as title, description,...
+  diff           Compare two Photos databases and print out differences
+  docs           Open osxphotos documentation in your browser.
+  dump           Print list of all photos & associated info from the Photos...
+  exiftool       Run exiftool on previously exported files to update metadata.
+  export         Export photos from the Photos database.
+  exportdb       Utilities for working with the osxphotos export database
+  help           Print help; for help on commands: help <command>.
+  import         Import photos and videos into Photos.
+  info           Print out descriptive info of the Photos library database.
+  inspect        Interactively inspect photos selected in Photos.
+  install        Install Python packages into the same environment as...
+  keywords       Print out keywords found in the Photos library.
+  labels         Print out image classification labels found in the Photos...
+  list           Print list of Photos libraries found on the system.
+  orphans        Find orphaned photos in a Photos library
+  persons        Print out persons (faces) found in the Photos library.
+  places         Print out places found in the Photos library.
+  query          Query the Photos database using 1 or more search options;...
+  repl           Run interactive osxphotos REPL shell (useful for...
+  run            Run a python file using same environment as osxphotos.
+  show           Show photo, album, or folder in Photos from UUID_OR_NAME
+  snap           Create snapshot of Photos database to use with diff command
+  sync           Sync metadata and albums between Photos libraries.
+  theme          Manage osxphotos color themes.
+  timewarp       Adjust date/time/timezone of photos in Apple Photos.
+  tutorial       Display osxphotos tutorial.
+  uninstall      Uninstall Python packages from the osxphotos environment
+  uuid           Print out unique IDs (UUID) of photos selected in Photos
+  version        Check for new version of osxphotos.
+
 ```
+<!--[[[end]]] -->
 
 To get help on a specific command, use `osxphotos help command_name`, for example, `osxphotos help export` to get help on the `export` command.
 
@@ -673,15 +690,14 @@ Usage: osxphotos export [OPTIONS] [PHOTOS_LIBRARY]... DEST
   this behavior.
 
 Options:
-  --db PHOTOS_LIBRARY_PATH        Specify Photos database path. Path to Photos
-                                  library/database can be specified using either
-                                  --db or directly as PHOTOS_LIBRARY positional
-                                  argument. If neither --db or PHOTOS_LIBRARY
+  --library, --db PHOTOS_LIBRARY_PATH
+                                  Specify path to Photos library. If not
                                   provided, will attempt to find the library to
                                   use in the following order: 1. last opened
                                   library, 2. system library, 3.
                                   ~/Pictures/Photos Library.photoslibrary
-  -V, --verbose                   Print verbose output.
+  -V, --verbose                   Print verbose output; may be specified
+                                  multiple times for more verbose output.
   --timestamp                     Add time stamp to verbose output
   --no-progress                   Do not display progress bar during export.
   --keyword KEYWORD               Search for photos with keyword KEYWORD. If
@@ -706,8 +722,9 @@ Options:
   --uuid UUID                     Search for photos with UUID(s). May be
                                   repeated to include multiple UUIDs.
   --uuid-from-file FILE           Search for photos with UUID(s) loaded from
-                                  FILE. Format is a single UUID per line.  Lines
-                                  preceded with # are ignored.
+                                  FILE. Format is a single UUID per line. Lines
+                                  preceded with # are ignored. If FILE is '-',
+                                  read UUIDs from stdin.
   --title TITLE                   Search for TITLE in title of photo.
   --no-title                      Search for photos with no title.
   --description DESC              Search for DESC in description of photo.
@@ -729,6 +746,7 @@ Options:
   -i, --ignore-case               Case insensitive search for title,
                                   description, place, keyword, person, or album.
   --edited                        Search for photos that have been edited.
+  --not-edited                    Search for photos that have not been edited.
   --external-edit                 Search for photos edited in external editor.
   --favorite                      Search for photos marked favorite.
   --not-favorite                  Search for photos not marked favorite.
@@ -851,6 +869,16 @@ Options:
                                   been synched)
   --not-incloud                   Search for photos that are not in iCloud (have
                                   not been synched)
+  --syndicated                    Search for photos that have been shared via
+                                  syndication ('Shared with You' album via
+                                  Messages, etc.)
+  --not-syndicated                Search for photos that have not been shared
+                                  via syndication ('Shared with You' album via
+                                  Messages, etc.)
+  --saved-to-library              Search for syndicated photos that have saved
+                                  to the library
+  --not-saved-to-library          Search for syndicated photos that have not
+                                  saved to the library
   --regex REGEX TEMPLATE          Search for photos where TEMPLATE matches
                                   regular expression REGEX. For example, to find
                                   photos in an album that begins with 'Beach': '
@@ -898,10 +926,10 @@ Options:
                                   evaluated. See https://github.com/RhetTbull/os
                                   xphotos/blob/master/examples/query_function.py
                                   for example of how to use this option.
-  --deleted                       Include photos from the 'Recently Deleted'
-                                  folder.
   --deleted-only                  Include only photos from the 'Recently
                                   Deleted' folder.
+  --deleted                       Include photos from the 'Recently Deleted'
+                                  folder.
   --update                        Only export new or updated files. See also
                                   --force-update and notes below on export and
                                   --update.
@@ -1386,10 +1414,10 @@ Options:
                                   will be printed after the photo is exported or
                                   skipped. May be repeated to print multiple
                                   template strings.
-  --theme THEME                   Specify the color theme to use for --verbose
-                                  output. Valid themes are 'dark', 'light',
-                                  'mono', and 'plain'. Defaults to 'dark' or
-                                  'light' depending on system dark mode setting.
+  --theme THEME                   Specify the color theme to use for output.
+                                  Valid themes are 'dark', 'light', 'mono', and
+                                  'plain'. Defaults to 'dark' or 'light'
+                                  depending on system dark mode setting.
   -h, --help                      Show this message and exit.
 
                                     Export                                    
@@ -1426,22 +1454,23 @@ option to re-export the entire library thus rebuilding the
 
                              Extended Attributes                              
 
-Some options (currently '--finder-tag-template', '--finder-tag-keywords',
-'-xattr-template') write additional metadata accessible by Spotlight to
-facilitate searching.  For example, --finder-tag-keyword writes all keywords
-(including any specified by '--keyword-template' or other options) to Finder
-tags that are searchable in Spotlight using the syntax: 'tag:tagname'. For
-example, if you have images with keyword "Travel" then using '--finder-tag-
-keywords' you could quickly find those images in the Finder by typing
-'tag:Travel' in the Spotlight search bar. Finder tags are written to the
-'com.apple.metadata:_kMDItemUserTags' extended attribute. Unlike EXIF
-metadata, extended attributes do not modify the actual file; the metadata is
-written to extended attributes associated with the file and the Spotlight
-metadata database.  Most cloud storage services do not synch extended
-attributes.  Dropbox does sync them and any changes to a file's extended
-attributes will cause Dropbox to re-sync the files.
+    Some options (currently '--finder-tag-template', '--finder-tag-keywords',
+    '-xattr-template') write     additional metadata accessible by Spotlight
+    to facilitate searching.      For example, --finder-tag-keyword writes all
+    keywords (including any specified by '--keyword-template'     or other
+    options) to Finder tags that are searchable in Spotlight using the syntax:
+    'tag:tagname'.     For example, if you have images with keyword "Travel"
+    then using '--finder-tag-keywords' you could quickly     find those images
+    in the Finder by typing 'tag:Travel' in the Spotlight search bar.
+    Finder tags are written to the 'com.apple.metadata:_kMDItemUserTags'
+    extended attribute.     Unlike EXIF metadata, extended attributes do not
+    modify the actual file;     the metadata is written to extended attributes
+    associated with the file and the Spotlight metadata database.      Most
+    cloud storage services do not synch extended attributes.      Dropbox does
+    sync them and any changes to a file's extended attributes     will cause
+    Dropbox to re-sync the files.
 
-The following attributes may be used with '--xattr-template':
+    The following attributes may be used with '--xattr-template':
 
 
 Attribute      Description
@@ -1585,6 +1614,10 @@ Valid filters are:
    ['a', 'b', 'c', 'd'].                                                      
  • prepend(x): Prepend x to list of values, e.g. prepend(d): ['a', 'b', 'c']  
    => ['d', 'a', 'b', 'c'].                                                   
+ • appends(x): Append s[tring] Append x to each value of list of values, e.g. 
+   appends(d): ['a', 'b', 'c'] => ['ad', 'bd', 'cd'].                         
+ • prepends(x): Prepend s[tring] x to each value of list of values, e.g.      
+   prepends(d): ['a', 'b', 'c'] => ['da', 'db', 'dc'].                        
  • remove(x): Remove x from list of values, e.g. remove(b): ['a', 'b', 'c'] =>
    ['a', 'c'].                                                                
  • slice(start:stop:step): Slice list using same semantics as Python's list   
@@ -1981,6 +2014,41 @@ Substitution                    Description
                                 as a 5-digit integer and pad with zeros, use
                                 '{id:05d}' which results in 00001, 00002,
                                 00003...etc.
+{counter}                       A sequential counter, starting at 0, that
+                                increments each time it is evaluated.To
+                                start counting at a value other than 0,
+                                append append '(starting_value)' to the
+                                field name.For example, to start counting at
+                                1 instead of 0: '{counter(1)}'.May be
+                                formatted using a python string format
+                                code.For example, to format as a 5-digit
+                                integer and pad with zeros, use
+                                '{counter:05d(1)}'which results in 00001,
+                                00002, 00003...etc.You may also specify a
+                                stop value which causes the counter to reset
+                                to the starting valuewhen the stop value is
+                                reached and a step size which causes the
+                                counter to increment bythe specified value
+                                instead of 1. Use the format
+                                '{counter(start,stop,step)}' where
+                                start,stop, and step are integers. For
+                                example, to count from 1 to 10 by 2, use
+                                '{counter(1,11,2)}'.Note that the counter
+                                stops counting when the stop value is
+                                reached and does not return thestop value.
+                                Start, stop, and step are optional and may
+                                be omitted. For example, to countfrom 0 by
+                                2s, use '{counter(,,2)}'.You may create an
+                                arbitrary number of counters by appending a
+                                unique name to the field namepreceded by a
+                                period: '{counter.a}', '{counter.b}', etc.
+                                Each counter will have its own stateand will
+                                start at 0 and increment by 1 unless
+                                otherwise specified. Note: {counter} is not
+                                suitable for use with 'export' and '--
+                                update' as the counter associated with a
+                                photo may change between export sessions.
+                                See also {id}.
 {album_seq}                     An integer, starting at 0, indicating the
                                 photo's index (sequence) in the containing
                                 album. Only valid when used in a '--
@@ -2041,7 +2109,7 @@ Substitution                    Description
 {cr}                            A carriage return: '\r'
 {crlf}                          A carriage return + line feed: '\r\n'
 {tab}                           :A tab: '\t'
-{osxphotos_version}             The osxphotos version, e.g. '0.56.2'
+{osxphotos_version}             The osxphotos version, e.g. '0.60.4'
 {osxphotos_cmd_line}            The full command line used to run osxphotos
 
 The following substitutions may result in multiple values. Thus if specified
@@ -2328,6 +2396,8 @@ Valid filters are:
 - `join(x)`: Join list of values with delimiter x, e.g. join(,): ['a', 'b', 'c'] => 'a,b,c'; the DELIM option functions similar to join(x) but with DELIM, the join happens before being passed to any filters.May optionally be used without an argument, that is 'join()' which joins values together with no delimiter. e.g. join(): ['a', 'b', 'c'] => 'abc'.
 - `append(x)`: Append x to list of values, e.g. append(d): ['a', 'b', 'c'] => ['a', 'b', 'c', 'd'].
 - `prepend(x)`: Prepend x to list of values, e.g. prepend(d): ['a', 'b', 'c'] => ['d', 'a', 'b', 'c'].
+- `appends(x)`: Append s[tring] Append x to each value of list of values, e.g. appends(d): ['a', 'b', 'c'] => ['ad', 'bd', 'cd'].
+- `prepends(x)`: Prepend s[tring] x to each value of list of values, e.g. prepends(d): ['a', 'b', 'c'] => ['da', 'db', 'dc'].
 - `remove(x)`: Remove x from list of values, e.g. remove(b): ['a', 'b', 'c'] => ['a', 'c'].
 - `slice(start:stop:step)`: Slice list using same semantics as Python's list slicing, e.g. slice(1:3): ['a', 'b', 'c', 'd'] => ['b', 'c']; slice(1:4:2): ['a', 'b', 'c', 'd'] => ['b', 'd']; slice(1:): ['a', 'b', 'c', 'd'] => ['b', 'c', 'd']; slice(:-1): ['a', 'b', 'c', 'd'] => ['a', 'b', 'c']; slice(::-1): ['a', 'b', 'c', 'd'] => ['d', 'c', 'b', 'a']. See also sslice().
 - `sslice(start:stop:step)`: [s(tring) slice] Slice values in a list using same semantics as Python's string slicing, e.g. sslice(1:3):'abcd => 'bc'; sslice(1:4:2): 'abcd' => 'bd', etc. See also slice().
@@ -2508,6 +2578,7 @@ The following template field substitutions are availabe for use the templating s
 |{uuid}|Photo's internal universally unique identifier (UUID) for the photo, a 36-character string unique to the photo, e.g. '128FB4C6-0B16-4E7D-9108-FB2E90DA1546'|
 |{shortuuid}|A shorter representation of photo's internal universally unique identifier (UUID) for the photo, a 22-character string unique to the photo, e.g. 'JYsxugP9UjetmCbBCHXcmu'|
 |{id}|A unique number for the photo based on its primary key in the Photos database. A sequential integer, e.g. 1, 2, 3...etc.  Each asset associated with a photo (e.g. an image and Live Photo preview) will share the same id. May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{id:05d}' which results in 00001, 00002, 00003...etc. |
+|{counter}|A sequential counter, starting at 0, that increments each time it is evaluated.To start counting at a value other than 0, append append '(starting_value)' to the field name.For example, to start counting at 1 instead of 0: '{counter(1)}'.May be formatted using a python string format code.For example, to format as a 5-digit integer and pad with zeros, use '{counter:05d(1)}'which results in 00001, 00002, 00003...etc.You may also specify a stop value which causes the counter to reset to the starting valuewhen the stop value is reached and a step size which causes the counter to increment bythe specified value instead of 1. Use the format '{counter(start,stop,step)}' where start,stop, and step are integers. For example, to count from 1 to 10 by 2, use '{counter(1,11,2)}'.Note that the counter stops counting when the stop value is reached and does not return thestop value. Start, stop, and step are optional and may be omitted. For example, to countfrom 0 by 2s, use '{counter(,,2)}'.You may create an arbitrary number of counters by appending a unique name to the field namepreceded by a period: '{counter.a}', '{counter.b}', etc. Each counter will have its own stateand will start at 0 and increment by 1 unless otherwise specified. Note: {counter} is not suitable for use with 'export' and '--update' as the counter associated with a photo may change between export sessions. See also {id}.|
 |{album_seq}|An integer, starting at 0, indicating the photo's index (sequence) in the containing album. Only valid when used in a '--filename' template and only when '{album}' or '{folder_album}' is used in the '--directory' template. For example '--directory "{folder_album}" --filename "{album_seq}_{original_name}"'. To start counting at a value other than 0, append append '(starting_value)' to the field name.  For example, to start counting at 1 instead of 0: '{album_seq(1)}'. May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{album_seq:05d}' which results in 00000, 00001, 00002...etc. To format while also using a starting value: '{album_seq:05d(1)}' which results in 0001, 00002...etc.This may result in incorrect sequences if you have duplicate albums with the same name; see also '{folder_album_seq}'.|
 |{folder_album_seq}|An integer, starting at 0, indicating the photo's index (sequence) in the containing album and folder path. Only valid when used in a '--filename' template and only when '{folder_album}' is used in the '--directory' template. For example '--directory "{folder_album}" --filename "{folder_album_seq}_{original_name}"'. To start counting at a value other than 0, append '(starting_value)' to the field name. For example, to start counting at 1 instead of 0: '{folder_album_seq(1)}' May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{folder_album_seq:05d}' which results in 00000, 00001, 00002...etc. To format while also using a starting value: '{folder_album_seq:05d(1)}' which results in 0001, 00002...etc.This may result in incorrect sequences if you have duplicate albums with the same name in the same folder; see also '{album_seq}'. |
 |{comma}|A comma: ','|
@@ -2525,7 +2596,7 @@ The following template field substitutions are availabe for use the templating s
 |{cr}|A carriage return: '\r'|
 |{crlf}|A carriage return + line feed: '\r\n'|
 |{tab}|:A tab: '\t'|
-|{osxphotos_version}|The osxphotos version, e.g. '0.56.2'|
+|{osxphotos_version}|The osxphotos version, e.g. '0.60.4'|
 |{osxphotos_cmd_line}|The full command line used to run osxphotos|
 |{album}|Album(s) photo is contained in|
 |{folder_album}|Folder path + album photo is contained in. e.g. 'Folder/Subfolder/Album' or just 'Album' if no enclosing folder|
@@ -2565,7 +2636,7 @@ I'll gladly consider pull requests for bug fixes or feature implementations.
 
 If you have an interesting example that shows usage of this package, submit an issue or pull request and i'll include it or link to it.
 
-Testing against "real world" Photos libraries would be especially helpful.  If you discover issues in testing against your Photos libraries, please open an issue.  I've done extensive testing against my own Photos library but that's a since data point and I'm certain there are issues lurking in various edge cases I haven't discovered yet.
+Testing against "real world" Photos libraries would be especially helpful.  If you discover issues in testing against your Photos libraries, please open an issue.  I've done extensive testing against my own Photos library but that's a single data point and I'm certain there are issues lurking in various edge cases I haven't discovered yet.
 
 ### Contributors ✨
 
@@ -2609,7 +2680,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/mkirkland4874"><img src="https://avatars.githubusercontent.com/u/36466711?v=4?s=75" width="75px;" alt="mkirkland4874"/><br /><sub><b>mkirkland4874</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Amkirkland4874" title="Bug reports">🐛</a> <a href="#example-mkirkland4874" title="Examples">💡</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/jcommisso07"><img src="https://avatars.githubusercontent.com/u/3111054?v=4?s=75" width="75px;" alt="Joseph Commisso"/><br /><sub><b>Joseph Commisso</b></sub></a><br /><a href="#data-jcommisso07" title="Data">🔣</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/dssinger"><img src="https://avatars.githubusercontent.com/u/1817903?v=4?s=75" width="75px;" alt="David Singer"/><br /><sub><b>David Singer</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Adssinger" title="Bug reports">🐛</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/oPromessa"><img src="https://avatars.githubusercontent.com/u/21261491?v=4?s=75" width="75px;" alt="oPromessa"/><br /><sub><b>oPromessa</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3AoPromessa" title="Bug reports">🐛</a> <a href="#ideas-oPromessa" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/RhetTbull/osxphotos/commits?author=oPromessa" title="Tests">⚠️</a> <a href="https://github.com/RhetTbull/osxphotos/commits?author=oPromessa" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/oPromessa"><img src="https://avatars.githubusercontent.com/u/21261491?v=4?s=75" width="75px;" alt="oPromessa"/><br /><sub><b>oPromessa</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3AoPromessa" title="Bug reports">🐛</a> <a href="#ideas-oPromessa" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/RhetTbull/osxphotos/commits?author=oPromessa" title="Tests">⚠️</a> <a href="https://github.com/RhetTbull/osxphotos/commits?author=oPromessa" title="Code">💻</a> <a href="https://github.com/RhetTbull/osxphotos/commits?author=oPromessa" title="Documentation">📖</a></td>
       <td align="center" valign="top" width="14.28%"><a href="http://spencerchang.me"><img src="https://avatars.githubusercontent.com/u/14796580?v=4?s=75" width="75px;" alt="Spencer Chang"/><br /><sub><b>Spencer Chang</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Aspencerc99" title="Bug reports">🐛</a></td>
     </tr>
     <tr>
@@ -2637,6 +2708,23 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
       <td align="center" valign="top" width="14.28%"><a href="https://qkeddy.github.io/quin-eddy-development-portfolio/"><img src="https://avatars.githubusercontent.com/u/9737814?v=4?s=75" width="75px;" alt="Quin Eddy"/><br /><sub><b>Quin Eddy</b></sub></a><br /><a href="#ideas-qkeddy" title="Ideas, Planning, & Feedback">🤔</a> <a href="#data-qkeddy" title="Data">🔣</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/johnsturgeon"><img src="https://avatars.githubusercontent.com/u/9746310?v=4?s=75" width="75px;" alt="John Sturgeon"/><br /><sub><b>John Sturgeon</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Ajohnsturgeon" title="Bug reports">🐛</a> <a href="https://github.com/RhetTbull/osxphotos/commits?author=johnsturgeon" title="Documentation">📖</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/mave2k"><img src="https://avatars.githubusercontent.com/u/8629837?v=4?s=75" width="75px;" alt="mave2k"/><br /><sub><b>mave2k</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/commits?author=mave2k" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://danielbeadle.net"><img src="https://avatars.githubusercontent.com/u/6235378?v=4?s=75" width="75px;" alt="Daniel Beadle"/><br /><sub><b>Daniel Beadle</b></sub></a><br /><a href="#ideas-djbeadle" title="Ideas, Planning, & Feedback">🤔</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="http://eecue.com/"><img src="https://avatars.githubusercontent.com/u/532536?v=4?s=75" width="75px;" alt="Dave Bullock"/><br /><sub><b>Dave Bullock</b></sub></a><br /><a href="#ideas-eecue" title="Ideas, Planning, & Feedback">🤔</a> <a href="#userTesting-eecue" title="User Testing">📓</a> <a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Aeecue" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/pweaver"><img src="https://avatars.githubusercontent.com/u/611620?v=4?s=75" width="75px;" alt="Pweaver"/><br /><sub><b>Pweaver</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Apweaver" title="Bug reports">🐛</a> <a href="#ideas-pweaver" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/aa599"><img src="https://avatars.githubusercontent.com/u/37746269?v=4?s=75" width="75px;" alt="aa599"/><br /><sub><b>aa599</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Aaa599" title="Bug reports">🐛</a> <a href="#ideas-aa599" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/swduncan"><img src="https://avatars.githubusercontent.com/u/2053195?v=4?s=75" width="75px;" alt="Steve Duncan"/><br /><sub><b>Steve Duncan</b></sub></a><br /><a href="#ideas-swduncan" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://www.projany.com"><img src="https://avatars.githubusercontent.com/u/15144745?v=4?s=75" width="75px;" alt="Ian Moir"/><br /><sub><b>Ian Moir</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Aianmmoir" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/pekingduck"><img src="https://avatars.githubusercontent.com/u/2597142?v=4?s=75" width="75px;" alt="Peking Duck"/><br /><sub><b>Peking Duck</b></sub></a><br /><a href="#ideas-pekingduck" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Apekingduck" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://www.patreon.com/cclauss"><img src="https://avatars.githubusercontent.com/u/3709715?v=4?s=75" width="75px;" alt="Christian Clauss"/><br /><sub><b>Christian Clauss</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/commits?author=cclauss" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/dvdkon"><img src="https://avatars.githubusercontent.com/u/3526303?v=4?s=75" width="75px;" alt="dvdkon"/><br /><sub><b>dvdkon</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/commits?author=dvdkon" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/wernerzj"><img src="https://avatars.githubusercontent.com/u/130370930?v=4?s=75" width="75px;" alt="wernerzj"/><br /><sub><b>wernerzj</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Awernerzj" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/rajscode"><img src="https://avatars.githubusercontent.com/u/99123253?v=4?s=75" width="75px;" alt="rajscode"/><br /><sub><b>rajscode</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Arajscode" title="Bug reports">🐛</a> <a href="https://github.com/RhetTbull/osxphotos/commits?author=rajscode" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/MaxLyt"><img src="https://avatars.githubusercontent.com/u/136200430?v=4?s=75" width="75px;" alt="MaxLyt"/><br /><sub><b>MaxLyt</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3AMaxLyt" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ces3001"><img src="https://avatars.githubusercontent.com/u/23762610?v=4?s=75" width="75px;" alt="ces3001"/><br /><sub><b>ces3001</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Aces3001" title="Bug reports">🐛</a></td>
     </tr>
   </tbody>
 </table>

README_DEV.md

@@ -7,7 +7,7 @@ These are notes for developers working on osxphotos. They're mostly to help me r
 - Clone the repo: `git clone git@github.com:RhetTbull/osxphotos.git`
 - Create a virtual environment and activate it: `python3 -m venv venv` then `source venv/bin/activate`.  I use [pyenv](https://github.com/pyenv/pyenv) with [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv) to manage my virtual environments
 - Install the requirements: `pip install -r requirements.txt`
-- Install the development requirements: `pip install -r requirements-dev.txt`
+- Install the development requirements: `pip install -r dev_requirements.txt`
 - Install osxphotos: `pip install -e .`
 
 ## Running tests

build.sh

@@ -12,6 +12,7 @@ cog -d -o osxphotos/phototemplate.md osxphotos/phototemplate.cog.md
 
 echo "Updating README.md"
 python3 utils/update_readme.py
+cog -r README.md
 
 echo "Updating API_README.md"
 cog -r API_README.md
@@ -53,4 +54,4 @@ ARCHSTR=$(uname -m)
 ZIPNAME=osxphotos_MacOS_exe_darwin_${ARCHSTR}_v${OSXPHOTOSVERSION}.zip
 echo "Zipping CLI executable to $ZIPNAME"
 cd dist && zip $ZIPNAME osxphotos && cd ..
-rm dist/osxphotos
+rm dist/osxphotos

dev_requirements.txt

@@ -2,7 +2,7 @@ build
 bump2version==1.0.1 
 cogapp>=3.3.0,<4.0.0
 furo
-m2r2==0.3.3
+m2r2==0.3.3.post2
 pdbpp
 pyinstaller==5.6.2
 pytest-cov==4.0.0 

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 2b1d245eff1c1e7c9d89e31092ea013b
+config: 224170f9893912f89ea2dcbac8e6ccff
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_modules/index.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../genindex.html" /><link rel="search" title="Search" href="../search.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>Overview: module code - osxphotos 0.56.2 documentation</title>
+        <title>Overview: module code - osxphotos 0.60.4 documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../_static/copybutton.css" />
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../index.html"><div class="brand">osxphotos 0.56.2 documentation</div></a>
+      <a href="../index.html"><div class="brand">osxphotos 0.60.4 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.56.2 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.4 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>

docs/_modules/osxphotos/_constants.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>osxphotos._constants - osxphotos 0.55.7 documentation</title>
+        <title>osxphotos._constants - osxphotos 0.60.4 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.55.7 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.60.4 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.55.7 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.4 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -195,14 +195,18 @@
         </div>
         <article role="main">
           <h1>Source code for osxphotos._constants</h1><div class="highlight"><pre>
-<span></span><span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">Constants used by osxphotos </span>
-<span class="sd">&quot;&quot;&quot;</span>
+<span></span><span class="sd">&quot;&quot;&quot; Constants used by osxphotos &quot;&quot;&quot;</span>
 
+<span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">annotations</span>
+
+<span class="kn">import</span> <span class="nn">logging</span>
 <span class="kn">import</span> <span class="nn">os.path</span>
+<span class="kn">import</span> <span class="nn">sqlite3</span>
 <span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span>
 <span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">Enum</span>
 
+<span class="n">logger</span><span class="p">:</span> <span class="n">logging</span><span class="o">.</span><span class="n">Logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s2">&quot;osxphotos&quot;</span><span class="p">)</span>
+
 <span class="n">APP_NAME</span> <span class="o">=</span> <span class="s2">&quot;osxphotos&quot;</span>
 
 <span class="n">OSXPHOTOS_URL</span> <span class="o">=</span> <span class="s2">&quot;https://github.com/RhetTbull/osxphotos&quot;</span>
@@ -320,6 +324,9 @@
     <span class="p">(</span><span class="s2">&quot;12&quot;</span><span class="p">,</span> <span class="s2">&quot;6&quot;</span><span class="p">),</span>
     <span class="p">(</span><span class="s2">&quot;13&quot;</span><span class="p">,</span> <span class="s2">&quot;0&quot;</span><span class="p">),</span>
     <span class="p">(</span><span class="s2">&quot;13&quot;</span><span class="p">,</span> <span class="s2">&quot;1&quot;</span><span class="p">),</span>
+    <span class="p">(</span><span class="s2">&quot;13&quot;</span><span class="p">,</span> <span class="s2">&quot;2&quot;</span><span class="p">),</span>
+    <span class="p">(</span><span class="s2">&quot;13&quot;</span><span class="p">,</span> <span class="s2">&quot;3&quot;</span><span class="p">),</span>
+    <span class="p">(</span><span class="s2">&quot;13&quot;</span><span class="p">,</span> <span class="s2">&quot;4&quot;</span><span class="p">),</span>
 <span class="p">]</span>
 
 <span class="c1"># Photos 5 has persons who are empty string if unidentified face</span>
@@ -335,7 +342,9 @@
 <span class="n">_PHOTOS_8_SHARED_PHOTO_PATH</span> <span class="o">=</span> <span class="s2">&quot;scopes/cloudsharing/data&quot;</span>
 
 <span class="c1"># Where are shared iCloud derivatives located?</span>
-<span class="n">_PHOTOS_5_SHARED_DERIVATIVE_PATH</span> <span class="o">=</span> <span class="s2">&quot;resources/cloudsharing/resources/derivatives/masters&quot;</span>
+<span class="n">_PHOTOS_5_SHARED_DERIVATIVE_PATH</span> <span class="o">=</span> <span class="p">(</span>
+    <span class="s2">&quot;resources/cloudsharing/resources/derivatives/masters&quot;</span>
+<span class="p">)</span>
 <span class="n">_PHOTOS_8_SHARED_DERIVATIVE_PATH</span> <span class="o">=</span> <span class="s2">&quot;scopes/cloudsharing/resources/derivatives/masters&quot;</span>
 
 <span class="c1"># What type of file? Based on ZGENERICASSET.ZKIND in Photos 5 database</span>
@@ -375,6 +384,9 @@
 <span class="c1"># If anyone has a keyword matching this, then too bad...</span>
 <span class="n">_OSXPHOTOS_NONE_SENTINEL</span> <span class="o">=</span> <span class="s2">&quot;OSXPhotosXYZZY42_Sentinel$&quot;</span>
 
+<span class="c1"># Lock file extension for reserving filenames when exporting</span>
+<span class="n">_OSXPHOTOS_LOCK_EXTENSION</span> <span class="o">=</span> <span class="s2">&quot;.osxphotos.lock&quot;</span>
+
 
 <span class="k">class</span> <span class="nc">SearchCategory</span><span class="p">:</span>
     <span class="sd">&quot;&quot;&quot;SearchInfo categories for Photos 5+; corresponds to categories in database/search/psi.sqlite:groups.category</span>
@@ -410,11 +422,11 @@
     <span class="n">TITLE</span> <span class="o">=</span> <span class="mi">2017</span>
     <span class="n">DESCRIPTION</span> <span class="o">=</span> <span class="mi">2018</span>
     <span class="n">HOME</span> <span class="o">=</span> <span class="mi">2020</span>
+    <span class="n">WORK</span> <span class="o">=</span> <span class="mi">2036</span>
     <span class="n">PERSON</span> <span class="o">=</span> <span class="mi">2021</span>
     <span class="n">ACTIVITY</span> <span class="o">=</span> <span class="mi">2027</span>
     <span class="n">HOLIDAY</span> <span class="o">=</span> <span class="mi">2029</span>
     <span class="n">SEASON</span> <span class="o">=</span> <span class="mi">2030</span>
-    <span class="n">WORK</span> <span class="o">=</span> <span class="mi">2036</span>
     <span class="n">VENUE</span> <span class="o">=</span> <span class="mi">2038</span>
     <span class="n">VENUE_TYPE</span> <span class="o">=</span> <span class="mi">2039</span>
     <span class="n">PHOTO_TYPE_VIDEO</span> <span class="o">=</span> <span class="mi">2044</span>
@@ -427,6 +439,7 @@
     <span class="n">PHOTO_TYPE_PORTRAIT</span> <span class="o">=</span> <span class="mi">2053</span>
     <span class="n">PHOTO_TYPE_SELFIES</span> <span class="o">=</span> <span class="mi">2054</span>
     <span class="n">PHOTO_TYPE_FAVORITES</span> <span class="o">=</span> <span class="mi">2055</span>
+    <span class="n">PHOTO_TYPE_ANIMATED</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 8+ only</span>
     <span class="n">MEDIA_TYPES</span> <span class="o">=</span> <span class="p">[</span>
         <span class="n">PHOTO_TYPE_VIDEO</span><span class="p">,</span>
         <span class="n">PHOTO_TYPE_SLOMO</span><span class="p">,</span>
@@ -441,7 +454,23 @@
     <span class="p">]</span>
     <span class="n">PHOTO_NAME</span> <span class="o">=</span> <span class="mi">2056</span>
     <span class="n">CAMERA</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 8+ only</span>
+    <span class="n">TEXT_FOUND</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 8+ only</span>
     <span class="n">DETECTED_TEXT</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 8+ only</span>
+    <span class="n">SOURCE</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 8+ only</span>
+
+    <span class="nd">@classmethod</span>
+    <span class="k">def</span> <span class="nf">categories</span><span class="p">(</span><span class="bp">cls</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">str</span><span class="p">]:</span>
+        <span class="sd">&quot;&quot;&quot;Return categories as dict of value: name&quot;&quot;&quot;</span>
+        <span class="c1"># a bit of a hack to basically reverse the enum</span>
+        <span class="k">return</span> <span class="p">{</span>
+            <span class="n">value</span><span class="p">:</span> <span class="n">name</span>
+            <span class="k">for</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="bp">cls</span><span class="o">.</span><span class="vm">__dict__</span><span class="o">.</span><span class="n">items</span><span class="p">()</span>
+            <span class="k">if</span> <span class="n">name</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>
+            <span class="ow">and</span> <span class="ow">not</span> <span class="n">name</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s2">&quot;__&quot;</span><span class="p">)</span>
+            <span class="ow">and</span> <span class="ow">not</span> <span class="n">callable</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
+            <span class="ow">and</span> <span class="n">name</span><span class="o">.</span><span class="n">isupper</span><span class="p">()</span>
+            <span class="ow">and</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="p">(</span><span class="nb">list</span><span class="p">,</span> <span class="nb">dict</span><span class="p">,</span> <span class="nb">tuple</span><span class="p">))</span>
+        <span class="p">}</span>
 
 
 <span class="k">class</span> <span class="nc">SearchCategory_Photos8</span><span class="p">(</span><span class="n">SearchCategory</span><span class="p">):</span>
@@ -449,6 +478,20 @@
 
     <span class="c1"># Many of the category values changed in Ventura / Photos 8</span>
     <span class="c1"># and some new categories were added</span>
+    <span class="n">CITY</span> <span class="o">=</span> <span class="mi">5</span>
+    <span class="n">LOCALITY_4</span> <span class="o">=</span> <span class="mi">4</span>
+    <span class="n">SUB_LOCALITY_5</span> <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">SUB_LOCALITY_6</span> <span class="o">=</span> <span class="mi">6</span>
+    <span class="n">LOCALITY_8</span> <span class="o">=</span> <span class="mi">8</span>
+    <span class="n">NAMED_AREA</span> <span class="o">=</span> <span class="mi">7</span>
+    <span class="n">ALL_LOCALITY</span> <span class="o">=</span> <span class="p">[</span>
+        <span class="n">LOCALITY_4</span><span class="p">,</span>
+        <span class="n">SUB_LOCALITY_6</span><span class="p">,</span>
+        <span class="n">LOCALITY_8</span><span class="p">,</span>
+        <span class="n">NAMED_AREA</span><span class="p">,</span>
+    <span class="p">]</span>
+    <span class="n">HOME</span> <span class="o">=</span> <span class="mi">1000</span>
+    <span class="n">WORK</span> <span class="o">=</span> <span class="mi">1001</span>
     <span class="n">LABEL</span> <span class="o">=</span> <span class="mi">1500</span>
     <span class="n">MONTH</span> <span class="o">=</span> <span class="mi">1100</span>
     <span class="n">YEAR</span> <span class="o">=</span> <span class="mi">1101</span>
@@ -458,11 +501,55 @@
     <span class="n">TITLE</span> <span class="o">=</span> <span class="mi">1201</span>
     <span class="n">DESCRIPTION</span> <span class="o">=</span> <span class="mi">1202</span>
     <span class="n">DETECTED_TEXT</span> <span class="o">=</span> <span class="mi">1203</span>  <span class="c1"># new in Photos 8</span>
+    <span class="n">TEXT_FOUND</span> <span class="o">=</span> <span class="mi">1205</span>  <span class="c1"># new in Photos 8</span>
     <span class="n">PERSON</span> <span class="o">=</span> <span class="mi">1300</span>
     <span class="n">ACTIVITY</span> <span class="o">=</span> <span class="mi">1600</span>
+    <span class="n">VENUE</span> <span class="o">=</span> <span class="mi">1700</span>
+    <span class="n">VENUE_TYPE</span> <span class="o">=</span> <span class="mi">1701</span>
+    <span class="n">PHOTO_TYPE_VIDEO</span> <span class="o">=</span> <span class="mi">1901</span>
+    <span class="n">PHOTO_TYPE_SELFIES</span> <span class="o">=</span> <span class="mi">1915</span>
+    <span class="n">PHOTO_TYPE_LIVE</span> <span class="o">=</span> <span class="mi">1906</span>
+    <span class="n">PHOTO_TYPE_PORTRAIT</span> <span class="o">=</span> <span class="mi">1914</span>
     <span class="n">PHOTO_TYPE_FAVORITES</span> <span class="o">=</span> <span class="mi">2000</span>
+    <span class="n">PHOTO_TYPE_PANORAMA</span> <span class="o">=</span> <span class="mi">1908</span>
+    <span class="n">PHOTO_TYPE_TIMELAPSE</span> <span class="o">=</span> <span class="mi">1909</span>
+    <span class="n">PHOTO_TYPE_SLOMO</span> <span class="o">=</span> <span class="mi">1905</span>
+    <span class="n">PHOTO_TYPE_BURSTS</span> <span class="o">=</span> <span class="mi">1913</span>
+    <span class="n">PHOTO_TYPE_SCREENSHOT</span> <span class="o">=</span> <span class="mi">1907</span>
+    <span class="n">PHOTO_TYPE_ANIMATED</span> <span class="o">=</span> <span class="mi">1912</span>
+    <span class="n">PHOTO_TYPE_RAW</span> <span class="o">=</span> <span class="mi">1902</span>
+    <span class="n">MEDIA_TYPES</span> <span class="o">=</span> <span class="p">[</span>
+        <span class="n">PHOTO_TYPE_VIDEO</span><span class="p">,</span>
+        <span class="n">PHOTO_TYPE_SLOMO</span><span class="p">,</span>
+        <span class="n">PHOTO_TYPE_LIVE</span><span class="p">,</span>
+        <span class="n">PHOTO_TYPE_SCREENSHOT</span><span class="p">,</span>
+        <span class="n">PHOTO_TYPE_PANORAMA</span><span class="p">,</span>
+        <span class="n">PHOTO_TYPE_TIMELAPSE</span><span class="p">,</span>
+        <span class="n">PHOTO_TYPE_BURSTS</span><span class="p">,</span>
+        <span class="n">PHOTO_TYPE_PORTRAIT</span><span class="p">,</span>
+        <span class="n">PHOTO_TYPE_SELFIES</span><span class="p">,</span>
+        <span class="n">PHOTO_TYPE_FAVORITES</span><span class="p">,</span>
+        <span class="n">PHOTO_TYPE_ANIMATED</span><span class="p">,</span>
+    <span class="p">]</span>
     <span class="n">PHOTO_NAME</span> <span class="o">=</span> <span class="mi">2100</span>
     <span class="n">CAMERA</span> <span class="o">=</span> <span class="mi">2300</span>  <span class="c1"># new in Photos 8</span>
+    <span class="n">SOURCE</span> <span class="o">=</span> <span class="mi">2200</span>  <span class="c1"># new in Photos 8, shows the app/software source for the photo, e.g. Messages, Safari, etc.</span>
+
+    <span class="nd">@classmethod</span>
+    <span class="k">def</span> <span class="nf">categories</span><span class="p">(</span><span class="bp">cls</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">str</span><span class="p">]:</span>
+        <span class="sd">&quot;&quot;&quot;Return categories as dict of value: name&quot;&quot;&quot;</span>
+        <span class="c1"># need to get the categories from the base class and update with the new values</span>
+        <span class="n">classdict</span> <span class="o">=</span> <span class="n">SearchCategory</span><span class="o">.</span><span class="vm">__dict__</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
+        <span class="n">classdict</span> <span class="o">|=</span> <span class="bp">cls</span><span class="o">.</span><span class="vm">__dict__</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
+        <span class="k">return</span> <span class="p">{</span>
+            <span class="n">value</span><span class="p">:</span> <span class="n">name</span>
+            <span class="k">for</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">classdict</span><span class="o">.</span><span class="n">items</span><span class="p">()</span>
+            <span class="k">if</span> <span class="n">name</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>
+            <span class="ow">and</span> <span class="ow">not</span> <span class="n">name</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s2">&quot;__&quot;</span><span class="p">)</span>
+            <span class="ow">and</span> <span class="ow">not</span> <span class="n">callable</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
+            <span class="ow">and</span> <span class="n">name</span><span class="o">.</span><span class="n">isupper</span><span class="p">()</span>
+            <span class="ow">and</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="p">(</span><span class="nb">list</span><span class="p">,</span> <span class="nb">dict</span><span class="p">,</span> <span class="nb">tuple</span><span class="p">))</span>
+        <span class="p">}</span>
 
 
 <span class="k">def</span> <span class="nf">search_category_factory</span><span class="p">(</span><span class="n">version</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">SearchCategory</span><span class="p">:</span>
@@ -471,7 +558,7 @@
 
 
 <span class="c1"># Max filename length on MacOS</span>
-<span class="n">MAX_FILENAME_LEN</span> <span class="o">=</span> <span class="mi">255</span>
+<span class="n">MAX_FILENAME_LEN</span> <span class="o">=</span> <span class="mi">255</span> <span class="o">-</span> <span class="nb">len</span><span class="p">(</span><span class="n">_OSXPHOTOS_LOCK_EXTENSION</span><span class="p">)</span>
 
 <span class="c1"># Max directory name length on MacOS</span>
 <span class="n">MAX_DIRNAME_LEN</span> <span class="o">=</span> <span class="mi">255</span>
@@ -576,6 +663,19 @@
     <span class="s2">&quot;time&quot;</span><span class="p">,</span>
     <span class="s2">&quot;tottime&quot;</span><span class="p">,</span>
 <span class="p">]</span>
+
+<span class="n">UUID_PATTERN</span> <span class="o">=</span> <span class="p">(</span>
+    <span class="sa">r</span><span class="s2">&quot;[0-9a-fA-F]</span><span class="si">{8}</span><span class="s2">-[0-9a-fA-F]</span><span class="si">{4}</span><span class="s2">-[0-9a-fA-F]</span><span class="si">{4}</span><span class="s2">-[0-9a-fA-F]</span><span class="si">{4}</span><span class="s2">-[0-9a-fA-F]</span><span class="si">{12}</span><span class="s2">&quot;</span>
+<span class="p">)</span>
+<span class="c1"># Reference: https://docs.python.org/3/library/sqlite3.html?highlight=sqlite3%20threadsafety#sqlite3.threadsafety</span>
+<span class="c1"># and https://docs.python.org/3/library/sqlite3.html?highlight=sqlite3%20threadsafety#sqlite3.connect</span>
+<span class="c1"># 3: serialized mode; Threads may share the module, connections and cursors</span>
+<span class="c1"># 3 is the default in the python.org python 3.11 distribution</span>
+<span class="c1"># earlier versions of python.org python 3.x default to 1 which means threads may not share</span>
+<span class="c1"># sqlite3 connections and thus PhotoInfo.export() cannot be used in a multithreaded environment</span>
+<span class="c1"># pass SQLITE_CHECK_SAME_THREAD to sqlite3.connect() to enable multithreaded access on systems that support it</span>
+<span class="n">SQLITE_CHECK_SAME_THREAD</span> <span class="o">=</span> <span class="ow">not</span> <span class="n">sqlite3</span><span class="o">.</span><span class="n">threadsafety</span> <span class="o">==</span> <span class="mi">3</span>
+<span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">SQLITE_CHECK_SAME_THREAD</span><span class="si">=}</span><span class="s2">, </span><span class="si">{</span><span class="n">sqlite3</span><span class="o">.</span><span class="n">threadsafety</span><span class="si">=}</span><span class="s2">&quot;</span><span class="p">)</span>
 </pre></div>
         </article>
       </div>

docs/_modules/osxphotos/albuminfo.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>osxphotos.albuminfo - osxphotos 0.54.1 documentation</title>
+        <title>osxphotos.albuminfo - osxphotos 0.59.2 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.54.1 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.59.2 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.54.1 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.59.2 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -215,6 +215,7 @@
     <span class="n">_PHOTOS_4_VERSION</span><span class="p">,</span>
     <span class="n">_PHOTOS_5_ALBUM_KIND</span><span class="p">,</span>
     <span class="n">_PHOTOS_5_FOLDER_KIND</span><span class="p">,</span>
+    <span class="n">_PHOTOS_5_VERSION</span><span class="p">,</span>
     <span class="n">TIME_DELTA</span><span class="p">,</span>
     <span class="n">AlbumSortOrder</span><span class="p">,</span>
 <span class="p">)</span>
@@ -246,9 +247,8 @@
 <span class="sd">        ValueError: raised if len(values) != len(sort_keys)</span>
 <span class="sd">    &quot;&quot;&quot;</span>
     <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">values</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="n">sort_keys</span><span class="p">):</span>
-        <span class="k">return</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;values and sort_keys must have same length&quot;</span><span class="p">)</span>
-
-    <span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="nb">zip</span><span class="p">(</span><span class="o">*</span><span class="nb">sorted</span><span class="p">(</span><span class="nb">zip</span><span class="p">(</span><span class="n">sort_keys</span><span class="p">,</span> <span class="n">values</span><span class="p">))))[</span><span class="mi">1</span><span class="p">]</span>
+        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;values and sort_keys must be same length&quot;</span><span class="p">)</span>
+    <span class="k">return</span> <span class="p">[</span><span class="n">x</span> <span class="k">for</span> <span class="n">_</span><span class="p">,</span> <span class="n">x</span> <span class="ow">in</span> <span class="nb">sorted</span><span class="p">(</span><span class="nb">zip</span><span class="p">(</span><span class="n">sort_keys</span><span class="p">,</span> <span class="n">values</span><span class="p">))]</span>
 
 
 <span class="k">class</span> <span class="nc">AlbumInfoBaseClass</span><span class="p">:</span>
@@ -258,7 +258,7 @@
 <span class="sd">    including folders, photos, etc.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
 
-    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">db</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">db</span><span class="p">,</span> <span class="n">uuid</span><span class="p">):</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span> <span class="o">=</span> <span class="n">uuid</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_db</span> <span class="o">=</span> <span class="n">db</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_title</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbalbum_details</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;title&quot;</span><span class="p">]</span>
@@ -318,7 +318,8 @@
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">end_date</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;For Albums, return end date (most recent image) of album or None for albums with no images</span>
-<span class="sd">        For Import Sessions, return end date of import sessions (when import was completed)&quot;&quot;&quot;</span>
+<span class="sd">        For Import Sessions, return end date of import sessions (when import was completed)</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="k">try</span><span class="p">:</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_end_date</span>
         <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
@@ -360,6 +361,16 @@
                 <span class="bp">self</span><span class="o">.</span><span class="n">_owner</span> <span class="o">=</span> <span class="kc">None</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_owner</span>
 
+    <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Return album info as a dict; does not include photos&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="p">{</span>
+            <span class="s2">&quot;uuid&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">,</span>
+            <span class="s2">&quot;creation_date&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">creation_date</span><span class="p">,</span>
+            <span class="s2">&quot;start_date&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">start_date</span><span class="p">,</span>
+            <span class="s2">&quot;end_date&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">end_date</span><span class="p">,</span>
+            <span class="s2">&quot;owner&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">owner</span><span class="p">,</span>
+        <span class="p">}</span>
+
     <span class="k">def</span> <span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;return number of photos contained in album&quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photos</span><span class="p">)</span>
@@ -371,6 +382,10 @@
 <span class="sd">    including folders, photos, etc.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
 
+    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">db</span><span class="p">,</span> <span class="n">uuid</span><span class="p">):</span>
+        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="n">db</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="n">uuid</span><span class="p">)</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_title</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbalbum_details</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;title&quot;</span><span class="p">]</span>
+
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">title</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;return title / name of album&quot;&quot;&quot;</span>
@@ -402,10 +417,11 @@
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">folder_names</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot;return hierarchical list of folders the album is contained in</span>
+        <span class="sd">&quot;&quot;&quot;Return hierarchical list of folders the album is contained in</span>
 <span class="sd">        the folder list is in form:</span>
 <span class="sd">        [&quot;Top level folder&quot;, &quot;sub folder 1&quot;, &quot;sub folder 2&quot;, ...]</span>
-<span class="sd">        returns empty list if album is not in any folders&quot;&quot;&quot;</span>
+<span class="sd">        or empty list if album is not in any folders</span>
+<span class="sd">        &quot;&quot;&quot;</span>
 
         <span class="k">try</span><span class="p">:</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_folder_names</span>
@@ -415,10 +431,9 @@
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">folder_list</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot;return hierarchical list of folders the album is contained in</span>
-<span class="sd">        as list of FolderInfo objects in form</span>
-<span class="sd">        [&quot;Top level folder&quot;, &quot;sub folder 1&quot;, &quot;sub folder 2&quot;, ...]</span>
-<span class="sd">        returns empty list if album is not in any folders&quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;Returns list of FolderInfo objects for each folder the album is contained in</span>
+<span class="sd">        or empty list if album is not in any folders</span>
+<span class="sd">        &quot;&quot;&quot;</span>
 
         <span class="k">try</span><span class="p">:</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_folders</span>
@@ -443,7 +458,7 @@
                 <span class="n">parent_pk</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbalbum_details</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="p">][</span><span class="s2">&quot;parentfolder&quot;</span><span class="p">]</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_parent</span> <span class="o">=</span> <span class="p">(</span>
                     <span class="n">FolderInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbalbums_pk</span><span class="p">[</span><span class="n">parent_pk</span><span class="p">])</span>
-                    <span class="k">if</span> <span class="n">parent_pk</span> <span class="o">!=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_folder_root_pk</span>
+                    <span class="k">if</span> <span class="n">parent_pk</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="n">parent_pk</span> <span class="o">!=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_folder_root_pk</span>
                     <span class="k">else</span> <span class="kc">None</span>
                 <span class="p">)</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_parent</span>
@@ -476,29 +491,81 @@
                 <span class="k">return</span> <span class="n">index</span>
         <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
             <span class="sa">f</span><span class="s2">&quot;Photo with uuid </span><span class="si">{</span><span class="n">photo</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2"> does not appear to be in this album&quot;</span>
-        <span class="p">)</span></div></div>
+        <span class="p">)</span></div>
+
+<div class="viewcode-block" id="AlbumInfo.asdict"><a class="viewcode-back" href="../../reference.html#osxphotos.AlbumInfo.asdict">[docs]</a>    <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Return album info as a dict; does not include photos&quot;&quot;&quot;</span>
+        <span class="n">dict_data</span> <span class="o">=</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span>
+        <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;title&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">title</span>
+        <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;folder_names&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">folder_names</span>
+        <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;folder_list&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">f</span><span class="o">.</span><span class="n">uuid</span> <span class="k">for</span> <span class="n">f</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">folder_list</span><span class="p">]</span>
+        <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;sort_order&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sort_order</span>
+        <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;parent&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">parent</span><span class="o">.</span><span class="n">uuid</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">parent</span> <span class="k">else</span> <span class="kc">None</span>
+        <span class="k">return</span> <span class="n">dict_data</span></div></div>
 
 
 <div class="viewcode-block" id="ImportInfo"><a class="viewcode-back" href="../../reference.html#osxphotos.ImportInfo">[docs]</a><span class="k">class</span> <span class="nc">ImportInfo</span><span class="p">(</span><span class="n">AlbumInfoBaseClass</span><span class="p">):</span>
     <span class="sd">&quot;&quot;&quot;Information about import sessions&quot;&quot;&quot;</span>
 
+    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">db</span><span class="p">,</span> <span class="n">uuid</span><span class="p">):</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span> <span class="o">=</span> <span class="n">uuid</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_db</span> <span class="o">=</span> <span class="n">db</span>
+
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">&gt;=</span> <span class="n">_PHOTOS_5_VERSION</span><span class="p">:</span>
+            <span class="k">return</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="n">db</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="n">uuid</span><span class="p">)</span>
+
+        <span class="n">import_session</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_import_group</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="p">]</span>
+        <span class="k">try</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_creation_date_timestamp</span> <span class="o">=</span> <span class="n">import_session</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span>
+        <span class="k">except</span> <span class="p">(</span><span class="ne">ValueError</span><span class="p">,</span> <span class="ne">TypeError</span><span class="p">,</span> <span class="ne">KeyError</span><span class="p">):</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_creation_date_timestamp</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1970</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_start_date_timestamp</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_creation_date_timestamp</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_end_date_timestamp</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_creation_date_timestamp</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_title</span> <span class="o">=</span> <span class="n">import_session</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_local_tz</span> <span class="o">=</span> <span class="n">get_local_tz</span><span class="p">(</span>
+            <span class="n">datetime</span><span class="o">.</span><span class="n">fromtimestamp</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_creation_date_timestamp</span> <span class="o">+</span> <span class="n">TIME_DELTA</span><span class="p">)</span>
+        <span class="p">)</span>
+
+    <span class="nd">@property</span>
+    <span class="k">def</span> <span class="nf">title</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;return title / name of import session&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_title</span>
+
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">photos</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;return list of photos contained in import session&quot;&quot;&quot;</span>
         <span class="k">try</span><span class="p">:</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_photos</span>
         <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
-            <span class="n">uuid_list</span><span class="p">,</span> <span class="n">sort_order</span> <span class="o">=</span> <span class="nb">zip</span><span class="p">(</span>
-                <span class="o">*</span><span class="p">[</span>
-                    <span class="p">(</span><span class="n">uuid</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;fok_import_session&quot;</span><span class="p">])</span>
-                    <span class="k">for</span> <span class="n">uuid</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbphotos</span>
-                    <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;import_uuid&quot;</span><span class="p">]</span> <span class="o">==</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span>
+            <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">&gt;=</span> <span class="n">_PHOTOS_5_VERSION</span><span class="p">:</span>
+                <span class="n">uuid_list</span><span class="p">,</span> <span class="n">sort_order</span> <span class="o">=</span> <span class="nb">zip</span><span class="p">(</span>
+                    <span class="o">*</span><span class="p">[</span>
+                        <span class="p">(</span><span class="n">uuid</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;fok_import_session&quot;</span><span class="p">])</span>
+                        <span class="k">for</span> <span class="n">uuid</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbphotos</span>
+                        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;import_uuid&quot;</span><span class="p">]</span> <span class="o">==</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span>
+                    <span class="p">]</span>
+                <span class="p">)</span>
+                <span class="n">sorted_uuid</span> <span class="o">=</span> <span class="n">sort_list_by_keys</span><span class="p">(</span><span class="n">uuid_list</span><span class="p">,</span> <span class="n">sort_order</span><span class="p">)</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">_photos</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">photos_by_uuid</span><span class="p">(</span><span class="n">sorted_uuid</span><span class="p">)</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="n">import_photo_uuids</span> <span class="o">=</span> <span class="p">[</span>
+                    <span class="n">u</span>
+                    <span class="k">for</span> <span class="n">u</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbphotos</span>
+                    <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">u</span><span class="p">][</span><span class="s2">&quot;import_uuid&quot;</span><span class="p">]</span> <span class="o">==</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span>
                 <span class="p">]</span>
-            <span class="p">)</span>
-            <span class="n">sorted_uuid</span> <span class="o">=</span> <span class="n">sort_list_by_keys</span><span class="p">(</span><span class="n">uuid_list</span><span class="p">,</span> <span class="n">sort_order</span><span class="p">)</span>
-            <span class="bp">self</span><span class="o">.</span><span class="n">_photos</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">photos_by_uuid</span><span class="p">(</span><span class="n">sorted_uuid</span><span class="p">)</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">_photos</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">photos_by_uuid</span><span class="p">(</span><span class="n">import_photo_uuids</span><span class="p">)</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_photos</span>
 
+<div class="viewcode-block" id="ImportInfo.asdict"><a class="viewcode-back" href="../../reference.html#osxphotos.ImportInfo.asdict">[docs]</a>    <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Return import info as a dict; does not include photos&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="p">{</span>
+            <span class="s2">&quot;uuid&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">,</span>
+            <span class="s2">&quot;creation_date&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">creation_date</span><span class="p">,</span>
+            <span class="s2">&quot;start_date&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">start_date</span><span class="p">,</span>
+            <span class="s2">&quot;end_date&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">end_date</span><span class="p">,</span>
+            <span class="s2">&quot;title&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">title</span><span class="p">,</span>
+        <span class="p">}</span></div>
+
     <span class="k">def</span> <span class="fm">__bool__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;Always returns True</span>
 <span class="sd">        A photo without an import session will return None for import_info,</span>
@@ -506,13 +573,32 @@
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="kc">True</span></div>
 
+
 <div class="viewcode-block" id="ProjectInfo"><a class="viewcode-back" href="../../reference.html#osxphotos.ProjectInfo">[docs]</a><span class="k">class</span> <span class="nc">ProjectInfo</span><span class="p">(</span><span class="n">AlbumInfo</span><span class="p">):</span>
     <span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    ProjectInfo with info about projects</span>
 <span class="sd">    Projects are cards, calendars, slideshows, etc.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
 
-    <span class="o">...</span></div>
+    <span class="nd">@property</span>
+    <span class="k">def</span> <span class="nf">folder_names</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Return hierarchical list of folders the album is contained in</span>
+<span class="sd">        the folder list is in form:</span>
+<span class="sd">        [&quot;Top level folder&quot;, &quot;sub folder 1&quot;, &quot;sub folder 2&quot;, ...]</span>
+<span class="sd">        or empty list if album is not in any folders</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+
+        <span class="c1"># projects are not in folders</span>
+        <span class="k">return</span> <span class="p">[]</span>
+
+    <span class="nd">@property</span>
+    <span class="k">def</span> <span class="nf">folder_list</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Returns list of FolderInfo objects for each folder the album is contained in</span>
+<span class="sd">        or empty list if album is not in any folders</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+
+        <span class="c1"># projects are not in folders</span>
+        <span class="k">return</span> <span class="p">[]</span></div>
 
 
 <div class="viewcode-block" id="FolderInfo"><a class="viewcode-back" href="../../reference.html#osxphotos.FolderInfo">[docs]</a><span class="k">class</span> <span class="nc">FolderInfo</span><span class="p">:</span>
@@ -583,7 +669,7 @@
                 <span class="n">parent_pk</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbalbum_details</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="p">][</span><span class="s2">&quot;parentfolder&quot;</span><span class="p">]</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_parent</span> <span class="o">=</span> <span class="p">(</span>
                     <span class="n">FolderInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbalbums_pk</span><span class="p">[</span><span class="n">parent_pk</span><span class="p">])</span>
-                    <span class="k">if</span> <span class="n">parent_pk</span> <span class="o">!=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_folder_root_pk</span>
+                    <span class="k">if</span> <span class="n">parent_pk</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="n">parent_pk</span> <span class="o">!=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_folder_root_pk</span>
                     <span class="k">else</span> <span class="kc">None</span>
                 <span class="p">)</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_parent</span>
@@ -613,6 +699,16 @@
             <span class="bp">self</span><span class="o">.</span><span class="n">_folders</span> <span class="o">=</span> <span class="n">folders</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_folders</span>
 
+<div class="viewcode-block" id="FolderInfo.asdict"><a class="viewcode-back" href="../../reference.html#osxphotos.FolderInfo.asdict">[docs]</a>    <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Return folder info as a dict&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="p">{</span>
+            <span class="s2">&quot;title&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">title</span><span class="p">,</span>
+            <span class="s2">&quot;uuid&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">,</span>
+            <span class="s2">&quot;parent&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">parent</span><span class="o">.</span><span class="n">uuid</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">parent</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="k">else</span> <span class="kc">None</span><span class="p">,</span>
+            <span class="s2">&quot;subfolders&quot;</span><span class="p">:</span> <span class="p">[</span><span class="n">f</span><span class="o">.</span><span class="n">uuid</span> <span class="k">for</span> <span class="n">f</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">subfolders</span><span class="p">],</span>
+            <span class="s2">&quot;albums&quot;</span><span class="p">:</span> <span class="p">[</span><span class="n">a</span><span class="o">.</span><span class="n">uuid</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">album_info</span><span class="p">],</span>
+        <span class="p">}</span></div>
+
     <span class="k">def</span> <span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;returns count of folders + albums contained in the folder&quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">subfolders</span><span class="p">)</span> <span class="o">+</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">album_info</span><span class="p">)</span></div>

docs/_modules/osxphotos/debug.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>osxphotos.debug - osxphotos 0.56.1 documentation</title>
+        <title>osxphotos.debug - osxphotos 0.58.1 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.56.1 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.58.1 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.56.1 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.58.1 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -197,6 +197,8 @@
           <h1>Source code for osxphotos.debug</h1><div class="highlight"><pre>
 <span></span><span class="sd">&quot;&quot;&quot;Utilities for debugging&quot;&quot;&quot;</span>
 
+<span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">annotations</span>
+
 <span class="kn">import</span> <span class="nn">logging</span>
 <span class="kn">import</span> <span class="nn">sys</span>
 <span class="kn">import</span> <span class="nn">time</span>
@@ -206,21 +208,33 @@
 <span class="kn">import</span> <span class="nn">wrapt</span>
 <span class="kn">from</span> <span class="nn">rich</span> <span class="kn">import</span> <span class="nb">print</span>
 
+<span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span>
+    <span class="s2">&quot;debug_breakpoint&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;debug_watch&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;get_debug_flags&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;get_debug_options&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;is_debug&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;set_debug&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;wrap_function&quot;</span><span class="p">,</span>
+<span class="p">]</span>
+
+
 <span class="c1"># global variable to control debug output</span>
 <span class="c1"># set via --debug</span>
-<span class="n">DEBUG</span> <span class="o">=</span> <span class="kc">False</span>
+<span class="n">__osxphotos_debug</span> <span class="o">=</span> <span class="kc">False</span>
 
 
 <div class="viewcode-block" id="set_debug"><a class="viewcode-back" href="../../reference.html#osxphotos.set_debug">[docs]</a><span class="k">def</span> <span class="nf">set_debug</span><span class="p">(</span><span class="n">debug</span><span class="p">:</span> <span class="nb">bool</span><span class="p">):</span>
     <span class="sd">&quot;&quot;&quot;set debug flag&quot;&quot;&quot;</span>
-    <span class="k">global</span> <span class="n">DEBUG</span>
-    <span class="n">DEBUG</span> <span class="o">=</span> <span class="n">debug</span>
+    <span class="k">global</span> <span class="n">__osxphotos_debug</span>
+    <span class="n">__osxphotos_debug</span> <span class="o">=</span> <span class="n">debug</span>
     <span class="n">logging</span><span class="o">.</span><span class="n">disable</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">NOTSET</span> <span class="k">if</span> <span class="n">debug</span> <span class="k">else</span> <span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span></div>
 
 
 <div class="viewcode-block" id="is_debug"><a class="viewcode-back" href="../../reference.html#osxphotos.is_debug">[docs]</a><span class="k">def</span> <span class="nf">is_debug</span><span class="p">():</span>
     <span class="sd">&quot;&quot;&quot;return debug flag&quot;&quot;&quot;</span>
-    <span class="k">return</span> <span class="n">DEBUG</span></div>
+    <span class="k">global</span> <span class="n">__osxphotos_debug</span>
+    <span class="k">return</span> <span class="n">__osxphotos_debug</span></div>
 
 
 <span class="k">def</span> <span class="nf">debug_watch</span><span class="p">(</span><span class="n">wrapped</span><span class="p">,</span> <span class="n">instance</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">kwargs</span><span class="p">):</span>

docs/_modules/osxphotos/exiftool.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>osxphotos.exiftool - osxphotos 0.55.6 documentation</title>
+        <title>osxphotos.exiftool - osxphotos 0.59.1 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.55.6 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.59.1 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.55.6 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.59.1 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>

docs/_modules/osxphotos/fileutil.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>osxphotos.fileutil - osxphotos 0.54.2 documentation</title>
+        <title>osxphotos.fileutil - osxphotos 0.60.0 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.54.2 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.60.0 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.54.2 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.0 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -206,9 +206,11 @@
 <span class="kn">from</span> <span class="nn">abc</span> <span class="kn">import</span> <span class="n">ABC</span><span class="p">,</span> <span class="n">abstractmethod</span>
 <span class="kn">from</span> <span class="nn">tempfile</span> <span class="kn">import</span> <span class="n">TemporaryDirectory</span>
 
-<span class="kn">import</span> <span class="nn">Foundation</span>
-
 <span class="kn">from</span> <span class="nn">.imageconverter</span> <span class="kn">import</span> <span class="n">ImageConverter</span>
+<span class="kn">from</span> <span class="nn">.utils</span> <span class="kn">import</span> <span class="n">is_macos</span><span class="p">,</span> <span class="n">normalize_fs_path</span>
+
+<span class="k">if</span> <span class="n">is_macos</span><span class="p">:</span>
+    <span class="kn">import</span> <span class="nn">Foundation</span>
 
 <span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;FileUtilABC&quot;</span><span class="p">,</span> <span class="s2">&quot;FileUtilMacOS&quot;</span><span class="p">,</span> <span class="s2">&quot;FileUtilShUtil&quot;</span><span class="p">,</span> <span class="s2">&quot;FileUtil&quot;</span><span class="p">,</span> <span class="s2">&quot;FileUtilNoOp&quot;</span><span class="p">]</span>
 
@@ -287,6 +289,9 @@
         <span class="k">if</span> <span class="n">src</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">or</span> <span class="n">dest</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;src and dest must not be None&quot;</span><span class="p">,</span> <span class="n">src</span><span class="p">,</span> <span class="n">dest</span><span class="p">)</span>
 
+        <span class="n">src</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">src</span><span class="p">)</span>
+        <span class="n">dest</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
+
         <span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">src</span><span class="p">):</span>
             <span class="k">raise</span> <span class="ne">FileNotFoundError</span><span class="p">(</span><span class="s2">&quot;src file does not appear to exist&quot;</span><span class="p">,</span> <span class="n">src</span><span class="p">)</span>
 
@@ -312,6 +317,9 @@
 <span class="sd">            OSError if copy fails</span>
 <span class="sd">            TypeError if either path is None</span>
 <span class="sd">        &quot;&quot;&quot;</span>
+        <span class="n">src</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">src</span><span class="p">)</span>
+        <span class="n">dest</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
+
         <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">src</span><span class="p">,</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">):</span>
             <span class="n">src</span> <span class="o">=</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="n">src</span><span class="p">)</span>
 
@@ -332,6 +340,7 @@
     <span class="nd">@classmethod</span>
     <span class="k">def</span> <span class="nf">unlink</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">filepath</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;unlink filepath; if it&#39;s pathlib.Path, use Path.unlink, otherwise use os.unlink&quot;&quot;&quot;</span>
+        <span class="n">filepath</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">filepath</span><span class="p">)</span>
         <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">filepath</span><span class="p">,</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">):</span>
             <span class="n">filepath</span><span class="o">.</span><span class="n">unlink</span><span class="p">()</span>
         <span class="k">else</span><span class="p">:</span>
@@ -340,6 +349,7 @@
     <span class="nd">@classmethod</span>
     <span class="k">def</span> <span class="nf">rmdir</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">dirpath</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;remove directory filepath; dirpath must be empty&quot;&quot;&quot;</span>
+        <span class="n">dirpath</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">dirpath</span><span class="p">)</span>
         <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">dirpath</span><span class="p">,</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">):</span>
             <span class="n">dirpath</span><span class="o">.</span><span class="n">rmdir</span><span class="p">()</span>
         <span class="k">else</span><span class="p">:</span>
@@ -348,6 +358,7 @@
     <span class="nd">@classmethod</span>
     <span class="k">def</span> <span class="nf">utime</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">path</span><span class="p">,</span> <span class="n">times</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;Set the access and modified time of path.&quot;&quot;&quot;</span>
+        <span class="n">path</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
         <span class="n">os</span><span class="o">.</span><span class="n">utime</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">times</span><span class="o">=</span><span class="n">times</span><span class="p">)</span>
 
     <span class="nd">@classmethod</span>
@@ -363,6 +374,9 @@
 <span class="sd">        Does not do a byte-by-byte comparison.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
 
+        <span class="n">f1</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">f1</span><span class="p">)</span>
+        <span class="n">f2</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">f2</span><span class="p">)</span>
+
         <span class="n">s1</span> <span class="o">=</span> <span class="bp">cls</span><span class="o">.</span><span class="n">_sig</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">stat</span><span class="p">(</span><span class="n">f1</span><span class="p">))</span>
         <span class="k">if</span> <span class="n">mtime1</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
             <span class="n">s1</span> <span class="o">=</span> <span class="p">(</span><span class="n">s1</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">s1</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="nb">int</span><span class="p">(</span><span class="n">mtime1</span><span class="p">))</span>
@@ -385,6 +399,7 @@
         <span class="k">if</span> <span class="ow">not</span> <span class="n">s2</span><span class="p">:</span>
             <span class="k">return</span> <span class="kc">False</span>
 
+        <span class="n">f1</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">f1</span><span class="p">)</span>
         <span class="n">s1</span> <span class="o">=</span> <span class="bp">cls</span><span class="o">.</span><span class="n">_sig</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">stat</span><span class="p">(</span><span class="n">f1</span><span class="p">))</span>
         <span class="k">if</span> <span class="n">s1</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">!=</span> <span class="n">stat</span><span class="o">.</span><span class="n">S_IFREG</span> <span class="ow">or</span> <span class="n">s2</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">!=</span> <span class="n">stat</span><span class="o">.</span><span class="n">S_IFREG</span><span class="p">:</span>
             <span class="k">return</span> <span class="kc">False</span>
@@ -393,6 +408,7 @@
     <span class="nd">@classmethod</span>
     <span class="k">def</span> <span class="nf">file_sig</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">f1</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;return os.stat signature for file f1 as tuple of (mode, size, mtime)&quot;&quot;&quot;</span>
+        <span class="n">f1</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">f1</span><span class="p">)</span>
         <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">_sig</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">stat</span><span class="p">(</span><span class="n">f1</span><span class="p">))</span>
 
     <span class="nd">@classmethod</span>
@@ -407,6 +423,8 @@
 <span class="sd">        Returns:</span>
 <span class="sd">            True if success, otherwise False</span>
 <span class="sd">        &quot;&quot;&quot;</span>
+        <span class="n">src_file</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">src_file</span><span class="p">)</span>
+        <span class="n">dest_file</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">dest_file</span><span class="p">)</span>
         <span class="n">converter</span> <span class="o">=</span> <span class="n">ImageConverter</span><span class="p">()</span>
         <span class="k">return</span> <span class="n">converter</span><span class="o">.</span><span class="n">write_jpeg</span><span class="p">(</span>
             <span class="n">src_file</span><span class="p">,</span> <span class="n">dest_file</span><span class="p">,</span> <span class="n">compression_quality</span><span class="o">=</span><span class="n">compression_quality</span>
@@ -424,6 +442,8 @@
 <span class="sd">            Name of renamed file (dest)</span>
 
 <span class="sd">        &quot;&quot;&quot;</span>
+        <span class="n">src</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">src</span><span class="p">)</span>
+        <span class="n">dest</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
         <span class="n">os</span><span class="o">.</span><span class="n">rename</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">src</span><span class="p">),</span> <span class="nb">str</span><span class="p">(</span><span class="n">dest</span><span class="p">))</span>
         <span class="k">return</span> <span class="n">dest</span>
 
@@ -468,6 +488,9 @@
 <span class="sd">            OSError if copy fails</span>
 <span class="sd">            TypeError if either path is None</span>
 <span class="sd">        &quot;&quot;&quot;</span>
+        <span class="n">src</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">src</span><span class="p">)</span>
+        <span class="n">dest</span> <span class="o">=</span> <span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
+
         <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">src</span><span class="p">,</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">):</span>
             <span class="n">src</span> <span class="o">=</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="n">src</span><span class="p">)</span>
 
@@ -485,7 +508,7 @@
         <span class="k">return</span> <span class="kc">True</span>
 
 
-<div class="viewcode-block" id="FileUtil"><a class="viewcode-back" href="../../reference.html#osxphotos.FileUtil">[docs]</a><span class="k">class</span> <span class="nc">FileUtil</span><span class="p">(</span><span class="n">FileUtilMacOS</span><span class="p">):</span>
+<div class="viewcode-block" id="FileUtil"><a class="viewcode-back" href="../../reference.html#osxphotos.FileUtil">[docs]</a><span class="k">class</span> <span class="nc">FileUtil</span><span class="p">(</span><span class="n">FileUtilShUtil</span><span class="p">):</span>
     <span class="sd">&quot;&quot;&quot;Various file utilities&quot;&quot;&quot;</span>
 
     <span class="k">pass</span></div>

docs/_modules/osxphotos/personinfo.html

@@ -1,13 +1,13 @@
 <!doctype html>
-<html class="no-js">
+<html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
-    <meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
-        <title>osxphotos.personinfo - osxphotos 0.50.4 documentation</title>
+    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
+        <title>osxphotos.personinfo - osxphotos 0.58.1 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
-    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
+    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
     
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.50.4 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.58.1 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.50.4 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.58.1 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -179,7 +179,8 @@
           </svg>
           <span>Back to top</span>
         </a>
-        <div class="content-icon-container"><div class="theme-toggle-container theme-toggle-content">
+        <div class="content-icon-container">
+          <div class="theme-toggle-container theme-toggle-content">
             <button class="theme-toggle">
               <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
               <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
@@ -194,25 +195,27 @@
         </div>
         <article role="main">
           <h1>Source code for osxphotos.personinfo</h1><div class="highlight"><pre>
-<span></span><span class="sd">""" PhotoInfo and FaceInfo classes to expose info about persons and faces in the Photos library """</span>
+<span></span><span class="sd">&quot;&quot;&quot; PhotoInfo and FaceInfo classes to expose info about persons and faces in the Photos library &quot;&quot;&quot;</span>
 
 <span class="kn">import</span> <span class="nn">json</span>
 <span class="kn">import</span> <span class="nn">logging</span>
 <span class="kn">import</span> <span class="nn">math</span>
-
 <span class="kn">from</span> <span class="nn">collections</span> <span class="kn">import</span> <span class="n">namedtuple</span>
+<span class="kn">from</span> <span class="nn">functools</span> <span class="kn">import</span> <span class="n">cached_property</span>
 
-<span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"PersonInfo"</span><span class="p">,</span> <span class="s2">"FaceInfo"</span><span class="p">,</span> <span class="s2">"rotate_image_point"</span><span class="p">]</span>
+<span class="kn">import</span> <span class="nn">osxphotos</span>
 
-<span class="n">MWG_RS_Area</span> <span class="o">=</span> <span class="n">namedtuple</span><span class="p">(</span><span class="s2">"MWG_RS_Area"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"x"</span><span class="p">,</span> <span class="s2">"y"</span><span class="p">,</span> <span class="s2">"h"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">])</span>
-<span class="n">MPRI_Reg_Rect</span> <span class="o">=</span> <span class="n">namedtuple</span><span class="p">(</span><span class="s2">"MPRI_Reg_Rect"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"x"</span><span class="p">,</span> <span class="s2">"y"</span><span class="p">,</span> <span class="s2">"h"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">])</span>
+<span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;PersonInfo&quot;</span><span class="p">,</span> <span class="s2">&quot;FaceInfo&quot;</span><span class="p">,</span> <span class="s2">&quot;rotate_image_point&quot;</span><span class="p">]</span>
+
+<span class="n">MWG_RS_Area</span> <span class="o">=</span> <span class="n">namedtuple</span><span class="p">(</span><span class="s2">&quot;MWG_RS_Area&quot;</span><span class="p">,</span> <span class="p">[</span><span class="s2">&quot;x&quot;</span><span class="p">,</span> <span class="s2">&quot;y&quot;</span><span class="p">,</span> <span class="s2">&quot;h&quot;</span><span class="p">,</span> <span class="s2">&quot;w&quot;</span><span class="p">])</span>
+<span class="n">MPRI_Reg_Rect</span> <span class="o">=</span> <span class="n">namedtuple</span><span class="p">(</span><span class="s2">&quot;MPRI_Reg_Rect&quot;</span><span class="p">,</span> <span class="p">[</span><span class="s2">&quot;x&quot;</span><span class="p">,</span> <span class="s2">&quot;y&quot;</span><span class="p">,</span> <span class="s2">&quot;h&quot;</span><span class="p">,</span> <span class="s2">&quot;w&quot;</span><span class="p">])</span>
 
 
 <div class="viewcode-block" id="PersonInfo"><a class="viewcode-back" href="../../reference.html#osxphotos.PersonInfo">[docs]</a><span class="k">class</span> <span class="nc">PersonInfo</span><span class="p">:</span>
-    <span class="sd">"""Info about a person in the Photos library"""</span>
+    <span class="sd">&quot;&quot;&quot;Info about a person in the Photos library&quot;&quot;&quot;</span>
 
-    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">db</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">pk</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
-        <span class="sd">"""Creates a new PersonInfo instance</span>
+    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">db</span><span class="p">:</span> <span class="s2">&quot;osxphotos.PhotosDB&quot;</span><span class="p">,</span> <span class="n">pk</span><span class="p">:</span> <span class="nb">int</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Creates a new PersonInfo instance</span>
 
 <span class="sd">        Arguments:</span>
 <span class="sd">            db: instance of PhotosDB object</span>
@@ -220,16 +223,16 @@
 
 <span class="sd">        Returns:</span>
 <span class="sd">            PersonInfo instance</span>
-<span class="sd">        """</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">_db</span> <span class="o">=</span> <span class="n">db</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">_pk</span> <span class="o">=</span> <span class="n">pk</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">:</span> <span class="s2">&quot;osxphotos.PhotosDB&quot;</span> <span class="o">=</span> <span class="n">db</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_pk</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="n">pk</span>
 
         <span class="n">person</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbpersons_pk</span><span class="p">[</span><span class="n">pk</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="s2">"uuid"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="s2">"fullname"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">display_name</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="s2">"displayname"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">keyface</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="s2">"keyface"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">facecount</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="s2">"facecount"</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="s2">&quot;uuid&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="s2">&quot;fullname&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">display_name</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="s2">&quot;displayname&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">keyface</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="s2">&quot;keyface&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">facecount</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="s2">&quot;facecount&quot;</span><span class="p">]</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">keyphoto</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
@@ -237,9 +240,9 @@
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_keyphoto</span>
         <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
             <span class="n">person</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbpersons_pk</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_pk</span><span class="p">]</span>
-            <span class="k">if</span> <span class="n">person</span><span class="p">[</span><span class="s2">"photo_uuid"</span><span class="p">]:</span>
+            <span class="k">if</span> <span class="n">person</span><span class="p">[</span><span class="s2">&quot;photo_uuid&quot;</span><span class="p">]:</span>
                 <span class="k">try</span><span class="p">:</span>
-                    <span class="n">key_photo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">get_photo</span><span class="p">(</span><span class="n">person</span><span class="p">[</span><span class="s2">"photo_uuid"</span><span class="p">])</span>
+                    <span class="n">key_photo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">get_photo</span><span class="p">(</span><span class="n">person</span><span class="p">[</span><span class="s2">&quot;photo_uuid&quot;</span><span class="p">])</span>
                 <span class="k">except</span> <span class="ne">IndexError</span><span class="p">:</span>
                     <span class="n">key_photo</span> <span class="o">=</span> <span class="kc">None</span>
             <span class="k">else</span><span class="p">:</span>
@@ -249,14 +252,14 @@
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">photos</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Returns list of PhotoInfo objects associated with this person"""</span>
+        <span class="sd">&quot;&quot;&quot;Returns list of PhotoInfo objects associated with this person&quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">photos_by_uuid</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbfaces_pk</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_pk</span><span class="p">])</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">face_info</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Returns a list of FaceInfo objects associated with this person sorted by quality score</span>
+        <span class="sd">&quot;&quot;&quot;Returns a list of FaceInfo objects associated with this person sorted by quality score</span>
 <span class="sd">        Highest quality face is result[0] and lowest quality face is result[n]</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="k">try</span><span class="p">:</span>
             <span class="n">faces</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_faceinfo_person</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_pk</span><span class="p">]</span>
             <span class="k">return</span> <span class="nb">sorted</span><span class="p">(</span>
@@ -268,30 +271,60 @@
             <span class="c1"># no faces</span>
             <span class="k">return</span> <span class="p">[]</span>
 
+    <span class="nd">@property</span>
+    <span class="k">def</span> <span class="nf">favorite</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Returns True if person is a favorite, False otherwise; Photos 5+ only; returns False on Photos &lt;= 4&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbpersons_pk</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_pk</span><span class="p">][</span><span class="s2">&quot;type&quot;</span><span class="p">]</span> <span class="o">==</span> <span class="mi">1</span>
+
+    <span class="nd">@property</span>
+    <span class="k">def</span> <span class="nf">sort_order</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Returns sort order of person; favorite persons are sorted before non-favorite persons&quot;; Photos 5+ only; returns 0 on Photos &lt;= 4&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_dbpersons_pk</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_pk</span><span class="p">][</span><span class="s2">&quot;manualorder&quot;</span><span class="p">]</span>
+
+    <span class="nd">@cached_property</span>
+    <span class="k">def</span> <span class="nf">feature_less</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Returns True if person has been marked as &quot;Feature This Person Less&quot; in Photos, False otherwise; Photos 8+ only; returns False on Photos &lt;= 7&quot;&quot;&quot;</span>
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">photos_version</span> <span class="o">&lt;</span> <span class="mi">8</span><span class="p">:</span>
+            <span class="k">return</span> <span class="kc">False</span>
+
+        <span class="k">if</span> <span class="n">results</span> <span class="o">:=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span>
+            <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">            SELECT ZTYPE</span>
+<span class="sd">            FROM ZUSERFEEDBACK</span>
+<span class="sd">            WHERE ZPERSON = ?</span>
+<span class="sd">            &quot;&quot;&quot;</span><span class="p">,</span>
+            <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_pk</span><span class="p">,),</span>
+        <span class="p">)</span><span class="o">.</span><span class="n">fetchone</span><span class="p">():</span>
+            <span class="k">return</span> <span class="nb">bool</span><span class="p">(</span><span class="n">results</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
+        <span class="k">return</span> <span class="kc">False</span>
+
 <div class="viewcode-block" id="PersonInfo.asdict"><a class="viewcode-back" href="../../reference.html#osxphotos.PersonInfo.asdict">[docs]</a>    <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Returns dictionary representation of class instance"""</span>
+        <span class="sd">&quot;&quot;&quot;Returns dictionary representation of class instance&quot;&quot;&quot;</span>
         <span class="n">keyphoto</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">keyphoto</span><span class="o">.</span><span class="n">uuid</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">keyphoto</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="k">else</span> <span class="kc">None</span>
         <span class="k">return</span> <span class="p">{</span>
-            <span class="s2">"uuid"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">,</span>
-            <span class="s2">"name"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
-            <span class="s2">"displayname"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">display_name</span><span class="p">,</span>
-            <span class="s2">"keyface"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">keyface</span><span class="p">,</span>
-            <span class="s2">"facecount"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">facecount</span><span class="p">,</span>
-            <span class="s2">"keyphoto"</span><span class="p">:</span> <span class="n">keyphoto</span><span class="p">,</span>
+            <span class="s2">&quot;uuid&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">,</span>
+            <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
+            <span class="s2">&quot;displayname&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">display_name</span><span class="p">,</span>
+            <span class="s2">&quot;keyface&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">keyface</span><span class="p">,</span>
+            <span class="s2">&quot;facecount&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">facecount</span><span class="p">,</span>
+            <span class="s2">&quot;keyphoto&quot;</span><span class="p">:</span> <span class="n">keyphoto</span><span class="p">,</span>
+            <span class="s2">&quot;favorite&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">favorite</span><span class="p">,</span>
+            <span class="s2">&quot;sort_order&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">sort_order</span><span class="p">,</span>
+            <span class="s2">&quot;feature_less&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">feature_less</span><span class="p">,</span>
         <span class="p">}</span></div>
 
 <div class="viewcode-block" id="PersonInfo.json"><a class="viewcode-back" href="../../reference.html#osxphotos.PersonInfo.json">[docs]</a>    <span class="k">def</span> <span class="nf">json</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Returns JSON representation of class instance"""</span>
+        <span class="sd">&quot;&quot;&quot;Returns JSON representation of class instance&quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">asdict</span><span class="p">())</span></div>
 
     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="k">return</span> <span class="sa">f</span><span class="s2">"PersonInfo(name=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s2">, display_name=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">display_name</span><span class="si">}</span><span class="s2">, uuid=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2">, facecount=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">facecount</span><span class="si">}</span><span class="s2">)"</span>
+        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;PersonInfo(name=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s2">, display_name=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">display_name</span><span class="si">}</span><span class="s2">, uuid=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2">, facecount=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">facecount</span><span class="si">}</span><span class="s2">)&quot;</span>
 
     <span class="k">def</span> <span class="fm">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
         <span class="k">return</span> <span class="p">(</span>
             <span class="nb">all</span><span class="p">(</span>
                 <span class="nb">getattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span> <span class="o">==</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span>
-                <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">"_db"</span><span class="p">,</span> <span class="s2">"_pk"</span><span class="p">]</span>
+                <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">&quot;_db&quot;</span><span class="p">,</span> <span class="s2">&quot;_pk&quot;</span><span class="p">]</span>
             <span class="p">)</span>
             <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">))</span>
             <span class="k">else</span> <span class="kc">False</span>
@@ -302,10 +335,10 @@
 
 
 <span class="k">class</span> <span class="nc">FaceInfo</span><span class="p">:</span>
-    <span class="sd">"""Info about a face in the Photos library"""</span>
+    <span class="sd">&quot;&quot;&quot;Info about a face in the Photos library&quot;&quot;&quot;</span>
 
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">db</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">pk</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
-        <span class="sd">"""Creates a new FaceInfo instance</span>
+        <span class="sd">&quot;&quot;&quot;Creates a new FaceInfo instance</span>
 
 <span class="sd">        Arguments:</span>
 <span class="sd">            db: instance of PhotosDB object</span>
@@ -313,59 +346,59 @@
 
 <span class="sd">        Returns:</span>
 <span class="sd">            FaceInfo instance</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_db</span> <span class="o">=</span> <span class="n">db</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_pk</span> <span class="o">=</span> <span class="n">pk</span>
 
         <span class="n">face</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_faceinfo_pk</span><span class="p">[</span><span class="n">pk</span><span class="p">]</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_info</span> <span class="o">=</span> <span class="n">face</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"uuid"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"fullname"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">asset_uuid</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"asset_uuid"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">_person_pk</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"person"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">center_x</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"centerx"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">center_y</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"centery"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">size</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"size"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">quality</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"quality"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">source_width</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"sourcewidth"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">source_height</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"sourceheight"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">has_smile</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"has_smile"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">manual</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"manual"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">face_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"facetype"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">age_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"agetype"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">eye_makeup_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"eyemakeuptype"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">eye_state</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"eyestate"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">facial_hair_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"facialhairtype"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">gender_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"gendertype"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">glasses_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"glassestype"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">hair_color_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"haircolortype"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">intrash</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"intrash"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">lip_makeup_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"lipmakeuptype"</span><span class="p">]</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">smile_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">"smiletype"</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;uuid&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;fullname&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">asset_uuid</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;asset_uuid&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_person_pk</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;person&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">center_x</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;centerx&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">center_y</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;centery&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">size</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;size&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">quality</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;quality&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">source_width</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;sourcewidth&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">source_height</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;sourceheight&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">has_smile</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;has_smile&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">manual</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;manual&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">face_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;facetype&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">age_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;agetype&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">eye_makeup_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;eyemakeuptype&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">eye_state</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;eyestate&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">facial_hair_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;facialhairtype&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">gender_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;gendertype&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">glasses_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;glassestype&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">hair_color_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;haircolortype&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">intrash</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;intrash&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">lip_makeup_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;lipmakeuptype&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">smile_type</span> <span class="o">=</span> <span class="n">face</span><span class="p">[</span><span class="s2">&quot;smiletype&quot;</span><span class="p">]</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">center</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Coordinates, in PIL format, for center of face</span>
+        <span class="sd">&quot;&quot;&quot;Coordinates, in PIL format, for center of face</span>
 
 <span class="sd">        Returns:</span>
 <span class="sd">            tuple of coordinates in form (x, y)</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_make_point</span><span class="p">((</span><span class="bp">self</span><span class="o">.</span><span class="n">center_x</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">center_y</span><span class="p">))</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">size_pixels</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Size of face in pixels (centered around center_x, center_y)</span>
+        <span class="sd">&quot;&quot;&quot;Size of face in pixels (centered around center_x, center_y)</span>
 
 <span class="sd">        Returns:</span>
 <span class="sd">            size, in int pixels, of a circle drawn around the center of the face</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="n">photo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span>
         <span class="n">size_reference</span> <span class="o">=</span> <span class="n">photo</span><span class="o">.</span><span class="n">width</span> <span class="k">if</span> <span class="n">photo</span><span class="o">.</span><span class="n">width</span> <span class="o">&gt;</span> <span class="n">photo</span><span class="o">.</span><span class="n">height</span> <span class="k">else</span> <span class="n">photo</span><span class="o">.</span><span class="n">height</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">size</span> <span class="o">*</span> <span class="n">size_reference</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">person_info</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""PersonInfo instance for person associated with this face"""</span>
+        <span class="sd">&quot;&quot;&quot;PersonInfo instance for person associated with this face&quot;&quot;&quot;</span>
         <span class="k">try</span><span class="p">:</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_person</span>
         <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
@@ -374,18 +407,18 @@
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">photo</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""PhotoInfo instance associated with this face"""</span>
+        <span class="sd">&quot;&quot;&quot;PhotoInfo instance associated with this face&quot;&quot;&quot;</span>
         <span class="k">try</span><span class="p">:</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_photo</span>
         <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_photo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">get_photo</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">asset_uuid</span><span class="p">)</span>
             <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_photo</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-                <span class="n">logging</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Could not get photo for uuid: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">asset_uuid</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
+                <span class="n">logging</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Could not get photo for uuid: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">asset_uuid</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_photo</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">mwg_rs_area</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Get coordinates for Metadata Working Group Region Area.</span>
+        <span class="sd">&quot;&quot;&quot;Get coordinates for Metadata Working Group Region Area.</span>
 
 <span class="sd">        Returns:</span>
 <span class="sd">            MWG_RS_Area named tuple with x, y, h, w where:</span>
@@ -396,7 +429,7 @@
 
 <span class="sd">        Reference:</span>
 <span class="sd">            https://photo.stackexchange.com/questions/106410/how-does-xmp-define-the-face-region</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">center_x</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">center_y</span>
         <span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_fix_orientation</span><span class="p">((</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">))</span>
 
@@ -411,7 +444,7 @@
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">mpri_reg_rect</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Get coordinates for Microsoft Photo Region Rectangle.</span>
+        <span class="sd">&quot;&quot;&quot;Get coordinates for Microsoft Photo Region Rectangle.</span>
 
 <span class="sd">        Returns:</span>
 <span class="sd">            MPRI_Reg_Rect named tuple with x, y, h, w where:</span>
@@ -422,7 +455,7 @@
 
 <span class="sd">        Reference:</span>
 <span class="sd">            https://docs.microsoft.com/en-us/windows/win32/wic/-wic-people-tagging</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">center_x</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">center_y</span>
         <span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_fix_orientation</span><span class="p">((</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">))</span>
 
@@ -440,13 +473,13 @@
         <span class="k">return</span> <span class="n">MPRI_Reg_Rect</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">h</span><span class="p">,</span> <span class="n">w</span><span class="p">)</span>
 
     <span class="k">def</span> <span class="nf">face_rect</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Get face rectangle coordinates for current version of the associated image</span>
+        <span class="sd">&quot;&quot;&quot;Get face rectangle coordinates for current version of the associated image</span>
 <span class="sd">            If image has been edited, rectangle applies to edited version, otherwise original version</span>
 <span class="sd">            Coordinates in format and reference frame used by PIL</span>
 
 <span class="sd">        Returns:</span>
 <span class="sd">            list [(x0, x1), (y0, y1)] of coordinates in reference frame used by PIL</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="n">photo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span>
         <span class="n">size_reference</span> <span class="o">=</span> <span class="n">photo</span><span class="o">.</span><span class="n">width</span> <span class="k">if</span> <span class="n">photo</span><span class="o">.</span><span class="n">width</span> <span class="o">&gt;</span> <span class="n">photo</span><span class="o">.</span><span class="n">height</span> <span class="k">else</span> <span class="n">photo</span><span class="o">.</span><span class="n">height</span>
         <span class="n">radius</span> <span class="o">=</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">size</span> <span class="o">/</span> <span class="mi">2</span><span class="p">)</span> <span class="o">*</span> <span class="n">size_reference</span>
@@ -456,34 +489,34 @@
         <span class="k">return</span> <span class="p">[(</span><span class="n">x0</span><span class="p">,</span> <span class="n">y0</span><span class="p">),</span> <span class="p">(</span><span class="n">x1</span><span class="p">,</span> <span class="n">y1</span><span class="p">)]</span>
 
     <span class="k">def</span> <span class="nf">roll_pitch_yaw</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Roll, pitch, yaw of face in radians as tuple"""</span>
+        <span class="sd">&quot;&quot;&quot;Roll, pitch, yaw of face in radians as tuple&quot;&quot;&quot;</span>
         <span class="n">info</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span>
-        <span class="n">roll</span> <span class="o">=</span> <span class="mi">0</span> <span class="k">if</span> <span class="n">info</span><span class="p">[</span><span class="s2">"roll"</span><span class="p">]</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">info</span><span class="p">[</span><span class="s2">"roll"</span><span class="p">]</span>
-        <span class="n">pitch</span> <span class="o">=</span> <span class="mi">0</span> <span class="k">if</span> <span class="n">info</span><span class="p">[</span><span class="s2">"pitch"</span><span class="p">]</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">info</span><span class="p">[</span><span class="s2">"pitch"</span><span class="p">]</span>
-        <span class="n">yaw</span> <span class="o">=</span> <span class="mi">0</span> <span class="k">if</span> <span class="n">info</span><span class="p">[</span><span class="s2">"yaw"</span><span class="p">]</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">info</span><span class="p">[</span><span class="s2">"yaw"</span><span class="p">]</span>
+        <span class="n">roll</span> <span class="o">=</span> <span class="mi">0</span> <span class="k">if</span> <span class="n">info</span><span class="p">[</span><span class="s2">&quot;roll&quot;</span><span class="p">]</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">info</span><span class="p">[</span><span class="s2">&quot;roll&quot;</span><span class="p">]</span>
+        <span class="n">pitch</span> <span class="o">=</span> <span class="mi">0</span> <span class="k">if</span> <span class="n">info</span><span class="p">[</span><span class="s2">&quot;pitch&quot;</span><span class="p">]</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">info</span><span class="p">[</span><span class="s2">&quot;pitch&quot;</span><span class="p">]</span>
+        <span class="n">yaw</span> <span class="o">=</span> <span class="mi">0</span> <span class="k">if</span> <span class="n">info</span><span class="p">[</span><span class="s2">&quot;yaw&quot;</span><span class="p">]</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">info</span><span class="p">[</span><span class="s2">&quot;yaw&quot;</span><span class="p">]</span>
 
         <span class="k">return</span> <span class="p">(</span><span class="n">roll</span><span class="p">,</span> <span class="n">pitch</span><span class="p">,</span> <span class="n">yaw</span><span class="p">)</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">roll</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Return roll angle in radians of the face region"""</span>
+        <span class="sd">&quot;&quot;&quot;Return roll angle in radians of the face region&quot;&quot;&quot;</span>
         <span class="n">roll</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">roll_pitch_yaw</span><span class="p">()</span>
         <span class="k">return</span> <span class="n">roll</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">pitch</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Return pitch angle in radians of the face region"""</span>
+        <span class="sd">&quot;&quot;&quot;Return pitch angle in radians of the face region&quot;&quot;&quot;</span>
         <span class="n">_</span><span class="p">,</span> <span class="n">pitch</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">roll_pitch_yaw</span><span class="p">()</span>
         <span class="k">return</span> <span class="n">pitch</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">yaw</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Return yaw angle in radians of the face region"""</span>
+        <span class="sd">&quot;&quot;&quot;Return yaw angle in radians of the face region&quot;&quot;&quot;</span>
         <span class="n">_</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="n">yaw</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">roll_pitch_yaw</span><span class="p">()</span>
         <span class="k">return</span> <span class="n">yaw</span>
 
     <span class="k">def</span> <span class="nf">_fix_orientation</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">xy</span><span class="p">):</span>
-        <span class="sd">"""Translate an (x, y) tuple based on image orientation</span>
+        <span class="sd">&quot;&quot;&quot;Translate an (x, y) tuple based on image orientation</span>
 
 <span class="sd">        Arguments:</span>
 <span class="sd">            xy: tuple of (x, y) coordinates for point to translate</span>
@@ -491,7 +524,7 @@
 
 <span class="sd">        Returns:</span>
 <span class="sd">            (x, y) tuple of translated coordinates</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="c1"># Reference: https://github.com/neilpa/phace/blob/7594776480505d0c389688a42099c94ac5d34f3f/cmd/phace/draw.go#L79-L94</span>
 
         <span class="n">orientation</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">orientation</span>
@@ -515,15 +548,15 @@
         <span class="k">elif</span> <span class="n">orientation</span> <span class="o">==</span> <span class="mi">8</span><span class="p">:</span>
             <span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="n">y</span><span class="p">,</span> <span class="n">x</span>
         <span class="k">elif</span> <span class="n">orientation</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
-            <span class="c1"># set by osxphotos if adjusted orientation cannot be read, assume it's 1</span>
+            <span class="c1"># set by osxphotos if adjusted orientation cannot be read, assume it&#39;s 1</span>
             <span class="n">y</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="o">-</span> <span class="n">y</span>
         <span class="k">else</span><span class="p">:</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Unhandled orientation: </span><span class="si">{</span><span class="n">orientation</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
+            <span class="n">logging</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Unhandled orientation: </span><span class="si">{</span><span class="n">orientation</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
 
         <span class="k">return</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
 
     <span class="k">def</span> <span class="nf">_make_point</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">xy</span><span class="p">):</span>
-        <span class="sd">"""Translate an (x, y) tuple based on image orientation</span>
+        <span class="sd">&quot;&quot;&quot;Translate an (x, y) tuple based on image orientation</span>
 <span class="sd">            and convert to image coordinates</span>
 
 <span class="sd">        Arguments:</span>
@@ -532,7 +565,7 @@
 
 <span class="sd">        Returns:</span>
 <span class="sd">            (x, y) tuple of translated coordinates in pixels in PIL format/reference frame</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="c1"># Reference: https://github.com/neilpa/phace/blob/7594776480505d0c389688a42099c94ac5d34f3f/cmd/phace/draw.go#L79-L94</span>
 
         <span class="n">orientation</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">orientation</span>
@@ -544,7 +577,7 @@
         <span class="k">return</span> <span class="p">(</span><span class="nb">int</span><span class="p">(</span><span class="n">x</span> <span class="o">*</span> <span class="n">dx</span><span class="p">),</span> <span class="nb">int</span><span class="p">(</span><span class="n">y</span> <span class="o">*</span> <span class="n">dy</span><span class="p">))</span>
 
     <span class="k">def</span> <span class="nf">_make_point_with_rotation</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">xy</span><span class="p">):</span>
-        <span class="sd">"""Translate an (x, y) tuple based on image orientation and rotation</span>
+        <span class="sd">&quot;&quot;&quot;Translate an (x, y) tuple based on image orientation and rotation</span>
 <span class="sd">            and convert to image coordinates</span>
 
 <span class="sd">        Arguments:</span>
@@ -553,7 +586,7 @@
 
 <span class="sd">        Returns:</span>
 <span class="sd">            (x, y) tuple of translated coordinates in pixels in PIL format/reference frame</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
 
         <span class="c1"># convert to image coordinates</span>
         <span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_make_point</span><span class="p">(</span><span class="n">xy</span><span class="p">)</span>
@@ -566,58 +599,58 @@
         <span class="k">return</span> <span class="p">(</span><span class="nb">int</span><span class="p">(</span><span class="n">xr</span><span class="p">),</span> <span class="nb">int</span><span class="p">(</span><span class="n">yr</span><span class="p">))</span>
 
     <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Returns dict representation of class instance"""</span>
+        <span class="sd">&quot;&quot;&quot;Returns dict representation of class instance&quot;&quot;&quot;</span>
         <span class="n">roll</span><span class="p">,</span> <span class="n">pitch</span><span class="p">,</span> <span class="n">yaw</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">roll_pitch_yaw</span><span class="p">()</span>
         <span class="k">return</span> <span class="p">{</span>
-            <span class="s2">"_pk"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">_pk</span><span class="p">,</span>
-            <span class="s2">"uuid"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">,</span>
-            <span class="s2">"name"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
-            <span class="s2">"asset_uuid"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">asset_uuid</span><span class="p">,</span>
-            <span class="s2">"_person_pk"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">_person_pk</span><span class="p">,</span>
-            <span class="s2">"center_x"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">center_x</span><span class="p">,</span>
-            <span class="s2">"center_y"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">center_y</span><span class="p">,</span>
-            <span class="s2">"center"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">center</span><span class="p">,</span>
-            <span class="s2">"size"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">size</span><span class="p">,</span>
-            <span class="s2">"face_rect"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">face_rect</span><span class="p">(),</span>
-            <span class="s2">"mpri_reg_rect"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">mpri_reg_rect</span><span class="o">.</span><span class="n">_asdict</span><span class="p">(),</span>
-            <span class="s2">"mwg_rs_area"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">mwg_rs_area</span><span class="o">.</span><span class="n">_asdict</span><span class="p">(),</span>
-            <span class="s2">"roll"</span><span class="p">:</span> <span class="n">roll</span><span class="p">,</span>
-            <span class="s2">"pitch"</span><span class="p">:</span> <span class="n">pitch</span><span class="p">,</span>
-            <span class="s2">"yaw"</span><span class="p">:</span> <span class="n">yaw</span><span class="p">,</span>
-            <span class="s2">"quality"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">quality</span><span class="p">,</span>
-            <span class="s2">"source_width"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">source_width</span><span class="p">,</span>
-            <span class="s2">"source_height"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">source_height</span><span class="p">,</span>
-            <span class="s2">"has_smile"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">has_smile</span><span class="p">,</span>
-            <span class="s2">"manual"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">manual</span><span class="p">,</span>
-            <span class="s2">"face_type"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">face_type</span><span class="p">,</span>
-            <span class="s2">"age_type"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">age_type</span><span class="p">,</span>
-            <span class="s2">"eye_makeup_type"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">eye_makeup_type</span><span class="p">,</span>
-            <span class="s2">"eye_state"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">eye_state</span><span class="p">,</span>
-            <span class="s2">"facial_hair_type"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">facial_hair_type</span><span class="p">,</span>
-            <span class="s2">"gender_type"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">gender_type</span><span class="p">,</span>
-            <span class="s2">"glasses_type"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">glasses_type</span><span class="p">,</span>
-            <span class="s2">"hair_color_type"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">hair_color_type</span><span class="p">,</span>
-            <span class="s2">"intrash"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">intrash</span><span class="p">,</span>
-            <span class="s2">"lip_makeup_type"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">lip_makeup_type</span><span class="p">,</span>
-            <span class="s2">"smile_type"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">smile_type</span><span class="p">,</span>
+            <span class="s2">&quot;_pk&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">_pk</span><span class="p">,</span>
+            <span class="s2">&quot;uuid&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">,</span>
+            <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
+            <span class="s2">&quot;asset_uuid&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">asset_uuid</span><span class="p">,</span>
+            <span class="s2">&quot;_person_pk&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">_person_pk</span><span class="p">,</span>
+            <span class="s2">&quot;center_x&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">center_x</span><span class="p">,</span>
+            <span class="s2">&quot;center_y&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">center_y</span><span class="p">,</span>
+            <span class="s2">&quot;center&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">center</span><span class="p">,</span>
+            <span class="s2">&quot;size&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">size</span><span class="p">,</span>
+            <span class="s2">&quot;face_rect&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">face_rect</span><span class="p">(),</span>
+            <span class="s2">&quot;mpri_reg_rect&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">mpri_reg_rect</span><span class="o">.</span><span class="n">_asdict</span><span class="p">(),</span>
+            <span class="s2">&quot;mwg_rs_area&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">mwg_rs_area</span><span class="o">.</span><span class="n">_asdict</span><span class="p">(),</span>
+            <span class="s2">&quot;roll&quot;</span><span class="p">:</span> <span class="n">roll</span><span class="p">,</span>
+            <span class="s2">&quot;pitch&quot;</span><span class="p">:</span> <span class="n">pitch</span><span class="p">,</span>
+            <span class="s2">&quot;yaw&quot;</span><span class="p">:</span> <span class="n">yaw</span><span class="p">,</span>
+            <span class="s2">&quot;quality&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">quality</span><span class="p">,</span>
+            <span class="s2">&quot;source_width&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">source_width</span><span class="p">,</span>
+            <span class="s2">&quot;source_height&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">source_height</span><span class="p">,</span>
+            <span class="s2">&quot;has_smile&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">has_smile</span><span class="p">,</span>
+            <span class="s2">&quot;manual&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">manual</span><span class="p">,</span>
+            <span class="s2">&quot;face_type&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">face_type</span><span class="p">,</span>
+            <span class="s2">&quot;age_type&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">age_type</span><span class="p">,</span>
+            <span class="s2">&quot;eye_makeup_type&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">eye_makeup_type</span><span class="p">,</span>
+            <span class="s2">&quot;eye_state&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">eye_state</span><span class="p">,</span>
+            <span class="s2">&quot;facial_hair_type&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">facial_hair_type</span><span class="p">,</span>
+            <span class="s2">&quot;gender_type&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">gender_type</span><span class="p">,</span>
+            <span class="s2">&quot;glasses_type&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">glasses_type</span><span class="p">,</span>
+            <span class="s2">&quot;hair_color_type&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">hair_color_type</span><span class="p">,</span>
+            <span class="s2">&quot;intrash&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">intrash</span><span class="p">,</span>
+            <span class="s2">&quot;lip_makeup_type&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">lip_makeup_type</span><span class="p">,</span>
+            <span class="s2">&quot;smile_type&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">smile_type</span><span class="p">,</span>
         <span class="p">}</span>
 
     <span class="k">def</span> <span class="nf">json</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Return JSON representation of FaceInfo instance"""</span>
+        <span class="sd">&quot;&quot;&quot;Return JSON representation of FaceInfo instance&quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">asdict</span><span class="p">())</span>
 
     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="k">return</span> <span class="sa">f</span><span class="s2">"FaceInfo(uuid=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2">, center_x=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">center_x</span><span class="si">}</span><span class="s2">, center_y = </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">center_y</span><span class="si">}</span><span class="s2">, size=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">size</span><span class="si">}</span><span class="s2">, person=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s2">, asset_uuid=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">asset_uuid</span><span class="si">}</span><span class="s2">)"</span>
+        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;FaceInfo(uuid=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2">, center_x=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">center_x</span><span class="si">}</span><span class="s2">, center_y = </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">center_y</span><span class="si">}</span><span class="s2">, size=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">size</span><span class="si">}</span><span class="s2">, person=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s2">, asset_uuid=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">asset_uuid</span><span class="si">}</span><span class="s2">)&quot;</span>
 
     <span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="k">return</span> <span class="sa">f</span><span class="s2">"FaceInfo(db=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="si">}</span><span class="s2">, pk=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_pk</span><span class="si">}</span><span class="s2">)"</span>
+        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;FaceInfo(db=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="si">}</span><span class="s2">, pk=</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_pk</span><span class="si">}</span><span class="s2">)&quot;</span>
 
     <span class="k">def</span> <span class="fm">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
         <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)):</span>
             <span class="k">return</span> <span class="kc">False</span>
 
         <span class="k">return</span> <span class="nb">all</span><span class="p">(</span>
-            <span class="nb">getattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span> <span class="o">==</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span> <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">"_db"</span><span class="p">,</span> <span class="s2">"_pk"</span><span class="p">]</span>
+            <span class="nb">getattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span> <span class="o">==</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span> <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">&quot;_db&quot;</span><span class="p">,</span> <span class="s2">&quot;_pk&quot;</span><span class="p">]</span>
         <span class="p">)</span>
 
     <span class="k">def</span> <span class="fm">__ne__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
@@ -625,7 +658,7 @@
 
 
 <span class="k">def</span> <span class="nf">rotate_image_point</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">xmid</span><span class="p">,</span> <span class="n">ymid</span><span class="p">,</span> <span class="n">angle</span><span class="p">):</span>
-    <span class="sd">"""rotate image point about xm, ym by angle in radians</span>
+    <span class="sd">&quot;&quot;&quot;rotate image point about xm, ym by angle in radians</span>
 
 <span class="sd">    Arguments:</span>
 <span class="sd">        x: x coordinate of point to rotate</span>
@@ -637,7 +670,7 @@
 
 <span class="sd">    Returns:</span>
 <span class="sd">        tuple of rotated points (xr, yr)</span>
-<span class="sd">    """</span>
+<span class="sd">    &quot;&quot;&quot;</span>
     <span class="c1"># translate point relative to the mid point</span>
     <span class="n">x</span> <span class="o">=</span> <span class="n">x</span> <span class="o">-</span> <span class="n">xmid</span>
     <span class="n">y</span> <span class="o">=</span> <span class="n">y</span> <span class="o">-</span> <span class="n">ymid</span>
@@ -688,7 +721,9 @@
 </div><script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
     <script src="../../_static/jquery.js"></script>
     <script src="../../_static/underscore.js"></script>
+    <script src="../../_static/_sphinx_javascript_frameworks_compat.js"></script>
     <script src="../../_static/doctools.js"></script>
+    <script src="../../_static/sphinx_highlight.js"></script>
     <script src="../../_static/scripts/furo.js"></script>
     <script src="../../_static/clipboard.min.js"></script>
     <script src="../../_static/copybutton.js"></script>

docs/_modules/osxphotos/photoexporter.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>osxphotos.photoexporter - osxphotos 0.55.6 documentation</title>
+        <title>osxphotos.photoexporter - osxphotos 0.60.2 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.55.6 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.60.2 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.55.6 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.2 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -198,6 +198,8 @@
 <span></span><span class="sd">&quot;&quot;&quot; PhotoExport class to export photos</span>
 <span class="sd">&quot;&quot;&quot;</span>
 
+<span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">annotations</span>
+
 <span class="kn">import</span> <span class="nn">dataclasses</span>
 <span class="kn">import</span> <span class="nn">json</span>
 <span class="kn">import</span> <span class="nn">logging</span>
@@ -205,12 +207,11 @@
 <span class="kn">import</span> <span class="nn">pathlib</span>
 <span class="kn">import</span> <span class="nn">re</span>
 <span class="kn">import</span> <span class="nn">typing</span> <span class="k">as</span> <span class="nn">t</span>
-<span class="kn">from</span> <span class="nn">collections</span> <span class="kn">import</span> <span class="n">namedtuple</span>  <span class="c1"># pylint: disable=syntax-error</span>
 <span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">asdict</span><span class="p">,</span> <span class="n">dataclass</span>
 <span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span>
 <span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">Enum</span>
+<span class="kn">from</span> <span class="nn">types</span> <span class="kn">import</span> <span class="n">SimpleNamespace</span>
 
-<span class="kn">import</span> <span class="nn">photoscript</span>
 <span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
 
 <span class="kn">from</span> <span class="nn">._constants</span> <span class="kn">import</span> <span class="p">(</span>
@@ -228,16 +229,9 @@
 <span class="p">)</span>
 <span class="kn">from</span> <span class="nn">._version</span> <span class="kn">import</span> <span class="n">__version__</span>
 <span class="kn">from</span> <span class="nn">.datetime_utils</span> <span class="kn">import</span> <span class="n">datetime_tz_to_utc</span>
-<span class="kn">from</span> <span class="nn">.exiftool</span> <span class="kn">import</span> <span class="n">ExifTool</span><span class="p">,</span> <span class="n">exiftool_can_write</span>
+<span class="kn">from</span> <span class="nn">.exiftool</span> <span class="kn">import</span> <span class="n">ExifTool</span><span class="p">,</span> <span class="n">ExifToolCaching</span><span class="p">,</span> <span class="n">exiftool_can_write</span><span class="p">,</span> <span class="n">get_exiftool_path</span>
 <span class="kn">from</span> <span class="nn">.export_db</span> <span class="kn">import</span> <span class="n">ExportDB</span><span class="p">,</span> <span class="n">ExportDBTemp</span>
 <span class="kn">from</span> <span class="nn">.fileutil</span> <span class="kn">import</span> <span class="n">FileUtil</span>
-<span class="kn">from</span> <span class="nn">.photokit</span> <span class="kn">import</span> <span class="p">(</span>
-    <span class="n">PHOTOS_VERSION_CURRENT</span><span class="p">,</span>
-    <span class="n">PHOTOS_VERSION_ORIGINAL</span><span class="p">,</span>
-    <span class="n">PHOTOS_VERSION_UNADJUSTED</span><span class="p">,</span>
-    <span class="n">PhotoKitFetchFailed</span><span class="p">,</span>
-    <span class="n">PhotoLibrary</span><span class="p">,</span>
-<span class="p">)</span>
 <span class="kn">from</span> <span class="nn">.phototemplate</span> <span class="kn">import</span> <span class="n">RenderOptions</span>
 <span class="kn">from</span> <span class="nn">.rich_utils</span> <span class="kn">import</span> <span class="n">add_rich_markup_tag</span>
 <span class="kn">from</span> <span class="nn">.uti</span> <span class="kn">import</span> <span class="n">get_preferred_uti_extension</span>
@@ -245,10 +239,26 @@
     <span class="n">hexdigest</span><span class="p">,</span>
     <span class="n">increment_filename</span><span class="p">,</span>
     <span class="n">increment_filename_with_count</span><span class="p">,</span>
+    <span class="n">is_macos</span><span class="p">,</span>
     <span class="n">lineno</span><span class="p">,</span>
     <span class="n">list_directory</span><span class="p">,</span>
+    <span class="n">lock_filename</span><span class="p">,</span>
+    <span class="n">normalize_fs_path</span><span class="p">,</span>
+    <span class="n">unlock_filename</span><span class="p">,</span>
 <span class="p">)</span>
 
+<span class="k">if</span> <span class="n">is_macos</span><span class="p">:</span>
+    <span class="kn">import</span> <span class="nn">photoscript</span>
+
+    <span class="kn">from</span> <span class="nn">.photokit</span> <span class="kn">import</span> <span class="p">(</span>
+        <span class="n">PHOTOS_VERSION_CURRENT</span><span class="p">,</span>
+        <span class="n">PHOTOS_VERSION_ORIGINAL</span><span class="p">,</span>
+        <span class="n">PHOTOS_VERSION_UNADJUSTED</span><span class="p">,</span>
+        <span class="n">PhotoKitFetchFailed</span><span class="p">,</span>
+        <span class="n">PhotoLibrary</span><span class="p">,</span>
+    <span class="p">)</span>
+
+
 <span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span>
     <span class="s2">&quot;ExportError&quot;</span><span class="p">,</span>
     <span class="s2">&quot;ExportOptions&quot;</span><span class="p">,</span>
@@ -263,6 +273,11 @@
 <span class="c1"># retry if download_missing/use_photos_export fails the first time (which sometimes it does)</span>
 <span class="n">MAX_PHOTOSCRIPT_RETRIES</span> <span class="o">=</span> <span class="mi">3</span>
 
+<span class="c1"># Global to hold the compiled XMP template</span>
+<span class="c1"># This is expensive to compile so we only want to do it once</span>
+<span class="n">_global_xmp_template</span><span class="p">:</span> <span class="n">Template</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
+
+
 <span class="c1"># return values for _should_update_photo</span>
 <span class="k">class</span> <span class="nc">ShouldUpdate</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>
     <span class="n">NOT_IN_DATABASE</span> <span class="o">=</span> <span class="mi">1</span>
@@ -430,6 +445,9 @@
     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="k">return</span> <span class="nb">str</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">asdict</span><span class="p">())</span>
 
+    <span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;StagedFiles(</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span><span class="si">}</span><span class="s2">)&quot;</span>
+
     <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="k">return</span> <span class="p">{</span>
             <span class="s2">&quot;original&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">original</span><span class="p">,</span>
@@ -504,7 +522,6 @@
         <span class="n">xattr_skipped</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
         <span class="n">xattr_written</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
     <span class="p">):</span>
-
         <span class="n">local_vars</span> <span class="o">=</span> <span class="nb">locals</span><span class="p">()</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_datetime</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span>
         <span class="k">for</span> <span class="n">attr</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">attributes</span><span class="p">:</span>
@@ -569,7 +586,7 @@
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">photo</span><span class="p">:</span> <span class="s2">&quot;PhotoInfo&quot;</span><span class="p">,</span> <span class="n">tmpdir</span><span class="p">:</span> <span class="n">t</span><span class="o">.</span><span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">photo</span> <span class="o">=</span> <span class="n">photo</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_render_options</span> <span class="o">=</span> <span class="n">RenderOptions</span><span class="p">()</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">_verbose</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">_verbose</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_verbose</span> <span class="o">=</span> <span class="n">photo</span><span class="o">.</span><span class="n">_verbose</span>
 
         <span class="c1"># define functions for adding markup</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_filepath</span> <span class="o">=</span> <span class="n">add_rich_markup_tag</span><span class="p">(</span><span class="s2">&quot;filepath&quot;</span><span class="p">,</span> <span class="n">rich</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
@@ -666,6 +683,11 @@
         <span class="n">dest</span><span class="p">,</span> <span class="n">options</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_should_convert_to_jpeg</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">options</span><span class="p">)</span>
 
         <span class="c1"># stage files for export by finding path in local library or downloading from iCloud as appropriate</span>
+        <span class="c1"># for `--download-missing` and `--update` case, this may cause unnecessary downloads</span>
+        <span class="c1"># as it will download the file even if it&#39;s not needed (won&#39;t be checked until the _should_update_photo() call from _export_photo()</span>
+        <span class="c1"># fixing this will require major refactoring of the export code, see #1086</span>
+        <span class="c1"># leaving it for now as this should not be a common use case</span>
+        <span class="c1"># (if using `--update` it is much better to be using &quot;Download originals to this Mac&quot; in Photos)</span>
         <span class="n">staged_files</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_stage_photos_for_export</span><span class="p">(</span><span class="n">options</span><span class="p">)</span>
         <span class="n">src</span> <span class="o">=</span> <span class="n">staged_files</span><span class="o">.</span><span class="n">edited</span> <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">edited</span> <span class="k">else</span> <span class="n">staged_files</span><span class="o">.</span><span class="n">original</span>
 
@@ -687,6 +709,7 @@
                 <span class="sa">f</span><span class="s2">&quot;Skipping missing </span><span class="si">{</span><span class="s1">&#39;edited&#39;</span> <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">edited</span> <span class="k">else</span> <span class="s1">&#39;original&#39;</span><span class="si">}</span><span class="s2"> photo </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_filename</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">original_filename</span><span class="p">)</span><span class="si">}</span><span class="s2"> (</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">uuid</span><span class="p">)</span><span class="si">}</span><span class="s2">)&quot;</span>
             <span class="p">)</span>
             <span class="n">all_results</span><span class="o">.</span><span class="n">missing</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
+            <span class="n">unlock_filename</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
 
         <span class="c1"># copy live photo associated .mov if requested</span>
         <span class="k">if</span> <span class="n">export_original</span> <span class="ow">and</span> <span class="n">options</span><span class="o">.</span><span class="n">live_photo</span> <span class="ow">and</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">live_photo</span><span class="p">:</span>
@@ -762,7 +785,9 @@
                 <span class="n">preview_name</span> <span class="o">=</span> <span class="p">(</span>
                     <span class="n">preview_name</span>
                     <span class="k">if</span> <span class="nb">any</span><span class="p">([</span><span class="n">options</span><span class="o">.</span><span class="n">overwrite</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">update</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">force_update</span><span class="p">])</span>
-                    <span class="k">else</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="n">increment_filename</span><span class="p">(</span><span class="n">preview_name</span><span class="p">))</span>
+                    <span class="k">else</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span>
+                        <span class="n">increment_filename</span><span class="p">(</span><span class="n">preview_name</span><span class="p">,</span> <span class="n">lock</span><span class="o">=</span><span class="ow">not</span> <span class="n">options</span><span class="o">.</span><span class="n">dry_run</span><span class="p">)</span>
+                    <span class="p">)</span>
                 <span class="p">)</span>
                 <span class="n">all_results</span> <span class="o">+=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_export_photo</span><span class="p">(</span>
                     <span class="n">preview_path</span><span class="p">,</span>
@@ -822,11 +847,10 @@
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">path_edited</span><span class="p">:</span>
             <span class="n">ext</span> <span class="o">=</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">path_edited</span><span class="p">)</span><span class="o">.</span><span class="n">suffix</span>
         <span class="k">else</span><span class="p">:</span>
-            <span class="n">uti</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">uti_edited</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">uti_edited</span> <span class="k">else</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">uti</span>
+            <span class="n">uti</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">uti_edited</span> <span class="ow">or</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">uti</span>
             <span class="n">ext</span> <span class="o">=</span> <span class="n">get_preferred_uti_extension</span><span class="p">(</span><span class="n">uti</span><span class="p">)</span>
-            <span class="n">ext</span> <span class="o">=</span> <span class="s2">&quot;.&quot;</span> <span class="o">+</span> <span class="n">ext</span>
-        <span class="n">edited_filename</span> <span class="o">=</span> <span class="n">original_filename</span><span class="o">.</span><span class="n">stem</span> <span class="o">+</span> <span class="s2">&quot;_edited&quot;</span> <span class="o">+</span> <span class="n">ext</span>
-        <span class="k">return</span> <span class="n">edited_filename</span>
+            <span class="n">ext</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;.</span><span class="si">{</span><span class="n">ext</span><span class="si">}</span><span class="s2">&quot;</span>
+        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">original_filename</span><span class="o">.</span><span class="n">stem</span><span class="si">}</span><span class="s2">_edited</span><span class="si">{</span><span class="n">ext</span><span class="si">}</span><span class="s2">&quot;</span>
 
     <span class="k">def</span> <span class="nf">_get_dest_path</span><span class="p">(</span>
         <span class="bp">self</span><span class="p">,</span> <span class="n">dest</span><span class="p">:</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">,</span> <span class="n">options</span><span class="p">:</span> <span class="n">ExportOptions</span>
@@ -841,16 +865,32 @@
 <span class="sd">            new dest path (pathlib.Path)</span>
 <span class="sd">        &quot;&quot;&quot;</span>
 
+        <span class="c1"># lock files are used to minimize chance of name collision when in parallel mode</span>
+        <span class="c1"># don&#39;t create lock files if in dry_run mode</span>
+        <span class="n">lock</span> <span class="o">=</span> <span class="ow">not</span> <span class="n">options</span><span class="o">.</span><span class="n">dry_run</span>
+
+        <span class="k">def</span> <span class="nf">_lock_filename</span><span class="p">(</span><span class="n">filename</span><span class="p">):</span>
+            <span class="sd">&quot;&quot;&quot;Lock filename if not in dry_run mode&quot;&quot;&quot;</span>
+            <span class="k">return</span> <span class="n">lock_filename</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span> <span class="k">if</span> <span class="n">lock</span> <span class="k">else</span> <span class="n">filename</span>
+
         <span class="c1"># if overwrite==False and #increment==False, export should fail if file exists</span>
-        <span class="k">if</span> <span class="n">dest</span><span class="o">.</span><span class="n">exists</span><span class="p">()</span> <span class="ow">and</span> <span class="ow">not</span> <span class="nb">any</span><span class="p">(</span>
-            <span class="p">[</span><span class="n">options</span><span class="o">.</span><span class="n">increment</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">update</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">force_update</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">overwrite</span><span class="p">]</span>
+        <span class="k">if</span> <span class="p">(</span>
+            <span class="ow">not</span> <span class="nb">any</span><span class="p">(</span>
+                <span class="p">[</span>
+                    <span class="n">options</span><span class="o">.</span><span class="n">increment</span><span class="p">,</span>
+                    <span class="n">options</span><span class="o">.</span><span class="n">update</span><span class="p">,</span>
+                    <span class="n">options</span><span class="o">.</span><span class="n">force_update</span><span class="p">,</span>
+                    <span class="n">options</span><span class="o">.</span><span class="n">overwrite</span><span class="p">,</span>
+                <span class="p">]</span>
+            <span class="p">)</span>
+            <span class="ow">and</span> <span class="n">dest</span><span class="o">.</span><span class="n">exists</span><span class="p">()</span>
         <span class="p">):</span>
             <span class="k">raise</span> <span class="ne">FileExistsError</span><span class="p">(</span>
                 <span class="sa">f</span><span class="s2">&quot;destination exists (</span><span class="si">{</span><span class="n">dest</span><span class="si">}</span><span class="s2">); overwrite=</span><span class="si">{</span><span class="n">options</span><span class="o">.</span><span class="n">overwrite</span><span class="si">}</span><span class="s2">, increment=</span><span class="si">{</span><span class="n">options</span><span class="o">.</span><span class="n">increment</span><span class="si">}</span><span class="s2">&quot;</span>
             <span class="p">)</span>
 
         <span class="c1"># if overwrite, we don&#39;t care if the file exists or not</span>
-        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">overwrite</span><span class="p">:</span>
+        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">overwrite</span> <span class="ow">and</span> <span class="n">_lock_filename</span><span class="p">(</span><span class="n">dest</span><span class="p">):</span>
             <span class="k">return</span> <span class="n">dest</span>
 
         <span class="c1"># if not update or overwrite, check to see if file exists and if so, add (1), (2), etc</span>
@@ -862,19 +902,21 @@
         <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">increment</span> <span class="ow">and</span> <span class="ow">not</span> <span class="nb">any</span><span class="p">(</span>
             <span class="p">[</span><span class="n">options</span><span class="o">.</span><span class="n">update</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">force_update</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">overwrite</span><span class="p">]</span>
         <span class="p">):</span>
-            <span class="k">return</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="n">increment_filename</span><span class="p">(</span><span class="n">dest</span><span class="p">))</span>
+            <span class="k">return</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="n">increment_filename</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">lock</span><span class="o">=</span><span class="n">lock</span><span class="p">))</span>
 
         <span class="c1"># if update and file exists, need to check to see if it&#39;s the right file by checking export db</span>
         <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">update</span> <span class="ow">or</span> <span class="n">options</span><span class="o">.</span><span class="n">force_update</span><span class="p">:</span>
             <span class="n">export_db</span> <span class="o">=</span> <span class="n">options</span><span class="o">.</span><span class="n">export_db</span>
             <span class="n">dest_uuid</span> <span class="o">=</span> <span class="n">export_db</span><span class="o">.</span><span class="n">get_uuid_for_file</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
-            <span class="k">if</span> <span class="n">dest_uuid</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">dest</span><span class="o">.</span><span class="n">exists</span><span class="p">():</span>
+            <span class="k">if</span> <span class="n">dest_uuid</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">dest</span><span class="o">.</span><span class="n">exists</span><span class="p">()</span> <span class="ow">and</span> <span class="n">_lock_filename</span><span class="p">(</span><span class="n">dest</span><span class="p">):</span>
                 <span class="c1"># destination doesn&#39;t exist in export db and doesn&#39;t exist on disk</span>
                 <span class="c1"># so we can just use it</span>
                 <span class="k">return</span> <span class="n">dest</span>
 
             <span class="k">if</span> <span class="n">dest_uuid</span> <span class="o">==</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">uuid</span><span class="p">:</span>
                 <span class="c1"># destination is the right file</span>
+                <span class="c1"># will use it even if locked so don&#39;t check return value of _lock_filename</span>
+                <span class="n">_lock_filename</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
                 <span class="k">return</span> <span class="n">dest</span>
 
             <span class="c1"># either dest_uuid is wrong or file exists and there&#39;s no associated UUID, so find a name that matches</span>
@@ -883,24 +925,35 @@
             <span class="c1"># first, find all matching files in export db and see if there&#39;s a match</span>
             <span class="k">if</span> <span class="n">dest_target</span> <span class="o">:=</span> <span class="n">export_db</span><span class="o">.</span><span class="n">get_target_for_file</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">uuid</span><span class="p">,</span> <span class="n">dest</span><span class="p">):</span>
                 <span class="c1"># there&#39;s a match so use that</span>
+                <span class="n">_lock_filename</span><span class="p">(</span><span class="n">dest_target</span><span class="p">)</span>
                 <span class="k">return</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="n">dest_target</span><span class="p">)</span>
 
             <span class="c1"># no match so need to create a new name</span>
             <span class="c1"># increment the destination file until we find one that doesn&#39;t exist and doesn&#39;t match another uuid in the database</span>
             <span class="n">count</span> <span class="o">=</span> <span class="mi">0</span>
-            <span class="n">dest</span><span class="p">,</span> <span class="n">count</span> <span class="o">=</span> <span class="n">increment_filename_with_count</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">count</span><span class="p">)</span>
+            <span class="n">dest</span><span class="p">,</span> <span class="n">count</span> <span class="o">=</span> <span class="n">increment_filename_with_count</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">count</span><span class="p">,</span> <span class="n">lock</span><span class="o">=</span><span class="n">lock</span><span class="p">)</span>
             <span class="n">count</span> <span class="o">+=</span> <span class="mi">1</span>
             <span class="k">while</span> <span class="n">export_db</span><span class="o">.</span><span class="n">get_uuid_for_file</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
-                <span class="n">dest</span><span class="p">,</span> <span class="n">count</span> <span class="o">=</span> <span class="n">increment_filename_with_count</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">count</span><span class="p">)</span>
+                <span class="n">dest</span><span class="p">,</span> <span class="n">count</span> <span class="o">=</span> <span class="n">increment_filename_with_count</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">count</span><span class="p">,</span> <span class="n">lock</span><span class="o">=</span><span class="n">lock</span><span class="p">)</span>
             <span class="k">return</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
 
         <span class="c1"># fail safe...I can&#39;t think of a case that gets here</span>
+        <span class="n">_lock_filename</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
         <span class="k">return</span> <span class="n">dest</span>
 
     <span class="k">def</span> <span class="nf">_should_update_photo</span><span class="p">(</span>
-        <span class="bp">self</span><span class="p">,</span> <span class="n">src</span><span class="p">:</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">,</span> <span class="n">dest</span><span class="p">:</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">,</span> <span class="n">options</span><span class="p">:</span> <span class="n">ExportOptions</span>
-    <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">t</span><span class="o">.</span><span class="n">Literal</span><span class="p">[</span><span class="kc">True</span><span class="p">,</span> <span class="kc">False</span><span class="p">]:</span>
-        <span class="sd">&quot;&quot;&quot;Return True if photo should be updated, else False&quot;&quot;&quot;</span>
+        <span class="bp">self</span><span class="p">,</span> <span class="n">src</span><span class="p">:</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span> <span class="n">dest</span><span class="p">:</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">,</span> <span class="n">options</span><span class="p">:</span> <span class="n">ExportOptions</span>
+    <span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bool</span> <span class="o">|</span> <span class="n">ShouldUpdate</span><span class="p">:</span>
+        <span class="sd">&quot;&quot;&quot;Return True if photo should be updated, else False</span>
+
+<span class="sd">        Args:</span>
+<span class="sd">            src (pathlib.Path | None): source path; if None, photo is missing and</span>
+<span class="sd">                any checks that require src will return True</span>
+<span class="sd">            dest (pathlib.Path): destination path</span>
+
+<span class="sd">        Returns:</span>
+<span class="sd">            False if photo should not be updated otherwise a truthy ShouldUpdate value</span>
+<span class="sd">        &quot;&quot;&quot;</span>
 
         <span class="c1"># NOTE: The order of certain checks is important</span>
         <span class="c1"># read the comments below to understand why before changing</span>
@@ -914,11 +967,11 @@
             <span class="c1"># photo doesn&#39;t exist in database, should update</span>
             <span class="k">return</span> <span class="n">ShouldUpdate</span><span class="o">.</span><span class="n">NOT_IN_DATABASE</span>
 
-        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">export_as_hardlink</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">dest</span><span class="o">.</span><span class="n">samefile</span><span class="p">(</span><span class="n">src</span><span class="p">):</span>
+        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">export_as_hardlink</span> <span class="ow">and</span> <span class="p">(</span><span class="ow">not</span> <span class="n">src</span> <span class="ow">or</span> <span class="ow">not</span> <span class="n">dest</span><span class="o">.</span><span class="n">samefile</span><span class="p">(</span><span class="n">src</span><span class="p">)):</span>
             <span class="c1"># different files, should update</span>
             <span class="k">return</span> <span class="n">ShouldUpdate</span><span class="o">.</span><span class="n">HARDLINK_DIFFERENT_FILES</span>
 
-        <span class="k">if</span> <span class="ow">not</span> <span class="n">options</span><span class="o">.</span><span class="n">export_as_hardlink</span> <span class="ow">and</span> <span class="n">dest</span><span class="o">.</span><span class="n">samefile</span><span class="p">(</span><span class="n">src</span><span class="p">):</span>
+        <span class="k">if</span> <span class="ow">not</span> <span class="n">options</span><span class="o">.</span><span class="n">export_as_hardlink</span> <span class="ow">and</span> <span class="p">(</span><span class="ow">not</span> <span class="n">src</span> <span class="ow">or</span> <span class="n">dest</span><span class="o">.</span><span class="n">samefile</span><span class="p">(</span><span class="n">src</span><span class="p">)):</span>
             <span class="c1"># same file but not exporting as hardlink, should update</span>
             <span class="k">return</span> <span class="n">ShouldUpdate</span><span class="o">.</span><span class="n">NOT_HARDLINK_SAME_FILES</span>
 
@@ -950,7 +1003,9 @@
             <span class="c1"># as exiftool will be used to update edited file</span>
             <span class="k">return</span> <span class="n">ShouldUpdate</span><span class="o">.</span><span class="n">EXIFTOOL_DIFFERENT</span> <span class="k">if</span> <span class="n">rv</span> <span class="k">else</span> <span class="kc">False</span>
 
-        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">edited</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">fileutil</span><span class="o">.</span><span class="n">cmp_file_sig</span><span class="p">(</span><span class="n">src</span><span class="p">,</span> <span class="n">file_record</span><span class="o">.</span><span class="n">src_sig</span><span class="p">):</span>
+        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">edited</span> <span class="ow">and</span> <span class="p">(</span>
+            <span class="ow">not</span> <span class="n">src</span> <span class="ow">or</span> <span class="ow">not</span> <span class="n">fileutil</span><span class="o">.</span><span class="n">cmp_file_sig</span><span class="p">(</span><span class="n">src</span><span class="p">,</span> <span class="n">file_record</span><span class="o">.</span><span class="n">src_sig</span><span class="p">)</span>
+        <span class="p">):</span>
             <span class="c1"># edited file in Photos doesn&#39;t match what was last exported</span>
             <span class="k">return</span> <span class="n">ShouldUpdate</span><span class="o">.</span><span class="n">EDITED_SIG_DIFFERENT</span>
 
@@ -1001,22 +1056,46 @@
 
         <span class="c1"># download any missing files</span>
         <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">download_missing</span><span class="p">:</span>
-            <span class="n">live_photo</span> <span class="o">=</span> <span class="n">staged</span><span class="o">.</span><span class="n">edited_live</span> <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">edited</span> <span class="k">else</span> <span class="n">staged</span><span class="o">.</span><span class="n">original_live</span>
-            <span class="n">missing_options</span> <span class="o">=</span> <span class="n">ExportOptions</span><span class="p">(</span>
-                <span class="n">edited</span><span class="o">=</span><span class="n">options</span><span class="o">.</span><span class="n">edited</span><span class="p">,</span>
-                <span class="n">preview</span><span class="o">=</span><span class="n">options</span><span class="o">.</span><span class="n">preview</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">staged</span><span class="o">.</span><span class="n">preview</span><span class="p">,</span>
-                <span class="n">raw_photo</span><span class="o">=</span><span class="n">options</span><span class="o">.</span><span class="n">raw_photo</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">staged</span><span class="o">.</span><span class="n">raw</span><span class="p">,</span>
-                <span class="n">live_photo</span><span class="o">=</span><span class="n">options</span><span class="o">.</span><span class="n">live_photo</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">live_photo</span><span class="p">,</span>
+            <span class="n">staged</span> <span class="o">|=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_stage_missing_photos_for_export</span><span class="p">(</span>
+                <span class="n">staged</span><span class="o">=</span><span class="n">staged</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="n">options</span>
             <span class="p">)</span>
-            <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">use_photokit</span><span class="p">:</span>
-                <span class="n">missing_staged</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_stage_photo_for_export_with_photokit</span><span class="p">(</span>
-                    <span class="n">options</span><span class="o">=</span><span class="n">missing_options</span>
-                <span class="p">)</span>
-            <span class="k">else</span><span class="p">:</span>
-                <span class="n">missing_staged</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_stage_photo_for_export_with_applescript</span><span class="p">(</span>
-                    <span class="n">options</span><span class="o">=</span><span class="n">missing_options</span>
-                <span class="p">)</span>
-            <span class="n">staged</span> <span class="o">|=</span> <span class="n">missing_staged</span>
+
+        <span class="k">return</span> <span class="n">staged</span>
+
+    <span class="k">def</span> <span class="nf">_stage_missing_photos_for_export</span><span class="p">(</span>
+        <span class="bp">self</span><span class="p">,</span> <span class="n">staged</span><span class="p">:</span> <span class="n">StagedFiles</span><span class="p">,</span> <span class="n">options</span><span class="p">:</span> <span class="n">ExportOptions</span>
+    <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">StagedFiles</span><span class="p">:</span>
+        <span class="sd">&quot;&quot;&quot;Download and stage any missing files for export&quot;&quot;&quot;</span>
+
+        <span class="c1"># if live photo and requesting edited version need the edited live photo</span>
+        <span class="n">live_photo</span> <span class="o">=</span> <span class="n">staged</span><span class="o">.</span><span class="n">edited_live</span> <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">edited</span> <span class="k">else</span> <span class="n">staged</span><span class="o">.</span><span class="n">original_live</span>
+
+        <span class="c1"># is there actually a missing file? (#1086)</span>
+        <span class="n">something_to_download</span> <span class="o">=</span> <span class="p">(</span>
+            <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">hasadjustments</span> <span class="ow">and</span> <span class="n">options</span><span class="o">.</span><span class="n">edited</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">staged</span><span class="o">.</span><span class="n">edited</span><span class="p">)</span>
+            <span class="ow">or</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">live_photo</span> <span class="ow">and</span> <span class="n">options</span><span class="o">.</span><span class="n">live_photo</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">live_photo</span><span class="p">)</span>
+            <span class="ow">or</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">has_raw</span> <span class="ow">and</span> <span class="n">options</span><span class="o">.</span><span class="n">raw_photo</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">staged</span><span class="o">.</span><span class="n">raw</span><span class="p">)</span>
+            <span class="ow">or</span> <span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">preview</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">staged</span><span class="o">.</span><span class="n">preview</span><span class="p">)</span>
+            <span class="ow">or</span> <span class="p">(</span><span class="ow">not</span> <span class="n">options</span><span class="o">.</span><span class="n">edited</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">staged</span><span class="o">.</span><span class="n">original</span><span class="p">)</span>
+        <span class="p">)</span>
+        <span class="k">if</span> <span class="ow">not</span> <span class="n">something_to_download</span><span class="p">:</span>
+            <span class="k">return</span> <span class="n">staged</span>
+
+        <span class="n">missing_options</span> <span class="o">=</span> <span class="n">ExportOptions</span><span class="p">(</span>
+            <span class="n">edited</span><span class="o">=</span><span class="n">options</span><span class="o">.</span><span class="n">edited</span><span class="p">,</span>
+            <span class="n">preview</span><span class="o">=</span><span class="n">options</span><span class="o">.</span><span class="n">preview</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">staged</span><span class="o">.</span><span class="n">preview</span><span class="p">,</span>
+            <span class="n">raw_photo</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">has_raw</span> <span class="ow">and</span> <span class="n">options</span><span class="o">.</span><span class="n">raw_photo</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">staged</span><span class="o">.</span><span class="n">raw</span><span class="p">,</span>
+            <span class="n">live_photo</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">live_photo</span> <span class="ow">and</span> <span class="n">options</span><span class="o">.</span><span class="n">live_photo</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">live_photo</span><span class="p">,</span>
+        <span class="p">)</span>
+        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">use_photokit</span><span class="p">:</span>
+            <span class="n">missing_staged</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_stage_photo_for_export_with_photokit</span><span class="p">(</span>
+                <span class="n">options</span><span class="o">=</span><span class="n">missing_options</span>
+            <span class="p">)</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="n">missing_staged</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_stage_photo_for_export_with_applescript</span><span class="p">(</span>
+                <span class="n">options</span><span class="o">=</span><span class="n">missing_options</span>
+            <span class="p">)</span>
+        <span class="n">staged</span> <span class="o">|=</span> <span class="n">missing_staged</span>
         <span class="k">return</span> <span class="n">staged</span>
 
     <span class="k">def</span> <span class="nf">_stage_photo_for_export_with_photokit</span><span class="p">(</span>
@@ -1131,7 +1210,8 @@
         <span class="sd">&quot;&quot;&quot;Stage a photo for export with AppleScript to a temporary directory</span>
 
 <span class="sd">        Note: If exporting an edited live photo, the associated live video will not be exported.</span>
-<span class="sd">        This is a limitation of the Photos AppleScript interface and Photos behaves the same way.&quot;&quot;&quot;</span>
+<span class="sd">        This is a limitation of the Photos AppleScript interface and Photos behaves the same way.</span>
+<span class="sd">        &quot;&quot;&quot;</span>
 
         <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">edited</span> <span class="ow">and</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">hasadjustments</span><span class="p">:</span>
             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Edited version requested but photo has no adjustments&quot;</span><span class="p">)</span>
@@ -1360,7 +1440,7 @@
                 <span class="k">try</span><span class="p">:</span>
                     <span class="n">fileutil</span><span class="o">.</span><span class="n">copy</span><span class="p">(</span><span class="n">src</span><span class="p">,</span> <span class="n">dest_str</span><span class="p">)</span>
                     <span class="n">verbose</span><span class="p">(</span>
-                        <span class="sa">f</span><span class="s2">&quot;Exported </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_filename</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">original_filename</span><span class="p">)</span><span class="si">}</span><span class="s2"> to </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_filepath</span><span class="p">(</span><span class="n">dest_str</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span>
+                        <span class="sa">f</span><span class="s2">&quot;Exported </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_filename</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">original_filename</span><span class="p">)</span><span class="si">}</span><span class="s2"> to </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_filepath</span><span class="p">(</span><span class="n">normalize_fs_path</span><span class="p">(</span><span class="n">dest_str</span><span class="p">))</span><span class="si">}</span><span class="s2">&quot;</span>
                     <span class="p">)</span>
                 <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
                     <span class="k">raise</span> <span class="n">ExportError</span><span class="p">(</span>
@@ -1391,7 +1471,7 @@
 
         <span class="c1"># set data in the database</span>
         <span class="k">with</span> <span class="n">export_db</span><span class="o">.</span><span class="n">create_or_get_file_record</span><span class="p">(</span><span class="n">dest_str</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">uuid</span><span class="p">)</span> <span class="k">as</span> <span class="n">rec</span><span class="p">:</span>
-            <span class="n">rec</span><span class="o">.</span><span class="n">photoinfo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
+            <span class="n">rec</span><span class="o">.</span><span class="n">photoinfo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">json</span><span class="p">(</span><span class="n">shallow</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
             <span class="n">rec</span><span class="o">.</span><span class="n">export_options</span> <span class="o">=</span> <span class="n">options</span><span class="o">.</span><span class="n">bit_flags</span>
             <span class="c1"># don&#39;t set src_sig as that is set above before any modifications by convert_to_jpeg or exiftool</span>
             <span class="k">if</span> <span class="ow">not</span> <span class="n">options</span><span class="o">.</span><span class="n">ignore_signature</span><span class="p">:</span>
@@ -1413,6 +1493,9 @@
                     <span class="s2">&quot;exiftool_warning&quot;</span><span class="p">:</span> <span class="n">exif_results</span><span class="o">.</span><span class="n">exiftool_warning</span><span class="p">,</span>
                 <span class="p">}</span>
 
+        <span class="c1"># clean up lock file</span>
+        <span class="n">unlock_filename</span><span class="p">(</span><span class="n">dest_str</span><span class="p">)</span>
+
         <span class="k">return</span> <span class="n">results</span>
 
     <span class="k">def</span> <span class="nf">_export_photo_uuid_applescript</span><span class="p">(</span>
@@ -1697,10 +1780,10 @@
         <span class="k">if</span> <span class="ow">not</span> <span class="n">options</span><span class="o">.</span><span class="n">dry_run</span><span class="p">:</span>
             <span class="n">warning_</span><span class="p">,</span> <span class="n">error_</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_write_exif_data</span><span class="p">(</span><span class="n">src</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="n">options</span><span class="p">)</span>
             <span class="k">if</span> <span class="n">warning_</span><span class="p">:</span>
-                <span class="n">exiftool_results</span><span class="o">.</span><span class="n">exiftool_warning</span><span class="o">.</span><span class="n">append</span><span class="p">((</span><span class="n">dest</span><span class="p">,</span> <span class="n">warning_</span><span class="p">))</span>
+                <span class="n">exiftool_results</span><span class="o">.</span><span class="n">exiftool_warning</span><span class="o">.</span><span class="n">append</span><span class="p">((</span><span class="nb">str</span><span class="p">(</span><span class="n">dest</span><span class="p">),</span> <span class="nb">str</span><span class="p">(</span><span class="n">warning_</span><span class="p">)))</span>
             <span class="k">if</span> <span class="n">error_</span><span class="p">:</span>
-                <span class="n">exiftool_results</span><span class="o">.</span><span class="n">exiftool_error</span><span class="o">.</span><span class="n">append</span><span class="p">((</span><span class="n">dest</span><span class="p">,</span> <span class="n">error_</span><span class="p">))</span>
-                <span class="n">exiftool_results</span><span class="o">.</span><span class="n">error</span><span class="o">.</span><span class="n">append</span><span class="p">((</span><span class="n">dest</span><span class="p">,</span> <span class="n">error_</span><span class="p">))</span>
+                <span class="n">exiftool_results</span><span class="o">.</span><span class="n">exiftool_error</span><span class="o">.</span><span class="n">append</span><span class="p">((</span><span class="nb">str</span><span class="p">(</span><span class="n">dest</span><span class="p">),</span> <span class="nb">str</span><span class="p">(</span><span class="n">error_</span><span class="p">)))</span>
+                <span class="n">exiftool_results</span><span class="o">.</span><span class="n">error</span><span class="o">.</span><span class="n">append</span><span class="p">((</span><span class="nb">str</span><span class="p">(</span><span class="n">dest</span><span class="p">),</span> <span class="nb">str</span><span class="p">(</span><span class="n">error_</span><span class="p">)))</span>
 
         <span class="n">exiftool_results</span><span class="o">.</span><span class="n">exif_updated</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
         <span class="n">exiftool_results</span><span class="o">.</span><span class="n">to_touch</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span>
@@ -1742,7 +1825,7 @@
         <span class="k">with</span> <span class="n">ExifTool</span><span class="p">(</span>
             <span class="n">filepath</span><span class="p">,</span>
             <span class="n">flags</span><span class="o">=</span><span class="n">options</span><span class="o">.</span><span class="n">exiftool_flags</span><span class="p">,</span>
-            <span class="n">exiftool</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_exiftool_path</span><span class="p">,</span>
+            <span class="n">exiftool</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">_exiftool_path</span><span class="p">,</span>
         <span class="p">)</span> <span class="k">as</span> <span class="n">exiftool</span><span class="p">:</span>
             <span class="k">for</span> <span class="n">exiftag</span><span class="p">,</span> <span class="n">val</span> <span class="ow">in</span> <span class="n">exif_info</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                 <span class="k">if</span> <span class="nb">type</span><span class="p">(</span><span class="n">val</span><span class="p">)</span> <span class="o">==</span> <span class="nb">list</span><span class="p">:</span>
@@ -1922,7 +2005,6 @@
                 <span class="k">elif</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">ismovie</span><span class="p">:</span>
                     <span class="n">exif</span><span class="p">[</span><span class="s2">&quot;Keys:GPSCoordinates&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">lat</span><span class="si">}</span><span class="s2"> </span><span class="si">{</span><span class="n">lon</span><span class="si">}</span><span class="s2">&quot;</span>
                     <span class="n">exif</span><span class="p">[</span><span class="s2">&quot;UserData:GPSCoordinates&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">lat</span><span class="si">}</span><span class="s2"> </span><span class="si">{</span><span class="n">lon</span><span class="si">}</span><span class="s2">&quot;</span>
-
         <span class="c1"># process date/time and timezone offset</span>
         <span class="c1"># Photos exports the following fields and sets modify date to creation date</span>
         <span class="c1"># [EXIF]    Modify Date             : 2020:10:30 00:00:00</span>
@@ -2032,7 +2114,7 @@
     <span class="k">def</span> <span class="nf">_get_exif_keywords</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;returns list of keywords found in the file&#39;s exif metadata&quot;&quot;&quot;</span>
         <span class="n">keywords</span> <span class="o">=</span> <span class="p">[]</span>
-        <span class="n">exif</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">exiftool</span>
+        <span class="n">exif</span> <span class="o">=</span> <span class="n">exiftool_caching</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="p">)</span>
         <span class="k">if</span> <span class="n">exif</span><span class="p">:</span>
             <span class="n">exifdict</span> <span class="o">=</span> <span class="n">exif</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span>
             <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">&quot;IPTC:Keywords&quot;</span><span class="p">,</span> <span class="s2">&quot;XMP:TagsList&quot;</span><span class="p">,</span> <span class="s2">&quot;XMP:Subject&quot;</span><span class="p">]:</span>
@@ -2049,7 +2131,7 @@
     <span class="k">def</span> <span class="nf">_get_exif_persons</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;returns list of persons found in the file&#39;s exif metadata&quot;&quot;&quot;</span>
         <span class="n">persons</span> <span class="o">=</span> <span class="p">[]</span>
-        <span class="n">exif</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">exiftool</span>
+        <span class="n">exif</span> <span class="o">=</span> <span class="n">exiftool_caching</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="p">)</span>
         <span class="k">if</span> <span class="n">exif</span><span class="p">:</span>
             <span class="n">exifdict</span> <span class="o">=</span> <span class="n">exif</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span>
             <span class="k">try</span><span class="p">:</span>
@@ -2130,10 +2212,7 @@
 
         <span class="n">options</span> <span class="o">=</span> <span class="n">options</span> <span class="ow">or</span> <span class="n">ExportOptions</span><span class="p">()</span>
 
-        <span class="n">xmp_template_file</span> <span class="o">=</span> <span class="p">(</span>
-            <span class="n">_XMP_TEMPLATE_NAME</span> <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_beta</span> <span class="k">else</span> <span class="n">_XMP_TEMPLATE_NAME_BETA</span>
-        <span class="p">)</span>
-        <span class="n">xmp_template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="n">filename</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">_TEMPLATE_DIR</span><span class="p">,</span> <span class="n">xmp_template_file</span><span class="p">))</span>
+        <span class="n">xmp_template</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_xmp_template</span><span class="p">()</span>
 
         <span class="k">if</span> <span class="n">extension</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
             <span class="n">extension</span> <span class="o">=</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">original_filename</span><span class="p">)</span>
@@ -2240,6 +2319,20 @@
         <span class="n">xmp_str</span> <span class="o">=</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">line</span> <span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">xmp_str</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span><span class="p">)</span> <span class="k">if</span> <span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span> <span class="o">!=</span> <span class="s2">&quot;&quot;</span><span class="p">)</span>
         <span class="k">return</span> <span class="n">xmp_str</span>
 
+    <span class="k">def</span> <span class="nf">_xmp_template</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Return the mako template for XMP sidecar, creating it if necessary&quot;&quot;&quot;</span>
+        <span class="k">global</span> <span class="n">_global_xmp_template</span>
+        <span class="k">if</span> <span class="n">_global_xmp_template</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
+            <span class="k">return</span> <span class="n">_global_xmp_template</span>
+
+        <span class="n">xmp_template_file</span> <span class="o">=</span> <span class="p">(</span>
+            <span class="n">_XMP_TEMPLATE_NAME_BETA</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">photo</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_beta</span> <span class="k">else</span> <span class="n">_XMP_TEMPLATE_NAME</span>
+        <span class="p">)</span>
+        <span class="n">_global_xmp_template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span>
+            <span class="n">filename</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">_TEMPLATE_DIR</span><span class="p">,</span> <span class="n">xmp_template_file</span><span class="p">)</span>
+        <span class="p">)</span>
+        <span class="k">return</span> <span class="n">_global_xmp_template</span>
+
     <span class="k">def</span> <span class="nf">_write_sidecar</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">filename</span><span class="p">,</span> <span class="n">sidecar_str</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;write sidecar_str to filename</span>
 <span class="sd">        used for exporting sidecar info&quot;&quot;&quot;</span>
@@ -2320,6 +2413,35 @@
         <span class="k">else</span><span class="p">:</span>
             <span class="n">new_files</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">file</span><span class="p">)</span>
     <span class="k">return</span> <span class="n">new_files</span>
+
+
+<span class="k">def</span> <span class="nf">exiftool_caching</span><span class="p">(</span><span class="n">photo</span><span class="p">:</span> <span class="n">SimpleNamespace</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">ExifToolCaching</span><span class="p">:</span>
+    <span class="sd">&quot;&quot;&quot;Return ExifToolCaching object for photo</span>
+
+<span class="sd">    Args:</span>
+<span class="sd">        photo: SimpleNamespace object with photo info</span>
+
+<span class="sd">    Returns:</span>
+<span class="sd">        ExifToolCaching object</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+    <span class="k">try</span><span class="p">:</span>
+        <span class="k">return</span> <span class="n">photo</span><span class="o">.</span><span class="n">_exiftool_caching</span>
+    <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
+        <span class="k">try</span><span class="p">:</span>
+            <span class="n">exiftool_path</span> <span class="o">=</span> <span class="n">photo</span><span class="o">.</span><span class="n">_exiftool_path</span> <span class="ow">or</span> <span class="n">get_exiftool_path</span><span class="p">()</span>
+            <span class="k">if</span> <span class="n">photo</span><span class="o">.</span><span class="n">path</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">path</span><span class="p">):</span>
+                <span class="n">exiftool</span> <span class="o">=</span> <span class="n">ExifToolCaching</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">path</span><span class="p">,</span> <span class="n">exiftool</span><span class="o">=</span><span class="n">exiftool_path</span><span class="p">)</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="n">exiftool</span> <span class="o">=</span> <span class="kc">None</span>
+        <span class="k">except</span> <span class="ne">FileNotFoundError</span><span class="p">:</span>
+            <span class="c1"># get_exiftool_path raises FileNotFoundError if exiftool not found</span>
+            <span class="n">exiftool</span> <span class="o">=</span> <span class="kc">None</span>
+            <span class="n">logging</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span>
+                <span class="s2">&quot;exiftool not in path; download and install from https://exiftool.org/&quot;</span>
+            <span class="p">)</span>
+
+        <span class="n">photo</span><span class="o">.</span><span class="n">_exiftool_caching</span> <span class="o">=</span> <span class="n">exiftool</span>
+        <span class="k">return</span> <span class="n">photo</span><span class="o">.</span><span class="n">_exiftool_caching</span>
 </pre></div>
         </article>
       </div>

docs/_modules/osxphotos/photoinfo.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>osxphotos.photoinfo - osxphotos 0.56.1 documentation</title>
+        <title>osxphotos.photoinfo - osxphotos 0.60.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.56.1 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.60.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.56.1 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -195,9 +195,7 @@
         </div>
         <article role="main">
           <h1>Source code for osxphotos.photoinfo</h1><div class="highlight"><pre>
-<span></span><span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">PhotoInfo class</span>
-<span class="sd">Represents a single photo in the Photos library and provides access to the photo&#39;s attributes</span>
+<span></span><span class="sd">&quot;&quot;&quot; PhotoInfo class: Represents a single photo in the Photos library and provides access to the photo&#39;s attributes</span>
 <span class="sd">PhotosDB.photos() returns a list of PhotoInfo objects</span>
 <span class="sd">&quot;&quot;&quot;</span>
 
@@ -212,12 +210,15 @@
 <span class="kn">import</span> <span class="nn">os.path</span>
 <span class="kn">import</span> <span class="nn">pathlib</span>
 <span class="kn">import</span> <span class="nn">plistlib</span>
+<span class="kn">import</span> <span class="nn">re</span>
 <span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">timedelta</span><span class="p">,</span> <span class="n">timezone</span>
 <span class="kn">from</span> <span class="nn">functools</span> <span class="kn">import</span> <span class="n">cached_property</span>
-<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Dict</span><span class="p">,</span> <span class="n">Optional</span>
+<span class="kn">from</span> <span class="nn">types</span> <span class="kn">import</span> <span class="n">SimpleNamespace</span>
+<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Any</span><span class="p">,</span> <span class="n">Dict</span><span class="p">,</span> <span class="n">Optional</span>
 
 <span class="kn">import</span> <span class="nn">yaml</span>
-<span class="kn">from</span> <span class="nn">osxmetadata</span> <span class="kn">import</span> <span class="n">OSXMetaData</span>
+
+<span class="kn">import</span> <span class="nn">osxphotos</span>
 
 <span class="kn">from</span> <span class="nn">._constants</span> <span class="kn">import</span> <span class="p">(</span>
     <span class="n">_DB_TABLE_NAMES</span><span class="p">,</span>
@@ -254,16 +255,23 @@
 <span class="kn">from</span> <span class="nn">.momentinfo</span> <span class="kn">import</span> <span class="n">MomentInfo</span>
 <span class="kn">from</span> <span class="nn">.personinfo</span> <span class="kn">import</span> <span class="n">FaceInfo</span><span class="p">,</span> <span class="n">PersonInfo</span>
 <span class="kn">from</span> <span class="nn">.photoexporter</span> <span class="kn">import</span> <span class="n">ExportOptions</span><span class="p">,</span> <span class="n">PhotoExporter</span>
+<span class="kn">from</span> <span class="nn">.phototables</span> <span class="kn">import</span> <span class="n">PhotoTables</span>
 <span class="kn">from</span> <span class="nn">.phototemplate</span> <span class="kn">import</span> <span class="n">PhotoTemplate</span><span class="p">,</span> <span class="n">RenderOptions</span>
 <span class="kn">from</span> <span class="nn">.placeinfo</span> <span class="kn">import</span> <span class="n">PlaceInfo4</span><span class="p">,</span> <span class="n">PlaceInfo5</span>
 <span class="kn">from</span> <span class="nn">.query_builder</span> <span class="kn">import</span> <span class="n">get_query</span>
 <span class="kn">from</span> <span class="nn">.scoreinfo</span> <span class="kn">import</span> <span class="n">ScoreInfo</span>
 <span class="kn">from</span> <span class="nn">.searchinfo</span> <span class="kn">import</span> <span class="n">SearchInfo</span>
-<span class="kn">from</span> <span class="nn">.text_detection</span> <span class="kn">import</span> <span class="n">detect_text</span>
 <span class="kn">from</span> <span class="nn">.uti</span> <span class="kn">import</span> <span class="n">get_preferred_uti_extension</span><span class="p">,</span> <span class="n">get_uti_for_extension</span>
-<span class="kn">from</span> <span class="nn">.utils</span> <span class="kn">import</span> <span class="n">_get_resource_loc</span><span class="p">,</span> <span class="n">hexdigest</span><span class="p">,</span> <span class="n">list_directory</span>
+<span class="kn">from</span> <span class="nn">.utils</span> <span class="kn">import</span> <span class="n">_get_resource_loc</span><span class="p">,</span> <span class="n">assert_macos</span><span class="p">,</span> <span class="n">hexdigest</span><span class="p">,</span> <span class="n">is_macos</span><span class="p">,</span> <span class="n">list_directory</span>
 
-<span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;PhotoInfo&quot;</span><span class="p">,</span> <span class="s2">&quot;PhotoInfoNone&quot;</span><span class="p">]</span>
+<span class="k">if</span> <span class="n">is_macos</span><span class="p">:</span>
+    <span class="kn">from</span> <span class="nn">osxmetadata</span> <span class="kn">import</span> <span class="n">OSXMetaData</span>
+
+    <span class="kn">from</span> <span class="nn">.text_detection</span> <span class="kn">import</span> <span class="n">detect_text</span>
+
+<span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;PhotoInfo&quot;</span><span class="p">,</span> <span class="s2">&quot;PhotoInfoNone&quot;</span><span class="p">,</span> <span class="s2">&quot;frozen_photoinfo_factory&quot;</span><span class="p">]</span>
+
+<span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s2">&quot;osxphotos&quot;</span><span class="p">)</span>
 
 
 <div class="viewcode-block" id="PhotoInfo"><a class="viewcode-back" href="../../reference.html#osxphotos.PhotoInfo">[docs]</a><span class="k">class</span> <span class="nc">PhotoInfo</span><span class="p">:</span>
@@ -272,10 +280,11 @@
 <span class="sd">    including keywords, persons, albums, uuid, path, etc.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
 
-    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">db</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">info</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span> <span class="o">=</span> <span class="n">uuid</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">_info</span> <span class="o">=</span> <span class="n">info</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">_db</span> <span class="o">=</span> <span class="n">db</span>
+    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">db</span><span class="p">:</span> <span class="s2">&quot;osxphotos.PhotosDB&quot;</span><span class="p">,</span> <span class="n">uuid</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">info</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">]):</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">uuid</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">]</span> <span class="o">=</span> <span class="n">info</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">:</span> <span class="s2">&quot;osxphotos.PhotosDB&quot;</span> <span class="o">=</span> <span class="n">db</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_exiftool_path</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_exiftool_path</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_verbose</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_verbose</span>
 
     <span class="nd">@property</span>
@@ -323,8 +332,7 @@
         <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">hasadjustments</span> <span class="ow">and</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">&lt;=</span> <span class="n">_PHOTOS_4_VERSION</span><span class="p">:</span>
             <span class="k">return</span> <span class="kc">None</span>
 
-        <span class="n">imagedate</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;lastmodifieddate&quot;</span><span class="p">]</span>
-        <span class="k">if</span> <span class="n">imagedate</span><span class="p">:</span>
+        <span class="k">if</span> <span class="n">imagedate</span> <span class="o">:=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;lastmodifieddate&quot;</span><span class="p">]:</span>
             <span class="n">seconds</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;imageTimeZoneOffsetSeconds&quot;</span><span class="p">]</span> <span class="ow">or</span> <span class="mi">0</span>
             <span class="n">delta</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">seconds</span><span class="o">=</span><span class="n">seconds</span><span class="p">)</span>
             <span class="n">tz</span> <span class="o">=</span> <span class="n">timezone</span><span class="p">(</span><span class="n">delta</span><span class="p">)</span>
@@ -361,6 +369,9 @@
         <span class="sd">&quot;&quot;&quot;Returns candidate path for original photo on Photos &gt;= version 5&quot;&quot;&quot;</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;shared&quot;</span><span class="p">]:</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_path_5_shared</span><span class="p">()</span>
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">syndicated</span> <span class="ow">and</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">saved_to_library</span><span class="p">:</span>
+            <span class="c1"># path for &quot;shared with you&quot; syndicated photos that have not yet been saved to the library</span>
+            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_path_syndication</span><span class="p">()</span>
         <span class="k">return</span> <span class="p">(</span>
             <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;directory&quot;</span><span class="p">],</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;filename&quot;</span><span class="p">])</span>
             <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;directory&quot;</span><span class="p">]</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s2">&quot;/&quot;</span><span class="p">)</span>
@@ -400,6 +411,21 @@
             <span class="n">filename</span><span class="p">,</span>
         <span class="p">)</span>
 
+    <span class="k">def</span> <span class="nf">_path_syndication</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Return path for syndicated photo on Photos &gt;= version 8&quot;&quot;&quot;</span>
+        <span class="c1"># Photos 8+ stores syndicated photos in a separate directory</span>
+        <span class="c1"># in ~/Photos Library.photoslibrary/scopes/syndication/originals/X/UUID.ext</span>
+        <span class="c1"># where X is first digit of UUID</span>
+        <span class="n">syndication_path</span> <span class="o">=</span> <span class="s2">&quot;scopes/syndication/originals&quot;</span>
+        <span class="n">uuid_dir</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
+        <span class="n">path</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_library_path</span><span class="p">,</span>
+            <span class="n">syndication_path</span><span class="p">,</span>
+            <span class="n">uuid_dir</span><span class="p">,</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">filename</span><span class="p">,</span>
+        <span class="p">)</span>
+        <span class="k">return</span> <span class="n">path</span> <span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">path</span><span class="p">)</span> <span class="k">else</span> <span class="kc">None</span>
+
     <span class="k">def</span> <span class="nf">_path_4</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;Returns candidate path for original photo on Photos &lt;= version 4&quot;&quot;&quot;</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;has_raw&quot;</span><span class="p">]:</span>
@@ -442,7 +468,7 @@
                 <span class="n">photopath</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_path_edited_5</span><span class="p">()</span>
 
             <span class="k">if</span> <span class="n">photopath</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">photopath</span><span class="p">):</span>
-                <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
                     <span class="sa">f</span><span class="s2">&quot;edited file for UUID </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="si">}</span><span class="s2"> should be at </span><span class="si">{</span><span class="n">photopath</span><span class="si">}</span><span class="s2"> but does not appear to exist&quot;</span>
                 <span class="p">)</span>
                 <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
@@ -482,7 +508,7 @@
                 <span class="n">filename</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="si">}</span><span class="s2">_2_0_a.mov&quot;</span>
             <span class="k">else</span><span class="p">:</span>
                 <span class="c1"># don&#39;t know what it is!</span>
-                <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;WARNING: unknown type </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s1">&#39;type&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;WARNING: unknown type </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s1">&#39;type&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
                 <span class="k">return</span> <span class="kc">None</span>
 
             <span class="k">return</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">library</span><span class="p">,</span> <span class="s2">&quot;resources&quot;</span><span class="p">,</span> <span class="s2">&quot;renders&quot;</span><span class="p">,</span> <span class="n">directory</span><span class="p">,</span> <span class="n">filename</span><span class="p">)</span>
@@ -529,7 +555,7 @@
             <span class="k">try</span><span class="p">:</span>
                 <span class="n">photopath</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_predicted_path_edited_4</span><span class="p">()</span>
             <span class="k">except</span> <span class="ne">ValueError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
-                <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;ERROR: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;ERROR: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
                 <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
 
             <span class="k">if</span> <span class="n">photopath</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">photopath</span><span class="p">):</span>
@@ -543,12 +569,12 @@
 
             <span class="c1"># check again to see if we found a valid file</span>
             <span class="k">if</span> <span class="n">photopath</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">photopath</span><span class="p">):</span>
-                <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
                     <span class="sa">f</span><span class="s2">&quot;MISSING PATH: edited file for UUID </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="si">}</span><span class="s2"> should be at </span><span class="si">{</span><span class="n">photopath</span><span class="si">}</span><span class="s2"> but does not appear to exist&quot;</span>
                 <span class="p">)</span>
                 <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
         <span class="k">else</span><span class="p">:</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2"> hasAdjustments but edit_resource_id is None&quot;</span><span class="p">)</span>
+            <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2"> hasAdjustments but edit_resource_id is None&quot;</span><span class="p">)</span>
             <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
 
         <span class="k">return</span> <span class="n">photopath</span>
@@ -583,6 +609,8 @@
         <span class="sd">&quot;&quot;&quot;return path_edited_live_photo for Photos &lt;= 4&quot;&quot;&quot;</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">&gt;</span> <span class="n">_PHOTOS_4_VERSION</span><span class="p">:</span>
             <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">&quot;Wrong database format!&quot;</span><span class="p">)</span>
+        <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">live_photo</span><span class="p">:</span>
+            <span class="k">return</span> <span class="kc">None</span>
         <span class="n">photopath</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_predicted_path_edited_live_photo_4</span><span class="p">()</span>
         <span class="k">if</span> <span class="n">photopath</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">photopath</span><span class="p">):</span>
             <span class="c1"># the heuristic failed, so try to find the file</span>
@@ -596,10 +624,6 @@
                 <span class="p">),</span>
                 <span class="kc">None</span><span class="p">,</span>
             <span class="p">)</span>
-        <span class="k">if</span> <span class="n">photopath</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
-                <span class="sa">f</span><span class="s2">&quot;MISSING PATH: edited live photo file for UUID </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="si">}</span><span class="s2"> does not appear to exist&quot;</span>
-            <span class="p">)</span>
         <span class="k">return</span> <span class="n">photopath</span>
 
     <span class="k">def</span> <span class="nf">_path_edited_5_live_photo</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
@@ -693,7 +717,7 @@
                 <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_masters_path</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;raw_info&quot;</span><span class="p">][</span><span class="s2">&quot;imagePath&quot;</span><span class="p">]</span>
             <span class="p">)</span>
         <span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">photopath</span><span class="p">):</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
+            <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
                 <span class="sa">f</span><span class="s2">&quot;MISSING PATH: RAW photo for UUID </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="si">}</span><span class="s2"> should be at </span><span class="si">{</span><span class="n">photopath</span><span class="si">}</span><span class="s2"> but does not appear to exist&quot;</span>
             <span class="p">)</span>
             <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
@@ -711,39 +735,26 @@
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">person_info</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;list of PersonInfo objects for person in picture&quot;&quot;&quot;</span>
-        <span class="k">try</span><span class="p">:</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_personinfo</span>
-        <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
-            <span class="bp">self</span><span class="o">.</span><span class="n">_personinfo</span> <span class="o">=</span> <span class="p">[</span>
-                <span class="n">PersonInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">pk</span><span class="o">=</span><span class="n">pk</span><span class="p">)</span> <span class="k">for</span> <span class="n">pk</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;persons&quot;</span><span class="p">]</span>
-            <span class="p">]</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_personinfo</span>
+        <span class="k">return</span> <span class="p">[</span><span class="n">PersonInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">pk</span><span class="o">=</span><span class="n">pk</span><span class="p">)</span> <span class="k">for</span> <span class="n">pk</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;persons&quot;</span><span class="p">]]</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">face_info</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;list of FaceInfo objects for faces in picture&quot;&quot;&quot;</span>
         <span class="k">try</span><span class="p">:</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_faceinfo</span>
-        <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
-            <span class="k">try</span><span class="p">:</span>
-                <span class="n">faces</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_faceinfo_uuid</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="p">]</span>
-                <span class="bp">self</span><span class="o">.</span><span class="n">_faceinfo</span> <span class="o">=</span> <span class="p">[</span><span class="n">FaceInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">pk</span><span class="o">=</span><span class="n">pk</span><span class="p">)</span> <span class="k">for</span> <span class="n">pk</span> <span class="ow">in</span> <span class="n">faces</span><span class="p">]</span>
-            <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
-                <span class="c1"># no faces</span>
-                <span class="bp">self</span><span class="o">.</span><span class="n">_faceinfo</span> <span class="o">=</span> <span class="p">[]</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_faceinfo</span>
+            <span class="n">faces</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_faceinfo_uuid</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="p">]</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_faceinfo</span> <span class="o">=</span> <span class="p">[</span><span class="n">FaceInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">pk</span><span class="o">=</span><span class="n">pk</span><span class="p">)</span> <span class="k">for</span> <span class="n">pk</span> <span class="ow">in</span> <span class="n">faces</span><span class="p">]</span>
+        <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
+            <span class="c1"># no faces</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_faceinfo</span> <span class="o">=</span> <span class="p">[]</span>
+        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_faceinfo</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">moment_info</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;Moment photo belongs to&quot;&quot;&quot;</span>
         <span class="k">try</span><span class="p">:</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_moment</span>
-        <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
-            <span class="k">try</span><span class="p">:</span>
-                <span class="bp">self</span><span class="o">.</span><span class="n">_moment</span> <span class="o">=</span> <span class="n">MomentInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">moment_pk</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;momentID&quot;</span><span class="p">])</span>
-            <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
-                <span class="bp">self</span><span class="o">.</span><span class="n">_moment</span> <span class="o">=</span> <span class="kc">None</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_moment</span>
+            <span class="k">return</span> <span class="n">MomentInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">moment_pk</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;momentID&quot;</span><span class="p">])</span>
+        <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
+            <span class="k">return</span> <span class="kc">None</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">albums</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
@@ -760,65 +771,41 @@
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">burst_albums</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;If photo is burst photo, list of albums it is contained in as well as any albums the key photo is contained in, otherwise returns self.albums&quot;&quot;&quot;</span>
-        <span class="k">try</span><span class="p">:</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_burst_albums</span>
-        <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
-            <span class="n">burst_albums</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">albums</span><span class="p">)</span>
-            <span class="k">for</span> <span class="n">photo</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">burst_photos</span><span class="p">:</span>
-                <span class="k">if</span> <span class="n">photo</span><span class="o">.</span><span class="n">burst_key</span><span class="p">:</span>
-                    <span class="n">burst_albums</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">albums</span><span class="p">)</span>
-            <span class="bp">self</span><span class="o">.</span><span class="n">_burst_albums</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span><span class="n">burst_albums</span><span class="p">))</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_burst_albums</span>
+        <span class="n">burst_albums</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">albums</span><span class="p">)</span>
+        <span class="k">for</span> <span class="n">photo</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">burst_photos</span><span class="p">:</span>
+            <span class="k">if</span> <span class="n">photo</span><span class="o">.</span><span class="n">burst_key</span><span class="p">:</span>
+                <span class="n">burst_albums</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">albums</span><span class="p">)</span>
+        <span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span><span class="n">burst_albums</span><span class="p">))</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">album_info</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;list of AlbumInfo objects representing albums the photo is contained in&quot;&quot;&quot;</span>
-        <span class="k">try</span><span class="p">:</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_album_info</span>
-        <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
-            <span class="n">album_uuids</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_album_uuids</span><span class="p">()</span>
-            <span class="bp">self</span><span class="o">.</span><span class="n">_album_info</span> <span class="o">=</span> <span class="p">[</span>
-                <span class="n">AlbumInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="n">album</span><span class="p">)</span> <span class="k">for</span> <span class="n">album</span> <span class="ow">in</span> <span class="n">album_uuids</span>
-            <span class="p">]</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_album_info</span>
+        <span class="n">album_uuids</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_album_uuids</span><span class="p">()</span>
+        <span class="k">return</span> <span class="p">[</span><span class="n">AlbumInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="n">album</span><span class="p">)</span> <span class="k">for</span> <span class="n">album</span> <span class="ow">in</span> <span class="n">album_uuids</span><span class="p">]</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">burst_album_info</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;If photo is a burst photo, returns list of AlbumInfo objects representing albums the photo is contained in as well as albums the burst key photo is contained in, otherwise returns self.album_info.&quot;&quot;&quot;</span>
-        <span class="k">try</span><span class="p">:</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_burst_album_info</span>
-        <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
-            <span class="n">burst_album_info</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">album_info</span><span class="p">)</span>
-            <span class="k">for</span> <span class="n">photo</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">burst_photos</span><span class="p">:</span>
-                <span class="k">if</span> <span class="n">photo</span><span class="o">.</span><span class="n">burst_key</span><span class="p">:</span>
-                    <span class="n">burst_album_info</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">album_info</span><span class="p">)</span>
-            <span class="bp">self</span><span class="o">.</span><span class="n">_burst_album_info</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span><span class="n">burst_album_info</span><span class="p">))</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_burst_album_info</span>
+        <span class="n">burst_album_info</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">album_info</span><span class="p">)</span>
+        <span class="k">for</span> <span class="n">photo</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">burst_photos</span><span class="p">:</span>
+            <span class="k">if</span> <span class="n">photo</span><span class="o">.</span><span class="n">burst_key</span><span class="p">:</span>
+                <span class="n">burst_album_info</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">album_info</span><span class="p">)</span>
+        <span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span><span class="n">burst_album_info</span><span class="p">))</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">import_info</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;ImportInfo object representing import session for the photo or None if no import session&quot;&quot;&quot;</span>
-        <span class="k">try</span><span class="p">:</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_import_info</span>
-        <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
-            <span class="bp">self</span><span class="o">.</span><span class="n">_import_info</span> <span class="o">=</span> <span class="p">(</span>
-                <span class="n">ImportInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;import_uuid&quot;</span><span class="p">])</span>
-                <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;import_uuid&quot;</span><span class="p">]</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>
-                <span class="k">else</span> <span class="kc">None</span>
-            <span class="p">)</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_import_info</span>
+        <span class="k">return</span> <span class="p">(</span>
+            <span class="n">ImportInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;import_uuid&quot;</span><span class="p">])</span>
+            <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;import_uuid&quot;</span><span class="p">]</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>
+            <span class="k">else</span> <span class="kc">None</span>
+        <span class="p">)</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">project_info</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;list of AlbumInfo objects representing projects for the photo or None if no projects&quot;&quot;&quot;</span>
-        <span class="k">try</span><span class="p">:</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_project_info</span>
-        <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
-            <span class="n">project_uuids</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_album_uuids</span><span class="p">(</span><span class="n">project</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
-            <span class="bp">self</span><span class="o">.</span><span class="n">_project_info</span> <span class="o">=</span> <span class="p">[</span>
-                <span class="n">ProjectInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="n">album</span><span class="p">)</span> <span class="k">for</span> <span class="n">album</span> <span class="ow">in</span> <span class="n">project_uuids</span>
-            <span class="p">]</span>
-            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_project_info</span>
+        <span class="n">project_uuids</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_album_uuids</span><span class="p">(</span><span class="n">project</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+        <span class="k">return</span> <span class="p">[</span><span class="n">ProjectInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="n">album</span><span class="p">)</span> <span class="k">for</span> <span class="n">album</span> <span class="ow">in</span> <span class="n">project_uuids</span><span class="p">]</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">keywords</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
@@ -832,8 +819,7 @@
         <span class="c1"># in this case, return None so result is the same as if title had never been set (which returns NULL)</span>
         <span class="c1"># issue #512</span>
         <span class="n">title</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;name&quot;</span><span class="p">]</span>
-        <span class="n">title</span> <span class="o">=</span> <span class="kc">None</span> <span class="k">if</span> <span class="n">title</span> <span class="o">==</span> <span class="s2">&quot;&quot;</span> <span class="k">else</span> <span class="n">title</span>
-        <span class="k">return</span> <span class="n">title</span>
+        <span class="k">return</span> <span class="kc">None</span> <span class="k">if</span> <span class="n">title</span> <span class="o">==</span> <span class="s2">&quot;&quot;</span> <span class="k">else</span> <span class="n">title</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">uuid</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
@@ -1106,33 +1092,14 @@
 
         <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">&lt;=</span> <span class="n">_PHOTOS_4_VERSION</span><span class="p">:</span>
-            <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">live_photo</span> <span class="ow">and</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">ismissing</span><span class="p">:</span>
-                <span class="n">live_model_id</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;live_model_id&quot;</span><span class="p">]</span>
-                <span class="k">if</span> <span class="n">live_model_id</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-                    <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;missing live_model_id: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
-                    <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
-                <span class="k">else</span><span class="p">:</span>
-                    <span class="n">folder_id</span><span class="p">,</span> <span class="n">file_id</span><span class="p">,</span> <span class="n">nn_id</span> <span class="o">=</span> <span class="n">_get_resource_loc</span><span class="p">(</span><span class="n">live_model_id</span><span class="p">)</span>
-                    <span class="n">library_path</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">library_path</span>
-                    <span class="n">photopath</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
-                        <span class="n">library_path</span><span class="p">,</span>
-                        <span class="s2">&quot;resources&quot;</span><span class="p">,</span>
-                        <span class="s2">&quot;media&quot;</span><span class="p">,</span>
-                        <span class="s2">&quot;master&quot;</span><span class="p">,</span>
-                        <span class="n">folder_id</span><span class="p">,</span>
-                        <span class="n">nn_id</span><span class="p">,</span>
-                        <span class="sa">f</span><span class="s2">&quot;jpegvideocomplement_</span><span class="si">{</span><span class="n">file_id</span><span class="si">}</span><span class="s2">.mov&quot;</span><span class="p">,</span>
-                    <span class="p">)</span>
-                    <span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">photopath</span><span class="p">):</span>
-                        <span class="c1"># In testing, I&#39;ve seen occasional missing movie for live photo</span>
-                        <span class="c1"># These appear to be valid -- e.g. live component hasn&#39;t been downloaded from iCloud</span>
-                        <span class="c1"># photos 4 has &quot;isOnDisk&quot; column we could check</span>
-                        <span class="c1"># or could do the actual check with &quot;isfile&quot;</span>
-                        <span class="c1"># TODO: should this be a warning or debug?</span>
-                        <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
-            <span class="k">else</span><span class="p">:</span>
-                <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
+            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_path_live_photo_4</span><span class="p">()</span>
         <span class="k">elif</span> <span class="bp">self</span><span class="o">.</span><span class="n">live_photo</span> <span class="ow">and</span> <span class="bp">self</span><span class="o">.</span><span class="n">path</span> <span class="ow">and</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">ismissing</span><span class="p">:</span>
+            <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">shared</span><span class="p">:</span>
+                <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_path_live_photo_shared_5</span><span class="p">()</span>
+            <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">syndicated</span> <span class="ow">and</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">saved_to_library</span><span class="p">:</span>
+                <span class="c1"># syndicated (&quot;Shared with you&quot;) photos not yet saved to library</span>
+                <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_path_live_syndicated</span><span class="p">()</span>
+
             <span class="n">filename</span> <span class="o">=</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">path</span><span class="p">)</span>
             <span class="n">photopath</span> <span class="o">=</span> <span class="n">filename</span><span class="o">.</span><span class="n">parent</span><span class="o">.</span><span class="n">joinpath</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">filename</span><span class="o">.</span><span class="n">stem</span><span class="si">}</span><span class="s2">_3.mov&quot;</span><span class="p">)</span>
             <span class="n">photopath</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">photopath</span><span class="p">)</span>
@@ -1146,8 +1113,68 @@
 
         <span class="k">return</span> <span class="n">photopath</span>
 
+    <span class="k">def</span> <span class="nf">_path_live_photo_shared_5</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Return path for live photo for shared photos&quot;&quot;&quot;</span>
+        <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">shared</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;photo </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2"> is not a shared photo&quot;</span><span class="p">)</span>
+        <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">live_photo</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;photo </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2"> is not a live photo&quot;</span><span class="p">)</span>
+
+        <span class="n">photopath</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_path_5_shared</span><span class="p">()</span>
+        <span class="k">if</span> <span class="n">photopath</span><span class="p">:</span>
+            <span class="n">photopath</span> <span class="o">=</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="n">photopath</span><span class="p">)</span><span class="o">.</span><span class="n">with_suffix</span><span class="p">(</span><span class="s2">&quot;.MOV&quot;</span><span class="p">)</span>
+            <span class="k">if</span> <span class="ow">not</span> <span class="n">photopath</span><span class="o">.</span><span class="n">exists</span><span class="p">():</span>
+                <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
+        <span class="k">return</span> <span class="n">photopath</span>
+
+    <span class="k">def</span> <span class="nf">_path_live_photo_4</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Return path for live edited photo for Photos &lt;= 4&quot;&quot;&quot;</span>
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">live_photo</span> <span class="ow">and</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">ismissing</span><span class="p">:</span>
+            <span class="n">live_model_id</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;live_model_id&quot;</span><span class="p">]</span>
+            <span class="k">if</span> <span class="n">live_model_id</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;missing live_model_id: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+                <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="n">folder_id</span><span class="p">,</span> <span class="n">file_id</span><span class="p">,</span> <span class="n">nn_id</span> <span class="o">=</span> <span class="n">_get_resource_loc</span><span class="p">(</span><span class="n">live_model_id</span><span class="p">)</span>
+                <span class="n">library_path</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">library_path</span>
+                <span class="n">photopath</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
+                    <span class="n">library_path</span><span class="p">,</span>
+                    <span class="s2">&quot;resources&quot;</span><span class="p">,</span>
+                    <span class="s2">&quot;media&quot;</span><span class="p">,</span>
+                    <span class="s2">&quot;master&quot;</span><span class="p">,</span>
+                    <span class="n">folder_id</span><span class="p">,</span>
+                    <span class="n">nn_id</span><span class="p">,</span>
+                    <span class="sa">f</span><span class="s2">&quot;jpegvideocomplement_</span><span class="si">{</span><span class="n">file_id</span><span class="si">}</span><span class="s2">.mov&quot;</span><span class="p">,</span>
+                <span class="p">)</span>
+                <span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">photopath</span><span class="p">):</span>
+                    <span class="c1"># In testing, I&#39;ve seen occasional missing movie for live photo</span>
+                    <span class="c1"># These appear to be valid -- e.g. live component hasn&#39;t been downloaded from iCloud</span>
+                    <span class="c1"># photos 4 has &quot;isOnDisk&quot; column we could check</span>
+                    <span class="c1"># or could do the actual check with &quot;isfile&quot;</span>
+                    <span class="c1"># TODO: should this be a warning or debug?</span>
+                    <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="n">photopath</span> <span class="o">=</span> <span class="kc">None</span>
+        <span class="k">return</span> <span class="n">photopath</span>
+
+    <span class="k">def</span> <span class="nf">_path_live_syndicated</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Return path for live syndicated photo on Photos &gt;= version 8&quot;&quot;&quot;</span>
+        <span class="c1"># Photos 8+ stores live syndicated photos in a separate directory</span>
+        <span class="c1"># in ~/Photos Library.photoslibrary/scopes/syndication/originals/X/UUID_3.mov</span>
+        <span class="c1"># where X is first digit of UUID</span>
+        <span class="n">syndication_path</span> <span class="o">=</span> <span class="s2">&quot;scopes/syndication/originals&quot;</span>
+        <span class="n">uuid_dir</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
+        <span class="n">filename</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">filename</span><span class="p">)</span><span class="o">.</span><span class="n">stem</span><span class="si">}</span><span class="s2">_3.mov&quot;</span>
+        <span class="n">live_photo</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_library_path</span><span class="p">,</span>
+            <span class="n">syndication_path</span><span class="p">,</span>
+            <span class="n">uuid_dir</span><span class="p">,</span>
+            <span class="n">filename</span><span class="p">,</span>
+        <span class="p">)</span>
+        <span class="k">return</span> <span class="n">live_photo</span> <span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">live_photo</span><span class="p">)</span> <span class="k">else</span> <span class="kc">None</span>
+
     <span class="nd">@cached_property</span>
-    <span class="k">def</span> <span class="nf">path_derivatives</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+    <span class="k">def</span> <span class="nf">path_derivatives</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
         <span class="sd">&quot;&quot;&quot;Return any derivative (preview) images associated with the photo as a list of paths, sorted by file size (largest first)&quot;&quot;&quot;</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">&lt;=</span> <span class="n">_PHOTOS_4_VERSION</span><span class="p">:</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_path_derivatives_4</span><span class="p">()</span>
@@ -1156,24 +1183,36 @@
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_path_derivatives_5_shared</span><span class="p">()</span>
 
         <span class="n">directory</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_uuid</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>  <span class="c1"># first char of uuid</span>
-        <span class="n">derivative_path</span> <span class="o">=</span> <span class="p">(</span>
-            <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_library_path</span><span class="p">)</span> <span class="o">/</span> <span class="sa">f</span><span class="s2">&quot;resources/derivatives/</span><span class="si">{</span><span class="n">directory</span><span class="si">}</span><span class="s2">&quot;</span>
-        <span class="p">)</span>
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">syndicated</span> <span class="ow">and</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">saved_to_library</span><span class="p">:</span>
+            <span class="c1"># syndicated (&quot;Shared with you&quot;) photos not yet saved to library</span>
+            <span class="n">derivative_path</span> <span class="o">=</span> <span class="s2">&quot;scopes/syndication/resources/derivatives&quot;</span>
+            <span class="n">thumb_path</span> <span class="o">=</span> <span class="p">(</span>
+                <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">derivative_path</span><span class="si">}</span><span class="s2">/masters/</span><span class="si">{</span><span class="n">directory</span><span class="si">}</span><span class="s2">/</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2">_4_5005_c.jpeg&quot;</span>
+            <span class="p">)</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="n">derivative_path</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;resources/derivatives/</span><span class="si">{</span><span class="n">directory</span><span class="si">}</span><span class="s2">&quot;</span>
+            <span class="n">thumb_path</span> <span class="o">=</span> <span class="p">(</span>
+                <span class="sa">f</span><span class="s2">&quot;resources/derivatives/masters/</span><span class="si">{</span><span class="n">directory</span><span class="si">}</span><span class="s2">/</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2">_4_5005_c.jpeg&quot;</span>
+            <span class="p">)</span>
+
+        <span class="n">derivative_path</span> <span class="o">=</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_library_path</span><span class="p">)</span><span class="o">.</span><span class="n">joinpath</span><span class="p">(</span><span class="n">derivative_path</span><span class="p">)</span>
+        <span class="n">thumb_path</span> <span class="o">=</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_library_path</span><span class="p">)</span><span class="o">.</span><span class="n">joinpath</span><span class="p">(</span><span class="n">thumb_path</span><span class="p">)</span>
+
+        <span class="c1"># find all files that start with uuid in derivative path</span>
         <span class="n">files</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">derivative_path</span><span class="o">.</span><span class="n">glob</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2">*.*&quot;</span><span class="p">))</span>
 
         <span class="c1"># previews may be missing from derivatives path</span>
         <span class="c1"># there are what appear to be low res thumbnails in the &quot;masters&quot; subfolder</span>
-        <span class="n">thumb_path</span> <span class="o">=</span> <span class="p">(</span>
-            <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_library_path</span><span class="p">)</span>
-            <span class="o">/</span> <span class="sa">f</span><span class="s2">&quot;resources/derivatives/masters/</span><span class="si">{</span><span class="n">directory</span><span class="si">}</span><span class="s2">/</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2">_4_5005_c.jpeg&quot;</span>
-        <span class="p">)</span>
         <span class="k">if</span> <span class="n">thumb_path</span><span class="o">.</span><span class="n">exists</span><span class="p">():</span>
             <span class="n">files</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">thumb_path</span><span class="p">)</span>
 
+        <span class="c1"># sort by file size, largest first</span>
         <span class="n">files</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">files</span><span class="p">,</span> <span class="n">reverse</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">f</span><span class="p">:</span> <span class="n">f</span><span class="o">.</span><span class="n">stat</span><span class="p">()</span><span class="o">.</span><span class="n">st_size</span><span class="p">)</span>
+
         <span class="c1"># return list of filename but skip .THM files (these are actually low-res thumbnails in JPEG format but with .THM extension)</span>
         <span class="n">derivatives</span> <span class="o">=</span> <span class="p">[</span><span class="nb">str</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span> <span class="k">for</span> <span class="n">filename</span> <span class="ow">in</span> <span class="n">files</span> <span class="k">if</span> <span class="n">filename</span><span class="o">.</span><span class="n">suffix</span> <span class="o">!=</span> <span class="s2">&quot;.THM&quot;</span><span class="p">]</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">isphoto</span> <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">derivatives</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span> <span class="ow">and</span> <span class="n">derivatives</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">endswith</span><span class="p">(</span><span class="s2">&quot;.mov&quot;</span><span class="p">):</span>
+            <span class="c1"># ensure .mov is first in list as poster image could be larger than the movie preview</span>
             <span class="n">derivatives</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="n">derivatives</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">derivatives</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">derivatives</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
 
         <span class="k">return</span> <span class="n">derivatives</span>
@@ -1393,7 +1432,6 @@
 <span class="sd">        &quot;&quot;&quot;</span>
 
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">&lt;=</span> <span class="n">_PHOTOS_4_VERSION</span><span class="p">:</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;score not implemented for this database version&quot;</span><span class="p">)</span>
             <span class="k">return</span> <span class="kc">None</span>
 
         <span class="k">try</span><span class="p">:</span>
@@ -1493,6 +1531,38 @@
             <span class="bp">self</span><span class="o">.</span><span class="n">_search_info_normalized</span> <span class="o">=</span> <span class="n">SearchInfo</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">normalized</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_search_info_normalized</span>
 
+    <span class="nd">@cached_property</span>
+    <span class="k">def</span> <span class="nf">syndicated</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bool</span> <span class="o">|</span> <span class="kc">None</span><span class="p">:</span>
+        <span class="sd">&quot;&quot;&quot;Return true if photo was shared via syndication (e.g. via Messages, etc.);</span>
+<span class="sd">        these are photos that appear in &quot;Shared with you&quot; album.</span>
+<span class="sd">        Photos 8+ only; returns None if not Photos 8+.</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">photos_version</span> <span class="o">&lt;</span> <span class="mi">8</span><span class="p">:</span>
+            <span class="k">return</span> <span class="kc">None</span>
+
+        <span class="k">try</span><span class="p">:</span>
+            <span class="k">return</span> <span class="p">(</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_syndication_uuid</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;syndication_identifier&quot;</span><span class="p">]</span>
+                <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>
+            <span class="p">)</span>
+        <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
+            <span class="k">return</span> <span class="kc">False</span>
+
+    <span class="nd">@cached_property</span>
+    <span class="k">def</span> <span class="nf">saved_to_library</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bool</span> <span class="o">|</span> <span class="kc">None</span><span class="p">:</span>
+        <span class="sd">&quot;&quot;&quot;Return True if syndicated photo has been saved to library;</span>
+<span class="sd">        returns False if photo is not syndicated or has not been saved to the library.</span>
+<span class="sd">        Returns None if not Photos 8+.</span>
+<span class="sd">        Syndicated photos are photos that appear in &quot;Shared with you&quot; album; Photos 8+ only.</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">photos_version</span> <span class="o">&lt;</span> <span class="mi">8</span><span class="p">:</span>
+            <span class="k">return</span> <span class="kc">None</span>
+
+        <span class="k">try</span><span class="p">:</span>
+            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_syndication_uuid</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;syndication_history&quot;</span><span class="p">]</span> <span class="o">!=</span> <span class="mi">0</span>
+        <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
+            <span class="k">return</span> <span class="kc">False</span>
+
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">labels</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;returns list of labels applied to photo by Photos image categorization</span>
@@ -1539,7 +1609,6 @@
 <span class="sd">        &quot;&quot;&quot;</span>
 
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">&lt;=</span> <span class="n">_PHOTOS_4_VERSION</span><span class="p">:</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;exif_info not implemented for this database version&quot;</span><span class="p">)</span>
             <span class="k">return</span> <span class="kc">None</span>
 
         <span class="k">try</span><span class="p">:</span>
@@ -1566,7 +1635,7 @@
                 <span class="n">lens_model</span><span class="o">=</span><span class="n">exif</span><span class="p">[</span><span class="s2">&quot;ZLENSMODEL&quot;</span><span class="p">],</span>
             <span class="p">)</span>
         <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Could not find exif record for uuid </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+            <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Could not find exif record for uuid </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
             <span class="n">exif_info</span> <span class="o">=</span> <span class="n">ExifInfo</span><span class="p">(</span>
                 <span class="n">iso</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
                 <span class="n">flash_fired</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
@@ -1622,11 +1691,14 @@
     <span class="k">def</span> <span class="nf">hexdigest</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;Returns a unique digest of the photo&#39;s properties and metadata;</span>
 <span class="sd">        useful for detecting changes in any property/metadata of the photo&quot;&quot;&quot;</span>
-        <span class="k">return</span> <span class="n">hexdigest</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">json</span><span class="p">())</span>
+        <span class="k">return</span> <span class="n">hexdigest</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_json_hexdigest</span><span class="p">())</span>
 
     <span class="nd">@cached_property</span>
-    <span class="k">def</span> <span class="nf">cloud_metadata</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Dict</span><span class="p">:</span>
-        <span class="sd">&quot;&quot;&quot;Returns contents of ZCLOUDMASTERMEDIAMETADATA as dict&quot;&quot;&quot;</span>
+    <span class="k">def</span> <span class="nf">cloud_metadata</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">dict</span><span class="p">[</span><span class="n">Any</span><span class="p">,</span> <span class="n">Any</span><span class="p">]:</span>
+        <span class="sd">&quot;&quot;&quot;Returns contents of ZCLOUDMASTERMEDIAMETADATA as dict; Photos 5+ only&quot;&quot;&quot;</span>
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">&lt;=</span> <span class="n">_PHOTOS_4_VERSION</span><span class="p">:</span>
+            <span class="k">return</span> <span class="p">{}</span>
+
         <span class="c1"># This is a large blob of data so don&#39;t load it unless requested</span>
         <span class="n">asset_table</span> <span class="o">=</span> <span class="n">_DB_TABLE_NAMES</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_photos_ver</span><span class="p">][</span><span class="s2">&quot;ASSET&quot;</span><span class="p">]</span>
         <span class="n">sql_cloud_metadata</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;&quot;&quot;</span>
@@ -1637,10 +1709,6 @@
 <span class="s2">            WHERE </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZUUID = ?</span>
 <span class="s2">        &quot;&quot;&quot;</span>
 
-        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">&lt;=</span> <span class="n">_PHOTOS_4_VERSION</span><span class="p">:</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;cloud_metadata not implemented for this database version&quot;</span><span class="p">)</span>
-            <span class="k">return</span> <span class="p">{}</span>
-
         <span class="n">_</span><span class="p">,</span> <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">get_db_connection</span><span class="p">()</span>
         <span class="n">metadata</span> <span class="o">=</span> <span class="p">{}</span>
         <span class="k">if</span> <span class="n">results</span> <span class="o">:=</span> <span class="n">cursor</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">sql_cloud_metadata</span><span class="p">,</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">,))</span><span class="o">.</span><span class="n">fetchone</span><span class="p">():</span>
@@ -1648,6 +1716,16 @@
                 <span class="n">metadata</span> <span class="o">=</span> <span class="n">plistlib</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">results</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
         <span class="k">return</span> <span class="n">metadata</span>
 
+    <span class="nd">@cached_property</span>
+    <span class="k">def</span> <span class="nf">cloud_guid</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
+        <span class="sd">&quot;&quot;&quot;Returns the GUID of the photo in iCloud (Photos 5+ only)&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;cloudMasterGUID&quot;</span><span class="p">]</span>
+
+    <span class="nd">@cached_property</span>
+    <span class="k">def</span> <span class="nf">cloud_owner_hashed_id</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
+        <span class="sd">&quot;&quot;&quot;Returns the hashed iCloud ID of the owner of the shared photo (Photos 5+ only)&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_info</span><span class="p">[</span><span class="s2">&quot;cloudownerhashedpersonid&quot;</span><span class="p">]</span>
+
     <span class="nd">@cached_property</span>
     <span class="k">def</span> <span class="nf">fingerprint</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
         <span class="sd">&quot;&quot;&quot;Returns fingerprint of original photo as a string&quot;&quot;&quot;</span>
@@ -1685,6 +1763,8 @@
 
     <span class="k">def</span> <span class="nf">_detected_text</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;detect text in photo, either from cached extended attribute or by attempting text detection&quot;&quot;&quot;</span>
+        <span class="n">assert_macos</span><span class="p">()</span>
+
         <span class="n">path</span> <span class="o">=</span> <span class="p">(</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">path_edited</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">hasadjustments</span> <span class="ow">and</span> <span class="bp">self</span><span class="o">.</span><span class="n">path_edited</span> <span class="k">else</span> <span class="bp">self</span><span class="o">.</span><span class="n">path</span>
         <span class="p">)</span>
@@ -1964,94 +2044,189 @@
         <span class="p">}</span>
         <span class="k">return</span> <span class="n">yaml</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">info</span><span class="p">,</span> <span class="n">sort_keys</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
 
-<div class="viewcode-block" id="PhotoInfo.asdict"><a class="viewcode-back" href="../../reference.html#osxphotos.PhotoInfo.asdict">[docs]</a>    <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot;return dict representation&quot;&quot;&quot;</span>
+<div class="viewcode-block" id="PhotoInfo.asdict"><a class="viewcode-back" href="../../reference.html#osxphotos.PhotoInfo.asdict">[docs]</a>    <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">shallow</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">]:</span>
+        <span class="sd">&quot;&quot;&quot;Return dict representation of PhotoInfo object.</span>
 
+<span class="sd">        Args:</span>
+<span class="sd">            shallow: if True, return shallow representation (does not contain folder_info, person_info, etc.)</span>
+
+<span class="sd">        Returns:</span>
+<span class="sd">            dict representation of PhotoInfo object</span>
+
+<span class="sd">        Note:</span>
+<span class="sd">            The shallow representation is used internally by export as it contains only the subset of data needed for export.</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+
+        <span class="n">comments</span> <span class="o">=</span> <span class="p">[</span><span class="n">comment</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">for</span> <span class="n">comment</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">comments</span><span class="p">]</span>
+        <span class="n">exif_info</span> <span class="o">=</span> <span class="n">dataclasses</span><span class="o">.</span><span class="n">asdict</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">exif_info</span><span class="p">)</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">exif_info</span> <span class="k">else</span> <span class="p">{}</span>
+        <span class="n">face_info</span> <span class="o">=</span> <span class="p">[</span><span class="n">face</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">for</span> <span class="n">face</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">face_info</span><span class="p">]</span>
         <span class="n">folders</span> <span class="o">=</span> <span class="p">{</span><span class="n">album</span><span class="o">.</span><span class="n">title</span><span class="p">:</span> <span class="n">album</span><span class="o">.</span><span class="n">folder_names</span> <span class="k">for</span> <span class="n">album</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">album_info</span><span class="p">}</span>
-        <span class="n">exif</span> <span class="o">=</span> <span class="n">dataclasses</span><span class="o">.</span><span class="n">asdict</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">exif_info</span><span class="p">)</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">exif_info</span> <span class="k">else</span> <span class="p">{}</span>
+        <span class="n">likes</span> <span class="o">=</span> <span class="p">[</span><span class="n">like</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">for</span> <span class="n">like</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">likes</span><span class="p">]</span>
         <span class="n">place</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">place</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">place</span> <span class="k">else</span> <span class="p">{}</span>
         <span class="n">score</span> <span class="o">=</span> <span class="n">dataclasses</span><span class="o">.</span><span class="n">asdict</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">score</span><span class="p">)</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">score</span> <span class="k">else</span> <span class="p">{}</span>
-        <span class="n">comments</span> <span class="o">=</span> <span class="p">[</span><span class="n">comment</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">for</span> <span class="n">comment</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">comments</span><span class="p">]</span>
-        <span class="n">likes</span> <span class="o">=</span> <span class="p">[</span><span class="n">like</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">for</span> <span class="n">like</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">likes</span><span class="p">]</span>
-        <span class="n">faces</span> <span class="o">=</span> <span class="p">[</span><span class="n">face</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">for</span> <span class="n">face</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">face_info</span><span class="p">]</span>
-        <span class="n">search_info</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">search_info</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">search_info</span> <span class="k">else</span> <span class="p">{}</span>
 
-        <span class="k">return</span> <span class="p">{</span>
-            <span class="s2">&quot;library&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_library_path</span><span class="p">,</span>
-            <span class="s2">&quot;uuid&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">,</span>
-            <span class="s2">&quot;filename&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">filename</span><span class="p">,</span>
-            <span class="s2">&quot;original_filename&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">original_filename</span><span class="p">,</span>
+        <span class="n">dict_data</span> <span class="o">=</span> <span class="p">{</span>
+            <span class="s2">&quot;albums&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">albums</span><span class="p">,</span>
+            <span class="s2">&quot;burst&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">burst</span><span class="p">,</span>
+            <span class="s2">&quot;cloud_guid&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">cloud_guid</span><span class="p">,</span>
+            <span class="s2">&quot;cloud_owner_hashed_id&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">cloud_owner_hashed_id</span><span class="p">,</span>
+            <span class="s2">&quot;comments&quot;</span><span class="p">:</span> <span class="n">comments</span><span class="p">,</span>
+            <span class="s2">&quot;date_added&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">date_added</span><span class="p">,</span>
+            <span class="s2">&quot;date_modified&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">date_modified</span><span class="p">,</span>
+            <span class="s2">&quot;date_trashed&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">date_trashed</span><span class="p">,</span>
             <span class="s2">&quot;date&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">date</span><span class="p">,</span>
             <span class="s2">&quot;description&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">description</span><span class="p">,</span>
-            <span class="s2">&quot;title&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">title</span><span class="p">,</span>
+            <span class="s2">&quot;exif_info&quot;</span><span class="p">:</span> <span class="n">exif_info</span><span class="p">,</span>
+            <span class="s2">&quot;external_edit&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">external_edit</span><span class="p">,</span>
+            <span class="s2">&quot;face_info&quot;</span><span class="p">:</span> <span class="n">face_info</span><span class="p">,</span>
+            <span class="s2">&quot;favorite&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">favorite</span><span class="p">,</span>
+            <span class="s2">&quot;filename&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">filename</span><span class="p">,</span>
+            <span class="s2">&quot;fingerprint&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">fingerprint</span><span class="p">,</span>
+            <span class="s2">&quot;folders&quot;</span><span class="p">:</span> <span class="n">folders</span><span class="p">,</span>
+            <span class="s2">&quot;has_raw&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">has_raw</span><span class="p">,</span>
+            <span class="s2">&quot;hasadjustments&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">hasadjustments</span><span class="p">,</span>
+            <span class="s2">&quot;hdr&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">hdr</span><span class="p">,</span>
+            <span class="s2">&quot;height&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">height</span><span class="p">,</span>
+            <span class="s2">&quot;hidden&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">hidden</span><span class="p">,</span>
+            <span class="s2">&quot;incloud&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">incloud</span><span class="p">,</span>
+            <span class="s2">&quot;intrash&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">intrash</span><span class="p">,</span>
+            <span class="s2">&quot;iscloudasset&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">iscloudasset</span><span class="p">,</span>
+            <span class="s2">&quot;ismissing&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">ismissing</span><span class="p">,</span>
+            <span class="s2">&quot;ismovie&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">ismovie</span><span class="p">,</span>
+            <span class="s2">&quot;isphoto&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">isphoto</span><span class="p">,</span>
+            <span class="s2">&quot;israw&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">israw</span><span class="p">,</span>
+            <span class="s2">&quot;isreference&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">isreference</span><span class="p">,</span>
             <span class="s2">&quot;keywords&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">keywords</span><span class="p">,</span>
             <span class="s2">&quot;labels&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">labels</span><span class="p">,</span>
-            <span class="s2">&quot;keywords&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">keywords</span><span class="p">,</span>
-            <span class="s2">&quot;albums&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">albums</span><span class="p">,</span>
-            <span class="s2">&quot;folders&quot;</span><span class="p">:</span> <span class="n">folders</span><span class="p">,</span>
-            <span class="s2">&quot;persons&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">persons</span><span class="p">,</span>
-            <span class="s2">&quot;faces&quot;</span><span class="p">:</span> <span class="n">faces</span><span class="p">,</span>
-            <span class="s2">&quot;path&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">path</span><span class="p">,</span>
-            <span class="s2">&quot;ismissing&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">ismissing</span><span class="p">,</span>
-            <span class="s2">&quot;hasadjustments&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">hasadjustments</span><span class="p">,</span>
-            <span class="s2">&quot;external_edit&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">external_edit</span><span class="p">,</span>
-            <span class="s2">&quot;favorite&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">favorite</span><span class="p">,</span>
-            <span class="s2">&quot;hidden&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">hidden</span><span class="p">,</span>
             <span class="s2">&quot;latitude&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">_latitude</span><span class="p">,</span>
-            <span class="s2">&quot;longitude&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">_longitude</span><span class="p">,</span>
-            <span class="s2">&quot;path_edited&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">path_edited</span><span class="p">,</span>
-            <span class="s2">&quot;shared&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">shared</span><span class="p">,</span>
-            <span class="s2">&quot;isphoto&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">isphoto</span><span class="p">,</span>
-            <span class="s2">&quot;ismovie&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">ismovie</span><span class="p">,</span>
-            <span class="s2">&quot;uti&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uti</span><span class="p">,</span>
-            <span class="s2">&quot;uti_original&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uti_original</span><span class="p">,</span>
-            <span class="s2">&quot;burst&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">burst</span><span class="p">,</span>
+            <span class="s2">&quot;library&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_library_path</span><span class="p">,</span>
+            <span class="s2">&quot;likes&quot;</span><span class="p">:</span> <span class="n">likes</span><span class="p">,</span>
             <span class="s2">&quot;live_photo&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">live_photo</span><span class="p">,</span>
+            <span class="s2">&quot;location&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">location</span><span class="p">,</span>
+            <span class="s2">&quot;longitude&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">_longitude</span><span class="p">,</span>
+            <span class="s2">&quot;orientation&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">orientation</span><span class="p">,</span>
+            <span class="s2">&quot;original_filename&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">original_filename</span><span class="p">,</span>
+            <span class="s2">&quot;original_filesize&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">original_filesize</span><span class="p">,</span>
+            <span class="s2">&quot;original_height&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">original_height</span><span class="p">,</span>
+            <span class="s2">&quot;original_orientation&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">original_orientation</span><span class="p">,</span>
+            <span class="s2">&quot;original_width&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">original_width</span><span class="p">,</span>
+            <span class="s2">&quot;owner&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">owner</span><span class="p">,</span>
+            <span class="s2">&quot;panorama&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">panorama</span><span class="p">,</span>
+            <span class="s2">&quot;path_edited_live_photo&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">path_edited_live_photo</span><span class="p">,</span>
+            <span class="s2">&quot;path_edited&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">path_edited</span><span class="p">,</span>
             <span class="s2">&quot;path_live_photo&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">path_live_photo</span><span class="p">,</span>
-            <span class="s2">&quot;iscloudasset&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">iscloudasset</span><span class="p">,</span>
-            <span class="s2">&quot;incloud&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">incloud</span><span class="p">,</span>
-            <span class="s2">&quot;isreference&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">isreference</span><span class="p">,</span>
-            <span class="s2">&quot;date_modified&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">date_modified</span><span class="p">,</span>
+            <span class="s2">&quot;path_raw&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">path_raw</span><span class="p">,</span>
+            <span class="s2">&quot;path&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">path</span><span class="p">,</span>
+            <span class="s2">&quot;persons&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">persons</span><span class="p">,</span>
+            <span class="s2">&quot;place&quot;</span><span class="p">:</span> <span class="n">place</span><span class="p">,</span>
             <span class="s2">&quot;portrait&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">portrait</span><span class="p">,</span>
+            <span class="s2">&quot;raw_original&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">raw_original</span><span class="p">,</span>
+            <span class="s2">&quot;score&quot;</span><span class="p">:</span> <span class="n">score</span><span class="p">,</span>
             <span class="s2">&quot;screenshot&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">screenshot</span><span class="p">,</span>
+            <span class="s2">&quot;selfie&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">selfie</span><span class="p">,</span>
+            <span class="s2">&quot;shared&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">shared</span><span class="p">,</span>
             <span class="s2">&quot;slow_mo&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">slow_mo</span><span class="p">,</span>
             <span class="s2">&quot;time_lapse&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">time_lapse</span><span class="p">,</span>
-            <span class="s2">&quot;hdr&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">hdr</span><span class="p">,</span>
-            <span class="s2">&quot;selfie&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">selfie</span><span class="p">,</span>
-            <span class="s2">&quot;panorama&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">panorama</span><span class="p">,</span>
-            <span class="s2">&quot;has_raw&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">has_raw</span><span class="p">,</span>
-            <span class="s2">&quot;israw&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">israw</span><span class="p">,</span>
-            <span class="s2">&quot;raw_original&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">raw_original</span><span class="p">,</span>
+            <span class="s2">&quot;title&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">title</span><span class="p">,</span>
+            <span class="s2">&quot;tzoffset&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">tzoffset</span><span class="p">,</span>
+            <span class="s2">&quot;uti_edited&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uti_edited</span><span class="p">,</span>
+            <span class="s2">&quot;uti_original&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uti_original</span><span class="p">,</span>
             <span class="s2">&quot;uti_raw&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uti_raw</span><span class="p">,</span>
-            <span class="s2">&quot;path_raw&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">path_raw</span><span class="p">,</span>
-            <span class="s2">&quot;place&quot;</span><span class="p">:</span> <span class="n">place</span><span class="p">,</span>
-            <span class="s2">&quot;exif&quot;</span><span class="p">:</span> <span class="n">exif</span><span class="p">,</span>
-            <span class="s2">&quot;score&quot;</span><span class="p">:</span> <span class="n">score</span><span class="p">,</span>
-            <span class="s2">&quot;intrash&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">intrash</span><span class="p">,</span>
-            <span class="s2">&quot;height&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">height</span><span class="p">,</span>
+            <span class="s2">&quot;uti&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uti</span><span class="p">,</span>
+            <span class="s2">&quot;uuid&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">uuid</span><span class="p">,</span>
+            <span class="s2">&quot;visible&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">visible</span><span class="p">,</span>
             <span class="s2">&quot;width&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">width</span><span class="p">,</span>
-            <span class="s2">&quot;orientation&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">orientation</span><span class="p">,</span>
-            <span class="s2">&quot;original_height&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">original_height</span><span class="p">,</span>
-            <span class="s2">&quot;original_width&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">original_width</span><span class="p">,</span>
-            <span class="s2">&quot;original_orientation&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">original_orientation</span><span class="p">,</span>
-            <span class="s2">&quot;original_filesize&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">original_filesize</span><span class="p">,</span>
-            <span class="s2">&quot;comments&quot;</span><span class="p">:</span> <span class="n">comments</span><span class="p">,</span>
-            <span class="s2">&quot;likes&quot;</span><span class="p">:</span> <span class="n">likes</span><span class="p">,</span>
-            <span class="s2">&quot;search_info&quot;</span><span class="p">:</span> <span class="n">search_info</span><span class="p">,</span>
-        <span class="p">}</span></div>
+        <span class="p">}</span>
 
-<div class="viewcode-block" id="PhotoInfo.json"><a class="viewcode-back" href="../../reference.html#osxphotos.PhotoInfo.json">[docs]</a>    <span class="k">def</span> <span class="nf">json</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot;Return JSON representation&quot;&quot;&quot;</span>
+        <span class="c1"># non-shallow keys</span>
+        <span class="k">if</span> <span class="ow">not</span> <span class="n">shallow</span><span class="p">:</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;album_info&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">album</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">for</span> <span class="n">album</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">album_info</span><span class="p">]</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;path_derivatives&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">path_derivatives</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;adjustments&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">adjustments</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">adjustments</span> <span class="k">else</span> <span class="p">{}</span>
+            <span class="p">)</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;burst_album_info&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">a</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">burst_album_info</span><span class="p">]</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;burst_albums&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">burst_albums</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;burst_default_pick&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">burst_default_pick</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;burst_key&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">burst_key</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;burst_photos&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span><span class="o">.</span><span class="n">uuid</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">burst_photos</span><span class="p">]</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;burst_selected&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">burst_selected</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;cloud_metadata&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">cloud_metadata</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;import_info&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">import_info</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">import_info</span> <span class="k">else</span> <span class="p">{}</span>
+            <span class="p">)</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;labels_normalized&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">labels_normalized</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;person_info&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">person_info</span><span class="p">]</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;project_info&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">project_info</span><span class="p">]</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;search_info&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">search_info</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">search_info</span> <span class="k">else</span> <span class="p">{}</span>
+            <span class="p">)</span>
+            <span class="n">dict_data</span><span class="p">[</span><span class="s2">&quot;search_info_normalized&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">search_info_normalized</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span>
+                <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">search_info_normalized</span>
+                <span class="k">else</span> <span class="p">{}</span>
+            <span class="p">)</span>
+
+        <span class="k">return</span> <span class="n">dict_data</span></div>
+
+<div class="viewcode-block" id="PhotoInfo.json"><a class="viewcode-back" href="../../reference.html#osxphotos.PhotoInfo.json">[docs]</a>    <span class="k">def</span> <span class="nf">json</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">indent</span><span class="p">:</span> <span class="nb">int</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span> <span class="n">shallow</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
+        <span class="sd">&quot;&quot;&quot;Return JSON representation</span>
+
+<span class="sd">        Args:</span>
+<span class="sd">            indent: indent level for JSON, if None, no indent</span>
+<span class="sd">            shallow: if True, return shallow JSON representation (does not contain folder_info, person_info, etc.)</span>
+
+<span class="sd">        Returns:</span>
+<span class="sd">            JSON string</span>
+
+<span class="sd">        Note:</span>
+<span class="sd">            The shallow representation is used internally by export as it contains only the subset of data needed for export.</span>
+<span class="sd">        &quot;&quot;&quot;</span>
 
         <span class="k">def</span> <span class="nf">default</span><span class="p">(</span><span class="n">o</span><span class="p">):</span>
             <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">o</span><span class="p">,</span> <span class="p">(</span><span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">)):</span>
                 <span class="k">return</span> <span class="n">o</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span>
 
-        <span class="n">dict_data</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">asdict</span><span class="p">()</span>
+        <span class="n">dict_data</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">asdict</span><span class="p">(</span><span class="n">shallow</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="k">if</span> <span class="n">shallow</span> <span class="k">else</span> <span class="bp">self</span><span class="o">.</span><span class="n">asdict</span><span class="p">(</span><span class="n">shallow</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
+
         <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">dict_data</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
+            <span class="c1"># sort lists such as keywords so JSON is consistent</span>
+            <span class="c1"># but do not sort certain items like location</span>
+            <span class="k">if</span> <span class="n">k</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">&quot;location&quot;</span><span class="p">]:</span>
+                <span class="k">continue</span>
             <span class="k">if</span> <span class="n">v</span> <span class="ow">and</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">v</span><span class="p">,</span> <span class="p">(</span><span class="nb">list</span><span class="p">,</span> <span class="nb">tuple</span><span class="p">))</span> <span class="ow">and</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">v</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="nb">dict</span><span class="p">):</span>
-                <span class="n">dict_data</span><span class="p">[</span><span class="n">k</span><span class="p">]</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">v</span><span class="p">)</span>
-        <span class="k">return</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="n">dict_data</span><span class="p">,</span> <span class="n">sort_keys</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">default</span><span class="p">)</span></div>
+                <span class="n">dict_data</span><span class="p">[</span><span class="n">k</span><span class="p">]</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">v</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="k">if</span> <span class="n">v</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="k">else</span> <span class="s2">&quot;&quot;</span><span class="p">)</span>
+        <span class="k">return</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="n">dict_data</span><span class="p">,</span> <span class="n">sort_keys</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">default</span><span class="p">,</span> <span class="n">indent</span><span class="o">=</span><span class="n">indent</span><span class="p">)</span></div>
+
+<div class="viewcode-block" id="PhotoInfo.tables"><a class="viewcode-back" href="../../reference.html#osxphotos.PhotoInfo.tables">[docs]</a>    <span class="k">def</span> <span class="nf">tables</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">PhotoTables</span><span class="p">:</span>
+        <span class="sd">&quot;&quot;&quot;Return PhotoTables object to provide access database tables associated with this photo (Photos 5+)&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="kc">None</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_photos_ver</span> <span class="o">&lt;</span> <span class="mi">5</span> <span class="k">else</span> <span class="n">PhotoTables</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span></div>
+
+    <span class="k">def</span> <span class="nf">_json_hexdigest</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;JSON for use by hexdigest()&quot;&quot;&quot;</span>
+
+        <span class="c1"># This differs from json() because hexdigest must not change if metadata changed</span>
+        <span class="c1"># With json(), sort order of lists of dicts is not consistent but these aren&#39;t needed</span>
+        <span class="c1"># for computing hexdigest so we can ignore them</span>
+        <span class="c1"># also don&#39;t use visible because it changes based on Photos UI state</span>
+
+        <span class="k">def</span> <span class="nf">default</span><span class="p">(</span><span class="n">o</span><span class="p">):</span>
+            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">o</span><span class="p">,</span> <span class="p">(</span><span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">)):</span>
+                <span class="k">return</span> <span class="n">o</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span>
+
+        <span class="n">dict_data</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">asdict</span><span class="p">(</span><span class="n">shallow</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+
+        <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">&quot;face_info&quot;</span><span class="p">,</span> <span class="s2">&quot;visible&quot;</span><span class="p">]:</span>
+            <span class="k">del</span> <span class="n">dict_data</span><span class="p">[</span><span class="n">k</span><span class="p">]</span>
+
+        <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">dict_data</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
+            <span class="c1"># sort lists such as keywords so JSON is consistent</span>
+            <span class="c1"># but do not sort certain items like location</span>
+            <span class="k">if</span> <span class="n">k</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">&quot;location&quot;</span><span class="p">]:</span>
+                <span class="k">continue</span>
+            <span class="k">if</span> <span class="n">v</span> <span class="ow">and</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">v</span><span class="p">,</span> <span class="p">(</span><span class="nb">list</span><span class="p">,</span> <span class="nb">tuple</span><span class="p">))</span> <span class="ow">and</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">v</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="nb">dict</span><span class="p">):</span>
+                <span class="n">dict_data</span><span class="p">[</span><span class="n">k</span><span class="p">]</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">v</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">v</span><span class="p">:</span> <span class="n">v</span> <span class="k">if</span> <span class="n">v</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="k">else</span> <span class="s2">&quot;&quot;</span><span class="p">)</span>
+        <span class="k">return</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="n">dict_data</span><span class="p">,</span> <span class="n">sort_keys</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">default</span><span class="p">)</span>
 
     <span class="k">def</span> <span class="fm">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;Compare two PhotoInfo objects for equality&quot;&quot;&quot;</span>
@@ -2075,13 +2250,114 @@
 
 
 <span class="k">class</span> <span class="nc">PhotoInfoNone</span><span class="p">:</span>
-    <span class="sd">&quot;&quot;&quot;mock class that returns None for all attributes&quot;&quot;&quot;</span>
+    <span class="sd">&quot;&quot;&quot;Mock class that returns None for all attributes&quot;&quot;&quot;</span>
 
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="k">pass</span>
 
     <span class="k">def</span> <span class="fm">__getattribute__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
         <span class="k">return</span> <span class="kc">None</span>
+
+
+<span class="k">def</span> <span class="nf">frozen_photoinfo_factory</span><span class="p">(</span><span class="n">photo</span><span class="p">:</span> <span class="n">PhotoInfo</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">SimpleNamespace</span><span class="p">:</span>
+    <span class="sd">&quot;&quot;&quot;Return a frozen SimpleNamespace object for a PhotoInfo object&quot;&quot;&quot;</span>
+    <span class="n">photo_json</span> <span class="o">=</span> <span class="n">photo</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
+
+    <span class="k">def</span> <span class="nf">_object_hook</span><span class="p">(</span><span class="n">d</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="n">Any</span><span class="p">,</span> <span class="n">Any</span><span class="p">]):</span>
+        <span class="k">if</span> <span class="ow">not</span> <span class="n">d</span><span class="p">:</span>
+            <span class="k">return</span> <span class="n">d</span>
+
+        <span class="c1"># if d key matches a ISO 8601 datetime (&#39;2023-03-24T06:46:57.690786&#39;, &#39;2019-07-04T16:24:01-07:00&#39;, &#39;2019-07-04T16:24:01+07:00&#39;), convert to datetime</span>
+        <span class="c1"># fromisoformat will also handle dates with timezone offset in form +0700, etc.</span>
+        <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">d</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
+            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">v</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span> <span class="ow">and</span> <span class="n">re</span><span class="o">.</span><span class="n">match</span><span class="p">(</span>
+                <span class="sa">r</span><span class="s2">&quot;\d</span><span class="si">{4}</span><span class="s2">-\d</span><span class="si">{2}</span><span class="s2">-\d</span><span class="si">{2}</span><span class="s2">T\d</span><span class="si">{2}</span><span class="s2">:\d</span><span class="si">{2}</span><span class="s2">:\d</span><span class="si">{2}</span><span class="s2">[.]?\d*[+-]?\d</span><span class="si">{2}</span><span class="s2">[:]?\d</span><span class="si">{2}</span><span class="s2">?&quot;</span><span class="p">,</span> <span class="n">v</span>
+            <span class="p">):</span>
+                <span class="n">d</span><span class="p">[</span><span class="n">k</span><span class="p">]</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="n">v</span><span class="p">)</span>
+        <span class="k">return</span> <span class="n">SimpleNamespace</span><span class="p">(</span><span class="o">**</span><span class="n">d</span><span class="p">)</span>
+
+    <span class="n">frozen</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">photo_json</span><span class="p">,</span> <span class="n">object_hook</span><span class="o">=</span><span class="k">lambda</span> <span class="n">d</span><span class="p">:</span> <span class="n">_object_hook</span><span class="p">(</span><span class="n">d</span><span class="p">))</span>
+
+    <span class="c1"># add on json() method to frozen object</span>
+    <span class="k">def</span> <span class="nf">_json</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>
+        <span class="k">return</span> <span class="n">photo_json</span>
+
+    <span class="n">frozen</span><span class="o">.</span><span class="n">json</span> <span class="o">=</span> <span class="n">_json</span>
+
+    <span class="c1"># add hexdigest property to frozen object</span>
+    <span class="n">frozen</span><span class="o">.</span><span class="n">hexdigest</span> <span class="o">=</span> <span class="n">photo</span><span class="o">.</span><span class="n">hexdigest</span>
+
+    <span class="k">def</span> <span class="nf">detected_text</span><span class="p">(</span><span class="n">confidence_threshold</span><span class="o">=</span><span class="n">TEXT_DETECTION_CONFIDENCE_THRESHOLD</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Detects text in photo and returns lists of results as (detected text, confidence)</span>
+
+<span class="sd">        confidence_threshold: float between 0.0 and 1.0. If text detection confidence is below this threshold,</span>
+<span class="sd">        text will not be returned. Default is TEXT_DETECTION_CONFIDENCE_THRESHOLD</span>
+
+<span class="sd">        If photo is edited, uses the edited photo, otherwise the original; falls back to the preview image if neither edited or original is available</span>
+
+<span class="sd">        Returns: list of (detected text, confidence) tuples</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+
+        <span class="k">try</span><span class="p">:</span>
+            <span class="k">return</span> <span class="n">frozen</span><span class="o">.</span><span class="n">_detected_text_cache</span><span class="p">[</span><span class="n">confidence_threshold</span><span class="p">]</span>
+        <span class="k">except</span> <span class="p">(</span><span class="ne">AttributeError</span><span class="p">,</span> <span class="ne">KeyError</span><span class="p">)</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">e</span><span class="p">,</span> <span class="ne">AttributeError</span><span class="p">):</span>
+                <span class="n">frozen</span><span class="o">.</span><span class="n">_detected_text_cache</span> <span class="o">=</span> <span class="p">{}</span>
+
+            <span class="k">try</span><span class="p">:</span>
+                <span class="n">detected_text</span> <span class="o">=</span> <span class="n">frozen</span><span class="o">.</span><span class="n">_detected_text</span><span class="p">()</span>
+            <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+                <span class="n">logging</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Error detecting text in photo </span><span class="si">{</span><span class="n">frozen</span><span class="o">.</span><span class="n">uuid</span><span class="si">}</span><span class="s2">: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+                <span class="n">detected_text</span> <span class="o">=</span> <span class="p">[]</span>
+
+            <span class="n">frozen</span><span class="o">.</span><span class="n">_detected_text_cache</span><span class="p">[</span><span class="n">confidence_threshold</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span>
+                <span class="p">(</span><span class="n">text</span><span class="p">,</span> <span class="n">confidence</span><span class="p">)</span>
+                <span class="k">for</span> <span class="n">text</span><span class="p">,</span> <span class="n">confidence</span> <span class="ow">in</span> <span class="n">detected_text</span>
+                <span class="k">if</span> <span class="n">confidence</span> <span class="o">&gt;=</span> <span class="n">confidence_threshold</span>
+            <span class="p">]</span>
+            <span class="k">return</span> <span class="n">frozen</span><span class="o">.</span><span class="n">_detected_text_cache</span><span class="p">[</span><span class="n">confidence_threshold</span><span class="p">]</span>
+
+    <span class="k">def</span> <span class="nf">_detected_text</span><span class="p">():</span>
+        <span class="sd">&quot;&quot;&quot;detect text in photo, either from cached extended attribute or by attempting text detection&quot;&quot;&quot;</span>
+        <span class="n">path</span> <span class="o">=</span> <span class="p">(</span>
+            <span class="n">frozen</span><span class="o">.</span><span class="n">path_edited</span>
+            <span class="k">if</span> <span class="n">frozen</span><span class="o">.</span><span class="n">hasadjustments</span> <span class="ow">and</span> <span class="n">frozen</span><span class="o">.</span><span class="n">path_edited</span>
+            <span class="k">else</span> <span class="n">frozen</span><span class="o">.</span><span class="n">path</span>
+        <span class="p">)</span>
+        <span class="n">path</span> <span class="o">=</span> <span class="n">path</span> <span class="ow">or</span> <span class="n">frozen</span><span class="o">.</span><span class="n">path_derivatives</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">if</span> <span class="n">frozen</span><span class="o">.</span><span class="n">path_derivatives</span> <span class="k">else</span> <span class="kc">None</span>
+        <span class="k">if</span> <span class="ow">not</span> <span class="n">path</span><span class="p">:</span>
+            <span class="k">return</span> <span class="p">[]</span>
+
+        <span class="n">md</span> <span class="o">=</span> <span class="n">OSXMetaData</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
+        <span class="k">try</span><span class="p">:</span>
+
+            <span class="k">def</span> <span class="nf">decoder</span><span class="p">(</span><span class="n">val</span><span class="p">):</span>
+                <span class="sd">&quot;&quot;&quot;Decode value from JSON&quot;&quot;&quot;</span>
+                <span class="k">return</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">val</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;utf-8&quot;</span><span class="p">))</span>
+
+            <span class="n">detected_text</span> <span class="o">=</span> <span class="n">md</span><span class="o">.</span><span class="n">get_xattr</span><span class="p">(</span>
+                <span class="s2">&quot;osxphotos.metadata:detected_text&quot;</span><span class="p">,</span> <span class="n">decode</span><span class="o">=</span><span class="n">decoder</span>
+            <span class="p">)</span>
+        <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
+            <span class="n">detected_text</span> <span class="o">=</span> <span class="kc">None</span>
+        <span class="k">if</span> <span class="n">detected_text</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+            <span class="n">orientation</span> <span class="o">=</span> <span class="n">frozen</span><span class="o">.</span><span class="n">orientation</span> <span class="ow">or</span> <span class="kc">None</span>
+            <span class="n">detected_text</span> <span class="o">=</span> <span class="n">detect_text</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">orientation</span><span class="p">)</span>
+
+            <span class="k">def</span> <span class="nf">encoder</span><span class="p">(</span><span class="n">obj</span><span class="p">):</span>
+                <span class="sd">&quot;&quot;&quot;Encode value as JSON&quot;&quot;&quot;</span>
+                <span class="n">val</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span>
+                <span class="k">return</span> <span class="n">val</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;utf-8&quot;</span><span class="p">)</span>
+
+            <span class="n">md</span><span class="o">.</span><span class="n">set_xattr</span><span class="p">(</span>
+                <span class="s2">&quot;osxphotos.metadata:detected_text&quot;</span><span class="p">,</span> <span class="n">detected_text</span><span class="p">,</span> <span class="n">encode</span><span class="o">=</span><span class="n">encoder</span>
+            <span class="p">)</span>
+        <span class="k">return</span> <span class="n">detected_text</span>
+
+    <span class="n">frozen</span><span class="o">.</span><span class="n">detected_text</span> <span class="o">=</span> <span class="n">detected_text</span>
+    <span class="n">frozen</span><span class="o">.</span><span class="n">_detected_text</span> <span class="o">=</span> <span class="n">_detected_text</span>
+
+    <span class="k">return</span> <span class="n">frozen</span>
 </pre></div>
         </article>
       </div>

docs/_modules/osxphotos/photosalbum.html

@@ -1,13 +1,13 @@
 <!doctype html>
-<html class="no-js">
+<html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
-    <meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
-        <title>osxphotos.photosalbum - osxphotos 0.51.7 documentation</title>
+    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
+        <title>osxphotos.photosalbum - osxphotos 0.60.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
-    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
+    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
     
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.51.7 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.60.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.51.7 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -179,7 +179,8 @@
           </svg>
           <span>Back to top</span>
         </a>
-        <div class="content-icon-container"><div class="theme-toggle-container theme-toggle-content">
+        <div class="content-icon-container">
+          <div class="theme-toggle-container theme-toggle-content">
             <button class="theme-toggle">
               <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
               <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
@@ -194,34 +195,37 @@
         </div>
         <article role="main">
           <h1>Source code for osxphotos.photosalbum</h1><div class="highlight"><pre>
-<span></span><span class="sd">""" PhotosAlbum class to create an album in default Photos library and add photos to it """</span>
+<span></span><span class="sd">&quot;&quot;&quot; PhotosAlbum class to create an album in default Photos library and add photos to it &quot;&quot;&quot;</span>
 
 <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">List</span><span class="p">,</span> <span class="n">Optional</span>
 
-<span class="kn">import</span> <span class="nn">photoscript</span>
 <span class="kn">from</span> <span class="nn">more_itertools</span> <span class="kn">import</span> <span class="n">chunked</span>
-<span class="kn">from</span> <span class="nn">photoscript</span> <span class="kn">import</span> <span class="n">Album</span><span class="p">,</span> <span class="n">Folder</span><span class="p">,</span> <span class="n">Photo</span><span class="p">,</span> <span class="n">PhotosLibrary</span>
 
 <span class="kn">from</span> <span class="nn">.photoinfo</span> <span class="kn">import</span> <span class="n">PhotoInfo</span>
-<span class="kn">from</span> <span class="nn">.utils</span> <span class="kn">import</span> <span class="n">noop</span><span class="p">,</span> <span class="n">pluralize</span>
+<span class="kn">from</span> <span class="nn">.utils</span> <span class="kn">import</span> <span class="n">assert_macos</span><span class="p">,</span> <span class="n">noop</span><span class="p">,</span> <span class="n">pluralize</span>
 
-<span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"PhotosAlbum"</span><span class="p">,</span> <span class="s2">"PhotosAlbumPhotoScript"</span><span class="p">]</span>
+<span class="n">assert_macos</span><span class="p">()</span>
+
+<span class="kn">import</span> <span class="nn">photoscript</span>
+<span class="kn">from</span> <span class="nn">photoscript</span> <span class="kn">import</span> <span class="n">Album</span><span class="p">,</span> <span class="n">Folder</span><span class="p">,</span> <span class="n">Photo</span><span class="p">,</span> <span class="n">PhotosLibrary</span>
+
+<span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;PhotosAlbum&quot;</span><span class="p">,</span> <span class="s2">&quot;PhotosAlbumPhotoScript&quot;</span><span class="p">]</span>
 
 
 <span class="k">def</span> <span class="nf">folder_by_path</span><span class="p">(</span><span class="n">folders</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="nb">str</span><span class="p">],</span> <span class="n">verbose</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">callable</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Folder</span><span class="p">:</span>
-    <span class="sd">"""Get (and create if necessary) a Photos Folder by path (passed as list of folder names)"""</span>
+    <span class="sd">&quot;&quot;&quot;Get (and create if necessary) a Photos Folder by path (passed as list of folder names)&quot;&quot;&quot;</span>
     <span class="n">library</span> <span class="o">=</span> <span class="n">PhotosLibrary</span><span class="p">()</span>
     <span class="n">verbose</span> <span class="o">=</span> <span class="n">verbose</span> <span class="ow">or</span> <span class="n">noop</span>
     <span class="n">top_folder_name</span> <span class="o">=</span> <span class="n">folders</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
     <span class="n">top_folder</span> <span class="o">=</span> <span class="n">library</span><span class="o">.</span><span class="n">folder</span><span class="p">(</span><span class="n">top_folder_name</span><span class="p">,</span> <span class="n">top_level</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
     <span class="k">if</span> <span class="ow">not</span> <span class="n">top_folder</span><span class="p">:</span>
-        <span class="n">verbose</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Creating folder '</span><span class="si">{</span><span class="n">top_folder_name</span><span class="si">}</span><span class="s2">'"</span><span class="p">)</span>
+        <span class="n">verbose</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Creating folder &#39;</span><span class="si">{</span><span class="n">top_folder_name</span><span class="si">}</span><span class="s2">&#39;&quot;</span><span class="p">)</span>
         <span class="n">top_folder</span> <span class="o">=</span> <span class="n">library</span><span class="o">.</span><span class="n">create_folder</span><span class="p">(</span><span class="n">top_folder_name</span><span class="p">)</span>
     <span class="n">current_folder</span> <span class="o">=</span> <span class="n">top_folder</span>
     <span class="k">for</span> <span class="n">folder_name</span> <span class="ow">in</span> <span class="n">folders</span><span class="p">:</span>
         <span class="n">folder</span> <span class="o">=</span> <span class="n">current_folder</span><span class="o">.</span><span class="n">folder</span><span class="p">(</span><span class="n">folder_name</span><span class="p">)</span>
         <span class="k">if</span> <span class="ow">not</span> <span class="n">folder</span><span class="p">:</span>
-            <span class="n">verbose</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Creating folder '</span><span class="si">{</span><span class="n">folder_name</span><span class="si">}</span><span class="s2">'"</span><span class="p">)</span>
+            <span class="n">verbose</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Creating folder &#39;</span><span class="si">{</span><span class="n">folder_name</span><span class="si">}</span><span class="s2">&#39;&quot;</span><span class="p">)</span>
             <span class="n">folder</span> <span class="o">=</span> <span class="n">current_folder</span><span class="o">.</span><span class="n">create_folder</span><span class="p">(</span><span class="n">folder_name</span><span class="p">)</span>
         <span class="n">current_folder</span> <span class="o">=</span> <span class="n">folder</span>
     <span class="k">return</span> <span class="n">current_folder</span>
@@ -230,7 +234,7 @@
 <span class="k">def</span> <span class="nf">album_by_path</span><span class="p">(</span>
     <span class="n">folders_album</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="nb">str</span><span class="p">],</span> <span class="n">verbose</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">callable</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
 <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Album</span><span class="p">:</span>
-    <span class="sd">"""Get (and create if necessary) a Photos Album by path (pass as list of folders, album name)"""</span>
+    <span class="sd">&quot;&quot;&quot;Get (and create if necessary) a Photos Album by path (pass as list of folders, album name)&quot;&quot;&quot;</span>
     <span class="n">library</span> <span class="o">=</span> <span class="n">PhotosLibrary</span><span class="p">()</span>
     <span class="n">verbose</span> <span class="o">=</span> <span class="n">verbose</span> <span class="ow">or</span> <span class="n">noop</span>
     <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">folders_album</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>
@@ -239,21 +243,21 @@
         <span class="n">folder</span> <span class="o">=</span> <span class="n">folder_by_path</span><span class="p">(</span><span class="n">folders_album</span><span class="p">,</span> <span class="n">verbose</span><span class="p">)</span>
         <span class="n">album</span> <span class="o">=</span> <span class="n">folder</span><span class="o">.</span><span class="n">album</span><span class="p">(</span><span class="n">album_name</span><span class="p">)</span>
         <span class="k">if</span> <span class="n">album</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-            <span class="n">verbose</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Creating album '</span><span class="si">{</span><span class="n">album_name</span><span class="si">}</span><span class="s2">'"</span><span class="p">)</span>
+            <span class="n">verbose</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Creating album &#39;</span><span class="si">{</span><span class="n">album_name</span><span class="si">}</span><span class="s2">&#39;&quot;</span><span class="p">)</span>
             <span class="n">album</span> <span class="o">=</span> <span class="n">folder</span><span class="o">.</span><span class="n">create_album</span><span class="p">(</span><span class="n">album_name</span><span class="p">)</span>
     <span class="k">else</span><span class="p">:</span>
         <span class="c1"># only have album name</span>
         <span class="n">album_name</span> <span class="o">=</span> <span class="n">folders_album</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
         <span class="n">album</span> <span class="o">=</span> <span class="n">library</span><span class="o">.</span><span class="n">album</span><span class="p">(</span><span class="n">album_name</span><span class="p">,</span> <span class="n">top_level</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
         <span class="k">if</span> <span class="n">album</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-            <span class="n">verbose</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Creating album '</span><span class="si">{</span><span class="n">album_name</span><span class="si">}</span><span class="s2">'"</span><span class="p">)</span>
+            <span class="n">verbose</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Creating album &#39;</span><span class="si">{</span><span class="n">album_name</span><span class="si">}</span><span class="s2">&#39;&quot;</span><span class="p">)</span>
             <span class="n">album</span> <span class="o">=</span> <span class="n">library</span><span class="o">.</span><span class="n">create_album</span><span class="p">(</span><span class="n">album_name</span><span class="p">)</span>
 
     <span class="k">return</span> <span class="n">album</span>
 
 
 <div class="viewcode-block" id="PhotosAlbum"><a class="viewcode-back" href="../../reference.html#osxphotos.PhotosAlbum">[docs]</a><span class="k">class</span> <span class="nc">PhotosAlbum</span><span class="p">:</span>
-    <span class="sd">"""Add osxphotos.photoinfo.PhotoInfo objects to album"""</span>
+    <span class="sd">&quot;&quot;&quot;Add osxphotos.photoinfo.PhotoInfo objects to album&quot;&quot;&quot;</span>
 
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span>
         <span class="bp">self</span><span class="p">,</span>
@@ -262,17 +266,17 @@
         <span class="n">split_folder</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
         <span class="n">rich</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
     <span class="p">):</span>
-        <span class="sd">"""Return a PhotosAlbum object, creating the album if necessary</span>
+        <span class="sd">&quot;&quot;&quot;Return a PhotosAlbum object, creating the album if necessary</span>
 
 <span class="sd">        Args:</span>
 <span class="sd">            name: Name of album</span>
 <span class="sd">            verbose: optional callable to print verbose output</span>
 <span class="sd">            split_folder: if set, split album name on value of split_folder to create folders if necessary,</span>
-<span class="sd">                e.g. if name = 'folder1/folder2/album' and split_folder='/',</span>
-<span class="sd">                then folders 'folder1' and 'folder2' will be created and album 'album' will be created in 'folder2';</span>
-<span class="sd">                if not set, album 'folder1/folder2/album' will be created</span>
+<span class="sd">                e.g. if name = &#39;folder1/folder2/album&#39; and split_folder=&#39;/&#39;,</span>
+<span class="sd">                then folders &#39;folder1&#39; and &#39;folder2&#39; will be created and album &#39;album&#39; will be created in &#39;folder2&#39;;</span>
+<span class="sd">                if not set, album &#39;folder1/folder2/album&#39; will be created</span>
 <span class="sd">            rich: if True, use rich themes for verbose output</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">verbose</span> <span class="o">=</span> <span class="n">verbose</span> <span class="ow">or</span> <span class="n">noop</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">library</span> <span class="o">=</span> <span class="n">photoscript</span><span class="o">.</span><span class="n">PhotosLibrary</span><span class="p">()</span>
 
@@ -285,7 +289,7 @@
         <span class="n">photo_</span> <span class="o">=</span> <span class="n">photoscript</span><span class="o">.</span><span class="n">Photo</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">uuid</span><span class="p">)</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">album</span><span class="o">.</span><span class="n">add</span><span class="p">([</span><span class="n">photo_</span><span class="p">])</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">verbose</span><span class="p">(</span>
-            <span class="sa">f</span><span class="s2">"Added </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_name</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">original_filename</span><span class="p">)</span><span class="si">}</span><span class="s2"> (</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_uuid</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">uuid</span><span class="p">)</span><span class="si">}</span><span class="s2">) to album </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_album</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="si">}</span><span class="s2">"</span>
+            <span class="sa">f</span><span class="s2">&quot;Added </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_name</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">original_filename</span><span class="p">)</span><span class="si">}</span><span class="s2"> (</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_uuid</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">uuid</span><span class="p">)</span><span class="si">}</span><span class="s2">) to album </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_album</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span>
         <span class="p">)</span>
 
     <span class="k">def</span> <span class="nf">add_list</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">photo_list</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">PhotoInfo</span><span class="p">]):</span>
@@ -294,43 +298,46 @@
             <span class="k">try</span><span class="p">:</span>
                 <span class="n">photos</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">photoscript</span><span class="o">.</span><span class="n">Photo</span><span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">uuid</span><span class="p">))</span>
             <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+                <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Error creating Photo object for photo </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_uuid</span><span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">uuid</span><span class="p">)</span><span class="si">}</span><span class="s2">: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">verbose</span><span class="p">(</span>
-                    <span class="sa">f</span><span class="s2">"Error creating Photo object for photo </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_uuid</span><span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">uuid</span><span class="p">)</span><span class="si">}</span><span class="s2">: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span>
+                    <span class="sa">f</span><span class="s2">&quot;Error creating Photo object for photo </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_uuid</span><span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">uuid</span><span class="p">)</span><span class="si">}</span><span class="s2">: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">&quot;</span>
                 <span class="p">)</span>
+        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;photos: </span><span class="si">{</span><span class="n">photos</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
         <span class="k">for</span> <span class="n">photolist</span> <span class="ow">in</span> <span class="n">chunked</span><span class="p">(</span><span class="n">photos</span><span class="p">,</span> <span class="mi">10</span><span class="p">):</span>
+            <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;photolist: </span><span class="si">{</span><span class="n">photolist</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">album</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">photolist</span><span class="p">)</span>
         <span class="n">photo_len</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">photo_list</span><span class="p">)</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">verbose</span><span class="p">(</span>
-            <span class="sa">f</span><span class="s2">"Added </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_num</span><span class="p">(</span><span class="n">photo_len</span><span class="p">)</span><span class="si">}</span><span class="s2"> </span><span class="si">{</span><span class="n">pluralize</span><span class="p">(</span><span class="n">photo_len</span><span class="p">,</span> <span class="s1">'photo'</span><span class="p">,</span> <span class="s1">'photos'</span><span class="p">)</span><span class="si">}</span><span class="s2"> to album </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_album</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="si">}</span><span class="s2">"</span>
+            <span class="sa">f</span><span class="s2">&quot;Added </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_num</span><span class="p">(</span><span class="n">photo_len</span><span class="p">)</span><span class="si">}</span><span class="s2"> </span><span class="si">{</span><span class="n">pluralize</span><span class="p">(</span><span class="n">photo_len</span><span class="p">,</span> <span class="s1">&#39;photo&#39;</span><span class="p">,</span> <span class="s1">&#39;photos&#39;</span><span class="p">)</span><span class="si">}</span><span class="s2"> to album </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_album</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span>
         <span class="p">)</span>
 
     <span class="k">def</span> <span class="nf">photos</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">album</span><span class="o">.</span><span class="n">photos</span><span class="p">()</span>
 
     <span class="k">def</span> <span class="nf">_format_uuid</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">uuid</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
-        <span class="sd">""" "Format uuid for verbose output"""</span>
-        <span class="k">return</span> <span class="sa">f</span><span class="s2">"[uuid]</span><span class="si">{</span><span class="n">uuid</span><span class="si">}</span><span class="s2">[/uuid]"</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">rich</span> <span class="k">else</span> <span class="n">uuid</span>
+        <span class="sd">&quot;&quot;&quot; &quot;Format uuid for verbose output&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;[uuid]</span><span class="si">{</span><span class="n">uuid</span><span class="si">}</span><span class="s2">[/uuid]&quot;</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">rich</span> <span class="k">else</span> <span class="n">uuid</span>
 
     <span class="k">def</span> <span class="nf">_format_album</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">album</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
-        <span class="sd">""" "Format album name for verbose output"""</span>
-        <span class="k">return</span> <span class="sa">f</span><span class="s2">"[filepath]</span><span class="si">{</span><span class="n">album</span><span class="si">}</span><span class="s2">[/filepath]"</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">rich</span> <span class="k">else</span> <span class="n">album</span>
+        <span class="sd">&quot;&quot;&quot; &quot;Format album name for verbose output&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;[filepath]</span><span class="si">{</span><span class="n">album</span><span class="si">}</span><span class="s2">[/filepath]&quot;</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">rich</span> <span class="k">else</span> <span class="n">album</span>
 
     <span class="k">def</span> <span class="nf">_format_name</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
-        <span class="sd">""" "Format name for verbose output"""</span>
-        <span class="k">return</span> <span class="sa">f</span><span class="s2">"[filename]</span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">[/filename]"</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">rich</span> <span class="k">else</span> <span class="n">name</span>
+        <span class="sd">&quot;&quot;&quot; &quot;Format name for verbose output&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;[filename]</span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">[/filename]&quot;</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">rich</span> <span class="k">else</span> <span class="n">name</span>
 
     <span class="k">def</span> <span class="nf">_format_num</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">num</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
-        <span class="sd">""" "Format number for verbose output"""</span>
-        <span class="k">return</span> <span class="sa">f</span><span class="s2">"[num]</span><span class="si">{</span><span class="n">num</span><span class="si">}</span><span class="s2">[/num]"</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">rich</span> <span class="k">else</span> <span class="nb">str</span><span class="p">(</span><span class="n">num</span><span class="p">)</span></div>
+        <span class="sd">&quot;&quot;&quot; &quot;Format number for verbose output&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;[num]</span><span class="si">{</span><span class="n">num</span><span class="si">}</span><span class="s2">[/num]&quot;</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">rich</span> <span class="k">else</span> <span class="nb">str</span><span class="p">(</span><span class="n">num</span><span class="p">)</span></div>
 
 
 <div class="viewcode-block" id="PhotosAlbumPhotoScript"><a class="viewcode-back" href="../../reference.html#osxphotos.PhotosAlbumPhotoScript">[docs]</a><span class="k">class</span> <span class="nc">PhotosAlbumPhotoScript</span><span class="p">(</span><span class="n">PhotosAlbum</span><span class="p">):</span>
-    <span class="sd">"""Add photoscript.Photo objects to album"""</span>
+    <span class="sd">&quot;&quot;&quot;Add photoscript.Photo objects to album&quot;&quot;&quot;</span>
 
     <span class="k">def</span> <span class="nf">add</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">photo</span><span class="p">:</span> <span class="n">Photo</span><span class="p">):</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">album</span><span class="o">.</span><span class="n">add</span><span class="p">([</span><span class="n">photo</span><span class="p">])</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">verbose</span><span class="p">(</span>
-            <span class="sa">f</span><span class="s2">"Added </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_name</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">filename</span><span class="p">)</span><span class="si">}</span><span class="s2"> (</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_uuid</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">uuid</span><span class="p">)</span><span class="si">}</span><span class="s2">) to album </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_album</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="si">}</span><span class="s2">"</span>
+            <span class="sa">f</span><span class="s2">&quot;Added </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_name</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">filename</span><span class="p">)</span><span class="si">}</span><span class="s2"> (</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_uuid</span><span class="p">(</span><span class="n">photo</span><span class="o">.</span><span class="n">uuid</span><span class="p">)</span><span class="si">}</span><span class="s2">) to album </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_album</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span>
         <span class="p">)</span>
 
     <span class="k">def</span> <span class="nf">add_list</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">photo_list</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">Photo</span><span class="p">]):</span>
@@ -338,7 +345,7 @@
             <span class="bp">self</span><span class="o">.</span><span class="n">album</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">photolist</span><span class="p">)</span>
         <span class="n">photo_len</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">photo_list</span><span class="p">)</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">verbose</span><span class="p">(</span>
-            <span class="sa">f</span><span class="s2">"Added </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_num</span><span class="p">(</span><span class="n">photo_len</span><span class="p">)</span><span class="si">}</span><span class="s2"> </span><span class="si">{</span><span class="n">pluralize</span><span class="p">(</span><span class="n">photo_len</span><span class="p">,</span> <span class="s1">'photo'</span><span class="p">,</span> <span class="s1">'photos'</span><span class="p">)</span><span class="si">}</span><span class="s2"> to album </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_album</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="si">}</span><span class="s2">"</span>
+            <span class="sa">f</span><span class="s2">&quot;Added </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_num</span><span class="p">(</span><span class="n">photo_len</span><span class="p">)</span><span class="si">}</span><span class="s2"> </span><span class="si">{</span><span class="n">pluralize</span><span class="p">(</span><span class="n">photo_len</span><span class="p">,</span> <span class="s1">&#39;photo&#39;</span><span class="p">,</span> <span class="s1">&#39;photos&#39;</span><span class="p">)</span><span class="si">}</span><span class="s2"> to album </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_album</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span>
         <span class="p">)</span></div>
 </pre></div>
         </article>
@@ -377,7 +384,9 @@
 </div><script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
     <script src="../../_static/jquery.js"></script>
     <script src="../../_static/underscore.js"></script>
+    <script src="../../_static/_sphinx_javascript_frameworks_compat.js"></script>
     <script src="../../_static/doctools.js"></script>
+    <script src="../../_static/sphinx_highlight.js"></script>
     <script src="../../_static/scripts/furo.js"></script>
     <script src="../../_static/clipboard.min.js"></script>
     <script src="../../_static/copybutton.js"></script>

docs/_modules/osxphotos/photosdb/_photosdb_process_comments.html

@@ -1,13 +1,13 @@
 <!doctype html>
-<html class="no-js">
+<html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../../genindex.html" /><link rel="search" title="Search" href="../../../search.html" />
 
-    <meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
-        <title>osxphotos.photosdb._photosdb_process_comments - osxphotos 0.50.13 documentation</title>
+    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
+        <title>osxphotos.photosdb._photosdb_process_comments - osxphotos 0.60.2 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../../_static/pygments.css" />
-    <link rel="stylesheet" type="text/css" href="../../../_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
+    <link rel="stylesheet" type="text/css" href="../../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../../_static/copybutton.css" />
     <link rel="stylesheet" type="text/css" href="../../../_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
     
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../../index.html"><div class="brand">osxphotos 0.50.13 documentation</div></a>
+      <a href="../../../index.html"><div class="brand">osxphotos 0.60.2 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.50.13 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.2 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -179,7 +179,8 @@
           </svg>
           <span>Back to top</span>
         </a>
-        <div class="content-icon-container"><div class="theme-toggle-container theme-toggle-content">
+        <div class="content-icon-container">
+          <div class="theme-toggle-container theme-toggle-content">
             <button class="theme-toggle">
               <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
               <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
@@ -194,8 +195,8 @@
         </div>
         <article role="main">
           <h1>Source code for osxphotos.photosdb._photosdb_process_comments</h1><div class="highlight"><pre>
-<span></span><span class="sd">""" PhotosDB method for processing comments and likes on shared photos.</span>
-<span class="sd">    Do not import this module directly """</span>
+<span></span><span class="sd">&quot;&quot;&quot; PhotosDB method for processing comments and likes on shared photos.</span>
+<span class="sd">    Do not import this module directly &quot;&quot;&quot;</span>
 
 <span class="kn">import</span> <span class="nn">dataclasses</span>
 <span class="kn">import</span> <span class="nn">datetime</span>
@@ -207,10 +208,10 @@
 
 
 <span class="k">def</span> <span class="nf">_process_comments</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-    <span class="sd">"""load the comments and likes data from the database</span>
+    <span class="sd">&quot;&quot;&quot;load the comments and likes data from the database</span>
 <span class="sd">    this is a PhotosDB method that should be imported in</span>
 <span class="sd">    the PhotosDB class definition in photosdb.py</span>
-<span class="sd">    """</span>
+<span class="sd">    &quot;&quot;&quot;</span>
     <span class="bp">self</span><span class="o">.</span><span class="n">_db_hashed_person_id</span> <span class="o">=</span> <span class="p">{}</span>
     <span class="bp">self</span><span class="o">.</span><span class="n">_db_comments_uuid</span> <span class="o">=</span> <span class="p">{}</span>
     <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">&lt;=</span> <span class="n">_PHOTOS_4_VERSION</span><span class="p">:</span>
@@ -221,7 +222,7 @@
 
 <div class="viewcode-block" id="CommentInfo"><a class="viewcode-back" href="../../../reference.html#osxphotos.CommentInfo">[docs]</a><span class="nd">@dataclass</span>
 <span class="k">class</span> <span class="nc">CommentInfo</span><span class="p">:</span>
-    <span class="sd">"""Class for shared photo comments"""</span>
+    <span class="sd">&quot;&quot;&quot;Class for shared photo comments&quot;&quot;&quot;</span>
 
     <span class="n">datetime</span><span class="p">:</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span>
     <span class="n">user</span><span class="p">:</span> <span class="nb">str</span>
@@ -234,7 +235,7 @@
 
 <div class="viewcode-block" id="LikeInfo"><a class="viewcode-back" href="../../../reference.html#osxphotos.LikeInfo">[docs]</a><span class="nd">@dataclass</span>
 <span class="k">class</span> <span class="nc">LikeInfo</span><span class="p">:</span>
-    <span class="sd">"""Class for shared photo likes"""</span>
+    <span class="sd">&quot;&quot;&quot;Class for shared photo likes&quot;&quot;&quot;</span>
 
     <span class="n">datetime</span><span class="p">:</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span>
     <span class="n">user</span><span class="p">:</span> <span class="nb">str</span>
@@ -247,25 +248,25 @@
 <span class="c1"># The following methods do not get imported into PhotosDB</span>
 <span class="c1"># but will get called by _process_comments</span>
 <span class="k">def</span> <span class="nf">_process_comments_4</span><span class="p">(</span><span class="n">photosdb</span><span class="p">):</span>
-    <span class="sd">"""process comments and likes info for Photos &lt;= 4</span>
-<span class="sd">    photosdb: PhotosDB instance"""</span>
+    <span class="sd">&quot;&quot;&quot;process comments and likes info for Photos &lt;= 4</span>
+<span class="sd">    photosdb: PhotosDB instance&quot;&quot;&quot;</span>
     <span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">(</span>
-        <span class="sa">f</span><span class="s2">"Not implemented for database version </span><span class="si">{</span><span class="n">photosdb</span><span class="o">.</span><span class="n">_db_version</span><span class="si">}</span><span class="s2">."</span>
+        <span class="sa">f</span><span class="s2">&quot;Not implemented for database version </span><span class="si">{</span><span class="n">photosdb</span><span class="o">.</span><span class="n">_db_version</span><span class="si">}</span><span class="s2">.&quot;</span>
     <span class="p">)</span>
 
 
 <span class="k">def</span> <span class="nf">_process_comments_5</span><span class="p">(</span><span class="n">photosdb</span><span class="p">):</span>
-    <span class="sd">"""process comments and likes info for Photos &gt;= 5</span>
-<span class="sd">    photosdb: PhotosDB instance"""</span>
+    <span class="sd">&quot;&quot;&quot;process comments and likes info for Photos &gt;= 5</span>
+<span class="sd">    photosdb: PhotosDB instance&quot;&quot;&quot;</span>
 
     <span class="n">db</span> <span class="o">=</span> <span class="n">photosdb</span><span class="o">.</span><span class="n">_tmp_db</span>
 
-    <span class="n">asset_table</span> <span class="o">=</span> <span class="n">_DB_TABLE_NAMES</span><span class="p">[</span><span class="n">photosdb</span><span class="o">.</span><span class="n">_photos_ver</span><span class="p">][</span><span class="s2">"ASSET"</span><span class="p">]</span>
+    <span class="n">asset_table</span> <span class="o">=</span> <span class="n">_DB_TABLE_NAMES</span><span class="p">[</span><span class="n">photosdb</span><span class="o">.</span><span class="n">_photos_ver</span><span class="p">][</span><span class="s2">&quot;ASSET&quot;</span><span class="p">]</span>
 
     <span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">)</span> <span class="o">=</span> <span class="n">sqlite_open_ro</span><span class="p">(</span><span class="n">db</span><span class="p">)</span>
 
     <span class="n">results</span> <span class="o">=</span> <span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span>
-        <span class="sd">"""</span>
+        <span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        SELECT DISTINCT</span>
 <span class="sd">        ZINVITEEHASHEDPERSONID AS HASHEDPERSONID,</span>
 <span class="sd">        ZINVITEEFIRSTNAME AS FIRSTNAME,</span>
@@ -273,7 +274,7 @@
 <span class="sd">        ZINVITEEFULLNAME AS FULLNAME</span>
 <span class="sd">        FROM ZCLOUDSHAREDALBUMINVITATIONRECORD</span>
 <span class="sd">        WHERE HASHEDPERSONID IS NOT NULL</span>
-<span class="sd">        AND HASHEDPERSONID != ""</span>
+<span class="sd">        AND HASHEDPERSONID != &quot;&quot;</span>
 <span class="sd">        AND NOT (FIRSTNAME IS NULL AND LASTNAME IS NULL)</span>
 <span class="sd">        UNION</span>
 <span class="sd">        SELECT DISTINCT</span>
@@ -283,9 +284,9 @@
 <span class="sd">        ZCLOUDOWNERFULLNAME AS FULLNAME</span>
 <span class="sd">        FROM ZGENERICALBUM</span>
 <span class="sd">        WHERE HASHEDPERSONID IS NOT NULL</span>
-<span class="sd">        AND HASHEDPERSONID != ""</span>
+<span class="sd">        AND HASHEDPERSONID != &quot;&quot;</span>
 <span class="sd">        AND NOT (FIRSTNAME IS NULL AND LASTNAME IS NULL)</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
     <span class="p">)</span>
 
     <span class="c1"># order of results</span>
@@ -298,35 +299,35 @@
     <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">results</span><span class="o">.</span><span class="n">fetchall</span><span class="p">():</span>
         <span class="n">person_id</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
         <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_hashed_person_id</span><span class="p">[</span><span class="n">person_id</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span>
-            <span class="s2">"first_name"</span><span class="p">:</span> <span class="n">normalize_unicode</span><span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">]),</span>
-            <span class="s2">"last_name"</span><span class="p">:</span> <span class="n">normalize_unicode</span><span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]),</span>
-            <span class="s2">"full_name"</span><span class="p">:</span> <span class="n">normalize_unicode</span><span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="mi">3</span><span class="p">]),</span>
+            <span class="s2">&quot;first_name&quot;</span><span class="p">:</span> <span class="n">normalize_unicode</span><span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">]),</span>
+            <span class="s2">&quot;last_name&quot;</span><span class="p">:</span> <span class="n">normalize_unicode</span><span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]),</span>
+            <span class="s2">&quot;full_name&quot;</span><span class="p">:</span> <span class="n">normalize_unicode</span><span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="mi">3</span><span class="p">]),</span>
         <span class="p">}</span>
 
     <span class="n">results</span> <span class="o">=</span> <span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span>
-        <span class="sa">f</span><span class="s2">"""</span>
+        <span class="sa">f</span><span class="s2">&quot;&quot;&quot;</span>
 <span class="s2">        SELECT </span>
 <span class="s2">        </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZUUID, -- UUID of the photo</span>
-<span class="s2">        ZCLOUDSHAREDCOMMENT.ZISLIKE, -- comment is actually a "like"</span>
+<span class="s2">        ZCLOUDSHAREDCOMMENT.ZISLIKE, -- comment is actually a &quot;like&quot;</span>
 <span class="s2">        ZCLOUDSHAREDCOMMENT.ZCOMMENTDATE, -- date of comment</span>
 <span class="s2">        ZCLOUDSHAREDCOMMENT.ZCOMMENTTEXT, -- text of comment</span>
 <span class="s2">        ZCLOUDSHAREDCOMMENT.ZCOMMENTERHASHEDPERSONID, -- hashed ID of person who made comment/like</span>
-<span class="s2">        ZCLOUDSHAREDCOMMENT.ZISMYCOMMENT -- is my (this user's) comment</span>
+<span class="s2">        ZCLOUDSHAREDCOMMENT.ZISMYCOMMENT -- is my (this user&#39;s) comment</span>
 <span class="s2">        FROM ZCLOUDSHAREDCOMMENT</span>
 <span class="s2">        JOIN </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2"> ON</span>
 <span class="s2">        </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.Z_PK = ZCLOUDSHAREDCOMMENT.ZCOMMENTEDASSET</span>
 <span class="s2">        OR</span>
 <span class="s2">        </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.Z_PK = ZCLOUDSHAREDCOMMENT.ZLIKEDASSET</span>
-<span class="s2">    """</span>
+<span class="s2">    &quot;&quot;&quot;</span>
     <span class="p">)</span>
 
     <span class="c1"># order of results</span>
     <span class="c1"># 0: ZGENERICASSET.ZUUID, -- UUID of the photo</span>
-    <span class="c1"># 1: ZCLOUDSHAREDCOMMENT.ZISLIKE, -- comment is actually a "like"</span>
+    <span class="c1"># 1: ZCLOUDSHAREDCOMMENT.ZISLIKE, -- comment is actually a &quot;like&quot;</span>
     <span class="c1"># 2: ZCLOUDSHAREDCOMMENT.ZCOMMENTDATE, -- date of comment</span>
     <span class="c1"># 3: ZCLOUDSHAREDCOMMENT.ZCOMMENTTEXT, -- text of comment</span>
     <span class="c1"># 4: ZCLOUDSHAREDCOMMENT.ZCOMMENTERHASHEDPERSONID, -- hashed ID of person who made comment/like</span>
-    <span class="c1"># 5: ZCLOUDSHAREDCOMMENT.ZISMYCOMMENT -- is my (this user's) comment</span>
+    <span class="c1"># 5: ZCLOUDSHAREDCOMMENT.ZISMYCOMMENT -- is my (this user&#39;s) comment</span>
 
     <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_comments_uuid</span> <span class="o">=</span> <span class="p">{}</span>
     <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">results</span><span class="p">:</span>
@@ -334,7 +335,7 @@
         <span class="n">is_like</span> <span class="o">=</span> <span class="nb">bool</span><span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>
         <span class="n">text</span> <span class="o">=</span> <span class="n">normalize_unicode</span><span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="mi">3</span><span class="p">])</span>
         <span class="k">try</span><span class="p">:</span>
-            <span class="n">user_name</span> <span class="o">=</span> <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_hashed_person_id</span><span class="p">[</span><span class="n">row</span><span class="p">[</span><span class="mi">4</span><span class="p">]][</span><span class="s2">"full_name"</span><span class="p">]</span>
+            <span class="n">user_name</span> <span class="o">=</span> <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_hashed_person_id</span><span class="p">[</span><span class="n">row</span><span class="p">[</span><span class="mi">4</span><span class="p">]][</span><span class="s2">&quot;full_name&quot;</span><span class="p">]</span>
         <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
             <span class="n">user_name</span> <span class="o">=</span> <span class="kc">None</span>
 
@@ -348,20 +349,20 @@
         <span class="k">try</span><span class="p">:</span>
             <span class="n">db_comments</span> <span class="o">=</span> <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_comments_uuid</span><span class="p">[</span><span class="n">uuid</span><span class="p">]</span>
         <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
-            <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_comments_uuid</span><span class="p">[</span><span class="n">uuid</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"likes"</span><span class="p">:</span> <span class="p">[],</span> <span class="s2">"comments"</span><span class="p">:</span> <span class="p">[]}</span>
+            <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_comments_uuid</span><span class="p">[</span><span class="n">uuid</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;likes&quot;</span><span class="p">:</span> <span class="p">[],</span> <span class="s2">&quot;comments&quot;</span><span class="p">:</span> <span class="p">[]}</span>
             <span class="n">db_comments</span> <span class="o">=</span> <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_comments_uuid</span><span class="p">[</span><span class="n">uuid</span><span class="p">]</span>
 
         <span class="k">if</span> <span class="n">is_like</span><span class="p">:</span>
-            <span class="n">db_comments</span><span class="p">[</span><span class="s2">"likes"</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">LikeInfo</span><span class="p">(</span><span class="n">dt</span><span class="p">,</span> <span class="n">user_name</span><span class="p">,</span> <span class="n">ismine</span><span class="p">))</span>
+            <span class="n">db_comments</span><span class="p">[</span><span class="s2">&quot;likes&quot;</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">LikeInfo</span><span class="p">(</span><span class="n">dt</span><span class="p">,</span> <span class="n">user_name</span><span class="p">,</span> <span class="n">ismine</span><span class="p">))</span>
         <span class="k">elif</span> <span class="n">text</span><span class="p">:</span>
-            <span class="n">db_comments</span><span class="p">[</span><span class="s2">"comments"</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">CommentInfo</span><span class="p">(</span><span class="n">dt</span><span class="p">,</span> <span class="n">user_name</span><span class="p">,</span> <span class="n">ismine</span><span class="p">,</span> <span class="n">text</span><span class="p">))</span>
+            <span class="n">db_comments</span><span class="p">[</span><span class="s2">&quot;comments&quot;</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">CommentInfo</span><span class="p">(</span><span class="n">dt</span><span class="p">,</span> <span class="n">user_name</span><span class="p">,</span> <span class="n">ismine</span><span class="p">,</span> <span class="n">text</span><span class="p">))</span>
 
     <span class="c1"># sort results</span>
     <span class="k">for</span> <span class="n">uuid</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_comments_uuid</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
-        <span class="k">if</span> <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_comments_uuid</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">"likes"</span><span class="p">]:</span>
-            <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_comments_uuid</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">"likes"</span><span class="p">]</span><span class="o">.</span><span class="n">sort</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span><span class="o">.</span><span class="n">datetime</span><span class="p">)</span>
-        <span class="k">if</span> <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_comments_uuid</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">"comments"</span><span class="p">]:</span>
-            <span class="n">value</span><span class="p">[</span><span class="s2">"comments"</span><span class="p">]</span><span class="o">.</span><span class="n">sort</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span><span class="o">.</span><span class="n">datetime</span><span class="p">)</span>
+        <span class="k">if</span> <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_comments_uuid</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;likes&quot;</span><span class="p">]:</span>
+            <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_comments_uuid</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;likes&quot;</span><span class="p">]</span><span class="o">.</span><span class="n">sort</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span><span class="o">.</span><span class="n">datetime</span><span class="p">)</span>
+        <span class="k">if</span> <span class="n">photosdb</span><span class="o">.</span><span class="n">_db_comments_uuid</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;comments&quot;</span><span class="p">]:</span>
+            <span class="n">value</span><span class="p">[</span><span class="s2">&quot;comments&quot;</span><span class="p">]</span><span class="o">.</span><span class="n">sort</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span><span class="o">.</span><span class="n">datetime</span><span class="p">)</span>
 
     <span class="n">conn</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
 </pre></div>
@@ -401,7 +402,9 @@
 </div><script data-url_root="../../../" id="documentation_options" src="../../../_static/documentation_options.js"></script>
     <script src="../../../_static/jquery.js"></script>
     <script src="../../../_static/underscore.js"></script>
+    <script src="../../../_static/_sphinx_javascript_frameworks_compat.js"></script>
     <script src="../../../_static/doctools.js"></script>
+    <script src="../../../_static/sphinx_highlight.js"></script>
     <script src="../../../_static/scripts/furo.js"></script>
     <script src="../../../_static/clipboard.min.js"></script>
     <script src="../../../_static/copybutton.js"></script>

docs/_modules/osxphotos/photosdb/photosdb.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../../genindex.html" /><link rel="search" title="Search" href="../../../search.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>osxphotos.photosdb.photosdb - osxphotos 0.56.2 documentation</title>
+        <title>osxphotos.photosdb.photosdb - osxphotos 0.60.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../../_static/copybutton.css" />
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../../index.html"><div class="brand">osxphotos 0.56.2 documentation</div></a>
+      <a href="../../../index.html"><div class="brand">osxphotos 0.60.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.56.2 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -200,22 +200,24 @@
 <span class="sd">Processes a Photos.app library database to extract information about photos</span>
 <span class="sd">&quot;&quot;&quot;</span>
 
+<span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">annotations</span>
+
 <span class="kn">import</span> <span class="nn">logging</span>
 <span class="kn">import</span> <span class="nn">os</span>
 <span class="kn">import</span> <span class="nn">os.path</span>
 <span class="kn">import</span> <span class="nn">pathlib</span>
 <span class="kn">import</span> <span class="nn">platform</span>
 <span class="kn">import</span> <span class="nn">re</span>
+<span class="kn">import</span> <span class="nn">sqlite3</span>
 <span class="kn">import</span> <span class="nn">sys</span>
 <span class="kn">import</span> <span class="nn">tempfile</span>
 <span class="kn">from</span> <span class="nn">collections</span> <span class="kn">import</span> <span class="n">OrderedDict</span>
 <span class="kn">from</span> <span class="nn">collections.abc</span> <span class="kn">import</span> <span class="n">Iterable</span>
 <span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span><span class="p">,</span> <span class="n">timedelta</span><span class="p">,</span> <span class="n">timezone</span>
-<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">List</span><span class="p">,</span> <span class="n">Optional</span>
+<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Any</span><span class="p">,</span> <span class="n">List</span><span class="p">,</span> <span class="n">Optional</span>
 <span class="kn">from</span> <span class="nn">unicodedata</span> <span class="kn">import</span> <span class="n">normalize</span>
 
 <span class="kn">import</span> <span class="nn">bitmath</span>
-<span class="kn">import</span> <span class="nn">photoscript</span>
 <span class="kn">from</span> <span class="nn">rich</span> <span class="kn">import</span> <span class="nb">print</span>
 
 <span class="kn">from</span> <span class="nn">.._constants</span> <span class="kn">import</span> <span class="p">(</span>
@@ -247,7 +249,6 @@
 <span class="kn">from</span> <span class="nn">.._version</span> <span class="kn">import</span> <span class="n">__version__</span>
 <span class="kn">from</span> <span class="nn">..albuminfo</span> <span class="kn">import</span> <span class="n">AlbumInfo</span><span class="p">,</span> <span class="n">FolderInfo</span><span class="p">,</span> <span class="n">ImportInfo</span><span class="p">,</span> <span class="n">ProjectInfo</span>
 <span class="kn">from</span> <span class="nn">..datetime_utils</span> <span class="kn">import</span> <span class="n">datetime_has_tz</span><span class="p">,</span> <span class="n">datetime_naive_to_local</span>
-<span class="kn">from</span> <span class="nn">..debug</span> <span class="kn">import</span> <span class="n">is_debug</span>
 <span class="kn">from</span> <span class="nn">..fileutil</span> <span class="kn">import</span> <span class="n">FileUtil</span>
 <span class="kn">from</span> <span class="nn">..personinfo</span> <span class="kn">import</span> <span class="n">PersonInfo</span>
 <span class="kn">from</span> <span class="nn">..photoinfo</span> <span class="kn">import</span> <span class="n">PhotoInfo</span>
@@ -257,13 +258,19 @@
 <span class="kn">from</span> <span class="nn">..sqlite_utils</span> <span class="kn">import</span> <span class="n">sqlite_db_is_locked</span><span class="p">,</span> <span class="n">sqlite_open_ro</span>
 <span class="kn">from</span> <span class="nn">..utils</span> <span class="kn">import</span> <span class="p">(</span>
     <span class="n">_check_file_exists</span><span class="p">,</span>
-    <span class="n">_get_os_version</span><span class="p">,</span>
+    <span class="n">is_macos</span><span class="p">,</span>
+    <span class="n">get_macos_version</span><span class="p">,</span>
     <span class="n">get_last_library_path</span><span class="p">,</span>
     <span class="n">noop</span><span class="p">,</span>
     <span class="n">normalize_unicode</span><span class="p">,</span>
 <span class="p">)</span>
 <span class="kn">from</span> <span class="nn">.photosdb_utils</span> <span class="kn">import</span> <span class="n">get_db_model_version</span><span class="p">,</span> <span class="n">get_db_version</span>
 
+<span class="k">if</span> <span class="n">is_macos</span><span class="p">:</span>
+    <span class="kn">import</span> <span class="nn">photoscript</span>
+
+<span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s2">&quot;osxphotos&quot;</span><span class="p">)</span>
+
 <span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;PhotosDB&quot;</span><span class="p">]</span>
 
 <span class="c1"># TODO: Add test for imageTimeZoneOffsetSeconds = None</span>
@@ -286,6 +293,7 @@
         <span class="n">labels_normalized</span><span class="p">,</span>
         <span class="n">labels_normalized_as_dict</span><span class="p">,</span>
     <span class="p">)</span>
+    <span class="kn">from</span> <span class="nn">._photosdb_process_syndicationinfo</span> <span class="kn">import</span> <span class="n">_process_syndicationinfo</span>
 
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span>
         <span class="bp">self</span><span class="p">,</span>
@@ -311,8 +319,8 @@
 
         <span class="c1"># Check OS version</span>
         <span class="n">system</span> <span class="o">=</span> <span class="n">platform</span><span class="o">.</span><span class="n">system</span><span class="p">()</span>
-        <span class="p">(</span><span class="n">ver</span><span class="p">,</span> <span class="n">major</span><span class="p">,</span> <span class="n">_</span><span class="p">)</span> <span class="o">=</span> <span class="n">_get_os_version</span><span class="p">()</span>
-        <span class="k">if</span> <span class="n">system</span> <span class="o">!=</span> <span class="s2">&quot;Darwin&quot;</span> <span class="ow">or</span> <span class="p">((</span><span class="n">ver</span><span class="p">,</span> <span class="n">major</span><span class="p">)</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">_TESTED_OS_VERSIONS</span><span class="p">):</span>
+        <span class="p">(</span><span class="n">ver</span><span class="p">,</span> <span class="n">major</span><span class="p">,</span> <span class="n">_</span><span class="p">)</span> <span class="o">=</span> <span class="n">get_macos_version</span><span class="p">()</span> <span class="k">if</span> <span class="n">is_macos</span> <span class="k">else</span> <span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
+        <span class="k">if</span> <span class="n">system</span> <span class="o">==</span> <span class="s2">&quot;Darwin&quot;</span> <span class="ow">and</span> <span class="p">((</span><span class="n">ver</span><span class="p">,</span> <span class="n">major</span><span class="p">)</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">_TESTED_OS_VERSIONS</span><span class="p">):</span>
             <span class="n">logging</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span>
                 <span class="sa">f</span><span class="s2">&quot;WARNING: This module has only been tested with macOS versions &quot;</span>
                 <span class="sa">f</span><span class="s2">&quot;[</span><span class="si">{</span><span class="s1">&#39;, &#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;</span><span class="si">{</span><span class="n">v</span><span class="si">}</span><span class="s1">.</span><span class="si">{</span><span class="n">m</span><span class="si">}</span><span class="s1">&#39;</span> <span class="k">for</span> <span class="p">(</span><span class="n">v</span><span class="p">,</span> <span class="n">m</span><span class="p">)</span> <span class="ow">in</span> <span class="n">_TESTED_OS_VERSIONS</span><span class="p">)</span><span class="si">}</span><span class="s2">]: &quot;</span>
@@ -477,8 +485,14 @@
         <span class="c1"># key is Z_PK of ZMOMENT table and values are the moment info</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_db_moment_pk</span> <span class="o">=</span> <span class="p">{}</span>
 
-        <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;dbfile = </span><span class="si">{</span><span class="n">dbfile</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+        <span class="c1"># Dict to hold data on imports for Photos &lt;= 4</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_db_import_group</span> <span class="o">=</span> <span class="p">{}</span>
+
+        <span class="c1"># Dict to hold syndication info for Photos &gt;= 8</span>
+        <span class="c1"># key is UUID and value is dict of syndication info</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_db_syndication_uuid</span> <span class="o">=</span> <span class="p">{}</span>
+
+        <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;dbfile = </span><span class="si">{</span><span class="n">dbfile</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
 
         <span class="k">if</span> <span class="n">dbfile</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
             <span class="n">dbfile</span> <span class="o">=</span> <span class="n">get_last_library_path</span><span class="p">()</span>
@@ -494,8 +508,7 @@
         <span class="k">if</span> <span class="ow">not</span> <span class="n">_check_file_exists</span><span class="p">(</span><span class="n">dbfile</span><span class="p">):</span>
             <span class="k">raise</span> <span class="ne">FileNotFoundError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;dbfile </span><span class="si">{</span><span class="n">dbfile</span><span class="si">}</span><span class="s2"> does not exist&quot;</span><span class="p">,</span> <span class="n">dbfile</span><span class="p">)</span>
 
-        <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;dbfile = </span><span class="si">{</span><span class="n">dbfile</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+        <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;dbfile = </span><span class="si">{</span><span class="n">dbfile</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
 
         <span class="c1"># init database names</span>
         <span class="c1"># _tmp_db is the file that will processed by _process_database4/5</span>
@@ -521,8 +534,15 @@
         <span class="c1"># _db_version is set from photos.db</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">=</span> <span class="n">get_db_version</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_tmp_db</span><span class="p">)</span>
         <span class="c1"># _photos_version is set from Photos.sqlite which only exists for Photos 5+</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">_photos_ver</span> <span class="o">=</span> <span class="mi">4</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db_version</span> <span class="o">==</span> <span class="mi">4</span> <span class="k">else</span> <span class="mi">5</span>
-
+        <span class="n">db_ver_int</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_db_version</span><span class="p">)</span>
+        <span class="k">if</span> <span class="n">db_ver_int</span> <span class="o">&lt;</span> <span class="mi">3000</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_photos_ver</span> <span class="o">=</span> <span class="mi">2</span>
+        <span class="k">elif</span> <span class="n">db_ver_int</span> <span class="o">&lt;</span> <span class="mi">4000</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_photos_ver</span> <span class="o">=</span> <span class="mi">3</span>
+        <span class="k">elif</span> <span class="n">db_ver_int</span> <span class="o">&lt;</span> <span class="mi">5000</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_photos_ver</span> <span class="o">=</span> <span class="mi">4</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_photos_ver</span> <span class="o">=</span> <span class="mi">5</span>
         <span class="c1"># If Photos &gt;= 5, actual data isn&#39;t in photos.db but in Photos.sqlite</span>
         <span class="k">if</span> <span class="nb">int</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_db_version</span><span class="p">)</span> <span class="o">&gt;</span> <span class="nb">int</span><span class="p">(</span><span class="n">_PHOTOS_4_VERSION</span><span class="p">):</span>
             <span class="n">dbpath</span> <span class="o">=</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_dbfile</span><span class="p">)</span><span class="o">.</span><span class="n">parent</span>
@@ -539,10 +559,9 @@
             <span class="c1"># set the photos version to actual value based on Photos.sqlite</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_photos_ver</span> <span class="o">=</span> <span class="n">get_db_model_version</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_tmp_db</span><span class="p">)</span>
 
-            <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-                <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
-                    <span class="sa">f</span><span class="s2">&quot;_dbfile = </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_dbfile</span><span class="si">}</span><span class="s2">, _dbfile_actual = </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_dbfile_actual</span><span class="si">}</span><span class="s2">&quot;</span>
-                <span class="p">)</span>
+            <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
+                <span class="sa">f</span><span class="s2">&quot;_dbfile = </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_dbfile</span><span class="si">}</span><span class="s2">, _dbfile_actual = </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_dbfile_actual</span><span class="si">}</span><span class="s2">&quot;</span>
+            <span class="p">)</span>
 
         <span class="n">library_path</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span><span class="n">dbfile</span><span class="p">))</span>
         <span class="p">(</span><span class="n">library_path</span><span class="p">,</span> <span class="n">_</span><span class="p">)</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">library_path</span><span class="p">)</span>  <span class="c1"># drop /database from path</span>
@@ -554,8 +573,7 @@
             <span class="n">masters_path</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">library_path</span><span class="p">,</span> <span class="s2">&quot;originals&quot;</span><span class="p">)</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_masters_path</span> <span class="o">=</span> <span class="n">masters_path</span>
 
-        <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;library = </span><span class="si">{</span><span class="n">library_path</span><span class="si">}</span><span class="s2">, masters = </span><span class="si">{</span><span class="n">masters_path</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+        <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;library = </span><span class="si">{</span><span class="n">library_path</span><span class="si">}</span><span class="s2">, masters = </span><span class="si">{</span><span class="n">masters_path</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
 
         <span class="k">if</span> <span class="nb">int</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_db_version</span><span class="p">)</span> <span class="o">&lt;=</span> <span class="nb">int</span><span class="p">(</span><span class="n">_PHOTOS_4_VERSION</span><span class="p">):</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_process_database4</span><span class="p">()</span>
@@ -703,7 +721,8 @@
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">album_info_shared</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;return list of AlbumInfo objects for each shared album in the photos database</span>
-<span class="sd">        only valid for Photos 5; on Photos &lt;= 4, prints warning and returns empty list&quot;&quot;&quot;</span>
+<span class="sd">        only valid for Photos 5; on Photos &lt;= 4, prints warning and returns empty list</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="c1"># if _dbalbum_details[key][&quot;cloudownerhashedpersonid&quot;] is not None, then it&#39;s a shared album</span>
         <span class="k">try</span><span class="p">:</span>
             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_album_info_shared</span>
@@ -730,7 +749,8 @@
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">albums_shared</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;return list of shared albums found in photos database</span>
-<span class="sd">        only valid for Photos 5; on Photos &lt;= 4, prints warning and returns empty list&quot;&quot;&quot;</span>
+<span class="sd">        only valid for Photos 5; on Photos &lt;= 4, prints warning and returns empty list</span>
+<span class="sd">        &quot;&quot;&quot;</span>
 
         <span class="c1"># Could be more than one album with same name</span>
         <span class="c1"># Right now, they are treated as same album and photos are combined from albums with same name</span>
@@ -782,6 +802,11 @@
         <span class="sd">&quot;&quot;&quot;returns path to the Photos library PhotosDB was initialized with&quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_library_path</span>
 
+    <span class="nd">@property</span>
+    <span class="k">def</span> <span class="nf">photos_version</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;returns version of Photos app that created the library&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_photos_ver</span>
+
 <div class="viewcode-block" id="PhotosDB.get_db_connection"><a class="viewcode-back" href="../../../reference.html#osxphotos.PhotosDB.get_db_connection">[docs]</a>    <span class="k">def</span> <span class="nf">get_db_connection</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;Get connection to the working copy of the Photos database</span>
 
@@ -810,38 +835,10 @@
             <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Error copying</span><span class="si">{</span><span class="n">fname</span><span class="si">}</span><span class="s2"> to </span><span class="si">{</span><span class="n">dest_path</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">file</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="p">)</span>
             <span class="k">raise</span> <span class="ne">Exception</span>
 
-        <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="n">dest_path</span><span class="p">)</span>
+        <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="n">dest_path</span><span class="p">)</span>
 
         <span class="k">return</span> <span class="n">dest_path</span>
 
-    <span class="c1"># NOTE: This method seems to cause problems with applescript</span>
-    <span class="c1"># Bummer...would&#39;be been nice to avoid copying the DB</span>
-    <span class="c1"># def _link_db_file(self, fname):</span>
-    <span class="c1">#     &quot;&quot;&quot; links the sqlite database file to a temp file &quot;&quot;&quot;</span>
-    <span class="c1">#     &quot;&quot;&quot; returns the name of the temp file &quot;&quot;&quot;</span>
-    <span class="c1">#     &quot;&quot;&quot; If sqlite shared memory and write-ahead log files exist, those are copied too &quot;&quot;&quot;</span>
-    <span class="c1">#     # required because python&#39;s sqlite3 implementation can&#39;t read a locked file</span>
-    <span class="c1">#     # _, suffix = os.path.splitext(fname)</span>
-    <span class="c1">#     dest_name = dest_path = &quot;&quot;</span>
-    <span class="c1">#     try:</span>
-    <span class="c1">#         dest_name = pathlib.Path(fname).name</span>
-    <span class="c1">#         dest_path = os.path.join(self._tempdir_name, dest_name)</span>
-    <span class="c1">#         FileUtil.hardlink(fname, dest_path)</span>
-    <span class="c1">#         # link write-ahead log and shared memory files (-wal and -shm) files if they exist</span>
-    <span class="c1">#         if os.path.exists(f&quot;{fname}-wal&quot;):</span>
-    <span class="c1">#             FileUtil.hardlink(f&quot;{fname}-wal&quot;, f&quot;{dest_path}-wal&quot;)</span>
-    <span class="c1">#         if os.path.exists(f&quot;{fname}-shm&quot;):</span>
-    <span class="c1">#             FileUtil.hardlink(f&quot;{fname}-shm&quot;, f&quot;{dest_path}-shm&quot;)</span>
-    <span class="c1">#     except:</span>
-    <span class="c1">#         print(&quot;Error linking &quot; + fname + &quot; to &quot; + dest_path, file=sys.stderr)</span>
-    <span class="c1">#         raise Exception</span>
-
-    <span class="c1">#     if is_debug():</span>
-    <span class="c1">#         logging.debug(dest_path)</span>
-
-    <span class="c1">#     return dest_path</span>
-
     <span class="k">def</span> <span class="nf">_process_database4</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;process the Photos database to extract info</span>
 <span class="sd">        works on Photos version &lt;= 4.0&quot;&quot;&quot;</span>
@@ -890,6 +887,8 @@
                 <span class="s2">&quot;displayname&quot;</span><span class="p">:</span> <span class="n">normalize_unicode</span><span class="p">(</span><span class="n">person</span><span class="p">[</span><span class="mi">4</span><span class="p">]),</span>
                 <span class="s2">&quot;photo_uuid&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
                 <span class="s2">&quot;keyface_uuid&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
+                <span class="s2">&quot;type&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5+</span>
+                <span class="s2">&quot;manualorder&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>  <span class="c1"># Photos 5+</span>
             <span class="p">}</span>
             <span class="k">try</span><span class="p">:</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbpersons_fullname</span><span class="p">[</span><span class="n">fullname</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">pk</span><span class="p">)</span>
@@ -921,7 +920,7 @@
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbpersons_pk</span><span class="p">[</span><span class="n">pk</span><span class="p">][</span><span class="s2">&quot;photo_uuid&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbpersons_pk</span><span class="p">[</span><span class="n">pk</span><span class="p">][</span><span class="s2">&quot;keyface_uuid&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span>
             <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
-                <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Unexpected KeyError _dbpersons_pk[</span><span class="si">{</span><span class="n">pk</span><span class="si">}</span><span class="s2">]&quot;</span><span class="p">)</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Unexpected KeyError _dbpersons_pk[</span><span class="si">{</span><span class="n">pk</span><span class="si">}</span><span class="s2">]&quot;</span><span class="p">)</span>
 
         <span class="c1"># get information on detected faces</span>
         <span class="n">verbose</span><span class="p">(</span><span class="s2">&quot;Processing detected faces in photos.&quot;</span><span class="p">)</span>
@@ -1019,10 +1018,10 @@
                 <span class="s2">&quot;cloudlibrarystate&quot;</span><span class="p">:</span> <span class="n">album</span><span class="p">[</span><span class="mi">2</span><span class="p">],</span>
                 <span class="s2">&quot;cloudidentifier&quot;</span><span class="p">:</span> <span class="n">album</span><span class="p">[</span><span class="mi">3</span><span class="p">],</span>
                 <span class="s2">&quot;intrash&quot;</span><span class="p">:</span> <span class="kc">False</span> <span class="k">if</span> <span class="n">album</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="o">==</span> <span class="mi">0</span> <span class="k">else</span> <span class="kc">True</span><span class="p">,</span>
-                <span class="s2">&quot;cloudlocalstate&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5</span>
-                <span class="s2">&quot;cloudownerfirstname&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5</span>
-                <span class="s2">&quot;cloudownderlastname&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5</span>
-                <span class="s2">&quot;cloudownerhashedpersonid&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5</span>
+                <span class="s2">&quot;cloudlocalstate&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5+</span>
+                <span class="s2">&quot;cloudownerfirstname&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5+</span>
+                <span class="s2">&quot;cloudownderlastname&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5+</span>
+                <span class="s2">&quot;cloudownerhashedpersonid&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5+</span>
                 <span class="s2">&quot;folderUuid&quot;</span><span class="p">:</span> <span class="n">album</span><span class="p">[</span><span class="mi">5</span><span class="p">],</span>
                 <span class="s2">&quot;albumType&quot;</span><span class="p">:</span> <span class="n">album</span><span class="p">[</span><span class="mi">6</span><span class="p">],</span>
                 <span class="s2">&quot;albumSubclass&quot;</span><span class="p">:</span> <span class="n">album</span><span class="p">[</span><span class="mi">7</span><span class="p">],</span>
@@ -1253,9 +1252,8 @@
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;lastmodifieddate&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">fromtimestamp</span><span class="p">(</span>
                     <span class="n">row</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="o">+</span> <span class="n">TIME_DELTA</span>
                 <span class="p">)</span>
-            <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
-                <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;lastmodifieddate&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
-            <span class="k">except</span> <span class="ne">TypeError</span><span class="p">:</span>
+            <span class="k">except</span> <span class="p">(</span><span class="ne">ValueError</span><span class="p">,</span> <span class="ne">TypeError</span><span class="p">):</span>
+                <span class="c1"># sometimes the date is invalid or null</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;lastmodifieddate&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
 
             <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;imageTimeZoneOffsetSeconds&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">9</span><span class="p">]</span>
@@ -1267,8 +1265,8 @@
                 <span class="n">delta</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">seconds</span><span class="o">=</span><span class="n">seconds</span><span class="p">)</span>
                 <span class="n">tz</span> <span class="o">=</span> <span class="n">timezone</span><span class="p">(</span><span class="n">delta</span><span class="p">)</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;imageDate&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">imagedate</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">tz</span><span class="o">=</span><span class="n">tz</span><span class="p">)</span>
-            <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
-                <span class="c1"># sometimes imageDate is invalid so use 1 Jan 1970 in UTC as image date</span>
+            <span class="k">except</span> <span class="p">(</span><span class="ne">ValueError</span><span class="p">,</span> <span class="ne">TypeError</span><span class="p">):</span>
+                <span class="c1"># sometimes imageDate is invalid so use 1 Jan 1970 as image date</span>
                 <span class="n">imagedate</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1970</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
                 <span class="n">tz</span> <span class="o">=</span> <span class="n">timezone</span><span class="p">(</span><span class="n">timedelta</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;imageDate&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">imagedate</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">tz</span><span class="o">=</span><span class="n">tz</span><span class="p">)</span>
@@ -1298,8 +1296,7 @@
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;type&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">_MOVIE_TYPE</span>
             <span class="k">else</span><span class="p">:</span>
                 <span class="c1"># unknown</span>
-                <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-                    <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;WARNING: </span><span class="si">{</span><span class="n">uuid</span><span class="si">}</span><span class="s2"> found unknown type </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">21</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;WARNING: </span><span class="si">{</span><span class="n">uuid</span><span class="si">}</span><span class="s2"> found unknown type </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">21</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;type&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
 
             <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;UTI&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">22</span><span class="p">]</span>
@@ -1364,12 +1361,13 @@
             <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;momentID&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">28</span><span class="p">]</span>
 
             <span class="c1"># Init cloud details that will be filled in later if cloud asset</span>
-            <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;cloudAssetGUID&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 5</span>
-            <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;cloudLocalState&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 5</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;cloudAssetGUID&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 5+</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;cloudLocalState&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 5+</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;cloudLibraryState&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;cloudStatus&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;cloudAvailable&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;incloud&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;cloudMasterGUID&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 5+</span>
 
             <span class="c1"># associated RAW image info</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;has_raw&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">True</span> <span class="k">if</span> <span class="n">row</span><span class="p">[</span><span class="mi">25</span><span class="p">]</span> <span class="o">==</span> <span class="mi">7</span> <span class="k">else</span> <span class="kc">False</span>
@@ -1532,21 +1530,19 @@
                         <span class="k">if</span> <span class="n">resource_type</span> <span class="o">==</span> <span class="mi">4</span><span class="p">:</span>
                             <span class="c1"># photo</span>
                             <span class="k">if</span> <span class="s2">&quot;edit_resource_id_photo&quot;</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">]:</span>
-                                <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-                                    <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
-                                        <span class="sa">f</span><span class="s2">&quot;WARNING: found more than one edit_resource_id_photo for &quot;</span>
-                                        <span class="sa">f</span><span class="s2">&quot;UUID </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="si">}</span><span class="s2">,adjustmentUUID </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="si">}</span><span class="s2">, modelID </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span>
-                                    <span class="p">)</span>
+                                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
+                                    <span class="sa">f</span><span class="s2">&quot;WARNING: found more than one edit_resource_id_photo for &quot;</span>
+                                    <span class="sa">f</span><span class="s2">&quot;UUID </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="si">}</span><span class="s2">,adjustmentUUID </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="si">}</span><span class="s2">, modelID </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span>
+                                <span class="p">)</span>
                             <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;edit_resource_id_photo&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>
                             <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;UTI_edited_photo&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span>
                         <span class="k">elif</span> <span class="n">resource_type</span> <span class="o">==</span> <span class="mi">8</span><span class="p">:</span>
                             <span class="c1"># video</span>
                             <span class="k">if</span> <span class="s2">&quot;edit_resource_id_video&quot;</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">]:</span>
-                                <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-                                    <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
-                                        <span class="sa">f</span><span class="s2">&quot;WARNING: found more than one edit_resource_id_video for &quot;</span>
-                                        <span class="sa">f</span><span class="s2">&quot;UUID </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="si">}</span><span class="s2">,adjustmentUUID </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="si">}</span><span class="s2">, modelID </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span>
-                                    <span class="p">)</span>
+                                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
+                                    <span class="sa">f</span><span class="s2">&quot;WARNING: found more than one edit_resource_id_video for &quot;</span>
+                                    <span class="sa">f</span><span class="s2">&quot;UUID </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="si">}</span><span class="s2">,adjustmentUUID </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="si">}</span><span class="s2">, modelID </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span>
+                                <span class="p">)</span>
                             <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;edit_resource_id_video&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>
                             <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;UTI_edited_video&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span>
 
@@ -1835,8 +1831,7 @@
 <span class="sd">        but it works so don&#39;t touch it.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
 
-        <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;_process_database5&quot;</span><span class="p">)</span>
+        <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;_process_database5&quot;</span><span class="p">)</span>
         <span class="n">verbose</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_verbose</span>
         <span class="n">verbose</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Processing database.&quot;</span><span class="p">)</span>
         <span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">c</span><span class="p">)</span> <span class="o">=</span> <span class="n">sqlite_open_ro</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_tmp_db</span><span class="p">)</span>
@@ -1859,8 +1854,7 @@
         <span class="n">hdr_type_column</span> <span class="o">=</span> <span class="n">_DB_TABLE_NAMES</span><span class="p">[</span><span class="n">photos_ver</span><span class="p">][</span><span class="s2">&quot;HDR_TYPE&quot;</span><span class="p">]</span>
 
         <span class="c1"># Look for all combinations of persons and pictures</span>
-        <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Getting information about persons&quot;</span><span class="p">)</span>
+        <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Getting information about persons&quot;</span><span class="p">)</span>
 
         <span class="c1"># get info to associate persons with photos</span>
         <span class="c1"># then get detected faces in each photo and link to persons</span>
@@ -1872,7 +1866,9 @@
 <span class="sd">                ZPERSON.ZFULLNAME,</span>
 <span class="sd">                ZPERSON.ZFACECOUNT,</span>
 <span class="sd">                ZPERSON.ZKEYFACE,</span>
-<span class="sd">                ZPERSON.ZDISPLAYNAME</span>
+<span class="sd">                ZPERSON.ZDISPLAYNAME,</span>
+<span class="sd">                ZPERSON.ZTYPE,</span>
+<span class="sd">                ZPERSON.ZMANUALORDER</span>
 <span class="sd">                FROM ZPERSON</span>
 <span class="sd">            &quot;&quot;&quot;</span>
         <span class="p">)</span>
@@ -1883,6 +1879,8 @@
         <span class="c1"># 3     ZPERSON.ZFACECOUNT,</span>
         <span class="c1"># 4     ZPERSON.ZKEYFACE,</span>
         <span class="c1"># 5     ZPERSON.ZDISPLAYNAME</span>
+        <span class="c1"># 6     ZPERSON.ZTYPE,  # ZTYPE = 1 == favorite, 0 == not favorite</span>
+        <span class="c1"># 7     ZPERSON.ZMANUALORDER # favorites are sorted by ZMANUALORDER</span>
 
         <span class="k">for</span> <span class="n">person</span> <span class="ow">in</span> <span class="n">c</span><span class="p">:</span>
             <span class="n">pk</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
@@ -1900,6 +1898,8 @@
                 <span class="s2">&quot;displayname&quot;</span><span class="p">:</span> <span class="n">normalize_unicode</span><span class="p">(</span><span class="n">person</span><span class="p">[</span><span class="mi">5</span><span class="p">]),</span>
                 <span class="s2">&quot;photo_uuid&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
                 <span class="s2">&quot;keyface_uuid&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
+                <span class="s2">&quot;type&quot;</span><span class="p">:</span> <span class="n">person</span><span class="p">[</span><span class="mi">6</span><span class="p">],</span>
+                <span class="s2">&quot;manualorder&quot;</span><span class="p">:</span> <span class="n">person</span><span class="p">[</span><span class="mi">7</span><span class="p">],</span>
             <span class="p">}</span>
             <span class="k">try</span><span class="p">:</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbpersons_fullname</span><span class="p">[</span><span class="n">fullname</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">pk</span><span class="p">)</span>
@@ -1931,7 +1931,7 @@
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbpersons_pk</span><span class="p">[</span><span class="n">pk</span><span class="p">][</span><span class="s2">&quot;photo_uuid&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbpersons_pk</span><span class="p">[</span><span class="n">pk</span><span class="p">][</span><span class="s2">&quot;keyface_uuid&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">person</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span>
             <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
-                <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Unexpected KeyError _dbpersons_pk[</span><span class="si">{</span><span class="n">pk</span><span class="si">}</span><span class="s2">]&quot;</span><span class="p">)</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Unexpected KeyError _dbpersons_pk[</span><span class="si">{</span><span class="n">pk</span><span class="si">}</span><span class="s2">]&quot;</span><span class="p">)</span>
 
         <span class="c1"># get information on detected faces</span>
         <span class="n">verbose</span><span class="p">(</span><span class="s2">&quot;Processing detected faces in photos.&quot;</span><span class="p">)</span>
@@ -2228,8 +2228,8 @@
                 <span class="n">delta</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">seconds</span><span class="o">=</span><span class="n">seconds</span><span class="p">)</span>
                 <span class="n">tz</span> <span class="o">=</span> <span class="n">timezone</span><span class="p">(</span><span class="n">delta</span><span class="p">)</span>
                 <span class="n">info</span><span class="p">[</span><span class="s2">&quot;imageDate&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">imagedate</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">tz</span><span class="o">=</span><span class="n">tz</span><span class="p">)</span>
-            <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
-                <span class="c1"># sometimes imageDate is invalid so use 1 Jan 1970 in UTC as image date</span>
+            <span class="k">except</span> <span class="p">(</span><span class="ne">ValueError</span><span class="p">,</span> <span class="ne">TypeError</span><span class="p">):</span>
+                <span class="c1"># sometimes imageDate is invalid or null so use 1 Jan 1970 in UTC as image date (#1014)</span>
                 <span class="n">imagedate</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1970</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
                 <span class="n">tz</span> <span class="o">=</span> <span class="n">timezone</span><span class="p">(</span><span class="n">timedelta</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span>
                 <span class="n">info</span><span class="p">[</span><span class="s2">&quot;imageDate&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">imagedate</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">tz</span><span class="o">=</span><span class="n">tz</span><span class="p">)</span>
@@ -2269,8 +2269,7 @@
             <span class="k">elif</span> <span class="n">row</span><span class="p">[</span><span class="mi">17</span><span class="p">]</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>
                 <span class="n">info</span><span class="p">[</span><span class="s2">&quot;type&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">_MOVIE_TYPE</span>
             <span class="k">else</span><span class="p">:</span>
-                <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-                    <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;WARNING: </span><span class="si">{</span><span class="n">uuid</span><span class="si">}</span><span class="s2"> found unknown type </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">17</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;WARNING: </span><span class="si">{</span><span class="n">uuid</span><span class="si">}</span><span class="s2"> found unknown type </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">17</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
                 <span class="n">info</span><span class="p">[</span><span class="s2">&quot;type&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
 
             <span class="n">info</span><span class="p">[</span><span class="s2">&quot;UTI&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">18</span><span class="p">]</span>
@@ -2331,6 +2330,7 @@
             <span class="n">info</span><span class="p">[</span><span class="s2">&quot;cloudLibraryState&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 4</span>
             <span class="n">info</span><span class="p">[</span><span class="s2">&quot;cloudStatus&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 4</span>
             <span class="n">info</span><span class="p">[</span><span class="s2">&quot;cloudAvailable&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Photos 4</span>
+            <span class="n">info</span><span class="p">[</span><span class="s2">&quot;cloudMasterGUID&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
 
             <span class="c1"># reverse geolocation info</span>
             <span class="n">info</span><span class="p">[</span><span class="s2">&quot;reverse_geolocation&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">25</span><span class="p">]</span>
@@ -2457,7 +2457,7 @@
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;fok_import_session&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;import_uuid&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span>
             <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
-                <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;No info record for uuid </span><span class="si">{</span><span class="n">uuid</span><span class="si">}</span><span class="s2"> for import session&quot;</span><span class="p">)</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;No info record for uuid </span><span class="si">{</span><span class="n">uuid</span><span class="si">}</span><span class="s2"> for import session&quot;</span><span class="p">)</span>
 
         <span class="c1"># Get extended description</span>
         <span class="n">verbose</span><span class="p">(</span><span class="s2">&quot;Processing additional photo details.&quot;</span><span class="p">)</span>
@@ -2474,10 +2474,9 @@
             <span class="k">if</span> <span class="n">uuid</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">:</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;extendedDescription&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">normalize_unicode</span><span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>
             <span class="k">else</span><span class="p">:</span>
-                <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-                    <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
-                        <span class="sa">f</span><span class="s2">&quot;WARNING: found description </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="si">}</span><span class="s2"> but no photo for </span><span class="si">{</span><span class="n">uuid</span><span class="si">}</span><span class="s2">&quot;</span>
-                    <span class="p">)</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
+                    <span class="sa">f</span><span class="s2">&quot;WARNING: found description </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="si">}</span><span class="s2"> but no photo for </span><span class="si">{</span><span class="n">uuid</span><span class="si">}</span><span class="s2">&quot;</span>
+                <span class="p">)</span>
 
         <span class="c1"># get information about adjusted/edited photos</span>
         <span class="n">c</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span>
@@ -2493,10 +2492,9 @@
             <span class="k">if</span> <span class="n">uuid</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">:</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;adjustmentFormatID&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>
             <span class="k">else</span><span class="p">:</span>
-                <span class="k">if</span> <span class="n">is_debug</span><span class="p">():</span>
-                    <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
-                        <span class="sa">f</span><span class="s2">&quot;WARNING: found adjustmentformatidentifier </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="si">}</span><span class="s2"> but no photo for uuid </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span>
-                    <span class="p">)</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span>
+                    <span class="sa">f</span><span class="s2">&quot;WARNING: found adjustmentformatidentifier </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="si">}</span><span class="s2"> but no photo for uuid </span><span class="si">{</span><span class="n">row</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span>
+                <span class="p">)</span>
 
         <span class="c1"># Find missing photos</span>
         <span class="c1"># TODO: this code is very kludgy and I had to make lots of assumptions</span>
@@ -2579,7 +2577,8 @@
         <span class="n">c</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span>
             <span class="sa">f</span><span class="s2">&quot;&quot;&quot; SELECT</span>
 <span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZUUID,</span>
-<span class="s2">                ZCLOUDMASTER.ZCLOUDLOCALSTATE</span>
+<span class="s2">                ZCLOUDMASTER.ZCLOUDLOCALSTATE,</span>
+<span class="s2">                ZCLOUDMASTER.ZCLOUDMASTERGUID</span>
 <span class="s2">                FROM ZCLOUDMASTER, </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2"></span>
 <span class="s2">                WHERE </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZMASTER = ZCLOUDMASTER.Z_PK &quot;&quot;&quot;</span>
         <span class="p">)</span>
@@ -2588,6 +2587,7 @@
             <span class="k">if</span> <span class="n">uuid</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">:</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;cloudLocalState&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;incloud&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">True</span> <span class="k">if</span> <span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="mi">3</span> <span class="k">else</span> <span class="kc">False</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;cloudMasterGUID&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>
 
         <span class="c1"># get information about associted RAW images</span>
         <span class="c1"># RAW images have ZDATASTORESUBTYPE = 17</span>
@@ -2719,6 +2719,10 @@
         <span class="n">verbose</span><span class="p">(</span><span class="s2">&quot;Processing moments.&quot;</span><span class="p">)</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_process_moments</span><span class="p">()</span>
 
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">photos_version</span> <span class="o">&gt;=</span> <span class="mi">8</span><span class="p">:</span>
+            <span class="n">verbose</span><span class="p">(</span><span class="s2">&quot;Processing syndication info.&quot;</span><span class="p">)</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_process_syndicationinfo</span><span class="p">()</span>
+
         <span class="n">verbose</span><span class="p">(</span><span class="s2">&quot;Done processing details from Photos library.&quot;</span><span class="p">)</span>
 
     <span class="k">def</span> <span class="nf">_process_moments</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
@@ -2811,8 +2815,8 @@
                     <span class="c1"># save raw time stamp valu</span>
                     <span class="n">moment_info</span><span class="p">[</span><span class="n">date_name</span> <span class="o">+</span> <span class="s2">&quot;_timestamp&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">moment_info</span><span class="p">[</span><span class="n">date_name</span><span class="p">]</span>
                     <span class="n">moment_info</span><span class="p">[</span><span class="n">date_name</span><span class="p">]</span> <span class="o">=</span> <span class="n">moment_date</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">tz</span><span class="o">=</span><span class="n">tz</span><span class="p">)</span>
-                <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
-                    <span class="c1"># sometimes imageDate is invalid so use 1 Jan 1970 in UTC as image date</span>
+                <span class="k">except</span> <span class="p">(</span><span class="ne">ValueError</span><span class="p">,</span> <span class="ne">TypeError</span><span class="p">):</span>
+                    <span class="c1"># sometimes imageDate is invalid or null so use 1 Jan 1970 in UTC as image date</span>
                     <span class="n">moment_date</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">1970</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
                     <span class="n">tz</span> <span class="o">=</span> <span class="n">timezone</span><span class="p">(</span><span class="n">timedelta</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span>
                     <span class="n">moment_info</span><span class="p">[</span><span class="n">date_name</span> <span class="o">+</span> <span class="s2">&quot;_timestamp&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">date_stamp</span>
@@ -2870,7 +2874,7 @@
         <span class="k">try</span><span class="p">:</span>
             <span class="n">folders</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dbalbum_folders</span><span class="p">[</span><span class="n">album_uuid</span><span class="p">]</span>
         <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Caught _dbalbum_folders KeyError for album: </span><span class="si">{</span><span class="n">album_uuid</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+            <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Caught _dbalbum_folders KeyError for album: </span><span class="si">{</span><span class="n">album_uuid</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
             <span class="k">return</span> <span class="p">[]</span>
 
         <span class="k">def</span> <span class="nf">_recurse_folder_hierarchy</span><span class="p">(</span><span class="n">folders</span><span class="p">,</span> <span class="n">hierarchy</span><span class="o">=</span><span class="p">[]):</span>
@@ -2907,7 +2911,7 @@
         <span class="k">try</span><span class="p">:</span>
             <span class="n">folders</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dbalbum_folders</span><span class="p">[</span><span class="n">album_uuid</span><span class="p">]</span>
         <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
-            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Caught _dbalbum_folders KeyError for album: </span><span class="si">{</span><span class="n">album_uuid</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+            <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Caught _dbalbum_folders KeyError for album: </span><span class="si">{</span><span class="n">album_uuid</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
             <span class="k">return</span> <span class="p">[]</span>
 
         <span class="k">def</span> <span class="nf">_recurse_folder_hierarchy</span><span class="p">(</span><span class="n">folders</span><span class="p">,</span> <span class="n">hierarchy</span><span class="o">=</span><span class="p">[]):</span>
@@ -3260,7 +3264,6 @@
         <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
             <span class="k">return</span> <span class="kc">None</span></div>
 
-    <span class="c1"># TODO: add to docs and test</span>
 <div class="viewcode-block" id="PhotosDB.photos_by_uuid"><a class="viewcode-back" href="../../../reference.html#osxphotos.PhotosDB.photos_by_uuid">[docs]</a>    <span class="k">def</span> <span class="nf">photos_by_uuid</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">uuids</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;Returns a list of photos with UUID in uuids.</span>
 <span class="sd">            Does not generate error if invalid or missing UUID passed.</span>
@@ -3273,14 +3276,11 @@
 <span class="sd">        Returns:</span>
 <span class="sd">            list of PhotoInfo instance for photo with UUID matching uuid or [] if no match</span>
 <span class="sd">        &quot;&quot;&quot;</span>
-        <span class="n">photos</span> <span class="o">=</span> <span class="p">[]</span>
-        <span class="k">for</span> <span class="n">uuid</span> <span class="ow">in</span> <span class="n">uuids</span><span class="p">:</span>
-            <span class="k">try</span><span class="p">:</span>
-                <span class="n">photos</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">PhotoInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="n">uuid</span><span class="p">,</span> <span class="n">info</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">]))</span>
-            <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
-                <span class="c1"># ignore missing/invlaid UUID</span>
-                <span class="k">pass</span>
-        <span class="k">return</span> <span class="n">photos</span></div>
+        <span class="k">return</span> <span class="p">[</span>
+            <span class="n">PhotoInfo</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="bp">self</span><span class="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="n">uuid</span><span class="p">,</span> <span class="n">info</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span><span class="p">[</span><span class="n">uuid</span><span class="p">])</span>
+            <span class="k">for</span> <span class="n">uuid</span> <span class="ow">in</span> <span class="n">uuids</span>
+            <span class="k">if</span> <span class="n">uuid</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos</span>
+        <span class="p">]</span></div>
 
 <div class="viewcode-block" id="PhotosDB.query"><a class="viewcode-back" href="../../../reference.html#osxphotos.PhotosDB.query">[docs]</a>    <span class="k">def</span> <span class="nf">query</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">options</span><span class="p">:</span> <span class="n">QueryOptions</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">List</span><span class="p">[</span><span class="n">PhotoInfo</span><span class="p">]:</span>
         <span class="sd">&quot;&quot;&quot;Run a query against PhotosDB to extract the photos based on user supplied options</span>
@@ -3438,6 +3438,8 @@
 
         <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">edited</span><span class="p">:</span>
             <span class="n">photos</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">photos</span> <span class="k">if</span> <span class="n">p</span><span class="o">.</span><span class="n">hasadjustments</span><span class="p">]</span>
+        <span class="k">elif</span> <span class="n">options</span><span class="o">.</span><span class="n">not_edited</span><span class="p">:</span>
+            <span class="n">photos</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">photos</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">p</span><span class="o">.</span><span class="n">hasadjustments</span><span class="p">]</span>
 
         <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">external_edit</span><span class="p">:</span>
             <span class="n">photos</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">photos</span> <span class="k">if</span> <span class="n">p</span><span class="o">.</span><span class="n">external_edit</span><span class="p">]</span>
@@ -3720,6 +3722,16 @@
             <span class="n">added_after</span> <span class="o">=</span> <span class="n">datetime_naive_to_local</span><span class="p">(</span><span class="n">added_after</span><span class="p">)</span>
             <span class="n">photos</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">photos</span> <span class="k">if</span> <span class="n">p</span><span class="o">.</span><span class="n">date_added</span> <span class="ow">and</span> <span class="n">p</span><span class="o">.</span><span class="n">date_added</span> <span class="o">&gt;</span> <span class="n">added_after</span><span class="p">]</span>
 
+        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">syndicated</span><span class="p">:</span>
+            <span class="n">photos</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">photos</span> <span class="k">if</span> <span class="n">p</span><span class="o">.</span><span class="n">syndicated</span><span class="p">]</span>
+        <span class="k">elif</span> <span class="n">options</span><span class="o">.</span><span class="n">not_syndicated</span><span class="p">:</span>
+            <span class="n">photos</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">photos</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">p</span><span class="o">.</span><span class="n">syndicated</span><span class="p">]</span>
+
+        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">saved_to_library</span><span class="p">:</span>
+            <span class="n">photos</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">photos</span> <span class="k">if</span> <span class="n">p</span><span class="o">.</span><span class="n">syndicated</span> <span class="ow">and</span> <span class="n">p</span><span class="o">.</span><span class="n">saved_to_library</span><span class="p">]</span>
+        <span class="k">elif</span> <span class="n">options</span><span class="o">.</span><span class="n">not_saved_to_library</span><span class="p">:</span>
+            <span class="n">photos</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">photos</span> <span class="k">if</span> <span class="n">p</span><span class="o">.</span><span class="n">syndicated</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">p</span><span class="o">.</span><span class="n">saved_to_library</span><span class="p">]</span>
+
         <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">function</span><span class="p">:</span>
             <span class="k">for</span> <span class="n">function</span> <span class="ow">in</span> <span class="n">options</span><span class="o">.</span><span class="n">function</span><span class="p">:</span>
                 <span class="n">photos</span> <span class="o">=</span> <span class="n">function</span><span class="p">[</span><span class="mi">0</span><span class="p">](</span><span class="n">photos</span><span class="p">)</span>
@@ -3748,10 +3760,11 @@
 
         <span class="k">return</span> <span class="n">photos</span></div>
 
-<div class="viewcode-block" id="PhotosDB.execute"><a class="viewcode-back" href="../../../reference.html#osxphotos.PhotosDB.execute">[docs]</a>    <span class="k">def</span> <span class="nf">execute</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">sql</span><span class="p">):</span>
+<div class="viewcode-block" id="PhotosDB.execute"><a class="viewcode-back" href="../../../reference.html#osxphotos.PhotosDB.execute">[docs]</a>    <span class="k">def</span> <span class="nf">execute</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">sql</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">params</span><span class="p">:</span> <span class="n">Any</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">sqlite3</span><span class="o">.</span><span class="n">Cursor</span><span class="p">:</span>
         <span class="sd">&quot;&quot;&quot;Execute sql statement and return cursor&quot;&quot;&quot;</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_db_connection</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_db_connection</span><span class="p">()</span>
-        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db_connection</span><span class="o">.</span><span class="n">cursor</span><span class="p">()</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">sql</span><span class="p">)</span></div>
+        <span class="n">params</span> <span class="o">=</span> <span class="n">params</span> <span class="ow">or</span> <span class="p">()</span>
+        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db_connection</span><span class="o">.</span><span class="n">cursor</span><span class="p">()</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">sql</span><span class="p">,</span> <span class="n">params</span><span class="p">)</span></div>
 
     <span class="k">def</span> <span class="nf">_duplicate_signature</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">uuid</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;Compute a signature for finding possible duplicates&quot;&quot;&quot;</span>

docs/_modules/osxphotos/phototemplate.html

@@ -4,10 +4,10 @@
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
-    <!-- Generated with Sphinx 5.3.0 and Furo 2022.12.07 -->
-        <title>osxphotos.phototemplate - osxphotos 0.55.4 documentation</title>
+    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
+        <title>osxphotos.phototemplate - osxphotos 0.60.0 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
-    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=91d0f0d1c444bdcb17a68e833c7a53903343c195" />
+    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
     
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.55.4 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.60.0 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,10 +146,10 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.55.4 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.0 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
-  <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
+  <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
   <input type="hidden" name="check_keywords" value="yes">
   <input type="hidden" name="area" value="default">
 </form>
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -211,12 +211,13 @@
 
 <span class="kn">from</span> <span class="nn">textx</span> <span class="kn">import</span> <span class="n">TextXSyntaxError</span><span class="p">,</span> <span class="n">metamodel_from_file</span>
 
+<span class="kn">import</span> <span class="nn">osxphotos.template_counter</span> <span class="k">as</span> <span class="nn">counter</span>
+
 <span class="kn">from</span> <span class="nn">._constants</span> <span class="kn">import</span> <span class="n">_UNKNOWN_PERSON</span><span class="p">,</span> <span class="n">TEXT_DETECTION_CONFIDENCE_THRESHOLD</span>
 <span class="kn">from</span> <span class="nn">._version</span> <span class="kn">import</span> <span class="n">__version__</span>
 <span class="kn">from</span> <span class="nn">.datetime_formatter</span> <span class="kn">import</span> <span class="n">DateTimeFormatter</span>
 <span class="kn">from</span> <span class="nn">.exiftool</span> <span class="kn">import</span> <span class="n">ExifToolCaching</span>
 <span class="kn">from</span> <span class="nn">.path_utils</span> <span class="kn">import</span> <span class="n">sanitize_dirname</span><span class="p">,</span> <span class="n">sanitize_filename</span><span class="p">,</span> <span class="n">sanitize_pathpart</span>
-<span class="kn">from</span> <span class="nn">.text_detection</span> <span class="kn">import</span> <span class="n">detect_text</span>
 <span class="kn">from</span> <span class="nn">.utils</span> <span class="kn">import</span> <span class="n">expand_and_validate_filepath</span><span class="p">,</span> <span class="n">load_function</span><span class="p">,</span> <span class="n">uuid_to_shortuuid</span>
 
 <span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span>
@@ -348,6 +349,24 @@
     <span class="o">+</span> <span class="s2">&quot;May be formatted using a python string format code. &quot;</span>
     <span class="o">+</span> <span class="s2">&quot;For example, to format as a 5-digit integer and pad with zeros, use &#39;</span><span class="si">{id:05d}</span><span class="s2">&#39; which results in &quot;</span>
     <span class="o">+</span> <span class="s2">&quot;00001, 00002, 00003...etc. &quot;</span><span class="p">,</span>
+    <span class="s2">&quot;</span><span class="si">{counter}</span><span class="s2">&quot;</span><span class="p">:</span> <span class="s2">&quot;A sequential counter, starting at 0, that increments each time it is evaluated.&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;To start counting at a value other than 0, append append &#39;(starting_value)&#39; to the field name.&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;For example, to start counting at 1 instead of 0: &#39;{counter(1)}&#39;.&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;May be formatted using a python string format code.&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;For example, to format as a 5-digit integer and pad with zeros, use &#39;{counter:05d(1)}&#39;&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;which results in 00001, 00002, 00003...etc.&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;You may also specify a stop value which causes the counter to reset to the starting value&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;when the stop value is reached and a step size which causes the counter to increment by&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;the specified value instead of 1. Use the format &#39;{counter(start,stop,step)}&#39; where start,&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;stop, and step are integers. For example, to count from 1 to 10 by 2, use &#39;{counter(1,11,2)}&#39;.&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;Note that the counter stops counting when the stop value is reached and does not return the&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;stop value. Start, stop, and step are optional and may be omitted. For example, to count&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;from 0 by 2s, use &#39;{counter(,,2)}&#39;.&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;You may create an arbitrary number of counters by appending a unique name to the field name&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;preceded by a period: &#39;</span><span class="si">{counter.a}</span><span class="s2">&#39;, &#39;</span><span class="si">{counter.b}</span><span class="s2">&#39;, etc. Each counter will have its own state&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;and will start at 0 and increment by 1 unless otherwise specified.&quot;</span>
+    <span class="o">+</span> <span class="s2">&quot; Note: </span><span class="si">{counter}</span><span class="s2"> is not suitable for use with &#39;export&#39; and &#39;--update&#39; &quot;</span>
+    <span class="o">+</span> <span class="s2">&quot;as the counter associated with a photo may change between export sessions. See also </span><span class="si">{id}</span><span class="s2">.&quot;</span><span class="p">,</span>
     <span class="s2">&quot;</span><span class="si">{album_seq}</span><span class="s2">&quot;</span><span class="p">:</span> <span class="s2">&quot;An integer, starting at 0, indicating the photo&#39;s index (sequence) in the containing album. &quot;</span>
     <span class="o">+</span> <span class="s2">&quot;Only valid when used in a &#39;--filename&#39; template and only when &#39;</span><span class="si">{album}</span><span class="s2">&#39; or &#39;</span><span class="si">{folder_album}</span><span class="s2">&#39; is used in the &#39;--directory&#39; template. &quot;</span>
     <span class="o">+</span> <span class="s1">&#39;For example </span><span class="se">\&#39;</span><span class="s1">--directory &quot;</span><span class="si">{folder_album}</span><span class="s1">&quot; --filename &quot;</span><span class="si">{album_seq}</span><span class="s1">_</span><span class="si">{original_name}</span><span class="s1">&quot;</span><span class="se">\&#39;</span><span class="s1">. &#39;</span>
@@ -462,6 +481,8 @@
     <span class="o">+</span> <span class="s2">&quot;e.g. join(): [&#39;a&#39;, &#39;b&#39;, &#39;c&#39;] =&gt; &#39;abc&#39;.&quot;</span><span class="p">,</span>
     <span class="s2">&quot;append(x)&quot;</span><span class="p">:</span> <span class="s2">&quot;Append x to list of values, e.g. append(d): [&#39;a&#39;, &#39;b&#39;, &#39;c&#39;] =&gt; [&#39;a&#39;, &#39;b&#39;, &#39;c&#39;, &#39;d&#39;].&quot;</span><span class="p">,</span>
     <span class="s2">&quot;prepend(x)&quot;</span><span class="p">:</span> <span class="s2">&quot;Prepend x to list of values, e.g. prepend(d): [&#39;a&#39;, &#39;b&#39;, &#39;c&#39;] =&gt; [&#39;d&#39;, &#39;a&#39;, &#39;b&#39;, &#39;c&#39;].&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;appends(x)&quot;</span><span class="p">:</span> <span class="s2">&quot;Append s[tring] Append x to each value of list of values, e.g. appends(d): [&#39;a&#39;, &#39;b&#39;, &#39;c&#39;] =&gt; [&#39;ad&#39;, &#39;bd&#39;, &#39;cd&#39;].&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;prepends(x)&quot;</span><span class="p">:</span> <span class="s2">&quot;Prepend s[tring] x to each value of list of values, e.g. prepends(d): [&#39;a&#39;, &#39;b&#39;, &#39;c&#39;] =&gt; [&#39;da&#39;, &#39;db&#39;, &#39;dc&#39;].&quot;</span><span class="p">,</span>
     <span class="s2">&quot;remove(x)&quot;</span><span class="p">:</span> <span class="s2">&quot;Remove x from list of values, e.g. remove(b): [&#39;a&#39;, &#39;b&#39;, &#39;c&#39;] =&gt; [&#39;a&#39;, &#39;c&#39;].&quot;</span><span class="p">,</span>
     <span class="s2">&quot;slice(start:stop:step)&quot;</span><span class="p">:</span> <span class="s2">&quot;Slice list using same semantics as Python&#39;s list slicing, &quot;</span>
     <span class="o">+</span> <span class="s2">&quot;e.g. slice(1:3): [&#39;a&#39;, &#39;b&#39;, &#39;c&#39;, &#39;d&#39;] =&gt; [&#39;b&#39;, &#39;c&#39;]; slice(1:4:2): [&#39;a&#39;, &#39;b&#39;, &#39;c&#39;, &#39;d&#39;] =&gt; [&#39;b&#39;, &#39;d&#39;]; &quot;</span>
@@ -498,6 +519,9 @@
 <span class="n">INPLACE_DEFAULT</span> <span class="o">=</span> <span class="s2">&quot;,&quot;</span>
 <span class="n">PATH_SEP_DEFAULT</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">sep</span>
 
+<span class="c1"># globals for tracking {seq} substitutions</span>
+<span class="n">_global_seq_count</span> <span class="o">=</span> <span class="mi">0</span>
+
 <span class="n">PUNCTUATION</span> <span class="o">=</span> <span class="p">{</span>
     <span class="s2">&quot;comma&quot;</span><span class="p">:</span> <span class="s2">&quot;,&quot;</span><span class="p">,</span>
     <span class="s2">&quot;semicolon&quot;</span><span class="p">:</span> <span class="s2">&quot;;&quot;</span><span class="p">,</span>
@@ -717,6 +741,8 @@
             <span class="c1"># process field arguments</span>
             <span class="k">if</span> <span class="n">ts</span><span class="o">.</span><span class="n">template</span><span class="o">.</span><span class="n">fieldarg</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
                 <span class="n">field_arg</span> <span class="o">=</span> <span class="n">ts</span><span class="o">.</span><span class="n">template</span><span class="o">.</span><span class="n">fieldarg</span><span class="o">.</span><span class="n">value</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="n">field_arg</span> <span class="o">=</span> <span class="kc">None</span>
 
             <span class="c1"># process delim</span>
             <span class="k">if</span> <span class="n">ts</span><span class="o">.</span><span class="n">template</span><span class="o">.</span><span class="n">delim</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
@@ -1116,6 +1142,8 @@
                 <span class="n">start_id</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">field_arg</span><span class="p">)</span> <span class="k">if</span> <span class="n">field_arg</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="k">else</span> <span class="mi">0</span>
                 <span class="n">value</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> <span class="o">+</span> <span class="n">start_id</span>
                 <span class="n">value</span> <span class="o">=</span> <span class="n">format_str_value</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">subfield</span><span class="p">)</span>
+        <span class="k">elif</span> <span class="n">field</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s2">&quot;counter&quot;</span><span class="p">):</span>
+            <span class="n">value</span> <span class="o">=</span> <span class="n">counter</span><span class="o">.</span><span class="n">get_counter_value</span><span class="p">(</span><span class="n">field</span><span class="p">,</span> <span class="n">subfield</span><span class="p">,</span> <span class="n">field_arg</span><span class="p">)</span>
         <span class="k">else</span><span class="p">:</span>
             <span class="c1"># if here, didn&#39;t get a match</span>
             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Unhandled template value: </span><span class="si">{</span><span class="n">field</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
@@ -1179,15 +1207,17 @@
             <span class="k">raise</span> <span class="ne">SyntaxError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Unknown filter: </span><span class="si">{</span><span class="n">filter_</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
 
         <span class="k">if</span> <span class="n">filter_</span> <span class="ow">in</span> <span class="p">[</span>
-            <span class="s2">&quot;split&quot;</span><span class="p">,</span>
-            <span class="s2">&quot;chop&quot;</span><span class="p">,</span>
-            <span class="s2">&quot;chomp&quot;</span><span class="p">,</span>
             <span class="s2">&quot;append&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;appends&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;chomp&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;chop&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;filter&quot;</span><span class="p">,</span>
             <span class="s2">&quot;prepend&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;prepends&quot;</span><span class="p">,</span>
             <span class="s2">&quot;remove&quot;</span><span class="p">,</span>
             <span class="s2">&quot;slice&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;split&quot;</span><span class="p">,</span>
             <span class="s2">&quot;sslice&quot;</span><span class="p">,</span>
-            <span class="s2">&quot;filter&quot;</span><span class="p">,</span>
         <span class="p">]</span> <span class="ow">and</span> <span class="p">(</span><span class="n">args</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">or</span> <span class="ow">not</span> <span class="nb">len</span><span class="p">(</span><span class="n">args</span><span class="p">)):</span>
             <span class="k">raise</span> <span class="ne">SyntaxError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">filter_</span><span class="si">}</span><span class="s2"> requires arguments&quot;</span><span class="p">)</span>
 
@@ -1204,15 +1234,13 @@
         <span class="k">elif</span> <span class="n">filter_</span> <span class="o">==</span> <span class="s2">&quot;braces&quot;</span><span class="p">:</span>
             <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;{&quot;</span> <span class="o">+</span> <span class="n">v</span> <span class="o">+</span> <span class="s2">&quot;}&quot;</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span>
         <span class="k">elif</span> <span class="n">filter_</span> <span class="o">==</span> <span class="s2">&quot;parens&quot;</span><span class="p">:</span>
-            <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;(&quot;</span> <span class="o">+</span> <span class="n">v</span> <span class="o">+</span> <span class="s2">&quot;)&quot;</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span>
+            <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="sa">f</span><span class="s2">&quot;(</span><span class="si">{</span><span class="n">v</span><span class="si">}</span><span class="s2">)&quot;</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span>
         <span class="k">elif</span> <span class="n">filter_</span> <span class="o">==</span> <span class="s2">&quot;brackets&quot;</span><span class="p">:</span>
-            <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;[&quot;</span> <span class="o">+</span> <span class="n">v</span> <span class="o">+</span> <span class="s2">&quot;]&quot;</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span>
+            <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="sa">f</span><span class="s2">&quot;[</span><span class="si">{</span><span class="n">v</span><span class="si">}</span><span class="s2">]&quot;</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span>
         <span class="k">elif</span> <span class="n">filter_</span> <span class="o">==</span> <span class="s2">&quot;shell_quote&quot;</span><span class="p">:</span>
             <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">shlex</span><span class="o">.</span><span class="n">quote</span><span class="p">(</span><span class="n">v</span><span class="p">)</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span>
         <span class="k">elif</span> <span class="n">filter_</span> <span class="o">==</span> <span class="s2">&quot;split&quot;</span><span class="p">:</span>
-            <span class="c1"># split on delimiter</span>
-            <span class="n">delim</span> <span class="o">=</span> <span class="n">args</span>
-            <span class="k">if</span> <span class="n">delim</span><span class="p">:</span>
+            <span class="k">if</span> <span class="n">delim</span> <span class="o">:=</span> <span class="n">args</span><span class="p">:</span>
                 <span class="n">new_values</span> <span class="o">=</span> <span class="p">[]</span>
                 <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">:</span>
                     <span class="n">new_values</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">v</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">delim</span><span class="p">))</span>
@@ -1223,15 +1251,15 @@
             <span class="c1"># chop off characters from the end</span>
             <span class="k">try</span><span class="p">:</span>
                 <span class="n">chop</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
-            <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
-                <span class="k">raise</span> <span class="ne">SyntaxError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Invalid value for chop: </span><span class="si">{</span><span class="n">args</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+            <span class="k">except</span> <span class="ne">ValueError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+                <span class="k">raise</span> <span class="ne">SyntaxError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Invalid value for chop: </span><span class="si">{</span><span class="n">args</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span> <span class="kn">from</span> <span class="nn">e</span>
             <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">v</span><span class="p">[:</span><span class="o">-</span><span class="n">chop</span><span class="p">]</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span> <span class="k">if</span> <span class="n">chop</span> <span class="k">else</span> <span class="n">values</span>
         <span class="k">elif</span> <span class="n">filter_</span> <span class="o">==</span> <span class="s2">&quot;chomp&quot;</span><span class="p">:</span>
             <span class="c1"># chop off characters from the beginning</span>
             <span class="k">try</span><span class="p">:</span>
                 <span class="n">chomp</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
-            <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
-                <span class="k">raise</span> <span class="ne">SyntaxError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Invalid value for chomp: </span><span class="si">{</span><span class="n">args</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+            <span class="k">except</span> <span class="ne">ValueError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+                <span class="k">raise</span> <span class="ne">SyntaxError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Invalid value for chomp: </span><span class="si">{</span><span class="n">args</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span> <span class="kn">from</span> <span class="nn">e</span>
             <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">v</span><span class="p">[</span><span class="n">chomp</span><span class="p">:]</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span> <span class="k">if</span> <span class="n">chomp</span> <span class="k">else</span> <span class="n">values</span>
         <span class="k">elif</span> <span class="n">filter_</span> <span class="o">==</span> <span class="s2">&quot;autosplit&quot;</span><span class="p">:</span>
             <span class="c1"># try to split keyword strings automatically</span>
@@ -1266,6 +1294,12 @@
         <span class="k">elif</span> <span class="n">filter_</span> <span class="o">==</span> <span class="s2">&quot;prepend&quot;</span><span class="p">:</span>
             <span class="c1"># prepend value to list</span>
             <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">args</span><span class="p">]</span> <span class="o">+</span> <span class="n">values</span>
+        <span class="k">elif</span> <span class="n">filter_</span> <span class="o">==</span> <span class="s2">&quot;appends&quot;</span><span class="p">:</span>
+            <span class="c1"># append value to each item in list</span>
+            <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">v</span><span class="si">}{</span><span class="n">args</span><span class="si">}</span><span class="s2">&quot;</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span>
+        <span class="k">elif</span> <span class="n">filter_</span> <span class="o">==</span> <span class="s2">&quot;prepends&quot;</span><span class="p">:</span>
+            <span class="c1"># prepend value to each item in list</span>
+            <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">args</span><span class="si">}{</span><span class="n">v</span><span class="si">}</span><span class="s2">&quot;</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span>
         <span class="k">elif</span> <span class="n">filter_</span> <span class="o">==</span> <span class="s2">&quot;remove&quot;</span><span class="p">:</span>
             <span class="c1"># remove value from list</span>
             <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">v</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span> <span class="k">if</span> <span class="n">v</span> <span class="o">!=</span> <span class="n">args</span><span class="p">]</span>
@@ -1315,7 +1349,7 @@
                 <span class="p">)</span>
             <span class="k">except</span> <span class="ne">ValueError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
                 <span class="k">raise</span> <span class="ne">SyntaxError</span><span class="p">(</span>
-                    <span class="sa">f</span><span class="s2">&quot;comparison operators may only be used with values that can be converted to numbers: </span><span class="si">{</span><span class="n">vals</span><span class="si">}</span><span class="s2"> </span><span class="si">{</span><span class="n">conditional_value</span><span class="si">}</span><span class="s2">&quot;</span>
+                    <span class="sa">f</span><span class="s2">&quot;comparison operators may only be used with values that can be converted to numbers: </span><span class="si">{</span><span class="n">value</span><span class="si">}</span><span class="s2"> </span><span class="si">{</span><span class="n">conditional_value</span><span class="si">}</span><span class="s2">&quot;</span>
                 <span class="p">)</span> <span class="kn">from</span> <span class="nn">e</span>
 
         <span class="n">predicate_is_true</span> <span class="o">=</span> <span class="kc">False</span>
@@ -1514,7 +1548,7 @@
         <span class="n">subfield</span> <span class="o">=</span> <span class="n">subfield</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
         <span class="k">if</span> <span class="n">subfield</span> <span class="ow">in</span> <span class="n">exifdict</span><span class="p">:</span>
             <span class="n">values</span> <span class="o">=</span> <span class="n">exifdict</span><span class="p">[</span><span class="n">subfield</span><span class="p">]</span>
-            <span class="n">values</span> <span class="o">=</span> <span class="p">[</span><span class="n">values</span><span class="p">]</span> <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">values</span><span class="p">,</span> <span class="nb">list</span><span class="p">)</span> <span class="k">else</span> <span class="n">values</span>
+            <span class="n">values</span> <span class="o">=</span> <span class="n">values</span> <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">values</span><span class="p">,</span> <span class="nb">list</span><span class="p">)</span> <span class="k">else</span> <span class="p">[</span><span class="n">values</span><span class="p">]</span>
             <span class="n">values</span> <span class="o">=</span> <span class="p">[</span><span class="nb">str</span><span class="p">(</span><span class="n">v</span><span class="p">)</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span>
 
             <span class="c1"># sanitize directory names if needed</span>
@@ -1844,7 +1878,7 @@
             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Unhandled template value: </span><span class="si">{</span><span class="n">field</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span> <span class="kn">from</span> <span class="nn">e</span>
 
 
-<span class="k">def</span> <span class="nf">get_place_value</span><span class="p">(</span><span class="n">photo</span><span class="p">:</span> <span class="s2">&quot;PhotoInfo&quot;</span><span class="p">,</span> <span class="n">field</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
+<span class="k">def</span> <span class="nf">get_place_value</span><span class="p">(</span><span class="n">photo</span><span class="p">:</span> <span class="s2">&quot;PhotoInfo&quot;</span><span class="p">,</span> <span class="n">field</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>  <span class="c1"># noqa: F821</span>
     <span class="sd">&quot;&quot;&quot;Get the value of a &#39;place&#39; field by attribute</span>
 
 <span class="sd">    Args:</span>
@@ -1912,7 +1946,9 @@
             
           </div>
           <div class="right-details">
-            
+            <div class="icons">
+              
+            </div>
           </div>
         </div>
         

docs/_modules/osxphotos/placeinfo.html

@@ -1,13 +1,13 @@
 <!doctype html>
-<html class="no-js">
+<html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
-    <meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
-        <title>osxphotos.placeinfo - osxphotos 0.51.7 documentation</title>
+    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
+        <title>osxphotos.placeinfo - osxphotos 0.60.0 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
-    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
+    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
     
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.51.7 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.60.0 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.51.7 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.0 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -179,7 +179,8 @@
           </svg>
           <span>Back to top</span>
         </a>
-        <div class="content-icon-container"><div class="theme-toggle-container theme-toggle-content">
+        <div class="content-icon-container">
+          <div class="theme-toggle-container theme-toggle-content">
             <button class="theme-toggle">
               <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
               <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
@@ -194,13 +195,13 @@
         </div>
         <article role="main">
           <h1>Source code for osxphotos.placeinfo</h1><div class="highlight"><pre>
-<span></span><span class="sd">""" </span>
+<span></span><span class="sd">&quot;&quot;&quot; </span>
 <span class="sd">    PlaceInfo class</span>
 <span class="sd">    Provides reverse geolocation info for photos </span>
 <span class="sd">    </span>
 <span class="sd">    See https://developer.apple.com/documentation/corelocation/clplacemark</span>
 <span class="sd">    for additional documentation on reverse geolocation data</span>
-<span class="sd">"""</span>
+<span class="sd">&quot;&quot;&quot;</span>
 <span class="kn">from</span> <span class="nn">abc</span> <span class="kn">import</span> <span class="n">ABC</span><span class="p">,</span> <span class="n">abstractmethod</span>
 <span class="kn">from</span> <span class="nn">collections</span> <span class="kn">import</span> <span class="n">namedtuple</span>  <span class="c1"># pylint: disable=syntax-error</span>
 
@@ -211,27 +212,27 @@
 <span class="kn">from</span> <span class="nn">.utils</span> <span class="kn">import</span> <span class="n">normalize_unicode</span>
 
 <span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span>
-    <span class="s2">"PLRevGeoLocationInfo"</span><span class="p">,</span>
-    <span class="s2">"PLRevGeoMapItem"</span><span class="p">,</span>
-    <span class="s2">"PLRevGeoMapItemAdditionalPlaceInfo"</span><span class="p">,</span>
-    <span class="s2">"CNPostalAddress"</span><span class="p">,</span>
-    <span class="s2">"PlaceInfo"</span><span class="p">,</span>
-    <span class="s2">"PlaceInfo4"</span><span class="p">,</span>
-    <span class="s2">"PlaceInfo5"</span><span class="p">,</span>
+    <span class="s2">&quot;PLRevGeoLocationInfo&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;PLRevGeoMapItem&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;PLRevGeoMapItemAdditionalPlaceInfo&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;CNPostalAddress&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;PlaceInfo&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;PlaceInfo4&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;PlaceInfo5&quot;</span><span class="p">,</span>
 <span class="p">]</span>
 
 <span class="c1"># postal address information, returned by PlaceInfo.address</span>
 <span class="n">PostalAddress</span> <span class="o">=</span> <span class="n">namedtuple</span><span class="p">(</span>
-    <span class="s2">"PostalAddress"</span><span class="p">,</span>
+    <span class="s2">&quot;PostalAddress&quot;</span><span class="p">,</span>
     <span class="p">[</span>
-        <span class="s2">"street"</span><span class="p">,</span>
-        <span class="s2">"sub_locality"</span><span class="p">,</span>
-        <span class="s2">"city"</span><span class="p">,</span>
-        <span class="s2">"sub_administrative_area"</span><span class="p">,</span>
-        <span class="s2">"state_province"</span><span class="p">,</span>
-        <span class="s2">"postal_code"</span><span class="p">,</span>
-        <span class="s2">"country"</span><span class="p">,</span>
-        <span class="s2">"iso_country_code"</span><span class="p">,</span>
+        <span class="s2">&quot;street&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;sub_locality&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;city&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;sub_administrative_area&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;state_province&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;postal_code&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;country&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;iso_country_code&quot;</span><span class="p">,</span>
     <span class="p">],</span>
 <span class="p">)</span>
 
@@ -240,38 +241,39 @@
 <span class="c1"># PLRevGeoLocationInfo.mapInfo.sortedPlaceInfos</span>
 <span class="c1"># field 18 is combined bodies of water (ocean + inland_water)</span>
 <span class="c1"># and maps to Photos &lt;= 4, RKPlace.type == 44</span>
-<span class="c1"># (Photos &lt;= 4 doesn't have ocean or inland_water types)</span>
-<span class="c1"># The fields named "field0", etc. appear to be unused</span>
+<span class="c1"># (Photos &lt;= 4 doesn&#39;t have ocean or inland_water types)</span>
+<span class="c1"># The fields named &quot;field0&quot;, etc. appear to be unused</span>
 <span class="n">PlaceNames</span> <span class="o">=</span> <span class="n">namedtuple</span><span class="p">(</span>
-    <span class="s2">"PlaceNames"</span><span class="p">,</span>
+    <span class="s2">&quot;PlaceNames&quot;</span><span class="p">,</span>
     <span class="p">[</span>
-        <span class="s2">"field0"</span><span class="p">,</span>
-        <span class="s2">"country"</span><span class="p">,</span>  <span class="c1"># The name of the country associated with the placemark.</span>
-        <span class="s2">"state_province"</span><span class="p">,</span>  <span class="c1"># administrativeArea, The state or province associated with the placemark.</span>
-        <span class="s2">"sub_administrative_area"</span><span class="p">,</span>  <span class="c1"># Additional administrative area information for the placemark.</span>
-        <span class="s2">"city"</span><span class="p">,</span>  <span class="c1"># locality, The city associated with the placemark.</span>
-        <span class="s2">"field5"</span><span class="p">,</span>
-        <span class="s2">"additional_city_info"</span><span class="p">,</span>  <span class="c1"># subLocality, Additional city-level information for the placemark.</span>
-        <span class="s2">"ocean"</span><span class="p">,</span>  <span class="c1"># The name of the ocean associated with the placemark.</span>
-        <span class="s2">"area_of_interest"</span><span class="p">,</span>  <span class="c1"># areasOfInterest, The relevant areas of interest associated with the placemark.</span>
-        <span class="s2">"inland_water"</span><span class="p">,</span>  <span class="c1"># The name of the inland water body associated with the placemark.</span>
-        <span class="s2">"field10"</span><span class="p">,</span>
-        <span class="s2">"region"</span><span class="p">,</span>  <span class="c1"># The geographic region associated with the placemark.</span>
-        <span class="s2">"sub_throughfare"</span><span class="p">,</span>  <span class="c1"># Additional street-level information for the placemark.</span>
-        <span class="s2">"field13"</span><span class="p">,</span>
-        <span class="s2">"postal_code"</span><span class="p">,</span>  <span class="c1"># The postal code associated with the placemark.</span>
-        <span class="s2">"field15"</span><span class="p">,</span>
-        <span class="s2">"field16"</span><span class="p">,</span>
-        <span class="s2">"street_address"</span><span class="p">,</span>  <span class="c1"># throughfare, The street address associated with the placemark.</span>
-        <span class="s2">"body_of_water"</span><span class="p">,</span>  <span class="c1"># RKPlace.type == 44, appears to be any body of water (ocean or inland)</span>
+        <span class="s2">&quot;field0&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;country&quot;</span><span class="p">,</span>  <span class="c1"># The name of the country associated with the placemark.</span>
+        <span class="s2">&quot;state_province&quot;</span><span class="p">,</span>  <span class="c1"># administrativeArea, The state or province associated with the placemark.</span>
+        <span class="s2">&quot;sub_administrative_area&quot;</span><span class="p">,</span>  <span class="c1"># Additional administrative area information for the placemark.</span>
+        <span class="s2">&quot;city&quot;</span><span class="p">,</span>  <span class="c1"># locality, The city associated with the placemark.</span>
+        <span class="s2">&quot;field5&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;additional_city_info&quot;</span><span class="p">,</span>  <span class="c1"># subLocality, Additional city-level information for the placemark.</span>
+        <span class="s2">&quot;ocean&quot;</span><span class="p">,</span>  <span class="c1"># The name of the ocean associated with the placemark.</span>
+        <span class="s2">&quot;area_of_interest&quot;</span><span class="p">,</span>  <span class="c1"># areasOfInterest, The relevant areas of interest associated with the placemark.</span>
+        <span class="s2">&quot;inland_water&quot;</span><span class="p">,</span>  <span class="c1"># The name of the inland water body associated with the placemark.</span>
+        <span class="s2">&quot;field10&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;region&quot;</span><span class="p">,</span>  <span class="c1"># The geographic region associated with the placemark.</span>
+        <span class="s2">&quot;sub_throughfare&quot;</span><span class="p">,</span>  <span class="c1"># Additional street-level information for the placemark.</span>
+        <span class="s2">&quot;field13&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;postal_code&quot;</span><span class="p">,</span>  <span class="c1"># The postal code associated with the placemark.</span>
+        <span class="s2">&quot;field15&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;field16&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;street_address&quot;</span><span class="p">,</span>  <span class="c1"># throughfare, The street address associated with the placemark.</span>
+        <span class="s2">&quot;body_of_water&quot;</span><span class="p">,</span>  <span class="c1"># RKPlace.type == 44, appears to be any body of water (ocean or inland)</span>
     <span class="p">],</span>
 <span class="p">)</span>
 
+
 <span class="c1"># The following classes represent Photo Library Reverse Geolocation Info as stored</span>
 <span class="c1"># in ZADDITIONALASSETATTRIBUTES.ZREVERSELOCATIONDATA</span>
 <span class="c1"># These classes are used by bpylist.archiver to unarchive the serialized objects</span>
 <span class="k">class</span> <span class="nc">PLRevGeoLocationInfo</span><span class="p">:</span>
-    <span class="sd">"""The top level reverse geolocation object"""</span>
+    <span class="sd">&quot;&quot;&quot;The top level reverse geolocation object&quot;&quot;&quot;</span>
 
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span>
         <span class="bp">self</span><span class="p">,</span>
@@ -299,14 +301,14 @@
         <span class="k">return</span> <span class="nb">all</span><span class="p">(</span>
             <span class="nb">getattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span> <span class="o">==</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span>
             <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="p">[</span>
-                <span class="s2">"addressString"</span><span class="p">,</span>
-                <span class="s2">"countryCode"</span><span class="p">,</span>
-                <span class="s2">"isHome"</span><span class="p">,</span>
-                <span class="s2">"compoundNames"</span><span class="p">,</span>
-                <span class="s2">"compoundSecondaryNames"</span><span class="p">,</span>
-                <span class="s2">"version"</span><span class="p">,</span>
-                <span class="s2">"geoServiceProvider"</span><span class="p">,</span>
-                <span class="s2">"postalAddress"</span><span class="p">,</span>
+                <span class="s2">&quot;addressString&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;countryCode&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;isHome&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;compoundNames&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;compoundSecondaryNames&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;version&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;geoServiceProvider&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;postalAddress&quot;</span><span class="p">,</span>
             <span class="p">]</span>
         <span class="p">)</span>
 
@@ -314,31 +316,31 @@
         <span class="k">return</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="fm">__eq__</span><span class="p">(</span><span class="n">other</span><span class="p">)</span>
 
     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="k">return</span> <span class="sa">f</span><span class="s2">"addressString: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">addressString</span><span class="si">}</span><span class="s2">, countryCode: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">countryCode</span><span class="si">}</span><span class="s2">, isHome: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">isHome</span><span class="si">}</span><span class="s2">, mapItem: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">mapItem</span><span class="si">}</span><span class="s2">, postalAddress: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">postalAddress</span><span class="si">}</span><span class="s2">"</span>
+        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;addressString: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">addressString</span><span class="si">}</span><span class="s2">, countryCode: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">countryCode</span><span class="si">}</span><span class="s2">, isHome: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">isHome</span><span class="si">}</span><span class="s2">, mapItem: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">mapItem</span><span class="si">}</span><span class="s2">, postalAddress: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">postalAddress</span><span class="si">}</span><span class="s2">&quot;</span>
 
     <span class="nd">@staticmethod</span>
     <span class="k">def</span> <span class="nf">encode_archive</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">archive</span><span class="p">):</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"addressString"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">addressString</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"countryCode"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">countryCode</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"mapItem"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">mapItem</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"isHome"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">isHome</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"compoundNames"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">compoundNames</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"compoundSecondaryNames"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">compoundSecondaryNames</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"version"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">version</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"geoServiceProvider"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">geoServiceProvider</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"postalAddress"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">postalAddress</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;addressString&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">addressString</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;countryCode&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">countryCode</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;mapItem&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">mapItem</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;isHome&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">isHome</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;compoundNames&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">compoundNames</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;compoundSecondaryNames&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">compoundSecondaryNames</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;version&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">version</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;geoServiceProvider&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">geoServiceProvider</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;postalAddress&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">postalAddress</span><span class="p">)</span>
 
     <span class="nd">@staticmethod</span>
     <span class="k">def</span> <span class="nf">decode_archive</span><span class="p">(</span><span class="n">archive</span><span class="p">):</span>
-        <span class="n">addressString</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"addressString"</span><span class="p">)</span>
-        <span class="n">countryCode</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"countryCode"</span><span class="p">)</span>
-        <span class="n">mapItem</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"mapItem"</span><span class="p">)</span>
-        <span class="n">isHome</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"isHome"</span><span class="p">)</span>
-        <span class="n">compoundNames</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"compoundNames"</span><span class="p">)</span>
-        <span class="n">compoundSecondaryNames</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"compoundSecondaryNames"</span><span class="p">)</span>
-        <span class="n">version</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"version"</span><span class="p">)</span>
-        <span class="n">geoServiceProvider</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"geoServiceProvider"</span><span class="p">)</span>
-        <span class="n">postalAddress</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"postalAddress"</span><span class="p">)</span>
+        <span class="n">addressString</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;addressString&quot;</span><span class="p">)</span>
+        <span class="n">countryCode</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;countryCode&quot;</span><span class="p">)</span>
+        <span class="n">mapItem</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;mapItem&quot;</span><span class="p">)</span>
+        <span class="n">isHome</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;isHome&quot;</span><span class="p">)</span>
+        <span class="n">compoundNames</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;compoundNames&quot;</span><span class="p">)</span>
+        <span class="n">compoundSecondaryNames</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;compoundSecondaryNames&quot;</span><span class="p">)</span>
+        <span class="n">version</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;version&quot;</span><span class="p">)</span>
+        <span class="n">geoServiceProvider</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;geoServiceProvider&quot;</span><span class="p">)</span>
+        <span class="n">postalAddress</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;postalAddress&quot;</span><span class="p">)</span>
         <span class="k">return</span> <span class="n">PLRevGeoLocationInfo</span><span class="p">(</span>
             <span class="n">addressString</span><span class="p">,</span>
             <span class="n">countryCode</span><span class="p">,</span>
@@ -353,7 +355,7 @@
 
 
 <span class="k">class</span> <span class="nc">PLRevGeoMapItem</span><span class="p">:</span>
-    <span class="sd">"""Stores the list of place names, organized by area"""</span>
+    <span class="sd">&quot;&quot;&quot;Stores the list of place names, organized by area&quot;&quot;&quot;</span>
 
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">sortedPlaceInfos</span><span class="p">,</span> <span class="n">finalPlaceInfos</span><span class="p">):</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">sortedPlaceInfos</span> <span class="o">=</span> <span class="n">sortedPlaceInfos</span>
@@ -362,7 +364,7 @@
     <span class="k">def</span> <span class="fm">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
         <span class="k">return</span> <span class="nb">all</span><span class="p">(</span>
             <span class="nb">getattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span> <span class="o">==</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span>
-            <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">"sortedPlaceInfos"</span><span class="p">,</span> <span class="s2">"finalPlaceInfos"</span><span class="p">]</span>
+            <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">&quot;sortedPlaceInfos&quot;</span><span class="p">,</span> <span class="s2">&quot;finalPlaceInfos&quot;</span><span class="p">]</span>
         <span class="p">)</span>
 
     <span class="k">def</span> <span class="fm">__ne__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
@@ -372,23 +374,23 @@
         <span class="n">sortedPlaceInfos</span> <span class="o">=</span> <span class="p">[</span><span class="nb">str</span><span class="p">(</span><span class="n">place</span><span class="p">)</span> <span class="k">for</span> <span class="n">place</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">sortedPlaceInfos</span><span class="p">]</span>
         <span class="n">finalPlaceInfos</span> <span class="o">=</span> <span class="p">[</span><span class="nb">str</span><span class="p">(</span><span class="n">place</span><span class="p">)</span> <span class="k">for</span> <span class="n">place</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">finalPlaceInfos</span><span class="p">]</span>
         <span class="k">return</span> <span class="p">(</span>
-            <span class="sa">f</span><span class="s2">"finalPlaceInfos: </span><span class="si">{</span><span class="n">finalPlaceInfos</span><span class="si">}</span><span class="s2">, sortedPlaceInfos: </span><span class="si">{</span><span class="n">sortedPlaceInfos</span><span class="si">}</span><span class="s2">"</span>
+            <span class="sa">f</span><span class="s2">&quot;finalPlaceInfos: </span><span class="si">{</span><span class="n">finalPlaceInfos</span><span class="si">}</span><span class="s2">, sortedPlaceInfos: </span><span class="si">{</span><span class="n">sortedPlaceInfos</span><span class="si">}</span><span class="s2">&quot;</span>
         <span class="p">)</span>
 
     <span class="nd">@staticmethod</span>
     <span class="k">def</span> <span class="nf">encode_archive</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">archive</span><span class="p">):</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"sortedPlaceInfos"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">sortedPlaceInfos</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"finalPlaceInfos"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">finalPlaceInfos</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;sortedPlaceInfos&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">sortedPlaceInfos</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;finalPlaceInfos&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">finalPlaceInfos</span><span class="p">)</span>
 
     <span class="nd">@staticmethod</span>
     <span class="k">def</span> <span class="nf">decode_archive</span><span class="p">(</span><span class="n">archive</span><span class="p">):</span>
-        <span class="n">sortedPlaceInfos</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"sortedPlaceInfos"</span><span class="p">)</span>
-        <span class="n">finalPlaceInfos</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"finalPlaceInfos"</span><span class="p">)</span>
+        <span class="n">sortedPlaceInfos</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;sortedPlaceInfos&quot;</span><span class="p">)</span>
+        <span class="n">finalPlaceInfos</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;finalPlaceInfos&quot;</span><span class="p">)</span>
         <span class="k">return</span> <span class="n">PLRevGeoMapItem</span><span class="p">(</span><span class="n">sortedPlaceInfos</span><span class="p">,</span> <span class="n">finalPlaceInfos</span><span class="p">)</span>
 
 
 <span class="k">class</span> <span class="nc">PLRevGeoMapItemAdditionalPlaceInfo</span><span class="p">:</span>
-    <span class="sd">"""Additional info about individual places"""</span>
+    <span class="sd">&quot;&quot;&quot;Additional info about individual places&quot;&quot;&quot;</span>
 
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">area</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">placeType</span><span class="p">,</span> <span class="n">dominantOrderType</span><span class="p">):</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">area</span> <span class="o">=</span> <span class="n">area</span>
@@ -399,35 +401,35 @@
     <span class="k">def</span> <span class="fm">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
         <span class="k">return</span> <span class="nb">all</span><span class="p">(</span>
             <span class="nb">getattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span> <span class="o">==</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span>
-            <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">"area"</span><span class="p">,</span> <span class="s2">"name"</span><span class="p">,</span> <span class="s2">"placeType"</span><span class="p">,</span> <span class="s2">"dominantOrderType"</span><span class="p">]</span>
+            <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">&quot;area&quot;</span><span class="p">,</span> <span class="s2">&quot;name&quot;</span><span class="p">,</span> <span class="s2">&quot;placeType&quot;</span><span class="p">,</span> <span class="s2">&quot;dominantOrderType&quot;</span><span class="p">]</span>
         <span class="p">)</span>
 
     <span class="k">def</span> <span class="fm">__ne__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
         <span class="k">return</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="fm">__eq__</span><span class="p">(</span><span class="n">other</span><span class="p">)</span>
 
     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="k">return</span> <span class="sa">f</span><span class="s2">"area: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">area</span><span class="si">}</span><span class="s2">, name: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s2">, placeType: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">placeType</span><span class="si">}</span><span class="s2">"</span>
+        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;area: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">area</span><span class="si">}</span><span class="s2">, name: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s2">, placeType: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">placeType</span><span class="si">}</span><span class="s2">&quot;</span>
 
     <span class="nd">@staticmethod</span>
     <span class="k">def</span> <span class="nf">encode_archive</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">archive</span><span class="p">):</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"area"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">area</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"name"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"placeType"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">placeType</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"dominantOrderType"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">dominantOrderType</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;area&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">area</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;name&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;placeType&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">placeType</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;dominantOrderType&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">dominantOrderType</span><span class="p">)</span>
 
     <span class="nd">@staticmethod</span>
     <span class="k">def</span> <span class="nf">decode_archive</span><span class="p">(</span><span class="n">archive</span><span class="p">):</span>
-        <span class="n">area</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"area"</span><span class="p">)</span>
-        <span class="n">name</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"name"</span><span class="p">)</span>
-        <span class="n">placeType</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"placeType"</span><span class="p">)</span>
-        <span class="n">dominantOrderType</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"dominantOrderType"</span><span class="p">)</span>
+        <span class="n">area</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;area&quot;</span><span class="p">)</span>
+        <span class="n">name</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;name&quot;</span><span class="p">)</span>
+        <span class="n">placeType</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;placeType&quot;</span><span class="p">)</span>
+        <span class="n">dominantOrderType</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;dominantOrderType&quot;</span><span class="p">)</span>
         <span class="k">return</span> <span class="n">PLRevGeoMapItemAdditionalPlaceInfo</span><span class="p">(</span>
             <span class="n">area</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">placeType</span><span class="p">,</span> <span class="n">dominantOrderType</span>
         <span class="p">)</span>
 
 
 <span class="k">class</span> <span class="nc">CNPostalAddress</span><span class="p">:</span>
-    <span class="sd">"""postal address for the reverse geolocation info"""</span>
+    <span class="sd">&quot;&quot;&quot;postal address for the reverse geolocation info&quot;&quot;&quot;</span>
 
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span>
         <span class="bp">self</span><span class="p">,</span>
@@ -453,14 +455,14 @@
         <span class="k">return</span> <span class="nb">all</span><span class="p">(</span>
             <span class="nb">getattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span> <span class="o">==</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">field</span><span class="p">)</span>
             <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="p">[</span>
-                <span class="s2">"_ISOCountryCode"</span><span class="p">,</span>
-                <span class="s2">"_city"</span><span class="p">,</span>
-                <span class="s2">"_country"</span><span class="p">,</span>
-                <span class="s2">"_postalCode"</span><span class="p">,</span>
-                <span class="s2">"_state"</span><span class="p">,</span>
-                <span class="s2">"_street"</span><span class="p">,</span>
-                <span class="s2">"_subAdministrativeArea"</span><span class="p">,</span>
-                <span class="s2">"_subLocality"</span><span class="p">,</span>
+                <span class="s2">&quot;_ISOCountryCode&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;_city&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;_country&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;_postalCode&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;_state&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;_street&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;_subAdministrativeArea&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;_subLocality&quot;</span><span class="p">,</span>
             <span class="p">]</span>
         <span class="p">)</span>
 
@@ -468,7 +470,7 @@
         <span class="k">return</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="fm">__eq__</span><span class="p">(</span><span class="n">other</span><span class="p">)</span>
 
     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="k">return</span> <span class="s2">", "</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
+        <span class="k">return</span> <span class="s2">&quot;, &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
             <span class="nb">map</span><span class="p">(</span>
                 <span class="nb">str</span><span class="p">,</span>
                 <span class="p">[</span>
@@ -486,25 +488,25 @@
 
     <span class="nd">@staticmethod</span>
     <span class="k">def</span> <span class="nf">encode_archive</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">archive</span><span class="p">):</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"_ISOCountryCode"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_ISOCountryCode</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"_country"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_country</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"_city"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_city</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"_postalCode"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_postalCode</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"_state"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_state</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"_street"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_street</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"_subAdministrativeArea"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_subAdministrativeArea</span><span class="p">)</span>
-        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">"_subLocality"</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_subLocality</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;_ISOCountryCode&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_ISOCountryCode</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;_country&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_country</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;_city&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_city</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;_postalCode&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_postalCode</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;_state&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_state</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;_street&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_street</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;_subAdministrativeArea&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_subAdministrativeArea</span><span class="p">)</span>
+        <span class="n">archive</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;_subLocality&quot;</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">_subLocality</span><span class="p">)</span>
 
     <span class="nd">@staticmethod</span>
     <span class="k">def</span> <span class="nf">decode_archive</span><span class="p">(</span><span class="n">archive</span><span class="p">):</span>
-        <span class="n">_ISOCountryCode</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"_ISOCountryCode"</span><span class="p">)</span>
-        <span class="n">_country</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"_country"</span><span class="p">)</span>
-        <span class="n">_city</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"_city"</span><span class="p">)</span>
-        <span class="n">_postalCode</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"_postalCode"</span><span class="p">)</span>
-        <span class="n">_state</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"_state"</span><span class="p">)</span>
-        <span class="n">_street</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"_street"</span><span class="p">)</span>
-        <span class="n">_subAdministrativeArea</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"_subAdministrativeArea"</span><span class="p">)</span>
-        <span class="n">_subLocality</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">"_subLocality"</span><span class="p">)</span>
+        <span class="n">_ISOCountryCode</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;_ISOCountryCode&quot;</span><span class="p">)</span>
+        <span class="n">_country</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;_country&quot;</span><span class="p">)</span>
+        <span class="n">_city</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;_city&quot;</span><span class="p">)</span>
+        <span class="n">_postalCode</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;_postalCode&quot;</span><span class="p">)</span>
+        <span class="n">_state</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;_state&quot;</span><span class="p">)</span>
+        <span class="n">_street</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;_street&quot;</span><span class="p">)</span>
+        <span class="n">_subAdministrativeArea</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;_subAdministrativeArea&quot;</span><span class="p">)</span>
+        <span class="n">_subLocality</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;_subLocality&quot;</span><span class="p">)</span>
 
         <span class="k">return</span> <span class="n">CNPostalAddress</span><span class="p">(</span>
             <span class="n">_ISOCountryCode</span><span class="p">,</span>
@@ -519,12 +521,12 @@
 
 
 <span class="c1"># register the classes with bpylist.archiver</span>
-<span class="n">archiver</span><span class="o">.</span><span class="n">update_class_map</span><span class="p">({</span><span class="s2">"CNPostalAddress"</span><span class="p">:</span> <span class="n">CNPostalAddress</span><span class="p">})</span>
+<span class="n">archiver</span><span class="o">.</span><span class="n">update_class_map</span><span class="p">({</span><span class="s2">&quot;CNPostalAddress&quot;</span><span class="p">:</span> <span class="n">CNPostalAddress</span><span class="p">})</span>
 <span class="n">archiver</span><span class="o">.</span><span class="n">update_class_map</span><span class="p">(</span>
-    <span class="p">{</span><span class="s2">"PLRevGeoMapItemAdditionalPlaceInfo"</span><span class="p">:</span> <span class="n">PLRevGeoMapItemAdditionalPlaceInfo</span><span class="p">}</span>
+    <span class="p">{</span><span class="s2">&quot;PLRevGeoMapItemAdditionalPlaceInfo&quot;</span><span class="p">:</span> <span class="n">PLRevGeoMapItemAdditionalPlaceInfo</span><span class="p">}</span>
 <span class="p">)</span>
-<span class="n">archiver</span><span class="o">.</span><span class="n">update_class_map</span><span class="p">({</span><span class="s2">"PLRevGeoMapItem"</span><span class="p">:</span> <span class="n">PLRevGeoMapItem</span><span class="p">})</span>
-<span class="n">archiver</span><span class="o">.</span><span class="n">update_class_map</span><span class="p">({</span><span class="s2">"PLRevGeoLocationInfo"</span><span class="p">:</span> <span class="n">PLRevGeoLocationInfo</span><span class="p">})</span>
+<span class="n">archiver</span><span class="o">.</span><span class="n">update_class_map</span><span class="p">({</span><span class="s2">&quot;PLRevGeoMapItem&quot;</span><span class="p">:</span> <span class="n">PLRevGeoMapItem</span><span class="p">})</span>
+<span class="n">archiver</span><span class="o">.</span><span class="n">update_class_map</span><span class="p">({</span><span class="s2">&quot;PLRevGeoLocationInfo&quot;</span><span class="p">:</span> <span class="n">PLRevGeoLocationInfo</span><span class="p">})</span>
 
 
 <div class="viewcode-block" id="PlaceInfo"><a class="viewcode-back" href="../../reference.html#osxphotos.PlaceInfo">[docs]</a><span class="k">class</span> <span class="nc">PlaceInfo</span><span class="p">(</span><span class="n">ABC</span><span class="p">):</span>
@@ -560,18 +562,18 @@
 
 
 <span class="k">class</span> <span class="nc">PlaceInfo4</span><span class="p">(</span><span class="n">PlaceInfo</span><span class="p">):</span>
-    <span class="sd">"""Reverse geolocation place info for a photo (Photos &lt;= 4)"""</span>
+    <span class="sd">&quot;&quot;&quot;Reverse geolocation place info for a photo (Photos &lt;= 4)&quot;&quot;&quot;</span>
 
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">place_names</span><span class="p">,</span> <span class="n">country_code</span><span class="p">):</span>
-        <span class="sd">"""place_names: list of place name tuples in ascending order by area</span>
+        <span class="sd">&quot;&quot;&quot;place_names: list of place name tuples in ascending order by area</span>
 <span class="sd">        tuple fields are: modelID, place name, place type, area, e.g.</span>
-<span class="sd">        [(5, "St James's Park", 45, 0),</span>
-<span class="sd">        (4, 'Westminster', 16, 22097376),</span>
-<span class="sd">        (3, 'London', 4, 1596146816),</span>
-<span class="sd">        (2, 'England', 2, 180406091776),</span>
-<span class="sd">        (1, 'United Kingdom', 1, 414681432064)]</span>
+<span class="sd">        [(5, &quot;St James&#39;s Park&quot;, 45, 0),</span>
+<span class="sd">        (4, &#39;Westminster&#39;, 16, 22097376),</span>
+<span class="sd">        (3, &#39;London&#39;, 4, 1596146816),</span>
+<span class="sd">        (2, &#39;England&#39;, 2, 180406091776),</span>
+<span class="sd">        (1, &#39;United Kingdom&#39;, 1, 414681432064)]</span>
 <span class="sd">        country_code: two letter country code for the country</span>
-<span class="sd">        """</span>
+<span class="sd">        &quot;&quot;&quot;</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_place_names</span> <span class="o">=</span> <span class="n">place_names</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_country_code</span> <span class="o">=</span> <span class="n">country_code</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_process_place_info</span><span class="p">()</span>
@@ -610,14 +612,14 @@
             <span class="p">)</span>
 
     <span class="k">def</span> <span class="nf">_process_place_info</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Process place_names to set self._name and self._names"""</span>
+        <span class="sd">&quot;&quot;&quot;Process place_names to set self._name and self._names&quot;&quot;&quot;</span>
         <span class="n">places</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_place_names</span>
 
         <span class="c1"># build a dictionary where key is placetype</span>
         <span class="n">places_dict</span> <span class="o">=</span> <span class="p">{}</span>
         <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">places</span><span class="p">:</span>
             <span class="c1"># places in format:</span>
-            <span class="c1"># [(5, "St James's Park", 45, 0), ]</span>
+            <span class="c1"># [(5, &quot;St James&#39;s Park&quot;, 45, 0), ]</span>
             <span class="c1">#   0: modelID</span>
             <span class="c1">#   1: name</span>
             <span class="c1">#   2: type</span>
@@ -659,7 +661,7 @@
 
         <span class="c1"># build the name as it appears in Photos</span>
         <span class="c1"># the length of the name is at most 3 fields and appears to be based on available</span>
-        <span class="c1"># reverse geolocation data in the following order (left to right, joined by ',')</span>
+        <span class="c1"># reverse geolocation data in the following order (left to right, joined by &#39;,&#39;)</span>
         <span class="c1"># always has country if available then either area of interest and city OR</span>
         <span class="c1"># city and state</span>
         <span class="c1"># e.g. 4, 2, 1 OR 8, 4, 1</span>
@@ -683,61 +685,61 @@
         <span class="k">if</span> <span class="n">place_names</span><span class="p">[</span><span class="mi">1</span><span class="p">]:</span>
             <span class="n">name_list</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">place_names</span><span class="p">[</span><span class="mi">1</span><span class="p">][</span><span class="mi">0</span><span class="p">])</span>
 
-        <span class="n">name</span> <span class="o">=</span> <span class="s2">", "</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">name_list</span><span class="p">)</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="n">name</span> <span class="k">if</span> <span class="n">name</span> <span class="o">!=</span> <span class="s2">""</span> <span class="k">else</span> <span class="kc">None</span>
+        <span class="n">name</span> <span class="o">=</span> <span class="s2">&quot;, &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">name_list</span><span class="p">)</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="n">name</span> <span class="k">if</span> <span class="n">name</span> <span class="o">!=</span> <span class="s2">&quot;&quot;</span> <span class="k">else</span> <span class="kc">None</span>
 
     <span class="k">def</span> <span class="fm">__ne__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
         <span class="k">return</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="fm">__eq__</span><span class="p">(</span><span class="n">other</span><span class="p">)</span>
 
     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="n">info</span> <span class="o">=</span> <span class="p">{</span>
-            <span class="s2">"name"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
-            <span class="s2">"names"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">names</span><span class="p">,</span>
-            <span class="s2">"country_code"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">country_code</span><span class="p">,</span>
+            <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
+            <span class="s2">&quot;names&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">names</span><span class="p">,</span>
+            <span class="s2">&quot;country_code&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">country_code</span><span class="p">,</span>
         <span class="p">}</span>
-        <span class="k">return</span> <span class="s2">"PlaceInfo("</span> <span class="o">+</span> <span class="s2">", "</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">k</span><span class="si">}</span><span class="s2">='</span><span class="si">{</span><span class="n">v</span><span class="si">}</span><span class="s2">'"</span> <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">info</span><span class="o">.</span><span class="n">items</span><span class="p">()])</span> <span class="o">+</span> <span class="s2">")"</span>
+        <span class="k">return</span> <span class="s2">&quot;PlaceInfo(&quot;</span> <span class="o">+</span> <span class="s2">&quot;, &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">k</span><span class="si">}</span><span class="s2">=&#39;</span><span class="si">{</span><span class="n">v</span><span class="si">}</span><span class="s2">&#39;&quot;</span> <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">info</span><span class="o">.</span><span class="n">items</span><span class="p">()])</span> <span class="o">+</span> <span class="s2">&quot;)&quot;</span>
 
     <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="k">return</span> <span class="p">{</span>
-            <span class="s2">"name"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
-            <span class="s2">"names"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">names</span><span class="o">.</span><span class="n">_asdict</span><span class="p">(),</span>
-            <span class="s2">"country_code"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">country_code</span><span class="p">,</span>
+            <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
+            <span class="s2">&quot;names&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">names</span><span class="o">.</span><span class="n">_asdict</span><span class="p">(),</span>
+            <span class="s2">&quot;country_code&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">country_code</span><span class="p">,</span>
         <span class="p">}</span>
 
 
 <span class="k">class</span> <span class="nc">PlaceInfo5</span><span class="p">(</span><span class="n">PlaceInfo</span><span class="p">):</span>
-    <span class="sd">"""Reverse geolocation place info for a photo (Photos &gt;= 5)"""</span>
+    <span class="sd">&quot;&quot;&quot;Reverse geolocation place info for a photo (Photos &gt;= 5)&quot;&quot;&quot;</span>
 
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">revgeoloc_bplist</span><span class="p">):</span>
-        <span class="sd">"""revgeoloc_bplist: a binary plist blob containing</span>
-<span class="sd">        a serialized PLRevGeoLocationInfo object"""</span>
+        <span class="sd">&quot;&quot;&quot;revgeoloc_bplist: a binary plist blob containing</span>
+<span class="sd">        a serialized PLRevGeoLocationInfo object&quot;&quot;&quot;</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_bplist</span> <span class="o">=</span> <span class="n">revgeoloc_bplist</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_plrevgeoloc</span> <span class="o">=</span> <span class="n">archiver</span><span class="o">.</span><span class="n">unarchive</span><span class="p">(</span><span class="n">revgeoloc_bplist</span><span class="p">)</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">_process_place_info</span><span class="p">()</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">address_str</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""returns the postal address as a string"""</span>
+        <span class="sd">&quot;&quot;&quot;returns the postal address as a string&quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_plrevgeoloc</span><span class="o">.</span><span class="n">addressString</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">country_code</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""returns the country code"""</span>
+        <span class="sd">&quot;&quot;&quot;returns the country code&quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_plrevgeoloc</span><span class="o">.</span><span class="n">countryCode</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">ishome</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""returns True if place is user's home address"""</span>
+        <span class="sd">&quot;&quot;&quot;returns True if place is user&#39;s home address&quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_plrevgeoloc</span><span class="o">.</span><span class="n">isHome</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""returns local place name"""</span>
+        <span class="sd">&quot;&quot;&quot;returns local place name&quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_name</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">names</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""returns PlaceNames tuple with detailed reverse geolocation place names"""</span>
+        <span class="sd">&quot;&quot;&quot;returns PlaceNames tuple with detailed reverse geolocation place names&quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_names</span>
 
     <span class="nd">@property</span>
@@ -762,7 +764,7 @@
         <span class="k">return</span> <span class="n">postal_address</span>
 
     <span class="k">def</span> <span class="nf">_process_place_info</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">"""Process sortedPlaceInfos to set self._name and self._names"""</span>
+        <span class="sd">&quot;&quot;&quot;Process sortedPlaceInfos to set self._name and self._names&quot;&quot;&quot;</span>
         <span class="n">places</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_plrevgeoloc</span><span class="o">.</span><span class="n">mapItem</span><span class="o">.</span><span class="n">sortedPlaceInfos</span>
 
         <span class="c1"># build a dictionary where key is placetype</span>
@@ -795,20 +797,20 @@
 
         <span class="c1"># build the name as it appears in Photos</span>
         <span class="c1"># the length of the name is variable and appears to be based on available</span>
-        <span class="c1"># reverse geolocation data in the following order (left to right, joined by ',')</span>
+        <span class="c1"># reverse geolocation data in the following order (left to right, joined by &#39;,&#39;)</span>
         <span class="c1"># 8: area_of_interest</span>
-        <span class="c1"># 11: region (I've only seen this applied to islands)</span>
+        <span class="c1"># 11: region (I&#39;ve only seen this applied to islands)</span>
         <span class="c1"># 4: locality / city</span>
         <span class="c1"># 2: administrative area (state/province)</span>
         <span class="c1"># 1: country</span>
         <span class="c1"># 9: inland_water</span>
         <span class="c1"># 7: ocean</span>
-        <span class="n">name</span> <span class="o">=</span> <span class="s2">", "</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
+        <span class="n">name</span> <span class="o">=</span> <span class="s2">&quot;, &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
             <span class="p">[</span>
                 <span class="n">p</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
                 <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="p">[</span>
                     <span class="n">place_names</span><span class="p">[</span><span class="mi">8</span><span class="p">],</span>  <span class="c1"># area of interest</span>
-                    <span class="n">place_names</span><span class="p">[</span><span class="mi">11</span><span class="p">],</span>  <span class="c1"># region (I've only seen this applied to islands)</span>
+                    <span class="n">place_names</span><span class="p">[</span><span class="mi">11</span><span class="p">],</span>  <span class="c1"># region (I&#39;ve only seen this applied to islands)</span>
                     <span class="n">place_names</span><span class="p">[</span><span class="mi">4</span><span class="p">],</span>  <span class="c1"># locality / city</span>
                     <span class="n">place_names</span><span class="p">[</span><span class="mi">2</span><span class="p">],</span>  <span class="c1"># administrative area (state/province)</span>
                     <span class="n">place_names</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span>  <span class="c1"># country</span>
@@ -818,7 +820,7 @@
                 <span class="k">if</span> <span class="n">p</span> <span class="ow">and</span> <span class="n">p</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
             <span class="p">]</span>
         <span class="p">)</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="n">name</span> <span class="k">if</span> <span class="n">name</span> <span class="o">!=</span> <span class="s2">""</span> <span class="k">else</span> <span class="kc">None</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="n">name</span> <span class="k">if</span> <span class="n">name</span> <span class="o">!=</span> <span class="s2">&quot;&quot;</span> <span class="k">else</span> <span class="kc">None</span>
 
     <span class="k">def</span> <span class="fm">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
         <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)):</span>
@@ -831,23 +833,23 @@
 
     <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="n">info</span> <span class="o">=</span> <span class="p">{</span>
-            <span class="s2">"name"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
-            <span class="s2">"names"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">names</span><span class="p">,</span>
-            <span class="s2">"country_code"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">country_code</span><span class="p">,</span>
-            <span class="s2">"ishome"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">ishome</span><span class="p">,</span>
-            <span class="s2">"address_str"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">address_str</span><span class="p">,</span>
-            <span class="s2">"address"</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">address</span><span class="p">),</span>
+            <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
+            <span class="s2">&quot;names&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">names</span><span class="p">,</span>
+            <span class="s2">&quot;country_code&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">country_code</span><span class="p">,</span>
+            <span class="s2">&quot;ishome&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">ishome</span><span class="p">,</span>
+            <span class="s2">&quot;address_str&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">address_str</span><span class="p">,</span>
+            <span class="s2">&quot;address&quot;</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">address</span><span class="p">),</span>
         <span class="p">}</span>
-        <span class="k">return</span> <span class="s2">"PlaceInfo("</span> <span class="o">+</span> <span class="s2">", "</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">k</span><span class="si">}</span><span class="s2">='</span><span class="si">{</span><span class="n">v</span><span class="si">}</span><span class="s2">'"</span> <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">info</span><span class="o">.</span><span class="n">items</span><span class="p">()])</span> <span class="o">+</span> <span class="s2">")"</span>
+        <span class="k">return</span> <span class="s2">&quot;PlaceInfo(&quot;</span> <span class="o">+</span> <span class="s2">&quot;, &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">k</span><span class="si">}</span><span class="s2">=&#39;</span><span class="si">{</span><span class="n">v</span><span class="si">}</span><span class="s2">&#39;&quot;</span> <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">info</span><span class="o">.</span><span class="n">items</span><span class="p">()])</span> <span class="o">+</span> <span class="s2">&quot;)&quot;</span>
 
     <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="k">return</span> <span class="p">{</span>
-            <span class="s2">"name"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
-            <span class="s2">"names"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">names</span><span class="o">.</span><span class="n">_asdict</span><span class="p">(),</span>
-            <span class="s2">"country_code"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">country_code</span><span class="p">,</span>
-            <span class="s2">"ishome"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">ishome</span><span class="p">,</span>
-            <span class="s2">"address_str"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">address_str</span><span class="p">,</span>
-            <span class="s2">"address"</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">address</span><span class="o">.</span><span class="n">_asdict</span><span class="p">()</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">address</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="k">else</span> <span class="kc">None</span><span class="p">,</span>
+            <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
+            <span class="s2">&quot;names&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">names</span><span class="o">.</span><span class="n">_asdict</span><span class="p">(),</span>
+            <span class="s2">&quot;country_code&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">country_code</span><span class="p">,</span>
+            <span class="s2">&quot;ishome&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">ishome</span><span class="p">,</span>
+            <span class="s2">&quot;address_str&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">address_str</span><span class="p">,</span>
+            <span class="s2">&quot;address&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">address</span><span class="o">.</span><span class="n">_asdict</span><span class="p">()</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">address</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="k">else</span> <span class="kc">None</span><span class="p">,</span>
         <span class="p">}</span>
 </pre></div>
         </article>
@@ -886,7 +888,9 @@
 </div><script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
     <script src="../../_static/jquery.js"></script>
     <script src="../../_static/underscore.js"></script>
+    <script src="../../_static/_sphinx_javascript_frameworks_compat.js"></script>
     <script src="../../_static/doctools.js"></script>
+    <script src="../../_static/sphinx_highlight.js"></script>
     <script src="../../_static/scripts/furo.js"></script>
     <script src="../../_static/clipboard.min.js"></script>
     <script src="../../_static/copybutton.js"></script>

docs/_modules/osxphotos/queryoptions.html

@@ -1,13 +1,13 @@
 <!doctype html>
-<html class="no-js">
+<html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
-    <meta name="generator" content="sphinx-4.4.0, furo 2022.04.07"/>
-        <title>osxphotos.queryoptions - osxphotos 0.50.13 documentation</title>
+    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
+        <title>osxphotos.queryoptions - osxphotos 0.60.3 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
-    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=68f4518137b9aefe99b631505a2064c3c42c9852" />
+    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
     
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.50.13 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.60.3 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.50.13 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.3 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -179,7 +179,8 @@
           </svg>
           <span>Back to top</span>
         </a>
-        <div class="content-icon-container"><div class="theme-toggle-container theme-toggle-content">
+        <div class="content-icon-container">
+          <div class="theme-toggle-container theme-toggle-content">
             <button class="theme-toggle">
               <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
               <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
@@ -194,28 +195,41 @@
         </div>
         <article role="main">
           <h1>Source code for osxphotos.queryoptions</h1><div class="highlight"><pre>
-<span></span><span class="sd">""" QueryOptions class for PhotosDB.query """</span>
+<span></span><span class="sd">&quot;&quot;&quot; QueryOptions class for PhotosDB.query &quot;&quot;&quot;</span>
 
+<span class="kn">import</span> <span class="nn">dataclasses</span>
 <span class="kn">import</span> <span class="nn">datetime</span>
+<span class="kn">import</span> <span class="nn">io</span>
+<span class="kn">import</span> <span class="nn">pathlib</span>
+<span class="kn">import</span> <span class="nn">re</span>
+<span class="kn">import</span> <span class="nn">sys</span>
 <span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">asdict</span><span class="p">,</span> <span class="n">dataclass</span>
 <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Iterable</span><span class="p">,</span> <span class="n">List</span><span class="p">,</span> <span class="n">Optional</span><span class="p">,</span> <span class="n">Tuple</span>
 
 <span class="kn">import</span> <span class="nn">bitmath</span>
 
-<span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"QueryOptions"</span><span class="p">]</span>
+<span class="kn">from</span> <span class="nn">._constants</span> <span class="kn">import</span> <span class="n">UUID_PATTERN</span>
+
+<span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;QueryOptions&quot;</span><span class="p">,</span> <span class="s2">&quot;query_options_from_kwargs&quot;</span><span class="p">,</span> <span class="s2">&quot;IncompatibleQueryOptions&quot;</span><span class="p">]</span>
+
+
+<span class="k">class</span> <span class="nc">IncompatibleQueryOptions</span><span class="p">(</span><span class="ne">Exception</span><span class="p">):</span>
+    <span class="sd">&quot;&quot;&quot;Incompatible query options&quot;&quot;&quot;</span>
+
+    <span class="k">pass</span>
 
 
 <div class="viewcode-block" id="QueryOptions"><a class="viewcode-back" href="../../reference.html#osxphotos.QueryOptions">[docs]</a><span class="nd">@dataclass</span>
 <span class="k">class</span> <span class="nc">QueryOptions</span><span class="p">:</span>
 
-    <span class="sd">"""QueryOptions class for PhotosDB.query</span>
+    <span class="sd">&quot;&quot;&quot;QueryOptions class for PhotosDB.query</span>
 
 <span class="sd">    Attributes:</span>
 <span class="sd">        added_after: search for photos added after a given date</span>
 <span class="sd">        added_before: search for photos added before a given date</span>
 <span class="sd">        added_in_last: search for photos added in last X datetime.timedelta</span>
 <span class="sd">        album: list of album names to search for</span>
-<span class="sd">        burst_photos: search for burst photos</span>
+<span class="sd">        burst_photos: include all associated burst photos for photos in query results</span>
 <span class="sd">        burst: search for burst photos</span>
 <span class="sd">        cloudasset: search for photos that are managed by iCloud</span>
 <span class="sd">        deleted_only: search only for deleted photos</span>
@@ -257,6 +271,7 @@
 <span class="sd">        no_title: search for photos with no title</span>
 <span class="sd">        not_burst: search for non-burst photos</span>
 <span class="sd">        not_cloudasset: search for photos that are not managed by iCloud</span>
+<span class="sd">        not_edited: search for photos that have not been edited</span>
 <span class="sd">        not_favorite: search for non-favorite photos</span>
 <span class="sd">        not_hdr: search for non-HDR photos</span>
 <span class="sd">        not_hidden: search for non-hidden photos</span>
@@ -290,7 +305,11 @@
 <span class="sd">        uti: list of UTIs to search for</span>
 <span class="sd">        uuid: list of uuids to search for</span>
 <span class="sd">        year: search for photos taken in a given year</span>
-<span class="sd">    """</span>
+<span class="sd">        syndicated: search for photos that have been shared via syndication (&quot;Shared with You&quot; album via Messages, etc.)</span>
+<span class="sd">        not_syndicated: search for photos that have not been shared via syndication (&quot;Shared with You&quot; album via Messages, etc.)</span>
+<span class="sd">        saved_to_library: search for syndicated photos that have been saved to the Photos library</span>
+<span class="sd">        not_saved_to_library: search for syndicated photos that have not been saved to the Photos library</span>
+<span class="sd">    &quot;&quot;&quot;</span>
 
     <span class="n">added_after</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
     <span class="n">added_before</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
@@ -339,6 +358,7 @@
     <span class="n">no_title</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
     <span class="n">not_burst</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
     <span class="n">not_cloudasset</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">not_edited</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
     <span class="n">not_favorite</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
     <span class="n">not_hdr</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
     <span class="n">not_hidden</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
@@ -373,9 +393,177 @@
     <span class="n">uti</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">Iterable</span><span class="p">[</span><span class="nb">str</span><span class="p">]]</span> <span class="o">=</span> <span class="kc">None</span>
     <span class="n">uuid</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">Iterable</span><span class="p">[</span><span class="nb">str</span><span class="p">]]</span> <span class="o">=</span> <span class="kc">None</span>
     <span class="n">year</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">Iterable</span><span class="p">[</span><span class="nb">int</span><span class="p">]]</span> <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">syndicated</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">not_syndicated</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">saved_to_library</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">not_saved_to_library</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
 
     <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="k">return</span> <span class="n">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span></div>
+
+
+<span class="k">def</span> <span class="nf">query_options_from_kwargs</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">QueryOptions</span><span class="p">:</span>
+    <span class="sd">&quot;&quot;&quot;Validate query options and create a QueryOptions instance.</span>
+<span class="sd">    Note: this will block on stdin if uuid_from_file is set to &quot;-&quot;</span>
+<span class="sd">    so it is best to call function before creating the PhotosDB instance</span>
+<span class="sd">    so that the validation of query options can happen before the database</span>
+<span class="sd">    is loaded.</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+    <span class="c1"># sanity check input args</span>
+    <span class="n">nonexclusive</span> <span class="o">=</span> <span class="p">[</span>
+        <span class="s2">&quot;added_after&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;added_before&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;added_in_last&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;album&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;duplicate&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;exif&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;external_edit&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;folder&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;from_date&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;from_time&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;has_raw&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;keyword&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;label&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;max_size&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;min_size&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;name&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;person&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;query_eval&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;query_function&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;regex&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;selected&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;to_date&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;to_time&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;uti&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;uuid&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;uuid_from_file&quot;</span><span class="p">,</span>
+        <span class="s2">&quot;year&quot;</span><span class="p">,</span>
+    <span class="p">]</span>
+    <span class="n">exclusive</span> <span class="o">=</span> <span class="p">[</span>
+        <span class="p">(</span><span class="s2">&quot;burst&quot;</span><span class="p">,</span> <span class="s2">&quot;not_burst&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;cloudasset&quot;</span><span class="p">,</span> <span class="s2">&quot;not_cloudasset&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;edited&quot;</span><span class="p">,</span> <span class="s2">&quot;not_edited&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;favorite&quot;</span><span class="p">,</span> <span class="s2">&quot;not_favorite&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;has_comment&quot;</span><span class="p">,</span> <span class="s2">&quot;no_comment&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;has_likes&quot;</span><span class="p">,</span> <span class="s2">&quot;no_likes&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;hdr&quot;</span><span class="p">,</span> <span class="s2">&quot;not_hdr&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;hidden&quot;</span><span class="p">,</span> <span class="s2">&quot;not_hidden&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;in_album&quot;</span><span class="p">,</span> <span class="s2">&quot;not_in_album&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;incloud&quot;</span><span class="p">,</span> <span class="s2">&quot;not_incloud&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;is_reference&quot;</span><span class="p">,</span> <span class="s2">&quot;not_reference&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;keyword&quot;</span><span class="p">,</span> <span class="s2">&quot;no_keyword&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;live&quot;</span><span class="p">,</span> <span class="s2">&quot;not_live&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;location&quot;</span><span class="p">,</span> <span class="s2">&quot;no_location&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;missing&quot;</span><span class="p">,</span> <span class="s2">&quot;not_missing&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;only_photos&quot;</span><span class="p">,</span> <span class="s2">&quot;only_movies&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;panorama&quot;</span><span class="p">,</span> <span class="s2">&quot;not_panorama&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;portrait&quot;</span><span class="p">,</span> <span class="s2">&quot;not_portrait&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;screenshot&quot;</span><span class="p">,</span> <span class="s2">&quot;not_screenshot&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;selfie&quot;</span><span class="p">,</span> <span class="s2">&quot;not_selfie&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;shared&quot;</span><span class="p">,</span> <span class="s2">&quot;not_shared&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;slow_mo&quot;</span><span class="p">,</span> <span class="s2">&quot;not_slow_mo&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;time_lapse&quot;</span><span class="p">,</span> <span class="s2">&quot;not_time_lapse&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;deleted&quot;</span><span class="p">,</span> <span class="s2">&quot;not_deleted&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;deleted&quot;</span><span class="p">,</span> <span class="s2">&quot;deleted_only&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;deleted_only&quot;</span><span class="p">,</span> <span class="s2">&quot;not_deleted&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;syndicated&quot;</span><span class="p">,</span> <span class="s2">&quot;not_syndicated&quot;</span><span class="p">),</span>
+        <span class="p">(</span><span class="s2">&quot;saved_to_library&quot;</span><span class="p">,</span> <span class="s2">&quot;not_saved_to_library&quot;</span><span class="p">),</span>
+    <span class="p">]</span>
+    <span class="c1"># TODO: add option to validate requiring at least one query arg</span>
+    <span class="k">for</span> <span class="n">arg</span><span class="p">,</span> <span class="n">not_arg</span> <span class="ow">in</span> <span class="n">exclusive</span><span class="p">:</span>
+        <span class="k">if</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span> <span class="ow">and</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">not_arg</span><span class="p">):</span>
+            <span class="n">arg</span> <span class="o">=</span> <span class="n">arg</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s2">&quot;_&quot;</span><span class="p">,</span> <span class="s2">&quot;-&quot;</span><span class="p">)</span>
+            <span class="n">not_arg</span> <span class="o">=</span> <span class="n">not_arg</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s2">&quot;_&quot;</span><span class="p">,</span> <span class="s2">&quot;-&quot;</span><span class="p">)</span>
+            <span class="k">raise</span> <span class="n">IncompatibleQueryOptions</span><span class="p">(</span>
+                <span class="sa">f</span><span class="s2">&quot;Incompatible query options: --</span><span class="si">{</span><span class="n">arg</span><span class="si">}</span><span class="s2"> and --</span><span class="si">{</span><span class="n">not_arg</span><span class="si">}</span><span class="s2"> are mutually exclusive&quot;</span>
+            <span class="p">)</span>
+
+    <span class="c1"># some options like title can be specified multiple times</span>
+    <span class="c1"># check if any of them are specified along with their no_ counterpart</span>
+    <span class="n">exclusive_multi_options</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;title&quot;</span><span class="p">,</span> <span class="s2">&quot;description&quot;</span><span class="p">,</span> <span class="s2">&quot;place&quot;</span><span class="p">,</span> <span class="s2">&quot;keyword&quot;</span><span class="p">]</span>
+    <span class="k">for</span> <span class="n">option</span> <span class="ow">in</span> <span class="n">exclusive_multi_options</span><span class="p">:</span>
+        <span class="k">if</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">option</span><span class="p">)</span> <span class="ow">and</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;no_</span><span class="si">{option}</span><span class="s2">&quot;</span><span class="p">):</span>
+            <span class="k">raise</span> <span class="n">IncompatibleQueryOptions</span><span class="p">(</span>
+                <span class="sa">f</span><span class="s2">&quot;--</span><span class="si">{</span><span class="n">option</span><span class="si">}</span><span class="s2"> and --no-</span><span class="si">{</span><span class="n">option</span><span class="si">}</span><span class="s2"> are mutually exclusive&quot;</span>
+            <span class="p">)</span>
+
+    <span class="n">include_photos</span> <span class="o">=</span> <span class="kc">True</span>
+    <span class="n">include_movies</span> <span class="o">=</span> <span class="kc">True</span>  <span class="c1"># default searches for everything</span>
+    <span class="k">if</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;only_movies&quot;</span><span class="p">):</span>
+        <span class="n">include_photos</span> <span class="o">=</span> <span class="kc">False</span>
+    <span class="k">if</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;only_photos&quot;</span><span class="p">):</span>
+        <span class="n">include_movies</span> <span class="o">=</span> <span class="kc">False</span>
+
+    <span class="c1"># load UUIDs if necessary and append to any uuids passed with --uuid</span>
+    <span class="n">uuids</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;uuid&quot;</span><span class="p">,</span> <span class="p">[]))</span>  <span class="c1"># Click option is a tuple</span>
+    <span class="k">if</span> <span class="n">uuid_from_file</span> <span class="o">:=</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;uuid_from_file&quot;</span><span class="p">):</span>
+        <span class="n">uuids</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">load_uuid_from_file</span><span class="p">(</span><span class="n">uuid_from_file</span><span class="p">))</span>
+        <span class="n">uuids</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">uuids</span><span class="p">)</span>
+
+    <span class="n">query_fields</span> <span class="o">=</span> <span class="p">[</span><span class="n">field</span><span class="o">.</span><span class="n">name</span> <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="n">dataclasses</span><span class="o">.</span><span class="n">fields</span><span class="p">(</span><span class="n">QueryOptions</span><span class="p">)]</span>
+    <span class="n">query_dict</span> <span class="o">=</span> <span class="p">{</span><span class="n">field</span><span class="p">:</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">field</span><span class="p">)</span> <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="n">query_fields</span><span class="p">}</span>
+    <span class="n">query_dict</span><span class="p">[</span><span class="s2">&quot;photos&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">include_photos</span>
+    <span class="n">query_dict</span><span class="p">[</span><span class="s2">&quot;movies&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">include_movies</span>
+    <span class="n">query_dict</span><span class="p">[</span><span class="s2">&quot;uuid&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">uuids</span>
+    <span class="n">query_dict</span><span class="p">[</span><span class="s2">&quot;function&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;query_function&quot;</span><span class="p">)</span>
+
+    <span class="k">return</span> <span class="n">QueryOptions</span><span class="p">(</span><span class="o">**</span><span class="n">query_dict</span><span class="p">)</span>
+
+
+<span class="k">def</span> <span class="nf">load_uuid_from_file</span><span class="p">(</span><span class="n">filename</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
+    <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">    Load UUIDs from file.</span>
+<span class="sd">    Does not validate UUIDs but does validate that the UUIDs are in the correct format.</span>
+<span class="sd">    Format is 1 UUID per line, any line beginning with # is ignored.</span>
+<span class="sd">    Whitespace is stripped.</span>
+
+<span class="sd">    Arguments:</span>
+<span class="sd">        filename: file name of the file containing UUIDs</span>
+
+<span class="sd">    Returns:</span>
+<span class="sd">        list of UUIDs or empty list of no UUIDs in file</span>
+
+<span class="sd">    Raises:</span>
+<span class="sd">        FileNotFoundError if file does not exist</span>
+<span class="sd">        ValueError if UUID is not in correct format</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+
+    <span class="k">if</span> <span class="n">filename</span> <span class="o">==</span> <span class="s2">&quot;-&quot;</span><span class="p">:</span>
+        <span class="k">return</span> <span class="n">_load_uuid_from_stream</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">stdin</span><span class="p">)</span>
+
+    <span class="k">if</span> <span class="ow">not</span> <span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span><span class="o">.</span><span class="n">is_file</span><span class="p">():</span>
+        <span class="k">raise</span> <span class="ne">FileNotFoundError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Could not find file </span><span class="si">{</span><span class="n">filename</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+
+    <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s2">&quot;r&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
+        <span class="k">return</span> <span class="n">_load_uuid_from_stream</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
+
+
+<span class="k">def</span> <span class="nf">_load_uuid_from_stream</span><span class="p">(</span><span class="n">stream</span><span class="p">:</span> <span class="n">io</span><span class="o">.</span><span class="n">IOBase</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
+    <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">    Load UUIDs from stream.</span>
+<span class="sd">    Does not validate UUIDs but does validate that the UUIDs are in the correct format.</span>
+<span class="sd">    Format is 1 UUID per line, any line beginning with # is ignored.</span>
+<span class="sd">    Whitespace is stripped.</span>
+
+<span class="sd">    Arguments:</span>
+<span class="sd">        filename: file name of the file containing UUIDs</span>
+
+<span class="sd">    Returns:</span>
+<span class="sd">        list of UUIDs or empty list of no UUIDs in file</span>
+
+<span class="sd">    Raises:</span>
+<span class="sd">        ValueError if UUID is not in correct format</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+
+    <span class="n">uuid</span> <span class="o">=</span> <span class="p">[]</span>
+    <span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">stream</span><span class="p">:</span>
+        <span class="n">line</span> <span class="o">=</span> <span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span>
+        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">line</span><span class="p">)</span> <span class="ow">and</span> <span class="n">line</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">!=</span> <span class="s2">&quot;#&quot;</span><span class="p">:</span>
+            <span class="k">if</span> <span class="ow">not</span> <span class="n">re</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;^</span><span class="si">{</span><span class="n">UUID_PATTERN</span><span class="si">}</span><span class="s2">$&quot;</span><span class="p">,</span> <span class="n">line</span><span class="p">):</span>
+                <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Invalid UUID: </span><span class="si">{</span><span class="n">line</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+            <span class="n">line</span> <span class="o">=</span> <span class="n">line</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span>
+            <span class="n">uuid</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">line</span><span class="p">)</span>
+    <span class="k">return</span> <span class="n">uuid</span>
 </pre></div>
         </article>
       </div>
@@ -413,7 +601,9 @@
 </div><script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
     <script src="../../_static/jquery.js"></script>
     <script src="../../_static/underscore.js"></script>
+    <script src="../../_static/_sphinx_javascript_frameworks_compat.js"></script>
     <script src="../../_static/doctools.js"></script>
+    <script src="../../_static/sphinx_highlight.js"></script>
     <script src="../../_static/scripts/furo.js"></script>
     <script src="../../_static/clipboard.min.js"></script>
     <script src="../../_static/copybutton.js"></script>

docs/_modules/osxphotos/scoreinfo.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>osxphotos.scoreinfo - osxphotos 0.56.2 documentation</title>
+        <title>osxphotos.scoreinfo - osxphotos 0.60.2 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.56.2 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.60.2 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.56.2 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.2 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>

docs/_modules/osxphotos/searchinfo.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>osxphotos.searchinfo - osxphotos 0.54.1 documentation</title>
+        <title>osxphotos.searchinfo - osxphotos 0.58.1 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
@@ -123,7 +123,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../index.html"><div class="brand">osxphotos 0.54.1 documentation</div></a>
+      <a href="../../index.html"><div class="brand">osxphotos 0.58.1 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -146,7 +146,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.54.1 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.58.1 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -160,7 +160,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../../cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -336,6 +336,13 @@
             <span class="k">return</span> <span class="p">[]</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_text_for_category</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_categories</span><span class="o">.</span><span class="n">DETECTED_TEXT</span><span class="p">)</span>
 
+    <span class="nd">@property</span>
+    <span class="k">def</span> <span class="nf">text_found</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Returns True if photos has detected text (macOS 13+ / Photos 8+ only)&quot;&quot;&quot;</span>
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_photo</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_photos_ver</span> <span class="o">&lt;</span> <span class="mi">8</span><span class="p">:</span>
+            <span class="k">return</span> <span class="p">[]</span>
+        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_text_for_category</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_categories</span><span class="o">.</span><span class="n">TEXT_FOUND</span><span class="p">)</span>
+
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">camera</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;returns camera name (macOS 13+ / Photos 8+ only)&quot;&quot;&quot;</span>
@@ -344,10 +351,18 @@
         <span class="n">camera</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_text_for_category</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_categories</span><span class="o">.</span><span class="n">CAMERA</span><span class="p">)</span>
         <span class="k">return</span> <span class="n">camera</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">if</span> <span class="n">camera</span> <span class="k">else</span> <span class="s2">&quot;&quot;</span>
 
+    <span class="nd">@property</span>
+    <span class="k">def</span> <span class="nf">source</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;returns source of the photo (e.g. &quot;Messages&quot;, &quot;Safar&quot;, etc) (macOS 13+ / Photos 8+ only)&quot;&quot;&quot;</span>
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_photo</span><span class="o">.</span><span class="n">_db</span><span class="o">.</span><span class="n">_photos_ver</span> <span class="o">&lt;</span> <span class="mi">8</span><span class="p">:</span>
+            <span class="k">return</span> <span class="s2">&quot;&quot;</span>
+        <span class="n">source</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_text_for_category</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_categories</span><span class="o">.</span><span class="n">SOURCE</span><span class="p">)</span>
+        <span class="k">return</span> <span class="n">source</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">if</span> <span class="n">source</span> <span class="k">else</span> <span class="s2">&quot;&quot;</span>
+
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">all</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;return all search info properties in a single list&quot;&quot;&quot;</span>
-        <span class="nb">all</span> <span class="o">=</span> <span class="p">(</span>
+        <span class="n">all_</span> <span class="o">=</span> <span class="p">(</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">labels</span>
             <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">place_names</span>
             <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">streets</span>
@@ -362,23 +377,23 @@
             <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">detected_text</span>
         <span class="p">)</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">city</span><span class="p">:</span>
-            <span class="nb">all</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">city</span><span class="p">]</span>
+            <span class="n">all_</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">city</span><span class="p">]</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">state</span><span class="p">:</span>
-            <span class="nb">all</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">state</span><span class="p">]</span>
+            <span class="n">all_</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">state</span><span class="p">]</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">state_abbreviation</span><span class="p">:</span>
-            <span class="nb">all</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">state_abbreviation</span><span class="p">]</span>
+            <span class="n">all_</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">state_abbreviation</span><span class="p">]</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">country</span><span class="p">:</span>
-            <span class="nb">all</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">country</span><span class="p">]</span>
+            <span class="n">all_</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">country</span><span class="p">]</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">month</span><span class="p">:</span>
-            <span class="nb">all</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">month</span><span class="p">]</span>
+            <span class="n">all_</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">month</span><span class="p">]</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">year</span><span class="p">:</span>
-            <span class="nb">all</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">year</span><span class="p">]</span>
+            <span class="n">all_</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">year</span><span class="p">]</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">season</span><span class="p">:</span>
-            <span class="nb">all</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">season</span><span class="p">]</span>
+            <span class="n">all_</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">season</span><span class="p">]</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">camera</span><span class="p">:</span>
-            <span class="nb">all</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">camera</span><span class="p">]</span>
+            <span class="n">all_</span> <span class="o">+=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">camera</span><span class="p">]</span>
 
-        <span class="k">return</span> <span class="nb">all</span>
+        <span class="k">return</span> <span class="n">all_</span>
 
 <div class="viewcode-block" id="SearchInfo.asdict"><a class="viewcode-back" href="../../reference.html#osxphotos.SearchInfo.asdict">[docs]</a>    <span class="k">def</span> <span class="nf">asdict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;return dict of search info&quot;&quot;&quot;</span>
@@ -403,6 +418,7 @@
             <span class="s2">&quot;media_types&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">media_types</span><span class="p">,</span>
             <span class="s2">&quot;detected_text&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">detected_text</span><span class="p">,</span>
             <span class="s2">&quot;camera&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">camera</span><span class="p">,</span>
+            <span class="s2">&quot;source&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">source</span><span class="p">,</span>
         <span class="p">}</span></div>
 
     <span class="k">def</span> <span class="nf">_get_text_for_category</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">category</span><span class="p">):</span>

docs/_sources/reference.rst.txt

@@ -1,5 +1,5 @@
-OSXPhotos python API 
-====================
+OSXPhotos Python Reference
+==========================
 
 .. automodule:: osxphotos
    :members:

docs/_sources/template_help.rst.txt

@@ -58,6 +58,8 @@ Valid filters are:
 * `join(x)`: Join list of values with delimiter x, e.g. join(,): ['a', 'b', 'c'] => 'a,b,c'; the DELIM option functions similar to join(x) but with DELIM, the join happens before being passed to any filters.May optionally be used without an argument, that is 'join()' which joins values together with no delimiter. e.g. join(): ['a', 'b', 'c'] => 'abc'.
 * `append(x)`: Append x to list of values, e.g. append(d): ['a', 'b', 'c'] => ['a', 'b', 'c', 'd'].
 * `prepend(x)`: Prepend x to list of values, e.g. prepend(d): ['a', 'b', 'c'] => ['d', 'a', 'b', 'c'].
+* `appends(x)`: Append s[tring] Append x to each value of list of values, e.g. appends(d): ['a', 'b', 'c'] => ['ad', 'bd', 'cd'].
+* `prepends(x)`: Prepend s[tring] x to each value of list of values, e.g. prepends(d): ['a', 'b', 'c'] => ['da', 'db', 'dc'].
 * `remove(x)`: Remove x from list of values, e.g. remove(b): ['a', 'b', 'c'] => ['a', 'c'].
 * `slice(start:stop:step)`: Slice list using same semantics as Python's list slicing, e.g. slice(1:3): ['a', 'b', 'c', 'd'] => ['b', 'c']; slice(1:4:2): ['a', 'b', 'c', 'd'] => ['b', 'd']; slice(1:): ['a', 'b', 'c', 'd'] => ['b', 'c', 'd']; slice(:-1): ['a', 'b', 'c', 'd'] => ['a', 'b', 'c']; slice(::-1): ['a', 'b', 'c', 'd'] => ['d', 'c', 'b', 'a']. See also sslice().
 * `sslice(start:stop:step)`: [s(tring) slice] Slice values in a list using same semantics as Python's string slicing, e.g. sslice(1:3):'abcd => 'bc'; sslice(1:4:2): 'abcd' => 'bd', etc. See also slice().
@@ -322,6 +324,8 @@ Template Substitutions
      - A shorter representation of photo's internal universally unique identifier (UUID) for the photo, a 22-character string unique to the photo, e.g. 'JYsxugP9UjetmCbBCHXcmu'
    * - {id}
      - A unique number for the photo based on its primary key in the Photos database. A sequential integer, e.g. 1, 2, 3...etc.  Each asset associated with a photo (e.g. an image and Live Photo preview) will share the same id. May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{id:05d}' which results in 00001, 00002, 00003...etc.
+   * - {counter}
+     - A sequential counter, starting at 0, that increments each time it is evaluated.To start counting at a value other than 0, append append '(starting_value)' to the field name.For example, to start counting at 1 instead of 0: '{counter(1)}'.May be formatted using a python string format code.For example, to format as a 5-digit integer and pad with zeros, use '{counter:05d(1)}'which results in 00001, 00002, 00003...etc.You may also specify a stop value which causes the counter to reset to the starting valuewhen the stop value is reached and a step size which causes the counter to increment bythe specified value instead of 1. Use the format '{counter(start,stop,step)}' where start,stop, and step are integers. For example, to count from 1 to 10 by 2, use '{counter(1,11,2)}'.Note that the counter stops counting when the stop value is reached and does not return thestop value. Start, stop, and step are optional and may be omitted. For example, to countfrom 0 by 2s, use '{counter(,,2)}'.You may create an arbitrary number of counters by appending a unique name to the field namepreceded by a period: '{counter.a}', '{counter.b}', etc. Each counter will have its own stateand will start at 0 and increment by 1 unless otherwise specified. Note: {counter} is not suitable for use with 'export' and '--update' as the counter associated with a photo may change between export sessions. See also {id}.
    * - {album_seq}
      - An integer, starting at 0, indicating the photo's index (sequence) in the containing album. Only valid when used in a '--filename' template and only when '{album}' or '{folder_album}' is used in the '--directory' template. For example '--directory "{folder_album}" --filename "{album\ *seq}*\ {original_name}"'. To start counting at a value other than 0, append append '(starting_value)' to the field name.  For example, to start counting at 1 instead of 0: '{album_seq(1)}'. May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{album_seq:05d}' which results in 00000, 00001, 00002...etc. To format while also using a starting value: '{album_seq:05d(1)}' which results in 0001, 00002...etc.This may result in incorrect sequences if you have duplicate albums with the same name; see also '{folder_album_seq}'.
    * - {folder_album_seq}
@@ -357,7 +361,7 @@ Template Substitutions
    * - {tab}
      - :A tab: '\t'
    * - {osxphotos_version}
-     - The osxphotos version, e.g. '0.56.2'
+     - The osxphotos version, e.g. '0.60.4'
    * - {osxphotos_cmd_line}
      - The full command line used to run osxphotos
    * - {album}

docs/_static/copybutton.css

@@ -35,7 +35,8 @@ div.highlight  {
     position: relative;
 }
 
-.highlight:hover button.copybtn {
+/* Show the copybutton */
+.highlight:hover button.copybtn, button.copybtn.success {
 	opacity: 1;
 }
 

docs/_static/copybutton.js

@@ -102,18 +102,25 @@ const clearSelection = () => {
   }
 }
 
-// Changes tooltip text for two seconds, then changes it back
+// Changes tooltip text for a moment, then changes it back
+// We want the timeout of our `success` class to be a bit shorter than the
+// tooltip and icon change, so that we can hide the icon before changing back.
+var timeoutIcon = 2000;
+var timeoutSuccessClass = 1500;
+
 const temporarilyChangeTooltip = (el, oldText, newText) => {
   el.setAttribute('data-tooltip', newText)
   el.classList.add('success')
-  setTimeout(() => el.setAttribute('data-tooltip', oldText), 2000)
-  setTimeout(() => el.classList.remove('success'), 2000)
+  // Remove success a little bit sooner than we change the tooltip
+  // So that we can use CSS to hide the copybutton first
+  setTimeout(() => el.classList.remove('success'), timeoutSuccessClass)
+  setTimeout(() => el.setAttribute('data-tooltip', oldText), timeoutIcon)
 }
 
 // Changes the copy button icon for two seconds, then changes it back
 const temporarilyChangeIcon = (el) => {
   el.innerHTML = iconCheck;
-  setTimeout(() => {el.innerHTML = iconCopy}, 2000)
+  setTimeout(() => {el.innerHTML = iconCopy}, timeoutIcon)
 }
 
 const addCopyButtonToCodeCells = () => {
@@ -125,7 +132,8 @@ const addCopyButtonToCodeCells = () => {
   }
 
   // Add copybuttons to all of our code cells
-  const codeCells = document.querySelectorAll('div.highlight pre')
+  const COPYBUTTON_SELECTOR = 'div.highlight pre';
+  const codeCells = document.querySelectorAll(COPYBUTTON_SELECTOR)
   codeCells.forEach((codeCell, index) => {
     const id = codeCellId(index)
     codeCell.setAttribute('id', id)
@@ -141,10 +149,25 @@ function escapeRegExp(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string
 }
 
+/**
+ * Removes excluded text from a Node.
+ *
+ * @param {Node} target Node to filter.
+ * @param {string} exclude CSS selector of nodes to exclude.
+ * @returns {DOMString} Text from `target` with text removed.
+ */
+function filterText(target, exclude) {
+    const clone = target.cloneNode(true);  // clone as to not modify the live DOM
+    if (exclude) {
+        // remove excluded nodes
+        clone.querySelectorAll(exclude).forEach(node => node.remove());
+    }
+    return clone.innerText;
+}
+
 // Callback when a copy button is clicked. Will be passed the node that was clicked
 // should then grab the text and replace pieces of text that shouldn't be used in output
 function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") {
-
     var regexp;
     var match;
 
@@ -199,7 +222,12 @@ function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onl
 
 var copyTargetText = (trigger) => {
   var target = document.querySelector(trigger.attributes['data-clipboard-target'].value);
-  return formatCopyText(target.innerText, '', false, true, true, true, '', '')
+
+  // get filtered text
+  let exclude = '.linenos, .gp';
+
+  let text = filterText(target, exclude);
+  return formatCopyText(text, '', false, true, true, true, '', '')
 }
 
   // Initialize with a callback so we can modify the text before copy

docs/_static/copybutton_funcs.js

@@ -2,10 +2,25 @@ function escapeRegExp(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string
 }
 
+/**
+ * Removes excluded text from a Node.
+ *
+ * @param {Node} target Node to filter.
+ * @param {string} exclude CSS selector of nodes to exclude.
+ * @returns {DOMString} Text from `target` with text removed.
+ */
+export function filterText(target, exclude) {
+    const clone = target.cloneNode(true);  // clone as to not modify the live DOM
+    if (exclude) {
+        // remove excluded nodes
+        clone.querySelectorAll(exclude).forEach(node => node.remove());
+    }
+    return clone.innerText;
+}
+
 // Callback when a copy button is clicked. Will be passed the node that was clicked
 // should then grab the text and replace pieces of text that shouldn't be used in output
 export function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") {
-
     var regexp;
     var match;
 

docs/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '0.56.2',
+    VERSION: '0.60.4',
     LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/index.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos" href="overview.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>osxphotos 0.56.2 documentation</title>
+        <title>osxphotos 0.60.4 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -124,7 +124,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="#"><div class="brand">osxphotos 0.56.2 documentation</div></a>
+      <a href="#"><div class="brand">osxphotos 0.60.4 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -147,7 +147,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="#">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.56.2 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.4 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -161,7 +161,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -236,7 +236,9 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="cli.html#osxphotos">osxphotos</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-about">about</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-add-locations">add-locations</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-albums">albums</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-batch-edit">batch-edit</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-diff">diff</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-docs">docs</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-dump">dump</a></li>
@@ -257,6 +259,7 @@
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-query">query</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-repl">repl</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-run">run</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-show">show</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-snap">snap</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-sync">sync</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-theme">theme</a></li>
@@ -279,8 +282,9 @@
 <li class="toctree-l2"><a class="reference internal" href="package_overview.html#using-the-osxphotos-cli-to-run-python-code">Using the osxphotos CLI to run python code</a></li>
 </ul>
 </li>
-<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a><ul>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.AlbumInfo"><code class="docutils literal notranslate"><span class="pre">AlbumInfo</span></code></a><ul>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.AlbumInfo.asdict"><code class="docutils literal notranslate"><span class="pre">AlbumInfo.asdict()</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.AlbumInfo.folder_list"><code class="docutils literal notranslate"><span class="pre">AlbumInfo.folder_list</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.AlbumInfo.folder_names"><code class="docutils literal notranslate"><span class="pre">AlbumInfo.folder_names</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.AlbumInfo.parent"><code class="docutils literal notranslate"><span class="pre">AlbumInfo.parent</span></code></a></li>
@@ -305,6 +309,7 @@
 </li>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.ExportDB"><code class="docutils literal notranslate"><span class="pre">ExportDB</span></code></a><ul>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.ExportDB.close"><code class="docutils literal notranslate"><span class="pre">ExportDB.close()</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.ExportDB.connection"><code class="docutils literal notranslate"><span class="pre">ExportDB.connection</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.ExportDB.create_file_record"><code class="docutils literal notranslate"><span class="pre">ExportDB.create_file_record()</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.ExportDB.create_or_get_file_record"><code class="docutils literal notranslate"><span class="pre">ExportDB.create_or_get_file_record()</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.ExportDB.delete_data_for_filepath"><code class="docutils literal notranslate"><span class="pre">ExportDB.delete_data_for_filepath()</span></code></a></li>
@@ -394,6 +399,7 @@
 </li>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.FolderInfo"><code class="docutils literal notranslate"><span class="pre">FolderInfo</span></code></a><ul>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.FolderInfo.album_info"><code class="docutils literal notranslate"><span class="pre">FolderInfo.album_info</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.FolderInfo.asdict"><code class="docutils literal notranslate"><span class="pre">FolderInfo.asdict()</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.FolderInfo.parent"><code class="docutils literal notranslate"><span class="pre">FolderInfo.parent</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.FolderInfo.subfolders"><code class="docutils literal notranslate"><span class="pre">FolderInfo.subfolders</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.FolderInfo.title"><code class="docutils literal notranslate"><span class="pre">FolderInfo.title</span></code></a></li>
@@ -401,7 +407,9 @@
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.ImportInfo"><code class="docutils literal notranslate"><span class="pre">ImportInfo</span></code></a><ul>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.ImportInfo.asdict"><code class="docutils literal notranslate"><span class="pre">ImportInfo.asdict()</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.ImportInfo.photos"><code class="docutils literal notranslate"><span class="pre">ImportInfo.photos</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.ImportInfo.title"><code class="docutils literal notranslate"><span class="pre">ImportInfo.title</span></code></a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.LikeInfo"><code class="docutils literal notranslate"><span class="pre">LikeInfo</span></code></a></li>
@@ -421,8 +429,11 @@
 <li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.PersonInfo"><code class="docutils literal notranslate"><span class="pre">PersonInfo</span></code></a><ul>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PersonInfo.asdict"><code class="docutils literal notranslate"><span class="pre">PersonInfo.asdict()</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PersonInfo.face_info"><code class="docutils literal notranslate"><span class="pre">PersonInfo.face_info</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PersonInfo.favorite"><code class="docutils literal notranslate"><span class="pre">PersonInfo.favorite</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PersonInfo.feature_less"><code class="docutils literal notranslate"><span class="pre">PersonInfo.feature_less</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PersonInfo.json"><code class="docutils literal notranslate"><span class="pre">PersonInfo.json()</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PersonInfo.photos"><code class="docutils literal notranslate"><span class="pre">PersonInfo.photos</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PersonInfo.sort_order"><code class="docutils literal notranslate"><span class="pre">PersonInfo.sort_order</span></code></a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.PhotoExporter"><code class="docutils literal notranslate"><span class="pre">PhotoExporter</span></code></a><ul>
@@ -443,7 +454,9 @@
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.burst_key"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.burst_key</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.burst_photos"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.burst_photos</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.burst_selected"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.burst_selected</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.cloud_guid"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.cloud_guid</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.cloud_metadata"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.cloud_metadata</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.cloud_owner_hashed_id"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.cloud_owner_hashed_id</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.comments"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.comments</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.date"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.date</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.date_added"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.date_added</span></code></a></li>
@@ -504,6 +517,7 @@
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.project_info"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.project_info</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.raw_original"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.raw_original</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.render_template"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.render_template()</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.saved_to_library"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.saved_to_library</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.score"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.score</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.screenshot"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.screenshot</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.search_info"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.search_info</span></code></a></li>
@@ -511,6 +525,8 @@
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.selfie"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.selfie</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.shared"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.shared</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.slow_mo"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.slow_mo</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.syndicated"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.syndicated</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.tables"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.tables()</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.time_lapse"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.time_lapse</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.title"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.title</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotoInfo.tzoffset"><code class="docutils literal notranslate"><span class="pre">PhotoInfo.tzoffset</span></code></a></li>
@@ -571,12 +587,17 @@
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotosDB.persons_as_dict"><code class="docutils literal notranslate"><span class="pre">PhotosDB.persons_as_dict</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotosDB.photos"><code class="docutils literal notranslate"><span class="pre">PhotosDB.photos()</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotosDB.photos_by_uuid"><code class="docutils literal notranslate"><span class="pre">PhotosDB.photos_by_uuid()</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotosDB.photos_version"><code class="docutils literal notranslate"><span class="pre">PhotosDB.photos_version</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotosDB.project_info"><code class="docutils literal notranslate"><span class="pre">PhotosDB.project_info</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.PhotosDB.query"><code class="docutils literal notranslate"><span class="pre">PhotosDB.query()</span></code></a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.PlaceInfo"><code class="docutils literal notranslate"><span class="pre">PlaceInfo</span></code></a></li>
-<li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.ProjectInfo"><code class="docutils literal notranslate"><span class="pre">ProjectInfo</span></code></a></li>
+<li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.ProjectInfo"><code class="docutils literal notranslate"><span class="pre">ProjectInfo</span></code></a><ul>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.ProjectInfo.folder_list"><code class="docutils literal notranslate"><span class="pre">ProjectInfo.folder_list</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.ProjectInfo.folder_names"><code class="docutils literal notranslate"><span class="pre">ProjectInfo.folder_names</span></code></a></li>
+</ul>
+</li>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.QueryOptions"><code class="docutils literal notranslate"><span class="pre">QueryOptions</span></code></a><ul>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.added_after"><code class="docutils literal notranslate"><span class="pre">QueryOptions.added_after</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.added_before"><code class="docutils literal notranslate"><span class="pre">QueryOptions.added_before</span></code></a></li>
@@ -624,6 +645,7 @@
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.no_title"><code class="docutils literal notranslate"><span class="pre">QueryOptions.no_title</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.not_burst"><code class="docutils literal notranslate"><span class="pre">QueryOptions.not_burst</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.not_cloudasset"><code class="docutils literal notranslate"><span class="pre">QueryOptions.not_cloudasset</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.not_edited"><code class="docutils literal notranslate"><span class="pre">QueryOptions.not_edited</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.not_favorite"><code class="docutils literal notranslate"><span class="pre">QueryOptions.not_favorite</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.not_hdr"><code class="docutils literal notranslate"><span class="pre">QueryOptions.not_hdr</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.not_hidden"><code class="docutils literal notranslate"><span class="pre">QueryOptions.not_hidden</span></code></a></li>
@@ -657,6 +679,10 @@
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.uti"><code class="docutils literal notranslate"><span class="pre">QueryOptions.uti</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.uuid"><code class="docutils literal notranslate"><span class="pre">QueryOptions.uuid</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.year"><code class="docutils literal notranslate"><span class="pre">QueryOptions.year</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.syndicated"><code class="docutils literal notranslate"><span class="pre">QueryOptions.syndicated</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.not_syndicated"><code class="docutils literal notranslate"><span class="pre">QueryOptions.not_syndicated</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.saved_to_library"><code class="docutils literal notranslate"><span class="pre">QueryOptions.saved_to_library</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.QueryOptions.not_saved_to_library"><code class="docutils literal notranslate"><span class="pre">QueryOptions.not_saved_to_library</span></code></a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos.ScoreInfo"><code class="docutils literal notranslate"><span class="pre">ScoreInfo</span></code></a><ul>
@@ -680,9 +706,11 @@
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.SearchInfo.neighborhoods"><code class="docutils literal notranslate"><span class="pre">SearchInfo.neighborhoods</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.SearchInfo.place_names"><code class="docutils literal notranslate"><span class="pre">SearchInfo.place_names</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.SearchInfo.season"><code class="docutils literal notranslate"><span class="pre">SearchInfo.season</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.SearchInfo.source"><code class="docutils literal notranslate"><span class="pre">SearchInfo.source</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.SearchInfo.state"><code class="docutils literal notranslate"><span class="pre">SearchInfo.state</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.SearchInfo.state_abbreviation"><code class="docutils literal notranslate"><span class="pre">SearchInfo.state_abbreviation</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.SearchInfo.streets"><code class="docutils literal notranslate"><span class="pre">SearchInfo.streets</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.SearchInfo.text_found"><code class="docutils literal notranslate"><span class="pre">SearchInfo.text_found</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.SearchInfo.venue_types"><code class="docutils literal notranslate"><span class="pre">SearchInfo.venue_types</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.SearchInfo.venues"><code class="docutils literal notranslate"><span class="pre">SearchInfo.venues</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="reference.html#osxphotos.SearchInfo.year"><code class="docutils literal notranslate"><span class="pre">SearchInfo.year</span></code></a></li>

docs/overview.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos Tutorial" href="tutorial.html" /><link rel="prev" title="Welcome to OSXPhotos’s documentation!" href="index.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>OSXPhotos - osxphotos 0.56.2 documentation</title>
+        <title>OSXPhotos - osxphotos 0.60.4 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -124,7 +124,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">osxphotos 0.56.2 documentation</div></a>
+      <a href="index.html"><div class="brand">osxphotos 0.60.4 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -147,7 +147,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.56.2 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.4 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -161,7 +161,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>

docs/package_overview.html

@@ -3,10 +3,10 @@
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
-<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos python API" href="reference.html" /><link rel="prev" title="OSXPhotos Template System" href="template_help.html" />
+<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos Python Reference" href="reference.html" /><link rel="prev" title="OSXPhotos Template System" href="template_help.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>OSXPhotos Python Package Overview - osxphotos 0.56.2 documentation</title>
+        <title>OSXPhotos Python Package Overview - osxphotos 0.60.4 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -124,7 +124,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">osxphotos 0.56.2 documentation</div></a>
+      <a href="index.html"><div class="brand">osxphotos 0.60.4 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -147,7 +147,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.56.2 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.4 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -161,7 +161,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -392,7 +392,7 @@ as well as <code class="docutils literal notranslate"><span class="pre">{functio
                 <div class="context">
                   <span>Next</span>
                 </div>
-                <div class="title">OSXPhotos python API</div>
+                <div class="title">OSXPhotos Python Reference</div>
               </div>
               <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
             </a>

docs/py-modindex.html

@@ -4,7 +4,7 @@
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" />
 
-    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/><title>Python Module Index - osxphotos 0.56.2 documentation</title>
+    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/><title>Python Module Index - osxphotos 0.60.4 documentation</title>
 <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -122,7 +122,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">osxphotos 0.56.2 documentation</div></a>
+      <a href="index.html"><div class="brand">osxphotos 0.60.4 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -145,7 +145,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.56.2 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.4 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -159,7 +159,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>

docs/search.html

@@ -4,7 +4,7 @@
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="#" />
 
-    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/><title>Search - osxphotos 0.56.2 documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/><title>Search - osxphotos 0.60.4 documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
@@ -121,7 +121,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">osxphotos 0.56.2 documentation</div></a>
+      <a href="index.html"><div class="brand">osxphotos 0.60.4 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -144,7 +144,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.56.2 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.4 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="#" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -158,7 +158,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>

docs/template_help.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos Python Package Overview" href="package_overview.html" /><link rel="prev" title="OSXPhotos Command Line Interface (CLI)" href="cli.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>OSXPhotos Template System - osxphotos 0.56.2 documentation</title>
+        <title>OSXPhotos Template System - osxphotos 0.60.4 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -124,7 +124,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">osxphotos 0.56.2 documentation</div></a>
+      <a href="index.html"><div class="brand">osxphotos 0.60.4 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -147,7 +147,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.56.2 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.4 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -161,7 +161,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1 current current-page"><a class="current reference internal" href="#">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>
@@ -240,6 +240,8 @@
 <li><p><cite>join(x)</cite>: Join list of values with delimiter x, e.g. join(,): [‘a’, ‘b’, ‘c’] =&gt; ‘a,b,c’; the DELIM option functions similar to join(x) but with DELIM, the join happens before being passed to any filters.May optionally be used without an argument, that is ‘join()’ which joins values together with no delimiter. e.g. join(): [‘a’, ‘b’, ‘c’] =&gt; ‘abc’.</p></li>
 <li><p><cite>append(x)</cite>: Append x to list of values, e.g. append(d): [‘a’, ‘b’, ‘c’] =&gt; [‘a’, ‘b’, ‘c’, ‘d’].</p></li>
 <li><p><cite>prepend(x)</cite>: Prepend x to list of values, e.g. prepend(d): [‘a’, ‘b’, ‘c’] =&gt; [‘d’, ‘a’, ‘b’, ‘c’].</p></li>
+<li><p><cite>appends(x)</cite>: Append s[tring] Append x to each value of list of values, e.g. appends(d): [‘a’, ‘b’, ‘c’] =&gt; [‘ad’, ‘bd’, ‘cd’].</p></li>
+<li><p><cite>prepends(x)</cite>: Prepend s[tring] x to each value of list of values, e.g. prepends(d): [‘a’, ‘b’, ‘c’] =&gt; [‘da’, ‘db’, ‘dc’].</p></li>
 <li><p><cite>remove(x)</cite>: Remove x from list of values, e.g. remove(b): [‘a’, ‘b’, ‘c’] =&gt; [‘a’, ‘c’].</p></li>
 <li><p><cite>slice(start:stop:step)</cite>: Slice list using same semantics as Python’s list slicing, e.g. slice(1:3): [‘a’, ‘b’, ‘c’, ‘d’] =&gt; [‘b’, ‘c’]; slice(1:4:2): [‘a’, ‘b’, ‘c’, ‘d’] =&gt; [‘b’, ‘d’]; slice(1:): [‘a’, ‘b’, ‘c’, ‘d’] =&gt; [‘b’, ‘c’, ‘d’]; slice(:-1): [‘a’, ‘b’, ‘c’, ‘d’] =&gt; [‘a’, ‘b’, ‘c’]; slice(::-1): [‘a’, ‘b’, ‘c’, ‘d’] =&gt; [‘d’, ‘c’, ‘b’, ‘a’]. See also sslice().</p></li>
 <li><p><cite>sslice(start:stop:step)</cite>: [s(tring) slice] Slice values in a list using same semantics as Python’s string slicing, e.g. sslice(1:3):’abcd =&gt; ‘bc’; sslice(1:4:2): ‘abcd’ =&gt; ‘bd’, etc. See also slice().</p></li>
@@ -551,55 +553,58 @@
 <tr class="row-even"><td><p>{id}</p></td>
 <td><p>A unique number for the photo based on its primary key in the Photos database. A sequential integer, e.g. 1, 2, 3…etc.  Each asset associated with a photo (e.g. an image and Live Photo preview) will share the same id. May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use ‘{id:05d}’ which results in 00001, 00002, 00003…etc.</p></td>
 </tr>
-<tr class="row-odd"><td><p>{album_seq}</p></td>
+<tr class="row-odd"><td><p>{counter}</p></td>
+<td><p>A sequential counter, starting at 0, that increments each time it is evaluated.To start counting at a value other than 0, append append ‘(starting_value)’ to the field name.For example, to start counting at 1 instead of 0: ‘{counter(1)}’.May be formatted using a python string format code.For example, to format as a 5-digit integer and pad with zeros, use ‘{counter:05d(1)}’which results in 00001, 00002, 00003…etc.You may also specify a stop value which causes the counter to reset to the starting valuewhen the stop value is reached and a step size which causes the counter to increment bythe specified value instead of 1. Use the format ‘{counter(start,stop,step)}’ where start,stop, and step are integers. For example, to count from 1 to 10 by 2, use ‘{counter(1,11,2)}’.Note that the counter stops counting when the stop value is reached and does not return thestop value. Start, stop, and step are optional and may be omitted. For example, to countfrom 0 by 2s, use ‘{counter(,,2)}’.You may create an arbitrary number of counters by appending a unique name to the field namepreceded by a period: ‘{counter.a}’, ‘{counter.b}’, etc. Each counter will have its own stateand will start at 0 and increment by 1 unless otherwise specified. Note: {counter} is not suitable for use with ‘export’ and ‘–update’ as the counter associated with a photo may change between export sessions. See also {id}.</p></td>
+</tr>
+<tr class="row-even"><td><p>{album_seq}</p></td>
 <td><p>An integer, starting at 0, indicating the photo’s index (sequence) in the containing album. Only valid when used in a ‘–filename’ template and only when ‘{album}’ or ‘{folder_album}’ is used in the ‘–directory’ template. For example ‘–directory “{folder_album}” –filename “{album<em>seq}</em>{original_name}”’. To start counting at a value other than 0, append append ‘(starting_value)’ to the field name.  For example, to start counting at 1 instead of 0: ‘{album_seq(1)}’. May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use ‘{album_seq:05d}’ which results in 00000, 00001, 00002…etc. To format while also using a starting value: ‘{album_seq:05d(1)}’ which results in 0001, 00002…etc.This may result in incorrect sequences if you have duplicate albums with the same name; see also ‘{folder_album_seq}’.</p></td>
 </tr>
-<tr class="row-even"><td><p>{folder_album_seq}</p></td>
+<tr class="row-odd"><td><p>{folder_album_seq}</p></td>
 <td><p>An integer, starting at 0, indicating the photo’s index (sequence) in the containing album and folder path. Only valid when used in a ‘–filename’ template and only when ‘{folder_album}’ is used in the ‘–directory’ template. For example ‘–directory “{folder_album}” –filename “{folder_album<em>seq}</em>{original_name}”’. To start counting at a value other than 0, append ‘(starting_value)’ to the field name. For example, to start counting at 1 instead of 0: ‘{folder_album_seq(1)}’ May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use ‘{folder_album_seq:05d}’ which results in 00000, 00001, 00002…etc. To format while also using a starting value: ‘{folder_album_seq:05d(1)}’ which results in 0001, 00002…etc.This may result in incorrect sequences if you have duplicate albums with the same name in the same folder; see also ‘{album_seq}’.</p></td>
 </tr>
-<tr class="row-odd"><td><p>{comma}</p></td>
+<tr class="row-even"><td><p>{comma}</p></td>
 <td><p>A comma: ‘,’</p></td>
 </tr>
-<tr class="row-even"><td><p>{semicolon}</p></td>
+<tr class="row-odd"><td><p>{semicolon}</p></td>
 <td><p>A semicolon: ‘;’</p></td>
 </tr>
-<tr class="row-odd"><td><p>{questionmark}</p></td>
+<tr class="row-even"><td><p>{questionmark}</p></td>
 <td><p>A question mark: ‘?’</p></td>
 </tr>
-<tr class="row-even"><td><p>{pipe}</p></td>
+<tr class="row-odd"><td><p>{pipe}</p></td>
 <td><p>A vertical pipe: ‘|’</p></td>
 </tr>
-<tr class="row-odd"><td><p>{openbrace}</p></td>
+<tr class="row-even"><td><p>{openbrace}</p></td>
 <td><p>An open brace: ‘{’</p></td>
 </tr>
-<tr class="row-even"><td><p>{closebrace}</p></td>
+<tr class="row-odd"><td><p>{closebrace}</p></td>
 <td><p>A close brace: ‘}’</p></td>
 </tr>
-<tr class="row-odd"><td><p>{openparens}</p></td>
+<tr class="row-even"><td><p>{openparens}</p></td>
 <td><p>An open parentheses: ‘(’</p></td>
 </tr>
-<tr class="row-even"><td><p>{closeparens}</p></td>
+<tr class="row-odd"><td><p>{closeparens}</p></td>
 <td><p>A close parentheses: ‘)’</p></td>
 </tr>
-<tr class="row-odd"><td><p>{openbracket}</p></td>
+<tr class="row-even"><td><p>{openbracket}</p></td>
 <td><p>An open bracket: ‘[’</p></td>
 </tr>
-<tr class="row-even"><td><p>{closebracket}</p></td>
+<tr class="row-odd"><td><p>{closebracket}</p></td>
 <td><p>A close bracket: ‘]’</p></td>
 </tr>
-<tr class="row-odd"><td><p>{newline}</p></td>
+<tr class="row-even"><td><p>{newline}</p></td>
 <td><p>A newline: ‘n’</p></td>
 </tr>
-<tr class="row-even"><td><p>{lf}</p></td>
+<tr class="row-odd"><td><p>{lf}</p></td>
 <td><p>A line feed: ‘n’, alias for {newline}</p></td>
 </tr>
-<tr class="row-odd"><td><p>{cr}</p></td>
+<tr class="row-even"><td><p>{cr}</p></td>
 <td><p>A carriage return: ‘r’</p></td>
 </tr>
-<tr class="row-even"><td><p>{crlf}</p></td>
+<tr class="row-odd"><td><p>{crlf}</p></td>
 <td><p>A carriage return + line feed: ‘rn’</p></td>
 </tr>
-<tr class="row-odd"><td><p>{tab}</p></td>
+<tr class="row-even"><td><p>{tab}</p></td>
 <td><dl class="field-list simple">
 <dt class="field-odd">A tab<span class="colon">:</span></dt>
 <dd class="field-odd"><p>‘t’</p>
@@ -607,73 +612,73 @@
 </dl>
 </td>
 </tr>
-<tr class="row-even"><td><p>{osxphotos_version}</p></td>
-<td><p>The osxphotos version, e.g. ‘0.56.2’</p></td>
+<tr class="row-odd"><td><p>{osxphotos_version}</p></td>
+<td><p>The osxphotos version, e.g. ‘0.60.4’</p></td>
 </tr>
-<tr class="row-odd"><td><p>{osxphotos_cmd_line}</p></td>
+<tr class="row-even"><td><p>{osxphotos_cmd_line}</p></td>
 <td><p>The full command line used to run osxphotos</p></td>
 </tr>
-<tr class="row-even"><td><p>{album}</p></td>
+<tr class="row-odd"><td><p>{album}</p></td>
 <td><p>Album(s) photo is contained in</p></td>
 </tr>
-<tr class="row-odd"><td><p>{folder_album}</p></td>
+<tr class="row-even"><td><p>{folder_album}</p></td>
 <td><p>Folder path + album photo is contained in. e.g. ‘Folder/Subfolder/Album’ or just ‘Album’ if no enclosing folder</p></td>
 </tr>
-<tr class="row-even"><td><p>{project}</p></td>
+<tr class="row-odd"><td><p>{project}</p></td>
 <td><p>Project(s) photo is contained in (such as greeting cards, calendars, slideshows)</p></td>
 </tr>
-<tr class="row-odd"><td><p>{album_project}</p></td>
+<tr class="row-even"><td><p>{album_project}</p></td>
 <td><p>Album(s) and project(s) photo is contained in; treats projects as regular albums</p></td>
 </tr>
-<tr class="row-even"><td><p>{folder_album_project}</p></td>
+<tr class="row-odd"><td><p>{folder_album_project}</p></td>
 <td><p>Folder path + album (includes projects as albums) photo is contained in. e.g. ‘Folder/Subfolder/Album’ or just ‘Album’ if no enclosing folder</p></td>
 </tr>
-<tr class="row-odd"><td><p>{keyword}</p></td>
+<tr class="row-even"><td><p>{keyword}</p></td>
 <td><p>Keyword(s) assigned to photo</p></td>
 </tr>
-<tr class="row-even"><td><p>{person}</p></td>
+<tr class="row-odd"><td><p>{person}</p></td>
 <td><p>Person(s) / face(s) in a photo</p></td>
 </tr>
-<tr class="row-odd"><td><p>{label}</p></td>
+<tr class="row-even"><td><p>{label}</p></td>
 <td><p>Image categorization label associated with a photo (Photos 5+ only). Labels are added automatically by Photos using machine learning algorithms to categorize images. These are not the same as {keyword} which refers to the user-defined keywords/tags applied in Photos.</p></td>
 </tr>
-<tr class="row-even"><td><p>{label_normalized}</p></td>
+<tr class="row-odd"><td><p>{label_normalized}</p></td>
 <td><p>All lower case version of ‘label’ (Photos 5+ only)</p></td>
 </tr>
-<tr class="row-odd"><td><p>{comment}</p></td>
+<tr class="row-even"><td><p>{comment}</p></td>
 <td><p>Comment(s) on shared Photos; format is ‘Person name: comment text’ (Photos 5+ only)</p></td>
 </tr>
-<tr class="row-even"><td><p>{exiftool}</p></td>
+<tr class="row-odd"><td><p>{exiftool}</p></td>
 <td><p>Format: ‘{exiftool:GROUP:TAGNAME}’; use exiftool (https://exiftool.org) to extract metadata, in form GROUP:TAGNAME, from image.  E.g. ‘{exiftool:EXIF:Make}’ to get camera make, or {exiftool:IPTC:Keywords} to extract keywords. See https://exiftool.org/TagNames/ for list of valid tag names.  You must specify group (e.g. EXIF, IPTC, etc) as used in <code class="docutils literal notranslate"><span class="pre">exiftool</span> <span class="pre">-G</span></code>. exiftool must be installed in the path to use this template.</p></td>
 </tr>
-<tr class="row-odd"><td><p>{searchinfo.holiday}</p></td>
+<tr class="row-even"><td><p>{searchinfo.holiday}</p></td>
 <td><p>Holiday names associated with a photo, e.g. ‘Christmas Day’; (Photos 5+ only, applied automatically by Photos’ image categorization algorithms).</p></td>
 </tr>
-<tr class="row-even"><td><p>{searchinfo.activity}</p></td>
+<tr class="row-odd"><td><p>{searchinfo.activity}</p></td>
 <td><p>Activities associated with a photo, e.g. ‘Sporting Event’; (Photos 5+ only, applied automatically by Photos’ image categorization algorithms).</p></td>
 </tr>
-<tr class="row-odd"><td><p>{searchinfo.venue}</p></td>
+<tr class="row-even"><td><p>{searchinfo.venue}</p></td>
 <td><p>Venues associated with a photo, e.g. name of restaurant; (Photos 5+ only, applied automatically by Photos’ image categorization algorithms).</p></td>
 </tr>
-<tr class="row-even"><td><p>{searchinfo.venue_type}</p></td>
+<tr class="row-odd"><td><p>{searchinfo.venue_type}</p></td>
 <td><p>Venue types associated with a photo, e.g. ‘Restaurant’; (Photos 5+ only, applied automatically by Photos’ image categorization algorithms).</p></td>
 </tr>
-<tr class="row-odd"><td><p>{photo}</p></td>
+<tr class="row-even"><td><p>{photo}</p></td>
 <td><p>Provides direct access to the PhotoInfo object for the photo. Must be used in format ‘{photo.property}’ where ‘property’ represents a PhotoInfo property. For example: ‘{photo.favorite}’ is the same as ‘{favorite}’ and ‘{photo.place.name}’ is the same as ‘{place.name}’. ‘{photo}’ provides access to properties that are not available as separate template fields but it assumes some knowledge of the underlying PhotoInfo class.  See <a class="reference external" href="https://rhettbull.github.io/osxphotos/">https://rhettbull.github.io/osxphotos/</a> for additional documentation on the PhotoInfo class.</p></td>
 </tr>
-<tr class="row-even"><td><p>{detected_text}</p></td>
+<tr class="row-odd"><td><p>{detected_text}</p></td>
 <td><p>List of text strings found in the image after performing text detection. Using ‘{detected_text}’ will cause osxphotos to perform text detection on your photos using the built-in macOS text detection algorithms which will slow down your export. The results for each photo will be cached in the export database so that future exports with ‘–update’ do not need to reprocess each photo. You may pass a confidence threshold value between 0.0 and 1.0 after a colon as in ‘{detected_text:0.5}’; The default confidence threshold is 0.75. ‘{detected_text}’ works only on macOS Catalina (10.15) or later. Note: this feature is not the same thing as Live Text in macOS Monterey, which osxphotos does not yet support.</p></td>
 </tr>
-<tr class="row-odd"><td><p>{shell_quote}</p></td>
+<tr class="row-even"><td><p>{shell_quote}</p></td>
 <td><p>Use in form ‘{shell_quote,TEMPLATE}’; quotes the rendered TEMPLATE value(s) for safe usage in the shell, e.g. My file.jpeg =&gt; ‘My file.jpeg’; only adds quotes if needed.</p></td>
 </tr>
-<tr class="row-even"><td><p>{strip}</p></td>
+<tr class="row-odd"><td><p>{strip}</p></td>
 <td><p>Use in form ‘{strip,TEMPLATE}’; strips whitespace from begining and end of rendered TEMPLATE value(s).</p></td>
 </tr>
-<tr class="row-odd"><td><p>{format}</p></td>
+<tr class="row-even"><td><p>{format}</p></td>
 <td><p>Use in form, ‘{format:TYPE:FORMAT,TEMPLATE}’; converts TEMPLATE value to TYPE then formats the value using Python string formatting codes specified by FORMAT; TYPE is one of: ‘int’, ‘float’, or ‘str’. For example, ‘{format:float:.1f,{exiftool:EXIF:FocalLength}}’ will format focal length to 1 decimal place (e.g. ‘100.0’).</p></td>
 </tr>
-<tr class="row-even"><td><p>{function}</p></td>
+<tr class="row-odd"><td><p>{function}</p></td>
 <td><p>Execute a python function from an external file and use return value as template substitution. Use in format: {function:file.py::function_name} where ‘file.py’ is the name of the python file and ‘function_name’ is the name of the function to call. The function will be passed the PhotoInfo object for the photo. See https://github.com/RhetTbull/osxphotos/blob/master/examples/template_function.py for an example of how to implement a template function.</p></td>
 </tr>
 </tbody>

docs/tutorial.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="OSXPhotos Command Line Interface (CLI)" href="cli.html" /><link rel="prev" title="OSXPhotos" href="overview.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29"/>
-        <title>OSXPhotos Tutorial - osxphotos 0.56.2 documentation</title>
+        <title>OSXPhotos Tutorial - osxphotos 0.60.4 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -124,7 +124,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">osxphotos 0.56.2 documentation</div></a>
+      <a href="index.html"><div class="brand">osxphotos 0.60.4 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -147,7 +147,7 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
   
   
-  <span class="sidebar-brand-text">osxphotos 0.56.2 documentation</span>
+  <span class="sidebar-brand-text">osxphotos 0.60.4 documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -161,7 +161,7 @@
 <li class="toctree-l1"><a class="reference internal" href="cli.html">OSXPhotos Command Line Interface (CLI)</a></li>
 <li class="toctree-l1"><a class="reference internal" href="template_help.html">OSXPhotos Template System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="package_overview.html">OSXPhotos Python Package Overview</a></li>
-<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">OSXPhotos Python Reference</a></li>
 </ul>
 
 </div>

docsrc/source/reference.rst

@@ -1,5 +1,5 @@
-OSXPhotos python API 
-====================
+OSXPhotos Python Reference
+==========================
 
 .. automodule:: osxphotos
    :members:

docsrc/source/template_help.rst

@@ -58,6 +58,8 @@ Valid filters are:
 * `join(x)`: Join list of values with delimiter x, e.g. join(,): ['a', 'b', 'c'] => 'a,b,c'; the DELIM option functions similar to join(x) but with DELIM, the join happens before being passed to any filters.May optionally be used without an argument, that is 'join()' which joins values together with no delimiter. e.g. join(): ['a', 'b', 'c'] => 'abc'.
 * `append(x)`: Append x to list of values, e.g. append(d): ['a', 'b', 'c'] => ['a', 'b', 'c', 'd'].
 * `prepend(x)`: Prepend x to list of values, e.g. prepend(d): ['a', 'b', 'c'] => ['d', 'a', 'b', 'c'].
+* `appends(x)`: Append s[tring] Append x to each value of list of values, e.g. appends(d): ['a', 'b', 'c'] => ['ad', 'bd', 'cd'].
+* `prepends(x)`: Prepend s[tring] x to each value of list of values, e.g. prepends(d): ['a', 'b', 'c'] => ['da', 'db', 'dc'].
 * `remove(x)`: Remove x from list of values, e.g. remove(b): ['a', 'b', 'c'] => ['a', 'c'].
 * `slice(start:stop:step)`: Slice list using same semantics as Python's list slicing, e.g. slice(1:3): ['a', 'b', 'c', 'd'] => ['b', 'c']; slice(1:4:2): ['a', 'b', 'c', 'd'] => ['b', 'd']; slice(1:): ['a', 'b', 'c', 'd'] => ['b', 'c', 'd']; slice(:-1): ['a', 'b', 'c', 'd'] => ['a', 'b', 'c']; slice(::-1): ['a', 'b', 'c', 'd'] => ['d', 'c', 'b', 'a']. See also sslice().
 * `sslice(start:stop:step)`: [s(tring) slice] Slice values in a list using same semantics as Python's string slicing, e.g. sslice(1:3):'abcd => 'bc'; sslice(1:4:2): 'abcd' => 'bd', etc. See also slice().
@@ -322,6 +324,8 @@ Template Substitutions
      - A shorter representation of photo's internal universally unique identifier (UUID) for the photo, a 22-character string unique to the photo, e.g. 'JYsxugP9UjetmCbBCHXcmu'
    * - {id}
      - A unique number for the photo based on its primary key in the Photos database. A sequential integer, e.g. 1, 2, 3...etc.  Each asset associated with a photo (e.g. an image and Live Photo preview) will share the same id. May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{id:05d}' which results in 00001, 00002, 00003...etc.
+   * - {counter}
+     - A sequential counter, starting at 0, that increments each time it is evaluated.To start counting at a value other than 0, append append '(starting_value)' to the field name.For example, to start counting at 1 instead of 0: '{counter(1)}'.May be formatted using a python string format code.For example, to format as a 5-digit integer and pad with zeros, use '{counter:05d(1)}'which results in 00001, 00002, 00003...etc.You may also specify a stop value which causes the counter to reset to the starting valuewhen the stop value is reached and a step size which causes the counter to increment bythe specified value instead of 1. Use the format '{counter(start,stop,step)}' where start,stop, and step are integers. For example, to count from 1 to 10 by 2, use '{counter(1,11,2)}'.Note that the counter stops counting when the stop value is reached and does not return thestop value. Start, stop, and step are optional and may be omitted. For example, to countfrom 0 by 2s, use '{counter(,,2)}'.You may create an arbitrary number of counters by appending a unique name to the field namepreceded by a period: '{counter.a}', '{counter.b}', etc. Each counter will have its own stateand will start at 0 and increment by 1 unless otherwise specified. Note: {counter} is not suitable for use with 'export' and '--update' as the counter associated with a photo may change between export sessions. See also {id}.
    * - {album_seq}
      - An integer, starting at 0, indicating the photo's index (sequence) in the containing album. Only valid when used in a '--filename' template and only when '{album}' or '{folder_album}' is used in the '--directory' template. For example '--directory "{folder_album}" --filename "{album\ *seq}*\ {original_name}"'. To start counting at a value other than 0, append append '(starting_value)' to the field name.  For example, to start counting at 1 instead of 0: '{album_seq(1)}'. May be formatted using a python string format code. For example, to format as a 5-digit integer and pad with zeros, use '{album_seq:05d}' which results in 00000, 00001, 00002...etc. To format while also using a starting value: '{album_seq:05d(1)}' which results in 0001, 00002...etc.This may result in incorrect sequences if you have duplicate albums with the same name; see also '{folder_album_seq}'.
    * - {folder_album_seq}
@@ -357,7 +361,7 @@ Template Substitutions
    * - {tab}
      - :A tab: '\t'
    * - {osxphotos_version}
-     - The osxphotos version, e.g. '0.56.2'
+     - The osxphotos version, e.g. '0.60.4'
    * - {osxphotos_cmd_line}
      - The full command line used to run osxphotos
    * - {album}

examples/batch_edit.py

@@ -0,0 +1,327 @@
+"""
+Batch edit currently selected photo metadata using osxphotos.
+
+Run this with `osxphotos run batch_edit.py` or `osxphotos run batch_edit.py --help` for more information.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import sys
+
+import click
+import photoscript
+
+import osxphotos
+from osxphotos.cli import echo, echo_error, kvstore, selection_command, verbose
+from osxphotos.cli.param_types import TemplateString
+from osxphotos.phototemplate import RenderOptions
+from osxphotos.sqlitekvstore import SQLiteKVStore
+
+
+class Latitude(click.ParamType):
+
+    name = "Latitude"
+
+    def convert(self, value, param, ctx):
+        try:
+            latitude = float(value)
+            if latitude < -90 or latitude > 90:
+                raise ValueError
+            return latitude
+        except Exception:
+            self.fail(
+                f"Invalid latitude {value}. Must be a floating point number between -90 and 90."
+            )
+
+
+class Longitude(click.ParamType):
+
+    name = "Longitude"
+
+    def convert(self, value, param, ctx):
+        try:
+            longitude = float(value)
+            if longitude < -180 or longitude > 180:
+                raise ValueError
+            return longitude
+        except Exception:
+            self.fail(
+                f"Invalid longitude {value}. Must be a floating point number between -180 and 180."
+            )
+
+
+@selection_command(name="batch-edit")
+@click.option(
+    "--title",
+    metavar="TITLE_TEMPLATE",
+    type=TemplateString(),
+    help="Set title of photo.",
+)
+@click.option(
+    "--description",
+    metavar="DESCRIPTION_TEMPLATE",
+    type=TemplateString(),
+    help="Set description of photo.",
+)
+@click.option(
+    "--keyword",
+    metavar="KEYWORD_TEMPLATE",
+    type=TemplateString(),
+    multiple=True,
+    help="Set keywords of photo. May be specified multiple times.",
+)
+@click.option(
+    "--location",
+    metavar="LATITUDE LONGITUDE",
+    type=click.Tuple([Latitude(), Longitude()]),
+    help="Set location of photo. "
+    "Must be specified as a pair of numbers with latitude in the range -90 to 90 and longitude in the range -180 to 180.",
+)
+@click.option("--dry-run", is_flag=True, help="Don't actually change anything.")
+@click.option(
+    "--undo",
+    is_flag=True,
+    help="Restores photo metadata to what it was prior to the last batch edit. "
+    "May be combined with --dry-run.",
+)
+def batch_edit(
+    photos: list[osxphotos.PhotoInfo],
+    title,
+    description,
+    keyword,
+    location,
+    dry_run,
+    undo,
+    **kwargs,
+):
+    """
+    Batch edit photo metadata such as title, description, keywords, etc.
+    Operates on currently selected photos.
+
+    Select one or more photos in Photos then run this command to edit the metadata.
+
+    For example:
+
+    \b
+        osxphotos run batch_edit.py \\
+        --verbose \\
+        --title "California vacation 2023 {created.year}-{created.dd}-{created.mm} {counter:03d}" \\
+        --description "{place.name}" \\ 
+        --keyword "Family" --keyword "Travel" --keyword "{keyword}"
+
+    This will set the title to "California vacation 2023 2023-02-20 001", and so on,
+    the description to the reverse geolocation place name, 
+    and the keywords to "Family", "Travel", and any existing keywords of the photo.
+
+    --title, --description, and --keyword may be any valid template string.
+    See https://rhettbull.github.io/osxphotos/template_help.html for more information
+    on the osxphotos template system.
+    """
+
+    if not title and not description and not keyword and not location and not undo:
+        echo_error(
+            "[error] Must specify at least one of: "
+            " --title, --description, --keyword, --location, --undo. "
+            "Use --help for more information."
+        )
+        sys.exit(1)
+
+    if undo and (title or description or keyword or location):
+        echo_error(
+            "[error] Cannot specify --undo and any options other than --dry-run. "
+            "Use --help for more information."
+        )
+        sys.exit(1)
+
+    if not photos:
+        echo_error("[error] No photos selected")
+        sys.exit(1)
+
+    # sort photos by date so that {counter} order is correct
+    photos.sort(key=lambda p: p.date)
+
+    undo_store = kvstore("batch_edit")
+    verbose(f"Undo database stored in [filepath]{undo_store.path}", level=2)
+
+    echo(f"Processing [num]{len(photos)}[/] photos...")
+    for photo in photos:
+        verbose(
+            f"Processing [filename]{photo.original_filename}[/] ([uuid]{photo.uuid}[/])"
+        )
+        if undo:
+            undo_photo_edits(photo, undo_store, dry_run)
+            continue
+        save_photo_undo_info(undo_store, photo)
+        set_photo_title_from_template(photo, title, dry_run)
+        set_photo_description_from_template(photo, description, dry_run)
+        set_photo_keywords_from_template(photo, keyword, dry_run)
+        set_photo_location(photo, location, dry_run)
+
+
+# cache photoscript Photo object to avoid re-creating it for each photo
+# maxsize=1 as this function is called repeatedly for each photo then
+# the next photo is processed
+@functools.lru_cache(maxsize=1)
+def photoscript_photo(photo: osxphotos.PhotoInfo) -> photoscript.Photo:
+    """Return photoscript Photo object for photo"""
+    return photoscript.Photo(photo.uuid)
+
+
+def save_photo_undo_info(undo_store: SQLiteKVStore, photo: osxphotos.PhotoInfo):
+    """Save undo information to undo store"""
+    undo_store[photo.uuid] = photo.json()
+
+
+def undo_photo_edits(
+    photo: osxphotos.PhotoInfo, undo_store: SQLiteKVStore, dry_run: bool
+):
+    """Undo edits for photo"""
+    if not (undo_info := undo_store.get(photo.uuid)):
+        verbose(
+            f"[warning] No undo information for photo [filename]{photo.original_filename}[/] ([uuid]{photo.uuid}[/])"
+        )
+        return
+    undo_info = json.loads(undo_info)
+    ps_photo = photoscript_photo(photo)
+    exiting_title, exiting_description, exiting_keywords, exiting_location = (
+        photo.title,
+        photo.description,
+        sorted(photo.keywords),
+        photo.location,
+    )
+    previous_title, previous_description, previous_keywords, previous_location = (
+        undo_info.get("title"),
+        undo_info.get("description"),
+        sorted(undo_info.get("keywords")),
+        (undo_info.get("latitude"), undo_info.get("longitude")),
+    )
+    verbose(
+        f"Undoing edits for [filename]{photo.original_filename}[/] ([uuid]{photo.uuid}[/])"
+    )
+    for name, existing, previous in (
+        ("title", exiting_title, previous_title),
+        ("description", exiting_description, previous_description),
+        ("keywords", exiting_keywords, previous_keywords),
+        ("location", exiting_location, previous_location),
+    ):
+        if existing != previous:
+            verbose(
+                f"  [i]{name}[/]: [change]{existing}[/] -> [no_change]{previous}[/]"
+            )
+            if not dry_run:
+                setattr(ps_photo, name, previous)
+        else:
+            verbose(f"  [i]{name} (no change)[/]: [no_change]{existing}[/]", level=2)
+
+
+def set_photo_title_from_template(
+    photo: osxphotos.PhotoInfo, title_template: str, dry_run: bool
+):
+    """Set photo title from template"""
+    if not title_template:
+        return
+
+    # don't render None values
+    render_options = RenderOptions(none_str="")
+
+    title_string, _ = photo.render_template(title_template, render_options)
+    title_string = [ts for ts in title_string if ts]
+    if not title_string:
+        verbose(
+            f"No title returned from template, nothing to do: [bold]{title_template}"
+        )
+        return
+
+    if len(title_string) > 1:
+        echo_error(
+            f"[error] Title template must return a single string: [bold]{title_string}"
+        )
+        sys.exit(1)
+
+    verbose(f"Setting [i]title[/i] to [bold]{title_string[0]}")
+    if not dry_run:
+        ps_photo = photoscript_photo(photo)
+        ps_photo.title = title_string[0]
+
+
+def set_photo_description_from_template(
+    photo: osxphotos.PhotoInfo, description_template: str, dry_run: bool
+):
+    """Set photo description from template"""
+    if not description_template:
+        return
+
+    # don't render None values
+    render_options = RenderOptions(none_str="")
+
+    description_string, _ = photo.render_template(description_template, render_options)
+    description_string = [ds for ds in description_string if ds]
+    if not description_string:
+        verbose(
+            f"No description returned from template, nothing to do: [bold]{description_template}"
+        )
+        return
+
+    if len(description_string) > 1:
+        echo_error(
+            f"[error] Description template must return a single string: [bold]{description_string}"
+        )
+        sys.exit(1)
+
+    verbose(f"Setting [i]description[/] to [bold]{description_string[0]}")
+    if not dry_run:
+        ps_photo = photoscript_photo(photo)
+        ps_photo.description = description_string[0]
+
+
+def set_photo_keywords_from_template(
+    photo: osxphotos.PhotoInfo, keyword_template: list[str], dry_run: bool
+):
+    """Set photo keywords from template"""
+    if not keyword_template:
+        return
+
+    # don't render None values
+    render_options = RenderOptions(none_str="")
+
+    keywords = set()
+    for kw in keyword_template:
+        kw_string, _ = photo.render_template(kw, render_options)
+        if kw_string:
+            # filter out empty strings
+            keywords.update([k for k in kw_string if k])
+
+    if not keywords:
+        verbose(
+            f"No keywords returned from template, nothing to do: [bold]{keyword_template}"
+        )
+        return
+
+    verbose(
+        f"Setting [i]keywords[/] to {', '.join(f'[bold]{kw}[/]' for kw in keywords)}"
+    )
+    if not dry_run:
+        ps_photo = photoscript_photo(photo)
+        ps_photo.keywords = list(keywords)
+
+
+def set_photo_location(
+    photo: osxphotos.PhotoInfo, location: tuple[float, float], dry_run: bool
+):
+    """Set photo location"""
+    if not location or location[0] is None or location[1] is None:
+        return
+
+    latitude, longitude = location
+    verbose(
+        f"Setting [i]location[/] to [num]{latitude:.6f}[/], [num]{longitude:.6f}[/]"
+    )
+    if not dry_run:
+        ps_photo = photoscript_photo(photo)
+        ps_photo.location = (latitude, longitude)
+
+
+if __name__ == "__main__":
+    batch_edit()

examples/cli_example_1.py

@@ -0,0 +1,67 @@
+"""Sample query command for osxphotos
+
+This shows how simple it is to create a command line tool using osxphotos to process your photos.
+
+Using the @query_command decorator turns your function to a full-fledged command line app that
+can be run via `osxphotos run cli_example_1.py` or `python cli_example_1.py` if you have pip installed osxphotos.
+
+Using this decorator makes it very easy to create a quick command line tool that can operate on
+a subset of your photos. Additionally, writing a command in this way makes it easy to later
+incorporate the command into osxphotos as a full-fledged command.
+
+The decorator will add all the query options available in `osxphotos query` as command line options
+as well as the following options:
+--verbose
+--timestamp
+--theme
+--db
+--debug (hidden, won't show in help)
+
+The decorated function will perform the query and pass the list of filtered PhotoInfo objects
+to your function.  You can then do whatever you want with the photos.
+
+For example, to run the command on only selected photos:
+
+    osxphotos run cli_example_1.py --selected
+
+To run the command on all photos with the keyword "foo":
+
+    osxphotos run cli_example_1.py --keyword foo
+
+For more advanced example, see `cli_example_2.py`
+"""
+
+from __future__ import annotations
+
+import osxphotos
+from osxphotos.cli import query_command, verbose
+
+
+@query_command
+def example(photos: list[osxphotos.PhotoInfo], **kwargs):
+    """Sample query command for osxphotos. Prints out the filename and date of each photo.
+
+    Whatever text you put in the function's docstring here, will be used as the command's
+    help text when run via `osxphotos run cli_example_1.py --help` or `python cli_example_1.py --help`
+    """
+
+    # verbose() will print to stdout if --verbose option is set
+    # you can optionally provide a level (default is 1) to print only if --verbose is set to that level
+    # for example: -VV or --verbose --verbose == level 2
+    verbose(f"Found {len(photos)} photo(s)")
+    verbose("This message will only be printed if verbose level 2 is set", level=2)
+
+    # do something with photos here
+    for photo in photos:
+        # photos is a list of PhotoInfo objects
+        # see: https://rhettbull.github.io/osxphotos/reference.html#osxphotos.PhotoInfo
+        verbose(f"Processing {photo.original_filename}")
+        print(f"{photo.original_filename} {photo.date}")
+        ...
+
+
+if __name__ == "__main__":
+    # call your function here
+    # you do not need to pass any arguments to the function
+    # as the decorator will handle parsing the command line arguments
+    example()

examples/cli_example_2.py

@@ -0,0 +1,160 @@
+"""Sample query command for osxphotos
+
+This shows how simple it is to create a command line tool using osxphotos to process your photos.
+
+Using the @query_command decorator turns your function to a full-fledged command line app that
+can be run via `osxphotos run cli_example_2.py` or `python cli_example_2.py` if you have pip installed osxphotos.
+
+Using this decorator makes it very easy to create a quick command line tool that can operate on
+a subset of your photos. Additionally, writing a command in this way makes it easy to later
+incorporate the command into osxphotos as a full-fledged command.
+
+The decorator will add all the query options available in `osxphotos query` as command line options
+as well as the following options:
+--verbose
+--timestamp
+--theme
+--db
+--debug (hidden, won't show in help)
+
+The decorated function will perform the query and pass the list of filtered PhotoInfo objects
+to your function.  You can then do whatever you want with the photos.
+
+For example, to run the command on only selected photos:
+
+    osxphotos run cli_example_2.py --selected
+
+To run the command on all photos with the keyword "foo":
+
+    osxphotos run cli_example_2.py --keyword foo
+
+The following helper functions may be useful and can be imported from osxphotos.cli:
+
+    abort(message: str, exit_code: int = 1)
+        Abort with error message and exit code
+    echo(message: str)
+        Print message to stdout using rich formatting
+    echo_error(message: str)
+        Print message to stderr using rich formatting
+    logger: logging.Logger
+        Python logger for osxphotos; for example, logger.debug("debug message")
+    verbose(*args, level: int = 1)
+        Print args to stdout if --verbose option is set
+    query_command: decorator to create an osxphotos query command
+    kvstore(name: str) -> SQLiteKVStore useful for storing state between runs
+
+The verbose, echo, and echo_error functions use rich formatting to print messages to stdout and stderr.
+See https://github.com/Textualize/rich for more information on rich formatting.
+
+In addition to standard rich formatting styles, the following styles will be defined
+(and can be changed using --theme):
+
+    [change]: something change
+    [no_change]: indicate no change
+    [count]: a count
+    [error]: an error
+    [filename]: a filename
+    [filepath]: a filepath
+    [num]: a number
+    [time]: a time or date
+    [tz]: a timezone
+    [warning]: a warning
+    [uuid]: a uuid
+
+The tags should be closed with [/] to end the style.  For example:
+
+    echo("[filename]foo[/] [time]bar[/]")
+
+For simpler examples, see `cli_example_1.py`
+"""
+
+from __future__ import annotations
+
+import datetime
+
+import click
+
+import osxphotos
+from osxphotos.cli import (
+    abort,
+    echo,
+    echo_error,
+    kvstore,
+    logger,
+    query_command,
+    verbose,
+)
+
+
+@query_command()
+@click.option(
+    "--resume",
+    is_flag=True,
+    help="Resume processing from last run, do not reprocess photos",
+)
+@click.option(
+    "--dry-run", is_flag=True, help="Do a dry run, don't actually do anything"
+)
+def example(resume, dry_run, photos: list[osxphotos.PhotoInfo], **kwargs):
+    """Sample query command for osxphotos. Prints out the filename and date of each photo.
+
+    Whatever text you put in the function's docstring here, will be used as the command's
+    help text when run via `osxphotos run cli_example_2.py --help` or `python cli_example_2.py --help`
+
+    The @query_command decorator returns a click.command so you can add additional options
+    using standard click decorators.  For example, the --resume and --dry-run options.
+    For more information on click, see https://palletsprojects.com/p/click/.
+    """
+
+    # abort will print the message to stderr and exit with the given exit code
+    if not photos:
+        abort("Nothing to do!", 1)
+
+    # verbose() will print to stdout if --verbose option is set
+    # you can optionally provide a level (default is 1) to print only if --verbose is set to that level
+    # for example: -VV or --verbose --verbose == level 2
+    verbose(f"Found [count]{len(photos)}[/] photos")
+    verbose("This message will only be printed if verbose level 2 is set", level=2)
+
+    # the logger is a python logging.Logger object
+    # debug messages will only be printed if --debug option is set
+    logger.debug(f"{kwargs=}")
+
+    # kvstore() returns a SQLiteKVStore object for storing state between runs
+    # this is basically a persistent dictionary that can be used to store state
+    # see https://github.com/RhetTbull/sqlitekvstore for more information
+    kv = kvstore("cli_example_2")
+    verbose(f"Using key-value cache: {kv.path}")
+
+    # do something with photos here
+    for photo in photos:
+        # photos is a list of PhotoInfo objects
+        # see: https://rhettbull.github.io/osxphotos/reference.html#osxphotos.PhotoInfo
+        if resume and photo.uuid in kv:
+            echo(
+                f"Skipping processed photo [filename]{photo.original_filename}[/] ([uuid]{photo.uuid}[/])"
+            )
+            continue
+
+        # store the uuid and current time in the kvstore
+        # the key and value must be a type supported by SQLite: int, float, str, bytes, bool, None
+        # if you need to store other values, you should serialize them to a string or bytes first
+        # for example, using json.dumps() or pickle.dumps()
+        kv[photo.uuid] = datetime.datetime.now().isoformat()
+        echo(f"Processing [filename]{photo.original_filename}[/] [time]{photo.date}[/]")
+        if not dry_run:
+            # do something with the photo here
+            echo(f"Doing something with [filename]{photo.original_filename}[/]")
+
+    # echo_error will print to stderr
+    # if you add [warning] or [error], it will be formatted accordingly
+    # and include an emoji to make the message stand out
+    echo_error("[warning]This is a warning message!")
+    echo_error("[error]This is an error message!")
+
+
+if __name__ == "__main__":
+    # call your function here
+    # you do not need to pass any arguments to the function
+    # as the decorator will handle parsing the command line arguments
+    example()

examples/cli_example_3.py

@@ -0,0 +1,60 @@
+"""Sample query command for osxphotos
+
+This shows how simple it is to create a command line tool using osxphotos to process your photos.
+
+Using the @selection_command decorator turns your function to a full-fledged command line app that
+can be run via `osxphotos run cli_example_1.py` or `python cli_example_1.py` if you have pip installed osxphotos.
+
+Using this decorator makes it very easy to create a quick command line tool that can operate on
+a subset of your photos. Additionally, writing a command in this way makes it easy to later
+incorporate the command into osxphotos as a full-fledged command.
+
+The decorator will add the following options to your command:
+--verbose
+--timestamp
+--theme
+--db
+--debug (hidden, won't show in help)
+
+The decorated function will get the selected photos and pass the list of PhotoInfo objects
+to your function.  You can then do whatever you want with the photos.
+"""
+
+from __future__ import annotations
+
+import osxphotos
+from osxphotos.cli import (
+    selection_command,
+    verbose,
+)
+
+
+@selection_command
+def example(photos: list[osxphotos.PhotoInfo], **kwargs):
+    """Sample command for osxphotos. Prints out the filename and date of each photo
+    currently selected in Photos.app.
+
+    Whatever text you put in the function's docstring here, will be used as the command's
+    help text when run via `osxphotos run cli_example_1.py --help` or `python cli_example_1.py --help`
+    """
+
+    # verbose() will print to stdout if --verbose option is set
+    # you can optionally provide a level (default is 1) to print only if --verbose is set to that level
+    # for example: -VV or --verbose --verbose == level 2
+    verbose(f"Found {len(photos)} photo(s)")
+    verbose("This message will only be printed if verbose level 2 is set", level=2)
+
+    # do something with photos here
+    for photo in photos:
+        # photos is a list of PhotoInfo objects
+        # see: https://rhettbull.github.io/osxphotos/reference.html#osxphotos.PhotoInfo
+        verbose(f"Processing {photo.original_filename}")
+        print(f"{photo.original_filename} {photo.date}")
+        ...
+
+
+if __name__ == "__main__":
+    # call your function here
+    # you do not need to pass any arguments to the function
+    # as the decorator will handle parsing the command line arguments
+    example()

examples/concurrent_export.py

@@ -0,0 +1,52 @@
+"""Example for concurrent export of photos using osxphotos.PhotoExporter.export()
+
+Note: concurrent export can only be used on Python 3.11 and later due to the way
+python's sqlite3 module is implemented. See https://docs.python.org/3/library/sqlite3.html#sqlite3.threadsafety
+for more information.
+"""
+
+import concurrent.futures
+import os
+import time
+
+import click
+
+import osxphotos
+from osxphotos.cli import echo, query_command, verbose
+
+
+@query_command()
+@click.option(
+    "--workers",
+    metavar="WORKERS",
+    help="Maximum number of worker threads to use for export. "
+    "If not specified, it will default to the number of processors on the machine, multiplied by 5.",
+    type=int,
+)
+@click.argument(
+    "export_dir",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, writable=True),
+)
+def export(workers, export_dir, photos: list[osxphotos.PhotoInfo], **kwargs):
+    """Export photos to EXPORT_DIR using concurrent export.
+    Use --workers to specify the number of worker threads to use.
+
+    This simple example exports only the original photo and does not export
+    edited versions, live photos, etc.
+    """
+    workers = workers or os.cpu_count() * 5
+    echo(f"Exporting {len(photos)} photos to {export_dir} using {workers} workers")
+    start_t = time.perf_counter()
+    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as executor:
+        futures = [executor.submit(p.export, export_dir) for p in photos]
+        exported = []
+        for future in concurrent.futures.as_completed(futures):
+            exported.extend(future.result())
+    end_t = time.perf_counter()
+    echo(
+        f"Exported {len(exported)} photos to {export_dir} in {end_t-start_t:.4f} seconds"
+    )
+
+
+if __name__ == "__main__":
+    export()

examples/export_previews.py

@@ -0,0 +1,126 @@
+""" Export previews for photos in the Photos library
+
+To run this with osxphotos on currently selected photos:
+
+    osxphotos run export_previews.py --selected export_path
+"""
+
+from __future__ import annotations
+
+import pathlib
+import shutil
+
+import click
+
+import osxphotos
+from osxphotos.cli import echo, echo_error, query_command, verbose
+from osxphotos.cli.export import get_dirnames_from_template, get_filenames_from_template
+from osxphotos.cli.param_types import TemplateString
+from osxphotos.utils import pluralize
+
+
+@query_command
+@click.option("--dry-run", is_flag=True, help="Dry run, don't actually export")
+@click.option(
+    "--directory",
+    type=TemplateString(),
+    help="Directory to export to under export_path. This is an osxphotos template string. "
+    "For example, to export previews to directories based on creation date: "
+    "--directory '{created.year}/{created.mm}/{created.dd}' ",
+)
+@click.option(
+    "--filename",
+    "filename_template",
+    type=TemplateString(),
+    help="Filename for exported preview. "
+    "This is an osxphotos template string; "
+    "for example, to export previews to filename based on creation date: "
+    "--filename '{original_name}-{created.year}-{created.mm}-{created.dd}' ",
+)
+@click.argument(
+    "export_dir", type=click.Path(exists=True, file_okay=False, dir_okay=True)
+)
+def export_previews(
+    photos: list[osxphotos.PhotoInfo],
+    dry_run: bool,
+    directory: str,
+    filename_template: str,
+    export_dir: str,
+    **kwargs,
+):
+    """Export previews for photos in the Photos library.
+
+    Pass one or more query options to select photos to export or use without query options
+    to export all images.
+
+    If --directory is passed, the previews will be exported to subdirectories under export_path
+    based on the template string passed to --directory. For example, to export previews to
+    directories based on creation date: --directory '{created.year}/{created.mm}/{created.dd}'
+
+    If --filename is passed, the previews will be exported with the filename specified by the
+    template string passed to --filename. For example, to export previews to filename based on
+    creation date: --filename '{original_name}-{created.year}-{created.mm}-{created.dd}'
+
+    If --dry-run is passed, the previews will not actually be exported but the export will be
+    simulated and the export paths printed to stdout.
+    """
+
+    verbose(f"Found {len(photos)} photo(s)")
+    count = 0
+    for photo in photos:
+        try:
+            # first derivative is the largest preview, so use that one
+            preview = pathlib.Path(photo.path_derivatives[0])
+        except IndexError:
+            echo(f"No preview for {photo.original_filename} ({photo.uuid})")
+            continue
+
+        verbose(f"Found preview for {photo.original_filename}: {preview}")
+        count += export_preview_to_directory_with_filename(
+            photo, preview, export_dir, directory, filename_template, dry_run
+        )
+    echo(f"Exported {count} preview {pluralize(count, 'image', 'images')}")
+
+
+def export_preview_to_directory_with_filename(
+    photo: osxphotos.PhotoInfo,
+    preview_path: pathlib.Path,
+    export_dir: str,
+    directory: str,
+    filename_template: str,
+    dry_run: bool,
+) -> int:
+    """Export preview for photo to directory with filename; returns count of images exported"""
+    count = 0
+    for dirname in get_dirnames_from_template(
+        photo=photo,
+        directory=directory,
+        export_by_date=False,
+        dest=export_dir,
+        dry_run=dry_run,
+    ):
+        for filename in get_filenames_from_template(
+            photo=photo,
+            filename_template=filename_template,
+            export_dir=export_dir,
+            dest_path=dirname,
+            original_name=True,
+        ):
+            # need to change filename extension to match preview
+            filename = pathlib.Path(filename).with_suffix(preview_path.suffix)
+            dest_path = pathlib.Path(dirname) / filename
+            echo(
+                f"Exporting preview for {photo.original_filename} ({photo.uuid}) to {dest_path}"
+            )
+            if not dry_run:
+                try:
+                    shutil.copy(preview_path, dest_path)
+                except Exception as e:
+                    echo_error(f"Error exporting preview: {e}")
+                    continue
+            count += 1
+    return count
+
+
+if __name__ == "__main__":
+    export_previews()

examples/post_function_import.py

@@ -3,9 +3,15 @@
 import typing as t
 import photoscript
 import pathlib
+from osxphotos.cli.import_cli import ReportRecord
+
 
 def post_function(
-    photo: photoscript.Photo, filepath: pathlib.Path, verbose: t.Callable, **kwargs
+    photo: photoscript.Photo,
+    filepath: pathlib.Path,
+    verbose: t.Callable,
+    report_record: ReportRecord,
+    **kwargs,
 ):
     """Call this with osxphotos import /file/to/import --post-function post_function.py::post_function
         This will get called immediately after the photo has been imported into Photos
@@ -15,6 +21,7 @@ def post_function(
         photo: photoscript.Photo instance for the photo that's just been imported
         filepath: pathlib.Path to the file that was imported (this is the path to the source file, not the path inside the Photos library)
         verbose: A function to print verbose output if --verbose is set; if --verbose is not set, acts as a no-op (nothing gets printed)
+        report_record: ReportRecord instance for the photo that's just been imported; update this if you want to change the report output
         **kwargs: reserved for future use; recommend you include **kwargs so your function still works if additional arguments are added in future versions
 
     Notes:
@@ -25,4 +32,16 @@ def post_function(
 
     # add a note to the photo's description
     verbose("Adding note to description")
-    photo.description = f"{photo.description} (imported with osxphotos)"
+    description = photo.description
+    description = (
+        f"{description} (imported with osxphotos)"
+        if description
+        else "(imported with osxphotos)"
+    )
+
+    # update report_record if you modify the photo and want the report to reflect the change
+    # the report_record object passed to the function is mutable so you can update it directly
+    report_record.description = description
+
+    # update the photo's description via the Photo object
+    photo.description = description

osxphotos/__init__.py

@@ -1,3 +1,7 @@
+"""__init__.py for osxphotos"""
+
+from __future__ import annotations
+
 import logging
 
 from ._constants import AlbumSortOrder
@@ -12,16 +16,25 @@ from .momentinfo import MomentInfo
 from .personinfo import PersonInfo
 from .photoexporter import ExportOptions, ExportResults, PhotoExporter
 from .photoinfo import PhotoInfo
-from .photosalbum import PhotosAlbum, PhotosAlbumPhotoScript
 from .photosdb import PhotosDB
 from .photosdb._photosdb_process_comments import CommentInfo, LikeInfo
+from .phototables import PhotoTables
 from .phototemplate import PhotoTemplate
 from .placeinfo import PlaceInfo
 from .queryoptions import QueryOptions
 from .scoreinfo import ScoreInfo
 from .searchinfo import SearchInfo
-from .utils import _get_logger
+from .utils import is_macos
 
+if is_macos:
+    from .photosalbum import PhotosAlbum, PhotosAlbumPhotoScript
+
+# configure logging; every module in osxphotos should use this logger
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(filename)s - %(lineno)d - %(message)s",
+)
+logger: logging.Logger = logging.getLogger("osxphotos")
 if not is_debug():
     logging.disable(logging.DEBUG)
 
@@ -37,12 +50,14 @@ __all__ = [
     "ExportResults",
     "FileUtil",
     "FileUtilNoOp",
+    "FolderInfo",
     "ImportInfo",
     "LikeInfo",
     "MomentInfo",
     "PersonInfo",
     "PhotoExporter",
     "PhotoInfo",
+    "PhotoTables",
     "PhotoTemplate",
     "PhotosAlbum",
     "PhotosAlbumPhotoScript",
@@ -53,8 +68,7 @@ __all__ = [
     "ScoreInfo",
     "SearchInfo",
     "__version__",
-    "_get_logger",
     "is_debug",
+    "logger",
     "set_debug",
-    "FolderInfo",
 ]

osxphotos/_constants.py

@@ -1,11 +1,15 @@
-"""
-Constants used by osxphotos 
-"""
+""" Constants used by osxphotos """
 
+from __future__ import annotations
+
+import logging
 import os.path
+import sqlite3
 from datetime import datetime
 from enum import Enum
 
+logger: logging.Logger = logging.getLogger("osxphotos")
+
 APP_NAME = "osxphotos"
 
 OSXPHOTOS_URL = "https://github.com/RhetTbull/osxphotos"
@@ -123,6 +127,9 @@ _TESTED_OS_VERSIONS = [
     ("12", "6"),
     ("13", "0"),
     ("13", "1"),
+    ("13", "2"),
+    ("13", "3"),
+    ("13", "4"),
 ]
 
 # Photos 5 has persons who are empty string if unidentified face
@@ -138,7 +145,9 @@ _PHOTOS_5_SHARED_PHOTO_PATH = "resources/cloudsharing/data"
 _PHOTOS_8_SHARED_PHOTO_PATH = "scopes/cloudsharing/data"
 
 # Where are shared iCloud derivatives located?
-_PHOTOS_5_SHARED_DERIVATIVE_PATH = "resources/cloudsharing/resources/derivatives/masters"
+_PHOTOS_5_SHARED_DERIVATIVE_PATH = (
+    "resources/cloudsharing/resources/derivatives/masters"
+)
 _PHOTOS_8_SHARED_DERIVATIVE_PATH = "scopes/cloudsharing/resources/derivatives/masters"
 
 # What type of file? Based on ZGENERICASSET.ZKIND in Photos 5 database
@@ -178,6 +187,9 @@ _MAX_IPTC_KEYWORD_LEN = 64
 # If anyone has a keyword matching this, then too bad...
 _OSXPHOTOS_NONE_SENTINEL = "OSXPhotosXYZZY42_Sentinel$"
 
+# Lock file extension for reserving filenames when exporting
+_OSXPHOTOS_LOCK_EXTENSION = ".osxphotos.lock"
+
 
 class SearchCategory:
     """SearchInfo categories for Photos 5+; corresponds to categories in database/search/psi.sqlite:groups.category
@@ -213,11 +225,11 @@ class SearchCategory:
     TITLE = 2017
     DESCRIPTION = 2018
     HOME = 2020
+    WORK = 2036
     PERSON = 2021
     ACTIVITY = 2027
     HOLIDAY = 2029
     SEASON = 2030
-    WORK = 2036
     VENUE = 2038
     VENUE_TYPE = 2039
     PHOTO_TYPE_VIDEO = 2044
@@ -230,6 +242,7 @@ class SearchCategory:
     PHOTO_TYPE_PORTRAIT = 2053
     PHOTO_TYPE_SELFIES = 2054
     PHOTO_TYPE_FAVORITES = 2055
+    PHOTO_TYPE_ANIMATED = None  # Photos 8+ only
     MEDIA_TYPES = [
         PHOTO_TYPE_VIDEO,
         PHOTO_TYPE_SLOMO,
@@ -244,7 +257,23 @@ class SearchCategory:
     ]
     PHOTO_NAME = 2056
     CAMERA = None  # Photos 8+ only
+    TEXT_FOUND = None  # Photos 8+ only
     DETECTED_TEXT = None  # Photos 8+ only
+    SOURCE = None  # Photos 8+ only
+
+    @classmethod
+    def categories(cls) -> dict[int, str]:
+        """Return categories as dict of value: name"""
+        # a bit of a hack to basically reverse the enum
+        return {
+            value: name
+            for name, value in cls.__dict__.items()
+            if name is not None
+            and not name.startswith("__")
+            and not callable(name)
+            and name.isupper()
+            and not isinstance(value, (list, dict, tuple))
+        }
 
 
 class SearchCategory_Photos8(SearchCategory):
@@ -252,6 +281,20 @@ class SearchCategory_Photos8(SearchCategory):
 
     # Many of the category values changed in Ventura / Photos 8
     # and some new categories were added
+    CITY = 5
+    LOCALITY_4 = 4
+    SUB_LOCALITY_5 = None
+    SUB_LOCALITY_6 = 6
+    LOCALITY_8 = 8
+    NAMED_AREA = 7
+    ALL_LOCALITY = [
+        LOCALITY_4,
+        SUB_LOCALITY_6,
+        LOCALITY_8,
+        NAMED_AREA,
+    ]
+    HOME = 1000
+    WORK = 1001
     LABEL = 1500
     MONTH = 1100
     YEAR = 1101
@@ -261,11 +304,55 @@ class SearchCategory_Photos8(SearchCategory):
     TITLE = 1201
     DESCRIPTION = 1202
     DETECTED_TEXT = 1203  # new in Photos 8
+    TEXT_FOUND = 1205  # new in Photos 8
     PERSON = 1300
     ACTIVITY = 1600
+    VENUE = 1700
+    VENUE_TYPE = 1701
+    PHOTO_TYPE_VIDEO = 1901
+    PHOTO_TYPE_SELFIES = 1915
+    PHOTO_TYPE_LIVE = 1906
+    PHOTO_TYPE_PORTRAIT = 1914
     PHOTO_TYPE_FAVORITES = 2000
+    PHOTO_TYPE_PANORAMA = 1908
+    PHOTO_TYPE_TIMELAPSE = 1909
+    PHOTO_TYPE_SLOMO = 1905
+    PHOTO_TYPE_BURSTS = 1913
+    PHOTO_TYPE_SCREENSHOT = 1907
+    PHOTO_TYPE_ANIMATED = 1912
+    PHOTO_TYPE_RAW = 1902
+    MEDIA_TYPES = [
+        PHOTO_TYPE_VIDEO,
+        PHOTO_TYPE_SLOMO,
+        PHOTO_TYPE_LIVE,
+        PHOTO_TYPE_SCREENSHOT,
+        PHOTO_TYPE_PANORAMA,
+        PHOTO_TYPE_TIMELAPSE,
+        PHOTO_TYPE_BURSTS,
+        PHOTO_TYPE_PORTRAIT,
+        PHOTO_TYPE_SELFIES,
+        PHOTO_TYPE_FAVORITES,
+        PHOTO_TYPE_ANIMATED,
+    ]
     PHOTO_NAME = 2100
     CAMERA = 2300  # new in Photos 8
+    SOURCE = 2200  # new in Photos 8, shows the app/software source for the photo, e.g. Messages, Safari, etc.
+
+    @classmethod
+    def categories(cls) -> dict[int, str]:
+        """Return categories as dict of value: name"""
+        # need to get the categories from the base class and update with the new values
+        classdict = SearchCategory.__dict__.copy()
+        classdict |= cls.__dict__.copy()
+        return {
+            value: name
+            for name, value in classdict.items()
+            if name is not None
+            and not name.startswith("__")
+            and not callable(name)
+            and name.isupper()
+            and not isinstance(value, (list, dict, tuple))
+        }
 
 
 def search_category_factory(version: int) -> SearchCategory:
@@ -274,7 +361,7 @@ def search_category_factory(version: int) -> SearchCategory:
 
 
 # Max filename length on MacOS
-MAX_FILENAME_LEN = 255
+MAX_FILENAME_LEN = 255 - len(_OSXPHOTOS_LOCK_EXTENSION)
 
 # Max directory name length on MacOS
 MAX_DIRNAME_LEN = 255
@@ -379,3 +466,16 @@ PROFILE_SORT_KEYS = [
     "time",
     "tottime",
 ]
+
+UUID_PATTERN = (
+    r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"
+)
+# Reference: https://docs.python.org/3/library/sqlite3.html?highlight=sqlite3%20threadsafety#sqlite3.threadsafety
+# and https://docs.python.org/3/library/sqlite3.html?highlight=sqlite3%20threadsafety#sqlite3.connect
+# 3: serialized mode; Threads may share the module, connections and cursors
+# 3 is the default in the python.org python 3.11 distribution
+# earlier versions of python.org python 3.x default to 1 which means threads may not share
+# sqlite3 connections and thus PhotoInfo.export() cannot be used in a multithreaded environment
+# pass SQLITE_CHECK_SAME_THREAD to sqlite3.connect() to enable multithreaded access on systems that support it
+SQLITE_CHECK_SAME_THREAD = not sqlite3.threadsafety == 3
+logger.debug(f"{SQLITE_CHECK_SAME_THREAD=}, {sqlite3.threadsafety=}")

osxphotos/_version.py

@@ -1,3 +1,3 @@
 """ version info """
 
-__version__ = "0.56.2"
+__version__ = "0.60.4"

osxphotos/albuminfo.py

@@ -18,6 +18,7 @@ from ._constants import (
     _PHOTOS_4_VERSION,
     _PHOTOS_5_ALBUM_KIND,
     _PHOTOS_5_FOLDER_KIND,
+    _PHOTOS_5_VERSION,
     TIME_DELTA,
     AlbumSortOrder,
 )
@@ -49,9 +50,8 @@ def sort_list_by_keys(values, sort_keys):
         ValueError: raised if len(values) != len(sort_keys)
     """
     if len(values) != len(sort_keys):
-        return ValueError("values and sort_keys must have same length")
-
-    return list(zip(*sorted(zip(sort_keys, values))))[1]
+        raise ValueError("values and sort_keys must be same length")
+    return [x for _, x in sorted(zip(sort_keys, values))]
 
 
 class AlbumInfoBaseClass:
@@ -61,7 +61,7 @@ class AlbumInfoBaseClass:
     including folders, photos, etc.
     """
 
-    def __init__(self, db=None, uuid=None):
+    def __init__(self, db, uuid):
         self._uuid = uuid
         self._db = db
         self._title = self._db._dbalbum_details[uuid]["title"]
@@ -121,7 +121,8 @@ class AlbumInfoBaseClass:
     @property
     def end_date(self):
         """For Albums, return end date (most recent image) of album or None for albums with no images
-        For Import Sessions, return end date of import sessions (when import was completed)"""
+        For Import Sessions, return end date of import sessions (when import was completed)
+        """
         try:
             return self._end_date
         except AttributeError:
@@ -163,6 +164,16 @@ class AlbumInfoBaseClass:
                 self._owner = None
             return self._owner
 
+    def asdict(self):
+        """Return album info as a dict; does not include photos"""
+        return {
+            "uuid": self.uuid,
+            "creation_date": self.creation_date,
+            "start_date": self.start_date,
+            "end_date": self.end_date,
+            "owner": self.owner,
+        }
+
     def __len__(self):
         """return number of photos contained in album"""
         return len(self.photos)
@@ -174,6 +185,10 @@ class AlbumInfo(AlbumInfoBaseClass):
     including folders, photos, etc.
     """
 
+    def __init__(self, db, uuid):
+        super().__init__(db=db, uuid=uuid)
+        self._title = self._db._dbalbum_details[uuid]["title"]
+
     @property
     def title(self):
         """return title / name of album"""
@@ -205,10 +220,11 @@ class AlbumInfo(AlbumInfoBaseClass):
 
     @property
     def folder_names(self):
-        """return hierarchical list of folders the album is contained in
+        """Return hierarchical list of folders the album is contained in
         the folder list is in form:
         ["Top level folder", "sub folder 1", "sub folder 2", ...]
-        returns empty list if album is not in any folders"""
+        or empty list if album is not in any folders
+        """
 
         try:
             return self._folder_names
@@ -218,10 +234,9 @@ class AlbumInfo(AlbumInfoBaseClass):
 
     @property
     def folder_list(self):
-        """return hierarchical list of folders the album is contained in
-        as list of FolderInfo objects in form
-        ["Top level folder", "sub folder 1", "sub folder 2", ...]
-        returns empty list if album is not in any folders"""
+        """Returns list of FolderInfo objects for each folder the album is contained in
+        or empty list if album is not in any folders
+        """
 
         try:
             return self._folders
@@ -246,7 +261,7 @@ class AlbumInfo(AlbumInfoBaseClass):
                 parent_pk = self._db._dbalbum_details[self._uuid]["parentfolder"]
                 self._parent = (
                     FolderInfo(db=self._db, uuid=self._db._dbalbums_pk[parent_pk])
-                    if parent_pk != self._db._folder_root_pk
+                    if parent_pk is not None and parent_pk != self._db._folder_root_pk
                     else None
                 )
             return self._parent
@@ -281,27 +296,79 @@ class AlbumInfo(AlbumInfoBaseClass):
             f"Photo with uuid {photo.uuid} does not appear to be in this album"
         )
 
+    def asdict(self):
+        """Return album info as a dict; does not include photos"""
+        dict_data = super().asdict()
+        dict_data["title"] = self.title
+        dict_data["folder_names"] = self.folder_names
+        dict_data["folder_list"] = [f.uuid for f in self.folder_list]
+        dict_data["sort_order"] = self.sort_order
+        dict_data["parent"] = self.parent.uuid if self.parent else None
+        return dict_data
+
 
 class ImportInfo(AlbumInfoBaseClass):
     """Information about import sessions"""
 
+    def __init__(self, db, uuid):
+        self._uuid = uuid
+        self._db = db
+
+        if self._db._db_version >= _PHOTOS_5_VERSION:
+            return super().__init__(db=db, uuid=uuid)
+
+        import_session = self._db._db_import_group[self._uuid]
+        try:
+            self._creation_date_timestamp = import_session[3]
+        except (ValueError, TypeError, KeyError):
+            self._creation_date_timestamp = datetime(1970, 1, 1)
+        self._start_date_timestamp = self._creation_date_timestamp
+        self._end_date_timestamp = self._creation_date_timestamp
+        self._title = import_session[2]
+        self._local_tz = get_local_tz(
+            datetime.fromtimestamp(self._creation_date_timestamp + TIME_DELTA)
+        )
+
+    @property
+    def title(self):
+        """return title / name of import session"""
+        return self._title
+
     @property
     def photos(self):
         """return list of photos contained in import session"""
         try:
             return self._photos
         except AttributeError:
-            uuid_list, sort_order = zip(
-                *[
-                    (uuid, self._db._dbphotos[uuid]["fok_import_session"])
-                    for uuid in self._db._dbphotos
-                    if self._db._dbphotos[uuid]["import_uuid"] == self.uuid
+            if self._db._db_version >= _PHOTOS_5_VERSION:
+                uuid_list, sort_order = zip(
+                    *[
+                        (uuid, self._db._dbphotos[uuid]["fok_import_session"])
+                        for uuid in self._db._dbphotos
+                        if self._db._dbphotos[uuid]["import_uuid"] == self.uuid
+                    ]
+                )
+                sorted_uuid = sort_list_by_keys(uuid_list, sort_order)
+                self._photos = self._db.photos_by_uuid(sorted_uuid)
+            else:
+                import_photo_uuids = [
+                    u
+                    for u in self._db._dbphotos
+                    if self._db._dbphotos[u]["import_uuid"] == self.uuid
                 ]
-            )
-            sorted_uuid = sort_list_by_keys(uuid_list, sort_order)
-            self._photos = self._db.photos_by_uuid(sorted_uuid)
+                self._photos = self._db.photos_by_uuid(import_photo_uuids)
             return self._photos
 
+    def asdict(self):
+        """Return import info as a dict; does not include photos"""
+        return {
+            "uuid": self.uuid,
+            "creation_date": self.creation_date,
+            "start_date": self.start_date,
+            "end_date": self.end_date,
+            "title": self.title,
+        }
+
     def __bool__(self):
         """Always returns True
         A photo without an import session will return None for import_info,
@@ -309,13 +376,32 @@ class ImportInfo(AlbumInfoBaseClass):
         """
         return True
 
+
 class ProjectInfo(AlbumInfo):
     """
     ProjectInfo with info about projects
     Projects are cards, calendars, slideshows, etc.
     """
 
-    ...
+    @property
+    def folder_names(self):
+        """Return hierarchical list of folders the album is contained in
+        the folder list is in form:
+        ["Top level folder", "sub folder 1", "sub folder 2", ...]
+        or empty list if album is not in any folders
+        """
+
+        # projects are not in folders
+        return []
+
+    @property
+    def folder_list(self):
+        """Returns list of FolderInfo objects for each folder the album is contained in
+        or empty list if album is not in any folders
+        """
+
+        # projects are not in folders
+        return []
 
 
 class FolderInfo:
@@ -386,7 +472,7 @@ class FolderInfo:
                 parent_pk = self._db._dbalbum_details[self._uuid]["parentfolder"]
                 self._parent = (
                     FolderInfo(db=self._db, uuid=self._db._dbalbums_pk[parent_pk])
-                    if parent_pk != self._db._folder_root_pk
+                    if parent_pk is not None and parent_pk != self._db._folder_root_pk
                     else None
                 )
             return self._parent
@@ -416,6 +502,16 @@ class FolderInfo:
             self._folders = folders
             return self._folders
 
+    def asdict(self):
+        """Return folder info as a dict"""
+        return {
+            "title": self.title,
+            "uuid": self.uuid,
+            "parent": self.parent.uuid if self.parent is not None else None,
+            "subfolders": [f.uuid for f in self.subfolders],
+            "albums": [a.uuid for a in self.album_info],
+        }
+
     def __len__(self):
         """returns count of folders + albums contained in the folder"""
         return len(self.subfolders) + len(self.album_info)

osxphotos/cli/__init__.py

@@ -5,6 +5,7 @@ import sys
 from rich import print
 from rich.traceback import install as install_traceback
 
+from osxphotos.utils import is_macos
 from osxphotos.debug import (
     debug_breakpoint,
     debug_watch,
@@ -46,8 +47,19 @@ if args.get("--debug", False):
 from .about import about
 from .albums import albums
 from .cli import cli_main
-from .common import get_photos_db, load_uuid_from_file
+from .cli_commands import (
+    abort,
+    echo,
+    echo_error,
+    logger,
+    query_command,
+    selection_command,
+    verbose,
+)
+from .cli_params import DB_OPTION, DEBUG_OPTIONS, JSON_OPTION
+from .common import OSXPHOTOS_HIDDEN, get_photos_db
 from .debug_dump import debug_dump
+from .docs import docs_command
 from .dump import dump
 from .exiftool_cli import exiftool
 from .export import export
@@ -57,48 +69,71 @@ from .help import help
 from .info import info
 from .install_uninstall_run import install, run, uninstall
 from .keywords import keywords
+from .kvstore import kvstore
 from .labels import labels
 from .list import _list_libraries, list_libraries
 from .orphans import orphans
 from .persons import persons
-from .photo_inspect import photo_inspect
 from .places import places
 from .query import query
 from .repl import repl
 from .snap_diff import diff, snap
+from .theme import theme
 from .tutorial import tutorial
-from .uuid import uuid
+from .version import version
+
+if is_macos:
+    from .add_locations import add_locations
+    from .batch_edit import batch_edit
+    from .import_cli import import_cli
+    from .photo_inspect import photo_inspect
+    from .show_command import show
+    from .sync import sync
+    from .timewarp import timewarp
+    from .uuid import uuid
 
 install_traceback()
 
 __all__ = [
+    "abort",
     "about",
+    "add_locations",
     "albums",
+    "batch_edit",
     "cli_main",
     "debug_dump",
     "diff",
+    "docs_command",
     "dump",
+    "echo",
+    "echo_error",
     "exiftool_cli",
     "export",
     "exportdb",
     "grep",
     "help",
+    "import_cli",
     "info",
     "install",
     "keywords",
+    "kvstore",
     "labels",
     "list_libraries",
     "list_libraries",
-    "load_uuid_from_file",
+    "logger",
     "orphans",
     "persons",
     "photo_inspect",
     "places",
     "query",
+    "query_command",
     "repl",
     "run",
+    "selection_command",
     "set_debug",
+    "show",
     "snap",
     "tutorial",
     "uuid",
+    "verbose",
 ]

osxphotos/cli/add_locations.py

@@ -0,0 +1,186 @@
+"""Add missing location data to photos in Photos.app using nearest neighbor."""
+
+from __future__ import annotations
+
+import datetime
+
+import click
+
+import osxphotos
+from osxphotos.queryoptions import IncompatibleQueryOptions, query_options_from_kwargs
+from osxphotos.utils import assert_macos, pluralize
+
+from .cli_params import QUERY_OPTIONS, THEME_OPTION, TIMESTAMP_OPTION, VERBOSE_OPTION
+from .click_rich_echo import rich_click_echo as echo
+from .click_rich_echo import rich_echo_error as echo_error
+from .param_types import TimeOffset
+from .rich_progress import rich_progress
+from .verbose import get_verbose_console, verbose_print
+
+assert_macos()
+
+import photoscript
+
+
+def get_location(
+    photos: list[osxphotos.PhotoInfo], idx: int, window: datetime.timedelta
+) -> osxphotos.PhotoInfo | None:
+    """Find nearest neighbor with location data within window of time.
+
+    Args:
+        photo: PhotoInfo object
+        idx: index of photo in list of photos
+        window: window of time to search for nearest neighbor
+
+    Returns:
+        nearest neighbor PhotoInfo object or None if no neighbor found
+    """
+    idx_back = None
+    idx_forward = None
+    if idx > 0:
+        # search backwards in time
+        for i in range(idx - 1, -1, -1):
+            if (
+                photos[idx].date - photos[i].date <= window
+                and None not in photos[i].location
+            ):
+                idx_back = i
+                break
+
+    if idx < len(photos) - 1:
+        # search forwards in time
+        for i in range(idx + 1, len(photos)):
+            if (
+                photos[i].date - photos[idx].date <= window
+                and None not in photos[i].location
+            ):
+                idx_forward = i
+                break
+
+    if idx_back is not None and idx_forward is not None:
+        # found location in both directions
+        # use location closest in time
+        if (
+            photos[idx].date - photos[idx_back].date
+            < photos[idx_forward].date - photos[idx].date
+        ):
+            return photos[idx_back]
+        else:
+            return photos[idx_forward]
+    elif idx_back is not None:
+        return photos[idx_back]
+    elif idx_forward is not None:
+        return photos[idx_forward]
+    else:
+        return None
+
+
+@click.command(name="add-locations")
+@click.option(
+    "--window",
+    "-w",
+    type=TimeOffset(),
+    default="1 hr",
+    help="Window of time to search for nearest neighbor; "
+    "searches +/- window of time.  Default is 1 hour. "
+    "Format is one of 'HH:MM:SS', 'D days', 'H hours' (or hr), 'M minutes' (or min), "
+    "'S seconds' (or sec), 'S' (where S is seconds).",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Don't actually add location, just print what would be done. "
+    "Most useful with --verbose.",
+)
+@VERBOSE_OPTION
+@TIMESTAMP_OPTION
+@QUERY_OPTIONS
+@THEME_OPTION
+@click.pass_obj
+@click.pass_context
+def add_locations(
+    ctx, cli_ob, window, dry_run, verbose_flag, timestamp, theme, **kwargs
+):
+    """Add missing location data to photos in Photos.app using nearest neighbor.
+
+    This command will search for photos that are missing location data and look
+    for the nearest neighbor photo within a given window of time that contains
+    location information. If a photo is found within the window of time, the
+    location of the nearest neighbor will be used to update the location of the
+    photo.
+
+    For example, if you took pictures with your iPhone and also with a camera that
+    doesn't have location information, you can use this command to add location
+    information to the photos taken with the camera from those taken with the
+    iPhone.
+
+    If you have many photos with missing location information but no nearest neighbor
+    within the window of time, you could add location information to some photos manually
+    then run this command again to add location information to the remaining photos.
+
+    You can specify a subset of photos to update using the query options.  For example,
+    `--selected` to update only the selected photos, `--added-after 2020-01-01` to update
+    only photos added after Jan 1, 2020, etc.
+
+    Example:
+
+    Add location data to all photos with missing location data within a ±2 hour window:
+
+    `osxphotos add-locations --window "2 hr" --verbose`
+
+    The add-locations command assumes that photos already have the correct date and time.
+    If you have photos that are missing both location data and date/time information,
+    you can use `osxphotos timewarp` to add date/time information to the photos and then
+    use `osxphotos add-locations` to add location information.
+    See `osxphotos help timewarp` for more information.
+    """
+    verbose = verbose_print(verbose_flag, timestamp, theme=theme)
+
+    verbose("Searching for photos with missing location data...")
+
+    try:
+        query_options = query_options_from_kwargs(**kwargs)
+    except IncompatibleQueryOptions as e:
+        echo_error("Incompatible query options")
+        echo_error(ctx.obj.group.commands["repl"].get_help(ctx))
+        ctx.exit(1)
+
+    photosdb = osxphotos.PhotosDB(verbose=verbose)
+    photos = photosdb.query(query_options)
+
+    # sort photos by date
+    photos = sorted(photos, key=lambda p: p.date)
+
+    num_photos = len(photos)
+    missing_location = 0
+    found_location = 0
+    verbose(f"Processing {len(photos)} photos, window = ±{window}...")
+    with rich_progress(console=get_verbose_console(), mock=verbose_flag) as progress:
+        task = progress.add_task(
+            f"Processing [num]{num_photos}[/] {pluralize(len(photos), 'photo', 'photos')}, window = ±{window}",
+            total=num_photos,
+        )
+        for idx, photo in enumerate(photos):
+            if None in photo.location:
+                missing_location += 1
+                verbose(
+                    f"Processing [filename]{photo.original_filename}[/] ([uuid]{photo.uuid}[/])"
+                )
+                if neighbor := get_location(photos, idx, window):
+                    verbose(
+                        f"Adding location {neighbor.location} to [filename]{photo.original_filename}[/] ([uuid]{photo.uuid}[/])"
+                        f" from [filename]{neighbor.original_filename}[/] ([uuid]{neighbor.uuid}[/])"
+                    )
+                    found_location += 1
+                    if not dry_run:
+                        photoscript.Photo(photo.uuid).location = neighbor.location
+                else:
+                    verbose(
+                        f"No location found for [filename]{photo.original_filename}[/] ([uuid]{photo.uuid}[/])"
+                    )
+            progress.advance(task)
+    echo(
+        f"Done. Processed: [num]{num_photos}[/] photos, "
+        f"missing location: [num]{missing_location}[/], "
+        f"found location: [num]{found_location}[/] "
+    )

osxphotos/cli/albums.py

@@ -6,12 +6,12 @@ import click
 import yaml
 
 import osxphotos
-
-from .common import DB_ARGUMENT, DB_OPTION, JSON_OPTION, get_photos_db
-from .list import _list_libraries
-
 from osxphotos._constants import _PHOTOS_4_VERSION
 
+from .cli_params import DB_ARGUMENT, DB_OPTION, JSON_OPTION
+from .common import get_photos_db
+from .list import _list_libraries
+
 
 @click.command()
 @DB_OPTION
@@ -36,7 +36,8 @@ def albums(ctx, cli_obj, db, json_, photos_library):
     if photosdb.db_version > _PHOTOS_4_VERSION:
         albums["shared albums"] = photosdb.albums_shared_as_dict
 
-    if json_ or cli_obj.json:
+    # cli_obj will be None if called from pytest
+    if json_ or (cli_obj and cli_obj.json):
         click.echo(json.dumps(albums, ensure_ascii=False))
     else:
         click.echo(yaml.dump(albums, sort_keys=False, allow_unicode=True))

osxphotos/cli/batch_edit.py

@@ -0,0 +1,315 @@
+"""
+batch-edit command for osxphotos CLI
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import sys
+
+import click
+
+import osxphotos
+from osxphotos.phototemplate import RenderOptions
+from osxphotos.sqlitekvstore import SQLiteKVStore
+from osxphotos.utils import assert_macos
+
+assert_macos()
+
+import photoscript
+
+from .cli_commands import echo, echo_error, selection_command, verbose
+from .kvstore import kvstore
+from .param_types import Latitude, Longitude, TemplateString
+
+
+@selection_command(name="batch-edit")
+@click.option(
+    "--title",
+    metavar="TITLE_TEMPLATE",
+    type=TemplateString(),
+    help="Set title of photo.",
+)
+@click.option(
+    "--description",
+    metavar="DESCRIPTION_TEMPLATE",
+    type=TemplateString(),
+    help="Set description of photo.",
+)
+@click.option(
+    "--keyword",
+    metavar="KEYWORD_TEMPLATE",
+    type=TemplateString(),
+    multiple=True,
+    help="Add keywords to photo. May be specified multiple times.",
+)
+@click.option(
+    "--replace-keywords",
+    is_flag=True,
+    help="When specified with --keyword, replace existing keywords. "
+    "Default is to add to existing keywords.",
+)
+@click.option(
+    "--location",
+    metavar="LATITUDE LONGITUDE",
+    type=click.Tuple([Latitude(), Longitude()]),
+    help="Set location of photo. "
+    "Must be specified as a pair of numbers with latitude in the range -90 to 90 and longitude in the range -180 to 180.",
+)
+@click.option("--dry-run", is_flag=True, help="Don't actually change anything.")
+@click.option(
+    "--undo",
+    is_flag=True,
+    help="Restores photo metadata to what it was prior to the last batch edit. "
+    "May be combined with --dry-run.",
+)
+def batch_edit(
+    photos: list[osxphotos.PhotoInfo],
+    title,
+    description,
+    keyword,
+    replace_keywords,
+    location,
+    dry_run,
+    undo,
+    **kwargs,
+):
+    """
+    Batch edit photo metadata such as title, description, keywords, etc.
+    Operates on currently selected photos.
+
+    Select one or more photos in Photos then run this command to edit the metadata.
+
+    For example:
+
+    \b
+        osxphotos batch-edit \\
+        --verbose \\
+        --title "California vacation 2023 {created.year}-{created.dd}-{created.mm} {counter:03d}" \\
+        --description "{place.name}" \\ 
+        --keyword "Family" --keyword "Travel"
+
+    This will set the title to "California vacation 2023 2023-02-20 001", and so on,
+    the description to the reverse geolocation place name, 
+    and add the keywords "Family" and "Travel".
+
+    --title, --description, and --keyword may be any valid template string.
+    See https://rhettbull.github.io/osxphotos/template_help.html 
+    or `osxphotos docs` for more information on the osxphotos template system.
+    """
+
+    if not title and not description and not keyword and not location and not undo:
+        echo_error(
+            "[error] Must specify at least one of: "
+            " --title, --description, --keyword, --location, --undo. "
+            "Use --help for more information."
+        )
+        sys.exit(1)
+
+    if undo and (title or description or keyword or location):
+        echo_error(
+            "[error] Cannot specify --undo and any options other than --dry-run. "
+            "Use --help for more information."
+        )
+        sys.exit(1)
+
+    if replace_keywords and not keyword:
+        echo_error(
+            "[error] Cannot specify --replace-keywords without --keyword. "
+            "Use --help for more information."
+        )
+        sys.exit(1)
+
+    if not photos:
+        echo_error("[error] No photos selected")
+        sys.exit(1)
+
+    # sort photos by date so that {counter} order is correct
+    photos.sort(key=lambda p: p.date)
+
+    undo_store = kvstore("batch_edit")
+    verbose(f"Undo database stored in [filepath]{undo_store.path}", level=2)
+
+    echo(f"Processing [num]{len(photos)}[/] photos...")
+    for photo in photos:
+        verbose(
+            f"Processing [filename]{photo.original_filename}[/] ([uuid]{photo.uuid}[/])"
+        )
+        if undo:
+            undo_photo_edits(photo, undo_store, dry_run)
+            continue
+        save_photo_undo_info(undo_store, photo)
+        set_photo_title_from_template(photo, title, dry_run)
+        set_photo_description_from_template(photo, description, dry_run)
+        set_photo_keywords_from_template(photo, keyword, replace_keywords, dry_run)
+        set_photo_location(photo, location, dry_run)
+
+
+# cache photoscript Photo object to avoid re-creating it for each photo
+# maxsize=1 as this function is called repeatedly for each photo then
+# the next photo is processed
+@functools.lru_cache(maxsize=1)
+def photoscript_photo(photo: osxphotos.PhotoInfo) -> photoscript.Photo:
+    """Return photoscript Photo object for photo"""
+    return photoscript.Photo(photo.uuid)
+
+
+def save_photo_undo_info(undo_store: SQLiteKVStore, photo: osxphotos.PhotoInfo):
+    """Save undo information to undo store"""
+    undo_store[photo.uuid] = photo.json()
+
+
+def undo_photo_edits(
+    photo: osxphotos.PhotoInfo, undo_store: SQLiteKVStore, dry_run: bool
+):
+    """Undo edits for photo"""
+    if not (undo_info := undo_store.get(photo.uuid)):
+        verbose(
+            f"[warning] No undo information for photo [filename]{photo.original_filename}[/] ([uuid]{photo.uuid}[/])"
+        )
+        return
+    undo_info = json.loads(undo_info)
+    ps_photo = photoscript_photo(photo)
+    exiting_title, exiting_description, exiting_keywords, exiting_location = (
+        photo.title,
+        photo.description,
+        sorted(photo.keywords),
+        photo.location,
+    )
+    previous_title, previous_description, previous_keywords, previous_location = (
+        undo_info.get("title"),
+        undo_info.get("description"),
+        sorted(undo_info.get("keywords")),
+        (undo_info.get("latitude"), undo_info.get("longitude")),
+    )
+    verbose(
+        f"Undoing edits for [filename]{photo.original_filename}[/] ([uuid]{photo.uuid}[/])"
+    )
+    for name, existing, previous in (
+        ("title", exiting_title, previous_title),
+        ("description", exiting_description, previous_description),
+        ("keywords", exiting_keywords, previous_keywords),
+        ("location", exiting_location, previous_location),
+    ):
+        if existing != previous:
+            verbose(
+                f"  [i]{name}[/]: [change]{existing}[/] -> [no_change]{previous}[/]"
+            )
+            if not dry_run:
+                setattr(ps_photo, name, previous)
+        else:
+            verbose(f"  [i]{name} (no change)[/]: [no_change]{existing}[/]", level=2)
+
+
+def set_photo_title_from_template(
+    photo: osxphotos.PhotoInfo, title_template: str, dry_run: bool
+):
+    """Set photo title from template"""
+    if not title_template:
+        return
+
+    # don't render None values
+    render_options = RenderOptions(none_str="")
+
+    title_string, _ = photo.render_template(title_template, render_options)
+    title_string = [ts for ts in title_string if ts]
+    if not title_string:
+        verbose(
+            f"No title returned from template, nothing to do: [bold]{title_template}"
+        )
+        return
+
+    if len(title_string) > 1:
+        echo_error(
+            f"[error] Title template must return a single string: [bold]{title_string}"
+        )
+        sys.exit(1)
+
+    verbose(f"Setting [i]title[/i] to [bold]{title_string[0]}")
+    if not dry_run:
+        ps_photo = photoscript_photo(photo)
+        ps_photo.title = title_string[0]
+
+
+def set_photo_description_from_template(
+    photo: osxphotos.PhotoInfo, description_template: str, dry_run: bool
+):
+    """Set photo description from template"""
+    if not description_template:
+        return
+
+    # don't render None values
+    render_options = RenderOptions(none_str="")
+
+    description_string, _ = photo.render_template(description_template, render_options)
+    description_string = [ds for ds in description_string if ds]
+    if not description_string:
+        verbose(
+            f"No description returned from template, nothing to do: [bold]{description_template}"
+        )
+        return
+
+    if len(description_string) > 1:
+        echo_error(
+            f"[error] Description template must return a single string: [bold]{description_string}"
+        )
+        sys.exit(1)
+
+    verbose(f"Setting [i]description[/] to [bold]{description_string[0]}")
+    if not dry_run:
+        ps_photo = photoscript_photo(photo)
+        ps_photo.description = description_string[0]
+
+
+def set_photo_keywords_from_template(
+    photo: osxphotos.PhotoInfo,
+    keyword_template: list[str],
+    replace_keywords: bool,
+    dry_run: bool,
+):
+    """Set photo keywords from template"""
+    if not keyword_template:
+        return
+
+    # don't render None values
+    render_options = RenderOptions(none_str="")
+
+    keywords = set()
+    for kw in keyword_template:
+        kw_string, _ = photo.render_template(kw, render_options)
+        if kw_string:
+            # filter out empty strings
+            keywords.update([k for k in kw_string if k])
+
+    if not keywords:
+        verbose(
+            f"No keywords returned from template, nothing to do: [bold]{keyword_template}"
+        )
+        return
+
+    if not replace_keywords:
+        keywords.update(photo.keywords)
+
+    verbose(
+        f"Setting [i]keywords[/] to {', '.join(f'[bold]{kw}[/]' for kw in keywords)}"
+    )
+    if not dry_run:
+        ps_photo = photoscript_photo(photo)
+        ps_photo.keywords = list(keywords)
+
+
+def set_photo_location(
+    photo: osxphotos.PhotoInfo, location: tuple[float, float], dry_run: bool
+):
+    """Set photo location"""
+    if not location or location[0] is None or location[1] is None:
+        return
+
+    latitude, longitude = location
+    verbose(
+        f"Setting [i]location[/] to [num]{latitude:.6f}[/], [num]{longitude:.6f}[/]"
+    )
+    if not dry_run:
+        ps_photo = photoscript_photo(photo)
+        ps_photo.location = (latitude, longitude)

osxphotos/cli/cli.py

@@ -9,19 +9,20 @@ import click
 
 from osxphotos._constants import PROFILE_SORT_KEYS
 from osxphotos._version import __version__
+from osxphotos.utils import is_macos
 
 from .about import about
 from .albums import albums
-from .common import DB_OPTION, JSON_OPTION, OSXPHOTOS_HIDDEN
+from .cli_params import DB_OPTION, DEBUG_OPTIONS, JSON_OPTION, VERSION_OPTION
+from .common import OSXPHOTOS_HIDDEN
 from .debug_dump import debug_dump
-from .docs import docs
+from .docs import docs_command
 from .dump import dump
 from .exiftool_cli import exiftool
 from .export import export
 from .exportdb import exportdb
 from .grep import grep
 from .help import help
-from .import_cli import import_cli
 from .info import info
 from .install_uninstall_run import install, run, uninstall
 from .keywords import keywords
@@ -29,18 +30,23 @@ from .labels import labels
 from .list import list_libraries
 from .orphans import orphans
 from .persons import persons
-from .photo_inspect import photo_inspect
 from .places import places
 from .query import query
 from .repl import repl
 from .snap_diff import diff, snap
-from .sync import sync
 from .theme import theme
-from .timewarp import timewarp
 from .tutorial import tutorial
-from .uuid import uuid
 from .version import version
-from .common import DEBUG_OPTIONS
+
+if is_macos:
+    from .add_locations import add_locations
+    from .batch_edit import batch_edit
+    from .import_cli import import_cli
+    from .photo_inspect import photo_inspect
+    from .show_command import show
+    from .sync import sync
+    from .timewarp import timewarp
+    from .uuid import uuid
 
 
 # Click CLI object & context settings
@@ -55,7 +61,7 @@ CTX_SETTINGS = dict(help_option_names=["-h", "--help"])
 
 
 @click.group(context_settings=CTX_SETTINGS)
-@click.version_option(__version__, "--version", "-v")
+@VERSION_OPTION
 @DB_OPTION
 @JSON_OPTION
 @DEBUG_OPTIONS
@@ -103,19 +109,18 @@ def cli_main(ctx, db, json_, profile, profile_sort, **kwargs):
 
 
 # install CLI commands
-for command in [
+commands = [
     about,
     albums,
     debug_dump,
     diff,
-    docs,
+    docs_command,
     dump,
     exiftool,
     export,
     exportdb,
     grep,
     help,
-    import_cli,
     info,
     install,
     keywords,
@@ -123,18 +128,28 @@ for command in [
     list_libraries,
     orphans,
     persons,
-    photo_inspect,
     places,
     query,
     repl,
     run,
     snap,
-    sync,
     theme,
-    timewarp,
     tutorial,
     uninstall,
-    uuid,
     version,
-]:
+]
+
+if is_macos:
+    commands += [
+        add_locations,
+        batch_edit,
+        import_cli,
+        photo_inspect,
+        show,
+        sync,
+        timewarp,
+        uuid,
+    ]
+
+for command in commands:
     cli_main.add_command(command)

osxphotos/cli/cli_commands.py

@@ -0,0 +1,310 @@
+"""Helper functions to make writing an osxphotos CLI tool easy.
+
+Includes decorator to create an osxphotos query command to be run via `osxphotos run example.py`.
+
+May also be run via `python example.py` if you have pip installed osxphotos
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+import typing as t  # match style used in Click source code
+
+import click
+
+from osxphotos.photosdb import PhotosDB
+from osxphotos.queryoptions import QueryOptions, query_options_from_kwargs
+from osxphotos.sqlitekvstore import SQLiteKVStore
+
+from .cli_params import (
+    _DB_PARAMETER,
+    _QUERY_PARAMETERS_DICT,
+    DB_OPTION,
+    THEME_OPTION,
+    TIMESTAMP_OPTION,
+    VERBOSE_OPTION,
+)
+from .click_rich_echo import rich_click_echo as echo
+from .click_rich_echo import rich_echo_error as echo_error
+from .click_rich_echo import set_rich_theme
+from .color_themes import get_theme
+from .verbose import verbose, verbose_print
+
+logger = logging.getLogger("osxphotos")
+
+# ensure echo, echo_error are configured with correct theme
+set_rich_theme(get_theme())
+
+__all__ = [
+    "abort",
+    "echo",
+    "echo_error",
+    "logger",
+    "query_command",
+    "selection_command",
+    "verbose",
+]
+
+
+def abort(message: str, exit_code: int = 1):
+    """Abort with error message and exit code"""
+    echo_error(f"[error]{message}[/]")
+    sys.exit(exit_code)
+
+
+def config_verbose_callback(ctx: click.Context, param: click.Parameter, value: t.Any):
+    """Callback for --verbose option"""
+    # calling verbose_print() will set the verbose level for the verbose() function
+    theme = ctx.params.get("theme")
+    timestamp = ctx.params.get("timestamp")
+    verbose_print(verbose=value, timestamp=timestamp, theme=theme)
+    return value
+
+
+def get_photos_for_query(ctx: click.Context):
+    """Return list of PhotoInfo objects for the photos matching the query options in ctx.params"""
+    options = query_options_from_kwargs(**ctx.params)
+    db = ctx.params.get("db")
+    photosdb = PhotosDB(dbfile=db, verbose=verbose)
+    return photosdb.query(options=options)
+
+
+def get_selected_photos(ctx: click.Context):
+    """Return list of PhotoInfo objects for the photos currently selected in Photos.app"""
+    photosdb = PhotosDB(verbose=verbose)
+    return photosdb.query(options=QueryOptions(selected=True))
+
+
+class QueryCommand(click.Command):
+    """
+    Click command to create an osxphotos query command.
+
+    This class is used by the query_command decorator to create a click command
+    that runs an osxphotos query. It will automatically add the query options as
+    well as the --verbose, --timestamp, --theme, and --db options.
+    """
+
+    standalone_mode = False
+
+    def __init__(
+        self,
+        name: t.Optional[str],
+        context_settings: t.Optional[t.Dict[str, t.Any]] = None,
+        callback: t.Optional[t.Callable[..., t.Any]] = None,
+        params: t.Optional[t.List[click.Parameter]] = None,
+        help: t.Optional[str] = None,
+        epilog: t.Optional[str] = None,
+        short_help: t.Optional[str] = None,
+        options_metavar: t.Optional[str] = "[OPTIONS]",
+        add_help_option: bool = True,
+        no_args_is_help: bool = False,
+        hidden: bool = False,
+        deprecated: bool = False,
+    ) -> None:
+        self.params = params or []
+        self.params.append(
+            click.Option(
+                param_decls=["--verbose", "-V", "verbose_flag"],
+                count=True,
+                help="Print verbose output; may be specified multiple times for more verbose output.",
+                callback=config_verbose_callback,
+            )
+        )
+        self.params.append(
+            click.Option(
+                param_decls=["--timestamp"],
+                is_flag=True,
+                help="Add time stamp to verbose output",
+            )
+        )
+        self.params.append(
+            click.Option(
+                param_decls=["--theme"],
+                metavar="THEME",
+                type=click.Choice(
+                    ["dark", "light", "mono", "plain"], case_sensitive=False
+                ),
+                help="Specify the color theme to use for output. "
+                "Valid themes are 'dark', 'light', 'mono', and 'plain'. "
+                "Defaults to 'dark' or 'light' depending on system dark mode setting.",
+            )
+        )
+        self.params.append(_DB_PARAMETER)
+        self.params.extend(_QUERY_PARAMETERS_DICT.values())
+
+        super().__init__(
+            name,
+            context_settings,
+            callback,
+            self.params,
+            help,
+            epilog,
+            short_help,
+            options_metavar,
+            add_help_option,
+            no_args_is_help,
+            hidden,
+            deprecated,
+        )
+
+    def make_context(
+        self,
+        info_name: t.Optional[str],
+        args: t.List[str],
+        parent: t.Optional[click.Context] = None,
+        **extra: t.Any,
+    ) -> click.Context:
+        ctx = super().make_context(info_name, args, parent, **extra)
+        ctx.obj = self
+        photos = get_photos_for_query(ctx)
+        ctx.params["photos"] = photos
+
+        # remove params handled by this class
+        ctx.params.pop("verbose_flag")
+        ctx.params.pop("timestamp")
+        ctx.params.pop("theme")
+        return ctx
+
+
+class SelectionCommand(click.Command):
+    """
+    Click command to create an osxphotos selection command that runs on selected photos.
+
+    This class is used by the query_command decorator to create a click command
+    that runs on currently selected photos.
+
+    The --verbose, --timestamp, --theme, and --db options will also be added to the command.
+    """
+
+    standalone_mode = False
+
+    def __init__(
+        self,
+        name: t.Optional[str],
+        context_settings: t.Optional[t.Dict[str, t.Any]] = None,
+        callback: t.Optional[t.Callable[..., t.Any]] = None,
+        params: t.Optional[t.List[click.Parameter]] = None,
+        help: t.Optional[str] = None,
+        epilog: t.Optional[str] = None,
+        short_help: t.Optional[str] = None,
+        options_metavar: t.Optional[str] = "[OPTIONS]",
+        add_help_option: bool = True,
+        no_args_is_help: bool = False,
+        hidden: bool = False,
+        deprecated: bool = False,
+    ) -> None:
+        self.params = params or []
+        self.params.append(
+            click.Option(
+                param_decls=["--verbose", "-V", "verbose_flag"],
+                count=True,
+                help="Print verbose output; may be specified multiple times for more verbose output.",
+                callback=config_verbose_callback,
+            )
+        )
+        self.params.append(
+            click.Option(
+                param_decls=["--timestamp"],
+                is_flag=True,
+                help="Add time stamp to verbose output",
+            )
+        )
+        self.params.append(
+            click.Option(
+                param_decls=["--theme"],
+                metavar="THEME",
+                type=click.Choice(
+                    ["dark", "light", "mono", "plain"], case_sensitive=False
+                ),
+                help="Specify the color theme to use for output. "
+                "Valid themes are 'dark', 'light', 'mono', and 'plain'. "
+                "Defaults to 'dark' or 'light' depending on system dark mode setting.",
+            )
+        )
+        self.params.append(
+            click.Option(
+                param_decls=["--library", "--db"],
+                required=False,
+                metavar="PHOTOS_LIBRARY_PATH",
+                default=None,
+                help=(
+                    "Specify Photos database path. "
+                    "Path to Photos library/database can be specified using either --db "
+                    "or directly as PHOTOS_LIBRARY positional argument. "
+                    "If neither --db or PHOTOS_LIBRARY provided, will attempt to find the library "
+                    "to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary"
+                ),
+                type=click.Path(exists=True),
+            )
+        )
+        super().__init__(
+            name,
+            context_settings,
+            callback,
+            self.params,
+            help,
+            epilog,
+            short_help,
+            options_metavar,
+            add_help_option,
+            no_args_is_help,
+            hidden,
+            deprecated,
+        )
+
+    def make_context(
+        self,
+        info_name: t.Optional[str],
+        args: t.List[str],
+        parent: t.Optional[click.Context] = None,
+        **extra: t.Any,
+    ) -> click.Context:
+        ctx = super().make_context(info_name, args, parent, **extra)
+        ctx.obj = self
+        photos = get_selected_photos(ctx)
+        ctx.params["photos"] = photos
+
+        # remove params handled by this class
+        ctx.params.pop("verbose_flag")
+        ctx.params.pop("timestamp")
+        ctx.params.pop("theme")
+        return ctx
+
+
+def query_command(name=None, cls=QueryCommand, **attrs):
+    """Decorator to create an osxphotos command to be run via `osxphotos run example.py`
+
+    The command will be passed a list of PhotoInfo objects for all photos in Photos
+    matching the query options or all photos if no query options are specified.
+
+    The standard osxphotos query options will be added to the command.
+
+    The CLI will also be passed the following options:
+
+    --verbose
+    --timestamp
+    --theme
+    --db
+    """
+    if callable(name) and cls:
+        return click.command(cls=cls, **attrs)(name)
+
+    return click.command(name, cls=cls, **attrs)
+
+
+def selection_command(name=None, cls=SelectionCommand, **attrs):
+    """Decorator to create an osxphotos command to be run via `osxphotos run example.py`
+
+    The command will be passed a list of PhotoInfo objects for all photos selected in Photos.
+    The CLI will also be passed the following options:
+
+    --verbose
+    --timestamp
+    --theme
+    --db
+    """
+    if callable(name) and cls:
+        return click.command(cls=cls, **attrs)(name)
+
+    return click.command(name, cls=cls, **attrs)

osxphotos/cli/cli_params.py

@@ -0,0 +1,758 @@
+"""Common options & parameters for osxphotos CLI commands"""
+
+
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable
+import click
+import contextlib
+from textwrap import dedent
+
+from ..utils import is_macos
+from .common import OSXPHOTOS_HIDDEN, print_version
+from .param_types import *
+
+__all__ = [
+    "DB_ARGUMENT",
+    "DB_OPTION",
+    "DEBUG_OPTIONS",
+    "DELETED_OPTIONS",
+    "FIELD_OPTION",
+    "JSON_OPTION",
+    "QUERY_OPTIONS",
+    "THEME_OPTION",
+    "TIMESTAMP_OPTION",
+    "VERBOSE_OPTION",
+    "VERSION_OPTION",
+]
+
+
+def validate_selected(ctx, param, value):
+    """ "Validate photos are actually selected when --selected is used"""
+
+    if not value:
+        # --selected not used, just return
+        return value
+
+    # imports here to avoid conflict with linux port
+    # TODO: fix this once linux port is complete
+    import photoscript
+    from applescript import ScriptError
+
+    selection = None
+    with contextlib.suppress(ScriptError):
+        # ScriptError raised if selection made in edit mode or Smart Albums (on older versions of Photos)
+        selection = photoscript.PhotosLibrary().selection
+
+    if not selection:
+        click.echo(
+            dedent(
+                """
+                --selected option used but no photos selected in Photos.
+
+                To select photos in Photos use one of the following methods:
+    
+                - Select a single photo: Click the photo, or press the arrow keys to quickly navigate to and select the photo.
+
+                - Select a group of adjacent photos in a day: Click the first photo, then hold down the Shift key while you click the last photo.
+                You can also hold down Shift and press the arrow keys, or simply drag to enclose the photos within the selection rectangle.
+
+                - Select photos in a day that are not adjacent to each other: Hold down the Command key as you click each photo.
+
+                - Deselect specific photos: Hold down the Command key and click the photos you want to deselect.
+
+                - Deselect all photos: Click an empty space in the window (not a photo).
+            """
+            ),
+            err=True,
+        )
+        ctx.exit(1)
+    return value
+
+
+def _param_memo(f: Callable[..., Any], param: click.Parameter) -> None:
+    """Add param to the list of params for a click.Command
+    This is directly from the click source code and
+    the implementation is thus tightly coupled to click internals
+    """
+    if isinstance(f, click.Command):
+        f.params.append(param)
+    else:
+        if not hasattr(f, "__click_params__"):
+            f.__click_params__ = []  # type: ignore
+
+        f.__click_params__.append(param)  # type: ignore
+
+
+def make_click_option_decorator(*params: click.Parameter) -> Callable[..., Any]:
+    """Make a decorator for a click option from one or more click Parameter objects"""
+
+    def decorator(wrapped=None) -> Callable[..., Any]:
+        """Function decorator to add option to a click command.
+
+        Args:
+            wrapped: function to decorate (this is normally passed automatically
+        """
+
+        if wrapped is None:
+            return decorator
+
+        def _add_options(wrapped):
+            """Add query options to wrapped function"""
+            for param in params:
+                _param_memo(wrapped, param)
+            return wrapped
+
+        return _add_options(wrapped)
+
+    return decorator
+
+
+VERSION_CHECK_OPTION = click.option("--no-version-check", required=False, is_flag=True)
+
+_DB_PARAMETER = click.Option(
+    ["--library", "--db", "db"],
+    required=False,
+    metavar="PHOTOS_LIBRARY_PATH",
+    default=None,
+    help=(
+        "Specify path to Photos library. "
+        "If not provided, will attempt to find the library to use in the following order: "
+        "1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary"
+    ),
+    type=click.Path(exists=True),
+)
+
+DB_OPTION = make_click_option_decorator(_DB_PARAMETER)
+
+DB_ARGUMENT = click.argument(
+    "photos_library",
+    nargs=-1,
+    type=DeprecatedPath(
+        exists=True,
+        deprecation_warning="The PHOTOS_LIBRARY argument is deprecated and "
+        "will be removed in a future version of osxphotos. "
+        "Use --library instead to specify the Photos Library path.",
+    ),
+)
+
+_JSON_PARAMETER = click.Option(
+    ["--json", "json_"],
+    required=False,
+    is_flag=True,
+    default=False,
+    help="Print output in JSON format.",
+)
+
+JSON_OPTION = make_click_option_decorator(_JSON_PARAMETER)
+
+_FIELD_PARAMETER = click.Option(
+    ["--field", "-f"],
+    metavar="FIELD TEMPLATE",
+    multiple=True,
+    nargs=2,
+    help="Output only specified custom fields. "
+    "FIELD is the name of the field and TEMPLATE is the template to use as the field value. "
+    "May be repeated to output multiple fields. "
+    "For example, to output photo uuid, name, and title: "
+    '`--field uuid "{uuid}" --field name "{original_name}" --field title "{title}"`.',
+)
+
+FIELD_OPTION = make_click_option_decorator(_FIELD_PARAMETER)
+
+_DELETED_PARAMETERS = [
+    click.Option(
+        ["--deleted"],
+        is_flag=True,
+        help="Include photos from the 'Recently Deleted' folder.",
+    ),
+    click.Option(
+        ["--deleted-only"],
+        is_flag=True,
+        help="Include only photos from the 'Recently Deleted' folder.",
+    ),
+]
+
+DELETED_OPTIONS = make_click_option_decorator(*_DELETED_PARAMETERS)
+
+# The following are used by the query command and by
+# QUERY_OPTIONS to add the query options to other commands
+# To add new query options, add them to _QUERY_OPTIONS as
+# a click.Option, add them to osxphotos/photosdb/photosdb.py::PhotosDB.query(),
+# and to osxphotos/query_options.py::QueryOptions
+_QUERY_PARAMETERS_DICT = {
+    "--keyword": click.Option(
+        ["--keyword"],
+        metavar="KEYWORD",
+        default=None,
+        multiple=True,
+        help="Search for photos with keyword KEYWORD. "
+        'If more than one keyword, treated as "OR", e.g. find photos matching any keyword',
+    ),
+    "--no-keyword": click.Option(
+        ["--no-keyword"],
+        is_flag=True,
+        help="Search for photos with no keyword.",
+    ),
+    "--person": click.Option(
+        ["--person"],
+        metavar="PERSON",
+        default=None,
+        multiple=True,
+        help="Search for photos with person PERSON. "
+        'If more than one person, treated as "OR", e.g. find photos matching any person',
+    ),
+    "--album": click.Option(
+        ["--album"],
+        metavar="ALBUM",
+        default=None,
+        multiple=True,
+        help="Search for photos in album ALBUM. "
+        'If more than one album, treated as "OR", e.g. find photos matching any album',
+    ),
+    "--folder": click.Option(
+        ["--folder"],
+        metavar="FOLDER",
+        default=None,
+        multiple=True,
+        help="Search for photos in an album in folder FOLDER. "
+        'If more than one folder, treated as "OR", e.g. find photos in any FOLDER.  '
+        "Only searches top level folders (e.g. does not look at subfolders)",
+    ),
+    "--name": click.Option(
+        ["--name"],
+        metavar="FILENAME",
+        default=None,
+        multiple=True,
+        help="Search for photos with filename matching FILENAME. "
+        'If more than one --name options is specified, they are treated as "OR", '
+        "e.g. find photos matching any FILENAME. ",
+    ),
+    "--uuid": click.Option(
+        ["--uuid"],
+        metavar="UUID",
+        default=None,
+        multiple=True,
+        help="Search for photos with UUID(s). "
+        "May be repeated to include multiple UUIDs.",
+    ),
+    "--uuid-from-file": click.Option(
+        ["--uuid-from-file"],
+        metavar="FILE",
+        default=None,
+        multiple=False,
+        help="Search for photos with UUID(s) loaded from FILE. "
+        "Format is a single UUID per line. Lines preceded with # are ignored. "
+        "If FILE is '-', read UUIDs from stdin.",
+        type=PathOrStdin(exists=True),
+    ),
+    "--title": click.Option(
+        ["--title"],
+        metavar="TITLE",
+        default=None,
+        multiple=True,
+        help="Search for TITLE in title of photo.",
+    ),
+    "--no-title": click.Option(
+        ["--no-title"], is_flag=True, help="Search for photos with no title."
+    ),
+    "--description": click.Option(
+        ["--description"],
+        metavar="DESC",
+        default=None,
+        multiple=True,
+        help="Search for DESC in description of photo.",
+    ),
+    "--no-description": click.Option(
+        ["--no-description"],
+        is_flag=True,
+        help="Search for photos with no description.",
+    ),
+    "--place": click.Option(
+        ["--place"],
+        metavar="PLACE",
+        default=None,
+        multiple=True,
+        help="Search for PLACE in photo's reverse geolocation info",
+    ),
+    "--no-place": click.Option(
+        ["--no-place"],
+        is_flag=True,
+        help="Search for photos with no associated place name info (no reverse geolocation info)",
+    ),
+    "--location": click.Option(
+        ["--location"],
+        is_flag=True,
+        help="Search for photos with associated location info (e.g. GPS coordinates)",
+    ),
+    "--no-location": click.Option(
+        ["--no-location"],
+        is_flag=True,
+        help="Search for photos with no associated location info (e.g. no GPS coordinates)",
+    ),
+    "--label": click.Option(
+        ["--label"],
+        metavar="LABEL",
+        multiple=True,
+        help="Search for photos with image classification label LABEL (Photos 5+ only). "
+        'If more than one label, treated as "OR", e.g. find photos matching any label',
+    ),
+    "--uti": click.Option(
+        ["--uti"],
+        metavar="UTI",
+        default=None,
+        multiple=False,
+        help="Search for photos whose uniform type identifier (UTI) matches UTI",
+    ),
+    "--ignore_case": click.Option(
+        ["-i", "--ignore-case"],
+        is_flag=True,
+        help="Case insensitive search for title, description, place, keyword, person, or album.",
+    ),
+    "--edited": click.Option(
+        ["--edited"],
+        is_flag=True,
+        help="Search for photos that have been edited.",
+    ),
+    "--not-edited": click.Option(
+        ["--not-edited"],
+        is_flag=True,
+        help="Search for photos that have not been edited.",
+    ),
+    "--external-edit": click.Option(
+        ["--external-edit"],
+        is_flag=True,
+        help="Search for photos edited in external editor.",
+    ),
+    "--favorite": click.Option(
+        ["--favorite"], is_flag=True, help="Search for photos marked favorite."
+    ),
+    "--not-favorite": click.Option(
+        ["--not-favorite"],
+        is_flag=True,
+        help="Search for photos not marked favorite.",
+    ),
+    "--hidden": click.Option(
+        ["--hidden"], is_flag=True, help="Search for photos marked hidden."
+    ),
+    "--not-hidden": click.Option(
+        ["--not-hidden"],
+        is_flag=True,
+        help="Search for photos not marked hidden.",
+    ),
+    "--shared": click.Option(
+        ["--shared"],
+        is_flag=True,
+        help="Search for photos in shared iCloud album (Photos 5+ only).",
+    ),
+    "--not-shared": click.Option(
+        ["--not-shared"],
+        is_flag=True,
+        help="Search for photos not in shared iCloud album (Photos 5+ only).",
+    ),
+    "--burst": click.Option(
+        ["--burst"],
+        is_flag=True,
+        help="Search for photos that were taken in a burst.",
+    ),
+    "--not-burst": click.Option(
+        ["--not-burst"],
+        is_flag=True,
+        help="Search for photos that are not part of a burst.",
+    ),
+    "--live": click.Option(
+        ["--live"], is_flag=True, help="Search for Apple live photos"
+    ),
+    "--not-live": click.Option(
+        ["--not-live"],
+        is_flag=True,
+        help="Search for photos that are not Apple live photos.",
+    ),
+    "--portrait": click.Option(
+        ["--portrait"],
+        is_flag=True,
+        help="Search for Apple portrait mode photos.",
+    ),
+    "--not-portrait": click.Option(
+        ["--not-portrait"],
+        is_flag=True,
+        help="Search for photos that are not Apple portrait mode photos.",
+    ),
+    "--screenshot": click.Option(
+        ["--screenshot"], is_flag=True, help="Search for screenshot photos."
+    ),
+    "--not-screenshot": click.Option(
+        ["--not-screenshot"],
+        is_flag=True,
+        help="Search for photos that are not screenshot photos.",
+    ),
+    "--slow-mo": click.Option(
+        ["--slow-mo"], is_flag=True, help="Search for slow motion videos."
+    ),
+    "--not-slow-mo": click.Option(
+        ["--not-slow-mo"],
+        is_flag=True,
+        help="Search for photos that are not slow motion videos.",
+    ),
+    "--time-lapse": click.Option(
+        ["--time-lapse"], is_flag=True, help="Search for time lapse videos."
+    ),
+    "--not-time-lapse": click.Option(
+        ["--not-time-lapse"],
+        is_flag=True,
+        help="Search for photos that are not time lapse videos.",
+    ),
+    "--hdr": click.Option(
+        ["--hdr"],
+        is_flag=True,
+        help="Search for high dynamic range (HDR) photos.",
+    ),
+    "--not-hdr": click.Option(
+        ["--not-hdr"],
+        is_flag=True,
+        help="Search for photos that are not HDR photos.",
+    ),
+    "--selfie": click.Option(
+        ["--selfie"],
+        is_flag=True,
+        help="Search for selfies (photos taken with front-facing cameras).",
+    ),
+    "--not-selfie": click.Option(
+        ["--not-selfie"],
+        is_flag=True,
+        help="Search for photos that are not selfies.",
+    ),
+    "--panorama": click.Option(
+        ["--panorama"], is_flag=True, help="Search for panorama photos."
+    ),
+    "--not-panorama": click.Option(
+        ["--not-panorama"],
+        is_flag=True,
+        help="Search for photos that are not panoramas.",
+    ),
+    "--has-raw": click.Option(
+        ["--has-raw"],
+        is_flag=True,
+        help="Search for photos with both a jpeg and raw version",
+    ),
+    "--only-movies": click.Option(
+        ["--only-movies"],
+        is_flag=True,
+        help="Search only for movies (default searches both images and movies).",
+    ),
+    "--only-photos": click.Option(
+        ["--only-photos"],
+        is_flag=True,
+        help="Search only for photos/images (default searches both images and movies).",
+    ),
+    "--from-date": click.Option(
+        ["--from-date"],
+        help="Search by item start date, e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).",
+        type=DateTimeISO8601(),
+    ),
+    "--to-date": click.Option(
+        ["--to-date"],
+        help="Search by item end date, e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).",
+        type=DateTimeISO8601(),
+    ),
+    "--from-time": click.Option(
+        ["--from-time"],
+        help="Search by item start time of day, e.g. 12:00, or 12:00:00.",
+        type=TimeISO8601(),
+    ),
+    "--to-time": click.Option(
+        ["--to-time"],
+        help="Search by item end time of day, e.g. 12:00 or 12:00:00.",
+        type=TimeISO8601(),
+    ),
+    "--year": click.Option(
+        ["--year"],
+        metavar="YEAR",
+        help="Search for items from a specific year, e.g. --year 2022 to find all photos from the year 2022. "
+        "May be repeated to search multiple years.",
+        multiple=True,
+        type=int,
+    ),
+    "--added-before": click.Option(
+        ["--added-before"],
+        metavar="DATE",
+        help="Search for items added to the library before a specific date/time, "
+        "e.g. --added-before e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).",
+        type=DateTimeISO8601(),
+    ),
+    "--added-after": click.Option(
+        ["--added-after"],
+        metavar="DATE",
+        help="Search for items added to the libray after a specific date/time, "
+        "e.g. --added-after e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).",
+        type=DateTimeISO8601(),
+    ),
+    "--added-in-last": click.Option(
+        ["--added-in-last"],
+        metavar="TIME_DELTA",
+        help="Search for items added to the library in the last TIME_DELTA, "
+        "where TIME_DELTA is a string like "
+        "'12 hrs', '1 day', '1d', '1 week', '2weeks', '1 month', '1 year'. "
+        "for example, `--added-in-last 7d` and `--added-in-last '1 week'` are equivalent. "
+        "months are assumed to be 30 days and years are assumed to be 365 days. "
+        "Common English abbreviations are accepted, e.g. d, day, days or m, min, minutes.",
+        type=TimeOffset(),
+    ),
+    "--has-comment": click.Option(
+        ["--has-comment"],
+        is_flag=True,
+        help="Search for photos that have comments.",
+    ),
+    "--no-comment": click.Option(
+        ["--no-comment"],
+        is_flag=True,
+        help="Search for photos with no comments.",
+    ),
+    "--has-likes": click.Option(
+        ["--has-likes"], is_flag=True, help="Search for photos that have likes."
+    ),
+    "--no-likes": click.Option(
+        ["--no-likes"], is_flag=True, help="Search for photos with no likes."
+    ),
+    "--is-reference": click.Option(
+        ["--is-reference"],
+        is_flag=True,
+        help="Search for photos that were imported as referenced files (not copied into Photos library).",
+    ),
+    "--not-reference": click.Option(
+        ["--not-reference"],
+        is_flag=True,
+        help="Search for photos that are not references, that is, they were copied into the Photos library "
+        "and are managed by Photos.",
+    ),
+    "--in-album": click.Option(
+        ["--in-album"],
+        is_flag=True,
+        help="Search for photos that are in one or more albums.",
+    ),
+    "--not-in-album": click.Option(
+        ["--not-in-album"],
+        is_flag=True,
+        help="Search for photos that are not in any albums.",
+    ),
+    "--duplicate": click.Option(
+        ["--duplicate"],
+        is_flag=True,
+        help="Search for photos with possible duplicates. osxphotos will compare signatures of photos, "
+        "evaluating date created, size, height, width, and edited status to find *possible* duplicates. "
+        "This does not compare images byte-for-byte nor compare hashes but should find photos imported multiple "
+        "times or duplicated within Photos.",
+    ),
+    "--min-size": click.Option(
+        ["--min-size"],
+        metavar="SIZE",
+        type=BitMathSize(),
+        help="Search for photos with size >= SIZE bytes. "
+        "The size evaluated is the photo's original size (when imported to Photos). "
+        "Size may be specified as integer bytes or using SI or NIST units. "
+        "For example, the following are all valid and equivalent sizes: '1048576' '1.048576MB', '1 MiB'.",
+    ),
+    "--max-size": click.Option(
+        ["--max-size"],
+        metavar="SIZE",
+        type=BitMathSize(),
+        help="Search for photos with size <= SIZE bytes. "
+        "The size evaluated is the photo's original size (when imported to Photos). "
+        "Size may be specified as integer bytes or using SI or NIST units. "
+        "For example, the following are all valid and equivalent sizes: '1048576' '1.048576MB', '1 MiB'.",
+    ),
+    "--missing": click.Option(
+        ["--missing"], is_flag=True, help="Search for photos missing from disk."
+    ),
+    "--not-missing": click.Option(
+        ["--not-missing"],
+        is_flag=True,
+        help="Search for photos present on disk (e.g. not missing).",
+    ),
+    "--cloudasset": click.Option(
+        ["--cloudasset"],
+        is_flag=True,
+        help="Search for photos that are part of an iCloud library",
+    ),
+    "--not-cloudasset": click.Option(
+        ["--not-cloudasset"],
+        is_flag=True,
+        help="Search for photos that are not part of an iCloud library",
+    ),
+    "--incloud": click.Option(
+        ["--incloud"],
+        is_flag=True,
+        help="Search for photos that are in iCloud (have been synched)",
+    ),
+    "--not-incloud": click.Option(
+        ["--not-incloud"],
+        is_flag=True,
+        help="Search for photos that are not in iCloud (have not been synched)",
+    ),
+    "--syndicated": click.Option(
+        ["--syndicated"],
+        is_flag=True,
+        help="Search for photos that have been shared via syndication ('Shared with You' album via Messages, etc.)",
+    ),
+    "--not-syndicated": click.Option(
+        ["--not-syndicated"],
+        is_flag=True,
+        help="Search for photos that have not been shared via syndication ('Shared with You' album via Messages, etc.)",
+    ),
+    "--saved-to-library": click.Option(
+        ["--saved-to-library"],
+        is_flag=True,
+        help="Search for syndicated photos that have saved to the library",
+    ),
+    "--not-saved-to-library": click.Option(
+        ["--not-saved-to-library"],
+        is_flag=True,
+        help="Search for syndicated photos that have not saved to the library",
+    ),
+    "--regex": click.Option(
+        ["--regex"],
+        metavar="REGEX TEMPLATE",
+        nargs=2,
+        multiple=True,
+        help="Search for photos where TEMPLATE matches regular expression REGEX. "
+        "For example, to find photos in an album that begins with 'Beach': '--regex \"^Beach\" \"{album}\"'. "
+        "You may specify more than one regular expression match by repeating '--regex' with different arguments.",
+    ),
+    "--selected": click.Option(
+        ["--selected"],
+        is_flag=True,
+        help="Filter for photos that are currently selected in Photos.",
+        callback=validate_selected,
+    ),
+    "--exif": click.Option(
+        ["--exif"],
+        metavar="EXIF_TAG VALUE",
+        nargs=2,
+        multiple=True,
+        help="Search for photos where EXIF_TAG exists in photo's EXIF data and contains VALUE. "
+        "For example, to find photos created by Adobe Photoshop: `--exif Software 'Adobe Photoshop' `"
+        "or to find all photos shot on a Canon camera: `--exif Make Canon`. "
+        "EXIF_TAG can be any valid exiftool tag, with or without group name, e.g. `EXIF:Make` or `Make`. "
+        "To use --exif, exiftool must be installed and in the path.",
+    ),
+    "--query-eval": click.Option(
+        ["--query-eval"],
+        metavar="CRITERIA",
+        multiple=True,
+        help="Evaluate CRITERIA to filter photos. "
+        "CRITERIA will be evaluated in context of the following python list comprehension: "
+        "`photos = [photo for photo in photos if CRITERIA]` "
+        "where photo represents a PhotoInfo object. "
+        "For example: `--query-eval photo.favorite` returns all photos that have been "
+        "favorited and is equivalent to --favorite. "
+        "You may specify more than one CRITERIA by using --query-eval multiple times. "
+        "CRITERIA must be a valid python expression. "
+        "See https://rhettbull.github.io/osxphotos/ for additional documentation on the PhotoInfo class.",
+    ),
+    "--query-function": click.Option(
+        ["--query-function"],
+        metavar="filename.py::function",
+        multiple=True,
+        type=FunctionCall(),
+        help="Run function to filter photos. Use this in format: --query-function filename.py::function where filename.py is a python "
+        + "file you've created and function is the name of the function in the python file you want to call. "
+        + "Your function will be passed a list of PhotoInfo objects and is expected to return a filtered list of PhotoInfo objects. "
+        + "You may use more than one function by repeating the --query-function option with a different value. "
+        + "Your query function will be called after all other query options have been evaluated. "
+        + "See https://github.com/RhetTbull/osxphotos/blob/master/examples/query_function.py for example of how to use this option.",
+    ),
+}
+
+if not is_macos:
+    del _QUERY_PARAMETERS_DICT["--selected"]
+
+
+def QUERY_OPTIONS(
+    wrapped=None, *, exclude: list[str] | None = None
+) -> Callable[..., Any]:
+    """Function decorator to add query options to a click command.
+
+    Args:
+        wrapped: function to decorate (this is normally passed automatically
+        exclude: list of query options to exclude from the command, for example `exclude=["--shared"]
+    """
+    if wrapped is None:
+        return functools.partial(QUERY_OPTIONS, exclude=exclude)
+
+    exclude = exclude or []
+
+    def _add_options(wrapped):
+        """Add query options to wrapped function"""
+        for option in reversed(_QUERY_PARAMETERS_DICT.keys()):
+            if option in exclude:
+                continue
+            click_opt = _QUERY_PARAMETERS_DICT[option]
+            _param_memo(wrapped, click_opt)
+        return wrapped
+
+    return _add_options(wrapped)
+
+
+_DEBUG_PARAMETERS = [
+    click.Option(
+        ["--debug"],
+        is_flag=True,
+        help="Enable debug output.",
+        hidden=OSXPHOTOS_HIDDEN,
+    ),
+    click.Option(
+        ["--watch"],
+        metavar="MODULE::NAME",
+        multiple=True,
+        help="Watch function or method calls. The function to watch must be in the form "
+        "MODULE::NAME where MODULE is the module path and NAME is the function or method name "
+        "contained in the module. For example, to watch all calls to FileUtil.copy() which is in "
+        "osxphotos.fileutil, use: "
+        "'--watch osxphotos.fileutil::FileUtil.copy'.  More than one --watch option can be specified.",
+        hidden=OSXPHOTOS_HIDDEN,
+    ),
+    click.Option(
+        ["--breakpoint"],
+        metavar="MODULE::NAME",
+        multiple=True,
+        help="Add breakpoint to function calls. The function to watch must be in the form "
+        "MODULE::NAME where MODULE is the module path and NAME is the function or method name "
+        "contained in the module. For example, to set a breakpoint for calls to "
+        "FileUtil.copy() which is in osxphotos.fileutil, use: "
+        "'--breakpoint osxphotos.fileutil::FileUtil.copy'.  More than one --breakpoint option can be specified.",
+        hidden=OSXPHOTOS_HIDDEN,
+    ),
+]
+DEBUG_OPTIONS = make_click_option_decorator(*_DEBUG_PARAMETERS)
+
+_THEME_PARAMETER = click.Option(
+    ["--theme"],
+    metavar="THEME",
+    type=click.Choice(["dark", "light", "mono", "plain"], case_sensitive=False),
+    help="Specify the color theme to use for output. "
+    "Valid themes are 'dark', 'light', 'mono', and 'plain'. "
+    "Defaults to 'dark' or 'light' depending on system dark mode setting.",
+)
+THEME_OPTION = make_click_option_decorator(_THEME_PARAMETER)
+
+_VERBOSE_PARAMETER = click.Option(
+    ["--verbose", "-V", "verbose_flag"],
+    count=True,
+    help="Print verbose output; may be specified multiple times for more verbose output.",
+)
+VERBOSE_OPTION = make_click_option_decorator(_VERBOSE_PARAMETER)
+
+_TIMESTAMP_PARAMETER = click.Option(
+    ["--timestamp"], is_flag=True, help="Add time stamp to verbose output"
+)
+TIMESTAMP_OPTION = make_click_option_decorator(_TIMESTAMP_PARAMETER)
+
+_VERSION_PARAMETER = click.Option(
+    ["--version", "-v", "_version_flag"],
+    is_flag=True,
+    help="Show the version and exit.",
+    callback=print_version,
+)
+
+VERSION_OPTION = make_click_option_decorator(_VERSION_PARAMETER)

osxphotos/cli/click_rich_echo.py

@@ -119,7 +119,9 @@ def rich_echo(
         # if not outputting to terminal, use a huge width to avoid wrapping
         # otherwise tests fail
         width = 10_000
-    console = get_rich_console() or Console(theme=theme, width=width)
+    console = get_rich_console() or Console(
+        theme=theme or get_rich_theme(), width=width
+    )
     if markdown:
         message = Markdown(message)
         # Markdown always adds a new line so disable unless explicitly specified

osxphotos/cli/common.py

@@ -1,9 +1,11 @@
 """Globals and constants use by the CLI commands"""
 
+from __future__ import annotations
 
-import dataclasses
 import os
 import pathlib
+import platform
+import sys
 from datetime import datetime
 
 import click
@@ -11,12 +13,9 @@ from packaging import version
 from xdg import xdg_config_home, xdg_data_home
 
 import osxphotos
-from osxphotos import QueryOptions
 from osxphotos._constants import APP_NAME
 from osxphotos._version import __version__
-from osxphotos.utils import get_latest_version
-
-from .param_types import *
+from osxphotos.utils import get_latest_version, get_macos_version
 
 # used to show/hide hidden commands
 OSXPHOTOS_HIDDEN = not bool(os.getenv("OSXPHOTOS_SHOW_HIDDEN", default=False))
@@ -33,28 +32,12 @@ CLI_COLOR_WARNING = "yellow"
 __all__ = [
     "CLI_COLOR_ERROR",
     "CLI_COLOR_WARNING",
-    "DB_ARGUMENT",
-    "DB_OPTION",
-    "DEBUG_OPTIONS",
-    "DELETED_OPTIONS",
-    "FIELD_OPTION",
-    "JSON_OPTION",
-    "QUERY_OPTIONS",
-    "THEME_OPTION",
     "get_photos_db",
-    "load_uuid_from_file",
     "noop",
-    "query_options_from_kwargs",
     "time_stamp",
 ]
 
 
-class IncompatibleQueryOptions(Exception):
-    """Incompatible query options"""
-
-    pass
-
-
 def noop(*args, **kwargs):
     """no-op function"""
     pass
@@ -98,550 +81,6 @@ def get_photos_db(*db_options):
         return None
 
 
-VERSION_CHECK_OPTION = click.option("--no-version-check", required=False, is_flag=True)
-
-DB_OPTION = click.option(
-    "--db",
-    required=False,
-    metavar="PHOTOS_LIBRARY_PATH",
-    default=None,
-    help=(
-        "Specify Photos database path. "
-        "Path to Photos library/database can be specified using either --db "
-        "or directly as PHOTOS_LIBRARY positional argument. "
-        "If neither --db or PHOTOS_LIBRARY provided, will attempt to find the library "
-        "to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary"
-    ),
-    type=click.Path(exists=True),
-)
-
-DB_ARGUMENT = click.argument("photos_library", nargs=-1, type=click.Path(exists=True))
-
-JSON_OPTION = click.option(
-    "--json",
-    "json_",
-    required=False,
-    is_flag=True,
-    default=False,
-    help="Print output in JSON format.",
-)
-
-FIELD_OPTION = click.option(
-    "--field",
-    "-f",
-    metavar="FIELD TEMPLATE",
-    multiple=True,
-    nargs=2,
-    help="Output only specified custom fields. "
-    "FIELD is the name of the field and TEMPLATE is the template to use as the field value. "
-    "May be repeated to output multiple fields. "
-    "For example, to output photo uuid, name, and title: "
-    '`--field uuid "{uuid}" --field name "{original_name}" --field title "{title}"`.',
-)
-
-
-def DELETED_OPTIONS(f):
-    o = click.option
-    options = [
-        o(
-            "--deleted",
-            is_flag=True,
-            help="Include photos from the 'Recently Deleted' folder.",
-        ),
-        o(
-            "--deleted-only",
-            is_flag=True,
-            help="Include only photos from the 'Recently Deleted' folder.",
-        ),
-    ]
-    for o in options[::-1]:
-        f = o(f)
-    return f
-
-
-def QUERY_OPTIONS(f):
-    o = click.option
-    options = [
-        o(
-            "--keyword",
-            metavar="KEYWORD",
-            default=None,
-            multiple=True,
-            help="Search for photos with keyword KEYWORD. "
-            'If more than one keyword, treated as "OR", e.g. find photos matching any keyword',
-        ),
-        o(
-            "--no-keyword",
-            is_flag=True,
-            help="Search for photos with no keyword.",
-        ),
-        o(
-            "--person",
-            metavar="PERSON",
-            default=None,
-            multiple=True,
-            help="Search for photos with person PERSON. "
-            'If more than one person, treated as "OR", e.g. find photos matching any person',
-        ),
-        o(
-            "--album",
-            metavar="ALBUM",
-            default=None,
-            multiple=True,
-            help="Search for photos in album ALBUM. "
-            'If more than one album, treated as "OR", e.g. find photos matching any album',
-        ),
-        o(
-            "--folder",
-            metavar="FOLDER",
-            default=None,
-            multiple=True,
-            help="Search for photos in an album in folder FOLDER. "
-            'If more than one folder, treated as "OR", e.g. find photos in any FOLDER.  '
-            "Only searches top level folders (e.g. does not look at subfolders)",
-        ),
-        o(
-            "--name",
-            metavar="FILENAME",
-            default=None,
-            multiple=True,
-            help="Search for photos with filename matching FILENAME. "
-            'If more than one --name options is specified, they are treated as "OR", '
-            "e.g. find photos matching any FILENAME. ",
-        ),
-        o(
-            "--uuid",
-            metavar="UUID",
-            default=None,
-            multiple=True,
-            help="Search for photos with UUID(s). "
-            "May be repeated to include multiple UUIDs.",
-        ),
-        o(
-            "--uuid-from-file",
-            metavar="FILE",
-            default=None,
-            multiple=False,
-            help="Search for photos with UUID(s) loaded from FILE. "
-            "Format is a single UUID per line.  Lines preceded with # are ignored.",
-            type=click.Path(exists=True),
-        ),
-        o(
-            "--title",
-            metavar="TITLE",
-            default=None,
-            multiple=True,
-            help="Search for TITLE in title of photo.",
-        ),
-        o("--no-title", is_flag=True, help="Search for photos with no title."),
-        o(
-            "--description",
-            metavar="DESC",
-            default=None,
-            multiple=True,
-            help="Search for DESC in description of photo.",
-        ),
-        o(
-            "--no-description",
-            is_flag=True,
-            help="Search for photos with no description.",
-        ),
-        o(
-            "--place",
-            metavar="PLACE",
-            default=None,
-            multiple=True,
-            help="Search for PLACE in photo's reverse geolocation info",
-        ),
-        o(
-            "--no-place",
-            is_flag=True,
-            help="Search for photos with no associated place name info (no reverse geolocation info)",
-        ),
-        o(
-            "--location",
-            is_flag=True,
-            help="Search for photos with associated location info (e.g. GPS coordinates)",
-        ),
-        o(
-            "--no-location",
-            is_flag=True,
-            help="Search for photos with no associated location info (e.g. no GPS coordinates)",
-        ),
-        o(
-            "--label",
-            metavar="LABEL",
-            multiple=True,
-            help="Search for photos with image classification label LABEL (Photos 5+ only). "
-            'If more than one label, treated as "OR", e.g. find photos matching any label',
-        ),
-        o(
-            "--uti",
-            metavar="UTI",
-            default=None,
-            multiple=False,
-            help="Search for photos whose uniform type identifier (UTI) matches UTI",
-        ),
-        o(
-            "-i",
-            "--ignore-case",
-            is_flag=True,
-            help="Case insensitive search for title, description, place, keyword, person, or album.",
-        ),
-        o("--edited", is_flag=True, help="Search for photos that have been edited."),
-        o(
-            "--external-edit",
-            is_flag=True,
-            help="Search for photos edited in external editor.",
-        ),
-        o("--favorite", is_flag=True, help="Search for photos marked favorite."),
-        o(
-            "--not-favorite",
-            is_flag=True,
-            help="Search for photos not marked favorite.",
-        ),
-        o("--hidden", is_flag=True, help="Search for photos marked hidden."),
-        o("--not-hidden", is_flag=True, help="Search for photos not marked hidden."),
-        o(
-            "--shared",
-            is_flag=True,
-            help="Search for photos in shared iCloud album (Photos 5+ only).",
-        ),
-        o(
-            "--not-shared",
-            is_flag=True,
-            help="Search for photos not in shared iCloud album (Photos 5+ only).",
-        ),
-        o(
-            "--burst",
-            is_flag=True,
-            help="Search for photos that were taken in a burst.",
-        ),
-        o(
-            "--not-burst",
-            is_flag=True,
-            help="Search for photos that are not part of a burst.",
-        ),
-        o("--live", is_flag=True, help="Search for Apple live photos"),
-        o(
-            "--not-live",
-            is_flag=True,
-            help="Search for photos that are not Apple live photos.",
-        ),
-        o("--portrait", is_flag=True, help="Search for Apple portrait mode photos."),
-        o(
-            "--not-portrait",
-            is_flag=True,
-            help="Search for photos that are not Apple portrait mode photos.",
-        ),
-        o("--screenshot", is_flag=True, help="Search for screenshot photos."),
-        o(
-            "--not-screenshot",
-            is_flag=True,
-            help="Search for photos that are not screenshot photos.",
-        ),
-        o("--slow-mo", is_flag=True, help="Search for slow motion videos."),
-        o(
-            "--not-slow-mo",
-            is_flag=True,
-            help="Search for photos that are not slow motion videos.",
-        ),
-        o("--time-lapse", is_flag=True, help="Search for time lapse videos."),
-        o(
-            "--not-time-lapse",
-            is_flag=True,
-            help="Search for photos that are not time lapse videos.",
-        ),
-        o("--hdr", is_flag=True, help="Search for high dynamic range (HDR) photos."),
-        o("--not-hdr", is_flag=True, help="Search for photos that are not HDR photos."),
-        o(
-            "--selfie",
-            is_flag=True,
-            help="Search for selfies (photos taken with front-facing cameras).",
-        ),
-        o("--not-selfie", is_flag=True, help="Search for photos that are not selfies."),
-        o("--panorama", is_flag=True, help="Search for panorama photos."),
-        o(
-            "--not-panorama",
-            is_flag=True,
-            help="Search for photos that are not panoramas.",
-        ),
-        o(
-            "--has-raw",
-            is_flag=True,
-            help="Search for photos with both a jpeg and raw version",
-        ),
-        o(
-            "--only-movies",
-            is_flag=True,
-            help="Search only for movies (default searches both images and movies).",
-        ),
-        o(
-            "--only-photos",
-            is_flag=True,
-            help="Search only for photos/images (default searches both images and movies).",
-        ),
-        o(
-            "--from-date",
-            help="Search by item start date, e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).",
-            type=DateTimeISO8601(),
-        ),
-        o(
-            "--to-date",
-            help="Search by item end date, e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).",
-            type=DateTimeISO8601(),
-        ),
-        o(
-            "--from-time",
-            help="Search by item start time of day, e.g. 12:00, or 12:00:00.",
-            type=TimeISO8601(),
-        ),
-        o(
-            "--to-time",
-            help="Search by item end time of day, e.g. 12:00 or 12:00:00.",
-            type=TimeISO8601(),
-        ),
-        o(
-            "--year",
-            metavar="YEAR",
-            help="Search for items from a specific year, e.g. --year 2022 to find all photos from the year 2022. "
-            "May be repeated to search multiple years.",
-            multiple=True,
-            type=int,
-        ),
-        o(
-            "--added-before",
-            metavar="DATE",
-            help="Search for items added to the library before a specific date/time, "
-            "e.g. --added-before e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).",
-            type=DateTimeISO8601(),
-        ),
-        o(
-            "--added-after",
-            metavar="DATE",
-            help="Search for items added to the libray after a specific date/time, "
-            "e.g. --added-after e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).",
-            type=DateTimeISO8601(),
-        ),
-        o(
-            "--added-in-last",
-            metavar="TIME_DELTA",
-            help="Search for items added to the library in the last TIME_DELTA, "
-            "where TIME_DELTA is a string like "
-            "'12 hrs', '1 day', '1d', '1 week', '2weeks', '1 month', '1 year'. "
-            "for example, `--added-in-last 7d` and `--added-in-last '1 week'` are equivalent. "
-            "months are assumed to be 30 days and years are assumed to be 365 days. "
-            "Common English abbreviations are accepted, e.g. d, day, days or m, min, minutes.",
-            type=TimeOffset(),
-        ),
-        o("--has-comment", is_flag=True, help="Search for photos that have comments."),
-        o("--no-comment", is_flag=True, help="Search for photos with no comments."),
-        o("--has-likes", is_flag=True, help="Search for photos that have likes."),
-        o("--no-likes", is_flag=True, help="Search for photos with no likes."),
-        o(
-            "--is-reference",
-            is_flag=True,
-            help="Search for photos that were imported as referenced files (not copied into Photos library).",
-        ),
-        o(
-            "--not-reference",
-            is_flag=True,
-            help="Search for photos that are not references, that is, they were copied into the Photos library "
-            "and are managed by Photos.",
-        ),
-        o(
-            "--in-album",
-            is_flag=True,
-            help="Search for photos that are in one or more albums.",
-        ),
-        o(
-            "--not-in-album",
-            is_flag=True,
-            help="Search for photos that are not in any albums.",
-        ),
-        o(
-            "--duplicate",
-            is_flag=True,
-            help="Search for photos with possible duplicates. osxphotos will compare signatures of photos, "
-            "evaluating date created, size, height, width, and edited status to find *possible* duplicates. "
-            "This does not compare images byte-for-byte nor compare hashes but should find photos imported multiple "
-            "times or duplicated within Photos.",
-        ),
-        o(
-            "--min-size",
-            metavar="SIZE",
-            type=BitMathSize(),
-            help="Search for photos with size >= SIZE bytes. "
-            "The size evaluated is the photo's original size (when imported to Photos). "
-            "Size may be specified as integer bytes or using SI or NIST units. "
-            "For example, the following are all valid and equivalent sizes: '1048576' '1.048576MB', '1 MiB'.",
-        ),
-        o(
-            "--max-size",
-            metavar="SIZE",
-            type=BitMathSize(),
-            help="Search for photos with size <= SIZE bytes. "
-            "The size evaluated is the photo's original size (when imported to Photos). "
-            "Size may be specified as integer bytes or using SI or NIST units. "
-            "For example, the following are all valid and equivalent sizes: '1048576' '1.048576MB', '1 MiB'.",
-        ),
-        o("--missing", is_flag=True, help="Search for photos missing from disk."),
-        o(
-            "--not-missing",
-            is_flag=True,
-            help="Search for photos present on disk (e.g. not missing).",
-        ),
-        o(
-            "--cloudasset",
-            is_flag=True,
-            help="Search for photos that are part of an iCloud library",
-        ),
-        o(
-            "--not-cloudasset",
-            is_flag=True,
-            help="Search for photos that are not part of an iCloud library",
-        ),
-        o(
-            "--incloud",
-            is_flag=True,
-            help="Search for photos that are in iCloud (have been synched)",
-        ),
-        o(
-            "--not-incloud",
-            is_flag=True,
-            help="Search for photos that are not in iCloud (have not been synched)",
-        ),
-        o(
-            "--regex",
-            metavar="REGEX TEMPLATE",
-            nargs=2,
-            multiple=True,
-            help="Search for photos where TEMPLATE matches regular expression REGEX. "
-            "For example, to find photos in an album that begins with 'Beach': '--regex \"^Beach\" \"{album}\"'. "
-            "You may specify more than one regular expression match by repeating '--regex' with different arguments.",
-        ),
-        o(
-            "--selected",
-            is_flag=True,
-            help="Filter for photos that are currently selected in Photos.",
-        ),
-        o(
-            "--exif",
-            metavar="EXIF_TAG VALUE",
-            nargs=2,
-            multiple=True,
-            help="Search for photos where EXIF_TAG exists in photo's EXIF data and contains VALUE. "
-            "For example, to find photos created by Adobe Photoshop: `--exif Software 'Adobe Photoshop' `"
-            "or to find all photos shot on a Canon camera: `--exif Make Canon`. "
-            "EXIF_TAG can be any valid exiftool tag, with or without group name, e.g. `EXIF:Make` or `Make`. "
-            "To use --exif, exiftool must be installed and in the path.",
-        ),
-        o(
-            "--query-eval",
-            metavar="CRITERIA",
-            multiple=True,
-            help="Evaluate CRITERIA to filter photos. "
-            "CRITERIA will be evaluated in context of the following python list comprehension: "
-            "`photos = [photo for photo in photos if CRITERIA]` "
-            "where photo represents a PhotoInfo object. "
-            "For example: `--query-eval photo.favorite` returns all photos that have been "
-            "favorited and is equivalent to --favorite. "
-            "You may specify more than one CRITERIA by using --query-eval multiple times. "
-            "CRITERIA must be a valid python expression. "
-            "See https://rhettbull.github.io/osxphotos/ for additional documentation on the PhotoInfo class.",
-        ),
-        o(
-            "--query-function",
-            metavar="filename.py::function",
-            multiple=True,
-            type=FunctionCall(),
-            help="Run function to filter photos. Use this in format: --query-function filename.py::function where filename.py is a python "
-            + "file you've created and function is the name of the function in the python file you want to call. "
-            + "Your function will be passed a list of PhotoInfo objects and is expected to return a filtered list of PhotoInfo objects. "
-            + "You may use more than one function by repeating the --query-function option with a different value. "
-            + "Your query function will be called after all other query options have been evaluated. "
-            + "See https://github.com/RhetTbull/osxphotos/blob/master/examples/query_function.py for example of how to use this option.",
-        ),
-    ]
-    for o in options[::-1]:
-        f = o(f)
-    return f
-
-
-def DEBUG_OPTIONS(f):
-    o = click.option
-    options = [
-        o(
-            "--debug",
-            is_flag=True,
-            help="Enable debug output.",
-            hidden=OSXPHOTOS_HIDDEN,
-        ),
-        o(
-            "--watch",
-            metavar="MODULE::NAME",
-            multiple=True,
-            help="Watch function or method calls. The function to watch must be in the form "
-            "MODULE::NAME where MODULE is the module path and NAME is the function or method name "
-            "contained in the module. For example, to watch all calls to FileUtil.copy() which is in "
-            "osxphotos.fileutil, use: "
-            "'--watch osxphotos.fileutil::FileUtil.copy'.  More than one --watch option can be specified.",
-            hidden=OSXPHOTOS_HIDDEN,
-        ),
-        o(
-            "--breakpoint",
-            metavar="MODULE::NAME",
-            multiple=True,
-            help="Add breakpoint to function calls. The function to watch must be in the form "
-            "MODULE::NAME where MODULE is the module path and NAME is the function or method name "
-            "contained in the module. For example, to set a breakpoint for calls to "
-            "FileUtil.copy() which is in osxphotos.fileutil, use: "
-            "'--breakpoint osxphotos.fileutil::FileUtil.copy'.  More than one --breakpoint option can be specified.",
-            hidden=OSXPHOTOS_HIDDEN,
-        ),
-    ]
-    for o in options[::-1]:
-        f = o(f)
-    return f
-
-
-THEME_OPTION = click.option(
-    "--theme",
-    metavar="THEME",
-    type=click.Choice(["dark", "light", "mono", "plain"], case_sensitive=False),
-    help="Specify the color theme to use for --verbose output. "
-    "Valid themes are 'dark', 'light', 'mono', and 'plain'. "
-    "Defaults to 'dark' or 'light' depending on system dark mode setting.",
-)
-
-
-def load_uuid_from_file(filename):
-    """Load UUIDs from file.  Does not validate UUIDs.
-        Format is 1 UUID per line, any line beginning with # is ignored.
-        Whitespace is stripped.
-
-    Arguments:
-        filename: file name of the file containing UUIDs
-
-    Returns:
-        list of UUIDs or empty list of no UUIDs in file
-
-    Raises:
-        FileNotFoundError if file does not exist
-    """
-
-    if not pathlib.Path(filename).is_file():
-        raise FileNotFoundError(f"Could not find file {filename}")
-
-    uuid = []
-    with open(filename, "r") as uuid_file:
-        for line in uuid_file:
-            line = line.strip()
-            if len(line) and line[0] != "#":
-                uuid.append(line)
-    return uuid
-
-
 def get_config_dir() -> pathlib.Path:
     """Get the directory where config files are stored; create it if necessary."""
     config_dir = xdg_config_home() / APP_NAME
@@ -671,101 +110,11 @@ def check_version():
         )
 
 
-def query_options_from_kwargs(**kwargs) -> QueryOptions:
-    """Validate query options and create a QueryOptions instance"""
-    # sanity check input args
-    nonexclusive = [
-        "added_after",
-        "added_before",
-        "added_in_last",
-        "album",
-        "duplicate",
-        "edited",
-        "exif",
-        "external_edit",
-        "folder",
-        "from_date",
-        "from_time",
-        "has_raw",
-        "keyword",
-        "label",
-        "max_size",
-        "min_size",
-        "name",
-        "person",
-        "query_eval",
-        "query_function",
-        "regex",
-        "selected",
-        "to_date",
-        "to_time",
-        "uti",
-        "uuid_from_file",
-        "uuid",
-        "year",
-    ]
-    exclusive = [
-        ("burst", "not_burst"),
-        ("cloudasset", "not_cloudasset"),
-        ("favorite", "not_favorite"),
-        ("has_comment", "no_comment"),
-        ("has_likes", "no_likes"),
-        ("hdr", "not_hdr"),
-        ("hidden", "not_hidden"),
-        ("in_album", "not_in_album"),
-        ("incloud", "not_incloud"),
-        ("live", "not_live"),
-        ("location", "no_location"),
-        ("keyword", "no_keyword"),
-        ("missing", "not_missing"),
-        ("only_photos", "only_movies"),
-        ("panorama", "not_panorama"),
-        ("portrait", "not_portrait"),
-        ("screenshot", "not_screenshot"),
-        ("selfie", "not_selfie"),
-        ("shared", "not_shared"),
-        ("slow_mo", "not_slow_mo"),
-        ("time_lapse", "not_time_lapse"),
-        ("is_reference", "not_reference"),
-    ]
-    # print help if no non-exclusive term or a double exclusive term is given
-    # TODO: add option to validate requiring at least one query arg
-    if any(all([kwargs[b], kwargs[n]]) for b, n in exclusive) or any(
-        [
-            all([any(kwargs["title"]), kwargs["no_title"]]),
-            all([any(kwargs["description"]), kwargs["no_description"]]),
-            all([any(kwargs["place"]), kwargs["no_place"]]),
-            all([any(kwargs["keyword"]), kwargs["no_keyword"]]),
-        ]
-    ):
-        raise IncompatibleQueryOptions
-
-    # can also be used with --deleted/--not-deleted which are not part of
-    # standard query options
-    try:
-        if kwargs["deleted"] and kwargs["not_deleted"]:
-            raise IncompatibleQueryOptions
-    except KeyError:
-        pass
-
-    # actually have something to query
-    include_photos = True
-    include_movies = True  # default searches for everything
-    if kwargs["only_movies"]:
-        include_photos = False
-    if kwargs["only_photos"]:
-        include_movies = False
-
-    # load UUIDs if necessary and append to any uuids passed with --uuid
-    uuid = None
-    if kwargs["uuid_from_file"]:
-        uuid_list = list(kwargs["uuid"])  # Click option is a tuple
-        uuid_list.extend(load_uuid_from_file(kwargs["uuid_from_file"]))
-        uuid = tuple(uuid_list)
-
-    query_fields = [field.name for field in dataclasses.fields(QueryOptions)]
-    query_dict = {field: kwargs.get(field) for field in query_fields}
-    query_dict["photos"] = include_photos
-    query_dict["movies"] = include_movies
-    query_dict["uuid"] = uuid
-    return QueryOptions(**query_dict)
+def print_version(ctx, param, value):
+    """Print version, this is a callback for the --version option"""
+    if not value:
+        return
+    click.echo(f"osxphotos, version {__version__}")
+    click.echo(f"Python {sys.version}")
+    click.echo(f"macOS {'.'.join(get_macos_version())}, {platform.machine()}")
+    ctx.exit()

osxphotos/cli/darkmode.py

@@ -1,19 +1,31 @@
-"""Detect dark mode on MacOS >= 10.14"""
+"""Detect dark mode on MacOS >= 10.14 or fake it elsewhere"""
 
-import objc
-import Foundation
+from osxphotos.utils import is_macos
 
 
-def theme():
-    with objc.autorelease_pool():
-        user_defaults = Foundation.NSUserDefaults.standardUserDefaults()
-        system_theme = user_defaults.stringForKey_("AppleInterfaceStyle")
-        return "dark" if system_theme == "Dark" else "light"
+if is_macos:
+    import objc
+    import Foundation
 
+    def theme():
+        with objc.autorelease_pool():
+            user_defaults = Foundation.NSUserDefaults.standardUserDefaults()
+            system_theme = user_defaults.stringForKey_("AppleInterfaceStyle")
+            return "dark" if system_theme == "Dark" else "light"
 
-def is_dark_mode():
-    return theme() == "dark"
+    def is_dark_mode():
+        return theme() == "dark"
 
+    def is_light_mode():
+        return theme() == "light"
 
-def is_light_mode():
-    return theme() == "light"
+else:
+
+    def theme():
+        return "light"
+
+    def is_dark_mode():
+        return theme() == "dark"
+
+    def is_light_mode():
+        return theme() == "light"

osxphotos/cli/debug_dump.py

@@ -8,8 +8,17 @@ from rich import print
 
 import osxphotos
 from osxphotos._constants import _PHOTOS_4_VERSION, _UNKNOWN_PLACE
+from osxphotos.queryoptions import query_options_from_kwargs
 
-from .common import DB_ARGUMENT, DB_OPTION, JSON_OPTION, OSXPHOTOS_HIDDEN, get_photos_db
+from .cli_params import (
+    DB_ARGUMENT,
+    DB_OPTION,
+    JSON_OPTION,
+    QUERY_OPTIONS,
+    TIMESTAMP_OPTION,
+    VERBOSE_OPTION,
+)
+from .common import OSXPHOTOS_HIDDEN, get_photos_db
 from .list import _list_libraries
 from .verbose import verbose_print
 
@@ -24,30 +33,35 @@ from .verbose import verbose_print
     + "can also use albums, persons, keywords, photos to dump related attributes.",
     multiple=True,
 )
-@click.option(
-    "--uuid",
-    metavar="UUID",
-    help="Use with '--dump photos' to dump only certain UUIDs. "
-    "May be repeated to include multiple UUIDs.",
-    multiple=True,
-)
-@click.option("--verbose", "-V", "verbose", is_flag=True, help="Print verbose output.")
+@VERBOSE_OPTION
+@TIMESTAMP_OPTION
+@QUERY_OPTIONS
 @click.pass_obj
 @click.pass_context
-def debug_dump(ctx, cli_obj, db, photos_library, dump, uuid, verbose):
-    """Print out debug info"""
+def debug_dump(
+    ctx, cli_obj, db, photos_library, dump, verbose_flag, timestamp, **kwargs
+):
+    """Print out debug info.
 
-    verbose_ = verbose_print(verbose, rich=True)
-    db = get_photos_db(*photos_library, db, cli_obj.db)
+    When run with --dump photos, any of the query options can be used to limit the
+    photos printed.  For example, to print info on currently selected photos:
+
+    osxphotos debug-dump --dump photos --selected
+    """
+
+    verbose = verbose_print(verbose_flag, timestamp)
+    db = get_photos_db(*photos_library, db, cli_obj.db if cli_obj else None)
     if db is None:
         click.echo(ctx.obj.group.commands["debug-dump"].get_help(ctx), err=True)
         click.echo("\n\nLocated the following Photos library databases: ", err=True)
         _list_libraries()
         return
 
+    query_options = query_options_from_kwargs(**kwargs)
+
     start_t = time.perf_counter()
     print(f"Opening database: {db}")
-    photosdb = osxphotos.PhotosDB(dbfile=db, verbose=verbose_)
+    photosdb = osxphotos.PhotosDB(dbfile=db, verbose=verbose)
     stop_t = time.perf_counter()
     print(f"Done; took {(stop_t-start_t):.2f} seconds")
 
@@ -78,16 +92,14 @@ def debug_dump(ctx, cli_obj, db, photos_library, dump, uuid, verbose):
             print("_dbpersons_fullname:")
             pprint.pprint(photosdb._dbpersons_fullname)
         elif attr == "photos":
-            if uuid:
-                for uuid_ in uuid:
-                    print(f"_dbphotos['{uuid_}']:")
-                    try:
-                        pprint.pprint(photosdb._dbphotos[uuid_])
-                    except KeyError:
-                        print(f"Did not find uuid {uuid_} in _dbphotos")
-            else:
-                print("_dbphotos:")
-                pprint.pprint(photosdb._dbphotos)
+            photos = photosdb.query(options=query_options)
+            uuid = [photo.uuid for photo in photos]
+            for uuid_ in uuid:
+                print(f"_dbphotos['{uuid_}']:")
+                try:
+                    pprint.pprint(photosdb._dbphotos[uuid_])
+                except KeyError:
+                    print(f"Did not find uuid {uuid_} in _dbphotos")
         else:
             try:
                 val = getattr(photosdb, attr)

osxphotos/cli/docs.py

@@ -13,10 +13,10 @@ from osxphotos._version import __version__
 from .common import get_config_dir, get_data_dir
 
 
-@click.command()
+@click.command(name="docs")
 @click.pass_obj
 @click.pass_context
-def docs(ctx, cli_obj):
+def docs_command(ctx, cli_obj):
     """Open osxphotos documentation in your browser."""
 
     # first check if docs installed in old location in confir dir and if so, delete them

osxphotos/cli/dump.py

@@ -11,15 +11,15 @@ from osxphotos.cli.click_rich_echo import (
 from osxphotos.phototemplate import RenderOptions
 from osxphotos.queryoptions import QueryOptions
 
-from .color_themes import get_default_theme
-from .common import (
+from .cli_params import (
     DB_ARGUMENT,
     DB_OPTION,
     DELETED_OPTIONS,
     FIELD_OPTION,
     JSON_OPTION,
-    get_photos_db,
 )
+from .color_themes import get_default_theme
+from .common import get_photos_db
 from .list import _list_libraries
 from .print_photo_info import print_photo_fields, print_photo_info
 from .verbose import get_verbose_console
@@ -56,7 +56,11 @@ def dump(
     photos_library,
     print_template,
 ):
-    """Print list of all photos & associated info from the Photos library."""
+    """Print list of all photos & associated info from the Photos library.
+
+    NOTE: dump is DEPRECATED and will be removed in a future release.
+    Use `osxphotos query` instead.
+    """
 
     # below needed for to make CliRunner work for testing
     cli_db = cli_obj.db if cli_obj is not None else None

osxphotos/cli/exiftool_cli.py

@@ -17,15 +17,9 @@ from osxphotos.fileutil import FileUtil, FileUtilNoOp
 from osxphotos.photoexporter import ExportOptions, ExportResults, PhotoExporter
 from osxphotos.utils import pluralize
 
-from .click_rich_echo import (
-    rich_click_echo,
-    rich_echo_error,
-    set_rich_console,
-    set_rich_theme,
-    set_rich_timestamp,
-)
-from .color_themes import get_theme
-from .common import DB_OPTION, THEME_OPTION, get_photos_db
+from .cli_params import DB_OPTION, THEME_OPTION, TIMESTAMP_OPTION, VERBOSE_OPTION
+from .click_rich_echo import rich_click_echo, rich_echo_error
+from .common import get_photos_db
 from .export import export, render_and_validate_report
 from .param_types import ExportDBType, TemplateString
 from .report_writer import ReportWriterNoOp, export_report_writer_factory
@@ -166,8 +160,8 @@ from .verbose import get_verbose_console, verbose_print
     help="If used with --report, add data to existing report file instead of overwriting it. "
     "See also --report.",
 )
-@click.option("--verbose", "-V", is_flag=True, help="Print verbose output.")
-@click.option("--timestamp", is_flag=True, help="Add time stamp to verbose output")
+@VERBOSE_OPTION
+@TIMESTAMP_OPTION
 @click.option(
     "--dry-run",
     is_flag=True,
@@ -203,7 +197,7 @@ def exiftool(
     save_config,
     theme,
     timestamp,
-    verbose,
+    verbose_flag,
 ):
     """Run exiftool on previously exported files to update metadata.
 
@@ -235,6 +229,7 @@ def exiftool(
 
     # need to ensure --exiftool is true in the config options
     locals_["exiftool"] = True
+    locals_["verbose"] = verbose_flag
     config = ConfigOptions(
         "export",
         locals_,
@@ -249,14 +244,7 @@ def exiftool(
             "save_config",
         ],
     )
-    color_theme = get_theme(theme)
-    verbose_ = verbose_print(
-        verbose, timestamp, rich=True, theme=color_theme, highlight=False
-    )
-    # set console for rich_echo to be same as for verbose_
-    set_rich_console(get_verbose_console())
-    set_rich_theme(color_theme)
-    set_rich_timestamp(timestamp)
+    verbose = verbose_print(verbose_flag, timestamp, theme=theme)
 
     # load config options from either file or export database
     # values already set in config will take precedence over any values
@@ -269,26 +257,16 @@ def exiftool(
                 f"[error]Error parsing {load_config} config file: {e.message}", err=True
             )
             sys.exit(1)
-        verbose_(f"Loaded options from file [filepath]{load_config}")
+        verbose(f"Loaded options from file [filepath]{load_config}")
     elif db_config:
         config = export_db_get_config(exportdb, config)
-        verbose_("Loaded options from export database")
+        verbose("Loaded options from export database")
 
     # from here on out, use config.param_name instead of using the params passed into the function
     # as the values may have been updated from config file or database
     if load_config or db_config:
         # config file might have changed verbose
-        color_theme = get_theme(config.theme)
-        verbose_ = verbose_print(
-            config.verbose,
-            config.timestamp,
-            rich=True,
-            theme=color_theme,
-            highlight=False,
-        )
-        # set console for rich_echo to be same as for verbose_
-        set_rich_console(get_verbose_console())
-        set_rich_timestamp(config.timestamp)
+        verbose = verbose_print(config.verbose, config.timestamp, theme=theme)
 
     # validate options
     if append and not report:
@@ -298,14 +276,14 @@ def exiftool(
     config.db = get_photos_db(config.db)
 
     if save_config:
-        verbose_(f"Saving options to config file '[filepath]{save_config}'")
+        verbose(f"Saving options to config file '[filepath]{save_config}'")
         config.write_to_file(save_config)
 
-    process_files(exportdb, export_dir, verbose=verbose_, options=config)
+    process_files(exportdb, export_dir, verbose=verbose, options=config)
 
 
 def process_files(
-    exportdb: str, export_dir: str, verbose: Callable, options: ConfigOptions
+    exportdb: str, export_dir: str, verbose: Callable[..., None], options: ConfigOptions
 ):
     """Process files in the export database.
 
@@ -362,6 +340,12 @@ def process_files(
                 hardlink_ok = True
             verbose(f"Processing file [filepath]{file}[/] ([num]{count}/{total}[/num])")
             photo = photosdb.get_photo(uuid)
+            if not photo:
+                verbose(
+                    f"Could not find photo for [filepath]{file}[/] ([uuid]{uuid}[/])"
+                )
+                report_writer.write(ExportResults(missing=[file]))
+                continue
             export_options = ExportOptions(
                 description_template=options.description_template,
                 dry_run=options.dry_run,

osxphotos/cli/export.py

@@ -1,7 +1,10 @@
 """export command for osxphotos CLI"""
 
+import atexit
+import inspect
 import os
 import pathlib
+import platform
 import shlex
 import subprocess
 import sys
@@ -9,13 +12,6 @@ import time
 from typing import Iterable, List, Optional, Tuple
 
 import click
-from osxmetadata import (
-    MDITEM_ATTRIBUTE_DATA,
-    MDITEM_ATTRIBUTE_SHORT_NAMES,
-    OSXMetaData,
-    Tag,
-)
-from osxmetadata.constants import _TAGS_NAMES
 
 import osxphotos
 from osxphotos._constants import (
@@ -44,42 +40,55 @@ from osxphotos.datetime_formatter import DateTimeFormatter
 from osxphotos.debug import is_debug
 from osxphotos.exiftool import get_exiftool_path
 from osxphotos.export_db import ExportDB, ExportDBInMemory
-from osxphotos.fileutil import FileUtil, FileUtilNoOp, FileUtilShUtil
+from osxphotos.fileutil import FileUtilMacOS, FileUtilNoOp, FileUtilShUtil
 from osxphotos.path_utils import is_valid_filepath, sanitize_filename, sanitize_filepath
 from osxphotos.photoexporter import ExportOptions, ExportResults, PhotoExporter
 from osxphotos.photoinfo import PhotoInfoNone
-from osxphotos.photokit import (
-    check_photokit_authorization,
-    request_photokit_authorization,
-)
-from osxphotos.photosalbum import PhotosAlbum
 from osxphotos.phototemplate import PhotoTemplate, RenderOptions
-from osxphotos.queryoptions import QueryOptions
+from osxphotos.queryoptions import load_uuid_from_file, query_options_from_kwargs
 from osxphotos.uti import get_preferred_uti_extension
-from osxphotos.utils import format_sec_to_hhmmss, normalize_fs_path, pluralize
-
-from .click_rich_echo import (
-    rich_click_echo,
-    rich_echo,
-    rich_echo_error,
-    set_rich_console,
-    set_rich_theme,
-    set_rich_timestamp,
+from osxphotos.utils import (
+    format_sec_to_hhmmss,
+    get_macos_version,
+    is_macos,
+    normalize_fs_path,
+    pluralize,
+    under_test,
 )
-from .color_themes import get_theme
-from .common import (
-    CLI_COLOR_ERROR,
-    CLI_COLOR_WARNING,
+
+if is_macos:
+    from osxmetadata import (
+        MDITEM_ATTRIBUTE_DATA,
+        MDITEM_ATTRIBUTE_SHORT_NAMES,
+        OSXMetaData,
+        Tag,
+    )
+    from osxmetadata.constants import _TAGS_NAMES
+
+    from osxphotos.photokit import (
+        check_photokit_authorization,
+        request_photokit_authorization,
+    )
+    from osxphotos.photosalbum import PhotosAlbum
+
+from .cli_commands import logger
+from .cli_params import (
     DB_ARGUMENT,
     DB_OPTION,
     DELETED_OPTIONS,
     JSON_OPTION,
-    OSXPHOTOS_CRASH_LOG,
-    OSXPHOTOS_HIDDEN,
     QUERY_OPTIONS,
     THEME_OPTION,
+    TIMESTAMP_OPTION,
+    VERBOSE_OPTION,
+)
+from .click_rich_echo import rich_click_echo, rich_echo, rich_echo_error
+from .common import (
+    CLI_COLOR_ERROR,
+    CLI_COLOR_WARNING,
+    OSXPHOTOS_CRASH_LOG,
+    OSXPHOTOS_HIDDEN,
     get_photos_db,
-    load_uuid_from_file,
     noop,
 )
 from .help import ExportCommand, get_help_msg
@@ -87,13 +96,13 @@ from .list import _list_libraries
 from .param_types import ExportDBType, FunctionCall, TemplateString
 from .report_writer import ReportWriterNoOp, export_report_writer_factory
 from .rich_progress import rich_progress
-from .verbose import get_verbose_console, time_stamp, verbose_print
+from .verbose import get_verbose_console, verbose_print
 
 
 @click.command(cls=ExportCommand)
 @DB_OPTION
-@click.option("--verbose", "-V", "verbose", is_flag=True, help="Print verbose output.")
-@click.option("--timestamp", is_flag=True, help="Add time stamp to verbose output")
+@VERBOSE_OPTION
+@TIMESTAMP_OPTION
 @click.option(
     "--no-progress", is_flag=True, help="Do not display progress bar during export."
 )
@@ -805,6 +814,7 @@ def export(
     no_title,
     not_burst,
     not_cloudasset,
+    not_edited,
     not_favorite,
     not_hdr,
     not_hidden,
@@ -845,7 +855,6 @@ def export(
     retry,
     save_config,
     screenshot,
-    selected,
     selfie,
     shared,
     sidecar,
@@ -874,9 +883,14 @@ def export(
     uti,
     uuid,
     uuid_from_file,
-    verbose,
+    verbose_flag,
     xattr_template,
     year,
+    syndicated,
+    not_syndicated,
+    saved_to_library,
+    not_saved_to_library,
+    selected=False,  # Isn't provided on unsupported platforms
     # debug,  # debug, watch, breakpoint handled in cli/__init__.py
     # watch,
     # breakpoint,
@@ -905,7 +919,12 @@ def export(
 
     # capture locals for use with ConfigOptions before changing any of them
     locals_ = locals()
-    set_crash_data("locals", locals_)
+    crash_data = locals_.copy()
+    set_crash_data("locals", crash_data)
+
+    # config expects --verbose to be named "verbose" not "verbose_flag"
+    locals_["verbose"] = verbose_flag
+    del locals_["verbose_flag"]
 
     # NOTE: because of the way ConfigOptions works, Click options must not
     # set defaults which are not None or False. If defaults need to be set
@@ -916,14 +935,7 @@ def export(
         ignore=["ctx", "cli_obj", "dest", "load_config", "save_config", "config_only"],
     )
 
-    color_theme = get_theme(theme)
-    verbose_ = verbose_print(
-        verbose, timestamp, rich=True, theme=color_theme, highlight=False
-    )
-    # set console for rich_echo to be same as for verbose_
-    set_rich_console(get_verbose_console())
-    set_rich_theme(color_theme)
-    set_rich_timestamp(timestamp)
+    verbose = verbose_print(verbose=verbose_flag, timestamp=timestamp, theme=theme)
 
     if load_config:
         try:
@@ -943,7 +955,8 @@ def export(
 
         # re-set the local vars to the corresponding config value
         # this isn't elegant but avoids having to rewrite this function to use cfg.varname for every parameter
-
+        # the query options appear to be unaccessed but they are used below by query_options_from_kwargs
+        # which accesses them via locals() to avoid a long list of parameters
         add_exported_to_album = cfg.add_exported_to_album
         add_missing_to_album = cfg.add_missing_to_album
         add_skipped_to_album = cfg.add_skipped_to_album
@@ -1024,6 +1037,7 @@ def export(
         no_title = cfg.no_title
         not_burst = cfg.not_burst
         not_cloudasset = cfg.not_cloudasset
+        not_edited = cfg.not_edited
         not_favorite = cfg.not_favorite
         not_hdr = cfg.not_hdr
         not_hidden = cfg.not_hidden
@@ -1093,23 +1107,28 @@ def export(
         uti = cfg.uti
         uuid = cfg.uuid
         uuid_from_file = cfg.uuid_from_file
-        verbose = cfg.verbose
+        # this is the one option that is named differently in the config file than the variable passed by --verbose (verbose_flag)
+        verbose_flag = cfg.verbose
         xattr_template = cfg.xattr_template
         year = cfg.year
-        # config file might have changed verbose
-        color_theme = get_theme(theme)
-        verbose_ = verbose_print(
-            verbose, timestamp, rich=True, theme=color_theme, highlight=False
-        )
-        # set console for rich_echo to be same as for verbose_
-        set_rich_console(get_verbose_console())
-        set_rich_timestamp(timestamp)
+        syndicated = cfg.syndicated
+        not_syndicated = cfg.not_syndicated
+        saved_to_library = cfg.saved_to_library
+        not_saved_to_library = cfg.not_saved_to_library
 
-        verbose_(f"Loaded options from file [filepath]{load_config}")
+        # config file might have changed verbose
+        verbose = verbose_print(verbose=verbose_flag, timestamp=timestamp, theme=theme)
+        verbose(f"Loaded options from file [filepath]{load_config}")
 
         set_crash_data("cfg", cfg.asdict())
 
-    verbose_(f"osxphotos version {__version__}")
+    verbose(f"osxphotos version: {__version__}")
+    verbose(f"Python version: {sys.version}")
+    if is_macos:
+        verbose(f"Platform: {platform.platform()}, {'.'.join(get_macos_version())}")
+    else:
+        verbose(f"Platform: {platform.platform()}")
+    verbose(f"Verbose level: {verbose_flag}")
 
     # validate options
     exclusive_options = [
@@ -1117,6 +1136,7 @@ def export(
         ("cloudasset", "not_cloudasset"),
         ("deleted", "deleted_only"),
         ("description", "no_description"),
+        ("edited", "not_edited"),
         ("export_as_hardlink", "convert_to_jpeg"),
         ("export_as_hardlink", "download_missing"),
         ("export_as_hardlink", "exiftool"),
@@ -1144,6 +1164,8 @@ def export(
         ("slow_mo", "not_slow_mo"),
         ("time_lapse", "not_time_lapse"),
         ("title", "no_title"),
+        ("syndicated", "not_syndicated"),
+        ("saved_to_library", "not_saved_to_library"),
     ]
     dependent_options = [
         ("append", ("report")),
@@ -1169,14 +1191,14 @@ def export(
 
     if config_only and not save_config:
         rich_click_echo(
-            "[error]--config-only must be used with --save-config",
+            "[error]Incompatible export options: --config-only must be used with --save-config",
             err=True,
         )
         sys.exit(1)
 
     if all(x in [s.lower() for s in sidecar] for x in ["json", "exiftool"]):
         rich_click_echo(
-            "[error]Cannot use --sidecar json with --sidecar exiftool due to name collisions",
+            "[error]Incompatible export options:: cannot use --sidecar json with --sidecar exiftool due to name collisions",
             err=True,
         )
         sys.exit(1)
@@ -1192,7 +1214,7 @@ def export(
                 sys.exit(1)
 
     if save_config:
-        verbose_(f"Saving options to config file '[filepath]{save_config}'")
+        verbose(f"Saving options to config file '[filepath]{save_config}'")
         cfg.write_to_file(save_config)
         if config_only:
             rich_echo(f"Saved config file to '[filepath]{save_config}'")
@@ -1257,7 +1279,7 @@ def export(
             ctx.exit(1)
 
     if any([exiftool, exiftool_merge_keywords, exiftool_merge_persons]):
-        verbose_(f"exiftool path: [filepath]{exiftool_path}")
+        verbose(f"exiftool path: [filepath]{exiftool_path}")
 
     # default searches for everything
     photos = True
@@ -1267,12 +1289,6 @@ def export(
     if only_photos:
         movies = False
 
-    # load UUIDs if necessary and append to any uuids passed with --uuid
-    if uuid_from_file:
-        uuid_list = list(uuid)  # Click option is a tuple
-        uuid_list.extend(load_uuid_from_file(uuid_from_file))
-        uuid = tuple(uuid_list)
-
     # below needed for to make CliRunner work for testing
     cli_db = cli_obj.db if cli_obj is not None else None
     db = get_photos_db(*photos_library, db, cli_db)
@@ -1315,7 +1331,8 @@ def export(
         )
         for other_db in other_db_files:
             rich_click_echo(f"{other_db}")
-        click.confirm("Do you want to continue?", abort=True)
+        if not click.confirm("Do you want to continue?"):
+            sys.exit(1)
 
     if dry_run:
         export_db = ExportDBInMemory(dbfile=export_db_path, export_dir=dest)
@@ -1326,114 +1343,37 @@ def export(
             if ramdb
             else ExportDB(dbfile=export_db_path, export_dir=dest)
         )
-        fileutil = FileUtilShUtil if alt_copy else FileUtil
+        fileutil = FileUtilShUtil if alt_copy or not is_macos else FileUtilMacOS
 
-    if verbose_:
+    if verbose:
         if export_db.was_created:
-            verbose_(f"Created export database [filepath]{export_db_path}")
+            verbose(f"Created export database [filepath]{export_db_path}")
         else:
-            verbose_(f"Using export database [filepath]{export_db_path}")
+            verbose(f"Using export database [filepath]{export_db_path}")
         upgraded = export_db.was_upgraded
         if upgraded:
-            verbose_(
+            verbose(
                 f"Upgraded export database [filepath]{export_db_path}[/] from version [num]{upgraded[0]}[/] to [num]{upgraded[1]}[/]"
             )
 
     # save config to export_db
     export_db.set_config(cfg.write_to_str())
 
+    query_kwargs = locals()
+    # skip missing bursts if using --download-missing by itself as AppleScript otherwise causes errors
+    query_kwargs["missing_bursts"] = (
+        (download_missing and use_photokit) or not download_missing,
+    )
+    query_kwargs["burst_photos"] = export_bursts
+    query_options = query_options_from_kwargs(**query_kwargs)
+
     photosdb = osxphotos.PhotosDB(
-        dbfile=db, verbose=verbose_, exiftool=exiftool_path, rich=True
+        dbfile=db, verbose=verbose, exiftool=exiftool_path, rich=True
     )
 
     # enable beta features if requested
     photosdb._beta = beta
 
-    query_options = QueryOptions(
-        added_after=added_after,
-        added_before=added_before,
-        added_in_last=added_in_last,
-        album=album,
-        burst_photos=export_bursts,
-        burst=burst,
-        cloudasset=cloudasset,
-        deleted_only=deleted_only,
-        deleted=deleted,
-        description=description,
-        duplicate=duplicate,
-        edited=edited,
-        exif=exif,
-        external_edit=external_edit,
-        favorite=favorite,
-        folder=folder,
-        from_date=from_date,
-        from_time=from_time,
-        function=query_function,
-        has_comment=has_comment,
-        has_likes=has_likes,
-        has_raw=has_raw,
-        hdr=hdr,
-        hidden=hidden,
-        ignore_case=ignore_case,
-        in_album=in_album,
-        incloud=incloud,
-        is_reference=is_reference,
-        keyword=keyword,
-        label=label,
-        live=live,
-        location=location,
-        max_size=max_size,
-        min_size=min_size,
-        # skip missing bursts if using --download-missing by itself as AppleScript otherwise causes errors
-        missing_bursts=(download_missing and use_photokit) or not download_missing,
-        missing=missing,
-        movies=movies,
-        name=name,
-        no_comment=no_comment,
-        no_description=no_description,
-        no_likes=no_likes,
-        no_location=no_location,
-        no_keyword=no_keyword,
-        no_place=no_place,
-        no_title=no_title,
-        not_burst=not_burst,
-        not_cloudasset=not_cloudasset,
-        not_favorite=not_favorite,
-        not_hdr=not_hdr,
-        not_hidden=not_hidden,
-        not_in_album=not_in_album,
-        not_incloud=not_incloud,
-        not_live=not_live,
-        not_missing=not_missing,
-        not_panorama=not_panorama,
-        not_portrait=not_portrait,
-        not_reference=not_reference,
-        not_screenshot=not_screenshot,
-        not_selfie=not_selfie,
-        not_shared=not_shared,
-        not_slow_mo=not_slow_mo,
-        not_time_lapse=not_time_lapse,
-        panorama=panorama,
-        person=person,
-        photos=photos,
-        place=place,
-        portrait=portrait,
-        query_eval=query_eval,
-        regex=regex,
-        screenshot=screenshot,
-        selected=selected,
-        selfie=selfie,
-        shared=shared,
-        slow_mo=slow_mo,
-        time_lapse=time_lapse,
-        title=title,
-        to_date=to_date,
-        to_time=to_time,
-        uti=uti,
-        uuid=uuid,
-        year=year,
-    )
-
     try:
         photos = photosdb.query(query_options)
     except ValueError as e:
@@ -1474,91 +1414,62 @@ def export(
 
         # set up for --add-export-to-album if needed
         album_export = (
-            PhotosAlbum(add_exported_to_album, verbose=verbose_)
+            PhotosAlbum(add_exported_to_album, verbose=verbose)
             if add_exported_to_album
             else None
         )
         album_skipped = (
-            PhotosAlbum(add_skipped_to_album, verbose=verbose_)
+            PhotosAlbum(add_skipped_to_album, verbose=verbose)
             if add_skipped_to_album
             else None
         )
         album_missing = (
-            PhotosAlbum(add_missing_to_album, verbose=verbose_)
+            PhotosAlbum(add_missing_to_album, verbose=verbose)
             if add_missing_to_album
             else None
         )
 
+        def cleanup_lock_files():
+            """Cleanup lock files"""
+            if not under_test():
+                verbose("Cleaning up lock files")
+            if dry_run:
+                return
+            for lock_file in pathlib.Path(dest).rglob("*.osxphotos.lock"):
+                try:
+                    lock_file.unlink()
+                except Exception as e:
+                    logger.debug(f"Error removing lock file {lock_file}: {e}")
+
+        atexit.register(cleanup_lock_files)
+
         photo_num = 0
         num_exported = 0
         limit_str = f" (limit = [num]{limit}[/num])" if limit else ""
+        # hack to avoid passing all the options to export_photo
+        kwargs = {
+            k: v
+            for k, v in locals().items()
+            if k in inspect.getfullargspec(export_photo).args
+        }
+        kwargs["export_dir"] = dest
+        kwargs["export_preview"] = preview
         with rich_progress(console=get_verbose_console(), mock=no_progress) as progress:
             task = progress.add_task(
                 f"Exporting [num]{num_photos}[/] photos{limit_str}", total=num_photos
             )
             for p in photos:
                 photo_num += 1
-                export_results = export_photo(
-                    photo=p,
-                    dest=dest,
-                    album_keyword=album_keyword,
-                    convert_to_jpeg=convert_to_jpeg,
-                    description_template=description_template,
-                    directory=directory,
-                    download_missing=download_missing,
-                    dry_run=dry_run,
-                    edited_suffix=edited_suffix,
-                    exiftool_merge_keywords=exiftool_merge_keywords,
-                    exiftool_merge_persons=exiftool_merge_persons,
-                    exiftool_option=exiftool_option,
-                    exiftool=exiftool,
-                    export_as_hardlink=export_as_hardlink,
-                    export_by_date=export_by_date,
-                    export_db=export_db,
-                    export_dir=dest,
-                    export_edited=export_edited,
-                    export_live=export_live,
-                    export_preview=preview,
-                    export_raw=export_raw,
-                    favorite_rating=favorite_rating,
-                    filename_template=filename_template,
-                    fileutil=fileutil,
-                    force_update=force_update,
-                    ignore_date_modified=ignore_date_modified,
-                    ignore_signature=ignore_signature,
-                    jpeg_ext=jpeg_ext,
-                    jpeg_quality=jpeg_quality,
-                    keyword_template=keyword_template,
-                    num_photos=num_photos,
-                    original_name=original_name,
-                    original_suffix=original_suffix,
-                    overwrite=overwrite,
-                    person_keyword=person_keyword,
-                    photo_num=photo_num,
-                    preview_if_missing=preview_if_missing,
-                    preview_suffix=preview_suffix,
-                    replace_keywords=replace_keywords,
-                    retry=retry,
-                    sidecar_drop_ext=sidecar_drop_ext,
-                    sidecar=sidecar,
-                    skip_original_if_edited=skip_original_if_edited,
-                    strip=strip,
-                    touch_file=touch_file,
-                    update=update,
-                    update_errors=update_errors,
-                    use_photokit=use_photokit,
-                    use_photos_export=use_photos_export,
-                    verbose_=verbose_,
-                    tmpdir=tmpdir,
-                )
-
+                kwargs["photo"] = p
+                kwargs["photo_num"] = photo_num
+                export_results = export_photo(**kwargs)
                 if post_function:
                     for function in post_function:
                         # post function is tuple of (function, filename.py::function_name)
-                        verbose_(f"Calling post-function [bold]{function[1]}")
+                        verbose(f"Calling post-function [bold]{function[1]}")
                         if not dry_run:
                             try:
-                                function[0](p, export_results, verbose_)
+                                function[0](p, export_results, verbose)
                             except Exception as e:
                                 rich_echo_error(
                                     f"[error]Error running post-function [italic]{function[1]}[/italic]: {e}"
@@ -1572,7 +1483,7 @@ def export(
                     dry_run=dry_run,
                     exiftool_path=exiftool_path,
                     export_db=export_db,
-                    verbose_=verbose_,
+                    verbose=verbose,
                 )
 
                 if album_export and export_results.exported:
@@ -1631,37 +1542,47 @@ def export(
                 )
 
                 if finder_tag_keywords or finder_tag_template:
-                    tags_written, tags_skipped = write_finder_tags(
-                        p,
-                        photo_files,
-                        keywords=finder_tag_keywords,
-                        keyword_template=keyword_template,
-                        album_keyword=album_keyword,
-                        person_keyword=person_keyword,
-                        exiftool_merge_keywords=exiftool_merge_keywords,
-                        finder_tag_template=finder_tag_template,
-                        strip=strip,
-                        export_dir=dest,
-                        verbose_=verbose_,
-                    )
-                    export_results.xattr_written.extend(tags_written)
-                    export_results.xattr_skipped.extend(tags_skipped)
-                    results.xattr_written.extend(tags_written)
-                    results.xattr_skipped.extend(tags_skipped)
+                    if dry_run:
+                        for filepath in photo_files:
+                            verbose(f"Writing Finder tags to [filepath]{filepath}[/]")
+                    else:
+                        tags_written, tags_skipped = write_finder_tags(
+                            p,
+                            photo_files,
+                            keywords=finder_tag_keywords,
+                            keyword_template=keyword_template,
+                            album_keyword=album_keyword,
+                            person_keyword=person_keyword,
+                            exiftool_merge_keywords=exiftool_merge_keywords,
+                            finder_tag_template=finder_tag_template,
+                            strip=strip,
+                            export_dir=dest,
+                            verbose=verbose,
+                        )
+                        export_results.xattr_written.extend(tags_written)
+                        export_results.xattr_skipped.extend(tags_skipped)
+                        results.xattr_written.extend(tags_written)
+                        results.xattr_skipped.extend(tags_skipped)
 
                 if xattr_template:
-                    xattr_written, xattr_skipped = write_extended_attributes(
-                        p,
-                        photo_files,
-                        xattr_template,
-                        strip=strip,
-                        export_dir=dest,
-                        verbose_=verbose_,
-                    )
-                    export_results.xattr_written.extend(xattr_written)
-                    export_results.xattr_skipped.extend(xattr_skipped)
-                    results.xattr_written.extend(xattr_written)
-                    results.xattr_skipped.extend(xattr_skipped)
+                    if dry_run:
+                        for filepath in photo_files:
+                            verbose(
+                                f"Writing extended attributes to [filepath]{filepath}[/]"
+                            )
+                    else:
+                        xattr_written, xattr_skipped = write_extended_attributes(
+                            p,
+                            photo_files,
+                            xattr_template,
+                            strip=strip,
+                            export_dir=dest,
+                            verbose=verbose,
+                        )
+                        export_results.xattr_written.extend(xattr_written)
+                        export_results.xattr_skipped.extend(xattr_skipped)
+                        results.xattr_written.extend(xattr_written)
+                        results.xattr_skipped.extend(xattr_skipped)
 
                 report_writer.write(export_results)
 
@@ -1754,7 +1675,7 @@ def export(
             all_files += files_to_keep
         rich_echo(f"Cleaning up [filepath]{dest}")
         cleaned_files, cleaned_dirs = cleanup_files(
-            dest, all_files, dirs_to_keep, fileutil, verbose_=verbose_
+            dest, all_files, dirs_to_keep, fileutil, verbose=verbose
         )
         file_str = "files" if len(cleaned_files) != 1 else "file"
         dir_str = "directories" if len(cleaned_dirs) != 1 else "directory"
@@ -1771,12 +1692,12 @@ def export(
     export_db.set_export_results(results)
 
     if report:
-        verbose_(f"Wrote export report to [filepath]{report}")
+        verbose(f"Wrote export report to [filepath]{report}")
         report_writer.close()
 
     # close export_db and write changes if needed
     if ramdb and not dry_run:
-        verbose_(f"Writing export database changes back to [filepath]{export_db.path}")
+        verbose(f"Writing export database changes back to [filepath]{export_db.path}")
         export_db.write_to_disk()
     export_db.close()
 
@@ -1784,7 +1705,7 @@ def export(
 def export_photo(
     photo=None,
     dest=None,
-    verbose_=None,
+    verbose=None,
     export_by_date=None,
     sidecar=None,
     sidecar_drop_ext=False,
@@ -1810,7 +1731,7 @@ def export_photo(
     keyword_template=None,
     description_template=None,
     export_db=None,
-    fileutil=FileUtil,
+    fileutil=FileUtilShUtil,
     dry_run=None,
     touch_file=None,
     edited_suffix="_edited",
@@ -1881,7 +1802,7 @@ def export_photo(
         update: bool, only export updated photos
         update_errors: bool, attempt to re-export photos that previously produced errors even if they otherwise would not be exported
         use_photos_export: bool; if True forces the use of AppleScript to export even if photo not missing
-        verbose_: callable for verbose output
+        verbose: callable for verbose output
         tmpdir: optional str; temporary directory to use for export
     Returns:
         list of path(s) of exported photo or None if photo was missing
@@ -1889,7 +1810,6 @@ def export_photo(
     Raises:
         ValueError on invalid filename_template
     """
-
     export_original = not (skip_original_if_edited and photo.hasadjustments)
 
     # can't export edited if photo doesn't have edited versions
@@ -1904,7 +1824,7 @@ def export_photo(
             # requested edited version but it's missing, download original
             export_original = True
             export_edited = False
-            verbose_(
+            verbose(
                 f"Edited file for [filename]{photo.original_filename}[/] is missing, exporting original"
             )
 
@@ -2000,7 +1920,7 @@ def export_photo(
             )
             original_filename = str(original_filename)
 
-            verbose_(
+            verbose(
                 f"Exporting [filename]{photo.original_filename}[/] ([filename]{photo.filename}[/]) ([count]{photo_num}/{num_photos}[/])"
             )
 
@@ -2048,7 +1968,7 @@ def export_photo(
                 update_errors=update_errors,
                 use_photos_export=use_photos_export,
                 use_photokit=use_photokit,
-                verbose_=verbose_,
+                verbose=verbose,
                 tmpdir=tmpdir,
             )
 
@@ -2116,7 +2036,7 @@ def export_photo(
                     f"{edited_filename.stem}{rendered_edited_suffix}{edited_ext}"
                 )
 
-                verbose_(
+                verbose(
                     f"Exporting edited version of [filename]{photo.original_filename}[/filename] ([filename]{photo.filename}[/filename])"
                 )
 
@@ -2164,7 +2084,7 @@ def export_photo(
                     update_errors=update_errors,
                     use_photos_export=use_photos_export,
                     use_photokit=use_photokit,
-                    verbose_=verbose_,
+                    verbose=verbose,
                     tmpdir=tmpdir,
                 )
 
@@ -2251,7 +2171,7 @@ def export_photo_to_directory(
     update_errors,
     use_photos_export,
     use_photokit,
-    verbose_,
+    verbose,
     tmpdir,
 ):
     """Export photo to directory dest_path"""
@@ -2263,7 +2183,7 @@ def export_photo_to_directory(
     if photo.intrash and not photo_path and not preview_if_missing:
         # skip deleted files if they're missing
         # as AppleScript/PhotoKit cannot export deleted photos
-        verbose_(
+        verbose(
             f"Skipping missing deleted photo {photo.original_filename} ({photo.uuid})"
         )
         results.missing.append(str(pathlib.Path(dest_path) / filename))
@@ -2272,7 +2192,7 @@ def export_photo_to_directory(
     render_options = RenderOptions(export_dir=export_dir, dest_path=dest_path)
 
     if not export_original and not edited:
-        verbose_(f"Skipping original version of [filename]{photo.original_filename}")
+        verbose(f"Skipping original version of [filename]{photo.original_filename}")
         return results
 
     tries = 0
@@ -2318,14 +2238,14 @@ def export_photo_to_directory(
                 use_persons_as_keywords=person_keyword,
                 use_photokit=use_photokit,
                 use_photos_export=use_photos_export,
-                verbose=verbose_,
+                verbose=verbose,
             )
             exporter = PhotoExporter(photo)
             export_results = exporter.export(
                 dest=dest_path, filename=filename, options=export_options
             )
             for warning_ in export_results.exiftool_warning:
-                verbose_(
+                verbose(
                     f"[warning]exiftool warning for file {warning_[0]}: {warning_[1]}"
                 )
             for error_ in export_results.exiftool_error:
@@ -2353,26 +2273,26 @@ def export_photo_to_directory(
                 err=True,
             )
             if tries > retry:
-                results.error.append((str(pathlib.Path(dest) / filename), e))
+                results.error.append((str(pathlib.Path(dest) / filename), str(e)))
                 break
             else:
                 rich_echo(
                     f"Retrying export for photo ([uuid]{photo.uuid}[/uuid]: [filename]{photo.original_filename}[/filename])"
                 )
 
-    if verbose_:
+    if verbose:
         if update or force_update:
             for new in results.new:
-                verbose_(f"Exported new file [filepath]{new}")
+                verbose(f"Exported new file [filepath]{new}")
             for updated in results.updated:
-                verbose_(f"Exported updated file [filepath]{updated}")
+                verbose(f"Exported updated file [filepath]{updated}")
             for skipped in results.skipped:
-                verbose_(f"Skipped up to date file [filepath]{skipped}")
+                verbose(f"Skipped up to date file [filepath]{skipped}")
         else:
             for exported in results.exported:
-                verbose_(f"Exported [filepath]{exported}")
+                verbose(f"Exported [filepath]{exported}")
         for touched in results.touched:
-            verbose_(f"Touched date on file [filepath]{touched}")
+            verbose(f"Touched date on file [filepath]{touched}")
 
     return results
 
@@ -2568,7 +2488,7 @@ def collect_files_to_keep(
     return files_to_keep, dirs_to_keep
 
 
-def cleanup_files(dest_path, files_to_keep, dirs_to_keep, fileutil, verbose_):
+def cleanup_files(dest_path, files_to_keep, dirs_to_keep, fileutil, verbose):
     """cleanup dest_path by deleting and files and empty directories
         not in files_to_keep
 
@@ -2577,7 +2497,7 @@ def cleanup_files(dest_path, files_to_keep, dirs_to_keep, fileutil, verbose_):
         files_to_keep: list of full file paths to keep (not delete)
         dirs_to_keep: list of full dir paths to keep (not delete if they are empty)
         fileutil: FileUtil object
-        verbose_: verbose callable for printing verbose output
+        verbose: verbose callable for printing verbose output
 
     Returns:
         tuple of (list of files deleted, list of directories deleted)
@@ -2589,9 +2509,13 @@ def cleanup_files(dest_path, files_to_keep, dirs_to_keep, fileutil, verbose_):
     deleted_files = []
     for p in pathlib.Path(dest_path).rglob("*"):
         if p.is_file() and normalize_fs_path(str(p).lower()) not in keepers:
-            verbose_(f"Deleting [filepath]{p}")
-            fileutil.unlink(p)
-            deleted_files.append(str(p))
+            verbose(f"Deleting [filepath]{p}")
+            try:
+                fileutil.unlink(p)
+                deleted_files.append(str(p))
+            except OSError as e:
+                # ignore errors deleting files, #987
+                verbose(f"Error deleting file {p}: {e}")
 
     # delete empty directories
     deleted_dirs = []
@@ -2601,9 +2525,13 @@ def cleanup_files(dest_path, files_to_keep, dirs_to_keep, fileutil, verbose_):
             continue
         if not list(pathlib.Path(dirpath).glob("*")):
             # directory and directory is empty
-            verbose_(f"Deleting empty directory {dirpath}")
-            fileutil.rmdir(dirpath)
-            deleted_dirs.append(str(dirpath))
+            verbose(f"Deleting empty directory {dirpath}")
+            try:
+                fileutil.rmdir(dirpath)
+                deleted_dirs.append(str(dirpath))
+            except OSError as e:
+                # ignore errors deleting directories, #987
+                verbose(f"Error deleting directory {dirpath}: {e}")
 
     return (deleted_files, deleted_dirs)
 
@@ -2619,7 +2547,7 @@ def write_finder_tags(
     finder_tag_template=None,
     strip=False,
     export_dir=None,
-    verbose_=noop,
+    verbose=noop,
 ):
     """Write Finder tags (extended attributes) to files; only writes attributes if attributes on file differ from what would be written
 
@@ -2633,7 +2561,7 @@ def write_finder_tags(
         exiftool_merge_keywords: if True, include any keywords in the exif data of the source image as keywords
         finder_tag_template: list of templates to evaluate for determining Finder tags
         export_dir: value to use for {export_dir} template
-        verbose_: function to call to print verbose messages
+        verbose: function to call to print verbose messages
 
     Returns:
         (list of file paths that were updated with new Finder tags, list of file paths skipped because Finder tags didn't need updating)
@@ -2693,11 +2621,11 @@ def write_finder_tags(
     for f in files:
         md = OSXMetaData(f)
         if sorted(md.tags) != sorted(tags):
-            verbose_(f"Writing Finder tags to {f}")
+            verbose(f"Writing Finder tags to [filepath]{f}[/]")
             md.tags = tags
             written.append(f)
         else:
-            verbose_(f"Skipping Finder tags for {f}: nothing to do")
+            verbose(f"Skipping Finder tags for [filepath]{f}[/]: nothing to do")
             skipped.append(f)
 
     return (written, skipped)
@@ -2709,14 +2637,17 @@ def write_extended_attributes(
     xattr_template,
     strip=False,
     export_dir=None,
-    verbose_=noop,
+    verbose=noop,
 ):
     """Writes extended attributes to exported files
 
     Args:
         photo: a PhotoInfo object
+        files: list of file paths to write extended attributes to
+        xattr_template: list of tuples: (attribute name, attribute template)
         strip:   xattr_template: list of tuples: (attribute name, attribute template)
         export_dir: value to use for {export_dir} template
+        verbose: function to call to print verbose messages
 
     Returns:
         tuple(list of file paths that were updated with new attributes, list of file paths skipped because attributes didn't need updating)
@@ -2766,10 +2697,14 @@ def write_extended_attributes(
             if (not file_value and not value) or file_value == value:
                 # if both not set or both equal, nothing to do
                 # get returns None if not set and value will be [] if not set so can't directly compare
-                verbose_(f"Skipping extended attribute {attr} for {f}: nothing to do")
+                verbose(
+                    f"Skipping extended attribute [bold]{attr}[/] for [filepath]{f}[/]: nothing to do"
+                )
                 skipped.add(f)
             else:
-                verbose_(f"Writing extended attribute {attr} to {f}")
+                verbose(
+                    f"Writing extended attribute [bold]{attr}[/] to [filepath]{f}[/]"
+                )
                 md.set(attr, value)
                 written.add(f)
 
@@ -2784,7 +2719,7 @@ def run_post_command(
     dry_run,
     exiftool_path,
     export_db,
-    verbose_,
+    verbose,
 ):
     # todo: pass in RenderOptions from export? (e.g. so it contains strip, etc?)
     # todo: need a shell_quote template type:
@@ -2801,7 +2736,7 @@ def run_post_command(
             command, _ = template.render(command_template, options=render_options)
             command = command[0] if command else None
             if command:
-                verbose_(f'Running command: "{command}"')
+                verbose(f'Running command: "{command}"')
                 if not dry_run:
                     args = shlex.split(command)
                     cwd = pathlib.Path(f).parent

osxphotos/cli/exportdb.py

@@ -3,6 +3,7 @@
 import json
 import pathlib
 import sys
+from textwrap import dedent
 
 import click
 from rich import print
@@ -15,6 +16,7 @@ from osxphotos.export_db import (
     ExportDB,
 )
 from osxphotos.export_db_utils import (
+    export_db_backup,
     export_db_check_signatures,
     export_db_get_errors,
     export_db_get_last_run,
@@ -23,9 +25,12 @@ from osxphotos.export_db_utils import (
     export_db_touch_files,
     export_db_update_signatures,
     export_db_vacuum,
+    export_db_migrate_photos_library,
+    export_db_get_last_library,
 )
 from osxphotos.utils import pluralize
 
+from .cli_params import THEME_OPTION, TIMESTAMP_OPTION, VERBOSE_OPTION
 from .click_rich_echo import (
     rich_click_echo,
     rich_echo,
@@ -139,6 +144,15 @@ from .verbose import get_verbose_console, verbose_print
     metavar="SQL_STATEMENT",
     help="Execute SQL_STATEMENT against export database and print results.",
 )
+@click.option(
+    "--migrate-photos-library",
+    metavar="PHOTOS_LIBRARY",
+    help="Migrate the export database to use the specified Photos library. "
+    "Use this if you have moved your Photos library to a new location or computer and "
+    "want to keep using the same export database. "
+    "This will update the UUIDs in the export database to match the new Photos library.",
+    type=click.Path(exists=True, file_okay=True, dir_okay=True),
+)
 @click.option(
     "--export-dir",
     help="Optional path to export directory (if not parent of export database).",
@@ -150,11 +164,13 @@ from .verbose import get_verbose_console, verbose_print
     help="If used with --report, add data to existing report file instead of overwriting it. "
     "See also --report.",
 )
-@click.option("--verbose", "-V", is_flag=True, help="Print verbose output.")
+@VERBOSE_OPTION
+@TIMESTAMP_OPTION
+@THEME_OPTION
 @click.option(
     "--dry-run",
     is_flag=True,
-    help="Run in dry-run mode (don't actually update files), e.g. for use with --update-signatures.",
+    help="Run in dry-run mode (don't actually update files); for example, use with --update-signatures or --migrate-photos-library.",
 )
 @click.argument("export_db", metavar="EXPORT_DATABASE", type=click.Path(exists=True))
 def exportdb(
@@ -168,9 +184,12 @@ def exportdb(
     last_errors,
     last_run,
     migrate,
+    migrate_photos_library,
     report,
     save_config,
     sql,
+    theme,
+    timestamp,
     touch_file,
     update_signatures,
     uuid_files,
@@ -178,22 +197,16 @@ def exportdb(
     delete_uuid,
     delete_file,
     vacuum,
-    verbose,
+    verbose_flag,
     version,
 ):
     """Utilities for working with the osxphotos export database"""
-    color_theme = get_theme()
-    verbose_ = verbose_print(
-        verbose, timestamp=False, rich=True, theme=color_theme, highlight=False
-    )
-    # set console for rich_echo to be same as for verbose_
-    set_rich_console(get_verbose_console(theme=color_theme))
-    set_rich_theme(color_theme)
+    verbose = verbose_print(verbose=verbose_flag, timestamp=timestamp, theme=theme)
 
     # validate options and args
     if append and not report:
-        rich_echo(
-            "[error]Error: --append requires --report; ee --help for more information.[/]",
+        rich_echo_error(
+            "[error]Error: --append requires --report; see --help for more information.[/]",
             file=sys.stderr,
         )
         sys.exit(1)
@@ -203,7 +216,7 @@ def exportdb(
         # assume it's the export folder
         export_db = export_db / OSXPHOTOS_EXPORT_DB
         if not export_db.is_file():
-            rich_echo(
+            rich_echo_error(
                 f"[error]Error: {OSXPHOTOS_EXPORT_DB} missing from {export_db.parent}[/error]"
             )
             sys.exit(1)
@@ -229,7 +242,9 @@ def exportdb(
         ]
     ]
     if sum(sub_commands) > 1:
-        rich_echo("[error]Only a single sub-command may be specified at a time[/error]")
+        rich_echo_error(
+            "[error]Only a single sub-command may be specified at a time[/error]"
+        )
         sys.exit(1)
 
     # process sub-commands
@@ -238,7 +253,7 @@ def exportdb(
         try:
             osxphotos_ver, export_db_ver = export_db_get_version(export_db)
         except Exception as e:
-            rich_echo(
+            rich_echo_error(
                 f"[error]Error: could not read version from {export_db}: {e}[/error]"
             )
             sys.exit(1)
@@ -253,7 +268,7 @@ def exportdb(
             start_size = pathlib.Path(export_db).stat().st_size
             export_db_vacuum(export_db)
         except Exception as e:
-            rich_echo(f"[error]Error: {e}[/error]")
+            rich_echo_error(f"[error]Error: {e}[/error]")
             sys.exit(1)
         else:
             rich_echo(
@@ -264,10 +279,10 @@ def exportdb(
     if update_signatures:
         try:
             updated, skipped = export_db_update_signatures(
-                export_db, export_dir, verbose_, dry_run
+                export_db, export_dir, verbose, dry_run
             )
         except Exception as e:
-            rich_echo(f"[error]Error: {e}[/error]")
+            rich_echo_error(f"[error]Error: {e}[/error]")
             sys.exit(1)
         else:
             rich_echo(
@@ -279,7 +294,7 @@ def exportdb(
         try:
             last_run_info = export_db_get_last_run(export_db)
         except Exception as e:
-            rich_echo(f"[error]Error: {e}[/error]")
+            rich_echo_error(f"[error]Error: {e}[/error]")
             sys.exit(1)
         else:
             rich_echo(f"last run at [time]{last_run_info[0]}:")
@@ -290,7 +305,7 @@ def exportdb(
         try:
             export_db_save_config_to_file(export_db, save_config)
         except Exception as e:
-            rich_echo(f"[error]Error: {e}[/error]")
+            rich_echo_error(f"[error]Error: {e}[/error]")
             sys.exit(1)
         else:
             rich_echo(f"Saved configuration to [filepath]{save_config}")
@@ -299,10 +314,10 @@ def exportdb(
     if check_signatures:
         try:
             matched, notmatched, skipped = export_db_check_signatures(
-                export_db, export_dir, verbose_=verbose_
+                export_db, export_dir, verbose_=verbose
             )
         except Exception as e:
-            rich_echo(f"[error]Error: {e}[/error]")
+            rich_echo_error(f"[error]Error: {e}[/error]")
             sys.exit(1)
         else:
             rich_echo(
@@ -314,10 +329,10 @@ def exportdb(
     if touch_file:
         try:
             touched, not_touched, skipped = export_db_touch_files(
-                export_db, export_dir, verbose_=verbose_, dry_run=dry_run
+                export_db, export_dir, verbose_=verbose, dry_run=dry_run
             )
         except Exception as e:
-            rich_echo(f"[error]Error: {e}[/error]")
+            rich_echo_error(f"[error]Error: {e}[/error]")
             sys.exit(1)
         else:
             rich_echo(
@@ -331,7 +346,7 @@ def exportdb(
         try:
             info_rec = exportdb.get_file_record(info)
         except Exception as e:
-            rich_echo(f"[error]Error: {e}[/error]")
+            rich_echo_error(f"[error]Error: {e}[/error]")
             sys.exit(1)
         else:
             if info_rec:
@@ -346,7 +361,7 @@ def exportdb(
         try:
             error_list = export_db_get_errors(export_db)
         except Exception as e:
-            rich_echo(f"[error]Error: {e}[/error]")
+            rich_echo_error(f"[error]Error: {e}[/error]")
             sys.exit(1)
         else:
             if error_list:
@@ -378,7 +393,7 @@ def exportdb(
         try:
             info_rec = exportdb.get_photoinfo_for_uuid(uuid_info)
         except Exception as e:
-            rich_echo(f"[error]Error: {e}[/error]")
+            rich_echo_error(f"[error]Error: {e}[/error]")
             sys.exit(1)
         else:
             if info_rec:
@@ -396,7 +411,7 @@ def exportdb(
         try:
             file_list = exportdb.get_files_for_uuid(uuid_files)
         except Exception as e:
-            rich_echo(f"[error]Error: {e}[/error]")
+            rich_echo_error(f"[error]Error: {e}[/error]")
             sys.exit(1)
         else:
             if file_list:
@@ -436,12 +451,14 @@ def exportdb(
         report_filename = render_and_validate_report(report_template, "", export_dir)
         export_results = exportdb.get_export_results(run_id)
         if not export_results:
-            rich_echo(f"[error]No report results found for run ID {run_id}[/error]")
+            rich_echo_error(
+                f"[error]No report results found for run ID {run_id}[/error]"
+            )
             sys.exit(1)
         try:
             report_writer = export_report_writer_factory(report_filename, append=append)
         except ValueError as e:
-            rich_echo(f"[error]Error: {e}[/error]")
+            rich_echo_error(f"[error]Error: {e}[/error]")
             sys.exit(1)
         report_writer.write(export_results)
         report_writer.close()
@@ -466,9 +483,39 @@ def exportdb(
             c = exportdb._conn.cursor()
             results = c.execute(sql)
         except Exception as e:
-            rich_echo(f"[error]Error: {e}[/error]")
+            rich_echo_error(f"[error]Error: {e}[/error]")
             sys.exit(1)
         else:
             for row in results:
                 print(row)
             sys.exit(0)
+
+    if migrate_photos_library:
+        # migrate Photos library to new library and update UUIDs in export database
+        last_library = export_db_get_last_library(export_db)
+        rich_echo(
+            dedent(
+                f"""
+        [warning]:warning-emoji:  This command will update your export database ([filepath]{export_db}[/]) 
+        to use [filepath]{migrate_photos_library}[/] as the new source library.
+        The last library used was [filepath]{last_library}[/].
+        This will allow you to use the export database with the new library but it will
+        no longer work correctly with the old library unless you run the `--migrate-photos-library`
+        command again to update the export database to use the previous library.
+
+        A backup of the export database will be created in the same directory as the export database.
+        """
+            )
+        )
+        if not click.confirm("Do you want to continue?"):
+            sys.exit(0)
+        if not dry_run:
+            backup_file = export_db_backup(export_db)
+            verbose(f"Backed up export database to [filepath]{backup_file}[/]")
+        migrated, notmigrated = export_db_migrate_photos_library(
+            export_db, migrate_photos_library, verbose, dry_run
+        )
+        rich_echo(
+            f"Migrated [num]{migrated}[/] {pluralize(migrated, 'photo', 'photos')}, "
+            f"[num]{notmigrated}[/] not migrated."
+        )

osxphotos/cli/grep.py

@@ -8,7 +8,8 @@ from rich import print
 from osxphotos.photosdb.photosdb_utils import get_photos_library_version
 from osxphotos.sqlgrep import sqlgrep
 
-from .common import DB_OPTION, OSXPHOTOS_HIDDEN, get_photos_db
+from .cli_params import DB_OPTION, OSXPHOTOS_HIDDEN
+from .common import get_photos_db
 
 
 @click.command(name="grep", hidden=OSXPHOTOS_HIDDEN)

osxphotos/cli/help.py

@@ -5,7 +5,6 @@ import re
 import typing as t
 
 import click
-from osxmetadata import MDITEM_ATTRIBUTE_DATA, MDITEM_ATTRIBUTE_SHORT_NAMES
 from rich.console import Console
 from rich.markdown import Markdown
 
@@ -21,6 +20,10 @@ from osxphotos.phototemplate import (
     TEMPLATE_SUBSTITUTIONS_PATHLIB,
     get_template_help,
 )
+from osxphotos.utils import is_macos
+
+if is_macos:
+    from osxmetadata import MDITEM_ATTRIBUTE_DATA, MDITEM_ATTRIBUTE_SHORT_NAMES
 
 from .click_rich_echo import rich_echo_via_pager
 from .color_themes import get_theme
@@ -249,68 +252,73 @@ class ExportCommand(click.Command):
             + f"rebuilding the '{OSXPHOTOS_EXPORT_DB}' database."
         )
         formatter.write("\n")
-        formatter.write(
-            rich_text("## Extended Attributes", width=formatter.width, markdown=True)
-        )
-        formatter.write("\n")
-        formatter.write_text(
-            """
-Some options (currently '--finder-tag-template', '--finder-tag-keywords', '-xattr-template') write
-additional metadata accessible by Spotlight to facilitate searching. 
-For example, --finder-tag-keyword writes all keywords (including any specified by '--keyword-template'
-or other options) to Finder tags that are searchable in Spotlight using the syntax: 'tag:tagname'.
-For example, if you have images with keyword "Travel" then using '--finder-tag-keywords' you could quickly
-find those images in the Finder by typing 'tag:Travel' in the Spotlight search bar.
-Finder tags are written to the 'com.apple.metadata:_kMDItemUserTags' extended attribute.
-Unlike EXIF metadata, extended attributes do not modify the actual file;
-the metadata is written to extended attributes associated with the file and the Spotlight metadata database. 
-Most cloud storage services do not synch extended attributes. 
-Dropbox does sync them and any changes to a file's extended attributes
-will cause Dropbox to re-sync the files.
 
-The following attributes may be used with '--xattr-template':
-
-            """
-        )
-
-        # build help text from all the attribute names
-        # passed to click.HelpFormatter.write_dl for formatting
-        attr_tuples = [
-            (
-                rich_text("[bold]Attribute[/bold]", width=formatter.width),
-                rich_text("[bold]Description[/bold]", width=formatter.width),
+        if is_macos:
+            formatter.write(
+                rich_text(
+                    "## Extended Attributes", width=formatter.width, markdown=True
+                )
             )
-        ]
-        for attr_key in sorted(EXTENDED_ATTRIBUTE_NAMES):
-            # get short and long name
-            attr = MDITEM_ATTRIBUTE_SHORT_NAMES[attr_key]
-            short_name = MDITEM_ATTRIBUTE_DATA[attr]["short_name"]
-            long_name = MDITEM_ATTRIBUTE_DATA[attr]["name"]
-            constant = MDITEM_ATTRIBUTE_DATA[attr]["xattr_constant"]
+            formatter.write("\n")
+            formatter.write_text(
+                """
+    Some options (currently '--finder-tag-template', '--finder-tag-keywords', '-xattr-template') write
+    additional metadata accessible by Spotlight to facilitate searching. 
+    For example, --finder-tag-keyword writes all keywords (including any specified by '--keyword-template'
+    or other options) to Finder tags that are searchable in Spotlight using the syntax: 'tag:tagname'.
+    For example, if you have images with keyword "Travel" then using '--finder-tag-keywords' you could quickly
+    find those images in the Finder by typing 'tag:Travel' in the Spotlight search bar.
+    Finder tags are written to the 'com.apple.metadata:_kMDItemUserTags' extended attribute.
+    Unlike EXIF metadata, extended attributes do not modify the actual file;
+    the metadata is written to extended attributes associated with the file and the Spotlight metadata database. 
+    Most cloud storage services do not synch extended attributes. 
+    Dropbox does sync them and any changes to a file's extended attributes
+    will cause Dropbox to re-sync the files.
 
-            # get help text
-            description = MDITEM_ATTRIBUTE_DATA[attr]["description"]
-            type_ = MDITEM_ATTRIBUTE_DATA[attr]["help_type"]
-            attr_help = f"{long_name}; {constant}; {description}; {type_}"
+    The following attributes may be used with '--xattr-template':
 
-            # add to list
-            attr_tuples.append((short_name, attr_help))
+                """
+            )
 
-        formatter.write_dl(attr_tuples)
-        formatter.write("\n")
-        formatter.write_text(
-            "For additional information on extended attributes see: https://developer.apple.com/documentation/coreservices/file_metadata/mditem/common_metadata_attribute_keys"
-        )
-        formatter.write("\n")
-        formatter.write(
-            rich_text("## Templating System", width=formatter.width, markdown=True)
-        )
-        formatter.write("\n")
-        help_text += formatter.getvalue()
-        help_text += template_help(width=formatter.width)
-        formatter = click.HelpFormatter(width=HELP_WIDTH)
+            # build help text from all the attribute names
+            # passed to click.HelpFormatter.write_dl for formatting
+            attr_tuples = [
+                (
+                    rich_text("[bold]Attribute[/bold]", width=formatter.width),
+                    rich_text("[bold]Description[/bold]", width=formatter.width),
+                )
+            ]
+            for attr_key in sorted(EXTENDED_ATTRIBUTE_NAMES):
+                # get short and long name
+                attr = MDITEM_ATTRIBUTE_SHORT_NAMES[attr_key]
+                short_name = MDITEM_ATTRIBUTE_DATA[attr]["short_name"]
+                long_name = MDITEM_ATTRIBUTE_DATA[attr]["name"]
+                constant = MDITEM_ATTRIBUTE_DATA[attr]["xattr_constant"]
+
+                # get help text
+                description = MDITEM_ATTRIBUTE_DATA[attr]["description"]
+                type_ = MDITEM_ATTRIBUTE_DATA[attr]["help_type"]
+                attr_help = f"{long_name}; {constant}; {description}; {type_}"
+
+                # add to list
+                attr_tuples.append((short_name, attr_help))
+
+            formatter.write_dl(attr_tuples)
+            formatter.write("\n")
+            formatter.write_text(
+                "For additional information on extended attributes see: https://developer.apple.com/documentation/coreservices/file_metadata/mditem/common_metadata_attribute_keys"
+            )
+            formatter.write("\n")
+            formatter.write(
+                rich_text("## Templating System", width=formatter.width, markdown=True)
+            )
+            formatter.write("\n")
+            help_text += formatter.getvalue()
+            help_text += template_help(width=formatter.width)
+            formatter = click.HelpFormatter(width=HELP_WIDTH)
+
+            formatter.write("\n")
 
-        formatter.write("\n")
         formatter.write_text(
             "With the --directory and --filename options you may specify a template for the "
             + "export directory or filename, respectively. "

osxphotos/cli/import_cli.py

@@ -1,9 +1,6 @@
 """import command for osxphotos CLI to import photos into Photos"""
 
-# Note: the style in this module is a bit different than much of the other osxphotos code
-# As an experiment, I've used mostly functions instead of classes (e.g. the report writer
-# functions vs ReportWriter class used by export) and I've kept everything for import
-# self-contained in this one file
+from __future__ import annotations
 
 import csv
 import datetime
@@ -23,13 +20,13 @@ from textwrap import dedent
 from typing import Callable, Dict, List, Optional, Tuple, Union
 
 import click
-from photoscript import Photo, PhotosLibrary
 from rich.console import Console
 from rich.markdown import Markdown
 from strpdatetime import strpdatetime
 
-from osxphotos._constants import _OSXPHOTOS_NONE_SENTINEL
+from osxphotos._constants import _OSXPHOTOS_NONE_SENTINEL, SQLITE_CHECK_SAME_THREAD
 from osxphotos._version import __version__
+from osxphotos.cli.cli_params import TIMESTAMP_OPTION, VERBOSE_OPTION
 from osxphotos.cli.common import get_data_dir
 from osxphotos.cli.help import HELP_WIDTH
 from osxphotos.cli.param_types import FunctionCall, StrpDateTimePattern, TemplateString
@@ -45,20 +42,23 @@ from osxphotos.photoinfo import PhotoInfoNone
 from osxphotos.photosalbum import PhotosAlbumPhotoScript
 from osxphotos.phototemplate import PhotoTemplate, RenderOptions
 from osxphotos.sqlitekvstore import SQLiteKVStore
-from osxphotos.utils import pluralize
+from osxphotos.utils import assert_macos, pluralize
 
-from .click_rich_echo import (
-    rich_click_echo,
-    rich_echo_error,
-    set_rich_console,
-    set_rich_theme,
-    set_rich_timestamp,
-)
-from .color_themes import get_theme
-from .common import THEME_OPTION
+assert_macos()
+
+from photoscript import Photo, PhotosLibrary
+
+from .cli_params import THEME_OPTION
+from .click_rich_echo import rich_click_echo, rich_echo_error
 from .rich_progress import rich_progress
 from .verbose import get_verbose_console, verbose_print
 
+# Note: the style in this module is a bit different than much of the other osxphotos code
+# As an experiment, I've used mostly functions instead of classes (e.g. the report writer
+# functions vs ReportWriter class used by export) and I've kept everything for import
+# self-contained in this one file
+
+
 MetaData = namedtuple("MetaData", ["title", "description", "keywords", "location"])
 
 OSXPHOTOS_ABOUT_STRING = f"Created by osxphotos version {__version__} (https://github.com/RhetTbull/osxphotos) on {datetime.datetime.now()}"
@@ -80,7 +80,8 @@ def echo(message, emoji=True, **kwargs):
 class PhotoInfoFromFile:
     """Mock PhotoInfo class for a file to be imported
 
-    Returns None for most attributes but allows some templates like exiftool and created to work correctly"""
+    Returns None for most attributes but allows some templates like exiftool and created to work correctly
+    """
 
     def __init__(self, filepath: Union[str, Path], exiftool: Optional[str] = None):
         self._path = str(filepath)
@@ -165,7 +166,8 @@ def import_photo(
     Args:
         filepath: path to the file to import
         dup_check: enable or disable Photo's duplicate check on import
-        verbose: Callable"""
+        verbose: Callable
+    """
     if imported := PhotosLibrary().import_photos(
         [filepath], skip_duplicate_check=not dup_check
     ):
@@ -207,7 +209,7 @@ def add_photo_to_albums(
     split_folder: str,
     exiftool_path: Path,
     verbose: Callable[..., None],
-):
+) -> list[str]:
     """Add photo to one or more albums"""
     albums = []
     for a in album:
@@ -225,6 +227,7 @@ def add_photo_to_albums(
             a, verbose=verbose, split_folder=split_folder, rich=True
         )
         photos_album.add(photo)
+    return albums
 
 
 def clear_photo_metadata(photo: Photo, filepath: Path, verbose: Callable[..., None]):
@@ -348,7 +351,11 @@ def location_from_file(
     return latitude, longitude
 
 
-def set_photo_metadata(photo: Photo, metadata: MetaData, merge_keywords: bool):
+def set_photo_metadata(
+    photo: Photo,
+    metadata: MetaData,
+    merge_keywords: bool,
+) -> MetaData:
     """Set metadata (title, description, keywords) for a Photo object"""
     photo.title = metadata.title
     photo.description = metadata.description
@@ -358,6 +365,7 @@ def set_photo_metadata(photo: Photo, metadata: MetaData, merge_keywords: bool):
             keywords.extend(old_keywords)
             keywords = list(set(keywords))
     photo.keywords = keywords
+    return MetaData(metadata.title, metadata.description, keywords, metadata.location)
 
 
 def set_photo_metadata_from_exiftool(
@@ -366,12 +374,12 @@ def set_photo_metadata_from_exiftool(
     exiftool_path: str,
     merge_keywords: bool,
     verbose: Callable[..., None],
-):
+) -> MetaData:
     """Set photo's metadata by reading metadata form file with exiftool"""
     verbose(f"Setting metadata and location from EXIF for [filename]{filepath.name}[/]")
     metadata = metadata_from_file(filepath, exiftool_path)
     if any([metadata.title, metadata.description, metadata.keywords]):
-        set_photo_metadata(photo, metadata, merge_keywords)
+        metadata = set_photo_metadata(photo, metadata, merge_keywords)
         verbose(f"Set metadata for [filename]{filepath.name}[/]:")
         verbose(
             f"title='{metadata.title}', description='{metadata.description}', keywords={metadata.keywords}"
@@ -387,6 +395,7 @@ def set_photo_metadata_from_exiftool(
         )
     else:
         verbose(f"No location to set for [filename]{filepath.name}[/]")
+    return metadata
 
 
 def set_photo_title(
@@ -396,7 +405,7 @@ def set_photo_title(
     title_template: str,
     exiftool_path: str,
     verbose: Callable[..., None],
-):
+) -> str:
     """Set title of photo"""
     title_text = render_photo_template(
         filepath, relative_filepath, title_template, exiftool_path
@@ -412,6 +421,9 @@ def set_photo_title(
             f"Setting title of photo [filename]{filepath.name}[/] to '{title_text[0]}'"
         )
         photo.title = title_text[0]
+        return title_text[0]
+    else:
+        return ""
 
 
 def set_photo_description(
@@ -421,7 +433,7 @@ def set_photo_description(
     description_template: str,
     exiftool_path: str,
     verbose: Callable[..., None],
-):
+) -> str:
     """Set description of photo"""
     description_text = render_photo_template(
         filepath, relative_filepath, description_template, exiftool_path
@@ -437,6 +449,9 @@ def set_photo_description(
             f"Setting description of photo [filename]{filepath.name}[/] to '{description_text[0]}'"
         )
         photo.description = description_text[0]
+        return description_text[0]
+    else:
+        return ""
 
 
 def set_photo_keywords(
@@ -447,7 +462,7 @@ def set_photo_keywords(
     exiftool_path: str,
     merge: bool,
     verbose: Callable[..., None],
-):
+) -> list[str]:
     """Set keywords of photo"""
     keywords = []
     for keyword in keyword_template:
@@ -460,6 +475,7 @@ def set_photo_keywords(
                 keywords = list(set(keywords))
         verbose(f"Setting keywords of photo [filename]{filepath.name}[/] to {keywords}")
         photo.keywords = keywords
+    return keywords
 
 
 def set_photo_location(
@@ -467,17 +483,18 @@ def set_photo_location(
     filepath: Path,
     location: Tuple[float, float],
     verbose: Callable[..., None],
-):
+) -> tuple[float, float]:
     """Set location of photo"""
     verbose(
         f"Setting location of photo [filename]{filepath.name}[/] to {location[0]}, {location[1]}"
     )
     photo.location = location
+    return location
 
 
 def set_photo_date_from_filename(
     photo: Photo, filepath: Path, parse_date: str, verbose: Callable[..., None]
-):
+) -> datetime.datetime | None:
     """Set date of photo from filename"""
     # TODO: handle timezone (use code from timewarp), for now convert timezone to local timezone
     try:
@@ -495,11 +512,12 @@ def set_photo_date_from_filename(
         verbose(
             f"[warning]Could not parse date from filename [filename]{filepath.name}[/][/]"
         )
-        return
+        return None
     verbose(
         f"Setting date of photo [filename]{filepath.name}[/] to [time]{date.strftime('%Y-%m-%d %H:%M:%S')}[/]"
     )
     photo.date = date
+    return date
 
 
 def get_relative_filepath(filepath: Path, relative_to: Optional[str]) -> Path:
@@ -592,6 +610,8 @@ def check_templates_and_exit(
 
 @dataclass
 class ReportRecord:
+    """Dataclass that records metadata on each file imported for writing to report"""
+
     albums: List[str] = field(default_factory=list)
     description: str = ""
     error: bool = False
@@ -619,6 +639,13 @@ class ReportRecord:
         )
         return cls(**dict_data)
 
+    def update_from_metadata(self, metadata: MetaData):
+        """Update a ReportRecord with data from a MetaData"""
+        self.title = metadata.title
+        self.description = metadata.description
+        self.keywords = metadata.keywords
+        self.location = metadata.location
+
     def asdict(self):
         return asdict(self)
 
@@ -632,15 +659,15 @@ class ReportRecord:
 
 def update_report_record(report_record: ReportRecord, photo: Photo, filepath: Path):
     """Update a ReportRecord with data from a Photo"""
-    report_record.albums = [a.title for a in photo.albums]
-    report_record.description = photo.description
+
+    # do not update albums as they are added to the report record as they are imported (#934)
     report_record.filename = filepath.name
     report_record.filepath = filepath
-    report_record.imported = True
+    report_record.uuid = photo.uuid
+    report_record.title = photo.title
+    report_record.description = photo.description
     report_record.keywords = photo.keywords
     report_record.location = photo.location
-    report_record.title = photo.title
-    report_record.uuid = photo.uuid
 
     return report_record
 
@@ -722,7 +749,7 @@ def write_sqlite_report(
 
     file_exists = os.path.isfile(report_file)
 
-    conn = sqlite3.connect(report_file)
+    conn = sqlite3.connect(report_file, check_same_thread=SQLITE_CHECK_SAME_THREAD)
     c = conn.cursor()
 
     if not append or not file_exists:
@@ -1333,10 +1360,8 @@ class ImportCommand(click.Command):
     help="If used with --report, add data to existing report file instead of overwriting it. "
     "See also --report.",
 )
-@click.option("--verbose", "-V", "verbose_", is_flag=True, help="Print verbose output.")
-@click.option(
-    "--timestamp", "-T", is_flag=True, help="Add time stamp to verbose output"
-)
+@VERBOSE_OPTION
+@TIMESTAMP_OPTION
 @click.option(
     "--no-progress", is_flag=True, help="Do not display progress bar during import."
 )
@@ -1390,19 +1415,12 @@ def import_cli(
     theme,
     timestamp,
     title,
-    verbose_,
+    verbose_flag,
     walk,
 ):
     """Import photos and videos into Photos."""
 
-    color_theme = get_theme(theme)
-    verbose = verbose_print(
-        verbose_, timestamp, rich=True, theme=color_theme, highlight=False
-    )
-    # set console for rich_echo to be same as for verbose_
-    set_rich_console(get_verbose_console())
-    set_rich_theme(color_theme)
-    set_rich_timestamp(timestamp)
+    verbose = verbose_print(verbose=verbose_flag, timestamp=timestamp, theme=theme)
 
     if not files:
         echo("Nothing to import", err=True)
@@ -1477,11 +1495,13 @@ def import_cli(
             report_data[filepath] = ReportRecord(
                 filepath=filepath, filename=filepath.name
             )
+            report_record = report_data[filepath]
             photo, error = import_photo(filepath, dup_check, verbose)
             if error:
                 error_count += 1
-                report_data[filepath].error = True
+                report_record.error = True
                 continue
+            report_record.imported = True
             imported_count += 1
 
             if clear_metadata:
@@ -1492,12 +1512,21 @@ def import_cli(
 
             if exiftool:
                 set_photo_metadata_from_exiftool(
-                    photo, filepath, exiftool_path, merge_keywords, verbose
+                    photo,
+                    filepath,
+                    exiftool_path,
+                    merge_keywords,
+                    verbose,
                 )
 
             if title:
                 set_photo_title(
-                    photo, filepath, relative_filepath, title, exiftool_path, verbose
+                    photo,
+                    filepath,
+                    relative_filepath,
+                    title,
+                    exiftool_path,
+                    verbose,
                 )
 
             if description:
@@ -1526,9 +1555,10 @@ def import_cli(
 
             if parse_date:
                 set_photo_date_from_filename(photo, filepath, parse_date, verbose)
+                # TODO: ReportRecord doesn't currently record date
 
             if album:
-                add_photo_to_albums(
+                report_record.albums = add_photo_to_albums(
                     photo,
                     filepath,
                     relative_filepath,
@@ -1543,14 +1573,15 @@ def import_cli(
                     # post function is tuple of (function, filename.py::function_name)
                     verbose(f"Calling post-function [bold]{function[1]}")
                     try:
-                        function[0](photo, filepath, verbose)
+                        function[0](photo, filepath, verbose, report_record)
                     except Exception as e:
                         rich_echo_error(
                             f"[error]Error running post-function [italic]{function[1]}[/italic]: {e}"
                         )
 
-            update_report_record(report_data[filepath], photo, filepath)
-            import_db.set(str(filepath), report_data[filepath])
+            # update report data
+            update_report_record(report_record, photo, filepath)
+            import_db.set(str(filepath), report_record)
 
             progress.advance(task)
 

osxphotos/cli/info.py

@@ -8,7 +8,8 @@ import yaml
 import osxphotos
 from osxphotos._constants import _PHOTOS_4_VERSION
 
-from .common import DB_ARGUMENT, DB_OPTION, JSON_OPTION, get_photos_db
+from .cli_params import DB_ARGUMENT, DB_OPTION, JSON_OPTION
+from .common import get_photos_db
 from .list import _list_libraries
 
 

osxphotos/cli/install_uninstall_run.py

@@ -1,5 +1,7 @@
 """install/uninstall/run commands for osxphotos CLI"""
 
+
+import contextlib
 import sys
 from runpy import run_module, run_path
 
@@ -50,14 +52,19 @@ def uninstall(packages, yes):
 
 
 @click.command(name="run", cls=RunCommand)
-# help command passed just to keep click from intercepting help
-# and allowing --help to be passed to the script being run
 @click.option("--help", "-h", is_flag=True, help="Show this message and exit")
 @click.argument("python_file", nargs=1, type=click.Path(exists=True))
 @click.argument("args", metavar="ARGS", nargs=-1)
 def run(python_file, help, args):
     """Run a python file using same environment as osxphotos.
     Any args are made available to the python file."""
-    # drop first two arguments, which are the osxphotos script and run command
-    sys.argv = sys.argv[2:]
+
+    # Need to drop all the args from sys.argv up to and including the run command
+    # For example, command could be one of the following:
+    # osxphotos run example.py --help
+    # osxphotos --debug run example.py --verbose --db /path/to/photos.db
+    # etc.
+    with contextlib.suppress(ValueError):
+        index = sys.argv.index("run")
+        sys.argv = sys.argv[index + 1 :]
     run_path(python_file, run_name="__main__")

osxphotos/cli/keywords.py

@@ -7,7 +7,8 @@ import yaml
 
 import osxphotos
 
-from .common import DB_ARGUMENT, DB_OPTION, JSON_OPTION, get_photos_db
+from .cli_params import DB_ARGUMENT, DB_OPTION, JSON_OPTION
+from .common import get_photos_db
 from .list import _list_libraries
 
 

osxphotos/cli/kvstore.py

@@ -0,0 +1,50 @@
+"""Simple interface to SQLiteKVStore for storing state between runs of the CLI tool."""
+
+
+from __future__ import annotations
+
+import atexit
+import contextlib
+import datetime
+
+from osxphotos.sqlitekvstore import SQLiteKVStore
+
+from .common import get_data_dir
+
+__all__ = ["kvstore"]
+
+# Store open connections
+__kvstores = []
+
+
+@atexit.register
+def close_kvstore():
+    """Close any open SQLiteKVStore databases"""
+    global __kvstores
+    for kv in __kvstores:
+        with contextlib.suppress(Exception):
+            kv.close()
+
+
+def kvstore(name: str) -> SQLiteKVStore:
+    """Return a key/value store for storing state between commands.
+
+    The key/value store is a SQLite database stored in the user's XDG data directory,
+    usually `~/.local/share/`.  The key/value store can be used like a dict to store
+    arbitrary key/value pairs which persist between runs of the CLI tool.
+
+    Args:
+        name: a unique name for the key/value store
+
+    Returns:
+        SQLiteKVStore object
+    """
+    global __kvstores
+    data_dir = get_data_dir()
+    if not name.endswith(".db"):
+        name += ".db"
+    kv = SQLiteKVStore(str(data_dir / name), wal=True)
+    if not kv.about:
+        kv.about = f"Key/value store for {name}, created by osxphotos CLI on {datetime.datetime.now()}"
+    __kvstores.append(kv)
+    return kv

osxphotos/cli/labels.py

@@ -7,7 +7,8 @@ import yaml
 
 import osxphotos
 
-from .common import DB_ARGUMENT, DB_OPTION, JSON_OPTION, get_photos_db
+from .cli_params import DB_ARGUMENT, DB_OPTION, JSON_OPTION
+from .common import get_photos_db
 from .list import _list_libraries
 
 

osxphotos/cli/list.py

@@ -6,7 +6,7 @@ import click
 
 import osxphotos
 
-from .common import JSON_OPTION
+from .cli_params import JSON_OPTION
 
 
 @click.command(name="list")

osxphotos/cli/orphans.py

@@ -14,17 +14,16 @@ from typing import Dict
 import click
 
 from osxphotos import PhotosDB
-from osxphotos._constants import _PHOTOS_4_VERSION
+from osxphotos._constants import _PHOTOS_4_VERSION, UUID_PATTERN
 from osxphotos.fileutil import FileUtil
 from osxphotos.utils import increment_filename, pluralize
 
+from .cli_params import DB_OPTION, THEME_OPTION, TIMESTAMP_OPTION, VERBOSE_OPTION
 from .click_rich_echo import rich_click_echo as echo
-from .click_rich_echo import set_rich_console, set_rich_theme, set_rich_timestamp
-from .color_themes import get_theme
-from .common import DB_OPTION, THEME_OPTION, get_photos_db
+from .common import get_photos_db
 from .help import get_help_msg
 from .list import _list_libraries
-from .verbose import get_verbose_console, verbose_print
+from .verbose import verbose_print
 
 
 @click.command(name="orphans")
@@ -36,22 +35,15 @@ from .verbose import get_verbose_console, verbose_print
     help="Export orphans to directory EXPORT_PATH. If --export not specified, orphans are listed but not exported.",
 )
 @DB_OPTION
-@click.option("--verbose", "-V", "verbose", is_flag=True, help="Print verbose output.")
-@click.option("--timestamp", is_flag=True, help="Add time stamp to verbose output")
+@VERBOSE_OPTION
+@TIMESTAMP_OPTION
 @THEME_OPTION
 @click.pass_obj
 @click.pass_context
-def orphans(ctx, cli_obj, export, db, verbose, timestamp, theme):
+def orphans(ctx, cli_obj, export, db, verbose_flag, timestamp, theme):
     """Find orphaned photos in a Photos library"""
 
-    color_theme = get_theme(theme)
-    verbose_ = verbose_print(
-        verbose, timestamp, rich=True, theme=color_theme, highlight=False
-    )
-    # set console for rich_echo to be same as for verbose_
-    set_rich_console(get_verbose_console())
-    set_rich_theme(color_theme)
-    set_rich_timestamp(timestamp)
+    verbose_ = verbose_print(verbose=verbose_flag, timestamp=timestamp, theme=theme)
 
     # below needed for to make CliRunner work for testing
     cli_db = cli_obj.db if cli_obj is not None else None
@@ -139,8 +131,7 @@ def scan_for_files(directory: str, uuid_dict: Dict):
 
     Note: modifies uuid_dict
     """
-    uuid_pattern = r"([0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12})"
-    uuid_regex = re.compile(uuid_pattern)
+    uuid_regex = re.compile(UUID_PATTERN)
     for dirpath, dirname, filenames in os.walk(directory):
         for filename in filenames:
             if match := uuid_regex.match(filename):

osxphotos/cli/param_types.py

@@ -20,8 +20,12 @@ __all__ = [
     "BitMathSize",
     "DateOffset",
     "DateTimeISO8601",
+    "DeprecatedPath",
     "ExportDBType",
     "FunctionCall",
+    "Latitude",
+    "Longitude",
+    "PathOrStdin",
     "StrpDateTimePattern",
     "TemplateString",
     "TimeISO8601",
@@ -31,8 +35,39 @@ __all__ = [
 ]
 
 
-class DateTimeISO8601(click.ParamType):
+class DeprecatedPath(click.Path):
+    """A click.Path that prints a deprecation warning when used."""
 
+    name = "DEPRECATED_PATH"
+
+    def __init__(self, *args, **kwargs):
+        if "deprecation_warning" in kwargs:
+            self.deprecation_warning = kwargs.pop("deprecation_warning")
+        else:
+            self.deprecation_warning = "This option is deprecated and will be removed in a future version of osxphotos."
+        super().__init__(*args, **kwargs)
+
+    def convert(self, value, param, ctx):
+        click.echo(
+            f"WARNING: {param.name} is deprecated. {self.deprecation_warning}",
+            err=True,
+        )
+        return super().convert(value, param, ctx)
+
+
+class PathOrStdin(click.Path):
+    """A click.Path or "-" to represent STDIN."""
+
+    name = "PATH_OR_STDIN"
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def convert(self, value, param, ctx):
+        return value if value == "-" else super().convert(value, param, ctx)
+
+
+class DateTimeISO8601(click.ParamType):
     name = "DATETIME"
 
     def convert(self, value, param, ctx):
@@ -46,7 +81,6 @@ class DateTimeISO8601(click.ParamType):
 
 
 class BitMathSize(click.ParamType):
-
     name = "BITMATH"
 
     def convert(self, value, param, ctx):
@@ -66,7 +100,6 @@ class BitMathSize(click.ParamType):
 
 
 class TimeISO8601(click.ParamType):
-
     name = "TIME"
 
     def convert(self, value, param, ctx):
@@ -105,7 +138,6 @@ class FunctionCall(click.ParamType):
 
 
 class ExportDBType(click.ParamType):
-
     name = "EXPORTDB"
 
     def convert(self, value, param, ctx):
@@ -240,3 +272,33 @@ class StrpDateTimePattern(click.ParamType):
                 self.fail(f"Invalid strpdatetime format string: {value}. {e}")
             else:
                 return value
+
+
+class Latitude(click.ParamType):
+    name = "Latitude"
+
+    def convert(self, value, param, ctx):
+        try:
+            latitude = float(value)
+            if latitude < -90 or latitude > 90:
+                raise ValueError
+            return latitude
+        except Exception:
+            self.fail(
+                f"Invalid latitude {value}. Must be a floating point number between -90 and 90."
+            )
+
+
+class Longitude(click.ParamType):
+    name = "Longitude"
+
+    def convert(self, value, param, ctx):
+        try:
+            longitude = float(value)
+            if longitude < -180 or longitude > 180:
+                raise ValueError
+            return longitude
+        except Exception:
+            self.fail(
+                f"Invalid longitude {value}. Must be a floating point number between -180 and 180."
+            )

osxphotos/cli/persons.py

@@ -6,7 +6,8 @@ import yaml
 
 import osxphotos
 
-from .common import DB_ARGUMENT, DB_OPTION, JSON_OPTION, get_photos_db
+from .cli_params import DB_ARGUMENT, DB_OPTION, JSON_OPTION
+from .common import get_photos_db
 from .list import _list_libraries
 
 

osxphotos/cli/photo_inspect.py

@@ -13,21 +13,26 @@ from typing import Generator, List, Optional, Tuple
 
 import bitmath
 import click
-from applescript import ScriptError
-from photoscript import PhotosLibrary
 from rich.console import Console
 from rich.layout import Layout
 from rich.live import Live
 from rich.panel import Panel
 
 from osxphotos import PhotoInfo, PhotosDB
-from osxphotos._constants import _UNKNOWN_PERSON
+from osxphotos._constants import _UNKNOWN_PERSON, search_category_factory
 from osxphotos.rich_utils import add_rich_markup_tag
-from osxphotos.text_detection import detect_text as detect_text_in_photo
-from osxphotos.utils import dd_to_dms_str
+from osxphotos.utils import assert_macos, dd_to_dms_str
 
+assert_macos()
+
+from applescript import ScriptError
+from photoscript import PhotosLibrary
+
+from osxphotos.text_detection import detect_text as detect_text_in_photo
+
+from .cli_params import DB_OPTION, THEME_OPTION
 from .color_themes import get_theme
-from .common import DB_OPTION, THEME_OPTION, get_photos_db
+from .common import get_photos_db
 
 # global that tracks UUID being inspected
 CURRENT_UUID = None
@@ -65,6 +70,22 @@ def trim(text: str, pad: str = "") -> str:
     return text if len(text) <= width else f"{text[: width- 3]}..."
 
 
+def format_search_info(photo: PhotoInfo) -> str:
+    """Format search info for photo"""
+    categories = sorted(list(photo._db._db_searchinfo_categories.keys()))
+    search_info = photo.search_info
+    if not search_info:
+        return ""
+    search_info_strs = []
+    category_dict = search_category_factory(photo._db.photos_version).categories()
+    for category in categories:
+        if text := search_info._get_text_for_category(category):
+            text = ", ".join(t for t in text if t) if isinstance(text, list) else text
+            category_name = str(category_dict.get(category, category)).lower()
+            search_info_strs.append(f"{bold(category_name)}: {text}")
+    return ", ".join(search_info_strs)
+
+
 def inspect_photo(
     photo: PhotoInfo,
     detected_text: Optional[str] = None,
@@ -138,8 +159,10 @@ def inspect_photo(
             + f"{', '.join(dd_to_dms_str(*photo.location)) if photo.location[0] else '-'}",
             bold("Place: ") + f"{photo.place.name if photo.place else '-'}",
             bold("Categories/Labels: ") + f"{', '.join(photo.labels) or '-'}",
+            bold("Search Info: ") + format_search_info(photo),
         ]
     )
+
     properties.append(format_flags(photo))
     properties.append(format_albums(photo))
 

osxphotos/cli/places.py

@@ -8,7 +8,8 @@ import yaml
 import osxphotos
 from osxphotos._constants import _PHOTOS_4_VERSION, _UNKNOWN_PLACE
 
-from .common import DB_ARGUMENT, DB_OPTION, JSON_OPTION, get_photos_db
+from .cli_params import DB_ARGUMENT, DB_OPTION, JSON_OPTION
+from .common import get_photos_db
 from .list import _list_libraries
 
 

osxphotos/cli/query.py

@@ -1,5 +1,6 @@
 """query command for osxphotos CLI"""
 
+import sys
 import click
 
 import osxphotos
@@ -9,43 +10,50 @@ from osxphotos.cli.click_rich_echo import (
     set_rich_theme,
 )
 from osxphotos.debug import set_debug
-from osxphotos.photosalbum import PhotosAlbum
 from osxphotos.phototemplate import RenderOptions
-from osxphotos.queryoptions import QueryOptions
+from osxphotos.queryoptions import query_options_from_kwargs
+from osxphotos.utils import assert_macos, is_macos
 
-from .color_themes import get_default_theme
-from .common import (
-    CLI_COLOR_ERROR,
-    CLI_COLOR_WARNING,
+if is_macos:
+    from osxphotos.photosalbum import PhotosAlbum
+
+from .cli_params import (
     DB_ARGUMENT,
     DB_OPTION,
     DELETED_OPTIONS,
     FIELD_OPTION,
     JSON_OPTION,
-    OSXPHOTOS_HIDDEN,
     QUERY_OPTIONS,
-    get_photos_db,
-    load_uuid_from_file,
+    make_click_option_decorator,
 )
+from .color_themes import get_default_theme
+from .common import CLI_COLOR_ERROR, CLI_COLOR_WARNING, OSXPHOTOS_HIDDEN, get_photos_db
 from .list import _list_libraries
 from .print_photo_info import print_photo_fields, print_photo_info
 from .verbose import get_verbose_console
 
+MACOS_OPTIONS = make_click_option_decorator(
+    *[
+        click.Option(
+            ["--add-to-album"],
+            metavar="ALBUM",
+            help="Add all photos from query to album ALBUM in Photos. Album ALBUM will be created "
+            "if it doesn't exist.  All photos in the query results will be added to this album. "
+            "This only works if the Photos library being queried is the last-opened (default) library in Photos. "
+            "This feature is currently experimental.  I don't know how well it will work on large query sets.",
+        ),
+    ]
+    if is_macos
+    else []
+)
+
 
 @click.command()
 @DB_OPTION
 @JSON_OPTION
 @QUERY_OPTIONS
 @DELETED_OPTIONS
-
-@click.option(
-    "--add-to-album",
-    metavar="ALBUM",
-    help="Add all photos from query to album ALBUM in Photos. Album ALBUM will be created "
-    "if it doesn't exist.  All photos in the query results will be added to this album. "
-    "This only works if the Photos library being queried is the last-opened (default) library in Photos. "
-    "This feature is currently experimental.  I don't know how well it will work on large query sets.",
-)
+@MACOS_OPTIONS
 @click.option(
     "--quiet",
     is_flag=True,
@@ -64,9 +72,6 @@ from .verbose import get_verbose_console
     "Most useful with --quiet. "
     "May be repeated to print multiple template strings. ",
 )
-@click.option(
-    "--debug", required=False, is_flag=True, default=False, hidden=OSXPHOTOS_HIDDEN
-)
 @DB_ARGUMENT
 @click.pass_obj
 @click.pass_context
@@ -74,93 +79,13 @@ def query(
     ctx,
     cli_obj,
     db,
-    photos_library,
-    add_to_album,
-    added_after,
-    added_before,
-    added_in_last,
-    album,
-    burst,
-    cloudasset,
-    deleted_only,
-    deleted,
-    description,
-    duplicate,
-    edited,
-    exif,
-    external_edit,
-    favorite,
     field,
-    folder,
-    from_date,
-    from_time,
-    has_comment,
-    has_likes,
-    has_raw,
-    hdr,
-    hidden,
-    ignore_case,
-    in_album,
-    incloud,
-    is_reference,
     json_,
-    keyword,
-    label,
-    live,
-    location,
-    max_size,
-    min_size,
-    missing,
-    name,
-    no_comment,
-    no_description,
-    no_likes,
-    no_location,
-    no_keyword,
-    no_place,
-    no_title,
-    not_burst,
-    not_cloudasset,
-    not_favorite,
-    not_hdr,
-    not_hidden,
-    not_in_album,
-    not_incloud,
-    not_live,
-    not_missing,
-    not_panorama,
-    not_portrait,
-    not_reference,
-    not_screenshot,
-    not_selfie,
-    not_shared,
-    not_slow_mo,
-    not_time_lapse,
-    only_movies,
-    only_photos,
-    panorama,
-    person,
-    place,
-    portrait,
     print_template,
-    query_eval,
-    query_function,
     quiet,
-    regex,
-    screenshot,
-    selected,
-    selfie,
-    shared,
-    slow_mo,
-    time_lapse,
-    title,
-    to_date,
-    to_time,
-    uti,
-    uuid_from_file,
-    uuid,
-    year,
-    debug,  # handled in cli/__init__.py
+    photos_library,
+    add_to_album=False,
+    **kwargs,
 ):
     """Query the Photos database using 1 or more search options;
     if more than one different option is provided, they are treated as "AND"
@@ -173,95 +98,14 @@ def query(
     osxphotos query --person "John Doe" --person "Jane Doe" --keyword "vacation"
 
     will return all photos with either person of ("John Doe" OR "Jane Doe") AND keyword of "vacation"
-    """
 
-    # if no query terms, show help and return
-    # sanity check input args
-    nonexclusive = [
-        added_after,
-        added_before,
-        added_in_last,
-        album,
-        duplicate,
-        edited,
-        exif,
-        external_edit,
-        folder,
-        from_date,
-        from_time,
-        has_raw,
-        keyword,
-        label,
-        max_size,
-        min_size,
-        name,
-        person,
-        query_eval,
-        query_function,
-        regex,
-        selected,
-        to_date,
-        to_time,
-        uti,
-        uuid_from_file,
-        uuid,
-        year,
-    ]
-    exclusive = [
-        (any(description), no_description),
-        (any(place), no_place),
-        (any(title), no_title),
-        (any(keyword), no_keyword),
-        (burst, not_burst),
-        (cloudasset, not_cloudasset),
-        (deleted, deleted_only),
-        (favorite, not_favorite),
-        (has_comment, no_comment),
-        (has_likes, no_likes),
-        (hdr, not_hdr),
-        (hidden, not_hidden),
-        (in_album, not_in_album),
-        (incloud, not_incloud),
-        (live, not_live),
-        (location, no_location),
-        (missing, not_missing),
-        (only_photos, only_movies),
-        (panorama, not_panorama),
-        (portrait, not_portrait),
-        (screenshot, not_screenshot),
-        (selfie, not_selfie),
-        (shared, not_shared),
-        (slow_mo, not_slow_mo),
-        (time_lapse, not_time_lapse),
-        (is_reference, not_reference),
-    ]
-    # print help if no non-exclusive term or a double exclusive term is given
-    if any(all(bb) for bb in exclusive) or not any(
-        nonexclusive + [b ^ n for b, n in exclusive]
-    ):
-        click.echo("Incompatible query options", err=True)
-        click.echo(ctx.obj.group.commands["query"].get_help(ctx), err=True)
-        return
+    If not query options are provided, all photos in the library will be returned.
+    """
 
     # set console for rich_echo to be same as for verbose_
     set_rich_console(get_verbose_console())
     set_rich_theme(get_default_theme())
 
-    # actually have something to query
-    # default searches for everything
-    photos = True
-    movies = True
-    if only_movies:
-        photos = False
-    if only_photos:
-        movies = False
-
-    # load UUIDs if necessary and append to any uuids passed with --uuid
-    if uuid_from_file:
-        uuid_list = list(uuid)  # Click option is a tuple
-        uuid_list.extend(load_uuid_from_file(uuid_from_file))
-        uuid = tuple(uuid_list)
-
     # below needed for to make CliRunner work for testing
     cli_db = cli_obj.db if cli_obj is not None else None
     db = get_photos_db(*photos_library, db, cli_db)
@@ -271,104 +115,30 @@ def query(
         _list_libraries()
         return
 
+    try:
+        query_options = query_options_from_kwargs(**kwargs)
+    except Exception as e:
+        raise click.BadOptionUsage("query", str(e)) from e
+
     photosdb = osxphotos.PhotosDB(dbfile=db)
-    query_options = QueryOptions(
-        added_after=added_after,
-        added_before=added_before,
-        added_in_last=added_in_last,
-        album=album,
-        burst=burst,
-        cloudasset=cloudasset,
-        deleted_only=deleted_only,
-        deleted=deleted,
-        description=description,
-        duplicate=duplicate,
-        edited=edited,
-        exif=exif,
-        external_edit=external_edit,
-        favorite=favorite,
-        folder=folder,
-        from_date=from_date,
-        from_time=from_time,
-        function=query_function,
-        has_comment=has_comment,
-        has_likes=has_likes,
-        has_raw=has_raw,
-        hdr=hdr,
-        hidden=hidden,
-        ignore_case=ignore_case,
-        in_album=in_album,
-        incloud=incloud,
-        is_reference=is_reference,
-        keyword=keyword,
-        label=label,
-        live=live,
-        location=location,
-        max_size=max_size,
-        min_size=min_size,
-        missing=missing,
-        movies=movies,
-        name=name,
-        no_comment=no_comment,
-        no_description=no_description,
-        no_likes=no_likes,
-        no_location=no_location,
-        no_keyword=no_keyword,
-        no_place=no_place,
-        no_title=no_title,
-        not_burst=not_burst,
-        not_cloudasset=not_cloudasset,
-        not_favorite=not_favorite,
-        not_hdr=not_hdr,
-        not_hidden=not_hidden,
-        not_in_album=not_in_album,
-        not_incloud=not_incloud,
-        not_live=not_live,
-        not_missing=not_missing,
-        not_panorama=not_panorama,
-        not_portrait=not_portrait,
-        not_reference=not_reference,
-        not_screenshot=not_screenshot,
-        not_selfie=not_selfie,
-        not_shared=not_shared,
-        not_slow_mo=not_slow_mo,
-        not_time_lapse=not_time_lapse,
-        panorama=panorama,
-        person=person,
-        photos=photos,
-        place=place,
-        portrait=portrait,
-        query_eval=query_eval,
-        regex=regex,
-        screenshot=screenshot,
-        selected=selected,
-        selfie=selfie,
-        shared=shared,
-        slow_mo=slow_mo,
-        time_lapse=time_lapse,
-        title=title,
-        to_date=to_date,
-        to_time=to_time,
-        uti=uti,
-        uuid=uuid,
-        year=year,
-    )
 
     try:
         photos = photosdb.query(query_options)
     except ValueError as e:
-        if "Invalid query_eval CRITERIA:" in str(e):
-            msg = str(e).split(":")[1]
-            raise click.BadOptionUsage(
-                "query_eval", f"Invalid query-eval CRITERIA: {msg}"
-            )
-        else:
-            raise ValueError(e)
+        if "Invalid query_eval CRITERIA:" not in str(e):
+            raise ValueError(e) from e
+
+        msg = str(e).split(":")[1]
+        raise click.BadOptionUsage(
+            "query_eval", f"Invalid query-eval CRITERIA: {msg}"
+        ) from e
 
     # below needed for to make CliRunner work for testing
     cli_json = cli_obj.json if cli_obj is not None else None
 
     if add_to_album and photos:
+        assert_macos()
+
         album_query = PhotosAlbum(add_to_album, verbose=None)
         photo_len = len(photos)
         photo_word = "photos" if photo_len > 1 else "photo"

osxphotos/cli/repl.py

@@ -1,32 +1,39 @@
 """repl command for osxphotos CLI"""
+from __future__ import annotations
 
 import os
 import os.path
 import pathlib
+import re
+import shlex
+import subprocess
 import sys
 import time
+from functools import partial
 from typing import List
 
 import click
-import photoscript
 from rich import pretty, print
 
 import osxphotos
 from osxphotos._constants import _PHOTOS_4_VERSION
+from osxphotos.cli.click_rich_echo import rich_echo_error as echo_error
 from osxphotos.photoinfo import PhotoInfo
 from osxphotos.photosdb import PhotosDB
 from osxphotos.pyrepl import embed_repl
-from osxphotos.queryoptions import QueryOptions
-
-from .common import (
-    DB_ARGUMENT,
-    DB_OPTION,
-    DELETED_OPTIONS,
+from osxphotos.queryoptions import (
     IncompatibleQueryOptions,
-    QUERY_OPTIONS,
-    get_photos_db,
+    QueryOptions,
     query_options_from_kwargs,
 )
+from osxphotos.utils import assert_macos, is_macos
+
+if is_macos:
+    import photoscript
+    from applescript import ScriptError
+
+from .cli_params import DB_ARGUMENT, DB_OPTION, DELETED_OPTIONS, QUERY_OPTIONS
+from .common import get_photos_db
 
 
 @click.command(name="repl")
@@ -54,7 +61,9 @@ def repl(ctx, cli_obj, db, emacs, beta, **kwargs):
     import logging
 
     from objexplore import explore
-    from photoscript import Album, Photo, PhotosLibrary
+
+    if is_macos:
+        from photoscript import Album, Photo, PhotosLibrary
     from rich import inspect as _inspect
 
     from osxphotos import ExifTool, PhotoInfo, PhotosDB
@@ -70,6 +79,11 @@ def repl(ctx, cli_obj, db, emacs, beta, **kwargs):
     logger.disabled = True
 
     pretty.install()
+    try:
+        query_options = query_options_from_kwargs(**kwargs)
+    except IncompatibleQueryOptions as e:
+        echo_error(f"Incompatible query options: {e}")
+        ctx.exit(1)
     print(f"python version: {sys.version}")
     print(f"osxphotos version: {osxphotos._version.__version__}")
     db = db or get_photos_db()
@@ -80,12 +94,6 @@ def repl(ctx, cli_obj, db, emacs, beta, **kwargs):
         print("Beta mode enabled")
     print("Getting photos")
     tic = time.perf_counter()
-    try:
-        query_options = query_options_from_kwargs(**kwargs)
-    except IncompatibleQueryOptions:
-        click.echo("Incompatible query options", err=True)
-        click.echo(ctx.obj.group.commands["repl"].get_help(ctx), err=True)
-        sys.exit(1)
     photos = _query_photos(photosdb, query_options)
     all_photos = _get_all_photos(photosdb)
     toc = time.perf_counter()
@@ -95,6 +103,7 @@ def repl(ctx, cli_obj, db, emacs, beta, **kwargs):
     get_photo = photosdb.get_photo
     show = _show_photo
     spotlight = _spotlight_photo
+    find = partial(_find_in_library, photosdb)
     get_selected = _get_selected(photosdb)
     try:
         selected = get_selected()
@@ -124,28 +133,31 @@ def repl(ctx, cli_obj, db, emacs, beta, **kwargs):
     )
     print(f"\nThe following functions may be helpful:")
     print(
-        f"- get_photo(uuid): return a PhotoInfo object for photo with uuid; e.g. get_photo('B13F4485-94E0-41CD-AF71-913095D62E31')"
+        "- get_photo(uuid): return a PhotoInfo object for photo with uuid; e.g. get_photo('B13F4485-94E0-41CD-AF71-913095D62E31')"
     )
     print(
-        f"- get_selected(); return list of PhotoInfo objects for photos selected in Photos"
+        "- get_selected(); return list of PhotoInfo objects for photos selected in Photos"
     )
     print(
-        f"- show(photo): open a photo object in the default viewer; e.g. show(selected[0])"
+        "- show(photo): open a photo object in the default viewer; e.g. show(selected[0])"
     )
     print(
-        f"- show(path): open a file at path in the default viewer; e.g. show('/path/to/photo.jpg')"
+        "- show(path): open a file at path in the default viewer; e.g. show('/path/to/photo.jpg')"
     )
-    print(f"- spotlight(photo): open a photo and spotlight it in Photos")
+    print("- spotlight(photo): open a photo and spotlight it in Photos")
     # print(
     #     f"- help(object): print help text including list of methods for object; for example, help(PhotosDB)"
     # )
     print(
-        f"- inspect(object): print information about an object; e.g. inspect(PhotoInfo)"
+        "- inspect(object): print information about an object; e.g. inspect(PhotoInfo)"
     )
     print(
-        f"- explore(object): interactively explore an object with objexplore; e.g. explore(PhotoInfo)"
+        "- explore(object): interactively explore an object with objexplore; e.g. explore(PhotoInfo)"
     )
-    print(f"- q, quit, quit(), exit, exit(): exit this interactive shell\n")
+    print(
+        "- find(text): search for files matching text in Photos library; e.g. find('B13F4485')"
+    )
+    print("- q, quit, quit(), exit, exit(): exit this interactive shell\n")
 
     embed_repl(
         globals=globals(),
@@ -194,15 +206,23 @@ def _get_selected(photosdb):
     """get list of PhotoInfo objects for photos selected in Photos"""
 
     def get_selected():
-        selected = photoscript.PhotosLibrary().selection
-        if not selected:
-            return []
-        return photosdb.photos(uuid=[p.uuid for p in selected])
+        assert_macos()
+        try:
+            selected = photoscript.PhotosLibrary().selection
+        except ScriptError as e:
+            # some photos (e.g. shared items) can't be selected and raise ScriptError:
+            # applescript.ScriptError: Photos got an error: Can’t get media item id "34C26DFA-0CEA-4DB7-8FDA-B87789B3209D/L0/001". (-1728) app='Photos' range=16820-16873
+            # In this case, we can parse the UUID from the error (though this only works for a single selected item)
+            if match := re.match(r".*Can’t get media item id \"(.*)\".*", str(e)):
+                uuid = match[1].split("/")[0]
+                return photosdb.photos(uuid=[uuid])
+        return photosdb.photos(uuid=[p.uuid for p in selected]) if selected else []
 
     return get_selected
 
 
 def _spotlight_photo(photo: PhotoInfo):
+    assert_macos()
     photo_ = photoscript.Photo(photo.uuid)
     photo_.spotlight()
 
@@ -220,3 +240,20 @@ def _query_photos(photosdb: PhotosDB, query_options: QueryOptions) -> List:
         ) from e
 
     return photos
+
+
+def _find_in_library(photosdb: PhotosDB, search_str: str) -> list[str]:
+    """Find files in Photos library matching search_str using find command"""
+    # this is a quick and dirty way to find files in the Photos library
+    # e.g. those matching a UUID or a filename
+    library_path = photosdb.library_path
+    if not library_path:
+        raise ValueError("Could not find Photos library")
+
+    search_str = shlex.quote(search_str)
+    library_path = shlex.quote(library_path)
+    cmd = f"find {library_path} | grep {search_str}"
+    output = subprocess.check_output(cmd, shell=True, universal_newlines=True)
+
+    # Split the output into lines and return as a list
+    return output.strip().split("\n")

osxphotos/cli/report_writer.py

@@ -12,6 +12,7 @@ from abc import ABC, abstractmethod
 from contextlib import suppress
 from typing import Dict, Union
 
+from osxphotos._constants import SQLITE_CHECK_SAME_THREAD
 from osxphotos.export_db import OSXPHOTOS_ABOUT_STRING
 from osxphotos.photoexporter import ExportResults
 from osxphotos.sqlite_utils import sqlite_columns
@@ -181,7 +182,9 @@ class ExportReportWriterSQLite(ReportWriterABC):
             with suppress(FileNotFoundError):
                 os.unlink(self.output_file)
 
-        self._conn = sqlite3.connect(self.output_file)
+        self._conn = sqlite3.connect(
+            self.output_file, check_same_thread=SQLITE_CHECK_SAME_THREAD
+        )
         self._create_tables()
         self.report_id = self._generate_report_id()
 
@@ -533,7 +536,9 @@ class SyncReportWriterSQLite(ReportWriterABC):
             with suppress(FileNotFoundError):
                 os.unlink(self.output_file)
 
-        self._conn = sqlite3.connect(self.output_file)
+        self._conn = sqlite3.connect(
+            self.output_file, check_same_thread=SQLITE_CHECK_SAME_THREAD
+        )
         self._create_tables()
         self.report_id = self._generate_report_id()
 

osxphotos/cli/show_command.py

@@ -0,0 +1,98 @@
+"""osxphotos show command"""
+
+import pathlib
+import re
+
+import click
+
+from osxphotos._constants import UUID_PATTERN
+from osxphotos.export_db_utils import get_uuid_for_filepath
+from osxphotos.photosdb.photosdb_utils import get_photos_library_version
+from osxphotos.utils import get_last_library_path, assert_macos
+
+assert_macos()
+
+from osxphotos.photoscript_utils import (
+    photoscript_object_from_name,
+    photoscript_object_from_uuid,
+)
+
+from .cli_commands import echo, echo_error
+from .cli_params import DB_OPTION
+from .click_rich_echo import set_rich_theme
+
+
+@click.command(name="show")
+@DB_OPTION
+@click.argument("uuid_or_name", metavar="UUID_OR_NAME", nargs=1, required=True)
+@click.pass_context
+def show(ctx, db, uuid_or_name):
+    """Show photo, album, or folder in Photos from UUID_OR_NAME
+
+    Examples:
+
+    osxphotos show 12345678-1234-1234-1234-123456789012
+
+    osxphotos show "My Album"
+
+    osxphotos show "My Folder"
+
+    osxphotos show IMG_1234.JPG
+
+    show can also be used to show a photo exported with `osxphotos export`:
+
+    osxphotos show /path/to/exported/photo.jpg
+
+    In this case, the UUID_OR_NAME is the path to the exported photo and osxphotos
+    will attempt to find the export database to match the photo to the original in
+    Photos. If your export database is not in the default location in the root of the
+    export directory, this will not work.
+
+    Notes:
+
+    This command requires Photos library version 5 or higher.
+    Currently this command cannot be used to show subfolders in Photos.
+    """
+    db = db or get_last_library_path()
+    if not db:
+        echo(
+            "Could not find Photos library. Use --library/--db to specify path to Photos library."
+        )
+        ctx.exit(1)
+
+    if get_photos_library_version(db) < 5:
+        echo_error("[error]show command requires Photos library version 5 or higher")
+        ctx.exit(1)
+
+    try:
+        if re.match(UUID_PATTERN, uuid_or_name):
+            if not (obj := photoscript_object_from_uuid(uuid_or_name, db)):
+                raise ValueError(
+                    f"could not find asset with UUID [uuid]{uuid_or_name}[/]"
+                )
+            obj_type = obj.__class__.__name__
+            echo(f"Found [filename]{obj_type}[/] with UUID: [uuid]{uuid_or_name}[/]")
+            obj.spotlight()
+        elif obj := photoscript_object_from_name(uuid_or_name, db):
+            obj_type = obj.__class__.__name__
+            echo(
+                f"Found [filename]{obj_type}[/] with name: [filepath]{uuid_or_name}[/]"
+            )
+            obj.spotlight()
+        elif uuid := get_uuid_for_filepath(pathlib.Path(uuid_or_name).resolve()):
+            if not (obj := photoscript_object_from_uuid(uuid, db)):
+                raise ValueError(
+                    f"could not find asset with UUID [uuid]{uuid}[/] for file [filepath]{uuid_or_name}[/]"
+                )
+            obj_type = obj.__class__.__name__
+            echo(
+                f"Found [filename]{obj_type}[/] from export database: [filepath]{uuid_or_name}[/]"
+            )
+            obj.spotlight()
+        else:
+            raise ValueError(
+                f"could not find asset with name [filepath]{uuid_or_name}[/]"
+            )
+    except Exception as e:
+        echo_error(f"[error]Error finding asset [uuid]{uuid_or_name}[/]: {e}")
+        ctx.exit(1)

osxphotos/cli/snap_diff.py

@@ -12,7 +12,8 @@ from rich.syntax import Syntax
 
 import osxphotos
 
-from .common import DB_OPTION, OSXPHOTOS_SNAPSHOT_DIR, get_photos_db
+from .cli_params import DB_OPTION, TIMESTAMP_OPTION, VERBOSE_OPTION
+from .common import OSXPHOTOS_SNAPSHOT_DIR, get_photos_db
 from .verbose import verbose_print
 
 
@@ -30,7 +31,7 @@ def snap(ctx, cli_obj, db):
     Works only on Photos library versions since Catalina (10.15) or newer.
     """
 
-    db = get_photos_db(db, cli_obj.db)
+    db = get_photos_db(db, cli_obj.db if cli_obj else None)
     db_path = pathlib.Path(db)
     if db_path.is_file():
         # assume it's the sqlite file
@@ -80,8 +81,9 @@ def snap(ctx, cli_obj, db):
     "Default is 'monokai'.",
 )
 @click.argument("db2", nargs=-1, type=click.Path(exists=True))
-@click.option("--verbose", "-V", "verbose", is_flag=True, help="Print verbose output.")
-def diff(ctx, cli_obj, db, raw_output, style, db2, verbose):
+@VERBOSE_OPTION
+@TIMESTAMP_OPTION
+def diff(ctx, cli_obj, db, raw_output, style, db2, verbose_flag, timestamp):
     """Compare two Photos databases and print out differences
 
     To use the diff command, you'll need to install sqldiff via homebrew:
@@ -110,7 +112,7 @@ def diff(ctx, cli_obj, db, raw_output, style, db2, verbose):
     Works only on Photos library versions since Catalina (10.15) or newer.
     """
 
-    verbose_ = verbose_print(verbose, rich=True)
+    verbose = verbose_print(verbose_flag, timestamp=timestamp)
 
     sqldiff = shutil.which("sqldiff")
     if not sqldiff:
@@ -118,9 +120,9 @@ def diff(ctx, cli_obj, db, raw_output, style, db2, verbose):
             "sqldiff not found; install via homebrew (https://brew.sh/): `brew install sqldiff`"
         )
         ctx.exit(2)
-    verbose_(f"sqldiff found at '{sqldiff}'")
+    verbose(f"sqldiff found at '{sqldiff}'")
 
-    db = get_photos_db(db, cli_obj.db)
+    db = get_photos_db(db, cli_obj.db if cli_obj else None)
     db_path = pathlib.Path(db)
     if db_path.is_file():
         # assume it's the sqlite file
@@ -133,7 +135,7 @@ def diff(ctx, cli_obj, db, raw_output, style, db2, verbose):
     else:
         # get most recent snapshot
         db_folder = os.environ.get("OSXPHOTOS_SNAPSHOT", OSXPHOTOS_SNAPSHOT_DIR)
-        verbose_(f"Using snapshot folder: '{db_folder}'")
+        verbose(f"Using snapshot folder: '{db_folder}'")
         folders = sorted([f for f in pathlib.Path(db_folder).glob("*") if f.is_dir()])
         folder_2 = folders[-1]
         db_2 = folder_2 / "Photos.sqlite"
@@ -143,7 +145,7 @@ def diff(ctx, cli_obj, db, raw_output, style, db2, verbose):
     if not db_2.exists():
         print(f"database file {db_2} missing")
 
-    verbose_(f"Comparing databases {db_1} and {db_2}")
+    verbose(f"Comparing databases {db_1} and {db_2}")
 
     diff_proc = subprocess.Popen([sqldiff, db_2, db_1], stdout=subprocess.PIPE)
     console = Console()

osxphotos/cli/sync.py

@@ -9,25 +9,33 @@ import pathlib
 from typing import Any, Callable, Literal
 
 import click
-import photoscript
 
 from osxphotos import PhotoInfo, PhotosDB, __version__
 from osxphotos.photoinfo import PhotoInfoNone
 from osxphotos.photosalbum import PhotosAlbum
 from osxphotos.photosdb.photosdb_utils import get_db_version
 from osxphotos.phototemplate import PhotoTemplate, RenderOptions
-from osxphotos.sqlitekvstore import SQLiteKVStore
-from osxphotos.utils import pluralize
-
-from .click_rich_echo import (
-    rich_click_echo,
-    rich_echo_error,
-    set_rich_console,
-    set_rich_theme,
-    set_rich_timestamp,
+from osxphotos.queryoptions import (
+    IncompatibleQueryOptions,
+    QueryOptions,
+    query_options_from_kwargs,
 )
-from .color_themes import get_theme
-from .common import DB_OPTION, QUERY_OPTIONS, THEME_OPTION, query_options_from_kwargs
+from osxphotos.sqlitekvstore import SQLiteKVStore
+from osxphotos.utils import assert_macos, pluralize
+
+assert_macos()
+
+import photoscript
+
+from .cli_params import (
+    DB_OPTION,
+    QUERY_OPTIONS,
+    THEME_OPTION,
+    TIMESTAMP_OPTION,
+    VERBOSE_OPTION,
+)
+from .click_rich_echo import rich_click_echo as echo
+from .click_rich_echo import rich_echo_error as echo_error
 from .param_types import TemplateString
 from .report_writer import sync_report_writer_factory
 from .rich_progress import rich_progress
@@ -106,7 +114,7 @@ def render_and_validate_report(report: str) -> str:
     report = report_file[0]
 
     if os.path.isdir(report):
-        rich_click_echo(
+        echo(
             f"[error]Report '{report}' is a directory, must be file name",
             err=True,
         )
@@ -162,6 +170,7 @@ def get_photo_metadata(photos: list[PhotoInfo]) -> str:
                                 photos_dict[k] = v
                             elif photos_dict[k] and v != photos_dict[k]:
                                 photos_dict[k] = f"{photos_dict[k]} {v}"
+
     # convert photos_dict to JSON string
     # wouldn't it be nice if json encoder handled datetimes...
     def default(o):
@@ -182,7 +191,7 @@ def export_metadata(
     verbose(f"Analyzing [num]{num_photos}[/] {photo_word} to export")
     verbose(f"Exporting [num]{len(photos)}[/] {photo_word} to {output_path}")
     export_metadata_to_db(photos, metadata_db, progress=True)
-    rich_click_echo(
+    echo(
         f"Done: exported metadata for [num]{len(photos)}[/] {photo_word} to [filepath]{output_path}[/]"
     )
     metadata_db.close()
@@ -255,6 +264,7 @@ def import_metadata(
     set_: tuple[str, ...],
     merge: tuple[str, ...],
     dry_run: bool,
+    unmatched: bool,
     verbose: Callable[..., None],
 ) -> SyncResults:
     """Import metadata from metadata_db"""
@@ -278,14 +288,16 @@ def import_metadata(
         # create an in memory database of the import library
         # so that the rest of the comparison code can be the same
         photosdb = PhotosDB(import_path, verbose=verbose)
-        photos = photosdb.photos()
+        # filter out shared photos which don't have a fingerprint and
+        # whose metadata can't be set
+        photos = photosdb.query(QueryOptions(not_shared=True))
         import_db = SQLiteKVStore(":memory:")
         verbose(f"Loading metadata from import library: [filepath]{import_path}[/]")
         export_metadata_to_db(photos, import_db, progress=False)
     elif import_type == "export":
         import_db = open_metadata_db(import_path)
     else:
-        rich_echo_error(
+        echo_error(
             f"Unable to determine type of import file: [filepath]{import_path}[/]"
         )
         raise click.Abort()
@@ -295,24 +307,25 @@ def import_metadata(
         if key in import_db:
             # import metadata from import_db
             for photo in key_photos:
-                rich_click_echo(
+                verbose(
                     f"Importing metadata for [filename]{photo.original_filename}[/] ([uuid]{photo.uuid}[/])"
                 )
                 metadata = import_db[key]
                 results += import_metadata_for_photo(
                     photo, metadata, set_, merge, dry_run, verbose
                 )
-        else:
+        elif unmatched:
             # unable to find metadata for photo in import_db
             for photo in key_photos:
-                rich_click_echo(
+                echo(
                     f"Unable to find metadata for [filename]{photo.original_filename}[/] ([uuid]{photo.uuid}[/]) in [filepath]{import_path}[/]"
                 )
 
-    # find any keys in import_db that don't match keys in photos
-    for key in import_db.keys():
-        if key not in key_to_photo:
-            rich_click_echo(f"Unable to find [uuid]{key}[/] in current library.")
+    if unmatched:
+        # find any keys in import_db that don't match keys in photos
+        for key in import_db.keys():
+            if key not in key_to_photo:
+                echo(f"Unable to find [uuid]{key}[/] in selected photos.")
 
     return results
 
@@ -363,7 +376,7 @@ def _update_albums_for_photo(
     before = sorted(photo.albums)
     albums_to_add = set(value) - set(before)
     if not albums_to_add:
-        verbose(f"\tNothing to do for albums")
+        verbose(f"\tNothing to do for albums", level=2)
         results.add_result(
             photo.uuid,
             photo.original_filename,
@@ -421,7 +434,7 @@ def _set_metadata_for_photo(
             if not dry_run:
                 set_photo_property(photo_, field, value)
         else:
-            verbose(f"\tNothing to do for {field}")
+            verbose(f"\tNothing to do for {field}", level=2)
 
         results.add_result(
             photo.uuid,
@@ -459,7 +472,7 @@ def _merge_metadata_for_photo(
             before = sorted(before)
 
         if value == before:
-            verbose(f"\tNothing to do for {field}")
+            verbose(f"\tNothing to do for {field}", level=2)
             results.add_result(
                 photo.uuid,
                 photo.original_filename,
@@ -481,7 +494,7 @@ def _merge_metadata_for_photo(
         elif before is None:
             new_value = value
         else:
-            rich_echo_error(
+            echo_error(
                 f"Unable to merge {field} for [filename]{photo.original_filename}[filename]"
             )
             raise click.Abort()
@@ -493,7 +506,7 @@ def _merge_metadata_for_photo(
         else:
             # Merge'd value might still be the same as original value
             # (e.g. if value is str and has previously been merged)
-            verbose(f"\tNothing to do for {field}")
+            verbose(f"\tNothing to do for {field}", level=2)
 
         results.add_result(
             photo.uuid,
@@ -529,7 +542,7 @@ def print_import_summary(results: SyncResults):
         f"updated {property}: [num]{summary.get(property,0)}[/]"
         for property in SYNC_PROPERTIES
     )
-    rich_click_echo(
+    echo(
         f"Processed [num]{summary['total']}[/] photos, updated: [num]{summary['updated']}[/], {property_summary}"
     )
 
@@ -596,6 +609,14 @@ def print_import_summary(results: SyncResults):
     "See also --set.",
     type=SyncImportType(),
 )
+@click.option(
+    "--unmatched",
+    "-U",
+    is_flag=True,
+    help="When used with --import, print out a list of photos in the import source that "
+    "were not matched against the local library. Also prints out a list of photos "
+    "in the local library that were not matched against the import source. ",
+)
 @click.option(
     "--report",
     "-R",
@@ -621,11 +642,9 @@ def print_import_summary(results: SyncResults):
     is_flag=True,
     help="Dry run; " "when used with --import, don't actually update metadata.",
 )
-@click.option("--verbose", "-V", "verbose_", is_flag=True, help="Print verbose output.")
-@click.option(
-    "--timestamp", "-T", is_flag=True, help="Add time stamp to verbose output."
-)
-@QUERY_OPTIONS
+@VERBOSE_OPTION
+@TIMESTAMP_OPTION
+@QUERY_OPTIONS(exclude=["--shared", "--not-shared"])
 @DB_OPTION
 @THEME_OPTION
 @click.pass_obj
@@ -643,7 +662,8 @@ def sync(
     set_,
     theme,
     timestamp,
-    verbose_,
+    unmatched,
+    verbose_flag,
     **kwargs,  # query options
 ):
     """Sync metadata and albums between Photos libraries.
@@ -697,19 +717,16 @@ def sync(
     osxphotos sync --export /path/to/export/folder/computer2.db --merge all --import /path/to/export/folder/computer1.db
 
     """
-    color_theme = get_theme(theme)
-    verbose = verbose_print(
-        verbose_, timestamp, rich=True, theme=color_theme, highlight=False
-    )
-    # set console for rich_echo to be same as for verbose_
-    set_rich_console(get_verbose_console())
-    set_rich_theme(color_theme)
-    set_rich_timestamp(timestamp)
+
+    verbose = verbose_print(verbose=verbose_flag, timestamp=timestamp, theme=theme)
 
     if (set_ or merge) and not import_path:
-        rich_echo_error("--set and --merge can only be used with --import")
+        echo_error("--set and --merge can only be used with --import")
         ctx.exit(1)
 
+    # filter out photos in shared albums as these cannot be updated
+    kwargs["not_shared"] = True
+
     set_ = parse_set_merge(set_)
     merge = parse_set_merge(merge)
 
@@ -723,17 +740,24 @@ def sync(
         set_ = set(set_)
         merge = set(merge)
         if set_ & merge:
-            rich_echo_error(
+            echo_error(
                 "--set and --merge cannot be used with the same fields: "
                 f"set: {set_}, merge: {merge}"
             )
             ctx.exit(1)
 
     if import_path:
-        query_options = query_options_from_kwargs(**kwargs)
+        try:
+            query_options = query_options_from_kwargs(**kwargs)
+        except IncompatibleQueryOptions:
+            echo_error("Incompatible query options")
+            echo_error(ctx.obj.group.commands["repl"].get_help(ctx))
+            ctx.exit(1)
         photosdb = PhotosDB(dbfile=db, verbose=verbose)
         photos = photosdb.query(query_options)
-        results = import_metadata(photos, import_path, set_, merge, dry_run, verbose)
+        results = import_metadata(
+            photos, import_path, set_, merge, dry_run, unmatched, verbose
+        )
         if report:
             report_path = render_and_validate_report(report)
             verbose(f"Writing report to {report_path}")
@@ -743,7 +767,7 @@ def sync(
         print_import_summary(results)
 
     if export_path:
-        photosdb = PhotosDB(dbfile=db, verbose=verbose)
         query_options = query_options_from_kwargs(**kwargs)
+        photosdb = PhotosDB(dbfile=db, verbose=verbose)
         photos = photosdb.query(query_options)
         export_metadata(photos, export_path, verbose)

osxphotos/cli/timewarp.py

@@ -1,43 +1,49 @@
 """ Fix time / date / timezone for photos in Apple Photos """
 
-import datetime
-import os
+from __future__ import annotations
+
 import sys
 from functools import partial
 from textwrap import dedent
-from typing import Callable, Optional
 
 import click
-from photoscript import Photo, PhotosLibrary
 from rich.console import Console
 
 from osxphotos._constants import APP_NAME
+from osxphotos._version import __version__
 from osxphotos.compare_exif import PhotoCompare
+from osxphotos.crash_reporter import crash_reporter, set_crash_data
 from osxphotos.datetime_utils import datetime_naive_to_local, datetime_to_new_tz
 from osxphotos.exif_datetime_updater import ExifDateTimeUpdater
 from osxphotos.exiftool import get_exiftool_path
-from osxphotos.photosalbum import PhotosAlbumPhotoScript
-from osxphotos.phototz import PhotoTimeZone, PhotoTimeZoneUpdater
-from osxphotos.timeutils import update_datetime
-from osxphotos.timezones import Timezone
-from osxphotos.utils import noop, pluralize
-
-from .click_rich_echo import (
-    rich_click_echo,
-    rich_echo,
-    rich_echo_error,
-    set_rich_console,
-    set_rich_theme,
-    set_rich_timestamp,
+from osxphotos.photodates import (
+    get_photo_date_added,
+    set_photo_date_added,
+    set_photo_date_from_filename,
+    update_photo_date_time,
+    update_photo_from_function,
+    update_photo_time_for_new_timezone,
 )
+from osxphotos.phototz import PhotoTimeZone, PhotoTimeZoneUpdater
+from osxphotos.utils import assert_macos, noop, pluralize
+
+assert_macos()
+
+from photoscript import PhotosLibrary
+from osxphotos.photosalbum import PhotosAlbumPhotoScript
+
+from .cli_params import THEME_OPTION, TIMESTAMP_OPTION, VERBOSE_OPTION
+from .click_rich_echo import rich_click_echo as echo
+from .click_rich_echo import rich_echo_error as echo_error
 from .color_themes import get_theme
-from .common import THEME_OPTION
+from .common import OSXPHOTOS_CRASH_LOG
 from .darkmode import is_dark_mode
 from .help import HELP_WIDTH, rich_text
 from .param_types import (
     DateOffset,
     DateTimeISO8601,
     FunctionCall,
+    StrpDateTimePattern,
     TimeOffset,
     TimeString,
     UTCOffset,
@@ -49,110 +55,6 @@ from .verbose import get_verbose_console, verbose_print
 DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S%z"
 
 
-def update_photo_date_time(
-    photo: Photo,
-    date,
-    time,
-    date_delta,
-    time_delta,
-    verbose_print: Callable,
-):
-    """Update date, time in photo"""
-    photo_date = photo.date
-    new_photo_date = update_datetime(
-        photo_date, date=date, time=time, date_delta=date_delta, time_delta=time_delta
-    )
-    filename = photo.filename
-    uuid = photo.uuid
-    if new_photo_date != photo_date:
-        photo.date = new_photo_date
-        verbose_print(
-            f"Updated date/time for photo [filename]{filename}[/filename] "
-            f"([uuid]{uuid}[/uuid]) from: [time]{photo_date}[/time] to [time]{new_photo_date}[/time]"
-        )
-    else:
-        verbose_print(
-            f"Skipped date/time update for photo [filename]{filename}[/filename] "
-            f"([uuid]{uuid}[/uuid]): nothing to do"
-        )
-
-
-def update_photo_time_for_new_timezone(
-    library_path: str,
-    photo: Photo,
-    new_timezone: Timezone,
-    verbose_print: Callable,
-):
-    """Update time in photo to keep it the same time but in a new timezone
-
-    For example, photo time is 12:00+0100 and new timezone is +0200,
-    so adjust photo time by 1 hour so it will now be 12:00+0200 instead of
-    13:00+0200 as it would be with no adjustment to the time"""
-    old_timezone = PhotoTimeZone(library_path=library_path).get_timezone(photo)[0]
-    # need to move time in opposite direction of timezone offset so that
-    # photo time is the same time but in the new timezone
-    delta = old_timezone - new_timezone.offset
-    photo_date = photo.date
-    new_photo_date = update_datetime(
-        dt=photo_date, time_delta=datetime.timedelta(seconds=delta)
-    )
-    filename = photo.filename
-    uuid = photo.uuid
-    if photo_date != new_photo_date:
-        photo.date = new_photo_date
-        verbose_print(
-            f"Adjusted date/time for photo [filename]{filename}[/filename] ([uuid]{uuid}[/uuid]) to match "
-            f"previous time [time]{photo_date}[time] but in new timezone [tz]{new_timezone}[/tz]."
-        )
-    else:
-        verbose_print(
-            f"Skipping date/time update for photo [filename]{filename}[/filename] ([uuid]{photo.uuid}[/uuid]), "
-            f"already matches new timezone [tz]{new_timezone}[/tz]"
-        )
-
-
-def update_photo_from_function(
-    library_path: str,
-    function: Callable,
-    verbose_print: Callable,
-    photo: Photo,
-    path: Optional[str],
-):
-    """Update photo from function call"""
-    photo_tz_sec, _, photo_tz_name = PhotoTimeZone(
-        library_path=library_path
-    ).get_timezone(photo)
-    dt_new, tz_new = function(
-        photo=photo,
-        path=path,
-        tz_sec=photo_tz_sec,
-        tz_name=photo_tz_name,
-        verbose=verbose_print,
-    )
-    if dt_new != photo.date:
-        old_date = photo.date
-        photo.date = dt_new
-        verbose_print(
-            f"Updated date/time for photo [filename]{photo.filename}[/filename] "
-            f"([uuid]{photo.uuid}[/uuid]) from: [time]{old_date}[/time] to [time]{dt_new}[/time]"
-        )
-    else:
-        verbose_print(
-            f"Skipped date/time update for photo [filename]{photo.filename}[/filename] "
-            f"([uuid]{photo.uuid}[/uuid]): nothing to do"
-        )
-    if tz_new != photo_tz_sec:
-        tz_updater = PhotoTimeZoneUpdater(
-            timezone=Timezone(tz_new), verbose=verbose_print, library_path=library_path
-        )
-        tz_updater.update_photo(photo)
-    else:
-        verbose_print(
-            f"Skipped timezone update for photo [filename]{photo.filename}[/filename] "
-            f"([uuid]{photo.uuid}[/uuid]): nothing to do"
-        )
-
-
 class TimeWarpCommand(click.Command):
     """Custom click.Command that overrides get_help() to show additional help info for export"""
 
@@ -214,6 +116,14 @@ For this to work, you'll need to install the third-party exiftool (https://exift
 
 *Note on timezones and times*: In Photos, when you change the timezone, Photos assumes the time itself was correct for the previous timezone and adjusts the time accordingly to the new timezone.  E.g. if the photo's time is `13:00` and the timezone is `GMT -07:00` and you adjust the timezone one hour east to `GMT -06:00`, Photos will change the time of the photo to `14:00`.  osxphotos timewarp follows this behavior.  Using `--match-time` allows you to adjust the timezone but keep the same time without adjustment. For example, if your camera clock was correct but lacked timezone information and you took photos in one timezone but imported them to photos in another, Photos will add the timezone of the computer at time of import.  You can use osxphotos timewarp to adjust the timezone but keep the time using `--match-time`.
 
+**Update the date the photos were added to Photos**
+
+`osxphotos timewarp --date-added 2021-09-10`
+
+**Update the date the photos were added to Photos to match the date of the photo**
+
+`osxphotos timewarp --date-added-from-photo`
+
 **Compare the date/time/timezone of selected photos with the date/time/timezone in the photos' original EXIF metadata**
 
 `osxphotos timewarp --compare-exif`
@@ -223,7 +133,41 @@ if the EXIF data is missing, use the file modification date/time; show verbose o
 
 `osxphotos timewarp --pull-exif --use-file-time --verbose`
 
-"""
+## Parsing Dates/Times from Filenames
+
+The --parse-date option allows you to parse dates/times from the original filename of the photo.
+This is useful if you files with dates/times embedded in the filename but not in the metadata.
+
+
+The argument to `--parse-date` is a pattern string that is used to parse the date/time
+from the filename. The pattern string is a superset of the python `strftime/strptime`
+format with the following additions:
+
+- *: Match any number of characters
+- ^: Match the beginning of the string
+- $: Match the end of the string
+- {n}: Match exactly n characters
+- {n,}: Match at least n characters
+- {n,m}: Match at least n characters and at most m characters
+- In addition to `%%` for a literal `%`, the following format codes are supported: 
+    `%^`, `%$`, `%*`, `%|`, `%{`, `%}` for `^`, `$`, `*`, `|`, `{`, `}` respectively
+- |: join multiple format codes; each code is tried in order until one matches
+- Unlike the standard library, the leading zero is not optional for 
+    %d, %m, %H, %I, %M, %S, %j, %U, %W, and %V
+- For optional leading zero, use %-d, %-m, %-H, %-I, %-M, %-S, %-j, %-U, %-W, and %-V
+
+For more information on strptime format codes, see: 
+https://docs.python.org/3/library/datetime.html?highlight=strptime#strftime-and-strptime-format-codes
+
+**Note**: The time zone of the parsed date/time is assumed to be the local time zone.
+If the parse pattern includes a time zone, the photo's time will be converted from
+the specified time zone to the local time zone. osxphotos import does not
+currently support setting the time zone of imported photos.
+See also `osxphotos help timewarp` for more information on the timewarp
+command which can be used to change the time zone of photos after import.
+
+
+"""  # noqa: E501
                 ),
                 width=formatter.width,
                 markdown=True,
@@ -279,6 +223,25 @@ if the EXIF data is missing, use the file modification date/time; show verbose o
     "This is the same behavior exhibited by Photos when manually adjusting timezone in the Get Info window. "
     "See also --match-time. ",
 )
+@click.option(
+    "--date-added",
+    metavar="DATE",
+    type=DateTimeISO8601(),
+    help="Set date/time added for selected photos. "
+    "This changes the date added or imported date in Photos but "
+    "does not change the date/time/timezone of the photo itself. "
+    "This is useful for removing photos from the Recents album, "
+    "for example if you have imported old scanned photos. "
+    "Format is 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS'. "
+    "If time is not included, midnight is assumed.",
+)
+@click.option(
+    "--date-added-from-photo",
+    is_flag=True,
+    help="Set date/time added for selected photos to the date/time the photo was taken. "
+    "This changes the date added or imported date in Photos but "
+    "does not change the date/time/timezone of the photo itself. ",
+)
 @click.option(
     "--inspect",
     "-i",
@@ -322,6 +285,19 @@ if the EXIF data is missing, use the file modification date/time; show verbose o
     "Requires the third-party exiftool utility be installed (see https://exiftool.org/). "
     "See also --push-exif.",
 )
+@click.option(
+    "--parse-date",
+    "-M",
+    metavar="DATE_PATTERN",
+    type=StrpDateTimePattern(),
+    help="Parse date from filename using DATE_PATTERN and set photo's date to match. "
+    "If file does not match DATE_PATTERN, the date will not be changed. "
+    "DATE_PATTERN is a strptime-compatible pattern with extensions as pattern described below. "
+    "If DATE_PATTERN matches time zone information, the photo's timezone will be set to match. "
+    "For example, if your photos are named 'IMG_1234_2022_11_23_12_34_56.jpg' where the date/time is "
+    "'2022-11-23 12:34:56', you could use the pattern '%Y_%m_%d_%H_%M_%S' or "
+    "'IMG_*_%Y_%m_%d_%H_%M_%S' to further narrow the pattern to only match files with 'IMG_xxxx_' in the name.",
+)
 @click.option(
     "--function",
     "-F",
@@ -363,7 +339,8 @@ if the EXIF data is missing, use the file modification date/time; show verbose o
     help="When used with --compare-exif, adds any photos with date/time/timezone differences "
     "between Photos/EXIF to album ALBUM.  If ALBUM does not exist, it will be created.",
 )
-@click.option("--verbose", "-V", "verbose", is_flag=True, help="Show verbose output.")
+@VERBOSE_OPTION
+@TIMESTAMP_OPTION
 @click.option(
     "--library",
     "-L",
@@ -379,19 +356,6 @@ if the EXIF data is missing, use the file modification date/time; show verbose o
     type=click.Path(exists=True),
     help="Optional path to exiftool executable (will look in $PATH if not specified) for those options which require exiftool.",
 )
-@click.option(
-    "--output-file",
-    "-o",
-    type=click.File(mode="w", lazy=False),
-    help="Output file. If not specified, output is written to stdout.",
-)
-@click.option(
-    "--terminal-width",
-    "-w",
-    type=int,
-    help="Terminal width in characters.",
-    hidden=True,
-)
 @click.option("--timestamp", is_flag=True, help="Add time stamp to verbose output")
 @THEME_OPTION
 @click.option(
@@ -404,12 +368,21 @@ if the EXIF data is missing, use the file modification date/time; show verbose o
     is_flag=True,
     help="Bypass confirmation prompt.  Use with caution.",
 )
+@crash_reporter(
+    OSXPHOTOS_CRASH_LOG,
+    "[red]Something went wrong and osxphotos encountered an error:[/red]",
+    "osxphotos crash log",
+    "Please file a bug report at https://github.com/RhetTbull/osxphotos/issues with the crash log attached.",
+    f"osxphotos version: {__version__}",
+)
 def timewarp(
     date,
     date_delta,
     time,
     time_delta,
     timezone,
+    date_added,
+    date_added_from_photo,
     inspect,
     compare_exif,
     push_exif,
@@ -419,12 +392,11 @@ def timewarp(
     use_file_time,
     add_to_album,
     exiftool_path,
-    verbose,
+    verbose_flag,
     library,
     theme,
+    parse_date,
     plain,
-    output_file,
-    terminal_width,
     timestamp,
     force,
 ):
@@ -436,24 +408,30 @@ def timewarp(
     See Timewarp Overview below for additional information.
     """
 
+    set_crash_data("locals", locals())
+
     # check constraints
     if not any(
         [
-            date,
-            date_delta,
-            time,
-            time_delta,
-            timezone,
-            inspect,
             compare_exif,
-            push_exif,
-            pull_exif,
+            date_added_from_photo,
+            date_added,
+            date_delta,
+            date,
             function,
+            inspect,
+            parse_date,
+            pull_exif,
+            push_exif,
+            time_delta,
+            time,
+            timezone,
         ]
     ):
         raise click.UsageError(
             "At least one of --date, --date-delta, --time, --time-delta, "
-            "--timezone, --inspect, --compare-exif, --push-exif, --pull-exif, --function "
+            "--timezone, --inspect, --compare-exif, --push-exif, --pull-exif, "
+            "--parse-date, --function, --date-added, or --date-added-from-photo "
             "must be specified."
         )
 
@@ -469,54 +447,28 @@ def timewarp(
     if add_to_album and not compare_exif:
         raise click.UsageError("--add-to-album must be used with --compare-exif.")
 
-    # configure colored rich output
-    # TODO: this is all a little hacky, find a better way to do this
-    color_theme = get_theme(theme)
-    verbose_ = verbose_print(
-        verbose,
-        timestamp,
-        rich=True,
-        theme=color_theme,
-        highlight=False,
-        file=output_file,
-    )
-    # set console for rich_echo to be same as for verbose_
-    terminal_width = terminal_width or (1000 if output_file else None)
-    if output_file:
-        set_rich_console(Console(file=output_file, width=terminal_width))
-    elif terminal_width:
-        set_rich_console(
-            Console(
-                file=sys.stdout,
-                theme=color_theme,
-                force_terminal=True,
-                width=terminal_width,
-            )
-        )
-    else:
-        set_rich_console(get_verbose_console(theme=color_theme))
-    set_rich_theme(color_theme)
+    verbose = verbose_print(verbose=verbose_flag, timestamp=timestamp, theme=theme)
 
     if any([compare_exif, push_exif, pull_exif]):
         exiftool_path = exiftool_path or get_exiftool_path()
-        verbose_(f"exiftool path: [filename]{exiftool_path}[/filename]")
+        verbose(f"exiftool path: [filename]{exiftool_path}[/filename]")
 
     try:
         photos = PhotosLibrary().selection
         if not photos:
-            rich_echo_error("[warning]No photos selected[/]")
+            echo_error("[warning]No photos selected[/]")
             sys.exit(0)
     except Exception as e:
         # AppleScript error -1728 occurs if user attempts to get selected photos in a Smart Album
         if "(-1728)" in str(e):
-            rich_echo_error(
+            echo_error(
                 "[error]Could not get selected photos. Ensure photos is open and photos are selected. "
                 "If you have selected photos and you see this message, it may be because the selected photos are in a Photos Smart Album. "
                 f"{APP_NAME} cannot access photos in a Smart Album.  Select the photos in a regular album or in 'All Photos' view. "
                 "Another option is to create a new album using 'File | New Album With Selection' then select the photos in the new album.[/]",
             )
         else:
-            rich_echo_error(
+            echo_error(
                 f"[error]Could not get selected photos. Ensure Photos is open and photos to process are selected. {e}[/]",
             )
         sys.exit(1)
@@ -525,14 +477,17 @@ def timewarp(
     if (
         any(
             [
-                date,
+                date_added_from_photo,
+                date_added,
                 date_delta,
-                time,
-                time_delta,
-                timezone,
-                push_exif,
-                pull_exif,
+                date,
                 function,
+                parse_date,
+                pull_exif,
+                push_exif,
+                time_delta,
+                time,
+                timezone,
             ]
         )
         and not force
@@ -556,13 +511,37 @@ def timewarp(
         time=time,
         date_delta=date_delta,
         time_delta=time_delta,
-        verbose_print=verbose_,
+        verbose=verbose,
     )
 
     update_photo_time_for_new_timezone_ = partial(
         update_photo_time_for_new_timezone,
         library_path=library,
-        verbose_print=verbose_,
+        verbose=verbose,
+    )
+
+    set_photo_date_from_filename_ = partial(
+        set_photo_date_from_filename,
+        library_path=library,
+        verbose=verbose,
+    )
+
+    set_photo_date_added_ = partial(
+        set_photo_date_added,
+        library_path=library,
+        verbose=verbose,
+        date_added=date_added,
+    )
+
+    set_photo_date_added_from_photo_ = partial(
+        set_photo_date_added,
+        library_path=library,
+        verbose=verbose,
+    )
+
+    get_photo_date_added_ = partial(
+        get_photo_date_added,
+        library_path=library,
     )
 
     if function:
@@ -570,7 +549,7 @@ def timewarp(
             update_photo_from_function,
             library_path=library,
             function=function[0],
-            verbose_print=verbose_,
+            verbose=verbose,
         )
     else:
         update_photo_from_function_ = noop
@@ -578,15 +557,25 @@ def timewarp(
     if inspect:
         tzinfo = PhotoTimeZone(library_path=library)
         if photos:
-            rich_echo(
-                "[filename]filename[/filename], [uuid]uuid[/uuid], [time]photo time (local)[/time], [time]photo time[/time], [tz]timezone offset[/tz], [tz]timezone name[/tz]"
+            echo(
+                "[filename]filename[/filename], [uuid]uuid[/uuid], "
+                "[time]photo time (local)[/time], "
+                "[time]photo time[/time], "
+                "[tz]timezone offset[/tz], [tz]timezone name[/tz], "
+                "[time]date added (local)[/time]"
             )
         for photo in photos:
+            set_crash_data("photo", f"{photo.uuid} {photo.filename}")
             tz_seconds, tz_str, tz_name = tzinfo.get_timezone(photo)
             photo_date_local = datetime_naive_to_local(photo.date)
             photo_date_tz = datetime_to_new_tz(photo_date_local, tz_seconds)
-            rich_echo(
-                f"[filename]{photo.filename}[/filename], [uuid]{photo.uuid}[/uuid], [time]{photo_date_local.strftime(DATETIME_FORMAT)}[/time], [time]{photo_date_tz.strftime(DATETIME_FORMAT)}[/time], [tz]{tz_str}[/tz], [tz]{tz_name}[/tz]"
+            date_added = datetime_naive_to_local(get_photo_date_added_(photo))
+            echo(
+                f"[filename]{photo.filename}[/filename], [uuid]{photo.uuid}[/uuid], "
+                f"[time]{photo_date_local.strftime(DATETIME_FORMAT)}[/time], "
+                f"[time]{photo_date_tz.strftime(DATETIME_FORMAT)}[/time], "
+                f"[tz]{tz_str}[/tz], [tz]{tz_name}[/tz], "
+                f"[time]{date_added.strftime(DATETIME_FORMAT)}[/time]"
             )
         sys.exit(0)
 
@@ -596,14 +585,15 @@ def timewarp(
         if photos:
             photocomp = PhotoCompare(
                 library_path=library,
-                verbose=verbose_,
+                verbose=verbose,
                 exiftool_path=exiftool_path,
             )
             if not album:
-                rich_echo(
+                echo(
                     "filename, uuid, photo time (Photos), photo time (EXIF), timezone offset (Photos), timezone offset (EXIF)"
                 )
         for photo in photos:
+            set_crash_data("photo", f"{photo.uuid} {photo.filename}")
             diff_results = (
                 photocomp.compare_exif_no_markup(photo)
                 if plain
@@ -622,20 +612,20 @@ def timewarp(
             if album:
                 if diff_results.diff:
                     different_photos += 1
-                    verbose_(
+                    verbose(
                         f"Photo {filename} ({uuid}) has different date/time/timezone, adding to album '{album.name}'"
                     )
                     album.add(photo)
                 else:
-                    verbose_(f"Photo {filename} ({uuid}) has same date/time/timezone")
+                    verbose(f"Photo {filename} ({uuid}) has same date/time/timezone")
             else:
-                rich_echo(
+                echo(
                     f"{filename}, {uuid}, "
                     f"{diff_results.photos_date} {diff_results.photos_time}, {diff_results.exif_date} {diff_results.exif_time}, "
                     f"{diff_results.photos_tz}, {diff_results.exif_tz}"
                 )
         if album:
-            rich_echo(
+            echo(
                 f"Compared {len(photos)} photos, found {different_photos} "
                 f"that {pluralize(different_photos, 'is', 'are')} different and "
                 f"added {pluralize(different_photos, 'it', 'them')} to album '{album.name}'."
@@ -644,14 +634,14 @@ def timewarp(
 
     if timezone:
         tz_updater = PhotoTimeZoneUpdater(
-            timezone, verbose=verbose_, library_path=library
+            timezone, verbose=verbose, library_path=library
         )
 
     if any([push_exif, pull_exif, function]):
         # ExifDateTimeUpdater used to get photo path for --function
         exif_updater = ExifDateTimeUpdater(
             library_path=library,
-            verbose=verbose_,
+            verbose=verbose,
             exiftool_path=exiftool_path,
             plain=plain,
         )
@@ -662,34 +652,39 @@ def timewarp(
             f"Processing [num]{num_photos}[/] {pluralize(len(photos), 'photo', 'photos')}",
             total=num_photos,
         )
-        for p in photos:
+        for photo in photos:
+            set_crash_data("photo", f"{photo.uuid} {photo.filename}")
+            if parse_date:
+                set_photo_date_from_filename_(photo, photo.filename, parse_date)
             if pull_exif:
                 exif_updater.update_photos_from_exif(
-                    p, use_file_modify_date=use_file_time
+                    photo, use_file_modify_date=use_file_time
                 )
             if any([date, time, date_delta, time_delta]):
-                update_photo_date_time_(p)
+                update_photo_date_time_(photo)
             if match_time:
                 # need to adjust time before the timezone is updated
                 # or the old timezone will be overwritten in the database
-                update_photo_time_for_new_timezone_(photo=p, new_timezone=timezone)
+                update_photo_time_for_new_timezone_(photo=photo, new_timezone=timezone)
             if timezone:
-                tz_updater.update_photo(p)
+                tz_updater.update_photo(photo)
+            if date_added:
+                set_photo_date_added_(photo)
+            if date_added_from_photo:
+                set_photo_date_added_from_photo_(photo, date_added=photo.date)
             if function:
-                verbose_(f"Calling function [bold]{function[1]}")
-                photo_path = exif_updater.get_photo_path(p)
-                update_photo_from_function_(photo=p, path=photo_path)
+                verbose(f"Calling function [bold]{function[1]}")
+                photo_path = exif_updater.get_photo_path(photo)
+                update_photo_from_function_(photo=photo, path=photo_path)
             if push_exif:
                 # this should be the last step in the if chain to ensure all Photos data is updated
                 # before exiftool is run
-                exif_warn, exif_error = exif_updater.update_exif_from_photos(p)
+                exif_warn, exif_error = exif_updater.update_exif_from_photos(photo)
                 if exif_warn:
-                    rich_echo_error(
-                        f"[warning]Warning running exiftool: {exif_warn}[/]"
-                    )
+                    echo_error(f"[warning]Warning running exiftool: {exif_warn}[/]")
                 if exif_error:
-                    rich_echo_error(f"[error]Error running exiftool: {exif_error}[/]")
+                    echo_error(f"[error]Error running exiftool: {exif_error}[/]")
 
             progress.advance(task)
 
-    rich_echo("Done.")
+    echo("Done.")

osxphotos/cli/uuid.py

@@ -1,6 +1,11 @@
 """uuid command for osxphotos CLI"""
 
 import click
+
+from osxphotos.utils import assert_macos
+
+assert_macos()
+
 import photoscript
 
 

osxphotos/cli/verbose.py

@@ -1,14 +1,22 @@
 """helper functions for printing verbose output"""
 
+from __future__ import annotations
+
 import os
-import typing as t
 from datetime import datetime
+from typing import IO, Any, Callable, Optional
 
 import click
 from rich.console import Console
 from rich.theme import Theme
 
-from .click_rich_echo import rich_click_echo
+from .click_rich_echo import (
+    rich_click_echo,
+    set_rich_console,
+    set_rich_theme,
+    set_rich_timestamp,
+)
+from .color_themes import get_theme
 from .common import CLI_COLOR_ERROR, CLI_COLOR_WARNING, time_stamp
 
 # set to 1 if running tests
@@ -17,14 +25,80 @@ OSXPHOTOS_IS_TESTING = bool(os.getenv("OSXPHOTOS_IS_TESTING", default=False))
 # include error/warning emoji's in verbose output
 ERROR_EMOJI = True
 
-__all__ = ["get_verbose_console", "verbose_print"]
+# global to store verbose level
+__verbose_level = 1
+
+# global verbose function
+__verbose_function: Callable[..., None] | None = None
+
+
+__all__ = [
+    "get_verbose_console",
+    "get_verbose_level",
+    "set_verbose_level",
+    "verbose_print",
+    "verbose",
+]
+
+
+def _reset_verbose_globals():
+    """Reset globals for testing"""
+    global __verbose_level
+    global __verbose_function
+    global _console
+    __verbose_level = 1
+    __verbose_function = None
+    _console = _Console()
+
+
+def noop(*args, **kwargs):
+    """no-op function"""
+    pass
+
+
+def verbose(*args, level: int = 1):
+    """Print verbose output
+
+    Args:
+        *args: arguments to pass to verbose function for printing
+        level: verbose level; if level > get_verbose_level(), output is suppressed
+    """
+
+    # Notes:
+    #     Normally you should use verbose_print() to get the verbose function instead of calling this directly
+    #     This is here so that verbose can be directly imported and used in other modules without calling verbose_print()
+    #     Use of verbose_print() will set the verbose function so that calling verbose() will work as expected
+    global __verbose_function
+    if __verbose_function is None:
+        return
+    __verbose_function(*args, level=level)
+
+
+def set_verbose_level(level: int):
+    """Set verbose level"""
+    global __verbose_level
+    global __verbose_function
+    __verbose_level = level
+    if level > 0 and __verbose_function is None:
+        # if verbose level set but verbose function not set, set it to default
+        # verbose_print sets the global __verbose_function
+        __verbose_function = _verbose_print_function(level)
+    elif level == 0 and __verbose_function is not None:
+        # if verbose level set to 0 but verbose function is set, set it to no-op
+        __verbose_function = noop
+
+
+def get_verbose_level() -> int:
+    """Get verbose level"""
+    global __verbose_level
+    return __verbose_level
 
 
 class _Console:
     """Store console object for verbose output"""
 
     def __init__(self):
-        self._console: t.Optional[Console] = None
+        self._console: Optional[Console] = None
 
     @property
     def console(self):
@@ -38,12 +112,7 @@ class _Console:
 _console = _Console()
 
 
-def noop(*args, **kwargs):
-    """no-op function"""
-    pass
-
-
-def get_verbose_console(theme: t.Optional[Theme] = None) -> Console:
+def get_verbose_console(theme: Optional[Theme] = None) -> Console:
     """Get console object or create one if not already created
 
     Args:
@@ -59,18 +128,68 @@ def get_verbose_console(theme: t.Optional[Theme] = None) -> Console:
 
 
 def verbose_print(
+    verbose: int = 1,
+    timestamp: bool = False,
+    rich: bool = True,
+    theme: str | None = None,
+    highlight: bool = False,
+    file: Optional[IO] = None,
+    **kwargs: Any,
+) -> Callable[..., None]:
+    """Configure verbose printing and create verbose function to print output
+
+    Args:
+        verbose: if > 0, returns verbose print function otherwise returns no-op function; the value of verbose is the verbose level
+        timestamp: if True, includes timestamp in verbose output
+        rich: use rich.print instead of click.echo
+        highlight: if True, use automatic rich.print highlighting
+        theme: optional name of theme to use for formatting (will be loaded by get_theme())
+        file: optional file handle to write to instead of stdout
+        kwargs: any extra arguments to pass to click.echo or rich.print depending on whether rich==True
+
+    Returns:
+        function to print output
+
+    Note: sets the console for rich_echo to be the same as the console used for verbose output
+    """
+
+    set_verbose_level(verbose)
+    color_theme = get_theme(theme)
+    verbose_function = _verbose_print_function(
+        verbose=verbose,
+        timestamp=timestamp,
+        rich=rich,
+        theme=color_theme,
+        highlight=highlight,
+        file=file,
+        **kwargs,
+    )
+
+    # set console for rich_echo to be same as for verbose
+    set_rich_console(get_verbose_console())
+    set_rich_theme(color_theme)
+    set_rich_timestamp(timestamp)
+
+    # set global verbose function to match
+    global __verbose_function
+    __verbose_function = verbose_function
+
+    return verbose_function
+
+
+def _verbose_print_function(
     verbose: bool = True,
     timestamp: bool = False,
     rich: bool = False,
     highlight: bool = False,
-    theme: t.Optional[Theme] = None,
-    file: t.Optional[t.IO] = None,
-    **kwargs: t.Any,
-) -> t.Callable:
+    theme: Optional[Theme] = None,
+    file: Optional[IO] = None,
+    **kwargs: Any,
+) -> Callable[..., None]:
     """Create verbose function to print output
 
     Args:
-        verbose: if True, returns verbose print function otherwise returns no-op function
+        verbose: if > 0, returns verbose print function otherwise returns no-op function; the value of verbose is the verbose level
         timestamp: if True, includes timestamp in verbose output
         rich: use rich.print instead of click.echo
         highlight: if True, use automatic rich.print highlighting
@@ -81,18 +200,22 @@ def verbose_print(
     Returns:
         function to print output
     """
-    if not verbose:
-        return noop
 
+    # configure console even if verbose is False so that rich_echo will work correctly
     global _console
     if file:
         _console.console = Console(theme=theme, file=file)
     else:
         _console.console = Console(theme=theme, width=10_000)
 
+    if not verbose:
+        return noop
+
     # closure to capture timestamp
-    def verbose_(*args):
+    def verbose_(*args, level: int = 1):
         """print output if verbose flag set"""
+        if get_verbose_level() < level:
+            return
         styled_args = []
         timestamp_str = f"{str(datetime.now())} -- " if timestamp else ""
         for arg in args:
@@ -103,10 +226,12 @@ def verbose_print(
                 elif "warning" in arg.lower():
                     arg = click.style(arg, fg=CLI_COLOR_WARNING)
             styled_args.append(arg)
-        click.echo(*styled_args, **kwargs)
+        click.echo(*styled_args, **kwargs, file=file or None)
 
-    def rich_verbose_(*args):
+    def rich_verbose_(*args, level: int = 1):
         """rich.print output if verbose flag set"""
+        if get_verbose_level() < level:
+            return
         global ERROR_EMOJI
         timestamp_str = time_stamp() if timestamp else ""
         new_args = []
@@ -124,8 +249,10 @@ def verbose_print(
             new_args.append(arg)
         _console.console.print(*new_args, highlight=highlight, **kwargs)
 
-    def rich_verbose_testing_(*args):
+    def rich_verbose_testing_(*args, level: int = 1):
         """print output if verbose flag set using rich.print"""
+        if get_verbose_level() < level:
+            return
         global ERROR_EMOJI
         timestamp_str = time_stamp() if timestamp else ""
         new_args = []