osxphotos package

osxphotos module

class osxphotos.PhotosDB(dbfile=None, verbose=None, exiftool=None)

Processes a Photos.app library database to extract information about photos

property album_info

return list of AlbumInfo objects for each album in the photos database

property album_info_shared

return list of AlbumInfo objects for each shared album in the photos database only valid for Photos 5; on Photos <= 4, prints warning and returns empty list

property albums

return list of albums found in photos database

property albums_as_dict

return albums as dict of albums, count in reverse sorted order (descending)

property albums_shared

return list of shared albums found in photos database only valid for Photos 5; on Photos <= 4, prints warning and returns empty list

property albums_shared_as_dict

returns shared albums as dict of albums, count in reverse sorted order (descending) valid only on Photos 5; on Photos <= 4, prints warning and returns empty dict

property db_path

returns path to the Photos library database PhotosDB was initialized with

property db_version

return the database version as stored in LiGlobals table

property folder_info

return list FolderInfo objects representing top-level folders in the photos database

property folders

return list of top-level folder names in the photos database

get_db_connection()

Get connection to the working copy of the Photos database

Returns

tuple of (connection, cursor) to sqlite3 database

get_photo(uuid)

Returns a single photo matching uuid

Parameters

uuid – the UUID of photo to get

Returns

PhotoInfo instance for photo with UUID matching uuid or None if no match

property import_info

return list of ImportInfo objects for each import session in the database

property keywords

return list of keywords found in photos database

property keywords_as_dict

return keywords as dict of keyword, count in reverse sorted order (descending)

property labels

return list of all search info labels found in the library

property labels_as_dict

count in reverse sorted order (descending)

Type

return labels as dict of label

property labels_normalized

return list of all normalized search info labels found in the library

property labels_normalized_as_dict

count in reverse sorted order (descending)

Type

return normalized labels as dict of label

property library_path

returns path to the Photos library PhotosDB was initialized with

property person_info

return list of PersonInfo objects for each person in the photos database

property persons

return list of persons found in photos database

property persons_as_dict

return persons as dict of person, count in reverse sorted order (descending)

photos(keywords=None, uuid=None, persons=None, albums=None, images=True, movies=True, from_date=None, to_date=None, intrash=False)

Return a list of PhotoInfo objects If called with no args, returns the entire database of photos If called with args, returns photos matching the args (e.g. keywords, persons, etc.) If more than one arg, returns photos matching all the criteria (e.g. keywords AND persons) If more than one keyword, uuid, persons, albums is passed, they are treated as “OR” criteria e.g. keywords=[“wedding”,”vacation”] returns photos matching either keyword from_date and to_date may be either naive or timezone-aware datetime.datetime objects. If naive, timezone will be assumed to be local timezone.

Parameters

• keywords – list of keywords to search for

• uuid – list of UUIDs to search for

• persons – list of persons to search for

• albums – list of album names to search for

• images – if True, returns image files, if False, does not return images; default is True

• movies – if True, returns movie files, if False, does not return movies; default is True

• from_date – return photos with creation date >= from_date (datetime.datetime object, default None)

• to_date – return photos with creation date <= to_date (datetime.datetime object, default None)

• intrash – if True, returns only images in “Recently deleted items” folder, if False returns only photos that aren’t deleted; default is False

Returns

list of PhotoInfo objects

photos_by_uuid(uuids)

Returns a list of photos with UUID in uuids.

Does not generate error if invalid or missing UUID passed. This is faster than using PhotosDB.photos if you have list of UUIDs. Returns photos regardless of intrash state.

Parameters

uuid – list of UUIDs of photos to get

Returns

list of PhotoInfo instance for photo with UUID matching uuid or [] if no match

query(options: osxphotos.queryoptions.QueryOptions) → List[osxphotos.photoinfo.photoinfo.PhotoInfo]

Run a query against PhotosDB to extract the photos based on user supplied options

Parameters

options – a QueryOptions instance

class osxphotos.PhotoInfo(db=None, uuid=None, info=None)

