+"""
+Constants used by osxphotos
+"""
+
+import os.path
+from datetime import datetime
+from enum import Enum
+
+APP_NAME = "osxphotos"
+
+OSXPHOTOS_URL = "https://github.com/RhetTbull/osxphotos"
+
+# Time delta: add this to Photos times to get unix time
+# Apple Epoch is Jan 1, 2001
+TIME_DELTA = (datetime(2001, 1, 1, 0, 0) - datetime(1970, 1, 1, 0, 0)).total_seconds()
+
+# Unicode format to use for comparing strings
+UNICODE_FORMAT = "NFC"
+
+# 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 or 5001
+_TESTED_DB_VERSIONS = ["6000", "5001", "4025", "4016", "3301", "2622"]
+
+# database model versions (applies to Photos 5, Photos 6)
+# these come from PLModelVersion key in binary plist in Z_METADATA.Z_PLIST
+# Photos 5 (10.15.1) == 13537
+# Photos 5 (10.15.4, 10.15.5, 10.15.6) == 13703
+# Photos 6 (10.16.0 Beta) == 14104
+_TEST_MODEL_VERSIONS = ["13537", "13703", "14104"]
+
+_PHOTOS_2_VERSION = "2622"
+
+# only version 3 - 4 have RKVersion.selfPortrait
+_PHOTOS_3_VERSION = "3301"
+
+# versions 5.0 and later have a different database structure
+_PHOTOS_4_VERSION = "4025" # latest Mojove version on 10.14.6
+_PHOTOS_5_VERSION = "5000" # I've seen both 5001 and 6000. 6000 is most common on Catalina and up but there are some version 5001 database in the wild
+
+# Ranges for model version by Photos version
+_PHOTOS_5_MODEL_VERSION = [13000, 13999]
+_PHOTOS_6_MODEL_VERSION = [14000, 14999]
+_PHOTOS_7_MODEL_VERSION = [
+ 15000,
+ 15999,
+] # Monterey developer preview is 15134, 12.1 is 15331
+
+# some table names differ between Photos 5 and Photos 6
+_DB_TABLE_NAMES = {
+ 5: {
+ "ASSET": "ZGENERICASSET",
+ "KEYWORD_JOIN": "Z_1KEYWORDS.Z_37KEYWORDS",
+ "ALBUM_JOIN": "Z_26ASSETS.Z_34ASSETS",
+ "ALBUM_SORT_ORDER": "Z_26ASSETS.Z_FOK_34ASSETS",
+ "IMPORT_FOK": "ZGENERICASSET.Z_FOK_IMPORTSESSION",
+ "DEPTH_STATE": "ZGENERICASSET.ZDEPTHSTATES",
+ "UTI_ORIGINAL": "ZINTERNALRESOURCE.ZUNIFORMTYPEIDENTIFIER",
+ "ASSET_ALBUM_JOIN": "Z_26ASSETS.Z_26ALBUMS",
+ "ASSET_ALBUM_TABLE": "Z_26ASSETS",
+ "HDR_TYPE": "ZCUSTOMRENDEREDVALUE",
+ },
+ 6: {
+ "ASSET": "ZASSET",
+ "KEYWORD_JOIN": "Z_1KEYWORDS.Z_36KEYWORDS",
+ "ALBUM_JOIN": "Z_26ASSETS.Z_3ASSETS",
+ "ALBUM_SORT_ORDER": "Z_26ASSETS.Z_FOK_3ASSETS",
+ "IMPORT_FOK": "null",
+ "DEPTH_STATE": "ZASSET.ZDEPTHTYPE",
+ "UTI_ORIGINAL": "ZINTERNALRESOURCE.ZUNIFORMTYPEIDENTIFIER",
+ "ASSET_ALBUM_JOIN": "Z_26ASSETS.Z_26ALBUMS",
+ "ASSET_ALBUM_TABLE": "Z_26ASSETS",
+ "HDR_TYPE": "ZCUSTOMRENDEREDVALUE",
+ },
+ 7: {
+ "ASSET": "ZASSET",
+ "KEYWORD_JOIN": "Z_1KEYWORDS.Z_38KEYWORDS",
+ "ALBUM_JOIN": "Z_27ASSETS.Z_3ASSETS",
+ "ALBUM_SORT_ORDER": "Z_27ASSETS.Z_FOK_3ASSETS",
+ "IMPORT_FOK": "null",
+ "DEPTH_STATE": "ZASSET.ZDEPTHTYPE",
+ "UTI_ORIGINAL": "ZINTERNALRESOURCE.ZCOMPACTUTI",
+ "ASSET_ALBUM_JOIN": "Z_27ASSETS.Z_27ALBUMS",
+ "ASSET_ALBUM_TABLE": "Z_27ASSETS",
+ "HDR_TYPE": "ZHDRTYPE",
+ },
+}
+
+# which version operating systems have been tested
+_TESTED_OS_VERSIONS = [
+ ("10", "12"),
+ ("10", "13"),
+ ("10", "14"),
+ ("10", "15"),
+ ("10", "16"),
+ ("11", "0"),
+ ("11", "1"),
+ ("11", "2"),
+ ("11", "3"),
+ ("11", "4"),
+ ("11", "5"),
+ ("11", "6"),
+ ("12", "0"),
+ ("12", "1"),
+ ("12", "2"),
+ ("12", "3"),
+]
+
+# Photos 5 has persons who are empty string if unidentified face
+_UNKNOWN_PERSON = "_UNKNOWN_"
+
+# photos with no reverse geolocation info (place)
+_UNKNOWN_PLACE = "_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"
+_XMP_TEMPLATE_NAME_BETA = "xmp_sidecar_beta.mako"
+
+# Constants used for processing folders and albums
+_PHOTOS_5_ALBUM_KIND = 2 # normal user album
+_PHOTOS_5_SHARED_ALBUM_KIND = 1505 # shared album
+_PHOTOS_5_PROJECT_ALBUM_KIND = 1508 # My Projects (e.g. Calendar, Card, Slideshow)
+_PHOTOS_5_FOLDER_KIND = 4000 # user folder
+_PHOTOS_5_ROOT_FOLDER_KIND = 3999 # root folder
+_PHOTOS_5_IMPORT_SESSION_ALBUM_KIND = 1506 # import session
+
+_PHOTOS_4_ALBUM_KIND = 3 # RKAlbum.albumSubclass
+_PHOTOS_4_ALBUM_TYPE_ALBUM = 1 # RKAlbum.albumType
+_PHOTOS_4_ALBUM_TYPE_PROJECT = 9 # RKAlbum.albumType
+_PHOTOS_4_ALBUM_TYPE_SLIDESHOW = 8 # RKAlbum.albumType
+_PHOTOS_4_TOP_LEVEL_ALBUMS = [
+ "TopLevelAlbums",
+ "TopLevelKeepsakes",
+ "TopLevelSlideshows",
+]
+_PHOTOS_4_ROOT_FOLDER = "LibraryFolder"
+
+# EXIF related constants
+# max keyword length for IPTC:Keyword, reference
+# https://www.iptc.org/std/photometadata/documentation/userguide/
+_MAX_IPTC_KEYWORD_LEN = 64
+
+# Sentinel value for detecting if a template in keyword_template doesn't match
+# If anyone has a keyword matching this, then too bad...
+_OSXPHOTOS_NONE_SENTINEL = "OSXPhotosXYZZY42_Sentinel$"
+
+# SearchInfo categories for Photos 5, corresponds to categories in database/search/psi.sqlite
+SEARCH_CATEGORY_LABEL = 2024
+SEARCH_CATEGORY_PLACE_NAME = 1
+SEARCH_CATEGORY_STREET = 2
+SEARCH_CATEGORY_NEIGHBORHOOD = 3
+SEARCH_CATEGORY_LOCALITY_4 = 4
+SEARCH_CATEGORY_SUB_LOCALITY_5 = 5
+SEARCH_CATEGORY_SUB_LOCALITY_6 = 6
+SEARCH_CATEGORY_CITY = 7
+SEARCH_CATEGORY_LOCALITY_8 = 8
+SEARCH_CATEGORY_NAMED_AREA = 9
+SEARCH_CATEGORY_ALL_LOCALITY = [
+ SEARCH_CATEGORY_LOCALITY_4,
+ SEARCH_CATEGORY_SUB_LOCALITY_5,
+ SEARCH_CATEGORY_SUB_LOCALITY_6,
+ SEARCH_CATEGORY_LOCALITY_8,
+ SEARCH_CATEGORY_NAMED_AREA,
+]
+SEARCH_CATEGORY_STATE = 10
+SEARCH_CATEGORY_STATE_ABBREVIATION = 11
+SEARCH_CATEGORY_COUNTRY = 12
+SEARCH_CATEGORY_BODY_OF_WATER = 14
+SEARCH_CATEGORY_MONTH = 1014
+SEARCH_CATEGORY_YEAR = 1015
+SEARCH_CATEGORY_KEYWORDS = 2016
+SEARCH_CATEGORY_TITLE = 2017
+SEARCH_CATEGORY_DESCRIPTION = 2018
+SEARCH_CATEGORY_HOME = 2020
+SEARCH_CATEGORY_PERSON = 2021
+SEARCH_CATEGORY_ACTIVITY = 2027
+SEARCH_CATEGORY_HOLIDAY = 2029
+SEARCH_CATEGORY_SEASON = 2030
+SEARCH_CATEGORY_WORK = 2036
+SEARCH_CATEGORY_VENUE = 2038
+SEARCH_CATEGORY_VENUE_TYPE = 2039
+SEARCH_CATEGORY_PHOTO_TYPE_VIDEO = 2044
+SEARCH_CATEGORY_PHOTO_TYPE_SLOMO = 2045
+SEARCH_CATEGORY_PHOTO_TYPE_LIVE = 2046
+SEARCH_CATEGORY_PHOTO_TYPE_SCREENSHOT = 2047
+SEARCH_CATEGORY_PHOTO_TYPE_PANORAMA = 2048
+SEARCH_CATEGORY_PHOTO_TYPE_TIMELAPSE = 2049
+SEARCH_CATEGORY_PHOTO_TYPE_BURSTS = 2052
+SEARCH_CATEGORY_PHOTO_TYPE_PORTRAIT = 2053
+SEARCH_CATEGORY_PHOTO_TYPE_SELFIES = 2054
+SEARCH_CATEGORY_PHOTO_TYPE_FAVORITES = 2055
+SEARCH_CATEGORY_MEDIA_TYPES = [
+ SEARCH_CATEGORY_PHOTO_TYPE_VIDEO,
+ SEARCH_CATEGORY_PHOTO_TYPE_SLOMO,
+ SEARCH_CATEGORY_PHOTO_TYPE_LIVE,
+ SEARCH_CATEGORY_PHOTO_TYPE_SCREENSHOT,
+ SEARCH_CATEGORY_PHOTO_TYPE_PANORAMA,
+ SEARCH_CATEGORY_PHOTO_TYPE_TIMELAPSE,
+ SEARCH_CATEGORY_PHOTO_TYPE_BURSTS,
+ SEARCH_CATEGORY_PHOTO_TYPE_PORTRAIT,
+ SEARCH_CATEGORY_PHOTO_TYPE_SELFIES,
+ SEARCH_CATEGORY_PHOTO_TYPE_FAVORITES,
+]
+SEARCH_CATEGORY_PHOTO_NAME = 2056
+
+
+# Max filename length on MacOS
+MAX_FILENAME_LEN = 255
+
+# Max directory name length on MacOS
+MAX_DIRNAME_LEN = 255
+
+# Default JPEG quality when converting to JPEG
+DEFAULT_JPEG_QUALITY = 1.0
+
+# Default suffix to add to edited images
+DEFAULT_EDITED_SUFFIX = "_edited"
+
+# Default suffix to add to original images
+DEFAULT_ORIGINAL_SUFFIX = ""
+
+# Default suffix to add to preview images
+DEFAULT_PREVIEW_SUFFIX = "_preview"
+
+# Bit masks for --sidecar
+SIDECAR_JSON = 0x1
+SIDECAR_EXIFTOOL = 0x2
+SIDECAR_XMP = 0x4
+
+# supported attributes for --xattr-template
+EXTENDED_ATTRIBUTE_NAMES = [
+ "authors",
+ "comment",
+ "copyright",
+ "creator",
+ "description",
+ "findercomment",
+ "headline",
+ "keywords",
+ "participants",
+ "projects",
+ "rating",
+ "subject",
+ "title",
+ "version",
+]
+EXTENDED_ATTRIBUTE_NAMES_QUOTED = [f"'{x}'" for x in EXTENDED_ATTRIBUTE_NAMES]
+
+
+# name of export DB
+OSXPHOTOS_EXPORT_DB = ".osxphotos_export.db"
+
+# bit flags for burst images ("burstPickType")
+BURST_PICK_TYPE_NONE = 0b0 # 0: sometimes used for single images with a burst UUID
+BURST_NOT_SELECTED = 0b10 # 2: burst image is not selected
+BURST_DEFAULT_PICK = 0b100 # 4: burst image is the one Photos picked to be key image before any selections made
+BURST_SELECTED = 0b1000 # 8: burst image is selected
+BURST_KEY = 0b10000 # 16: burst image is the key photo (top of burst stack)
+BURST_UNKNOWN = 0b100000 # 32: this is almost always set with BURST_DEFAULT_PICK and never if BURST_DEFAULT_PICK is not set. I think this has something to do with what algorithm Photos used to pick the default image
+
+LIVE_VIDEO_EXTENSIONS = [".mov"]
+
+# categories that --post-command can be used with; these map to ExportResults fields
+POST_COMMAND_CATEGORIES = {
+ "exported": "All exported files",
+ "new": "When used with '--update', all newly exported files",
+ "updated": "When used with '--update', all files which were previously exported but updated this time",
+ "skipped": "When used with '--update', all files which were skipped (because they were previously exported and didn't change)",
+ "missing": "All files which were not exported because they were missing from the Photos library",
+ "exif_updated": "When used with '--exiftool', all files on which exiftool updated the metadata",
+ "touched": "When used with '--touch-file', all files where the date was touched",
+ "converted_to_jpeg": "When used with '--convert-to-jpeg', all files which were converted to jpeg",
+ "sidecar_json_written": "When used with '--sidecar json', all JSON sidecar files which were written",
+ "sidecar_json_skipped": "When used with '--sidecar json' and '--update', all JSON sidecar files which were skipped",
+ "sidecar_exiftool_written": "When used with '--sidecar exiftool', all exiftool sidecar files which were written",
+ "sidecar_exiftool_skipped": "When used with '--sidecar exiftool' and '--update, all exiftool sidecar files which were skipped",
+ "sidecar_xmp_written": "When used with '--sidecar xmp', all XMP sidecar files which were written",
+ "sidecar_xmp_skipped": "When used with '--sidecar xmp' and '--update', all XMP sidecar files which were skipped",
+ "error": "All files which produced an error during export",
+ # "deleted_files": "When used with '--cleanup', all files deleted during the export",
+ # "deleted_directories": "When used with '--cleanup', all directories deleted during the export",
+}
+
+
+[docs]class AlbumSortOrder(Enum):
+ """Album Sort Order"""
+
+ UNKNOWN = 0
+ MANUAL = 1
+ NEWEST_FIRST = 2
+ OLDEST_FIRST = 3
+ TITLE = 5
+
+
+TEXT_DETECTION_CONFIDENCE_THRESHOLD = 0.75
+
+# stat sort order for cProfile: https://docs.python.org/3/library/profile.html#pstats.Stats.sort_stats
+PROFILE_SORT_KEYS = [
+ "calls",
+ "cumulative",
+ "cumtime",
+ "file",
+ "filename",
+ "module",
+ "ncalls",
+ "pcalls",
+ "line",
+ "name",
+ "nfl",
+ "stdname",
+ "time",
+ "tottime",
+]
+
+"""
+AlbumInfo and FolderInfo classes for dealing with albums and folders
+
+AlbumInfo class
+Represents a single Album in the Photos library and provides access to the album's attributes
+PhotosDB.albums() returns a list of AlbumInfo objects
+
+FolderInfo class
+Represents a single Folder in the Photos library and provides access to the folders attributes
+PhotosDB.folders() returns a list of FolderInfo objects
+"""
+
+from datetime import datetime, timedelta, timezone
+
+from ._constants import (
+ _PHOTOS_4_ALBUM_KIND,
+ _PHOTOS_4_TOP_LEVEL_ALBUMS,
+ _PHOTOS_4_VERSION,
+ _PHOTOS_5_ALBUM_KIND,
+ _PHOTOS_5_FOLDER_KIND,
+ TIME_DELTA,
+ AlbumSortOrder,
+)
+from .datetime_utils import get_local_tz
+from .query_builder import get_query
+
+__all__ = [
+ "sort_list_by_keys",
+ "AlbumInfoBaseClass",
+ "AlbumInfo",
+ "ImportInfo",
+ "ProjectInfo",
+ "FolderInfo",
+]
+
+
+def sort_list_by_keys(values, sort_keys):
+ """Sorts list values by a second list sort_keys
+ e.g. given ["a","c","b"], [1, 3, 2], returns ["a", "b", "c"]
+
+ Args:
+ values: a list of values to be sorted
+ sort_keys: a list of keys to sort values by
+
+ Returns:
+ list of values, sorted by sort_keys
+
+ Raises:
+ ValueError: raised if len(values) != len(sort_keys)
+ """
+ if len(values) != len(sort_keys):
+ return ValueError("values and sort_keys must have same length")
+
+ return list(zip(*sorted(zip(sort_keys, values))))[1]
+
+
+class AlbumInfoBaseClass:
+ """
+ Base class for AlbumInfo, ImportInfo
+ Info about a specific Album, contains all the details about the album
+ including folders, photos, etc.
+ """
+
+ def __init__(self, db=None, uuid=None):
+ self._uuid = uuid
+ self._db = db
+ self._title = self._db._dbalbum_details[uuid]["title"]
+ self._creation_date_timestamp = self._db._dbalbum_details[uuid]["creation_date"]
+ self._start_date_timestamp = self._db._dbalbum_details[uuid]["start_date"]
+ self._end_date_timestamp = self._db._dbalbum_details[uuid]["end_date"]
+ self._local_tz = get_local_tz(
+ datetime.fromtimestamp(self._creation_date_timestamp + TIME_DELTA)
+ )
+
+ @property
+ def uuid(self):
+ """return uuid of album"""
+ return self._uuid
+
+ @property
+ def creation_date(self):
+ """return creation date of album"""
+ try:
+ return self._creation_date
+ except AttributeError:
+ try:
+ self._creation_date = (
+ datetime.fromtimestamp(
+ self._creation_date_timestamp + TIME_DELTA
+ ).astimezone(tz=self._local_tz)
+ if self._creation_date_timestamp
+ else datetime(1970, 1, 1, 0, 0, 0).astimezone(
+ tz=timezone(timedelta(0))
+ )
+ )
+ except ValueError:
+ self._creation_date = datetime(1970, 1, 1, 0, 0, 0).astimezone(
+ tz=timezone(timedelta(0))
+ )
+ return self._creation_date
+
+ @property
+ def start_date(self):
+ """For Albums, return start date (earliest image) of album or None for albums with no images
+ For Import Sessions, return start date of import session (when import began)"""
+ try:
+ return self._start_date
+ except AttributeError:
+ try:
+ self._start_date = (
+ datetime.fromtimestamp(
+ self._start_date_timestamp + TIME_DELTA
+ ).astimezone(tz=self._local_tz)
+ if self._start_date_timestamp
+ else None
+ )
+ except ValueError:
+ self._start_date = None
+ return self._start_date
+
+ @property
+ def end_date(self):
+ """For Albums, return end date (most recent image) of album or None for albums with no images
+ For Import Sessions, return end date of import sessions (when import was completed)"""
+ try:
+ return self._end_date
+ except AttributeError:
+ try:
+ self._end_date = (
+ datetime.fromtimestamp(
+ self._end_date_timestamp + TIME_DELTA
+ ).astimezone(tz=self._local_tz)
+ if self._end_date_timestamp
+ else None
+ )
+ except ValueError:
+ self._end_date = None
+ return self._end_date
+
+ @property
+ def photos(self):
+ return []
+
+ @property
+ def owner(self):
+ """Return name of photo owner for shared album (Photos 5+ only), or None if not shared"""
+ if self._db._db_version <= _PHOTOS_4_VERSION:
+ return None
+
+ try:
+ return self._owner
+ except AttributeError:
+ try:
+ personid = self._db._dbalbum_details[self.uuid][
+ "cloudownerhashedpersonid"
+ ]
+ self._owner = (
+ self._db._db_hashed_person_id[personid]["full_name"]
+ if personid
+ else None
+ )
+ except KeyError:
+ self._owner = None
+ return self._owner
+
+ def __len__(self):
+ """return number of photos contained in album"""
+ return len(self.photos)
+
+
+[docs]class AlbumInfo(AlbumInfoBaseClass):
+ """
+ Info about a specific Album, contains all the details about the album
+ including folders, photos, etc.
+ """
+
+ @property
+ def title(self):
+ """return title / name of album"""
+ return self._title
+
+ @property
+ def photos(self):
+ """return list of photos contained in album sorted in same sort order as Photos"""
+ try:
+ return self._photos
+ except AttributeError:
+ if self.uuid in self._db._dbalbums_album:
+ uuid, sort_order = zip(*self._db._dbalbums_album[self.uuid])
+ sorted_uuid = sort_list_by_keys(uuid, sort_order)
+ photos = self._db.photos_by_uuid(sorted_uuid)
+ sort_order = self.sort_order
+ if sort_order == AlbumSortOrder.NEWEST_FIRST:
+ self._photos = sorted(photos, key=lambda p: p.date, reverse=True)
+ elif sort_order == AlbumSortOrder.OLDEST_FIRST:
+ self._photos = sorted(photos, key=lambda p: p.date)
+ elif sort_order == AlbumSortOrder.TITLE:
+ self._photos = sorted(photos, key=lambda p: p.title or "")
+ else:
+ # assume AlbumSortOrder.MANUAL
+ self._photos = photos
+ else:
+ self._photos = []
+ return self._photos
+
+ @property
+ def folder_names(self):
+ """return hierarchical list of folders the album is contained in
+ the folder list is in form:
+ ["Top level folder", "sub folder 1", "sub folder 2", ...]
+ returns empty list if album is not in any folders"""
+
+ try:
+ return self._folder_names
+ except AttributeError:
+ self._folder_names = self._db._album_folder_hierarchy_list(self._uuid)
+ return self._folder_names
+
+ @property
+ def folder_list(self):
+ """return hierarchical list of folders the album is contained in
+ as list of FolderInfo objects in form
+ ["Top level folder", "sub folder 1", "sub folder 2", ...]
+ returns empty list if album is not in any folders"""
+
+ try:
+ return self._folders
+ except AttributeError:
+ self._folders = self._db._album_folder_hierarchy_folderinfo(self._uuid)
+ return self._folders
+
+ @property
+ def parent(self):
+ """returns FolderInfo object for parent folder or None if no parent (e.g. top-level album)"""
+ try:
+ return self._parent
+ except AttributeError:
+ if self._db._db_version <= _PHOTOS_4_VERSION:
+ parent_uuid = self._db._dbalbum_details[self._uuid]["folderUuid"]
+ self._parent = (
+ FolderInfo(db=self._db, uuid=parent_uuid)
+ if parent_uuid not in _PHOTOS_4_TOP_LEVEL_ALBUMS
+ else None
+ )
+ else:
+ parent_pk = self._db._dbalbum_details[self._uuid]["parentfolder"]
+ self._parent = (
+ FolderInfo(db=self._db, uuid=self._db._dbalbums_pk[parent_pk])
+ if parent_pk != self._db._folder_root_pk
+ else None
+ )
+ return self._parent
+
+ @property
+ def sort_order(self):
+ """return sort order of album"""
+ if self._db._db_version <= _PHOTOS_4_VERSION:
+ return AlbumSortOrder.MANUAL
+
+ details = self._db._dbalbum_details[self._uuid]
+ if details["customsortkey"] == 1:
+ if details["customsortascending"] == 0:
+ return AlbumSortOrder.NEWEST_FIRST
+ elif details["customsortascending"] == 1:
+ return AlbumSortOrder.OLDEST_FIRST
+ else:
+ return AlbumSortOrder.UNKNOWN
+ elif details["customsortkey"] == 5:
+ return AlbumSortOrder.TITLE
+ elif details["customsortkey"] == 0:
+ return AlbumSortOrder.MANUAL
+ else:
+ return AlbumSortOrder.UNKNOWN
+
+[docs] def photo_index(self, photo):
+ """return index of photo in album (based on album sort order)"""
+ for index, p in enumerate(self.photos):
+ if p.uuid == photo.uuid:
+ return index
+ raise ValueError(
+ f"Photo with uuid {photo.uuid} does not appear to be in this album"
+ )
+
+
+[docs]class ImportInfo(AlbumInfoBaseClass):
+ """Information about import sessions"""
+
+ @property
+ def photos(self):
+ """return list of photos contained in import session"""
+ try:
+ return self._photos
+ except AttributeError:
+ uuid_list, sort_order = zip(
+ *[
+ (uuid, self._db._dbphotos[uuid]["fok_import_session"])
+ for uuid in self._db._dbphotos
+ if self._db._dbphotos[uuid]["import_uuid"] == self.uuid
+ ]
+ )
+ sorted_uuid = sort_list_by_keys(uuid_list, sort_order)
+ self._photos = self._db.photos_by_uuid(sorted_uuid)
+ return self._photos
+
+
+[docs]class ProjectInfo(AlbumInfo):
+ """
+ ProjectInfo with info about projects
+ Projects are cards, calendars, slideshows, etc.
+ """
+
+ ...
+
+
+class FolderInfo:
+ """
+ Info about a specific folder, contains all the details about the folder
+ including folders, albums, etc
+ """
+
+ def __init__(self, db=None, uuid=None):
+ self._uuid = uuid
+ self._db = db
+ if self._db._db_version <= _PHOTOS_4_VERSION:
+ self._pk = None
+ self._title = self._db._dbfolder_details[uuid]["name"]
+ else:
+ self._pk = self._db._dbalbum_details[uuid]["pk"]
+ self._title = self._db._dbalbum_details[uuid]["title"]
+
+ @property
+ def title(self):
+ """return title / name of folder"""
+ return self._title
+
+ @property
+ def uuid(self):
+ """return uuid of folder"""
+ return self._uuid
+
+ @property
+ def album_info(self):
+ """return list of albums (as AlbumInfo objects) contained in the folder"""
+ try:
+ return self._albums
+ except AttributeError:
+ if self._db._db_version <= _PHOTOS_4_VERSION:
+ albums = [
+ AlbumInfo(db=self._db, uuid=album)
+ for album, detail in self._db._dbalbum_details.items()
+ if not detail["intrash"]
+ and detail["albumSubclass"] == _PHOTOS_4_ALBUM_KIND
+ and detail["folderUuid"] == self._uuid
+ ]
+ else:
+ albums = [
+ AlbumInfo(db=self._db, uuid=album)
+ for album, detail in self._db._dbalbum_details.items()
+ if not detail["intrash"]
+ and detail["kind"] == _PHOTOS_5_ALBUM_KIND
+ and detail["parentfolder"] == self._pk
+ ]
+ self._albums = albums
+ return self._albums
+
+ @property
+ def parent(self):
+ """returns FolderInfo object for parent or None if no parent (e.g. top-level folder)"""
+ try:
+ return self._parent
+ except AttributeError:
+ if self._db._db_version <= _PHOTOS_4_VERSION:
+ parent_uuid = self._db._dbfolder_details[self._uuid]["parentFolderUuid"]
+ self._parent = (
+ FolderInfo(db=self._db, uuid=parent_uuid)
+ if parent_uuid not in _PHOTOS_4_TOP_LEVEL_ALBUMS
+ else None
+ )
+ else:
+ parent_pk = self._db._dbalbum_details[self._uuid]["parentfolder"]
+ self._parent = (
+ FolderInfo(db=self._db, uuid=self._db._dbalbums_pk[parent_pk])
+ if parent_pk != self._db._folder_root_pk
+ else None
+ )
+ return self._parent
+
+ @property
+ def subfolders(self):
+ """return list of folders (as FolderInfo objects) contained in the folder"""
+ try:
+ return self._folders
+ except AttributeError:
+ if self._db._db_version <= _PHOTOS_4_VERSION:
+ folders = [
+ FolderInfo(db=self._db, uuid=folder)
+ for folder, detail in self._db._dbfolder_details.items()
+ if not detail["intrash"]
+ and not detail["isMagic"]
+ and detail["parentFolderUuid"] == self._uuid
+ ]
+ else:
+ folders = [
+ FolderInfo(db=self._db, uuid=album)
+ for album, detail in self._db._dbalbum_details.items()
+ if not detail["intrash"]
+ and detail["kind"] == _PHOTOS_5_FOLDER_KIND
+ and detail["parentfolder"] == self._pk
+ ]
+ self._folders = folders
+ return self._folders
+
+ def __len__(self):
+ """returns count of folders + albums contained in the folder"""
+ return len(self.subfolders) + len(self.album_info)
+
+"""Utilities for debugging"""
+
+import logging
+import sys
+import time
+from datetime import datetime
+from typing import Dict, List
+
+import wrapt
+from rich import print
+
+# global variable to control debug output
+# set via --debug
+DEBUG = False
+
+
+[docs]def set_debug(debug: bool):
+ """set debug flag"""
+ global DEBUG
+ DEBUG = debug
+ logging.disable(logging.NOTSET if debug else logging.DEBUG)
+
+
+
+
+
+def debug_watch(wrapped, instance, args, kwargs):
+ """For use with wrapt.wrap_function_wrapper to watch calls to a function"""
+ caller = sys._getframe().f_back.f_code.co_name
+ name = wrapped.__name__
+ timestamp = datetime.now().isoformat()
+ print(
+ f"{timestamp} {name} called from {caller} with args: {args} and kwargs: {kwargs}"
+ )
+ start_t = time.perf_counter()
+ rv = wrapped(*args, **kwargs)
+ stop_t = time.perf_counter()
+ print(f"{timestamp} {name} returned: {rv}, elapsed time: {stop_t - start_t} sec")
+ return rv
+
+
+def debug_breakpoint(wrapped, instance, args, kwargs):
+ """For use with wrapt.wrap_function_wrapper to set breakpoint on a function"""
+ breakpoint()
+ return wrapped(*args, **kwargs)
+
+
+def wrap_function(function_path, wrapper):
+ """Wrap a function with wrapper function"""
+ module, name = function_path.split(".", 1)
+ try:
+ return wrapt.wrap_function_wrapper(module, name, wrapper)
+ except AttributeError as e:
+ raise AttributeError(f"{module}.{name} does not exist") from e
+
+
+def get_debug_options(arg_names: List, argv: List) -> Dict:
+ """Get the options for the debug options;
+ Some of the debug options like --watch and --breakpoint need to be processed before any other packages are loaded
+ so they can't be handled in the normal click argument processing, thus this function is called
+ from osxphotos/cli/__init__.py
+
+ Assumes multi-valued options are OK and that all options take form of --option VALUE or --option=VALUE
+ """
+ # argv[0] is the program name
+ # argv[1] is the command
+ # argv[2:] are the arguments
+ args = {}
+ for arg_name in arg_names:
+ for idx, arg in enumerate(argv[1:]):
+ if arg.startswith(f"{arg_name}="):
+ arg_value = arg.split("=")[1]
+ try:
+ args[arg].append(arg_value)
+ except KeyError:
+ args[arg] = [arg_value]
+ elif arg == arg_name:
+ try:
+ args[arg].append(argv[idx + 2])
+ except KeyError:
+ try:
+ args[arg] = [argv[idx + 2]]
+ except IndexError as e:
+ raise ValueError(f"Missing value for {arg}") from e
+ except IndexError as e:
+ raise ValueError(f"Missing value for {arg}") from e
+ return args
+
+
+def get_debug_flags(arg_names: List, argv: List) -> Dict:
+ """Get the flags for the debug options;
+ Processes flags like --debug that resolve to True or False
+ """
+ # argv[0] is the program name
+ # argv[1] is the command
+ # argv[2:] are the arguments
+ args = {arg_name: False for arg_name in arg_names}
+ for arg_name in arg_names:
+ if arg_name in argv[1:]:
+ args[arg_name] = True
+ return args
+
+""" ExifInfo class to expose EXIF info from the library """
+
+from dataclasses import dataclass
+
+__all__ = ["ExifInfo"]
+
+
+[docs]@dataclass(frozen=True)
+class ExifInfo:
+ """EXIF info associated with a photo from the Photos library"""
+
+ flash_fired: bool
+ iso: int
+ metering_mode: int
+ sample_rate: int
+ track_format: int
+ white_balance: int
+ aperture: float
+ bit_rate: float
+ duration: float
+ exposure_bias: float
+ focal_length: float
+ fps: float
+ latitude: float
+ longitude: float
+ shutter_speed: float
+ camera_make: str
+ camera_model: str
+ codec: str
+ lens_model: str
+
+""" Yet another simple exiftool wrapper
+ I rolled my own for following reasons:
+ 1. I wanted something under MIT license (best alternative was licensed under GPL/BSD)
+ 2. I wanted singleton behavior so only a single exiftool process was ever running
+ 3. When used as a context manager, I wanted the operations to batch until exiting the context (improved performance)
+ If these aren't important to you, I highly recommend you use Sven Marnach's excellent
+ pyexiftool: https://github.com/smarnach/pyexiftool which provides more functionality """
+
+import atexit
+import html
+import json
+import logging
+import os
+import pathlib
+import re
+import shutil
+import subprocess
+from abc import ABC, abstractmethod
+from functools import lru_cache # pylint: disable=syntax-error
+
+__all__ = [
+ "escape_str",
+ "exiftool_can_write",
+ "ExifTool",
+ "ExifToolCaching",
+ "get_exiftool_path",
+ "terminate_exiftool",
+ "unescape_str",
+]
+
+# exiftool -stay_open commands outputs this EOF marker after command is run
+EXIFTOOL_STAYOPEN_EOF = "{ready}"
+EXIFTOOL_STAYOPEN_EOF_LEN = len(EXIFTOOL_STAYOPEN_EOF)
+
+# list of exiftool processes to cleanup when exiting or when terminate is called
+EXIFTOOL_PROCESSES = []
+
+# exiftool supported file types, created by utils/exiftool_supported_types.py
+EXIFTOOL_FILETYPES_JSON = "exiftool_filetypes.json"
+with (pathlib.Path(__file__).parent / EXIFTOOL_FILETYPES_JSON).open("r") as f:
+ EXIFTOOL_SUPPORTED_FILETYPES = json.load(f)
+
+
+def exiftool_can_write(suffix: str) -> bool:
+ """Return True if exiftool supports writing to a file with the given suffix, otherwise False"""
+ if not suffix:
+ return False
+ suffix = suffix.lower()
+ if suffix[0] == ".":
+ suffix = suffix[1:]
+ return (
+ suffix in EXIFTOOL_SUPPORTED_FILETYPES
+ and EXIFTOOL_SUPPORTED_FILETYPES[suffix]["write"]
+ )
+
+
+def escape_str(s):
+ """escape string for use with exiftool -E"""
+ if type(s) != str:
+ return s
+ s = html.escape(s)
+ s = s.replace("\n", "
")
+ s = s.replace("\t", "	")
+ s = s.replace("\r", "
")
+ return s
+
+
+def unescape_str(s):
+ """unescape an HTML string returned by exiftool -E"""
+ if type(s) != str:
+ return s
+ # avoid " in values which result in json.loads() throwing an exception, #636
+ s = s.replace(""", '\\"')
+ return html.unescape(s)
+
+
+@atexit.register
+def terminate_exiftool():
+ """Terminate any running ExifTool subprocesses; call this to cleanup when done using ExifTool"""
+ for proc in EXIFTOOL_PROCESSES:
+ proc._stop_proc()
+
+
+@lru_cache(maxsize=1)
+def get_exiftool_path():
+ """return path of exiftool, cache result"""
+ exiftool_path = shutil.which("exiftool")
+ if exiftool_path:
+ return exiftool_path.rstrip()
+ else:
+ raise FileNotFoundError(
+ "Could not find exiftool. Please download and install from "
+ "https://exiftool.org/"
+ )
+
+
+class _ExifToolProc:
+ """Runs exiftool in a subprocess via Popen
+ Creates a singleton object"""
+
+ def __new__(cls, *args, **kwargs):
+ """create new object or return instance of already created singleton"""
+ if not hasattr(cls, "instance") or not cls.instance:
+ cls.instance = super().__new__(cls)
+
+ return cls.instance
+
+ def __init__(self, exiftool=None):
+ """construct _ExifToolProc singleton object or return instance of already created object
+ exiftool: optional path to exiftool binary (if not provided, will search path to find it)
+ """
+
+ if hasattr(self, "_process_running") and self._process_running:
+ # already running
+ if exiftool is not None and exiftool != self._exiftool:
+ logging.warning(
+ f"exiftool subprocess already running, "
+ f"ignoring exiftool={exiftool}"
+ )
+ return
+ self._process_running = False
+ self._exiftool = exiftool or get_exiftool_path()
+ self._start_proc()
+
+ @property
+ def process(self):
+ """return the exiftool subprocess"""
+ if self._process_running:
+ return self._process
+ else:
+ self._start_proc()
+ return self._process
+
+ @property
+ def pid(self):
+ """return process id (PID) of the exiftool process"""
+ return self._process.pid
+
+ @property
+ def exiftool(self):
+ """return path to exiftool process"""
+ return self._exiftool
+
+ def _start_proc(self):
+ """start exiftool in batch mode"""
+
+ if self._process_running:
+ logging.warning("exiftool already running: {self._process}")
+ return
+
+ # open exiftool process
+ # make sure /usr/bin at start of path so exiftool can find xattr (see #636)
+ env = os.environ.copy()
+ env["PATH"] = f'/usr/bin/:{env["PATH"]}'
+ self._process = subprocess.Popen(
+ [
+ self._exiftool,
+ "-stay_open", # keep process open in batch mode
+ "True", # -stay_open=True, keep process open in batch mode
+ "-@", # read command-line arguments from file
+ "-", # read from stdin
+ "-common_args", # specifies args common to all commands subsequently run
+ "-n", # no print conversion (e.g. print tag values in machine readable format)
+ "-P", # Preserve file modification date/time
+ "-G", # print group name for each tag
+ "-E", # escape tag values for HTML (allows use of HTML 
 for newlines)
+ ],
+ stdin=subprocess.PIPE,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.STDOUT,
+ env=env,
+ )
+ self._process_running = True
+
+ EXIFTOOL_PROCESSES.append(self)
+
+ def _stop_proc(self):
+ """stop the exiftool process if it's running, otherwise, do nothing"""
+
+ if not self._process_running:
+ return
+
+ try:
+ self._process.stdin.write(b"-stay_open\n")
+ self._process.stdin.write(b"False\n")
+ self._process.stdin.flush()
+ except Exception as e:
+ pass
+
+ try:
+ self._process.communicate(timeout=5)
+ except subprocess.TimeoutExpired:
+ self._process.kill()
+ self._process.communicate()
+
+ del self._process
+ self._process_running = False
+
+
+[docs]class ExifTool:
+ """Basic exiftool interface for reading and writing EXIF tags"""
+
+ def __init__(self, filepath, exiftool=None, overwrite=True, flags=None):
+ """Create ExifTool object
+
+ Args:
+ file: path to image file
+ exiftool: path to exiftool, if not specified will look in path
+ overwrite: if True, will overwrite image file without creating backup, default=False
+ flags: optional list of exiftool flags to prepend to exiftool command when writing metadata (e.g. -m or -F)
+
+ Returns:
+ ExifTool instance
+ """
+ self.file = filepath
+ self.overwrite = overwrite
+ self.flags = flags or []
+ self.data = {}
+ self.warning = None
+ self.error = None
+ # if running as a context manager, self._context_mgr will be True
+ self._context_mgr = False
+ self._exiftoolproc = _ExifToolProc(exiftool=exiftool)
+ self._read_exif()
+
+ @property
+ def _process(self):
+ return self._exiftoolproc.process
+
+[docs] def setvalue(self, tag, value):
+ """Set tag to value(s); if value is None, will delete tag
+
+ Args:
+ tag: str; name of tag to set
+ value: str; value to set tag to
+
+ Returns:
+ True if success otherwise False
+
+ If error generated by exiftool, returns False and sets self.error to error string
+ If warning generated by exiftool, returns True (unless there was also an error) and sets self.warning to warning string
+ If called in context manager, returns True (execution is delayed until exiting context manager)
+ """
+
+ if value is None:
+ value = ""
+ value = escape_str(value)
+ command = [f"-{tag}={value}"]
+ if self.overwrite and not self._context_mgr:
+ command.append("-overwrite_original")
+
+ # avoid "Warning: Some character(s) could not be encoded in Latin" warning
+ command.append("-iptc:codedcharacterset=utf8")
+
+ if self._context_mgr:
+ self._commands.extend(command)
+ return True
+ else:
+ _, _, error = self.run_commands(*command)
+ return error == ""
+
+[docs] def addvalues(self, tag, *values):
+ """Add one or more value(s) to tag
+ If more than one value is passed, each value will be added to the tag
+
+ Args:
+ tag: str; tag to set
+ *values: str; one or more values to set
+
+ Returns:
+ True if success otherwise False
+
+ If error generated by exiftool, returns False and sets self.error to error string
+ If warning generated by exiftool, returns True (unless there was also an error) and sets self.warning to warning string
+ If called in context manager, returns True (execution is delayed until exiting context manager)
+
+ Notes: exiftool may add duplicate values for some tags so the caller must ensure
+ the values being added are not already in the EXIF data
+ For some tags, such as IPTC:Keywords, this will add a new value to the list of keywords,
+ but for others, such as EXIF:ISO, this will literally add a value to the existing value.
+ It's up to the caller to know what exiftool will do for each tag
+ If setvalue called before addvalues, exiftool does not appear to add duplicates,
+ but if addvalues called without first calling setvalue, exiftool will add duplicate values
+ """
+ if not values:
+ raise ValueError("Must pass at least one value")
+
+ command = []
+ for value in values:
+ if value is None:
+ raise ValueError("Can't add None value to tag")
+ value = escape_str(value)
+ command.append(f"-{tag}+={value}")
+
+ if self.overwrite and not self._context_mgr:
+ command.append("-overwrite_original")
+
+ if self._context_mgr:
+ self._commands.extend(command)
+ return True
+ else:
+ _, _, error = self.run_commands(*command)
+ return error == ""
+
+[docs] def run_commands(self, *commands, no_file=False):
+ """Run commands in the exiftool process and return result.
+
+ Args:
+ *commands: exiftool commands to run
+ no_file: (bool) do not pass the filename to exiftool (default=False)
+ by default, all commands will be run against self.file
+ use no_file=True to run a command without passing the filename
+ Returns:
+ (output, warning, errror)
+ output: bytes is containing output of exiftool commands
+ warning: if exiftool generated warnings, string containing warning otherwise empty string
+ error: if exiftool generated errors, string containing otherwise empty string
+
+ Note: Also sets self.warning and self.error if warning or error generated.
+ """
+ if not (hasattr(self, "_process") and self._process):
+ raise ValueError("exiftool process is not running")
+
+ if not commands:
+ raise TypeError("must provide one or more command to run")
+
+ if self._context_mgr and self.overwrite:
+ commands = list(commands)
+ commands.append("-overwrite_original")
+
+ filename = os.fsencode(self.file) if not no_file else b""
+
+ if self.flags:
+ # need to split flags, e.g. so "--ext AVI" becomes ["--ext", "AVI"]
+ flags = []
+ for f in self.flags:
+ flags.extend(f.split())
+ command_str = b"\n".join([f.encode("utf-8") for f in flags])
+ command_str += b"\n"
+ else:
+ command_str = b""
+
+ command_str += (
+ b"\n".join([c.encode("utf-8") for c in commands])
+ + b"\n"
+ + filename
+ + b"\n"
+ + b"-execute\n"
+ )
+
+ # send the command
+ self._process.stdin.write(command_str)
+ self._process.stdin.flush()
+
+ # read the output
+ output = b""
+ warning = b""
+ error = b""
+ while EXIFTOOL_STAYOPEN_EOF not in str(output):
+ line = self._process.stdout.readline()
+ if line.startswith(b"Warning"):
+ warning += line.strip()
+ elif line.startswith(b"Error"):
+ error += line.strip()
+ else:
+ output += line.strip()
+ warning = "" if warning == b"" else warning.decode("utf-8")
+ error = "" if error == b"" else error.decode("utf-8")
+ self.warning = warning
+ self.error = error
+
+ return output[:-EXIFTOOL_STAYOPEN_EOF_LEN], warning, error
+
+ @property
+ def pid(self):
+ """return process id (PID) of the exiftool process"""
+ return self._process.pid
+
+ @property
+ def version(self):
+ """returns exiftool version"""
+ ver, _, _ = self.run_commands("-ver", no_file=True)
+ return ver.decode("utf-8")
+
+[docs] def asdict(self, tag_groups=True, normalized=False):
+ """return dictionary of all EXIF tags and values from exiftool
+ returns empty dict if no tags
+
+ Args:
+ tag_groups: if True (default), dict keys have tag groups, e.g. "IPTC:Keywords"; if False, drops groups from keys, e.g. "Keywords"
+ normalized: if True, dict keys are all normalized to lower case (default is False)
+ """
+ json_str, _, _ = self.run_commands("-json")
+ if not json_str:
+ return dict()
+ json_str = unescape_str(json_str.decode("utf-8"))
+
+ try:
+ exifdict = json.loads(json_str)
+ except Exception as e:
+ # will fail with some commands, e.g --ext AVI which produces
+ # 'No file with specified extension' instead of json
+ logging.warning(f"error loading json returned by exiftool: {e} {json_str}")
+ return dict()
+ exifdict = exifdict[0]
+ if not tag_groups:
+ # strip tag groups
+ exif_new = {}
+ for k, v in exifdict.items():
+ k = re.sub(r".*:", "", k)
+ exif_new[k] = v
+ exifdict = exif_new
+
+ if normalized:
+ exifdict = {k.lower(): v for (k, v) in exifdict.items()}
+
+ return exifdict
+
+[docs] def json(self):
+ """returns JSON string containing all EXIF tags and values from exiftool"""
+ json, _, _ = self.run_commands("-json")
+ json = unescape_str(json.decode("utf-8"))
+ return json
+
+ def _read_exif(self):
+ """read exif data from file"""
+ data = self.asdict()
+ self.data = {k: v for k, v in data.items()}
+
+ def __str__(self):
+ return f"file: {self.file}\nexiftool: {self._exiftoolproc._exiftool}"
+
+ def __enter__(self):
+ self._context_mgr = True
+ self._commands = []
+ return self
+
+ def __exit__(self, exc_type, exc_value, traceback):
+ if exc_type:
+ return False
+ elif self._commands:
+ # run_commands sets self.warning and self.error as needed
+ self.run_commands(*self._commands)
+
+
+class ExifToolCaching(ExifTool):
+ """Basic exiftool interface for reading and writing EXIF tags, with caching.
+ Use this only when you know the file's EXIF data will not be changed by any external process.
+
+ Creates a singleton cached ExifTool instance"""
+
+ _singletons = {}
+
+ def __new__(cls, filepath, exiftool=None):
+ """create new object or return instance of already created singleton"""
+ if filepath not in cls._singletons:
+ cls._singletons[filepath] = _ExifToolCaching(filepath, exiftool=exiftool)
+ return cls._singletons[filepath]
+
+
+class _ExifToolCaching(ExifTool):
+ def __init__(self, filepath, exiftool=None):
+ """Create read-only ExifTool object that caches values
+
+ Args:
+ file: path to image file
+ exiftool: path to exiftool, if not specified will look in path
+
+ Returns:
+ ExifTool instance
+ """
+ self._json_cache = None
+ self._asdict_cache = {}
+ super().__init__(filepath, exiftool=exiftool, overwrite=False, flags=None)
+
+ def run_commands(self, *commands, no_file=False):
+ if commands[0] not in ["-json", "-ver"]:
+ raise NotImplementedError(f"{self.__class__} is read-only")
+ return super().run_commands(*commands, no_file=no_file)
+
+ def setvalue(self, tag, value):
+ raise NotImplementedError(f"{self.__class__} is read-only")
+
+ def addvalues(self, tag, *values):
+ raise NotImplementedError(f"{self.__class__} is read-only")
+
+ def json(self):
+ if not self._json_cache:
+ self._json_cache = super().json()
+ return self._json_cache
+
+ def asdict(self, tag_groups=True, normalized=False):
+ """return dictionary of all EXIF tags and values from exiftool
+ returns empty dict if no tags
+
+ Args:
+ tag_groups: if True (default), dict keys have tag groups, e.g. "IPTC:Keywords"; if False, drops groups from keys, e.g. "Keywords"
+ normalized: if True, dict keys are all normalized to lower case (default is False)
+ """
+ try:
+ return self._asdict_cache[tag_groups][normalized]
+ except KeyError:
+ if tag_groups not in self._asdict_cache:
+ self._asdict_cache[tag_groups] = {}
+ self._asdict_cache[tag_groups][normalized] = super().asdict(
+ tag_groups=tag_groups, normalized=normalized
+ )
+ return self._asdict_cache[tag_groups][normalized]
+
+ def flush_cache(self):
+ """Clear cached data so that calls to json or asdict return fresh data"""
+ self._json_cache = None
+ self._asdict_cache = {}
+
+""" Helper class for managing database used by PhotoExporter for tracking state of exports and updates """
+
+
+import datetime
+import json
+import logging
+import os
+import pathlib
+import sqlite3
+import sys
+from io import StringIO
+from sqlite3 import Error
+from tempfile import TemporaryDirectory
+from typing import Optional, Tuple, Union
+
+from ._constants import OSXPHOTOS_EXPORT_DB
+from ._version import __version__
+from .fileutil import FileUtil
+from .utils import normalize_fs_path
+
+__all__ = [
+ "ExportDB",
+ "ExportDBInMemory",
+ "ExportDBTemp",
+]
+
+OSXPHOTOS_EXPORTDB_VERSION = "6.0"
+OSXPHOTOS_ABOUT_STRING = f"Created by osxphotos version {__version__} (https://github.com/RhetTbull/osxphotos) on {datetime.datetime.now()}"
+
+
+[docs]class ExportDB:
+ """Interface to sqlite3 database used to store state information for osxphotos export command"""
+
+ def __init__(self, dbfile, export_dir):
+ """create a new ExportDB object
+
+ Args:
+ dbfile: path to osxphotos export database file
+ export_dir: path to directory where exported files are stored
+ memory: if True, use in-memory database
+ """
+
+ self._dbfile = dbfile
+ # export_dir is required as all files referenced by get_/set_uuid_for_file will be converted to
+ # relative paths to this path
+ # this allows the entire export tree to be moved to a new disk/location
+ # whilst preserving the UUID to filename mapping
+ self._path = export_dir
+ self._conn = self._open_export_db(dbfile)
+ self._perform_db_maintenace(self._conn)
+ self._insert_run_info()
+
+ @property
+ def path(self):
+ """returns path to export database"""
+ return self._dbfile
+
+ @property
+ def export_dir(self):
+ """returns path to export directory"""
+ return self._path
+
+[docs] def get_file_record(self, filename: Union[pathlib.Path, str]) -> "ExportRecord":
+ """get info for filename and uuid
+
+ Returns: an ExportRecord object
+ """
+ filename = self._relative_filepath(filename)
+ filename_normalized = self._normalize_filepath(filename)
+ conn = self._conn
+ c = conn.cursor()
+ row = c.execute(
+ "SELECT uuid FROM export_data WHERE filepath_normalized = ?;",
+ (filename_normalized,),
+ ).fetchone()
+
+ if not row:
+ return None
+ return ExportRecord(conn, filename_normalized)
+
+[docs] def create_file_record(
+ self, filename: Union[pathlib.Path, str], uuid: str
+ ) -> "ExportRecord":
+ """create a new record for filename and uuid
+
+ Returns: an ExportRecord object
+ """
+ filename = self._relative_filepath(filename)
+ filename_normalized = self._normalize_filepath(filename)
+ conn = self._conn
+ c = conn.cursor()
+ c.execute(
+ "INSERT INTO export_data (filepath, filepath_normalized, uuid) VALUES (?, ?, ?);",
+ (filename, filename_normalized, uuid),
+ )
+ conn.commit()
+ return ExportRecord(conn, filename_normalized)
+
+[docs] def create_or_get_file_record(
+ self, filename: Union[pathlib.Path, str], uuid: str
+ ) -> "ExportRecord":
+ """create a new record for filename and uuid or return existing record
+
+ Returns: an ExportRecord object
+ """
+ filename = self._relative_filepath(filename)
+ filename_normalized = self._normalize_filepath(filename)
+ conn = self._conn
+ c = conn.cursor()
+ c.execute(
+ "INSERT OR IGNORE INTO export_data (filepath, filepath_normalized, uuid) VALUES (?, ?, ?);",
+ (filename, filename_normalized, uuid),
+ )
+ conn.commit()
+ return ExportRecord(conn, filename_normalized)
+
+[docs] def get_uuid_for_file(self, filename):
+ """query database for filename and return UUID
+ returns None if filename not found in database
+ """
+ filepath_normalized = self._normalize_filepath_relative(filename)
+ conn = self._conn
+ try:
+ c = conn.cursor()
+ c.execute(
+ "SELECT uuid FROM export_data WHERE filepath_normalized = ?",
+ (filepath_normalized,),
+ )
+ results = c.fetchone()
+ uuid = results[0] if results else None
+ except Error as e:
+ logging.warning(e)
+ uuid = None
+ return uuid
+
+[docs] def get_photoinfo_for_uuid(self, uuid):
+ """returns the photoinfo JSON struct for a UUID"""
+ conn = self._conn
+ try:
+ c = conn.cursor()
+ c.execute("SELECT photoinfo FROM photoinfo WHERE uuid = ?", (uuid,))
+ results = c.fetchone()
+ info = results[0] if results else None
+ except Error as e:
+ logging.warning(e)
+ info = None
+
+ return info
+
+[docs] def set_photoinfo_for_uuid(self, uuid, info):
+ """sets the photoinfo JSON struct for a UUID"""
+ conn = self._conn
+ try:
+ c = conn.cursor()
+ c.execute(
+ "INSERT OR REPLACE INTO photoinfo(uuid, photoinfo) VALUES (?, ?);",
+ (uuid, info),
+ )
+ conn.commit()
+ except Error as e:
+ logging.warning(e)
+
+[docs] def get_previous_uuids(self):
+ """returns list of UUIDs of previously exported photos found in export database"""
+ conn = self._conn
+ previous_uuids = []
+ try:
+ c = conn.cursor()
+ c.execute("SELECT DISTINCT uuid FROM export_data")
+ results = c.fetchall()
+ previous_uuids = [row[0] for row in results]
+ except Error as e:
+ logging.warning(e)
+ return previous_uuids
+
+[docs] def set_config(self, config_data):
+ """set config in the database"""
+ conn = self._conn
+ try:
+ dt = datetime.datetime.now().isoformat()
+ c = conn.cursor()
+ c.execute(
+ "INSERT OR REPLACE INTO config(datetime, config) VALUES (?, ?);",
+ (dt, config_data),
+ )
+ conn.commit()
+ except Error as e:
+ logging.warning(e)
+
+[docs] def close(self):
+ """close the database connection"""
+ try:
+ self._conn.close()
+ except Error as e:
+ logging.warning(e)
+
+ def _open_export_db(self, dbfile):
+ """open export database and return a db connection
+ if dbfile does not exist, will create and initialize the database
+ if dbfile needs to be upgraded, will perform needed migrations
+ returns: connection to the database
+ """
+
+ if not os.path.isfile(dbfile):
+ conn = self._get_db_connection(dbfile)
+ if not conn:
+ raise Exception("Error getting connection to database {dbfile}")
+ self._create_or_migrate_db_tables(conn)
+ self.was_created = True
+ self.was_upgraded = ()
+ else:
+ conn = self._get_db_connection(dbfile)
+ self.was_created = False
+ version_info = self._get_database_version(conn)
+ if version_info[1] < OSXPHOTOS_EXPORTDB_VERSION:
+ self._create_or_migrate_db_tables(conn)
+ self.was_upgraded = (version_info[1], OSXPHOTOS_EXPORTDB_VERSION)
+ else:
+ self.was_upgraded = ()
+ self.version = OSXPHOTOS_EXPORTDB_VERSION
+
+ # turn on performance optimizations
+ c = conn.cursor()
+ c.execute("PRAGMA journal_mode=WAL;")
+ c.execute("PRAGMA synchronous=NORMAL;")
+ c.execute("PRAGMA cache_size=-100000;")
+ c.execute("PRAGMA temp_store=MEMORY;")
+
+ return conn
+
+ def _get_db_connection(self, dbfile):
+ """return db connection to dbname"""
+ try:
+ conn = sqlite3.connect(dbfile)
+ except Error as e:
+ logging.warning(e)
+ conn = None
+
+ return conn
+
+ def _get_database_version(self, conn):
+ """return tuple of (osxphotos, exportdb) versions for database connection conn"""
+ version_info = conn.execute(
+ "SELECT osxphotos, exportdb, max(id) FROM version"
+ ).fetchone()
+ return (version_info[0], version_info[1])
+
+ def _create_or_migrate_db_tables(self, conn):
+ """create (if not already created) the necessary db tables for the export database and apply any needed migrations
+
+ Args:
+ conn: sqlite3 db connection
+ """
+ try:
+ version = self._get_database_version(conn)
+ except Exception as e:
+ version = (__version__, "4.3")
+
+ # Current for version 4.3, for anything greater, do a migration after creation
+ sql_commands = [
+ """ CREATE TABLE IF NOT EXISTS version (
+ id INTEGER PRIMARY KEY,
+ osxphotos TEXT,
+ exportdb TEXT
+ ); """,
+ """ CREATE TABLE IF NOT EXISTS about (
+ id INTEGER PRIMARY KEY,
+ about TEXT
+ );""",
+ """ CREATE TABLE IF NOT EXISTS files (
+ id INTEGER PRIMARY KEY,
+ filepath TEXT NOT NULL,
+ filepath_normalized TEXT NOT NULL,
+ uuid TEXT,
+ orig_mode INTEGER,
+ orig_size INTEGER,
+ orig_mtime REAL,
+ exif_mode INTEGER,
+ exif_size INTEGER,
+ exif_mtime REAL
+ ); """,
+ """ CREATE TABLE IF NOT EXISTS runs (
+ id INTEGER PRIMARY KEY,
+ datetime TEXT,
+ python_path TEXT,
+ script_name TEXT,
+ args TEXT,
+ cwd TEXT
+ ); """,
+ """ CREATE TABLE IF NOT EXISTS info (
+ id INTEGER PRIMARY KEY,
+ uuid text NOT NULL,
+ json_info JSON
+ ); """,
+ """ CREATE TABLE IF NOT EXISTS exifdata (
+ id INTEGER PRIMARY KEY,
+ filepath_normalized TEXT NOT NULL,
+ json_exifdata JSON
+ ); """,
+ """ CREATE TABLE IF NOT EXISTS edited (
+ id INTEGER PRIMARY KEY,
+ filepath_normalized TEXT NOT NULL,
+ mode INTEGER,
+ size INTEGER,
+ mtime REAL
+ ); """,
+ """ CREATE TABLE IF NOT EXISTS converted (
+ id INTEGER PRIMARY KEY,
+ filepath_normalized TEXT NOT NULL,
+ mode INTEGER,
+ size INTEGER,
+ mtime REAL
+ ); """,
+ """ CREATE TABLE IF NOT EXISTS sidecar (
+ id INTEGER PRIMARY KEY,
+ filepath_normalized TEXT NOT NULL,
+ sidecar_data TEXT,
+ mode INTEGER,
+ size INTEGER,
+ mtime REAL
+ ); """,
+ """ CREATE TABLE IF NOT EXISTS detected_text (
+ id INTEGER PRIMARY KEY,
+ uuid TEXT NOT NULL,
+ text_data JSON
+ ); """,
+ """ CREATE UNIQUE INDEX IF NOT EXISTS idx_files_filepath_normalized on files (filepath_normalized); """,
+ """ CREATE UNIQUE INDEX IF NOT EXISTS idx_info_uuid on info (uuid); """,
+ """ CREATE UNIQUE INDEX IF NOT EXISTS idx_exifdata_filename on exifdata (filepath_normalized); """,
+ """ CREATE UNIQUE INDEX IF NOT EXISTS idx_edited_filename on edited (filepath_normalized);""",
+ """ CREATE UNIQUE INDEX IF NOT EXISTS idx_converted_filename on converted (filepath_normalized);""",
+ """ CREATE UNIQUE INDEX IF NOT EXISTS idx_sidecar_filename on sidecar (filepath_normalized);""",
+ """ CREATE UNIQUE INDEX IF NOT EXISTS idx_detected_text on detected_text (uuid);""",
+ ]
+ # create the tables if needed
+ try:
+ c = conn.cursor()
+ for cmd in sql_commands:
+ c.execute(cmd)
+ c.execute(
+ "INSERT INTO version(osxphotos, exportdb) VALUES (?, ?);",
+ (__version__, OSXPHOTOS_EXPORTDB_VERSION),
+ )
+ c.execute("INSERT INTO about(about) VALUES (?);", (OSXPHOTOS_ABOUT_STRING,))
+ conn.commit()
+ except Error as e:
+ logging.warning(e)
+
+ # perform needed migrations
+ if version[1] < "4.3":
+ self._migrate_normalized_filepath(conn)
+
+ if version[1] < "5.0":
+ self._migrate_4_3_to_5_0(conn)
+
+ if version[1] < "6.0":
+ # create export_data table
+ self._migrate_5_0_to_6_0(conn)
+
+ conn.execute("VACUUM;")
+ conn.commit()
+
+ def __del__(self):
+ """ensure the database connection is closed"""
+ try:
+ self._conn.close()
+ except:
+ pass
+
+ def _insert_run_info(self):
+ dt = datetime.datetime.utcnow().isoformat()
+ python_path = sys.executable
+ cmd = sys.argv[0]
+ args = " ".join(sys.argv[1:]) if len(sys.argv) > 1 else ""
+ cwd = os.getcwd()
+ conn = self._conn
+ try:
+ c = conn.cursor()
+ c.execute(
+ "INSERT INTO runs (datetime, python_path, script_name, args, cwd) VALUES (?, ?, ?, ?, ?)",
+ (dt, python_path, cmd, args, cwd),
+ )
+
+ conn.commit()
+ except Error as e:
+ logging.warning(e)
+
+ def _relative_filepath(self, filepath: Union[str, pathlib.Path]) -> str:
+ """return filepath relative to self._path"""
+ return str(pathlib.Path(filepath).relative_to(self._path))
+
+ def _normalize_filepath(self, filepath: Union[str, pathlib.Path]) -> str:
+ """normalize filepath for unicode, lower case"""
+ return normalize_fs_path(str(filepath)).lower()
+
+ def _normalize_filepath_relative(self, filepath: Union[str, pathlib.Path]) -> str:
+ """normalize filepath for unicode, relative path (to export dir), lower case"""
+ filepath = self._relative_filepath(filepath)
+ return normalize_fs_path(str(filepath)).lower()
+
+ def _migrate_normalized_filepath(self, conn):
+ """Fix all filepath_normalized columns for unicode normalization"""
+ # Prior to database version 4.3, filepath_normalized was not normalized for unicode
+ c = conn.cursor()
+ migration_sql = [
+ """ CREATE TABLE IF NOT EXISTS files_migrate (
+ id INTEGER PRIMARY KEY,
+ filepath TEXT NOT NULL,
+ filepath_normalized TEXT NOT NULL,
+ uuid TEXT,
+ orig_mode INTEGER,
+ orig_size INTEGER,
+ orig_mtime REAL,
+ exif_mode INTEGER,
+ exif_size INTEGER,
+ exif_mtime REAL,
+ UNIQUE(filepath_normalized)
+ ); """,
+ """ INSERT INTO files_migrate SELECT * FROM files;""",
+ """ DROP TABLE files;""",
+ """ ALTER TABLE files_migrate RENAME TO files;""",
+ ]
+ for sql in migration_sql:
+ c.execute(sql)
+ conn.commit()
+
+ for table in ["converted", "edited", "exifdata", "files", "sidecar"]:
+ old_values = c.execute(
+ f"SELECT filepath_normalized, id FROM {table}"
+ ).fetchall()
+ new_values = [
+ (self._normalize_filepath(filepath_normalized), id_)
+ for filepath_normalized, id_ in old_values
+ ]
+ c.executemany(
+ f"UPDATE {table} SET filepath_normalized=? WHERE id=?", new_values
+ )
+ conn.commit()
+
+ def _migrate_4_3_to_5_0(self, conn):
+ """Migrate database from version 4.3 to 5.0"""
+ try:
+ c = conn.cursor()
+ # add metadata column to files to support --force-update
+ c.execute("ALTER TABLE files ADD COLUMN metadata TEXT;")
+ conn.commit()
+ except Error as e:
+ logging.warning(e)
+
+ def _migrate_5_0_to_6_0(self, conn):
+ try:
+ c = conn.cursor()
+
+ # add export_data table
+ c.execute(
+ """ CREATE TABLE IF NOT EXISTS export_data(
+ id INTEGER PRIMARY KEY,
+ filepath_normalized TEXT NOT NULL,
+ filepath TEXT NOT NULL,
+ uuid TEXT NOT NULL,
+ src_mode INTEGER,
+ src_size INTEGER,
+ src_mtime REAL,
+ dest_mode INTEGER,
+ dest_size INTEGER,
+ dest_mtime REAL,
+ digest TEXT,
+ exifdata JSON,
+ export_options INTEGER,
+ UNIQUE(filepath_normalized)
+ ); """,
+ )
+ c.execute(
+ """ CREATE UNIQUE INDEX IF NOT EXISTS idx_export_data_filepath_normalized on export_data (filepath_normalized); """,
+ )
+
+ # migrate data
+ c.execute(
+ """ INSERT INTO export_data (filepath_normalized, filepath, uuid) SELECT filepath_normalized, filepath, uuid FROM files;""",
+ )
+ c.execute(
+ """ UPDATE export_data
+ SET (src_mode, src_size, src_mtime) =
+ (SELECT mode, size, mtime
+ FROM edited
+ WHERE export_data.filepath_normalized = edited.filepath_normalized);
+ """,
+ )
+ c.execute(
+ """ UPDATE export_data
+ SET (dest_mode, dest_size, dest_mtime) =
+ (SELECT orig_mode, orig_size, orig_mtime
+ FROM files
+ WHERE export_data.filepath_normalized = files.filepath_normalized);
+ """,
+ )
+ c.execute(
+ """ UPDATE export_data SET digest =
+ (SELECT metadata FROM files
+ WHERE files.filepath_normalized = export_data.filepath_normalized
+ ); """
+ )
+ c.execute(
+ """ UPDATE export_data SET exifdata =
+ (SELECT json_exifdata FROM exifdata
+ WHERE exifdata.filepath_normalized = export_data.filepath_normalized
+ ); """
+ )
+
+ # create config table
+ c.execute(
+ """ CREATE TABLE IF NOT EXISTS config (
+ id INTEGER PRIMARY KEY,
+ datetime TEXT,
+ config TEXT
+ ); """
+ )
+
+ # create photoinfo table
+ c.execute(
+ """ CREATE TABLE IF NOT EXISTS photoinfo (
+ id INTEGER PRIMARY KEY,
+ uuid TEXT NOT NULL,
+ photoinfo JSON,
+ UNIQUE(uuid)
+ ); """
+ )
+ c.execute(
+ """CREATE UNIQUE INDEX IF NOT EXISTS idx_photoinfo_uuid on photoinfo (uuid);"""
+ )
+ c.execute(
+ """ INSERT INTO photoinfo (uuid, photoinfo) SELECT uuid, json_info FROM info;"""
+ )
+
+ # drop indexes no longer needed
+ c.execute("DROP INDEX IF EXISTS idx_files_filepath_normalized;")
+ c.execute("DROP INDEX IF EXISTS idx_exifdata_filename;")
+ c.execute("DROP INDEX IF EXISTS idx_edited_filename;")
+ c.execute("DROP INDEX IF EXISTS idx_converted_filename;")
+ c.execute("DROP INDEX IF EXISTS idx_sidecar_filename;")
+ c.execute("DROP INDEX IF EXISTS idx_detected_text;")
+
+ # drop tables no longer needed
+ c.execute("DROP TABLE IF EXISTS files;")
+ c.execute("DROP TABLE IF EXISTS info;")
+ c.execute("DROP TABLE IF EXISTS exifdata;")
+ c.execute("DROP TABLE IF EXISTS edited;")
+ c.execute("DROP TABLE IF EXISTS converted;")
+ c.execute("DROP TABLE IF EXISTS sidecar;")
+ c.execute("DROP TABLE IF EXISTS detected_text;")
+
+ conn.commit()
+ except Error as e:
+ logging.warning(e)
+
+ def _perform_db_maintenace(self, conn):
+ """Perform database maintenance"""
+ try:
+ c = conn.cursor()
+ c.execute(
+ """DELETE FROM config
+ WHERE id < (
+ SELECT MIN(id)
+ FROM (SELECT id FROM config ORDER BY id DESC LIMIT 9)
+ );
+ """
+ )
+ conn.commit()
+ except Error as e:
+ logging.warning(e)
+
+
+class ExportDBInMemory(ExportDB):
+ """In memory version of ExportDB
+ Copies the on-disk database into memory so it may be operated on without
+ modifying the on-disk version
+ """
+
+ def __init__(self, dbfile: str, export_dir: str):
+ """ "Initialize ExportDBInMemory
+
+ Args:
+ dbfile (str): path to database file
+ export_dir (str): path to export directory
+ write_back (bool): whether to write changes back to disk when closing; if False (default), changes are not written to disk
+ """
+ self._dbfile = dbfile or f"./{OSXPHOTOS_EXPORT_DB}"
+ # export_dir is required as all files referenced by get_/set_uuid_for_file will be converted to
+ # relative paths to this path
+ # this allows the entire export tree to be moved to a new disk/location
+ # whilst preserving the UUID to filename mapping
+ self._path = export_dir
+ self._conn = self._open_export_db(self._dbfile)
+ self._insert_run_info()
+
+ def write_to_disk(self):
+ """Write changes from in-memory database back to disk"""
+
+ # dump the database
+ conn = self._conn
+ conn.commit()
+ dbdump = self._dump_db(conn)
+
+ # cleanup the old on-disk database
+ # also unlink the wal and shm files if needed
+ dbfile = pathlib.Path(self._dbfile)
+ if dbfile.exists():
+ dbfile.unlink()
+ wal = dbfile.with_suffix(".db-wal")
+ if wal.exists():
+ wal.unlink()
+ shm = dbfile.with_suffix(".db-shm")
+ if shm.exists():
+ shm.unlink()
+
+ conn_on_disk = sqlite3.connect(str(dbfile))
+ conn_on_disk.cursor().executescript(dbdump.read())
+ conn_on_disk.commit()
+ conn_on_disk.close()
+
+ def close(self):
+ """close the database connection"""
+ try:
+ if self._conn:
+ self._conn.close()
+ except Error as e:
+ logging.warning(e)
+
+ def _open_export_db(self, dbfile):
+ """open export database and return a db connection
+ returns: connection to the database
+ """
+ if not os.path.isfile(dbfile):
+ conn = self._get_db_connection()
+ if not conn:
+ raise Exception("Error getting connection to in-memory database")
+ self._create_or_migrate_db_tables(conn)
+ self.was_created = True
+ self.was_upgraded = ()
+ else:
+ conn = sqlite3.connect(dbfile)
+ dbdump = self._dump_db(conn)
+ conn.close()
+
+ # Create a database in memory and import from the dump
+ conn = sqlite3.connect(":memory:")
+ conn.cursor().executescript(dbdump.read())
+ conn.commit()
+ self.was_created = False
+ version_info = self._get_database_version(conn)
+ if version_info[1] < OSXPHOTOS_EXPORTDB_VERSION:
+ self._create_or_migrate_db_tables(conn)
+ self.was_upgraded = (version_info[1], OSXPHOTOS_EXPORTDB_VERSION)
+ else:
+ self.was_upgraded = ()
+ self.version = OSXPHOTOS_EXPORTDB_VERSION
+
+ return conn
+
+ def _get_db_connection(self):
+ """return db connection to in memory database"""
+ try:
+ conn = sqlite3.connect(":memory:")
+ except Error as e:
+ logging.warning(e)
+ conn = None
+
+ return conn
+
+ def _dump_db(self, conn: sqlite3.Connection) -> StringIO:
+ """dump sqlite db to a string buffer"""
+ dbdump = StringIO()
+ for line in conn.iterdump():
+ dbdump.write("%s\n" % line)
+ dbdump.seek(0)
+ return dbdump
+
+ def __del__(self):
+ """close the database connection"""
+ try:
+ self.close()
+ except Error as e:
+ pass
+
+
+class ExportDBTemp(ExportDBInMemory):
+ """Temporary in-memory version of ExportDB"""
+
+ def __init__(self):
+ self._temp_dir = TemporaryDirectory()
+ self._dbfile = f"{self._temp_dir.name}/{OSXPHOTOS_EXPORT_DB}"
+ self._path = self._temp_dir.name
+ self._conn = self._open_export_db(self._dbfile)
+ self._insert_run_info()
+
+ def _relative_filepath(self, filepath: Union[str, pathlib.Path]) -> str:
+ """Overrides _relative_filepath to return a path for use in the temp db"""
+ filepath = str(filepath)
+ if filepath[0] == "/":
+ return filepath[1:]
+ return filepath
+
+
+class ExportRecord:
+ """ExportRecord class"""
+
+ __slots__ = [
+ "_conn",
+ "_context_manager",
+ "_filepath_normalized",
+ ]
+
+ def __init__(self, conn, filepath_normalized):
+ self._conn = conn
+ self._filepath_normalized = filepath_normalized
+ self._context_manager = False
+
+ @property
+ def filepath(self):
+ """return filepath"""
+ conn = self._conn
+ c = conn.cursor()
+ row = c.execute(
+ "SELECT filepath FROM export_data WHERE filepath_normalized = ?;",
+ (self._filepath_normalized,),
+ ).fetchone()
+ if row:
+ return row[0]
+
+ raise ValueError(
+ f"No filepath found in database for {self._filepath_normalized}"
+ )
+
+ @property
+ def filepath_normalized(self):
+ """return filepath_normalized"""
+ return self._filepath_normalized
+
+ @property
+ def uuid(self):
+ """return uuid"""
+ conn = self._conn
+ c = conn.cursor()
+ row = c.execute(
+ "SELECT uuid FROM export_data WHERE filepath_normalized = ?;",
+ (self._filepath_normalized,),
+ ).fetchone()
+ if row:
+ return row[0]
+
+ raise ValueError(f"No uuid found in database for {self._filepath_normalized}")
+
+ @property
+ def digest(self):
+ """returns the digest value"""
+ conn = self._conn
+ c = conn.cursor()
+ row = c.execute(
+ "SELECT digest FROM export_data WHERE filepath_normalized = ?;",
+ (self._filepath_normalized,),
+ ).fetchone()
+ if row:
+ return row[0]
+
+ raise ValueError(f"No digest found in database for {self._filepath_normalized}")
+
+ @digest.setter
+ def digest(self, value):
+ """set digest value"""
+ conn = self._conn
+ c = conn.cursor()
+ c.execute(
+ "UPDATE export_data SET digest = ? WHERE filepath_normalized = ?;",
+ (value, self._filepath_normalized),
+ )
+ if not self._context_manager:
+ conn.commit()
+
+ @property
+ def exifdata(self):
+ """returns exifdata value for record"""
+ conn = self._conn
+ c = conn.cursor()
+ row = c.execute(
+ "SELECT exifdata FROM export_data WHERE filepath_normalized = ?;",
+ (self._filepath_normalized,),
+ ).fetchone()
+ if row:
+ return row[0]
+
+ raise ValueError(
+ f"No exifdata found in database for {self._filepath_normalized}"
+ )
+
+ @exifdata.setter
+ def exifdata(self, value):
+ """set exifdata value"""
+ conn = self._conn
+ c = conn.cursor()
+ c.execute(
+ "UPDATE export_data SET exifdata = ? WHERE filepath_normalized = ?;",
+ (
+ value,
+ self._filepath_normalized,
+ ),
+ )
+ if not self._context_manager:
+ conn.commit()
+
+ @property
+ def src_sig(self):
+ """return source file signature value"""
+ conn = self._conn
+ c = conn.cursor()
+ row = c.execute(
+ "SELECT src_mode, src_size, src_mtime FROM export_data WHERE filepath_normalized = ?;",
+ (self._filepath_normalized,),
+ ).fetchone()
+ if row:
+ mtime = int(row[2]) if row[2] is not None else None
+ return (row[0], row[1], mtime)
+
+ raise ValueError(
+ f"No src_sig found in database for {self._filepath_normalized}"
+ )
+
+ @src_sig.setter
+ def src_sig(self, value):
+ """set source file signature value"""
+ conn = self._conn
+ c = conn.cursor()
+ c.execute(
+ "UPDATE export_data SET src_mode = ?, src_size = ?, src_mtime = ? WHERE filepath_normalized = ?;",
+ (
+ value[0],
+ value[1],
+ value[2],
+ self._filepath_normalized,
+ ),
+ )
+ if not self._context_manager:
+ conn.commit()
+
+ @property
+ def dest_sig(self):
+ """return destination file signature"""
+ conn = self._conn
+ c = conn.cursor()
+ row = c.execute(
+ "SELECT dest_mode, dest_size, dest_mtime FROM export_data WHERE filepath_normalized = ?;",
+ (self._filepath_normalized,),
+ ).fetchone()
+ if row:
+ mtime = int(row[2]) if row[2] is not None else None
+ return (row[0], row[1], mtime)
+
+ raise ValueError(
+ f"No dest_sig found in database for {self._filepath_normalized}"
+ )
+
+ @dest_sig.setter
+ def dest_sig(self, value):
+ """set destination file signature"""
+ conn = self._conn
+ c = conn.cursor()
+ c.execute(
+ "UPDATE export_data SET dest_mode = ?, dest_size = ?, dest_mtime = ? WHERE filepath_normalized = ?;",
+ (
+ value[0],
+ value[1],
+ value[2],
+ self._filepath_normalized,
+ ),
+ )
+ if not self._context_manager:
+ conn.commit()
+
+ @property
+ def photoinfo(self):
+ """Returns info value"""
+ conn = self._conn
+ c = conn.cursor()
+ row = c.execute(
+ "SELECT photoinfo from photoinfo where uuid = ?;",
+ (self.uuid,),
+ ).fetchone()
+ return row[0] if row else None
+
+ @photoinfo.setter
+ def photoinfo(self, value):
+ """Sets info value"""
+ conn = self._conn
+ c = conn.cursor()
+ c.execute(
+ "INSERT OR REPLACE INTO photoinfo (uuid, photoinfo) VALUES (?, ?);",
+ (self.uuid, value),
+ )
+ if not self._context_manager:
+ conn.commit()
+
+ @property
+ def export_options(self):
+ """Get export_options value"""
+ conn = self._conn
+ c = conn.cursor()
+ row = c.execute(
+ "SELECT export_options from export_data where filepath_normalized = ?;",
+ (self._filepath_normalized,),
+ ).fetchone()
+ return row[0] if row else None
+
+ @export_options.setter
+ def export_options(self, value):
+ """Set export_options value"""
+ conn = self._conn
+ c = conn.cursor()
+ c.execute(
+ "UPDATE export_data SET export_options = ? WHERE filepath_normalized = ?;",
+ (value, self._filepath_normalized),
+ )
+ if not self._context_manager:
+ conn.commit()
+
+ def asdict(self):
+ """Return dict of self"""
+ exifdata = json.loads(self.exifdata) if self.exifdata else None
+ photoinfo = json.loads(self.photoinfo) if self.photoinfo else None
+ return {
+ "filepath": self.filepath,
+ "filepath_normalized": self.filepath_normalized,
+ "uuid": self.uuid,
+ "digest": self.digest,
+ "src_sig": self.src_sig,
+ "dest_sig": self.dest_sig,
+ "export_options": self.export_options,
+ "exifdata": exifdata,
+ "photoinfo": photoinfo,
+ }
+
+ def __enter__(self):
+ self._context_manager = True
+ return self
+
+ def __exit__(self, exc_type, exc_value, traceback):
+ if exc_type:
+ self._conn.rollback()
+ else:
+ self._conn.commit()
+ self._context_manager = False
+
+""" FileUtil class with methods for copy, hardlink, unlink, etc. """
+
+import os
+import pathlib
+import stat
+import tempfile
+import typing as t
+from abc import ABC, abstractmethod
+from tempfile import TemporaryDirectory
+
+import Foundation
+
+from .imageconverter import ImageConverter
+
+__all__ = ["FileUtilABC", "FileUtilMacOS", "FileUtil", "FileUtilNoOp"]
+
+
+class FileUtilABC(ABC):
+ """Abstract base class for FileUtil"""
+
+ @classmethod
+ @abstractmethod
+ def hardlink(cls, src, dest):
+ pass
+
+ @classmethod
+ @abstractmethod
+ def copy(cls, src, dest, norsrc=False):
+ pass
+
+ @classmethod
+ @abstractmethod
+ def unlink(cls, dest):
+ pass
+
+ @classmethod
+ @abstractmethod
+ def rmdir(cls, dest):
+ pass
+
+ @classmethod
+ @abstractmethod
+ def utime(cls, path, times):
+ pass
+
+ @classmethod
+ @abstractmethod
+ def cmp(cls, file1, file2, mtime1=None):
+ pass
+
+ @classmethod
+ @abstractmethod
+ def cmp_file_sig(cls, file1, file2):
+ pass
+
+ @classmethod
+ @abstractmethod
+ def file_sig(cls, file1):
+ pass
+
+ @classmethod
+ @abstractmethod
+ def convert_to_jpeg(cls, src_file, dest_file, compression_quality=1.0):
+ pass
+
+ @classmethod
+ @abstractmethod
+ def rename(cls, src, dest):
+ pass
+
+ @classmethod
+ @abstractmethod
+ def tmpdir(
+ cls, prefix: t.Optional[str] = None, dir: t.Optional[str] = None
+ ) -> tempfile.TemporaryDirectory:
+ pass
+
+
+class FileUtilMacOS(FileUtilABC):
+ """Various file utilities"""
+
+ @classmethod
+ def hardlink(cls, src, dest):
+ """Hardlinks a file from src path to dest path
+ src: source path as string
+ dest: destination path as string
+ Raises exception if linking 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 FileNotFoundError("src file does not appear to exist", src)
+
+ try:
+ os.link(src, dest)
+ except Exception as e:
+ raise e from e
+
+ @classmethod
+ def copy(cls, src, dest):
+ """Copies a file from src path to dest path
+
+ Args:
+ src: source path as string; must be a valid file path
+ dest: destination path as string
+ dest may be either directory or file; in either case, src file must not exist in dest
+ Note: src and dest may be either a string or a pathlib.Path object
+
+ Returns:
+ True if copy succeeded
+
+ Raises:
+ OSError if copy fails
+ TypeError if either path is None
+ """
+ if not isinstance(src, pathlib.Path):
+ src = pathlib.Path(src)
+
+ if not isinstance(dest, pathlib.Path):
+ dest = pathlib.Path(dest)
+
+ if dest.is_dir():
+ dest /= src.name
+
+ filemgr = Foundation.NSFileManager.defaultManager()
+ error = filemgr.copyItemAtPath_toPath_error_(str(src), str(dest), None)
+ # error is a tuple of (bool, error_string)
+ # error[0] is True if copy succeeded
+ if not error[0]:
+ raise OSError(error[1])
+ return True
+
+ @classmethod
+ def unlink(cls, filepath):
+ """unlink filepath; if it's pathlib.Path, use Path.unlink, otherwise use os.unlink"""
+ if isinstance(filepath, pathlib.Path):
+ filepath.unlink()
+ else:
+ os.unlink(filepath)
+
+ @classmethod
+ def rmdir(cls, dirpath):
+ """remove directory filepath; dirpath must be empty"""
+ if isinstance(dirpath, pathlib.Path):
+ dirpath.rmdir()
+ else:
+ os.rmdir(dirpath)
+
+ @classmethod
+ def utime(cls, path, times):
+ """Set the access and modified time of path."""
+ os.utime(path, times=times)
+
+ @classmethod
+ def cmp(cls, f1, f2, mtime1=None):
+ """Does shallow compare (file signatures) of f1 to file f2.
+ Arguments:
+ f1 -- File name
+ f2 -- File name
+ mtime1 -- optional, pass alternate file modification timestamp for f1; will be converted to int
+
+ Return value:
+ True if the file signatures as returned by stat are the same, False otherwise.
+ Does not do a byte-by-byte comparison.
+ """
+
+ s1 = cls._sig(os.stat(f1))
+ if mtime1 is not None:
+ s1 = (s1[0], s1[1], int(mtime1))
+ s2 = cls._sig(os.stat(f2))
+ if s1[0] != stat.S_IFREG or s2[0] != stat.S_IFREG:
+ return False
+ return s1 == s2
+
+ @classmethod
+ def cmp_file_sig(cls, f1, s2):
+ """Compare file f1 to signature s2.
+ Arguments:
+ f1 -- File name
+ s2 -- stats as returned by _sig
+
+ Return value:
+ True if the files are the same, False otherwise.
+ """
+
+ if not s2:
+ return False
+
+ s1 = cls._sig(os.stat(f1))
+ if s1[0] != stat.S_IFREG or s2[0] != stat.S_IFREG:
+ return False
+ return s1 == s2
+
+ @classmethod
+ def file_sig(cls, f1):
+ """return os.stat signature for file f1 as tuple of (mode, size, mtime)"""
+ return cls._sig(os.stat(f1))
+
+ @classmethod
+ def convert_to_jpeg(cls, src_file, dest_file, compression_quality=1.0):
+ """converts image file src_file to jpeg format as dest_file
+
+ Args:
+ src_file: image file to convert
+ dest_file: destination path to write converted file to
+ compression quality: JPEG compression quality in range 0.0 <= compression_quality <= 1.0; default 1.0 (best quality)
+
+ Returns:
+ True if success, otherwise False
+ """
+ converter = ImageConverter()
+ return converter.write_jpeg(
+ src_file, dest_file, compression_quality=compression_quality
+ )
+
+ @classmethod
+ def rename(cls, src, dest):
+ """Copy src to dest
+
+ Args:
+ src: path to source file
+ dest: path to destination file
+
+ Returns:
+ Name of renamed file (dest)
+
+ """
+ os.rename(str(src), str(dest))
+ return dest
+
+ @classmethod
+ def tmpdir(
+ cls, prefix: t.Optional[str] = None, dir: t.Optional[str] = None
+ ) -> tempfile.TemporaryDirectory:
+ """Securely creates a temporary directory using the same rules as mkdtemp().
+ The resulting object can be used as a context manager.
+ On completion of the context or destruction of the temporary directory object,
+ the newly created temporary directory and all its contents are removed from the filesystem.
+ """
+ return TemporaryDirectory(prefix=prefix, dir=dir)
+
+ @staticmethod
+ def _sig(st):
+ """return tuple of (mode, size, mtime) of file based on os.stat
+ Args:
+ st: os.stat signature
+ """
+ # use int(st.st_mtime) because ditto does not copy fractional portion of mtime
+ return (stat.S_IFMT(st.st_mode), st.st_size, int(st.st_mtime))
+
+
+
+
+
+[docs]class FileUtilNoOp(FileUtil):
+ """No-Op implementation of FileUtil for testing / dry-run mode
+ all methods with exception of tmpdir, cmp, cmp_file_sig and file_cmp are no-op
+ cmp and cmp_file_sig functions as FileUtil methods do
+ file_cmp returns mock data
+ """
+
+ @staticmethod
+ def noop(*args):
+ pass
+
+ def __new__(cls, verbose=None):
+ if verbose:
+ if callable(verbose):
+ cls.verbose = verbose
+ else:
+ raise ValueError(f"verbose {verbose} not callable")
+ return super(FileUtilNoOp, cls).__new__(cls)
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs] @classmethod
+ def convert_to_jpeg(cls, src_file, dest_file, compression_quality=1.0):
+ pass
+
+
+
+[docs] @classmethod
+ def tmpdir(
+ cls, prefix: t.Optional[str] = None, dir: t.Optional[str] = None
+ ) -> tempfile.TemporaryDirectory:
+ """Securely creates a temporary directory using the same rules as mkdtemp().
+ The resulting object can be used as a context manager.
+ On completion of the context or destruction of the temporary directory object,
+ the newly created temporary directory and all its contents are removed from the filesystem.
+ """
+ return TemporaryDirectory(prefix=prefix, dir=dir)
+
+__all__ = ["MomentInfo"]
+"""MomentInfo class with details about photo moments."""
+
+
+[docs]class MomentInfo:
+ """Info about a photo moment"""
+
+ def __init__(self, db, moment_pk):
+ """Initialize with a moment PK; returns None if PK not found."""
+ self._db = db
+ self._pk = moment_pk
+
+ self._moment = self._db._db_moment_pk.get(moment_pk)
+ if not self._moment:
+ raise ValueError(f"No moment with PK {moment_pk}")
+
+ @property
+ def pk(self):
+ """Primary key of the moment."""
+ return self._pk
+
+ @property
+ def location(self):
+ """Location of the moment."""
+ return (self._moment.get("latitude"), self._moment.get("longitude"))
+
+ @property
+ def title(self):
+ """Title of the moment."""
+ return self._moment.get("title")
+
+ @property
+ def subtitle(self):
+ """Subtitle of the moment."""
+ return self._moment.get("subtitle")
+
+ @property
+ def start_date(self):
+ """Start date of the moment."""
+ return self._moment.get("startDate")
+
+ @property
+ def end_date(self):
+ """Stop date of the moment."""
+ return self._moment.get("endDate")
+
+ @property
+ def date(self):
+ """Date of the moment."""
+ return self._moment.get("representativeDate")
+
+ @property
+ def modification_date(self):
+ """Modification date of the moment."""
+ return self._moment.get("modificationDate")
+
+ @property
+ def photos(self):
+ """All photos in this moment"""
+ try:
+ return self._photos
+ except AttributeError:
+ photo_uuids = [
+ uuid
+ for uuid, photo in self._db._dbphotos.items()
+ if photo["momentID"] == self._pk
+ ]
+
+ self._photos = self._db.photos_by_uuid(photo_uuids)
+ return self._photos
+
+""" PhotoInfo and FaceInfo classes to expose info about persons and faces in the Photos library """
+
+import json
+import logging
+import math
+
+from collections import namedtuple
+
+__all__ = ["PersonInfo", "FaceInfo", "rotate_image_point"]
+
+MWG_RS_Area = namedtuple("MWG_RS_Area", ["x", "y", "h", "w"])
+MPRI_Reg_Rect = namedtuple("MPRI_Reg_Rect", ["x", "y", "h", "w"])
+
+
+[docs]class PersonInfo:
+ """Info about a person in the Photos library"""
+
+ def __init__(self, db=None, pk=None):
+ """Creates a new PersonInfo instance
+
+ Arguments:
+ db: instance of PhotosDB object
+ pk: primary key value of person to initialize PersonInfo with
+
+ Returns:
+ PersonInfo instance
+ """
+ self._db = db
+ self._pk = pk
+
+ person = self._db._dbpersons_pk[pk]
+ self.uuid = person["uuid"]
+ self.name = person["fullname"]
+ self.display_name = person["displayname"]
+ self.keyface = person["keyface"]
+ self.facecount = person["facecount"]
+
+ @property
+ def keyphoto(self):
+ try:
+ return self._keyphoto
+ except AttributeError:
+ person = self._db._dbpersons_pk[self._pk]
+ if person["photo_uuid"]:
+ try:
+ key_photo = self._db.get_photo(person["photo_uuid"])
+ except IndexError:
+ key_photo = None
+ else:
+ key_photo = None
+ self._keyphoto = key_photo
+ return self._keyphoto
+
+ @property
+ def photos(self):
+ """Returns list of PhotoInfo objects associated with this person"""
+ return self._db.photos_by_uuid(self._db._dbfaces_pk[self._pk])
+
+ @property
+ def face_info(self):
+ """Returns a list of FaceInfo objects associated with this person sorted by quality score
+ Highest quality face is result[0] and lowest quality face is result[n]
+ """
+ try:
+ faces = self._db._db_faceinfo_person[self._pk]
+ return sorted(
+ [FaceInfo(db=self._db, pk=face) for face in faces],
+ key=lambda face: face.quality,
+ reverse=True,
+ )
+ except KeyError:
+ # no faces
+ return []
+
+[docs] def asdict(self):
+ """Returns dictionary representation of class instance"""
+ keyphoto = self.keyphoto.uuid if self.keyphoto is not None else None
+ return {
+ "uuid": self.uuid,
+ "name": self.name,
+ "displayname": self.display_name,
+ "keyface": self.keyface,
+ "facecount": self.facecount,
+ "keyphoto": keyphoto,
+ }
+
+[docs] def json(self):
+ """Returns JSON representation of class instance"""
+ return json.dumps(self.asdict())
+
+ def __str__(self):
+ return f"PersonInfo(name={self.name}, display_name={self.display_name}, uuid={self.uuid}, facecount={self.facecount})"
+
+ def __eq__(self, other):
+ if not isinstance(other, type(self)):
+ return False
+
+ return all(
+ getattr(self, field) == getattr(other, field) for field in ["_db", "_pk"]
+ )
+
+ def __ne__(self, other):
+ return not self.__eq__(other)
+
+
+class FaceInfo:
+ """Info about a face in the Photos library"""
+
+ def __init__(self, db=None, pk=None):
+ """Creates a new FaceInfo instance
+
+ Arguments:
+ db: instance of PhotosDB object
+ pk: primary key value of face to init the object with
+
+ Returns:
+ FaceInfo instance
+ """
+ self._db = db
+ self._pk = pk
+
+ face = self._db._db_faceinfo_pk[pk]
+ self._info = face
+ self.uuid = face["uuid"]
+ self.name = face["fullname"]
+ self.asset_uuid = face["asset_uuid"]
+ self._person_pk = face["person"]
+ self.center_x = face["centerx"]
+ self.center_y = face["centery"]
+ self.mouth_x = face["mouthx"]
+ self.mouth_y = face["mouthy"]
+ self.left_eye_x = face["lefteyex"]
+ self.left_eye_y = face["lefteyey"]
+ self.right_eye_x = face["righteyex"]
+ self.right_eye_y = face["righteyey"]
+ self.size = face["size"]
+ self.quality = face["quality"]
+ self.source_width = face["sourcewidth"]
+ self.source_height = face["sourceheight"]
+ self.has_smile = face["has_smile"]
+ self.left_eye_closed = face["left_eye_closed"]
+ self.right_eye_closed = face["right_eye_closed"]
+ self.manual = face["manual"]
+ self.face_type = face["facetype"]
+ self.age_type = face["agetype"]
+ # self.bald_type = face["baldtype"]
+ self.eye_makeup_type = face["eyemakeuptype"]
+ self.eye_state = face["eyestate"]
+ self.facial_hair_type = face["facialhairtype"]
+ self.gender_type = face["gendertype"]
+ self.glasses_type = face["glassestype"]
+ self.hair_color_type = face["haircolortype"]
+ self.intrash = face["intrash"]
+ self.lip_makeup_type = face["lipmakeuptype"]
+ self.smile_type = face["smiletype"]
+
+ @property
+ def center(self):
+ """Coordinates, in PIL format, for center of face
+
+ Returns:
+ tuple of coordinates in form (x, y)
+ """
+ return self._make_point((self.center_x, self.center_y))
+
+ @property
+ def size_pixels(self):
+ """Size of face in pixels (centered around center_x, center_y)
+
+ Returns:
+ size, in int pixels, of a circle drawn around the center of the face
+ """
+ photo = self.photo
+ size_reference = photo.width if photo.width > photo.height else photo.height
+ return self.size * size_reference
+
+ @property
+ def mouth(self):
+ """Coordinates, in PIL format, for mouth position
+
+ Returns:
+ tuple of coordinates in form (x, y)
+ """
+ return self._make_point_with_rotation((self.mouth_x, self.mouth_y))
+
+ @property
+ def left_eye(self):
+ """Coordinates, in PIL format, for left eye position
+
+ Returns:
+ tuple of coordinates in form (x, y)
+ """
+ return self._make_point_with_rotation((self.left_eye_x, self.left_eye_y))
+
+ @property
+ def right_eye(self):
+ """Coordinates, in PIL format, for right eye position
+
+ Returns:
+ tuple of coordinates in form (x, y)
+ """
+ return self._make_point_with_rotation((self.right_eye_x, self.right_eye_y))
+
+ @property
+ def person_info(self):
+ """PersonInfo instance for person associated with this face"""
+ try:
+ return self._person
+ except AttributeError:
+ self._person = PersonInfo(db=self._db, pk=self._person_pk)
+ return self._person
+
+ @property
+ def photo(self):
+ """PhotoInfo instance associated with this face"""
+ try:
+ return self._photo
+ except AttributeError:
+ self._photo = self._db.get_photo(self.asset_uuid)
+ if self._photo is None:
+ logging.warning(f"Could not get photo for uuid: {self.asset_uuid}")
+ return self._photo
+
+ @property
+ def mwg_rs_area(self):
+ """Get coordinates for Metadata Working Group Region Area.
+
+ Returns:
+ MWG_RS_Area named tuple with x, y, h, w where:
+ x = stArea:x
+ y = stArea:y
+ h = stArea:h
+ w = stArea:w
+
+ Reference:
+ https://photo.stackexchange.com/questions/106410/how-does-xmp-define-the-face-region
+ """
+ x, y = self.center_x, self.center_y
+ x, y = self._fix_orientation((x, y))
+
+ if self.photo.orientation in [5, 6, 7, 8]:
+ w = self.size_pixels / self.photo.height
+ h = self.size_pixels / self.photo.width
+ else:
+ h = self.size_pixels / self.photo.height
+ w = self.size_pixels / self.photo.width
+
+ return MWG_RS_Area(x, y, h, w)
+
+ @property
+ def mpri_reg_rect(self):
+ """Get coordinates for Microsoft Photo Region Rectangle.
+
+ Returns:
+ MPRI_Reg_Rect named tuple with x, y, h, w where:
+ x = x coordinate of top left corner of rectangle
+ y = y coordinate of top left corner of rectangle
+ h = height of rectangle
+ w = width of rectangle
+
+ Reference:
+ https://docs.microsoft.com/en-us/windows/win32/wic/-wic-people-tagging
+ """
+ x, y = self.center_x, self.center_y
+ x, y = self._fix_orientation((x, y))
+
+ if self.photo.orientation in [5, 6, 7, 8]:
+ w = self.size_pixels / self.photo.width
+ h = self.size_pixels / self.photo.height
+ x = x - self.size_pixels / self.photo.height / 2
+ y = y - self.size_pixels / self.photo.width / 2
+ else:
+ h = self.size_pixels / self.photo.width
+ w = self.size_pixels / self.photo.height
+ x = x - self.size_pixels / self.photo.width / 2
+ y = y - self.size_pixels / self.photo.height / 2
+
+ return MPRI_Reg_Rect(x, y, h, w)
+
+ def face_rect(self):
+ """Get face rectangle coordinates for current version of the associated image
+ If image has been edited, rectangle applies to edited version, otherwise original version
+ Coordinates in format and reference frame used by PIL
+
+ Returns:
+ list [(x0, x1), (y0, y1)] of coordinates in reference frame used by PIL
+ """
+ photo = self.photo
+ size_reference = photo.width if photo.width > photo.height else photo.height
+ radius = (self.size / 2) * size_reference
+ x, y = self._make_point((self.center_x, self.center_y))
+ x0, y0 = x - radius, y - radius
+ x1, y1 = x + radius, y + radius
+ return [(x0, y0), (x1, y1)]
+
+ def roll_pitch_yaw(self):
+ """Roll, pitch, yaw of face in radians as tuple"""
+ info = self._info
+ roll = 0 if info["roll"] is None else info["roll"]
+ pitch = 0 if info["pitch"] is None else info["pitch"]
+ yaw = 0 if info["yaw"] is None else info["yaw"]
+
+ return (roll, pitch, yaw)
+
+ @property
+ def roll(self):
+ """Return roll angle in radians of the face region"""
+ roll, _, _ = self.roll_pitch_yaw()
+ return roll
+
+ @property
+ def pitch(self):
+ """Return pitch angle in radians of the face region"""
+ _, pitch, _ = self.roll_pitch_yaw()
+ return pitch
+
+ @property
+ def yaw(self):
+ """Return yaw angle in radians of the face region"""
+ _, _, yaw = self.roll_pitch_yaw()
+ return yaw
+
+ def _fix_orientation(self, xy):
+ """Translate an (x, y) tuple based on image orientation
+
+ Arguments:
+ xy: tuple of (x, y) coordinates for point to translate
+ in format used by Photos (percent of height/width)
+
+ Returns:
+ (x, y) tuple of translated coordinates
+ """
+ # Reference: https://github.com/neilpa/phace/blob/7594776480505d0c389688a42099c94ac5d34f3f/cmd/phace/draw.go#L79-L94
+
+ orientation = self.photo.orientation
+ x, y = xy
+ if orientation == 1:
+ y = 1.0 - y
+ elif orientation == 2:
+ y = 1.0 - y
+ x = 1.0 - x
+ elif orientation == 3:
+ x = 1.0 - x
+ elif orientation == 4:
+ pass
+ elif orientation == 5:
+ x, y = 1.0 - y, x
+ elif orientation == 6:
+ x, y = 1.0 - y, 1.0 - x
+ elif orientation == 7:
+ x, y = y, x
+ y = 1.0 - y
+ elif orientation == 8:
+ x, y = y, x
+ elif orientation == 0:
+ # set by osxphotos if adjusted orientation cannot be read, assume it's 1
+ y = 1.0 - y
+ else:
+ logging.warning(f"Unhandled orientation: {orientation}")
+
+ return (x, y)
+
+ def _make_point(self, xy):
+ """Translate an (x, y) tuple based on image orientation
+ and convert to image coordinates
+
+ Arguments:
+ xy: tuple of (x, y) coordinates for point to translate
+ in format used by Photos (percent of height/width)
+
+ Returns:
+ (x, y) tuple of translated coordinates in pixels in PIL format/reference frame
+ """
+ # Reference: https://github.com/neilpa/phace/blob/7594776480505d0c389688a42099c94ac5d34f3f/cmd/phace/draw.go#L79-L94
+
+ orientation = self.photo.orientation
+ x, y = self._fix_orientation(xy)
+ dx = self.photo.width
+ dy = self.photo.height
+ if orientation in [5, 6, 7, 8]:
+ dx, dy = dy, dx
+ return (int(x * dx), int(y * dy))
+
+ def _make_point_with_rotation(self, xy):
+ """Translate an (x, y) tuple based on image orientation and rotation
+ and convert to image coordinates
+
+ Arguments:
+ xy: tuple of (x, y) coordinates for point to translate
+ in format used by Photos (percent of height/width)
+
+ Returns:
+ (x, y) tuple of translated coordinates in pixels in PIL format/reference frame
+ """
+
+ # convert to image coordinates
+ x, y = self._make_point(xy)
+
+ # rotate about center
+ xmid, ymid = self.center
+ roll, _, _ = self.roll_pitch_yaw()
+ xr, yr = rotate_image_point(x, y, xmid, ymid, roll)
+
+ return (int(xr), int(yr))
+
+ def asdict(self):
+ """Returns dict representation of class instance"""
+ roll, pitch, yaw = self.roll_pitch_yaw()
+ return {
+ "_pk": self._pk,
+ "uuid": self.uuid,
+ "name": self.name,
+ "asset_uuid": self.asset_uuid,
+ "_person_pk": self._person_pk,
+ "center_x": self.center_x,
+ "center_y": self.center_y,
+ "center": self.center,
+ "mouth_x": self.mouth_x,
+ "mouth_y": self.mouth_y,
+ "mouth": self.mouth,
+ "left_eye_x": self.left_eye_x,
+ "left_eye_y": self.left_eye_y,
+ "left_eye": self.left_eye,
+ "right_eye_x": self.right_eye_x,
+ "right_eye_y": self.right_eye_y,
+ "right_eye": self.right_eye,
+ "size": self.size,
+ "face_rect": self.face_rect(),
+ "mpri_reg_rect": self.mpri_reg_rect._asdict(),
+ "mwg_rs_area": self.mwg_rs_area._asdict(),
+ "roll": roll,
+ "pitch": pitch,
+ "yaw": yaw,
+ "quality": self.quality,
+ "source_width": self.source_width,
+ "source_height": self.source_height,
+ "has_smile": self.has_smile,
+ "left_eye_closed": self.left_eye_closed,
+ "right_eye_closed": self.right_eye_closed,
+ "manual": self.manual,
+ "face_type": self.face_type,
+ "age_type": self.age_type,
+ # "bald_type": self.bald_type,
+ "eye_makeup_type": self.eye_makeup_type,
+ "eye_state": self.eye_state,
+ "facial_hair_type": self.facial_hair_type,
+ "gender_type": self.gender_type,
+ "glasses_type": self.glasses_type,
+ "hair_color_type": self.hair_color_type,
+ "intrash": self.intrash,
+ "lip_makeup_type": self.lip_makeup_type,
+ "smile_type": self.smile_type,
+ }
+
+ def json(self):
+ """Return JSON representation of FaceInfo instance"""
+ return json.dumps(self.asdict())
+
+ def __str__(self):
+ return f"FaceInfo(uuid={self.uuid}, center_x={self.center_x}, center_y = {self.center_y}, size={self.size}, person={self.name}, asset_uuid={self.asset_uuid})"
+
+ def __repr__(self):
+ return f"FaceInfo(db={self._db}, pk={self._pk})"
+
+ def __eq__(self, other):
+ if not isinstance(other, type(self)):
+ return False
+
+ return all(
+ getattr(self, field) == getattr(other, field) for field in ["_db", "_pk"]
+ )
+
+ def __ne__(self, other):
+ return not self.__eq__(other)
+
+
+def rotate_image_point(x, y, xmid, ymid, angle):
+ """rotate image point about xm, ym by angle in radians
+
+ Arguments:
+ x: x coordinate of point to rotate
+ y: y coordinate of point to rotate
+ xmid: x coordinate of center point to rotate about
+ ymid: y coordinate of center point to rotate about
+ angle: angle in radians about which to coordinate,
+ counter-clockwise is positive
+
+ Returns:
+ tuple of rotated points (xr, yr)
+ """
+ # translate point relative to the mid point
+ x = x - xmid
+ y = y - ymid
+
+ # rotate by angle and translate back
+ # the photo coordinate system is downwards y is positive so
+ # need to adjust the rotation accordingly
+ cos_angle = math.cos(angle)
+ sin_angle = math.sin(angle)
+ xr = x * cos_angle + y * sin_angle + xmid
+ yr = -x * sin_angle + y * cos_angle + ymid
+
+ return (xr, yr)
+
+""" PhotoExport class to export photos
+"""
+
+import dataclasses
+import hashlib
+import json
+import logging
+import os
+import pathlib
+import re
+import tempfile
+import typing as t
+from collections import namedtuple # pylint: disable=syntax-error
+from dataclasses import asdict, dataclass
+from enum import Enum
+
+import photoscript
+from mako.template import Template
+
+from ._constants import (
+ _MAX_IPTC_KEYWORD_LEN,
+ _OSXPHOTOS_NONE_SENTINEL,
+ _TEMPLATE_DIR,
+ _UNKNOWN_PERSON,
+ _XMP_TEMPLATE_NAME,
+ _XMP_TEMPLATE_NAME_BETA,
+ DEFAULT_PREVIEW_SUFFIX,
+ LIVE_VIDEO_EXTENSIONS,
+ SIDECAR_EXIFTOOL,
+ SIDECAR_JSON,
+ SIDECAR_XMP,
+)
+from ._version import __version__
+from .datetime_utils import datetime_tz_to_utc
+from .exiftool import ExifTool, exiftool_can_write
+from .export_db import ExportDB, ExportDBTemp
+from .fileutil import FileUtil
+from .photokit import (
+ PHOTOS_VERSION_CURRENT,
+ PHOTOS_VERSION_ORIGINAL,
+ PHOTOS_VERSION_UNADJUSTED,
+ PhotoKitFetchFailed,
+ PhotoLibrary,
+)
+from .phototemplate import RenderOptions
+from .rich_utils import add_rich_markup_tag
+from .uti import get_preferred_uti_extension
+from .utils import increment_filename, lineno, list_directory
+
+__all__ = [
+ "ExportError",
+ "ExportOptions",
+ "ExportResults",
+ "PhotoExporter",
+ "hexdigest",
+ "rename_jpeg_files",
+]
+
+if t.TYPE_CHECKING:
+ from .photoinfo import PhotoInfo
+
+# retry if download_missing/use_photos_export fails the first time (which sometimes it does)
+MAX_PHOTOSCRIPT_RETRIES = 3
+
+# return values for _should_update_photo
+class ShouldUpdate(Enum):
+ NOT_IN_DATABASE = 1
+ HARDLINK_DIFFERENT_FILES = 2
+ NOT_HARDLINK_SAME_FILES = 3
+ DEST_SIG_DIFFERENT = 4
+ EXPORT_OPTIONS_DIFFERENT = 5
+ EXIFTOOL_DIFFERENT = 6
+ EDITED_SIG_DIFFERENT = 7
+ DIGEST_DIFFERENT = 8
+
+
+class ExportError(Exception):
+ """error during export"""
+
+ pass
+
+
+[docs]@dataclass
+class ExportOptions:
+ """Options class for exporting photos with export
+
+ Attributes:
+ convert_to_jpeg (bool): if True, converts non-jpeg images to jpeg
+ description_template (str): t.Optional template string that will be rendered for use as photo description
+ download_missing: (bool, default=False): if True will attempt to export photo via applescript interaction with Photos if missing (see also use_photokit, use_photos_export)
+ dry_run: (bool, default=False): set to True to run in "dry run" mode
+ edited: (bool, default=False): if True will export the edited version of the photo otherwise exports the original version
+ exiftool_flags (list of str): t.Optional list of flags to pass to exiftool when using exiftool option, e.g ["-m", "-F"]
+ exiftool: (bool, default = False): if True, will use exiftool to write metadata to export file
+ export_as_hardlink: (bool, default=False): if True, will hardlink files instead of copying them
+ export_db: (ExportDB): instance of a class that conforms to ExportDB with methods for getting/setting data related to exported files to compare update state
+ face_regions: (bool, default=True): if True, will export face regions
+ fileutil: (FileUtilABC): class that conforms to FileUtilABC with various file utilities
+ force_update: (bool, default=False): if True, will export photo if any metadata has changed but export otherwise would not be triggered (e.g. metadata changed but not using exiftool)
+ ignore_date_modified (bool): for use with sidecar and exiftool; if True, sets EXIF:ModifyDate to EXIF:DateTimeOriginal even if date_modified is set
+ ignore_signature (bool, default=False): ignore file signature when used with update (look only at filename)
+ increment (bool, 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
+ jpeg_ext (str): if set, will use this value for extension on jpegs converted to jpeg with convert_to_jpeg; if not set, uses jpeg; do not include the leading "."
+ jpeg_quality (float in range 0.0 <= jpeg_quality <= 1.0): a value of 1.0 specifies use best quality, a value of 0.0 specifies use maximum compression.
+ keyword_template (list of str): list of template strings that will be rendered as used as keywords
+ live_photo (bool, default=False): if True, will also export the associated .mov for live photos
+ location (bool): if True, include location in exported metadata
+ merge_exif_keywords (bool): if True, merged keywords found in file's exif data (requires exiftool)
+ merge_exif_persons (bool): if True, merged persons found in file's exif data (requires exiftool)
+ overwrite (bool, default=False): if True will overwrite files if they already exist
+ persons (bool): if True, include persons in exported metadata
+ preview_suffix (str): t.Optional string to append to end of filename for preview images
+ preview (bool): if True, also exports preview image
+ raw_photo (bool, default=False): if True, will also export the associated RAW photo
+ render_options (RenderOptions): t.Optional osxphotos.phototemplate.RenderOptions instance to specify options for rendering templates
+ replace_keywords (bool): if True, keyword_template replaces any keywords, otherwise it's additive
+ rich (bool): if True, will use rich markup with verbose output
+ sidecar_drop_ext (bool, default=False): if True, drops the photo's extension from sidecar filename (e.g. 'IMG_1234.json' instead of 'IMG_1234.JPG.json')
+ sidecar: bit field (int): set to one or more of `SIDECAR_XMP`, `SIDECAR_JSON`, `SIDECAR_EXIFTOOL`
+ - SIDECAR_JSON: if set will write a json sidecar with data in format readable by exiftool sidecar filename will be dest/filename.json;
+ includes exiftool tag group names (e.g. `exiftool -G -j`)
+ - SIDECAR_EXIFTOOL: if set will write a json sidecar with data in format readable by exiftool sidecar filename will be dest/filename.json;
+ does not include exiftool tag group names (e.g. `exiftool -j`)
+ - SIDECAR_XMP: if set will write an XMP sidecar with IPTC data sidecar filename will be dest/filename.xmp
+ strip (bool): if True, strip whitespace from rendered templates
+ timeout (int, default=120): timeout in seconds used with use_photos_export
+ touch_file (bool, default=False): if True, sets file's modification time upon photo date
+ update (bool, default=False): if True export will run in update mode, that is, it will not export the photo if the current version already exists in the destination
+ use_albums_as_keywords (bool, default = False): if True, will include album names in keywords when exporting metadata with exiftool or sidecar
+ use_persons_as_keywords (bool, default = False): if True, will include person names in keywords when exporting metadata with exiftool or sidecar
+ use_photos_export (bool, default=False): if True will attempt to export photo via applescript interaction with Photos even if not missing (see also use_photokit, download_missing)
+ use_photokit (bool, default=False): if True, will use photokit to export photos when use_photos_export is True
+ verbose (callable): optional callable function to use for printing verbose text during processing; if None (default), does not print output.
+ tmpdir: (str, default=None): Optional directory to use for temporary files, if None (default) uses system tmp directory
+
+ """
+
+ convert_to_jpeg: bool = False
+ description_template: t.Optional[str] = None
+ download_missing: bool = False
+ dry_run: bool = False
+ edited: bool = False
+ exiftool_flags: t.Optional[t.List] = None
+ exiftool: bool = False
+ export_as_hardlink: bool = False
+ export_db: t.Optional[ExportDB] = None
+ face_regions: bool = True
+ fileutil: t.Optional[FileUtil] = None
+ force_update: bool = False
+ ignore_date_modified: bool = False
+ ignore_signature: bool = False
+ increment: bool = True
+ jpeg_ext: t.Optional[str] = None
+ jpeg_quality: float = 1.0
+ keyword_template: t.Optional[t.List[str]] = None
+ live_photo: bool = False
+ location: bool = True
+ merge_exif_keywords: bool = False
+ merge_exif_persons: bool = False
+ overwrite: bool = False
+ persons: bool = True
+ preview_suffix: str = DEFAULT_PREVIEW_SUFFIX
+ preview: bool = False
+ raw_photo: bool = False
+ render_options: t.Optional[RenderOptions] = None
+ replace_keywords: bool = False
+ rich: bool = False
+ sidecar_drop_ext: bool = False
+ sidecar: int = 0
+ strip: bool = False
+ timeout: int = 120
+ touch_file: bool = False
+ update: bool = False
+ use_albums_as_keywords: bool = False
+ use_persons_as_keywords: bool = False
+ use_photokit: bool = False
+ use_photos_export: bool = False
+ verbose: t.Optional[t.Callable] = None
+ tmpdir: t.Optional[str] = None
+
+ def asdict(self):
+ return asdict(self)
+
+ @property
+ def bit_flags(self):
+ """Return bit flags representing options that affect export"""
+ # currently only exiftool makes a difference
+ return self.exiftool << 1
+
+
+class StagedFiles:
+ """Represents files staged for export"""
+
+ def __init__(
+ self,
+ original: t.Optional[str] = None,
+ original_live: t.Optional[str] = None,
+ edited: t.Optional[str] = None,
+ edited_live: t.Optional[str] = None,
+ preview: t.Optional[str] = None,
+ raw: t.Optional[str] = None,
+ error: t.Optional[t.List[str]] = None,
+ ):
+ self.original = original
+ self.original_live = original_live
+ self.edited = edited
+ self.edited_live = edited_live
+ self.preview = preview
+ self.raw = raw
+ self.error = error or []
+
+ # TODO: bursts?
+
+ def __ior__(self, other):
+ self.original = self.original or other.original
+ self.original_live = self.original_live or other.original_live
+ self.edited = self.edited or other.edited
+ self.edited_live = self.edited_live or other.edited_live
+ self.preview = self.preview or other.preview
+ self.raw = self.raw or other.raw
+ self.error += other.error
+ return self
+
+ def __str__(self):
+ return str(self.asdict())
+
+ def asdict(self):
+ return {
+ "original": self.original,
+ "original_live": self.original_live,
+ "edited": self.edited,
+ "edited_live": self.edited_live,
+ "preview": self.preview,
+ "raw": self.raw,
+ "error": self.error,
+ }
+
+
+[docs]class ExportResults:
+ """Results class which holds export results for export"""
+
+ def __init__(
+ self,
+ exported=None,
+ new=None,
+ updated=None,
+ skipped=None,
+ exif_updated=None,
+ touched=None,
+ to_touch=None,
+ converted_to_jpeg=None,
+ sidecar_json_written=None,
+ sidecar_json_skipped=None,
+ sidecar_exiftool_written=None,
+ sidecar_exiftool_skipped=None,
+ sidecar_xmp_written=None,
+ sidecar_xmp_skipped=None,
+ missing=None,
+ error=None,
+ exiftool_warning=None,
+ exiftool_error=None,
+ xattr_written=None,
+ xattr_skipped=None,
+ deleted_files=None,
+ deleted_directories=None,
+ exported_album=None,
+ skipped_album=None,
+ missing_album=None,
+ ):
+ self.exported = exported or []
+ self.new = new or []
+ self.updated = updated or []
+ self.skipped = skipped or []
+ self.exif_updated = exif_updated or []
+ self.touched = touched or []
+ self.to_touch = to_touch or []
+ self.converted_to_jpeg = converted_to_jpeg or []
+ self.sidecar_json_written = sidecar_json_written or []
+ self.sidecar_json_skipped = sidecar_json_skipped or []
+ self.sidecar_exiftool_written = sidecar_exiftool_written or []
+ self.sidecar_exiftool_skipped = sidecar_exiftool_skipped or []
+ self.sidecar_xmp_written = sidecar_xmp_written or []
+ self.sidecar_xmp_skipped = sidecar_xmp_skipped or []
+ self.missing = missing or []
+ self.error = error or []
+ self.exiftool_warning = exiftool_warning or []
+ self.exiftool_error = exiftool_error or []
+ self.xattr_written = xattr_written or []
+ self.xattr_skipped = xattr_skipped or []
+ self.deleted_files = deleted_files or []
+ self.deleted_directories = deleted_directories or []
+ self.exported_album = exported_album or []
+ self.skipped_album = skipped_album or []
+ self.missing_album = missing_album or []
+
+[docs] def all_files(self):
+ """return all filenames contained in results"""
+ files = (
+ self.exported
+ + self.new
+ + self.updated
+ + self.skipped
+ + self.exif_updated
+ + self.touched
+ + self.converted_to_jpeg
+ + self.sidecar_json_written
+ + self.sidecar_json_skipped
+ + self.sidecar_exiftool_written
+ + self.sidecar_exiftool_skipped
+ + self.sidecar_xmp_written
+ + self.sidecar_xmp_skipped
+ + self.missing
+ )
+ files += [x[0] for x in self.exiftool_warning]
+ files += [x[0] for x in self.exiftool_error]
+ files += [x[0] for x in self.error]
+
+ files = list(set(files))
+ return files
+
+ def __iadd__(self, other):
+ self.exported += other.exported
+ self.new += other.new
+ self.updated += other.updated
+ self.skipped += other.skipped
+ self.exif_updated += other.exif_updated
+ self.touched += other.touched
+ self.to_touch += other.to_touch
+ self.converted_to_jpeg += other.converted_to_jpeg
+ self.sidecar_json_written += other.sidecar_json_written
+ self.sidecar_json_skipped += other.sidecar_json_skipped
+ self.sidecar_exiftool_written += other.sidecar_exiftool_written
+ self.sidecar_exiftool_skipped += other.sidecar_exiftool_skipped
+ self.sidecar_xmp_written += other.sidecar_xmp_written
+ self.sidecar_xmp_skipped += other.sidecar_xmp_skipped
+ self.missing += other.missing
+ self.error += other.error
+ self.exiftool_warning += other.exiftool_warning
+ self.exiftool_error += other.exiftool_error
+ self.deleted_files += other.deleted_files
+ self.deleted_directories += other.deleted_directories
+ self.exported_album += other.exported_album
+ self.skipped_album += other.skipped_album
+ self.missing_album += other.missing_album
+
+ return self
+
+ def __str__(self):
+ return (
+ "ExportResults("
+ + f"exported={self.exported}"
+ + f",new={self.new}"
+ + f",updated={self.updated}"
+ + f",skipped={self.skipped}"
+ + f",exif_updated={self.exif_updated}"
+ + f",touched={self.touched}"
+ + f",to_touch={self.to_touch}"
+ + f",converted_to_jpeg={self.converted_to_jpeg}"
+ + f",sidecar_json_written={self.sidecar_json_written}"
+ + f",sidecar_json_skipped={self.sidecar_json_skipped}"
+ + f",sidecar_exiftool_written={self.sidecar_exiftool_written}"
+ + f",sidecar_exiftool_skipped={self.sidecar_exiftool_skipped}"
+ + f",sidecar_xmp_written={self.sidecar_xmp_written}"
+ + f",sidecar_xmp_skipped={self.sidecar_xmp_skipped}"
+ + f",missing={self.missing}"
+ + f",error={self.error}"
+ + f",exiftool_warning={self.exiftool_warning}"
+ + f",exiftool_error={self.exiftool_error}"
+ + f",deleted_files={self.deleted_files}"
+ + f",deleted_directories={self.deleted_directories}"
+ + f",exported_album={self.exported_album}"
+ + f",skipped_album={self.skipped_album}"
+ + f",missing_album={self.missing_album}"
+ + ")"
+ )
+
+
+[docs]class PhotoExporter:
+ """Export a photo"""
+ def __init__(self, photo: "PhotoInfo", tmpdir: t.Optional[str] = None):
+ self.photo = photo
+ self._render_options = RenderOptions()
+ self._verbose = self.photo._verbose
+
+ # define functions for adding markup
+ self._filepath = add_rich_markup_tag("filepath", rich=False)
+ self._filename = add_rich_markup_tag("filename", rich=False)
+ self._uuid = add_rich_markup_tag("uuid", rich=False)
+ self._num = add_rich_markup_tag("num", rich=False)
+
+ # temp directory for staging downloaded missing files
+ self._temp_dir = None
+ self._temp_dir_path = None
+ self.fileutil = FileUtil
+
+[docs] def export(
+ self,
+ dest,
+ filename=None,
+ options: t.Optional[ExportOptions] = None,
+ ) -> ExportResults:
+ """Export photo
+
+ Args:
+ dest: must be valid destination path or exception raised
+ filename: (optional): name of exported picture; if not provided, will use current filename
+ **NOTE**: if provided, user must ensure file extension (suffix) is correct.
+ For example, if photo is .CR2 file, edited image may be .jpeg.
+ If you provide an extension different than what the actual file is,
+ will export the photo using the incorrect file extension (unless use_photos_export is true,
+ in which case export will use the extension provided by Photos upon export.
+ e.g. to get the extension of the edited photo,
+ reference PhotoInfo.path_edited
+ options (`ExportOptions`): t.Optional ExportOptions instance
+
+ Returns:
+ ExportResults instance
+
+ Note:
+ To use dry run mode, you must set options.dry_run=True and also pass in memory version of export_db,
+ and no-op fileutil (e.g. `ExportDBInMemory` and `FileUtilNoOp`) in options.export_db and options.fileutil respectively
+ """
+
+ options = options or ExportOptions()
+
+ # temp dir must be initialized before any of the methods called by export() are called
+ self._init_temp_dir(options)
+
+ verbose = options.verbose or self._verbose
+ if verbose and not callable(verbose):
+ raise TypeError("verbose must be callable")
+
+ # define functions for adding markup
+ self._filepath = add_rich_markup_tag("filepath", rich=options.rich)
+ self._filename = add_rich_markup_tag("filename", rich=options.rich)
+ self._uuid = add_rich_markup_tag("uuid", rich=options.rich)
+ self._num = add_rich_markup_tag("num", rich=options.rich)
+
+ # can't use export_as_hardlink with download_missing, use_photos_export as can't hardlink the temporary files downloaded
+ if options.export_as_hardlink and options.download_missing:
+ raise ValueError(
+ "Cannot use export_as_hardlink with download_missing or use_photos_export"
+ )
+
+ # when called from export(), won't get an export_db, so use temp version
+ options.export_db = options.export_db or ExportDBTemp()
+
+ # ensure there's a FileUtil class to use
+ options.fileutil = options.fileutil or FileUtil
+ self.fileutil = options.fileutil
+
+ self._render_options = options.render_options or RenderOptions()
+
+ # export_original, and export_edited are just used for clarity in the code
+ export_original = not options.edited
+ export_edited = options.edited
+ if export_edited and not self.photo.hasadjustments:
+ raise ValueError(
+ "Photo does not have adjustments, cannot export edited version"
+ )
+
+ # verify destination is a valid path
+ if dest is None:
+ raise ValueError("dest must not be None")
+ elif not options.dry_run and not os.path.isdir(dest):
+ raise FileNotFoundError("Invalid path passed to export")
+
+ if export_edited:
+ filename = filename or self._get_edited_filename(
+ self.photo.original_filename
+ )
+ else:
+ filename = filename or self.photo.original_filename
+ dest = pathlib.Path(dest) / filename
+
+ # Is there something to convert with convert_to_jpeg?
+ dest, options = self._should_convert_to_jpeg(dest, options)
+
+ # stage files for export by finding path in local library or downloading from iCloud as appropriate
+ staged_files = self._stage_photos_for_export(options)
+ src = staged_files.edited if options.edited else staged_files.original
+
+ # get the right destination path depending on options.update, etc.
+ dest = self._get_dest_path(src, dest, options)
+
+ self._render_options.filepath = str(dest)
+ all_results = ExportResults()
+
+ if src:
+ # export the dest file
+ all_results += self._export_photo(
+ src,
+ dest,
+ options=options,
+ )
+ else:
+ verbose(
+ f"Skipping missing {'edited' if options.edited else 'original'} photo {self._filename(self.photo.original_filename)} ({self._uuid(self.photo.uuid)})"
+ )
+ all_results.missing.append(dest)
+
+ # copy live photo associated .mov if requested
+ if export_original and options.live_photo and self.photo.live_photo:
+ live_name = dest.parent / f"{dest.stem}.mov"
+ if staged_files.original_live:
+ src_live = staged_files.original_live
+ all_results += self._export_photo(
+ src_live,
+ live_name,
+ # don't try to convert the live photo
+ options=dataclasses.replace(options, convert_to_jpeg=False),
+ )
+ else:
+ verbose(
+ f"Skipping missing live photo for {self._filename(self.photo.original_filename)} ({self._uuid(self.photo.uuid)})"
+ )
+ all_results.missing.append(live_name)
+
+ if export_edited and options.live_photo and self.photo.live_photo:
+ live_name = dest.parent / f"{dest.stem}.mov"
+ if staged_files.edited_live:
+ src_live = staged_files.edited_live
+ all_results += self._export_photo(
+ src_live,
+ live_name,
+ # don't try to convert the live photo
+ options=dataclasses.replace(options, convert_to_jpeg=False),
+ )
+ else:
+ verbose(
+ f"Skipping missing edited live photo for {self._filename(self.photo.original_filename)} ({self._uuid(self.photo.uuid)})"
+ )
+ all_results.missing.append(live_name)
+
+ # copy associated RAW image if requested
+ if options.raw_photo and self.photo.has_raw:
+ if staged_files.raw:
+ raw_path = pathlib.Path(staged_files.raw)
+ raw_ext = raw_path.suffix
+ raw_name = dest.parent / f"{dest.stem}{raw_ext}"
+ all_results += self._export_photo(
+ raw_path,
+ raw_name,
+ options=options,
+ )
+ else:
+ # guess at most likely raw name
+ raw_ext = get_preferred_uti_extension(self.photo.uti_raw) or "raw"
+ raw_name = dest.parent / f"{dest.stem}.{raw_ext}"
+ all_results.missing.append(raw_name)
+ verbose(
+ f"Skipping missing raw photo for {self._filename(self.photo.original_filename)} ({self._uuid(self.photo.uuid)})"
+ )
+
+ # copy preview image if requested
+ if options.preview:
+ if staged_files.preview:
+ # Photos keeps multiple different derivatives and path_derivatives returns list of them
+ # first derivative is the largest so export that one
+ preview_path = pathlib.Path(staged_files.preview)
+ preview_ext = preview_path.suffix
+ preview_name = (
+ dest.parent / f"{dest.stem}{options.preview_suffix}{preview_ext}"
+ )
+ # if original is missing, the filename won't have been incremented so
+ # need to check here to make sure there aren't duplicate preview files in
+ # the export directory
+ preview_name = (
+ preview_name
+ if any([options.overwrite, options.update, options.force_update])
+ else pathlib.Path(increment_filename(preview_name))
+ )
+ all_results += self._export_photo(
+ preview_path,
+ preview_name,
+ options=options,
+ )
+ else:
+ # don't know what actual preview suffix would be but most likely jpeg
+ preview_name = dest.parent / f"{dest.stem}{options.preview_suffix}.jpeg"
+ all_results.missing.append(preview_name)
+ verbose(
+ f"Skipping missing preview photo for {self._filename(self.photo.original_filename)} ({self._uuid(self.photo.uuid)})"
+ )
+
+ all_results += self._write_sidecar_files(dest=dest, options=options)
+
+ return all_results
+
+ def _init_temp_dir(self, options: ExportOptions):
+ """Initialize (if necessary) the object's temporary directory.
+
+ Args:
+ options: ExportOptions object
+ """
+ if self._temp_dir is not None:
+ return
+
+ fileutil = options.fileutil or FileUtil
+ self._temp_dir = fileutil.tmpdir(prefix="osxphotos_export_", dir=options.tmpdir)
+ self._temp_dir_path = pathlib.Path(self._temp_dir.name)
+ return
+
+ def _touch_files(
+ self, touch_files: t.List, options: ExportOptions
+ ) -> ExportResults:
+ """touch file date/time to match photo creation date/time; only touches files if needed"""
+ fileutil = options.fileutil
+ touch_results = []
+ for touch_file in set(touch_files):
+ ts = int(self.photo.date.timestamp())
+ try:
+ stat = os.stat(touch_file)
+ if stat.st_mtime != ts:
+ fileutil.utime(touch_file, (ts, ts))
+ touch_results.append(touch_file)
+ except FileNotFoundError as e:
+ # ignore errors if in dry_run as file may not be present
+ if not options.dry_run:
+ raise e from e
+ return ExportResults(touched=touch_results)
+
+ def _get_edited_filename(self, original_filename):
+ """Return the filename for the exported edited photo
+ (used when filename isn't provided in call to export)"""
+ # need to get the right extension for edited file
+ original_filename = pathlib.Path(original_filename)
+ if self.photo.path_edited:
+ ext = pathlib.Path(self.photo.path_edited).suffix
+ else:
+ uti = self.photo.uti_edited if self.photo.uti_edited else self.photo.uti
+ ext = get_preferred_uti_extension(uti)
+ ext = "." + ext
+ edited_filename = original_filename.stem + "_edited" + ext
+ return edited_filename
+
+ def _get_dest_path(
+ self, src: str, dest: pathlib.Path, options: ExportOptions
+ ) -> pathlib.Path:
+ """If destination exists find match in ExportDB, on disk, or add (1), (2), and so on to filename to get a valid destination
+
+ Args:
+ src (str): source file path
+ dest (str): destination path
+ options (ExportOptions): Export options
+
+ Returns:
+ new dest path (pathlib.Path)
+ """
+
+ # if overwrite==False and #increment==False, export should fail if file exists
+ if dest.exists() and not any(
+ [options.increment, options.update, options.force_update, options.overwrite]
+ ):
+ raise FileExistsError(
+ f"destination exists ({dest}); overwrite={options.overwrite}, increment={options.increment}"
+ )
+
+ # if not update or overwrite, 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 options.increment and not any(
+ [options.update, options.force_update, options.overwrite]
+ ):
+ return pathlib.Path(increment_filename(dest))
+
+ # if update and file exists, need to check to see if it's the right file by checking export db
+ if (options.update or options.force_update) and dest.exists() and src:
+ export_db = options.export_db
+ # destination exists, check to see if destination is the right UUID
+ dest_uuid = export_db.get_uuid_for_file(dest)
+ if dest_uuid != self.photo.uuid:
+ # not the right file, find the right one
+ # find files that match "dest_name (*.ext" (e.g. "dest_name (1).jpg", "dest_name (2).jpg)", ...)
+ dest_files = list_directory(
+ dest.parent,
+ startswith=f"{dest.stem} (",
+ endswith=dest.suffix,
+ include_path=True,
+ )
+ for file_ in dest_files:
+ dest_uuid = export_db.get_uuid_for_file(file_)
+ if dest_uuid == self.photo.uuid:
+ dest = pathlib.Path(file_)
+ break
+ else:
+ # increment the destination file
+ dest = pathlib.Path(increment_filename(dest))
+
+ # either dest was updated in the if clause above or not updated at all
+ return dest
+
+ def _should_update_photo(
+ self, src: pathlib.Path, dest: pathlib.Path, options: ExportOptions
+ ) -> t.Literal[True, False]:
+ """Return True if photo should be updated, else False"""
+ export_db = options.export_db
+ fileutil = options.fileutil
+
+ file_record = export_db.get_file_record(dest)
+
+ if not file_record:
+ # photo doesn't exist in database, should update
+ return ShouldUpdate.NOT_IN_DATABASE
+
+ if options.export_as_hardlink and not dest.samefile(src):
+ # different files, should update
+ return ShouldUpdate.HARDLINK_DIFFERENT_FILES
+
+ if not options.export_as_hardlink and dest.samefile(src):
+ # same file but not exporting as hardlink, should update
+ return ShouldUpdate.NOT_HARDLINK_SAME_FILES
+
+ if not options.ignore_signature and not fileutil.cmp_file_sig(
+ dest, file_record.dest_sig
+ ):
+ # destination file doesn't match what was last exported
+ return ShouldUpdate.DEST_SIG_DIFFERENT
+
+ if file_record.export_options != options.bit_flags:
+ # exporting with different set of options (e.g. exiftool), should update
+ # need to check this before exiftool in case exiftool options are different
+ # and export database is missing; this will always be True if database is missing
+ # as it'll be None and bit_flags will be an int
+ return ShouldUpdate.EXPORT_OPTIONS_DIFFERENT
+
+ if options.exiftool:
+ current_exifdata = self._exiftool_json_sidecar(options=options)
+ rv = current_exifdata != file_record.exifdata
+ # if using exiftool, don't need to continue checking edited below
+ # as exiftool will be used to update edited file
+ return ShouldUpdate.EXIFTOOL_DIFFERENT if rv else False
+
+ if options.edited and not fileutil.cmp_file_sig(src, file_record.src_sig):
+ # edited file in Photos doesn't match what was last exported
+ return ShouldUpdate.EDITED_SIG_DIFFERENT
+
+ if options.force_update:
+ current_digest = hexdigest(self.photo.json())
+ if current_digest != file_record.digest:
+ # metadata in Photos changed, force update
+ return ShouldUpdate.DIGEST_DIFFERENT
+
+ # photo should not be updated
+ return False
+
+ def _stage_photos_for_export(self, options: ExportOptions) -> StagedFiles:
+ """Stages photos for export
+
+ If photo is present on disk in the library, uses path to the photo on disk.
+ If photo is missing and download_missing is true, downloads the photo from iCloud to temporary location.
+ """
+
+ staged = StagedFiles()
+
+ if options.use_photos_export:
+ # use Photos AppleScript or PhotoKit to do the export
+ return (
+ self._stage_photo_for_export_with_photokit(options=options)
+ if options.use_photokit
+ else self._stage_photo_for_export_with_applescript(options=options)
+ )
+
+ if options.raw_photo and self.photo.has_raw:
+ staged.raw = self.photo.path_raw
+
+ if options.preview and self.photo.path_derivatives:
+ staged.preview = self.photo.path_derivatives[0]
+
+ if not options.edited:
+ # original file
+ if self.photo.path:
+ staged.original = self.photo.path
+ if options.live_photo and self.photo.live_photo:
+ staged.original_live = self.photo.path_live_photo
+
+ if options.edited:
+ # edited file
+ staged.edited = self.photo.path_edited
+ if options.live_photo and self.photo.live_photo:
+ staged.edited_live = self.photo.path_edited_live_photo
+
+ # download any missing files
+ if options.download_missing:
+ live_photo = staged.edited_live if options.edited else staged.original_live
+ missing_options = ExportOptions(
+ edited=options.edited,
+ preview=options.preview and not staged.preview,
+ raw_photo=options.raw_photo and not staged.raw,
+ live_photo=options.live_photo and not live_photo,
+ )
+ if options.use_photokit:
+ missing_staged = self._stage_photo_for_export_with_photokit(
+ options=missing_options
+ )
+ else:
+ missing_staged = self._stage_photo_for_export_with_applescript(
+ options=missing_options
+ )
+ staged |= missing_staged
+ return staged
+
+ def _stage_photo_for_export_with_photokit(
+ self,
+ options: ExportOptions,
+ ) -> StagedFiles:
+ """Stage a photo for export with photokit to a temporary directory"""
+
+ if options.edited and not self.photo.hasadjustments:
+ raise ValueError("Edited version requested but photo has no adjustments")
+
+ dest = self._temp_dir_path / self.photo.original_filename
+
+ # export live_photo .mov file?
+ live_photo = bool(options.live_photo and self.photo.live_photo)
+
+ overwrite = any([options.overwrite, options.update, options.force_update])
+
+ # figure out which photo version to request
+ if options.edited or self.photo.shared:
+ # shared photos (in shared albums) show up as not having adjustments (not edited)
+ # but Photos is unable to export the "original" as only a jpeg copy is shared in iCloud
+ # so tell Photos to export the current version in this case
+ photos_version = PHOTOS_VERSION_CURRENT
+ elif self.photo.has_raw:
+ # PhotoKit always returns the raw photo of raw+jpeg pair for PHOTOS_VERSION_ORIGINAL even if JPEG is the original
+ photos_version = PHOTOS_VERSION_UNADJUSTED
+ else:
+ photos_version = PHOTOS_VERSION_ORIGINAL
+
+ uti = (
+ self.photo.uti_edited
+ if options.edited and self.photo.uti_edited
+ else self.photo.uti
+ )
+ ext = get_preferred_uti_extension(uti)
+ dest = dest.parent / f"{dest.stem}.{ext}"
+
+ photolib = PhotoLibrary()
+ results = StagedFiles()
+ photo = None
+ try:
+ photo = photolib.fetch_uuid(self.photo.uuid)
+ except PhotoKitFetchFailed as e:
+ # if failed to find UUID, might be a burst photo
+ if self.photo.burst and self.photo._info["burstUUID"]:
+ bursts = photolib.fetch_burst_uuid(
+ self.photo._info["burstUUID"], all=True
+ )
+ # PhotoKit UUIDs may contain "/L0/001" so only look at beginning
+ photo = [p for p in bursts if p.uuid.startswith(self.photo.uuid)]
+ photo = photo[0] if photo else None
+ if not photo:
+ results.error.append(
+ (
+ str(dest),
+ f"PhotoKitFetchFailed exception exporting photo {self.photo.uuid}: {e} ({lineno(__file__)})",
+ )
+ )
+ return results
+
+ # now export the requested version of the photo
+ try:
+ exported = photo.export(
+ dest.parent,
+ dest.name,
+ version=photos_version,
+ overwrite=overwrite,
+ video=live_photo,
+ )
+ if len(exported) == 1:
+ results_attr = "edited" if options.edited else "original"
+ setattr(results, results_attr, exported[0])
+ elif len(exported) == 2:
+ for exported_file in exported:
+ if exported_file.lower().endswith(".mov"):
+ # live photo
+ results_attr = (
+ "edited_live" if options.edited else "original_live"
+ )
+ else:
+ results_attr = "edited" if options.edited else "original"
+ setattr(results, results_attr, exported_file)
+ except Exception as e:
+ results.error.append((str(dest), f"{e} ({lineno(__file__)})"))
+
+ if options.raw_photo and self.photo.has_raw:
+ # also request the raw photo
+ try:
+ exported = photo.export(
+ dest.parent,
+ dest.name,
+ version=photos_version,
+ raw=True,
+ overwrite=overwrite,
+ video=live_photo,
+ )
+ if exported:
+ results.raw = exported[0]
+ except Exception as e:
+ results.error.append((str(dest), f"{e} ({lineno(__file__)})"))
+
+ if options.preview and self.photo.path_derivatives:
+ results.preview = self.photo.path_derivatives[0]
+
+ return results
+
+ def _stage_photo_for_export_with_applescript(
+ self,
+ options: ExportOptions,
+ ) -> StagedFiles:
+ """Stage a photo for export with AppleScript to a temporary directory
+
+ Note: If exporting an edited live photo, the associated live video will not be exported.
+ This is a limitation of the Photos AppleScript interface and Photos behaves the same way."""
+
+ if options.edited and not self.photo.hasadjustments:
+ raise ValueError("Edited version requested but photo has no adjustments")
+
+ dest = self._temp_dir_path / self.photo.original_filename
+ dest = pathlib.Path(increment_filename(dest))
+
+ # export live_photo .mov file?
+ live_photo = bool(options.live_photo and self.photo.live_photo)
+ overwrite = any([options.overwrite, options.update, options.force_update])
+ edited_version = options.edited or self.photo.shared
+ # shared photos (in shared albums) show up as not having adjustments (not edited)
+ # but Photos is unable to export the "original" as only a jpeg copy is shared in iCloud
+ # so tell Photos to export the current version in this case
+ uti = (
+ self.photo.uti_edited
+ if options.edited and self.photo.uti_edited
+ else self.photo.uti
+ )
+ ext = get_preferred_uti_extension(uti)
+ dest = dest.parent / f"{dest.stem}.{ext}"
+
+ results = StagedFiles()
+
+ try:
+ exported = self._export_photo_uuid_applescript(
+ self.photo.uuid,
+ dest.parent,
+ filestem=dest.stem,
+ original=not edited_version,
+ edited=edited_version,
+ live_photo=live_photo,
+ timeout=options.timeout,
+ burst=self.photo.burst,
+ overwrite=overwrite,
+ )
+ except ExportError as e:
+ results.error.append((str(dest), f"{e} ({lineno(__file__)})"))
+ return results
+
+ if len(exported) == 1:
+ results_attr = "edited" if options.edited else "original"
+ setattr(results, results_attr, exported[0])
+ elif len(exported) == 2:
+ # could be live or raw+jpeg
+ for exported_file in exported:
+ if exported_file.lower().endswith(".mov"):
+ # live photo
+ results_attr = (
+ "edited_live"
+ if live_photo and options.edited
+ else "original_live"
+ if live_photo
+ else None
+ )
+ elif self.photo.has_raw and pathlib.Path(
+ exported_file.lower()
+ ).suffix not in [
+ ".jpg",
+ ".jpeg",
+ ".heic",
+ ]:
+ # assume raw photo if not a common non-raw image format
+ results_attr = "raw" if options.raw_photo else None
+ else:
+ results_attr = "edited" if options.edited else "original"
+ if results_attr:
+ setattr(results, results_attr, exported_file)
+
+ if options.preview and self.photo.path_derivatives:
+ results.preview = self.photo.path_derivatives[0]
+
+ return results
+
+ def _should_convert_to_jpeg(
+ self, dest: pathlib.Path, options: ExportOptions
+ ) -> t.Tuple[pathlib.Path, ExportOptions]:
+ """Determine if a file really should be converted to jpeg or not
+ and return the new destination and ExportOptions instance with the convert_to_jpeg flag set appropriately
+ """
+ if not (options.convert_to_jpeg and self.photo.isphoto):
+ # nothing to convert
+ return dest, dataclasses.replace(options, convert_to_jpeg=False)
+
+ convert_to_jpeg = False
+ ext = "." + options.jpeg_ext if options.jpeg_ext else ".jpeg"
+ if not options.edited and self.photo.uti_original != "public.jpeg":
+ # not a jpeg but will convert to jpeg upon export so fix file extension
+ convert_to_jpeg = True
+ dest = dest.parent / f"{dest.stem}{ext}"
+ elif options.edited and self.photo.uti != "public.jpeg":
+ # in Big Sur+, edited HEICs are HEIC
+ convert_to_jpeg = True
+ dest = dest.parent / f"{dest.stem}{ext}"
+ return dest, dataclasses.replace(options, convert_to_jpeg=convert_to_jpeg)
+
+ def _is_temp_file(self, filepath: str) -> bool:
+ """Returns True if file is in the PhotosExporter temp directory otherwise False"""
+ filepath = pathlib.Path(filepath)
+ return filepath.parent == self._temp_dir_path
+
+ def _copy_to_temp_file(self, filepath: str) -> str:
+ """Copies filepath to a temp file preserving access and modification times"""
+ filepath = pathlib.Path(filepath)
+ dest = self._temp_dir_path / filepath.name
+ dest = increment_filename(dest)
+ self.fileutil.copy(filepath, dest)
+ stat = os.stat(filepath)
+ self.fileutil.utime(dest, (stat.st_atime, stat.st_mtime))
+ return str(dest)
+
+ def _export_photo(
+ self,
+ src,
+ dest,
+ options,
+ ):
+ """Helper function for export()
+ Does the actual copy or hardlink taking the appropriate
+ action depending on update, overwrite, export_as_hardlink
+ Assumes destination is the right destination (e.g. UUID matches)
+ Sets UUID and JSON info for exported file using set_uuid_for_file, set_info_for_uuid
+ Expects that src is a temporary file (as set by _stage_photos_for_export) and
+ may modify the src (e.g. for convert_to_jpeg or exiftool)
+
+ Args:
+ src (str): src path
+ dest (pathlib.Path): dest path
+ options (ExportOptions): options for export
+
+ Returns:
+ ExportResults
+
+ Raises:
+ ValueError if export_as_hardlink and convert_to_jpeg both True
+ """
+
+ if options.export_as_hardlink and options.convert_to_jpeg:
+ raise ValueError(
+ "export_as_hardlink and convert_to_jpeg cannot both be True"
+ )
+
+ if options.export_as_hardlink and self._is_temp_file(src):
+ raise ValueError("export_as_hardlink cannot be used with temp files")
+
+ exported_files = []
+ update_updated_files = []
+ update_new_files = []
+ update_skipped_files = [] # skip files that are already up to date
+ converted_to_jpeg_files = []
+ exif_results = ExportResults()
+
+ dest_str = str(dest)
+ dest_exists = dest.exists()
+
+ fileutil = options.fileutil
+ export_db = options.export_db
+
+ if options.update or options.force_update: # updating
+ if dest_exists:
+ if self._should_update_photo(src, dest, options):
+ update_updated_files.append(dest_str)
+ else:
+ update_skipped_files.append(dest_str)
+ else:
+ # update, destination doesn't exist (new file)
+ update_new_files.append(dest_str)
+ else:
+ # not update, export the file
+ exported_files.append(dest_str)
+
+ export_files = update_new_files + update_updated_files + exported_files
+ for export_dest in export_files:
+ # set src_sig before any modifications by convert_to_jpeg or exiftool
+ export_record = export_db.create_or_get_file_record(
+ export_dest, self.photo.uuid
+ )
+ export_record.src_sig = fileutil.file_sig(src)
+ if dest_exists and any(
+ [options.overwrite, options.update, options.force_update]
+ ):
+ # need to remove the destination first
+ try:
+ fileutil.unlink(dest)
+ except Exception as e:
+ raise ExportError(
+ f"Error removing file {dest}: {e} (({lineno(__file__)})"
+ ) from e
+ if options.export_as_hardlink:
+ try:
+ fileutil.hardlink(src, dest)
+ except Exception as e:
+ raise ExportError(
+ f"Error hardlinking {src} to {dest}: {e} ({lineno(__file__)})"
+ ) from e
+ else:
+ if options.convert_to_jpeg:
+ # use convert_to_jpeg to export the file
+ # convert to a temp file before copying
+ tmp_file = increment_filename(
+ self._temp_dir_path
+ / f"{pathlib.Path(src).stem}_converted_to_jpeg.jpeg"
+ )
+ fileutil.convert_to_jpeg(
+ src, tmp_file, compression_quality=options.jpeg_quality
+ )
+ src = tmp_file
+ converted_to_jpeg_files.append(dest_str)
+
+ if options.exiftool:
+ # if exiftool, write the metadata
+ # need to copy the file to a temp file before writing metadata
+ src = pathlib.Path(src)
+ tmp_file = increment_filename(
+ self._temp_dir_path / f"{src.stem}_exiftool{src.suffix}"
+ )
+ fileutil.copy(src, tmp_file)
+ # point src to the tmp_file so that the original source is not modified
+ # and the export grabs the new file
+ src = tmp_file
+ exif_results = self._write_exif_metadata_to_file(
+ src, dest, options=options
+ )
+
+ try:
+ fileutil.copy(src, dest_str)
+ except Exception as e:
+ raise ExportError(
+ f"Error copying file {src} to {dest_str}: {e} ({lineno(__file__)})"
+ ) from e
+
+ results = ExportResults(
+ converted_to_jpeg=converted_to_jpeg_files,
+ error=exif_results.error,
+ exif_updated=exif_results.exif_updated,
+ exiftool_error=exif_results.exiftool_error,
+ exiftool_warning=exif_results.exiftool_warning,
+ exported=exported_files + update_new_files + update_updated_files,
+ new=update_new_files,
+ skipped=update_skipped_files,
+ updated=update_updated_files,
+ )
+
+ # touch files if needed
+ if options.touch_file:
+ results += self._touch_files(
+ exported_files
+ + update_new_files
+ + update_updated_files
+ + update_skipped_files,
+ options,
+ )
+
+ # set data in the database
+ with export_db.create_or_get_file_record(dest_str, self.photo.uuid) as rec:
+ photoinfo = self.photo.json()
+ rec.photoinfo = photoinfo
+ rec.export_options = options.bit_flags
+ # don't set src_sig as that is set above before any modifications by convert_to_jpeg or exiftool
+ if not options.ignore_signature:
+ rec.dest_sig = fileutil.file_sig(dest)
+ if options.exiftool:
+ rec.exifdata = self._exiftool_json_sidecar(options)
+ if options.force_update:
+ rec.digest = hexdigest(photoinfo)
+
+ return results
+
+ def _export_photo_uuid_applescript(
+ self,
+ uuid: str,
+ dest: str,
+ filestem=None,
+ original=True,
+ edited=False,
+ live_photo=False,
+ timeout=120,
+ burst=False,
+ dry_run=False,
+ overwrite=False,
+ ):
+ """Export photo to dest path using applescript to control Photos
+ If photo is a live photo, exports both the photo and associated .mov file
+
+ Args:
+ 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
+ If photo not edited and edited=True, will still export the original image
+ caller must verify image has been edited
+ *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
+ burst: (boolean) set to True if file is a burst image to avoid Photos export error
+ dry_run: (boolean) set to True to run in "dry run" mode which will download file but not actually copy to destination
+
+ Returns: list of paths to exported file(s) or None if export failed
+
+ Raises: ExportError if error during export
+
+ 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.
+ """
+
+ dest = pathlib.Path(dest)
+ if not dest.is_dir():
+ raise ValueError(f"dest {dest} must be a directory")
+
+ if not original ^ edited:
+ raise ValueError("edited or original must be True but not both")
+
+ # export to a subdirectory of tmpdir
+ tmpdir = self.fileutil.tmpdir(
+ "osxphotos_applescript_export_", dir=self._temp_dir_path
+ )
+
+ exported_files = []
+ filename = None
+ try:
+ # I've seen intermittent failures with the PhotoScript export so retry if
+ # export doesn't return anything
+ retries = 0
+ while not exported_files and retries < MAX_PHOTOSCRIPT_RETRIES:
+ photo = photoscript.Photo(uuid)
+ filename = photo.filename
+ exported_files = photo.export(
+ tmpdir.name, original=original, timeout=timeout
+ )
+ retries += 1
+ except Exception as e:
+ raise ExportError(e)
+
+ if not exported_files or not filename:
+ # nothing got exported
+ raise ExportError(f"Could not export photo {uuid} ({lineno(__file__)})")
+ # 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
+ filename_stem = pathlib.Path(filename).stem
+ exported_paths = []
+ for fname in exported_files:
+ path = pathlib.Path(tmpdir.name) / fname
+ if (
+ len(exported_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
+ continue
+ if len(exported_files) > 1 and burst and path.stem != filename_stem:
+ # skip any burst photo that's not the one we asked for
+ 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
+ if not dry_run:
+ if overwrite and dest_new.exists():
+ FileUtil.unlink(dest_new)
+ FileUtil.copy(str(path), str(dest_new))
+ exported_paths.append(str(dest_new))
+ return exported_paths
+
+ def _write_sidecar_files(
+ self,
+ dest: pathlib.Path,
+ options: ExportOptions,
+ ) -> ExportResults:
+ """Write sidecar files for the photo."""
+
+ export_db = options.export_db
+ fileutil = options.fileutil
+ verbose = options.verbose or self._verbose
+
+ # export metadata
+ sidecars = []
+ sidecar_json_files_skipped = []
+ sidecar_json_files_written = []
+ sidecar_exiftool_files_skipped = []
+ sidecar_exiftool_files_written = []
+ sidecar_xmp_files_skipped = []
+ sidecar_xmp_files_written = []
+
+ dest_suffix = "" if options.sidecar_drop_ext else dest.suffix
+ if options.sidecar & SIDECAR_JSON:
+ sidecar_filename = dest.parent / pathlib.Path(
+ f"{dest.stem}{dest_suffix}.json"
+ )
+ sidecar_str = self._exiftool_json_sidecar(
+ filename=dest.name, options=options
+ )
+ sidecars.append(
+ (
+ sidecar_filename,
+ sidecar_str,
+ sidecar_json_files_written,
+ sidecar_json_files_skipped,
+ "JSON",
+ )
+ )
+
+ if options.sidecar & SIDECAR_EXIFTOOL:
+ sidecar_filename = dest.parent / pathlib.Path(
+ f"{dest.stem}{dest_suffix}.json"
+ )
+ sidecar_str = self._exiftool_json_sidecar(
+ tag_groups=False, filename=dest.name, options=options
+ )
+ sidecars.append(
+ (
+ sidecar_filename,
+ sidecar_str,
+ sidecar_exiftool_files_written,
+ sidecar_exiftool_files_skipped,
+ "exiftool",
+ )
+ )
+
+ if options.sidecar & SIDECAR_XMP:
+ sidecar_filename = dest.parent / pathlib.Path(
+ f"{dest.stem}{dest_suffix}.xmp"
+ )
+ sidecar_str = self._xmp_sidecar(
+ extension=dest.suffix[1:] if dest.suffix else None, options=options
+ )
+ sidecars.append(
+ (
+ sidecar_filename,
+ sidecar_str,
+ sidecar_xmp_files_written,
+ sidecar_xmp_files_skipped,
+ "XMP",
+ )
+ )
+
+ for data in sidecars:
+ sidecar_filename = data[0]
+ sidecar_str = data[1]
+ files_written = data[2]
+ files_skipped = data[3]
+ sidecar_type = data[4]
+
+ sidecar_digest = hexdigest(sidecar_str)
+ sidecar_record = export_db.create_or_get_file_record(
+ sidecar_filename, self.photo.uuid
+ )
+ write_sidecar = (
+ not (options.update or options.force_update)
+ or (
+ (options.update or options.force_update)
+ and not sidecar_filename.exists()
+ )
+ or (
+ (options.update or options.force_update)
+ and (sidecar_digest != sidecar_record.digest)
+ or not fileutil.cmp_file_sig(
+ sidecar_filename, sidecar_record.dest_sig
+ )
+ )
+ )
+ if write_sidecar:
+ verbose(
+ f"Writing {sidecar_type} sidecar {self._filepath(sidecar_filename)}"
+ )
+ files_written.append(str(sidecar_filename))
+ if not options.dry_run:
+ self._write_sidecar(sidecar_filename, sidecar_str)
+ sidecar_record.digest = sidecar_digest
+ sidecar_record.dest_sig = fileutil.file_sig(sidecar_filename)
+ else:
+ verbose(
+ f"Skipped up to date {sidecar_type} sidecar {self._filepath(sidecar_filename)}"
+ )
+ files_skipped.append(str(sidecar_filename))
+
+ results = ExportResults(
+ sidecar_json_written=sidecar_json_files_written,
+ sidecar_json_skipped=sidecar_json_files_skipped,
+ sidecar_exiftool_written=sidecar_exiftool_files_written,
+ sidecar_exiftool_skipped=sidecar_exiftool_files_skipped,
+ sidecar_xmp_written=sidecar_xmp_files_written,
+ sidecar_xmp_skipped=sidecar_xmp_files_skipped,
+ )
+
+ if options.touch_file:
+ all_sidecars = (
+ sidecar_json_files_written
+ + sidecar_exiftool_files_written
+ + sidecar_xmp_files_written
+ + sidecar_json_files_skipped
+ + sidecar_exiftool_files_skipped
+ + sidecar_xmp_files_skipped
+ )
+ results += self._touch_files(all_sidecars, options)
+
+ # update destination signatures in database
+ for sidecar_filename in all_sidecars:
+ sidecar_record = export_db.create_or_get_file_record(
+ sidecar_filename, self.photo.uuid
+ )
+ sidecar_record.dest_sig = fileutil.file_sig(sidecar_filename)
+
+ return results
+
+ def _write_exif_metadata_to_file(
+ self,
+ src,
+ dest,
+ options: ExportOptions,
+ ) -> ExportResults:
+ """Write exif metadata to file using exiftool
+
+ Note: this method modifies src so src must be a copy of the original file;
+ it also does not write to dest (dest is the intended destination for purposes of
+ referencing the export database. This allows the exiftool update to be done on the
+ local machine prior to being copied to the export destination which may be on a
+ network drive or other slower external storage."""
+
+ verbose = options.verbose or self._verbose
+ exiftool_results = ExportResults()
+
+ # don't try to write if unsupported file type for exiftool
+ if not exiftool_can_write(os.path.splitext(src)[-1]):
+ exiftool_results.exiftool_warning.append(
+ (
+ dest,
+ f"Unsupported file type for exiftool, skipping exiftool for {dest}",
+ )
+ )
+ # set file signature so the file doesn't get re-exported with --update
+ return exiftool_results
+
+ # determine if we need to write the exif metadata
+ # if we are not updating, we always write
+ # else, need to check the database to determine if we need to write
+ verbose(
+ f"Writing metadata with exiftool for {self._filepath(pathlib.Path(dest).name)}"
+ )
+ if not options.dry_run:
+ warning_, error_ = self._write_exif_data(src, options=options)
+ if warning_:
+ exiftool_results.exiftool_warning.append((dest, warning_))
+ if error_:
+ exiftool_results.exiftool_error.append((dest, error_))
+ exiftool_results.error.append((dest, error_))
+
+ exiftool_results.exif_updated.append(dest)
+ exiftool_results.to_touch.append(dest)
+ return exiftool_results
+
+ def _should_run_exiftool(self, dest, options: ExportOptions) -> bool:
+ """Return True if exiftool should be run to update metadata"""
+ run_exiftool = not options.update and not options.force_update
+ if options.update or options.force_update:
+ files_are_different = False
+ exif_record = options.export_db.get_file_record(dest)
+ old_data = exif_record.exifdata if exif_record else None
+ if old_data is not None:
+ old_data = json.loads(old_data)[0]
+ current_data = json.loads(self._exiftool_json_sidecar(options=options))
+ current_data = current_data[0]
+ if old_data != current_data:
+ files_are_different = True
+
+ if old_data is None or files_are_different:
+ # didn't have old data, assume we need to write it
+ # or files were different
+ run_exiftool = True
+ return run_exiftool
+
+ def _write_exif_data(self, filepath: str, options: ExportOptions):
+ """write exif data to image file at filepath
+
+ Args:
+ filepath: full path to the image file
+
+ Returns:
+ (warning, error) of warning and error strings if exiftool produces warnings or errors
+ """
+ if not os.path.exists(filepath):
+ raise FileNotFoundError(f"Could not find file {filepath}")
+ exif_info = self._exiftool_dict(options=options)
+
+ with ExifTool(
+ filepath,
+ flags=options.exiftool_flags,
+ exiftool=self.photo._db._exiftool_path,
+ ) as exiftool:
+ for exiftag, val in exif_info.items():
+ if type(val) == list:
+ for v in val:
+ exiftool.setvalue(exiftag, v)
+ else:
+ exiftool.setvalue(exiftag, val)
+ return exiftool.warning, exiftool.error
+
+ def _exiftool_dict(
+ self,
+ options: t.Optional[ExportOptions] = None,
+ filename: t.Optional[str] = None,
+ ):
+ """Return dict of EXIF details for building exiftool JSON sidecar or sending commands to ExifTool.
+ Does not include all the EXIF fields as those are likely already in the image.
+
+ Args:
+ options (ExportOptions): options for export
+ filename (str): name of source image file (without path); if not None, exiftool JSON signature will be included; if None, signature will not be included
+
+ Returns: dict with exiftool tags / values
+
+ Exports the following:
+ EXIF:ImageDescription (may include template)
+ XMP:Description (may include template)
+ XMP:Title
+ IPTC:ObjectName
+ XMP:TagsList (may include album name, person name, or template)
+ IPTC:Keywords (may include album name, person name, or template)
+ IPTC:Caption-Abstract
+ XMP:Subject (set to keywords + persons)
+ XMP:PersonInImage
+ EXIF:GPSLatitudeRef, EXIF:GPSLongitudeRef
+ EXIF:GPSLatitude, EXIF:GPSLongitude
+ EXIF:GPSPosition
+ EXIF:DateTimeOriginal
+ EXIF:OffsetTimeOriginal
+ EXIF:ModifyDate
+ IPTC:DateCreated
+ IPTC:TimeCreated
+ QuickTime:CreationDate
+ QuickTime:CreateDate (UTC)
+ QuickTime:ModifyDate (UTC)
+ QuickTime:GPSCoordinates
+ UserData:GPSCoordinates
+
+ Reference:
+ https://iptc.org/std/photometadata/specification/IPTC-PhotoMetadata-201610_1.pdf
+ """
+
+ options = options or ExportOptions()
+
+ exif = (
+ {
+ "SourceFile": filename,
+ "ExifTool:ExifToolVersion": "12.00",
+ "File:FileName": filename,
+ }
+ if filename is not None
+ else {}
+ )
+
+ if options.description_template is not None:
+ render_options = dataclasses.replace(
+ self._render_options, expand_inplace=True, inplace_sep=", "
+ )
+ rendered = self.photo.render_template(
+ options.description_template, render_options
+ )[0]
+ description = " ".join(rendered) if rendered else ""
+ if options.strip:
+ description = description.strip()
+ exif["EXIF:ImageDescription"] = description
+ exif["XMP:Description"] = description
+ exif["IPTC:Caption-Abstract"] = description
+ elif self.photo.description:
+ exif["EXIF:ImageDescription"] = self.photo.description
+ exif["XMP:Description"] = self.photo.description
+ exif["IPTC:Caption-Abstract"] = self.photo.description
+
+ if self.photo.title:
+ exif["XMP:Title"] = self.photo.title
+ exif["IPTC:ObjectName"] = self.photo.title
+
+ keyword_list = []
+ if options.merge_exif_keywords:
+ keyword_list.extend(self._get_exif_keywords())
+
+ if self.photo.keywords and not options.replace_keywords:
+ keyword_list.extend(self.photo.keywords)
+
+ person_list = []
+ if options.persons:
+ if options.merge_exif_persons:
+ person_list.extend(self._get_exif_persons())
+
+ if self.photo.persons:
+ # filter out _UNKNOWN_PERSON
+ person_list.extend(
+ [p for p in self.photo.persons if p != _UNKNOWN_PERSON]
+ )
+
+ if options.use_persons_as_keywords and person_list:
+ keyword_list.extend(person_list)
+
+ if options.use_albums_as_keywords and self.photo.albums:
+ keyword_list.extend(self.photo.albums)
+
+ if options.keyword_template:
+ rendered_keywords = []
+ render_options = dataclasses.replace(
+ self._render_options, none_str=_OSXPHOTOS_NONE_SENTINEL, path_sep="/"
+ )
+ for template_str in options.keyword_template:
+ rendered, unmatched = self.photo.render_template(
+ template_str, render_options
+ )
+ if unmatched:
+ logging.warning(
+ f"Unmatched template substitution for template: {template_str} {unmatched}"
+ )
+ rendered_keywords.extend(rendered)
+
+ if options.strip:
+ rendered_keywords = [keyword.strip() for keyword in rendered_keywords]
+
+ # filter out any template values that didn't match by looking for sentinel
+ rendered_keywords = [
+ keyword
+ for keyword in sorted(rendered_keywords)
+ if _OSXPHOTOS_NONE_SENTINEL not in keyword
+ ]
+
+ # check to see if any keywords too long
+ long_keywords = [
+ long_str
+ for long_str in rendered_keywords
+ if len(long_str) > _MAX_IPTC_KEYWORD_LEN
+ ]
+ if long_keywords:
+ self._verbose(
+ f"Warning: some keywords exceed max IPTC Keyword length of {_MAX_IPTC_KEYWORD_LEN} (exiftool will truncate these): {long_keywords}"
+ )
+
+ keyword_list.extend(rendered_keywords)
+
+ if keyword_list:
+ # remove duplicates
+ keyword_list = sorted(list(set(str(keyword) for keyword in keyword_list)))
+ exif["IPTC:Keywords"] = keyword_list.copy()
+ exif["XMP:Subject"] = keyword_list.copy()
+ exif["XMP:TagsList"] = keyword_list.copy()
+
+ if options.persons and person_list:
+ person_list = sorted(list(set(person_list)))
+ exif["XMP:PersonInImage"] = person_list.copy()
+
+ if options.face_regions and self.photo.face_info:
+ exif.update(self._get_mwg_face_regions_exiftool())
+
+ # if self.favorite():
+ # exif["Rating"] = 5
+
+ if options.location:
+ (lat, lon) = self.photo.location
+ if lat is not None and lon is not None:
+ if self.photo.isphoto:
+ exif["EXIF:GPSLatitude"] = lat
+ exif["EXIF:GPSLongitude"] = lon
+ lat_ref = "N" if lat >= 0 else "S"
+ lon_ref = "E" if lon >= 0 else "W"
+ exif["EXIF:GPSLatitudeRef"] = lat_ref
+ exif["EXIF:GPSLongitudeRef"] = lon_ref
+ elif self.photo.ismovie:
+ exif["Keys:GPSCoordinates"] = f"{lat} {lon}"
+ exif["UserData:GPSCoordinates"] = f"{lat} {lon}"
+
+ # process date/time and timezone offset
+ # Photos exports the following fields and sets modify date to creation date
+ # [EXIF] Modify Date : 2020:10:30 00:00:00
+ # [EXIF] Date/Time Original : 2020:10:30 00:00:00
+ # [EXIF] Create Date : 2020:10:30 00:00:00
+ # [IPTC] Digital Creation Date : 2020:10:30
+ # [IPTC] Date Created : 2020:10:30
+ #
+ # for videos:
+ # [QuickTime] CreateDate : 2020:12:11 06:10:10
+ # [QuickTime] ModifyDate : 2020:12:11 06:10:10
+ # [Keys] CreationDate : 2020:12:10 22:10:10-08:00
+ # This code deviates from Photos in one regard:
+ # if photo has modification date, use it otherwise use creation date
+
+ date = self.photo.date
+ 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]}"
+
+ # exiftool expects format to "2015:01:18 12:00:00"
+ datetimeoriginal = date.strftime("%Y:%m:%d %H:%M:%S")
+
+ if self.photo.isphoto:
+ exif["EXIF:DateTimeOriginal"] = datetimeoriginal
+ exif["EXIF:CreateDate"] = datetimeoriginal
+ exif["EXIF:OffsetTimeOriginal"] = offsettime
+
+ dateoriginal = date.strftime("%Y:%m:%d")
+ exif["IPTC:DateCreated"] = dateoriginal
+
+ timeoriginal = date.strftime(f"%H:%M:%S{offsettime}")
+ exif["IPTC:TimeCreated"] = timeoriginal
+
+ if (
+ self.photo.date_modified is not None
+ and not options.ignore_date_modified
+ ):
+ exif["EXIF:ModifyDate"] = self.photo.date_modified.strftime(
+ "%Y:%m:%d %H:%M:%S"
+ )
+ else:
+ exif["EXIF:ModifyDate"] = self.photo.date.strftime("%Y:%m:%d %H:%M:%S")
+ elif self.photo.ismovie:
+ # QuickTime spec specifies times in UTC
+ # QuickTime:CreateDate and ModifyDate are in UTC w/ no timezone
+ # QuickTime:CreationDate must include time offset or Photos shows invalid values
+ # reference: https://exiftool.org/TagNames/QuickTime.html#Keys
+ # https://exiftool.org/forum/index.php?topic=11927.msg64369#msg64369
+ exif["QuickTime:CreationDate"] = f"{datetimeoriginal}{offsettime}"
+
+ date_utc = datetime_tz_to_utc(date)
+ creationdate = date_utc.strftime("%Y:%m:%d %H:%M:%S")
+ exif["QuickTime:CreateDate"] = creationdate
+ if self.photo.date_modified is None or options.ignore_date_modified:
+ exif["QuickTime:ModifyDate"] = creationdate
+ else:
+ exif["QuickTime:ModifyDate"] = datetime_tz_to_utc(
+ self.photo.date_modified
+ ).strftime("%Y:%m:%d %H:%M:%S")
+
+ return exif
+
+ def _get_mwg_face_regions_exiftool(self):
+ """Return a dict with MWG face regions for use by exiftool"""
+ if self.photo.orientation in [5, 6, 7, 8]:
+ w = self.photo.height
+ h = self.photo.width
+ else:
+ w = self.photo.width
+ h = self.photo.height
+ exif = {}
+ exif["XMP:RegionAppliedToDimensionsW"] = w
+ exif["XMP:RegionAppliedToDimensionsH"] = h
+ exif["XMP:RegionAppliedToDimensionsUnit"] = "pixel"
+ exif["XMP:RegionName"] = []
+ exif["XMP:RegionType"] = []
+ exif["XMP:RegionAreaX"] = []
+ exif["XMP:RegionAreaY"] = []
+ exif["XMP:RegionAreaW"] = []
+ exif["XMP:RegionAreaH"] = []
+ exif["XMP:RegionAreaUnit"] = []
+ exif["XMP:RegionPersonDisplayName"] = []
+ # exif["XMP:RegionRectangle"] = []
+ for face in self.photo.face_info:
+ if not face.name:
+ continue
+ area = face.mwg_rs_area
+ exif["XMP:RegionName"].append(face.name)
+ exif["XMP:RegionType"].append("Face")
+ exif["XMP:RegionAreaX"].append(area.x)
+ exif["XMP:RegionAreaY"].append(area.y)
+ exif["XMP:RegionAreaW"].append(area.w)
+ exif["XMP:RegionAreaH"].append(area.h)
+ exif["XMP:RegionAreaUnit"].append("normalized")
+ exif["XMP:RegionPersonDisplayName"].append(face.name)
+ # exif["XMP:RegionRectangle"].append(f"{area.x},{area.y},{area.h},{area.w}")
+ return exif
+
+ def _get_exif_keywords(self):
+ """returns list of keywords found in the file's exif metadata"""
+ keywords = []
+ exif = self.photo.exiftool
+ if exif:
+ exifdict = exif.asdict()
+ for field in ["IPTC:Keywords", "XMP:TagsList", "XMP:Subject"]:
+ try:
+ kw = exifdict[field]
+ if kw and type(kw) != list:
+ kw = [kw]
+ kw = [str(k) for k in kw]
+ keywords.extend(kw)
+ except KeyError:
+ pass
+ return keywords
+
+ def _get_exif_persons(self):
+ """returns list of persons found in the file's exif metadata"""
+ persons = []
+ exif = self.photo.exiftool
+ if exif:
+ exifdict = exif.asdict()
+ try:
+ p = exifdict["XMP:PersonInImage"]
+ if p and type(p) != list:
+ p = [p]
+ p = [str(p_) for p_ in p]
+ persons.extend(p)
+ except KeyError:
+ pass
+ return persons
+
+ def _exiftool_json_sidecar(
+ self,
+ options: t.Optional[ExportOptions] = None,
+ tag_groups: bool = True,
+ filename: t.Optional[str] = None,
+ ):
+ """Return dict of EXIF details for building exiftool JSON sidecar or sending commands to ExifTool.
+ Does not include all the EXIF fields as those are likely already in the image.
+
+ Args:
+ options (ExportOptions): options for export
+ tag_groups (bool, default=True): if True, include tag groups in the output
+ filename (str): name of source image file (without path); if not None, exiftool JSON signature will be included; if None, signature will not be included
+
+ Returns: dict with exiftool tags / values
+
+ Exports the following:
+ EXIF:ImageDescription
+ XMP:Description (may include template)
+ IPTC:CaptionAbstract
+ XMP:Title
+ IPTC:ObjectName
+ XMP:TagsList
+ IPTC:Keywords (may include album name, person name, or template)
+ XMP:Subject (set to keywords + person)
+ XMP:PersonInImage
+ EXIF:GPSLatitudeRef, EXIF:GPSLongitudeRef
+ EXIF:GPSLatitude, EXIF:GPSLongitude
+ EXIF:GPSPosition
+ EXIF:DateTimeOriginal
+ EXIF:OffsetTimeOriginal
+ EXIF:ModifyDate
+ IPTC:DigitalCreationDate
+ IPTC:DateCreated
+ QuickTime:CreationDate
+ QuickTime:CreateDate (UTC)
+ QuickTime:ModifyDate (UTC)
+ QuickTime:GPSCoordinates
+ UserData:GPSCoordinates
+ """
+
+ options = options or ExportOptions()
+ exif = self._exiftool_dict(filename=filename, options=options)
+
+ if not tag_groups:
+ # strip tag groups
+ exif_new = {}
+ for k, v in exif.items():
+ k = re.sub(r".*:", "", k)
+ exif_new[k] = v
+ exif = exif_new
+
+ return json.dumps([exif])
+
+ def _xmp_sidecar(
+ self,
+ options: t.Optional[ExportOptions] = None,
+ extension: t.Optional[str] = None,
+ ):
+ """returns string for XMP sidecar
+
+ Args:
+ options (ExportOptions): options for export
+ extension (t.Optional[str]): which extension to use for SidecarForExtension property
+ """
+
+ options = options or ExportOptions()
+
+ xmp_template_file = (
+ _XMP_TEMPLATE_NAME if not self.photo._db._beta else _XMP_TEMPLATE_NAME_BETA
+ )
+ xmp_template = Template(filename=os.path.join(_TEMPLATE_DIR, xmp_template_file))
+
+ if extension is None:
+ extension = pathlib.Path(self.photo.original_filename)
+ extension = extension.suffix[1:] if extension.suffix else None
+
+ if options.description_template is not None:
+ render_options = dataclasses.replace(
+ self._render_options, expand_inplace=True, inplace_sep=", "
+ )
+ rendered = self.photo.render_template(
+ options.description_template, render_options
+ )[0]
+ description = " ".join(rendered) if rendered else ""
+ if options.strip:
+ description = description.strip()
+ else:
+ description = (
+ self.photo.description if self.photo.description is not None else ""
+ )
+
+ keyword_list = []
+ if options.merge_exif_keywords:
+ keyword_list.extend(self._get_exif_keywords())
+
+ if self.photo.keywords and not options.replace_keywords:
+ keyword_list.extend(self.photo.keywords)
+
+ # TODO: keyword handling in this and _exiftool_json_sidecar is
+ # good candidate for pulling out in a function
+
+ person_list = []
+ if options.persons:
+ if options.merge_exif_persons:
+ person_list.extend(self._get_exif_persons())
+
+ if self.photo.persons:
+ # filter out _UNKNOWN_PERSON
+ person_list.extend(
+ [p for p in self.photo.persons if p != _UNKNOWN_PERSON]
+ )
+
+ if options.use_persons_as_keywords and person_list:
+ keyword_list.extend(person_list)
+
+ if options.use_albums_as_keywords and self.photo.albums:
+ keyword_list.extend(self.photo.albums)
+
+ if options.keyword_template:
+ rendered_keywords = []
+ render_options = dataclasses.replace(
+ self._render_options, none_str=_OSXPHOTOS_NONE_SENTINEL, path_sep="/"
+ )
+ for template_str in options.keyword_template:
+ rendered, unmatched = self.photo.render_template(
+ template_str, render_options
+ )
+ if unmatched:
+ logging.warning(
+ f"Unmatched template substitution for template: {template_str} {unmatched}"
+ )
+ rendered_keywords.extend(rendered)
+
+ if options.strip:
+ rendered_keywords = [keyword.strip() for keyword in rendered_keywords]
+
+ # filter out any template values that didn't match by looking for sentinel
+ rendered_keywords = [
+ keyword
+ for keyword in rendered_keywords
+ if _OSXPHOTOS_NONE_SENTINEL not in keyword
+ ]
+
+ keyword_list.extend(rendered_keywords)
+
+ # remove duplicates
+ # sorted mainly to make testing the XMP file easier
+ if keyword_list:
+ keyword_list = sorted(list(set(keyword_list)))
+ if options.persons and person_list:
+ person_list = sorted(list(set(person_list)))
+
+ subject_list = keyword_list
+
+ latlon = self.photo.location if options.location else (None, None)
+
+ xmp_str = xmp_template.render(
+ photo=self.photo,
+ description=description,
+ keywords=keyword_list,
+ persons=person_list,
+ subjects=subject_list,
+ extension=extension,
+ location=latlon,
+ version=__version__,
+ )
+
+ # 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 or 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()
+
+
+def hexdigest(strval):
+ """hexdigest of a string, using blake2b"""
+ h = hashlib.blake2b(digest_size=20)
+ h.update(bytes(strval, "utf-8"))
+ return h.hexdigest()
+
+
+def _check_export_suffix(src, dest, edited):
+ """Helper function for exporting photos to check file extensions of destination path.
+
+ Checks that dst file extension is appropriate for the src.
+ If edited=True, will use src file extension of ".jpeg" if None provided for src.
+
+ Args:
+ src: path to source file or None.
+ dest: path to destination file.
+ edited: set to True if exporting an edited photo.
+
+ Returns:
+ True if src and dest extensions are OK, else False.
+
+ Raises:
+ ValueError if edited is False and src is None
+ """
+
+ # check extension of destination
+ if src is not None:
+ # use suffix from edited file
+ actual_suffix = pathlib.Path(src).suffix
+ elif edited:
+ # use .jpeg as that's probably correct
+ actual_suffix = ".jpeg"
+ else:
+ raise ValueError("src must not be None if edited=False")
+
+ # Photo's often converts .JPG to .jpeg or .tif to .tiff on import
+ dest_ext = dest.suffix.lower()
+ actual_ext = actual_suffix.lower()
+ suffixes = sorted([dest_ext, actual_ext])
+ return (
+ dest_ext == actual_ext
+ or suffixes == [".jpeg", ".jpg"]
+ or suffixes == [".tif", ".tiff"]
+ )
+
+
+def rename_jpeg_files(files, jpeg_ext, fileutil):
+ """rename any jpeg files in files so that extension matches jpeg_ext
+
+ Args:
+ files: list of file paths
+ jpeg_ext: extension to use for jpeg files found in files, e.g. "jpg"
+ fileutil: a FileUtil object
+
+ Returns:
+ list of files with updated names
+
+ Note: If non-jpeg files found, they will be ignore and returned in the return list
+ """
+ jpeg_ext = "." + jpeg_ext
+ jpegs = [".jpeg", ".jpg"]
+ new_files = []
+ for file in files:
+ path = pathlib.Path(file)
+ if path.suffix.lower() in jpegs and path.suffix != jpeg_ext:
+ new_file = path.parent / (path.stem + jpeg_ext)
+ fileutil.rename(file, new_file)
+ new_files.append(new_file)
+ else:
+ new_files.append(file)
+ return new_files
+