Updated docs [skip ci]

Added get_photos_library_version
Added export test for --exif
2021-12-26 20:09:10 -08:00 · 2021-12-26 19:57:33 -08:00 · 2021-12-25 05:53:26 -08:00 · 2021-12-25 05:41:37 -08:00 · 2021-12-24 18:12:02 -08:00 · 2021-12-24 18:08:18 -08:00
629 changed files with 16779 additions and 10585 deletions
--- a/.all-contributorsrc
+++ b/.all-contributorsrc
@@ -222,6 +222,88 @@
      "contributions": [
        "bug"
      ]
+    },
+    {
+      "login": "mkirkland4874",
+      "name": "mkirkland4874",
+      "avatar_url": "https://avatars.githubusercontent.com/u/36466711?v=4",
+      "profile": "https://github.com/mkirkland4874",
+      "contributions": [
+        "bug",
+        "example"
+      ]
+    },
+    {
+      "login": "jcommisso07",
+      "name": "Joseph Commisso",
+      "avatar_url": "https://avatars.githubusercontent.com/u/3111054?v=4",
+      "profile": "https://github.com/jcommisso07",
+      "contributions": [
+        "data"
+      ]
+    },
+    {
+      "login": "dssinger",
+      "name": "David Singer",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1817903?v=4",
+      "profile": "https://github.com/dssinger",
+      "contributions": [
+        "bug"
+      ]
+    },
+    {
+      "login": "oPromessa",
+      "name": "oPromessa",
+      "avatar_url": "https://avatars.githubusercontent.com/u/21261491?v=4",
+      "profile": "https://github.com/oPromessa",
+      "contributions": [
+        "bug"
+      ]
+    },
+    {
+      "login": "spencerc99",
+      "name": "Spencer Chang",
+      "avatar_url": "https://avatars.githubusercontent.com/u/14796580?v=4",
+      "profile": "http://spencerchang.me",
+      "contributions": [
+        "bug"
+      ]
+    },
+    {
+      "login": "dgleich",
+      "name": "David Gleich",
+      "avatar_url": "https://avatars.githubusercontent.com/u/33995?v=4",
+      "profile": "https://www.cs.purdue.edu/homes/dgleich",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "alandefreitas",
+      "name": "Alan de Freitas",
+      "avatar_url": "https://avatars.githubusercontent.com/u/5369819?v=4",
+      "profile": "https://alandefreitas.github.io/alandefreitas/",
+      "contributions": [
+        "bug"
+      ]
+    },
+    {
+      "login": "hyfen",
+      "name": "Andrew Louis",
+      "avatar_url": "https://avatars.githubusercontent.com/u/6291?v=4",
+      "profile": "https://hyfen.net",
+      "contributions": [
+        "doc", "code"
+      ]
+    },
+    {
+      "login": "neebah",
+      "name": "neebah",
+      "avatar_url": "https://avatars.githubusercontent.com/u/71442026?v=4",
+      "profile": "https://github.com/neebah",
+      "contributions": [
+        "bug"
+      ]
    }
  ],
  "contributorsPerLine": 7,
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+** Before submitting a bug report, please ensure you are running the most recent version of osxphotos and that the bug is reproducible on the latest version **
+
+- If you installed with pipx: `pipx upgrade osxphotos`
+- If you installed with pip: `pip install --upgrade osxphotos`
+- If you installed the pre-built binary, download and install the latest [release](https://github.com/RhetTbull/osxphotos/releases)
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. What' the full command line you used with osxphotos?
+2. What was the error output?
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. which version of macOS]
+ - osxphotos version (`osxphotos --version`)
+
+**Additional context**
+Add any other context about the problem here.
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: feature request
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -4,13 +4,13 @@ on: [push, pull_request]

 jobs:
  build:
-
-    runs-on: macOS-latest
+    runs-on: ${{ matrix.os }}
    if: "!contains(github.event.head_commit.message, '[skip ci]')"
    strategy:
      max-parallel: 4
      matrix:
-        python-version: [3.7, 3.8]
+        os: [macos-10.15]
+        python-version: [3.7, 3.8, 3.9]

    steps:
    - uses: actions/checkout@v1
@@ -21,6 +21,7 @@ jobs:
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
+        pip install -r dev_requirements.txt
        pip install -r requirements.txt
   # - name: Lint with flake8
   #   run: |
@@ -31,6 +32,4 @@ jobs:
       # flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
    - name: Test with pytest
      run: |
-        pip install pytest
-        pip install pytest-mock
        python -m pytest tests/
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,5 @@ osxphotos.egg-info/
 cli.spec
 *.pyc
 docsrc/_build/
+venv/
+.python-version
--- a/.isort.cfg
+++ b/.isort.cfg
@@ -0,0 +1,3 @@
+[settings]
+profile=black
+multi_line_output=3
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,464 @@ All notable changes to this project will be documented in this file. Dates are d

 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).

+#### [v0.43.6](https://github.com/RhetTbull/osxphotos/compare/v0.43.5...v0.43.6)
+
+> 10 December 2021
+
+- Fixes typo in README [`#548`](https://github.com/RhetTbull/osxphotos/pull/548)
+- docs: add alandefreitas as a contributor for bug [`#551`](https://github.com/RhetTbull/osxphotos/pull/551)
+- docs: add dgleich as a contributor for code [`#541`](https://github.com/RhetTbull/osxphotos/pull/541)
+- Updated docs [`197e566`](https://github.com/RhetTbull/osxphotos/commit/197e5663df058a013ce2d6f8c5fd7ff71a5cc46e)
+- Added test library for Monterey on M1 [`3e038bf`](https://github.com/RhetTbull/osxphotos/commit/3e038bf124b98d6b74f19dd4db0f8f1e3c48e787)
+- Updated docs [skip ci] [`f6dedaa`](https://github.com/RhetTbull/osxphotos/commit/f6dedaa6197dc244616c5b4e9e8ce42ce6b7a252)
+- Added MomentInfo for Photos 5+, #71 [`a52b4d2`](https://github.com/RhetTbull/osxphotos/commit/a52b4d2f43970086bf25659bd58dc8479b841704)
+- Fixed error for missing photo path, #547 [`0906dbe`](https://github.com/RhetTbull/osxphotos/commit/0906dbe6370922b4c9649350014ed8a21d29c4fd)
+
+#### [v0.43.5](https://github.com/RhetTbull/osxphotos/compare/v0.43.4...v0.43.5)
+
+> 25 November 2021
+
+- Updated dependencies for pyobjc 8.0 [`7d92359`](https://github.com/RhetTbull/osxphotos/commit/7d923590ae4df941b1b9d35c21937c03eb7b4284)
+
+#### [v0.43.4](https://github.com/RhetTbull/osxphotos/compare/v0.43.3...v0.43.4)
+
+> 11 November 2021
+
+- Fix for --use-photokit with --skip-live, #537 [`0e6c92d`](https://github.com/RhetTbull/osxphotos/commit/0e6c92dbd951dd0e63cfb8b6d64e6ab96ece5955)
+
+#### [v0.43.3](https://github.com/RhetTbull/osxphotos/compare/v0.43.1...v0.43.3)
+
+> 7 November 2021
+
+- Updated docs [skip ci] [`fb583e2`](https://github.com/RhetTbull/osxphotos/commit/fb583e28e0fc2c23bf24052db8a5ee669d8c92f5)
+- Updated OTL to MTL [`2ffcf1e`](https://github.com/RhetTbull/osxphotos/commit/2ffcf1e82bfc013a4a9e0e7a709a7c1395c074ce)
+- Test fixes for Monterey/M1 [`51ba549`](https://github.com/RhetTbull/osxphotos/commit/51ba54971a874cfce00368aa5be5380b3439c254)
+
+#### [v0.43.1](https://github.com/RhetTbull/osxphotos/compare/v0.43.0...v0.43.1)
+
+> 30 October 2021
+
+- Dependency update for Monterey [`818f4f4`](https://github.com/RhetTbull/osxphotos/commit/818f4f45a4ce520b0ba1c688eabd2f4311be9540)
+- Updated docs [skip ci] [`2cf19f6`](https://github.com/RhetTbull/osxphotos/commit/2cf19f6af1a03767e4d53eee556c4d3ed9af1776)
+
+#### [v0.43.0](https://github.com/RhetTbull/osxphotos/compare/v0.42.94...v0.43.0)
+
+> 28 October 2021
+
+- Updated for Monterey 12.0.1 release [`ef82c6e`](https://github.com/RhetTbull/osxphotos/commit/ef82c6e32b536b0677530133892f95b852c6dce0)
+
+#### [v0.42.94](https://github.com/RhetTbull/osxphotos/compare/v0.42.93...v0.42.94)
+
+> 15 October 2021
+
+- docs: add spencerc99 as a contributor for bug [`#527`](https://github.com/RhetTbull/osxphotos/pull/527)
+- Fix for #526 with --update [`419b34e`](https://github.com/RhetTbull/osxphotos/commit/419b34ea73f15ccbe29f51896e11e9735ea5786b)
+- Updated docs [skip ci] [`0e9b9d6`](https://github.com/RhetTbull/osxphotos/commit/0e9b9d625190b94c1dd68276e3b0e5367002d87c)
+- Fixed FileUtil to use correct import [`f64c4ed`](https://github.com/RhetTbull/osxphotos/commit/f64c4ed374c120a95fe8adea26bd44852ca67e31)
+
+#### [v0.42.93](https://github.com/RhetTbull/osxphotos/compare/v0.42.92...v0.42.93)
+
+> 11 October 2021
+
+- Fix for #526 [`202bc11`](https://github.com/RhetTbull/osxphotos/commit/202bc1144bc842ddec825eef0745830d56170aba)
+- Updated README.md [skip ci] [`a0c654e`](https://github.com/RhetTbull/osxphotos/commit/a0c654e43f4aa5389a96c3c84fd7037c33d23404)
+
+#### [v0.42.92](https://github.com/RhetTbull/osxphotos/compare/v0.42.91...v0.42.92)
+
+> 11 October 2021
+
+- docs: add oPromessa as a contributor for bug [`#525`](https://github.com/RhetTbull/osxphotos/pull/525)
+- Fix for #524 [`04ac0a1`](https://github.com/RhetTbull/osxphotos/commit/04ac0a11215b275178013e60c6a61b9f1b3603c9)
+- Fix for #525 [`d2b0bd4`](https://github.com/RhetTbull/osxphotos/commit/d2b0bd4e28cfdf3c930aa6ae3317549327b0e29c)
+- Updated docs [skip ci] [`2bb677d`](https://github.com/RhetTbull/osxphotos/commit/2bb677dc19abaf254bc66e2cd788676e0613e548)
+
+#### [v0.42.91](https://github.com/RhetTbull/osxphotos/compare/v0.42.90...v0.42.91)
+
+> 11 October 2021
+
+- Updated docs [skip ci] [`b23e74f`](https://github.com/RhetTbull/osxphotos/commit/b23e74f8f5a8387564108c330c3f8ac11189860d)
+- Added python 3.10 to supported versions [`3f81a3c`](https://github.com/RhetTbull/osxphotos/commit/3f81a3c179dde37e9811ef19c847920bb3bd514c)
+- Updated dependencies [`a895833`](https://github.com/RhetTbull/osxphotos/commit/a895833c7f0a264488e671f1735f9e10d2618e2d)
+
+#### [v0.42.90](https://github.com/RhetTbull/osxphotos/compare/v0.42.89...v0.42.90)
+
+> 30 September 2021
+
+- Updated REPL, now with more cowbell [`c472698`](https://github.com/RhetTbull/osxphotos/commit/c472698b1d0d8ff9f4d1bde715859bf766f99290)
+- Updated docs [skip ci] [`1ddb1de`](https://github.com/RhetTbull/osxphotos/commit/1ddb1de99841e65b690ffc1cbcc5e42e6e25f727)
+
+#### [v0.42.89](https://github.com/RhetTbull/osxphotos/compare/v0.42.88...v0.42.89)
+
+> 26 September 2021
+
+- Updated docs [skip ci] [`bfbc156`](https://github.com/RhetTbull/osxphotos/commit/bfbc156821d2d262b7bd9c4437e23e310da10769)
+- Updated docs [skip ci] [`3abaa5a`](https://github.com/RhetTbull/osxphotos/commit/3abaa5ae84ca44cd900f1e3af4532ab405d41a09)
+- Fixed AlbumInfo.owner, #239 [`bfd6274`](https://github.com/RhetTbull/osxphotos/commit/bfd627460255c65f870bca6d036401e8792d29d5)
+
+#### [v0.42.88](https://github.com/RhetTbull/osxphotos/compare/v0.42.87...v0.42.88)
+
+> 26 September 2021
+
+- Performance fix for #239, owner [`14710e3`](https://github.com/RhetTbull/osxphotos/commit/14710e31789d71b2c948a37722fb6054aca4d85e)
+- version bump [`06138e1`](https://github.com/RhetTbull/osxphotos/commit/06138e15d0b87e4865a9ef0cc542303edb44c861)
+
+#### [v0.42.87](https://github.com/RhetTbull/osxphotos/compare/v0.42.86...v0.42.87)
+
+> 26 September 2021
+
+#### [v0.42.86](https://github.com/RhetTbull/osxphotos/compare/v0.42.85...v0.42.86)
+
+> 26 September 2021
+
+- Fix for #517, #239 [`ac47df8`](https://github.com/RhetTbull/osxphotos/commit/ac47df8475762fe8c8f63ad5ffa83b1e20d116b8)
+- Fixed formatting [`6adafb8`](https://github.com/RhetTbull/osxphotos/commit/6adafb8ce70e95a9f0bec1a3db6362742fcd1b0d)
+- Updated docs [skip ci] [`725f7c8`](https://github.com/RhetTbull/osxphotos/commit/725f7c87351353efeee8c43c3c7f8a95acb14490)
+
+#### [v0.42.85](https://github.com/RhetTbull/osxphotos/compare/v0.42.84...v0.42.85)
+
+> 25 September 2021
+
+- Implemented PhotoInfo.owner, AlbumInfo.owner, #216, #239 [`c4b7c26`](https://github.com/RhetTbull/osxphotos/commit/c4b7c2623f077d9964d5d578ce6c01bb83fab088)
+- Updated docs [skip ci] [`59ba325`](https://github.com/RhetTbull/osxphotos/commit/59ba325273b2f16935be944fd46c1237ce637bb8)
+
+#### [v0.42.84](https://github.com/RhetTbull/osxphotos/compare/v0.42.83...v0.42.84)
+
+> 25 September 2021
+
+- Fix for #516 [`e3e1da2`](https://github.com/RhetTbull/osxphotos/commit/e3e1da2fd898896595fc851288f905bd4e2150f8)
+- Updated docs [skip ci] [`64c226b`](https://github.com/RhetTbull/osxphotos/commit/64c226b85529581e393a2d0604b41c37a8dc2eaf)
+- Update docs [`c429a86`](https://github.com/RhetTbull/osxphotos/commit/c429a860b1ebeb77f3c3e36e9660fc9153d85d11)
+
+#### [v0.42.83](https://github.com/RhetTbull/osxphotos/compare/v0.42.82...v0.42.83)
+
+> 15 September 2021
+
+- Fixed detected_text to use image orientation if available [`dd08c7f`](https://github.com/RhetTbull/osxphotos/commit/dd08c7f701335a7e1e30fda251e6ad20ff781652)
+- Added twine [`16335a6`](https://github.com/RhetTbull/osxphotos/commit/16335a6bd66eaa53fd1c390901e2fb028059d8e1)
+- Added wheel [`e0f6d8e`](https://github.com/RhetTbull/osxphotos/commit/e0f6d8ecf27fe772b748c7b2f3108558fbc23e8a)
+
+#### [v0.42.82](https://github.com/RhetTbull/osxphotos/compare/v0.42.80...v0.42.82)
+
+> 14 September 2021
+
+- Fix for #515 [`93bf0c2`](https://github.com/RhetTbull/osxphotos/commit/93bf0c210cf01f351611427662025c86955ac373)
+- Fix for #515, updated tests [`59c31ff`](https://github.com/RhetTbull/osxphotos/commit/59c31ff88d099b251cf1b571279d7a28a0aac138)
+- Updated docs [`773dca8`](https://github.com/RhetTbull/osxphotos/commit/773dca849424c61a7447cb1bb87140708ab0a07c)
+
+#### [v0.42.80](https://github.com/RhetTbull/osxphotos/compare/v0.42.79...v0.42.80)
+
+> 29 August 2021
+
+- Bug fix for null title, #512 [`6bcc676`](https://github.com/RhetTbull/osxphotos/commit/6bcc67634ca50e84494539b8a25eb7925dcede62)
+- Updated dependencies [`2eb6e70`](https://github.com/RhetTbull/osxphotos/commit/2eb6e70e57ff1dc79907a29618757953f5871145)
+- Updated README [skip ci] [`81dd1a7`](https://github.com/RhetTbull/osxphotos/commit/81dd1a753062dacc83aaf4ce8a7667de2cda599b)
+
+#### [v0.42.79](https://github.com/RhetTbull/osxphotos/compare/v0.42.78...v0.42.79)
+
+> 29 August 2021
+
+#### [v0.42.78](https://github.com/RhetTbull/osxphotos/compare/v0.42.77...v0.42.78)
+
+> 29 August 2021
+
+- docs: add dssinger as a contributor for bug [`#514`](https://github.com/RhetTbull/osxphotos/pull/514)
+- Fix for newlines in exif tags, #513 [`f0d7496`](https://github.com/RhetTbull/osxphotos/commit/f0d7496bc66aae291337efc570a2e2c4b9b5529c)
+
+#### [v0.42.77](https://github.com/RhetTbull/osxphotos/compare/v0.42.74...v0.42.77)
+
+> 28 August 2021
+
+- Fixed --strip behavior, #511 [`dbb4dbc`](https://github.com/RhetTbull/osxphotos/commit/dbb4dbc0a7f7cb590ab3b2ce532c5c618c7fc249)
+- Update test for #506 [`f1cea14`](https://github.com/RhetTbull/osxphotos/commit/f1cea1498b3b973aa500d874126b9668a8743f1f)
+- Added {strip} template [`159d110`](https://github.com/RhetTbull/osxphotos/commit/159d1102aabd56def2caf6754747f7a4caa7d374)
+
+#### [v0.42.74](https://github.com/RhetTbull/osxphotos/compare/v0.42.73...v0.42.74)
+
+> 23 August 2021
+
+- Fix for #506 [`db5b34d`](https://github.com/RhetTbull/osxphotos/commit/db5b34d58950c65f95d22a0e81390b9d4fb7ccd7)
+- Updated README [skip ci] [`fb4138c`](https://github.com/RhetTbull/osxphotos/commit/fb4138cfe6cfad02fead821b70b4b84d11b027e9)
+
+#### [v0.42.73](https://github.com/RhetTbull/osxphotos/compare/v0.42.72...v0.42.73)
+
+> 15 August 2021
+
+- Added inspect() to repl, closes #501 [`#501`](https://github.com/RhetTbull/osxphotos/issues/501)
+- Updated docs for Text Detection [skip ci] [`c2b2476`](https://github.com/RhetTbull/osxphotos/commit/c2b2476e385fcd3773bd8abb942e788be2af8169)
+- Updated README.md [skip ci] [`2041789`](https://github.com/RhetTbull/osxphotos/commit/2041789ff4a3979a73712b27a51a77e8a880efb8)
+
+#### [v0.42.72](https://github.com/RhetTbull/osxphotos/compare/v0.42.71...v0.42.72)
+
+> 2 August 2021
+
+- Improved caching of detected_text results [`fa2027d`](https://github.com/RhetTbull/osxphotos/commit/fa2027d45308738d2335d4b5a72c3ef5c478491a)
+
+#### [v0.42.71](https://github.com/RhetTbull/osxphotos/compare/v0.42.70...v0.42.71)
+
+> 29 July 2021
+
+- Updated text_detection to detect macOS version [`7376223`](https://github.com/RhetTbull/osxphotos/commit/7376223eb87a4919fd54cc685a3f263e83626879)
+- Updated detected_text docs to make it clear this only works on Catalina+ [`ecd0b8e`](https://github.com/RhetTbull/osxphotos/commit/ecd0b8e22f8bf1f8d1e98d64834bebf0394dd903)
+- Fix for #500, check for macOS version before loading Vision [`673243c`](https://github.com/RhetTbull/osxphotos/commit/673243c6cd1c267b6b741b5429cdb63c062648d1)
+
+#### [v0.42.70](https://github.com/RhetTbull/osxphotos/compare/v0.42.69...v0.42.70)
+
+> 29 July 2021
+
+- Added error logging to {detected_text} processing, #499 [`b1c0fb3`](https://github.com/RhetTbull/osxphotos/commit/b1c0fb3e8284600394ddbfdd7dfa94916a843c81)
+- Updated README.md [skip ci] [`1ee3e03`](https://github.com/RhetTbull/osxphotos/commit/1ee3e035c42d687158f7cf73382f0f263516dc37)
+- Removed unneeded test file [skip ci] [`607cf80`](https://github.com/RhetTbull/osxphotos/commit/607cf80dda37ad529edd91fe92af3885b04b9a37)
+
+#### [v0.42.69](https://github.com/RhetTbull/osxphotos/compare/v0.42.67...v0.42.69)
+
+> 28 July 2021
+
+- Added {detected_text} template [`c233523`](https://github.com/RhetTbull/osxphotos/commit/c2335236be7a1eecf4f25a9dcb844df4d6372b5c)
+- Added PhotoInfo.detected_text() [`123340e`](https://github.com/RhetTbull/osxphotos/commit/123340eadabb0fb07209c4207ccad13a53de3619)
+- Updated dependencies [`0c8fbd6`](https://github.com/RhetTbull/osxphotos/commit/0c8fbd69af7a0d696de5224bf3c302e0c240905f)
+
+#### [v0.42.67](https://github.com/RhetTbull/osxphotos/compare/v0.42.66...v0.42.67)
+
+> 24 July 2021
+
+- Added {album_seq} and {folder_album_seq}, #496 [`12f39db`](https://github.com/RhetTbull/osxphotos/commit/12f39dbaf520ad767e3da667257ce00af60fdd7e)
+- Fixed {album_seq} and {folder_album_seq} help text [`077d577`](https://github.com/RhetTbull/osxphotos/commit/077d577c9890c4840a60c3e450dcd4167aa669ea)
+
+#### [v0.42.66](https://github.com/RhetTbull/osxphotos/compare/v0.42.65...v0.42.66)
+
+> 23 July 2021
+
+- Updated docs [`666b6ca`](https://github.com/RhetTbull/osxphotos/commit/666b6cac33fb8a2d0fc602609f11e190e11c538f)
+- Added {id} sequence number template, #154 [`e95c096`](https://github.com/RhetTbull/osxphotos/commit/e95c0967846106f6da2adaa0b85520df8b351bb0)
+- Updated example [skip ci] [`8216c33`](https://github.com/RhetTbull/osxphotos/commit/8216c33b596dba35007168cda4e8de34d9f4b2ea)
+
+#### [v0.42.65](https://github.com/RhetTbull/osxphotos/compare/v0.42.64...v0.42.65)
+
+> 20 July 2021
+
+- Fixed album sort order for custom sort, #497 [`e27c40c`](https://github.com/RhetTbull/osxphotos/commit/e27c40c7724dc47a7c95d1a417808c2b1f13adb0)
+- Updated test data [`a05e7be`](https://github.com/RhetTbull/osxphotos/commit/a05e7be14e080af0cef80831c3ff7fa0a897a1b2)
+- Updated example [skip ci] [`6f4cab6`](https://github.com/RhetTbull/osxphotos/commit/6f4cab6721ca3091031d8010e29d959e3afdecb2)
+
+#### [v0.42.64](https://github.com/RhetTbull/osxphotos/compare/v0.42.63...v0.42.64)
+
+> 18 July 2021
+
+- Pass dest_path to template function via RenderOptions, enable implementation of #496 [`2d899ef`](https://github.com/RhetTbull/osxphotos/commit/2d899ef0453c0800ff9b9d374b2b7db0948688fe)
+
+#### [v0.42.63](https://github.com/RhetTbull/osxphotos/compare/v0.42.62...v0.42.63)
+
+> 18 July 2021
+
+- Added album_sort_order example [`b04ea81`](https://github.com/RhetTbull/osxphotos/commit/b04ea8174d049d9f3783aac6bbc397ed71584965)
+- Updated README.md [skip ci] [`88099de`](https://github.com/RhetTbull/osxphotos/commit/88099de688bcb6a1ddcad6c340833f1627aff268)
+- Added RenderOptions to {function} template, #496 [`173a0fc`](https://github.com/RhetTbull/osxphotos/commit/173a0fce28e91177dec114d0dba001adfb76834a)
+
+#### [v0.42.62](https://github.com/RhetTbull/osxphotos/compare/v0.42.61...v0.42.62)
+
+> 16 July 2021
+
+- Upgraded osxmetadata to add new extended attributes [`7d81b94`](https://github.com/RhetTbull/osxphotos/commit/7d81b94c16623d11312aaf1b0c47fb580d01bc66)
+- Updated tutorial with --regex example [skip ci] [`bf208bb`](https://github.com/RhetTbull/osxphotos/commit/bf208bbe4b965a2d39fc1836335b7b65f402af30)
+- Update README.md [`d627cfc`](https://github.com/RhetTbull/osxphotos/commit/d627cfc4fa22497769babc3d686393c6043d1f37)
+
+#### [v0.42.61](https://github.com/RhetTbull/osxphotos/compare/v0.42.60...v0.42.61)
+
+> 7 July 2021
+
+- Added --selected, closes #489 [`#489`](https://github.com/RhetTbull/osxphotos/issues/489)
+
+#### [v0.42.60](https://github.com/RhetTbull/osxphotos/compare/v0.42.59...v0.42.60)
+
+> 6 July 2021
+
+- docs: add mkirkland4874 as a contributor for example [`#492`](https://github.com/RhetTbull/osxphotos/pull/492)
+- Updated README.md [skip ci], closes #488 [`#488`](https://github.com/RhetTbull/osxphotos/issues/488)
+- Added example for {function} template [`016297d`](https://github.com/RhetTbull/osxphotos/commit/016297d2ffcf2e8db0d659ccfe7411ecff3dd41b)
+- Fixed cleanup to delete empty folders, #491 [`1bf11b0`](https://github.com/RhetTbull/osxphotos/commit/1bf11b0414a7fcf785c792b98f6231821bdad4d4)
+
+#### [v0.42.59](https://github.com/RhetTbull/osxphotos/compare/v0.42.58...v0.42.59)
+
+> 4 July 2021
+
+- Re-enabled try/except in cli export [`d497b94`](https://github.com/RhetTbull/osxphotos/commit/d497b94ad506bf6cf044bbabe7fcbf4ab9d5b9e7)
+- Added test for try/except block in cli export [`2e32d62`](https://github.com/RhetTbull/osxphotos/commit/2e32d62237f59b16a9be422104347d6a1332865c)
+
+#### [v0.42.58](https://github.com/RhetTbull/osxphotos/compare/v0.42.57...v0.42.58)
+
+> 4 July 2021
+
+- Added --preview-if-missing, #446 [`632169f`](https://github.com/RhetTbull/osxphotos/commit/632169f2774558ef8487eb7fb9323aecbadedd88)
+
+#### [v0.42.57](https://github.com/RhetTbull/osxphotos/compare/v0.42.54...v0.42.57)
+
+> 4 July 2021
+
+- Refactored export2, #485, #486 [`28c681a`](https://github.com/RhetTbull/osxphotos/commit/28c681aa96874588bc59335b2a0db3b8be6eabaa)
+- Added --preview, #470 [`7e2d09b`](https://github.com/RhetTbull/osxphotos/commit/7e2d09bf123428c09a669d8d581e1a35e374273d)
+- Fixed path_derivatives to always return jpeg if photo is a photo [`b4dbad5`](https://github.com/RhetTbull/osxphotos/commit/b4dbad5e7451447480699105fb62b157dce8195d)
+
+#### [v0.42.54](https://github.com/RhetTbull/osxphotos/compare/v0.42.52...v0.42.54)
+
+> 2 July 2021
+
+- Removed _applescript, #461 [`1d26ac9`](https://github.com/RhetTbull/osxphotos/commit/1d26ac9630dd0a414c01cc4f89a080e4efd7fd97)
+- Removed _applescript, #461 [`03b4f59`](https://github.com/RhetTbull/osxphotos/commit/03b4f59549de54da91c36feba613d69f9e86e47b)
+- Added get_selected() to REPL [`2e1c91c`](https://github.com/RhetTbull/osxphotos/commit/2e1c91cd672eefe84063933437e5d691f5ad1db1)
+
+#### [v0.42.52](https://github.com/RhetTbull/osxphotos/compare/v0.42.51...v0.42.52)
+
+> 2 July 2021
+
+- docs: add jcommisso07 as a contributor for data [`#483`](https://github.com/RhetTbull/osxphotos/pull/483)
+- docs: add mkirkland4874 as a contributor for bug [`#482`](https://github.com/RhetTbull/osxphotos/pull/482)
+- Fix for path_raw when file is reference, #480 [`4cc3220`](https://github.com/RhetTbull/osxphotos/commit/4cc322028790b3beefce42af5e35c23976b1a35a)
+- Updated README.md [skip ci] [`6339e3c`](https://github.com/RhetTbull/osxphotos/commit/6339e3c70ee174394af356710de4bf9442bad9fc)
+
+#### [v0.42.51](https://github.com/RhetTbull/osxphotos/compare/v0.42.46...v0.42.51)
+
+> 30 June 2021
+
+- Alpha support for Monterey/macOS 12 [`08147e9`](https://github.com/RhetTbull/osxphotos/commit/08147e91d92013c9cd179187a447f81bc08de3af)
+- Refactored UTI utils to get ready for Monterey [`d034605`](https://github.com/RhetTbull/osxphotos/commit/d0346057843aae3a72a79695819df31385db596f)
+- Updated photokit code to work with raw+jpeg, #478 [`a73db3a`](https://github.com/RhetTbull/osxphotos/commit/a73db3a1bbc2a320d68dcf7f31f1074bc23a242a)
+
+#### [v0.42.46](https://github.com/RhetTbull/osxphotos/compare/v0.42.45...v0.42.46)
+
+> 23 June 2021
+
+- Bug fix for template functions #477 [`4931758`](https://github.com/RhetTbull/osxphotos/commit/49317582c4582e291463d368425513b09a799058)
+- Updated README.md [skip ci] [`64fd852`](https://github.com/RhetTbull/osxphotos/commit/64fd85253508b51c3f945f4c8ff02585f1b90aab)
+- Fixed deprecation warning [`3fbfc55`](https://github.com/RhetTbull/osxphotos/commit/3fbfc55e84756844070f4080ce415ba77d5c7665)
+
+#### [v0.42.45](https://github.com/RhetTbull/osxphotos/compare/v0.42.44...v0.42.45)
+
+> 20 June 2021
+
+- Implemented --query-function, #430 [`07da803`](https://github.com/RhetTbull/osxphotos/commit/07da8031c63487eb42cb3e524f20971e6d2fc929)
+- Added query function [skip ci] [`be363b9`](https://github.com/RhetTbull/osxphotos/commit/be363b9727d6fca6e747b0d952cd3252ddfe6e3b)
+- Updated README.md [skip ci] [`377e165`](https://github.com/RhetTbull/osxphotos/commit/377e165be48b84c7678ca2f86fc2ffdcbcb93736)
+
+#### [v0.42.44](https://github.com/RhetTbull/osxphotos/compare/v0.42.43...v0.42.44)
+
+> 20 June 2021
+
+- Added --location, --no-location, #474 [`870a59a`](https://github.com/RhetTbull/osxphotos/commit/870a59a2fa10766361b384216594af36d3605850)
+
+#### [v0.42.43](https://github.com/RhetTbull/osxphotos/compare/v0.42.42...v0.42.43)
+
+> 20 June 2021
+
+- Implemented --post-function, #442 [`987c91a`](https://github.com/RhetTbull/osxphotos/commit/987c91a9ff4b9936d479d7d238a5e5b842265dec)
+- Added post_function.py [`233942c`](https://github.com/RhetTbull/osxphotos/commit/233942c9b6836fb6fa9907e9264ec3513322930b)
+- Fixed function names to work around Click.runner issue [`821e338`](https://github.com/RhetTbull/osxphotos/commit/821e338b7575c6e053b8d3d958c481dfa62a00bc)
+
+#### [v0.42.42](https://github.com/RhetTbull/osxphotos/compare/v0.42.41...v0.42.42)
+
+> 19 June 2021
+
+- Bug fix for --download-missing, #456 [`0cd8f32`](https://github.com/RhetTbull/osxphotos/commit/0cd8f32893046b679ea6280822f4dba5aa7de1fd)
+- Updated README.md [skip ci] [`37dc023`](https://github.com/RhetTbull/osxphotos/commit/37dc023fcbfddca8abd2b72119138d72e0bfed53)
+- Added isort cfg to match black [`904acbc`](https://github.com/RhetTbull/osxphotos/commit/904acbc576b27d7d05d770e061a6c01a439b8fad)
+
+#### [v0.42.41](https://github.com/RhetTbull/osxphotos/compare/v0.42.40...v0.42.41)
+
+> 19 June 2021
+
+- Added repl command to CLI; closes #472 [`#472`](https://github.com/RhetTbull/osxphotos/issues/472)
+- Updated README.md [skip ci] [`130df1a`](https://github.com/RhetTbull/osxphotos/commit/130df1a76794f77bc0e8f148185c6407d6b480bc)
+
+#### [v0.42.40](https://github.com/RhetTbull/osxphotos/compare/v0.42.39...v0.42.40)
+
+> 19 June 2021
+
+- Added tutorial, closes #432 [`#432`](https://github.com/RhetTbull/osxphotos/issues/432)
+
+#### [v0.42.39](https://github.com/RhetTbull/osxphotos/compare/v0.42.38...v0.42.39)
+
+> 18 June 2021
+
+- Updated help text, #469 [`42c551d`](https://github.com/RhetTbull/osxphotos/commit/42c551de8a1e6f682c04b6071c1147eb8039ed3a)
+
+#### [v0.42.38](https://github.com/RhetTbull/osxphotos/compare/v0.42.37...v0.42.38)
+
+> 18 June 2021
+
+- Added error handling for --add-to-album [`bc5cd93`](https://github.com/RhetTbull/osxphotos/commit/bc5cd93e974214e2327d604ff92b3c6b6ce62f04)
+- Updated README.md [skip ci] [`62d49a7`](https://github.com/RhetTbull/osxphotos/commit/62d49a7138971c43625e55518f069b1b36b787ff)
+
+#### [v0.42.37](https://github.com/RhetTbull/osxphotos/compare/v0.42.36...v0.42.37)
+
+> 18 June 2021
+
+- Added additional info to error message for --add-to-album [`64bb07a`](https://github.com/RhetTbull/osxphotos/commit/64bb07a0267f2fdd024a7150fe1788b07218ac2f)
+
+#### [v0.42.36](https://github.com/RhetTbull/osxphotos/compare/v0.42.35...v0.42.36)
+
+> 18 June 2021
+
+- Fix for #471 [`8e3f8fc`](https://github.com/RhetTbull/osxphotos/commit/8e3f8fc7d089b644b85e8e52fe220519133d2bea)
+- Updated README.md [skip ci] [`f1902b7`](https://github.com/RhetTbull/osxphotos/commit/f1902b7fd4d22c47bcf9fd101b077bbbabb71a9a)
+
+#### [v0.42.35](https://github.com/RhetTbull/osxphotos/compare/v0.42.34...v0.42.35)
+
+> 18 June 2021
+
+- Added --post-command, implements #443 [`fa29f51`](https://github.com/RhetTbull/osxphotos/commit/fa29f51aeb89b3f14176693a9d0a5ff8c3565b71)
+- Added matrix for GitHub action OS [`ee0b369`](https://github.com/RhetTbull/osxphotos/commit/ee0b3690869e9dbf48e733353540c19d44da51e3)
+- Added macos 10.15 and 11 [`2fc45c2`](https://github.com/RhetTbull/osxphotos/commit/2fc45c2468ecf09bb9370f1c2057d63157501839)
+
+#### [v0.42.34](https://github.com/RhetTbull/osxphotos/compare/v0.42.31...v0.42.34)
+
+> 14 June 2021
+
+- Refactored PhotoTemplate to support pathlib templates [`2cdec3f`](https://github.com/RhetTbull/osxphotos/commit/2cdec3fc78155a10362e6c65c2ec0e7ebf61ee38)
+- Added {filepath} template field in prep for --post-command and other goodies [`c0bd0ff`](https://github.com/RhetTbull/osxphotos/commit/c0bd0ffc9fa3c8aeefd1452cbb9b82511393004f)
+- Fixed missing more-itertools, #466 [`1009732`](https://github.com/RhetTbull/osxphotos/commit/10097323e5372939e1af69849dc1d4ddaf3c6667)
+
+#### [v0.42.31](https://github.com/RhetTbull/osxphotos/compare/v0.42.30...v0.42.31)
+
+> 12 June 2021
+
+- Cleaned up tests, fixed bug in PhotosDB.query [`0758f84`](https://github.com/RhetTbull/osxphotos/commit/0758f84dc4bae74854c2321bc71c033d71acd4e2)
+- Added --duplicate flag to find possible duplicates [`83892e0`](https://github.com/RhetTbull/osxphotos/commit/83892e096a2987a99c2bb2dc08e7bb8ab569a289)
+- Updated README.md [skip ci] [`1a46cdf`](https://github.com/RhetTbull/osxphotos/commit/1a46cdf63ce6defbd8cd6cbacc65fa5779102582)
+
+#### [v0.42.30](https://github.com/RhetTbull/osxphotos/compare/v0.42.28...v0.42.30)
+
+> 9 June 2021
+
+- Refactored PhotoInfo.export2 [`d7a9ad1`](https://github.com/RhetTbull/osxphotos/commit/d7a9ad1d0a6d1c4327e9d43b7719d860abd34836)
+- Updated dependencies to minimize pyobjc requirements [`61943d0`](https://github.com/RhetTbull/osxphotos/commit/61943d051b8e37397eb009c8ae0b0ba86c0ab3a3)
+- Fix for --convert-to-jpeg with use_photos_export, #460 [`4b6c35b`](https://github.com/RhetTbull/osxphotos/commit/4b6c35b5f939f18c0147fb034ab619f7c4f9b124)
+
+#### [v0.42.28](https://github.com/RhetTbull/osxphotos/compare/v0.42.27...v0.42.28)
+
+> 1 June 2021
+
+- Added PhotoInfo.duplicates [`7accfdb`](https://github.com/RhetTbull/osxphotos/commit/7accfdb06654184e74517033749787ed049d8b7f)
+- Added CONTRIBUTING.md [`99f4394`](https://github.com/RhetTbull/osxphotos/commit/99f4394f8e71f636f6e090ecb508672f672205e8)
+
+#### [v0.42.27](https://github.com/RhetTbull/osxphotos/compare/v0.42.26...v0.42.27)
+
+> 29 May 2021
+
+- Fix for #455 [`b48133c`](https://github.com/RhetTbull/osxphotos/commit/b48133cd8309ce7e9a6dbab283d484a552135e33)
+- Updated README.md [skip ci] [`9161739`](https://github.com/RhetTbull/osxphotos/commit/9161739ee61b0098a6930df34ec5cfd5a9abd722)
+- Updated README.rst for PyPI [`71cf8be`](https://github.com/RhetTbull/osxphotos/commit/71cf8be94a4387676135d8f2e108a9de7f7cf4df)
+
+#### [v0.42.26](https://github.com/RhetTbull/osxphotos/compare/v0.42.24...v0.42.26)
+
+> 28 May 2021
+
+- docs: add kaduskj as a contributor [`#453`](https://github.com/RhetTbull/osxphotos/pull/453)
+- Fixed bug in imageconverter exception handling, closes #440 [`#440`](https://github.com/RhetTbull/osxphotos/issues/440)
+- PhotoInfo.exiftool now returns ExifToolCaching, closes #450 [`#450`](https://github.com/RhetTbull/osxphotos/issues/450)
+- Fixes for #454 [`2d68594`](https://github.com/RhetTbull/osxphotos/commit/2d68594b7811a60fedf002e712c48b1a0ca87361)
+- Updated tested versions to 11.3 [`a298772`](https://github.com/RhetTbull/osxphotos/commit/a2987725151a0e4b6e399ccfeaedceac33afd5c6)
+- Updated README.md [skip ci] [`24ccf79`](https://github.com/RhetTbull/osxphotos/commit/24ccf798c2aefd8cafa8645c1bff4c0a5776f0b1)
+- Updated README.md [skip ci] [`b026147`](https://github.com/RhetTbull/osxphotos/commit/b026147c9ad4ba01129a243a1d2d60044b0181d3)
+
 #### [v0.42.24](https://github.com/RhetTbull/osxphotos/compare/v0.42.23...v0.42.24)

 > 23 May 2021
@@ -87,6 +545,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added tutorial to README [`f54205f`](https://github.com/RhetTbull/osxphotos/commit/f54205ff49a37bbef4dfca435602a50fbb4ebd02)
 - Refactored export_photo to enable work on #420 [`48c229b`](https://github.com/RhetTbull/osxphotos/commit/48c229b52c9a1881832d61434fcf38284ade918c)
 - Refactored README.md to improve Template System section [`1d14fc8`](https://github.com/RhetTbull/osxphotos/commit/1d14fc8041ae0a2b7db3b95bb08a5986176de649)
+- Updated tutorial [`aad435d`](https://github.com/RhetTbull/osxphotos/commit/aad435da3683834e17cb18b87c2aa7d1306e068e)
+- Fixed typo in tutorial [`131105d`](https://github.com/RhetTbull/osxphotos/commit/131105d82cf74bdf2dbf67077fd317d775c5b74e)

 #### [v0.42.9](https://github.com/RhetTbull/osxphotos/compare/v0.42.8...v0.42.9)

@@ -102,6 +562,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Updated docs [skip ci] [`3f57514`](https://github.com/RhetTbull/osxphotos/commit/3f57514fa37bdaf372f52e02dbf76f1bc2b66b9b)
 - Updated docs [`50fa851`](https://github.com/RhetTbull/osxphotos/commit/50fa851f23f5a40f116d520fc70b1f523636b9a3)
 - Added template_filter.py to examples [`9371db0`](https://github.com/RhetTbull/osxphotos/commit/9371db094e40c3d64745b705b8b3ebdcbd04267d)
+- Fixed docs for function: filter [`1cdf4ad`](https://github.com/RhetTbull/osxphotos/commit/1cdf4addade706b5bf3105441a70fc9d529608a9)
+- Version bump [`a483b8a`](https://github.com/RhetTbull/osxphotos/commit/a483b8a900de66b6124e91d53c44260e3c3dfea8)

 #### [v0.42.6](https://github.com/RhetTbull/osxphotos/compare/v0.42.4...v0.42.6)

@@ -237,6 +699,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added AdjustmentsInfo, #150, #379 [`5ee6aff`](https://github.com/RhetTbull/osxphotos/commit/5ee6affc0525db1975cb5095f62494ef10d92f7e)
 - docs: update .all-contributorsrc [skip ci] [`ebac9d0`](https://github.com/RhetTbull/osxphotos/commit/ebac9d0bfb43f59f046aacdd0290d1fcd29a3b5e)
 - docs: update README.md [skip ci] [`29716c5`](https://github.com/RhetTbull/osxphotos/commit/29716c52726a4e699c03d43ecc67db57f55b36f8)
+- Version bump [`fbe8229`](https://github.com/RhetTbull/osxphotos/commit/fbe822910370652975ab83b82344169df4c3027c)

 #### [v0.40.17](https://github.com/RhetTbull/osxphotos/compare/v0.40.16...v0.40.17)

@@ -306,6 +769,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Fixed XMP template for issue #361 [`43af4d2`](https://github.com/RhetTbull/osxphotos/commit/43af4d205a7264e530bc2b2789d297be633391e1)
 - Updated sidecar test data [`591f9bc`](https://github.com/RhetTbull/osxphotos/commit/591f9bcc62720f7eddebba3b3dcff265907550dd)
 - Added tests for --only-new, #358 [`adc4b05`](https://github.com/RhetTbull/osxphotos/commit/adc4b056029794faddd464d22022a2a17298a924)
+- Updated tests for ExportDB, #358 [`48d2223`](https://github.com/RhetTbull/osxphotos/commit/48d2223edde4850830cc6a3f9776ce08f81a6636)
+- Added 11.2 to tested versions, #360 [`2284598`](https://github.com/RhetTbull/osxphotos/commit/2284598a24f63232c01dcf27b9982002123834ca)

 #### [v0.40.6](https://github.com/RhetTbull/osxphotos/compare/v0.40.5...v0.40.6)

@@ -431,6 +896,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Create terminalizer-demo.yml [`5dc2eea`](https://github.com/RhetTbull/osxphotos/commit/5dc2eeaf9a7265873c81db23bbc86d3023189a26)
 - Force cleanup of objects with autorelease pool [`b67f11a`](https://github.com/RhetTbull/osxphotos/commit/b67f11a3bb95c08a39a185b6d884092870e949f2)
 - doc: Recorded screencast and updated of readme  [`658e8ac`](https://github.com/RhetTbull/osxphotos/commit/658e8ac096d141fce48483dbfc1426bea317d806)
+- doc: fixed toc in readme [`aba50c5`](https://github.com/RhetTbull/osxphotos/commit/aba50c5c733420dc30f861d866a2c0bdc8933714)
+-  Add @Rott-Apple as a contributor [`71cb015`](https://github.com/RhetTbull/osxphotos/commit/71cb01572d2d946df18dd7b36f95b2f2e5b48f86)

 #### [v0.39.11](https://github.com/RhetTbull/osxphotos/compare/v0.39.10...v0.39.11)

@@ -442,6 +909,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Ensure merge_exif_keywords are str not int [`123ebb2`](https://github.com/RhetTbull/osxphotos/commit/123ebb2cb752bb94291ac2b77e4a327cee996df1)
 - docs: update .all-contributorsrc [skip ci] [`5e676d3`](https://github.com/RhetTbull/osxphotos/commit/5e676d3507c3e2e1f1cd9da7d8843005865c0d4c)
 - docs: update README.md [skip ci] [`935865d`](https://github.com/RhetTbull/osxphotos/commit/935865dc6572bc8e80a8eb1ab8f000342ded0a2b)
+- Updated tests workflow badge link [`a7678df`](https://github.com/RhetTbull/osxphotos/commit/a7678df3974ff539050f5acb4c94817f525dcd56)
+- Ensure keyword list only contains string [`7b6a0af`](https://github.com/RhetTbull/osxphotos/commit/7b6a0af3146202030069ed5823061ee221ab41bc)

 #### [v0.39.10](https://github.com/RhetTbull/osxphotos/compare/v0.39.9...v0.39.10)

@@ -473,6 +942,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added tag_groups arg to ExifTool.asdict(), issue #324 [`2480f2a`](https://github.com/RhetTbull/osxphotos/commit/2480f2a325dbb09689f8c417618b7b9e976bfcb9)
 - doc: start with examples before the export reference [`7c7bf1b`](https://github.com/RhetTbull/osxphotos/commit/7c7bf1be6b6382a995a4e17906adfd8720d0a1c3)
 - Updated dependencies in README.md [`b1cab32`](https://github.com/RhetTbull/osxphotos/commit/b1cab32ff4c7b65ae4c9a5a9a11c175dbd487c0a)
+- remove extra spaces [`a59bb5b`](https://github.com/RhetTbull/osxphotos/commit/a59bb5b02f10fa554dae346a7271be37f50d8bcc)
+- Adding back  dependency https://github.com/RhetTbull/PhotoScript) [`7c8bfc8`](https://github.com/RhetTbull/osxphotos/commit/7c8bfc811ab3a93dabadf1655f7d0e217d6c7b01)

 #### [v0.39.6](https://github.com/RhetTbull/osxphotos/compare/v0.39.5...v0.39.6)

@@ -482,6 +953,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - doc simplify readme [`02ef0f9`](https://github.com/RhetTbull/osxphotos/commit/02ef0f9a254e83a3729a09cea1ae523407074896)
 - Added exception handling/capture for convert-to-jpeg, issue #322 [`05f111a`](https://github.com/RhetTbull/osxphotos/commit/05f111a287e882ed6b451a550a87753501316aba)
 - Cleanup up the readme [`38842ff`](https://github.com/RhetTbull/osxphotos/commit/38842ff9249e6f5b3069a88a759c8df97ddce51c)
+-  Add @synox as a contributor [`83915c6`](https://github.com/RhetTbull/osxphotos/commit/83915c65abb880036f80ebd830eb1e34292f9599)

 #### [v0.39.5](https://github.com/RhetTbull/osxphotos/compare/v0.39.4...v0.39.5)

@@ -519,6 +991,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added tests for Finder tags [`29e4245`](https://github.com/RhetTbull/osxphotos/commit/29e424575a522ae03efe5a140be46bfd0a1346c5)
 - Initial implementation for Finder tags [`5885b23`](https://github.com/RhetTbull/osxphotos/commit/5885b23d3249cf91953092a6b1ce967da2667e29)
 - Updated README for finder tags [`f25a299`](https://github.com/RhetTbull/osxphotos/commit/f25a2993097ad7b2b8ab2d1c787db58c0d799a41)
+- Updated requirements.txt [`ea373c4`](https://github.com/RhetTbull/osxphotos/commit/ea373c4197ce1cce00e89157fe560d1366f7e764)

 #### [v0.38.22](https://github.com/RhetTbull/osxphotos/compare/v0.38.21...v0.38.22)

@@ -628,6 +1101,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added additional test cases for #286, --ignore-signature [`880a9b6`](https://github.com/RhetTbull/osxphotos/commit/880a9b67a14787ef23ae68ad3164d7eda1af16ec)
 -  Add @finestream as a contributor [`ad860b1`](https://github.com/RhetTbull/osxphotos/commit/ad860b1500dffd846322e05562ba4f2019cd1017)
 - Fixed issue #296 [`a7c688c`](https://github.com/RhetTbull/osxphotos/commit/a7c688cfc2221833e0252d71bbe596eee5f9a6e8)
+- Updated README.md [`d40b16a`](https://github.com/RhetTbull/osxphotos/commit/d40b16a456c64014674505b7c715c80b977da76a)
+- Update __main__.py [`e097f3a`](https://github.com/RhetTbull/osxphotos/commit/e097f3aad546b5be5eabab529bd2c35ce3056876)

 #### [v0.38.5](https://github.com/RhetTbull/osxphotos/compare/v0.38.4...v0.38.5)

@@ -655,6 +1130,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - removed extended_attributes reference [`6559c4d`](https://github.com/RhetTbull/osxphotos/commit/6559c4d8f64ad41df925182f9f24f6f67eecd1df)
 - This is why I never use branches [`baf45cc`](https://github.com/RhetTbull/osxphotos/commit/baf45ccd2aa24858bb1a8f95ef798121ee80af30)
 - Initial implementation of configoptions for --save-config, --load-config [`22355fd`](https://github.com/RhetTbull/osxphotos/commit/22355fd44609f42e412c580dfc9e5e0b7cf6c464)
+- Refactoring of save-config/load-config code [`37b1e5c`](https://github.com/RhetTbull/osxphotos/commit/37b1e5ca472e9679301fa96d2b7fdd8c4ad438b2)
+- Added tests for configoptions.py [`0262e0d`](https://github.com/RhetTbull/osxphotos/commit/0262e0d97e06ee36786b4491efa178608afb5de5)

 #### [v0.38.0](https://github.com/RhetTbull/osxphotos/compare/v0.37.7...v0.38.0)

@@ -746,6 +1223,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added test for missing original_filename [`116cb66`](https://github.com/RhetTbull/osxphotos/commit/116cb662fbddf9153f6858c6ea97dc7f65c77705)
 -  Add @jstrine as a contributor [`7460bc8`](https://github.com/RhetTbull/osxphotos/commit/7460bc88fcc5e1e7435c9b9bcdf7ec9c7c5e39ea)
 - Escape characters which cause XML parsing issues [`c42050a`](https://github.com/RhetTbull/osxphotos/commit/c42050a10cac40b0b5ac70c587e07f257a9b50dd)
+- Fix tests for apostrophe [`d0d2e80`](https://github.com/RhetTbull/osxphotos/commit/d0d2e8080096bf66f93a830386800ce713680c51)
+- Fix test for XMP sidecar with GPS info [`c27cfb1`](https://github.com/RhetTbull/osxphotos/commit/c27cfb1223fa82b9e5549b93c283e9444693270a)

 #### [v0.36.21](https://github.com/RhetTbull/osxphotos/compare/v0.36.20...v0.36.21)

@@ -929,6 +1408,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - --convert-to-jpeg initial version working [`38f201d`](https://github.com/RhetTbull/osxphotos/commit/38f201d0fb70bf299a828c1dd0d034a119e380c4)
 - Added tests, fixed bug in export_db [`5a13605`](https://github.com/RhetTbull/osxphotos/commit/5a13605f850bb947c8888246f06a5ca4e6aa5f10)
 - Updated tests [`b2b39aa`](https://github.com/RhetTbull/osxphotos/commit/b2b39aa6075df11861cf5d8945b657204f120e87)
+- Fixed path_edited for Big Sur [`c389207`](https://github.com/RhetTbull/osxphotos/commit/c389207daa4fec555fbf9d2aee8347997f9a8412)
+- Added HEIC test image [`ddc1e69`](https://github.com/RhetTbull/osxphotos/commit/ddc1e69b4a4ac712e1af312b865c4216f9ad350c)

 #### [v0.34.5](https://github.com/RhetTbull/osxphotos/compare/v0.34.3...v0.34.5)

@@ -945,6 +1426,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added tests for 10.15.6 [`432da7f`](https://github.com/RhetTbull/osxphotos/commit/432da7f139a5e4b37eeb358f4ede45314407f8e5)
 - Fixed bug related to issue #222 [`c939df7`](https://github.com/RhetTbull/osxphotos/commit/c939df717159e8b97955c0b267327cd56a9ed56c)
 - Version bump for bug fix [`62d54cc`](https://github.com/RhetTbull/osxphotos/commit/62d54cc0beabd0141545608184d4b2c658eedf0f)
+- Update README.md [`6883fec`](https://github.com/RhetTbull/osxphotos/commit/6883fec2b2236d892b88327e1b4e9da1237f7dea)
+- Update exiftool.py [`3d21dad`](https://github.com/RhetTbull/osxphotos/commit/3d21dadf4102e9101e48a0c6f739a544f7f9d9de)

 #### [v0.34.2](https://github.com/RhetTbull/osxphotos/compare/v0.34.1...v0.34.2)

@@ -980,6 +1463,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Normalize unicode for issue #208 [`a36eb41`](https://github.com/RhetTbull/osxphotos/commit/a36eb416b19284477922b6a5f837f4040327138b)
 - Added force_download.py to examples [`b611d34`](https://github.com/RhetTbull/osxphotos/commit/b611d34d19db480af72f57ef55eacd0a32c8d1e8)
 - Added photoshop:SidecarForExtension to XMP, partial fix for #210 [`60d96a8`](https://github.com/RhetTbull/osxphotos/commit/60d96a8f563882fba2365a6ab58c1276725eedaa)
+- Updated README.md [`c9b1518`](https://github.com/RhetTbull/osxphotos/commit/c9b15186a022d91248451279e5f973e3f2dca4b4)
+- Update README.md [`42e8fba`](https://github.com/RhetTbull/osxphotos/commit/42e8fba125a3c6b1bd0d538f2af511aabfbeb478)

 #### [v0.33.5](https://github.com/RhetTbull/osxphotos/compare/v0.33.3...v0.33.5)

@@ -1006,6 +1491,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - --touch-file now working with --update [`6c11e3f`](https://github.com/RhetTbull/osxphotos/commit/6c11e3fa5b5b05b98b9fdbb0e59e3a78c7dff980)
 - Refactor/cleanup _export_photo [`eefa1f1`](https://github.com/RhetTbull/osxphotos/commit/eefa1f181f4fd7b027ae69abd2b764afb590c081)
 - Fixed touch tests [`1bf7105`](https://github.com/RhetTbull/osxphotos/commit/1bf7105737fbd756064a2f9ef4d4bbd0b067978c)
+- Working on issue 206 [`ebd878a`](https://github.com/RhetTbull/osxphotos/commit/ebd878a075983ef3df0b1ead1a725e01508721f8)
+- Working on issue #206 [`c9c9202`](https://github.com/RhetTbull/osxphotos/commit/c9c920220545dc27c8cb1379d7bde15987cce72c)

 #### [v0.33.0](https://github.com/RhetTbull/osxphotos/compare/v0.32.0...v0.33.0)

@@ -1016,6 +1503,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added tests for 10.15.6 [`d2deeff`](https://github.com/RhetTbull/osxphotos/commit/d2deefff834e46e1a26adc01b1b025ac839dbc78)
 - Added ImportInfo for Photos 5+ [`98e4170`](https://github.com/RhetTbull/osxphotos/commit/98e417023ec5bd8292b25040d0844f3706645950)
 - Update README.md [`360c8d8`](https://github.com/RhetTbull/osxphotos/commit/360c8d8e1b4760e95a8b71b3a0bf0df4fb5adaf5)
+- Update README.md [`868cda8`](https://github.com/RhetTbull/osxphotos/commit/868cda8482ce6b29dd00e04a209d40550e6b128b)

 #### [v0.32.0](https://github.com/RhetTbull/osxphotos/compare/v0.31.2...v0.32.0)

@@ -1032,6 +1520,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Dropped py36 due to datetime.fromisoformat [`a714ae0`](https://github.com/RhetTbull/osxphotos/commit/a714ae0af089b13acf70c4f29934393aa48ed222)
 - Added --uuid-from-file to CLI [`840e993`](https://github.com/RhetTbull/osxphotos/commit/840e9937bede407ef55972a361618683245e086b)
 - Added write_uuid_to_file.applescript to utils [`bea770b`](https://github.com/RhetTbull/osxphotos/commit/bea770b322d21cf3f8245d20e182006247cb71d6)
+- Updated README.md [`002fce8`](https://github.com/RhetTbull/osxphotos/commit/002fce8e93edd936d4b866118ae6d4c94e5d6744)
+- Added py37 [`d0ec862`](https://github.com/RhetTbull/osxphotos/commit/d0ec8620c721fe7576ab7d519a5eaac4d17a317e)

 #### [v0.31.0](https://github.com/RhetTbull/osxphotos/compare/v0.30.13...v0.31.0)

@@ -1243,6 +1733,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added test for Photos 5 on 10.15.5 [`2243395`](https://github.com/RhetTbull/osxphotos/commit/2243395bff9e1cc379626cc5007e44e6e63b95e0)
 - Refactored template code out of PhotoInfo into PhotoTemplate [`16f802b`](https://github.com/RhetTbull/osxphotos/commit/16f802bf717610e13712b8aa477d05d94b14d294)
 - Added test for SearchInfo on 10.15.5 [`3a8bef1`](https://github.com/RhetTbull/osxphotos/commit/3a8bef1572e4d83b1e0a4b85c8f06e329cc7e8de)
+- performance improvements for update and export_db [`42b89d3`](https://github.com/RhetTbull/osxphotos/commit/42b89d34f3d14818daefbd3bfabc1be9344d2e1a)
+- More refactoring in PhotoTemplate [`f35ea70`](https://github.com/RhetTbull/osxphotos/commit/f35ea70b72e8c6743b1f6009466d2a15d40338ac)

 #### [v0.29.5](https://github.com/RhetTbull/osxphotos/compare/v0.29.2...v0.29.5)

@@ -1274,6 +1766,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added --update to CLI export; reference issue #100 [`b1171e9`](https://github.com/RhetTbull/osxphotos/commit/b1171e96cc06362555725995bb311317eb163e49)
 - Added as_dict to PlaceInfo [`8c4fe40`](https://github.com/RhetTbull/osxphotos/commit/8c4fe40aa6850f166e526cffaa088550884399af)
 - Updated README.md [`11d368a`](https://github.com/RhetTbull/osxphotos/commit/11d368a69cbe67e909e64b020f0334fc09dd3ac4)
+- version bump [`c06c230`](https://github.com/RhetTbull/osxphotos/commit/c06c230a469754691d11fff1034fb02daeeba649)
+- Test library update [`f416418`](https://github.com/RhetTbull/osxphotos/commit/f416418546a12bc6c1bda13f6b712758584d06dc)

 #### [v0.28.19](https://github.com/RhetTbull/osxphotos/compare/v0.28.18...v0.28.19)

@@ -1283,6 +1777,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Revert "test library updates" [`48e9c32`](https://github.com/RhetTbull/osxphotos/commit/48e9c32add549e66c3ef8c65f8821f5033b55b11)
 - test library updates [`d125854`](https://github.com/RhetTbull/osxphotos/commit/d125854f2a04e37747af3e0796370a565c1c9bd0)
 - version bump [`bd9d5a2`](https://github.com/RhetTbull/osxphotos/commit/bd9d5a26f3bfcbb33896a139fa86cdab46768103)
+- Update README.md [`85760dc`](https://github.com/RhetTbull/osxphotos/commit/85760dc4fe2274d826ed80494fd4e66866398609)
+- Update README.md [`be07f90`](https://github.com/RhetTbull/osxphotos/commit/be07f90e5a8179e452730ea654e4c9627b1f6ebc)

 #### [v0.28.18](https://github.com/RhetTbull/osxphotos/compare/v0.28.17...v0.28.18)

@@ -1307,6 +1803,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Refactored photosdb and photoinfo to add SearchInfo and labels [`98b3f63`](https://github.com/RhetTbull/osxphotos/commit/98b3f63a92aa2105f8fa97af992fc6fe2d78b973)
 - Added additional test for --export-as-hardlink [`57315d4`](https://github.com/RhetTbull/osxphotos/commit/57315d44497fde977956f76f667470208f11aa2d)
 - Updated a couple of tests to use pytest-mock [`397db0d`](https://github.com/RhetTbull/osxphotos/commit/397db0d72fb218669a9ecbff134fa9b392a14661)
+- added test for export using hardlinks, fixed a test that failed if users locale settings were different to en_US [`b0ec6c6`](https://github.com/RhetTbull/osxphotos/commit/b0ec6c6b36d8cfe05723d47b210d9d7c5aabdfe5)
+- Added link to original work by @simonw [`ca8f2b8`](https://github.com/RhetTbull/osxphotos/commit/ca8f2b8d5c55b5a554fd1337b1070c97ec381916)

 #### [v0.28.13](https://github.com/RhetTbull/osxphotos/compare/v0.28.10...v0.28.13)

@@ -1357,6 +1855,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Updated tests and test library with RAW images [`9b9b54e`](https://github.com/RhetTbull/osxphotos/commit/9b9b54e590e43ae49fb3ae41d493a1f8faec4181)
 - Updated setup.py to resolve issue with bpylist2 on python &lt; 3.8 [`8e4b88a`](https://github.com/RhetTbull/osxphotos/commit/8e4b88ad1fc18438f941e045bfc8aeac878914f9)
 - Added cli.py for use with pyinstaller [`cf28cb6`](https://github.com/RhetTbull/osxphotos/commit/cf28cb6452de17f2ef8d80435386e8d5a1aabd34)
+- added raw_is_original handling [`a337e79`](https://github.com/RhetTbull/osxphotos/commit/a337e79e13802b4824c2f088ce9db1c027d6f3c5)
+- Updated setup.py and README with install instructions [`85d2baa`](https://github.com/RhetTbull/osxphotos/commit/85d2baac104fbd0db5cccc0888a55805a2385b9a)

 #### [0.28.2](https://github.com/RhetTbull/osxphotos/compare/v0.28.1...0.28.2)

@@ -1435,6 +1935,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Updated render_filepath_template to support multiple values [`6a89888`](https://github.com/RhetTbull/osxphotos/commit/6a898886ddadc9d5bc9dbad6ee7365270dd0a26d)
 - Added {album}, {keyword}, and {person} to template system [`507c4a3`](https://github.com/RhetTbull/osxphotos/commit/507c4a374014f999ca19789bce0df0c14332e021)
 - Added places command to CLI [`fd5e748`](https://github.com/RhetTbull/osxphotos/commit/fd5e748dca759ea1c3a7329d447f363afe8418b7)
+- Updated export example [`01cd7fe`](https://github.com/RhetTbull/osxphotos/commit/01cd7fed6d7fc0c61c171a05319c211eb0a9f7c1)
+- Fixed typo in help text [`c02953e`](https://github.com/RhetTbull/osxphotos/commit/c02953ef5fe1aee219e0557bfd8c3322f1900a81)

 #### [v0.24.2](https://github.com/RhetTbull/osxphotos/compare/v0.24.1...v0.24.2)

@@ -1513,6 +2015,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added query/export options for special media types [`2b7d84a`](https://github.com/RhetTbull/osxphotos/commit/2b7d84a4d103982ad874d875bafbc34d654d539a)
 - README.md update [`a27ce33`](https://github.com/RhetTbull/osxphotos/commit/a27ce33473df3260dfb7ed26e28295cbf87d1e78)
 - Test library updates [`2d7d0b8`](https://github.com/RhetTbull/osxphotos/commit/2d7d0b86e0008cae043e314937504f36ad882990)
+- Fixed bug in --download-missing related to burst images [`1f13ba8`](https://github.com/RhetTbull/osxphotos/commit/1f13ba837fe36ff4eeb48cca02f5312a88a0a765)
+- test library update [`acb6b9e`](https://github.com/RhetTbull/osxphotos/commit/acb6b9e72f7f6b8f4f1d64b46f270a4d3e984fef)

 #### [v0.22.13](https://github.com/RhetTbull/osxphotos/compare/v0.22.12...v0.22.13)

@@ -1546,6 +2050,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Slight refactor to PhotosDB.photos() [`91d5729`](https://github.com/RhetTbull/osxphotos/commit/91d5729beaa0f0c2583e6320b18d958429e66075)
 - Test library updates [`6e563e2`](https://github.com/RhetTbull/osxphotos/commit/6e563e214c569ba7838f7464de9258c3bba5db23)
 - Removed _tmp_file code that's no longer needed [`27994c9`](https://github.com/RhetTbull/osxphotos/commit/27994c9fd372303833a5794f1de9815f425c762e)
+- Updated photos_repl.py [`fdf636a`](https://github.com/RhetTbull/osxphotos/commit/fdf636ac8864ebb2cc324b1f9d3c6c82ee3910f9)
+- Added PhotosDB() behavior to open last library if no args passed but also added cautionary note to README [`46d3c7d`](https://github.com/RhetTbull/osxphotos/commit/46d3c7dbdaf848d5c340ce8a362ff296a36c552d)

 #### [v0.22.7](https://github.com/RhetTbull/osxphotos/compare/v0.22.4...v0.22.7)

@@ -1558,6 +2064,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added XMP sidecar to export [`4dfb131`](https://github.com/RhetTbull/osxphotos/commit/4dfb131a21b1b1efefe3b918ecb06fc6fcb03f2c)
 - Added date_modified to PhotoInfo [`67b0ae0`](https://github.com/RhetTbull/osxphotos/commit/67b0ae0bf679815372d415c3064e21d46a5b8718)
 - Added date_modified to PhotoInfo [`4d36b3b`](https://github.com/RhetTbull/osxphotos/commit/4d36b3b31f3e0e74d9d111b6b691771e19f94086)
+- Updated CLI options with more descriptive metavar names [`e79cb92`](https://github.com/RhetTbull/osxphotos/commit/e79cb92693758c984dc789d5fa5d2e87e381e921)
+- CLI now looks for photos library to use if non specified by user [`50b7e69`](https://github.com/RhetTbull/osxphotos/commit/50b7e6920a694aa45f478d1131868525c9147919)

 #### [v0.22.4](https://github.com/RhetTbull/osxphotos/compare/v0.22.0...v0.22.4)

@@ -1568,6 +2076,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Refactor cli: singular --db, --json and query options. [`e214746`](https://github.com/RhetTbull/osxphotos/commit/e214746063271e6f9f586286103ed051ada49d85)
 - Implement from_date and to_date in PhotosDB as well as query and export command. Some refactoring of CLI as well. [`cfa2b4a`](https://github.com/RhetTbull/osxphotos/commit/cfa2b4a828facf0aff5bc19f777457ad776c4a05)
 - Refactored _query.  Still hairy, but less so. [`b9dee49`](https://github.com/RhetTbull/osxphotos/commit/b9dee4995c6d89fadb3d2482374b7098f2ab5ed9)
+- Updated README.md [`0aff83f`](https://github.com/RhetTbull/osxphotos/commit/0aff83ff21c20e293c0b75bacf2863090a0fb725)
+- Started adding tests for CLI [`f0b18c3`](https://github.com/RhetTbull/osxphotos/commit/f0b18c3d29b2141d348be0495013c51c072c6251)

 #### [v0.22.0](https://github.com/RhetTbull/osxphotos/compare/v0.21.5...v0.22.0)

@@ -1618,6 +2128,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - removed old applescript code and files [`1839593`](https://github.com/RhetTbull/osxphotos/commit/18395933a583314d5d992492713752003852e75c)
 - Added test cases and documentation for shared photos and shared albums [`6d20e9e`](https://github.com/RhetTbull/osxphotos/commit/6d20e9e36185aa027d82237cadfe3b55614ba96f)
 - Refactored PhotoInfo to use properties instead of methods--major update [`1ddd90c`](https://github.com/RhetTbull/osxphotos/commit/1ddd90cbdc824afc5df9d2347e730bd9f86350ee)
+- Moved PhotosDB attributes to properties instead of methods [`d95acdf`](https://github.com/RhetTbull/osxphotos/commit/d95acdf9f8764a1720bcba71a6dad29bf668eaf9)
+- changed interface for export, prepped for exiftool_json_sidecar [`1fe8859`](https://github.com/RhetTbull/osxphotos/commit/1fe885962e8a9a420e776bdd3dc640ca143224b2)

 #### [v0.15.1](https://github.com/RhetTbull/osxphotos/compare/v0.15.0...v0.15.1)

@@ -1641,6 +2153,8 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Added get_db_path and get_library_path to PhotosDB [`1d006a4`](https://github.com/RhetTbull/osxphotos/commit/1d006a4b50ed58b01c6116734bef5f740655a063)
 - Updated PhotosDB.__init__() to accept positional or named arg for dbfile and added associated tests [`9118043`](https://github.com/RhetTbull/osxphotos/commit/911804317b98bf485a39b8588c772be14314aa51)
 - Updated album code in process_database4 and process_database5 to use album uuid [`1cf3e4b`](https://github.com/RhetTbull/osxphotos/commit/1cf3e4b9540c15f8bda2545deb183912bcda40a7)
+- Updated get_db_version and associated tests [`eb563ad`](https://github.com/RhetTbull/osxphotos/commit/eb563ad29738f29f3514ebfb4747baa2dc5356be)
+- Added external_edit for Photos 5 [`42baa29`](https://github.com/RhetTbull/osxphotos/commit/42baa29c18fe2ff16e4d684f87ef7a85993898c1)

 #### [v0.14.8](https://github.com/RhetTbull/osxphotos/compare/v0.14.6...v0.14.8)

--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,15 @@
+# Contributing
+
+Contributions of all kinds are welcome!  You don't need to know python to contribute to this project. For example, documentation updates are just as welcome as code!
+
+Please explore open [issues](https://github.com/RhetTbull/osxphotos/issues), [discussions](https://github.com/RhetTbull/osxphotos/discussions), and the project [wiki](https://github.com/RhetTbull/osxphotos/wiki) to learn more about the project.
+
+If you want to contribute source code, I recommend you explore the [wiki](https://github.com/RhetTbull/osxphotos/wiki/Structure-of-the-code) to learn about the source structure first.
+
+See the [README.md](tests/README.md) in the tests directory before running any tests.
+
+## Code of Conduct
+
+Be nice to each other.  Treat everyone with dignity and respect.
+
+Abusive behavior of any kind will not be tolerated here.
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -2,4 +2,5 @@ include README.md
 include README.rst
 include osxphotos/templates/*
 include osxphotos/phototemplate.tx
-include osxphotos/phototemplate.md
+include osxphotos/phototemplate.md
+include osxphotos/queries/*
--- a/README.md
+++ b/README.md
@@ -3,8 +3,9 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![tests](https://github.com/RhetTbull/osxphotos/workflows/Tests/badge.svg)](https://github.com/RhetTbull/osxphotos/workflows/Tests/badge.svg)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/osxphotos)
+[![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)
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-23-orange.svg?style=flat)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-32-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.
@@ -36,6 +37,7 @@ OSXPhotos provides the ability to interact with and query Apple's Photos.app lib
  + [Raw Photos](#raw-photos)
  + [Template System](#template-system)
  + [ExifTool](#exiftoolExifTool)
+  + [Text Detection](#textdetection)
  + [Utility Functions](#utility-functions)
 * [Examples](#examples)
 * [Related Projects](#related-projects)
@@ -50,11 +52,13 @@ 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) until macOS Big Sur (10.16/11.1).
+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).
+

 | macOS Version     | macOS name | Photos.app version |
 | ----------------- |------------|:-------------------|
-| 10.16, 11.0-11.3  | Big Sur    | 6.0 ✅             |
+| 12.0              | 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 ✅             |
@@ -118,6 +122,7 @@ This package will install a command line utility called `osxphotos` that allows

 ```
 > osxphotos
+
 Usage: osxphotos [OPTIONS] COMMAND [ARGS]...

 Options:
@@ -134,18 +139,22 @@ Options:
  -h, --help                   Show this message and exit.

 Commands:
-  about     Print information about osxphotos including license.
-  albums    Print out albums found in the Photos library.
-  dump      Print list of all photos & associated info from the Photos...
-  export    Export photos from the Photos database.
-  help      Print help; for help on commands: help <command>.
-  info      Print out descriptive info of the Photos library database.
-  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.
-  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...
+  about      Print information about osxphotos including license.
+  albums     Print out albums found in the Photos library.
+  dump       Print list of all photos & associated info from the Photos...
+  export     Export photos from the Photos database.
+  help       Print help; for help on commands: help <command>.
+  info       Print out descriptive info of the Photos library database.
+  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.
+  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,...
+  tutorial   Display osxphotos tutorial.
+  uninstall  Uninstall Python packages from the osxphotos environment
 ```

 To get help on a specific command, use `osxphotos help <command_name>`
@@ -405,6 +414,12 @@ To export only photos contained in the album "Summer Vacation":

 `osxphotos export /path/to/export --album "Summer Vacation"`

+In Photos, it's possible to have multiple albums with the same name. In this case, osxphotos would export photos from all albums matching the value passed to `--album`.  If you wanted to export only one of the albums and this album is in a folder, the `--regex` option (short for "regular expression"), which does pattern matching, could be used with the `{folder_album}` template to match the specific album.  For example, if you had a "Summer Vacation" album inside the folder "2018" and also one with the same name inside the folder "2019", you could export just the album "2018/Summer Vacation" using this command:
+
+`osxphotos export /path/to/export --regex "2018/Summer Vacation" "{folder_album}"`
+
+This command matches the pattern "2018/Summer Vacation" against the full folder/album path for every photo.
+
 There are also a number of query options to export only certain types of photos.  For example, to export only photos taken with iPhone "Portrait Mode":

 `osxphotos export /path/to/export --portrait`
@@ -439,15 +454,15 @@ For example, to set Finder comment to the photo's title and description:

 In the template string above, `{newline}` instructs osxphotos to insert a new line character ("\n") between the title and description. In this example, if `{title}` or `{descr}` is empty, you'll get "title\n" or "\ndescription" which may not be desired so you can use more advanced features of the template system to handle these cases:

-`osxphotos export /path/to/export --xattr-template findercomment "{title}{title?{descr?{newline},},}{descr}"`
+`osxphotos export /path/to/export --xattr-template findercomment "{title,}{title?{descr?{newline},},}{descr,}"`

 Explanation of the template string:

 ```txt
-{title}{title?{descr?{newline},},}{descr}
+{title,}{title?{descr?{newline},},}{descr,}
 │           │      │ │       │ │  │ 
 │           │      │ │       │ │  │ 
- └──> insert title  │ │       │ │  │ 
+ └──> insert title (or nothing if no title) 
             │      │ │       │ │  │
             └───> is there a title?
                    │ │       │ │  │
@@ -459,7 +474,8 @@ Explanation of the template string:
                                │  │ 
                                └───> if title is blank, insert nothing
                                   │
-                                   └───> finally, insert description
+                                   └───> finally, insert description 
+                                         (or nothing if no description)
 ```

 In this example, `title?` demonstrates use of the boolean (True/False) feature of the template system.  `title?` is read as "Is the title True (or not blank/empty)?  If so, then the value immediately following the `?` is used in place of `title`.  If `title` is blank, then the value immediately following the comma is used instead.  The format for boolean fields is `field?value if true,value if false`.  Either `value if true` or `value if false` may be blank, in which case a blank string ("") is used for the value and both may also be an entirely new template string as seen in the above example.  Using this format, template strings may be nested inside each other to form complex `if-then-else` statements.
@@ -482,6 +498,40 @@ Then the next to you run osxphotos, you can simply do this:

 The configuration file is a plain text file in [TOML](https://toml.io/en/) format so the `.toml` extension is standard but you can name the file anything you like. 

+#### Run commands on exported photos for post-processing
+
+You can use the `--post-command` option to run one or more commands against exported files. The `--post-command` option takes two arguments: CATEGORY and COMMAND.  CATEGORY is a string that describes which category of file to run the command against.  The available categories are described in the help text available via: `osxphotos help export`. For example, the `exported` category includes all exported photos and the `skipped` category includes all photos that were skipped when running export with `--update`.  COMMAND is an osxphotos template string which will be rendered then passed to the shell for execution.  
+
+For example, the following command generates a log of all exported files and their associated keywords:
+
+`osxphotos export /path/to/export --post-command exported "echo {shell_quote,{filepath}{comma}{,+keyword,}} >> {shell_quote,{export_dir}/exported.txt}"`
+
+The special template field `{shell_quote}` ensures a string is properly quoted for execution in the shell.  For example, it's possible that a file path or keyword in this example has a space in the value and if not properly quoted, this would cause an error in the execution of the command. When running commands, the template `{filepath}` is set to the full path of the exported file and `{export_dir}` is set to the full path of the base export directory.  
+
+Explanation of the template string:
+
+```txt
+{shell_quote,{filepath}{comma}{,+keyword,}}
+ │            │         │      │        │
+ │            │         │      |        │
+ └──> quote everything after comma for proper execution in the shell
+              │         │      │        │
+              └───> filepath of the exported file
+                       │       │        │
+                       └───> insert a comma 
+                               │        │
+                               └───> join the list of keywords together with a ","
+                                        │
+                                        └───> if no keywords, insert nothing (empty string: "")
+```
+
+Another example: if you had `exiftool` installed and wanted to wipe all metadata from all exported files, you could use the following:
+
+`osxphotos export /path/to/export --post-command exported "/usr/local/bin/exiftool -all= {filepath|shell_quote}"`
+
+This command uses the `|shell_quote` template filter instead of the `{shell_quote}` template because the only thing that needs to be quoted is the path to the exported file. Template filters filter the value of the rendered template field.  A number of other filters are available and are described in the help text. 
+
+
 #### An example from an actual osxphotos user

 Here's a comprehensive use case from an actual osxphotos user that integrates many of the concepts discussed in this tutorial (thank-you Philippe for contributing this!):
@@ -576,6 +626,10 @@ Options:
                                  geolocation info
  --no-place                      Search for photos with no associated place
                                  name info (no reverse geolocation info)
+  --location                      Search for photos with associated location
+                                  info (e.g. GPS coordinates)
+  --no-location                   Search for photos with no associated location
+                                  info (e.g. no GPS coordinates)
  --label LABEL                   Search for photos with image classification
                                  label LABEL (Photos 5 only). If more than one
                                  label, treated as "OR", e.g. find photos
@@ -647,6 +701,14 @@ Options:
  --in-album                      Search for photos that are in one or more
                                  albums.
  --not-in-album                  Search for photos that are not in any albums.
+  --duplicate                     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 SIZE                 Search for photos with size >= SIZE bytes. The
                                  size evaluated is the photo's original size
                                  (when imported to Photos). Size may be
@@ -667,6 +729,17 @@ Options:
                                  --regex "^Beach" "{album}"'. You may specify
                                  more than one regular expression match by
                                  repeating '--regex' with different arguments.
+  --selected                      Filter for photos that are currently selected
+                                  in Photos.
+  --exif EXIF_TAG VALUE           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 CRITERIA           Evaluate CRITERIA to filter photos. CRITERIA
                                  will be evaluated in context of the following
                                  python list comprehension: `photos = [photo
@@ -681,6 +754,22 @@ Options:
                                  https://rhettbull.github.io/osxphotos/ for
                                  additional documentation on the PhotoInfo
                                  class.
+  --query-function filename.py::function
+                                  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/os
+                                  xphotos/blob/master/examples/query_function.py
+                                  for example of how to use this option.
  --missing                       Export only photos missing from the Photos
                                  library; must be used with --download-missing.
  --deleted                       Include photos from the 'Recently Deleted'
@@ -742,23 +831,48 @@ Options:
                                  the library if a photo is a burst photo.
  --skip-live                     Do not export the associated live video
                                  component of a live photo.
-  --skip-raw                      Do not export associated raw images of a
-                                  RAW+JPEG pair.  Note: this does not skip raw
-                                  photos if the raw photo does not have an
-                                  associated jpeg image (e.g. the raw file was
-                                  imported to Photos without a jpeg preview).
+  --skip-raw                      Do not export associated RAW image of a
+                                  RAW+JPEG pair.  Note: this does not skip RAW
+                                  photos if the RAW photo does not have an
+                                  associated JPEG image (e.g. the RAW file was
+                                  imported to Photos without a JPEG preview).
  --current-name                  Use photo's current filename instead of
                                  original filename for export.  Note: Starting
                                  with Photos 5, all photos are renamed upon
                                  import.  By default, photos are exported with
                                  the the original name they had before import.
-  --convert-to-jpeg               Convert all non-jpeg images (e.g. raw, HEIC,
-                                  PNG, etc) to JPEG upon export.  Only works if
-                                  your Mac has a GPU.
+  --convert-to-jpeg               Convert all non-JPEG images (e.g. RAW, HEIC,
+                                  PNG, etc) to JPEG upon export. Note: does not
+                                  convert the RAW component of a RAW+JPEG pair
+                                  as the associated JPEG image will be exported.
+                                  You can use --skip-raw to skip exporting the
+                                  associated RAW image of a RAW+JPEG pair. See
+                                  also --jpeg-quality and --jpeg-ext. Only works
+                                  if your Mac has a GPU (thus may not work on
+                                  virtual machines).
  --jpeg-quality FLOAT RANGE      Value in range 0.0 to 1.0 to use with
                                  --convert-to-jpeg. A value of 1.0 specifies
                                  best quality, a value of 0.0 specifies maximum
                                  compression. Defaults to 1.0  [0.0<=x<=1.0]
+  --preview                       Export preview image generated by Photos. This
+                                  is a lower-resolution image used by Photos to
+                                  quickly preview the image. See also --preview-
+                                  suffix and --preview-if-missing.
+  --preview-if-missing            Export preview image generated by Photos if
+                                  the actual photo file is missing from the
+                                  library. This may be helpful if photos were
+                                  not copied to the Photos library and the
+                                  original photo is missing. See also --preview-
+                                  suffix and --preview.
+  --preview-suffix SUFFIX         Optional suffix template for naming preview
+                                  photos.  Default name for preview photos is in
+                                  form 'photoname_preview.ext'. For example,
+                                  with '--preview-suffix _low_res', the preview
+                                  photo would be named 'photoname_low_res.ext'.
+                                  The default suffix is '_preview'. Multi-value
+                                  templates (see Templating System) are not
+                                  permitted with --preview-suffix. See also
+                                  --preview and --preview-if-missing.
  --download-missing              Attempt to download missing photos from
                                  iCloud. The current implementation uses
                                  Applescript to interact with Photos to export
@@ -901,8 +1015,10 @@ Options:
  --xattr-template ATTRIBUTE TEMPLATE
                                  Set extended attribute ATTRIBUTE to TEMPLATE
                                  value. Valid attributes are: 'authors',
-                                  'comment', 'copyright', 'description',
-                                  'findercomment', 'headline', 'keywords'. For
+                                  'comment', 'copyright', 'creator',
+                                  'description', 'findercomment', 'headline',
+                                  'keywords', 'participants', 'projects',
+                                  'rating', 'subject', 'title', 'version'. For
                                  example, to set Finder comment to the photo's
                                  title and description: '--xattr-template
                                  findercomment "{title}; {descr}" See Extended
@@ -1001,6 +1117,36 @@ Options:
                                  feature is currently experimental.  I don't
                                  know how well it will work on large export
                                  sets.
+  --post-command CATEGORY COMMAND
+                                  Run COMMAND on exported files of category
+                                  CATEGORY.  CATEGORY can be one of: exported,
+                                  new, updated, skipped, missing, exif_updated,
+                                  touched, converted_to_jpeg,
+                                  sidecar_json_written, sidecar_json_skipped,
+                                  sidecar_exiftool_written,
+                                  sidecar_exiftool_skipped, sidecar_xmp_written,
+                                  sidecar_xmp_skipped, error. COMMAND is an
+                                  osxphotos template string, for example: '--
+                                  post-command exported "echo
+                                  {filepath|shell_quote} >>
+                                  {export_dir}/exported.txt"', which appends the
+                                  full path of all exported files to the file
+                                  'exported.txt'. You can run more than one
+                                  command by repeating the '--post-command'
+                                  option with different arguments. See Post
+                                  Command below.
+  --post-function filename.py::function
+                                  Run function on exported files. Use this in
+                                  format: --post-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.
+                                  The function will be passed information about
+                                  the photo that's been exported and a list of
+                                  all exported files associated with the photo.
+                                  You can run more than one function by
+                                  repeating the '--post-function' option with
+                                  different arguments. See Post Function below.
  --exportdb EXPORTDB_FILE        Specify alternate name for database file which
                                  stores state information for export and
                                  --update. If --exportdb is not specified,
@@ -1082,6 +1228,9 @@ comment        A comment related to the file.  This differs from the Finder
               (com.apple.metadata:kMDItemComment)
 copyright      The copyright owner of the file contents.  A string.
               (com.apple.metadata:kMDItemCopyright)
+creator        Application used to create the document content (for example
+               “Word”, “Pages”, and so on).  A string.
+               (com.apple.metadata:kMDItemCreator)
 description    A description of the content of the resource.  The description
               may include an abstract, table of contents, reference to a
               graphical representation of content or a free-text account of
@@ -1095,6 +1244,23 @@ keywords       Keywords associated with this file. For example, “Birthday”,
               (_kMDItemUserTags) which are keywords/tags shown in the Finder
               and searchable in Spotlight using "tag:tag_name".  A list of
               strings. (com.apple.metadata:kMDItemKeywords)
+participants   The list of people who are visible in an image or movie or
+               written about in a document. A list of strings.
+               (com.apple.metadata:kMDItemParticipants)
+projects       The list of projects that this file is part of. For example, if
+               you were working on a movie all of the files could be marked as
+               belonging to the project “My Movie”. A list of strings.
+               (com.apple.metadata:kMDItemProjects)
+rating         User rating of this item. For example, the stars rating of an
+               iTunes track. An integer.
+               (com.apple.metadata:kMDItemStarRating)
+subject        Subject of the this item. A string.
+               (com.apple.metadata:kMDItemSubject)
+title          The title of the file. For example, this could be the title of
+               a document, the name of a song, or the subject of an email
+               message. A string. (com.apple.metadata:kMDItemTitle)
+version        The version number of this file. A string.
+               (com.apple.metadata:kMDItemVersion)

 For additional information on extended attributes see: https://developer.apple.c
 om/documentation/coreservices/file_metadata/mditem/common_metadata_attribute_key
@@ -1104,8 +1270,8 @@ s
 ** Templating System **

 The templating system converts one or template statements, written in osxphotos 
-templating language, to one or more rendered values using information from the  
-photo being processed.                                                          
+metadata templating language, to one or more rendered values using information  
+from the photo being processed.                                                 

 In its simplest form, a template statement has the form: "{template_field}", for
 example "{title}" which would resolve to the title of the photo.                
@@ -1158,6 +1324,8 @@ Valid filters are:
 • braces: Enclose value in curly braces, e.g. 'value => '{value}'.             
 • parens: Enclose value in parentheses, e.g. 'value' => '(value')              
 • brackets: Enclose value in brackets, e.g. 'value' => '[value]'               
+ • shell_quote: Quotes the value for safe usage in the shell, e.g. My file.jpeg 
+   => 'My file.jpeg'; only adds quotes if needed.                               
 • function: Run custom python function to filter value; use in format          
   'function:/path/to/file.py::function_name'. See example at https://github.com
   /RhetTbull/osxphotos/blob/master/examples/template_filter.py                 
@@ -1483,6 +1651,55 @@ Substitution                    Description
                                (UUID) for the photo, a 36-character string
                                unique to the photo, e.g.
                                '128FB4C6-0B16-4E7D-9108-FB2E90DA1546'
+{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.
+{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 a period and the 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.
+                                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
+                                append a period and the 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. 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: ','
 {semicolon}                     A semicolon: ';'
 {questionmark}                  A question mark: '?'
@@ -1497,7 +1714,7 @@ Substitution                    Description
 {lf}                            A line feed: '\n', alias for {newline}
 {cr}                            A carriage return: '\r'
 {crlf}                          a carriage return + line feed: '\r\n'
-{osxphotos_version}             The osxphotos version, e.g. '0.42.26'
+{osxphotos_version}             The osxphotos version, e.g. '0.43.8'
 {osxphotos_cmd_line}            The full command line used to run osxphotos

 The following substitutions may result in multiple values. Thus if specified for
@@ -1556,6 +1773,26 @@ Substitution             Description
                         underlying PhotoInfo class.  See
                         https://rhettbull.github.io/osxphotos/ for additional
                         documentation on the PhotoInfo class.
+{detected_text}          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.
+{shell_quote}            Use in form '{shell_quote,TEMPLATE}'; quotes the
+                         rendered TEMPLATE value(s) for safe usage in the
+                         shell, e.g. My file.jpeg => 'My file.jpeg'; only adds
+                         quotes if needed.
+{strip}                  Use in form '{strip,TEMPLATE}'; strips whitespace
+                         from begining and end of rendered TEMPLATE value(s).
 {function}               Execute a python function from an external file and
                         use return value as template substitution. Use in
                         format: {function:file.py::function_name} where
@@ -1566,6 +1803,103 @@ Substitution             Description
                         /blob/master/examples/template_function.py for an
                         example of how to implement a template function.

+The following substitutions are file or directory paths. You can access various
+parts of the path using the following modifiers:
+
+{path.parent}: the parent directory
+{path.name}: the name of the file or final sub-directory
+{path.stem}: the name of the file without the extension
+{path.suffix}: the suffix of the file including the leading '.'
+
+For example, if the field {export_dir} is '/Shared/Backup/Photos':
+{export_dir.parent} is '/Shared/Backup'
+
+If the field {filepath} is '/Shared/Backup/Photos/IMG_1234.JPG':
+{filepath.parent} is '/Shared/Backup/Photos'
+{filepath.name} is 'IMG_1234.JPG'
+{filepath.stem} is 'IMG_1234'
+{filepath.suffix} is '.JPG'
+
+Substitution  Description
+{export_dir}  The full path to the export directory
+{filepath}    The full path to the exported file
+
+
+** Post Command **
+You can run commands on the exported photos for post-processing using the '--
+post-command' option. '--post-command' is passed a CATEGORY and a COMMAND.
+COMMAND is an osxphotos template string which will be rendered and passed to the
+shell for execution. CATEGORY is the category of file to pass to COMMAND. The
+following categories are available:
+
+Category                  Description
+exported                  All exported files
+new                       When used with '--update', all newly exported files
+updated                   When used with '--update', all files which were
+                          previously exported but updated this time
+skipped                   When used with '--update', all files which were
+                          skipped (because they were previously exported and
+                          didn't change)
+missing                   All files which were not exported because they were
+                          missing from the Photos library
+exif_updated              When used with '--exiftool', all files on which
+                          exiftool updated the metadata
+touched                   When used with '--touch-file', all files where the
+                          date was touched
+converted_to_jpeg         When used with '--convert-to-jpeg', all files which
+                          were converted to jpeg
+sidecar_json_written      When used with '--sidecar json', all JSON sidecar
+                          files which were written
+sidecar_json_skipped      When used with '--sidecar json' and '--update', all
+                          JSON sidecar files which were skipped
+sidecar_exiftool_written  When used with '--sidecar exiftool', all exiftool
+                          sidecar files which were written
+sidecar_exiftool_skipped  When used with '--sidecar exiftool' and '--update,
+                          all exiftool sidecar files which were skipped
+sidecar_xmp_written       When used with '--sidecar xmp', all XMP sidecar
+                          files which were written
+sidecar_xmp_skipped       When used with '--sidecar xmp' and '--update', all
+                          XMP sidecar files which were skipped
+error                     All files which produced an error during export
+
+In addition to all normal template fields, the template fields '{filepath}' and
+'{export_dir}' will be available to your command template. Both of these are
+path-type templates which means their various parts can be accessed using the
+available properties, e.g. '{filepath.name}' provides just the file name without
+path and '{filepath.suffix}' is the file extension (suffix) of the file. When
+using paths in your command template, it is important to properly quote the
+paths as they will be passed to the shell and path names may contain spaces.
+Both the '{shell_quote}' template and the '|shell_quote' template filter are
+available for this purpose.  For example, the following command outputs the full
+path of newly exported files to file 'new.txt':
+
+--post-command new "echo {filepath|shell_quote} >> {shell_quote,{export_dir}/exported.txt}"
+
+In the above command, the 'shell_quote' filter is used to ensure '{filepath}' is
+properly quoted and the '{shell_quote}' template ensures the constructed path of
+'{exported_dir}/exported.txt' is properly quoted. If '{filepath}' is 'IMG
+1234.jpeg' and '{export_dir}' is '/Volumes/Photo Export', the command thus
+renders to:
+
+echo 'IMG 1234.jpeg' >> '/Volumes/Photo Export/exported.txt'
+
+It is highly recommended that you run osxphotos with '--dry-run --verbose' first
+to ensure your commands are as expected. This will not actually run the commands
+but will print out the exact command string which would be executed.
+
+
+** Post Function **
+You can run your own python functions on the exported photos for post-processing
+using the '--post-function' option. '--post-function' is passed the name a
+python file and the name of the function in the file to call using format
+'filename.py::function_name'. See the example function at
+https://github.com/RhetTbull/osxphotos/blob/master/examples/post_function.py You
+may specify multiple functions to run by repeating the --post-function option.
+All post functions will be called immediately after export of each photo and
+immediately before any --post-command commands. Post functions will not be
+called if the --dry-run flag is set.
+
+

 ```
 <!-- OSXPHOTOS-EXPORT-USAGE:END -->
@@ -2051,6 +2385,8 @@ For example, in my library, Photos says I have 19,386 photos and 474 movies.  Ho
 #### <a name="getphoto">`get_photo(uuid)`</A>
 Returns a single PhotoInfo instance for photo with UUID matching `uuid` or None if no photo is found matching `uuid`.  If you know the UUID of a photo, `get_photo()` is much faster than `photos`.  See also [photos()](#photos).

+#### `execute(sql)`
+Execute sql statement against the Photos database and return a sqlite cursor with the results.

 ### PhotoInfo 
 PhotosDB.photos() returns a list of PhotoInfo objects.  Each PhotoInfo object represents a single photo in the Photos library.
@@ -2109,7 +2445,7 @@ Returns the absolute path to the edited photo on disk as a string.  If the photo
 **Note**: will also return None if the edited photo is missing on disk. 

 #### `path_derivatives`
-Returns list of paths to any derivative preview images associated with the photo. The list of returned paths is sorted in descieding order by size (the largest, presumably highest quality) preview image will be the first element in the returned list. These will be named something like this on Photos 5+: 
+Returns list of paths to any derivative preview images associated with the photo. The list of returned paths is sorted in descending order by size (the largest, presumably highest quality) preview image will be the first element in the returned list. These will be named something like this on Photos 5+: 

 - `F19E06B8-A712-4B5C-907A-C007D37BDA16_1_101_o.jpeg`
 - `F19E06B8-A712-4B5C-907A-C007D37BDA16_1_102_o.jpeg`
@@ -2194,7 +2530,12 @@ Returns a [PlaceInfo](#PlaceInfo) object with reverse geolocation data or None i
 #### `shared`
 Returns True if photo is in a shared album, otherwise False.

-**Note**: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns None instead of True/False.
+**Note**: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns None.
+
+#### `owner`
+Returns full name of the photo owner (person who shared the photo) for shared photos or None if photo is not shared. Also returns None if you are the person who shared the photo.
+
+**Note**: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns None.

 #### `comments`
 Returns list of [CommentInfo](#commentinfo) objects for comments on shared photos or empty list if no comments.
@@ -2287,6 +2628,9 @@ Returns the path to the live video component of a [live photo](#live_photo). If

 **Note**: will also return None if the live video component is missing on disk. It's possible that the original photo may be on disk ([ismissing](#ismissing)==False) but the video component is missing, likely because it has not been downloaded from iCloud.

+#### `path_edited_live_photo`
+Returns the path to the edited live video component of an edited [live photo](#live_photo). If photo is not a live photo or not edited, returns None.
+
 #### `portrait`
 Returns True if photo was taken in iPhone portrait mode, otherwise False.

@@ -2388,6 +2732,9 @@ Returns a [ScoreInfo](#scoreinfo) data class object which provides access to the

 **Note**: Valid only for Photos 5; returns None for earlier Photos versions.

+#### `duplicates`
+Returns list of PhotoInfo objects for *possible* duplicates or empty list if no matching duplicates.  Photos are considered possible duplicates if the photo's original file size, date created, height, and width match another those of another photo.  This does not do a byte-for-byte comparison or compute a hash which makes it fast and allows for identification of possible duplicates even if originals are not downloaded from iCloud.  The signature-based approach should be robust enough to match duplicates created either through the "duplicate photo" menu item or imported twice into the library but you should not rely on this 100% for identification of all duplicates.
+
 #### `json()`
 Returns a JSON representation of all photo info.

@@ -2395,11 +2742,11 @@ Returns a JSON representation of all photo info.
 Returns a dictionary representation of all photo info.

 #### `export()`
-`export(dest, *filename, edited=False, live_photo=False, export_as_hardlink=False, overwrite=False, increment=True, sidecar_json=False, sidecar_exiftool=False, sidecar_xmp=False, use_photos_export=False, timeout=120, exiftool=False, use_albums_as_keywords=False, use_persons_as_keywords=False)`
+`export(dest, filename=None, edited=False, live_photo=False, export_as_hardlink=False, overwrite=False, increment=True, sidecar_json=False, sidecar_exiftool=False, sidecar_xmp=False, use_photos_export=False, timeout=120, exiftool=False, use_albums_as_keywords=False, use_persons_as_keywords=False)`

 Export photo from the Photos library to another destination on disk.  
 - dest: must be valid destination path as str (or exception raised).
- *filename (optional): name of picture as str; if not provided, will use current filename.  **NOTE**: if provided, user must ensure file extension (suffix) is correct. For example, if photo is .CR2 file, edited image may be .jpeg.  If you provide an extension different than what the actual file is, export will print a warning but will happily export the photo using the incorrect file extension.  e.g. to get the extension of the edited photo, look at [PhotoInfo.path_edited](#path_edited).
+- filename (optional): name of picture as str; if not provided, will use current filename.  **NOTE**: if provided, user must ensure file extension (suffix) is correct. For example, if photo is .CR2 file, edited image may be .jpeg.  If you provide an extension different than what the actual file is, export will print a warning but will happily export the photo using the incorrect file extension.  e.g. to get the extension of the edited photo, look at [PhotoInfo.path_edited](#path_edited).
 - edited: boolean; if True (default=False), will export the edited version of the photo (or raise exception if no edited version)
 - export_as_hardlink: boolean; if True (default=False), will hardlink files instead of copying them
 - overwrite: boolean; if True (default=False), will overwrite files if they alreay exist
@@ -2434,29 +2781,51 @@ Then
 If overwrite=False and increment=False, export will fail if destination file already exists


-#### <a name="rendertemplate">`render_template()`</a>
-
-`render_template(template_str, none_str = "_", path_sep = None, expand_inplace = False, inplace_sep = None, filename=False, dirname=False, strip=False)`
+#### <a name="rendertemplate">`render_template(template_str, options=None)`</a>

 Render template string for photo.  none_str is used if template substitution results in None value and no default specified.

- `template_str`: str in osxphotos template language (OTL) format. See also [Template System](#template-system) table. See notes below regarding specific details of the syntax.
- `none_str`: optional str to use as substitution when template value is None and no default specified in the template string.  default is "_".
- `path_sep`: optional character to use as path separator when joining path like fields such as `{folder_album}`; default is `os.path.sep`.  May also be provided in the template itself. If provided both in the call to `render_template()` and in the template itself, the value in the template string takes precedence.
- `expand_inplace`: expand multi-valued substitutions in-place as a single string instead of returning individual strings
- `inplace_sep`: optional string to use as separator between multi-valued keywords with expand_inplace; default is ','
- `filename`: if True, template output will be sanitized to produce valid file name
- `dirname`: if True, template output will be sanitized to produce valid directory name
- `strip`: if True, leading/trailign whitespace will be stripped from rendered template strings
+- `template_str`: str in metadata template language (MTL) format. See also [Template System](#template-system) table. See notes below regarding specific details of the syntax.
+- `options`: an optional osxphotos.phototemplate.RenderOptions object specifying the options to pass to the rendering engine.
+
+`RenderOptions` has the following properties:
+
+- template: str template
+- none_str: str to use default for None values, default is '_'
+- path_sep: optional string to use as path separator, default is os.path.sep
+- expand_inplace: expand multi-valued substitutions in-place as a single string instead of returning individual strings
+- inplace_sep: optional string to use as separator between multi-valued keywords with expand_inplace; default is ','
+- filename: if True, template output will be sanitized to produce valid file name
+- dirname: if True, template output will be sanitized to produce valid directory name
+- strip: if True, strips leading/trailing whitespace from rendered templates
+- edited_version: set to True if you want {edited_version} to resolve to True (e.g. exporting edited version of photo)
+- export_dir: set to the export directory if you want to evalute {export_dir} template
+- filepath: set to value for filepath of the exported photo if you want to evaluate {filepath} template
+- quote: quote path templates for execution in the shell

 Returns a tuple of (rendered, unmatched) where rendered is a list of rendered strings with all substitutions made and unmatched is a list of any strings that resembled a template substitution but did not match a known substitution. E.g. if template contained "{foo}", unmatched would be ["foo"].  If there are unmatched strings, rendered will be [].  E.g. a template statement must fully match or will result in error and return all unmatched fields in unmatched.

-e.g. `render_template("{created.year}/{foo}", photo)` would return `([],["foo"])`
+e.g. `photo.render_template("{created.year}/{foo}")` would return `([],["foo"])`

 Some substitutions, notably `album`, `keyword`, and `person` could return multiple values, hence a new string will be return for each possible substitution (hence why a list of rendered strings is returned).  For example, a photo in 2 albums: 'Vacation' and 'Family' would result in the following rendered values if template was "{created.year}/{album}" and created.year == 2020: `["2020/Vacation","2020/Family"]` 

 See [Template System](#template-system) for additional details.

+
+#### <a name="detected_text_method">`detected_text(confidence_threshold=TEXT_DETECTION_CONFIDENCE_THRESHOLD)`</a>
+
+Detects text in photo and returns lists of results as (detected text, confidence)
+
+- `confidence_threshold`: float between 0.0 and 1.0. If text detection confidence is below this threshold, text will not be returned. Default is `osxphotos._constants.TEXT_DETECTION_CONFIDENCE_THRESHOLD`
+
+If photo is edited, uses the edited photo, otherwise the original; falls back to the preview image if neither edited or original is available.
+
+Returns: list of (detected text, confidence) tuples.
+
+Note: This is *not* the same as Live Text in macOS Monterey.  When using `detected_text()`, osxphotos will use Apple's [Vision framework](https://developer.apple.com/documentation/vision/recognizing_text_in_images?language=objc) to perform text detection on the image.  On my circa 2013 MacBook Pro, this takes about 2 seconds per image.  `detected_text()` does memoize the results for a given `confidence_threshold` so repeated calls will not re-process the photo.  This works only on macOS Catalina (10.15) or later.
+
+See also [Text Detection](#textdetection).
+
 ### ExifInfo
 [PhotosInfo.exif_info](#exif-info) returns an `ExifInfo` object with some EXIF data about the photo (Photos 5 only).  `ExifInfo` contains the following properties:

@@ -2540,6 +2909,11 @@ Photos Library
 #### `parent`
 Returns a [FolderInfo](#FolderInfo) object representing the albums parent folder or `None` if album is not a in a folder.

+#### `owner`
+Returns full name of the album owner (person who shared the album) for shared albums or None if album is not shared.
+
+**Note**: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns None.
+
 ### ImportInfo 
 PhotosDB.import_info returns a list of ImportInfo objects.  Each ImportInfo object represents an import session in the library.  PhotoInfo.import_info returns a single ImportInfo object representing the import session for the photo (or `None` if no associated import session).

@@ -2583,8 +2957,24 @@ Returns a list of [FolderInfo](#FolderInfo) objects representing the sub-folders
 #### `parent`
 Returns a [FolderInfo](#FolderInfo) object representing the folder's parent folder or `None` if album is not a in a folder.

+#### `sort_order`
+Returns album sort order (as `AlbumSortOrder` enum).  On Photos <=4, always returns `AlbumSortOrder.MANUAL`.
+
+`AlbumSortOrder` has following values:
+
+- `UNKNOWN`
+- `MANUAL`
+- `NEWEST_FIRST`
+- `OLDEST_FIRST`
+- `TITLE`
+
+#### `photo_index(photo)`
+Returns index of photo in album (based on album sort order).
+
+
 **Note**: FolderInfo and AlbumInfo objects effectively work as a linked list.  The children of a folder are contained in `subfolders` and `album_info` and the parent object of both `AlbumInfo` and `FolderInfo` is represented by `parent`.  For example:

+
 ```pycon
 >>> import osxphotos
 >>> photosdb = osxphotos.PhotosDB()
@@ -2891,7 +3281,6 @@ The following additional properties are also available but are not yet fully doc
 - `manual`: 
 - `face_type`:
 - `age_type`:
- `bald_type`:
 - `eye_makeup_type`:
 - `eye_state`:
 - `facial_hair_type`:
@@ -2974,7 +3363,7 @@ To get the path of every raw photo, whether it's a single raw photo or a raw+JPE
 ### Template System 

 <!-- OSXPHOTOS-TEMPLATE-HELP:START - Do not remove or modify this section -->
-The templating system converts one or template statements, written in osxphotos templating language, to one or more rendered values using information from the photo being processed. 
+The templating system converts one or template statements, written in osxphotos metadata templating language, to one or more rendered values using information from the photo being processed. 

 In its simplest form, a template statement has the form: `"{template_field}"`, for example `"{title}"` which would resolve to the title of the photo.

@@ -3015,6 +3404,7 @@ Valid filters are:
 - braces: Enclose value in curly braces, e.g. 'value => '{value}'.
 - parens: Enclose value in parentheses, e.g. 'value' => '(value')
 - brackets: Enclose value in brackets, e.g. 'value' => '[value]'
+- shell_quote: Quotes the value for safe usage in the shell, e.g. My file.jpeg => 'My file.jpeg'; only adds quotes if needed.
 - function: Run custom python function to filter value; use in format 'function:/path/to/file.py::function_name'. See example at https://github.com/RhetTbull/osxphotos/blob/master/examples/template_filter.py
 <!-- OSXPHOTOS-FILTER-TABLE:END -->

@@ -3177,6 +3567,9 @@ The following template field substitutions are availabe for use the templating s
 |{exif.camera_model}|Camera model from original photo's EXIF information as imported by Photos, e.g. 'iPhone 6s'|
 |{exif.lens_model}|Lens model from original photo's EXIF information as imported by Photos, e.g. 'iPhone 6s back camera 4.15mm f/2.2'|
 |{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'|
+|{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. |
+|{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 a period and the 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. 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 append a period and the 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. 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: ','|
 |{semicolon}|A semicolon: ';'|
 |{questionmark}|A question mark: '?'|
@@ -3191,7 +3584,7 @@ The following template field substitutions are availabe for use the templating s
 |{lf}|A line feed: '\n', alias for {newline}|
 |{cr}|A carriage return: '\r'|
 |{crlf}|a carriage return + line feed: '\r\n'|
-|{osxphotos_version}|The osxphotos version, e.g. '0.42.26'|
+|{osxphotos_version}|The osxphotos version, e.g. '0.43.8'|
 |{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|
@@ -3206,6 +3599,9 @@ The following template field substitutions are availabe for use the templating s
 |{searchinfo.venue}|Venues associated with a photo, e.g. name of restaurant; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).|
 |{searchinfo.venue_type}|Venue types associated with a photo, e.g. 'Restaurant'; (Photos 5+ only, applied automatically by Photos' image categorization algorithms).|
 |{photo}|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 https://rhettbull.github.io/osxphotos/ for additional documentation on the PhotoInfo class.|
+|{detected_text}|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.|
+|{shell_quote}|Use in form '{shell_quote,TEMPLATE}'; quotes the rendered TEMPLATE value(s) for safe usage in the shell, e.g. My file.jpeg => 'My file.jpeg'; only adds quotes if needed.|
+|{strip}|Use in form '{strip,TEMPLATE}'; strips whitespace from begining and end of rendered TEMPLATE value(s).|
 |{function}|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.|
 <!-- OSXPHOTOS-TEMPLATE-TABLE:END -->

@@ -3269,6 +3665,14 @@ osxphotos.exiftool also provides an `ExifToolCaching` class which caches all met

 `ExifTool()` runs `exiftool` as a subprocess using the `-stay_open True` flag to keep the process running in the background.  The subprocess will be cleaned up when your main script terminates.  `ExifTool()` uses a singleton pattern to ensure that only one instance of `exiftool` is created.  Multiple instances of `ExifTool()` will all use the same `exiftool` subprocess.

+### <a name="textdetection">Text Detection</a>
+
+The [PhotoInfo.detected_text()](#detected_text_method) and the `{detected_text}` template will perform text detection on the photos in your library. Text detection is a slow process so to avoid unnecessary re-processing of photos, osxphotos will cache the results of the text detection process as an extended attribute on the photo image file.  Extended attributes do not modify the actual file.  The extended attribute is named `osxphotos.metadata:detected_text` and can be viewed using the built-in [xattr](https://ss64.com/osx/xattr.html) command or my [osxmetadata](https://github.com/RhetTbull/osxmetadata) tool.  If you want to remove the cached attribute, you can do so with osxmetadata as follows:
+
+`osxmetadata --clear osxphotos.metadata:detected_text --walk ~/Pictures/Photos\ Library.photoslibrary/`
+
+
+
 ### Utility Functions

 The following functions are located in osxphotos.utils
@@ -3285,13 +3689,6 @@ Returns path to last opened Photo Library as string.

 Returns list of Photos libraries found on the system.  **Note**: On MacOS 10.15, this appears to list all libraries. On older systems, it may not find some libraries if they are not located in ~/Pictures.  Provided for convenience but do not rely on this to find all libraries on the system.

-#### `dd_to_dms_str(lat, lon)`
-Convert latitude, longitude in degrees to degrees, minutes, seconds as string.
- `lat`: latitude in degrees
- `lon`: longitude in degrees
-returns: string tuple in format ("51 deg 30' 12.86\\" N", "0 deg 7' 54.50\\" W")
-This is the same format used by exiftool's json format.
-

 ## Examples

@@ -3347,15 +3744,10 @@ if __name__ == "__main__":

 ## Related Projects

- [rhettbull/photosmeta](https://github.com/rhettbull/photosmeta): uses osxphotos and [exiftool](https://exiftool.org/) to apply metadata from Photos as exif data in the photo files.  Can also export photos while preserving metadata and also apply Photos keywords as spotlight tags to make it easier to search for photos using spotlight.  This is mostly made obsolete by osxphotos.  The one feature that photosmeta has that osxphotos does not is ability to update the metadata of the actual photo files in the Photos library without exporting them. (Use with caution!)
+- [rhettbull/exif2findertags](https://github.com/RhetTbull/exif2findertags): Read EXIF metadata from image and video files and convert it to macOS Finder tags and/or Finder comments and other extended attributes.
+- [rhettbull/photos_time_warp](https://github.com/RhetTbull/photos_time_warp): Batch adjust the date, time, or timezone of photos in Apple Photos. 
 - [rhettbull/PhotoScript](https://github.com/RhetTbull/PhotoScript): python wrapper around Photos' applescript API allowing automation of Photos (including creation/deletion of items) from python.
- [patrikhson/photo-export](https://github.com/patrikhson/photo-export): Exports older versions of Photos databases.  Provided the inspiration for osxphotos.
- [doersino/apple-photos-export](https://github.com/doersino/apple-photos-export): Photos export script for Mojave.
- [orangeturtle739/photos-export](https://github.com/orangeturtle739/photos-export): Set of scripts to export Photos libraries.
- [ndbroadbent/icloud_photos_downloader](https://github.com/ndbroadbent/icloud_photos_downloader): Download photos from iCloud.  Currently unmaintained.
- [AaronVanGeffen/ExportPhotosLibrary](https://github.com/AaronVanGeffen/ExportPhotosLibrary): Another python script for exporting older versions of Photos libraries.
- [MossieurPropre/PhotosAlbumExporter](https://github.com/MossieurPropre/PhotosAlbumExporter): Javascript script to export photos while maintaining album structure.
- [ajslater/magritte](https://github.com/ajslater/magritte): Another python command line script for exporting photos from older versions of Photos libraries.
+- [ndbroadbent/icloud_photos_downloader](https://github.com/ndbroadbent/icloud_photos_downloader): Download photos from iCloud. 

 ## Contributing

@@ -3406,6 +3798,17 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
  <tr>
    <td align="center"><a href="http://blog.dewost.com/"><img src="https://avatars.githubusercontent.com/u/17090228?v=4?s=75" width="75px;" alt=""/><br /><sub><b>Philippe Dewost</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/commits?author=pdewost" title="Documentation">📖</a> <a href="#example-pdewost" title="Examples">💡</a> <a href="#ideas-pdewost" title="Ideas, Planning, & Feedback">🤔</a></td>
    <td align="center"><a href="https://github.com/kaduskj"><img src="https://avatars.githubusercontent.com/u/983067?v=4?s=75" width="75px;" alt=""/><br /><sub><b>kaduskj</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Akaduskj" title="Bug reports">🐛</a></td>
+    <td align="center"><a href="https://github.com/mkirkland4874"><img src="https://avatars.githubusercontent.com/u/36466711?v=4?s=75" width="75px;" alt=""/><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"><a href="https://github.com/jcommisso07"><img src="https://avatars.githubusercontent.com/u/3111054?v=4?s=75" width="75px;" alt=""/><br /><sub><b>Joseph Commisso</b></sub></a><br /><a href="#data-jcommisso07" title="Data">🔣</a></td>
+    <td align="center"><a href="https://github.com/dssinger"><img src="https://avatars.githubusercontent.com/u/1817903?v=4?s=75" width="75px;" alt=""/><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"><a href="https://github.com/oPromessa"><img src="https://avatars.githubusercontent.com/u/21261491?v=4?s=75" width="75px;" alt=""/><br /><sub><b>oPromessa</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3AoPromessa" title="Bug reports">🐛</a></td>
+    <td align="center"><a href="http://spencerchang.me"><img src="https://avatars.githubusercontent.com/u/14796580?v=4?s=75" width="75px;" alt=""/><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>
+    <td align="center"><a href="https://www.cs.purdue.edu/homes/dgleich"><img src="https://avatars.githubusercontent.com/u/33995?v=4?s=75" width="75px;" alt=""/><br /><sub><b>David Gleich</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/commits?author=dgleich" title="Code">💻</a></td>
+    <td align="center"><a href="https://alandefreitas.github.io/alandefreitas/"><img src="https://avatars.githubusercontent.com/u/5369819?v=4?s=75" width="75px;" alt=""/><br /><sub><b>Alan de Freitas</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Aalandefreitas" title="Bug reports">🐛</a></td>
+    <td align="center"><a href="https://hyfen.net"><img src="https://avatars.githubusercontent.com/u/6291?v=4?s=75" width="75px;" alt=""/><br /><sub><b>Andrew Louis</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/commits?author=hyfen" title="Documentation">📖</a> <a href="https://github.com/RhetTbull/osxphotos/commits?author=hyfen" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/neebah"><img src="https://avatars.githubusercontent.com/u/71442026?v=4?s=75" width="75px;" alt=""/><br /><sub><b>neebah</b></sub></a><br /><a href="https://github.com/RhetTbull/osxphotos/issues?q=author%3Aneebah" title="Bug reports">🐛</a></td>
  </tr>
 </table>

@@ -3446,6 +3849,9 @@ For additional details about how osxphotos is implemented or if you would like t
 - [Rich](https://github.com/willmcgugan/rich)
 - [textx](https://github.com/textX/textX)
 - [bitmath](https://github.com/tbielawa/bitmath)
+- [more-itertools](https://github.com/more-itertools/more-itertools)
+- [ptpython](https://github.com/prompt-toolkit/ptpython)
+- [objexplore](https://github.com/kylepollina/objexplore)


 ## Acknowledgements
--- a/README.rst
+++ b/README.rst
@@ -16,8 +16,9 @@ You can also easily export both the original and edited photos.
 Supported operating systems
 ---------------------------

-Only works on macOS (aka Mac OS X). Tested on macOS Sierra (10.12.6) until macOS Catalina (10.15.7). 
-Beta support for macOS Big Sur (10.16.01/11.01).
+Only works on macOS (aka Mac OS X). Tested on macOS Sierra (10.12.6) through macOS Big Sur (11.3).
+
+If you have access to macOS 12 / Monterey beta and would like to help ensure osxphotos is compatible, please contact me via GitHub.

 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.
@@ -109,6 +110,8 @@ Alternatively, you can also run the command line utility like this: ``python3 -m
     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 shell
+     tutorial  Display osxphotos tutorial.

 To get help on a specific command, use ``osxphotos help <command_name>``

--- a/build.sh
+++ b/build.sh
@@ -3,9 +3,10 @@
 # script to help build osxphotos release
 # this is unique to my own dev setup

-activate osxphotos
+# source venv/bin/activate
 rm -rf dist; rm -rf build
 python3 utils/update_readme.py
 (cd docsrc && make github && make pdf)
-python3 setup.py sdist bdist_wheel
-./make_cli_exe.sh
+# python3 setup.py sdist bdist_wheel
+python3 -m build
+./make_cli_exe.sh
--- a/dev_requirements.txt
+++ b/dev_requirements.txt
@@ -0,0 +1,10 @@
+build
+m2r2
+pyinstaller==4.4
+pytest-mock
+pytest==6.2.4
+sphinx_click
+sphinx_rtd_theme
+twine
+wheel
+Sphinx
--- a/docs/.buildinfo
+++ b/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: 210ecd9d654dea5d4c21627449ca1d63
+config: 72fd70158d2f5a08b80c8c23b4740046
 tags: 645f666f9bcd5a90fca523b33c5a78b7
--- a/docs/_modules/index.html
+++ b/docs/_modules/index.html
@@ -5,10 +5,10 @@
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Overview: module code &#8212; osxphotos 0.42.20 documentation</title>
-    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
-    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
-    <script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+    <title>Overview: module code &#8212; osxphotos 0.43.8 documentation</title>
+    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="../_static/alabaster.css" />
+    <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/doctools.js"></script>
@@ -31,7 +31,11 @@
          <div class="body" role="main">
            
  <h1>All modules for which code is available</h1>
-<ul><li><a href="osxphotos/photoinfo/photoinfo.html">osxphotos.photoinfo.photoinfo</a></li>
+<ul><li><a href="osxphotos/photoinfo/_photoinfo_exifinfo.html">osxphotos.photoinfo._photoinfo_exifinfo</a></li>
+<li><a href="osxphotos/photoinfo/_photoinfo_export.html">osxphotos.photoinfo._photoinfo_export</a></li>
+<li><a href="osxphotos/photoinfo/_photoinfo_scoreinfo.html">osxphotos.photoinfo._photoinfo_scoreinfo</a></li>
+<li><a href="osxphotos/photoinfo/_photoinfo_searchinfo.html">osxphotos.photoinfo._photoinfo_searchinfo</a></li>
+<li><a href="osxphotos/photoinfo/photoinfo.html">osxphotos.photoinfo.photoinfo</a></li>
 <li><a href="osxphotos/photosdb/photosdb.html">osxphotos.photosdb.photosdb</a></li>
 </ul>

@@ -67,7 +71,7 @@
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
-      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
@@ -89,7 +93,7 @@
      &copy;2021, Rhet Turnbull.
      
      |
-      Powered by <a href="http://sphinx-doc.org/">Sphinx 3.5.2</a>
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 4.3.2</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
    </div>
--- a/docs/_modules/osxphotos/photoinfo/_photoinfo_export.html
+++ b/docs/_modules/osxphotos/photoinfo/_photoinfo_export.html
--- a/docs/_modules/osxphotos/photoinfo/photoinfo.html
+++ b/docs/_modules/osxphotos/photoinfo/photoinfo.html
--- a/docs/_modules/osxphotos/photosdb/photosdb.html
+++ b/docs/_modules/osxphotos/photosdb/photosdb.html
@@ -5,10 +5,10 @@
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>osxphotos.photosdb.photosdb &#8212; osxphotos 0.42.19 documentation</title>
-    <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
-    <link rel="stylesheet" href="../../../_static/alabaster.css" type="text/css" />
-    <script id="documentation_options" data-url_root="../../../" src="../../../_static/documentation_options.js"></script>
+    <title>osxphotos.photosdb.photosdb &#8212; osxphotos 0.43.8 documentation</title>
+    <link rel="stylesheet" type="text/css" href="../../../_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css" />
+    <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/doctools.js"></script>
@@ -44,11 +44,15 @@
 <span class="kn">import</span> <span class="nn">re</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">pprint</span> <span class="kn">import</span> <span class="n">pformat</span>
 <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">List</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>
    <span class="n">_DB_TABLE_NAMES</span><span class="p">,</span>
@@ -76,6 +80,7 @@
 <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>
+<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">..queryoptions</span> <span class="kn">import</span> <span class="n">QueryOptions</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>
@@ -95,29 +100,29 @@


 <div class="viewcode-block" id="PhotosDB"><a class="viewcode-back" href="../../../reference.html#osxphotos.PhotosDB">[docs]</a><span class="k">class</span> <span class="nc">PhotosDB</span><span class="p">:</span>
-    <span class="sd">&quot;&quot;&quot; Processes a Photos.app library database to extract information about photos &quot;&quot;&quot;</span>
+    <span class="sd">&quot;&quot;&quot;Processes a Photos.app library database to extract information about photos&quot;&quot;&quot;</span>

    <span class="c1"># import additional methods</span>
+    <span class="kn">from</span> <span class="nn">._photosdb_process_comments</span> <span class="kn">import</span> <span class="n">_process_comments</span>
    <span class="kn">from</span> <span class="nn">._photosdb_process_exif</span> <span class="kn">import</span> <span class="n">_process_exifinfo</span>
    <span class="kn">from</span> <span class="nn">._photosdb_process_faceinfo</span> <span class="kn">import</span> <span class="n">_process_faceinfo</span>
+    <span class="kn">from</span> <span class="nn">._photosdb_process_scoreinfo</span> <span class="kn">import</span> <span class="n">_process_scoreinfo</span>
    <span class="kn">from</span> <span class="nn">._photosdb_process_searchinfo</span> <span class="kn">import</span> <span class="p">(</span>
        <span class="n">_process_searchinfo</span><span class="p">,</span>
        <span class="n">labels</span><span class="p">,</span>
-        <span class="n">labels_normalized</span><span class="p">,</span>
        <span class="n">labels_as_dict</span><span class="p">,</span>
+        <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_scoreinfo</span> <span class="kn">import</span> <span class="n">_process_scoreinfo</span>
-    <span class="kn">from</span> <span class="nn">._photosdb_process_comments</span> <span class="kn">import</span> <span class="n">_process_comments</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">dbfile</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">exiftool</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; Create a new PhotosDB object.</span>
+        <span class="sd">&quot;&quot;&quot;Create a new PhotosDB object.</span>

 <span class="sd">        Args:</span>
 <span class="sd">            dbfile: specify full path to photos library or photos.db; if None, will attempt to locate last library opened by Photos.</span>
 <span class="sd">            verbose: optional callable function to use for printing verbose text during processing; if None (default), does not print output.</span>
 <span class="sd">            exiftool: optional path to exiftool for methods that require this (e.g. PhotoInfo.exiftool); if not provided, will search PATH</span>
-<span class="sd">        </span>
+
 <span class="sd">        Raises:</span>
 <span class="sd">            FileNotFoundError if dbfile is not a valid Photos library.</span>
 <span class="sd">            TypeError if verbose is not None and not callable.</span>
@@ -273,6 +278,17 @@
        <span class="c1"># Will hold the primary key of root folder</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_folder_root_pk</span> <span class="o">=</span> <span class="kc">None</span>

+        <span class="c1"># Dict to hold signatures for finding possible duplicates</span>
+        <span class="c1"># key is tuple of (original_filesize, date) and value is list of uuids that match that signature</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_db_signatures</span> <span class="o">=</span> <span class="p">{}</span>
+
+        <span class="c1"># Dict to hold information on volume names (Photos 5+)</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">_db_filesystem_volumes</span> <span class="o">=</span> <span class="p">{}</span>
+
+        <span class="c1"># Dict to hold information on moments (Photos 5+)</span>
+        <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">_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>

@@ -353,9 +369,11 @@
        <span class="k">else</span><span class="p">:</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_process_database5</span><span class="p">()</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="nd">@property</span>
    <span class="k">def</span> <span class="nf">keywords_as_dict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; return keywords as dict of keyword, count in reverse sorted order (descending) &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return keywords as dict of keyword, count in reverse sorted order (descending)&quot;&quot;&quot;</span>
        <span class="n">keywords</span> <span class="o">=</span> <span class="p">{</span>
            <span class="n">k</span><span class="p">:</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_dbkeywords_keyword</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="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dbkeywords_keyword</span><span class="o">.</span><span class="n">keys</span><span class="p">()</span>
        <span class="p">}</span>
@@ -365,7 +383,7 @@

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">persons_as_dict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; return persons as dict of person, count in reverse sorted order (descending) &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return persons as dict of person, count in reverse sorted order (descending)&quot;&quot;&quot;</span>
        <span class="n">persons</span> <span class="o">=</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">_dbfaces_pk</span><span class="p">:</span>
            <span class="n">fullname</span> <span class="o">=</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;fullname&quot;</span><span class="p">]</span>
@@ -378,7 +396,7 @@

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">albums_as_dict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; return albums as dict of albums, count in reverse sorted order (descending) &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return albums as dict of albums, count in reverse sorted order (descending)&quot;&quot;&quot;</span>
        <span class="n">albums</span> <span class="o">=</span> <span class="p">{}</span>
        <span class="n">album_keys</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">shared</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
        <span class="k">for</span> <span class="n">album</span> <span class="ow">in</span> <span class="n">album_keys</span><span class="p">:</span>
@@ -395,8 +413,8 @@

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">albums_shared_as_dict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; returns shared albums as dict of albums, count in reverse sorted order (descending)</span>
-<span class="sd">            valid only on Photos 5; on Photos &lt;= 4, prints warning and returns empty dict &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;returns shared albums as dict of albums, count in reverse sorted order (descending)</span>
+<span class="sd">        valid only on Photos 5; on Photos &lt;= 4, prints warning and returns empty dict&quot;&quot;&quot;</span>

        <span class="n">albums</span> <span class="o">=</span> <span class="p">{}</span>
        <span class="n">album_keys</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">shared</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
@@ -414,19 +432,19 @@

    <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>
-        <span class="sd">&quot;&quot;&quot; return list of keywords found in photos database &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return list of keywords found in photos database&quot;&quot;&quot;</span>
        <span class="n">keywords</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dbkeywords_keyword</span><span class="o">.</span><span class="n">keys</span><span class="p">()</span>
        <span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="n">keywords</span><span class="p">)</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">persons</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; return list of persons found in photos database &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return list of persons found in photos database&quot;&quot;&quot;</span>
        <span class="n">persons</span> <span class="o">=</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">k</span><span class="p">][</span><span class="s2">&quot;fullname&quot;</span><span class="p">]</span> <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dbfaces_pk</span><span class="p">}</span>
        <span class="k">return</span> <span class="nb">list</span><span class="p">(</span><span class="n">persons</span><span class="p">)</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">&quot;&quot;&quot; return list of PersonInfo objects for each person in the photos database &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return list of PersonInfo objects for each person in the photos database&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_info</span>
        <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
@@ -437,7 +455,7 @@

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">folder_info</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; return list FolderInfo objects representing top-level folders in the photos database &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return list FolderInfo objects representing top-level folders in the photos database&quot;&quot;&quot;</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>
            <span class="n">folders</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="p">,</span> <span class="n">uuid</span><span class="o">=</span><span class="n">folder</span><span class="p">)</span>
@@ -458,7 +476,7 @@

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">folders</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; return list of top-level folder names in the photos database &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return list of top-level folder names in the photos database&quot;&quot;&quot;</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>
            <span class="n">folder_names</span> <span class="o">=</span> <span class="p">[</span>
                <span class="n">folder</span><span class="p">[</span><span class="s2">&quot;name&quot;</span><span class="p">]</span>
@@ -479,7 +497,7 @@

    <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; return list of AlbumInfo objects for each album in the photos database &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return list of AlbumInfo objects for each album in the photos database&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>
@@ -491,8 +509,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">&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="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>
@@ -505,7 +523,7 @@

    <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>
-        <span class="sd">&quot;&quot;&quot; return list of albums found in photos database &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return list of albums found in photos database&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>
@@ -518,8 +536,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">&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="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>
@@ -534,7 +552,7 @@

    <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; return list of ImportInfo objects for each import session in the database &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return list of ImportInfo objects for each import session in the database&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>
@@ -546,21 +564,21 @@

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">db_version</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; return the database version as stored in LiGlobals table &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return the database version as stored in LiGlobals table&quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_db_version</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">db_path</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; returns path to the Photos library database PhotosDB was initialized with &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;returns path to the Photos library database PhotosDB was initialized with&quot;&quot;&quot;</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">abspath</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="nd">@property</span>
    <span class="k">def</span> <span class="nf">library_path</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; returns path to the Photos library PhotosDB was initialized with &quot;&quot;&quot;</span>
+        <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>

 <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>
+        <span class="sd">&quot;&quot;&quot;Get connection to the working copy of the Photos database</span>

 <span class="sd">        Returns:</span>
 <span class="sd">            tuple of (connection, cursor) to sqlite3 database</span>
@@ -568,7 +586,7 @@
        <span class="k">return</span> <span class="n">_open_sql_file</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_tmp_db</span><span class="p">)</span></div>

    <span class="k">def</span> <span class="nf">_copy_db_file</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fname</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; copies the sqlite database file to a temp file &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;copies the sqlite database file to a temp file&quot;&quot;&quot;</span>
        <span class="sd">&quot;&quot;&quot; returns the name of the temp file &quot;&quot;&quot;</span>
        <span class="sd">&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>
@@ -620,13 +638,15 @@
    <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>
+        <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>

        <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="s2">&quot;Processing database.&quot;</span><span class="p">)</span>
        <span class="n">verbose</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Database version: </span><span class="si">{</span><span class="bp">self</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="bp">self</span><span class="o">.</span><span class="n">_photos_ver</span> <span class="o">=</span> <span class="mi">4</span>  <span class="c1"># only used in Photos 5+</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">_open_sql_file</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"># get info to associate persons with photos</span>
@@ -811,6 +831,8 @@
                <span class="s2">&quot;creation_date&quot;</span><span class="p">:</span> <span class="n">album</span><span class="p">[</span><span class="mi">8</span><span class="p">],</span>
                <span class="s2">&quot;start_date&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5 only</span>
                <span class="s2">&quot;end_date&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5 only</span>
+                <span class="s2">&quot;customsortascending&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5 only</span>
+                <span class="s2">&quot;customsortkey&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>  <span class="c1"># Photos 5 only</span>
            <span class="p">}</span>

        <span class="c1"># get details about folders</span>
@@ -1123,6 +1145,9 @@
            <span class="c1"># get info on special types</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;specialType&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>
            <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;masterModelID&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">26</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;pk&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span>
+                <span class="mi">26</span>
+            <span class="p">]</span>  <span class="c1"># same as masterModelID, to match 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;panorama&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">1</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;slow_mo&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">2</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;time_lapse&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">3</span> <span class="k">else</span> <span class="kc">False</span>
@@ -1213,6 +1238,16 @@
            <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">44</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;fok_import_session&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>

+            <span class="c1"># photos 5+ only, for shared photos</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;cloudownerhashedpersonid&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
+
+            <span class="c1"># compute signatures for finding possible duplicates</span>
+            <span class="n">signature</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_duplicate_signature</span><span class="p">(</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">_db_signatures</span><span class="p">[</span><span class="n">signature</span><span class="p">]</span><span class="o">.</span><span class="n">append</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="bp">self</span><span class="o">.</span><span class="n">_db_signatures</span><span class="p">[</span><span class="n">signature</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">uuid</span><span class="p">]</span>
+
        <span class="c1"># get additional details from RKMaster, needed for RAW processing</span>
        <span class="n">verbose</span><span class="p">(</span><span class="s2">&quot;Processing additional photo details.&quot;</span><span class="p">)</span>
        <span class="n">c</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span>
@@ -1565,15 +1600,15 @@
            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="n">pformat</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos_burst</span><span class="p">))</span>

    <span class="k">def</span> <span class="nf">_build_album_folder_hierarchy_4</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="n">folders</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; recursively build folder/album hierarchy</span>
-<span class="sd">            uuid: parent uuid of the album being processed </span>
-<span class="sd">                 (parent uuid is a folder in RKFolders)</span>
-<span class="sd">            folders: dict holding the folder hierarchy </span>
-<span class="sd">            NOTE: This implementation is different than _build_album_folder_hierarchy_5 </span>
-<span class="sd">            which takes the uuid of the album being processed.  Here uuid is the parent uuid</span>
-<span class="sd">            of the parent folder album because in Photos &lt;=4, folders are in RKFolders and </span>
-<span class="sd">            albums in RKAlbums.  In Photos 5, folders are just special albums </span>
-<span class="sd">            with kind = _PHOTOS_5_FOLDER_KIND &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;recursively build folder/album hierarchy</span>
+<span class="sd">        uuid: parent uuid of the album being processed</span>
+<span class="sd">             (parent uuid is a folder in RKFolders)</span>
+<span class="sd">        folders: dict holding the folder hierarchy</span>
+<span class="sd">        NOTE: This implementation is different than _build_album_folder_hierarchy_5</span>
+<span class="sd">        which takes the uuid of the album being processed.  Here uuid is the parent uuid</span>
+<span class="sd">        of the parent folder album because in Photos &lt;=4, folders are in RKFolders and</span>
+<span class="sd">        albums in RKAlbums.  In Photos 5, folders are just special albums</span>
+<span class="sd">        with kind = _PHOTOS_5_FOLDER_KIND&quot;&quot;&quot;</span>

        <span class="n">parent_uuid</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_dbfolder_details</span><span class="p">[</span><span class="n">uuid</span><span class="p">][</span><span class="s2">&quot;parentFolderUuid&quot;</span><span class="p">]</span>

@@ -1596,11 +1631,11 @@
        <span class="k">return</span> <span class="n">folders</span>

    <span class="k">def</span> <span class="nf">_process_database5</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 5 and version 6</span>
+        <span class="sd">&quot;&quot;&quot;process the Photos database to extract info</span>
+<span class="sd">        works on Photos version 5 and version 6</span>

-<span class="sd">            This is a big hairy 700 line function that should probably be refactored</span>
-<span class="sd">            but it works so don&#39;t touch it.</span>
+<span class="sd">        This is a big hairy 700 line function that should probably be refactored</span>
+<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">_debug</span><span class="p">():</span>
@@ -1615,10 +1650,14 @@
        <span class="n">verbose</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Database version: </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">_db_version</span><span class="si">}</span><span class="s2">, </span><span class="si">{</span><span class="n">photos_ver</span><span class="si">}</span><span class="s2">.&quot;</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">photos_ver</span><span class="p">][</span><span class="s2">&quot;ASSET&quot;</span><span class="p">]</span>
        <span class="n">keyword_join</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;KEYWORD_JOIN&quot;</span><span class="p">]</span>
+        <span class="n">asset_album_table</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;ASSET_ALBUM_TABLE&quot;</span><span class="p">]</span>
        <span class="n">album_join</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;ALBUM_JOIN&quot;</span><span class="p">]</span>
        <span class="n">album_sort</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;ALBUM_SORT_ORDER&quot;</span><span class="p">]</span>
+        <span class="n">asset_album_join</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;ASSET_ALBUM_JOIN&quot;</span><span class="p">]</span>
        <span class="n">import_fok</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;IMPORT_FOK&quot;</span><span class="p">]</span>
        <span class="n">depth_state</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;DEPTH_STATE&quot;</span><span class="p">]</span>
+        <span class="n">uti_original_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;UTI_ORIGINAL&quot;</span><span class="p">]</span>
+        <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">_debug</span><span class="p">():</span>
@@ -1648,7 +1687,11 @@

        <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>
-            <span class="n">fullname</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="k">if</span> <span class="n">person</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="o">!=</span> <span class="s2">&quot;&quot;</span> <span class="k">else</span> <span class="n">_UNKNOWN_PERSON</span>
+            <span class="n">fullname</span> <span class="o">=</span> <span class="p">(</span>
+                <span class="n">person</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>
+                <span class="k">if</span> <span class="p">(</span><span class="n">person</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="o">!=</span> <span class="s2">&quot;&quot;</span> <span class="ow">and</span> <span class="n">person</span><span class="p">[</span><span class="mi">2</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">else</span> <span class="n">_UNKNOWN_PERSON</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="o">=</span> <span class="p">{</span>
                <span class="s2">&quot;pk&quot;</span><span class="p">:</span> <span class="n">pk</span><span class="p">,</span>
                <span class="s2">&quot;uuid&quot;</span><span class="p">:</span> <span class="n">person</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span>
@@ -1734,8 +1777,8 @@
 <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">                </span><span class="si">{</span><span class="n">album_sort</span><span class="si">}</span><span class="s2"></span>
 <span class="s2">                FROM </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2"> </span>
-<span class="s2">                JOIN Z_26ASSETS ON </span><span class="si">{</span><span class="n">album_join</span><span class="si">}</span><span class="s2"> = </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.Z_PK </span>
-<span class="s2">                JOIN ZGENERICALBUM ON ZGENERICALBUM.Z_PK = Z_26ASSETS.Z_26ALBUMS</span>
+<span class="s2">                JOIN </span><span class="si">{</span><span class="n">asset_album_table</span><span class="si">}</span><span class="s2"> ON </span><span class="si">{</span><span class="n">album_join</span><span class="si">}</span><span class="s2"> = </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.Z_PK </span>
+<span class="s2">                JOIN ZGENERICALBUM ON ZGENERICALBUM.Z_PK = </span><span class="si">{</span><span class="n">asset_album_join</span><span class="si">}</span><span class="s2"></span>
 <span class="s2">            &quot;&quot;&quot;</span>
        <span class="p">)</span>

@@ -1773,7 +1816,9 @@
            <span class="s2">&quot;ZTRASHEDSTATE, &quot;</span>  <span class="c1"># 9</span>
            <span class="s2">&quot;ZCREATIONDATE, &quot;</span>  <span class="c1"># 10</span>
            <span class="s2">&quot;ZSTARTDATE, &quot;</span>  <span class="c1"># 11</span>
-            <span class="s2">&quot;ZENDDATE &quot;</span>  <span class="c1"># 12</span>
+            <span class="s2">&quot;ZENDDATE, &quot;</span>  <span class="c1"># 12</span>
+            <span class="s2">&quot;ZCUSTOMSORTASCENDING, &quot;</span>  <span class="c1"># 13</span>
+            <span class="s2">&quot;ZCUSTOMSORTKEY &quot;</span>  <span class="c1"># 14</span>
            <span class="s2">&quot;FROM ZGENERICALBUM &quot;</span>
        <span class="p">)</span>
        <span class="k">for</span> <span class="n">album</span> <span class="ow">in</span> <span class="n">c</span><span class="p">:</span>
@@ -1793,6 +1838,8 @@
                <span class="s2">&quot;creation_date&quot;</span><span class="p">:</span> <span class="n">album</span><span class="p">[</span><span class="mi">10</span><span class="p">],</span>
                <span class="s2">&quot;start_date&quot;</span><span class="p">:</span> <span class="n">album</span><span class="p">[</span><span class="mi">11</span><span class="p">],</span>
                <span class="s2">&quot;end_date&quot;</span><span class="p">:</span> <span class="n">album</span><span class="p">[</span><span class="mi">12</span><span class="p">],</span>
+                <span class="s2">&quot;customsortascending&quot;</span><span class="p">:</span> <span class="n">album</span><span class="p">[</span><span class="mi">13</span><span class="p">],</span>
+                <span class="s2">&quot;customsortkey&quot;</span><span class="p">:</span> <span class="n">album</span><span class="p">[</span><span class="mi">14</span><span class="p">],</span>
            <span class="p">}</span>

            <span class="c1"># add cross-reference by pk to uuid</span>
@@ -1902,7 +1949,7 @@
 <span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZAVALANCHEUUID,</span>
 <span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZAVALANCHEPICKTYPE,</span>
 <span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZKINDSUBTYPE,</span>
-<span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZCUSTOMRENDEREDVALUE,</span>
+<span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.</span><span class="si">{</span><span class="n">hdr_type_column</span><span class="si">}</span><span class="s2">,</span>
 <span class="s2">                ZADDITIONALASSETATTRIBUTES.ZCAMERACAPTUREDEVICE,</span>
 <span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZCLOUDASSETGUID,</span>
 <span class="s2">                ZADDITIONALASSETATTRIBUTES.ZREVERSELOCATIONDATA,</span>
@@ -1921,7 +1968,9 @@
 <span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZVISIBILITYSTATE,</span>
 <span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZTRASHEDDATE,</span>
 <span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZSAVEDASSETTYPE,</span>
-<span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZADDEDDATE</span>
+<span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZADDEDDATE,</span>
+<span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.Z_PK,</span>
+<span class="s2">                </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZCLOUDOWNERHASHEDPERSONID</span>
 <span class="s2">                FROM </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2"> </span>
 <span class="s2">                JOIN ZADDITIONALASSETATTRIBUTES ON ZADDITIONALASSETATTRIBUTES.ZASSET = </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.Z_PK </span>
 <span class="s2">                ORDER BY </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.ZUUID  &quot;&quot;&quot;</span>
@@ -1970,6 +2019,8 @@
        <span class="c1"># 39   ZGENERICASSET.ZTRASHEDDATE -- date item placed in the trash or null if not in trash</span>
        <span class="c1"># 40   ZGENERICASSET.ZSAVEDASSETTYPE -- how item imported</span>
        <span class="c1"># 41   ZGENERICASSET.ZADDEDDATE -- date item added to the library</span>
+        <span class="c1"># 42   ZGENERICASSET.Z_PK -- primary key</span>
+        <span class="c1"># 43   ZGENERICASSET.ZCLOUDOWNERHASHEDPERSONID -- used to look up owner name (for shared photos)</span>

        <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">c</span><span class="p">:</span>
            <span class="n">uuid</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
@@ -2154,6 +2205,9 @@
            <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="n">info</span><span class="p">[</span><span class="s2">&quot;added_date&quot;</span><span class="p">]</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">info</span><span class="p">[</span><span class="s2">&quot;pk&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">42</span><span class="p">]</span>
+            <span class="n">info</span><span class="p">[</span><span class="s2">&quot;cloudownerhashedpersonid&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">43</span><span class="p">]</span>
+
            <span class="c1"># initialize import session info which will be filled in later</span>
            <span class="c1"># not every photo has an import session so initialize all records now</span>
            <span class="n">info</span><span class="p">[</span><span class="s2">&quot;import_session&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
@@ -2174,6 +2228,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="o">=</span> <span class="n">info</span>

+            <span class="c1"># compute signatures for finding possible duplicates</span>
+            <span class="n">signature</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_duplicate_signature</span><span class="p">(</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">_db_signatures</span><span class="p">[</span><span class="n">signature</span><span class="p">]</span><span class="o">.</span><span class="n">append</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="bp">self</span><span class="o">.</span><span class="n">_db_signatures</span><span class="p">[</span><span class="n">signature</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">uuid</span><span class="p">]</span>
+
            <span class="c1"># # if row[19] is not None and ((row[20] == 2) or (row[20] == 4)):</span>
            <span class="c1"># # burst photo</span>
            <span class="c1"># if row[19] is not None:</span>
@@ -2259,20 +2320,33 @@

        <span class="c1"># Get info on remote/local availability for photos in shared albums</span>
        <span class="c1"># Also get UTI of original image (zdatastoresubtype = 1)</span>
-        <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="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_photos_ver</span> <span class="o">&gt;=</span> <span class="mi">7</span><span class="p">:</span>
+            <span class="n">sql_missing</span> <span class="o">=</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">                ZINTERNALRESOURCE.ZLOCALAVAILABILITY, </span>
 <span class="s2">                ZINTERNALRESOURCE.ZREMOTEAVAILABILITY,</span>
 <span class="s2">                ZINTERNALRESOURCE.ZDATASTORESUBTYPE,</span>
-<span class="s2">                ZINTERNALRESOURCE.ZUNIFORMTYPEIDENTIFIER,</span>
+<span class="s2">                </span><span class="si">{</span><span class="n">uti_original_column</span><span class="si">}</span><span class="s2">,</span>
+<span class="s2">                null </span>
+<span class="s2">                FROM </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2"></span>
+<span class="s2">                JOIN ZADDITIONALASSETATTRIBUTES ON ZADDITIONALASSETATTRIBUTES.ZASSET = </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.Z_PK </span>
+<span class="s2">                JOIN ZINTERNALRESOURCE ON ZINTERNALRESOURCE.ZASSET = ZADDITIONALASSETATTRIBUTES.ZASSET </span>
+<span class="s2">                WHERE  ZDATASTORESUBTYPE = 1 OR ZDATASTORESUBTYPE = 3 &quot;&quot;&quot;</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="n">sql_missing</span> <span class="o">=</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">                ZINTERNALRESOURCE.ZLOCALAVAILABILITY, </span>
+<span class="s2">                ZINTERNALRESOURCE.ZREMOTEAVAILABILITY,</span>
+<span class="s2">                ZINTERNALRESOURCE.ZDATASTORESUBTYPE,</span>
+<span class="s2">                </span><span class="si">{</span><span class="n">uti_original_column</span><span class="si">}</span><span class="s2">,</span>
 <span class="s2">                ZUNIFORMTYPEIDENTIFIER.ZIDENTIFIER</span>
 <span class="s2">                FROM </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2"></span>
 <span class="s2">                JOIN ZADDITIONALASSETATTRIBUTES ON ZADDITIONALASSETATTRIBUTES.ZASSET = </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.Z_PK </span>
 <span class="s2">                JOIN ZINTERNALRESOURCE ON ZINTERNALRESOURCE.ZASSET = ZADDITIONALASSETATTRIBUTES.ZASSET </span>
 <span class="s2">                JOIN ZUNIFORMTYPEIDENTIFIER ON ZUNIFORMTYPEIDENTIFIER.Z_PK = ZINTERNALRESOURCE.ZUNIFORMTYPEIDENTIFIER </span>
 <span class="s2">                WHERE  ZDATASTORESUBTYPE = 1 OR ZDATASTORESUBTYPE = 3 &quot;&quot;&quot;</span>
-        <span class="p">)</span>
+
+        <span class="n">c</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">sql_missing</span><span class="p">)</span>

        <span class="c1"># Order of results:</span>
        <span class="c1"># 0 {asset_table}.ZUUID,</span>
@@ -2332,20 +2406,36 @@

        <span class="c1"># get information about associted RAW images</span>
        <span class="c1"># RAW images have ZDATASTORESUBTYPE = 17</span>
-        <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="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_photos_ver</span> <span class="o">&gt;=</span> <span class="mi">7</span><span class="p">:</span>
+            <span class="n">sql_raw</span> <span class="o">=</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">                ZINTERNALRESOURCE.ZDATALENGTH, </span>
+<span class="s2">                null,</span>
+<span class="s2">                ZINTERNALRESOURCE.ZDATASTORESUBTYPE,</span>
+<span class="s2">                ZINTERNALRESOURCE.ZRESOURCETYPE,</span>
+<span class="s2">                ZINTERNALRESOURCE.ZFILESYSTEMBOOKMARK</span>
+<span class="s2">                FROM </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2"></span>
+<span class="s2">                JOIN ZINTERNALRESOURCE ON ZINTERNALRESOURCE.ZASSET = ZADDITIONALASSETATTRIBUTES.ZASSET</span>
+<span class="s2">                JOIN ZADDITIONALASSETATTRIBUTES ON ZADDITIONALASSETATTRIBUTES.ZASSET = </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.Z_PK </span>
+<span class="s2">                WHERE ZINTERNALRESOURCE.ZDATASTORESUBTYPE = 17</span>
+<span class="s2">            &quot;&quot;&quot;</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="n">sql_raw</span> <span class="o">=</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">                ZINTERNALRESOURCE.ZDATALENGTH, </span>
 <span class="s2">                ZUNIFORMTYPEIDENTIFIER.ZIDENTIFIER,</span>
 <span class="s2">                ZINTERNALRESOURCE.ZDATASTORESUBTYPE,</span>
-<span class="s2">                ZINTERNALRESOURCE.ZRESOURCETYPE</span>
+<span class="s2">                ZINTERNALRESOURCE.ZRESOURCETYPE,</span>
+<span class="s2">                ZINTERNALRESOURCE.ZFILESYSTEMBOOKMARK</span>
 <span class="s2">                FROM </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2"></span>
 <span class="s2">                JOIN ZINTERNALRESOURCE ON ZINTERNALRESOURCE.ZASSET = ZADDITIONALASSETATTRIBUTES.ZASSET</span>
 <span class="s2">                JOIN ZADDITIONALASSETATTRIBUTES ON ZADDITIONALASSETATTRIBUTES.ZASSET = </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.Z_PK </span>
 <span class="s2">                JOIN ZUNIFORMTYPEIDENTIFIER ON ZUNIFORMTYPEIDENTIFIER.Z_PK =  ZINTERNALRESOURCE.ZUNIFORMTYPEIDENTIFIER</span>
 <span class="s2">                WHERE ZINTERNALRESOURCE.ZDATASTORESUBTYPE = 17</span>
-<span class="s2">        &quot;&quot;&quot;</span>
-        <span class="p">)</span>
+<span class="s2">            &quot;&quot;&quot;</span>
+
+        <span class="n">c</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">sql_raw</span><span class="p">)</span>
+
        <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">c</span><span class="p">:</span>
            <span class="n">uuid</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="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>
@@ -2354,6 +2444,33 @@
                <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_raw&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;datastore_subtype&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="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;resource_type&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="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;raw_bookmark&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">5</span><span class="p">]</span>
+
+        <span class="c1"># get paths for the relative imports for RAW+JPEG images</span>
+        <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">            ZFILESYSTEMVOLUME.ZNAME,</span>
+<span class="s2">            ZFILESYSTEMBOOKMARK.ZPATHRELATIVETOVOLUME</span>
+<span class="s2">            FROM </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2"> </span>
+<span class="s2">            JOIN ZINTERNALRESOURCE ON ZINTERNALRESOURCE.ZASSET = ZADDITIONALASSETATTRIBUTES.ZASSET</span>
+<span class="s2">            JOIN ZADDITIONALASSETATTRIBUTES ON ZADDITIONALASSETATTRIBUTES.ZASSET = </span><span class="si">{</span><span class="n">asset_table</span><span class="si">}</span><span class="s2">.Z_PK </span>
+<span class="s2">            JOIN ZFILESYSTEMBOOKMARK ON ZFILESYSTEMBOOKMARK.ZRESOURCE = ZINTERNALRESOURCE.Z_PK</span>
+<span class="s2">            JOIN ZFILESYSTEMVOLUME ON ZFILESYSTEMVOLUME.Z_PK = ZINTERNALRESOURCE.ZFILESYSTEMVOLUME</span>
+<span class="s2">            WHERE ZINTERNALRESOURCE.ZDATASTORESUBTYPE = 17</span>
+<span class="s2">            &quot;&quot;&quot;</span>
+        <span class="p">)</span>
+
+        <span class="c1"># path to the raw image will be /Volumes/ZFILESYSTEMVOLUME.ZNAME/ZFILESYSTEMBOOKMARK.ZPATHRELATIVETOVOLUME</span>
+        <span class="c1"># 0: {asset_table}.ZUUID, -- UUID</span>
+        <span class="c1"># 1: ZFILESYSTEMVOLUME.ZNAME, -- name of the volume</span>
+        <span class="c1"># 2: ZFILESYSTEMBOOKMARK.ZPATHRELATIVETOVOLUME -- path to the raw image</span>
+
+        <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">c</span><span class="p">:</span>
+            <span class="n">uuid</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="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;raw_volume&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;raw_relative_path&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"># add faces and keywords to photo data</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">_dbphotos</span><span class="p">:</span>
@@ -2413,6 +2530,10 @@
        <span class="n">verbose</span><span class="p">(</span><span class="s2">&quot;Processing comments and likes for shared photos.&quot;</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_process_comments</span><span class="p">()</span>

+        <span class="c1"># process moments</span>
+        <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="c1"># done processing, dump debug data if requested</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">if</span> <span class="n">_debug</span><span class="p">():</span>
@@ -2458,10 +2579,113 @@
            <span class="n">logging</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s2">&quot;Burst Photos (dbphotos_burst:&quot;</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">pformat</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_dbphotos_burst</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>
+        <span class="sd">&quot;&quot;&quot;Process data from ZMOMENT table&quot;&quot;&quot;</span>
+        <span class="c1"># _db_moment_pk is dict in form {pk: {moment info}} by ZMOMENT.Z_PK</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>
+            <span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">(</span>
+                <span class="sa">f</span><span class="s2">&quot;Moment info implemented for this database version&quot;</span>
+            <span class="p">)</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_process_moment_5</span><span class="p">()</span>
+
+    <span class="k">def</span> <span class="nf">_process_moment_5</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;Process moment info for Photos 5 databases&quot;&quot;&quot;</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="n">results</span> <span class="o">=</span> <span class="bp">self</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;</span>
+<span class="s2">            SELECT </span>
+<span class="s2">            Z_PK,</span>
+<span class="s2">            ZTIMEZONEOFFSET,</span>
+<span class="s2">            ZTRASHEDSTATE,</span>
+<span class="s2">            ZAPPROXIMATELATITUDE,</span>
+<span class="s2">            ZAPPROXIMATELONGITUDE,</span>
+<span class="s2">            ZENDDATE,</span>
+<span class="s2">            ZMODIFICATIONDATE,</span>
+<span class="s2">            ZREPRESENTATIVEDATE,</span>
+<span class="s2">            ZSTARTDATE,</span>
+<span class="s2">            ZSUBTITLE,</span>
+<span class="s2">            ZTITLE,</span>
+<span class="s2">            ZUUID</span>
+<span class="s2">            FROM ZMOMENT&quot;&quot;&quot;</span>
+        <span class="p">)</span>
+
+        <span class="c1"># results</span>
+        <span class="c1"># 0  Z_PK,</span>
+        <span class="c1"># 1  ZTIMEZONEOFFSET,</span>
+        <span class="c1"># 2  ZTRASHEDSTATE,</span>
+        <span class="c1"># 3  ZAPPROXIMATELATITUDE,</span>
+        <span class="c1"># 4  ZAPPROXIMATELONGITUDE,</span>
+        <span class="c1"># 5  ZENDDATE,</span>
+        <span class="c1"># 6  ZMODIFICATIONDATE,</span>
+        <span class="c1"># 7  ZREPRESENTATIVEDATE,</span>
+        <span class="c1"># 8  ZSTARTDATE,</span>
+        <span class="c1"># 9  ZSUBTITLE,</span>
+        <span class="c1"># 10 ZTITLE,</span>
+        <span class="c1"># 11 ZUUID</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>
+            <span class="n">moment_info</span> <span class="o">=</span> <span class="p">{}</span>
+            <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;pk&quot;</span><span class="p">]</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">moment_info</span><span class="p">[</span><span class="s2">&quot;timezoneOffset&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="n">moment_info</span><span class="p">[</span><span class="s2">&quot;trashedState&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="n">moment_info</span><span class="p">[</span><span class="s2">&quot;approximateLatitude&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="n">moment_info</span><span class="p">[</span><span class="s2">&quot;approximateLongitude&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="n">moment_info</span><span class="p">[</span><span class="s2">&quot;endDate&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">5</span><span class="p">]</span>
+            <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;modificationDate&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">6</span><span class="p">]</span>
+            <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;representativeDate&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">7</span><span class="p">]</span>
+            <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;startDate&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">8</span><span class="p">]</span>
+            <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;subtitle&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>
+            <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;title&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">10</span><span class="p">]</span>
+            <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;uuid&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="p">[</span><span class="mi">11</span><span class="p">]</span>
+
+            <span class="c1"># if both lat/lon == -180, then it means location undefined</span>
+            <span class="k">if</span> <span class="p">(</span>
+                <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;approximateLatitude&quot;</span><span class="p">]</span> <span class="o">==</span> <span class="o">-</span><span class="mf">180.0</span>
+                <span class="ow">and</span> <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;approximateLongitude&quot;</span><span class="p">]</span> <span class="o">==</span> <span class="o">-</span><span class="mf">180.0</span>
+            <span class="p">):</span>
+                <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;latitude&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
+                <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;longitude&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;latitude&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;approximateLatitude&quot;</span><span class="p">]</span>
+                <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;longitude&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;approximateLongitude&quot;</span><span class="p">]</span>
+
+            <span class="c1"># process date stamps</span>
+            <span class="n">offset_seconds</span> <span class="o">=</span> <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;timezoneOffset&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">offset_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="k">for</span> <span class="n">date_name</span> <span class="ow">in</span> <span class="p">[</span>
+                <span class="s2">&quot;startDate&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;endDate&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;modificationDate&quot;</span><span class="p">,</span>
+                <span class="s2">&quot;representativeDate&quot;</span><span class="p">,</span>
+            <span class="p">]:</span>
+                <span class="n">date_stamp</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="k">try</span><span class="p">:</span>
+                    <span class="n">moment_date</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">date_stamp</span> <span class="o">+</span> <span class="n">TIME_DELTA</span><span class="p">)</span>
+                    <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="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>
+                    <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="c1"># process title/subtitle</span>
+            <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;title&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;title&quot;</span><span class="p">]</span> <span class="ow">or</span> <span class="s2">&quot;&quot;</span>
+            <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;subtitle&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;subtitle&quot;</span><span class="p">]</span> <span class="ow">or</span> <span class="s2">&quot;&quot;</span>
+
+            <span class="bp">self</span><span class="o">.</span><span class="n">_db_moment_pk</span><span class="p">[</span><span class="n">moment_info</span><span class="p">[</span><span class="s2">&quot;pk&quot;</span><span class="p">]]</span> <span class="o">=</span> <span class="n">moment_info</span>
+
    <span class="k">def</span> <span class="nf">_build_album_folder_hierarchy_5</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="n">folders</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; recursively build folder/album hierarchy</span>
-<span class="sd">            uuid: uuid of the album/folder being processed</span>
-<span class="sd">            folders: dict holding the folder hierarchy &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;recursively build folder/album hierarchy</span>
+<span class="sd">        uuid: uuid of the album/folder being processed</span>
+<span class="sd">        folders: dict holding the folder hierarchy&quot;&quot;&quot;</span>

        <span class="c1"># get parent uuid</span>
        <span class="n">parent</span> <span class="o">=</span> <span class="bp">self</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;parentfolder&quot;</span><span class="p">]</span>
@@ -2482,17 +2706,17 @@
        <span class="k">return</span> <span class="n">folders</span>

    <span class="k">def</span> <span class="nf">_album_folder_hierarchy_list</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">album_uuid</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; return appropriate album_folder_hierarchy_list for the _db_version &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return appropriate album_folder_hierarchy_list for the _db_version&quot;&quot;&quot;</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>
            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_album_folder_hierarchy_list_4</span><span class="p">(</span><span class="n">album_uuid</span><span class="p">)</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_album_folder_hierarchy_list_5</span><span class="p">(</span><span class="n">album_uuid</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">_album_folder_hierarchy_list_4</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">album_uuid</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; return hierarchical list of folder names album_uuid 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 of album is not in any folders &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return hierarchical list of folder names album_uuid 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 of album is not in any folders&quot;&quot;&quot;</span>
        <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>
@@ -2500,7 +2724,7 @@
            <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>
-            <span class="sd">&quot;&quot;&quot; recursively walk the folders dict to build list of folder hierarchy &quot;&quot;&quot;</span>
+            <span class="sd">&quot;&quot;&quot;recursively walk the folders dict to build list of folder hierarchy&quot;&quot;&quot;</span>
            <span class="k">if</span> <span class="ow">not</span> <span class="n">folders</span><span class="p">:</span>
                <span class="c1"># empty folder dict (album has no folder hierarchy)</span>
                <span class="k">return</span> <span class="p">[]</span>
@@ -2526,10 +2750,10 @@
        <span class="k">return</span> <span class="n">hierarchy</span>

    <span class="k">def</span> <span class="nf">_album_folder_hierarchy_list_5</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">album_uuid</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; return hierarchical list of folder names album_uuid 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 of album is not in any folders &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return hierarchical list of folder names album_uuid 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 of album is not in any folders&quot;&quot;&quot;</span>
        <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>
@@ -2537,7 +2761,7 @@
            <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>
-            <span class="sd">&quot;&quot;&quot; recursively walk the folders dict to build list of folder hierarchy &quot;&quot;&quot;</span>
+            <span class="sd">&quot;&quot;&quot;recursively walk the folders dict to build list of folder hierarchy&quot;&quot;&quot;</span>

            <span class="k">if</span> <span class="ow">not</span> <span class="n">folders</span><span class="p">:</span>
                <span class="c1"># empty folder dict (album has no folder hierarchy)</span>
@@ -2569,15 +2793,15 @@
            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_album_folder_hierarchy_folderinfo_5</span><span class="p">(</span><span class="n">album_uuid</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">_album_folder_hierarchy_folderinfo_4</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">album_uuid</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; return hierarchical list of FolderInfo objects album_uuid is contained in</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 of album is not in any folders &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return hierarchical list of FolderInfo objects album_uuid is contained in</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 of album is not in any folders&quot;&quot;&quot;</span>
        <span class="c1"># title = photosdb._dbalbum_details[album_uuid][&quot;title&quot;]</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="c1"># logging.warning(f&quot;uuid = {album_uuid}, folder = {folders}&quot;)</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>
-            <span class="sd">&quot;&quot;&quot; recursively walk the folders dict to build list of folder hierarchy &quot;&quot;&quot;</span>
+            <span class="sd">&quot;&quot;&quot;recursively walk the folders dict to build list of folder hierarchy&quot;&quot;&quot;</span>
            <span class="c1"># logging.warning(f&quot;folders={folders},hierarchy = {hierarchy}&quot;)</span>
            <span class="k">if</span> <span class="ow">not</span> <span class="n">folders</span><span class="p">:</span>
                <span class="c1"># empty folder dict (album has no folder hierarchy)</span>
@@ -2603,14 +2827,14 @@
        <span class="k">return</span> <span class="n">hierarchy</span>

    <span class="k">def</span> <span class="nf">_album_folder_hierarchy_folderinfo_5</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">album_uuid</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; return hierarchical list of FolderInfo objects album_uuid is contained in</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 of album is not in any folders &quot;&quot;&quot;</span>
+        <span class="sd">&quot;&quot;&quot;return hierarchical list of FolderInfo objects album_uuid is contained in</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 of album is not in any folders&quot;&quot;&quot;</span>
        <span class="c1"># title = photosdb._dbalbum_details[album_uuid][&quot;title&quot;]</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">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>
-            <span class="sd">&quot;&quot;&quot; recursively walk the folders dict to build list of folder hierarchy &quot;&quot;&quot;</span>
+            <span class="sd">&quot;&quot;&quot;recursively walk the folders dict to build list of folder hierarchy&quot;&quot;&quot;</span>

            <span class="k">if</span> <span class="ow">not</span> <span class="n">folders</span><span class="p">:</span>
                <span class="c1"># empty folder dict (album has no folder hierarchy)</span>
@@ -2635,19 +2859,19 @@
        <span class="k">return</span> <span class="n">hierarchy</span>

    <span class="k">def</span> <span class="nf">_get_album_uuids</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">shared</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">import_session</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; Return list of album UUIDs found in photos database</span>
-<span class="sd">        </span>
+        <span class="sd">&quot;&quot;&quot;Return list of album UUIDs found in photos database</span>
+
 <span class="sd">            Filters out albums in the trash and any special album types</span>
-<span class="sd">        </span>
+
 <span class="sd">        Args:</span>
 <span class="sd">            shared: boolean; if True, returns shared albums, else normal albums</span>
 <span class="sd">            import_session: boolean, if True, returns import session albums, else normal or shared albums</span>
 <span class="sd">            Note: flags (shared, import_session) are mutually exclusive</span>
-<span class="sd">        </span>
+
 <span class="sd">        Raises:</span>
 <span class="sd">            ValueError: raised if mutually exclusive flags passed</span>

-<span class="sd">        Returns: list of album UUIDs </span>
+<span class="sd">        Returns: list of album UUIDs</span>
 <span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="n">shared</span> <span class="ow">and</span> <span class="n">import_session</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
@@ -2699,14 +2923,14 @@
        <span class="k">return</span> <span class="n">album_list</span>

    <span class="k">def</span> <span class="nf">_get_albums</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">shared</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; Return list of album titles found in photos database</span>
+        <span class="sd">&quot;&quot;&quot;Return list of album titles found in photos database</span>
 <span class="sd">            Albums may have duplicate titles -- these will be treated as a single album.</span>
-<span class="sd">        </span>
+
 <span class="sd">            Filters out albums in the trash and any special album types</span>

 <span class="sd">        Args:</span>
 <span class="sd">            shared: boolean; if True, returns shared albums, else normal albums</span>
-<span class="sd">        </span>
+
 <span class="sd">        Returns: list of album names</span>
 <span class="sd">        &quot;&quot;&quot;</span>

@@ -2725,7 +2949,7 @@
        <span class="n">to_date</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
        <span class="n">intrash</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
    <span class="p">):</span>
-        <span class="sd">&quot;&quot;&quot; Return a list of PhotoInfo objects</span>
+        <span class="sd">&quot;&quot;&quot;Return a list of PhotoInfo objects</span>
 <span class="sd">        If called with no args, returns the entire database of photos</span>
 <span class="sd">        If called with args, returns photos matching the args (e.g. keywords, persons, etc.)</span>
 <span class="sd">        If more than one arg, returns photos matching all the criteria (e.g. keywords AND persons)</span>
@@ -2740,10 +2964,10 @@
 <span class="sd">            persons: list of persons to search for</span>
 <span class="sd">            albums: list of album names to search for</span>
 <span class="sd">            images: if True, returns image files, if False, does not return images; default is True</span>
-<span class="sd">            movies: if True, returns movie files, if False, does not return movies; default is True </span>
+<span class="sd">            movies: if True, returns movie files, if False, does not return movies; default is True</span>
 <span class="sd">            from_date: return photos with creation date &gt;= from_date (datetime.datetime object, default None)</span>
 <span class="sd">            to_date: return photos with creation date &lt;= to_date (datetime.datetime object, default None)</span>
-<span class="sd">            intrash: if True, returns only images in &quot;Recently deleted items&quot; folder, </span>
+<span class="sd">            intrash: if True, returns only images in &quot;Recently deleted items&quot; folder,</span>
 <span class="sd">                     if False returns only photos that aren&#39;t deleted; default is False</span>

 <span class="sd">        Returns:</span>
@@ -2850,7 +3074,7 @@
        <span class="k">return</span> <span class="n">photoinfo</span></div>

 <div class="viewcode-block" id="PhotosDB.get_photo"><a class="viewcode-back" href="../../../reference.html#osxphotos.PhotosDB.get_photo">[docs]</a>    <span class="k">def</span> <span class="nf">get_photo</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; Returns a single photo matching uuid</span>
+        <span class="sd">&quot;&quot;&quot;Returns a single photo matching uuid</span>

 <span class="sd">        Arguments:</span>
 <span class="sd">            uuid: the UUID of photo to get</span>
@@ -2865,7 +3089,7 @@

    <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">&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>
 <span class="sd">            This is faster than using PhotosDB.photos if you have list of UUIDs.</span>
 <span class="sd">            Returns photos regardless of intrash state.</span>
@@ -3217,11 +3441,12 @@

        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">regex</span><span class="p">:</span>
            <span class="n">flags</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">IGNORECASE</span> <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">ignore_case</span> <span class="k">else</span> <span class="mi">0</span>
+            <span class="n">render_options</span> <span class="o">=</span> <span class="n">RenderOptions</span><span class="p">(</span><span class="n">none_str</span><span class="o">=</span><span class="s2">&quot;&quot;</span><span class="p">)</span>
+            <span class="n">photo_list</span> <span class="o">=</span> <span class="p">[]</span>
            <span class="k">for</span> <span class="n">regex</span><span class="p">,</span> <span class="n">template</span> <span class="ow">in</span> <span class="n">options</span><span class="o">.</span><span class="n">regex</span><span class="p">:</span>
                <span class="n">regex</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="n">regex</span><span class="p">,</span> <span class="n">flags</span><span class="p">)</span>
-                <span class="n">photo_list</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">photos</span><span class="p">:</span>
-                    <span class="n">rendered</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">p</span><span class="o">.</span><span class="n">render_template</span><span class="p">(</span><span class="n">template</span><span class="p">,</span> <span class="n">none_str</span><span class="o">=</span><span class="s2">&quot;&quot;</span><span class="p">)</span>
+                    <span class="n">rendered</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">p</span><span class="o">.</span><span class="n">render_template</span><span class="p">(</span><span class="n">template</span><span class="p">,</span> <span class="n">render_options</span><span class="p">)</span>
                    <span class="k">for</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">rendered</span><span class="p">:</span>
                        <span class="k">if</span> <span class="n">regex</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
                            <span class="n">photo_list</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">p</span><span class="p">)</span>
@@ -3236,8 +3461,99 @@
                <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="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Invalid query_eval CRITERIA: </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="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">duplicate</span><span class="p">:</span>
+            <span class="n">no_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">no_date</span> <span class="o">=</span> <span class="n">no_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="n">photos</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</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">duplicates</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">date_added</span> <span class="ow">or</span> <span class="n">no_date</span><span class="p">,</span>
+            <span class="p">)</span>
+            <span class="c1"># gather all duplicates but ensure each uuid is only represented once</span>
+            <span class="n">photodict</span> <span class="o">=</span> <span class="n">OrderedDict</span><span class="p">()</span>
+            <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">photos</span><span class="p">:</span>
+                <span class="k">if</span> <span class="n">p</span><span class="o">.</span><span class="n">uuid</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">photodict</span><span class="p">:</span>
+                    <span class="n">photodict</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="o">=</span> <span class="n">p</span>
+                    <span class="k">for</span> <span class="n">d</span> <span class="ow">in</span> <span class="nb">sorted</span><span class="p">(</span>
+                        <span class="n">p</span><span class="o">.</span><span class="n">duplicates</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">date_added</span> <span class="ow">or</span> <span class="n">no_date</span>
+                    <span class="p">):</span>
+                        <span class="k">if</span> <span class="n">d</span><span class="o">.</span><span class="n">uuid</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">photodict</span><span class="p">:</span>
+                            <span class="n">photodict</span><span class="p">[</span><span class="n">d</span><span class="o">.</span><span class="n">uuid</span><span class="p">]</span> <span class="o">=</span> <span class="n">d</span>
+            <span class="n">photos</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">photodict</span><span class="o">.</span><span class="n">values</span><span class="p">())</span>
+
+            <span class="c1"># filter for deleted as photo.duplicates will include photos in the trash</span>
+            <span class="k">if</span> <span class="ow">not</span> <span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">deleted</span> <span class="ow">or</span> <span class="n">options</span><span class="o">.</span><span class="n">deleted_only</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">intrash</span><span class="p">]</span>
+            <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">deleted_only</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">intrash</span><span class="p">]</span>
+
+        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">location</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">location</span> <span class="o">!=</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">elif</span> <span class="n">options</span><span class="o">.</span><span class="n">no_location</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">location</span> <span class="o">==</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">options</span><span class="o">.</span><span class="n">selected</span><span class="p">:</span>
+            <span class="c1"># photos selected in Photos app</span>
+            <span class="k">try</span><span class="p">:</span>
+                <span class="c1"># catch AppleScript errors as the scripting interfce to Photos is flaky</span>
+                <span class="n">selected</span> <span class="o">=</span> <span class="n">photoscript</span><span class="o">.</span><span class="n">PhotosLibrary</span><span class="p">()</span><span class="o">.</span><span class="n">selection</span>
+                <span class="n">selected_uuid</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="n">selected</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">uuid</span> <span class="ow">in</span> <span class="n">selected_uuid</span><span class="p">]</span>
+            <span class="k">except</span> <span class="ne">Exception</span><span class="p">:</span>
+                <span class="c1"># no photos selected or a selected photo was &quot;open&quot;</span>
+                <span class="c1"># selection only works if photos selected in main media browser</span>
+                <span class="n">photos</span> <span class="o">=</span> <span class="p">[]</span>
+
+        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">exif</span><span class="p">:</span>
+            <span class="n">matching_photos</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">photos</span><span class="p">:</span>
+                <span class="k">if</span> <span class="ow">not</span> <span class="n">p</span><span class="o">.</span><span class="n">exiftool</span><span class="p">:</span>
+                    <span class="k">continue</span>
+                <span class="n">exifdata</span> <span class="o">=</span> <span class="n">p</span><span class="o">.</span><span class="n">exiftool</span><span class="o">.</span><span class="n">asdict</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="n">exifdata</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">exiftool</span><span class="o">.</span><span class="n">asdict</span><span class="p">(</span><span class="n">tag_groups</span><span class="o">=</span><span class="kc">False</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">for</span> <span class="n">exiftag</span><span class="p">,</span> <span class="n">exifvalue</span> <span class="ow">in</span> <span class="n">options</span><span class="o">.</span><span class="n">exif</span><span class="p">:</span>
+                    <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">ignore_case</span><span class="p">:</span>
+                        <span class="n">exifvalue</span> <span class="o">=</span> <span class="n">exifvalue</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
+                        <span class="n">exifdata_value</span> <span class="o">=</span> <span class="n">exifdata</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">exiftag</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;&quot;</span><span class="p">)</span>
+                        <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">exifdata_value</span><span class="p">,</span> <span class="nb">str</span><span class="p">):</span>
+                            <span class="n">exifdata_value</span> <span class="o">=</span> <span class="n">exifdata_value</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
+                        <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">exifdata_value</span><span class="p">,</span> <span class="n">Iterable</span><span class="p">):</span>
+                            <span class="n">exifdata_value</span> <span class="o">=</span> <span class="p">[</span><span class="n">v</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">exifdata_value</span><span class="p">]</span>
+                        <span class="k">else</span><span class="p">:</span>
+                            <span class="n">exifdata_value</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">exifdata_value</span><span class="p">)</span>
+
+                        <span class="k">if</span> <span class="n">exifvalue</span> <span class="ow">in</span> <span class="n">exifdata_value</span><span class="p">:</span>
+                            <span class="n">matching_photos</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">p</span><span class="p">)</span>
+                    <span class="k">else</span><span class="p">:</span>
+                        <span class="n">exifdata_value</span> <span class="o">=</span> <span class="n">exifdata</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">exiftag</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;&quot;</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">exifdata_value</span><span class="p">,</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="n">Iterable</span><span class="p">)):</span>
+                            <span class="n">exifdata_value</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">exifdata_value</span><span class="p">)</span>
+                        <span class="k">if</span> <span class="n">exifvalue</span> <span class="ow">in</span> <span class="n">exifdata_value</span><span class="p">:</span>
+                            <span class="n">matching_photos</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">p</span><span class="p">)</span>
+            <span class="n">photos</span> <span class="o">=</span> <span class="n">matching_photos</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>
+
        <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>
+        <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="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>
+        <span class="k">return</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;original_filesize&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;imageDate&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;height&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;width&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;UTI&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;hasAdjustments&quot;</span><span class="p">],</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;osxphotos.</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="vm">__name__</span><span class="si">}</span><span class="s2">(dbfile=&#39;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">db_path</span><span class="si">}</span><span class="s2">&#39;)&quot;</span>

@@ -3249,10 +3565,14 @@
        <span class="k">return</span> <span class="kc">False</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; Returns number of photos in the database</span>
-<span class="sd">            Includes recently deleted photos and non-selected burst images</span>
+        <span class="sd">&quot;&quot;&quot;Returns number of photos in the database</span>
+<span class="sd">        Includes recently deleted photos and non-selected burst images</span>
 <span class="sd">        &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">_dbphotos</span><span class="p">)</span></div>
+        <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">_dbphotos</span><span class="p">)</span>
+
+    <span class="k">def</span> <span class="fm">__del__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="k">if</span> <span class="nb">getattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="s2">&quot;_db_connection&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">):</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">_db_connection</span><span class="o">.</span><span class="n">close</span><span class="p">()</span></div>


 <span class="k">def</span> <span class="nf">_get_photos_by_attribute</span><span class="p">(</span><span class="n">photos</span><span class="p">,</span> <span class="n">attribute</span><span class="p">,</span> <span class="n">values</span><span class="p">,</span> <span class="n">ignore_case</span><span class="p">):</span>
@@ -3280,7 +3600,7 @@
    <span class="k">else</span><span class="p">:</span>
        <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">values</span><span class="p">:</span>
            <span class="n">photos_search</span><span class="o">.</span><span class="n">extend</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">x</span> <span class="ow">in</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="n">attribute</span><span class="p">))</span>
-    <span class="k">return</span> <span class="n">photos_search</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">photos_search</span><span class="p">))</span>
 </pre></div>

          </div>
@@ -3317,7 +3637,7 @@
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../../../search.html" method="get">
-      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
@@ -3339,7 +3659,7 @@
      &copy;2021, Rhet Turnbull.
      
      |
-      Powered by <a href="http://sphinx-doc.org/">Sphinx 3.5.2</a>
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 4.3.2</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
    </div>
--- a/docs/_static/basic.css
+++ b/docs/_static/basic.css
@@ -130,7 +130,7 @@ ul.search li a {
    font-weight: bold;
 }

-ul.search li div.context {
+ul.search li p.context {
    color: #888;
    margin: 2px 0 0 30px;
    text-align: left;
@@ -277,25 +277,25 @@ p.rubric {
    font-weight: bold;
 }

-img.align-left, .figure.align-left, object.align-left {
+img.align-left, figure.align-left, .figure.align-left, object.align-left {
    clear: left;
    float: left;
    margin-right: 1em;
 }

-img.align-right, .figure.align-right, object.align-right {
+img.align-right, figure.align-right, .figure.align-right, object.align-right {
    clear: right;
    float: right;
    margin-left: 1em;
 }

-img.align-center, .figure.align-center, object.align-center {
+img.align-center, figure.align-center, .figure.align-center, object.align-center {
  display: block;
  margin-left: auto;
  margin-right: auto;
 }

-img.align-default, .figure.align-default {
+img.align-default, figure.align-default, .figure.align-default {
  display: block;
  margin-left: auto;
  margin-right: auto;
@@ -319,7 +319,8 @@ img.align-default, .figure.align-default {

 /* -- sidebars -------------------------------------------------------------- */

-div.sidebar {
+div.sidebar,
+aside.sidebar {
    margin: 0 0 0.5em 1em;
    border: 1px solid #ddb;
    padding: 7px;
@@ -377,12 +378,14 @@ div.body p.centered {
 /* -- content of sidebars/topics/admonitions -------------------------------- */

 div.sidebar > :last-child,
+aside.sidebar > :last-child,
 div.topic > :last-child,
 div.admonition > :last-child {
    margin-bottom: 0;
 }

 div.sidebar::after,
+aside.sidebar::after,
 div.topic::after,
 div.admonition::after,
 blockquote::after {
@@ -455,20 +458,22 @@ td > :last-child {

 /* -- figures --------------------------------------------------------------- */

-div.figure {
+div.figure, figure {
    margin: 0.5em;
    padding: 0.5em;
 }

-div.figure p.caption {
+div.figure p.caption, figcaption {
    padding: 0.3em;
 }

-div.figure p.caption span.caption-number {
+div.figure p.caption span.caption-number,
+figcaption span.caption-number {
    font-style: italic;
 }

-div.figure p.caption span.caption-text {
+div.figure p.caption span.caption-text,
+figcaption span.caption-text {
 }

 /* -- field list styles ----------------------------------------------------- */
@@ -503,6 +508,63 @@ table.hlist td {
    vertical-align: top;
 }

+/* -- object description styles --------------------------------------------- */
+
+.sig {
+	font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+}
+
+.sig-name, code.descname {
+    background-color: transparent;
+    font-weight: bold;
+}
+
+.sig-name {
+	font-size: 1.1em;
+}
+
+code.descname {
+    font-size: 1.2em;
+}
+
+.sig-prename, code.descclassname {
+    background-color: transparent;
+}
+
+.optional {
+    font-size: 1.3em;
+}
+
+.sig-paren {
+    font-size: larger;
+}
+
+.sig-param.n {
+	font-style: italic;
+}
+
+/* C++ specific styling */
+
+.sig-inline.c-texpr,
+.sig-inline.cpp-texpr {
+	font-family: unset;
+}
+
+.sig.c   .k, .sig.c   .kt,
+.sig.cpp .k, .sig.cpp .kt {
+	color: #0033B3;
+}
+
+.sig.c   .m,
+.sig.cpp .m {
+	color: #1750EB;
+}
+
+.sig.c   .s, .sig.c   .sc,
+.sig.cpp .s, .sig.cpp .sc {
+	color: #067D17;
+}
+

 /* -- other body styles ----------------------------------------------------- */

@@ -629,14 +691,6 @@ dl.glossary dt {
    font-size: 1.1em;
 }

-.optional {
-    font-size: 1.3em;
-}
-
-.sig-paren {
-    font-size: larger;
-}
-
 .versionmodified {
    font-style: italic;
 }
@@ -677,8 +731,9 @@ dl.glossary dt {

 .classifier:before {
    font-style: normal;
-    margin: 0.5em;
+    margin: 0 0.5em;
    content: ":";
+    display: inline-block;
 }

 abbr, acronym {
@@ -765,8 +820,12 @@ div.code-block-caption code {

 table.highlighttable td.linenos,
 span.linenos,
-div.doctest > div.highlight span.gp {  /* gp: Generic.Prompt */
-    user-select: none;
+div.highlight span.gp {  /* gp: Generic.Prompt */
+  user-select: none;
+  -webkit-user-select: text; /* Safari fallback only */
+  -webkit-user-select: none; /* Chrome/Safari */
+  -moz-user-select: none; /* Firefox */
+  -ms-user-select: none; /* IE10+ */
 }

 div.code-block-caption span.caption-number {
@@ -781,16 +840,6 @@ div.literal-block-wrapper {
    margin: 1em 0;
 }

-code.descname {
-    background-color: transparent;
-    font-weight: bold;
-    font-size: 1.2em;
-}
-
-code.descclassname {
-    background-color: transparent;
-}
-
 code.xref, a code {
    background-color: transparent;
    font-weight: bold;
--- a/docs/_static/doctools.js
+++ b/docs/_static/doctools.js
@@ -301,12 +301,14 @@ var Documentation = {
              window.location.href = prevHref;
              return false;
            }
+            break;
          case 39: // right
            var nextHref = $('link[rel="next"]').prop('href');
            if (nextHref) {
              window.location.href = nextHref;
              return false;
            }
+            break;
        }
      }
    });
--- a/docs/_static/documentation_options.js
+++ b/docs/_static/documentation_options.js
@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
    URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '0.42.20',
+    VERSION: '0.43.8',
    LANGUAGE: 'None',
    COLLAPSE_INDEX: false,
    BUILDER: 'html',
--- a/docs/_static/pygments.css
+++ b/docs/_static/pygments.css
@@ -1,7 +1,7 @@
 pre { line-height: 125%; }
-td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
-span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
-td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
+td.linenos pre { color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px; }
+span.linenos { color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px; }
+td.linenos pre.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
 span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
 .highlight .hll { background-color: #ffffcc }
 .highlight { background: #f8f8f8; }
--- a/docs/_static/searchtools.js
+++ b/docs/_static/searchtools.js
@@ -282,7 +282,10 @@ var Search = {
                  complete: function(jqxhr, textstatus) {
                    var data = jqxhr.responseText;
                    if (data !== '' && data !== undefined) {
-                      listItem.append(Search.makeSearchSummary(data, searchterms, hlterms));
+                      var summary = Search.makeSearchSummary(data, searchterms, hlterms);
+                      if (summary) {
+                        listItem.append(summary);
+                      }
                    }
                    Search.output.append(listItem);
                    setTimeout(function() {
@@ -325,7 +328,9 @@ var Search = {
    var results = [];

    for (var prefix in objects) {
-      for (var name in objects[prefix]) {
+      for (var iMatch = 0; iMatch != objects[prefix].length; ++iMatch) {
+        var match = objects[prefix][iMatch];
+        var name = match[4];
        var fullname = (prefix ? prefix + '.' : '') + name;
        var fullnameLower = fullname.toLowerCase()
        if (fullnameLower.indexOf(object) > -1) {
@@ -339,7 +344,6 @@ var Search = {
          } else if (parts[parts.length - 1].indexOf(object) > -1) {
            score += Scorer.objPartialMatch;
          }
-          var match = objects[prefix][name];
          var objname = objnames[match[1]][2];
          var title = titles[match[0]];
          // If more than one term searched for, we require other words to be
@@ -498,6 +502,9 @@ var Search = {
   */
  makeSearchSummary : function(htmlText, keywords, hlwords) {
    var text = Search.htmlToText(htmlText);
+    if (text == "") {
+      return null;
+    }
    var textLower = text.toLowerCase();
    var start = 0;
    $.each(keywords, function() {
@@ -509,7 +516,7 @@ var Search = {
    var excerpt = ((start > 0) ? '...' : '') +
      $.trim(text.substr(start, 240)) +
      ((start + 240 - text.length) ? '...' : '');
-    var rv = $('<div class="context"></div>').text(excerpt);
+    var rv = $('<p class="context"></p>').text(excerpt);
    $.each(hlwords, function() {
      rv = rv.highlightText(this, 'highlighted');
    });
--- a/docs/_static/underscore-1.13.1.js
+++ b/docs/_static/underscore-1.13.1.js
--- a/docs/_static/underscore.js
+++ b/docs/_static/underscore.js
--- a/docs/cli.html
+++ b/docs/cli.html
--- a/docs/genindex.html
+++ b/docs/genindex.html
@@ -5,10 +5,10 @@
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Index &#8212; osxphotos 0.42.20 documentation</title>
-    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
-    <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
-    <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <title>Index &#8212; osxphotos 0.43.8 documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
+    <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/doctools.js"></script>
@@ -168,6 +168,8 @@
        <li><a href="cli.html#cmdoption-osxphotos-places-db">osxphotos-places command line option</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-db">osxphotos-query command line option</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-repl-db">osxphotos-repl command line option</a>
 </li>
      </ul></li>
      <li>
@@ -227,6 +229,15 @@

      <ul>
        <li><a href="cli.html#cmdoption-osxphotos-export-dry-run">osxphotos-export command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --duplicate
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-export-duplicate">osxphotos-export command line option</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-query-duplicate">osxphotos-query command line option</a>
 </li>
      </ul></li>
      <li>
@@ -243,6 +254,22 @@

      <ul>
        <li><a href="cli.html#cmdoption-osxphotos-export-edited-suffix">osxphotos-export command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --emacs
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-repl-emacs">osxphotos-repl command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --exif &lt;EXIF_TAG VALUE&gt;
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-export-exif">osxphotos-export command line option</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-query-exif">osxphotos-query command line option</a>
 </li>
      </ul></li>
      <li>
@@ -538,6 +565,15 @@

      <ul>
        <li><a href="cli.html#cmdoption-osxphotos-export-load-config">osxphotos-export command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --location
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-export-location">osxphotos-export command line option</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-query-location">osxphotos-query command line option</a>
 </li>
      </ul></li>
      <li>
@@ -585,8 +621,6 @@
        <li><a href="cli.html#cmdoption-osxphotos-query-no-comment">osxphotos-query command line option</a>
 </li>
      </ul></li>
-  </ul></td>
-  <td style="width: 33%; vertical-align: top;"><ul>
      <li>
    --no-description

@@ -603,6 +637,17 @@
        <li><a href="cli.html#cmdoption-osxphotos-export-no-likes">osxphotos-export command line option</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-no-likes">osxphotos-query command line option</a>
+</li>
+      </ul></li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li>
+    --no-location
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-export-no-location">osxphotos-export command line option</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-query-no-location">osxphotos-query command line option</a>
 </li>
      </ul></li>
      <li>
@@ -841,6 +886,41 @@
        <li><a href="cli.html#cmdoption-osxphotos-export-portrait">osxphotos-export command line option</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-portrait">osxphotos-query command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --post-command &lt;CATEGORY COMMAND&gt;
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-export-post-command">osxphotos-export command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --post-function &lt;filename.py::function&gt;
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-export-post-function">osxphotos-export command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --preview
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-export-preview">osxphotos-export command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --preview-if-missing
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-export-preview-if-missing">osxphotos-export command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --preview-suffix &lt;SUFFIX&gt;
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-export-preview-suffix">osxphotos-export command line option</a>
 </li>
      </ul></li>
      <li>
@@ -850,6 +930,15 @@
        <li><a href="cli.html#cmdoption-osxphotos-export-query-eval">osxphotos-export command line option</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-query-eval">osxphotos-query command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --query-function &lt;filename.py::function&gt;
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-export-query-function">osxphotos-export command line option</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-query-query-function">osxphotos-query command line option</a>
 </li>
      </ul></li>
      <li>
@@ -896,6 +985,15 @@
        <li><a href="cli.html#cmdoption-osxphotos-export-screenshot">osxphotos-export command line option</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-screenshot">osxphotos-query command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --selected
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-export-selected">osxphotos-export command line option</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-query-selected">osxphotos-query command line option</a>
 </li>
      </ul></li>
      <li>
@@ -1029,6 +1127,13 @@

      <ul>
        <li><a href="cli.html#cmdoption-osxphotos-export-update">osxphotos-export command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --upgrade
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-install-U">osxphotos-install command line option</a>
 </li>
      </ul></li>
      <li>
@@ -1091,6 +1196,13 @@

      <ul>
        <li><a href="cli.html#cmdoption-osxphotos-export-xattr-template">osxphotos-export command line option</a>
+</li>
+      </ul></li>
+      <li>
+    --yes
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-uninstall-y">osxphotos-uninstall command line option</a>
 </li>
      </ul></li>
      <li>
@@ -1100,6 +1212,13 @@
        <li><a href="cli.html#cmdoption-osxphotos-export-i">osxphotos-export command line option</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-i">osxphotos-query command line option</a>
+</li>
+      </ul></li>
+      <li>
+    -U
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-install-U">osxphotos-install command line option</a>
 </li>
      </ul></li>
      <li>
@@ -1114,6 +1233,13 @@

      <ul>
        <li><a href="cli.html#cmdoption-osxphotos-v">osxphotos command line option</a>
+</li>
+      </ul></li>
+      <li>
+    -y
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-uninstall-y">osxphotos-uninstall command line option</a>
 </li>
      </ul></li>
  </ul></td>
@@ -1122,19 +1248,19 @@
 <h2 id="A">A</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.activities">activities() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.activities">activities (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.adjustments">adjustments() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.adjustments">adjustments (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.album_info">album_info() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.album_info">album_info (osxphotos.PhotoInfo property)</a>

      <ul>
        <li><a href="reference.html#osxphotos.PhotosDB.album_info">(osxphotos.PhotosDB property)</a>
 </li>
      </ul></li>
-      <li><a href="reference.html#osxphotos.PhotosDB.album_info_shared">album_info_shared() (osxphotos.PhotosDB property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.album_info_shared">album_info_shared (osxphotos.PhotosDB property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.albums">albums() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.albums">albums (osxphotos.PhotoInfo property)</a>

      <ul>
        <li><a href="reference.html#osxphotos.PhotosDB.albums">(osxphotos.PhotosDB property)</a>
@@ -1142,13 +1268,13 @@
      </ul></li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotosDB.albums_as_dict">albums_as_dict() (osxphotos.PhotosDB property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.albums_as_dict">albums_as_dict (osxphotos.PhotosDB property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotosDB.albums_shared">albums_shared() (osxphotos.PhotosDB property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.albums_shared">albums_shared (osxphotos.PhotosDB property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotosDB.albums_shared_as_dict">albums_shared_as_dict() (osxphotos.PhotosDB property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.albums_shared_as_dict">albums_shared_as_dict (osxphotos.PhotosDB property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.all">all() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.all">all (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExportResults.all_files">all_files() (osxphotos.PhotoInfo.ExportResults method)</a>
 </li>
@@ -1170,23 +1296,23 @@
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.bit_rate">bit_rate (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.bodies_of_water">bodies_of_water() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.bodies_of_water">bodies_of_water (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.burst">burst() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.burst">burst (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.burst_album_info">burst_album_info() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.burst_album_info">burst_album_info (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.burst_albums">burst_albums() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.burst_albums">burst_albums (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.burst_default_pick">burst_default_pick() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.burst_default_pick">burst_default_pick (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.burst_key">burst_key() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.burst_key">burst_key (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.burst_photos">burst_photos() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.burst_photos">burst_photos (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.burst_selected">burst_selected() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.burst_selected">burst_selected (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -1198,15 +1324,15 @@
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.camera_model">camera_model (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.city">city() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.city">city (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.codec">codec (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.comments">comments() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.comments">comments (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.country">country() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.country">country (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.curation">curation (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
@@ -1216,21 +1342,21 @@
 <h2 id="D">D</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.date">date() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.date">date (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.date_added">date_added() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.date_added">date_added (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.date_modified">date_modified() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.date_modified">date_modified (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.date_trashed">date_trashed() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.date_trashed">date_trashed (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotosDB.db_path">db_path() (osxphotos.PhotosDB property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.db_path">db_path (osxphotos.PhotosDB property)</a>
+</li>
+      <li><a href="reference.html#osxphotos.PhotosDB.db_version">db_version (osxphotos.PhotosDB property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotosDB.db_version">db_version() (osxphotos.PhotosDB property)</a>
-</li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.description">description() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.description">description (osxphotos.PhotoInfo property)</a>
 </li>
      <li>
    DEST
@@ -1239,6 +1365,10 @@
        <li><a href="cli.html#cmdoption-osxphotos-export-arg-DEST">osxphotos-export command line option</a>
 </li>
      </ul></li>
+      <li><a href="reference.html#osxphotos.PhotoInfo.detected_text">detected_text() (osxphotos.PhotoInfo method)</a>
+</li>
+      <li><a href="reference.html#osxphotos.PhotoInfo.duplicates">duplicates (osxphotos.PhotoInfo property)</a>
+</li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.duration">duration (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
  </ul></td>
@@ -1247,19 +1377,21 @@
 <h2 id="E">E</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.exif_info">exif_info() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.execute">execute() (osxphotos.PhotosDB method)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.exiftool">exiftool() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.exif_info">exif_info (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.export">export() (osxphotos.PhotoInfo method)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.exiftool">exiftool (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#osxphotos.PhotoInfo.export">export() (osxphotos.PhotoInfo method)</a>
+</li>
      <li><a href="reference.html#osxphotos.PhotoInfo.export2">export2() (osxphotos.PhotoInfo method)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.exposure_bias">exposure_bias (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.external_edit">external_edit() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.external_edit">external_edit (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -1267,13 +1399,13 @@
 <h2 id="F">F</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.face_info">face_info() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.face_info">face_info (osxphotos.PhotoInfo property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.failure">failure (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.favorite">favorite() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.favorite">favorite (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.filename">filename() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.filename">filename (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
@@ -1281,9 +1413,9 @@
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.focal_length">focal_length (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotosDB.folder_info">folder_info() (osxphotos.PhotosDB property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.folder_info">folder_info (osxphotos.PhotosDB property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotosDB.folders">folders() (osxphotos.PhotosDB property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.folders">folders (osxphotos.PhotosDB property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.fps">fps (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
@@ -1307,21 +1439,21 @@
  <td style="width: 33%; vertical-align: top;"><ul>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.harmonious_color">harmonious_color (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.has_raw">has_raw() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.has_raw">has_raw (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.hasadjustments">hasadjustments() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.hasadjustments">hasadjustments (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.hdr">hdr() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.hdr">hdr (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.height">height() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.height">height (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.hidden">hidden() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.hidden">hidden (osxphotos.PhotoInfo property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.highlight_visibility">highlight_visibility (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.holidays">holidays() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.holidays">holidays (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -1331,37 +1463,37 @@
  <td style="width: 33%; vertical-align: top;"><ul>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.immersiveness">immersiveness (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.import_info">import_info() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.import_info">import_info (osxphotos.PhotoInfo property)</a>

      <ul>
        <li><a href="reference.html#osxphotos.PhotosDB.import_info">(osxphotos.PhotosDB property)</a>
 </li>
      </ul></li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.incloud">incloud() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.incloud">incloud (osxphotos.PhotoInfo property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.interaction">interaction (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.interesting_subject">interesting_subject (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.intrash">intrash() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.intrash">intrash (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.intrusive_object_presence">intrusive_object_presence (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.iscloudasset">iscloudasset() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.iscloudasset">iscloudasset (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.ismissing">ismissing() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.ismissing">ismissing (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.ismovie">ismovie() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.ismovie">ismovie (osxphotos.PhotoInfo property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.iso">iso (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.isphoto">isphoto() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.isphoto">isphoto (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.israw">israw() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.israw">israw (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.isreference">isreference() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.isreference">isreference (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -1377,7 +1509,7 @@
 <h2 id="K">K</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.keywords">keywords() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.keywords">keywords (osxphotos.PhotoInfo property)</a>

      <ul>
        <li><a href="reference.html#osxphotos.PhotosDB.keywords">(osxphotos.PhotosDB property)</a>
@@ -1385,7 +1517,7 @@
      </ul></li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotosDB.keywords_as_dict">keywords_as_dict() (osxphotos.PhotosDB property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.keywords_as_dict">keywords_as_dict (osxphotos.PhotosDB property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -1393,7 +1525,7 @@
 <h2 id="L">L</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.labels">labels() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.labels">labels (osxphotos.PhotoInfo property)</a>

      <ul>
        <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.labels">(osxphotos.PhotoInfo.SearchInfo property)</a>
@@ -1401,15 +1533,15 @@
        <li><a href="reference.html#osxphotos.PhotosDB.labels">(osxphotos.PhotosDB property)</a>
 </li>
      </ul></li>
-      <li><a href="reference.html#osxphotos.PhotosDB.labels_as_dict">labels_as_dict() (osxphotos.PhotosDB property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.labels_as_dict">labels_as_dict (osxphotos.PhotosDB property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.labels_normalized">labels_normalized() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.labels_normalized">labels_normalized (osxphotos.PhotoInfo property)</a>

      <ul>
        <li><a href="reference.html#osxphotos.PhotosDB.labels_normalized">(osxphotos.PhotosDB property)</a>
 </li>
      </ul></li>
-      <li><a href="reference.html#osxphotos.PhotosDB.labels_normalized_as_dict">labels_normalized_as_dict() (osxphotos.PhotosDB property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.labels_normalized_as_dict">labels_normalized_as_dict (osxphotos.PhotosDB property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.latitude">latitude (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
@@ -1417,17 +1549,17 @@
  <td style="width: 33%; vertical-align: top;"><ul>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.lens_model">lens_model (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotosDB.library_path">library_path() (osxphotos.PhotosDB property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.library_path">library_path (osxphotos.PhotosDB property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.likes">likes() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.likes">likes (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.live_photo">live_photo() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.live_photo">live_photo (osxphotos.PhotoInfo property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.lively_color">lively_color (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.locality_names">locality_names() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.locality_names">locality_names (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.location">location() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.location">location (osxphotos.PhotoInfo property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.longitude">longitude (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
@@ -1439,13 +1571,15 @@
 <h2 id="M">M</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.media_types">media_types() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.media_types">media_types (osxphotos.PhotoInfo.SearchInfo property)</a>
+</li>
+      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.metering_mode">metering_mode (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.metering_mode">metering_mode (osxphotos.PhotoInfo.ExifInfo attribute)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.moment">moment (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.month">month() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.month">month (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -1453,7 +1587,7 @@
 <h2 id="N">N</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.neighborhoods">neighborhoods() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.neighborhoods">neighborhoods (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
@@ -1465,17 +1599,17 @@
 <h2 id="O">O</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.orientation">orientation() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.orientation">orientation (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.original_filename">original_filename() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.original_filename">original_filename (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.original_filesize">original_filesize() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.original_filesize">original_filesize (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.original_height">original_height() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.original_height">original_height (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.original_orientation">original_orientation() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.original_orientation">original_orientation (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.original_width">original_width() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.original_width">original_width (osxphotos.PhotoInfo property)</a>
 </li>
      <li>
    osxphotos command line option
@@ -1553,10 +1687,14 @@
        <li><a href="cli.html#cmdoption-osxphotos-export-download-missing">--download-missing</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-dry-run">--dry-run</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-export-duplicate">--duplicate</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-edited">--edited</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-edited-suffix">--edited-suffix &lt;SUFFIX&gt;</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-export-exif">--exif &lt;EXIF_TAG VALUE&gt;</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-exiftool">--exiftool</a>
 </li>
@@ -1623,6 +1761,8 @@
        <li><a href="cli.html#cmdoption-osxphotos-export-live">--live</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-load-config">--load-config &lt;config file path&gt;</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-export-location">--location</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-max-size">--max-size &lt;SIZE&gt;</a>
 </li>
@@ -1637,6 +1777,8 @@
        <li><a href="cli.html#cmdoption-osxphotos-export-no-description">--no-description</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-no-likes">--no-likes</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-export-no-location">--no-location</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-no-place">--no-place</a>
 </li>
@@ -1687,8 +1829,20 @@
        <li><a href="cli.html#cmdoption-osxphotos-export-place">--place &lt;PLACE&gt;</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-portrait">--portrait</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-export-post-command">--post-command &lt;CATEGORY COMMAND&gt;</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-export-post-function">--post-function &lt;filename.py::function&gt;</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-export-preview">--preview</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-export-preview-if-missing">--preview-if-missing</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-export-preview-suffix">--preview-suffix &lt;SUFFIX&gt;</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-query-eval">--query-eval &lt;CRITERIA&gt;</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-export-query-function">--query-function &lt;filename.py::function&gt;</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-regex">--regex &lt;REGEX TEMPLATE&gt;</a>
 </li>
@@ -1701,6 +1855,8 @@
        <li><a href="cli.html#cmdoption-osxphotos-export-save-config">--save-config &lt;config file path&gt;</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-screenshot">--screenshot</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-export-selected">--selected</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-export-selfie">--selfie</a>
 </li>
@@ -1777,6 +1933,17 @@
        <li><a href="cli.html#cmdoption-osxphotos-info-json">--json</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-info-arg-PHOTOS_LIBRARY">PHOTOS_LIBRARY</a>
+</li>
+      </ul></li>
+      <li>
+    osxphotos-install command line option
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-install-U">--upgrade</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-install-U">-U</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-install-arg-PACKAGES">PACKAGES</a>
 </li>
      </ul></li>
      <li>
@@ -1849,8 +2016,12 @@
        <li><a href="cli.html#cmdoption-osxphotos-query-deleted-only">--deleted-only</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-description">--description &lt;DESC&gt;</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-query-duplicate">--duplicate</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-edited">--edited</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-query-exif">--exif &lt;EXIF_TAG VALUE&gt;</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-external-edit">--external-edit</a>
 </li>
@@ -1887,6 +2058,8 @@
        <li><a href="cli.html#cmdoption-osxphotos-query-label">--label &lt;LABEL&gt;</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-live">--live</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-query-location">--location</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-max-size">--max-size &lt;SIZE&gt;</a>
 </li>
@@ -1901,6 +2074,8 @@
        <li><a href="cli.html#cmdoption-osxphotos-query-no-description">--no-description</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-no-likes">--no-likes</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-query-no-location">--no-location</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-no-place">--no-place</a>
 </li>
@@ -1951,10 +2126,14 @@
        <li><a href="cli.html#cmdoption-osxphotos-query-portrait">--portrait</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-query-eval">--query-eval &lt;CRITERIA&gt;</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-query-query-function">--query-function &lt;filename.py::function&gt;</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-regex">--regex &lt;REGEX TEMPLATE&gt;</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-screenshot">--screenshot</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-query-selected">--selected</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-selfie">--selfie</a>
 </li>
@@ -1979,9 +2158,38 @@
        <li><a href="cli.html#cmdoption-osxphotos-query-i">-i</a>
 </li>
        <li><a href="cli.html#cmdoption-osxphotos-query-arg-PHOTOS_LIBRARY">PHOTOS_LIBRARY</a>
+</li>
+      </ul></li>
+      <li>
+    osxphotos-repl command line option
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-repl-db">--db &lt;Photos database path&gt;</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-repl-emacs">--emacs</a>
+</li>
+      </ul></li>
+      <li>
+    osxphotos-tutorial command line option
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-tutorial-arg-WIDTH">WIDTH</a>
+</li>
+      </ul></li>
+      <li>
+    osxphotos-uninstall command line option
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-uninstall-y">--yes</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-uninstall-y">-y</a>
+</li>
+        <li><a href="cli.html#cmdoption-osxphotos-uninstall-arg-PACKAGES">PACKAGES</a>
 </li>
      </ul></li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.overall">overall (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
+</li>
+      <li><a href="reference.html#osxphotos.PhotoInfo.owner">owner (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -1989,31 +2197,42 @@
 <h2 id="P">P</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.panorama">panorama() (osxphotos.PhotoInfo property)</a>
+      <li>
+    PACKAGES
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-install-arg-PACKAGES">osxphotos-install command line option</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.path">path() (osxphotos.PhotoInfo property)</a>
+        <li><a href="cli.html#cmdoption-osxphotos-uninstall-arg-PACKAGES">osxphotos-uninstall command line option</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.path_derivatives">path_derivatives() (osxphotos.PhotoInfo property)</a>
+      </ul></li>
+      <li><a href="reference.html#osxphotos.PhotoInfo.panorama">panorama (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.path_edited">path_edited() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.path">path (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.path_live_photo">path_live_photo() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.path_derivatives">path_derivatives (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.path_raw">path_raw() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.path_edited">path_edited (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.person_info">person_info() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.path_edited_live_photo">path_edited_live_photo (osxphotos.PhotoInfo property)</a>
+</li>
+      <li><a href="reference.html#osxphotos.PhotoInfo.path_live_photo">path_live_photo (osxphotos.PhotoInfo property)</a>
+</li>
+      <li><a href="reference.html#osxphotos.PhotoInfo.path_raw">path_raw (osxphotos.PhotoInfo property)</a>
+</li>
+      <li><a href="reference.html#osxphotos.PhotoInfo.person_info">person_info (osxphotos.PhotoInfo property)</a>

      <ul>
        <li><a href="reference.html#osxphotos.PhotosDB.person_info">(osxphotos.PhotosDB property)</a>
 </li>
      </ul></li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.persons">persons() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.persons">persons (osxphotos.PhotoInfo property)</a>

      <ul>
        <li><a href="reference.html#osxphotos.PhotosDB.persons">(osxphotos.PhotosDB property)</a>
 </li>
      </ul></li>
-      <li><a href="reference.html#osxphotos.PhotosDB.persons_as_dict">persons_as_dict() (osxphotos.PhotosDB property)</a>
+      <li><a href="reference.html#osxphotos.PhotosDB.persons_as_dict">persons_as_dict (osxphotos.PhotosDB property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo">PhotoInfo (class in osxphotos)</a>
 </li>
@@ -2029,6 +2248,8 @@
 </li>
      <li><a href="reference.html#osxphotos.PhotosDB.photos_by_uuid">photos_by_uuid() (osxphotos.PhotosDB method)</a>
 </li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
      <li>
    PHOTOS_LIBRARY

@@ -2052,13 +2273,11 @@
        <li><a href="cli.html#cmdoption-osxphotos-query-arg-PHOTOS_LIBRARY">osxphotos-query command line option</a>
 </li>
      </ul></li>
-  </ul></td>
-  <td style="width: 33%; vertical-align: top;"><ul>
      <li><a href="reference.html#osxphotos.PhotosDB">PhotosDB (class in osxphotos)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.place">place() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.place">place (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.place_names">place_names() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.place_names">place_names (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.pleasant_camera_tilt">pleasant_camera_tilt (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
@@ -2076,7 +2295,7 @@
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.pleasant_symmetry">pleasant_symmetry (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.portrait">portrait() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.portrait">portrait (osxphotos.PhotoInfo property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.promotion">promotion (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
@@ -2094,7 +2313,7 @@
 <h2 id="R">R</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.raw_original">raw_original() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.raw_original">raw_original (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
@@ -2108,33 +2327,33 @@
  <td style="width: 33%; vertical-align: top;"><ul>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.sample_rate">sample_rate (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.score">score() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.score">score (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.screenshot">screenshot() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.screenshot">screenshot (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.search_info">search_info() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.search_info">search_info (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.search_info_normalized">search_info_normalized() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.search_info_normalized">search_info_normalized (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.season">season() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.season">season (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.selfie">selfie() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.selfie">selfie (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.shared">shared() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.shared">shared (osxphotos.PhotoInfo property)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.sharply_focused_subject">sharply_focused_subject (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.shutter_speed">shutter_speed (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.slow_mo">slow_mo() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.slow_mo">slow_mo (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.state">state() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.state">state (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.state_abbreviation">state_abbreviation() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.state_abbreviation">state_abbreviation (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.streets">streets() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.streets">streets (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -2144,9 +2363,9 @@
  <td style="width: 33%; vertical-align: top;"><ul>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.tastefully_blurred">tastefully_blurred (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.time_lapse">time_lapse() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.time_lapse">time_lapse (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.title">title() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.title">title (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
@@ -2159,7 +2378,7 @@
      </ul></li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.track_format">track_format (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.tzoffset">tzoffset() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.tzoffset">tzoffset (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -2167,17 +2386,17 @@
 <h2 id="U">U</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.uti">uti() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.uti">uti (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.uti_edited">uti_edited() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.uti_edited">uti_edited (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.uti_original">uti_original() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.uti_original">uti_original (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.uti_raw">uti_raw() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.uti_raw">uti_raw (osxphotos.PhotoInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.uuid">uuid() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.uuid">uuid (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -2185,13 +2404,13 @@
 <h2 id="V">V</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.venue_types">venue_types() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.venue_types">venue_types (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
  </ul></td>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.venues">venues() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.venues">venues (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.visible">visible() (osxphotos.PhotoInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.visible">visible (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -2203,13 +2422,20 @@
 </li>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.well_framed_subject">well_framed_subject (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
-  </ul></td>
-  <td style="width: 33%; vertical-align: top;"><ul>
      <li><a href="reference.html#osxphotos.PhotoInfo.ScoreInfo.well_timed_shot">well_timed_shot (osxphotos.PhotoInfo.ScoreInfo attribute)</a>
 </li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
      <li><a href="reference.html#osxphotos.PhotoInfo.ExifInfo.white_balance">white_balance (osxphotos.PhotoInfo.ExifInfo attribute)</a>
 </li>
-      <li><a href="reference.html#osxphotos.PhotoInfo.width">width() (osxphotos.PhotoInfo property)</a>
+      <li>
+    WIDTH
+
+      <ul>
+        <li><a href="cli.html#cmdoption-osxphotos-tutorial-arg-WIDTH">osxphotos-tutorial command line option</a>
+</li>
+      </ul></li>
+      <li><a href="reference.html#osxphotos.PhotoInfo.width">width (osxphotos.PhotoInfo property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -2217,7 +2443,7 @@
 <h2 id="Y">Y</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.year">year() (osxphotos.PhotoInfo.SearchInfo property)</a>
+      <li><a href="reference.html#osxphotos.PhotoInfo.SearchInfo.year">year (osxphotos.PhotoInfo.SearchInfo property)</a>
 </li>
  </ul></td>
 </tr></table>
@@ -2256,7 +2482,7 @@
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
-      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
@@ -2278,7 +2504,7 @@
      &copy;2021, Rhet Turnbull.
      
      |
-      Powered by <a href="http://sphinx-doc.org/">Sphinx 3.5.2</a>
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 4.3.2</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
    </div>
--- a/docs/index.html
+++ b/docs/index.html
@@ -5,10 +5,10 @@
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Welcome to osxphotos’s documentation! &#8212; osxphotos 0.42.20 documentation</title>
-    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
-    <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
-    <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <title>Welcome to osxphotos’s documentation! &#8212; osxphotos 0.43.8 documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
+    <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/doctools.js"></script>
@@ -45,8 +45,8 @@ You can also easily export both the original and edited photos.</p>
 </div>
 <div class="section" id="supported-operating-systems">
 <h2>Supported operating systems<a class="headerlink" href="#supported-operating-systems" title="Permalink to this headline">¶</a></h2>
-<p>Only works on macOS (aka Mac OS X). Tested on macOS Sierra (10.12.6) until macOS Catalina (10.15.7).
-Beta support for macOS Big Sur (10.16.01/11.01).</p>
+<p>Only works on macOS (aka Mac OS X). Tested on macOS Sierra (10.12.6) through macOS Big Sur (11.3).</p>
+<p>If you have access to macOS 12 / Monterey beta and would like to help ensure osxphotos is compatible, please contact me via GitHub.</p>
 <p>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.</p>
 <p>Requires python &gt;= <code class="docutils literal notranslate"><span class="pre">3.7</span></code>.</p>
@@ -122,6 +122,8 @@ Alternatively, you can also run the command line utility like this: <code class=
  <span class="n">persons</span>   <span class="n">Print</span> <span class="n">out</span> <span class="n">persons</span> <span class="p">(</span><span class="n">faces</span><span class="p">)</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">library</span><span class="o">.</span>
  <span class="n">places</span>    <span class="n">Print</span> <span class="n">out</span> <span class="n">places</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">library</span><span class="o">.</span>
  <span class="n">query</span>     <span class="n">Query</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">database</span> <span class="n">using</span> <span class="mi">1</span> <span class="ow">or</span> <span class="n">more</span> <span class="n">search</span> <span class="n">options</span><span class="p">;</span> <span class="k">if</span><span class="o">...</span>
+  <span class="n">repl</span>      <span class="n">Run</span> <span class="n">interactive</span> <span class="n">osxphotos</span> <span class="n">shell</span>
+  <span class="n">tutorial</span>  <span class="n">Display</span> <span class="n">osxphotos</span> <span class="n">tutorial</span><span class="o">.</span>
 </pre></div>
 </div>
 <p>To get help on a specific command, use <code class="docutils literal notranslate"><span class="pre">osxphotos</span> <span class="pre">help</span> <span class="pre">&lt;command_name&gt;</span></code></p>
@@ -286,12 +288,16 @@ Alternatively, you can also run the command line utility like this: <code class=
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-export">export</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-help">help</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-info">info</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-install">install</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-keywords">keywords</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-labels">labels</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-list">list</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-persons">persons</a></li>
 <li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-places">places</a></li>
 <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-tutorial">tutorial</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-uninstall">uninstall</a></li>
 </ul>
 </li>
 </ul>
@@ -347,7 +353,7 @@ Alternatively, you can also run the command line utility like this: <code class=
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
-      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
@@ -369,7 +375,7 @@ Alternatively, you can also run the command line utility like this: <code class=
      &copy;2021, Rhet Turnbull.
      
      |
-      Powered by <a href="http://sphinx-doc.org/">Sphinx 3.5.2</a>
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 4.3.2</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
      |
--- a/docs/modules.html
+++ b/docs/modules.html
@@ -5,10 +5,10 @@
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>osxphotos &#8212; osxphotos 0.42.20 documentation</title>
-    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
-    <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
-    <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <title>osxphotos &#8212; osxphotos 0.43.8 documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
+    <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/doctools.js"></script>
@@ -69,7 +69,7 @@
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
-      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
@@ -91,7 +91,7 @@
      &copy;2021, Rhet Turnbull.
      
      |
-      Powered by <a href="http://sphinx-doc.org/">Sphinx 3.5.2</a>
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 4.3.2</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
      |
--- a/docs/objects.inv
+++ b/docs/objects.inv
--- a/docs/reference.html
+++ b/docs/reference.html
--- a/docs/search.html
+++ b/docs/search.html
@@ -5,11 +5,11 @@
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Search &#8212; osxphotos 0.42.20 documentation</title>
-    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
-    <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
+    <title>Search &#8212; osxphotos 0.43.8 documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
    
-    <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <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/doctools.js"></script>
@@ -37,26 +37,35 @@
          <div class="body" role="main">
            
  <h1 id="search-documentation">Search</h1>
-  <div id="fallback" class="admonition warning">
-  <script>$('#fallback').hide();</script>
+  
+  <noscript>
+  <div class="admonition warning">
  <p>
    Please activate JavaScript to enable the search
    functionality.
  </p>
  </div>
+  </noscript>
+  
+  
  <p>
    Searching for multiple words only shows matches that contain
    all words.
  </p>
+  
+  
  <form action="" method="get">
-    <input type="text" name="q" aria-labelledby="search-documentation" value="" />
+    <input type="text" name="q" aria-labelledby="search-documentation" value="" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
    <input type="submit" value="search" />
    <span id="search-progress" style="padding-left: 10px"></span>
  </form>
  
+  
+  
  <div id="search-results">
  
  </div>
+  

          </div>
          
@@ -102,7 +111,7 @@
      &copy;2021, Rhet Turnbull.
      
      |
-      Powered by <a href="http://sphinx-doc.org/">Sphinx 3.5.2</a>
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 4.3.2</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
    </div>
--- a/docs/searchindex.js
+++ b/docs/searchindex.js
--- a/examples/album_sort_order.py
+++ b/examples/album_sort_order.py
@@ -0,0 +1,112 @@
+""" Example function for use with osxphotos export --post-function option showing how to record album sort order """
+
+import os
+import pathlib
+from typing import Optional
+
+from osxphotos import ExportResults, PhotoInfo
+from osxphotos.albuminfo import AlbumInfo
+from osxphotos.path_utils import sanitize_dirname
+from osxphotos.phototemplate import RenderOptions
+
+
+def album_sequence(photo: PhotoInfo, options: RenderOptions, **kwargs) -> str:
+    """Call this with {function} template to get album sequence (sort order) when exporting with {folder_album} template
+
+    For example, calling this template function like the following prepends sequence#_ to each exported file if the file is in an album:
+
+    osxphotos export /path/to/export -V --directory "{folder_album}" --filename "{album?{function:examples/album_sort_order.py::album_sequence}_,}{original_name}"
+
+    The sequence will start at 0.  To change the sequence to start at a different offset (e.g. 1), set the environment variable OSXPHOTOS_ALBUM_SEQUENCE_START=1 (or whatever offset you want)
+    """
+    dest_path = options.dest_path
+    if not dest_path:
+        return ""
+
+    album_info = None
+    for album in photo.album_info:
+        # following code is how {folder_album} builds the folder path
+        folder = "/".join(sanitize_dirname(f) for f in album.folder_names)
+        folder += "/" + sanitize_dirname(album.title)
+        if dest_path.endswith(folder):
+            album_info = album
+            break
+    else:
+        # didn't find the album, so skip this file
+        return ""
+    start_index = int(os.getenv("OSXPHOTOS_ALBUM_SEQUENCE_START", 0))
+    return str(album_info.photo_index(photo) + start_index)
+
+
+def album_sort_order(
+    photo: PhotoInfo, results: ExportResults, verbose: callable, **kwargs
+):
+    """Call this with osxphotos export /path/to/export --post-function album_sort_order.py::album_sort_order
+        This will get called immediately after the photo has been exported
+
+    Args:
+        photo: PhotoInfo instance for the photo that's just been exported
+        results: ExportResults instance with information about the files associated with the exported photo
+        verbose: A function to print verbose output if --verbose is set; if --verbose is not set, acts as a no-op (nothing gets printed)
+        **kwargs: reserved for future use; recommend you include **kwargs so your function still works if additional arguments are added in future versions
+
+    Notes:
+        Use verbose(str) instead of print if you want your function to conditionally output text depending on --verbose flag
+        Any string printed with verbose that contains "warning" or "error" (case-insensitive) will be printed with the appropriate warning or error color
+        Will not be called if --dry-run flag is enabled
+        Will be called immediately after export and before any --post-command commands are executed
+    """
+
+    # ExportResults has the following properties
+    # fields with filenames contain the full path to the file
+    # exported: list of all files exported
+    # new: list of all new files exported (--update)
+    # updated: list of all files updated (--update)
+    # skipped: list of all files skipped (--update)
+    # exif_updated: list of all files that were updated with --exiftool
+    # touched: list of all files that had date updated with --touch-file
+    # converted_to_jpeg: list of files converted to jpeg with --convert-to-jpeg
+    # sidecar_json_written: list of all JSON sidecar files written
+    # sidecar_json_skipped: list of all JSON sidecar files skipped (--update)
+    # sidecar_exiftool_written: list of all exiftool sidecar files written
+    # sidecar_exiftool_skipped: list of all exiftool sidecar files skipped (--update)
+    # sidecar_xmp_written: list of all XMP sidecar files written
+    # sidecar_xmp_skipped: list of all XMP sidecar files skipped (--update)
+    # missing: list of all missing files
+    # error: list tuples of (filename, error) for any errors generated during export
+    # exiftool_warning: list of tuples of (filename, warning) for any warnings generated by exiftool with --exiftool
+    # exiftool_error: list of tuples of (filename, error) for any errors generated by exiftool with --exiftool
+    # xattr_written: list of files that had extended attributes written
+    # xattr_skipped: list of files that where extended attributes were skipped (--update)
+    # deleted_files: list of deleted files
+    # deleted_directories: list of deleted directories
+    # exported_album: list of tuples of (filename, album_name) for exported files added to album with --add-exported-to-album
+    # skipped_album: list of tuples of (filename, album_name) for skipped files added to album with --add-skipped-to-album
+    # missing_album: list of tuples of (filename, album_name) for missing files added to album with --add-missing-to-album
+
+    for filepath in results.exported:
+        # do your processing here
+        filepath = pathlib.Path(filepath)
+        album_dir = filepath.parent.name
+        if album_dir not in photo.albums:
+            return
+
+        # get the first album that matches this name of which the photo is a member
+        album_info = None
+        for album in photo.album_info:
+            if album.title == album_dir:
+                album_info = album
+                break
+        else:
+            # didn't find the album, so skip this file
+            return
+
+        try:
+            sort_order = album_info.photo_index(photo)
+        except ValueError:
+            # photo not in album, so skip this file
+            return
+
+        verbose(f"Sort order for {filepath} in album {album_dir} is {sort_order}")
+        with open(str(filepath) + "_sort_order.txt", "w") as f:
+            f.write(str(sort_order))
--- a/examples/export_template.py
+++ b/examples/export_template.py
@@ -0,0 +1,173 @@
+""" Example showing how to use a custom function for osxphotos {function} template 
+    to export photos in a folder structure similar to Photos' own structure
+
+    Use:  osxphotos export /path/to/export --directory "{function:/path/to/export_template.py::photos_folders}"
+
+    This will likely export multiple copies of each photo.  If using APFS file system, this should be
+    a non-issue as osxphotos will use copy-on-write so each exported photo doesn't take up additional space
+    unless you edit the photo.
+
+    Thank-you @mkirkland4874 for the inspiration for this example!
+
+    This will produce output similar to this:
+
+Library
+- Photos
+-- {created.year}
+---- {created.mm}
+------ {created.dd}
+- Favorites
+- Hidden
+- Recently Deleted
+- People
+- Places
+- Imports
+Media Types
+- Videos
+- Selfies
+- Portrait
+- Panoramas
+- Time-lapse
+- Slow-mo
+- Bursts
+- Screenshots
+My Albums
+-- Album 1
+-- Album 2
+-- Folder 1
+---- Album 3
+Shared Albums
+-- Shared Album 1
+-- Shared Album 2
+"""
+
+from typing import List, Union
+
+import osxphotos
+from osxphotos._constants import _UNKNOWN_PERSON
+from osxphotos.datetime_formatter import DateTimeFormatter
+from osxphotos.path_utils import sanitize_dirname
+from osxphotos.phototemplate import RenderOptions
+
+
+def place_folder(photo: osxphotos.PhotoInfo) -> str:
+    """Return places as folder in format Country/State/City/etc."""
+    if not photo.place:
+        return ""
+
+    places = []
+    if photo.place.names.country:
+        places.append(photo.place.names.country[0])
+
+    if photo.place.names.state_province:
+        places.append(photo.place.names.state_province[0])
+
+    if photo.place.names.sub_administrative_area:
+        places.append(photo.place.names.sub_administrative_area[0])
+
+    if photo.place.names.additional_city_info:
+        places.append(photo.place.names.additional_city_info[0])
+
+    if photo.place.names.area_of_interest:
+        places.append(photo.place.names.area_of_interest[0])
+
+    if places:
+        return "Library/Places/" + "/".join(sanitize_dirname(place) for place in places)
+    else:
+        return ""
+
+
+def photos_folders(photo: osxphotos.PhotoInfo, options: osxphotos.phototemplate.RenderOptions, **kwargs) -> Union[List, str]:
+    """template function for use with --directory to export photos in a folder structure similar to Photos
+
+    Args:
+        photo: osxphotos.PhotoInfo object
+        options: RenderOptions instance
+        **kwargs: not currently used, placeholder to keep functions compatible with possible changes to {function}
+
+    Returns: list of directories for each photo
+
+    """
+
+    rendered_date, _ = photo.render_template("{created.year}/{created.mm}/{created.dd}")
+    date_path = rendered_date[0]
+
+    def add_date_path(path):
+        """add date path (year/mm/dd)"""
+        return f"{path}/{date_path}"
+
+    # Library
+
+    directories = []
+    if not photo.hidden and not photo.intrash and not photo.shared:
+        # set directories to [Library/Photos/year/mm/dd]
+        # render_template returns a tuple of [rendered value(s)], [unmatched]
+        # here, we can ignore the unmatched value, assigned to _, as we know template will match
+        directories, _ = photo.render_template(
+            "Library/Photos/{created.year}/{created.mm}/{created.dd}"
+        )
+
+    if photo.favorite:
+        directories.append(add_date_path("Library/Favorites"))
+    if photo.hidden:
+        directories.append(add_date_path("Library/Hidden"))
+    if photo.intrash:
+        directories.append(add_date_path("Library/Recently Deleted"))
+
+    directories.extend(
+        [
+            add_date_path(f"Library/People/{person}")
+            for person in photo.persons
+            if person != _UNKNOWN_PERSON
+        ]
+    )
+
+    if photo.place:
+        directories.append(add_date_path(place_folder(photo)))
+
+    if photo.import_info:
+        dt = DateTimeFormatter(photo.import_info.creation_date)
+        directories.append(f"Library/Imports/{dt.year}/{dt.mm}/{dt.dd}")
+
+    # Media Types
+
+    if photo.ismovie:
+        directories.append(add_date_path("Media Types/Videos"))
+    if photo.selfie:
+        directories.append(add_date_path("Media Types/Selfies"))
+    if photo.live_photo:
+        directories.append(add_date_path("Media Types/Live Photos"))
+    if photo.portrait:
+        directories.append(add_date_path("Media Types/Portrait"))
+    if photo.panorama:
+        directories.append(add_date_path("Media Types/Panoramas"))
+    if photo.time_lapse:
+        directories.append(add_date_path("Media Types/Time-lapse"))
+    if photo.slow_mo:
+        directories.append(add_date_path("Media Types/Slo-mo"))
+    if photo.burst:
+        directories.append(add_date_path("Media Types/Bursts"))
+    if photo.screenshot:
+        directories.append(add_date_path("Media Types/Screenshots"))
+
+    # Albums
+
+    # render the folders and albums in folder/subfolder/album format
+    # the __NO_ALBUM__ is used as a sentinel to strip out photos not in an album
+    # use RenderOptions.dirname to force the rendered folder_album value to be sanitized as a valid path
+    # use RenderOptions.none_str to specify custom value for any photo that doesn't belong to an album so
+    # those can be filtered out; if not specified, none_str is "_"
+    folder_albums, _ = photo.render_template(
+        "{folder_album}", RenderOptions(dirname=True, none_str="__NO_ALBUM__")
+    )
+
+    root_directory = "Shared Albums/" if photo.shared else "My Albums/"
+    directories.extend(
+        [
+            root_directory + folder_album
+            for folder_album in folder_albums
+            if folder_album != "__NO_ALBUM__"
+        ]
+    )
+
+    return directories
--- a/examples/post_function.py
+++ b/examples/post_function.py
@@ -0,0 +1,54 @@
+""" Example function for use with osxphotos export --post-function option """
+
+from osxphotos import PhotoInfo, ExportResults
+
+
+def post_function(
+    photo: PhotoInfo, results: ExportResults, verbose: callable, **kwargs
+):
+    """Call this with osxphotos export /path/to/export --post-function post_function.py::post_function
+        This will get called immediately after the photo has been exported
+
+    Args:
+        photo: PhotoInfo instance for the photo that's just been exported
+        results: ExportResults instance with information about the files associated with the exported photo
+        verbose: A function to print verbose output if --verbose is set; if --verbose is not set, acts as a no-op (nothing gets printed)
+        **kwargs: reserved for future use; recommend you include **kwargs so your function still works if additional arguments are added in future versions
+
+    Notes:
+        Use verbose(str) instead of print if you want your function to conditionally output text depending on --verbose flag
+        Any string printed with verbose that contains "warning" or "error" (case-insensitive) will be printed with the appropriate warning or error color
+        Will not be called if --dry-run flag is enabled
+        Will be called immediately after export and before any --post-command commands are executed
+    """
+
+    # ExportResults has the following properties
+    # fields with filenames contain the full path to the file
+    # exported: list of all files exported
+    # new: list of all new files exported (--update)
+    # updated: list of all files updated (--update)
+    # skipped: list of all files skipped (--update)
+    # exif_updated: list of all files that were updated with --exiftool
+    # touched: list of all files that had date updated with --touch-file
+    # converted_to_jpeg: list of files converted to jpeg with --convert-to-jpeg
+    # sidecar_json_written: list of all JSON sidecar files written
+    # sidecar_json_skipped: list of all JSON sidecar files skipped (--update)
+    # sidecar_exiftool_written: list of all exiftool sidecar files written
+    # sidecar_exiftool_skipped: list of all exiftool sidecar files skipped (--update)
+    # sidecar_xmp_written: list of all XMP sidecar files written
+    # sidecar_xmp_skipped: list of all XMP sidecar files skipped (--update)
+    # missing: list of all missing files
+    # error: list tuples of (filename, error) for any errors generated during export
+    # exiftool_warning: list of tuples of (filename, warning) for any warnings generated by exiftool with --exiftool
+    # exiftool_error: list of tuples of (filename, error) for any errors generated by exiftool with --exiftool
+    # xattr_written: list of files that had extended attributes written
+    # xattr_skipped: list of files that where extended attributes were skipped (--update)
+    # deleted_files: list of deleted files
+    # deleted_directories: list of deleted directories
+    # exported_album: list of tuples of (filename, album_name) for exported files added to album with --add-exported-to-album
+    # skipped_album: list of tuples of (filename, album_name) for skipped files added to album with --add-skipped-to-album
+    # missing_album: list of tuples of (filename, album_name) for missing files added to album with --add-missing-to-album
+
+    for filename in results.exported:
+        # do your processing here
+        verbose(f"post_function: {photo.original_filename} exported as {filename}")
--- a/examples/query_function.py
+++ b/examples/query_function.py
@@ -0,0 +1,31 @@
+""" example function for osxphotos --query-function """
+
+from typing import List
+
+from osxphotos import PhotoInfo
+
+
+# call this with --query-function examples/query_function.py::best_selfies
+def best_selfies(photos: List[PhotoInfo]) -> List[PhotoInfo]:
+    """your query function should take a list of PhotoInfo objects and return a list of PhotoInfo objects (or empty list)"""
+    # this example finds your best selfie for every year
+
+    # get list of selfies sorted by date
+    photos = sorted([p for p in photos if p.selfie], key=lambda p: p.date)
+    if not photos:
+        return []
+
+    start_year = photos[0].date.year
+    stop_year = photos[-1].date.year
+    best_selfies = []
+    for year in range(start_year, stop_year + 1):
+        # find best selfie each year as determined by overall aesthetic score
+        selfies = sorted(
+            [p for p in photos if p.date.year == year],
+            key=lambda p: p.score.overall,
+            reverse=True,
+        )
+        if selfies:
+            best_selfies.append(selfies[0])
+
+    return best_selfies
--- a/osxphotos.spec
+++ b/osxphotos.spec
@@ -8,41 +8,50 @@ import importlib
 pathex = os.getcwd()

 # include necessary data files
-datas=[('osxphotos/templates/xmp_sidecar.mako', 'osxphotos/templates'), ('osxphotos/templates/xmp_sidecar_beta.mako', 'osxphotos/templates'), ('osxphotos/phototemplate.tx', 'osxphotos'), ('osxphotos/phototemplate.md', 'osxphotos')]
-package_imports = [['photoscript', ['photoscript.applescript']]]
+datas = [
+    ("osxphotos/templates/xmp_sidecar.mako", "osxphotos/templates"),
+    ("osxphotos/templates/xmp_sidecar_beta.mako", "osxphotos/templates"),
+    ("osxphotos/phototemplate.tx", "osxphotos"),
+    ("osxphotos/phototemplate.md", "osxphotos"),
+    ("osxphotos/tutorial.md", "osxphotos"),
+]
+package_imports = [["photoscript", ["photoscript.applescript"]]]
 for package, files in package_imports:
    proot = os.path.dirname(importlib.import_module(package).__file__)
    datas.extend((os.path.join(proot, f), package) for f in files)

 block_cipher = None

-a = Analysis(['cli.py'],
-             pathex=[pathex],
-             binaries=[],
-             datas=datas,
-             hiddenimports=['pkg_resources.py2_warn'],
-             hookspath=[],
-             runtime_hooks=[],
-             excludes=[],
-             win_no_prefer_redirects=False,
-             win_private_assemblies=False,
-             cipher=block_cipher,
-             noarchive=False)
+a = Analysis(
+    ["cli.py"],
+    pathex=[pathex],
+    binaries=[],
+    datas=datas,
+    hiddenimports=["pkg_resources.py2_warn"],
+    hookspath=[],
+    runtime_hooks=[],
+    excludes=[],
+    win_no_prefer_redirects=False,
+    win_private_assemblies=False,
+    cipher=block_cipher,
+    noarchive=False,
+)

-pyz = PYZ(a.pure, a.zipped_data,
-             cipher=block_cipher)
+pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)

-exe = EXE(pyz,
-          a.scripts,
-          a.binaries,
-          a.zipfiles,
-          a.datas,
-          [],
-          name='osxphotos',
-          debug=False,
-          bootloader_ignore_signals=False,
-          strip=False,
-          upx=True,
-          upx_exclude=[],
-          runtime_tmpdir=None,
-          console=True )
+exe = EXE(
+    pyz,
+    a.scripts,
+    a.binaries,
+    a.zipfiles,
+    a.datas,
+    [],
+    name="osxphotos",
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    runtime_tmpdir=None,
+    console=True,
+)
--- a/osxphotos/init.py
+++ b/osxphotos/init.py
@@ -1,5 +1,7 @@
+from ._constants import AlbumSortOrder
 from ._version import __version__
-from .photoinfo import PhotoInfo
+from .exiftool import ExifTool
+from .photoinfo import ExportResults, PhotoInfo
 from .photosdb import PhotosDB
 from .photosdb._photosdb_process_comments import CommentInfo, LikeInfo
 from .phototemplate import PhotoTemplate
@@ -7,5 +9,4 @@ from .queryoptions import QueryOptions
 from .utils import _debug, _get_logger, _set_debug

 # TODO: Add test for imageTimeZoneOffsetSeconds = None
-# TODO: Add test for __str__ and to_json
 # TODO: Add special albums and magic albums
--- a/osxphotos/_applescript/init.py
+++ b/osxphotos/_applescript/init.py
@@ -1,162 +0,0 @@
-""" applescript -- Easy-to-use Python wrapper for NSAppleScript """
-
-import sys
-
-from Foundation import NSAppleScript, NSAppleEventDescriptor, NSURL, \
-		NSAppleScriptErrorMessage, NSAppleScriptErrorBriefMessage, \
-		NSAppleScriptErrorNumber, NSAppleScriptErrorAppName, NSAppleScriptErrorRange
-
-from .aecodecs import Codecs, fourcharcode, AEType, AEEnum
-from . import kae
-
-__all__ = ['AppleScript', 'ScriptError', 'AEType', 'AEEnum', 'kMissingValue', 'kae']
-
-
-######################################################################
-
-
-class AppleScript:
-	""" Represents a compiled AppleScript. The script object is persistent; its handlers may be called multiple times and its top-level properties will retain current state until the script object's disposal.
-	
-	
-	"""
-
-	_codecs = Codecs()
-	
-	def __init__(self, source=None, path=None):
-		"""
-			source : str | None -- AppleScript source code
-			path : str | None -- full path to .scpt/.applescript file
-			
-			Notes:
-			
-			- Either the path or the source argument must be provided.
-			
-			- If the script cannot be read/compiled, a ScriptError is raised.
-		"""
-		if path:
-			url = NSURL.fileURLWithPath_(path)
-			self._script, errorinfo = NSAppleScript.alloc().initWithContentsOfURL_error_(url, None)
-			if errorinfo:
-				raise ScriptError(errorinfo)
-		elif source:
-			self._script = NSAppleScript.alloc().initWithSource_(source)
-		else:
-			raise ValueError("Missing source or path argument.")
-		if not self._script.isCompiled():
-			errorinfo = self._script.compileAndReturnError_(None)[1]
-			if errorinfo:
-				raise ScriptError(errorinfo)
-	
-	def __repr__(self):
-		s = self.source
-		return 'AppleScript({})'.format(repr(s) if len(s) < 100 else '{}...{}'.format(repr(s)[:80], repr(s)[-17:]))
-	
-	##
-	
-	def _newevent(self, suite, code, args):
-		evt = NSAppleEventDescriptor.appleEventWithEventClass_eventID_targetDescriptor_returnID_transactionID_(
-						fourcharcode(suite), fourcharcode(code), NSAppleEventDescriptor.nullDescriptor(), 0, 0)
-		evt.setDescriptor_forKeyword_(self._codecs.pack(args), fourcharcode(kae.keyDirectObject))
-		return evt
-	
-	def _unpackresult(self, result, errorinfo):
-		if not result:
-			raise ScriptError(errorinfo)
-		return self._codecs.unpack(result)
-
-	##
-	
-	source = property(lambda self: str(self._script.source()), doc="str -- the script's source code")
-	
-	def run(self, *args):
-		""" Run the script, optionally passing arguments to its run handler.
-			
-				args : anything -- arguments to pass to script, if any; see also supported type mappings documentation
-				Result : anything | None -- the script's return value, if any
-			
-			Notes:
-			
-			- The run handler must be explicitly declared in order to pass arguments.
-			
-			- AppleScript will ignore excess arguments. Passing insufficient arguments will result in an error.
-			
-			- If execution fails, a ScriptError is raised.
-		"""
-		if args:
-			evt = self._newevent(kae.kCoreEventClass, kae.kAEOpenApplication, args)
-			return self._unpackresult(*self._script.executeAppleEvent_error_(evt, None))
-		else:
-			return self._unpackresult(*self._script.executeAndReturnError_(None))
-	
-	def call(self, name, *args):
-		""" Call the specified user-defined handler.
-				
-				name : str -- the handler's name (case-sensitive)
-				args : anything -- arguments to pass to script, if any; see documentation for supported types
-				Result : anything | None -- the script's return value, if any
-			
-			Notes:
-			
-			- The handler's name must be a user-defined identifier, not an AppleScript keyword; e.g. 'myCount' is acceptable; 'count' is not.
-			
-			- AppleScript will ignore excess arguments. Passing insufficient arguments will result in an error.
-			
-			- If execution fails, a ScriptError is raised.
-		"""
-		evt = self._newevent(kae.kASAppleScriptSuite, kae.kASPrepositionalSubroutine, args)
-		evt.setDescriptor_forKeyword_(NSAppleEventDescriptor.descriptorWithString_(name), 
-						fourcharcode(kae.keyASSubroutineName))
-		return self._unpackresult(*self._script.executeAppleEvent_error_(evt, None))
-
-
-##
-
-
-class ScriptError(Exception):
-	""" Indicates an AppleScript compilation/execution error. """
-	
-	def __init__(self, errorinfo):
-		self._errorinfo = dict(errorinfo)
-	
-	def __repr__(self):
-		return 'ScriptError({})'.format(self._errorinfo)
-	
-	@property
-	def message(self):
-		""" str -- the error message """
-		msg = self._errorinfo.get(NSAppleScriptErrorMessage)
-		if not msg:
-			msg = self._errorinfo.get(NSAppleScriptErrorBriefMessage, 'Script Error')
-		return msg
-	
-	number = property(lambda self: self._errorinfo.get(NSAppleScriptErrorNumber),
-			doc="int | None -- the error number, if given")
-	
-	appname = property(lambda self: self._errorinfo.get(NSAppleScriptErrorAppName),
-			doc="str | None -- the name of the application that reported the error, where relevant")
-	
-	@property
-	def range(self):
-		""" (int, int) -- the start and end points (1-indexed) within the source code where the error occurred """
-		range = self._errorinfo.get(NSAppleScriptErrorRange)
-		if range:
-			start = range.rangeValue().location
-			end = start + range.rangeValue().length
-			return (start, end)
-		else:
-			return None
-	
-	def __str__(self):
-		msg = self.message
-		for s, v in [(' ({})', self.number), (' app={!r}', self.appname), (' range={0[0]}-{0[1]}', self.range)]:
-			if v is not None:
-				msg += s.format(v)
-		return msg.encode('ascii', 'replace') if sys.version_info.major < 3 else msg # 2.7 compatibility
-
-
-##
-
-
-kMissingValue = AEType(kae.cMissingValue) # convenience constant
-
--- a/osxphotos/_applescript/aecodecs.py
+++ b/osxphotos/_applescript/aecodecs.py
@@ -1,269 +0,0 @@
-""" aecodecs -- Convert from common Python types to Apple Event Manager types and vice-versa. """
-
-import datetime, struct, sys
-
-from Foundation import NSAppleEventDescriptor, NSURL
-
-from . import kae
-
-
-__all__ = ['Codecs', 'AEType', 'AEEnum']
-
-
-######################################################################
-
-
-def fourcharcode(code):
-	""" Convert four-char code for use in NSAppleEventDescriptor methods.
-		
-		code : bytes -- four-char code, e.g. b'utxt'
-		Result : int -- OSType, e.g. 1970567284
-	"""
-	return struct.unpack('>I', code)[0]
-
-
-#######
-
-
-class Codecs:
-	""" Implements mappings for common Python types with direct AppleScript equivalents. Used by AppleScript class. """
-
-	kMacEpoch = datetime.datetime(1904, 1, 1)
-	kUSRF = fourcharcode(kae.keyASUserRecordFields)
-
-	def __init__(self):
-		# Clients may add/remove/replace encoder and decoder items:
-		self.encoders = {
-				NSAppleEventDescriptor.class__(): self.packdesc,
-				type(None): self.packnone,
-				bool: self.packbool,
-				int: self.packint,
-				float: self.packfloat,
-				bytes: self.packbytes,
-				str: self.packstr,
-				list: self.packlist,
-				tuple: self.packlist,
-				dict: self.packdict,
-				datetime.datetime: self.packdatetime,
-				AEType: self.packtype,
-				AEEnum: self.packenum,
-		}
-		if sys.version_info.major < 3: # 2.7 compatibility
-			self.encoders[unicode] = self.packstr
-		
-		self.decoders = {fourcharcode(k): v for k, v in {
-				kae.typeNull: self.unpacknull,
-				kae.typeBoolean: self.unpackboolean,
-				kae.typeFalse: self.unpackboolean,
-				kae.typeTrue: self.unpackboolean,
-				kae.typeSInt32: self.unpacksint32,
-				kae.typeIEEE64BitFloatingPoint: self.unpackfloat64,
-				kae.typeUTF8Text: self.unpackunicodetext,
-				kae.typeUTF16ExternalRepresentation: self.unpackunicodetext,
-				kae.typeUnicodeText: self.unpackunicodetext,
-				kae.typeLongDateTime: self.unpacklongdatetime,
-				kae.typeAEList: self.unpackaelist,
-				kae.typeAERecord: self.unpackaerecord,
-				kae.typeAlias: self.unpackfile,
-				kae.typeFSS: self.unpackfile,
-				kae.typeFSRef: self.unpackfile,
-				kae.typeFileURL: self.unpackfile,
-				kae.typeType: self.unpacktype,
-				kae.typeEnumeration: self.unpackenumeration,
-		}.items()}
-	
-	def pack(self, data):
-		"""Pack Python data.
-			data : anything -- a Python value
-			Result : NSAppleEventDescriptor -- an AE descriptor, or error if no encoder exists for this type of data
-		"""
-		try:
-			return self.encoders[data.__class__](data) # quick lookup by type/class
-		except (KeyError, AttributeError) as e:
-			for type, encoder in self.encoders.items(): # slower but more thorough lookup that can handle subtypes/subclasses
-				if isinstance(data, type):
-					return encoder(data)
-		raise TypeError("Can't pack data into an AEDesc (unsupported type): {!r}".format(data))
-	
-	def unpack(self, desc):
-		"""Unpack an Apple event descriptor.
-			desc : NSAppleEventDescriptor
-			Result : anything -- a Python value, or the original NSAppleEventDescriptor if no decoder is found
-		"""
-		decoder = self.decoders.get(desc.descriptorType())
-		# unpack known type
-		if decoder:
-			return decoder(desc)
-		# if it's a record-like desc, unpack as dict with an extra AEType(b'pcls') key containing the desc type
-		rec = desc.coerceToDescriptorType_(fourcharcode(kae.typeAERecord))
-		if rec:
-			rec = self.unpackaerecord(rec)
-			rec[AEType(kae.pClass)] = AEType(struct.pack('>I', desc.descriptorType()))
-			return rec
-		# return as-is
-		return desc
-	
-	##
-	
-	def _packbytes(self, desctype, data):
-		return NSAppleEventDescriptor.descriptorWithDescriptorType_bytes_length_(
-			fourcharcode(desctype), data, len(data))
-	
-	def packdesc(self, val):
-		return val
-	
-	def packnone(self, val):
-		return NSAppleEventDescriptor.nullDescriptor()
-	
-	def packbool(self, val):
-		return NSAppleEventDescriptor.descriptorWithBoolean_(int(val))
-	
-	def packint(self, val):
-		if (-2**31) <= val < (2**31):
-			return NSAppleEventDescriptor.descriptorWithInt32_(val)
-		else:
-			return self.pack(float(val))
-	
-	def packfloat(self, val):
-		return self._packbytes(kae.typeFloat, struct.pack('d', val))
-	
-	def packbytes(self, val):
-		return self._packbytes(kae.typeData, val)
-	
-	def packstr(self, val):
-		return NSAppleEventDescriptor.descriptorWithString_(val)
-	
-	def packdatetime(self, val):
-		delta = val - self.kMacEpoch
-		sec = delta.days * 3600 * 24 + delta.seconds
-		return self._packbytes(kae.typeLongDateTime, struct.pack('q', sec))
-	
-	def packlist(self, val):
-		lst = NSAppleEventDescriptor.listDescriptor()
-		for item in val:
-			lst.insertDescriptor_atIndex_(self.pack(item), 0)
-		return lst
-	
-	def packdict(self, val):
-		record = NSAppleEventDescriptor.recordDescriptor()
-		usrf = desctype = None
-		for key, value in val.items():
-			if isinstance(key, AEType):
-				if key.code == kae.pClass and isinstance(value, AEType): # AS packs records that contain a 'class' property by coercing the packed record to the descriptor type specified by the property's value (assuming it's an AEType)
-					desctype = value
-				else:
-					record.setDescriptor_forKeyword_(self.pack(value), fourcharcode(key.code))
-			else:
-				if not usrf:
-					usrf = NSAppleEventDescriptor.listDescriptor()
-				usrf.insertDescriptor_atIndex_(self.pack(key), 0)
-				usrf.insertDescriptor_atIndex_(self.pack(value), 0)
-		if usrf:
-			record.setDescriptor_forKeyword_(usrf, self.kUSRF)
-		if desctype:
-			newrecord = record.coerceToDescriptorType_(fourcharcode(desctype.code))
-			if newrecord:
-				record = newrecord
-			else: # coercion failed for some reason, so pack as normal key-value pair
-				record.setDescriptor_forKeyword_(self.pack(desctype), fourcharcode(key.code))
-		return record
-	
-	def packtype(self, val):
-		return NSAppleEventDescriptor.descriptorWithTypeCode_(fourcharcode(val.code))
-	
-	def packenum(self, val): 
-		return NSAppleEventDescriptor.descriptorWithEnumCode_(fourcharcode(val.code))
-	
-	#######
-	
-	def unpacknull(self, desc):
-		return None
-	
-	def unpackboolean(self, desc):
-		return desc.booleanValue()
-	
-	def unpacksint32(self, desc):
-		return desc.int32Value()
-	
-	def unpackfloat64(self, desc):
-		return struct.unpack('d', bytes(desc.data()))[0]
-	
-	def unpackunicodetext(self, desc):
-		return desc.stringValue()
-	
-	def unpacklongdatetime(self, desc):
-		return self.kMacEpoch + datetime.timedelta(seconds=struct.unpack('q', bytes(desc.data()))[0])
-	
-	def unpackaelist(self, desc):
-		return [self.unpack(desc.descriptorAtIndex_(i + 1)) for i in range(desc.numberOfItems())]
-	
-	def unpackaerecord(self, desc):
-		dct = {}
-		for i in range(desc.numberOfItems()):
-			key = desc.keywordForDescriptorAtIndex_(i + 1)
-			value = desc.descriptorForKeyword_(key)
-			if key == self.kUSRF:
-				lst = self.unpackaelist(value)
-				for i in range(0, len(lst), 2):
-					dct[lst[i]] = lst[i+1]
-			else:
-				dct[AEType(struct.pack('>I', key))] = self.unpack(value)
-		return dct
-	
-	def unpacktype(self, desc):
-		return AEType(struct.pack('>I', desc.typeCodeValue()))
-	
-	def unpackenumeration(self, desc):
-		return AEEnum(struct.pack('>I', desc.enumCodeValue()))
-	
-	def unpackfile(self, desc):
-		url = bytes(desc.coerceToDescriptorType_(fourcharcode(kae.typeFileURL)).data()).decode('utf8')
-		return NSURL.URLWithString_(url).path()
-
-
-#######
-
-
-class AETypeBase:
-	""" Base class for AEType and AEEnum.
-	
-		Notes:
-		
-		- Hashable and comparable, so may be used as keys in dictionaries that map to AE records.
-	"""
-	
-	def __init__(self, code):
-		"""
-			code : bytes -- four-char code, e.g. b'utxt'
-		"""
-		if not isinstance(code, bytes):
-			raise TypeError('invalid code (not a bytes object): {!r}'.format(code))
-		elif len(code) != 4:
-			raise ValueError('invalid code (not four bytes long): {!r}'.format(code))
-		self._code = code
-	
-	code = property(lambda self:self._code, doc="bytes -- four-char code, e.g. b'utxt'")
-	
-	def __hash__(self): 
-		return hash(self._code)
-	
-	def __eq__(self, val):
-		return val.__class__ == self.__class__ and val.code == self._code
-	
-	def __ne__(self, val):
-		return not self == val
-		
-	def __repr__(self):
-		return "{}({!r})".format(self.__class__.__name__, self._code)
-
-
-##
-
-
-class AEType(AETypeBase):
-	"""An AE type. Maps to an AppleScript type class, e.g. AEType(b'utxt') <=> 'unicode text'."""
-
-
-class AEEnum(AETypeBase):
-	"""An AE enumeration. Maps to an AppleScript constant, e.g. AEEnum(b'yes ') <=> 'yes'."""
-
--- a/osxphotos/_applescript/kae.py
+++ b/osxphotos/_applescript/kae.py
--- a/osxphotos/_constants.py
+++ b/osxphotos/_constants.py
@@ -4,6 +4,7 @@ Constants used by osxphotos

 import os.path
 from datetime import datetime
+from enum import Enum

 OSXPHOTOS_URL = "https://github.com/RhetTbull/osxphotos"

@@ -29,16 +30,19 @@ _TESTED_DB_VERSIONS = ["6000", "4025", "4016", "3301", "2622"]
 # Photos 6 (10.16.0 Beta) == 14104
 _TEST_MODEL_VERSIONS = ["13537", "13703", "14104"]

+_PHOTOS_2_VERSION = "2622"
+
 # only version 3 - 4 have RKVersion.selfPortrait
 _PHOTOS_3_VERSION = "3301"

 # versions 5.0 and later have a different database structure
 _PHOTOS_4_VERSION = "4025"  # latest Mojove version on 10.14.6
-_PHOTOS_5_VERSION = "6000"  # seems to be current on 10.15.1 through 10.15.6
+_PHOTOS_5_VERSION = "6000"  # seems to be current on 10.15.1 through 10.15.7 (also Big Sur and Monterey which switch to model version)

 # Ranges for model version by Photos version
 _PHOTOS_5_MODEL_VERSION = [13000, 13999]
 _PHOTOS_6_MODEL_VERSION = [14000, 14999]
+_PHOTOS_7_MODEL_VERSION = [15000, 15999]  # Monterey developer preview is 15134

 # some table names differ between Photos 5 and Photos 6
 _DB_TABLE_NAMES = {
@@ -49,6 +53,10 @@ _DB_TABLE_NAMES = {
        "ALBUM_SORT_ORDER": "Z_26ASSETS.Z_FOK_34ASSETS",
        "IMPORT_FOK": "ZGENERICASSET.Z_FOK_IMPORTSESSION",
        "DEPTH_STATE": "ZGENERICASSET.ZDEPTHSTATES",
+        "UTI_ORIGINAL": "ZINTERNALRESOURCE.ZUNIFORMTYPEIDENTIFIER",
+        "ASSET_ALBUM_JOIN": "Z_26ASSETS.Z_26ALBUMS",
+        "ASSET_ALBUM_TABLE": "Z_26ASSETS",
+        "HDR_TYPE": "ZCUSTOMRENDEREDVALUE",
    },
    6: {
        "ASSET": "ZASSET",
@@ -57,6 +65,22 @@ _DB_TABLE_NAMES = {
        "ALBUM_SORT_ORDER": "Z_26ASSETS.Z_FOK_3ASSETS",
        "IMPORT_FOK": "null",
        "DEPTH_STATE": "ZASSET.ZDEPTHTYPE",
+        "UTI_ORIGINAL": "ZINTERNALRESOURCE.ZUNIFORMTYPEIDENTIFIER",
+        "ASSET_ALBUM_JOIN": "Z_26ASSETS.Z_26ALBUMS",
+        "ASSET_ALBUM_TABLE": "Z_26ASSETS",
+        "HDR_TYPE": "ZCUSTOMRENDEREDVALUE",
+    },
+    7: {
+        "ASSET": "ZASSET",
+        "KEYWORD_JOIN": "Z_1KEYWORDS.Z_38KEYWORDS",
+        "ALBUM_JOIN": "Z_27ASSETS.Z_3ASSETS",
+        "ALBUM_SORT_ORDER": "Z_27ASSETS.Z_FOK_3ASSETS",
+        "IMPORT_FOK": "null",
+        "DEPTH_STATE": "ZASSET.ZDEPTHTYPE",
+        "UTI_ORIGINAL": "ZINTERNALRESOURCE.ZCOMPACTUTI",
+        "ASSET_ALBUM_JOIN": "Z_27ASSETS.Z_27ALBUMS",
+        "ASSET_ALBUM_TABLE": "Z_27ASSETS",
+        "HDR_TYPE": "ZHDRTYPE",
    },
 }

@@ -71,6 +95,9 @@ _TESTED_OS_VERSIONS = [
    ("11", "1"),
    ("11", "2"),
    ("11", "3"),
+    ("11", "4"),
+    ("11", "5"),
+    ("11", "6"),
 ]

 # Photos 5 has persons who are empty string if unidentified face
@@ -188,6 +215,9 @@ DEFAULT_EDITED_SUFFIX = "_edited"
 # Default suffix to add to original images
 DEFAULT_ORIGINAL_SUFFIX = ""

+# Default suffix to add to preview images
+DEFAULT_PREVIEW_SUFFIX = "_preview"
+
 # Colors for print CLI messages
 CLI_COLOR_ERROR = "red"
 CLI_COLOR_WARNING = "yellow"
@@ -202,10 +232,17 @@ EXTENDED_ATTRIBUTE_NAMES = [
    "authors",
    "comment",
    "copyright",
+    "creator",
    "description",
    "findercomment",
    "headline",
    "keywords",
+    "participants",
+    "projects",
+    "rating",
+    "subject",
+    "title",
+    "version",
 ]
 EXTENDED_ATTRIBUTE_NAMES_QUOTED = [f"'{x}'" for x in EXTENDED_ATTRIBUTE_NAMES]

@@ -214,12 +251,43 @@ OSXPHOTOS_EXPORT_DB = ".osxphotos_export.db"

 # bit flags for burst images ("burstPickType")
 BURST_NOT_SELECTED = 0b10  # 2: burst image is not selected
-BURST_DEFAULT_PICK = (
-    0b100
-)  # 4: burst image is the one Photos picked to be key image before any selections made
+BURST_DEFAULT_PICK = 0b100  # 4: burst image is the one Photos picked to be key image before any selections made
 BURST_SELECTED = 0b1000  # 8: burst image is selected
 BURST_KEY = 0b10000  # 16: burst image is the key photo (top of burst stack)
-BURST_UNKNOWN = (
-    0b100000
-)  # 32: this is almost always set with BURST_DEFAULT_PICK and never if BURST_DEFAULT_PICK is not set.  I think this has something to do with what algorithm Photos used to pick the default image
+BURST_UNKNOWN = 0b100000  # 32: this is almost always set with BURST_DEFAULT_PICK and never if BURST_DEFAULT_PICK is not set.  I think this has something to do with what algorithm Photos used to pick the default image

+LIVE_VIDEO_EXTENSIONS = [".mov"]
+
+# categories that --post-command can be used with; these map to ExportResults fields
+POST_COMMAND_CATEGORIES = {
+    "exported": "All exported files",
+    "new": "When used with '--update', all newly exported files",
+    "updated": "When used with '--update', all files which were previously exported but updated this time",
+    "skipped": "When used with '--update', all files which were skipped (because they were previously exported and didn't change)",
+    "missing": "All files which were not exported because they were missing from the Photos library",
+    "exif_updated": "When used with '--exiftool', all files on which exiftool updated the metadata",
+    "touched": "When used with '--touch-file', all files where the date was touched",
+    "converted_to_jpeg": "When used with '--convert-to-jpeg', all files which were converted to jpeg",
+    "sidecar_json_written": "When used with '--sidecar json', all JSON sidecar files which were written",
+    "sidecar_json_skipped": "When used with '--sidecar json' and '--update', all JSON sidecar files which were skipped",
+    "sidecar_exiftool_written": "When used with '--sidecar exiftool', all exiftool sidecar files which were written",
+    "sidecar_exiftool_skipped": "When used with '--sidecar exiftool' and '--update, all exiftool sidecar files which were skipped",
+    "sidecar_xmp_written": "When used with '--sidecar xmp', all XMP sidecar files which were written",
+    "sidecar_xmp_skipped": "When used with '--sidecar xmp' and '--update', all XMP sidecar files which were skipped",
+    "error": "All files which produced an error during export",
+    # "deleted_files": "When used with '--cleanup', all files deleted during the export",
+    # "deleted_directories": "When used with '--cleanup', all directories deleted during the export",
+}
+
+
+class AlbumSortOrder(Enum):
+    """Album Sort Order"""
+
+    UNKNOWN = 0
+    MANUAL = 1
+    NEWEST_FIRST = 2
+    OLDEST_FIRST = 3
+    TITLE = 5
+
+
+TEXT_DETECTION_CONFIDENCE_THRESHOLD = 0.75
--- a/osxphotos/_version.py
+++ b/osxphotos/_version.py
@@ -1,3 +1,3 @@
 """ version info """

-__version__ = "0.42.26"
+__version__ = "0.43.8"
--- a/osxphotos/albuminfo.py
+++ b/osxphotos/albuminfo.py
@@ -19,21 +19,23 @@ from ._constants import (
    _PHOTOS_5_ALBUM_KIND,
    _PHOTOS_5_FOLDER_KIND,
    TIME_DELTA,
+    AlbumSortOrder,
 )
 from .datetime_utils import get_local_tz
+from .query_builder import get_query


 def sort_list_by_keys(values, sort_keys):
-    """ Sorts list values by a second list sort_keys
+    """Sorts list values by a second list sort_keys
        e.g. given ["a","c","b"], [1, 3, 2], returns ["a", "b", "c"]

    Args:
        values: a list of values to be sorted
        sort_keys: a list of keys to sort values by
-    
+
    Returns:
        list of values, sorted by sort_keys
-    
+
    Raises:
        ValueError: raised if len(values) != len(sort_keys)
    """
@@ -63,12 +65,12 @@ class AlbumInfoBaseClass:

    @property
    def uuid(self):
-        """ return uuid of album """
+        """return uuid of album"""
        return self._uuid

    @property
    def creation_date(self):
-        """ return creation date of album """
+        """return creation date of album"""
        try:
            return self._creation_date
        except AttributeError:
@@ -90,8 +92,8 @@ class AlbumInfoBaseClass:

    @property
    def start_date(self):
-        """ For Albums, return start date (earliest image) of album or None for albums with no images
-            For Import Sessions, return start date of import session (when import began) """
+        """For Albums, return start date (earliest image) of album or None for albums with no images
+        For Import Sessions, return start date of import session (when import began)"""
        try:
            return self._start_date
        except AttributeError:
@@ -109,8 +111,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 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)"""
        try:
            return self._end_date
        except AttributeError:
@@ -130,8 +132,30 @@ class AlbumInfoBaseClass:
    def photos(self):
        return []

+    @property
+    def owner(self):
+        """Return name of photo owner for shared album (Photos 5+ only), or None if not shared"""
+        if self._db._db_version <= _PHOTOS_4_VERSION:
+            return None
+
+        try:
+            return self._owner
+        except AttributeError:
+            try:
+                personid = self._db._dbalbum_details[self.uuid][
+                    "cloudownerhashedpersonid"
+                ]
+                self._owner = (
+                    self._db._db_hashed_person_id[personid]["full_name"]
+                    if personid
+                    else None
+                )
+            except KeyError:
+                self._owner = None
+            return self._owner
+
    def __len__(self):
-        """ return number of photos contained in album """
+        """return number of photos contained in album"""
        return len(self.photos)


@@ -144,29 +168,39 @@ class AlbumInfo(AlbumInfoBaseClass):

    @property
    def title(self):
-        """ return title / name of album """
+        """return title / name of album"""
        return self._title

    @property
    def photos(self):
-        """ return list of photos contained in album sorted in same sort order as Photos """
+        """return list of photos contained in album sorted in same sort order as Photos"""
        try:
            return self._photos
        except AttributeError:
            if self.uuid in self._db._dbalbums_album:
                uuid, sort_order = zip(*self._db._dbalbums_album[self.uuid])
                sorted_uuid = sort_list_by_keys(uuid, sort_order)
-                self._photos = self._db.photos_by_uuid(sorted_uuid)
+                photos = self._db.photos_by_uuid(sorted_uuid)
+                sort_order = self.sort_order
+                if sort_order == AlbumSortOrder.NEWEST_FIRST:
+                    self._photos = sorted(photos, key=lambda p: p.date, reverse=True)
+                elif sort_order == AlbumSortOrder.OLDEST_FIRST:
+                    self._photos = sorted(photos, key=lambda p: p.date)
+                elif sort_order == AlbumSortOrder.TITLE:
+                    self._photos = sorted(photos, key=lambda p: p.title or "")
+                else:
+                    # assume AlbumSortOrder.MANUAL
+                    self._photos = photos
            else:
                self._photos = []
            return self._photos

    @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", ...]
-            returns empty list if album is not in any folders """
+        """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"""

        try:
            return self._folder_names
@@ -176,10 +210,10 @@ 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 """
+        """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"""

        try:
            return self._folders
@@ -189,7 +223,7 @@ class AlbumInfo(AlbumInfoBaseClass):

    @property
    def parent(self):
-        """ returns FolderInfo object for parent folder or None if no parent (e.g. top-level album) """
+        """returns FolderInfo object for parent folder or None if no parent (e.g. top-level album)"""
        try:
            return self._parent
        except AttributeError:
@@ -209,11 +243,44 @@ class AlbumInfo(AlbumInfoBaseClass):
                )
            return self._parent

+    @property
+    def sort_order(self):
+        """return sort order of album"""
+        if self._db._db_version <= _PHOTOS_4_VERSION:
+            return AlbumSortOrder.MANUAL
+
+        details = self._db._dbalbum_details[self._uuid]
+        if details["customsortkey"] == 1:
+            if details["customsortascending"] == 0:
+                return AlbumSortOrder.NEWEST_FIRST
+            elif details["customsortascending"] == 1:
+                return AlbumSortOrder.OLDEST_FIRST
+            else:
+                return AlbumSortOrder.UNKNOWN
+        elif details["customsortkey"] == 5:
+            return AlbumSortOrder.TITLE
+        elif details["customsortkey"] == 0:
+            return AlbumSortOrder.MANUAL
+        else:
+            return AlbumSortOrder.UNKNOWN
+
+    def photo_index(self, photo):
+        """return index of photo in album (based on album sort order)"""
+        index = 0
+        for p in self.photos:
+            if p.uuid == photo.uuid:
+                return index
+            index += 1
+        else:
+            raise ValueError(
+                f"Photo with uuid {photo.uuid} does not appear to be in this album"
+            )
+

 class ImportInfo(AlbumInfoBaseClass):
    @property
    def photos(self):
-        """ return list of photos contained in import session """
+        """return list of photos contained in import session"""
        try:
            return self._photos
        except AttributeError:
@@ -231,7 +298,7 @@ class ImportInfo(AlbumInfoBaseClass):

 class FolderInfo:
    """
-    Info about a specific folder, contains all the details about the folder 
+    Info about a specific folder, contains all the details about the folder
    including folders, albums, etc
    """

@@ -247,17 +314,17 @@ class FolderInfo:

    @property
    def title(self):
-        """ return title / name of folder"""
+        """return title / name of folder"""
        return self._title

    @property
    def uuid(self):
-        """ return uuid of folder """
+        """return uuid of folder"""
        return self._uuid

    @property
    def album_info(self):
-        """ return list of albums (as AlbumInfo objects) contained in the folder """
+        """return list of albums (as AlbumInfo objects) contained in the folder"""
        try:
            return self._albums
        except AttributeError:
@@ -282,7 +349,7 @@ class FolderInfo:

    @property
    def parent(self):
-        """ returns FolderInfo object for parent or None if no parent (e.g. top-level folder) """
+        """returns FolderInfo object for parent or None if no parent (e.g. top-level folder)"""
        try:
            return self._parent
        except AttributeError:
@@ -304,7 +371,7 @@ class FolderInfo:

    @property
    def subfolders(self):
-        """ return list of folders (as FolderInfo objects) contained in the folder """
+        """return list of folders (as FolderInfo objects) contained in the folder"""
        try:
            return self._folders
        except AttributeError:
@@ -328,5 +395,5 @@ class FolderInfo:
            return self._folders

    def __len__(self):
-        """ returns count of folders + albums contained in the folder """
+        """returns count of folders + albums contained in the folder"""
        return len(self.subfolders) + len(self.album_info)
--- a/osxphotos/cli.py
+++ b/osxphotos/cli.py
--- a/osxphotos/cli_help.py
+++ b/osxphotos/cli_help.py
@@ -1,6 +1,7 @@
 """Help text helper class for osxphotos CLI """

 import io
+import pathlib
 import re

 import click
@@ -12,16 +13,19 @@ from ._constants import (
    EXTENDED_ATTRIBUTE_NAMES,
    EXTENDED_ATTRIBUTE_NAMES_QUOTED,
    OSXPHOTOS_EXPORT_DB,
+    POST_COMMAND_CATEGORIES,
 )
 from .phototemplate import (
    TEMPLATE_SUBSTITUTIONS,
    TEMPLATE_SUBSTITUTIONS_MULTI_VALUED,
+    TEMPLATE_SUBSTITUTIONS_PATHLIB,
    get_template_help,
 )


+# TODO: The following help text could probably be done as mako template
 class ExportCommand(click.Command):
-    """ Custom click.Command that overrides get_help() to show additional help info for export """
+    """Custom click.Command that overrides get_help() to show additional help info for export"""

    def get_help(self, ctx):
        help_text = super().get_help(ctx)
@@ -65,7 +69,9 @@ class ExportCommand(click.Command):
            + f"rebuilding the '{OSXPHOTOS_EXPORT_DB}' database."
        )
        formatter.write("\n\n")
-        formatter.write(rich_text("[bold]** Extended Attributes **[/bold]", width=formatter.width))
+        formatter.write(
+            rich_text("[bold]** Extended Attributes **[/bold]", width=formatter.width)
+        )
        formatter.write("\n")
        formatter.write_text(
            """
@@ -99,7 +105,9 @@ The following attributes may be used with '--xattr-template':
            "For additional information on extended attributes see: https://developer.apple.com/documentation/coreservices/file_metadata/mditem/common_metadata_attribute_keys"
        )
        formatter.write("\n\n")
-        formatter.write(rich_text("[bold]** Templating System **[/bold]", width=formatter.width))
+        formatter.write(
+            rich_text("[bold]** Templating System **[/bold]", width=formatter.width)
+        )
        formatter.write("\n")
        formatter.write(template_help(width=formatter.width))
        formatter.write("\n")
@@ -128,7 +136,11 @@ The following attributes may be used with '--xattr-template':
            + "an error and the script will abort."
        )
        formatter.write("\n")
-        formatter.write(rich_text("[bold]** Template Substitutions **[/bold]", width=formatter.width))
+        formatter.write(
+            rich_text(
+                "[bold]** Template Substitutions **[/bold]", width=formatter.width
+            )
+        )
        formatter.write("\n")
        templ_tuples = [("Substitution", "Description")]
        templ_tuples.extend((k, v) for k, v in TEMPLATE_SUBSTITUTIONS.items())
@@ -151,21 +163,127 @@ The following attributes may be used with '--xattr-template':
        )

        formatter.write_dl(templ_tuples)
+
+        formatter.write("\n")
+        formatter.write_text(
+            "The following substitutions are file or directory paths. "
+            + "You can access various parts of the path using the following modifiers:"
+        )
+        formatter.write("\n")
+        formatter.write("{path.parent}: the parent directory\n")
+        formatter.write("{path.name}: the name of the file or final sub-directory\n")
+        formatter.write("{path.stem}: the name of the file without the extension\n")
+        formatter.write(
+            "{path.suffix}: the suffix of the file including the leading '.'\n"
+        )
+        formatter.write("\n")
+        formatter.write(
+            "For example, if the field {export_dir} is '/Shared/Backup/Photos':\n"
+        )
+        formatter.write("{export_dir.parent} is '/Shared/Backup'\n")
+        formatter.write("\n")
+        formatter.write(
+            "If the field {filepath} is '/Shared/Backup/Photos/IMG_1234.JPG':\n"
+        )
+        formatter.write("{filepath.parent} is '/Shared/Backup/Photos'\n")
+        formatter.write("{filepath.name} is 'IMG_1234.JPG'\n")
+        formatter.write("{filepath.stem} is 'IMG_1234'\n")
+        formatter.write("{filepath.suffix} is '.JPG'\n")
+        formatter.write("\n")
+        templ_tuples = [("Substitution", "Description")]
+        templ_tuples.extend((k, v) for k, v in TEMPLATE_SUBSTITUTIONS_PATHLIB.items())
+
+        formatter.write_dl(templ_tuples)
+
+        formatter.write("\n\n")
+        formatter.write(
+            rich_text("[bold]** Post Command **[/bold]", width=formatter.width)
+        )
+        formatter.write_text(
+            "You can run commands on the exported photos for post-processing "
+            + "using the '--post-command' option. '--post-command' is passed a CATEGORY and a COMMAND. "
+            + "COMMAND is an osxphotos template string which will be rendered and passed to the shell "
+            + "for execution. CATEGORY is the category of file to pass to COMMAND. "
+            + "The following categories are available: "
+        )
+        formatter.write("\n")
+        templ_tuples = [("Category", "Description")]
+        templ_tuples.extend((k, v) for k, v in POST_COMMAND_CATEGORIES.items())
+        formatter.write_dl(templ_tuples)
+        formatter.write("\n")
+        formatter.write_text(
+            "In addition to all normal template fields, the template fields "
+            + "'{filepath}' and '{export_dir}' will be available to your command template. "
+            + "Both of these are path-type templates which means their various parts can be accessed using "
+            + "the available properties, e.g. '{filepath.name}' provides just the file name without path "
+            + "and '{filepath.suffix}' is the file extension (suffix) of the file. "
+            + "When using paths in your command template, it is important to properly quote the paths "
+            + "as they will be passed to the shell and path names may contain spaces. "
+            + "Both the '{shell_quote}' template and the '|shell_quote' template filter are available for "
+            + "this purpose.  For example, the following command outputs the full path of newly exported files to file 'new.txt': "
+        )
+        formatter.write("\n")
+        formatter.write(
+            '--post-command new "echo {filepath|shell_quote} >> {shell_quote,{export_dir}/exported.txt}"'
+        )
+        formatter.write("\n\n")
+        formatter.write_text(
+            "In the above command, the 'shell_quote' filter is used to ensure '{filepath}' is properly quoted "
+            + "and the '{shell_quote}' template ensures the constructed path of '{exported_dir}/exported.txt' is properly quoted. "
+            "If '{filepath}' is 'IMG 1234.jpeg' and '{export_dir}' is '/Volumes/Photo Export', the command "
+            "thus renders to: "
+        )
+        formatter.write("\n")
+        formatter.write("echo 'IMG 1234.jpeg' >> '/Volumes/Photo Export/exported.txt'")
+        formatter.write("\n\n")
+        formatter.write_text(
+            "It is highly recommended that you run osxphotos with '--dry-run --verbose' "
+            + "first to ensure your commands are as expected. This will not actually run the commands but will "
+            + "print out the exact command string which would be executed."
+        )
+        formatter.write("\n\n")
+        formatter.write(
+            rich_text("[bold]** Post Function **[/bold]", width=formatter.width)
+        )
+        formatter.write_text(
+            "You can run your own python functions on the exported photos for post-processing "
+            + "using the '--post-function' option. '--post-function' is passed the name a python file "
+            + "and the name of the function in the file to call using format 'filename.py::function_name'. "
+            + "See the example function at https://github.com/RhetTbull/osxphotos/blob/master/examples/post_function.py "
+            + "You may specify multiple functions to run by repeating the --post-function option. "
+            + "All post functions will be called immediately after export of each photo and immediately before any --post-command commands. "
+            + "Post functions will not be called if the --dry-run flag is set."
+        )
+        formatter.write("\n")
+
        help_text += formatter.getvalue()
        return help_text


 def template_help(width=78):
-    """Return formatted string for template system """
+    """Return formatted string for template system"""
    sio = io.StringIO()
    console = Console(file=sio, force_terminal=True, width=width)
-    template_help_md = strip_md_links(get_template_help())
+    template_help_md = strip_md_header_and_links(get_template_help())
    console.print(Markdown(template_help_md))
    help_str = sio.getvalue()
    sio.close()
    return help_str


+def tutorial_help(width=78):
+    """Return formatted string for tutorial"""
+    sio = io.StringIO()
+    console = Console(file=sio, force_terminal=True, width=width)
+    help_md = get_tutorial_text()
+    help_md = strip_html_comments(help_md)
+    help_md = strip_md_links(help_md)
+    console.print(Markdown(help_md))
+    help_str = sio.getvalue()
+    sio.close()
+    return help_str
+
+
 def rich_text(text, width=78):
    """Return rich formatted text"""
    sio = io.StringIO()
@@ -176,16 +294,16 @@ def rich_text(text, width=78):
    return rich_text


-def strip_md_links(md):
-    """strip markdown links from markdown text md
-    
+def strip_md_header_and_links(md):
+    """strip markdown headers and links from markdown text md
+
    Args:
        md: str, markdown text
-    
-    Returns:
-        str with markdown links removed

-    Note: This uses a very basic regex that likely fails on all sorts of edge cases 
+    Returns:
+        str with markdown headers and links removed
+
+    Note: This uses a very basic regex that likely fails on all sorts of edge cases
    but works for the links in the osxphotos docs
    """
    links = r"(?:[*#])|\[(.*?)\]\(.+?\)"
@@ -195,3 +313,36 @@ def strip_md_links(md):

    return re.sub(links, subfn, md)

+
+def strip_md_links(md):
+    """strip markdown links from markdown text md
+
+    Args:
+        md: str, markdown text
+
+    Returns:
+        str with markdown links removed
+
+    Note: This uses a very basic regex that likely fails on all sorts of edge cases
+    but works for the links in the osxphotos docs
+    """
+    links = r"\[(.*?)\]\(.+?\)"
+
+    def subfn(match):
+        return match.group(1)
+
+    return re.sub(links, subfn, md)
+
+
+def strip_html_comments(text):
+    """Strip html comments from text (which doesn't need to be valid HTML)"""
+    return re.sub(r"<!--(.|\s|\n)*?-->", "", text)
+
+
+def get_tutorial_text():
+    """Load tutorial text from file"""
+    # TODO: would be better to use importlib.abc.ResourceReader but I can't find a single example of how to do this
+    help_file = pathlib.Path(__file__).parent / "tutorial.md"
+    with open(help_file, "r") as fd:
+        md = fd.read()
+    return md
--- a/osxphotos/exiftool.py
+++ b/osxphotos/exiftool.py
@@ -7,6 +7,7 @@
    pyexiftool: https://github.com/smarnach/pyexiftool which provides more functionality """

 import atexit
+import html
 import json
 import logging
 import os
@@ -24,16 +25,34 @@ EXIFTOOL_STAYOPEN_EOF_LEN = len(EXIFTOOL_STAYOPEN_EOF)
 EXIFTOOL_PROCESSES = []


+def escape_str(s):
+    """escape string for use with exiftool -E"""
+    if type(s) != str:
+        return s
+    s = html.escape(s)
+    s = s.replace("\n", "&#xa;")
+    s = s.replace("\t", "&#x9;")
+    s = s.replace("\r", "&#xd;")
+    return s
+
+
+def unescape_str(s):
+    """unescape an HTML string returned by exiftool -E"""
+    if type(s) != str:
+        return s
+    return html.unescape(s)
+
+
@atexit.register
 def terminate_exiftool():
-    """Terminate any running ExifTool subprocesses; call this to cleanup when done using ExifTool """
+    """Terminate any running ExifTool subprocesses; call this to cleanup when done using ExifTool"""
    for proc in EXIFTOOL_PROCESSES:
        proc._stop_proc()


@lru_cache(maxsize=1)
 def get_exiftool_path():
-    """ return path of exiftool, cache result """
+    """return path of exiftool, cache result"""
    exiftool_path = shutil.which("exiftool")
    if exiftool_path:
        return exiftool_path.rstrip()
@@ -49,7 +68,7 @@ class _ExifToolProc:
    Creates a singleton object"""

    def __new__(cls, *args, **kwargs):
-        """ create new object or return instance of already created singleton """
+        """create new object or return instance of already created singleton"""
        if not hasattr(cls, "instance") or not cls.instance:
            cls.instance = super().__new__(cls)

@@ -74,7 +93,7 @@ class _ExifToolProc:

    @property
    def process(self):
-        """ return the exiftool subprocess """
+        """return the exiftool subprocess"""
        if self._process_running:
            return self._process
        else:
@@ -83,16 +102,16 @@ class _ExifToolProc:

    @property
    def pid(self):
-        """ return process id (PID) of the exiftool process """
+        """return process id (PID) of the exiftool process"""
        return self._process.pid

    @property
    def exiftool(self):
-        """ return path to exiftool process """
+        """return path to exiftool process"""
        return self._exiftool

    def _start_proc(self):
-        """ start exiftool in batch mode """
+        """start exiftool in batch mode"""

        if self._process_running:
            logging.warning("exiftool already running: {self._process}")
@@ -110,6 +129,7 @@ class _ExifToolProc:
                "-n",  # no print conversion (e.g. print tag values in machine readable format)
                "-P",  # Preserve file modification date/time
                "-G",  # print group name for each tag
+                "-E",  # escape tag values for HTML (allows use of HTML &#xa; for newlines)
            ],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
@@ -120,7 +140,7 @@ class _ExifToolProc:
        EXIFTOOL_PROCESSES.append(self)

    def _stop_proc(self):
-        """ stop the exiftool process if it's running, otherwise, do nothing """
+        """stop the exiftool process if it's running, otherwise, do nothing"""

        if not self._process_running:
            return
@@ -143,7 +163,7 @@ class _ExifToolProc:


 class ExifTool:
-    """ Basic exiftool interface for reading and writing EXIF tags """
+    """Basic exiftool interface for reading and writing EXIF tags"""

    def __init__(self, filepath, exiftool=None, overwrite=True, flags=None):
        """Create ExifTool object
@@ -189,6 +209,7 @@ class ExifTool:

        if value is None:
            value = ""
+        value = escape_str(value)
        command = [f"-{tag}={value}"]
        if self.overwrite and not self._context_mgr:
            command.append("-overwrite_original")
@@ -233,6 +254,7 @@ class ExifTool:
        for value in values:
            if value is None:
                raise ValueError("Can't add None value to tag")
+            value = escape_str(value)
            command.append(f"-{tag}+={value}")

        if self.overwrite and not self._context_mgr:
@@ -315,12 +337,12 @@ class ExifTool:

    @property
    def pid(self):
-        """ return process id (PID) of the exiftool process """
+        """return process id (PID) of the exiftool process"""
        return self._process.pid

    @property
    def version(self):
-        """ returns exiftool version """
+        """returns exiftool version"""
        ver, _, _ = self.run_commands("-ver", no_file=True)
        return ver.decode("utf-8")

@@ -335,6 +357,7 @@ class ExifTool:
        json_str, _, _ = self.run_commands("-json")
        if not json_str:
            return dict()
+        json_str = unescape_str(json_str.decode("utf-8"))

        try:
            exifdict = json.loads(json_str)
@@ -342,7 +365,6 @@ class ExifTool:
            # will fail with some commands, e.g --ext AVI which produces
            # 'No file with specified extension' instead of json
            return dict()
-
        exifdict = exifdict[0]
        if not tag_groups:
            # strip tag groups
@@ -358,12 +380,13 @@ class ExifTool:
        return exifdict

    def json(self):
-        """ returns JSON string containing all EXIF tags and values from exiftool """
+        """returns JSON string containing all EXIF tags and values from exiftool"""
        json, _, _ = self.run_commands("-json")
+        json = unescape_str(json.decode("utf-8"))
        return json

    def _read_exif(self):
-        """ read exif data from file """
+        """read exif data from file"""
        data = self.asdict()
        self.data = {k: v for k, v in data.items()}

@@ -384,15 +407,15 @@ class ExifTool:


 class ExifToolCaching(ExifTool):
-    """ Basic exiftool interface for reading and writing EXIF tags, with caching. 
-        Use this only when you know the file's EXIF data will not be changed by any external process. 
-        
-        Creates a singleton cached ExifTool instance """
+    """Basic exiftool interface for reading and writing EXIF tags, with caching.
+    Use this only when you know the file's EXIF data will not be changed by any external process.
+
+    Creates a singleton cached ExifTool instance"""

    _singletons = {}

    def __new__(cls, filepath, exiftool=None):
-        """ create new object or return instance of already created singleton """
+        """create new object or return instance of already created singleton"""
        if filepath not in cls._singletons:
            cls._singletons[filepath] = _ExifToolCaching(filepath, exiftool=exiftool)
        return cls._singletons[filepath]
@@ -448,7 +471,6 @@ class _ExifToolCaching(ExifTool):
            return self._asdict_cache[tag_groups][normalized]

    def flush_cache(self):
-        """ Clear cached data so that calls to json or asdict return fresh data """
+        """Clear cached data so that calls to json or asdict return fresh data"""
        self._json_cache = None
        self._asdict_cache = {}
-
--- a/osxphotos/export_db.py
+++ b/osxphotos/export_db.py
@@ -1,6 +1,4 @@
-""" Helper class for managing a database used by 
-    PhotoInfo.export for tracking state of exports and updates
-"""
+""" Helper class for managing a database used by PhotoInfo.export for tracking state of exports and updates """

 import datetime
 import logging
@@ -12,13 +10,15 @@ from abc import ABC, abstractmethod
 from io import StringIO
 from sqlite3 import Error

+from ._constants import OSXPHOTOS_EXPORT_DB
 from ._version import __version__

-OSXPHOTOS_EXPORTDB_VERSION = "3.2"
+OSXPHOTOS_EXPORTDB_VERSION = "4.0"
+OSXPHOTOS_ABOUT_STRING = f"Created by osxphotos version {__version__} (https://github.com/RhetTbull/osxphotos) on {str(datetime.datetime.now())}"


 class ExportDB_ABC(ABC):
-    """ abstract base class for ExportDB """
+    """abstract base class for ExportDB"""

    @abstractmethod
    def get_uuid_for_file(self, filename):
@@ -88,6 +88,14 @@ class ExportDB_ABC(ABC):
    def get_previous_uuids(self):
        pass

+    @abstractmethod
+    def get_detected_text_for_uuid(self, uuid):
+        pass
+
+    @abstractmethod
+    def set_detected_text_for_uuid(self, uuid, json_text):
+        pass
+
    @abstractmethod
    def set_data(
        self,
@@ -104,7 +112,7 @@ class ExportDB_ABC(ABC):


 class ExportDBNoOp(ExportDB_ABC):
-    """ An ExportDB with NoOp methods """
+    """An ExportDB with NoOp methods"""

    def __init__(self):
        self.was_created = True
@@ -162,6 +170,12 @@ class ExportDBNoOp(ExportDB_ABC):
    def get_previous_uuids(self):
        return []

+    def get_detected_text_for_uuid(self, uuid):
+        return None 
+
+    def set_detected_text_for_uuid(self, uuid, json_text):
+        pass
+
    def set_data(
        self,
        filename,
@@ -177,23 +191,23 @@ class ExportDBNoOp(ExportDB_ABC):


 class ExportDB(ExportDB_ABC):
-    """ Interface to sqlite3 database used to store state information for osxphotos export command """
+    """Interface to sqlite3 database used to store state information for osxphotos export command"""

    def __init__(self, dbfile):
-        """ dbfile: path to osxphotos export database file """
+        """dbfile: path to osxphotos export database file"""
        self._dbfile = dbfile
        # _path is parent of the database
        # all files referenced by get_/set_uuid_for_file will be converted to
        # relative paths to this parent _path
        # this allows the entire export tree to be moved to a new disk/location
-        # whilst preserving the UUID to filename mappping
+        # whilst preserving the UUID to filename mapping
        self._path = pathlib.Path(dbfile).parent
        self._conn = self._open_export_db(dbfile)
        self._insert_run_info()

    def get_uuid_for_file(self, filename):
-        """ query database for filename and return UUID
-            returns None if filename not found in database
+        """query database for filename and return UUID
+        returns None if filename not found in database
        """
        filename = str(pathlib.Path(filename).relative_to(self._path)).lower()
        conn = self._conn
@@ -211,7 +225,7 @@ class ExportDB(ExportDB_ABC):
        return uuid

    def set_uuid_for_file(self, filename, uuid):
-        """ set UUID of filename to uuid in the database """
+        """set UUID of filename to uuid in the database"""
        filename = str(pathlib.Path(filename).relative_to(self._path))
        filename_normalized = filename.lower()
        conn = self._conn
@@ -226,9 +240,9 @@ class ExportDB(ExportDB_ABC):
            logging.warning(e)

    def set_stat_orig_for_file(self, filename, stats):
-        """ set stat info for filename
-            filename: filename to set the stat info for
-            stat: a tuple of length 3: mode, size, mtime """
+        """set stat info for filename
+        filename: filename to set the stat info for
+        stat: a tuple of length 3: mode, size, mtime"""
        filename = str(pathlib.Path(filename).relative_to(self._path)).lower()
        if len(stats) != 3:
            raise ValueError(f"expected 3 elements for stat, got {len(stats)}")
@@ -247,8 +261,8 @@ class ExportDB(ExportDB_ABC):
            logging.warning(e)

    def get_stat_orig_for_file(self, filename):
-        """ get stat info for filename
-            returns: tuple of (mode, size, mtime) 
+        """get stat info for filename
+        returns: tuple of (mode, size, mtime)
        """
        filename = str(pathlib.Path(filename).relative_to(self._path)).lower()
        conn = self._conn
@@ -272,21 +286,21 @@ class ExportDB(ExportDB_ABC):
        return stats

    def set_stat_edited_for_file(self, filename, stats):
-        """ set stat info for edited version of image (in Photos' library)
-            filename: filename to set the stat info for
-            stat: a tuple of length 3: mode, size, mtime """
+        """set stat info for edited version of image (in Photos' library)
+        filename: filename to set the stat info for
+        stat: a tuple of length 3: mode, size, mtime"""
        return self._set_stat_for_file("edited", filename, stats)

    def get_stat_edited_for_file(self, filename):
-        """ get stat info for edited version of image (in Photos' library)
-            filename: filename to set the stat info for
-            stat: a tuple of length 3: mode, size, mtime """
+        """get stat info for edited version of image (in Photos' library)
+        filename: filename to set the stat info for
+        stat: a tuple of length 3: mode, size, mtime"""
        return self._get_stat_for_file("edited", filename)

    def set_stat_exif_for_file(self, filename, stats):
-        """ set stat info for filename (after exiftool has updated it)
-            filename: filename to set the stat info for
-            stat: a tuple of length 3: mode, size, mtime """
+        """set stat info for filename (after exiftool has updated it)
+        filename: filename to set the stat info for
+        stat: a tuple of length 3: mode, size, mtime"""
        filename = str(pathlib.Path(filename).relative_to(self._path)).lower()
        if len(stats) != 3:
            raise ValueError(f"expected 3 elements for stat, got {len(stats)}")
@@ -305,8 +319,8 @@ class ExportDB(ExportDB_ABC):
            logging.warning(e)

    def get_stat_exif_for_file(self, filename):
-        """ get stat info for filename (after exiftool has updated it)
-            returns: tuple of (mode, size, mtime) 
+        """get stat info for filename (after exiftool has updated it)
+        returns: tuple of (mode, size, mtime)
        """
        filename = str(pathlib.Path(filename).relative_to(self._path)).lower()
        conn = self._conn
@@ -330,19 +344,19 @@ class ExportDB(ExportDB_ABC):
        return stats

    def set_stat_converted_for_file(self, filename, stats):
-        """ set stat info for filename (after image converted to jpeg)
-            filename: filename to set the stat info for
-            stat: a tuple of length 3: mode, size, mtime """
+        """set stat info for filename (after image converted to jpeg)
+        filename: filename to set the stat info for
+        stat: a tuple of length 3: mode, size, mtime"""
        return self._set_stat_for_file("converted", filename, stats)

    def get_stat_converted_for_file(self, filename):
-        """ get stat info for filename (after jpeg conversion)
-            returns: tuple of (mode, size, mtime) 
+        """get stat info for filename (after jpeg conversion)
+        returns: tuple of (mode, size, mtime)
        """
        return self._get_stat_for_file("converted", filename)

    def get_info_for_uuid(self, uuid):
-        """ returns the info JSON struct for a UUID """
+        """returns the info JSON struct for a UUID"""
        conn = self._conn
        try:
            c = conn.cursor()
@@ -356,7 +370,7 @@ class ExportDB(ExportDB_ABC):
        return info

    def set_info_for_uuid(self, uuid, info):
-        """ sets the info JSON struct for a UUID """
+        """sets the info JSON struct for a UUID"""
        conn = self._conn
        try:
            c = conn.cursor()
@@ -369,7 +383,7 @@ class ExportDB(ExportDB_ABC):
            logging.warning(e)

    def get_exifdata_for_file(self, filename):
-        """ returns the exifdata JSON struct for a file """
+        """returns the exifdata JSON struct for a file"""
        filename = str(pathlib.Path(filename).relative_to(self._path)).lower()
        conn = self._conn
        try:
@@ -387,7 +401,7 @@ class ExportDB(ExportDB_ABC):
        return exifdata

    def set_exifdata_for_file(self, filename, exifdata):
-        """ sets the exifdata JSON struct for a file """
+        """sets the exifdata JSON struct for a file"""
        filename = str(pathlib.Path(filename).relative_to(self._path)).lower()
        conn = self._conn
        try:
@@ -401,7 +415,7 @@ class ExportDB(ExportDB_ABC):
            logging.warning(e)

    def get_sidecar_for_file(self, filename):
-        """ returns the sidecar data and signature for a file """
+        """returns the sidecar data and signature for a file"""
        filename = str(pathlib.Path(filename).relative_to(self._path)).lower()
        conn = self._conn
        try:
@@ -429,7 +443,7 @@ class ExportDB(ExportDB_ABC):
        return sidecar_data, sidecar_sig

    def set_sidecar_for_file(self, filename, sidecar_data, sidecar_sig):
-        """ sets the sidecar data and signature for a file """
+        """sets the sidecar data and signature for a file"""
        filename = str(pathlib.Path(filename).relative_to(self._path)).lower()
        conn = self._conn
        try:
@@ -443,7 +457,7 @@ class ExportDB(ExportDB_ABC):
            logging.warning(e)

    def get_previous_uuids(self):
-        """returns list of UUIDs of previously exported photos found in export database """
+        """returns list of UUIDs of previously exported photos found in export database"""
        conn = self._conn
        previous_uuids = []
        try:
@@ -455,6 +469,36 @@ class ExportDB(ExportDB_ABC):
            logging.warning(e)
        return previous_uuids

+    def get_detected_text_for_uuid(self, uuid):
+        """Get the detected_text for a uuid"""
+        conn = self._conn
+        try:
+            c = conn.cursor()
+            c.execute(
+                "SELECT text_data FROM detected_text WHERE uuid = ?",
+                (uuid,),
+            )
+            results = c.fetchone()
+            detected_text = results[0] if results else None
+        except Error as e:
+            logging.warning(e)
+            detected_text = None
+
+        return detected_text
+
+    def set_detected_text_for_uuid(self, uuid, text_json):
+        """Set the detected text for uuid"""
+        conn = self._conn
+        try:
+            c = conn.cursor()
+            c.execute(
+                "INSERT OR REPLACE INTO detected_text(uuid, text_data) VALUES (?, ?);",
+                (uuid, text_json,),
+            )
+            conn.commit()
+        except Error as e:
+            logging.warning(e)
+
    def set_data(
        self,
        filename,
@@ -466,8 +510,7 @@ class ExportDB(ExportDB_ABC):
        info_json,
        exif_json,
    ):
-        """ sets all the data for file and uuid at once 
-        """
+        """sets all the data for file and uuid at once"""
        filename = str(pathlib.Path(filename).relative_to(self._path))
        filename_normalized = filename.lower()
        conn = self._conn
@@ -510,7 +553,7 @@ class ExportDB(ExportDB_ABC):
            logging.warning(e)

    def close(self):
-        """ close the database connection """
+        """close the database connection"""
        try:
            self._conn.close()
        except Error as e:
@@ -548,9 +591,9 @@ class ExportDB(ExportDB_ABC):
        return stats

    def _open_export_db(self, dbfile):
-        """ open export database and return a db connection
-            if dbfile does not exist, will create and initialize the database 
-            returns: connection to the database 
+        """open export database and return a db connection
+        if dbfile does not exist, will create and initialize the database
+        returns: connection to the database
        """

        if not os.path.isfile(dbfile):
@@ -573,7 +616,7 @@ class ExportDB(ExportDB_ABC):
        return conn

    def _get_db_connection(self, dbfile):
-        """ return db connection to dbname """
+        """return db connection to dbname"""
        try:
            conn = sqlite3.connect(dbfile)
        except Error as e:
@@ -583,15 +626,15 @@ class ExportDB(ExportDB_ABC):
        return conn

    def _get_database_version(self, conn):
-        """ return tuple of (osxphotos, exportdb) versions for database connection conn """
+        """return tuple of (osxphotos, exportdb) versions for database connection conn"""
        version_info = conn.execute(
            "SELECT osxphotos, exportdb, max(id) FROM version"
        ).fetchone()
        return (version_info[0], version_info[1])

    def _create_db_tables(self, conn):
-        """ create (if not already created) the necessary db tables for the export database
-            conn: sqlite3 db connection 
+        """create (if not already created) the necessary db tables for the export database
+        conn: sqlite3 db connection
        """
        sql_commands = {
            "sql_version_table": """ CREATE TABLE IF NOT EXISTS version (
@@ -599,6 +642,10 @@ class ExportDB(ExportDB_ABC):
                                osxphotos TEXT,
                                exportdb TEXT 
                                ); """,
+            "sql_about_table": """ CREATE TABLE IF NOT EXISTS about (
+                                id INTEGER PRIMARY KEY,
+                                about TEXT
+                                );""",
            "sql_files_table": """ CREATE TABLE IF NOT EXISTS files (
                              id INTEGER PRIMARY KEY,
                              filepath TEXT NOT NULL,
@@ -651,12 +698,18 @@ class ExportDB(ExportDB_ABC):
                              size INTEGER,
                              mtime REAL
                              ); """,
+            "sql_detected_text_table": """ CREATE TABLE IF NOT EXISTS detected_text (
+                              id INTEGER PRIMARY KEY,
+                              uuid TEXT NOT NULL,
+                              text_data JSON
+                              ); """,
            "sql_files_idx": """ CREATE UNIQUE INDEX IF NOT EXISTS idx_files_filepath_normalized on files (filepath_normalized); """,
            "sql_info_idx": """ CREATE UNIQUE INDEX IF NOT EXISTS idx_info_uuid on info (uuid); """,
            "sql_exifdata_idx": """ CREATE UNIQUE INDEX IF NOT EXISTS idx_exifdata_filename on exifdata (filepath_normalized); """,
            "sql_edited_idx": """ CREATE UNIQUE INDEX IF NOT EXISTS idx_edited_filename on edited (filepath_normalized);""",
            "sql_converted_idx": """ CREATE UNIQUE INDEX IF NOT EXISTS idx_converted_filename on converted (filepath_normalized);""",
            "sql_sidecar_idx": """ CREATE UNIQUE INDEX IF NOT EXISTS idx_sidecar_filename on sidecar (filepath_normalized);""",
+            "sql_detected_text_idx": """ CREATE UNIQUE INDEX IF NOT EXISTS idx_detected_text on detected_text (uuid);""",
        }
        try:
            c = conn.cursor()
@@ -666,12 +719,13 @@ class ExportDB(ExportDB_ABC):
                "INSERT INTO version(osxphotos, exportdb) VALUES (?, ?);",
                (__version__, OSXPHOTOS_EXPORTDB_VERSION),
            )
+            c.execute("INSERT INTO about(about) VALUES (?);", (OSXPHOTOS_ABOUT_STRING,))
            conn.commit()
        except Error as e:
            logging.warning(e)

    def __del__(self):
-        """ ensure the database connection is closed """
+        """ensure the database connection is closed"""
        try:
            self._conn.close()
        except:
@@ -696,35 +750,33 @@ class ExportDB(ExportDB_ABC):


 class ExportDBInMemory(ExportDB):
-    """ In memory version of ExportDB
-        Copies the on-disk database into memory so it may be operated on without 
-        modifying the on-disk verison 
+    """In memory version of ExportDB
+    Copies the on-disk database into memory so it may be operated on without
+    modifying the on-disk version
    """

-    def init(self, dbfile):
-        self._dbfile = dbfile
+    def __init__(self, dbfile):
+        self._dbfile = dbfile or f"./{OSXPHOTOS_EXPORT_DB}"
        # _path is parent of the database
        # all files referenced by get_/set_uuid_for_file will be converted to
        # relative paths to this parent _path
        # this allows the entire export tree to be moved to a new disk/location
-        # whilst preserving the UUID to filename mappping
-        self._path = pathlib.Path(dbfile).parent
-        self._conn = self._open_export_db(dbfile)
+        # whilst preserving the UUID to filename mapping
+        self._path = pathlib.Path(self._dbfile).parent
+        self._conn = self._open_export_db(self._dbfile)
        self._insert_run_info()

    def _open_export_db(self, dbfile):
-        """ open export database and return a db connection
-            returns: connection to the database 
+        """open export database and return a db connection
+        returns: connection to the database
        """
        if not os.path.isfile(dbfile):
            conn = self._get_db_connection()
-            if conn:
-                self._create_db_tables(conn)
-                self.was_created = True
-                self.was_upgraded = ()
-                self.version = OSXPHOTOS_EXPORTDB_VERSION
-            else:
+            if not conn:
                raise Exception("Error getting connection to in-memory database")
+            self._create_db_tables(conn)
+            self.was_created = True
+            self.was_upgraded = ()
        else:
            try:
                conn = sqlite3.connect(dbfile)
@@ -749,12 +801,11 @@ class ExportDBInMemory(ExportDB):
                self.was_upgraded = (exportdb_ver, OSXPHOTOS_EXPORTDB_VERSION)
            else:
                self.was_upgraded = ()
-            self.version = OSXPHOTOS_EXPORTDB_VERSION
-
+        self.version = OSXPHOTOS_EXPORTDB_VERSION
        return conn

    def _get_db_connection(self):
-        """ return db connection to in memory database """
+        """return db connection to in memory database"""
        try:
            conn = sqlite3.connect(":memory:")
        except Error as e:
--- a/osxphotos/fileutil.py
+++ b/osxphotos/fileutil.py
@@ -7,7 +7,7 @@ import subprocess
 import sys
 from abc import ABC, abstractmethod

-import CoreFoundation
+import Foundation

 from .imageconverter import ImageConverter

@@ -114,7 +114,7 @@ class FileUtilMacOS(FileUtilABC):
        if dest.is_dir():
            dest /= src.name

-        filemgr = CoreFoundation.NSFileManager.defaultManager()
+        filemgr = Foundation.NSFileManager.defaultManager()
        error = filemgr.copyItemAtPath_toPath_error_(str(src), str(dest), None)
        # error is a tuple of (bool, error_string)
        # error[0] is True if copy succeeded
--- a/osxphotos/momentinfo.py
+++ b/osxphotos/momentinfo.py
@@ -0,0 +1,69 @@
+"""MomentInfo class with details about photo moments."""
+
+
+class MomentInfo:
+    """Info about a photo moment"""
+
+    def __init__(self, db, moment_pk):
+        """Initialize with a moment PK; returns None if PK not found."""
+        self._db = db
+        self._pk = moment_pk
+
+        self._moment = self._db._db_moment_pk.get(moment_pk)
+        if not self._moment:
+            raise ValueError(f"No moment with PK {moment_pk}")
+
+    @property
+    def pk(self):
+        """Primary key of the moment."""
+        return self._pk
+
+    @property
+    def location(self):
+        """Location of the moment."""
+        return (self._moment.get("latitude"), self._moment.get("longitude"))
+
+    @property
+    def title(self):
+        """Title of the moment."""
+        return self._moment.get("title")
+
+    @property
+    def subtitle(self):
+        """Subtitle of the moment."""
+        return self._moment.get("subtitle")
+
+    @property
+    def start_date(self):
+        """Start date of the moment."""
+        return self._moment.get("startDate")
+
+    @property
+    def end_date(self):
+        """Stop date of the moment."""
+        return self._moment.get("endDate")
+
+    @property
+    def date(self):
+        """Date of the moment."""
+        return self._moment.get("representativeDate")
+
+    @property
+    def modification_date(self):
+        """Modification date of the moment."""
+        return self._moment.get("modificationDate")
+
+    @property
+    def photos(self):
+        """All photos in this moment"""
+        try:
+            return self._photos
+        except AttributeError:
+            photo_uuids = [
+                uuid
+                for uuid, photo in self._db._dbphotos.items()
+                if photo["momentID"] == self._pk
+            ]
+
+            self._photos = self._db.photos_by_uuid(photo_uuids)
+            return self._photos
--- a/osxphotos/path_utils.py
+++ b/osxphotos/path_utils.py
@@ -6,22 +6,22 @@ from ._constants import MAX_DIRNAME_LEN, MAX_FILENAME_LEN


 def sanitize_filepath(filepath):
-    """ sanitize a filepath """
+    """sanitize a filepath"""
    return pathvalidate.sanitize_filepath(filepath, platform="macos")


 def is_valid_filepath(filepath):
-    """ returns True if a filepath is valid otherwise False """
+    """returns True if a filepath is valid otherwise False"""
    return pathvalidate.is_valid_filepath(filepath, platform="macos")


 def sanitize_filename(filename, replacement=":"):
-    """ replace any illegal characters in a filename and truncate filename if needed
+    """replace any illegal characters in a filename and truncate filename if needed

    Args:
        filename: str, filename to sanitze
        replacement: str, value to replace any illegal characters with; default = ":"
-    
+
    Returns:
        filename with any illegal characters replaced by replacement and truncated if necessary
    """
@@ -46,12 +46,12 @@ def sanitize_filename(filename, replacement=":"):


 def sanitize_dirname(dirname, replacement=":"):
-    """ replace any illegal characters in a directory name and truncate directory name if needed
+    """replace any illegal characters in a directory name and truncate directory name if needed

    Args:
-        dirname: str, directory name to sanitze
-        replacement: str, value to replace any illegal characters with; default = ":"
-    
+        dirname: str, directory name to sanitize
+        replacement: str, value to replace any illegal characters with; default = ":"; if None, no replacement occurs
+
    Returns:
        dirname with any illegal characters replaced by replacement and truncated if necessary
    """
@@ -61,19 +61,20 @@ def sanitize_dirname(dirname, replacement=":"):


 def sanitize_pathpart(pathpart, replacement=":"):
-    """ replace any illegal characters in a path part (either directory or filename without extension) and truncate name if needed
+    """replace any illegal characters in a path part (either directory or filename without extension) and truncate name if needed

    Args:
-        pathpart: str, path part to sanitze
-        replacement: str, value to replace any illegal characters with; default = ":"
-    
+        pathpart: str, path part to sanitize
+        replacement: str, value to replace any illegal characters with; default = ":"; if None, no replacement occurs
+
    Returns:
        pathpart with any illegal characters replaced by replacement and truncated if necessary
    """
    if pathpart:
-        pathpart = pathpart.replace("/", replacement)
+        pathpart = (
+            pathpart.replace("/", replacement) if replacement is not None else pathpart
+        )
        if len(pathpart) > MAX_DIRNAME_LEN:
            drop = len(pathpart) - MAX_DIRNAME_LEN
            pathpart = pathpart[:-drop]
    return pathpart
-
--- a/osxphotos/personinfo.py
+++ b/osxphotos/personinfo.py
@@ -141,7 +141,7 @@ class FaceInfo:
        self.manual = face["manual"]
        self.face_type = face["facetype"]
        self.age_type = face["agetype"]
-        self.bald_type = face["baldtype"]
+        # self.bald_type = face["baldtype"]
        self.eye_makeup_type = face["eyemakeuptype"]
        self.eye_state = face["eyestate"]
        self.facial_hair_type = face["facialhairtype"]
@@ -438,7 +438,7 @@ class FaceInfo:
            "manual": self.manual,
            "face_type": self.face_type,
            "age_type": self.age_type,
-            "bald_type": self.bald_type,
+            # "bald_type": self.bald_type,
            "eye_makeup_type": self.eye_makeup_type,
            "eye_state": self.eye_state,
            "facial_hair_type": self.facial_hair_type,
--- a/osxphotos/photoinfo/init.py
+++ b/osxphotos/photoinfo/init.py
@@ -7,4 +7,4 @@ PhotosDB.photos() returns a list of PhotoInfo objects
 from ._photoinfo_exifinfo import ExifInfo
 from ._photoinfo_export import ExportResults
 from ._photoinfo_scoreinfo import ScoreInfo
-from .photoinfo import PhotoInfo
+from .photoinfo import PhotoInfo, PhotoInfoNone
--- a/osxphotos/photoinfo/_photoinfo_export.py
+++ b/osxphotos/photoinfo/_photoinfo_export.py
--- a/osxphotos/photoinfo/photoinfo.py
+++ b/osxphotos/photoinfo/photoinfo.py
--- a/osxphotos/photokit.py
+++ b/osxphotos/photokit.py
@@ -6,8 +6,6 @@
 """

 # NOTES:
-# - This likely leaks memory like a sieve as I need to ensure all the
-#   Objective C objects are cleaned up.
 # - There are several techniques used for handling PhotoKit's various
 #   asynchronous calls used in this code: event loop+notification, threading
 #   event, while loop. I've experimented with each to find the one that works.
@@ -34,7 +32,8 @@ from Foundation import NSNotificationCenter, NSObject
 from PyObjCTools import AppHelper

 from .fileutil import FileUtil
-from .utils import _get_os_version, get_preferred_uti_extension, increment_filename
+from .uti import get_preferred_uti_extension
+from .utils import _get_os_version, increment_filename

 # NOTE: This requires user have granted access to the terminal (e.g. Terminal.app or iTerm)
 # to access Photos.  This should happen automatically the first time it's called. I've
@@ -64,7 +63,7 @@ MIN_SLEEP = 0.015

 ### utility functions
 def NSURL_to_path(url):
-    """ Convert URL string as represented by NSURL to a path string """
+    """Convert URL string as represented by NSURL to a path string"""
    nsurl = Foundation.NSURL.alloc().initWithString_(
        Foundation.NSString.alloc().initWithString_(str(url))
    )
@@ -74,7 +73,7 @@ def NSURL_to_path(url):


 def path_to_NSURL(path):
-    """ Convert path string to NSURL """
+    """Convert path string to NSURL"""
    pathstr = Foundation.NSString.alloc().initWithString_(str(path))
    url = Foundation.NSURL.fileURLWithPath_(pathstr)
    pathstr.dealloc()
@@ -82,10 +81,10 @@ def path_to_NSURL(path):


 def check_photokit_authorization():
-    """ Check authorization to use user's Photos Library
+    """Check authorization to use user's Photos Library

    Returns:
-       True if user has authorized access to the Photos library, otherwise False 
+       True if user has authorized access to the Photos library, otherwise False
    """

    auth_status = Photos.PHPhotoLibrary.authorizationStatus()
@@ -93,7 +92,7 @@ def check_photokit_authorization():


 def request_photokit_authorization():
-    """ Request authorization to user's Photos Library
+    """Request authorization to user's Photos Library

    Returns:
        authorization status
@@ -135,39 +134,39 @@ def request_photokit_authorization():

 ### exceptions
 class PhotoKitError(Exception):
-    """Base class for exceptions in this module. """
+    """Base class for exceptions in this module."""

    pass


 class PhotoKitFetchFailed(PhotoKitError):
-    """Exception raised for errors in the input. """
+    """Exception raised for errors in the input."""

    pass


 class PhotoKitAuthError(PhotoKitError):
-    """Exception raised if unable to authorize use of PhotoKit. """
+    """Exception raised if unable to authorize use of PhotoKit."""

    pass


 class PhotoKitExportError(PhotoKitError):
-    """Exception raised if unable to export asset. """
+    """Exception raised if unable to export asset."""

    pass


 class PhotoKitMediaTypeError(PhotoKitError):
-    """ Exception raised if an unknown mediaType() is encountered """
+    """Exception raised if an unknown mediaType() is encountered"""

    pass


 ### helper classes
 class ImageData:
-    """ Simple class to hold the data passed to the handler for 
-        requestImageDataAndOrientationForAsset_options_resultHandler_ 
+    """Simple class to hold the data passed to the handler for
+    requestImageDataAndOrientationForAsset_options_resultHandler_
    """

    def __init__(
@@ -181,8 +180,7 @@ class ImageData:


 class AVAssetData:
-    """ Simple class to hold the data passed to the handler for 
-    """
+    """Simple class to hold the data passed to the handler for"""

    def __init__(self):
        self.asset = None
@@ -192,7 +190,7 @@ class AVAssetData:


 class PHAssetResourceData:
-    """ Simple class to hold data from 
+    """Simple class to hold data from
    requestDataForAssetResource:options:dataReceivedHandler:completionHandler:
    """

@@ -200,19 +198,9 @@ class PHAssetResourceData:
        self.data = b""


-# class LivePhotoData:
-#     """ Simple class to hold the data passed to the handler for
-#         requestLivePhotoForAsset:targetSize:contentMode:options:resultHandler:
-#     """
-
-#     def __init__(self):
-#         self.live_photo = None
-#         self.info = None
-
-
 class PhotoKitNotificationDelegate(NSObject):
-    """ Handles notifications from NotificationCenter;
-        used with asynchronous PhotoKit requests to stop event loop when complete
+    """Handles notifications from NotificationCenter;
+    used with asynchronous PhotoKit requests to stop event loop when complete
    """

    def liveNotification_(self, note):
@@ -226,11 +214,11 @@ class PhotoKitNotificationDelegate(NSObject):

 ### main class implementation
 class PhotoAsset:
-    """ PhotoKit PHAsset representation """
+    """PhotoKit PHAsset representation"""

    def __init__(self, manager, phasset):
-        """ Return a PhotoAsset object
-        
+        """Return a PhotoAsset object
+
        Args:
            manager = ImageManager object
            phasset: a PHAsset object
@@ -241,32 +229,32 @@ class PhotoAsset:

    @property
    def phasset(self):
-        """ Return PHAsset instance """
+        """Return PHAsset instance"""
        return self._phasset

    @property
    def uuid(self):
-        """ Return local identifier (UUID) of PHAsset """
+        """Return local identifier (UUID) of PHAsset"""
        return self._phasset.localIdentifier()

    @property
    def isphoto(self):
-        """ Return True if asset is photo (image), otherwise False """
+        """Return True if asset is photo (image), otherwise False"""
        return self.media_type == Photos.PHAssetMediaTypeImage

    @property
    def ismovie(self):
-        """ Return True if asset is movie (video), otherwise False """
+        """Return True if asset is movie (video), otherwise False"""
        return self.media_type == Photos.PHAssetMediaTypeVideo

    @property
    def isaudio(self):
-        """ Return True if asset is audio, otherwise False """
+        """Return True if asset is audio, otherwise False"""
        return self.media_type == Photos.PHAssetMediaTypeAudio

    @property
    def original_filename(self):
-        """ Return original filename asset was imported with """
+        """Return original filename asset was imported with"""
        resources = self._resources()
        for resource in resources:
            if (
@@ -278,10 +266,22 @@ class PhotoAsset:
                return resource.originalFilename()
        return None

+    @property
+    def raw_filename(self):
+        """Return RAW filename for RAW+JPEG photos or None if no RAW asset"""
+        resources = self._resources()
+        for resource in resources:
+            if (
+                self.isphoto
+                and resource.type() == Photos.PHAssetResourceTypeAlternatePhoto
+            ):
+                return resource.originalFilename()
+        return None
+
    @property
    def hasadjustments(self):
-        """ Check to see if a PHAsset has adjustment data associated with it
-            Returns False if no adjustments, True if any adjustments """
+        """Check to see if a PHAsset has adjustment data associated with it
+        Returns False if no adjustments, True if any adjustments"""

        # reference: https://developer.apple.com/documentation/photokit/phassetresource/1623988-assetresourcesforasset?language=objc

@@ -298,112 +298,112 @@ class PhotoAsset:

    @property
    def media_type(self):
-        """ media type such as image or video """
+        """media type such as image or video"""
        return self.phasset.mediaType()

    @property
    def media_subtypes(self):
-        """ media subtype """
+        """media subtype"""
        return self.phasset.mediaSubtypes()

    @property
    def panorama(self):
-        """ return True if asset is panorama, otherwise False """
+        """return True if asset is panorama, otherwise False"""
        return bool(self.media_subtypes & Photos.PHAssetMediaSubtypePhotoPanorama)

    @property
    def hdr(self):
-        """ return True if asset is HDR, otherwise False """
+        """return True if asset is HDR, otherwise False"""
        return bool(self.media_subtypes & Photos.PHAssetMediaSubtypePhotoHDR)

    @property
    def screenshot(self):
-        """ return True if asset is screenshot, otherwise False """
+        """return True if asset is screenshot, otherwise False"""
        return bool(self.media_subtypes & Photos.PHAssetMediaSubtypePhotoScreenshot)

    @property
    def live(self):
-        """ return True if asset is live, otherwise False """
+        """return True if asset is live, otherwise False"""
        return bool(self.media_subtypes & Photos.PHAssetMediaSubtypePhotoLive)

    @property
    def streamed(self):
-        """ return True if asset is streamed video, otherwise False """
+        """return True if asset is streamed video, otherwise False"""
        return bool(self.media_subtypes & Photos.PHAssetMediaSubtypeVideoStreamed)

    @property
    def slow_mo(self):
-        """ return True if asset is slow motion (high frame rate) video, otherwise False """
+        """return True if asset is slow motion (high frame rate) video, otherwise False"""
        return bool(self.media_subtypes & Photos.PHAssetMediaSubtypeVideoHighFrameRate)

    @property
    def time_lapse(self):
-        """ return True if asset is time lapse video, otherwise False """
+        """return True if asset is time lapse video, otherwise False"""
        return bool(self.media_subtypes & Photos.PHAssetMediaSubtypeVideoTimelapse)

    @property
    def portrait(self):
-        """ return True if asset is portrait (depth effect), otherwise False """
+        """return True if asset is portrait (depth effect), otherwise False"""
        return bool(self.media_subtypes & Photos.PHAssetMediaSubtypePhotoDepthEffect)

    @property
    def burstid(self):
-        """ return burstIdentifier of image if image is burst photo otherwise None """
+        """return burstIdentifier of image if image is burst photo otherwise None"""
        return self.phasset.burstIdentifier()

    @property
    def burst(self):
-        """ return True if image is burst otherwise False """
+        """return True if image is burst otherwise False"""
        return bool(self.burstid)

    @property
    def source_type(self):
-        """ the means by which the asset entered the user's library """
+        """the means by which the asset entered the user's library"""
        return self.phasset.sourceType()

    @property
    def pixel_width(self):
-        """ width in pixels """
+        """width in pixels"""
        return self.phasset.pixelWidth()

    @property
    def pixel_height(self):
-        """ height in pixels """
+        """height in pixels"""
        return self.phasset.pixelHeight()

    @property
    def date(self):
-        """ date asset was created """
+        """date asset was created"""
        return self.phasset.creationDate()

    @property
    def date_modified(self):
-        """ date asset was modified """
+        """date asset was modified"""
        return self.phasset.modificationDate()

    @property
    def location(self):
-        """ location of the asset """
+        """location of the asset"""
        return self.phasset.location()

    @property
    def duration(self):
-        """ duration of the asset """
+        """duration of the asset"""
        return self.phasset.duration()

    @property
    def favorite(self):
-        """ True if asset is favorite, otherwise False """
+        """True if asset is favorite, otherwise False"""
        return self.phasset.isFavorite()

    @property
    def hidden(self):
-        """ True if asset is hidden, otherwise False """
+        """True if asset is hidden, otherwise False"""
        return self.phasset.isHidden()

    def metadata(self, version=PHOTOS_VERSION_CURRENT):
-        """ Return dict of asset metadata
-        
+        """Return dict of asset metadata
+
        Args:
            version: which version of image (PHOTOS_VERSION_ORIGINAL or PHOTOS_VERSION_CURRENT)
        """
@@ -411,17 +411,28 @@ class PhotoAsset:
        return imagedata.metadata

    def uti(self, version=PHOTOS_VERSION_CURRENT):
-        """ Return UTI of asset
-        
+        """Return UTI of asset
+
        Args:
            version: which version of image (PHOTOS_VERSION_ORIGINAL or PHOTOS_VERSION_CURRENT)
        """
        imagedata = self._request_image_data(version=version)
        return imagedata.uti

+    def uti_raw(self):
+        """Return UTI of RAW component of RAW+JPEG pair"""
+        resources = self._resources()
+        for resource in resources:
+            if (
+                self.isphoto
+                and resource.type() == Photos.PHAssetResourceTypeAlternatePhoto
+            ):
+                return resource.uniformTypeIdentifier()
+        return None
+
    def url(self, version=PHOTOS_VERSION_CURRENT):
-        """ Return URL of asset
-        
+        """Return URL of asset
+
        Args:
            version: which version of image (PHOTOS_VERSION_ORIGINAL or PHOTOS_VERSION_CURRENT)
        """
@@ -429,8 +440,8 @@ class PhotoAsset:
        return str(imagedata.info["PHImageFileURLKey"])

    def path(self, version=PHOTOS_VERSION_CURRENT):
-        """ Return path of asset
-        
+        """Return path of asset
+
        Args:
            version: which version of image (PHOTOS_VERSION_ORIGINAL or PHOTOS_VERSION_CURRENT)
        """
@@ -439,8 +450,8 @@ class PhotoAsset:
        return url.fileSystemRepresentation().decode("utf-8")

    def orientation(self, version=PHOTOS_VERSION_CURRENT):
-        """ Return orientation of asset
-        
+        """Return orientation of asset
+
        Args:
            version: which version of image (PHOTOS_VERSION_ORIGINAL or PHOTOS_VERSION_CURRENT)
        """
@@ -449,8 +460,8 @@ class PhotoAsset:

    @property
    def degraded(self, version=PHOTOS_VERSION_CURRENT):
-        """ Return True if asset is degraded version 
-        
+        """Return True if asset is degraded version
+
        Args:
            version: which version of image (PHOTOS_VERSION_ORIGINAL or PHOTOS_VERSION_CURRENT)
        """
@@ -458,15 +469,23 @@ class PhotoAsset:
        return imagedata.info["PHImageResultIsDegradedKey"]

    def export(
-        self, dest, filename=None, version=PHOTOS_VERSION_CURRENT, overwrite=False
+        self,
+        dest,
+        filename=None,
+        version=PHOTOS_VERSION_CURRENT,
+        overwrite=False,
+        raw=False,
+        **kwargs,
    ):
-        """ Export image to path
+        """Export image to path

        Args:
            dest: str, path to destination directory
            filename: str, optional name of exported file; if not provided, defaults to asset's original filename
            version: which version of image (PHOTOS_VERSION_ORIGINAL or PHOTOS_VERSION_CURRENT)
            overwrite: bool, if True, overwrites destination file if it already exists; default is False
+            raw: bool, if True, export RAW component of RAW+JPEG pair, default is False
+            **kwargs: used only to avoid issues with each asset type having slightly different export arguments

        Returns:
            List of path to exported image(s)
@@ -475,9 +494,6 @@ class PhotoAsset:
            ValueError if dest is not a valid directory
        """

-        # if self.live:
-        #     raise NotImplementedError("Live photos not implemented yet")
-
        with objc.autorelease_pool():
            filename = (
                pathlib.Path(filename)
@@ -491,11 +507,28 @@ class PhotoAsset:

            output_file = None
            if self.isphoto:
-                imagedata = self._request_image_data(version=version)
-                if not imagedata.image_data:
-                    raise PhotoKitExportError("Could not get image data")
-
-                ext = get_preferred_uti_extension(imagedata.uti)
+                # will hold exported image data and needs to be cleaned up at end
+                imagedata = None
+                if raw:
+                    # export the raw component
+                    resources = self._resources()
+                    for resource in resources:
+                        if resource.type() == Photos.PHAssetResourceTypeAlternatePhoto:
+                            data = self._request_resource_data(resource)
+                            ext = pathlib.Path(self.raw_filename).suffix[1:]
+                            break
+                    else:
+                        raise PhotoKitExportError(
+                            "Could not get image data for RAW photo"
+                        )
+                else:
+                    # TODO: if user has selected use RAW as original, this returns the RAW
+                    # can get the jpeg with resource.type() == Photos.PHAssetResourceTypePhoto
+                    imagedata = self._request_image_data(version=version)
+                    if not imagedata.image_data:
+                        raise PhotoKitExportError("Could not get image data")
+                    ext = get_preferred_uti_extension(imagedata.uti)
+                    data = imagedata.image_data

                output_file = dest / f"{filename.stem}.{ext}"

@@ -503,7 +536,9 @@ class PhotoAsset:
                    output_file = pathlib.Path(increment_filename(output_file))

                with open(output_file, "wb") as fd:
-                    fd.write(imagedata.image_data)
+                    fd.write(data)
+
+                if imagedata:
                    del imagedata
            elif self.ismovie:
                videodata = self._request_video_data(version=version)
@@ -525,14 +560,14 @@ class PhotoAsset:
            return [str(output_file)]

    def _request_image_data(self, version=PHOTOS_VERSION_ORIGINAL):
-        """ Request image data and metadata for self._phasset 
-            
+        """Request image data and metadata for self._phasset
+
        Args:
            version: which version to request
-                     PHOTOS_VERSION_ORIGINAL (default), request original highest fidelity version 
+                     PHOTOS_VERSION_ORIGINAL (default), request original highest fidelity version
                     PHOTOS_VERSION_CURRENT, request current version with all edits
                     PHOTOS_VERSION_UNADJUSTED, request highest quality unadjusted version
-        
+
        Returns:
            ImageData instance

@@ -562,14 +597,12 @@ class PhotoAsset:
            event = threading.Event()

            def handler(imageData, dataUTI, orientation, info):
-                """ result handler for requestImageDataAndOrientationForAsset_options_resultHandler_ 
-                    all returned by the request is set as properties of nonlocal data (Fetchdata object) """
+                """result handler for requestImageDataAndOrientationForAsset_options_resultHandler_
+                all returned by the request is set as properties of nonlocal data (Fetchdata object)"""

                nonlocal requestdata

-                options = {}
-                # pylint: disable=no-member
-                options[Quartz.kCGImageSourceShouldCache] = Foundation.kCFBooleanFalse
+                options = {Quartz.kCGImageSourceShouldCache: Foundation.kCFBooleanFalse}
                imgSrc = Quartz.CGImageSourceCreateWithData(imageData, options)
                requestdata.metadata = Quartz.CGImageSourceCopyPropertiesAtIndex(
                    imgSrc, 0, options
@@ -593,25 +626,67 @@ class PhotoAsset:
            del requestdata
            return data

+    def _request_resource_data(self, resource):
+        """Request asset resource data (either photo or video component)
+
+        Args:
+            resource: PHAssetResource to request
+
+        Raises:
+        """
+
+        with objc.autorelease_pool():
+            resource_manager = Photos.PHAssetResourceManager.defaultManager()
+            options = Photos.PHAssetResourceRequestOptions.alloc().init()
+            options.setNetworkAccessAllowed_(True)
+
+            requestdata = PHAssetResourceData()
+            event = threading.Event()
+
+            def handler(data):
+                """result handler for requestImageDataAndOrientationForAsset_options_resultHandler_
+                all returned by the request is set as properties of nonlocal data (Fetchdata object)"""
+
+                nonlocal requestdata
+
+                requestdata.data += data
+
+            def completion_handler(error):
+                if error:
+                    raise PhotoKitExportError(
+                        "Error requesting data for asset resource"
+                    )
+                event.set()
+
+            resource_manager.requestDataForAssetResource_options_dataReceivedHandler_completionHandler_(
+                resource, options, handler, completion_handler
+            )
+
+            event.wait()
+
+            # not sure why this is needed -- some weird ref count thing maybe
+            # if I don't do this, memory leaks
+            data = copy.copy(requestdata.data)
+            del requestdata
+            return data
+
    def _make_result_handle_(self, data):
-        """ Make handler function and threading event to use with 
-            requestImageDataAndOrientationForAsset_options_resultHandler_ 
-            data: Fetchdata class to hold resulting metadata 
-            returns: handler function, threading.Event() instance 
-            Following call to requestImageDataAndOrientationForAsset_options_resultHandler_, 
-            data will hold data from the fetch """
+        """Make handler function and threading event to use with
+        requestImageDataAndOrientationForAsset_options_resultHandler_
+        data: Fetchdata class to hold resulting metadata
+        returns: handler function, threading.Event() instance
+        Following call to requestImageDataAndOrientationForAsset_options_resultHandler_,
+        data will hold data from the fetch"""

        event = threading.Event()

        def handler(imageData, dataUTI, orientation, info):
-            """ result handler for requestImageDataAndOrientationForAsset_options_resultHandler_ 
-                all returned by the request is set as properties of nonlocal data (Fetchdata object) """
+            """result handler for requestImageDataAndOrientationForAsset_options_resultHandler_
+            all returned by the request is set as properties of nonlocal data (Fetchdata object)"""

            nonlocal data

-            options = {}
-            # pylint: disable=no-member
-            options[Quartz.kCGImageSourceShouldCache] = Foundation.kCFBooleanFalse
+            options = {Quartz.kCGImageSourceShouldCache: Foundation.kCFBooleanFalse}
            imgSrc = Quartz.CGImageSourceCreateWithData(imageData, options)
            data.metadata = Quartz.CGImageSourceCopyPropertiesAtIndex(
                imgSrc, 0, options
@@ -626,14 +701,14 @@ class PhotoAsset:
        return handler, event

    def _resources(self):
-        """ Return list of PHAssetResource for object """
+        """Return list of PHAssetResource for object"""
        resources = Photos.PHAssetResource.assetResourcesForAsset_(self.phasset)
        return [resources.objectAtIndex_(idx) for idx in range(resources.count())]


 class SlowMoVideoExporter(NSObject):
    def initWithAVAsset_path_(self, avasset, path):
-        """ init helper class for exporting slow-mo video
+        """init helper class for exporting slow-mo video

        Args:
            avasset: AVAsset
@@ -648,15 +723,17 @@ class SlowMoVideoExporter(NSObject):
        return self

    def exportSlowMoVideo(self):
-        """ export slow-mo video with AVAssetExportSession
-        
+        """export slow-mo video with AVAssetExportSession
+
        Returns:
            path to exported file
        """

        with objc.autorelease_pool():
-            exporter = AVFoundation.AVAssetExportSession.alloc().initWithAsset_presetName_(
-                self.avasset, AVFoundation.AVAssetExportPresetHighestQuality
+            exporter = (
+                AVFoundation.AVAssetExportSession.alloc().initWithAsset_presetName_(
+                    self.avasset, AVFoundation.AVAssetExportPresetHighestQuality
+                )
            )
            exporter.setOutputURL_(self.url)
            exporter.setOutputFileType_(AVFoundation.AVFileTypeQuickTimeMovie)
@@ -665,7 +742,7 @@ class SlowMoVideoExporter(NSObject):
            self.done = False

            def handler():
-                """ result handler for exportAsynchronouslyWithCompletionHandler """
+                """result handler for exportAsynchronouslyWithCompletionHandler"""
                self.done = True

            exporter.exportAsynchronouslyWithCompletionHandler_(handler)
@@ -695,11 +772,10 @@ class SlowMoVideoExporter(NSObject):
        self.url = None
        self.done = None
        self.nc = None
-        # super(NSObject, self).dealloc()


 class VideoAsset(PhotoAsset):
-    """ PhotoKit PHAsset representation of video asset """
+    """PhotoKit PHAsset representation of video asset"""

    # TODO: doesn't work for slow-mo videos
    # see https://stackoverflow.com/questions/26152396/how-to-access-nsdata-nsurl-of-slow-motion-videos-using-photokit
@@ -707,15 +783,21 @@ class VideoAsset(PhotoAsset):
    # https://developer.apple.com/documentation/photokit/phimagemanager/1616981-requestexportsessionforvideo?language=objc
    # above 10.15 only
    def export(
-        self, dest, filename=None, version=PHOTOS_VERSION_CURRENT, overwrite=False
+        self,
+        dest,
+        filename=None,
+        version=PHOTOS_VERSION_CURRENT,
+        overwrite=False,
+        **kwargs,
    ):
-        """ Export video to path
+        """Export video to path

        Args:
            dest: str, path to destination directory
            filename: str, optional name of exported file; if not provided, defaults to asset's original filename
            version: which version of image (PHOTOS_VERSION_ORIGINAL or PHOTOS_VERSION_CURRENT)
            overwrite: bool, if True, overwrites destination file if it already exists; default is False
+            **kwargs: used only to avoid issues with each asset type having slightly different export arguments

        Returns:
            List of path to exported image(s)
@@ -765,7 +847,7 @@ class VideoAsset(PhotoAsset):
    def _export_slow_mo(
        self, dest, filename=None, version=PHOTOS_VERSION_CURRENT, overwrite=False
    ):
-        """ Export slow-motion video to path
+        """Export slow-motion video to path

        Args:
            dest: str, path to destination directory
@@ -814,14 +896,14 @@ class VideoAsset(PhotoAsset):

    # todo: rewrite this with NotificationCenter and App event loop?
    def _request_video_data(self, version=PHOTOS_VERSION_ORIGINAL):
-        """ Request video data for self._phasset 
-            
+        """Request video data for self._phasset
+
        Args:
            version: which version to request
-                     PHOTOS_VERSION_ORIGINAL (default), request original highest fidelity version 
+                     PHOTOS_VERSION_ORIGINAL (default), request original highest fidelity version
                     PHOTOS_VERSION_CURRENT, request current version with all edits
                     PHOTOS_VERSION_UNADJUSTED, request highest quality unadjusted version
-        
+
        Raises:
            ValueError if passed invalid value for version
        """
@@ -843,7 +925,7 @@ class VideoAsset(PhotoAsset):
            event = threading.Event()

            def handler(asset, audiomix, info):
-                """ result handler for requestAVAssetForVideo:asset options:options resultHandler """
+                """result handler for requestAVAssetForVideo:asset options:options resultHandler"""
                nonlocal requestdata

                requestdata.asset = asset
@@ -865,8 +947,8 @@ class VideoAsset(PhotoAsset):


 class LivePhotoRequest(NSObject):
-    """ Manage requests for live photo assets
-        See: https://developer.apple.com/documentation/photokit/phimagemanager/1616984-requestlivephotoforasset?language=objc
+    """Manage requests for live photo assets
+    See: https://developer.apple.com/documentation/photokit/phimagemanager/1616984-requestlivephotoforasset?language=objc
    """

    def initWithManager_Asset_(self, manager, asset):
@@ -879,7 +961,7 @@ class LivePhotoRequest(NSObject):
        return self

    def requestLivePhotoResources(self, version=PHOTOS_VERSION_CURRENT):
-        """ return the photos and video components of a live video as [PHAssetResource] """
+        """return the photos and video components of a live video as [PHAssetResource]"""

        with objc.autorelease_pool():
            options = Photos.PHLivePhotoRequestOptions.alloc().init()
@@ -897,7 +979,7 @@ class LivePhotoRequest(NSObject):
            self.live_photo = None

            def handler(result, info):
-                """ result handler for requestLivePhotoForAsset:targetSize:contentMode:options:resultHandler: """
+                """result handler for requestLivePhotoForAsset:targetSize:contentMode:options:resultHandler:"""
                if not info["PHImageResultIsDegradedKey"]:
                    self.live_photo = result
                    self.info = info
@@ -939,7 +1021,7 @@ class LivePhotoRequest(NSObject):


 class LivePhotoAsset(PhotoAsset):
-    """ Represents a live photo """
+    """Represents a live photo"""

    def export(
        self,
@@ -949,8 +1031,9 @@ class LivePhotoAsset(PhotoAsset):
        overwrite=False,
        photo=True,
        video=True,
+        **kwargs,
    ):
-        """ Export image to path
+        """Export image to path

        Args:
            dest: str, path to destination directory
@@ -959,6 +1042,7 @@ class LivePhotoAsset(PhotoAsset):
            overwrite: bool, if True, overwrites destination file if it already exists; default is False
            photo: bool, if True, export photo component of live photo
            video: bool, if True, export live video component of live photo
+            **kwargs: used only to avoid issues with each asset type having slightly different export arguments

        Returns:
            list of [path to exported image and/or video]
@@ -1010,39 +1094,6 @@ class LivePhotoAsset(PhotoAsset):
                photo_output_file = pathlib.Path(increment_filename(photo_output_file))
                video_output_file = pathlib.Path(increment_filename(video_output_file))

-            # def handler(error):
-            #     if error:
-            #         raise PhotoKitExportError(f"writeDataForAssetResource error: {error}")
-
-            # resource_manager = Photos.PHAssetResourceManager.defaultManager()
-            # options = Photos.PHAssetResourceRequestOptions.alloc().init()
-            # options.setNetworkAccessAllowed_(True)
-            # exported = []
-            # Note: Tried writeDataForAssetResource_toFile_options_completionHandler_ which works
-            # but sets quarantine flag and for reasons I can't determine (maybe quarantine flag)
-            # causes pathlib.Path().is_file() to fail in tests
-
-            # if photo:
-            #     photo_output_url = path_to_NSURL(photo_output_file)
-            #     resource_manager.writeDataForAssetResource_toFile_options_completionHandler_(
-            #         photo_resource, photo_output_url, options, handler
-            #     )
-            #     exported.append(str(photo_output_file))
-
-            # if video:
-            #     video_output_url = path_to_NSURL(video_output_file)
-            #     resource_manager.writeDataForAssetResource_toFile_options_completionHandler_(
-            #         video_resource, video_output_url, options, handler
-            #     )
-            #     exported.append(str(video_output_file))
-
-            # def completion_handler(error):
-            #     if error:
-            #         raise PhotoKitExportError(f"writeDataForAssetResource error: {error}")
-
-            # would be nice to be able to usewriteDataForAssetResource_toFile_options_completionHandler_
-            # but it sets quarantine flags that cause issues so instead, request the data and write the files directly
-
            exported = []
            if photo:
                data = self._request_resource_data(photo_resource)
@@ -1061,93 +1112,14 @@ class LivePhotoAsset(PhotoAsset):
            request.dealloc()
            return exported

-    def _request_resource_data(self, resource):
-        """ Request asset resource data (either photo or video component)
-            
-        Args:
-            resource: PHAssetResource to request
-        
-        Raises:
-        """
-
-        with objc.autorelease_pool():
-            resource_manager = Photos.PHAssetResourceManager.defaultManager()
-            options = Photos.PHAssetResourceRequestOptions.alloc().init()
-            options.setNetworkAccessAllowed_(True)
-
-            requestdata = PHAssetResourceData()
-            event = threading.Event()
-
-            def handler(data):
-                """ result handler for requestImageDataAndOrientationForAsset_options_resultHandler_ 
-                    all returned by the request is set as properties of nonlocal data (Fetchdata object) """
-
-                nonlocal requestdata
-
-                requestdata.data += data
-
-            def completion_handler(error):
-                if error:
-                    raise PhotoKitExportError(
-                        "Error requesting data for asset resource"
-                    )
-                event.set()
-
-            resource_manager.requestDataForAssetResource_options_dataReceivedHandler_completionHandler_(
-                resource, options, handler, completion_handler
-            )
-
-            event.wait()
-
-            # not sure why this is needed -- some weird ref count thing maybe
-            # if I don't do this, memory leaks
-            data = copy.copy(requestdata.data)
-            del requestdata
-            return data
-
-    # def request_image_data(self, version=PHOTOS_VERSION_CURRENT):
-    #     # Returns an NSImage which isn't overly useful
-    #     # https://developer.apple.com/documentation/photokit/phimagemanager/1616964-requestimageforasset?language=objc
-
-    #     # requestImageForAsset:targetSize:contentMode:options:resultHandler:
-
-    #     options = Photos.PHImageRequestOptions.alloc().init()
-    #     options.setVersion_(version)
-    #     options.setNetworkAccessAllowed_(True)
-    #     options.setSynchronous_(True)
-    #     options.setDeliveryMode_(
-    #         Photos.PHImageRequestOptionsDeliveryModeHighQualityFormat
-    #     )
-
-    #     event = threading.Event()
-    #     image_data = ImageData()
-
-    #     def handler(result, info):
-    #         nonlocal image_data
-    #         if not info["PHImageResultIsDegradedKey"]:
-    #             image_data.image_data = result
-    #             image_data.info = info
-    #             event.set()
-
-    #     self._manager.requestImageForAsset_targetSize_contentMode_options_resultHandler_(
-    #         self._phasset,
-    #         Photos.PHImageManagerMaximumSize,
-    #         Photos.PHImageContentModeDefault,
-    #         options,
-    #         handler,
-    #     )
-    #     event.wait()
-    #     options.dealloc()
-    #     return image_data
-

 class PhotoLibrary:
-    """ Interface to PhotoKit PHImageManager and PHPhotoLibrary """
+    """Interface to PhotoKit PHImageManager and PHPhotoLibrary"""

    def __init__(self):
-        """ Initialize ImageManager instance.  Requests authorization to use the 
+        """Initialize ImageManager instance.  Requests authorization to use the
        Photos library if authorization has not already been granted.
-        
+
        Raises:
            PhotoKitAuthError if unable to authorize access to PhotoKit
        """
@@ -1166,7 +1138,7 @@ class PhotoLibrary:
        self._phimagemanager = Photos.PHCachingImageManager.defaultManager()

    def request_authorization(self):
-        """ Request authorization to user's Photos Library
+        """Request authorization to user's Photos Library

        Returns:
            authorization status
@@ -1176,7 +1148,7 @@ class PhotoLibrary:
        return self.auth_status

    def fetch_uuid_list(self, uuid_list):
-        """ fetch PHAssets with uuids in uuid_list
+        """fetch PHAssets with uuids in uuid_list

        Args:
            uuid_list: list of str (UUID of image assets to fetch)
@@ -1205,7 +1177,7 @@ class PhotoLibrary:
                )

    def fetch_uuid(self, uuid):
-        """ fetch PHAsset with uuid = uuid
+        """fetch PHAsset with uuid = uuid

        Args:
            uuid: str; UUID of image asset to fetch
@@ -1223,8 +1195,8 @@ class PhotoLibrary:
            raise PhotoKitFetchFailed(f"Fetch did not return result for uuid {uuid}")

    def fetch_burst_uuid(self, burstid, all=False):
-        """ fetch PhotoAssets with burst ID = burstid 
-        
+        """fetch PhotoAssets with burst ID = burstid
+
        Args:
            burstid: str, burst UUID
            all: return all burst assets; if False returns only those selected by the user (including the "key photo" even if user hasn't manually selected it)
@@ -1253,11 +1225,11 @@ class PhotoLibrary:
            )

    def _asset_factory(self, phasset):
-        """ creates a PhotoAsset, VideoAsset, or LivePhotoAsset
+        """creates a PhotoAsset, VideoAsset, or LivePhotoAsset

        Args:
-            phasset: PHAsset object 
-        
+            phasset: PHAsset object
+
        Returns:
            PhotoAsset, VideoAsset, or LivePhotoAsset depending on type of PHAsset
        """
--- a/osxphotos/photosalbum.py
+++ b/osxphotos/photosalbum.py
@@ -1,7 +1,10 @@
 """ PhotosAlbum class to create an album in default Photos library and add photos to it """

-from typing import Optional, List
+from typing import List, Optional
+
 import photoscript
+from more_itertools import chunked
+
 from .photoinfo import PhotoInfo
 from .utils import noop

@@ -26,8 +29,14 @@ class PhotosAlbum:
        )

    def add_list(self, photo_list: List[PhotoInfo]):
-        photos = [photoscript.Photo(p.uuid) for p in photo_list]
-        self.album.add(photos)
+        photos = []
+        for p in photo_list:
+            try:
+                photos.append(photoscript.Photo(p.uuid))
+            except Exception as e:
+                self.verbose(f"Error creating Photo object for photo {p.uuid}: {e}")
+        for photolist in chunked(photos, 10):
+            self.album.add(photolist)
        photo_len = len(photos)
        photo_word = "photos" if photo_len > 1 else "photo"
        self.verbose(f"Added {photo_len} {photo_word} to album {self.name}")
--- a/osxphotos/photosdb/_photosdb_process_comments.py
+++ b/osxphotos/photosdb/_photosdb_process_comments.py
@@ -70,12 +70,24 @@ def _process_comments_5(photosdb):
    results = conn.execute(
        """
        SELECT DISTINCT
-        ZINVITEEHASHEDPERSONID,
-        ZINVITEEFIRSTNAME,
-        ZINVITEELASTNAME,
-        ZINVITEEFULLNAME
-        FROM
-        ZCLOUDSHAREDALBUMINVITATIONRECORD
+        ZINVITEEHASHEDPERSONID AS HASHEDPERSONID,
+        ZINVITEEFIRSTNAME AS FIRSTNAME,
+        ZINVITEELASTNAME AS LASTNAME,
+        ZINVITEEFULLNAME AS FULLNAME
+        FROM ZCLOUDSHAREDALBUMINVITATIONRECORD
+        WHERE HASHEDPERSONID IS NOT NULL
+        AND HASHEDPERSONID != ""
+        AND NOT (FIRSTNAME IS NULL AND LASTNAME IS NULL)
+        UNION
+        SELECT DISTINCT
+        ZCLOUDOWNERHASHEDPERSONID AS HASHEDPERSONID,
+        ZCLOUDOWNERFIRSTNAME AS FIRSTNAME,
+        ZCLOUDOWNERLASTNAME AS LASTNAME,
+        ZCLOUDOWNERFULLNAME AS FULLNAME
+        FROM ZGENERICALBUM
+        WHERE HASHEDPERSONID IS NOT NULL
+        AND HASHEDPERSONID != ""
+        AND NOT (FIRSTNAME IS NULL AND LASTNAME IS NULL)
        """
    )

@@ -148,10 +160,10 @@ def _process_comments_5(photosdb):
            db_comments["comments"].append(CommentInfo(dt, user_name, ismine, text))

    # sort results
-    for uuid in photosdb._db_comments_uuid:
+    for uuid, value in photosdb._db_comments_uuid.items():
        if photosdb._db_comments_uuid[uuid]["likes"]:
            photosdb._db_comments_uuid[uuid]["likes"].sort(key=lambda x: x.datetime)
        if photosdb._db_comments_uuid[uuid]["comments"]:
-            photosdb._db_comments_uuid[uuid]["comments"].sort(key=lambda x: x.datetime)
+            value["comments"].sort(key=lambda x: x.datetime)

    conn.close()
--- a/osxphotos/photosdb/_photosdb_process_faceinfo.py
+++ b/osxphotos/photosdb/_photosdb_process_faceinfo.py
@@ -146,7 +146,6 @@ def _process_faceinfo_4(photosdb):

        # Photos 5 only
        face["agetype"] = None
-        face["baldtype"] = None
        face["eyemakeuptype"] = None
        face["eyestate"] = None
        face["facialhairtype"] = None
@@ -194,7 +193,7 @@ def _process_faceinfo_5(photosdb):
        ZDETECTEDFACE.ZPERSON,
        ZPERSON.ZFULLNAME,
        ZDETECTEDFACE.ZAGETYPE,
-        ZDETECTEDFACE.ZBALDTYPE,
+        NULL, -- ZDETECTEDFACE.ZBALDTYPE (Removed in Monterey)
        ZDETECTEDFACE.ZEYEMAKEUPTYPE,
        ZDETECTEDFACE.ZEYESSTATE,
        ZDETECTEDFACE.ZFACIALHAIRTYPE,
@@ -239,7 +238,7 @@ def _process_faceinfo_5(photosdb):
    # 3    ZDETECTEDFACE.ZPERSON,
    # 4    ZPERSON.ZFULLNAME,
    # 5    ZDETECTEDFACE.ZAGETYPE,
-    # 6    ZDETECTEDFACE.ZBALDTYPE,
+    # 6    ZDETECTEDFACE.ZBALDTYPE,  (Not available on Monterey)
    # 7    ZDETECTEDFACE.ZEYEMAKEUPTYPE,
    # 8    ZDETECTEDFACE.ZEYESSTATE,
    # 9    ZDETECTEDFACE.ZFACIALHAIRTYPE,
@@ -284,7 +283,6 @@ def _process_faceinfo_5(photosdb):
        face["person"] = person_pk
        face["fullname"] = normalize_unicode(row[4])
        face["agetype"] = row[5]
-        face["baldtype"] = row[6]
        face["eyemakeuptype"] = row[7]
        face["eyestate"] = row[8]
        face["facialhairtype"] = row[9]
--- a/osxphotos/photosdb/photosdb.py
+++ b/osxphotos/photosdb/photosdb.py
@@ -11,11 +11,15 @@ import platform
 import re
 import sys
 import tempfile
+from collections import OrderedDict
+from collections.abc import Iterable
 from datetime import datetime, timedelta, timezone
 from pprint import pformat
 from typing import List

 import bitmath
+import photoscript
+from rich import print

 from .._constants import (
    _DB_TABLE_NAMES,
@@ -43,6 +47,7 @@ from ..datetime_utils import datetime_has_tz, datetime_naive_to_local
 from ..fileutil import FileUtil
 from ..personinfo import PersonInfo
 from ..photoinfo import PhotoInfo
+from ..phototemplate import RenderOptions
 from ..queryoptions import QueryOptions
 from ..utils import (
    _check_file_exists,
@@ -62,29 +67,29 @@ from .photosdb_utils import get_db_model_version, get_db_version


 class PhotosDB:
-    """ Processes a Photos.app library database to extract information about photos """
+    """Processes a Photos.app library database to extract information about photos"""

    # import additional methods
+    from ._photosdb_process_comments import _process_comments
    from ._photosdb_process_exif import _process_exifinfo
    from ._photosdb_process_faceinfo import _process_faceinfo
+    from ._photosdb_process_scoreinfo import _process_scoreinfo
    from ._photosdb_process_searchinfo import (
        _process_searchinfo,
        labels,
-        labels_normalized,
        labels_as_dict,
+        labels_normalized,
        labels_normalized_as_dict,
    )
-    from ._photosdb_process_scoreinfo import _process_scoreinfo
-    from ._photosdb_process_comments import _process_comments

    def __init__(self, dbfile=None, verbose=None, exiftool=None):
-        """ Create a new PhotosDB object.
+        """Create a new PhotosDB object.

        Args:
            dbfile: specify full path to photos library or photos.db; if None, will attempt to locate last library opened by Photos.
            verbose: optional callable function to use for printing verbose text during processing; if None (default), does not print output.
            exiftool: optional path to exiftool for methods that require this (e.g. PhotoInfo.exiftool); if not provided, will search PATH
-        
+
        Raises:
            FileNotFoundError if dbfile is not a valid Photos library.
            TypeError if verbose is not None and not callable.
@@ -240,6 +245,17 @@ class PhotosDB:
        # Will hold the primary key of root folder
        self._folder_root_pk = None

+        # Dict to hold signatures for finding possible duplicates
+        # key is tuple of (original_filesize, date) and value is list of uuids that match that signature
+        self._db_signatures = {}
+
+        # Dict to hold information on volume names (Photos 5+)
+        self._db_filesystem_volumes = {}
+
+        # Dict to hold information on moments (Photos 5+)
+        # key is Z_PK of ZMOMENT table and values are the moment info
+        self._db_moment_pk = {}
+
        if _debug():
            logging.debug(f"dbfile = {dbfile}")

@@ -320,9 +336,11 @@ class PhotosDB:
        else:
            self._process_database5()

+        self._db_connection, _ = self.get_db_connection()
+
    @property
    def keywords_as_dict(self):
-        """ return keywords as dict of keyword, count in reverse sorted order (descending) """
+        """return keywords as dict of keyword, count in reverse sorted order (descending)"""
        keywords = {
            k: len(self._dbkeywords_keyword[k]) for k in self._dbkeywords_keyword.keys()
        }
@@ -332,7 +350,7 @@ class PhotosDB:

    @property
    def persons_as_dict(self):
-        """ return persons as dict of person, count in reverse sorted order (descending) """
+        """return persons as dict of person, count in reverse sorted order (descending)"""
        persons = {}
        for pk in self._dbfaces_pk:
            fullname = self._dbpersons_pk[pk]["fullname"]
@@ -345,7 +363,7 @@ class PhotosDB:

    @property
    def albums_as_dict(self):
-        """ return albums as dict of albums, count in reverse sorted order (descending) """
+        """return albums as dict of albums, count in reverse sorted order (descending)"""
        albums = {}
        album_keys = self._get_album_uuids(shared=False)
        for album in album_keys:
@@ -362,8 +380,8 @@ class PhotosDB:

    @property
    def albums_shared_as_dict(self):
-        """ returns shared albums as dict of albums, count in reverse sorted order (descending)
-            valid only on Photos 5; on Photos <= 4, prints warning and returns empty dict """
+        """returns shared albums as dict of albums, count in reverse sorted order (descending)
+        valid only on Photos 5; on Photos <= 4, prints warning and returns empty dict"""

        albums = {}
        album_keys = self._get_album_uuids(shared=True)
@@ -381,19 +399,19 @@ class PhotosDB:

    @property
    def keywords(self):
-        """ return list of keywords found in photos database """
+        """return list of keywords found in photos database"""
        keywords = self._dbkeywords_keyword.keys()
        return list(keywords)

    @property
    def persons(self):
-        """ return list of persons found in photos database """
+        """return list of persons found in photos database"""
        persons = {self._dbpersons_pk[k]["fullname"] for k in self._dbfaces_pk}
        return list(persons)

    @property
    def person_info(self):
-        """ return list of PersonInfo objects for each person in the photos database """
+        """return list of PersonInfo objects for each person in the photos database"""
        try:
            return self._person_info
        except AttributeError:
@@ -404,7 +422,7 @@ class PhotosDB:

    @property
    def folder_info(self):
-        """ return list FolderInfo objects representing top-level folders in the photos database """
+        """return list FolderInfo objects representing top-level folders in the photos database"""
        if self._db_version <= _PHOTOS_4_VERSION:
            folders = [
                FolderInfo(db=self, uuid=folder)
@@ -425,7 +443,7 @@ class PhotosDB:

    @property
    def folders(self):
-        """ return list of top-level folder names in the photos database """
+        """return list of top-level folder names in the photos database"""
        if self._db_version <= _PHOTOS_4_VERSION:
            folder_names = [
                folder["name"]
@@ -446,7 +464,7 @@ class PhotosDB:

    @property
    def album_info(self):
-        """ return list of AlbumInfo objects for each album in the photos database """
+        """return list of AlbumInfo objects for each album in the photos database"""
        try:
            return self._album_info
        except AttributeError:
@@ -458,8 +476,8 @@ class PhotosDB:

    @property
    def album_info_shared(self):
-        """ return list of AlbumInfo objects for each shared album in the photos database
-            only valid for Photos 5; on Photos <= 4, prints warning and returns empty list """
+        """return list of AlbumInfo objects for each shared album in the photos database
+        only valid for Photos 5; on Photos <= 4, prints warning and returns empty list"""
        # if _dbalbum_details[key]["cloudownerhashedpersonid"] is not None, then it's a shared album
        try:
            return self._album_info_shared
@@ -472,7 +490,7 @@ class PhotosDB:

    @property
    def albums(self):
-        """ return list of albums found in photos database """
+        """return list of albums found in photos database"""

        # Could be more than one album with same name
        # Right now, they are treated as same album and photos are combined from albums with same name
@@ -485,8 +503,8 @@ class PhotosDB:

    @property
    def albums_shared(self):
-        """ return list of shared albums found in photos database
-            only valid for Photos 5; on Photos <= 4, prints warning and returns empty list """
+        """return list of shared albums found in photos database
+        only valid for Photos 5; on Photos <= 4, prints warning and returns empty list"""

        # Could be more than one album with same name
        # Right now, they are treated as same album and photos are combined from albums with same name
@@ -501,7 +519,7 @@ class PhotosDB:

    @property
    def import_info(self):
-        """ return list of ImportInfo objects for each import session in the database """
+        """return list of ImportInfo objects for each import session in the database"""
        try:
            return self._import_info
        except AttributeError:
@@ -513,21 +531,21 @@ class PhotosDB:

    @property
    def db_version(self):
-        """ return the database version as stored in LiGlobals table """
+        """return the database version as stored in LiGlobals table"""
        return self._db_version

    @property
    def db_path(self):
-        """ returns path to the Photos library database PhotosDB was initialized with """
+        """returns path to the Photos library database PhotosDB was initialized with"""
        return os.path.abspath(self._dbfile)

    @property
    def library_path(self):
-        """ returns path to the Photos library PhotosDB was initialized with """
+        """returns path to the Photos library PhotosDB was initialized with"""
        return self._library_path

    def get_db_connection(self):
-        """ Get connection to the working copy of the Photos database 
+        """Get connection to the working copy of the Photos database

        Returns:
            tuple of (connection, cursor) to sqlite3 database
@@ -535,7 +553,7 @@ class PhotosDB:
        return _open_sql_file(self._tmp_db)

    def _copy_db_file(self, fname):
-        """ copies the sqlite database file to a temp file """
+        """copies the sqlite database file to a temp file"""
        """ returns the name of the temp file """
        """ If sqlite shared memory and write-ahead log files exist, those are copied too """
        # required because python's sqlite3 implementation can't read a locked file
@@ -587,13 +605,15 @@ class PhotosDB:
    #     return dest_path

    def _process_database4(self):
-        """ process the Photos database to extract info
-            works on Photos version <= 4.0 """
+        """process the Photos database to extract info
+        works on Photos version <= 4.0"""

        verbose = self._verbose
        verbose("Processing database.")
        verbose(f"Database version: {self._db_version}.")

+        self._photos_ver = 4  # only used in Photos 5+
+
        (conn, c) = _open_sql_file(self._tmp_db)

        # get info to associate persons with photos
@@ -778,6 +798,8 @@ class PhotosDB:
                "creation_date": album[8],
                "start_date": None,  # Photos 5 only
                "end_date": None,  # Photos 5 only
+                "customsortascending": None,  # Photos 5 only
+                "customsortkey": None,  # Photos 5 only
            }

        # get details about folders
@@ -1090,6 +1112,9 @@ class PhotosDB:
            # get info on special types
            self._dbphotos[uuid]["specialType"] = row[25]
            self._dbphotos[uuid]["masterModelID"] = row[26]
+            self._dbphotos[uuid]["pk"] = row[
+                26
+            ]  # same as masterModelID, to match Photos 5
            self._dbphotos[uuid]["panorama"] = True if row[25] == 1 else False
            self._dbphotos[uuid]["slow_mo"] = True if row[25] == 2 else False
            self._dbphotos[uuid]["time_lapse"] = True if row[25] == 3 else False
@@ -1180,6 +1205,16 @@ class PhotosDB:
            self._dbphotos[uuid]["import_uuid"] = row[44]
            self._dbphotos[uuid]["fok_import_session"] = None

+            # photos 5+ only, for shared photos
+            self._dbphotos[uuid]["cloudownerhashedpersonid"] = None
+
+            # compute signatures for finding possible duplicates
+            signature = self._duplicate_signature(uuid)
+            try:
+                self._db_signatures[signature].append(uuid)
+            except KeyError:
+                self._db_signatures[signature] = [uuid]
+
        # get additional details from RKMaster, needed for RAW processing
        verbose("Processing additional photo details.")
        c.execute(
@@ -1532,15 +1567,15 @@ class PhotosDB:
            logging.debug(pformat(self._dbphotos_burst))

    def _build_album_folder_hierarchy_4(self, uuid, folders=None):
-        """ recursively build folder/album hierarchy
-            uuid: parent uuid of the album being processed 
-                 (parent uuid is a folder in RKFolders)
-            folders: dict holding the folder hierarchy 
-            NOTE: This implementation is different than _build_album_folder_hierarchy_5 
-            which takes the uuid of the album being processed.  Here uuid is the parent uuid
-            of the parent folder album because in Photos <=4, folders are in RKFolders and 
-            albums in RKAlbums.  In Photos 5, folders are just special albums 
-            with kind = _PHOTOS_5_FOLDER_KIND """
+        """recursively build folder/album hierarchy
+        uuid: parent uuid of the album being processed
+             (parent uuid is a folder in RKFolders)
+        folders: dict holding the folder hierarchy
+        NOTE: This implementation is different than _build_album_folder_hierarchy_5
+        which takes the uuid of the album being processed.  Here uuid is the parent uuid
+        of the parent folder album because in Photos <=4, folders are in RKFolders and
+        albums in RKAlbums.  In Photos 5, folders are just special albums
+        with kind = _PHOTOS_5_FOLDER_KIND"""

        parent_uuid = self._dbfolder_details[uuid]["parentFolderUuid"]

@@ -1563,11 +1598,11 @@ class PhotosDB:
        return folders

    def _process_database5(self):
-        """ process the Photos database to extract info 
-            works on Photos version 5 and version 6
+        """process the Photos database to extract info
+        works on Photos version 5 and version 6

-            This is a big hairy 700 line function that should probably be refactored
-            but it works so don't touch it.
+        This is a big hairy 700 line function that should probably be refactored
+        but it works so don't touch it.
        """

        if _debug():
@@ -1582,10 +1617,14 @@ class PhotosDB:
        verbose(f"Database version: {self._db_version}, {photos_ver}.")
        asset_table = _DB_TABLE_NAMES[photos_ver]["ASSET"]
        keyword_join = _DB_TABLE_NAMES[photos_ver]["KEYWORD_JOIN"]
+        asset_album_table = _DB_TABLE_NAMES[photos_ver]["ASSET_ALBUM_TABLE"]
        album_join = _DB_TABLE_NAMES[photos_ver]["ALBUM_JOIN"]
        album_sort = _DB_TABLE_NAMES[photos_ver]["ALBUM_SORT_ORDER"]
+        asset_album_join = _DB_TABLE_NAMES[photos_ver]["ASSET_ALBUM_JOIN"]
        import_fok = _DB_TABLE_NAMES[photos_ver]["IMPORT_FOK"]
        depth_state = _DB_TABLE_NAMES[photos_ver]["DEPTH_STATE"]
+        uti_original_column = _DB_TABLE_NAMES[photos_ver]["UTI_ORIGINAL"]
+        hdr_type_column = _DB_TABLE_NAMES[photos_ver]["HDR_TYPE"]

        # Look for all combinations of persons and pictures
        if _debug():
@@ -1705,8 +1744,8 @@ class PhotosDB:
                {asset_table}.ZUUID,
                {album_sort}
                FROM {asset_table} 
-                JOIN Z_26ASSETS ON {album_join} = {asset_table}.Z_PK 
-                JOIN ZGENERICALBUM ON ZGENERICALBUM.Z_PK = Z_26ASSETS.Z_26ALBUMS
+                JOIN {asset_album_table} ON {album_join} = {asset_table}.Z_PK 
+                JOIN ZGENERICALBUM ON ZGENERICALBUM.Z_PK = {asset_album_join}
            """
        )

@@ -1744,7 +1783,9 @@ class PhotosDB:
            "ZTRASHEDSTATE, "  # 9
            "ZCREATIONDATE, "  # 10
            "ZSTARTDATE, "  # 11
-            "ZENDDATE "  # 12
+            "ZENDDATE, "  # 12
+            "ZCUSTOMSORTASCENDING, "  # 13
+            "ZCUSTOMSORTKEY "  # 14
            "FROM ZGENERICALBUM "
        )
        for album in c:
@@ -1764,6 +1805,8 @@ class PhotosDB:
                "creation_date": album[10],
                "start_date": album[11],
                "end_date": album[12],
+                "customsortascending": album[13],
+                "customsortkey": album[14],
            }

            # add cross-reference by pk to uuid
@@ -1873,7 +1916,7 @@ class PhotosDB:
                {asset_table}.ZAVALANCHEUUID,
                {asset_table}.ZAVALANCHEPICKTYPE,
                {asset_table}.ZKINDSUBTYPE,
-                {asset_table}.ZCUSTOMRENDEREDVALUE,
+                {asset_table}.{hdr_type_column},
                ZADDITIONALASSETATTRIBUTES.ZCAMERACAPTUREDEVICE,
                {asset_table}.ZCLOUDASSETGUID,
                ZADDITIONALASSETATTRIBUTES.ZREVERSELOCATIONDATA,
@@ -1892,7 +1935,9 @@ class PhotosDB:
                {asset_table}.ZVISIBILITYSTATE,
                {asset_table}.ZTRASHEDDATE,
                {asset_table}.ZSAVEDASSETTYPE,
-                {asset_table}.ZADDEDDATE
+                {asset_table}.ZADDEDDATE,
+                {asset_table}.Z_PK,
+                {asset_table}.ZCLOUDOWNERHASHEDPERSONID
                FROM {asset_table} 
                JOIN ZADDITIONALASSETATTRIBUTES ON ZADDITIONALASSETATTRIBUTES.ZASSET = {asset_table}.Z_PK 
                ORDER BY {asset_table}.ZUUID  """
@@ -1941,6 +1986,8 @@ class PhotosDB:
        # 39   ZGENERICASSET.ZTRASHEDDATE -- date item placed in the trash or null if not in trash
        # 40   ZGENERICASSET.ZSAVEDASSETTYPE -- how item imported
        # 41   ZGENERICASSET.ZADDEDDATE -- date item added to the library
+        # 42   ZGENERICASSET.Z_PK -- primary key
+        # 43   ZGENERICASSET.ZCLOUDOWNERHASHEDPERSONID -- used to look up owner name (for shared photos)

        for row in c:
            uuid = row[0]
@@ -2125,6 +2172,9 @@ class PhotosDB:
            except (ValueError, TypeError):
                info["added_date"] = datetime(1970, 1, 1)

+            info["pk"] = row[42]
+            info["cloudownerhashedpersonid"] = row[43]
+
            # initialize import session info which will be filled in later
            # not every photo has an import session so initialize all records now
            info["import_session"] = None
@@ -2145,6 +2195,13 @@ class PhotosDB:

            self._dbphotos[uuid] = info

+            # compute signatures for finding possible duplicates
+            signature = self._duplicate_signature(uuid)
+            try:
+                self._db_signatures[signature].append(uuid)
+            except KeyError:
+                self._db_signatures[signature] = [uuid]
+
            # # if row[19] is not None and ((row[20] == 2) or (row[20] == 4)):
            # # burst photo
            # if row[19] is not None:
@@ -2230,20 +2287,33 @@ class PhotosDB:

        # Get info on remote/local availability for photos in shared albums
        # Also get UTI of original image (zdatastoresubtype = 1)
-        c.execute(
-            f""" SELECT 
+        if self._photos_ver >= 7:
+            sql_missing = f""" SELECT 
                {asset_table}.ZUUID, 
                ZINTERNALRESOURCE.ZLOCALAVAILABILITY, 
                ZINTERNALRESOURCE.ZREMOTEAVAILABILITY,
                ZINTERNALRESOURCE.ZDATASTORESUBTYPE,
-                ZINTERNALRESOURCE.ZUNIFORMTYPEIDENTIFIER,
+                {uti_original_column},
+                null 
+                FROM {asset_table}
+                JOIN ZADDITIONALASSETATTRIBUTES ON ZADDITIONALASSETATTRIBUTES.ZASSET = {asset_table}.Z_PK 
+                JOIN ZINTERNALRESOURCE ON ZINTERNALRESOURCE.ZASSET = ZADDITIONALASSETATTRIBUTES.ZASSET 
+                WHERE  ZDATASTORESUBTYPE = 1 OR ZDATASTORESUBTYPE = 3 """
+        else:
+            sql_missing = f""" SELECT 
+                {asset_table}.ZUUID, 
+                ZINTERNALRESOURCE.ZLOCALAVAILABILITY, 
+                ZINTERNALRESOURCE.ZREMOTEAVAILABILITY,
+                ZINTERNALRESOURCE.ZDATASTORESUBTYPE,
+                {uti_original_column},
                ZUNIFORMTYPEIDENTIFIER.ZIDENTIFIER
                FROM {asset_table}
                JOIN ZADDITIONALASSETATTRIBUTES ON ZADDITIONALASSETATTRIBUTES.ZASSET = {asset_table}.Z_PK 
                JOIN ZINTERNALRESOURCE ON ZINTERNALRESOURCE.ZASSET = ZADDITIONALASSETATTRIBUTES.ZASSET 
                JOIN ZUNIFORMTYPEIDENTIFIER ON ZUNIFORMTYPEIDENTIFIER.Z_PK = ZINTERNALRESOURCE.ZUNIFORMTYPEIDENTIFIER 
                WHERE  ZDATASTORESUBTYPE = 1 OR ZDATASTORESUBTYPE = 3 """
-        )
+
+        c.execute(sql_missing)

        # Order of results:
        # 0 {asset_table}.ZUUID,
@@ -2303,20 +2373,36 @@ class PhotosDB:

        # get information about associted RAW images
        # RAW images have ZDATASTORESUBTYPE = 17
-        c.execute(
-            f""" SELECT
+        if self._photos_ver >= 7:
+            sql_raw = f""" SELECT
+                {asset_table}.ZUUID,
+                ZINTERNALRESOURCE.ZDATALENGTH, 
+                null,
+                ZINTERNALRESOURCE.ZDATASTORESUBTYPE,
+                ZINTERNALRESOURCE.ZRESOURCETYPE,
+                ZINTERNALRESOURCE.ZFILESYSTEMBOOKMARK
+                FROM {asset_table}
+                JOIN ZINTERNALRESOURCE ON ZINTERNALRESOURCE.ZASSET = ZADDITIONALASSETATTRIBUTES.ZASSET
+                JOIN ZADDITIONALASSETATTRIBUTES ON ZADDITIONALASSETATTRIBUTES.ZASSET = {asset_table}.Z_PK 
+                WHERE ZINTERNALRESOURCE.ZDATASTORESUBTYPE = 17
+            """
+        else:
+            sql_raw = f""" SELECT
                {asset_table}.ZUUID,
                ZINTERNALRESOURCE.ZDATALENGTH, 
                ZUNIFORMTYPEIDENTIFIER.ZIDENTIFIER,
                ZINTERNALRESOURCE.ZDATASTORESUBTYPE,
-                ZINTERNALRESOURCE.ZRESOURCETYPE
+                ZINTERNALRESOURCE.ZRESOURCETYPE,
+                ZINTERNALRESOURCE.ZFILESYSTEMBOOKMARK
                FROM {asset_table}
                JOIN ZINTERNALRESOURCE ON ZINTERNALRESOURCE.ZASSET = ZADDITIONALASSETATTRIBUTES.ZASSET
                JOIN ZADDITIONALASSETATTRIBUTES ON ZADDITIONALASSETATTRIBUTES.ZASSET = {asset_table}.Z_PK 
                JOIN ZUNIFORMTYPEIDENTIFIER ON ZUNIFORMTYPEIDENTIFIER.Z_PK =  ZINTERNALRESOURCE.ZUNIFORMTYPEIDENTIFIER
                WHERE ZINTERNALRESOURCE.ZDATASTORESUBTYPE = 17
-        """
-        )
+            """
+
+        c.execute(sql_raw)
+
        for row in c:
            uuid = row[0]
            if uuid in self._dbphotos:
@@ -2325,6 +2411,33 @@ class PhotosDB:
                self._dbphotos[uuid]["UTI_raw"] = row[2]
                self._dbphotos[uuid]["datastore_subtype"] = row[3]
                self._dbphotos[uuid]["resource_type"] = row[4]
+                self._dbphotos[uuid]["raw_bookmark"] = row[5]
+
+        # get paths for the relative imports for RAW+JPEG images
+        c.execute(
+            f""" SELECT
+            {asset_table}.ZUUID,
+            ZFILESYSTEMVOLUME.ZNAME,
+            ZFILESYSTEMBOOKMARK.ZPATHRELATIVETOVOLUME
+            FROM {asset_table} 
+            JOIN ZINTERNALRESOURCE ON ZINTERNALRESOURCE.ZASSET = ZADDITIONALASSETATTRIBUTES.ZASSET
+            JOIN ZADDITIONALASSETATTRIBUTES ON ZADDITIONALASSETATTRIBUTES.ZASSET = {asset_table}.Z_PK 
+            JOIN ZFILESYSTEMBOOKMARK ON ZFILESYSTEMBOOKMARK.ZRESOURCE = ZINTERNALRESOURCE.Z_PK
+            JOIN ZFILESYSTEMVOLUME ON ZFILESYSTEMVOLUME.Z_PK = ZINTERNALRESOURCE.ZFILESYSTEMVOLUME
+            WHERE ZINTERNALRESOURCE.ZDATASTORESUBTYPE = 17
+            """
+        )
+
+        # path to the raw image will be /Volumes/ZFILESYSTEMVOLUME.ZNAME/ZFILESYSTEMBOOKMARK.ZPATHRELATIVETOVOLUME
+        # 0: {asset_table}.ZUUID, -- UUID
+        # 1: ZFILESYSTEMVOLUME.ZNAME, -- name of the volume
+        # 2: ZFILESYSTEMBOOKMARK.ZPATHRELATIVETOVOLUME -- path to the raw image
+
+        for row in c:
+            uuid = row[0]
+            if uuid in self._dbphotos:
+                self._dbphotos[uuid]["raw_volume"] = row[1]
+                self._dbphotos[uuid]["raw_relative_path"] = row[2]

        # add faces and keywords to photo data
        for uuid in self._dbphotos:
@@ -2384,6 +2497,10 @@ class PhotosDB:
        verbose("Processing comments and likes for shared photos.")
        self._process_comments()

+        # process moments
+        verbose("Processing moments.")
+        self._process_moments()
+
        # done processing, dump debug data if requested
        verbose("Done processing details from Photos library.")
        if _debug():
@@ -2429,10 +2546,113 @@ class PhotosDB:
            logging.debug("Burst Photos (dbphotos_burst:")
            logging.debug(pformat(self._dbphotos_burst))

+    def _process_moments(self):
+        """Process data from ZMOMENT table"""
+        # _db_moment_pk is dict in form {pk: {moment info}} by ZMOMENT.Z_PK
+
+        if self._db_version <= _PHOTOS_4_VERSION:
+            raise NotImplementedError(
+                f"Moment info implemented for this database version"
+            )
+        else:
+            self._process_moment_5()
+
+    def _process_moment_5(self):
+        """Process moment info for Photos 5 databases"""
+
+        self._db_moment_pk = {}
+
+        results = self.execute(
+            f"""
+            SELECT 
+            Z_PK,
+            ZTIMEZONEOFFSET,
+            ZTRASHEDSTATE,
+            ZAPPROXIMATELATITUDE,
+            ZAPPROXIMATELONGITUDE,
+            ZENDDATE,
+            ZMODIFICATIONDATE,
+            ZREPRESENTATIVEDATE,
+            ZSTARTDATE,
+            ZSUBTITLE,
+            ZTITLE,
+            ZUUID
+            FROM ZMOMENT"""
+        )
+
+        # results
+        # 0  Z_PK,
+        # 1  ZTIMEZONEOFFSET,
+        # 2  ZTRASHEDSTATE,
+        # 3  ZAPPROXIMATELATITUDE,
+        # 4  ZAPPROXIMATELONGITUDE,
+        # 5  ZENDDATE,
+        # 6  ZMODIFICATIONDATE,
+        # 7  ZREPRESENTATIVEDATE,
+        # 8  ZSTARTDATE,
+        # 9  ZSUBTITLE,
+        # 10 ZTITLE,
+        # 11 ZUUID
+
+        for row in results:
+            moment_info = {}
+            moment_info["pk"] = row[0]
+            moment_info["timezoneOffset"] = row[1]
+            moment_info["trashedState"] = row[2]
+            moment_info["approximateLatitude"] = row[3]
+            moment_info["approximateLongitude"] = row[4]
+            moment_info["endDate"] = row[5]
+            moment_info["modificationDate"] = row[6]
+            moment_info["representativeDate"] = row[7]
+            moment_info["startDate"] = row[8]
+            moment_info["subtitle"] = row[9]
+            moment_info["title"] = row[10]
+            moment_info["uuid"] = row[11]
+
+            # if both lat/lon == -180, then it means location undefined
+            if (
+                moment_info["approximateLatitude"] == -180.0
+                and moment_info["approximateLongitude"] == -180.0
+            ):
+                moment_info["latitude"] = None
+                moment_info["longitude"] = None
+            else:
+                moment_info["latitude"] = moment_info["approximateLatitude"]
+                moment_info["longitude"] = moment_info["approximateLongitude"]
+
+            # process date stamps
+            offset_seconds = moment_info["timezoneOffset"] or 0
+            delta = timedelta(seconds=offset_seconds)
+            tz = timezone(delta)
+            for date_name in [
+                "startDate",
+                "endDate",
+                "modificationDate",
+                "representativeDate",
+            ]:
+                date_stamp = moment_info[date_name]
+                try:
+                    moment_date = datetime.fromtimestamp(date_stamp + TIME_DELTA)
+                    # save raw time stamp valu
+                    moment_info[date_name + "_timestamp"] = moment_info[date_name]
+                    moment_info[date_name] = moment_date.astimezone(tz=tz)
+                except ValueError:
+                    # sometimes imageDate is invalid so use 1 Jan 1970 in UTC as image date
+                    moment_date = datetime(1970, 1, 1)
+                    tz = timezone(timedelta(0))
+                    moment_info[date_name + "_timestamp"] = date_stamp
+                    moment_info[date_name] = moment_date.astimezone(tz=tz)
+
+            # process title/subtitle
+            moment_info["title"] = moment_info["title"] or ""
+            moment_info["subtitle"] = moment_info["subtitle"] or ""
+
+            self._db_moment_pk[moment_info["pk"]] = moment_info
+
    def _build_album_folder_hierarchy_5(self, uuid, folders=None):
-        """ recursively build folder/album hierarchy
-            uuid: uuid of the album/folder being processed
-            folders: dict holding the folder hierarchy """
+        """recursively build folder/album hierarchy
+        uuid: uuid of the album/folder being processed
+        folders: dict holding the folder hierarchy"""

        # get parent uuid
        parent = self._dbalbum_details[uuid]["parentfolder"]
@@ -2453,17 +2673,17 @@ class PhotosDB:
        return folders

    def _album_folder_hierarchy_list(self, album_uuid):
-        """ return appropriate album_folder_hierarchy_list for the _db_version """
+        """return appropriate album_folder_hierarchy_list for the _db_version"""
        if self._db_version <= _PHOTOS_4_VERSION:
            return self._album_folder_hierarchy_list_4(album_uuid)
        else:
            return self._album_folder_hierarchy_list_5(album_uuid)

    def _album_folder_hierarchy_list_4(self, album_uuid):
-        """ return hierarchical list of folder names album_uuid is contained in
-            the folder list is in form:
-            ["Top level folder", "sub folder 1", "sub folder 2"]
-            returns empty list of album is not in any folders """
+        """return hierarchical list of folder names album_uuid is contained in
+        the folder list is in form:
+        ["Top level folder", "sub folder 1", "sub folder 2"]
+        returns empty list of album is not in any folders"""
        try:
            folders = self._dbalbum_folders[album_uuid]
        except KeyError:
@@ -2471,7 +2691,7 @@ class PhotosDB:
            return []

        def _recurse_folder_hierarchy(folders, hierarchy=[]):
-            """ recursively walk the folders dict to build list of folder hierarchy """
+            """recursively walk the folders dict to build list of folder hierarchy"""
            if not folders:
                # empty folder dict (album has no folder hierarchy)
                return []
@@ -2497,10 +2717,10 @@ class PhotosDB:
        return hierarchy

    def _album_folder_hierarchy_list_5(self, album_uuid):
-        """ return hierarchical list of folder names album_uuid is contained in
-            the folder list is in form:
-            ["Top level folder", "sub folder 1", "sub folder 2"]
-            returns empty list of album is not in any folders """
+        """return hierarchical list of folder names album_uuid is contained in
+        the folder list is in form:
+        ["Top level folder", "sub folder 1", "sub folder 2"]
+        returns empty list of album is not in any folders"""
        try:
            folders = self._dbalbum_folders[album_uuid]
        except KeyError:
@@ -2508,7 +2728,7 @@ class PhotosDB:
            return []

        def _recurse_folder_hierarchy(folders, hierarchy=[]):
-            """ recursively walk the folders dict to build list of folder hierarchy """
+            """recursively walk the folders dict to build list of folder hierarchy"""

            if not folders:
                # empty folder dict (album has no folder hierarchy)
@@ -2540,15 +2760,15 @@ class PhotosDB:
            return self._album_folder_hierarchy_folderinfo_5(album_uuid)

    def _album_folder_hierarchy_folderinfo_4(self, album_uuid):
-        """ return hierarchical list of FolderInfo objects album_uuid is contained in
-            ["Top level folder", "sub folder 1", "sub folder 2"]
-            returns empty list of album is not in any folders """
+        """return hierarchical list of FolderInfo objects album_uuid is contained in
+        ["Top level folder", "sub folder 1", "sub folder 2"]
+        returns empty list of album is not in any folders"""
        # title = photosdb._dbalbum_details[album_uuid]["title"]
        folders = self._dbalbum_folders[album_uuid]
        # logging.warning(f"uuid = {album_uuid}, folder = {folders}")

        def _recurse_folder_hierarchy(folders, hierarchy=[]):
-            """ recursively walk the folders dict to build list of folder hierarchy """
+            """recursively walk the folders dict to build list of folder hierarchy"""
            # logging.warning(f"folders={folders},hierarchy = {hierarchy}")
            if not folders:
                # empty folder dict (album has no folder hierarchy)
@@ -2574,14 +2794,14 @@ class PhotosDB:
        return hierarchy

    def _album_folder_hierarchy_folderinfo_5(self, album_uuid):
-        """ return hierarchical list of FolderInfo objects album_uuid is contained in
-            ["Top level folder", "sub folder 1", "sub folder 2"]
-            returns empty list of album is not in any folders """
+        """return hierarchical list of FolderInfo objects album_uuid is contained in
+        ["Top level folder", "sub folder 1", "sub folder 2"]
+        returns empty list of album is not in any folders"""
        # title = photosdb._dbalbum_details[album_uuid]["title"]
        folders = self._dbalbum_folders[album_uuid]

        def _recurse_folder_hierarchy(folders, hierarchy=[]):
-            """ recursively walk the folders dict to build list of folder hierarchy """
+            """recursively walk the folders dict to build list of folder hierarchy"""

            if not folders:
                # empty folder dict (album has no folder hierarchy)
@@ -2606,19 +2826,19 @@ class PhotosDB:
        return hierarchy

    def _get_album_uuids(self, shared=False, import_session=False):
-        """ Return list of album UUIDs found in photos database
-        
+        """Return list of album UUIDs found in photos database
+
            Filters out albums in the trash and any special album types
-        
+
        Args:
            shared: boolean; if True, returns shared albums, else normal albums
            import_session: boolean, if True, returns import session albums, else normal or shared albums
            Note: flags (shared, import_session) are mutually exclusive
-        
+
        Raises:
            ValueError: raised if mutually exclusive flags passed

-        Returns: list of album UUIDs 
+        Returns: list of album UUIDs
        """
        if shared and import_session:
            raise ValueError(
@@ -2670,14 +2890,14 @@ class PhotosDB:
        return album_list

    def _get_albums(self, shared=False):
-        """ Return list of album titles found in photos database
+        """Return list of album titles found in photos database
            Albums may have duplicate titles -- these will be treated as a single album.
-        
+
            Filters out albums in the trash and any special album types

        Args:
            shared: boolean; if True, returns shared albums, else normal albums
-        
+
        Returns: list of album names
        """

@@ -2696,7 +2916,7 @@ class PhotosDB:
        to_date=None,
        intrash=False,
    ):
-        """ Return a list of PhotoInfo objects
+        """Return a list of PhotoInfo objects
        If called with no args, returns the entire database of photos
        If called with args, returns photos matching the args (e.g. keywords, persons, etc.)
        If more than one arg, returns photos matching all the criteria (e.g. keywords AND persons)
@@ -2711,10 +2931,10 @@ class PhotosDB:
            persons: list of persons to search for
            albums: list of album names to search for
            images: if True, returns image files, if False, does not return images; default is True
-            movies: if True, returns movie files, if False, does not return movies; default is True 
+            movies: if True, returns movie files, if False, does not return movies; default is True
            from_date: return photos with creation date >= from_date (datetime.datetime object, default None)
            to_date: return photos with creation date <= to_date (datetime.datetime object, default None)
-            intrash: if True, returns only images in "Recently deleted items" folder, 
+            intrash: if True, returns only images in "Recently deleted items" folder,
                     if False returns only photos that aren't deleted; default is False

        Returns:
@@ -2821,7 +3041,7 @@ class PhotosDB:
        return photoinfo

    def get_photo(self, uuid):
-        """ Returns a single photo matching uuid
+        """Returns a single photo matching uuid

        Arguments:
            uuid: the UUID of photo to get
@@ -2836,7 +3056,7 @@ class PhotosDB:

    # TODO: add to docs and test
    def photos_by_uuid(self, uuids):
-        """ Returns a list of photos with UUID in uuids.
+        """Returns a list of photos with UUID in uuids.
            Does not generate error if invalid or missing UUID passed.
            This is faster than using PhotosDB.photos if you have list of UUIDs.
            Returns photos regardless of intrash state.
@@ -3188,11 +3408,12 @@ class PhotosDB:

        if options.regex:
            flags = re.IGNORECASE if options.ignore_case else 0
+            render_options = RenderOptions(none_str="")
+            photo_list = []
            for regex, template in options.regex:
                regex = re.compile(regex, flags)
-                photo_list = []
                for p in photos:
-                    rendered, _ = p.render_template(template, none_str="")
+                    rendered, _ = p.render_template(template, render_options)
                    for value in rendered:
                        if regex.search(value):
                            photo_list.append(p)
@@ -3207,8 +3428,99 @@ class PhotosDB:
                except Exception as e:
                    raise ValueError(f"Invalid query_eval CRITERIA: {e}")

+        if options.duplicate:
+            no_date = datetime(1970, 1, 1)
+            tz = timezone(timedelta(0))
+            no_date = no_date.astimezone(tz=tz)
+            photos = sorted(
+                [p for p in photos if p.duplicates],
+                key=lambda x: x.date_added or no_date,
+            )
+            # gather all duplicates but ensure each uuid is only represented once
+            photodict = OrderedDict()
+            for p in photos:
+                if p.uuid not in photodict:
+                    photodict[p.uuid] = p
+                    for d in sorted(
+                        p.duplicates, key=lambda x: x.date_added or no_date
+                    ):
+                        if d.uuid not in photodict:
+                            photodict[d.uuid] = d
+            photos = list(photodict.values())
+
+            # filter for deleted as photo.duplicates will include photos in the trash
+            if not (options.deleted or options.deleted_only):
+                photos = [p for p in photos if not p.intrash]
+            if options.deleted_only:
+                photos = [p for p in photos if p.intrash]
+
+        if options.location:
+            photos = [p for p in photos if p.location != (None, None)]
+        elif options.no_location:
+            photos = [p for p in photos if p.location == (None, None)]
+
+        if options.selected:
+            # photos selected in Photos app
+            try:
+                # catch AppleScript errors as the scripting interfce to Photos is flaky
+                selected = photoscript.PhotosLibrary().selection
+                selected_uuid = [p.uuid for p in selected]
+                photos = [p for p in photos if p.uuid in selected_uuid]
+            except Exception:
+                # no photos selected or a selected photo was "open"
+                # selection only works if photos selected in main media browser
+                photos = []
+
+        if options.exif:
+            matching_photos = []
+            for p in photos:
+                if not p.exiftool:
+                    continue
+                exifdata = p.exiftool.asdict(normalized=True)
+                exifdata.update(p.exiftool.asdict(tag_groups=False, normalized=True))
+                for exiftag, exifvalue in options.exif:
+                    if options.ignore_case:
+                        exifvalue = exifvalue.lower()
+                        exifdata_value = exifdata.get(exiftag.lower(), "")
+                        if isinstance(exifdata_value, str):
+                            exifdata_value = exifdata_value.lower()
+                        elif isinstance(exifdata_value, Iterable):
+                            exifdata_value = [v.lower() for v in exifdata_value]
+                        else:
+                            exifdata_value = str(exifdata_value)
+
+                        if exifvalue in exifdata_value:
+                            matching_photos.append(p)
+                    else:
+                        exifdata_value = exifdata.get(exiftag.lower(), "")
+                        if not isinstance(exifdata_value, (str, Iterable)):
+                            exifdata_value = str(exifdata_value)
+                        if exifvalue in exifdata_value:
+                            matching_photos.append(p)
+            photos = matching_photos
+
+        if options.function:
+            for function in options.function:
+                photos = function[0](photos)
+
        return photos

+    def execute(self, sql):
+        """Execute sql statement and return cursor"""
+        self._db_connection, _ = self.get_db_connection()
+        return self._db_connection.cursor().execute(sql)
+
+    def _duplicate_signature(self, uuid):
+        """Compute a signature for finding possible duplicates"""
+        return (
+            self._dbphotos[uuid]["original_filesize"],
+            self._dbphotos[uuid]["imageDate"],
+            self._dbphotos[uuid]["height"],
+            self._dbphotos[uuid]["width"],
+            self._dbphotos[uuid]["UTI"],
+            self._dbphotos[uuid]["hasAdjustments"],
+        )
+
    def __repr__(self):
        return f"osxphotos.{self.__class__.__name__}(dbfile='{self.db_path}')"

@@ -3220,11 +3532,15 @@ class PhotosDB:
        return False

    def __len__(self):
-        """ Returns number of photos in the database
-            Includes recently deleted photos and non-selected burst images
+        """Returns number of photos in the database
+        Includes recently deleted photos and non-selected burst images
        """
        return len(self._dbphotos)

+    def __del__(self):
+        if getattr(self, "_db_connection", None):
+            self._db_connection.close()
+

 def _get_photos_by_attribute(photos, attribute, values, ignore_case):
    """Search for photos based on values being in PhotoInfo.attribute
@@ -3251,4 +3567,4 @@ def _get_photos_by_attribute(photos, attribute, values, ignore_case):
    else:
        for x in values:
            photos_search.extend(p for p in photos if x in getattr(p, attribute))
-    return photos_search
+    return list(set(photos_search))
--- a/osxphotos/photosdb/photosdb_utils.py
+++ b/osxphotos/photosdb/photosdb_utils.py
@@ -4,8 +4,13 @@ import logging
 import plistlib

 from .._constants import (
+    _PHOTOS_2_VERSION,
+    _PHOTOS_3_VERSION,
+    _PHOTOS_4_VERSION,
    _PHOTOS_5_MODEL_VERSION,
+    _PHOTOS_5_VERSION,
    _PHOTOS_6_MODEL_VERSION,
+    _PHOTOS_7_MODEL_VERSION,
    _TESTED_DB_VERSIONS,
 )
 from ..utils import _open_sql_file
@@ -73,12 +78,41 @@ def get_db_model_version(db_file):

    model_ver = get_model_version(db_file)
    if _PHOTOS_5_MODEL_VERSION[0] <= model_ver <= _PHOTOS_5_MODEL_VERSION[1]:
-        db_ver = 5
+        return 5
    elif _PHOTOS_6_MODEL_VERSION[0] <= model_ver <= _PHOTOS_6_MODEL_VERSION[1]:
-        db_ver = 6
+        return 6
+    elif _PHOTOS_7_MODEL_VERSION[0] <= model_ver <= _PHOTOS_7_MODEL_VERSION[1]:
+        return 7
    else:
        logging.warning(f"Unknown model version: {model_ver}")
        # cross our fingers and try latest version
-        db_ver = 6
+        return 7

-    return db_ver
+
+class UnknownLibraryVersion(Exception):
+    pass
+
+
+def get_photos_library_version(library_path):
+    """Return int indicating which Photos version a library was created with """
+    library_path = pathlib.Path(library_path)
+    db_ver = get_db_version(str(library_path / "database" / "photos.db"))
+    db_ver = int(db_ver)
+    if db_ver == int(_PHOTOS_2_VERSION):
+        return 2
+    if db_ver == int(_PHOTOS_3_VERSION):
+        return 3
+    if db_ver == int(_PHOTOS_4_VERSION):
+        return 4
+    if db_ver != int(_PHOTOS_5_VERSION):
+        raise UnknownLibraryVersion(f"db_ver = {db_ver}")
+
+    model_ver = get_model_version(str(library_path / "database" / "Photos.sqlite"))
+    model_ver = int(model_ver)
+    if _PHOTOS_5_MODEL_VERSION[0] <= model_ver <= _PHOTOS_5_MODEL_VERSION[1]:
+        return 5
+    if _PHOTOS_6_MODEL_VERSION[0] <= model_ver <= _PHOTOS_6_MODEL_VERSION[1]:
+        return 6
+    if _PHOTOS_7_MODEL_VERSION[0] <= model_ver <= _PHOTOS_7_MODEL_VERSION[1]:
+        return 7
+    raise UnknownLibraryVersion(f"db_ver = {db_ver}, model_ver = {model_ver}")
--- a/osxphotos/phototemplate.md
+++ b/osxphotos/phototemplate.md
@@ -1,4 +1,4 @@
-The templating system converts one or template statements, written in osxphotos templating language, to one or more rendered values using information from the photo being processed. 
+The templating system converts one or template statements, written in osxphotos metadata templating language, to one or more rendered values using information from the photo being processed. 

 In its simplest form, a template statement has the form: `"{template_field}"`, for example `"{title}"` which would resolve to the title of the photo.

@@ -39,6 +39,7 @@ Valid filters are:
 - braces: Enclose value in curly braces, e.g. 'value => '{value}'.
 - parens: Enclose value in parentheses, e.g. 'value' => '(value')
 - brackets: Enclose value in brackets, e.g. 'value' => '[value]'
+- shell_quote: Quotes the value for safe usage in the shell, e.g. My file.jpeg => 'My file.jpeg'; only adds quotes if needed.
 - function: Run custom python function to filter value; use in format 'function:/path/to/file.py::function_name'. See example at https://github.com/RhetTbull/osxphotos/blob/master/examples/template_filter.py
 <!-- OSXPHOTOS-FILTER-TABLE:END -->

--- a/osxphotos/phototemplate.py
+++ b/osxphotos/phototemplate.py
@@ -1,24 +1,33 @@
-""" Custom template system for osxphotos, implements osxphotos template language (OTL) """
+""" Custom template system for osxphotos, implements metadata template language (MTL) """

 import datetime
+import json
 import locale
+import logging
 import os
 import pathlib
+import shlex
 import sys
+from dataclasses import dataclass
+from typing import Optional

 from textx import TextXSyntaxError, metamodel_from_file

-from ._constants import _UNKNOWN_PERSON
+from ._constants import _UNKNOWN_PERSON, TEXT_DETECTION_CONFIDENCE_THRESHOLD
 from ._version import __version__
 from .datetime_formatter import DateTimeFormatter
 from .exiftool import ExifToolCaching
+from .export_db import ExportDB_ABC, ExportDBInMemory
 from .path_utils import sanitize_dirname, sanitize_filename, sanitize_pathpart
-from .utils import load_function
+from .text_detection import detect_text
+from .utils import expand_and_validate_filepath, load_function
+
+# TODO: a lot of values are passed from function to function like path_sep--make these all class properties

 # ensure locale set to user's locale
 locale.setlocale(locale.LC_ALL, "")

-OTL_GRAMMAR_MODEL = str(pathlib.Path(__file__).parent / "phototemplate.tx")
+MTL_GRAMMAR_MODEL = str(pathlib.Path(__file__).parent / "phototemplate.tx")

 """TextX metamodel for osxphotos template language """

@@ -122,6 +131,29 @@ TEMPLATE_SUBSTITUTIONS = {
    "{exif.camera_model}": "Camera model from original photo's EXIF information as imported by Photos, e.g. 'iPhone 6s'",
    "{exif.lens_model}": "Lens model from original photo's EXIF information as imported by Photos, e.g. 'iPhone 6s back camera 4.15mm f/2.2'",
    "{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'",
+    "{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. ",
+    "{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 a period and the 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. "
+    + "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 append a period and the 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. "
+    + "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: ','",
    "{semicolon}": "A semicolon: ';'",
    "{questionmark}": "A question mark: '?'",
@@ -137,7 +169,12 @@ TEMPLATE_SUBSTITUTIONS = {
    "{cr}": r"A carriage return: '\r'",
    "{crlf}": r"a carriage return + line feed: '\r\n'",
    "{osxphotos_version}": f"The osxphotos version, e.g. '{__version__}'",
-    "{osxphotos_cmd_line}": "The full command line used to run osxphotos"
+    "{osxphotos_cmd_line}": "The full command line used to run osxphotos",
+}
+
+TEMPLATE_SUBSTITUTIONS_PATHLIB = {
+    "{export_dir}": "The full path to the export directory",
+    "{filepath}": "The full path to the exported file",
 }

 # Permitted multi-value substitutions (each of these returns None or 1 or more values)
@@ -164,6 +201,15 @@ TEMPLATE_SUBSTITUTIONS_MULTI_VALUED = {
    + "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 https://rhettbull.github.io/osxphotos/ for additional documentation on the PhotoInfo class.",
+    "{detected_text}": "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}'; "
+    + f"The default confidence threshold is {TEXT_DETECTION_CONFIDENCE_THRESHOLD}. "
+    + "'{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.",
+    "{shell_quote}": "Use in form '{shell_quote,TEMPLATE}'; quotes the rendered TEMPLATE value(s) for safe usage in the shell, e.g. My file.jpeg => 'My file.jpeg'; only adds quotes if needed.",
+    "{strip}": "Use in form '{strip,TEMPLATE}'; strips whitespace from begining and end of rendered TEMPLATE value(s).",
    "{function}": "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. "
@@ -179,7 +225,8 @@ FILTER_VALUES = {
    "braces": "Enclose value in curly braces, e.g. 'value => '{value}'.",
    "parens": "Enclose value in parentheses, e.g. 'value' => '(value')",
    "brackets": "Enclose value in brackets, e.g. 'value' => '[value]'",
-    "function": "Run custom python function to filter value; use in format 'function:/path/to/file.py::function_name'. See example at https://github.com/RhetTbull/osxphotos/blob/master/examples/template_filter.py"
+    "shell_quote": "Quotes the value for safe usage in the shell, e.g. My file.jpeg => 'My file.jpeg'; only adds quotes if needed.",
+    "function": "Run custom python function to filter value; use in format 'function:/path/to/file.py::function_name'. See example at https://github.com/RhetTbull/osxphotos/blob/master/examples/template_filter.py",
 }

 # Just the substitutions without the braces
@@ -187,13 +234,18 @@ SINGLE_VALUE_SUBSTITUTIONS = [
    field.replace("{", "").replace("}", "") for field in TEMPLATE_SUBSTITUTIONS
 ]

-# Just the multi-valued substitution names without the braces
+PATHLIB_SUBSTITUTIONS = [
+    field.replace("{", "").replace("}", "") for field in TEMPLATE_SUBSTITUTIONS_PATHLIB
+]
+
 MULTI_VALUE_SUBSTITUTIONS = [
    field.replace("{", "").replace("}", "")
    for field in TEMPLATE_SUBSTITUTIONS_MULTI_VALUED
 ]

-FIELD_NAMES = SINGLE_VALUE_SUBSTITUTIONS + MULTI_VALUE_SUBSTITUTIONS
+FIELD_NAMES = (
+    SINGLE_VALUE_SUBSTITUTIONS + MULTI_VALUE_SUBSTITUTIONS + PATHLIB_SUBSTITUTIONS
+)

 # default values for string manipulation template options
 INPLACE_DEFAULT = ","
@@ -217,36 +269,78 @@ PUNCTUATION = {
 }


+@dataclass
+class RenderOptions:
+    """Options for PhotoTemplate.render
+
+    template: str template
+    none_str: str to use default for None values, default is '_'
+    path_sep: optional string to use as path separator, default is os.path.sep
+    expand_inplace: expand multi-valued substitutions in-place as a single string
+        instead of returning individual strings
+    inplace_sep: optional string to use as separator between multi-valued keywords
+    with expand_inplace; default is ','
+    filename: if True, template output will be sanitized to produce valid file name
+    dirname: if True, template output will be sanitized to produce valid directory name
+    strip: if True, strips leading/trailing whitespace from rendered templates
+    edited_version: set to True if you want {edited_version} to resolve to True (e.g. exporting edited version of photo)
+    export_dir: set to the export directory if you want to evalute {export_dir} template
+    dest_path: set to the destination path of the photo (for use by {function} template), only valid with --filename
+    filepath: set to value for filepath of the exported photo if you want to evaluate {filepath} template
+    quote: quote path templates for execution in the shell
+    exportdb: ExportDB object
+    """
+
+    none_str: str = "_"
+    path_sep: Optional[str] = PATH_SEP_DEFAULT
+    expand_inplace: bool = False
+    inplace_sep: Optional[str] = INPLACE_DEFAULT
+    filename: bool = False
+    dirname: bool = False
+    strip: bool = False
+    edited_version: bool = False
+    export_dir: Optional[str] = None
+    dest_path: Optional[str] = None
+    filepath: Optional[str] = None
+    quote: bool = False
+    exportdb: Optional[ExportDB_ABC] = None
+
+
 class PhotoTemplateParser:
-    """Parser for PhotoTemplate """
+    """Parser for PhotoTemplate"""

    # implemented as Singleton

    def __new__(cls, *args, **kwargs):
-        """ create new object or return instance of already created singleton """
+        """create new object or return instance of already created singleton"""
        if not hasattr(cls, "instance") or not cls.instance:
            cls.instance = super().__new__(cls)

        return cls.instance

    def __init__(self):
-        """ return existing singleton or create a new one """
+        """return existing singleton or create a new one"""

        if hasattr(self, "metamodel"):
            return

-        self.metamodel = metamodel_from_file(OTL_GRAMMAR_MODEL, skipws=False)
+        self.metamodel = metamodel_from_file(MTL_GRAMMAR_MODEL, skipws=False)

    def parse(self, template_statement):
-        """Parse a template_statement string """
+        """Parse a template_statement string"""
        return self.metamodel.model_from_str(template_statement)

+    def fields(self, template_statement):
+        """Return list of fields found in a template statement; does not verify that fields are valid"""
+        model = self.parse(template_statement)
+        return [ts.template.field for ts in model.template_strings if ts.template]
+

 class PhotoTemplate:
-    """ PhotoTemplate class to render a template string from a PhotoInfo object """
+    """PhotoTemplate class to render a template string from a PhotoInfo object"""

    def __init__(self, photo, exiftool_path=None):
-        """ Inits PhotoTemplate class with photo
+        """Inits PhotoTemplate class with photo

        Args:
            photo: a PhotoInfo instance.
@@ -262,49 +356,58 @@ class PhotoTemplate:
        # get parser singleton
        self.parser = PhotoTemplateParser()

-        # should {edited_version} render True?
-        self.edited_version = False
+        # initialize render options
+        # this will be done in render() but for testing, some of the lookup functions are called directly
+        options = RenderOptions()
+        self.options = options
+        self.path_sep = options.path_sep
+        self.inplace_sep = options.inplace_sep
+        self.edited_version = options.edited_version
+        self.none_str = options.none_str
+        self.expand_inplace = options.expand_inplace
+        self.filename = options.filename
+        self.dirname = options.dirname
+        self.strip = options.strip
+        self.export_dir = options.export_dir
+        self.filepath = options.filepath
+        self.quote = options.quote
+        self.dest_path = options.dest_path
+        self.exportdb = options.exportdb or ExportDBInMemory(None)

    def render(
        self,
-        template,
-        none_str="_",
-        path_sep=None,
-        expand_inplace=False,
-        inplace_sep=None,
-        filename=False,
-        dirname=False,
-        strip=False,
-        edited_version=False,
+        template: str,
+        options: RenderOptions,
    ):
-        """ Render a filename or directory template 
+        """Render a filename or directory template

        Args:
-            template: str template 
-            none_str: str to use default for None values, default is '_' 
-            path_sep: optional string to use as path separator, default is os.path.sep
-            expand_inplace: expand multi-valued substitutions in-place as a single string 
-                instead of returning individual strings
-            inplace_sep: optional string to use as separator between multi-valued keywords
-            with expand_inplace; default is ','
-            filename: if True, template output will be sanitized to produce valid file name
-            dirname: if True, template output will be sanitized to produce valid directory name 
-            strip: if True, strips leading/trailing whitespace from rendered templates
-            edited_version: set to True if you want {edited_version} to resolve to True (e.g. exporting edited version of photo)
+            template: str template
+            options: a RenderOptions instance

        Returns:
            ([rendered_strings], [unmatched]): tuple of list of rendered strings and list of unmatched template values
        """

-        if path_sep is None:
-            path_sep = PATH_SEP_DEFAULT
-
-        if inplace_sep is None:
-            inplace_sep = INPLACE_DEFAULT
-
        if type(template) is not str:
            raise TypeError(f"template must be type str, not {type(template)}")

+        self.options = options
+        self.path_sep = options.path_sep
+        self.inplace_sep = options.inplace_sep
+        self.edited_version = options.edited_version
+        self.none_str = options.none_str
+        self.expand_inplace = options.expand_inplace
+        self.filename = options.filename
+        self.dirname = options.dirname
+        self.strip = options.strip
+        self.export_dir = options.export_dir
+        self.dest_path = options.dest_path
+        self.filepath = options.filepath
+        self.quote = options.quote
+        self.dest_path = options.dest_path
+        self.exportdb = options.exportdb or self.exportdb
+
        try:
            model = self.parser.parse(template)
        except TextXSyntaxError as e:
@@ -314,53 +417,29 @@ class PhotoTemplate:
            # empty string
            return [], []

-        self.edited_version = edited_version
-
-        return self._render_statement(
-            model,
-            none_str=none_str,
-            path_sep=path_sep,
-            expand_inplace=expand_inplace,
-            inplace_sep=inplace_sep,
-            filename=filename,
-            dirname=dirname,
-            strip=strip,
-        )
+        return self._render_statement(model)

    def _render_statement(
        self,
        statement,
-        none_str="_",
        path_sep=None,
-        expand_inplace=False,
-        inplace_sep=None,
-        filename=False,
-        dirname=False,
-        strip=False,
    ):
+        path_sep = path_sep or self.path_sep
        results = []
        unmatched = []
        for ts in statement.template_strings:
            results, unmatched = self._render_template_string(
-                ts,
-                none_str=none_str,
-                path_sep=path_sep,
-                expand_inplace=expand_inplace,
-                inplace_sep=inplace_sep,
-                filename=filename,
-                dirname=dirname,
-                results=results,
-                unmatched=unmatched,
+                ts, results=results, unmatched=unmatched, path_sep=path_sep
            )

        rendered_strings = results

-        if filename:
+        if self.filename:
            rendered_strings = [
                sanitize_filename(rendered_str) for rendered_str in rendered_strings
            ]

-        if strip:
+        if self.strip:
            rendered_strings = [
                rendered_str.strip() for rendered_str in rendered_strings
            ]
@@ -370,16 +449,11 @@ class PhotoTemplate:
    def _render_template_string(
        self,
        ts,
-        none_str="_",
-        path_sep=None,
-        expand_inplace=False,
-        inplace_sep=None,
-        filename=False,
-        dirname=False,
+        path_sep,
        results=None,
        unmatched=None,
    ):
-        """Render a TemplateString object """
+        """Render a TemplateString object"""

        results = results or [""]
        unmatched = unmatched or []
@@ -387,7 +461,8 @@ class PhotoTemplate:
        if ts.template:
            # have a template field to process
            field = ts.template.field
-            if field not in FIELD_NAMES and not field.startswith("photo"):
+            field_part = field.split(".")[0]
+            if field not in FIELD_NAMES and field_part not in FIELD_NAMES:
                unmatched.append(field)
                return [], unmatched

@@ -414,12 +489,7 @@ class PhotoTemplate:
                if ts.template.bool.value is not None:
                    bool_val, u = self._render_statement(
                        ts.template.bool.value,
-                        none_str=none_str,
                        path_sep=path_sep,
-                        expand_inplace=expand_inplace,
-                        inplace_sep=inplace_sep,
-                        filename=filename,
-                        dirname=dirname,
                    )
                    unmatched.extend(u)
                else:
@@ -435,12 +505,7 @@ class PhotoTemplate:
                if ts.template.default.value is not None:
                    default, u = self._render_statement(
                        ts.template.default.value,
-                        none_str=none_str,
                        path_sep=path_sep,
-                        expand_inplace=expand_inplace,
-                        inplace_sep=inplace_sep,
-                        filename=filename,
-                        dirname=dirname,
                    )
                    unmatched.extend(u)
                else:
@@ -457,12 +522,7 @@ class PhotoTemplate:
                    # conditional value is also a TemplateString
                    conditional_value, u = self._render_statement(
                        ts.template.conditional.value,
-                        none_str=none_str,
                        path_sep=path_sep,
-                        expand_inplace=expand_inplace,
-                        inplace_sep=inplace_sep,
-                        filename=filename,
-                        dirname=dirname,
                    )
                    unmatched.extend(u)
                else:
@@ -474,14 +534,16 @@ class PhotoTemplate:
                conditional_value = []

            vals = []
-            if field in SINGLE_VALUE_SUBSTITUTIONS:
+            if (
+                field in SINGLE_VALUE_SUBSTITUTIONS
+                or field.split(".")[0] in SINGLE_VALUE_SUBSTITUTIONS
+            ):
                vals = self.get_template_value(
                    field,
                    default=default,
-                    delim=delim or inplace_sep,
-                    path_sep=path_sep,
-                    filename=filename,
-                    dirname=dirname,
+                    subfield=subfield,
+                    # delim=delim or self.inplace_sep,
+                    # path_sep=path_sep,
                )
            elif field == "exiftool":
                if subfield is None:
@@ -489,7 +551,7 @@ class PhotoTemplate:
                        "SyntaxError: GROUP:NAME subfield must not be null with {exiftool:GROUP:NAME}'"
                    )
                vals = self.get_template_value_exiftool(
-                    subfield, filename=filename, dirname=dirname
+                    subfield,
                )
            elif field == "function":
                if subfield is None:
@@ -497,21 +559,23 @@ class PhotoTemplate:
                        "SyntaxError: filename and function must not be null with {function::filename.py:function_name}"
                    )
                vals = self.get_template_value_function(
-                    subfield, filename=filename, dirname=dirname
+                    subfield,
                )
            elif field in MULTI_VALUE_SUBSTITUTIONS or field.startswith("photo"):
                vals = self.get_template_value_multi(
-                    field, path_sep=path_sep, filename=filename, dirname=dirname
+                    field, subfield, path_sep=path_sep, default=default
                )
+            elif field.split(".")[0] in PATHLIB_SUBSTITUTIONS:
+                vals = self.get_template_value_pathlib(field)
            else:
                unmatched.append(field)
                return [], unmatched

            vals = [val for val in vals if val is not None]

-            if expand_inplace or delim is not None:
-                sep = delim if delim is not None else inplace_sep
-                vals = [sep.join(sorted(vals))]
+            if self.expand_inplace or delim is not None:
+                sep = delim if delim is not None else self.inplace_sep
+                vals = [sep.join(sorted(vals))] if vals else []

            for filter_ in filters:
                vals = self.get_template_value_filter(filter_, vals)
@@ -531,7 +595,7 @@ class PhotoTemplate:
                # have a conditional operator

                def string_test(test_function):
-                    """ Perform string comparison using test_function; closure to capture conditional_value, vals, negation """
+                    """Perform string comparison using test_function; closure to capture conditional_value, vals, negation"""
                    match = False
                    for c in conditional_value:
                        for v in vals:
@@ -546,18 +610,14 @@ class PhotoTemplate:
                        return []

                def comparison_test(test_function):
-                    """ Perform numerical comparisons using test_function; closure to capture conditional_val, vals, negation """
+                    """Perform numerical comparisons using test_function; closure to capture conditional_val, vals, negation"""
                    if len(vals) != 1 or len(conditional_value) != 1:
                        raise ValueError(
                            f"comparison operators may only be used with a single value: {vals} {conditional_value}"
                        )
                    try:
-                        match = (
-                            True
-                            if test_function(
-                                float(vals[0]), float(conditional_value[0])
-                            )
-                            else False
+                        match = bool(
+                            test_function(float(vals[0]), float(conditional_value[0]))
                        )
                        if (match and not negation) or (negation and not match):
                            return ["True"]
@@ -607,7 +667,7 @@ class PhotoTemplate:
            if is_bool:
                vals = default if not vals else bool_val
            elif not vals:
-                vals = default or [none_str]
+                vals = default or [self.none_str]

            pre = ts.pre or ""
            post = ts.post or ""
@@ -632,31 +692,30 @@ class PhotoTemplate:
        self,
        field,
        default,
-        bool_val=None,
-        delim=None,
-        path_sep=None,
-        filename=False,
-        dirname=False,
+        subfield=None,
+        # bool_val=None,
+        # delim=None,
+        # path_sep=None,
    ):
        """lookup value for template field (single-value template substitutions)

        Args:
            field: template field to find value for.
            default: the default value provided by the user
-            bool_val: True value if expression is boolean 
+            bool_val: True value if expression is boolean
            delim: delimiter for expand in place
            path_sep: path separator for fields that are path-like
-            filename: if True, template output will be sanitized to produce valid file name
-            dirname: if True, template output will be sanitized to produce valid directory name 
-        
+            subfield: subfield (value after : in field)
+
        Returns:
            The matching template value (which may be None).

        Raises:
            ValueError if no rule exists for field.
        """
-        if field not in FIELD_NAMES:
-            raise ValueError(f"SyntaxError: Unknown field: {field}")
+
+        if self.photo.uuid is None:
+            return []

        # initialize today with current date/time if needed
        if self.today is None:
@@ -910,6 +969,26 @@ class PhotoTemplate:
            value = self.photo.exif_info.lens_model if self.photo.exif_info else None
        elif field == "uuid":
            value = self.photo.uuid
+        elif field == "id":
+            value = format_str_value(self.photo._info["pk"], subfield)
+        elif field.startswith("album_seq") or field.startswith("folder_album_seq"):
+            dest_path = self.dest_path
+            if not dest_path:
+                value = None
+            else:
+                if field.startswith("album_seq"):
+                    album = pathlib.Path(dest_path).name
+                    album_info = _get_album_by_name(self.photo, album)
+                else:
+                    album_info = _get_album_by_path(self.photo, dest_path)
+                value = album_info.photo_index(self.photo) if album_info else None
+            if value is not None:
+                try:
+                    start_id = field.split(".", 1)
+                    value = int(value) + int(start_id[1])
+                except IndexError:
+                    pass
+                value = format_str_value(value, subfield)
        elif field in PUNCTUATION:
            value = PUNCTUATION[field]
        elif field == "osxphotos_version":
@@ -920,9 +999,43 @@ class PhotoTemplate:
            # if here, didn't get a match
            raise ValueError(f"Unhandled template value: {field}")

-        if filename:
+        if self.filename:
            value = sanitize_pathpart(value)
-        elif dirname:
+        elif self.dirname:
+            value = sanitize_dirname(value)
+
+        # ensure no empty strings in value (see #512)
+        value = None if value == "" else value
+
+        return [value]
+
+    def get_template_value_pathlib(self, field):
+        """lookup value for template pathlib template fields
+
+        Args:
+            field: template field to find value for.
+
+        Returns:
+            The matching template value (which may be None).
+
+        Raises:
+            ValueError if no rule exists for field.
+        """
+        field_stem = field.split(".")[0]
+        if field_stem not in PATHLIB_SUBSTITUTIONS:
+            raise ValueError(f"SyntaxError: Unknown field: {field}")
+
+        field_value = None
+        try:
+            field_value = getattr(self, field_stem)
+        except AttributeError:
+            raise ValueError(f"Unknown path-like field: {field_stem}")
+
+        value = _get_pathlib_value(field, field_value, self.quote)
+
+        if self.filename:
+            value = sanitize_pathpart(value)
+        elif self.dirname:
            value = sanitize_dirname(value)

        return [value]
@@ -968,20 +1081,26 @@ class PhotoTemplate:
                value = ["[" + v + "]" for v in values]
            else:
                value = ["[" + values + "]"] if values else []
+        elif filter_ == "shell_quote":
+            if values and type(values) == list:
+                value = [shlex.quote(v) for v in values]
+            else:
+                value = [shlex.quote(values)] if values else []
        elif filter_.startswith("function:"):
            value = self.get_template_value_filter_function(filter_, values)
        else:
            value = []
        return value

-    def get_template_value_multi(self, field, path_sep, filename=False, dirname=False):
+    def get_template_value_multi(self, field, subfield, path_sep, default):
        """lookup value for template field (multi-value template substitutions)

        Args:
            field: template field to find value for.
+            subfield: the template subfield value
            path_sep: path separator to use for folder_album field
-            dirname: if True, values will be sanitized to be valid directory names; default = False
-        
+            default: value of default field
+
        Returns:
            List of the matching template values or [].

@@ -990,6 +1109,10 @@ class PhotoTemplate:
        """

        """ return list of values for a multi-valued template field """
+
+        if self.photo.uuid is None:
+            return []
+
        values = []
        if field == "album":
            values = self.photo.burst_albums if self.photo.burst else self.photo.albums
@@ -1013,7 +1136,7 @@ class PhotoTemplate:
            for album in album_info:
                if album.folder_names:
                    # album in folder
-                    if dirname:
+                    if self.dirname:
                        # being used as a filepath so sanitize each part
                        folder = path_sep.join(
                            sanitize_dirname(f) for f in album.folder_names
@@ -1023,12 +1146,10 @@ class PhotoTemplate:
                        folder = path_sep.join(album.folder_names)
                        folder += path_sep + album.title
                    values.append(folder)
+                elif self.dirname:
+                    values.append(sanitize_dirname(album.title))
                else:
-                    # album not in folder
-                    if dirname:
-                        values.append(sanitize_dirname(album.title))
-                    else:
-                        values.append(album.title)
+                    values.append(album.title)
        elif field == "comment":
            values = [
                f"{comment.user}: {comment.text}" for comment in self.photo.comments
@@ -1043,6 +1164,10 @@ class PhotoTemplate:
            values = (
                self.photo.search_info.venue_types if self.photo.search_info else []
            )
+        elif field == "shell_quote":
+            values = [shlex.quote(v) for v in default if v]
+        elif field == "strip":
+            values = [v.strip() for v in default]
        elif field.startswith("photo"):
            # provide access to PhotoInfo object
            properties = field.split(".")
@@ -1069,13 +1194,15 @@ class PhotoTemplate:
                values = [str(obj)]
            else:
                values = [val for val in obj]
+        elif field == "detected_text":
+            values = _get_detected_text(self.photo, self.exportdb, confidence=subfield)
        else:
            raise ValueError(f"Unhandled template value: {field}")

        # sanitize directory names if needed, folder_album handled differently above
-        if filename:
+        if self.filename:
            values = [sanitize_pathpart(value) for value in values]
-        elif dirname and field != "folder_album":
+        elif self.dirname and field != "folder_album":
            # skip folder_album because it would have been handled above
            values = [sanitize_dirname(value) for value in values]

@@ -1083,9 +1210,15 @@ class PhotoTemplate:
        values = values or []
        return values

-    def get_template_value_exiftool(self, subfield, filename=None, dirname=None):
+    def get_template_value_exiftool(
+        self,
+        subfield,
+    ):
        """Get template value for format "{exiftool:EXIF:Model}" """

+        if self.photo is None:
+            return []
+
        if not self.photo.path:
            return []

@@ -1098,17 +1231,20 @@ class PhotoTemplate:
            values = [str(v) for v in values]

            # sanitize directory names if needed
-            if filename:
+            if self.filename:
                values = [sanitize_pathpart(value) for value in values]
-            elif dirname:
+            elif self.dirname:
                values = [sanitize_dirname(value) for value in values]
        else:
            values = []

        return values

-    def get_template_value_function(self, subfield, filename=None, dirname=None):
-        """Get template value from external function """
+    def get_template_value_function(
+        self,
+        subfield,
+    ):
+        """Get template value from external function"""

        if "::" not in subfield:
            raise ValueError(
@@ -1117,11 +1253,12 @@ class PhotoTemplate:

        filename, funcname = subfield.split("::")

-        if not pathlib.Path(filename).is_file():
+        filename_validated = expand_and_validate_filepath(filename)
+        if not filename_validated:
            raise ValueError(f"'{filename}' does not appear to be a file")

-        template_func = load_function(filename, funcname)
-        values = template_func(self.photo)
+        template_func = load_function(filename_validated, funcname)
+        values = template_func(self.photo, options=self.options)

        if not isinstance(values, (str, list)):
            raise TypeError(
@@ -1131,17 +1268,18 @@ class PhotoTemplate:
            values = [values]

        # sanitize directory names if needed
-        if filename:
+        if self.filename:
            values = [sanitize_pathpart(value) for value in values]
-        elif dirname:
-            values = [sanitize_dirname(value) for value in values]
+        elif self.dirname:
+            # sanitize but don't replace any "/" as user function may want to create sub directories
+            values = [sanitize_dirname(value, replacement=None) for value in values]

        return values

    def get_template_value_filter_function(self, filter_, values):
-        """Filter template value from external function """
+        """Filter template value from external function"""

-        filter_ = filter_.replace("function:","")
+        filter_ = filter_.replace("function:", "")

        if "::" not in filter_:
            raise ValueError(
@@ -1150,10 +1288,11 @@ class PhotoTemplate:

        filename, funcname = filter_.split("::")

-        if not pathlib.Path(filename).is_file():
+        filename_validated = expand_and_validate_filepath(filename)
+        if not filename_validated:
            raise ValueError(f"'{filename}' does not appear to be a file")

-        template_func = load_function(filename, funcname)
+        template_func = load_function(filename_validated, funcname)

        if not isinstance(values, (list, tuple)):
            values = [values]
@@ -1166,9 +1305,8 @@ class PhotoTemplate:

        return values

-
    def get_photo_video_type(self, default):
-        """ return media type, e.g. photo or video """
+        """return media type, e.g. photo or video"""
        default_dict = parse_default_kv(default, PHOTO_VIDEO_TYPE_DEFAULTS)
        if self.photo.isphoto:
            return default_dict["photo"]
@@ -1176,7 +1314,7 @@ class PhotoTemplate:
            return default_dict["video"]

    def get_media_type(self, default):
-        """ return special media type, e.g. slow_mo, panorama, etc., defaults to photo or video if no special type """
+        """return special media type, e.g. slow_mo, panorama, etc., defaults to photo or video if no special type"""
        default_dict = parse_default_kv(default, MEDIA_TYPE_DEFAULTS)
        p = self.photo
        if p.selfie:
@@ -1210,7 +1348,7 @@ class PhotoTemplate:


 def parse_default_kv(default, default_dict):
-    """ parse a string in form key1=value1;key2=value2,... as used for some template fields
+    """parse a string in form key1=value1;key2=value2,... as used for some template fields

    Args:
        default: str, in form 'photo=foto;video=vidéo'
@@ -1235,9 +1373,86 @@ def parse_default_kv(default, default_dict):


 def get_template_help():
-    """Return help for template system as markdown string """
+    """Return help for template system as markdown string"""
    # TODO: would be better to use importlib.abc.ResourceReader but I can't find a single example of how to do this
    help_file = pathlib.Path(__file__).parent / "phototemplate.md"
    with open(help_file, "r") as fd:
        md = fd.read()
    return md
+
+
+def _get_pathlib_value(field, value, quote):
+    """Get the value for a pathlib.Path type template
+
+    Args:
+        field: the path field, e.g. "filename.stem"
+        value: the value for the path component
+        quote: bool; if true, quotes the returned path for safe execution in the shell
+    """
+    parts = field.split(".")
+
+    if len(parts) == 1:
+        return shlex.quote(value) if quote else value
+
+    if len(parts) > 2:
+        raise ValueError(f"Illegal value for path template: {field}")
+
+    path = parts[0]
+    attribute = parts[1]
+    path = pathlib.Path(value)
+    try:
+        val = getattr(path, attribute)
+        val_str = str(val)
+        if quote:
+            val_str = shlex.quote(val_str)
+        return val_str
+    except AttributeError:
+        raise ValueError("Illegal value for path template: {attribute}")
+
+
+def format_str_value(value, format_str):
+    """Format value based on format code in field in format id:02d"""
+    if not format_str:
+        return str(value)
+    format_str = "{0:" + f"{format_str}" + "}"
+    return format_str.format(value)
+
+
+def _get_album_by_name(photo, album):
+    """Finds first album named album that photo is in and returns the AlbumInfo object, otherwise returns None"""
+    for album_info in photo.album_info:
+        if album_info.title == album:
+            return album_info
+    return None
+
+
+def _get_album_by_path(photo, folder_album_path):
+    """finds the first album whose folder_album path matches and folder_album_path and returns the AlbumInfo object, otherwise, returns None"""
+
+    for album_info in photo.album_info:
+        # following code is how {folder_album} builds the folder path
+        folder = "/".join(sanitize_dirname(f) for f in album_info.folder_names)
+        folder += "/" + sanitize_dirname(album_info.title)
+        if folder_album_path.endswith(folder):
+            return album_info
+    return None
+
+
+def _get_detected_text(photo, exportdb, confidence=TEXT_DETECTION_CONFIDENCE_THRESHOLD):
+    """Returns the detected text for a photo
+    {detected_text} uses this instead of PhotoInfo.detected_text() to cache the text for all confidence values
+    """
+    if not photo.isphoto:
+        return []
+
+    confidence = (
+        float(confidence)
+        if confidence is not None
+        else TEXT_DETECTION_CONFIDENCE_THRESHOLD
+    )
+
+    # _detected_text caches the text detection results in an extended attribute
+    # so the first time this gets called is slow but repeated accesses are fast
+    detected_text = photo._detected_text()
+    exportdb.set_detected_text_for_uuid(photo.uuid, json.dumps(detected_text))
+    return [text for text, conf in detected_text if conf >= confidence]
--- a/osxphotos/phototemplate.tx
+++ b/osxphotos/phototemplate.tx
@@ -1,4 +1,4 @@
-// OSXPhotos Template Language (OTL)
+// OSXPhotos Metadata Template Language (MTL)
 // a TemplateString has format:
 // pre{delim+template_field:subfield|filter(path_sep)[find,replace] conditional?bool_value,default}post
 // a TemplateStatement may contain zero or more TemplateStrings
@@ -63,7 +63,8 @@ SubField:
 ;

 SUBFIELD_WORD:
-    /[\.\w:\/]+/
+    /[\.\w:\/\-\~\'\"\%\@\#\^\’]+/
+    /\\\s/?
 ;

 Filter:
--- a/osxphotos/pyrepl.py
+++ b/osxphotos/pyrepl.py
@@ -0,0 +1,131 @@
+""" Custom Python REPL based on ptpython that allows quitting with custom keywords instead of `quit()` """
+
+""" This file is distributed under the same license as the ptpython package:
+
+Copyright (c) 2015, Jonathan Slenders (ptpython), (c) 2021 Rhet Turnbull (this file)
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+
+* Neither the name of the {organization} nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+
+import sys
+from typing import Callable, List, Optional
+
+from ptpython.repl import (
+    ContextManager,
+    DummyContext,
+    PythonRepl,
+    builtins,
+    patch_stdout_context,
+)
+
+
+class PyReplQuitter(PythonRepl):
+    """Custom pypython repl that allows quitting REPL with custom commands"""
+
+    def __init__(self, *args, quit_words: Optional[List[str]] = None, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.quit_words = quit_words or ["quit", "q"]
+
+    def eval(self, line: str) -> object:
+        if line.strip() in self.quit_words:
+            sys.exit(0)
+        return super().eval(line)
+
+
+def embed_repl(
+    globals=None,
+    locals=None,
+    configure: Optional[Callable[[PythonRepl], None]] = None,
+    vi_mode: bool = False,
+    history_filename: Optional[str] = None,
+    title: Optional[str] = None,
+    startup_paths=None,
+    patch_stdout: bool = False,
+    return_asyncio_coroutine: bool = False,
+    quit_words: Optional[List[str]] = None,
+) -> None:
+    """
+    Call this to embed  Python shell at the current point in your program.
+    It's similar to `IPython.embed` and `bpython.embed`. ::
+        from prompt_toolkit.contrib.repl import embed
+        embed(globals(), locals())
+    :param vi_mode: Boolean. Use Vi instead of Emacs key bindings.
+    :param configure: Callable that will be called with the `PythonRepl` as a first
+                      argument, to trigger configuration.
+    :param title: Title to be displayed in the terminal titlebar. (None or string.)
+    :param patch_stdout:  When true, patch `sys.stdout` so that background
+        threads that are printing will print nicely above the prompt.
+    """
+    # Default globals/locals
+    if globals is None:
+        globals = {
+            "__name__": "__main__",
+            "__package__": None,
+            "__doc__": None,
+            "__builtins__": builtins,
+        }
+
+    locals = locals or globals
+
+    def get_globals():
+        return globals
+
+    def get_locals():
+        return locals
+
+    # Create REPL.
+    repl = PyReplQuitter(
+        get_globals=get_globals,
+        get_locals=get_locals,
+        vi_mode=vi_mode,
+        history_filename=history_filename,
+        startup_paths=startup_paths,
+        quit_words=quit_words,
+    )
+
+    if title:
+        repl.terminal_title = title
+
+    if configure:
+        configure(repl)
+
+    # Start repl.
+    patch_context: ContextManager = (
+        patch_stdout_context() if patch_stdout else DummyContext()
+    )
+
+    if return_asyncio_coroutine:
+
+        async def coroutine():
+            with patch_context:
+                await repl.run_async()
+
+        return coroutine()
+    else:
+        with patch_context:
+            repl.run()
--- a/osxphotos/queries/README.md
+++ b/osxphotos/queries/README.md
@@ -0,0 +1,5 @@
+# Query templates
+
+This folder contains sql query templates for getting various photo properties
+
+The query templates must be rendered with mako (see query_builder.py)
--- a/osxphotos/queries/cloud_album_owner.sql.mako
+++ b/osxphotos/queries/cloud_album_owner.sql.mako
@@ -0,0 +1,4 @@
+-- Get owner name for shared iCloud album
+SELECT ZGENERICALBUM.ZCLOUDOWNERFULLNAME AS OWNER_FULLNAME
+FROM ZGENERICALBUM
+WHERE ZGENERICALBUM.ZUUID = '${uuid}'
--- a/osxphotos/queries/shared_owner.sql.mako
+++ b/osxphotos/queries/shared_owner.sql.mako
@@ -0,0 +1,23 @@
+-- Get the owner name of person who owns a photo in a shared album
+--
+-- Case where someone has invited you to a shared album
+-- Need to get the owner of the shared album
+SELECT DISTINCT
+ZGENERICALBUM.ZCLOUDOWNERFULLNAME as OWNER_FULLNAME
+FROM ZGENERICALBUM
+JOIN ${asset_table} ON ${asset_table}.ZCLOUDOWNERHASHEDPERSONID = ZGENERICALBUM.ZCLOUDOWNERHASHEDPERSONID
+WHERE ${asset_table}.ZUUID = "${uuid}"
+AND ZGENERICALBUM.ZCLOUDOWNERHASHEDPERSONID IS NOT NULL 
+AND ZGENERICALBUM.ZCLOUDOWNERHASHEDPERSONID != ""
+AND OWNER_FULLNAME != "(null) (null)"
+UNION
+-- Case where you have invited someone to a shared album
+-- Need to get the data for person who was invited to the album
+SELECT DISTINCT
+ZCLOUDSHAREDALBUMINVITATIONRECORD.ZINVITEEFULLNAME AS OWNER_FULLNAME
+FROM ZCLOUDSHAREDALBUMINVITATIONRECORD 
+JOIN ${asset_table} ON ${asset_table}.ZCLOUDOWNERHASHEDPERSONID = ZCLOUDSHAREDALBUMINVITATIONRECORD.ZINVITEEHASHEDPERSONID
+WHERE ${asset_table}.ZUUID = "${uuid}"
+AND ZCLOUDSHAREDALBUMINVITATIONRECORD.ZINVITEEHASHEDPERSONID IS NOT NULL
+AND ZCLOUDSHAREDALBUMINVITATIONRECORD.ZINVITEEHASHEDPERSONID != ""
+AND OWNER_FULLNAME != "(null) (null)"
--- a/osxphotos/queries/title.sql.mako
+++ b/osxphotos/queries/title.sql.mako
@@ -0,0 +1,6 @@
+-- Get title of a photo with given UUID
+SELECT 
+ZADDITIONALASSETATTRIBUTES.ZTITLE
+FROM ZADDITIONALASSETATTRIBUTES
+JOIN ${asset_table} ON ${asset_table}.Z_PK = ZADDITIONALASSETATTRIBUTES.ZASSET
+WHERE ${asset_table}.ZUUID = "${uuid}"
--- a/osxphotos/query_builder.py
+++ b/osxphotos/query_builder.py
@@ -0,0 +1,36 @@
+"""Build sql queries from template to retrieve info from the database"""
+
+import os.path
+import pathlib
+from functools import lru_cache
+
+from mako.template import Template
+
+from ._constants import _DB_TABLE_NAMES
+
+QUERY_DIR = os.path.join(os.path.dirname(__file__), "queries")
+
+
+def get_query(query_name, photos_ver, **kwargs):
+    """Return sqlite query string for an attribute and a given database version"""
+
+    # there can be a single query for multiple database versions or separate queries for each version
+    # try generic version first (most common case), if that fails, look for version specific query
+    query_string = _get_query_string(query_name, photos_ver)
+    asset_table = _DB_TABLE_NAMES[photos_ver]["ASSET"]
+    query_template = Template(query_string)
+    return query_template.render(asset_table=asset_table, **kwargs)
+
+
+@lru_cache(maxsize=None)
+def _get_query_string(query_name, photos_ver):
+    """Return sqlite query string for an attribute and a given database version"""
+    query_file = pathlib.Path(QUERY_DIR) / f"{query_name}.sql.mako"
+    if not query_file.is_file():
+        query_file = pathlib.Path(QUERY_DIR) / f"{query_name}_{photos_ver}.sql.mako"
+        if not query_file.is_file():
+            raise FileNotFoundError(f"Query file '{query_file}' not found")
+
+    with open(query_file, "r") as f:
+        query_string = f.read()
+    return query_string
--- a/osxphotos/queryoptions.py
+++ b/osxphotos/queryoptions.py
@@ -1,8 +1,9 @@
 """ QueryOptions class for PhotosDB.query """

-from dataclasses import dataclass
-from typing import Optional, Iterable, Tuple
 import datetime
+from dataclasses import asdict, dataclass
+from typing import Iterable, List, Optional, Tuple
+
 import bitmath


@@ -30,7 +31,7 @@ class QueryOptions:
    shared: Optional[bool] = None
    not_shared: Optional[bool] = None
    photos: Optional[bool] = True
-    movies: Optional[bool] = True 
+    movies: Optional[bool] = True
    uti: Optional[Iterable[str]] = None
    burst: Optional[bool] = None
    not_burst: Optional[bool] = None
@@ -78,6 +79,12 @@ class QueryOptions:
    max_size: Optional[bitmath.Byte] = None
    regex: Optional[Iterable[Tuple[str, str]]] = None
    query_eval: Optional[Iterable[str]] = None
+    duplicate: Optional[bool] = None
+    location: Optional[bool] = None
+    no_location: Optional[bool] = None
+    function: Optional[List[Tuple[callable, str]]] = None
+    selected: Optional[bool] = None
+    exif: Optional[Iterable[Tuple[str, str]]] = None

    def asdict(self):
        return asdict(self)
--- a/osxphotos/text_detection.py
+++ b/osxphotos/text_detection.py
@@ -0,0 +1,89 @@
+""" Use Apple's Vision Framework via PyObjC to perform text detection on images (macOS 10.15+ only) """
+
+import logging
+from typing import List, Optional
+
+import objc
+import Quartz
+from Cocoa import NSURL
+from Foundation import NSDictionary
+
+# needed to capture system-level stderr
+from wurlitzer import pipes
+
+from .utils import _get_os_version
+
+ver, major, minor = _get_os_version()
+if ver == "10" and int(major) < 15:
+    vision = False
+else:
+    import Vision
+
+    vision = True
+
+
+def detect_text(img_path: str, orientation: Optional[int] = None) -> List:
+    """process image at img_path with VNRecognizeTextRequest and return list of results
+
+    Args:
+        img_path: path to the image file
+        orientation: optional EXIF orientation (if known, passing orientation may improve quality of results)
+    """
+    if not vision:
+        logging.warning(f"detect_text not implemented for this version of macOS")
+        return []
+
+    with objc.autorelease_pool():
+        input_url = NSURL.fileURLWithPath_(img_path)
+
+        with pipes() as (out, err):
+            # capture stdout and stderr from system calls
+            # otherwise, Quartz.CIImage.imageWithContentsOfURL_
+            # prints to stderr something like:
+            # 2020-09-20 20:55:25.538 python[73042:5650492] Creating client/daemon connection: B8FE995E-3F27-47F4-9FA8-559C615FD774
+            # 2020-09-20 20:55:25.652 python[73042:5650492] Got the query meta data reply for: com.apple.MobileAsset.RawCamera.Camera, response: 0
+            input_image = Quartz.CIImage.imageWithContentsOfURL_(input_url)
+
+        vision_options = NSDictionary.dictionaryWithDictionary_({})
+        if orientation is not None:
+            if not 1 <= orientation <= 8:
+                raise ValueError("orientation must be between 1 and 8")
+            vision_handler = Vision.VNImageRequestHandler.alloc().initWithCIImage_orientation_options_(
+                input_image, orientation, vision_options
+            )
+        else:
+            vision_handler = (
+                Vision.VNImageRequestHandler.alloc().initWithCIImage_options_(
+                    input_image, vision_options
+                )
+            )
+        results = []
+        handler = make_request_handler(results)
+        vision_request = (
+            Vision.VNRecognizeTextRequest.alloc().initWithCompletionHandler_(handler)
+        )
+        error = vision_handler.performRequests_error_([vision_request], None)
+        vision_request.dealloc()
+        vision_handler.dealloc()
+
+        for result in results:
+            result[0] = str(result[0])
+
+        return results
+
+
+def make_request_handler(results):
+    """results: list to store results"""
+    if not isinstance(results, list):
+        raise ValueError("results must be a list")
+
+    def handler(request, error):
+        if error:
+            print(f"Error! {error}")
+        else:
+            observations = request.results()
+            for text_observation in observations:
+                recognized_text = text_observation.topCandidates_(1)[0]
+                results.append([recognized_text.string(), recognized_text.confidence()])
+
+    return handler
--- a/docsrc/source/tutorial.md
+++ b/docsrc/source/tutorial.md
@@ -238,6 +238,12 @@ To export only photos contained in the album "Summer Vacation":

 `osxphotos export /path/to/export --album "Summer Vacation"`

+In Photos, it's possible to have multiple albums with the same name. In this case, osxphotos would export photos from all albums matching the value passed to `--album`.  If you wanted to export only one of the albums and this album is in a folder, the `--regex` option (short for "regular expression"), which does pattern matching, could be used with the `{folder_album}` template to match the specific album.  For example, if you had a "Summer Vacation" album inside the folder "2018" and also one with the same name inside the folder "2019", you could export just the album "2018/Summer Vacation" using this command:
+
+`osxphotos export /path/to/export --regex "2018/Summer Vacation" "{folder_album}"`
+
+This command matches the pattern "2018/Summer Vacation" against the full folder/album path for every photo.
+
 There are also a number of query options to export only certain types of photos.  For example, to export only photos taken with iPhone "Portrait Mode":

 `osxphotos export /path/to/export --portrait`
@@ -272,15 +278,15 @@ For example, to set Finder comment to the photo's title and description:

 In the template string above, `{newline}` instructs osxphotos to insert a new line character ("\n") between the title and description. In this example, if `{title}` or `{descr}` is empty, you'll get "title\n" or "\ndescription" which may not be desired so you can use more advanced features of the template system to handle these cases:

-`osxphotos export /path/to/export --xattr-template findercomment "{title}{title?{descr?{newline},},}{descr}"`
+`osxphotos export /path/to/export --xattr-template findercomment "{title,}{title?{descr?{newline},},}{descr,}"`

 Explanation of the template string:

 ```txt
-{title}{title?{descr?{newline},},}{descr}
+{title,}{title?{descr?{newline},},}{descr,}
 │           │      │ │       │ │  │ 
 │           │      │ │       │ │  │ 
- └──> insert title  │ │       │ │  │ 
+ └──> insert title (or nothing if no title) 
             │      │ │       │ │  │
             └───> is there a title?
                    │ │       │ │  │
@@ -292,7 +298,8 @@ Explanation of the template string:
                                │  │ 
                                └───> if title is blank, insert nothing
                                   │
-                                   └───> finally, insert description
+                                   └───> finally, insert description 
+                                         (or nothing if no description)
 ```

 In this example, `title?` demonstrates use of the boolean (True/False) feature of the template system.  `title?` is read as "Is the title True (or not blank/empty)?  If so, then the value immediately following the `?` is used in place of `title`.  If `title` is blank, then the value immediately following the comma is used instead.  The format for boolean fields is `field?value if true,value if false`.  Either `value if true` or `value if false` may be blank, in which case a blank string ("") is used for the value and both may also be an entirely new template string as seen in the above example.  Using this format, template strings may be nested inside each other to form complex `if-then-else` statements.
@@ -315,6 +322,40 @@ Then the next to you run osxphotos, you can simply do this:

 The configuration file is a plain text file in [TOML](https://toml.io/en/) format so the `.toml` extension is standard but you can name the file anything you like. 

+### Run commands on exported photos for post-processing
+
+You can use the `--post-command` option to run one or more commands against exported files. The `--post-command` option takes two arguments: CATEGORY and COMMAND.  CATEGORY is a string that describes which category of file to run the command against.  The available categories are described in the help text available via: `osxphotos help export`. For example, the `exported` category includes all exported photos and the `skipped` category includes all photos that were skipped when running export with `--update`.  COMMAND is an osxphotos template string which will be rendered then passed to the shell for execution.  
+
+For example, the following command generates a log of all exported files and their associated keywords:
+
+`osxphotos export /path/to/export --post-command exported "echo {shell_quote,{filepath}{comma}{,+keyword,}} >> {shell_quote,{export_dir}/exported.txt}"`
+
+The special template field `{shell_quote}` ensures a string is properly quoted for execution in the shell.  For example, it's possible that a file path or keyword in this example has a space in the value and if not properly quoted, this would cause an error in the execution of the command. When running commands, the template `{filepath}` is set to the full path of the exported file and `{export_dir}` is set to the full path of the base export directory.  
+
+Explanation of the template string:
+
+```txt
+{shell_quote,{filepath}{comma}{,+keyword,}}
+ │            │         │      │        │
+ │            │         │      |        │
+ └──> quote everything after comma for proper execution in the shell
+              │         │      │        │
+              └───> filepath of the exported file
+                       │       │        │
+                       └───> insert a comma 
+                               │        │
+                               └───> join the list of keywords together with a ","
+                                        │
+                                        └───> if no keywords, insert nothing (empty string: "")
+```
+
+Another example: if you had `exiftool` installed and wanted to wipe all metadata from all exported files, you could use the following:
+
+`osxphotos export /path/to/export --post-command exported "/usr/local/bin/exiftool -all= {filepath|shell_quote}"`
+
+This command uses the `|shell_quote` template filter instead of the `{shell_quote}` template because the only thing that needs to be quoted is the path to the exported file. Template filters filter the value of the rendered template field.  A number of other filters are available and are described in the help text. 
+
+
 ### An example from an actual osxphotos user

 Here's a comprehensive use case from an actual osxphotos user that integrates many of the concepts discussed in this tutorial (thank-you Philippe for contributing this!):
--- a/osxphotos/uti.py
+++ b/osxphotos/uti.py
@@ -0,0 +1,624 @@
+""" get UTI for a given file extension and the preferred extension for a given UTI """
+
+""" Implementation note: runs only on macOS
+
+    On macOS <= 11 (Big Sur), uses objective C CoreServices methods 
+    UTTypeCopyPreferredTagWithClass and UTTypeCreatePreferredIdentifierForTag to retrieve the 
+    UTI and the extension.  These are deprecated in 10.15 (Catalina) and no longer supported on Monterey.
+
+    On Monterey, these calls are replaced with Swift methods that I can't call from python so 
+    this code uses a cached dict of UTI values.  The code first checks to see if the extension or UTI 
+    is available in the cache and if so, returns it. If not, it performs a subprocess call to `mdls` to 
+    retrieve the UTI (by creating a temp file with the correct extension) and returns the UTI.  This only 
+    works for the extension -> UTI lookup. On Monterey, if there is no cached value for UTI -> extension lookup, 
+    returns None.
+
+    It's a bit hacky but best I can think of to make this robust on different versions of macOS.  PRs welcome.
+"""
+
+import csv
+import re
+import subprocess
+import tempfile
+
+import CoreServices
+import objc
+
+from .utils import _get_os_version
+
+# cached values of all the UTIs (< 6 chars long) known to my Mac running macOS 10.15.7
+UTI_CSV = """extension,UTI,preferred_extension,MIME_type
+c,public.c-source,c,None
+f,public.fortran-source,f,None
+h,public.c-header,h,None
+i,public.c-source.preprocessed,i,None
+l,public.lex-source,l,None
+m,public.objective-c-source,m,None
+o,public.object-code,o,None
+r,com.apple.rez-source,r,None
+s,public.assembly-source,s,None
+y,public.yacc-source,y,None
+z,public.z-archive,z,application/x-compress
+aa,com.audible.aa-audiobook,aa,audio/audible
+ai,com.adobe.illustrator.ai-image,ai,None
+as,com.apple.applesingle-archive,as,None
+au,public.au-audio,au,audio/basic
+bz,public.bzip2-archive,bz2,application/x-bzip2
+cc,public.c-plus-plus-source,cp,None
+cp,public.c-plus-plus-source,cp,None
+dv,public.dv-movie,dv,video/x-dv
+gz,org.gnu.gnu-zip-archive,gz,application/x-gzip
+hh,public.c-plus-plus-header,hh,None
+hp,public.c-plus-plus-header,hh,None
+ii,public.c-plus-plus-source.preprocessed,ii,None
+js,com.netscape.javascript-source,js,text/javascript
+lm,public.lex-source,l,None
+mi,public.objective-c-source.preprocessed,mi,None
+mm,public.objective-c-plus-plus-source,mm,None
+pf,com.apple.colorsync-profile,icc,None
+pl,public.perl-script,pl,text/x-perl-script
+pm,public.perl-script,pl,text/x-perl-script
+ps,com.adobe.postscript,ps,application/postscript
+py,public.python-script,py,text/x-python-script
+qt,com.apple.quicktime-movie,mov,video/quicktime
+ra,com.real.realaudio,ram,audio/vnd.rn-realaudio
+rb,public.ruby-script,rb,text/x-ruby-script
+rm,com.real.realmedia,rm,application/vnd.rn-realmedia
+sh,public.shell-script,sh,None
+ts,public.mpeg-2-transport-stream,ts,None
+ul,public.ulaw-audio,ul,None
+uu,public.uuencoded-archive,uu,text/x-uuencode
+wm,com.microsoft.windows-media-wm,wm,video/x-ms-wm
+ym,public.yacc-source,y,None
+aac,public.aac-audio,aac,audio/aac
+aae,com.apple.photos.apple-adjustment-envelope,aae,None
+aaf,org.aafassociation.advanced-authoring-format,aaf,None
+aax,com.audible.aax-audiobook,aax,audio/vnd.audible.aax
+abc,public.alembic,abc,None
+ac3,public.ac3-audio,ac3,audio/ac3
+ada,public.ada-source,ada,None
+adb,public.ada-source,ada,None
+ads,public.ada-source,ada,None
+aif,public.aifc-audio,aifc,audio/aiff
+amr,org.3gpp.adaptive-multi-rate-audio,amr,audio/amr
+app,com.apple.application-bundle,app,None
+arw,com.sony.arw-raw-image,arw,None
+asf,com.microsoft.advanced-systems-format,asf,video/x-ms-asf
+asx,com.microsoft.advanced-stream-redirector,asx,video/x-ms-asx
+avi,public.avi,avi,video/avi
+bdm,public.avchd-content,bdm,None
+bin,com.apple.macbinary-archive,bin,application/macbinary
+bmp,com.microsoft.bmp,bmp,image/bmp
+bwf,com.microsoft.waveform-audio,wav,audio/vnd.wave
+bz2,public.bzip2-archive,bz2,application/x-bzip2
+caf,com.apple.coreaudio-format,caf,None
+cdr,com.apple.disk-image-cdr,dvdr,None
+cel,public.flc-animation,flc,video/flc
+cer,public.x509-certificate,cer,application/x-x509-ca-cert
+cpp,public.c-plus-plus-source,cp,None
+crt,public.x509-certificate,cer,application/x-x509-ca-cert
+crw,com.canon.crw-raw-image,crw,image/x-canon-crw
+cr2,com.canon.cr2-raw-image,cr2,None
+cr3,com.canon.cr3-raw-image,cr3,None
+csh,public.csh-script,csh,None
+css,public.css,css,text/css
+csv,public.comma-separated-values-text,csv,text/csv
+cxx,public.c-plus-plus-source,cp,None
+dae,org.khronos.collada.digital-asset-exchange,dae,None
+dcm,org.nema.dicom,dcm,application/dicom
+dcr,com.kodak.raw-image,dcr,None
+dds,com.microsoft.dds,dds,None
+der,public.x509-certificate,cer,application/x-x509-ca-cert
+dif,public.dv-movie,dv,video/x-dv
+dll,com.microsoft.windows-dynamic-link-library,dll,application/x-msdownload
+dls,public.downloadable-sound,dls,audio/dls
+dmg,com.apple.disk-image-udif,dmg,None
+dng,com.adobe.raw-image,dng,image/x-adobe-dng
+doc,com.microsoft.word.doc,doc,application/msword
+dot,com.microsoft.word.dot,dot,application/msword
+dxo,com.dxo.raw-image,dxo,image/x-dxo-dxo
+ec3,public.enhanced-ac3-audio,eac3,audio/eac3
+edn,com.adobe.edn,edn,None
+efx,com.j2.efx-fax,efx,image/efax
+eml,com.apple.mail.email,eml,message/rfc822
+eps,com.adobe.encapsulated-postscript,eps,None
+erf,com.epson.raw-image,erf,image/x-epson-erf
+etd,com.adobe.etd,etd,None
+exe,com.microsoft.windows-executable,exe,application/x-msdownload
+exp,com.apple.symbol-export,exp,None
+exr,com.ilm.openexr-image,exr,None
+fdf,com.adobe.fdf,fdf,None
+fff,com.hasselblad.fff-raw-image,fff,None
+flc,public.flc-animation,flc,video/flc
+fli,public.flc-animation,flc,video/flc
+flv,com.adobe.flash.video,flv,video/x-flv
+for,public.fortran-source,f,None
+fpx,com.kodak.flashpix-image,fpx,image/fpx
+f4a,com.adobe.flash.video,flv,video/x-flv
+f4b,com.adobe.flash.video,flv,video/x-flv
+f4p,com.adobe.flash.video,flv,video/x-flv
+f4v,com.adobe.flash.video,flv,video/x-flv
+f77,public.fortran-77-source,f77,None
+f90,public.fortran-90-source,f90,None
+f95,public.fortran-95-source,f95,None
+gif,com.compuserve.gif,gif,image/gif
+hdr,public.radiance,pic,None
+hpp,public.c-plus-plus-header,hh,None
+hqx,com.apple.binhex-archive,hqx,application/mac-binhex40
+htm,public.html,html,text/html
+hxx,public.c-plus-plus-header,hh,None
+iba,com.apple.ibooksauthor.pkgbook,iba,None
+icc,com.apple.colorsync-profile,icc,None
+icm,com.apple.colorsync-profile,icc,None
+ico,com.microsoft.ico,ico,image/vnd.microsoft.icon
+ics,com.apple.ical.ics,ics,text/calendar
+iig,com.apple.iig-source,iig,None
+iiq,com.phaseone.raw-image,iiq,None
+img,com.apple.disk-image-ndif,ndif,None
+inl,public.c-plus-plus-inline-header,inl,None
+ipa,com.apple.itunes.ipa,ipa,None
+ipp,public.c-plus-plus-header,hh,None
+ips,com.apple.ips,ips,None
+iso,public.iso-image,iso,None
+ite,com.apple.tv.ite,ite,None
+itl,com.apple.itunes.db,itl,None
+jar,com.sun.java-archive,jar,application/java-archive
+jav,com.sun.java-source,java,None
+jfx,com.j2.jfx-fax,jfx,None
+jpe,public.jpeg,jpeg,image/jpeg
+jpf,public.jpeg-2000,jp2,image/jp2
+jpg,public.jpeg,jpeg,image/jpeg
+jpx,public.jpeg-2000,jp2,image/jp2
+jp2,public.jpeg-2000,jp2,image/jp2
+j2c,public.jpeg-2000,jp2,image/jp2
+j2k,public.jpeg-2000,jp2,image/jp2
+kar,public.midi-audio,midi,audio/midi
+key,com.apple.iwork.keynote.key,key,None
+ksh,public.ksh-script,ksh,None
+kth,com.apple.iwork.keynote.kth,kth,None
+ktx,org.khronos.ktx,ktx,None
+lid,public.dylan-source,dlyan,None
+lmm,public.lex-source,l,None
+log,com.apple.log,log,None
+lpp,public.lex-source,l,None
+lxx,public.lex-source,l,None
+mid,public.midi-audio,midi,audio/midi
+mig,public.mig-source,defs,None
+mii,public.objective-c-plus-plus-source.preprocessed,mii,None
+mjs,com.netscape.javascript-source,js,text/javascript
+mnc,ca.mcgill.mni.bic.mnc,mnc,None
+mos,com.leafamerica.raw-image,mos,None
+mov,com.apple.quicktime-movie,mov,video/quicktime
+mpe,public.mpeg,mpg,video/mpeg
+mpg,public.mpeg,mpg,video/mpeg
+mpo,public.mpo-image,mpo,None
+mp2,public.mp2,mp2,None
+mp3,public.mp3,mp3,audio/mpeg
+mp4,public.mpeg-4,mp4,video/mp4
+mrw,com.konicaminolta.raw-image,mrw,None
+mts,public.avchd-mpeg-2-transport-stream,mts,None
+mxf,org.smpte.mxf,mxf,application/mxf
+m15,public.mpeg,mpg,video/mpeg
+m2v,public.mpeg-2-video,m2v,video/mpeg2
+m3u,public.m3u-playlist,m3u,audio/mpegurl
+m4a,com.apple.m4a-audio,m4a,audio/x-m4a
+m4b,com.apple.protected-mpeg-4-audio-b,m4b,None
+m4p,com.apple.protected-mpeg-4-audio,m4p,None
+m4r,com.apple.mpeg-4-ringtone,m4r,audio/x-m4r
+m4v,com.apple.m4v-video,m4v,video/x-m4v
+m75,public.mpeg,mpg,video/mpeg
+nef,com.nikon.raw-image,nef,None
+nii,gov.nih.nifti-1,nii,None
+nrw,com.nikon.nrw-raw-image,nrw,image/x-nikon-nrw
+obj,public.geometry-definition-format,obj,None
+odb,org.oasis-open.opendocument.database,odb,application/vnd.oasis.opendocument.database
+odc,org.oasis-open.opendocument.chart,odc,application/vnd.oasis.opendocument.chart
+odf,org.oasis-open.opendocument.formula,odf,application/vnd.oasis.opendocument.formula
+odg,org.oasis-open.opendocument.graphics,odg,application/vnd.oasis.opendocument.graphics
+odi,org.oasis-open.opendocument.image,odi,application/vnd.oasis.opendocument.image
+odm,org.oasis-open.opendocument.text-master,odm,application/vnd.oasis.opendocument.text-master
+odp,org.oasis-open.opendocument.presentation,odp,application/vnd.oasis.opendocument.presentation
+ods,org.oasis-open.opendocument.spreadsheet,ods,application/vnd.oasis.opendocument.spreadsheet
+odt,org.oasis-open.opendocument.text,odt,application/vnd.oasis.opendocument.text
+omf,com.avid.open-media-framework,omf,None
+orf,com.olympus.raw-image,orf,None
+otc,public.opentype-collection-font,otc,None
+otf,public.opentype-font,otf,None
+otg,org.oasis-open.opendocument.graphics-template,otg,application/vnd.oasis.opendocument.graphics-template
+oth,org.oasis-open.opendocument.text-web,oth,application/vnd.oasis.opendocument.text-web
+oti,org.oasis-open.opendocument.image-template,oti,application/vnd.oasis.opendocument.image-template
+otp,org.oasis-open.opendocument.presentation-template,otp,application/vnd.oasis.opendocument.presentation-template
+ots,org.oasis-open.opendocument.spreadsheet-template,ots,application/vnd.oasis.opendocument.spreadsheet-template
+ott,org.oasis-open.opendocument.text-template,ott,application/vnd.oasis.opendocument.text-template
+pas,public.pascal-source,pas,None
+pax,public.cpio-archive,cpio,None
+pbm,public.pbm,pbm,None
+pch,public.precompiled-c-header,pch,None
+pct,com.apple.pict,pict,image/pict
+pdf,com.adobe.pdf,pdf,application/pdf
+pef,com.pentax.raw-image,pef,None
+pem,public.x509-certificate,cer,application/x-x509-ca-cert
+pfa,com.adobe.postscript-pfa-font,pfa,None
+pfb,com.adobe.postscript-pfb-font,pfb,None
+pfm,public.pbm,pbm,None
+pfx,com.rsa.pkcs-12,p12,application/x-pkcs12
+pgm,public.pbm,pbm,None
+pgn,com.apple.chess.pgn,pgn,None
+php,public.php-script,php,text/php
+ph3,public.php-script,php,text/php
+ph4,public.php-script,php,text/php
+pic,com.apple.pict,pict,image/pict
+pkg,com.apple.installer-package-archive,pkg,None
+pls,public.pls-playlist,pls,audio/x-scpls
+ply,public.polygon-file-format,ply,None
+png,public.png,png,image/png
+pot,com.microsoft.powerpoint.pot,pot,application/vnd.ms-powerpoint
+ppm,public.pbm,pbm,None
+pps,com.microsoft.powerpoint.pps,pps,application/vnd.ms-powerpoint
+ppt,com.microsoft.powerpoint.ppt,ppt,application/vnd.ms-powerpoint
+psb,com.adobe.photoshop-large-image,psb,None
+psd,com.adobe.photoshop-image,psd,image/vnd.adobe.photoshop
+pvr,public.pvr,pvr,None
+pvt,com.apple.private.live-photo-bundle,pvt,None
+pwl,com.leica.pwl-raw-image,pwl,image/x-leica-pwl
+p12,com.rsa.pkcs-12,p12,application/x-pkcs12
+qti,com.apple.quicktime-image,qtif,image/x-quicktime
+qtz,com.apple.quartz-composer-composition,qtz,application/x-quartzcomposer
+raf,com.fuji.raw-image,raf,None
+ram,com.real.realaudio,ram,audio/vnd.rn-realaudio
+raw,com.panasonic.raw-image,raw,None
+rbw,public.ruby-script,rb,text/x-ruby-script
+rmp,com.apple.music.rmp-playlist,rmp,application/vnd.rn-rn_music_package
+rss,public.rss,rss,application/rss+xml
+rtf,public.rtf,rtf,text/rtf
+rwl,com.leica.rwl-raw-image,rwl,None
+rw2,com.panasonic.rw2-raw-image,rw2,None
+scc,com.scenarist.closed-caption,scc,None
+scn,com.apple.scenekit.scene,scn,None
+sda,org.openoffice.graphics,sxd,application/vnd.sun.xml.draw
+sdc,org.openoffice.spreadsheet,sxc,application/vnd.sun.xml.calc
+sdd,org.openoffice.presentation,sxi,application/vnd.sun.xml.impress
+sdp,org.openoffice.presentation,sxi,application/vnd.sun.xml.impress
+sdv,public.3gpp,3gp,video/3gpp
+sdw,org.openoffice.text,sxw,application/vnd.sun.xml.writer
+sd2,com.digidesign.sd2-audio,sd2,None
+sea,com.stuffit.archive.sit,sit,application/x-stuffit
+sf2,com.soundblaster.soundfont,sf2,None
+sgi,com.sgi.sgi-image,sgi,image/sgi
+sit,com.stuffit.archive.sit,sit,application/x-stuffit
+slm,com.apple.photos.slow-motion-video-sidecar,slm,None
+smf,public.midi-audio,midi,audio/midi
+smi,com.apple.disk-image-smi,smi,None
+snd,public.au-audio,au,audio/basic
+spx,com.apple.systemprofiler.document,spx,None
+srf,com.sony.raw-image,srf,None
+srw,com.samsung.raw-image,srw,None
+sr2,com.sony.sr2-raw-image,sr2,image/x-sony-sr2
+stc,org.openoffice.spreadsheet-template,stc,application/vnd.sun.xml.calc.template
+std,org.openoffice.graphics-template,std,application/vnd.sun.xml.draw.template
+sti,org.openoffice.presentation-template,sti,application/vnd.sun.xml.impress.template
+stl,public.standard-tesselated-geometry-format,stl,None
+stw,org.openoffice.text-template,stw,application/vnd.sun.xml.writer.template
+svg,public.svg-image,svg,image/svg+xml
+sxc,org.openoffice.spreadsheet,sxc,application/vnd.sun.xml.calc
+sxd,org.openoffice.graphics,sxd,application/vnd.sun.xml.draw
+sxg,org.openoffice.text-master,sxg,application/vnd.sun.xml.writer.global
+sxi,org.openoffice.presentation,sxi,application/vnd.sun.xml.impress
+sxm,org.openoffice.formula,sxm,application/vnd.sun.xml.math
+sxw,org.openoffice.text,sxw,application/vnd.sun.xml.writer
+tar,public.tar-archive,tar,application/x-tar
+tbz,public.tar-bzip2-archive,tbz2,None
+tga,com.truevision.tga-image,tga,image/targa
+tgz,org.gnu.gnu-zip-tar-archive,tgz,None
+tif,public.tiff,tiff,image/tiff
+tsv,public.tab-separated-values-text,tsv,text/tab-separated-values
+ttc,public.truetype-collection-font,ttc,None
+ttf,public.truetype-ttf-font,ttf,None
+txt,public.plain-text,txt,text/plain
+ulw,public.ulaw-audio,ul,None
+url,com.microsoft.internet-shortcut,url,None
+usd,com.pixar.universal-scene-description,usd,None
+vcf,public.vcard,vcf,text/directory
+vcs,com.apple.ical.vcs,vcs,text/x-vcalendar
+vfw,public.avi,avi,video/avi
+vtt,org.w3.webvtt,vtt,text/vtt
+war,com.sun.web-application-archive,war,None
+wav,com.microsoft.waveform-audio,wav,audio/vnd.wave
+wax,com.microsoft.windows-media-wax,wax,video/x-ms-wax
+web,com.getdropbox.dropbox.shortcut,web,None
+wma,com.microsoft.windows-media-wma,wma,video/x-ms-wma
+wmp,com.microsoft.windows-media-wmp,wmp,video/x-ms-wmp
+wmv,com.microsoft.windows-media-wmv,wmv,video/x-ms-wmv
+wmx,com.microsoft.windows-media-wmx,wmx,video/x-ms-wmx
+wvx,com.microsoft.windows-media-wvx,wvx,video/x-ms-wvx
+xar,com.apple.xar-archive,xar,None
+xbm,public.xbitmap-image,xbm,image/x-xbitmap
+xfd,public.xfd,xfd,None
+xht,public.xhtml,xhtml,application/xhtml+xml
+xip,com.apple.xip-archive,xip,None
+xla,com.microsoft.excel.xla,xla,None
+xls,com.microsoft.excel.xls,xls,application/vnd.ms-excel
+xlt,com.microsoft.excel.xlt,xlt,application/vnd.ms-excel
+xlw,com.microsoft.excel.xlw,xlw,application/vnd.ms-excel
+xml,public.xml,xml,application/xml
+xmp,com.seriflabs.xmp,xmp,application/rdf+xml
+xpc,com.apple.xpc-service,xpc,None
+yml,public.yaml,yml,application/x-yaml
+ymm,public.yacc-source,y,None
+ypp,public.yacc-source,y,None
+yxx,public.yacc-source,y,None
+zip,public.zip-archive,zip,application/zip
+zsh,public.zsh-script,zsh,None
+3fr,com.hasselblad.3fr-raw-image,3fr,None
+3gp,public.3gpp,3gp,video/3gpp
+3g2,public.3gpp2,3g2,video/3gpp2
+adts,public.aac-audio,aac,audio/aac
+ahap,com.apple.haptics.ahap,ahap,None
+aifc,public.aifc-audio,aifc,audio/aiff
+aiff,public.aifc-audio,aifc,audio/aiff
+astc,org.khronos.astc,astc,None
+avci,public.avci,avci,image/avci
+avcs,public.avcs,avcs,image/avcs
+band,com.apple.garageband.project,band,None
+bash,public.bash-script,bash,None
+bdmv,public.avchd-content,bdm,None
+book,com.apple.ibooksauthor.pkgbook,iba,None
+cdda,public.aifc-audio,aifc,audio/aiff
+chat,com.apple.ichat.transcript,ichat,None
+cpgz,com.apple.bom-compressed-cpio,cpgz,None
+cpio,public.cpio-archive,cpio,None
+dart,com.apple.disk-image-dart,dart,None
+dc42,com.apple.disk-image-dc42,dc42,None
+defs,public.mig-source,defs,None
+dext,com.apple.driver-extension,dext,None
+diff,public.patch-file,patch,None
+dist,com.apple.installer-distribution-package,dist,None
+docm,org.openxmlformats.wordprocessingml.document.macroenabled,docm,application/vnd.ms-word.document.macroenabled.12
+docx,org.openxmlformats.wordprocessingml.document,docx,application/vnd.openxmlformats-officedocument.wordprocessingml.document
+dotm,org.openxmlformats.wordprocessingml.template.macroenabled,dotm,application/vnd.ms-word.template.macroenabled.12
+dotx,org.openxmlformats.wordprocessingml.template,dotx,application/vnd.openxmlformats-officedocument.wordprocessingml.template
+dsym,com.apple.xcode.dsym,dsym,None
+dvdr,com.apple.disk-image-cdr,dvdr,None
+eac3,public.enhanced-ac3-audio,eac3,audio/eac3
+emlx,com.apple.mail.emlx,emlx,None
+enex,com.evernote.enex,enex,None
+epub,org.idpf.epub-container,epub,application/epub+zip
+fh10,com.seriflabs.affinity,fh10,None
+fh11,com.seriflabs.affinity,fh10,None
+flac,org.xiph.flac,flac,audio/flac
+fpbf,com.apple.finder.burn-folder,fpbf,None
+game,com.apple.chess.game,game,None
+gdoc,com.google.gdoc,gdoc,None
+gtar,org.gnu.gnu-tar-archive,gtar,application/x-gtar
+gzip,org.gnu.gnu-zip-archive,gz,application/x-gzip
+hang,com.apple.hangreport,hang,None
+heic,public.heic,heic,image/heic
+heif,public.heif,heif,image/heif
+html,public.html,html,text/html
+hvpl,com.apple.music.visual,hvpl,None
+icbu,com.apple.ical.backup,icbu,None
+icns,com.apple.icns,icns,None
+ipsw,com.apple.itunes.ipsw,ipsw,None
+itlp,com.apple.music.itlp,itlp,None
+itms,com.apple.itunes.store-url,itms,None
+java,com.sun.java-source,java,None
+jnlp,com.sun.java-web-start,jnlp,application/x-java-jnlp-file
+jpeg,public.jpeg,jpeg,image/jpeg
+json,public.json,json,application/json
+latm,public.mp4a-loas,loas,None
+loas,public.mp4a-loas,loas,None
+lpdf,com.apple.localized-pdf-bundle,lpdf,None
+mbox,com.apple.mail.mbox,mbox,None
+menu,com.apple.menu-extra,menu,None
+midi,public.midi-audio,midi,audio/midi
+minc,ca.mcgill.mni.bic.mnc,mnc,None
+mpeg,public.mpeg,mpg,video/mpeg
+mpga,public.mp3,mp3,audio/mpeg
+mpg4,public.mpeg-4,mp4,video/mp4
+mpkg,com.apple.installer-package-archive,pkg,None
+m2ts,public.avchd-mpeg-2-transport-stream,mts,None
+m3u8,public.m3u-playlist,m3u,audio/mpegurl
+ndif,com.apple.disk-image-ndif,ndif,None
+note,com.apple.notes.note,note,None
+php3,public.php-script,php,text/php
+php4,public.php-script,php,text/php
+pict,com.apple.pict,pict,image/pict
+pntg,com.apple.macpaint-image,pntg,None
+potm,org.openxmlformats.presentationml.template.macroenabled,potm,application/vnd.ms-powerpoint.template.macroenabled.12
+potx,org.openxmlformats.presentationml.template,potx,application/vnd.openxmlformats-officedocument.presentationml.template
+ppsm,org.openxmlformats.presentationml.slideshow.macroenabled,ppsm,application/vnd.ms-powerpoint.slideshow.macroenabled.12
+ppsx,org.openxmlformats.presentationml.slideshow,ppsx,application/vnd.openxmlformats-officedocument.presentationml.slideshow
+pptm,org.openxmlformats.presentationml.presentation.macroenabled,pptm,application/vnd.ms-powerpoint.presentation.macroenabled.12
+pptx,org.openxmlformats.presentationml.presentation,pptx,application/vnd.openxmlformats-officedocument.presentationml.presentation
+pset,com.apple.pdf-printer-settings,pset,None
+qtif,com.apple.quicktime-image,qtif,image/x-quicktime
+rmvb,com.real.realmedia-vbr,rmvb,application/vnd.rn-realmedia-vbr
+rtfd,com.apple.rtfd,rtfd,None
+scnz,com.apple.scenekit.scene,scn,None
+scpt,com.apple.applescript.script,scpt,None
+shtm,public.html,html,text/html
+sidx,com.stuffit.archive.sidx,sidx,application/x-stuffitx-index
+sitx,com.stuffit.archive.sitx,sitx,application/x-stuffitx
+spin,com.apple.spinreport,spin,None
+suit,com.apple.font-suitcase,suit,None
+svgz,public.svg-image,svg,image/svg+xml
+tbz2,public.tar-bzip2-archive,tbz2,None
+tcsh,public.tcsh-script,tcsh,None
+term,com.apple.terminal.session,term,None
+text,public.plain-text,txt,text/plain
+tiff,public.tiff,tiff,image/tiff
+tool,com.apple.terminal.shell-script,command,None
+udif,com.apple.disk-image-udif,dmg,None
+ulaw,public.ulaw-audio,ul,None
+usda,com.pixar.universal-scene-description,usd,None
+usdc,com.pixar.universal-scene-description,usd,None
+usdz,com.pixar.universal-scene-description-mobile,usdz,model/vnd.usdz+zip
+vcal,com.apple.ical.vcs,vcs,text/x-vcalendar
+wave,com.microsoft.waveform-audio,wav,audio/vnd.wave
+wdgt,com.apple.dashboard-widget,wdgt,None
+webp,public.webp,webp,None
+xfdf,com.adobe.xfdf,xfdf,None
+xhtm,public.xhtml,xhtml,application/xhtml+xml
+xlsb,com.microsoft.excel.sheet.binary.macroenabled,xlsb,application/vnd.ms-excel.sheet.binary.macroenabled.12
+xlsm,org.openxmlformats.spreadsheetml.sheet.macroenabled,xlsm,application/vnd.ms-excel.sheet.macroenabled.12
+xlsx,org.openxmlformats.spreadsheetml.sheet,xlsx,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
+xltm,org.openxmlformats.spreadsheetml.template.macroenabled,xltm,application/vnd.ms-excel.template.macroenabled.12
+xltx,org.openxmlformats.spreadsheetml.template,xltx,application/vnd.openxmlformats-officedocument.spreadsheetml.template
+yaml,public.yaml,yml,application/x-yaml
+3gpp,public.3gpp,3gp,video/3gpp
+3gp2,public.3gpp2,3g2,video/3gpp2
+abcdg,com.apple.addressbook.group,abcdg,None
+abcdp,com.apple.addressbook.person,abcdp,None
+afpub,com.seriflabs.affinitypublisher.document,afpub,None
+appex,com.apple.application-and-system-extension,appex,None
+avchd,public.avchd-collection,avchd,None
+blank,com.apple.preview.blank,blank,None
+class,com.sun.java-class,class,None
+crash,com.apple.crashreport,crash,None
+dfont,com.apple.truetype-datafork-suitcase-font,dfont,None
+dicom,org.nema.dicom,dcm,application/dicom
+distz,com.apple.installer-distribution-package,dist,None
+dlyan,public.dylan-source,dlyan,None
+dylib,com.apple.mach-o-dylib,dylib,None
+heics,public.heics,heics,image/heic-sequence
+heifs,public.heifs,heifs,image/heif-sequence
+ichat,com.apple.ichat.transcript,ichat,None
+pages,com.apple.iwork.pages.pages,pages,None
+panic,com.apple.panicreport,panic,None
+paper,com.getdropbox.dropbox.paper,paper,None
+patch,public.patch-file,patch,None
+phtml,public.php-script,php,text/php
+plist,com.apple.property-list,plist,None
+saver,com.apple.systempreference.screen-saver,saver,None
+scptd,com.apple.applescript.script-bundle,scptd,None
+sfont,com.apple.cfr-font,sfont,None
+shtml,public.html,html,text/html
+swift,public.swift-source,swift,None
+toast,com.roxio.disk-image-toast,toast,None
+vcard,public.vcard,vcf,text/directory
+wdmon,com.apple.wireless-diagnostics.wdmon,wdmon,None
+xhtml,public.xhtml,xhtml,application/xhtml+xml
+action,com.apple.automator-action,action,None
+afploc,com.apple.afp-internet-location,afploc,None
+"""
+
+# load CSV separated uti data into dictionaries with key of extension and UTI
+EXT_UTI_DICT = {}
+UTI_EXT_DICT = {}
+
+
+def _load_uti_dict():
+    """load an initialize the cached UTI and extension dicts"""
+    _reader = csv.DictReader(UTI_CSV.split("\n"), delimiter=",")
+    for row in _reader:
+        EXT_UTI_DICT[row["extension"]] = row["UTI"]
+        UTI_EXT_DICT[row["UTI"]] = row["preferred_extension"]
+
+
+_load_uti_dict()
+
+# OS version for determining which methods can be used
+OS_VER, OS_MAJOR, _ = (int(x) for x in _get_os_version())
+
+
+def _get_uti_from_mdls(extension):
+    """use mdls to get the UTI for a given extension on systems that don't support UTTypeCreatePreferredIdentifierForTag
+    Returns: UTI or None if UTI cannot be determined"""
+
+    # mdls -name kMDItemContentType foo.3fr
+    # kMDItemContentType = "com.hasselblad.3fr-raw-image"
+
+    try:
+        with tempfile.NamedTemporaryFile(suffix="." + extension) as temp:
+            output = subprocess.check_output(
+                [
+                    "/usr/bin/mdls",
+                    "-name",
+                    "kMDItemContentType",
+                    temp.name,
+                ]
+            ).splitlines()
+            output = output[0].decode("UTF-8") if output else None
+            if not output:
+                return None
+
+            match = re.match(r'kMDItemContentType\s+\=\s+"(.*)"', output)
+            if match:
+                return match.group(1)
+            return None
+    except Exception:
+        return None
+
+
+def _get_uti_from_ext_dict(ext):
+    try:
+        return EXT_UTI_DICT[ext.lower()]
+    except KeyError:
+        return None
+
+
+def _get_ext_from_uti_dict(uti):
+    try:
+        return UTI_EXT_DICT[uti.lower()]
+    except KeyError:
+        return None
+
+
+def get_preferred_uti_extension(uti):
+    """get preferred extension for a UTI type
+    uti: UTI str, e.g. 'public.jpeg'
+    returns: preferred extension as str or None if cannot be determined"""
+
+    if (OS_VER, OS_MAJOR) <= (10, 16):
+        # reference: https://developer.apple.com/documentation/coreservices/1442744-uttypecopypreferredtagwithclass?language=objc
+        # deprecated in Catalina+, likely won't work at all on macOS 12
+        with objc.autorelease_pool():
+            extension = CoreServices.UTTypeCopyPreferredTagWithClass(
+                uti, CoreServices.kUTTagClassFilenameExtension
+            )
+            if extension:
+                return extension
+
+            # on MacOS 10.12, HEIC files are not supported and UTTypeCopyPreferredTagWithClass will return None for HEIC
+            if uti == "public.heic":
+                return "HEIC"
+
+            return None
+
+    return _get_ext_from_uti_dict(uti)
+
+
+def get_uti_for_extension(extension):
+    """get UTI for a given file extension"""
+
+    # accepts extension with or without leading 0
+    if extension[0] == ".":
+        extension = extension[1:]
+
+    if (OS_VER, OS_MAJOR) <= (10, 16):
+        # https://developer.apple.com/documentation/coreservices/1448939-uttypecreatepreferredidentifierf
+        with objc.autorelease_pool():
+            uti = CoreServices.UTTypeCreatePreferredIdentifierForTag(
+                CoreServices.kUTTagClassFilenameExtension, extension, None
+            )
+            if uti:
+                return uti
+
+            # on MacOS 10.12, HEIC files are not supported and UTTypeCopyPreferredTagWithClass will return None for HEIC
+            if extension.lower() == "heic":
+                return "public.heic"
+
+            return None
+
+    uti = _get_uti_from_ext_dict(extension)
+    if uti:
+        return uti
+
+    uti = _get_uti_from_mdls(extension)
+    if uti:
+        # cache the UTI
+        EXT_UTI_DICT[extension.lower()] = uti
+        UTI_EXT_DICT[uti] = extension.lower()
+        return uti
+
+    return None
--- a/osxphotos/utils.py
+++ b/osxphotos/utils.py
@@ -16,11 +16,11 @@ import sys
 import unicodedata
 import urllib.parse
 from plistlib import load as plistload
-from typing import Callable
+from typing import Callable, Union

 import CoreFoundation
-import CoreServices
 import objc
+from Foundation import NSString

 from ._constants import UNICODE_FORMAT

@@ -38,7 +38,7 @@ if not _DEBUG:

 def _get_logger():
    """Used only for testing
-    
+
    Returns:
        logging.Logger object -- logging.Logger object for osxphotos
    """
@@ -46,7 +46,7 @@ def _get_logger():


 def _set_debug(debug):
-    """ Enable or disable debug logging """
+    """Enable or disable debug logging"""
    global _DEBUG
    _DEBUG = debug
    if debug:
@@ -56,18 +56,18 @@ def _set_debug(debug):


 def _debug():
-    """ returns True if debugging turned on (via _set_debug), otherwise, false """
+    """returns True if debugging turned on (via _set_debug), otherwise, false"""
    return _DEBUG


 def noop(*args, **kwargs):
-    """ do nothing (no operation) """
+    """do nothing (no operation)"""
    pass


 def lineno(filename):
-    """ Returns string with filename and current line number in caller as '(filename): line_num'
-    Will trim filename to just the name, dropping path, if any. """
+    """Returns string with filename and current line number in caller as '(filename): line_num'
+    Will trim filename to just the name, dropping path, if any."""
    line = inspect.currentframe().f_back.f_lineno
    filename = pathlib.Path(filename).name
    return f"{filename}: {line}"
@@ -92,14 +92,14 @@ def _get_os_version():


 def _check_file_exists(filename):
-    """ returns true if file exists and is not a directory
-        otherwise returns false """
+    """returns true if file exists and is not a directory
+    otherwise returns false"""
    filename = os.path.abspath(filename)
    return os.path.exists(filename) and not os.path.isdir(filename)


 def _get_resource_loc(model_id):
-    """ returns folder_id and file_id needed to find location of edited photo """
+    """returns folder_id and file_id needed to find location of edited photo"""
    """ and live photos for version <= Photos 4.0 """
    # determine folder where Photos stores edited version
    # edited images are stored in:
@@ -117,7 +117,7 @@ def _get_resource_loc(model_id):


 def _dd_to_dms(dd):
-    """ convert lat or lon in decimal degrees (dd) to degrees, minutes, seconds """
+    """convert lat or lon in decimal degrees (dd) to degrees, minutes, seconds"""
    """ return tuple of int(deg), int(min), float(sec) """
    dd = float(dd)
    negative = dd < 0
@@ -136,7 +136,7 @@ def _dd_to_dms(dd):


 def dd_to_dms_str(lat, lon):
-    """ convert latitude, longitude in degrees to degrees, minutes, seconds as string """
+    """convert latitude, longitude in degrees to degrees, minutes, seconds as string"""
    """ lat: latitude in degrees  """
    """ lon: longitude in degrees """
    """ returns: string tuple in format ("51 deg 30' 12.86\" N", "0 deg 7' 54.50\" W") """
@@ -165,7 +165,7 @@ def dd_to_dms_str(lat, lon):


 def get_system_library_path():
-    """ return the path to the system Photos library as string """
+    """return the path to the system Photos library as string"""
    """ only works on MacOS 10.15 """
    """ on earlier versions, returns None """
    _, major, _ = _get_os_version()
@@ -190,8 +190,8 @@ def get_system_library_path():


 def get_last_library_path():
-    """ returns the path to the last opened Photos library 
-        If a library has never been opened, returns None """
+    """returns the path to the last opened Photos library
+    If a library has never been opened, returns None"""
    plist_file = pathlib.Path(
        str(pathlib.Path.home())
        + "/Library/Containers/com.apple.Photos/Data/Library/Preferences/com.apple.Photos.plist"
@@ -241,7 +241,7 @@ def get_last_library_path():


 def list_photo_libraries():
-    """ returns list of Photos libraries found on the system """
+    """returns list of Photos libraries found on the system"""
    """ on MacOS < 10.15, this may omit some libraries """

    # On 10.15, mdfind appears to find all libraries
@@ -265,50 +265,31 @@ def list_photo_libraries():
    return lib_list


-def get_preferred_uti_extension(uti):
-    """ get preferred extension for a UTI type
-        uti: UTI str, e.g. 'public.jpeg'
-        returns: preferred extension as str """
-
-    # reference: https://developer.apple.com/documentation/coreservices/1442744-uttypecopypreferredtagwithclass?language=objc
+def normalize_fs_path(path: str) -> str:
+    """Normalize filesystem paths with unicode in them"""
    with objc.autorelease_pool():
-        return CoreServices.UTTypeCopyPreferredTagWithClass(
-            uti, CoreServices.kUTTagClassFilenameExtension
-        )
+        normalized_path = NSString.fileSystemRepresentation(path)
+        return normalized_path.decode("utf8")


 def findfiles(pattern, path_):
    """Returns list of filenames from path_ matched by pattern
-       shell pattern. Matching is case-insensitive.
-       If 'path_' is invalid/doesn't exist, returns []."""
+    shell pattern. Matching is case-insensitive.
+    If 'path_' is invalid/doesn't exist, returns []."""
    if not os.path.isdir(path_):
        return []
    # See: https://gist.github.com/techtonik/5694830

+    # paths need to be normalized for unicode as filesystem returns unicode in NFD form
+    pattern = normalize_fs_path(pattern)
    rule = re.compile(fnmatch.translate(pattern), re.IGNORECASE)
-    return [name for name in os.listdir(path_) if rule.match(name)]
-
-
-# TODO: this doesn't always work, still looking for a way to
-# force Photos to open the library being operated on
-# def _open_photos_library_applescript(library_path):
-#     """ Force Photos to open a specific library
-#         library_path: path to the Photos library """
-#     open_scpt = AppleScript(
-#         f"""
-#         on openLibrary
-#             tell application "Photos"
-# 	          open POSIX file "{library_path}"
-#             end tell
-#         end openLibrary
-#         """
-#     )
-#     open_scpt.run()
+    files = [normalize_fs_path(p) for p in os.listdir(path_)]
+    return [name for name in files if rule.match(name)]


 def _open_sql_file(dbname):
-    """ opens sqlite file dbname in read-only mode
-        returns tuple of (connection, cursor) """
+    """opens sqlite file dbname in read-only mode
+    returns tuple of (connection, cursor)"""
    try:
        dbpath = pathlib.Path(dbname).resolve()
        conn = sqlite3.connect(f"{dbpath.as_uri()}?mode=ro", timeout=1, uri=True)
@@ -319,9 +300,9 @@ def _open_sql_file(dbname):


 def _db_is_locked(dbname):
-    """ check to see if a sqlite3 db is locked
-        returns True if database is locked, otherwise False
-        dbname: name of database to test """
+    """check to see if a sqlite3 db is locked
+    returns True if database is locked, otherwise False
+    dbname: name of database to test"""

    # first, check to see if lock file exists, if so, assume the file is locked
    lock_name = f"{dbname}.lock"
@@ -372,7 +353,7 @@ def _db_is_locked(dbname):


 def normalize_unicode(value):
-    """ normalize unicode data """
+    """normalize unicode data"""
    if value is not None:
        if isinstance(value, (tuple, list)):
            return tuple(unicodedata.normalize(UNICODE_FORMAT, v) for v in value)
@@ -384,34 +365,68 @@ def normalize_unicode(value):
        return None


-def increment_filename(filepath):
-    """ Return filename (1).ext, etc if filename.ext exists
+def increment_filename_with_count(filepath: Union[str,pathlib.Path], count: int = 0) -> str:
+    """Return filename (1).ext, etc if filename.ext exists

-        If file exists in filename's parent folder with same stem as filename, 
+        If file exists in filename's parent folder with same stem as filename,
        add (1), (2), etc. until a non-existing filename is found.

    Args:
-        filepath: str; full path, including file name
+        filepath: str or pathlib.Path; full path, including file name
+        count: int; starting increment value
+
+    Returns:
+        tuple of new filepath (or same if not incremented), count
+
+    Note: This obviously is subject to race condition so using with caution.
+    """
+    dest = filepath if isinstance(filepath, pathlib.Path) else pathlib.Path(filepath)
+    dest_files = findfiles(f"{dest.stem}*", str(dest.parent))
+    dest_files = [normalize_fs_path(pathlib.Path(f).stem.lower()) for f in dest_files]
+    dest_new = dest.stem
+    if count:
+        dest_new = f"{dest.stem} ({count})"
+    while normalize_fs_path(dest_new.lower()) in dest_files:
+        count += 1
+        dest_new = f"{dest.stem} ({count})"
+    dest = dest.parent / f"{dest_new}{dest.suffix}"
+    return str(dest), count
+
+
+def increment_filename(filepath: Union[str, pathlib.Path]) -> str:
+    """Return filename (1).ext, etc if filename.ext exists
+
+        If file exists in filename's parent folder with same stem as filename,
+        add (1), (2), etc. until a non-existing filename is found.
+
+    Args:
+        filepath: str or pathlib.Path; full path, including file name

    Returns:
        new filepath (or same if not incremented)

    Note: This obviously is subject to race condition so using with caution.
    """
-    dest = pathlib.Path(str(filepath))
-    count = 1
-    dest_files = findfiles(f"{dest.stem}*", str(dest.parent))
-    dest_files = [pathlib.Path(f).stem.lower() for f in dest_files]
-    dest_new = dest.stem
-    while dest_new.lower() in dest_files:
-        dest_new = f"{dest.stem} ({count})"
-        count += 1
-    dest = dest.parent / f"{dest_new}{dest.suffix}"
-    return str(dest)
+    new_filepath, _ = increment_filename_with_count(filepath)
+    return new_filepath
+
+
+def expand_and_validate_filepath(path: str) -> str:
+    """validate and expand ~ in filepath, also un-escapes spaces
+
+    Returns:
+        expanded path if path is valid file, else None
+    """
+
+    path = re.sub(r"\\ ", " ", path)
+    path = pathlib.Path(path).expanduser()
+    if path.is_file():
+        return str(path)
+    return None


 def load_function(pyfile: str, function_name: str) -> Callable:
-    """ Load function_name from python file pyfile """
+    """Load function_name from python file pyfile"""
    module_file = pathlib.Path(pyfile)
    if not module_file.is_file():
        raise FileNotFoundError(f"module {pyfile} does not appear to exist")
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,211 +1,26 @@
-aiohttp==4.0.0a1
-altgraph==0.17
-ansimarkup==1.4.0
-appdirs==1.4.3
-appnope==0.1.0
-astroid==2.2.5
-async-timeout==3.0.1
-atomicwrites==1.3.0
-attrs==19.1.0
-backcall==0.1.0
-better-exceptions-fork==0.2.1.post6
-bitmath==1.3.3.1
-bleach==3.3.0
+Click>=8.0.1,<9.0
+Mako>=1.1.4,<1.2.0
+PyYAML>=5.4.1,<6.0.0
+bitmath>=1.3.3.1,<1.4.0.0
 bpylist2==3.0.2
-certifi==2020.4.5.1
-cffi==1.14.0
-chardet==3.0.4
-Click==7.0
-colorama==0.4.1
-coverage==4.5.4
-decorator==4.4.2
-distlib==0.3.1
-docutils==0.16
-entrypoints==0.3
-filelock==3.0.12
-idna==2.9
-importlib-metadata==1.6.0
-ipykernel==5.1.4
-ipython==7.13.0
-ipython-genutils==0.2.0
-isort==4.3.20
-jedi==0.16.0
-jupyter-client==6.1.2
-jupyter-core==4.6.3
-keyring==21.2.0
-lazy-object-proxy==1.4.1
-loguru==0.2.5
-macholib==1.14
-Mako==1.1.1
-MarkupSafe==1.1.1
-mccabe==0.6.1
-modulegraph==0.18
-more-itertools==7.2.0
-multidict==4.7.6
-osxmetadata>=0.99.11
-packaging==19.0
-parso==0.6.2
-pathspec==0.7.0
-pathvalidate==2.2.1
-pexpect==4.8.0
-photoscript==0.1.2
-pickleshare==0.7.5
-Pillow==8.1.1
-pkginfo==1.5.0.1
-pluggy==0.12.0
-prompt-toolkit==3.0.4
-psutil==5.7.0
-ptyprocess==0.6.0
-py==1.10.0
-py2app==0.21
-pycparser==2.20
-pyfiglet==0.8.post1
-Pygments==2.7.4
-PyInstaller==3.6
-pyinstaller-setuptools==2019.3
-pylint==2.3.1
-pyobjc==6.2.2
-pyobjc-core==6.2.2
-pyobjc-framework-Accounts==6.2.2
-pyobjc-framework-AddressBook==6.2.2
-pyobjc-framework-AdSupport==6.2.2
-pyobjc-framework-AppleScriptKit==6.2.2
-pyobjc-framework-AppleScriptObjC==6.2.2
-pyobjc-framework-ApplicationServices==6.2.2
-pyobjc-framework-AuthenticationServices==6.2.2
-pyobjc-framework-AutomaticAssessmentConfiguration==6.2.2
-pyobjc-framework-Automator==6.2.2
-pyobjc-framework-AVFoundation==6.2.2
-pyobjc-framework-AVKit==6.2.2
-pyobjc-framework-BusinessChat==6.2.2
-pyobjc-framework-CalendarStore==6.2.2
-pyobjc-framework-CFNetwork==6.2.2
-pyobjc-framework-CloudKit==6.2.2
-pyobjc-framework-Cocoa==6.2.2
-pyobjc-framework-Collaboration==6.2.2
-pyobjc-framework-ColorSync==6.2.2
-pyobjc-framework-Contacts==6.2.2
-pyobjc-framework-ContactsUI==6.2.2
-pyobjc-framework-CoreAudio==6.2.2
-pyobjc-framework-CoreAudioKit==6.2.2
-pyobjc-framework-CoreBluetooth==6.2.2
-pyobjc-framework-CoreData==6.2.2
-pyobjc-framework-CoreHaptics==6.2.2
-pyobjc-framework-CoreLocation==6.2.2
-pyobjc-framework-CoreMedia==6.2.2
-pyobjc-framework-CoreMediaIO==6.2.2
-pyobjc-framework-CoreML==6.2.2
-pyobjc-framework-CoreMotion==6.2.2
-pyobjc-framework-CoreServices==6.2.2
-pyobjc-framework-CoreSpotlight==6.2.2
-pyobjc-framework-CoreText==6.2.2
-pyobjc-framework-CoreWLAN==6.2.2
-pyobjc-framework-CryptoTokenKit==6.2.2
-pyobjc-framework-DeviceCheck==6.2.2
-pyobjc-framework-DictionaryServices==6.2.2
-pyobjc-framework-DiscRecording==6.2.2
-pyobjc-framework-DiscRecordingUI==6.2.2
-pyobjc-framework-DiskArbitration==6.2.2
-pyobjc-framework-DVDPlayback==6.2.2
-pyobjc-framework-EventKit==6.2.2
-pyobjc-framework-ExceptionHandling==6.2.2
-pyobjc-framework-ExecutionPolicy==6.2.2
-pyobjc-framework-ExternalAccessory==6.2.2
-pyobjc-framework-FileProvider==6.2.2
-pyobjc-framework-FileProviderUI==6.2.2
-pyobjc-framework-FinderSync==6.2.2
-pyobjc-framework-FSEvents==6.2.2
-pyobjc-framework-GameCenter==6.2.2
-pyobjc-framework-GameController==6.2.2
-pyobjc-framework-GameKit==6.2.2
-pyobjc-framework-GameplayKit==6.2.2
-pyobjc-framework-ImageCaptureCore==6.2.2
-pyobjc-framework-IMServicePlugIn==6.2.2
-pyobjc-framework-InputMethodKit==6.2.2
-pyobjc-framework-InstallerPlugins==6.2.2
-pyobjc-framework-InstantMessage==6.2.2
-pyobjc-framework-Intents==6.2.2
-pyobjc-framework-IOSurface==6.2.2
-pyobjc-framework-iTunesLibrary==6.2.2
-pyobjc-framework-LatentSemanticMapping==6.2.2
-pyobjc-framework-LaunchServices==6.2.2
-pyobjc-framework-libdispatch==6.2.2
-pyobjc-framework-LinkPresentation==6.2.2
-pyobjc-framework-LocalAuthentication==6.2.2
-pyobjc-framework-MapKit==6.2.2
-pyobjc-framework-MediaAccessibility==6.2.2
-pyobjc-framework-MediaLibrary==6.2.2
-pyobjc-framework-MediaPlayer==6.2.2
-pyobjc-framework-MediaToolbox==6.2.2
-pyobjc-framework-Metal==6.2.2
-pyobjc-framework-MetalKit==6.2.2
-pyobjc-framework-ModelIO==6.2.2
-pyobjc-framework-MultipeerConnectivity==6.2.2
-pyobjc-framework-NaturalLanguage==6.2.2
-pyobjc-framework-NetFS==6.2.2
-pyobjc-framework-Network==6.2.2
-pyobjc-framework-NetworkExtension==6.2.2
-pyobjc-framework-NotificationCenter==6.2.2
-pyobjc-framework-OpenDirectory==6.2.2
-pyobjc-framework-OSAKit==6.2.2
-pyobjc-framework-OSLog==6.2.2
-pyobjc-framework-PencilKit==6.2.2
-pyobjc-framework-Photos==6.2.2
-pyobjc-framework-PhotosUI==6.2.2
-pyobjc-framework-PreferencePanes==6.2.2
-pyobjc-framework-PubSub==6.2
-pyobjc-framework-PushKit==6.2.2
-pyobjc-framework-QTKit==6.0.1
-pyobjc-framework-Quartz==6.2.2
-pyobjc-framework-QuickLookThumbnailing==6.2.2
-pyobjc-framework-SafariServices==6.2.2
-pyobjc-framework-SceneKit==6.2.2
-pyobjc-framework-ScreenSaver==6.2.2
-pyobjc-framework-ScriptingBridge==6.2.2
-pyobjc-framework-SearchKit==6.2.2
-pyobjc-framework-Security==6.2.2
-pyobjc-framework-SecurityFoundation==6.2.2
-pyobjc-framework-SecurityInterface==6.2.2
-pyobjc-framework-ServiceManagement==6.2.2
-pyobjc-framework-Social==6.2.2
-pyobjc-framework-SoundAnalysis==6.2.2
-pyobjc-framework-Speech==6.2.2
-pyobjc-framework-SpriteKit==6.2.2
-pyobjc-framework-StoreKit==6.2.2
-pyobjc-framework-SyncServices==6.2.2
-pyobjc-framework-SystemConfiguration==6.2.2
-pyobjc-framework-SystemExtensions==6.2.2
-pyobjc-framework-UserNotifications==6.2.2
-pyobjc-framework-VideoSubscriberAccount==6.2.2
-pyobjc-framework-VideoToolbox==6.2.2
-pyobjc-framework-Vision==6.2.2
-pyobjc-framework-WebKit==6.2.2
-pyparsing==2.4.1.1
-python-dateutil==2.8.1
-PyYAML==5.4
-pyzmq==18.1.1
-readme-renderer==25.0
-regex==2020.2.20
-requests==2.23.0
-requests-toolbelt==0.9.1
-rich==9.11.1
-six==1.14.0
-termcolor==1.1.0
-textx==2.3.0
-toml==0.10.0
-tornado==6.0.4
-tox==3.19.0
-tox-conda==0.2.1
-tqdm==4.45.0
-traitlets==4.3.3
-twine==3.1.1
-typed-ast==1.4.1
-typing-extensions==3.7.4.2
-urllib3==1.25.9
-virtualenv==20.0.30
-wcwidth==0.1.9
-webencodings==0.5.1
-wrapt==1.11.1
-wurlitzer==2.0.1
-yarl==1.4.2
-zipp==0.5.2
+dataclasses==0.7;python_version<'3.7'
+more-itertools>=8.8.0,<9.0.0
+objexplore>=1.5.5,<1.6.0
+osxmetadata>=0.99.34,<1.0.0
+pathvalidate>=2.4.1,<2.5.0
+photoscript>=0.1.4,<0.2.0
+ptpython>=3.0.20,<3.1.0
+pyobjc-core>=7.3,<9.0
+pyobjc-framework-AVFoundation>=7.3,<9.0
+pyobjc-framework-AppleScriptKit>=7.3,<9.0
+pyobjc-framework-AppleScriptObjC>=7.3,<9.0
+pyobjc-framework-Cocoa>=7.3,<9.0
+pyobjc-framework-CoreServices>=7.2,<9.0
+pyobjc-framework-Metal>=7.3,<9.0
+pyobjc-framework-Photos>=7.3,<9.0
+pyobjc-framework-Quartz>=7.3,<9.0
+pyobjc-framework-Vision>=7.3,<9.0
+rich>=10.6.0,<=11.0.0
+textx>=2.3.0,<2.4.0
+toml>=0.10.2,<0.11.0
+wurlitzer>=2.1.0,<2.2.0
--- a/setup.py
+++ b/setup.py
@@ -70,23 +70,36 @@ setup(
        "Programming Language :: Python :: 3.7",
        "Programming Language :: Python :: 3.8",
        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
        "Topic :: Software Development :: Libraries :: Python Modules",
    ],
    install_requires=[
-        "pyobjc>=6.2.2",
-        "Click>=7",
-        "PyYAML>=5.1.2",
-        "Mako>=1.1.1",
+        "Click>=8.0.1,<9.0",
+        "Mako>=1.1.4,<1.2.0",
+        "PyYAML>=5.4.1,<5.5.0",
+        "bitmath>=1.3.3.1,<1.4.0.0",
        "bpylist2==3.0.2",
-        "pathvalidate==2.2.1",
        "dataclasses==0.7;python_version<'3.7'",
-        "wurlitzer>=2.0.1",
-        "photoscript>=0.1.2",
-        "toml>=0.10.0",
-        "osxmetadata>=0.99.13",
-        "textx==2.3.0",
-        "rich>=9.11.1",
-        "bitmath==1.3.3.1",
+        "more-itertools>=8.8.0,<9.0.0",
+        "objexplore>=1.5.5,<1.6.0",
+        "osxmetadata>=0.99.34,<1.0.0",
+        "pathvalidate>=2.4.1,<3.0.0",
+        "photoscript>=0.1.4,<0.2.0",
+        "ptpython>=3.0.20,<4.0.0",
+        "pyobjc-core>=7.3,<9.0",
+        "pyobjc-framework-AVFoundation>=7.3,<9.0",
+        "pyobjc-framework-AppleScriptKit>=7.3,<9.0",
+        "pyobjc-framework-AppleScriptObjC>=7.3,<9.0",
+        "pyobjc-framework-Cocoa>=7.3,<9.0",
+        "pyobjc-framework-CoreServices>=7.2,<9.0",
+        "pyobjc-framework-Metal>=7.3,<9.0",
+        "pyobjc-framework-Photos>=7.3,<9.0",
+        "pyobjc-framework-Quartz>=7.3,<9.0",
+        "pyobjc-framework-Vision>=7.3,<9.0",
+        "rich>=10.6.0,<=11.0.0",
+        "textx>=2.3.0,<3.0.0",
+        "toml>=0.10.2,<0.11.0",
+        "wurlitzer>=2.1.0,<3.0.0",
    ],
    entry_points={"console_scripts": ["osxphotos=osxphotos.__main__:cli"]},
    include_package_data=True,
--- a/tests/Test-10.12.6.photoslibrary/database/photos.db-shm
+++ b/tests/Test-10.12.6.photoslibrary/database/photos.db-shm
--- a/tests/Test-10.12.6.photoslibrary/database/photos.db-wal
+++ b/tests/Test-10.12.6.photoslibrary/database/photos.db-wal
--- a/tests/Test-10.12.6.photoslibrary/private/com.apple.Photos/appPrivateData.plist
+++ b/tests/Test-10.12.6.photoslibrary/private/com.apple.Photos/appPrivateData.plist
@@ -5,7 +5,7 @@
 	<key>LithiumMessageTracer</key>
 	<dict>
 		<key>LastReportedDate</key>
-		<date>2020-04-17T18:39:50Z</date>
+		<date>2021-06-01T17:42:08Z</date>
 	</dict>
 	<key>PXPeopleScreenUnlocked</key>
 	<true/>
--- a/tests/Test-10.12.6.photoslibrary/private/com.apple.photoanalysisd/GraphService/PhotosGraph/construction-photosgraph.graphdb
+++ b/tests/Test-10.12.6.photoslibrary/private/com.apple.photoanalysisd/GraphService/PhotosGraph/construction-photosgraph.graphdb
--- a/tests/Test-10.12.6.photoslibrary/private/com.apple.photoanalysisd/GraphService/PhotosGraph/construction-photosgraph.graphdb-shm
+++ b/tests/Test-10.12.6.photoslibrary/private/com.apple.photoanalysisd/GraphService/PhotosGraph/construction-photosgraph.graphdb-shm
--- a/tests/Test-10.12.6.photoslibrary/resources/moments/analysismetadata.plist
+++ b/tests/Test-10.12.6.photoslibrary/resources/moments/analysismetadata.plist
@@ -11,6 +11,6 @@
 	<key>PLLastRevGeoForcedProviderOutOfDateCheckVersionKey</key>
 	<integer>1</integer>
 	<key>PLLastRevGeoVerFileFetchDateKey</key>
-	<date>2020-04-17T18:39:52Z</date>
+	<date>2021-06-01T17:42:08Z</date>
 </dict>
 </plist>
--- a/tests/Test-10.12.6.photoslibrary/resources/moments/historicalmarker.plist
+++ b/tests/Test-10.12.6.photoslibrary/resources/moments/historicalmarker.plist
@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>LastHistoryRowId</key>
-	<integer>502</integer>
+	<integer>517</integer>
 	<key>LibraryBuildTag</key>
 	<string>E3E46F2A-7168-4973-AB3E-5848F80BFC7D</string>
 	<key>LibrarySchemaVersion</key>
--- a/tests/Test-10.12.6.photoslibrary/resources/proxies/derivatives/00/00/a/UNADJUSTEDNONRAW_mini_a.jpg
+++ b/tests/Test-10.12.6.photoslibrary/resources/proxies/derivatives/00/00/a/UNADJUSTEDNONRAW_mini_a.jpg
--- a/tests/Test-10.12.6.photoslibrary/resources/proxies/derivatives/00/00/a/UNADJUSTEDNONRAW_thumb_a.jpg
+++ b/tests/Test-10.12.6.photoslibrary/resources/proxies/derivatives/00/00/a/UNADJUSTEDNONRAW_thumb_a.jpg
--- a/tests/Test-10.12.6.photoslibrary/resources/recovery/RKImageProxyState/0000000000.lij
+++ b/tests/Test-10.12.6.photoslibrary/resources/recovery/RKImageProxyState/0000000000.lij
--- a/tests/Test-10.12.6.photoslibrary/resources/recovery/RKKeywordForVersion/0000000000.lij
+++ b/tests/Test-10.12.6.photoslibrary/resources/recovery/RKKeywordForVersion/0000000000.lij
--- a/tests/Test-10.12.6.photoslibrary/resources/recovery/RKVersion/0000000000.lij
+++ b/tests/Test-10.12.6.photoslibrary/resources/recovery/RKVersion/0000000000.lij
--- a/tests/Test-10.12.6.photoslibrary/resources/recovery/RKVersionAnalysisState/0000000000.lij
+++ b/tests/Test-10.12.6.photoslibrary/resources/recovery/RKVersionAnalysisState/0000000000.lij
--- a/tests/Test-10.12.6.photoslibrary/resources/segments/Thumb64Segment_0.data
+++ b/tests/Test-10.12.6.photoslibrary/resources/segments/Thumb64Segment_0.data
--- a/tests/Test-10.12.6.photoslibrary/resources/segments/ThumbJPGSegment_0.data
+++ b/tests/Test-10.12.6.photoslibrary/resources/segments/ThumbJPGSegment_0.data
--- a/tests/Test-10.15.7.photoslibrary/database/Photos.sqlite
+++ b/tests/Test-10.15.7.photoslibrary/database/Photos.sqlite
--- a/tests/Test-10.15.7.photoslibrary/database/Photos.sqlite-shm
+++ b/tests/Test-10.15.7.photoslibrary/database/Photos.sqlite-shm
--- a/tests/Test-10.15.7.photoslibrary/database/Photos.sqlite-wal
+++ b/tests/Test-10.15.7.photoslibrary/database/Photos.sqlite-wal
--- a/tests/Test-10.15.7.photoslibrary/database/Photos.sqlite.lock
+++ b/tests/Test-10.15.7.photoslibrary/database/Photos.sqlite.lock
@@ -5,9 +5,9 @@
 	<key>hostname</key>
 	<string>Rhets-MacBook-Pro.local</string>
 	<key>hostuuid</key>
-	<string>9575E48B-8D5F-5654-ABAC-4431B1167324</string>
+	<string>585B80BF-8D1F-55EF-A9E8-6CF4E5523959</string>
 	<key>pid</key>
-	<integer>86501</integer>
+	<integer>1961</integer>
 	<key>processname</key>
 	<string>photolibraryd</string>
 	<key>uid</key>
--- a/tests/Test-10.15.7.photoslibrary/database/search/psi.sqlite
+++ b/tests/Test-10.15.7.photoslibrary/database/search/psi.sqlite
--- a/tests/Test-10.15.7.photoslibrary/database/search/synonymsProcess.plist
+++ b/tests/Test-10.15.7.photoslibrary/database/search/synonymsProcess.plist
--- a/tests/Test-10.15.7.photoslibrary/database/search/zeroKeywords.data
+++ b/tests/Test-10.15.7.photoslibrary/database/search/zeroKeywords.data
--- a/Show More
+++ b/Show More