Info about a specific photo, contains all the details about the photo including keywords, persons, albums, uuid, path, etc.

class ExifInfo(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)

EXIF info associated with a photo from the Photos library

aperture: float

bit_rate: float

camera_make: str

camera_model: str

codec: str

duration: float

exposure_bias: float

flash_fired: bool

focal_length: float

fps: float

iso: int

latitude: float

lens_model: str

longitude: float

metering_mode: int

sample_rate: int

shutter_speed: float

track_format: int

white_balance: int

class ExportResults(exported=None, new=None, updated=None, skipped=None, exif_updated=None, touched=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)

holds export results for export2

all_files()

return all filenames contained in results

class ScoreInfo(overall: float, curation: float, promotion: float, highlight_visibility: float, behavioral: float, failure: float, harmonious_color: float, immersiveness: float, interaction: float, interesting_subject: float, intrusive_object_presence: float, lively_color: float, low_light: float, noise: float, pleasant_camera_tilt: float, pleasant_composition: float, pleasant_lighting: float, pleasant_pattern: float, pleasant_perspective: float, pleasant_post_processing: float, pleasant_reflection: float, pleasant_symmetry: float, sharply_focused_subject: float, tastefully_blurred: float, well_chosen_subject: float, well_framed_subject: float, well_timed_shot: float)

Computed photo score info associated with a photo from the Photos library

behavioral: float

curation: float

failure: float

harmonious_color: float

highlight_visibility: float

immersiveness: float

interaction: float

interesting_subject: float

intrusive_object_presence: float

lively_color: float

low_light: float

noise: float

overall: float

pleasant_camera_tilt: float

pleasant_composition: float

pleasant_lighting: float

pleasant_pattern: float

pleasant_perspective: float

pleasant_post_processing: float

pleasant_reflection: float

pleasant_symmetry: float

promotion: float

sharply_focused_subject: float

tastefully_blurred: float

well_chosen_subject: float

well_framed_subject: float

well_timed_shot: float

class SearchInfo(photo, normalized=False)

Info about search terms such as machine learning labels that Photos knows about a photo

property activities

returns list of activity names

property all

return all search info properties in a single list

asdict()

return dict of search info

property bodies_of_water

returns list of body of water names

property city

returns city/town

property country

returns country name

property holidays

returns list of holiday names

property labels

return list of labels associated with Photo

property locality_names

returns list of other locality names

property media_types

returns list of media types (photo, video, panorama, etc)

property month

returns month name

property neighborhoods

returns list of neighborhoods

property place_names

returns list of place names

property season

returns season name

property state

returns state name

property state_abbreviation

returns state abbreviation

property streets

returns list of street names

property venue_types

returns list of venue types

property venues

returns list of venue names

property year

returns year

property adjustments

Returns AdjustmentsInfo class for adjustment data or None if no adjustments; Photos 5+ only

property album_info

list of AlbumInfo objects representing albums the photo is contained in

property albums

list of albums picture is contained in

asdict()

return dict representation

property burst

Returns True if photo is part of a Burst photo set, otherwise False

property burst_album_info

If photo is a burst photo, returns list of AlbumInfo objects representing albums the photo is contained in as well as albums the burst key photo is contained in, otherwise returns self.album_info.

property burst_albums

If photo is burst photo, list of albums it is contained in as well as any albums the key photo is contained in, otherwise returns self.albums

property burst_default_pick

Returns True if photo is a burst image and is the photo that Photos selected as the default image for the burst set, otherwise False

property burst_key

Returns True if photo is a burst photo and is the key image for the burst set (the image that Photos shows on top of the burst stack), otherwise False

property burst_photos

If photo is a burst photo, returns list of PhotoInfo objects that are part of the same burst photo set; otherwise returns empty list. self is not included in the returned list

property burst_selected

Returns True if photo is a burst photo and has been selected from the burst set by the user, otherwise False

property comments

Returns list of Comment objects for any comments on the photo (sorted by date)

property date

image creation date as timezone aware datetime object

property date_added

Date photo was added to the database

property date_modified

image modification date as timezone aware datetime object or None if no modification date set

