Cleaned up comments and unneeded test code

Corrected Panorama Flag

.github/workflows/pythonpackage.yml

@@ -5,7 +5,7 @@ on: [push]
 jobs:
   build:
 
-    runs-on: macOS-10.14
+    runs-on: macOS-latest
     strategy:
       max-parallel: 4
       matrix:

CHANGELOG.md

@@ -0,0 +1,178 @@
+### Changelog
+
+All notable changes to this project will be documented in this file. Dates are displayed in UTC.
+
+Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
+
+#### [v0.22.9](https://github.com/RhetTbull/osxphotos/compare/v0.22.7...v0.22.9)
+
+> 1 February 2020
+
+- Updated PhotosDB to only copy database if locked, speed improvement for cases where DB not locked; closes #34 [`#34`](https://github.com/RhetTbull/osxphotos/issues/34)
+- Changed temp file handling to use tempfile.TemporaryDirectory, closes #59 [`#59`](https://github.com/RhetTbull/osxphotos/issues/59)
+- 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)
+- Updated CHANGELOG.md [`f910124`](https://github.com/RhetTbull/osxphotos/commit/f910124fe1fbf75d44c09c79607374bf000733a1)
+
+#### [v0.22.7](https://github.com/RhetTbull/osxphotos/compare/v0.22.4...v0.22.7)
+
+> 27 January 2020
+
+- Corrected Panorama Flag [`#58`](https://github.com/RhetTbull/osxphotos/pull/58)
+- Jan 20 Updates [`#1`](https://github.com/RhetTbull/osxphotos/pull/1)
+- Added XMP sidecar option to export, closes #51 [`#51`](https://github.com/RhetTbull/osxphotos/issues/51)
+- Test library updates, closes #52 [`#52`](https://github.com/RhetTbull/osxphotos/issues/52)
+- 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)
+
+> 20 January 2020
+
+- Add --from-date and --to-date to query and export command [`#57`](https://github.com/RhetTbull/osxphotos/pull/57)
+- Refactor CLI [`#55`](https://github.com/RhetTbull/osxphotos/pull/55)
+- 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)
+
+> 18 January 2020
+
+- Refactored PhotosDB and CLI to require explicity passing the database to avoid non-deterministic behavior when last database can't be found.  This may break existing code. [`ede56ff`](https://github.com/RhetTbull/osxphotos/commit/ede56ffc31cf98811b3d4d16e22406ac0eae0315)
+- Changed get_system_library_path to return None if could not get system library [`646ea4f`](https://github.com/RhetTbull/osxphotos/commit/646ea4f24ca1119b27280af1445e31adcd0690f0)
+- Updated CHANGELOG.md [`bd20388`](https://github.com/RhetTbull/osxphotos/commit/bd20388778dfa645277029601c63fc9835b7a406)
+
+#### [v0.21.5](https://github.com/RhetTbull/osxphotos/compare/v0.21.0...v0.21.5)
+
+> 13 January 2020
+
+- Fixed search for edited photo in path_edited [`edb31f7`](https://github.com/RhetTbull/osxphotos/commit/edb31f796a76912e6ed8182b691396cf4ec62ffa)
+- Added tests for live photos [`5473f3b`](https://github.com/RhetTbull/osxphotos/commit/5473f3b3fd745d4772721dfd1ed821ab0660bf72)
+- Added incloud and iscloudasset for Photos 4 [`e089d13`](https://github.com/RhetTbull/osxphotos/commit/e089d135d3e04320bf98b2c9b11875343e68be04)
+
+#### [v0.21.0](https://github.com/RhetTbull/osxphotos/compare/v0.20.0...v0.21.0)
+
+> 4 January 2020
+
+- Added live photo support for both Photos 4 & 5 [`d5eaff0`](https://github.com/RhetTbull/osxphotos/commit/d5eaff02f2a29a9d105ab72e9a9aeffbc9a3425b)
+- Added support for burst photos; added export-bursts to CLI [`593983a`](https://github.com/RhetTbull/osxphotos/commit/593983a09940e67fb9347bf345cfd7289465fa0a)
+- Added live-photo option to CLI query and export [`6f6d37c`](https://github.com/RhetTbull/osxphotos/commit/6f6d37ceacf71a52a2c0216f0ad75afee244946a)
+
+#### [v0.20.0](https://github.com/RhetTbull/osxphotos/compare/v0.19.0...v0.20.0)
+
+> 1 January 2020
+
+- Added support for filtering only movies or photos to CLI; added search for UTI to CLI [`9cd5363`](https://github.com/RhetTbull/osxphotos/commit/9cd5363a800dd85f333219788c661745b2ce88ad)
+- Added support for bust photos; added export-bursts to CLI [`1136f84`](https://github.com/RhetTbull/osxphotos/commit/1136f84d9b5ea454115ba3d2720625722671e63b)
+- Temporary fix to filter out unselected burst photos [`a550ba0`](https://github.com/RhetTbull/osxphotos/commit/a550ba00d6ff43a819cb18446e532f10ded81834)
+
+#### [v0.19.0](https://github.com/RhetTbull/osxphotos/compare/v0.18.0...v0.19.0)
+
+> 29 December 2019
+
+- Added support for movies for Photos 5; fixed bugs in ismissing and path [`6f4d129`](https://github.com/RhetTbull/osxphotos/commit/6f4d129f07046c4a34d3d6cf6854c8514a594781)
+- Added support for movies for Photos 5; fixed bugs in ismissing and path [`b030966`](https://github.com/RhetTbull/osxphotos/commit/b030966051af93be380ff967ac047bf566e5d817)
+- Initial support for movies [`dbe363e`](https://github.com/RhetTbull/osxphotos/commit/dbe363e4d754253a0405fb1df045677e8780d630)
+
+#### [v0.18.0](https://github.com/RhetTbull/osxphotos/compare/v0.15.1...v0.18.0)
+
+> 27 December 2019
+
+- Restructured entire code base to make it easier to maintain. Closes #16 [`#16`](https://github.com/RhetTbull/osxphotos/issues/16)
+- Added TOC to README; closes #24 [`#24`](https://github.com/RhetTbull/osxphotos/issues/24)
+- 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.14.21...v0.15.1)
+
+> 14 December 2019
+
+- Added PhotoInfo.export(); closes #10 [`#10`](https://github.com/RhetTbull/osxphotos/issues/10)
+- refactored private vars in PhotoInfo [`d5a5bd4`](https://github.com/RhetTbull/osxphotos/commit/d5a5bd41b3d3e184d3f9a9d05a32a51fcbe1ef0a)
+- Updated export example [`bf8aed6`](https://github.com/RhetTbull/osxphotos/commit/bf8aed69cfff61733e4cfd5ed2058bb20e3f5299)
+
+#### [v0.14.21](https://github.com/RhetTbull/osxphotos/compare/v0.14.8...v0.14.21)
+
+> 9 December 2019
+
+- Added list option to cmd_line. Closes #14 [`#14`](https://github.com/RhetTbull/osxphotos/issues/14)
+- added edited and external_edit to cmd_line and __str__, to_json; closes #12 [`#12`](https://github.com/RhetTbull/osxphotos/issues/12)
+- Cleaned up logic in cmd_line query(). Closes #17 [`#17`](https://github.com/RhetTbull/osxphotos/issues/17)
+- 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)
+
+> 30 November 2019
+
+- Added path_edited() for Photos 5, still needs to be added for Photos <= 4.0 [`68eef42`](https://github.com/RhetTbull/osxphotos/commit/68eef42599c737e180d2d0ead936630abd5a8a65)
+- Fixed path_edited() for Photos 4.0 [`37dfc1e`](https://github.com/RhetTbull/osxphotos/commit/37dfc1e1513c93088fca7cc6def1219d32694468)
+- cleaned up commented out code [`3dc0943`](https://github.com/RhetTbull/osxphotos/commit/3dc09434535b98a7989c2051a28ecf3ebdc772cc)
+
+#### [v0.14.6](https://github.com/RhetTbull/osxphotos/compare/v0.14.4...v0.14.6)
+
+> 28 November 2019
+
+- Added tests for hidden and favorite to both 14.6 and 15.1 [`51e720d`](https://github.com/RhetTbull/osxphotos/commit/51e720dce9238c2a2b44a7ae956e40f0cd6452d7)
+- Added location (latitude/longitude), closes issue #2 [`44321da`](https://github.com/RhetTbull/osxphotos/commit/44321da243e374c5239e9bcd28c3515e32e1076a)
+- cleaned up test code [`b2242da`](https://github.com/RhetTbull/osxphotos/commit/b2242da9b7031f614c73be3fb5446a97f69b1d0d)
+
+#### [v0.14.4](https://github.com/RhetTbull/osxphotos/compare/v0.14.0...v0.14.4)
+
+> 25 November 2019
+
+- Added name and description to cmd_line [`5af2b3e`](https://github.com/RhetTbull/osxphotos/commit/5af2b3e039e5e5a92b858592b8b968568d82e40f)
+- removed loguru code [`aa73c2f`](https://github.com/RhetTbull/osxphotos/commit/aa73c2f0559de6bcdc521e9345e07898b36795bb)
+- Added hidden/favorite/missing to cmd_line [`b36b7e7`](https://github.com/RhetTbull/osxphotos/commit/b36b7e7eb2a258f864f34363de4b6d9228ee6090)
+
+#### [v0.14.0](https://github.com/RhetTbull/osxphotos/compare/v0.12.3...v0.14.0)
+
+> 24 November 2019
+
+- added test for 10.15/Catalina [`243492d`](https://github.com/RhetTbull/osxphotos/commit/243492df88409566c46cbc02ca01d509e711bcdd)
+- moved process_photos to process_photos4 and process_photos5 [`7eff015`](https://github.com/RhetTbull/osxphotos/commit/7eff015439361f3f7be99777d878713afd10c480)
+- basic Photos 5 info now being read [`a4b5f2a`](https://github.com/RhetTbull/osxphotos/commit/a4b5f2a501d9c98f9609de96757481f323b31ab0)
+
+#### [v0.12.3](https://github.com/RhetTbull/osxphotos/compare/v0.12.2...v0.12.3)
+
+> 24 August 2019
+
+- fixed typo in README [`39ef8dd`](https://github.com/RhetTbull/osxphotos/commit/39ef8ddf3fdf8e9d22566c51783f9b78fab4f439)
+
+#### [v0.12.2](https://github.com/RhetTbull/osxphotos/compare/v0.10.4-beta...v0.12.2)
+
+> 24 August 2019
+
+- Added tests for 10.14.6 [`fb2c12d`](https://github.com/RhetTbull/osxphotos/commit/fb2c12d9818fbec74f947638b1b60a2c3f73effb)
+- Added support and tests for 10.12 [`58f5283`](https://github.com/RhetTbull/osxphotos/commit/58f52833d62672ed13fcfa16be5d999e75f37e2b)
+- Added osxphotos command line tool [`0e65ab5`](https://github.com/RhetTbull/osxphotos/commit/0e65ab5452d96dc9913683d90d1fb2c833cd75b8)
+
+#### [v0.10.4-beta](https://github.com/RhetTbull/osxphotos/compare/v0.10.1-alpha...v0.10.4-beta)
+
+> 28 July 2019
+
+- Added test for 10.14 mojave [`af122e9`](https://github.com/RhetTbull/osxphotos/commit/af122e9392d45387e302ebb79b28e045dd3fa61a)
+- update requirements.txt [`81be373`](https://github.com/RhetTbull/osxphotos/commit/81be373505ad858ae8ef1196ccfb5e6f04bf6bfc)
+- Updated README, added os & db version tests, updated test library for 10.13 [`a58ac14`](https://github.com/RhetTbull/osxphotos/commit/a58ac149f313ece99ff2d32a8c22e8b8b75eaebc)
+
+#### v0.10.1-alpha
+
+> 27 July 2019
+
+- first commit [`8b61d57`](https://github.com/RhetTbull/osxphotos/commit/8b61d573ed4dbb3fd44b94ee265767b2011fcf90)
+- Added tests [`3023f56`](https://github.com/RhetTbull/osxphotos/commit/3023f568b73733fb3dfbba4f519a7c2d1995784f)
+- Updated README, added PhotoInfo.hasadjustments() [`9efa83c`](https://github.com/RhetTbull/osxphotos/commit/9efa83c5cd3f23cf681c459f73a466496c552396)

README.md

@@ -3,103 +3,208 @@
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+- [OSXPhotos](#osxphotos)
+  * [What is osxphotos?](#what-is-osxphotos)
+  * [Supported operating systems](#supported-operating-systems)
+  * [Installation instructions](#installation-instructions)
+  * [Command Line Usage](#command-line-usage)
+  * [Example uses of the module](#example-uses-of-the-module)
+  * [Module Interface](#module-interface)
+    + [PhotosDB](#photosdb)
+    + [PhotoInfo](#photoinfo)
+    + [Utility Functions](#utility-functions)
+    + [Examples](#examples)
+  * [Related Projects](#related-projects)
+  * [Contributing](#contributing)
+  * [Implementation Notes](#implementation-notes)
+  * [Dependencies](#dependencies)
+  * [Acknowledgements](#acknowledgements) 
+  
 ## What is osxphotos?
 
-OSXPhotos provides the ability to interact with and query Apple's Photos app library database on Mac OS X. Using this module you can query the Photos database for information about the photos stored in a Photos library--for example, file name, file path, and metadata such as keywords/tags, persons/faces, albums, etc.     
+OSXPhotos provides the ability to interact with and query Apple's Photos.app library database on MacOS. Using this module you can query the Photos database for information about the photos stored in a Photos library on your Mac--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.
 
 ## Supported operating systems
 
-Only works on Mac OS X. Tested on Mac OS 10.12.6 / Photos 2.0, 10.13.6 / Photos 3.0 and Mac OS 10.14.5, 10.14.6 / Photos 4.0. Requires python >= 3.6
+Only works on MacOS (aka Mac OS X). Tested on MacOS 10.12.6 / Photos 2.0, 10.13.6 / Photos 3.0, MacOS 10.14.5, 10.14.6 / Photos 4.0, MacOS 10.15.1 / Photos 5.0. Requires python >= 3.6
 
-NOTE: Alpha support for Mac OS 10.15.0 / Photos 5.0.  Photos 5.0 uses a new database format which required rewrite of much of the code for this package.  If you find bugs, please open an [issue](https://github.com/RhetTbull/osxphotos/issues/).
-
-This module will read Photos databases for any supported version on any supported OS version.  E.g. you can read a database created with Photos 4.0 on Mac OS 10.14 on a machine running Mac OS 10.12
+This module will read Photos databases for any supported version on any supported OS version.  E.g. you can read a database created with Photos 4.0 on MacOS 10.14 on a machine running MacOS 10.12
 
 
 ## Installation instructions
 
 osxmetadata uses setuptools, thus simply run:
 
-	python setup.py install
+	python3 setup.py install
 
 ## Command Line Usage
 
-This module will install a command line utility called `osxphotos` that allows you to query the Photos database.
+This module will install a command line utility called `osxphotos` that allows you to query the Photos database.  Alternatively, you can also run the command line utility like this: `python3 -m osxphotos`
 
 If you only care about the command line tool, I recommend installing with [pipx](https://github.com/pipxproject/pipx)
 
 After installing pipx:
 `pipx install osxphotos`
 
+Then you should be able to run `osxphotos` on the command line:
+
 ```
+> osxphotos
 Usage: osxphotos [OPTIONS] COMMAND [ARGS]...
 
 Options:
-  --db <Photos database path>  Specify database file
-  --json                       Print output in JSON format
+  --db <Photos database path>  Specify database file.
+  --json                       Print output in JSON format.
+  -v, --version                Show the version and exit.
   -h, --help                   Show this message and exit.
 
 Commands:
-  albums    print out albums found in the Photos library
-  dump      print list of all photos & associated info from the Photos...
-  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
-  persons   print out persons (faces) found in the Photos library
-  query     query the Photos database using 1 or more search options
+  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.
+  list      Print list of Photos libraries found on the system.
+  persons   Print out persons (faces) found in the Photos library.
+  query     Query the Photos database using 1 or more search options; if...
 ```
 
 To get help on a specific command, use `osxphotos help <command_name>`
 
-Example: `osxphotos help query`
+Example: `osxphotos help export`
 
 ```
-Usage: osxphotos help [OPTIONS]
+Usage: osxphotos export [OPTIONS] [PHOTOS_LIBRARY]... DEST
 
-  Query the Photos database using 1 or more search options
-
-  If more than one option is provided, they are treated as "AND"  (e.g.
-  search for photos matching all options)
+  Export photos from the Photos database. Export path DEST is required.
+  Optionally, query the Photos database using 1 or more search options;  if
+  more than one option is provided, they are treated as "AND"  (e.g. search
+  for photos matching all options). If no query options are provided, all
+  photos will be exported.
 
 Options:
-  --keyword TEXT      search for keyword(s)
-  --person TEXT       search for person(s)
-  --album TEXT        search for album(s)
-  --uuid TEXT         search for UUID(s)
-  --name TEXT         search for TEXT in name of photo
-  --no-name           search for photos with no name
-  --description TEXT  search for TEXT in description of photo
-  --no-description    search for photos with no description
-  -i, --ignore-case   case insensitive search for name or description. Does
-                      not apply to keyword, person, or album
-  --favorite          search for photos marked favorite
-  --not-favorite      search for photos not marked favorite
-  --hidden            search for photos marked hidden
-  --not-hidden        search for photos not marked hidden
-  --missing           search for photos missing from disk
-  --not-missing       search for photos present on disk (e.g. not missing)
-  --json              Print output in JSON format
-  -h, --help          Show this message and exit.
+  --db <Photos database path>     Specify Photos database path. Path to Photos
+                                  library/database can be specified using
+                                  either --db or directly as PHOTOS_LIBRARY
+                                  positional argument. If neither --db or
+                                  PHOTOS_LIBRARY provided, will attempt to
+                                  find the library to use in the following
+                                  order: 1. last opened library, 2. system
+                                  library, 3. ~/Pictures/Photos
+                                  Library.photoslibrary
+  --keyword KEYWORD               Search for keyword(s).
+  --person PERSON                 Search for person(s).
+  --album ALBUM                   Search for album(s).
+  --uuid UUID                     Search for UUID(s).
+  --title TITLE                   Search for TITLE in title of photo.
+  --no-title                      Search for photos with no title.
+  --description DESC              Search for DESC in description of photo.
+  --no-description                Search for photos with no description.
+  --uti UTI                       Search for photos whose uniform type
+                                  identifier (UTI) matches UTI
+  -i, --ignore-case               Case insensitive search for title or
+                                  description. Does not apply to keyword,
+                                  person, or album.
+  --edited                        Search for photos that have been edited.
+  --external-edit                 Search for photos edited in external editor.
+  --favorite                      Search for photos marked favorite.
+  --not-favorite                  Search for photos not marked favorite.
+  --hidden                        Search for photos marked hidden.
+  --not-hidden                    Search for photos not marked hidden.
+  --shared                        Search for photos in shared iCloud album
+                                  (Photos 5 only).
+  --not-shared                    Search for photos not in shared iCloud album
+                                  (Photos 5 only).
+  --burst                         Search for photos that were taken in a
+                                  burst.
+  --not-burst                     Search for photos that are not part of a
+                                  burst.
+  --live                          Search for Apple live photos
+  --not-live                      Search for photos that are not Apple live
+                                  photos
+  --only-movies                   Search only for movies (default searches
+                                  both images and movies).
+  --only-photos                   Search only for photos/images (default
+                                  searches both images and movies).
+  --from-date [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]
+                                  Search by start item date, e.g.
+                                  2000-01-12T12:00:00 or 2000-12-31 (ISO 8601
+                                  w/o TZ).
+  --to-date [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]
+                                  Search by end item date, e.g.
+                                  2000-01-12T12:00:00 or 2000-12-31 (ISO 8601
+                                  w/o TZ).
+  -V, --verbose                   Print verbose output.
+  --overwrite                     Overwrite existing files. Default behavior
+                                  is to add (1), (2), etc to filename if file
+                                  already exists. Use this with caution as it
+                                  may create name collisions on export. (e.g.
+                                  if two files happen to have the same name)
+  --export-by-date                Automatically create output folders to
+                                  organize photos by date created (e.g.
+                                  DEST/2019/12/20/photoname.jpg).
+  --export-edited                 Also export edited version of photo if an
+                                  edited version exists.  Edited photo will be
+                                  named in form of "photoname_edited.ext"
+  --export-bursts                 If a photo is a burst photo export all
+                                  associated burst images in the library.
+  --export-live                   If a photo is a live photo export the
+                                  associated live video component.  Live video
+                                  will have same name as photo but with .mov
+                                  extension.
+  --original-name                 Use photo's original filename instead of
+                                  current filename for export.
+  --sidecar FORMAT                Create sidecar for each photo exported;
+                                  valid FORMAT values: xmp, json; --sidecar
+                                  json: create JSON sidecar useable by
+                                  exiftool (https://exiftool.org/) The sidecar
+                                  file can be used to apply metadata to the
+                                  file with exiftool, for example: "exiftool
+                                  -j=photoname.json photoname.jpg" The sidecar
+                                  file is named in format photoname.json
+                                  --sidecar xmp: create XMP sidecar used by
+                                  Adobe Lightroom, etc. The sidecar file is
+                                  named in format photoname.xmp
+  --download-missing              Attempt to download missing photos from
+                                  iCloud. The current implementation uses
+                                  Applescript to interact with Photos to
+                                  export the photo which will force Photos to
+                                  download from iCloud if the photo does not
+                                  exist on disk.  This will be slow and will
+                                  require internet connection. This obviously
+                                  only works if the Photos library is synched
+                                  to iCloud.
+  -h, --help                      Show this message and exit.
 ```
 
+Example: export all photos to ~/Desktop/export, including edited versions and live photo movies, group in folders by date created
+`osxphotos export --export-edited --export-live --export-by-date ~/Pictures/Photos\ Library.photoslibrary ~/Desktop/export`
+
+**Note**: Photos library/database path can also be specified using --db option:
+`osxphotos export --export-edited --export-live --export-by-date --db ~/Pictures/Photos\ Library.photoslibrary ~/Desktop/export`
+
 Example: find all photos with keyword "Kids" and output results to json file named results.json:
 
-`osxphotos query --keyword Kids --json >results.json`
+`osxphotos query --keyword Kids --json ~/Pictures/Photos\ Library.photoslibrary >results.json`
 
-## Example uses of the module
+## Example uses of the module 
 
 ```python
+import os.path
+
 import osxphotos
 
 def main():
-    photosdb = osxphotos.PhotosDB()
-    print(photosdb.keywords())
-    print(photosdb.persons())
-    print(photosdb.albums())
+    db = os.path.expanduser("~/Pictures/Photos Library.photoslibrary")
+    photosdb = osxphotos.PhotosDB(db)
+    print(photosdb.keywords)
+    print(photosdb.persons)
+    print(photosdb.albums)
 
-    print(photosdb.keywords_as_dict())
-    print(photosdb.persons_as_dict())
-    print(photosdb.albums_as_dict())
+    print(photosdb.keywords_as_dict)
+    print(photosdb.persons_as_dict)
+    print(photosdb.albums_as_dict)
 
     # find all photos with Keyword = Foo and containing John Smith
     photos = photosdb.photos(keywords=["Foo"],persons=["John Smith"])
@@ -110,42 +215,100 @@ def main():
     for p in photos:
         print(
             p.uuid,
-            p.filename(),
-            p.original_filename(),
-            p.date(),
-            p.description(),
-            p.name(),
-            p.keywords(),
-            p.albums(),
-            p.persons(),
-            p.path(),
+            p.filename,
+            p.original_filename,
+            p.date,
+            p.description,
+            p.title,
+            p.keywords,
+            p.albums,
+            p.persons,
+            p.path,
         )
 
 if __name__ == "__main__":
     main()
 ```
 
+```python
+""" Export all photos to ~/Desktop/export
+    If file has been edited, export the edited version, 
+    otherwise, export the original version """
+
+import os.path
+import osxphotos
+
+
+def main():
+    db = os.path.expanduser("~/Pictures/Photos Library.photoslibrary")
+    photosdb = osxphotos.PhotosDB(db)
+    photos = photosdb.photos()
+
+    export_path = os.path.expanduser("~/Desktop/export")
+
+    for p in photos:
+        if not p.ismissing:
+            if p.hasadjustments:
+                exported = p.export(export_path, edited=True)
+            else:
+                exported = p.export(export_path)
+            print(f"Exported {p.filename} to {exported}")
+        else:
+            print(f"Skipping missing photo: {p.filename}")
+
+
+if __name__ == "__main__":
+    main()
+```
+
 ## Module Interface
 
 ### PhotosDB
 
-#### Open the default Photos library
+#### Read a Photos library database
 
 ```python
-osxphotos.PhotosDB([dbfile="path to database file"])
+osxphotos.PhotosDB() # not recommended, see Note below
+osxphotos.PhotosDB(path)
+osxphotos.PhotosDB(dbfile=path)
 ```
 
-Opens the Photos library database and returns a PhotosDB object.  Optionally, pass the path to a specific database file.  If `dbfile` is not included, will open the default (last opened) Photos database.
+Reads the Photos library database and returns a PhotosDB object.  
 
-Note: this will open the last library that was opened in Photos. This is not necessarily the System Photos Library.  If you have more than one Photos library, you can select which to open by holding down Option key while opening Photos.
+Pass the path to a Photos library or to a specific database file (e.g. "/Users/smith/Pictures/Photos Library.photoslibrary" or "/Users/smith/Pictures/Photos Library.photoslibrary/database/photos.db").  Normally, it's recommended you pass the path the .photoslibrary folder, not the actual database path.  The latter option is provided for debugging -- e.g. for reading a database file if you don't have the entire library. Path to photos library may be passed **either** as first argument **or** as named argument `dbfile`. **Note**: In Photos, users may specify a different library to open by holding down the *option* key while opening Photos.app. See also [get_last_library_path](#get_last_library_path) and [get_system_library_path](#get_system_library_path)
+
+If an invalid path is passed, PhotosDB will raise `FileNotFoundError` exception.
+
+**Note**: If neither path or dbfile is passed, PhotosDB will use get_last_library_path to open the last opened Photos library.  This usually works but is not 100% reliable.  It can also lead to loading a different library than expected if the user has held down *option* key when opening Photos to switch libraries.  It is therefore recommended you explicitely pass the path to `PhotosDB()`.  
+
+#### Open the default (last opened) Photos library
+
+The default library is the library that would open if the user opened Photos.app.
+
+```python
+import osxphotos
+photosdb = osxphotos.PhotosDB(osxphotos.utils.get_last_library_path())
+```
+
+#### Open System Photos library
+
+In Photos 5 (Catalina / MacOS 10.15), you can use `get_system_library_path()` to get the path to the System photo library if you want to ensure PhotosDB opens the system library.  This does not work on older versions of MacOS. E.g.
 
 ```python
 import osxphotos
 
-photosdb = osxphotos.PhotosDB()
+path = osxphotos.get_system_library_path()
+photosdb = osxphotos.PhotosDB(path)
 ```
 
-Returns a PhotosDB object. 
+also,
+
+```python
+import osxphotos
+
+path = osxphotos.get_system_library_path()
+photosdb = osxphotos.PhotosDB(dbfile=path)
+```
 
 #### Open a specific Photos library
 ```python
@@ -154,88 +317,121 @@ import osxphotos
 photosdb = osxphotos.PhotosDB(dbfile="/Users/smith/Pictures/Test.photoslibrary/database/photos.db")
 ```
 
-Pass the fully qualified path to the specific Photos database you want to open. The database is called photos.db and resides in the database folder in your Photos library
+or
 
-#### ```keywords```
+```python
+import osxphotos
+
+photosdb = osxphotos.PhotosDB("/Users/smith/Pictures/Test.photoslibrary")
+```
+
+Pass the fully qualified path to the Photos library or the actual database file inside the library. The database is called photos.db and resides in the database folder in your Photos library.  If you pass only the path to the library, PhotosDB will add the database path automatically.  The option to pass the actual database path is provided so database files can be queried even if separated from the actual .photoslibrary file. 
+
+Returns a PhotosDB object. 
+
+**Note**: If you have a large library (e.g. many thousdands of photos), creating the PhotosDB object can take a long time (10s of seconds).  See [Implementation Notes](#implementation-notes) for additional details. 
+
+#### `keywords`
 ```python
 # assumes photosdb is a PhotosDB object (see above)
-keywords = photosdb.keywords()
+keywords = photosdb.keywords
 ```
 
 Returns a list of the keywords found in the Photos library
 
-#### ```albums```
+#### `albums`
 ```python
 # assumes photosdb is a PhotosDB object (see above)
-albums = photosdb.albums()
+albums = photosdb.albums
 ```
 
-Returns a list of the albums found in the Photos library
+Returns a list of the albums found in the Photos library.  
 
-#### ```persons```
+**Note**: In Photos 5.0 (MacOS 10.15/Catalina), It is possible to have more than one album with the same name in Photos.  Albums with duplicate names are treated as a single album and the photos in each are combined.  For example, if you have two albums named "Wedding" and each has 2 photos, osxphotos will treat this as a single album named "Wedding" with 4 photos in it.
+
+#### `albums_shared`
+
+Returns list of shared albums found in photos database (e.g. albums shared via iCloud photo sharing)
+
+**Note**: *Only valid for Photos 5 / MacOS 10.15*; on Photos <= 4, prints warning and returns empty list.
+
+#### `persons`
 ```python
 # assumes photosdb is a PhotosDB object (see above)
-persons = photosdb.persons()
+persons = photosdb.persons
 ```
 
 Returns a list of the persons (faces) found in the Photos library
 
-#### ```keywords_as_dict```
+#### `keywords_as_dict`
 ```python
 # assumes photosdb is a PhotosDB object (see above)
-keyword_dict = photosdb.keywords_as_dict()
+keyword_dict = photosdb.keywords_as_dict
 ```
 
 Returns a dictionary of keywords found in the Photos library where key is the keyword and value is the count of how many times that keyword appears in the library (ie. how many photos are tagged with the keyword).  Resulting dictionary is in reverse sorted order (e.g. keyword with the highest count is first).
 
-#### ```persons_as_dict```
+#### `persons_as_dict`
 ```python
 # assumes photosdb is a PhotosDB object (see above)
-persons_dict = photosdb.persons_as_dict()
+persons_dict = photosdb.persons_as_dict
 ```
 
 Returns a dictionary of persons (faces) found in the Photos library where key is the person name and value is the count of how many times that person appears in the library (ie. how many photos are tagged with the person).  Resulting dictionary is in reverse sorted order (e.g. person who appears in the most photos is listed first).
 
-#### ```albums_as_dict```
+#### `albums_as_dict`
 ```python
 # assumes photosdb is a PhotosDB object (see above)
-albums_dict = photosdb.albums_as_dict()
+albums_dict = photosdb.albums_as_dict
 ```
 
-Returns a dictionary of albums found in the Photos library where key is the album name and value is the count of how many photos are in the album.  Resulting dictionary is in reverse sorted order (e.g. album with the most photos is listed first)
+Returns a dictionary of albums found in the Photos library where key is the album name and value is the count of how many photos are in the album.  Resulting dictionary is in reverse sorted order (e.g. album with the most photos is listed first).  
 
-#### ```get_photos_library_path```
+**Note**: In Photos 5.0 (MacOS 10.15/Catalina), It is possible to have more than one album with the same name in Photos.  Albums with duplicate names are treated as a single album and the photos in each are combined.  For example, if you have two albums named "Wedding" and each has 2 photos, osxphotos will treat this as a single album named "Wedding" with 4 photos in it.
+
+#### `albums_shared_as_dict`
 ```python
 # assumes photosdb is a PhotosDB object (see above)
-photosdb.get_photos_library_path()
+albums_shared_dict = photosdb.albums_shared_as_dict
+```
+
+Returns a dictionary of shared albums (e.g. shared via iCloud photo sharing) found in the Photos library where key is the album name and value is the count of how many photos are in the album.  Resulting dictionary is in reverse sorted order (e.g. album with the most photos is listed first).   
+
+**Note**: *Photos 5 / MacOS 10.15 only*.  On earlier versions of Photos, prints warning and returns empty dictionary.
+
+#### `library_path`
+```python
+# assumes photosdb is a PhotosDB object (see above)
+photosdb.library_path
 ```
 
 Returns the path to the Photos library as a string
 
-#### ```get_db_path```
+#### `db_path`
 ```python
 # assumes photosdb is a PhotosDB object (see above)
-photosdb.get_db_path()
+photosdb.db_path
 ```
 
 Returns the path to the Photos database PhotosDB was initialized with
 
-#### ```get_db_version```
+#### `db_version`
 ```python
 # assumes photosdb is a PhotosDB object (see above)
-photosdb.get_db_version()
+photosdb.db_version
 ```
 
 Returns the version number for Photos library database.  You likely won't need this but it's provided in case needed for debugging. PhotosDB will print a warning to `sys.stderr` if you open a database version that has not been tested. 
 
 
-#### ```photos```
+#### ` photos(keywords=None, uuid=None, persons=None, albums=None, images=True, movies=False, from_date=None, to_date=None)`
+
 ```python
 # assumes photosdb is a PhotosDB object (see above)
-photos = photosdb.photos([keywords=['keyword',]], [uuid=['uuid',]], [persons=['person',]], [albums=['album',]])
+photos = photosdb.photos([keywords=['keyword',]], [uuid=['uuid',]], [persons=['person',]], [albums=['album',]],[from_date=datetime.datetime],[to_date=datetime.datetime])
 ```
 
-Returns a list of PhotoInfo objects.  Each PhotoInfo object represents a photo in the Photos Libary.
+Returns a list of [PhotoInfo](#PhotoInfo) objects.  Each PhotoInfo object represents a photo in the Photos Libary.
 
 If called with no parameters, returns a list of every photo in the Photos library. 
 
@@ -245,16 +441,24 @@ photos = photosdb.photos(
     keywords = [],
     uuid = [],
     persons = [],
-    albums = []
+    albums = [],
+    images = bool,
+    movies = bool,
+    from_date = datetime.datetime,
+    to_date = datetime.datetime
 )
 ```
 
 - ```keywords```: list of one or more keywords.  Returns only photos containing the keyword(s).  If more than one keyword is provided finds photos matching any of the keywords (e.g. treated as "or")
-- ```uuid```: list of one or more uuids.  Returns only photos whos UUID matches.  Note: The UUID is the universally unique identifier that the Photos database uses to identify each photo.  You shouldn't normally need to use this but it is a way to access a specific photo if you know the UUID.  If more than more uuid is provided, returns photos that match any of the uuids (e.g. treated as "or")
+- ```uuid```: list of one or more uuids.  Returns only photos whos UUID matches.  **Note**: The UUID is the universally unique identifier that the Photos database uses to identify each photo.  You shouldn't normally need to use this but it is a way to access a specific photo if you know the UUID.  If more than more uuid is provided, returns photos that match any of the uuids (e.g. treated as "or")
 - ```persons```: list of one or more persons. Returns only photos containing the person(s).  If more than one person provided, returns photos that match any of the persons (e.g. treated as "or")
 - ```albums```: list of one or more album names.  Returns only photos contained in the album(s). If more than one album name is provided, returns photos contained in any of the albums (.e.g. treated as "or")
+- ```images```: bool; if True, returns photos/images; default is True
+- ```movies```: bool; if True, returns movies/videos; default is False
+- ```from_date```: datetime.datetime; if provided, finds photos where creation date >= from_date; default is None
+- ```to_date```: datetime.datetime; if provided, finds photos where creation date <= to_date; default is None
 
-If more than one of these parameters is provided, they are treated as "and" criteria. E.g.
+If more than one of (keywords, uuid, persons, albums,from_date, to_date) is provided, they are treated as "and" criteria. E.g.
 
 Finds all photos with (keyword = "wedding" or "birthday") and (persons = "Juan Rodriguez")
 
@@ -295,98 +499,307 @@ photos2 = photosdb.photos(keywords=["Kids"])
 photos3 = [p for p in photos2 if p not in photos1]
 ```
 
+By default, photos() only returns images, not movies.  To also get movies, pass movies=True:
+```python
+photos_and_movies = photosdb.photos(movies=True)
+```
+
+To get only movies:
+```python
+movies = photosdb.photos(images=False, movies=True)
+```
+**Note** PhotosDB.photos() may return a different number of photos than Photos.app reports in the GUI. This is because photos() returns [hidden](#hidden) photos, [shared](#shared) photos, and for [burst](#burst) photos, all selected burst images even if non-selected burst images have not been deleted. Photos only reports 1 single photo for each set of burst images until you "finalize" the burst by selecting key photos and deleting the others using the "Make a selection" option. 
+
+For example, in my library, Photos says I have 19,386 photos and 474 movies.  However, PhotosDB.photos() reports 25,002 photos.  The difference is due to 5,609 shared photos and 7 hidden photos.  (*Note* Shared photos only valid for Photos 5).  Similarly, filtering for just movies returns 625 results.  The difference between 625 and 474 reported by Photos is due to 151 shared movies.
+
+```python
+>>> import osxphotos
+>>> photosdb = osxphotos.PhotosDB("/Users/smith/Pictures/Photos Library.photoslibrary")
+>>> photos = photosdb.photos()
+>>> len(photos)
+25002
+>>> shared = [p for p in photos if p.shared]
+>>> len(shared)
+5609
+>>> not_shared = [p for p in photos if not p.shared]
+>>> len(not_shared)
+19393
+>>> hidden = [p for p in photos if p.hidden]
+>>> len(hidden)
+7
+>>> movies = photosdb.photos(movies=True, images=False)
+>>> len(movies)
+625
+>>> shared_movies = [m for m in movies if m.shared]
+>>> len(shared_movies)
+151
+>>>
+```
+
 ### PhotoInfo 
 PhotosDB.photos() returns a list of PhotoInfo objects.  Each PhotoInfo object represents a single photo in the Photos library.
 
-#### `uuid()`
+#### `uuid`
 Returns the universally unique identifier (uuid) of the photo.  This is how Photos keeps track of individual photos within the database.
 
-#### `filename()`
-Returns the current filename of the photo on disk.  See also `original_filename()`
+#### `filename`
+Returns the current filename of the photo on disk.  See also [original_filename](#original_filename)
 
-#### `original_filename()`
-Returns the original filename of the photo when it was imported to Photos.  Note: Photos 5.0+ renames the photo when it adds the file to the library using UUID.  See also `filename()`
+#### `original_filename`
+Returns the original filename of the photo when it was imported to Photos.  **Note**: Photos 5.0+ renames the photo when it adds the file to the library using UUID.  See also [filename](#filename)
 
-#### `date()`
-Returns the date of the photo as a datetime.datetime object
+#### `date`
+Returns the create date of the photo as a datetime.datetime object
 
-#### `description()`
+#### `date_modified`
+Returns the modification date of the photo as a datetime.datetime object or None if photo has no modification date
+
+#### `description`
 Returns the description of the photo
 
-#### `name()`
-Returns the name (or the title as Photos calls it) of the photo
+#### `title`
+Returns the title of the photo
 
-#### `keywords()`
+#### `keywords`
 Returns a list of keywords (e.g. tags) applied to the photo
 
-#### `albums()`
+#### `albums`
 Returns a list of albums the photo is contained in
 
-#### `persons()`
+#### `persons`
 Returns a list of the names of the persons in the photo
 
-#### `path()`
-Returns the absolute path to the photo on disk as a string.  Note: this returns the path to the *original* unedited file (see `hasadjustments()`).  If the file is missing on disk, path=`None` (see `ismissing()`)
+#### `path`
+Returns the absolute path to the photo on disk as a string.  **Note**: this returns the path to the *original* unedited file (see [hasadjustments](#hasadjustments)).  If the file is missing on disk, path=`None` (see [ismissing](#ismissing)).
 
-#### `ismissing()`
-Returns `True` if the original image file is missing on disk, otherwise `False`.  This can occur if the file has been uploaded to iCloud but not yet downloaded to the local library or if the file was deleted or imported from a disk that has been unmounted. Note: this status is set by Photos and osxphotos does not verify that the file path returned by `path()` actually exists.  It merely reports what Photos has stored in the library database. 
+#### `path_edited`
+Returns the absolute path to the edited photo on disk as a string.  If the photo has not been edited, returns `None`.  See also [path](#path) and [hasadjustments](#hasadjustments).  
 
-#### `hasadjustments()`
-Returns `True` if the file has been edited in Photos, otherwise `False`
+**Note**: will also return None if the edited photo is missing on disk. 
 
-#### `favorite()`
+#### `ismissing`
+Returns `True` if the original image file is missing on disk, otherwise `False`.  This can occur if the file has been uploaded to iCloud but not yet downloaded to the local library or if the file was deleted or imported from a disk that has been unmounted and user hasn't enabled "Copy items to the Photos library" in Photos preferences. **Note**: this status is computed based on data in the Photos library and `ismissing` does not verify if the photo is actually missing. See also [path](#path).
+
+#### `hasadjustments`
+Returns `True` if the picture has been edited, otherwise `False`
+
+#### `external_edit`
+Returns `True` if the picture was edited in an external editor (outside Photos.app), otherwise `False`
+
+#### `favorite`
 Returns `True` if the picture has been marked as a favorite, otherwise `False`
 
-#### `hidden()`
+#### `hidden`
 Returns `True` if the picture has been marked as hidden, otherwise `False`
 
-#### `to_json()`
-Returns a JSON representation of all photo info 
+#### `location`
+Returns latitude and longitude as a tuple of floats (latitude, longitude).  If location is not set, latitude and longitude are returned as `None`
 
-Examples:
+#### `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. 
+
+#### `isphoto`
+Returns True if type is photo/still image, otherwise False
+
+#### `ismovie`
+Returns True if type is movie/video, otherwise False
+
+#### `iscloudasset`
+Returns True if photo is a cloud asset, that is, it is in a library synched to iCloud.  See also [incloud](#incloud)
+
+#### `incloud`
+Returns True if photo is a [cloud asset](#iscloudasset) and is synched to iCloud otherwise False if photo is a cloud asset and not yet synched to iCloud. Returns None if photo is not a cloud asset.
+
+**Note**: Applies to master (original) photo only.  It's possible for the master to be in iCloud but a local edited version is not yet synched to iCloud. `incloud` provides status of only the master photo.  osxphotos does not yet provide a means to determine if the edited version is in iCloud.  If you need this feature, please open an [issue](https://github.com/RhetTbull/osxphotos/issues).
+
+#### `uti`
+Returns Uniform Type Identifier (UTI) for the image, for example: 'public.jpeg' or 'com.apple.quicktime-movie'
+
+#### `burst`
+Returns True if photos is a burst image (e.g. part of a set of burst images), otherwise False.
+See [burst_photos](#burst_photos)
+
+#### `burst_photos`
+If photo is a burst image (see [burst](#burst)), returns a list of PhotoInfo objects for all other photos in the same burst set. If not a burst image, returns empty list.
+
+Example below gets list of all photos that are bursts, selects one of of them and prints out the names of the other images in the burst set.  PhotosDB.photos() will only return the photos in the burst set that the user [selected](https://support.apple.com/guide/photos/view-photo-bursts-phtde06a275d/mac) using "Make a Selection..." in Photos or the key image Photos selected if the user has not yet made a selection.  This is similar to how Photos displays and counts burst photos.  Using `burst_photos` you can access the other images in the burst set to export them, etc. 
 
 ```python
-# assumes photosdb is a PhotosDB object (see above)
-photos=photosdb.photos()
-for p in photos:
-    print(
-        p.uuid(),
-        p.filename(),
-        p.original_filename(),
-        p.date(),
-        p.description(),
-        p.name(),
-        p.keywords(),
-        p.albums(),
-        p.persons(),
-        p.path(),
-        p.ismissing(),
-        p.hasadjustments(),
-    )
+>>> import osxphotos
+>>> photosdb = osxphotos.PhotosDB("/Users/smith/Pictures/Photos Library.photoslibrary")
+>>> bursts = [p for p in photosdb.photos() if p.burst]
+>>> burst_photo = bursts[5]
+>>> len(burst_photo.burst_photos)
+4
+>>> burst_photo.original_filename
+'IMG_9851.JPG'
+>>> for photo in burst_photo.burst_photos:
+...     print(photo.original_filename)
+...
+IMG_9853.JPG
+IMG_9852.JPG
+IMG_9854.JPG
+IMG_9855.JPG
 ```
 
-## History
+#### `live_photo`
+Returns True if photo is an Apple live photo (ie. it has an associated "live" video component), otherwise returns False.  See [path_live_photo](#path_live_photo).
 
-This project started as a command line utility, `photosmeta`, available at [photosmeta](https://github.com/RhetTbull/photosmeta) This module converts the photosmeta Photos library query functionality into a module.  
+#### `path_live_photo`
+Returns the path to the live video component of a [live photo](#live_photo). If photo is not a live photo, returns None.
 
+**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.
+
+#### `json()`
+Returns a JSON representation of all photo info 
+
+#### `export(dest, *filename, edited=False, live_photo=False, overwrite=False, increment=True, sidecar_json=False, sidecar_xmp=False, use_photos_export=False, timeout=120,)`
+
+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
+- edited: boolean; if True (default=False), will export the edited version of the photo (or raise exception if no edited version)
+- overwrite: boolean; if True (default=False), will overwrite files if they alreay exist
+- live_photo: boolean; if True (default=False), will also export the associted .mov for live photos; exported live photo will be named filename.mov
+- increment: boolean; if True (default=True), will increment file name until a non-existent name is found
+- sidecar_json: (boolean, default = False); if True will also write a json sidecar with IPTC data in format readable by exiftool; sidecar filename will be dest/filename.json where filename is the stem of the photo name
+- sidecar_xmp: (boolean, default = False); if True will also write a XMP sidecar with IPTC data; sidecar filename will be dest/filename.xmp where filename is the stem of the photo name
+- use_photos_export: boolean; (default=False), if True will attempt to export photo via applescript interaction with Photos; useful for forcing download of missing photos.  This only works if the Photos library being used is the default library (last opened by Photos) as applescript will directly interact with whichever library Photos is currently using.
+- timeout: (int, default=120) timeout in seconds used with use_photos_export
+
+The json sidecar file can be used by exiftool to apply the metadata from the json file to the image.  For example: 
+
+```python
+import osxphotos
+
+photosdb = osxphotos.PhotosDB("/Users/smith/Pictures/Photos Library.photoslibrary")
+photos = photosdb.photos()
+photos[0].export("/tmp","photo_name.jpg",sidecar_json=True)
+```
+
+Then
+
+`exiftool -j=photo_name.json photo_name.jpg`
+
+If overwrite=False and increment=False, export will fail if destination file already exists
+
+Returns the full path to the exported file
+
+**Implementation Note**: Because the usual python file copy methods don't preserve all the metadata available on MacOS, export uses /usr/bin/ditto to do the copy for export. ditto preserves most metadata such as extended attributes, permissions, ACLs, etc.
+
+### Utility Functions
+
+The following functions are located in osxphotos.utils
+
+#### ```get_system_library_path()```
+
+**MacOS 10.15 Only** Returns path to System Photo Library as string.  On MacOS version < 10.15, returns None.
+
+#### ```get_last_library_path()```
+
+Returns path to last opened Photo Library as string.  
+
+#### ```list_photo_libraries()```
+
+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.
+
+#### ```create_path_by_date(dest, dt)```
+Creates a path in dest folder in form dest/YYYY/MM/DD/
+dest: valid path as str
+dt: datetime.timetuple() object
+Checks to see if path exists, if it does, do nothing and return path. If path does not exist, creates it and returns path.  Useful for exporting photos to a date-based folder structure.
+
+### Examples
+
+```python
+import osxphotos
+
+def main():
+
+    photosdb = osxphotos.PhotosDB("/Users/smith/Pictures/Photos Library.photoslibrary")
+    print(f"db file = {photosdb.db_path}")
+    print(f"db version = {photosdb.db_version}")
+
+    print(photosdb.keywords)
+    print(photosdb.persons)
+    print(photosdb.albums)
+
+    print(photosdb.keywords_as_dict)
+    print(photosdb.persons_as_dict)
+    print(photosdb.albums_as_dict)
+
+    # find all photos with Keyword = Kids and containing person Katie
+    photos = photosdb.photos(keywords=["Kids"], persons=["Katie"])
+    print(f"found {len(photos)} photos")
+
+    # find all photos that include Katie but do not contain the keyword wedding
+    photos = [
+        p
+        for p in photosdb.photos(persons=["Katie"])
+        if p not in photosdb.photos(keywords=["wedding"])
+    ]
+
+    # get all photos in the database
+    photos = photosdb.photos()
+    for p in photos:
+        print(
+            p.uuid,
+            p.filename,
+            p.date,
+            p.description,
+            p.title,
+            p.keywords,
+            p.albums,
+            p.persons,
+            p.path,
+            p.ismissing,
+            p.hasadjustments,
+        )
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## Related Projects
+
+[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.
+
+## Contributing
+
+Contributing is easy!  if you find bugs or want to suggest additional features/changes, please open an [issue](https://github.com/rhettbull/osxphotos/issues/).
+
+I'll gladly consider pull requests for bug fixes or feature implementations.  
+
+If you have an interesting example that shows usage of this module, submit an issue or pull request and i'll include it or link to it.
+
+Testing against "real world" Photos libraries would be especially helpful.  If you discover issues in testing against your Photos libraries, please open an issue.  I've done extensive testing against my own Photos library but that's a since data point and I'm certain there are issues lurking in various edge cases I haven't discovered yet.
 
 ## Implementation Notes
 
-This module is very kludgy.  It works by creating a copy of the sqlite3 database that Photos uses to store data about the Photos library. The class PhotosDB then queries this database to extract information about the photos such as persons (faces identified in the photos), albums, keywords, etc.  
+This module works by creating a copy of the sqlite3 database that photos uses to store data about the photos library. the class photosdb then queries this database to extract information about the photos such as persons (faces identified in the photos), albums, keywords, etc.  If your library is large, the database can be hundreds of MB in size and the copy then read can take many 10s of seconds to complete.  Once copied, the entire database is processed and an in-memory data structure is created meaning all subsequent accesses of the PhotosDB object occur much more quickly. 
 
-If Apple changes the database format this will likely break.  
+If apple changes the database format this will likely break.
 
-The sqlite3 database used by Photos uses write ahead logging that is updated asynchronously in the background by a Photos helper service.  Sometimes the update takes a long time meaning the latest changes made in Photos (e.g. add a keyword) will not show up in the database for sometime.  I know of no way around this.
+Apple does provide a framework ([PhotoKit](https://developer.apple.com/documentation/photokit?language=objc)) for querying the user's Photos library and I attempted to create the funcationality in this module using this framework but unfortunately PhotoKit does not provide access to much of the needed metadata (such as Faces/Persons).  While copying the sqlite file is a bit kludgy, it allows osxphotos to provide access to all available metadata.
 
 ## Dependencies
 - [PyObjC](https://pythonhosted.org/pyobjc/)
 - [PyYAML](https://pypi.org/project/PyYAML/)
 - [Click](https://pypi.org/project/click/)
+- [Mako](https://www.makotemplates.org/)
 
 ## Acknowledgements
-This code was inspired by photo-export by Patrick Fältström see: (https://github.com/patrikhson/photo-export) Copyright (c) 2015 Patrik Fältström paf@frobbit.se
+This project was originally inspired by [photo-export](https://github.com/patrikhson/photo-export) by Patrick Fältström,  Copyright (c) 2015 Patrik Fältström paf@frobbit.se
+
+I use [py-applescript](https://github.com/rdhyee/py-applescript) by "Raymond Yee / rdhyee" to interact with Photos. Rather than import this module, I included the entire module (which is published as public domain code) in a private module to prevent ambiguity with other applescript modules on PyPi. py-applescript uses a native bridge via PyObjC and is very fast compared to the other osascript based modules.
 
-To interact with the Photos app, I use [py-applescript]( https://github.com/rdhyee/py-applescript) by "Raymond Yee / rdhyee".  Rather than import this module, I included the entire module
-(which is published as public domain code) in a private module to prevent ambiguity with
-other applescript modules on PyPi.  py-applescript uses a native bridge via PyObjC and
-is very fast compared to the other osascript based modules.

examples/examples.py

@@ -1,18 +1,24 @@
 import osxphotos
+import os.path
 
 
 def main():
-    photosdb = osxphotos.PhotosDB()
-    print(f"db file = {photosdb.get_db_path()}")
-    print(f"db version = {photosdb.get_db_version()}")
+    db = osxphotos.utils.get_system_library_path()
+    if db is None:
+        # Note: get_system_library_path only works on MacOS 10.15+
+        db = os.path.expanduser("~/Pictures/Photos Library.photoslibrary")
 
-    print(photosdb.keywords())
-    print(photosdb.persons())
-    print(photosdb.albums())
+    photosdb = osxphotos.PhotosDB(db)
+    print(f"db file = {photosdb.db_path}")
+    print(f"db version = {photosdb.db_version}")
 
-    print(photosdb.keywords_as_dict())
-    print(photosdb.persons_as_dict())
-    print(photosdb.albums_as_dict())
+    print(photosdb.keywords)
+    print(photosdb.persons)
+    print(photosdb.albums)
+
+    print(photosdb.keywords_as_dict)
+    print(photosdb.persons_as_dict)
+    print(photosdb.albums_as_dict)
 
     # find all photos with Keyword = Kids and containing person Katie
     photos = photosdb.photos(keywords=["Kids"], persons=["Katie"])
@@ -29,17 +35,17 @@ def main():
     photos = photosdb.photos()
     for p in photos:
         print(
-            p.uuid(),
-            p.filename(),
-            p.date(),
-            p.description(),
-            p.name(),
-            p.keywords(),
-            p.albums(),
-            p.persons(),
-            p.path(),
-            p.ismissing(),
-            p.hasadjustments(),
+            p.uuid,
+            p.filename,
+            p.date,
+            p.description,
+            p.title,
+            p.keywords,
+            p.albums,
+            p.persons,
+            p.path,
+            p.ismissing,
+            p.hasadjustments,
         )
 
 

examples/export.py

@@ -0,0 +1,29 @@
+""" Export all photos to ~/Desktop/export
+    If file has been edited, export the edited version, 
+    otherwise, export the original version """
+
+import os.path
+
+import osxphotos
+
+
+def main():
+    db = os.path.expanduser("~/Pictures/Photos Library.photoslibrary")
+    photosdb = osxphotos.PhotosDB(db)
+    photos = photosdb.photos()
+
+    export_path = os.path.expanduser("~/Desktop/export")
+
+    for p in photos:
+        if not p.ismissing:
+            if p.hasadjustments:
+                exported = p.export(export_path, edited=True)
+            else:
+                exported = p.export(export_path)
+            print(f"Exported {p.filename} to {exported}")
+        else:
+            print(f"Skipping missing photo: {p.filename}")
+
+
+if __name__ == "__main__":
+    main()

examples/photos_repl.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3 -i
+
+# Open an interactive REPL with photosdb and photos defined
+# as osxphotos.PhotosDB() and PhotosDB.photos respectively
+# useful for debugging or exploring the Photos database
+
+# If you run this using python from command line, do so with -i flag:
+# python3 -i examples/photos_repl.py
+
+import sys
+import time
+
+# click needed since this uses a couple of functions from CLI (__main__.py)
+import click
+
+import osxphotos
+from osxphotos.__main__ import get_photos_db, _list_libraries
+
+
+def main():
+    db = None
+
+    if len(sys.argv) > 1:
+        db = sys.argv[1]
+    else:
+        db = get_photos_db()
+
+    if db:
+        print("loading database")
+        tic = time.perf_counter()
+        photosdb = osxphotos.PhotosDB(dbfile=db)
+        toc = time.perf_counter()
+        print(f"done: took {toc-tic} seconds")
+        return photosdb
+    else:
+        _list_libraries()
+        sys.exit()
+
+
+if __name__ == "__main__":
+    print(f"osxphotos version: {osxphotos._version.__version__}")
+    photosdb = main()
+    print(f"database version: {photosdb.db_version}")
+    print("getting photos")
+    tic = time.perf_counter()
+    photos = photosdb.photos(images=True, movies=True)
+    toc = time.perf_counter()
+    print(f"found {len(photos)} photos in {toc-tic} seconds")

osxphotos/_applescript.py

@@ -1,207 +0,0 @@
-""" applescript -- Easy-to-use Python wrapper for NSAppleScript """
-"""
-    This code is from py-applescript, a public domain package available at:
-    https://github.com/rdhyee/py-applescript
-
-    I've included the whole thing here for simplicity as there is more than one
-    applescript packge on PyPi so there's ambiguity as to which one "import applescript"
-    would use if user had installed another library. 
-    
-    This package is used instead of the others because it uses a native PyObjC 
-    bridge and is thus much faster than others which use osascript.
-
-"""
-
-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

osxphotos/_applescript/__init__.py

@@ -0,0 +1,162 @@
+""" 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
+

osxphotos/_applescript/aecodecs.py

@@ -0,0 +1,269 @@
+""" 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'."""
+

osxphotos/_constants.py

@@ -0,0 +1,36 @@
+"""
+Constants used by osxphotos 
+"""
+
+import os.path
+
+# which Photos library database versions have been tested
+# Photos 2.0 (10.12.6) == 2622
+# Photos 3.0 (10.13.6) == 3301
+# Photos 4.0 (10.14.5) == 4016
+# Photos 4.0 (10.14.6) == 4025
+# Photos 5.0 (10.15.0) == 6000
+# TODO: Should this also use compatibleBackToVersion from LiGlobals?
+_TESTED_DB_VERSIONS = ["6000", "4025", "4016", "3301", "2622"]
+
+# versions later than this have a different database structure
+_PHOTOS_5_VERSION = "6000"
+
+# which major version operating systems have been tested
+_TESTED_OS_VERSIONS = ["12", "13", "14", "15"]
+
+# Photos 5 has persons who are empty string if unidentified face
+_UNKNOWN_PERSON = "_UNKNOWN_"
+
+_EXIF_TOOL_URL = "https://exiftool.org/"
+
+# Where are shared iCloud photos located?
+_PHOTOS_5_SHARED_PHOTO_PATH = "resources/cloudsharing/data"
+
+# What type of file? Based on ZGENERICASSET.ZKIND in Photos 5 database
+_PHOTO_TYPE = 0
+_MOVIE_TYPE = 1
+
+# Name of XMP template file
+_TEMPLATE_DIR = os.path.join(os.path.dirname(__file__), "templates")
+_XMP_TEMPLATE_NAME = "xmp_sidecar.mako"

osxphotos/_version.py

@@ -0,0 +1,3 @@
+""" version info """
+
+__version__ = "0.22.10"

osxphotos/aecodecs.py

@@ -1,294 +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'."""

osxphotos/cmd_line.py

@@ -1,354 +0,0 @@
-import csv
-import json
-import sys
-
-import click
-import yaml
-
-import osxphotos
-
-# TODO: add query for description, name (contains text)
-# TODO: add "--any" to search any field (e.g. keyword, description, name contains "wedding") (add case insensitive option)
-
-
-class CLI_Obj:
-    def __init__(self, db=None, json=False):
-        self.photosdb = osxphotos.PhotosDB(dbfile=db)
-        self.json = json
-
-
-CTX_SETTINGS = dict(help_option_names=["-h", "--help"])
-
-
-@click.group(context_settings=CTX_SETTINGS)
-@click.option(
-    "--db",
-    required=False,
-    metavar="<Photos database path>",
-    default=None,
-    help="Specify database file",
-)
-@click.option(
-    "--json",
-    required=False,
-    is_flag=True,
-    default=False,
-    help="Print output in JSON format",
-)
-@click.pass_context
-def cli(ctx, db, json):
-    ctx.obj = CLI_Obj(db=db, json=json)
-
-
-@cli.command()
-@click.pass_obj
-def keywords(cli_obj):
-    """ print out keywords found in the Photos library"""
-    keywords = {"keywords": cli_obj.photosdb.keywords_as_dict()}
-    if cli_obj.json:
-        print(json.dumps(keywords))
-    else:
-        print(yaml.dump(keywords, sort_keys=False))
-
-
-@cli.command()
-@click.pass_obj
-def albums(cli_obj):
-    """ print out albums found in the Photos library """
-    albums = {"albums": cli_obj.photosdb.albums_as_dict()}
-    if cli_obj.json:
-        print(json.dumps(albums))
-    else:
-        print(yaml.dump(albums, sort_keys=False))
-
-
-@cli.command()
-@click.pass_obj
-def persons(cli_obj):
-    """ print out persons (faces) found in the Photos library """
-    persons = {"persons": cli_obj.photosdb.persons_as_dict()}
-    if cli_obj.json:
-        print(json.dumps(persons))
-    else:
-        print(yaml.dump(persons, sort_keys=False))
-
-
-@cli.command()
-@click.pass_obj
-def info(cli_obj):
-    """ print out descriptive info of the Photos library database """
-    pdb = cli_obj.photosdb
-    info = {}
-    info["database_path"] = pdb.get_db_path()
-    info["database_version"] = pdb.get_db_version()
-
-    photos = pdb.photos()
-    info["photo_count"] = len(photos)
-
-    keywords = pdb.keywords_as_dict()
-    info["keywords_count"] = len(keywords)
-    info["keywords"] = keywords
-
-    albums = pdb.albums_as_dict()
-    info["albums_count"] = len(albums)
-    info["albums"] = albums
-
-    persons = pdb.persons_as_dict()
-    # handle empty person names (added by Photos 5.0+ when face detected but not identified)
-    noperson = "UNKNOWN"
-    if "" in persons:
-        if noperson in persons:
-            persons[noperson].append(persons[""])
-        else:
-            persons[noperson] = persons[""]
-        persons.pop("", None)
-
-    info["persons_count"] = len(persons)
-    info["persons"] = persons
-
-    if cli_obj.json:
-        print(json.dumps(info))
-    else:
-        print(yaml.dump(info, sort_keys=False))
-
-
-@cli.command()
-@click.pass_obj
-def dump(cli_obj):
-    """ print list of all photos & associated info from the Photos library """
-    pdb = cli_obj.photosdb
-    photos = pdb.photos()
-    print_photo_info(photos, cli_obj.json)
-
-
-@cli.command()
-@click.option("--keyword", default=None, multiple=True, help="search for keyword(s)")
-@click.option("--person", default=None, multiple=True, help="search for person(s)")
-@click.option("--album", default=None, multiple=True, help="search for album(s)")
-@click.option("--uuid", default=None, multiple=True, help="search for UUID(s)")
-@click.option(
-    "--name", default=None, multiple=True, help="search for TEXT in name of photo"
-)
-@click.option("--no-name", is_flag=True, help="search for photos with no name")
-@click.option(
-    "--description",
-    default=None,
-    multiple=True,
-    help="search for TEXT in description of photo",
-)
-@click.option("--no-description", is_flag=True, help="search for photos with no description")
-@click.option(
-    "-i",
-    "--ignore-case",
-    is_flag=True,
-    help="case insensitive search for name or description. Does not apply to keyword, person, or album",
-)
-@click.option("--favorite", is_flag=True, help="search for photos marked favorite")
-@click.option(
-    "--not-favorite", is_flag=True, help="search for photos not marked favorite"
-)
-@click.option("--hidden", is_flag=True, help="search for photos marked hidden")
-@click.option("--not-hidden", is_flag=True, help="search for photos not marked hidden")
-@click.option("--missing", is_flag=True, help="search for photos missing from disk")
-@click.option(
-    "--not-missing",
-    is_flag=True,
-    help="search for photos present on disk (e.g. not missing)",
-)
-@click.option(
-    "--json",
-    required=False,
-    is_flag=True,
-    default=False,
-    help="Print output in JSON format",
-)
-@click.pass_obj
-@click.pass_context
-def query(
-    ctx,
-    cli_obj,
-    keyword,
-    person,
-    album,
-    uuid,
-    name,
-    no_name,
-    description,
-    no_description,
-    ignore_case,
-    json,
-    favorite,
-    not_favorite,
-    hidden,
-    not_hidden,
-    missing,
-    not_missing,
-):
-    """ Query the Photos database using 1 or more search options\n
-        If more than one option is provided, they are treated as "AND" 
-        (e.g. search for photos matching all options)
-    """
-
-    # if no query terms, show help and return
-    if (
-        not keyword
-        and not person
-        and not album
-        and not uuid
-        and not name
-        and not no_name
-        and not description
-        and not no_description
-        and not favorite
-        and not not_favorite
-        and not hidden
-        and not not_hidden
-        and not missing
-        and not not_missing
-    ):
-        print(cli.commands["query"].get_help(ctx))
-        return
-    elif favorite and not_favorite:
-        # can't search for both favorite and notfavorite
-        print(cli.commands["query"].get_help(ctx))
-        return
-    elif hidden and not_hidden:
-        # can't search for both hidden and nothidden
-        print(cli.commands["query"].get_help(ctx))
-        return
-    elif missing and not_missing:
-        # can't search for both missing and notmissing
-        print(cli.commands["query"].get_help(ctx))
-        return
-    elif name and no_name:
-        # can't search for both name and no_name
-        print(cli.commands["query"].get_help(ctx))
-        return 
-    elif description and no_description:
-        # can't search for both description and no_description
-        print(cli.commands["query"].get_help(ctx))
-        return 
-    else:
-        photos = cli_obj.photosdb.photos(
-            keywords=keyword, persons=person, albums=album, uuid=uuid
-        )
-
-        if name:
-            # search name field for text
-            # if more than one, find photos with all name values in in name
-            if ignore_case:
-                # case-insensitive
-                for n in name:
-                    n = n.lower()
-                    photos = [p for p in photos if p.name() and n in p.name().lower()]
-            else:
-                for n in name:
-                    photos = [p for p in photos if p.name() and n in p.name()]
-        elif no_name:
-            photos = [p for p in photos if not p.name()]
-
-        if description:
-            # search description field for text
-            # if more than one, find photos with all name values in in description
-            if ignore_case:
-                # case-insensitive
-                for d in description:
-                    d = d.lower()
-                    photos = [
-                        p
-                        for p in photos
-                        if p.description() and d in p.description().lower()
-                    ]
-            else:
-                for d in description:
-                    photos = [
-                        p for p in photos if p.description() and d in p.description()
-                    ]
-        elif no_description:
-            photos = [p for p in photos if not p.description()]
-
-        if favorite:
-            photos = [p for p in photos if p.favorite()]
-        elif not_favorite:
-            photos = [p for p in photos if not p.favorite()]
-
-        if hidden:
-            photos = [p for p in photos if p.hidden()]
-        elif not_hidden:
-            photos = [p for p in photos if not p.hidden()]
-
-        if missing:
-            photos = [p for p in photos if p.ismissing()]
-        elif not_missing:
-            photos = [p for p in photos if not p.ismissing()]
-
-        print_photo_info(photos, cli_obj.json or json)
-
-
-@cli.command()
-@click.argument("topic", default=None, required=False, nargs=1)
-@click.pass_context
-def help(ctx, topic, **kw):
-    """ print help; for help on commands: help <command> """
-    if topic is None:
-        print(ctx.parent.get_help())
-    else:
-        print(cli.commands[topic].get_help(ctx))
-
-
-def print_photo_info(photos, json=False):
-    if json:
-        dump = []
-        for p in photos:
-            dump.append(p.to_json())
-        print(f"[{', '.join(dump)}]")
-    else:
-        # dump as CSV
-        csv_writer = csv.writer(
-            sys.stdout, delimiter=",", quotechar='"', quoting=csv.QUOTE_MINIMAL
-        )
-        dump = []
-        # add headers
-        dump.append(
-            [
-                "uuid",
-                "filename",
-                "original_filename",
-                "date",
-                "description",
-                "name",
-                "keywords",
-                "albums",
-                "persons",
-                "path",
-                "ismissing",
-                "hasadjustments",
-                "favorite",
-                "hidden",
-            ]
-        )
-        for p in photos:
-            dump.append(
-                [
-                    p.uuid(),
-                    p.filename(),
-                    p.original_filename(),
-                    str(p.date()),
-                    p.description(),
-                    p.name(),
-                    ", ".join(p.keywords()),
-                    ", ".join(p.albums()),
-                    ", ".join(p.persons()),
-                    p.path(),
-                    p.ismissing(),
-                    p.hasadjustments(),
-                    p.favorite(),
-                    p.hidden(),
-                ]
-            )
-        for row in dump:
-            csv_writer.writerow(row)
-
-
-if __name__ == "__main__":
-    cli()

osxphotos/photoinfo.py

@@ -0,0 +1,866 @@
+"""
+PhotoInfo class
+Represents a single photo in the Photos library and provides access to the photo's attributes
+PhotosDB.photos() returns a list of PhotoInfo objects
+"""
+
+import glob
+import json
+import logging
+import os.path
+import pathlib
+import re
+import subprocess
+import sys
+from datetime import timedelta, timezone
+from pprint import pformat
+
+import yaml
+from mako.template import Template
+
+from ._constants import (
+    _MOVIE_TYPE,
+    _PHOTO_TYPE,
+    _PHOTOS_5_SHARED_PHOTO_PATH,
+    _PHOTOS_5_VERSION,
+    _TEMPLATE_DIR,
+    _XMP_TEMPLATE_NAME,
+)
+from .utils import (
+    _copy_file,
+    _export_photo_uuid_applescript,
+    _get_resource_loc,
+    dd_to_dms_str,
+)
+
+
+class PhotoInfo:
+    """
+    Info about a specific photo, contains all the details about the photo
+    including keywords, persons, albums, uuid, path, etc.
+    """
+
+    def __init__(self, db=None, uuid=None, info=None):
+        self._uuid = uuid
+        self._info = info
+        self._db = db
+
+    @property
+    def filename(self):
+        """ filename of the picture """
+        return self._info["filename"]
+
+    @property
+    def original_filename(self):
+        """ original filename of the picture 
+            Photos 5 mangles filenames upon import """
+        return self._info["originalFilename"]
+
+    @property
+    def date(self):
+        """ image creation date as timezone aware datetime object """
+        imagedate = self._info["imageDate"]
+        seconds = self._info["imageTimeZoneOffsetSeconds"] or 0
+        delta = timedelta(seconds=seconds)
+        tz = timezone(delta)
+        imagedate_utc = imagedate.astimezone(tz=tz)
+        return imagedate_utc
+
+    @property
+    def date_modified(self):
+        """ image modification date as timezone aware datetime object
+            or None if no modification date set """
+        imagedate = self._info["lastmodifieddate"]
+        if imagedate:
+            seconds = self._info["imageTimeZoneOffsetSeconds"] or 0
+            delta = timedelta(seconds=seconds)
+            tz = timezone(delta)
+            imagedate_utc = imagedate.astimezone(tz=tz)
+            return imagedate_utc
+        else:
+            return None
+
+    @property
+    def tzoffset(self):
+        """ timezone offset from UTC in seconds """
+        return self._info["imageTimeZoneOffsetSeconds"]
+
+    @property
+    def path(self):
+        """ absolute path on disk of the original picture """
+
+        photopath = None
+        if self._info["isMissing"] == 1:
+            return photopath  # path would be meaningless until downloaded
+
+        if self._db._db_version < _PHOTOS_5_VERSION:
+            vol = self._info["volume"]
+            if vol is not None:
+                photopath = os.path.join("/Volumes", vol, self._info["imagePath"])
+            else:
+                photopath = os.path.join(
+                    self._db._masters_path, self._info["imagePath"]
+                )
+            return photopath
+            # TODO: Is there a way to use applescript or PhotoKit to force the download in this
+
+        if self._info["shared"]:
+            # shared photo
+            photopath = os.path.join(
+                self._db._library_path,
+                _PHOTOS_5_SHARED_PHOTO_PATH,
+                self._info["directory"],
+                self._info["filename"],
+            )
+            return photopath
+
+        # if self._info["masterFingerprint"]:
+        # if masterFingerprint is not null, path appears to be valid
+        if self._info["directory"].startswith("/"):
+            photopath = os.path.join(self._info["directory"], self._info["filename"])
+        else:
+            photopath = os.path.join(
+                self._db._masters_path, self._info["directory"], self._info["filename"]
+            )
+        return photopath
+
+        # if all else fails, photopath = None
+        # photopath = None
+        # logging.debug(
+        #     f"WARNING: photopath None, masterFingerprint null, not shared {pformat(self._info)}"
+        # )
+        # return photopath
+
+    @property
+    def path_edited(self):
+        """ absolute path on disk of the edited picture """
+        """ None if photo has not been edited """
+
+        # TODO: break this code into a _path_edited_4 and _path_edited_5
+        # version to simplify the big if/then; same for path_live_photo
+
+        photopath = None
+
+        if self._db._db_version < _PHOTOS_5_VERSION:
+            if self._info["hasAdjustments"]:
+                edit_id = self._info["edit_resource_id"]
+                if edit_id is not None:
+                    library = self._db._library_path
+                    folder_id, file_id = _get_resource_loc(edit_id)
+                    # todo: is this always true or do we need to search file file_id under folder_id
+                    # figure out what kind it is and build filename
+                    filename = None
+                    if self._info["type"] == _PHOTO_TYPE:
+                        # it's a photo
+                        filename = f"fullsizeoutput_{file_id}.jpeg"
+                    elif self._info["type"] == _MOVIE_TYPE:
+                        # it's a movie
+                        filename = f"fullsizeoutput_{file_id}.mov"
+                    else:
+                        # don't know what it is!
+                        logging.debug(f"WARNING: unknown type {self._info['type']}")
+                        return None
+
+                    # photopath appears to usually be in "00" subfolder but
+                    # could be elsewhere--I haven't figured out this logic yet
+                    # first see if it's in 00
+                    photopath = os.path.join(
+                        library,
+                        "resources",
+                        "media",
+                        "version",
+                        folder_id,
+                        "00",
+                        filename,
+                    )
+
+                    if not os.path.isfile(photopath):
+                        rootdir = os.path.join(
+                            library, "resources", "media", "version", folder_id
+                        )
+
+                        for dirname, _, filelist in os.walk(rootdir):
+                            if filename in filelist:
+                                photopath = os.path.join(dirname, filename)
+                                break
+
+                    # check again to see if we found a valid file
+                    if not os.path.isfile(photopath):
+                        logging.debug(
+                            f"MISSING PATH: edited file for UUID {self._uuid} should be at {photopath} but does not appear to exist"
+                        )
+                        photopath = None
+                else:
+                    logging.debug(
+                        f"{self.uuid} hasAdjustments but edit_resource_id is None"
+                    )
+                    photopath = None
+            else:
+                photopath = None
+
+            # if self._info["isMissing"] == 1:
+            #     photopath = None  # path would be meaningless until downloaded
+        else:
+            # in Photos 5.0 / Catalina / MacOS 10.15:
+            # edited photos appear to always be converted to .jpeg and stored in
+            # library_name/resources/renders/X/UUID_1_201_a.jpeg
+            # where X = first letter of UUID
+            # and UUID = UUID of image
+            # this seems to be true even for photos not copied to Photos library and
+            # where original format was not jpg/jpeg
+            # if more than one edit, previous edit is stored as UUID_p.jpeg
+
+            if self._info["hasAdjustments"]:
+                library = self._db._library_path
+                directory = self._uuid[0]  # first char of uuid
+                filename = None
+                if self._info["type"] == _PHOTO_TYPE:
+                    # it's a photo
+                    filename = f"{self._uuid}_1_201_a.jpeg"
+                elif self._info["type"] == _MOVIE_TYPE:
+                    # it's a movie
+                    filename = f"{self._uuid}_2_0_a.mov"
+                else:
+                    # don't know what it is!
+                    logging.debug(f"WARNING: unknown type {self._info['type']}")
+                    return None
+
+                photopath = os.path.join(
+                    library, "resources", "renders", directory, filename
+                )
+
+                if not os.path.isfile(photopath):
+                    logging.debug(
+                        f"edited file for UUID {self._uuid} should be at {photopath} but does not appear to exist"
+                    )
+                    photopath = None
+            else:
+                photopath = None
+
+            # TODO: might be possible for original/master to be missing but edit to still be there
+            # if self._info["isMissing"] == 1:
+            #     photopath = None  # path would be meaningless until downloaded
+
+            logging.debug(photopath)
+
+        return photopath
+
+    @property
+    def description(self):
+        """ long / extended description of picture """
+        return self._info["extendedDescription"]
+
+    @property
+    def persons(self):
+        """ list of persons in picture """
+        return self._info["persons"]
+
+    @property
+    def albums(self):
+        """ list of albums picture is contained in """
+        albums = []
+        for album in self._info["albums"]:
+            albums.append(self._db._dbalbum_details[album]["title"])
+        return albums
+
+    @property
+    def keywords(self):
+        """ list of keywords for picture """
+        return self._info["keywords"]
+
+    @property
+    def title(self):
+        """ name / title of picture """
+        return self._info["name"]
+
+    @property
+    def uuid(self):
+        """ UUID of picture """
+        return self._uuid
+
+    @property
+    def ismissing(self):
+        """ returns true if photo is missing from disk (which means it's not been downloaded from iCloud) 
+        NOTE:   the photos.db database uses an asynchrounous write-ahead log so changes in Photos
+                do not immediately get written to disk. In particular, I've noticed that downloading 
+                an image from the cloud does not force the database to be updated until something else
+                e.g. an edit, keyword, etc. occurs forcing a database synch
+                The exact process / timing is a mystery to be but be aware that if some photos were recently
+                downloaded from cloud to local storate their status in the database might still show
+                isMissing = 1
+        """
+        return True if self._info["isMissing"] == 1 else False
+
+    @property
+    def hasadjustments(self):
+        """ True if picture has adjustments / edits """
+        return True if self._info["hasAdjustments"] == 1 else False
+
+    @property
+    def external_edit(self):
+        """ Returns True if picture was edited outside of Photos using external editor """
+        return (
+            True
+            if self._info["adjustmentFormatID"] == "com.apple.Photos.externalEdit"
+            else False
+        )
+
+    @property
+    def favorite(self):
+        """ True if picture is marked as favorite """
+        return True if self._info["favorite"] == 1 else False
+
+    @property
+    def hidden(self):
+        """ True if picture is hidden """
+        return True if self._info["hidden"] == 1 else False
+
+    @property
+    def location(self):
+        """ returns (latitude, longitude) as float in degrees or None """
+        return (self._latitude, self._longitude)
+
+    @property
+    def shared(self):
+        """ returns True if photos is in a shared iCloud album otherwise false
+            Only valid on Photos 5; returns None on older versions """
+        if self._db._db_version >= _PHOTOS_5_VERSION:
+            return self._info["shared"]
+        else:
+            return None
+
+    @property
+    def uti(self):
+        """ Returns Uniform Type Identifier (UTI) for the image
+            for example: public.jpeg or com.apple.quicktime-movie
+        """
+        return self._info["UTI"]
+
+    @property
+    def ismovie(self):
+        """ Returns True if file is a movie, otherwise False
+        """
+        return True if self._info["type"] == _MOVIE_TYPE else False
+
+    @property
+    def isphoto(self):
+        """ Returns True if file is an image, otherwise False
+        """
+        return True if self._info["type"] == _PHOTO_TYPE else False
+
+    @property
+    def incloud(self):
+        """ Returns True if photo is cloud asset and is synched to cloud
+                    False if photo is cloud asset and not yet synched to cloud
+                    None if photo is not cloud asset
+        """
+        return self._info["incloud"]
+
+    @property
+    def iscloudasset(self):
+        """ Returns True if photo is a cloud asset (in an iCloud library),
+            otherwise False 
+        """
+        if self._db._db_version < _PHOTOS_5_VERSION:
+            return (
+                True
+                if self._info["cloudLibraryState"] is not None
+                and self._info["cloudLibraryState"] != 0
+                else False
+            )
+        else:
+            return True if self._info["cloudAssetGUID"] is not None else False
+
+    @property
+    def burst(self):
+        """ Returns True if photo is part of a Burst photo set, otherwise False """
+        return self._info["burst"]
+
+    @property
+    def burst_photos(self):
+        """ If photo is a burst photo, returns list of PhotoInfo objects 
+            that are part of the same burst photo set; otherwise returns empty list.
+            self is not included in the returned list """
+        if self._info["burst"]:
+            burst_uuid = self._info["burstUUID"]
+            burst_photos = [
+                PhotoInfo(db=self._db, uuid=u, info=self._db._dbphotos[u])
+                for u in self._db._dbphotos_burst[burst_uuid]
+                if u != self._uuid
+            ]
+            return burst_photos
+        else:
+            return []
+
+    @property
+    def live_photo(self):
+        """ Returns True if photo is a live photo, otherwise False """
+        return self._info["live_photo"]
+
+    @property
+    def path_live_photo(self):
+        """ Returns path to the associated video file for a live photo
+            If photo is not a live photo, returns None
+            If photo is missing, returns None """
+
+        photopath = None
+        if self._db._db_version < _PHOTOS_5_VERSION:
+            if self.live_photo and not self.ismissing:
+                live_model_id = self._info["live_model_id"]
+                if live_model_id == None:
+                    logging.debug(f"missing live_model_id: {self._uuid}")
+                    photopath = None
+                else:
+                    folder_id, file_id = _get_resource_loc(live_model_id)
+                    library_path = self._db.library_path
+                    photopath = os.path.join(
+                        library_path,
+                        "resources",
+                        "media",
+                        "master",
+                        folder_id,
+                        "00",
+                        f"jpegvideocomplement_{file_id}.mov",
+                    )
+                    if not os.path.isfile(photopath):
+                        # In testing, I've seen occasional missing movie for live photo
+                        # These appear to be valid -- e.g. live component hasn't been downloaded from iCloud
+                        # photos 4 has "isOnDisk" column we could check
+                        # or could do the actual check with "isfile"
+                        # TODO: should this be a warning or debug?
+                        logging.debug(
+                            f"MISSING PATH: live photo path for UUID {self._uuid} should be at {photopath} but does not appear to exist"
+                        )
+                        photopath = None
+            else:
+                photopath = None
+        else:
+            # Photos 5
+            if self.live_photo and not self.ismissing:
+                filename = pathlib.Path(self.path)
+                photopath = filename.parent.joinpath(f"{filename.stem}_3.mov")
+                photopath = str(photopath)
+                if not os.path.isfile(photopath):
+                    # In testing, I've seen occasional missing movie for live photo
+                    # these appear to be valid -- e.g. video component not yet downloaded from iCloud
+                    # TODO: should this be a warning or debug?
+                    logging.debug(
+                        f"MISSING PATH: live photo path for UUID {self._uuid} should be at {photopath} but does not appear to exist"
+                    )
+                    photopath = None
+            else:
+                photopath = None
+
+        return photopath
+
+    def export(
+        self,
+        dest,
+        *filename,
+        edited=False,
+        live_photo=False,
+        overwrite=False,
+        increment=True,
+        sidecar_json=False,
+        sidecar_xmp=False,
+        use_photos_export=False,
+        timeout=120,
+    ):
+        """ export photo 
+            dest: must be valid destination path (or exception raised) 
+            filename: (optional): name of picture; if not provided, will use current filename 
+            edited: (boolean, default=False); if True will export the edited version of the photo 
+                    (or raise exception if no edited version) 
+            live_photo: (boolean, default=False); if True, will also export the associted .mov for live photos
+            overwrite: (boolean, default=False); if True will overwrite files if they alreay exist 
+            increment: (boolean, default=True); if True, will increment file name until a non-existant name is found 
+                       if overwrite=False and increment=False, export will fail if destination file already exists 
+            sidecar_json: (boolean, default = False); if True will also write a json sidecar with IPTC data in format readable by exiftool
+                      sidecar filename will be dest/filename.json 
+            sidecar_xmp: (boolean, default = False); if True will also write a XMP sidecar with IPTC data 
+                      sidecar filename will be dest/filename.xmp 
+            use_photos_export: (boolean, default=False); if True will attempt to export photo via applescript interaction with Photos
+            timeout: (int, default=120) timeout in seconds used with use_photos_export
+            returns the full path to the exported file """
+
+        # TODO: add this docs:
+        #  ( for jpeg in *.jpeg; do exiftool -v -json=$jpeg.json $jpeg; done )
+
+        # check arguments and get destination path and filename (if provided)
+        if filename and len(filename) > 2:
+            raise TypeError(
+                "Too many positional arguments.  Should be at most two: destination, filename."
+            )
+        else:
+            # verify destination is a valid path
+            if dest is None:
+                raise ValueError("Destination must not be None")
+            elif not os.path.isdir(dest):
+                raise FileNotFoundError("Invalid path passed to export")
+
+            if filename and len(filename) == 1:
+                # second arg is filename of picture
+                filename = filename[0]
+            else:
+                # no filename provided so use the default
+                # if edited file requested, use filename but add _edited
+                # need to use file extension from edited file as Photos saves a jpeg once edited
+                if edited and not use_photos_export:
+                    # verify we have a valid path_edited and use that to get filename
+                    if not self.path_edited:
+                        raise FileNotFoundError(
+                            "edited=True but path_edited is none; hasadjustments: "
+                            f" {self.hasadjustments}"
+                        )
+                    edited_name = pathlib.Path(self.path_edited).name
+                    edited_suffix = pathlib.Path(edited_name).suffix
+                    filename = (
+                        pathlib.Path(self.filename).stem + "_edited" + edited_suffix
+                    )
+                else:
+                    filename = self.filename
+
+        # check destination path
+        dest = pathlib.Path(dest)
+        filename = pathlib.Path(filename)
+        dest = dest / filename
+
+        # check to see if file exists and if so, add (1), (2), etc until we find one that works
+        # Photos checks the stem and adds (1), (2), etc which avoids collision with sidecars
+        # e.g. exporting sidecar for file1.png and file1.jpeg
+        # if file1.png exists and exporting file1.jpeg,
+        # dest will be file1 (1).jpeg even though file1.jpeg doesn't exist to prevent sidecar collision
+        if increment and not overwrite:
+            count = 1
+            glob_str = str(dest.parent / f"{dest.stem}*")
+            dest_files = glob.glob(glob_str)
+            dest_files = [pathlib.Path(f).stem for f in dest_files]
+            dest_new = dest.stem
+            while dest_new in dest_files:
+                dest_new = f"{dest.stem} ({count})"
+                count += 1
+            dest = dest.parent / f"{dest_new}{dest.suffix}"
+
+        # if overwrite==False and #increment==False, export should fail if file exists
+        if dest.exists() and not overwrite and not increment:
+            raise FileExistsError(
+                f"destination exists ({dest}); overwrite={overwrite}, increment={increment}"
+            )
+
+        if not use_photos_export:
+            # find the source file on disk and export
+            # get path to source file and verify it's not None and is valid file
+            # TODO: how to handle ismissing or not hasadjustments and edited=True cases?
+            if edited:
+                if not self.hasadjustments:
+                    logging.warning(
+                        "Attempting to export edited photo but hasadjustments=False"
+                    )
+
+                if self.path_edited is not None:
+                    src = self.path_edited
+                else:
+                    raise FileNotFoundError(
+                        f"edited=True but path_edited is none; hasadjustments: {self.hasadjustments}"
+                    )
+            else:
+                if self.ismissing:
+                    logging.warning(
+                        f"Attempting to export photo with ismissing=True: path = {self.path}"
+                    )
+
+                if self.path is None:
+                    logging.warning(
+                        f"Attempting to export photo but path is None: ismissing = {self.ismissing}"
+                    )
+                    raise FileNotFoundError("Cannot export photo if path is None")
+                else:
+                    src = self.path
+
+            if not os.path.isfile(src):
+                raise FileNotFoundError(f"{src} does not appear to exist")
+
+            logging.debug(
+                f"exporting {src} to {dest}, overwrite={overwrite}, increment={increment}, dest exists: {dest.exists()}"
+            )
+
+            # copy the file, _copy_file uses ditto to preserve Mac extended attributes
+            _copy_file(src, dest)
+
+            # copy live photo associated .mov if requested
+            if live_photo and self.live_photo:
+                live_name = dest.parent / f"{dest.stem}.mov"
+                src_live = self.path_live_photo
+
+                if src_live is not None:
+                    logging.debug(
+                        f"Exporting live photo video of {filename} as {live_name.name}"
+                    )
+                    _copy_file(src_live, str(live_name))
+                else:
+                    logging.warning(f"Skipping missing live movie for {filename}")
+        else:
+            # use_photo_export
+            exported = None
+            # export live_photo .mov file?
+            live_photo = True if live_photo and self.live_photo else False
+            if edited:
+                # exported edited version and not original
+                if filename:
+                    # use filename stem provided
+                    filestem = dest.stem
+                else:
+                    # didn't get passed a filename, add _edited
+                    filestem = f"{dest.stem}_edited"
+                    exported = _export_photo_uuid_applescript(
+                        self.uuid,
+                        dest.parent,
+                        filestem=filestem,
+                        original=False,
+                        edited=True,
+                        live_photo=live_photo,
+                        timeout=timeout,
+                    )
+            else:
+                # export original version and not edited
+                filestem = dest.stem
+                exported = _export_photo_uuid_applescript(
+                    self.uuid,
+                    dest.parent,
+                    filestem=filestem,
+                    original=True,
+                    edited=False,
+                    live_photo=live_photo,
+                    timeout=timeout,
+                )
+
+            if exported is None:
+                logging.warning(f"Error exporting photo {self.uuid} to {dest}")
+
+        if sidecar_json:
+            logging.debug("writing exiftool_json_sidecar")
+            sidecar_filename = dest.parent / pathlib.Path(f"{dest.stem}.json")
+            sidecar_str = self._exiftool_json_sidecar()
+            try:
+                self._write_sidecar(sidecar_filename, sidecar_str)
+            except Exception as e:
+                logging.warning(f"Error writing json sidecar to {sidecar_filename}")
+                raise e
+
+        if sidecar_xmp:
+            logging.debug("writing xmp_sidecar")
+            sidecar_filename = dest.parent / pathlib.Path(f"{dest.stem}.xmp")
+            sidecar_str = self._xmp_sidecar()
+            try:
+                self._write_sidecar(sidecar_filename, sidecar_str)
+            except Exception as e:
+                logging.warning(f"Error writing xmp sidecar to {sidecar_filename}")
+                raise e
+
+        return str(dest)
+
+    def _exiftool_json_sidecar(self):
+        """ return json string of EXIF details in exiftool sidecar format
+            Does not include all the EXIF fields as those are likely already in the image
+            Exports the following:
+                FileName
+                ImageDescription
+                Description
+                Title
+                TagsList
+                Keywords
+                Subject
+                PersonInImage
+                GPSLatitude, GPSLongitude
+                GPSPosition
+                GPSLatitudeRef, GPSLongitudeRef
+                DateTimeOriginal
+                OffsetTimeOriginal
+                ModifyDate """
+
+        exif = {}
+        exif["_CreatedBy"] = "osxphotos, https://github.com/RhetTbull/osxphotos"
+        exif["FileName"] = self.filename
+
+        if self.description:
+            exif["ImageDescription"] = self.description
+            exif["Description"] = self.description
+
+        if self.title:
+            exif["Title"] = self.title
+
+        if self.keywords:
+            exif["TagsList"] = exif["Keywords"] = list(self.keywords)
+            # Photos puts both keywords and persons in Subject when using "Export IPTC as XMP"
+            exif["Subject"] = list(self.keywords)
+
+        if self.persons:
+            exif["PersonInImage"] = self.persons
+            # Photos puts both keywords and persons in Subject when using "Export IPTC as XMP"
+            if "Subject" in exif:
+                exif["Subject"].extend(self.persons)
+            else:
+                exif["Subject"] = self.persons
+
+        # if self.favorite():
+        #     exif["Rating"] = 5
+
+        (lat, lon) = self.location
+        if lat is not None and lon is not None:
+            lat_str, lon_str = dd_to_dms_str(lat, lon)
+            exif["GPSLatitude"] = lat_str
+            exif["GPSLongitude"] = lon_str
+            exif["GPSPosition"] = f"{lat_str}, {lon_str}"
+            lat_ref = "North" if lat >= 0 else "South"
+            lon_ref = "East" if lon >= 0 else "West"
+            exif["GPSLatitudeRef"] = lat_ref
+            exif["GPSLongitudeRef"] = lon_ref
+
+        # process date/time and timezone offset
+        date = self.date
+        # exiftool expects format to "2015:01:18 12:00:00"
+        datetimeoriginal = date.strftime("%Y:%m:%d %H:%M:%S")
+        offsettime = date.strftime("%z")
+        # find timezone offset in format "-04:00"
+        offset = re.findall(r"([+-]?)([\d]{2})([\d]{2})", offsettime)
+        offset = offset[0]  # findall returns list of tuples
+        offsettime = f"{offset[0]}{offset[1]}:{offset[2]}"
+        exif["DateTimeOriginal"] = datetimeoriginal
+        exif["OffsetTimeOriginal"] = offsettime
+
+        if self.date_modified is not None:
+            exif["ModifyDate"] = self.date_modified.strftime("%Y:%m:%d %H:%M:%S")
+
+        json_str = json.dumps([exif])
+        return json_str
+
+    def _xmp_sidecar(self):
+        """ returns string for XMP sidecar """
+        # TODO: add additional fields to XMP file?
+
+        xmp_template = Template(
+            filename=os.path.join(_TEMPLATE_DIR, _XMP_TEMPLATE_NAME)
+        )
+        xmp_str = xmp_template.render(photo=self)
+        # remove extra lines that mako inserts from template
+        xmp_str = "\n".join(
+            [line for line in xmp_str.split("\n") if line.strip() != ""]
+        )
+        return xmp_str
+
+    def _write_sidecar(self, filename, sidecar_str):
+        """ write sidecar_str to filename
+            used for exporting sidecar info """
+        if not filename and not sidecar_str:
+            raise (
+                ValueError(
+                    f"filename {filename} and sidecar_str {sidecar_str} must not be None"
+                )
+            )
+
+        # TODO: catch exception?
+        f = open(filename, "w")
+        f.write(sidecar_str)
+        f.close()
+
+    @property
+    def _longitude(self):
+        """ Returns longitude, in degrees """
+        return self._info["longitude"]
+
+    @property
+    def _latitude(self):
+        """ Returns latitude, in degrees """
+        return self._info["latitude"]
+
+    def __repr__(self):
+        return f"osxphotos.{self.__class__.__name__}(db={self._db}, uuid='{self._uuid}', info={self._info})"
+
+    def __str__(self):
+        """ string representation of PhotoInfo object """
+
+        date_iso = self.date.isoformat()
+        date_modified_iso = (
+            self.date_modified.isoformat() if self.date_modified else None
+        )
+
+        info = {
+            "uuid": self.uuid,
+            "filename": self.filename,
+            "original_filename": self.original_filename,
+            "date": date_iso,
+            "description": self.description,
+            "title": self.title,
+            "keywords": self.keywords,
+            "albums": self.albums,
+            "persons": self.persons,
+            "path": self.path,
+            "ismissing": self.ismissing,
+            "hasadjustments": self.hasadjustments,
+            "external_edit": self.external_edit,
+            "favorite": self.favorite,
+            "hidden": self.hidden,
+            "latitude": self._latitude,
+            "longitude": self._longitude,
+            "path_edited": self.path_edited,
+            "shared": self.shared,
+            "isphoto": self.isphoto,
+            "ismovie": self.ismovie,
+            "uti": self.uti,
+            "burst": self.burst,
+            "live_photo": self.live_photo,
+            "path_live_photo": self.path_live_photo,
+            "iscloudasset": self.iscloudasset,
+            "incloud": self.incloud,
+            "date_modified": date_modified_iso,
+        }
+        return yaml.dump(info, sort_keys=False)
+
+    def json(self):
+        """ return JSON representation """
+
+        date_modified_iso = (
+            self.date_modified.isoformat() if self.date_modified else None
+        )
+
+        pic = {
+            "uuid": self.uuid,
+            "filename": self.filename,
+            "original_filename": self.original_filename,
+            "date": self.date.isoformat(),
+            "description": self.description,
+            "title": self.title,
+            "keywords": self.keywords,
+            "albums": self.albums,
+            "persons": self.persons,
+            "path": self.path,
+            "ismissing": self.ismissing,
+            "hasadjustments": self.hasadjustments,
+            "external_edit": self.external_edit,
+            "favorite": self.favorite,
+            "hidden": self.hidden,
+            "latitude": self._latitude,
+            "longitude": self._longitude,
+            "path_edited": self.path_edited,
+            "shared": self.shared,
+            "isphoto": self.isphoto,
+            "ismovie": self.ismovie,
+            "uti": self.uti,
+            "burst": self.burst,
+            "live_photo": self.live_photo,
+            "path_live_photo": self.path_live_photo,
+            "iscloudasset": self.iscloudasset,
+            "incloud": self.incloud,
+            "date_modified": date_modified_iso,
+        }
+        return json.dumps(pic)
+
+    # compare two PhotoInfo objects for equality
+    def __eq__(self, other):
+        if isinstance(other, self.__class__):
+            return self.__dict__ == other.__dict__
+
+        return False
+
+    def __ne__(self, other):
+        return not self.__eq__(other)

osxphotos/templates/xmp_sidecar.mako

@@ -0,0 +1,99 @@
+<!-- Created with osxphotos https://github.com/RhetTbull/osxphotos -->
+
+<%def name="dc_description(desc)">
+    % if desc is None:
+        <dc:description></dc:description>
+    % else:
+        <dc:description>${desc}</dc:description>
+    % endif
+</%def>
+
+<%def name="dc_title(title)">
+    % if title is None:
+        <dc:title></dc:title>
+    % else:
+        <dc:title>${title}</dc:title>
+    % endif
+</%def>
+
+<%def name="dc_subject(subject)">
+    % if subject:
+        <!-- keywords and persons listed in <dc:subject> as Photos does -->
+        <dc:subject>
+            <rdf:Seq>
+            % for subj in subject:
+                <rdf:li>${subj}</rdf:li>
+            % endfor
+            </rdf:Seq>
+        </dc:subject>
+    % endif
+</%def>
+
+<%def name="dc_datecreated(date)">
+    % if date is not None:
+        <photoshop:DateCreated>${date.isoformat()}</photoshop:DateCreated>
+    % endif
+</%def>
+
+<%def name="iptc_personinimage(persons)">
+    % if persons:
+        <Iptc4xmpExt:PersonInImage>
+            <rdf:Bag>
+                % for person in persons:
+                    <rdf:li>${person}</rdf:li>
+                % endfor
+            </rdf:Bag>
+        </Iptc4xmpExt:PersonInImage>
+    % endif 
+</%def>
+
+<%def name="dk_tagslist(keywords)">
+    % if keywords:
+        <digiKam:TagsList>
+            <rdf:Seq>
+            % for keyword in keywords:
+                <rdf:li>${keyword}</rdf:li>
+            % endfor
+            </rdf:Seq>
+        </digiKam:TagsList>
+    % endif
+</%def>
+
+<%def name="adobe_createdate(date)">
+    % if date is not None:
+        <xmp:CreateDate>${date.strftime("%Y-%m-%dT%H:%M:%S")}</xmp:CreateDate>
+    % endif
+</%def>
+
+<%def name="adobe_modifydate(date)">
+    % if date is not None:
+        <xmp:ModifyDate>${date.strftime("%Y-%m-%dT%H:%M:%S")}</xmp:ModifyDate>
+    % endif
+</%def>
+
+<x:xmpmeta xmlns:x="adobe:ns:meta/" x:xmptk="XMP Core 5.4.0">
+    <!-- mirrors Photos 5 "Export IPTC as XMP" option -->
+    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+        <rdf:Description rdf:about="" 
+            xmlns:dc="http://purl.org/dc/elements/1.1/" 
+            xmlns:photoshop="http://ns.adobe.com/photoshop/1.0/">
+            ${dc_description(photo.description)}
+            ${dc_title(photo.title)}
+            ${dc_subject(photo.keywords + photo.persons)}
+            ${dc_datecreated(photo.date)}
+        </rdf:Description>
+        <rdf:Description rdf:about='' 
+            xmlns:Iptc4xmpExt='http://iptc.org/std/Iptc4xmpExt/2008-02-29/'>
+            ${iptc_personinimage(photo.persons)}
+        </rdf:Description>
+        <rdf:Description rdf:about='' 
+            xmlns:digiKam='http://www.digikam.org/ns/1.0/'>
+            ${dk_tagslist(photo.keywords)}
+        </rdf:Description>
+        <rdf:Description rdf:about='' 
+            xmlns:xmp='http://ns.adobe.com/xap/1.0/'>
+            ${adobe_createdate(photo.date)}
+            ${adobe_modifydate(photo.date)}
+        </rdf:Description>
+   </rdf:RDF>
+</x:xmpmeta>

osxphotos/utils.py

@@ -0,0 +1,450 @@
+import glob
+import logging
+import os.path
+import platform
+import sqlite3
+import subprocess
+import tempfile
+import urllib.parse
+import pathlib
+from plistlib import load as plistload
+
+import CoreFoundation
+import objc
+from Foundation import *
+
+from osxphotos._applescript import AppleScript
+
+_DEBUG = False
+
+
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s - %(levelname)s - %(filename)s - %(lineno)d - %(message)s",
+)
+
+if not _DEBUG:
+    logging.disable(logging.DEBUG)
+
+
+def _get_logger():
+    """Used only for testing
+    
+    Returns:
+        logging.Logger object -- logging.Logger object for osxphotos
+    """
+    return logging.Logger(__name__)
+
+
+def _set_debug(debug):
+    """ Enable or disable debug logging """
+    global _DEBUG
+    _DEBUG = debug
+    if debug:
+        logging.disable(logging.NOTSET)
+    else:
+        logging.disable(logging.DEBUG)
+
+
+def _debug():
+    """ returns True if debugging turned on (via _set_debug), otherwise, false """
+    return _DEBUG
+
+
+def _get_os_version():
+    # returns tuple containing OS version
+    # e.g. 10.13.6 = (10, 13, 6)
+    version = platform.mac_ver()[0].split(".")
+    if len(version) == 2:
+        (ver, major) = version
+        minor = "0"
+    elif len(version) == 3:
+        (ver, major, minor) = version
+    else:
+        raise (
+            ValueError(
+                f"Could not parse version string: {platform.mac_ver()} {version}"
+            )
+        )
+    return (ver, major, minor)
+
+
+def _check_file_exists(filename):
+    """ 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 """
+    """ and live photos for version <= Photos 4.0 """
+    # determine folder where Photos stores edited version
+    # edited images are stored in:
+    # Photos Library.photoslibrary/resources/media/version/XX/00/fullsizeoutput_Y.jpeg
+    # where XX and Y are computed based on RKModelResources.modelId
+
+    # file_id (Y in above example) is hex representation of model_id without leading 0x
+    file_id = hex_id = hex(model_id)[2:]
+
+    # folder_id (XX) in above example if first two chars of model_id converted to hex
+    # and left padded with zeros if < 4 digits
+    folder_id = hex_id.zfill(4)[0:2]
+
+    return folder_id, file_id
+
+
+def _dd_to_dms(dd):
+    """ 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
+    dd = abs(dd)
+    min_, sec_ = divmod(dd * 3600, 60)
+    deg_, min_ = divmod(min_, 60)
+    if negative:
+        if deg_ > 0:
+            deg_ = deg_ * -1
+        elif min_ > 0:
+            min_ = min_ * -1
+        else:
+            sec_ = sec_ * -1
+
+    return int(deg_), int(min_), sec_
+
+
+def _copy_file(src, dest):
+    """ Copies a file from src path to dest path 
+        src: source path as string 
+        dest: destination path as string
+        Uses ditto to perform copy; will silently overwrite dest if it exists
+        Raises exception if copy fails or either path is None """
+
+    if src is None or dest is None:
+        raise ValueError("src and dest must not be None", src, dest)
+
+    if not os.path.isfile(src):
+        raise ValueError("src file does not appear to exist", src)
+
+    # if error on copy, subprocess will raise CalledProcessError
+    try:
+        subprocess.run(
+            ["/usr/bin/ditto", src, dest], check=True, stderr=subprocess.PIPE
+        )
+    except subprocess.CalledProcessError as e:
+        logging.critical(
+            f"ditto returned error: {e.returncode} {e.stderr.decode(sys.getfilesystemencoding()).rstrip()}"
+        )
+        raise e
+
+
+def 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 """
+    # TODO: add this to readme
+
+    lat_deg, lat_min, lat_sec = _dd_to_dms(lat)
+    lon_deg, lon_min, lon_sec = _dd_to_dms(lon)
+
+    lat_hemisphere = "N"
+    if any([lat_deg < 0, lat_min < 0, lat_sec < 0]):
+        lat_hemisphere = "S"
+
+    lon_hemisphere = "E"
+    if any([lon_deg < 0, lon_min < 0, lon_sec < 0]):
+        lon_hemisphere = "W"
+
+    lat_str = (
+        f"{abs(lat_deg)} deg {abs(lat_min)}' {abs(lat_sec):.2f}\" {lat_hemisphere}"
+    )
+    lon_str = (
+        f"{abs(lon_deg)} deg {abs(lon_min)}' {abs(lon_sec):.2f}\" {lon_hemisphere}"
+    )
+
+    return lat_str, lon_str
+
+
+def get_system_library_path():
+    """ 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()
+    if int(major) < 15:
+        logging.debug(
+            f"get_system_library_path not implemented for MacOS < 10.15: you have {major}"
+        )
+        return None
+
+    plist_file = pathlib.Path(
+        str(pathlib.Path.home())
+        + "/Library/Containers/com.apple.photolibraryd/Data/Library/Preferences/com.apple.photolibraryd.plist"
+    )
+    if plist_file.is_file():
+        with open(plist_file, "rb") as fp:
+            pl = plistload(fp)
+    else:
+        logging.warning(f"could not find plist file: {str(plist_file)}")
+        return None
+
+    photospath = pl["SystemLibraryPath"]
+
+    if photospath is not None:
+        return photospath
+    else:
+        logging.warning("Could not get path to Photos database")
+        return None
+
+
+def get_last_library_path():
+    """ 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"
+    )
+    if plist_file.is_file():
+        with open(plist_file, "rb") as fp:
+            pl = plistload(fp)
+    else:
+        logging.debug(f"could not find plist file: {str(plist_file)}")
+        return None
+
+    # get the IPXDefaultLibraryURLBookmark from com.apple.Photos.plist
+    # this is a serialized CFData object
+    photosurlref = pl["IPXDefaultLibraryURLBookmark"]
+
+    if photosurlref is not None:
+        # use CFURLCreateByResolvingBookmarkData to de-serialize bookmark data into a CFURLRef
+        photosurl = CoreFoundation.CFURLCreateByResolvingBookmarkData(
+            kCFAllocatorDefault, photosurlref, 0, None, None, None, None
+        )
+
+        # the CFURLRef we got is a sruct that python treats as an array
+        # I'd like to pass this to CFURLGetFileSystemRepresentation to get the path but
+        # CFURLGetFileSystemRepresentation barfs when it gets an array from python instead of expected struct
+        # first element is the path string in form:
+        # file:///Users/username/Pictures/Photos%20Library.photoslibrary/
+        photosurlstr = photosurl[0].absoluteString() if photosurl[0] else None
+
+        # now coerce the file URI back into an OS path
+        # surely there must be a better way
+        if photosurlstr is not None:
+            photospath = os.path.normpath(
+                urllib.parse.unquote(urllib.parse.urlparse(photosurlstr).path)
+            )
+        else:
+            logging.warning(
+                "Could not extract photos URL String from IPXDefaultLibraryURLBookmark"
+            )
+            return None
+
+        return photospath
+    else:
+        logging.debug("Could not get path to Photos database")
+        return None
+
+
+def list_photo_libraries():
+    """ 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
+    # On older MacOS versions, mdfind appears to ignore some libraries
+    # glob to find libraries in ~/Pictures then mdfind to find all the others
+    # TODO: make this more robust
+    lib_list = glob.glob(f"{str(Path.home())}/Pictures/*.photoslibrary")
+
+    # On older OS, may not get all libraries so make sure we get the last one
+    last_lib = get_last_library_path()
+    if last_lib:
+        lib_list.append(last_lib)
+
+    output = subprocess.check_output(
+        ["/usr/bin/mdfind", "-onlyin", "/", "-name", ".photoslibrary"]
+    ).splitlines()
+    for lib in output:
+        lib_list.append(lib.decode("utf-8"))
+    lib_list = list(set(lib_list))
+    lib_list.sort()
+    return lib_list
+
+
+def create_path_by_date(dest, dt):
+    """ Creates a path in dest folder in form dest/YYYY/MM/DD/
+        dest: valid path as str
+        dt: datetime.timetuple() object
+        Checks to see if path exists, if it does, do nothing and return path
+        If path does not exist, creates it and returns path"""
+    if not os.path.isdir(dest):
+        raise FileNotFoundError(f"dest {dest} must be valid path")
+    yyyy, mm, dd = dt[0:3]
+    yyyy = str(yyyy).zfill(4)
+    mm = str(mm).zfill(2)
+    dd = str(dd).zfill(2)
+    new_dest = os.path.join(dest, yyyy, mm, dd)
+    if not os.path.isdir(new_dest):
+        os.makedirs(new_dest)
+    return new_dest
+
+
+# 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"
+# 	         activate
+# 	         open POSIX file "{library_path}"
+#             end tell
+#         end openLibrary
+#         """
+#     )
+#     open_scpt.run()
+
+
+def _export_photo_uuid_applescript(
+    uuid,
+    dest,
+    filestem=None,
+    original=True,
+    edited=False,
+    live_photo=False,
+    timeout=120,
+):
+    """ Export photo to dest path using applescript to control Photos
+        If photo is a live photo, exports both the photo and associated .mov file
+        uuid: UUID of photo to export
+        dest: destination path to export to
+        filestem: (string) if provided, exported filename will be named stem.ext 
+                  where ext is extension of the file exported by photos (e.g. .jpeg, .mov, etc)
+                  If not provided, file will be named with whatever name Photos uses
+                  If filestem.ext exists, it wil be overwritten
+        original: (boolean) if True, export original image; default = True
+        edited: (boolean) if True, export edited photo; default = False
+                will produce an error if image does not have edits/adjustments 
+        *Note*: must be called with either edited or original but not both, 
+                will raise error if called with both edited and original = True
+        live_photo: (boolean) if True, export associated .mov live photo; default = False
+        timeout: timeout value in seconds; export will fail if applescript run time exceeds timeout
+        Returns: list of paths to exported file(s) or None if export failed
+        Note: For Live Photos, if edited=True, will export a jpeg but not the movie, even if photo
+              has not been edited. This is due to how Photos Applescript interface works.
+    """
+
+    # setup the applescript to do the export
+    export_scpt = AppleScript(
+        """ 
+		on export_by_uuid(theUUID, thePath, original, edited, theTimeOut)
+			tell application "Photos"
+				activate
+				set thePath to thePath
+				set theItem to media item id theUUID
+				set theFilename to filename of theItem
+				set itemList to {theItem}
+				
+				if original then
+					with timeout of theTimeOut seconds
+						export itemList to POSIX file thePath with using originals
+					end timeout
+				end if
+				
+				if edited then
+					with timeout of theTimeOut seconds
+						export itemList to POSIX file thePath
+					end timeout
+				end if
+				
+				return theFilename
+			end tell
+
+		end export_by_uuid
+		"""
+    )
+
+    dest = pathlib.Path(dest)
+    if not dest.is_dir:
+        raise ValueError(f"dest {dest} must be a directory")
+
+    if not original ^ edited:
+        raise ValueError(f"edited or original must be True but not both")
+
+    tmpdir = tempfile.TemporaryDirectory(prefix="osxphotos_")
+
+    # export original
+    filename = None
+    try:
+        filename = export_scpt.call(
+            "export_by_uuid", uuid, tmpdir.name, original, edited, timeout
+        )
+    except Exception as e:
+        logging.warning("Error exporting uuid %s: %s" % (uuid, str(e)))
+        return None
+
+    if filename is not None:
+        # need to find actual filename as sometimes Photos renames JPG to jpeg on export
+        # may be more than one file exported (e.g. if Live Photo, Photos exports both .jpeg and .mov)
+        # TemporaryDirectory will cleanup on return
+        files = glob.glob(os.path.join(tmpdir.name, "*"))
+        exported_paths = []
+        for fname in files:
+            path = pathlib.Path(fname)
+            if len(files) > 1 and not live_photo and path.suffix.lower() == ".mov":
+                # it's the .mov part of live photo but not requested, so don't export
+                logging.debug(f"Skipping live photo file {path}")
+                continue
+            if filestem:
+                # rename the file based on filestem, keeping original extension
+                dest_new = dest / f"{filestem}{path.suffix}"
+            else:
+                # use the name Photos provided
+                dest_new = dest / path.name
+            logging.debug(f"exporting {path} to dest_new: {dest_new}")
+            _copy_file(str(path), str(dest_new))
+            exported_paths.append(str(dest_new))
+        return exported_paths
+    else:
+        return None
+
+
+def _open_sql_file(dbname):
+    """ 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)
+        c = conn.cursor()
+    except sqlite3.Error as e:
+        sys.exit(f"An error occurred opening sqlite file: {e.args[0]} {dbname}")
+    return (conn, c)
+
+
+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 """
+
+    # first, check to see if lock file exists, if so, assume the file is locked
+    lock_name = f"{dbname}.lock"
+    if os.path.exists(lock_name):
+        logging.debug(f"{dbname} is locked")
+        return True
+
+    # no lock file so try to read from the database to see if it's locked
+    locked = None
+    try:
+        (conn, c) = _open_sql_file(dbname)
+        c.execute("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;")
+        conn.close()
+        logging.debug(f"{dbname} is not locked")
+        locked = False
+    except Exception as e:
+        logging.debug(f"{dbname} is locked")
+        locked = True
+
+    return locked

requirements.txt

@@ -6,117 +6,141 @@ better-exceptions-fork==0.2.1.post6
 certifi==2019.3.9
 Click==7.0
 colorama==0.4.1
+coverage==4.5.4
 importlib-metadata==0.18
 isort==4.3.20
 lazy-object-proxy==1.4.1
+loguru==0.2.5
 mccabe==0.6.1
 more-itertools==7.2.0
+-e git+https://github.com/RhetTbull/osxphotos.git@0271b8ad9daf8b2fb80ce81e894478370e421379#egg=osxphotos
 packaging==19.0
 pluggy==0.12.0
 py==1.8.0
 Pygments==2.4.2
 pylint==2.3.1
-pyobjc==5.2
-pyobjc-core==5.2
-pyobjc-framework-Accounts==5.2
-pyobjc-framework-AddressBook==5.2
-pyobjc-framework-AdSupport==5.2
-pyobjc-framework-AppleScriptKit==5.2
-pyobjc-framework-AppleScriptObjC==5.2
-pyobjc-framework-ApplicationServices==5.2
-pyobjc-framework-Automator==5.2
-pyobjc-framework-AVFoundation==5.2
-pyobjc-framework-AVKit==5.2
-pyobjc-framework-BusinessChat==5.2
-pyobjc-framework-CalendarStore==5.2
-pyobjc-framework-CFNetwork==5.2
-pyobjc-framework-CloudKit==5.2
-pyobjc-framework-Cocoa==5.2
-pyobjc-framework-Collaboration==5.2
-pyobjc-framework-ColorSync==5.2
-pyobjc-framework-Contacts==5.2
-pyobjc-framework-ContactsUI==5.2
-pyobjc-framework-CoreAudio==5.2
-pyobjc-framework-CoreAudioKit==5.2
-pyobjc-framework-CoreBluetooth==5.2
-pyobjc-framework-CoreData==5.2
-pyobjc-framework-CoreLocation==5.2
-pyobjc-framework-CoreMedia==5.2
-pyobjc-framework-CoreMediaIO==5.2
-pyobjc-framework-CoreML==5.2
-pyobjc-framework-CoreServices==5.2
-pyobjc-framework-CoreSpotlight==5.2
-pyobjc-framework-CoreText==5.2
-pyobjc-framework-CoreWLAN==5.2
-pyobjc-framework-CryptoTokenKit==5.2
-pyobjc-framework-DictionaryServices==5.2
-pyobjc-framework-DiscRecording==5.2
-pyobjc-framework-DiscRecordingUI==5.2
-pyobjc-framework-DiskArbitration==5.2
-pyobjc-framework-DVDPlayback==5.2
-pyobjc-framework-EventKit==5.2
-pyobjc-framework-ExceptionHandling==5.2
-pyobjc-framework-ExternalAccessory==5.2
-pyobjc-framework-FinderSync==5.2
-pyobjc-framework-FSEvents==5.2
-pyobjc-framework-GameCenter==5.2
-pyobjc-framework-GameController==5.2
-pyobjc-framework-GameKit==5.2
-pyobjc-framework-GameplayKit==5.2
-pyobjc-framework-ImageCaptureCore==5.2
-pyobjc-framework-IMServicePlugIn==5.2
-pyobjc-framework-InputMethodKit==5.2
-pyobjc-framework-InstallerPlugins==5.2
-pyobjc-framework-InstantMessage==5.2
-pyobjc-framework-Intents==5.2
-pyobjc-framework-IOSurface==5.2
-pyobjc-framework-iTunesLibrary==5.2
-pyobjc-framework-LatentSemanticMapping==5.2
-pyobjc-framework-LaunchServices==5.2
-pyobjc-framework-libdispatch==5.2
-pyobjc-framework-LocalAuthentication==5.2
-pyobjc-framework-MapKit==5.2
-pyobjc-framework-MediaAccessibility==5.2
-pyobjc-framework-MediaLibrary==5.2
-pyobjc-framework-MediaPlayer==5.2
-pyobjc-framework-MediaToolbox==5.2
-pyobjc-framework-ModelIO==5.2
-pyobjc-framework-MultipeerConnectivity==5.2
-pyobjc-framework-NaturalLanguage==5.2
-pyobjc-framework-NetFS==5.2
-pyobjc-framework-Network==5.2
-pyobjc-framework-NetworkExtension==5.2
-pyobjc-framework-NotificationCenter==5.2
-pyobjc-framework-OpenDirectory==5.2
-pyobjc-framework-OSAKit==5.2
-pyobjc-framework-Photos==5.2
-pyobjc-framework-PhotosUI==5.2
-pyobjc-framework-PreferencePanes==5.2
-pyobjc-framework-PubSub==5.2
-pyobjc-framework-QTKit==5.2
-pyobjc-framework-Quartz==5.2
-pyobjc-framework-SafariServices==5.2
-pyobjc-framework-SceneKit==5.2
-pyobjc-framework-ScreenSaver==5.2
-pyobjc-framework-ScriptingBridge==5.2
-pyobjc-framework-SearchKit==5.2
-pyobjc-framework-Security==5.2
-pyobjc-framework-SecurityFoundation==5.2
-pyobjc-framework-SecurityInterface==5.2
-pyobjc-framework-ServiceManagement==5.2
-pyobjc-framework-Social==5.2
-pyobjc-framework-SpriteKit==5.2
-pyobjc-framework-StoreKit==5.2
-pyobjc-framework-SyncServices==5.2
-pyobjc-framework-SystemConfiguration==5.2
-pyobjc-framework-UserNotifications==5.2
-pyobjc-framework-VideoSubscriberAccount==5.2
-pyobjc-framework-VideoToolbox==5.2
-pyobjc-framework-Vision==5.2
-pyobjc-framework-WebKit==5.2
+pyobjc==6.0.1
+pyobjc-core==6.0.1
+pyobjc-framework-Accounts==6.0.1
+pyobjc-framework-AddressBook==6.0.1
+pyobjc-framework-AdSupport==6.0.1
+pyobjc-framework-AppleScriptKit==6.0.1
+pyobjc-framework-AppleScriptObjC==6.0.1
+pyobjc-framework-ApplicationServices==6.0.1
+pyobjc-framework-AuthenticationServices==6.0.1
+pyobjc-framework-Automator==6.0.1
+pyobjc-framework-AVFoundation==6.0.1
+pyobjc-framework-AVKit==6.0.1
+pyobjc-framework-BusinessChat==6.0.1
+pyobjc-framework-CalendarStore==6.0.1
+pyobjc-framework-CFNetwork==6.0.1
+pyobjc-framework-CloudKit==6.0.1
+pyobjc-framework-Cocoa==6.0.1
+pyobjc-framework-Collaboration==6.0.1
+pyobjc-framework-ColorSync==6.0.1
+pyobjc-framework-Contacts==6.0.1
+pyobjc-framework-ContactsUI==6.0.1
+pyobjc-framework-CoreAudio==6.0.1
+pyobjc-framework-CoreAudioKit==6.0.1
+pyobjc-framework-CoreBluetooth==6.0.1
+pyobjc-framework-CoreData==6.0.1
+pyobjc-framework-CoreHaptics==6.0.1
+pyobjc-framework-CoreLocation==6.0.1
+pyobjc-framework-CoreMedia==6.0.1
+pyobjc-framework-CoreMediaIO==6.0.1
+pyobjc-framework-CoreML==6.0.1
+pyobjc-framework-CoreMotion==6.0.1
+pyobjc-framework-CoreServices==6.0.1
+pyobjc-framework-CoreSpotlight==6.0.1
+pyobjc-framework-CoreText==6.0.1
+pyobjc-framework-CoreWLAN==6.0.1
+pyobjc-framework-CryptoTokenKit==6.0.1
+pyobjc-framework-DeviceCheck==6.0.1
+pyobjc-framework-DictionaryServices==6.0.1
+pyobjc-framework-DiscRecording==6.0.1
+pyobjc-framework-DiscRecordingUI==6.0.1
+pyobjc-framework-DiskArbitration==6.0.1
+pyobjc-framework-DVDPlayback==6.0.1
+pyobjc-framework-EventKit==6.0.1
+pyobjc-framework-ExceptionHandling==6.0.1
+pyobjc-framework-ExecutionPolicy==6.0.1
+pyobjc-framework-ExternalAccessory==6.0.1
+pyobjc-framework-FileProvider==6.0.1
+pyobjc-framework-FileProviderUI==6.0.1
+pyobjc-framework-FinderSync==6.0.1
+pyobjc-framework-FSEvents==6.0.1
+pyobjc-framework-GameCenter==6.0.1
+pyobjc-framework-GameController==6.0.1
+pyobjc-framework-GameKit==6.0.1
+pyobjc-framework-GameplayKit==6.0.1
+pyobjc-framework-ImageCaptureCore==6.0.1
+pyobjc-framework-IMServicePlugIn==6.0.1
+pyobjc-framework-InputMethodKit==6.0.1
+pyobjc-framework-InstallerPlugins==6.0.1
+pyobjc-framework-InstantMessage==6.0.1
+pyobjc-framework-Intents==6.0.1
+pyobjc-framework-IOSurface==6.0.1
+pyobjc-framework-iTunesLibrary==6.0.1
+pyobjc-framework-LatentSemanticMapping==6.0.1
+pyobjc-framework-LaunchServices==6.0.1
+pyobjc-framework-libdispatch==6.0.1
+pyobjc-framework-LinkPresentation==6.0.1
+pyobjc-framework-LocalAuthentication==6.0.1
+pyobjc-framework-MapKit==6.0.1
+pyobjc-framework-MediaAccessibility==6.0.1
+pyobjc-framework-MediaLibrary==6.0.1
+pyobjc-framework-MediaPlayer==6.0.1
+pyobjc-framework-MediaToolbox==6.0.1
+pyobjc-framework-MetalKit==6.0.1
+pyobjc-framework-ModelIO==6.0.1
+pyobjc-framework-MultipeerConnectivity==6.0.1
+pyobjc-framework-NaturalLanguage==6.0.1
+pyobjc-framework-NetFS==6.0.1
+pyobjc-framework-Network==6.0.1
+pyobjc-framework-NetworkExtension==6.0.1
+pyobjc-framework-NotificationCenter==6.0.1
+pyobjc-framework-OpenDirectory==6.0.1
+pyobjc-framework-OSAKit==6.0.1
+pyobjc-framework-OSLog==6.0.1
+pyobjc-framework-PencilKit==6.0.1
+pyobjc-framework-Photos==6.0.1
+pyobjc-framework-PhotosUI==6.0.1
+pyobjc-framework-PreferencePanes==6.0.1
+pyobjc-framework-PubSub==6.0.1
+pyobjc-framework-PushKit==6.0.1
+pyobjc-framework-QTKit==6.0.1
+pyobjc-framework-Quartz==6.0.1
+pyobjc-framework-QuickLookThumbnailing==6.0.1
+pyobjc-framework-SafariServices==6.0.1
+pyobjc-framework-SceneKit==6.0.1
+pyobjc-framework-ScreenSaver==6.0.1
+pyobjc-framework-ScriptingBridge==6.0.1
+pyobjc-framework-SearchKit==6.0.1
+pyobjc-framework-Security==6.0.1
+pyobjc-framework-SecurityFoundation==6.0.1
+pyobjc-framework-SecurityInterface==6.0.1
+pyobjc-framework-ServiceManagement==6.0.1
+pyobjc-framework-Social==6.0.1
+pyobjc-framework-SoundAnalysis==6.0.1
+pyobjc-framework-Speech==6.0.1
+pyobjc-framework-SpriteKit==6.0.1
+pyobjc-framework-StoreKit==6.0.1
+pyobjc-framework-SyncServices==6.0.1
+pyobjc-framework-SystemConfiguration==6.0.1
+pyobjc-framework-SystemExtensions==6.0.1
+pyobjc-framework-UserNotifications==6.0.1
+pyobjc-framework-VideoSubscriberAccount==6.0.1
+pyobjc-framework-VideoToolbox==6.0.1
+pyobjc-framework-Vision==6.0.1
+pyobjc-framework-WebKit==6.0.1
 pyparsing==2.4.1.1
+pytest==5.3.1
+pytest-cov==2.8.1
+pytest-sugar==0.9.2
 PyYAML==5.1.2
 six==1.12.0
+termcolor==1.1.0
 wcwidth==0.1.7
 wrapt==1.11.1
 zipp==0.5.2
+Mako==1.1.1

setup.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-# setup.py script for osxphotos 
+# setup.py script for osxphotos
 #
 # Copyright (c) 2019 Rhet Turnbull, rturnbull+git@gmail.com
 # All rights reserved.
@@ -26,19 +26,22 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-# from distutils.core import setup
-from setuptools import setup, find_packages
+import os
+from setuptools import find_packages, setup
 
-# read the contents of README file
-from os import path
-
-this_directory = path.abspath(path.dirname(__file__))
-with open(path.join(this_directory, "README.md"), encoding="utf-8") as f:
+this_directory = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(this_directory, "README.md"), encoding="utf-8") as f:
     long_description = f.read()
 
+about = {}
+with open(
+    os.path.join(this_directory, "osxphotos", "_version.py"), mode="r", encoding="utf-8"
+) as f:
+    exec(f.read(), about)
+
 setup(
     name="osxphotos",
-    version="0.14.4",
+    version=about["__version__"],
     description="Manipulate (read-only) Apple's Photos app library on Mac OS X",
     long_description=long_description,
     long_description_content_type="text/markdown",
@@ -47,7 +50,7 @@ setup(
     url="https://github.com/RhetTbull/",
     project_urls={"GitHub": "https://github.com/RhetTbull/osxphotos"},
     download_url="https://github.com/RhetTbull/osxphotos",
-    packages=find_packages(exclude=["tests","examples"]), 
+    packages=find_packages(exclude=["tests", "examples"]),
     license="License :: OSI Approved :: MIT License",
     classifiers=[
         "Development Status :: 4 - Beta",
@@ -58,8 +61,6 @@ setup(
         "Programming Language :: Python :: 3.6",
         "Topic :: Software Development :: Libraries :: Python Modules",
     ],
-    install_requires=["pyobjc","Click","pyyaml",],
-    entry_points = {
-         'console_scripts' : ['osxphotos=osxphotos.cmd_line:cli'],
-    }
+    install_requires=["pyobjc>=6.0.1", "Click>=7", "PyYAML>=5.1.2", "Mako>=1.1.1"],
+    entry_points={"console_scripts": ["osxphotos=osxphotos.__main__:cli"]},
 )

tests/Empty-Library-4.0-3461.7.150.photoslibrary/database/DataModelVersion.plist

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>DatabaseMinorVersion</key>
+	<integer>1</integer>
+	<key>DatabaseVersion</key>
+	<integer>112</integer>
+	<key>LastOpenMode</key>
+	<integer>2</integer>
+	<key>LibrarySchemaVersion</key>
+	<integer>4025</integer>
+	<key>MetaSchemaVersion</key>
+	<integer>2</integer>
+	<key>createDate</key>
+	<date>2019-12-27T23:19:08Z</date>
+</dict>
+</plist>

tests/Empty-Library-4.0-3461.7.150.photoslibrary/private/com.apple.Photos/appPrivateData.plist

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>Photos</key>
+	<dict>
+		<key>CollapsedSidebarSectionIdentifiers</key>
+		<array/>
+		<key>ExpandedSidebarItemIdentifiers</key>
+		<array>
+			<string>TopLevelAlbums</string>
+			<string>TopLevelSlideshows</string>
+		</array>
+		<key>lastKnownItemCounts</key>
+		<dict>
+			<key>other</key>
+			<integer>0</integer>
+			<key>photos</key>
+			<integer>0</integer>
+			<key>videos</key>
+			<integer>0</integer>
+		</dict>
+	</dict>
+</dict>
+</plist>

tests/Empty-Library-4.0-3461.7.150.photoslibrary/private/com.apple.photoanalysisd/GraphService/PhotoAnalysisServicePreferences.plist

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>PhotoAnalysisGraphLastBackgroundGraphRebuildJobDate</key>
+	<date>2019-12-27T23:19:59Z</date>
+</dict>
+</plist>

tests/Empty-Library-4.0-3461.7.150.photoslibrary/resources/moments/analysismetadata.plist

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>PLLanguageAndLocaleKey</key>
+	<string>en-US:en_US</string>
+	<key>PLLastGeoProviderIdKey</key>
+	<string>7618</string>
+	<key>PLLastLocationInfoFormatVer</key>
+	<integer>12</integer>
+	<key>PLLastRevGeoForcedProviderOutOfDateCheckVersionKey</key>
+	<integer>1</integer>
+</dict>
+</plist>

tests/Empty-Library-4.0-3461.7.150.photoslibrary/resources/moments/historicalmarker.plist

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>LastHistoryRowId</key>
+	<integer>53</integer>
+	<key>LibraryBuildTag</key>
+	<string>F176BAF5-4B7A-4878-83C4-4D4175F299BF</string>
+	<key>LibrarySchemaVersion</key>
+	<integer>4025</integer>
+</dict>
+</plist>

tests/Empty-Library-4.0-3461.7.150.photoslibrary/resources/recovery/Info.plist

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>DatabaseMinorVersion</key>
+	<integer>1</integer>
+	<key>DatabaseVersion</key>
+	<integer>112</integer>
+	<key>HistoricalMarker</key>
+	<dict>
+		<key>LastHistoryRowId</key>
+		<integer>53</integer>
+		<key>LibraryBuildTag</key>
+		<string>F176BAF5-4B7A-4878-83C4-4D4175F299BF</string>
+		<key>LibrarySchemaVersion</key>
+		<integer>4025</integer>
+	</dict>
+	<key>LibrarySchemaVersion</key>
+	<integer>4025</integer>
+	<key>MetaSchemaVersion</key>
+	<integer>2</integer>
+	<key>SnapshotComplete</key>
+	<true/>
+	<key>SnapshotCompletedDate</key>
+	<date>2019-12-27T23:19:08Z</date>
+	<key>SnapshotLastValidated</key>
+	<date>2019-12-27T23:19:08Z</date>
+	<key>SnapshotTables</key>
+	<dict/>
+</dict>
+</plist>

tests/README.md

@@ -17,5 +17,6 @@ Images used from:
 - [Carlos Montesdeoca](https://www.flickr.com/photos/carlosmontesdeocastudio)
 - [Rydale Clothing](https://www.flickr.com/photos/rydaleclothing)
 - [Marco Verch](https://www.flickr.com/photos/30478819@N08/48228222317/)
+- [K M](https://www.flickr.com/photos/153387643@N08/49334338022/)
 
 

tests/Test-10.12.6.photoslibrary/private/com.apple.Photos/appPrivateData.plist

@@ -5,7 +5,7 @@
 	<key>LithiumMessageTracer</key>
 	<dict>
 		<key>LastReportedDate</key>
-		<date>2019-08-24T02:50:48Z</date>
+		<date>2019-12-08T16:44:38Z</date>
 	</dict>
 	<key>PXPeopleScreenUnlocked</key>
 	<true/>

tests/Test-10.12.6.photoslibrary/private/com.apple.photoanalysisd/GraphService/PhotoAnalysisServicePreferences.plist

@@ -3,8 +3,8 @@
 <plist version="1.0">
 <dict>
 	<key>PhotoAnalysisGraphLastBackgroundGraphRebuildJobDate</key>
-	<date>2019-08-24T02:51:33Z</date>
+	<date>2020-01-22T02:10:26Z</date>
 	<key>PhotoAnalysisGraphLastBackgroundMemoryGenerationJobDate</key>
-	<date>2019-08-24T13:19:30Z</date>
+	<date>2020-01-22T02:10:27Z</date>
 </dict>
 </plist>

tests/Test-10.12.6.photoslibrary/resources/moments/analysismetadata.plist

@@ -11,6 +11,6 @@
 	<key>PLLastRevGeoForcedProviderOutOfDateCheckVersionKey</key>
 	<integer>1</integer>
 	<key>PLLastRevGeoVerFileFetchDateKey</key>
-	<date>2019-08-24T02:51:30Z</date>
+	<date>2020-01-19T17:29:28Z</date>
 </dict>
 </plist>

tests/Test-10.12.6.photoslibrary/resources/recovery/Info.plist

@@ -9,7 +9,7 @@
 	<key>HistoricalMarker</key>
 	<dict>
 		<key>LastHistoryRowId</key>
-		<integer>403</integer>
+		<integer>414</integer>
 		<key>LibraryBuildTag</key>
 		<string>E3E46F2A-7168-4973-AB3E-5848F80BFC7D</string>
 		<key>LibrarySchemaVersion</key>

tests/Test-10.14.6-path_edited.photoslibrary/database/DataModelVersion.plist

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>DatabaseMinorVersion</key>
+	<integer>1</integer>
+	<key>DatabaseVersion</key>
+	<integer>112</integer>
+	<key>LastOpenMode</key>
+	<integer>2</integer>
+	<key>LibrarySchemaVersion</key>
+	<integer>4025</integer>
+	<key>MetaSchemaVersion</key>
+	<integer>2</integer>
+	<key>createDate</key>
+	<date>2019-07-27T13:16:43Z</date>
+</dict>
+</plist>

tests/Test-10.14.6-path_edited.photoslibrary/private/com.apple.Photos/appPrivateData.plist

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>Photos</key>
+	<dict>
+		<key>CollapsedSidebarSectionIdentifiers</key>
+		<array/>
+		<key>ExpandedSidebarItemIdentifiers</key>
+		<array>
+			<string>TopLevelAlbums</string>
+			<string>TopLevelSlideshows</string>
+		</array>
+		<key>IPXWorkspaceControllerZoomLevelsKey</key>
+		<dict>
+			<key>kZoomLevelIdentifierAlbums</key>
+			<integer>10</integer>
+			<key>kZoomLevelIdentifierVersions</key>
+			<integer>7</integer>
+		</dict>
+		<key>lastAddToDestination</key>
+		<dict>
+			<key>key</key>
+			<integer>1</integer>
+			<key>lastKnownDisplayName</key>
+			<string>Test Album (1)</string>
+			<key>type</key>
+			<string>album</string>
+			<key>uuid</key>
+			<string>Uq6qsKihRRSjMHTiD+0Azg</string>
+		</dict>
+		<key>lastKnownItemCounts</key>
+		<dict>
+			<key>other</key>
+			<integer>0</integer>
+			<key>photos</key>
+			<integer>6</integer>
+			<key>videos</key>
+			<integer>0</integer>
+		</dict>
+	</dict>
+</dict>
+</plist>

tests/Test-10.14.6-path_edited.photoslibrary/private/com.apple.photoanalysisd/GraphService/PhotoAnalysisServicePreferences.plist

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>PhotoAnalysisGraphLastBackgroundGraphRebuildJobDate</key>
+	<date>2020-01-11T16:41:00Z</date>
+	<key>PhotoAnalysisGraphLastBackgroundMemoryGenerationJobDate</key>
+	<date>2020-01-12T06:02:45Z</date>
+</dict>
+</plist>

tests/Test-10.14.6-path_edited.photoslibrary/private/com.apple.photoanalysisd/VisionService/PersonPromoter

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>ProcessedInQuiescentState</key>
+	<true/>
+	<key>SuggestedMeIdentifier</key>
+	<string></string>
+	<key>Version</key>
+	<integer>3</integer>
+</dict>
+</plist>

tests/Test-10.14.6-path_edited.photoslibrary/private/com.apple.photoanalysisd/VisionService/clustererState.plist

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>PVClustererBringUpState</key>
+	<integer>50</integer>
+</dict>
+</plist>

tests/Test-10.14.6-path_edited.photoslibrary/private/com.apple.photoanalysisd/VisionService/faceWorkerState.plist

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>IncrementalPersonProcessingStage</key>
+	<integer>0</integer>
+	<key>PersonBuilderLastMinimumFaceGroupSizeForCreatingMergeCandidates</key>
+	<integer>15</integer>
+	<key>PersonBuilderMergeCandidatesEnabled</key>
+	<true/>
+</dict>
+</plist>

tests/Test-10.14.6-path_edited.photoslibrary/private/com.apple.photomodel/appPrivateData.plist

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>LithiumMessageTracer</key>
+	<dict>
+		<key>LastReportedDate</key>
+		<date>2020-01-04T18:29:59Z</date>
+	</dict>
+</dict>
+</plist>