osxphotos package

osxphotos module

class osxphotos.PhotosDB(dbfile=None, verbose=None, exiftool=None, rich=None)[source]

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

execute(sql)[source]

Execute sql statement and return cursor

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()[source]

Get connection to the working copy of the Photos database

Returns

tuple of (connection, cursor) to sqlite3 database

get_photo(uuid)[source]

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)[source]

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)[source]
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

property project_info

return list of AlbumInfo projects for each project in the database

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

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)[source]

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

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()[source]

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

detected_text(confidence_threshold=0.75)[source]

Detects text in photo and returns lists of results as (detected text, confidence)

confidence_threshold: float between 0.0 and 1.0. If text detection confidence is below this threshold, text will not be returned. Default is TEXT_DETECTION_CONFIDENCE_THRESHOLD

If photo is edited, uses the edited photo, otherwise the original; falls back to the preview image if neither edited or original is available

Returns: list of (detected text, confidence) tuples

property duplicates

return list of PhotoInfo objects for possible duplicates (matching signature of original size, date, height, width) or empty list if no matching duplicates

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 a ExifToolCaching (read-only instance of 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=None, 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, render_options: Optional[osxphotos.phototemplate.RenderOptions] = None)[source]

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, otherwise exports the original version

(or raise exception if no edited version)

live_photo: (boolean, default=False); if True, will also export the associated .mov for live photos raw_photo: (boolean, default=False); if True, will also export the associated 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 already 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 render_options: an optional osxphotos.phototemplate.RenderOptions instance with options to pass to template renderer

Returns

list of photos exported

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()[source]

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 moment

Moment photo belongs to

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 owner

Return name of photo owner for shared photos (Photos 5+ only), or None if not shared

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_edited_live_photo

return path to edited version of live photo movie; only valid for Photos 5+

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 project_info

list of AlbumInfo objects representing projects for the photo or None if no projects

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: str, options: Optional[osxphotos.phototemplate.RenderOptions] = None)[source]

Renders a template string for PhotoInfo instance using PhotoTemplate

Parameters
  • template_str – a template string with fields to render

  • options – a RenderOptions instance

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