property date_trashed

Date asset was placed in the trash or None

property description

long / extended description of picture

property exif_info

Returns an ExifInfo object with the EXIF data for photo Note: the returned EXIF data is the data Photos stores in the database on import; ExifInfo does not provide access to the EXIF info in the actual image file Some or all of the fields may be None Only valid for Photos 5; on earlier database returns None

property exiftool

Returns an ExifTool object for the photo requires that exiftool (https://exiftool.org/) be installed If exiftool not installed, logs warning and returns None If photo path is missing, returns None

export(dest, *filename, edited=False, live_photo=False, raw_photo=False, export_as_hardlink=False, overwrite=False, increment=True, sidecar_json=False, sidecar_exiftool=False, sidecar_xmp=False, use_photos_export=False, timeout=120, exiftool=False, use_albums_as_keywords=False, use_persons_as_keywords=False, keyword_template=None, description_template=None)

export photo 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, export will print a warning but 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; in this case, an incorrect extension is silently ignored). e.g. to get the extension of the edited photo, reference PhotoInfo.path_edited

edited: (boolean, default=False); if True will export the edited version of the photo

(or raise exception if no edited version)

live_photo: (boolean, default=False); if True, will also export the associted .mov for live photos raw_photo: (boolean, default=False); if True, will also export the associted RAW photo export_as_hardlink: (boolean, default=False); if True, will hardlink files instead of copying them overwrite: (boolean, default=False); if True will overwrite files if they alreay exist increment: (boolean, default=True); if True, will increment file name until a non-existant name is found

if overwrite=False and increment=False, export will fail if destination file already exists

sidecar_json: 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

use_photos_export: (boolean, default=False); if True will attempt to export photo via applescript interaction with Photos timeout: (int, default=120) timeout in seconds used with use_photos_export exiftool: (boolean, default = False); if True, will use exiftool to write metadata to export file returns list of full paths to the exported files use_albums_as_keywords: (boolean, default = False); if True, will include album names in keywords when exporting metadata with exiftool or sidecar use_persons_as_keywords: (boolean, default = False); if True, will include person names in keywords when exporting metadata with exiftool or sidecar keyword_template: (list of strings); list of template strings that will be rendered as used as keywords description_template: string; optional template string that will be rendered for use as photo description

Returns: list of photos exported

export2(dest, *filename, edited=False, live_photo=False, raw_photo=False, export_as_hardlink=False, overwrite=False, increment=True, sidecar=0, sidecar_drop_ext=False, use_photos_export=False, timeout=120, exiftool=False, use_albums_as_keywords=False, use_persons_as_keywords=False, keyword_template=None, description_template=None, update=False, ignore_signature=False, export_db=None, fileutil=<class 'osxphotos.fileutil.FileUtil'>, dry_run=False, touch_file=False, convert_to_jpeg=False, jpeg_quality=1.0, ignore_date_modified=False, use_photokit=False, verbose=None, exiftool_flags=None, merge_exif_keywords=False, merge_exif_persons=False, jpeg_ext=None, persons=True, location=True, replace_keywords=False)

export photo, like export but with update and dry_run options 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

edited: (boolean, default=False); if True will export the edited version of the photo

(or raise exception if no edited version)

live_photo: (boolean, default=False); if True, will also export the associted .mov for live photos raw_photo: (boolean, default=False); if True, will also export the associted RAW photo export_as_hardlink: (boolean, default=False); if True, will hardlink files instead of copying them overwrite: (boolean, default=False); if True will overwrite files if they alreay exist increment: (boolean, default=True); if True, will increment file name until a non-existant name is found

if overwrite=False and increment=False, export will fail if destination file already exists

sidecar: bit field: 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

sidecar_drop_ext: (boolean, default=False); if True, drops the photo’s extension from sidecar filename (e.g. ‘IMG_1234.json’ instead of ‘IMG_1234.JPG.json’) use_photos_export: (boolean, default=False); if True will attempt to export photo via applescript interaction with Photos timeout: (int, default=120) timeout in seconds used with use_photos_export exiftool: (boolean, default = False); if True, will use exiftool to write metadata to export file use_albums_as_keywords: (boolean, default = False); if True, will include album names in keywords when exporting metadata with exiftool or sidecar use_persons_as_keywords: (boolean, default = False); if True, will include person names in keywords when exporting metadata with exiftool or sidecar keyword_template: (list of strings); list of template strings that will be rendered as used as keywords description_template: string; optional template string that will be rendered for use as photo description update: (boolean, 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

ignore_signature: (bool, default=False), ignore file signature when used with update (look only at filename) export_db: (ExportDB_ABC); instance of a class that conforms to ExportDB_ABC with methods

for getting/setting data related to exported files to compare update state

fileutil: (FileUtilABC); class that conforms to FileUtilABC with various file utilities dry_run: (boolean, default=False); set to True to run in “dry run” mode touch_file: (boolean, default=False); if True, sets file’s modification time upon photo date convert_to_jpeg: boolean; if True, converts non-jpeg images to jpeg 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. ignore_date_modified: for use with sidecar and exiftool; if True, sets EXIF:ModifyDate to EXIF:DateTimeOriginal even if date_modified is set verbose: optional callable function to use for printing verbose text during processing; if None (default), does not print output. exiftool_flags: optional list of flags to pass to exiftool when using exiftool option, e.g [“-m”, “-F”] merge_exif_keywords: boolean; if True, merged keywords found in file’s exif data (requires exiftool) merge_exif_persons: boolean; if True, merged persons found in file’s exif data (requires exiftool) jpeg_ext: 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 “.” persons: if True, include persons in exported metadata location: if True, include location in exported metadata replace_keywords: if True, keyword_template replaces any keywords, otherwise it’s additive

Returns: ExportResults class

ExportResults has attributes: “exported”, “new”, “updated”, “skipped”, “exif_updated”, “touched”, “converted_to_jpeg”, “sidecar_json_written”, “sidecar_json_skipped”, “sidecar_exiftool_written”, “sidecar_exiftool_skipped”, “sidecar_xmp_written”, “sidecar_xmp_skipped”, “missing”, “error”, “error_str”, “exiftool_warning”, “exiftool_error”,

Note: to use dry run mode, you must set dry_run=True and also pass in memory version of export_db,

and no-op fileutil (e.g. ExportDBInMemory and FileUtilNoOp)

property external_edit

Returns True if picture was edited outside of Photos using external editor

property face_info

list of FaceInfo objects for faces in picture

property favorite

True if picture is marked as favorite

property filename

filename of the picture

property has_raw

returns True if photo has an associated raw image (that is, it’s a RAW+JPEG pair), otherwise False

property hasadjustments

True if picture has adjustments / edits

property hdr

Returns True if photo is an HDR photo, otherwise False

property height

returns height of the current photo version in pixels

property hidden

True if picture is hidden

property import_info

ImportInfo object representing import session for the photo or None if no import session

property incloud

Returns True if photo is cloud asset and is synched to cloud False if photo is cloud asset and not yet synched to cloud None if photo is not cloud asset

property intrash

True if picture is in trash (‘Recently Deleted’ folder)

property iscloudasset

Returns True if photo is a cloud asset (in an iCloud library), otherwise False

property ismissing

returns true if photo is missing from disk (which means it’s not been downloaded from iCloud) NOTE: the photos.db database uses an asynchrounous write-ahead log so changes in Photos

do not immediately get written to disk. In particular, I’ve noticed that downloading an image from the cloud does not force the database to be updated until something else e.g. an edit, keyword, etc. occurs forcing a database synch The exact process / timing is a mystery to be but be aware that if some photos were recently downloaded from cloud to local storate their status in the database might still show isMissing = 1

property ismovie

Returns True if file is a movie, otherwise False

property isphoto

Returns True if file is an image, otherwise False

property israw

returns True if photo is a raw image. For images with an associated RAW+JPEG pair, see has_raw

property isreference

Returns True if photo is a reference (not copied to the Photos library), otherwise False

json()

Return JSON representation

property keywords

list of keywords for picture

property labels

returns list of labels applied to photo by Photos image categorization only valid on Photos 5, on older libraries returns empty list

property labels_normalized

returns normalized list of labels applied to photo by Photos image categorization only valid on Photos 5, on older libraries returns empty list

property likes

Returns list of Like objects for any likes on the photo (sorted by date)

property live_photo

Returns True if photo is a live photo, otherwise False

property location

returns (latitude, longitude) as float in degrees or None

property orientation

returns EXIF orientation of the current photo version as int or 0 if current orientation cannot be determined

property original_filename

original filename of the picture Photos 5 mangles filenames upon import

property original_filesize

returns filesize of original photo in bytes as int

property original_height

returns height of the original photo version in pixels

property original_orientation

returns EXIF orientation of the original photo version as int

property original_width

returns width of the original photo version in pixels

property panorama

Returns True if photo is a panorama, otherwise False

property path

absolute path on disk of the original picture

property path_derivatives

Return any derivative (preview) images associated with the photo as a list of paths, sorted by file size (largest first)

property path_edited

absolute path on disk of the edited picture

property path_live_photo

Returns path to the associated video file for a live photo If photo is not a live photo, returns None If photo is missing, returns None

property path_raw

absolute path of associated RAW image or None if there is not one

property person_info

list of PersonInfo objects for person in picture

property persons

list of persons in picture

property place

Returns PlaceInfo object containing reverse geolocation info

property portrait

Returns True if photo is a portrait, otherwise False

property raw_original

returns True if associated raw image and the raw image is selected in Photos via “Use RAW as Original ” otherwise returns False

render_template(template_str, none_str='_', path_sep=None, expand_inplace=False, inplace_sep=None, filename=False, dirname=False, strip=False, edited=False)

Renders a template string for PhotoInfo instance using PhotoTemplate

Parameters

• template_str – a template string with fields to render

• none_str – a str to use if template field renders to None, default is “_”.

• path_sep – a single character str to use as path separator when joining fields like folder_album; if not provided, defaults to os.path.sep

• expand_inplace – expand multi-valued substitutions in-place as a single string instead of returning individual strings

• inplace_sep – optional string to use as separator between multi-valued keywords with expand_inplace; default is ‘,’

• filename – if True, template output will be sanitized to produce valid file name

• dirname – if True, template output will be sanitized to produce valid directory name

• strip – if True, strips leading/trailing white space from resulting template

• edited – if True, sets {edited_version} field to True, otherwise it gets set to False; set if you want template evaluated for edited version

Returns

tuple of list of rendered strings and list of unmatched template values

Return type

([rendered_strings], [unmatched])

property score

Computed score information for a photo

Returns

ScoreInfo instance

property screenshot

Returns True if photo is an HDR photo, otherwise False

property search_info

returns SearchInfo object for photo only valid on Photos 5, on older libraries, returns None

property search_info_normalized

returns SearchInfo object for photo that produces normalized results only valid on Photos 5, on older libraries, returns None

property selfie

Returns True if photo is a selfie (front facing camera), otherwise False

property shared

returns True if photos is in a shared iCloud album otherwise false Only valid on Photos 5; returns None on older versions

property slow_mo

Returns True if photo is a slow motion video, otherwise False

property time_lapse

Returns True if photo is a time lapse video, otherwise False

property title

name / title of picture

property tzoffset

timezone offset from UTC in seconds

property uti

Returns Uniform Type Identifier (UTI) for the image for example: public.jpeg or com.apple.quicktime-movie

property uti_edited

Returns Uniform Type Identifier (UTI) for the edited image if the photo has been edited, otherwise None; for example: public.jpeg

property uti_original

Returns Uniform Type Identifier (UTI) for the original image for example: public.jpeg or com.apple.quicktime-movie

property uti_raw

Returns Uniform Type Identifier (UTI) for the RAW image if there is one for example: com.canon.cr2-raw-image Returns None if no associated RAW image

property uuid

UUID of picture

property visible

True if picture is visble

property width

returns width of the current photo version in pixels