OSXPhotos Python Reference¶

__init__.py for osxphotos

class osxphotos.AlbumInfo(db, uuid)[source]¶

Info about a specific Album, contains all the details about the album including folders, photos, etc.

asdict()[source]¶: Return album info as a dict; does not include photos

property folder_list¶: Returns list of FolderInfo objects for each folder the album is contained in or empty list if album is not in any folders

property folder_names¶: 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”, …] or empty list if album is not in any folders

property parent¶: returns FolderInfo object for parent folder or None if no parent (e.g. top-level album)

photo_index(photo)[source]¶: return index of photo in album (based on album sort order)

property photos¶: return list of photos contained in album sorted in same sort order as Photos

property sort_order¶: return sort order of album

property title¶: return title / name of album

class osxphotos.AlbumSortOrder(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶: Album Sort Order

class osxphotos.CommentInfo(datetime: datetime, user: str, ismine: bool, text: str)[source]¶: Class for shared photo comments

class osxphotos.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)[source]¶: EXIF info associated with a photo from the Photos library

class osxphotos.ExifTool(filepath, exiftool=None, overwrite=True, flags=None, large_file_support=True)[source]¶

Basic exiftool interface for reading and writing EXIF tags

addvalues(tag, *values)[source]¶

Add one or more value(s) to tag: If more than one value is passed, each value will be added to the tag

Parameters:

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

asdict(tag_groups=True, normalized=False)[source]¶

return dictionary of all EXIF tags and values from exiftool returns empty dict if no tags

Parameters:

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()[source]¶: returns JSON string containing all EXIF tags and values from exiftool

property pid¶: return process id (PID) of the exiftool process

run_commands(*commands, no_file=False)[source]¶

Run commands in the exiftool process and return result.

Parameters:

*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, error) 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.

setvalue(tag: str, value: Any)[source]¶

Set tag to value(s); if value is None, will delete tag

Parameters:

tag – str; name of tag to set
value – Any; value to set tag to

Returns:

True if success otherwise False

property version¶: returns exiftool version

class osxphotos.ExifWriter(photo: PhotoInfo)[source]¶

Write EXIF & other metadata to files using exiftool for a Photo asset

Parameters:: photo – PhotoInfo, the photo object to write metadata for

exiftool_dict(options: ExifOptions | None = None, filename: str | None = None)[source]¶

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.

Parameters:

options (ExifOptions) – 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:ContentCreateDate QuickTime:CreateDate (UTC) QuickTime:ModifyDate (UTC) QuickTime:GPSCoordinates UserData:GPSCoordinates XMP:Rating XMP:RegionAppliedToDimensionsW XMP:RegionAppliedToDimensionsH XMP:RegionAppliedToDimensionsUnit XMP:RegionName XMP:RegionType XMP:RegionAreaX XMP:RegionAreaY XMP:RegionAreaW XMP:RegionAreaH XMP:RegionAreaUnit XMP:RegionPersonDisplayName
Reference:: https://iptc.org/std/photometadata/specification/IPTC-PhotoMetadata-201610_1.pdf

exiftool_json_sidecar(options: ExifOptions | None = None, tag_groups: bool = True, filename: str | None = None) → str[source]¶

Return JSON string 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.

Parameters:

options (ExifOptions) – options for export
tag_groups (bool, default=True) – if True, include tag groups in the output
filename (str) – name of target image file (without path); if not None, exiftool JSON signature will be included; if None, signature will not be included

Returns: JSON string for 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

write_exif_data(filepath: str | Path, options: ExifOptions)[source]¶

Write exif data to image file at filepath

Parameters:: options (ExifOptions) – options controlling what data is written
Returns:: (warning, error) of warning and error strings if exiftool produces warnings or errors

class osxphotos.ExportDB(dbfile: str | PathLike, export_dir: str | PathLike | None, version: str | None = None)[source]¶

Interface to sqlite3 database used to store state information for osxphotos export command

Parameters:

dbfile – path to osxphotos export database file
export_dir – path to directory where exported files are stored; if None will read value from database
version – if supplied, creates database with this version; otherwise uses current version; (must be >= “4.3” and <= OSXPHOTOS_EXPORTDB_VERSION) For testing only; in normal usage, omit this argument

Note: export_dir = None must only be used when opening an existing database to read and not to export

close()[source]¶: close the database connection

property connection: Connection¶: returns sqlite3 connection

create_file_record(filename: str | PathLike, uuid: str) → ExportRecord[source]¶

create a new record for filename and uuid

Returns: an ExportRecord object

create_or_get_file_record(filename: str | PathLike, uuid: str) → ExportRecord[source]¶

create a new record for filename and uuid or return existing record

Returns: an ExportRecord object

delete_data_for_filepath(filepath: str | PathLike)[source]¶: Delete all exportdb data for given filepath

delete_data_for_uuid(uuid: str)[source]¶: Delete all exportdb data for given UUID

property export_dir: str¶: returns path to export directory

get_export_results(run: int = 0) → 'osxphotos.photoexporter.ExportResults' | None[source]¶

Retrieve export results from database

Parameters:

run (-1 = previous) – which run to retrieve results for;
run
run
that (-2 = run prior to)
etc.

Returns:

ExportResults object or None if no results found

get_exported_files()[source]¶: Returns tuple of (uuid, filepath) for all paths of all exported files tracked in the database

get_file_record(filename: str | os.PathLike) → 'ExportRecord' | None[source]¶

get info for filename

Returns: an ExportRecord object or None if filename not found

get_files_for_uuid(uuid: str) → list[str][source]¶: query database for UUID and return list of files associated with UUID or empty list

get_history(filepath: str | PathLike | None = None, uuid: str | None = None)[source]¶

Get history for a filepath or uuid

Parameters:

filepath – path to file
uuid – UUID of file

Returns:

list of history records

get_last_export_directory() → str | None[source]¶: Return the last export directory from the database

get_photoinfo_for_uuid(uuid: str) → str | None[source]¶: returns the photoinfo JSON string for a UUID or None if not found

get_previous_uuids()[source]¶: returns list of UUIDs of previously exported photos found in export database

get_target_for_file(uuid: str, filename: str | PathLike) → str | None[source]¶

query database for file matching file name and return the matching filename if there is one;: otherwise return None; looks for file.ext, file (1).ext, file (2).ext and so on to find the actual target name that was used to export filename

Returns: the matching filename or None if no match found

get_uuid_for_file(filename: str) → str | None[source]¶: query database for filename and return UUID returns None if filename not found in database

property path: str¶: returns path to export database

set_config(config_data: str)[source]¶: set config in the database

set_export_results(results: ExportResults)[source]¶: Store export results in database; data is pickled and gzipped for storage

set_history(filename: str | PathLike, uuid: str, action: str, diff: str | None)[source]¶

Set the history record for the filepath

Parameters:

filename – path to file
action – action taken on file, e.g. “exported”, “skipped”, “missing”, “updated”
diff – diff for file as a serialized JSON str

set_photoinfo_for_uuid(uuid: str, info: str)[source]¶: sets the photoinfo JSON string for a UUID

class osxphotos.ExportDBTemp(version: str | None = None)[source]¶

Temporary in-memory version of ExportDB

Parameters:: version – if supplied, creates database with this version; otherwise uses current version; (must be >= “4.3” and <= OSXPHOTOS_EXPORTDB_VERSION) For testing only; in normal usage, omit this argument

class osxphotos.ExportOptions(convert_to_jpeg: bool = False, description_template: str | None = None, download_missing: bool = False, dry_run: bool = False, edited: bool = False, exiftool_flags: list[str] | None = None, exiftool: bool = False, export_as_hardlink: bool = False, export_db: ExportDB | None = None, face_regions: bool = True, fileutil: FileUtil | None = None, force_update: bool = False, ignore_date_modified: bool = False, ignore_signature: bool = False, increment: bool = True, jpeg_ext: str | None = None, jpeg_quality: float = 1.0, keyword_template: list[str] | None = 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 = '_preview', preview: bool = False, raw_photo: bool = False, render_options: RenderOptions | None = None, replace_keywords: bool = False, rich: bool = False, export_aae: bool = False, sidecar_drop_ext: bool = False, sidecar: int = 0, strip: bool = False, timeout: int = 120, touch_file: bool = False, update: bool = False, update_errors: bool = False, use_albums_as_keywords: bool = False, use_persons_as_keywords: bool = False, use_photokit: bool = False, use_photos_export: bool = False, verbose: Callable[[Any], Any] | None = None, tmpdir: str | None = None, favorite_rating: bool = False, fix_orientation: bool = False)[source]¶

Options class for exporting photos with export

convert_to_jpeg¶

if True, converts non-jpeg images to jpeg

Type:: bool

description_template¶

Optional template string that will be rendered for use as photo description

Type:: str

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)

Type:: bool

dry_run¶

(bool, default=False): set to True to run in “dry run” mode

Type:: bool

edited¶

(bool, default=False): if True will export the edited version of the photo otherwise exports the original version

Type:: bool

exiftool_flags¶

Optional list of flags to pass to exiftool when using exiftool option, e.g [“-m”, “-F”]

Type:: list of str

exiftool¶

(bool, default = False): if True, will use exiftool to write metadata to export file

Type:: bool

export_as_hardlink¶

(bool, default=False): if True, will hardlink files instead of copying them

Type:: bool

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

Type:: osxphotos.export_db.ExportDB | None

face_regions¶

(bool, default=True): if True, will export face regions

Type:: bool

fileutil¶

(FileUtilABC): class that conforms to FileUtilABC with various file utilities

Type:: osxphotos.fileutil.FileUtil | None

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)

Type:: bool

ignore_date_modified¶

for use with sidecar and exiftool; if True, sets EXIF:ModifyDate to EXIF:DateTimeOriginal even if date_modified is set

Type:: bool

ignore_signature¶

ignore file signature when used with update (look only at filename)

Type:: bool, default=False

increment¶

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

Type:: bool, default=True

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 “.”

Type:: str

jpeg_quality¶

a value of 1.0 specifies use best quality, a value of 0.0 specifies use maximum compression.

Type:: float in range 0.0 <= jpeg_quality <= 1.0

keyword_template¶

list of template strings that will be rendered as used as keywords

Type:: list of str

live_photo¶

if True, will also export the associated .mov for live photos

Type:: bool, default=False

location¶

if True, include location in exported metadata

Type:: bool

merge_exif_keywords¶

if True, merged keywords found in file’s exif data (requires exiftool)

Type:: bool

merge_exif_persons¶

if True, merged persons found in file’s exif data (requires exiftool)

Type:: bool

overwrite¶

if True will overwrite files if they already exist

Type:: bool, default=False

persons¶

if True, include persons in exported metadata

Type:: bool

preview_suffix¶

Optional string to append to end of filename for preview images

Type:: str

preview¶

if True, also exports preview image

Type:: bool

raw_photo¶

if True, will also export the associated RAW photo

Type:: bool, default=False

render_options¶

Optional osxphotos.phototemplate.RenderOptions instance to specify options for rendering templates

Type:: RenderOptions

replace_keywords¶

if True, keyword_template replaces any keywords, otherwise it’s additive

Type:: bool

rich¶

if True, will use rich markup with verbose output

Type:: bool

export_aae¶

if True, also exports adjustments as .AAE file

Type:: bool

sidecar_drop_ext¶

if True, drops the photo’s extension from sidecar filename (e.g. ‘IMG_1234.json’ instead of ‘IMG_1234.JPG.json’)

Type:: bool, default=False

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

Type:: int

strip¶

if True, strip whitespace from rendered templates

Type:: bool

timeout¶

timeout in seconds used with use_photos_export

Type:: int, default=120

touch_file¶

if True, sets file’s modification time upon photo date

Type:: bool, default=False

update¶

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

Type:: bool, default=False

update_errors¶

if True photos that previously produced a warning or error will be re-exported; otherwise they will note be

Type:: bool, default=False

use_albums_as_keywords¶

if True, will include album names in keywords when exporting metadata with exiftool or sidecar

Type:: bool, default = False

use_persons_as_keywords¶

if True, will include person names in keywords when exporting metadata with exiftool or sidecar

Type:: bool, default = False

use_photos_export¶

if True will attempt to export photo via applescript interaction with Photos even if not missing (see also use_photokit, download_missing)

Type:: bool, default=False

use_photokit¶

if True, will use photokit to export photos when use_photos_export is True

Type:: bool, default=False

verbose¶

optional callable function to use for printing verbose text during processing; if None (default), does not print output.

Type:: callable

tmpdir¶

(str, default=None): Optional directory to use for temporary files, if None (default) uses system tmp directory

Type:: str | None

favorite_rating¶

if True, set XMP:Rating=5 for favorite images and XMP:Rating=0 for non-favorites

Type:: bool

fix_orientation¶

if True, will adjust image orientation based on exif data if necessary

Type:: bool

property bit_flags¶: Return bit flags representing options that affect export

class osxphotos.ExportResults(converted_to_jpeg: list[str] | None = None, deleted_directories: list[str] | None = None, deleted_files: list[str] | None = None, error: list[str] | None = None, exif_updated: list[str] | None = None, exiftool_error: list[tuple[str, str]] | None = None, exiftool_warning: list[tuple[str, str]] | None = None, exported: list[str] | None = None, exported_album: list[tuple[str, str]] | None = None, metadata_changed: list[str] | None = None, missing: list[str] | None = None, missing_album: list[tuple[str, str]] | None = None, new: list[str] | None = None, aae_written: list[str] | None = None, aae_skipped: list[str] | None = None, sidecar_exiftool_skipped: list[str] | None = None, sidecar_exiftool_written: list[str] | None = None, sidecar_json_skipped: list[str] | None = None, sidecar_json_written: list[str] | None = None, sidecar_xmp_skipped: list[str] | None = None, sidecar_xmp_written: list[str] | None = None, sidecar_user_written: list[str] | None = None, sidecar_user_skipped: list[str] | None = None, sidecar_user_error: list[tuple[str, str]] | None = None, skipped: list[str] | None = None, skipped_album: list[tuple[str, str]] | None = None, to_touch: list[str] | None = None, touched: list[str] | None = None, updated: list[str] | None = None, xattr_skipped: list[str] | None = None, xattr_written: list[str] | None = None, user_written: list[str] | None = None, user_skipped: list[str] | None = None, user_error: list[tuple[str, str]] | None = None)[source]¶

Results class which holds export results for export

Parameters:

converted_to_jpeg – list of files converted to jpeg
deleted_directories – list of directories deleted
deleted_files – list of files deleted
error – list of tuples of (filename, error) for any errors generated during export
exif_updated – list of files where exif data was updated with exiftool
exiftool_error – list of tuples of (filename, error) for any errors generated by exiftool
exiftool_warning – list of tuples of (filename, warning) for any warnings generated by exiftool
exported – list of files exported
exported_album – list of tuples of (file, album) for any files exported to an album
metadata_changed – list of filenames that had metadata changes since last export
missing – list of files that were missing
missing_album – list of tuples of (file, album) for any files that were missing from an album
new – list of files that were new
aae_written – list of files where .AAE file was written
aae_skipped – list of files where .AAE file was written
sidecar_exiftool_skipped – list of files where exiftool sidecar was skipped
sidecar_exiftool_written – list of files where exiftool sidecar was written
sidecar_json_skipped – list of files where json sidecar was skipped
sidecar_json_written – list of files where json sidecar was written
sidecar_xmp_skipped – list of files where xmp sidecar was skipped
sidecar_xmp_written – list of files where xmp sidecar was written
sidecar_user_written – list of files where user sidecar was written
sidecar_user_skipped – list of files where user sidecar was skipped
sidecar_user_error – list of tuples of (filename, error) for any errors generated by user sidecar
skipped – list of files that were skipped
skipped_album – list of tuples of (file, album) for any files that were skipped from an album
to_touch – list of files that were touched
touched – list of files that were touched
updated – list of files that were updated
xattr_skipped – list of files where xattr was skipped
xattr_written – list of files where xattr was written
user_written – list of files written by user post_function
user_skipped – list of files skipped by user post_function
user_error – list of tuples of (filename, error) for any errors generated by user post_function

Notes

Each attribute is a list of files or None if no files for that attribute. Error and warning attributes are a list of tuples of (filename, error) where filename is the file that caused the error and error is the error message. Album attributes are a list of tuples of (file, album) where file is the file exported and album is the album it was exported to. ExportResults can be added together with the += operator to combine results as the export progresses.

all_files() → list[str][source]¶: return all filenames contained in results

property attributes: list[str]¶: Return list of attributes tracked by ExportResults

property datetime: str¶: Return datetime when ExportResults was created

class osxphotos.FaceInfo(db=None, pk=None)[source]¶

Info about a face in the Photos library

asdict()[source]¶: Returns dict representation of class instance

property center¶

Coordinates, in PIL format, for center of face

Returns:: tuple of coordinates in form (x, y)

face_rect()[source]¶

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

json()[source]¶: Return JSON representation of FaceInfo instance

property mpri_reg_rect¶

Get coordinates for Microsoft Photo Region Rectangle.

Returns:: 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
Return type:: MPRI_Reg_Rect named tuple with x, y, h, w where

Reference:: https://docs.microsoft.com/en-us/windows/win32/wic/-wic-people-tagging

property mwg_rs_area¶

Get coordinates for Metadata Working Group Region Area.

Returns:: x = stArea:x y = stArea:y h = stArea:h w = stArea:w
Return type:: MWG_RS_Area named tuple with x, y, h, w where

Reference:: https://photo.stackexchange.com/questions/106410/how-does-xmp-define-the-face-region

property person_info¶: PersonInfo instance for person associated with this face

property photo¶: PhotoInfo instance associated with this face

property pitch¶: Return pitch angle in radians of the face region

property roll¶: Return roll angle in radians of the face region

roll_pitch_yaw()[source]¶: Roll, pitch, yaw of face in radians as tuple

property size_pixels¶

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

property yaw¶: Return yaw angle in radians of the face region

class osxphotos.FileUtil[source]¶: Various file utilities

class osxphotos.FileUtilNoOp(verbose=None)[source]¶

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

classmethod convert_to_jpeg(src_file, dest_file, compression_quality=1.0)[source]¶

converts image file src_file to jpeg format as dest_file

Parameters:

src_file – image file to convert
dest_file – destination path to write converted file to
quality (compression) – JPEG compression quality in range 0.0 <= compression_quality <= 1.0; default 1.0 (best quality)

Returns:

True if success, otherwise False

classmethod copy(src, dest)[source]¶

Copies a file from src path to dest path using shutil.copy

Parameters:

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 –

classmethod file_sig(file1)[source]¶: return os.stat signature for file f1 as tuple of (mode, size, mtime)

classmethod hardlink(src, dest)[source]¶: 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

classmethod rename(src, dest)[source]¶

Copy src to dest

Parameters:

src – path to source file
dest – path to destination file

Returns:

Name of renamed file (dest)

classmethod rmdir(dest)[source]¶: remove directory filepath; dirpath must be empty

classmethod tmpdir(prefix: str | None = None, dir: str | None = None) → TemporaryDirectory[source]¶: 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.

classmethod unlink(dest)[source]¶: unlink filepath; if it’s pathlib.Path, use Path.unlink, otherwise use os.unlink

classmethod utime(path, times)[source]¶: Set the access and modified time of path.

class osxphotos.FolderInfo(db=None, uuid=None)[source]¶

Info about a specific folder, contains all the details about the folder including folders, albums, etc

property album_info¶: return list of albums (as AlbumInfo objects) contained in the folder

asdict()[source]¶: Return folder info as a dict

property parent¶: returns FolderInfo object for parent or None if no parent (e.g. top-level folder)

property subfolders¶: return list of folders (as FolderInfo objects) contained in the folder

property title¶: return title / name of folder

property uuid¶: return uuid of folder

class osxphotos.ImportInfo(db, uuid)[source]¶

Information about import sessions

asdict()[source]¶: Return import info as a dict; does not include photos

property photos¶: return list of photos contained in import session

property title¶: return title / name of import session

class osxphotos.LikeInfo(datetime: datetime, user: str, ismine: bool)[source]¶: Class for shared photo likes

class osxphotos.MomentInfo(db, moment_pk)[source]¶

Info about a photo moment

asdict()[source]¶: Returns all moment info as dictionary

property date¶: Date of the moment.

property end_date¶: Stop date of the moment.

property location¶: Location of the moment.

property modification_date¶: Modification date of the moment.

property photos¶: All photos in this moment

property pk¶: Primary key of the moment.

property start_date¶: Start date of the moment.

property subtitle¶: Subtitle of the moment.

property title¶: Title of the moment.

class osxphotos.PersonInfo(db: PhotosDB, pk: int)[source]¶

Info about a person in the Photos library

asdict()[source]¶: Returns dictionary representation of class instance

property face_info¶: 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]

property favorite¶: Returns True if person is a favorite, False otherwise; Photos 5+ only; returns False on Photos <= 4

property feature_less¶: Returns True if person has been marked as “Feature This Person Less” in Photos, False otherwise; Photos 8+ only; returns False on Photos <= 7

json()[source]¶: Returns JSON representation of class instance

property photos¶: Returns list of PhotoInfo objects associated with this person

property sort_order¶: Returns sort order of person; favorite persons are sorted before non-favorite persons”; Photos 5+ only; returns 0 on Photos <= 4

class osxphotos.PhotoExporter(photo: PhotoInfo, tmpdir: t.Optional[str] = None)[source]¶

Export a photo

export(dest, filename=None, options: ExportOptions | None = None) → ExportResults[source]¶

Export photo

Parameters:

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

write_exiftool_metadata_to_file(src, dest, options: ExportOptions) → ExportResults[source]¶

Write exif metadata to src file using exiftool

Caution: This method modifies src, not dest, so src must be a copy of the original file if you don’t want the source modified; 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).

class osxphotos.PhotoInfo(db: PhotosDB, uuid: str, info: dict[str, Any])[source]¶

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

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

property adjustments_path: Path | None¶: Returns path to adjustments file or none if file doesn’t exist

property album_info: list[AlbumInfo]¶: list of AlbumInfo objects representing albums the photo is contained in

property albums: list[str]¶: list of albums picture is contained in

asdict(shallow: bool = True) → dict[str, Any][source]¶

Return dict representation of PhotoInfo object.

Parameters:: shallow – if True, return shallow representation (does not contain folder_info, person_info, etc.)
Returns:: dict representation of PhotoInfo object

Note

The shallow representation is used internally by export as it contains only the subset of data needed for export.

property burst: bool¶: Returns True if photo is part of a Burst photo set, otherwise False

property burst_album_info: list[AlbumInfo]¶: 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: list[str]¶: 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: bool¶: 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: bool¶: 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: list[PhotoInfo]¶: 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: bool¶: Returns True if photo is a burst photo and has been selected from the burst set by the user, otherwise False

property cloud_guid: str¶: Returns the GUID of the photo in iCloud (Photos 5+ only)

property cloud_metadata: dict[Any, Any]¶: Returns contents of ZCLOUDMASTERMEDIAMETADATA as dict; Photos 5+ only

property cloud_owner_hashed_id: str¶: Returns the hashed iCloud ID of the owner of the shared photo (Photos 5+ only)

property comments: list[CommentInfo]¶: Returns list of CommentInfo objects for any comments on the photo (sorted by date)

property date: datetime¶: image creation date as timezone aware datetime object

property date_added: datetime | None¶: Date photo was added to the database

property date_modified: datetime | None¶: image modification date as timezone aware datetime object or None if no modification date set

property date_trashed: datetime | None¶: Date asset was placed in the trash or None

property description: str¶: long / extended description of picture

detected_text(confidence_threshold=0.75) → list[tuple[str, float]][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: list[PhotoInfo]¶: 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: ExifInfo | None¶: 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: ExifToolCaching | None¶: 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: RenderOptions | None = None) → list[str][source]¶

Export a photo

Parameters:

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
files (returns list of full paths to the exported)
use_albums_as_keywords – (boolean, default = False); if True, will include album names in keywords
sidecar (when exporting metadata with exiftool or)
use_persons_as_keywords – (boolean, default = False); if True, will include person names in keywords
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: bool¶: Returns True if picture was edited outside of Photos using external editor

property face_info: list[FaceInfo]¶: list of FaceInfo objects for faces in picture

property favorite: bool¶: True if picture is marked as favorite

property filename: str¶: filename of the picture

property fingerprint: str | None¶: Returns fingerprint of original photo as a string or None if not available

property flagged: bool¶: Returns True if photo is flagged; iPhoto only; on Photos always returns False

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

property hasadjustments: bool¶: True if picture has adjustments / edits

property hdr: bool¶: Returns True if photo is an HDR photo, otherwise False

property height: int¶: returns height of the current photo version in pixels

property hexdigest: str¶: Returns a unique digest of the photo’s properties and metadata; useful for detecting changes in any property/metadata of the photo

property hidden: bool¶: True if picture is hidden

property import_info: ImportInfo | None¶: ImportInfo object representing import session for the photo or None if no import session

property incloud: bool | None¶: 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: bool¶: True if picture is in trash (‘Recently Deleted’ folder)

property iscloudasset: bool¶: Returns True if photo is a cloud asset (in an iCloud library), otherwise False

property ismissing: bool¶

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: bool¶: Returns True if file is a movie, otherwise False

property isphoto: bool¶: Returns True if file is an image, otherwise False

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

property isreference: bool¶: Returns True if photo is a reference (not copied to the Photos library), otherwise False

json(indent: int | None = None, shallow: bool = True) → str[source]¶

Return JSON representation

Parameters:

indent – indent level for JSON, if None, no indent
shallow – if True, return shallow JSON representation (does not contain folder_info, person_info, etc.)

Returns:

JSON string

Note

The shallow representation is used internally by export as it contains only the subset of data needed for export.

property keywords: list[str]¶: list of keywords for picture

property labels: list[str]¶: 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: list[str]¶: returns normalized list of labels applied to photo by Photos image categorization only valid on Photos 5, on older libraries returns empty list

property latitude: float | None¶: Returns latitude as float in degrees or None

property likes: list[LikeInfo]¶: Returns list of LikeInfo objects for any likes on the photo (sorted by date)

property live_photo: bool¶: Returns True if photo is a live photo, otherwise False

property location: tuple[float, float] | tuple[None, None]¶: Returns (latitude, longitude) as float in degrees or None

property longitude: float | None¶: Returns longitude as float in degrees or None

property moment_info: MomentInfo | None¶: Moment photo belongs to

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

property original_filename: str¶: original filename of the picture Photos 5 mangles filenames upon import

property original_filesize: int¶: returns filesize of original photo in bytes as int

property original_height: int¶: returns height of the original photo version in pixels

property original_orientation: int¶: returns EXIF orientation of the original photo version as int

property original_width: int¶: returns width of the original photo version in pixels

property owner: str | None¶: Return name of photo owner for shared photos (Photos 5+ only), or None if not shared

property panorama: bool¶: Returns True if photo is a panorama, otherwise False

property path: str | None¶: absolute path on disk of the original picture

property path_derivatives: list[str]¶: Return any derivative (preview) images associated with the photo as a list of paths, sorted by file size (largest first)

property path_edited: str | None¶: absolute path on disk of the edited picture

property path_edited_live_photo: str | None¶: return path to edited version of live photo movie

property path_live_photo: str | None¶: 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: str | None¶: absolute path of associated RAW image or None if there is not one

property person_info: list[PersonInfo]¶: list of PersonInfo objects for person in picture

property persons: list[str]¶: list of persons in picture

property place: PlaceInfo4 | PlaceInfo5 | None¶: Returns PlaceInfo object containing reverse geolocation info

property portrait: bool¶: Returns True if photo is a portrait, otherwise False

property project_info: list[ProjectInfo]¶: list of ProjectInfo objects representing projects for the photo or None if no projects

property rating: int¶: Star rating of photo as int from 0 to 5; for iPhoto, returns star rating; for Photos, always returns 0

property raw_original: bool¶: 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: RenderOptions | None = None) → tuple[list[str], list[str]][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 saved_to_library: bool | None¶: Return True if syndicated photo has been saved to library; returns False if photo is not syndicated or has not been saved to the library. Returns None if not Photos 7+. Syndicated photos are photos that appear in “Shared with you” album; Photos 7+ only.

property score: ScoreInfo¶

Computed score information for a photo

Returns:: ScoreInfo instance

property screen_recording: bool¶: Returns True if video is a screen_recording, otherwise False

property screenshot: bool¶: Returns True if photo is a screenshot, otherwise False

property search_info: SearchInfo | None¶: returns SearchInfo object for photo only valid on Photos 5, on older libraries, returns None

property search_info_normalized: SearchInfo | None¶: returns SearchInfo object for photo that produces normalized results only valid on Photos 5, on older libraries, returns None

property selfie: bool¶: Returns True if photo is a selfie (front facing camera), otherwise False

property share_info: ShareInfo | None¶: Returns ShareInfo object with information about the shared photo in a shared iCloud library (Photos 8+ only) (currently experimental)

property share_participant_info: list[ShareParticipant]¶: Returns list of ShareParticipant objects with information on who the photo is shared with (Photos 8+ only)

property share_participants: list[str]¶: Returns list of names of people the photo is shared with (Photos 8+ only)

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

property shared_library: bool¶: Returns True if photo is in a shared iCloud library otherwise False (Photos 8+ only)

property shared_moment: bool¶: Returns True if photo is part of a shared moment otherwise False (Photos 7+ only)

property shared_moment_info: ShareInfo | None¶: Returns ShareInfo object with information about the shared moment the photo is part of (Photos 7+ only)

property slow_mo: bool¶: Returns True if photo is a slow motion video, otherwise False

property syndicated: bool | None¶: Return true if photo was shared via syndication (e.g. via Messages, etc.); these are photos that appear in “Shared with you” album. Photos 7+ only; returns None if not Photos 7+.

tables() → PhotoTables | None[source]¶: Return PhotoTables object to provide access database tables associated with this photo (Photos 5+)

property time_lapse: bool¶: Returns True if photo is a time lapse video, otherwise False

property title: str | None¶: name / title of picture

property tzoffset: int¶: timezone offset from UTC in seconds

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

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

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

property uti_raw: str | None¶: 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: str¶: UUID of picture

property visible: bool¶: True if picture is visble

property width: int¶: returns width of the current photo version in pixels

class osxphotos.PhotoTemplate(photo, exiftool_path=None)[source]¶

PhotoTemplate class to render a template string from a PhotoInfo object

expand_variables(value: str) → List[str][source]¶: Expand variables in value

expand_variables_to_str(value: str, name: str) → str[source]¶

Expand variables in value and return a str of the expanded value. Enforce that the expanded value is a single value, raises ValueError if not.

Parameters:

value – the value to expand
name – the name of the value being expanded (used in error messages)

filter_predicate(value: str, args: str) → bool[source]¶: Return True if value passes predicate

get_field_values(field: str, subfield: str | None, field_arg: str | None, default: List[str]) → Tuple[List[str], List[str]][source]¶: Get the values for a field

get_filter_values(filter_: str, values: List[str]) → List[str][source]¶: Return filtered values

get_format_values(field: str, subfield: str, default: List[str]) → List[str | None] | None[source]¶: Return values for {format} templates

get_media_type(default)[source]¶: return special media type, e.g. slow_mo, panorama, etc., defaults to photo or video if no special type

get_photo_bool_attribute(attr, default, bool_val)[source]¶: Return the boolean value for a photo attribute

get_photo_video_type(default)[source]¶: return media type, e.g. photo or video

get_template_value(field: str, default: List[str], subfield: str | None, field_arg: str | None)[source]¶

lookup value for template field (single-value template substitutions)

Parameters:

field – template field to find value for.
default – the default value provided by the user
bool_val – True value if expression is boolean
delim – delimiter for expand in place
path_sep – path separator for fields that are path-like
subfield – subfield (value after : in field)

Returns:

The matching template value (which may be None).

Raises:

ValueError if no rule exists for field. –

get_template_value_exiftool(subfield)[source]¶: Get template value for format “{exiftool:EXIF:Model}”

get_template_value_filter_function(filter_, args, values)[source]¶: Filter template value from external function

get_template_value_function(subfield: str, field_arg: str | None, caller: str)[source]¶

Get template value from external function

Parameters:

subfield – the filename and function name in for filename.py::function
field_arg – the argument to pass to the function
caller – the calling source of the template (‘export’ or ‘import’)

get_template_value_multi(field, subfield, path_sep, default)[source]¶

lookup value for template field (multi-value template substitutions)

Parameters:

field – template field to find value for.
subfield – the template subfield value
path_sep – path separator to use for folder_album field
default – value of default field

Returns:

List of the matching template values or [].

Raises:

ValueError if no rule exists for field. –

get_template_value_pathlib(field)[source]¶

lookup value for template pathlib template fields

Parameters:: field – template field to find value for.
Returns:: The matching template value (which may be None).
Raises:: ValueError if no rule exists for field. –

render(template: str, options: RenderOptions)[source]¶

Render a filename or directory template

Parameters:

template – str template
options – a RenderOptions instance

Returns:

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

Return type:

([rendered_strings], [unmatched])

class osxphotos.PhotosAlbum(name: str, verbose: Callable[[...], Any] | None = None, split_folder: str | None = None, rich: bool = False)[source]¶

Add osxphotos.photoinfo.PhotoInfo objects to album

append(photo: PhotoInfo)[source]¶: Add photo to album

extend(photos: Iterable[PhotoInfo])[source]¶: Add list of photos to album

class osxphotos.PhotosAlbumPhotoScript(name: str, verbose: Callable[[...], Any] | None = None, split_folder: str | None = None, rich: bool = False)[source]¶

Add photoscript.Photo objects to album

append(photo: Photo)[source]¶: Add photo to album

extend(photos: Iterable[Photo])[source]¶: Add list of photos to album

class osxphotos.PhotosDB(dbfile=None, verbose=None, exiftool=None, rich=None, library_path=None, _skip_searchinfo=False)[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: str, params: Any | None = None) → Cursor[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 and associated with at least one photo

property keywords_as_dict¶

count in reverse sorted order (descending)

Type:: Teturn keywords as dict of keyword

property keywords_without_photo¶: Return keywords that exist in the database but are not assined to any photo (Photos 5+ only)

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 and associated with at least one photo

property persons_as_dict¶: Return persons as dict of person, count in reverse sorted order (descending)

photos(keywords: List[str] | None = None, uuid: List[str] | None = None, persons: List[str] | None = None, albums: List[str] | None = None, images: bool = True, movies: bool = True, from_date: datetime | None = None, to_date: datetime | None = None, intrash: bool = False) → List[PhotoInfo][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 photos_version¶: Returns version of Photos app that created the library

property project_info¶: Return list of AlbumInfo projects for each project in the database

query(options: QueryOptions) → list[PhotoInfo][source]¶

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

Parameters:: options – a QueryOptions instance

class osxphotos.PlaceInfo[source]¶

Reverse geolocation place info for a photo.

property address¶

Returns a PostalAddress namedtuple with details of the postal address containing the following fields:

city
country
postal_code
state
street
sub_administrative_area
sub_locality
iso_country_code

property address_str: str | None¶: Returns the full postal address as a string if defined, otherwise None.

asdict()[source]¶: Returns a dictionary representation of the PlaceInfo object.

property country_code: str | None¶: Returns the country_code of place, for example “GB”. Returns None if PhotoInfo contains no country code.

property ishome: bool¶: Returns True if photo place is user’s home address, otherwise False.

property name: str | None¶: Returns the name of the local place as str. This is what Photos displays in the Info window. Note Photos 5 uses a different algorithm to determine the name than earlier versions which means the same Photo may have a different place name in Photos 4 and Photos 5. PhotoInfo.name will return the name Photos would have shown depending on the version of the library being processed. Returns None if photo does not contain a name.

property names: PlaceNames | None¶

Returns a PlaceNames namedtuple with the following fields. Each field is a list with zero or more values, sorted by area in ascending order. E.g. names.area_of_interest could be [‘Gulf Islands National Seashore’, ‘Santa Rosa Island’], [“Knott’s Berry Farm”], or [] if area_of_interest not defined. The value shown in Photos is the first value in the list. With the exception of body_of_water each of these field corresponds to an attribute of a [CLPlacemark](https://developer.apple.com/documentation/corelocation/clplacemark) object.

country; the name of the country associated with the placemark.
state_province; administrativeArea, The state or province associated with the placemark.
sub_administrative_area; additional administrative area information for the placemark.
city; locality; the city associated with the placemark.
additional_city_info; subLocality, Additional city-level information for the placemark.
ocean; the name of the ocean associated with the placemark.
area_of_interest; areasOfInterest, The relevant areas of interest associated with the placemark.
inland_water; the name of the inland water body associated with the placemark.
region; the geographic region associated with the placemark.
sub_throughfare; additional street-level information for the placemark.
postal_code; the postal code associated with the placemark.
street_address; throughfare, The street address associated with the placemark.
body_of_water; in Photos 4, any body of water; in Photos 5 contains the union of ocean and inland_water

Note: In Photos <= 4.0, only the following fields are defined; all others are set to empty list:

country
state_province
sub_administrative_area
city
additional_city_info
area_of_interest
body_of_water

Note

The PlaceNames namedtuple contains reserved fields not listed below (see implementation for details), thus it should be referenced only by name (e.g. names.city) and not by index.

class osxphotos.ProjectInfo(db, uuid)[source]¶

ProjectInfo with info about projects Projects are cards, calendars, slideshows, etc.

property folder_list¶: Returns list of FolderInfo objects for each folder the album is contained in or empty list if album is not in any folders

property folder_names¶: 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”, …] or empty list if album is not in any folders

QueryOptions class for PhotosDB.query

added_after¶

search for photos added on or after a given date

Type:: Optional[datetime.datetime]

added_before¶

search for photos added before a given date

Type:: Optional[datetime.datetime]

added_in_last¶

search for photos added in last X datetime.timedelta

Type:: Optional[datetime.timedelta]

album¶

list of album names to search for

Type:: Optional[Iterable[str]]

burst_photos¶

include all associated burst photos for photos in query results

Type:: Optional[bool]

burst¶

search for burst photos

Type:: Optional[bool]

cloudasset¶

search for photos that are managed by iCloud

Type:: Optional[bool]

deleted_only¶

search only for deleted photos

Type:: Optional[bool]

deleted¶

also include deleted photos

Type:: Optional[bool]

description¶

list of descriptions to search for

Type:: Optional[Iterable[str]]

duplicate¶

search for duplicate photos

Type:: Optional[bool]

edited¶

search for edited photos

Type:: Optional[bool]

exif¶

search for photos with EXIF tags that matches the given data

Type:: Optional[Iterable[Tuple[str, str]]]

external_edit¶

search for photos edited in external apps

Type:: Optional[bool]

favorite¶

search for favorite photos

Type:: Optional[bool]

folder¶

list of folder names to search for

Type:: Optional[Iterable[str]]

from_date¶

search for photos taken on or after this date

Type:: Optional[datetime.datetime]

from_time¶

search for photos taken on or after this time of day

Type:: Optional[datetime.time]

function¶

list of query functions to evaluate

Type:: Optional[List[Tuple[callable, str]]]

has_comment¶

search for photos with comments

Type:: Optional[bool]

has_likes¶

search for shared photos with likes

Type:: Optional[bool]

has_raw¶

search for photos with associated raw files

Type:: Optional[bool]

hdr¶

search for HDR photos

Type:: Optional[bool]

hidden¶

search for hidden photos

Type:: Optional[bool]

ignore_case¶

ignore case when searching

Type:: Optional[bool]

in_album¶

search for photos in an album

Type:: Optional[bool]

incloud¶

search for cloud assets that are synched to iCloud

Type:: Optional[bool]

is_reference¶

search for photos stored by reference (that is, they are not managed by Photos)

Type:: Optional[bool]

keyword¶

list of keywords to search for

Type:: Optional[Iterable[str]]

label¶

list of labels to search for

Type:: Optional[Iterable[str]]

live¶

search for live photos

Type:: Optional[bool]

location¶

search for photos with a location

Type:: Optional[bool]

max_size¶

maximum size of photos to search for

Type:: Optional[bitmath.Byte]

min_size¶

minimum size of photos to search for

Type:: Optional[bitmath.Byte]

missing_bursts¶

for burst photos, also include burst photos that are missing

Type:: Optional[bool]

missing¶

search for missing photos

Type:: Optional[bool]

movies¶

search for movies

Type:: Optional[bool]

name¶

list of names to search for

Type:: Optional[Iterable[str]]

no_comment¶

search for photos with no comments

Type:: Optional[bool]

no_description¶

search for photos with no description

Type:: Optional[bool]

no_likes¶

search for shared photos with no likes

Type:: Optional[bool]

no_location¶

search for photos with no location

Type:: Optional[bool]

no_keyword¶

search for photos with no keywords

Type:: Optional[bool]

no_place¶

search for photos with no place

Type:: Optional[bool]

no_title¶

search for photos with no title

Type:: Optional[bool]

not_burst¶

search for non-burst photos

Type:: Optional[bool]

not_cloudasset¶

search for photos that are not managed by iCloud

Type:: Optional[bool]

not_edited¶

search for photos that have not been edited

Type:: Optional[bool]

not_favorite¶

search for non-favorite photos

Type:: Optional[bool]

not_hdr¶

search for non-HDR photos

Type:: Optional[bool]

not_hidden¶

search for non-hidden photos

Type:: Optional[bool]

not_in_album¶

search for photos not in an album

Type:: Optional[bool]

not_incloud¶

search for cloud asset photos that are not yet synched to iCloud

Type:: Optional[bool]

not_live¶

search for non-live photos

Type:: Optional[bool]

not_missing¶

search for non-missing photos

Type:: Optional[bool]

not_panorama¶

search for non-panorama photos

Type:: Optional[bool]

not_portrait¶

search for non-portrait photos

Type:: Optional[bool]

not_reference¶

search for photos not stored by reference (that is, they are managed by Photos)

Type:: Optional[bool]

not_screenshot¶

search for non-screenshot photos

Type:: Optional[bool]

not_screen_recording¶

search for non-screen recordings videos

Type:: Optional[bool]

not_selfie¶

search for non-selfie photos

Type:: Optional[bool]

not_shared¶

search for non-shared photos

Type:: Optional[bool]

not_slow_mo¶

search for non-slow-mo photos

Type:: Optional[bool]

not_time_lapse¶

search for non-time-lapse photos

Type:: Optional[bool]

panorama¶

search for panorama photos

Type:: Optional[bool]

person¶

list of person names to search for

Type:: Optional[Iterable[str]]

photos¶

search for photos

Type:: Optional[bool]

place¶

list of place names to search for

Type:: Optional[Iterable[str]]

portrait¶

search for portrait photos

Type:: Optional[bool]

query_eval¶

list of query expressions to evaluate

Type:: Optional[Iterable[str]]

regex¶

list of regular expressions to search for

Type:: Optional[Iterable[Tuple[str, str]]]

screenshot¶

search for screenshot photos

Type:: Optional[bool]

screen_recording¶

search for screen recording videos

Type:: Optional[bool]

selected¶

search for selected photos

Type:: Optional[bool]

selfie¶

search for selfie photos

Type:: Optional[bool]

shared¶

search for shared photos

Type:: Optional[bool]

slow_mo¶

search for slow-mo photos

Type:: Optional[bool]

time_lapse¶

search for time-lapse photos

Type:: Optional[bool]

title¶

list of titles to search for

Type:: Optional[Iterable[str]]

to_date¶

search for photos taken before this date

Type:: Optional[datetime.datetime]

to_time¶

search for photos taken before this time of day

Type:: Optional[datetime.time]

uti¶

list of UTIs to search for

Type:: Optional[Iterable[str]]

uuid¶

list of uuids to search for

Type:: Optional[Iterable[str]]

year¶

search for photos taken in a given year

Type:: Optional[Iterable[int]]

syndicated¶

search for photos that have been shared via syndication (“Shared with You” album via Messages, etc.)

Type:: Optional[bool]

not_syndicated¶

search for photos that have not been shared via syndication (“Shared with You” album via Messages, etc.)

Type:: Optional[bool]

saved_to_library¶

search for syndicated photos that have been saved to the Photos library

Type:: Optional[bool]

not_saved_to_library¶

search for syndicated photos that have not been saved to the Photos library

Type:: Optional[bool]

shared_moment¶

search for photos that have been shared via a shared moment

Type:: Optional[bool]

not_shared_moment¶

search for photos that have not been shared via a shared moment

Type:: Optional[bool]

shared_library¶

search for photos that are part of a shared iCloud library

Type:: Optional[bool]

not_shared_library¶

search for photos that are not part of a shared iCloud library

Type:: Optional[bool]

class osxphotos.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)[source]¶

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

asdict()[source]¶: Return ScoreInfo as a dict

class osxphotos.SearchInfo(photo, normalized=False)[source]¶

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()[source]¶: return dict of search info

property bodies_of_water¶: returns list of body of water names

property camera¶: returns camera name (macOS 13+ / Photos 8+ only)

property city¶: returns city/town

property country¶: returns country name

property detected_text¶: Returns text detected in the photo (macOS 13+ / Photos 8+ only)

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 source¶: returns source of the photo (e.g. “Messages”, “Safar”, etc) (macOS 13+ / Photos 8+ only)

property state¶: returns state name

property state_abbreviation¶: returns state abbreviation

property streets¶: returns list of street names

property text_found¶: Returns True if photos has detected text (macOS 13+ / Photos 8+ only)

property venue_types¶: returns list of venue types

property venues¶: returns list of venue names

property year¶: returns year

class osxphotos.SidecarWriter(photo: PhotoInfo)[source]¶

Write sidecars for PhotoInfo objects

Can write XMP, JSON, and exiftool sidecars

Parameters:: photo – PhotoInfo object

Note

Sidecars are written by calling write_sidecar_files() which returns an ExportResults object

write_sidecar_files(dest: Path, options: ExportOptions) → ExportResults[source]¶

Write sidecar files for the photo.

Parameters:

dest – destination path for photo that sidecars are being written for
options – ExportOptions object that configures the sidecars

Returns:

An ExportResults object containing information about the exported sidecar files in the following attributes:

sidecar_json_written: list of JSON sidecar files written

sidecar_json_skipped: list of JSON sidecar files skipped

sidecar_exiftool_written: list of exiftool JSON sidecar files written

sidecar_exiftool_skipped: list of exiftool JSON sidecar files skipped

sidecar_xmp_written: list of XMP sidecar files written

sidecar_xmp_skipped: list of XMP sidecar files skipped

Note

dest is the path to the the sidecar belongs to. THe sidecar filename will be dest.ext where ext is the extension for sidecar (e.g. xmp or json) If dest is “img_1234.jpg”, XMP sidecar would be “img_1234.jpg.xmp” Use ExportOptions(sidecar_drop_ext) to drop the image extension from the sidecar filename (e.g. “img_1234.xmp”)

xmp_sidecar(options: ExportOptions | None = None, extension: str | None = None)[source]¶

returns string for XMP sidecar

Parameters:

options (ExportOptions) – options for export
extension (Optional[str]) – which extension to use for SidecarForExtension property

class osxphotos.iPhotoAlbumInfo(album: dict[str, Any], db: iPhotoDB)[source]¶

AlbumInfo class for iPhoto

asdict() → dict[str, Any][source]¶: Return album info as a dict; does not include photos

property folder_list: list[iPhotoFolderInfo]¶: Returns hierachical list of iPhotoFolderInfo objects for each folder the album is contained in or empty list if album is not in any folders

property folder_names: list[str]¶: 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”, …] or empty list if album is not in any folders

json() → str[source]¶: JSON representation of album

property parent: iPhotoFolderInfo | None¶: returns iPhotoFolderInfo object for parent folder or None if no parent (e.g. top-level album)

photo_index(photo: iPhotoPhotoInfo) → int[source]¶: Return index of photo in album; not implemented, always 0

property photos: list[iPhotoPhotoInfo]¶: Return list of photos contained in the album

property sort_order: int¶: Return sort order; not implemented, always 0

property title: str¶: Title of album

property uuid: str¶: UUID of album

class osxphotos.iPhotoDB(dbfile: str, verbose: Callable[[...], None] = None, exiftool: str | None = None, rich: bool = False, _skip_searchinfo: bool = True)[source]¶

Read an iPhoto library database; interface matches osxphotos.PhotosDB

property album_info: list[iPhotoAlbumInfo]¶: Return list of iPhotoAlbumInfo objects for each album in the library

property albums: list[str]¶: Return list of album names

property albums_as_dict: dict[str, int]¶: Return albums as dict of list of albums keyed by count of photos

property db_version: str¶: Return the database version as stored in Library.apdb RKAdminData table

get_db_connection() → tuple[Connection, Cursor][source]¶

Get connection to the working copy of the Photos database

Returns:: tuple of (connection, cursor) to sqlite3 database
Raises:: NotImplementedError on iPhoto –

get_photo(uuid: str) → iPhotoPhotoInfo[source]¶: Return photo by uuid

property keywords_as_dict: dict[str, int]¶: Return keywords as dict of list of keywords keyed by count of photos

property persons_as_dict: dict[str, list[str]]¶: Return persons as dict of list of persons keyed count of photos

photos(keywords: list[str] | None = None, uuid: list[str] | None = None, persons: list[str] | None = None, albums: list[str] | None = None, images: bool = True, movies: bool = True, from_date: datetime | None = None, to_date: datetime | None = None, intrash: bool = False) → list[iPhotoPhotoInfo][source]¶

Return a list of iPhotoPhotoInfo 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 iPhotoPhotoInfo objects

property photos_version: str¶: Returns version of the library as a string

query(options: QueryOptions) → list[iPhotoPhotoInfo][source]¶

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

Parameters:: options – a QueryOptions instance

class osxphotos.iPhotoFaceInfo(photo: iPhotoPhotoInfo, face: dict[str, Any], db: iPhotoDB)[source]¶

FaceInfo implementation for iPhoto

asdict() → dict[str, Any][source]¶: Returns dict representation of class instance

property center: tuple[int, int]¶

Coordinates, in PIL format, for center of face

Returns:: tuple of coordinates in form (x, y)

property center_x: float¶: X coordinate for center of face as percent of width

property center_y: float¶: Y coordinate for center of face as percent of height

face_rect() → list[tuple[int, int]][source]¶

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

json() → str[source]¶: Return JSON representation of iPhotoFaceInfo instance

property mpri_reg_rect: MPRI_Reg_Rect¶

Get coordinates for Microsoft Photo Region Rectangle.

Returns:: 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
Return type:: MPRI_Reg_Rect named tuple with x, y, h, w where

Reference:: https://docs.microsoft.com/en-us/windows/win32/wic/-wic-people-tagging

property mwg_rs_area: MWG_RS_Area¶

Get coordinates for Metadata Working Group Region Area.

Returns:: x = stArea:x y = stArea:y h = stArea:h w = stArea:w
Return type:: MWG_RS_Area named tuple with x, y, h, w where

Reference:: https://photo.stackexchange.com/questions/106410/how-does-xmp-define-the-face-region

property name: str | None¶: Name of person in the photo or None

property person_info: iPhotoPersonInfo¶: iPhotoPersonInfo object for face

property pitch: float¶: Return pitch angle in radians of the face region

property quality: float¶: Quality (confidence) of face detection

property roll: float¶: Return roll angle in radians of the face region

roll_pitch_yaw() → tuple[float, float, float][source]¶: Roll, pitch, yaw of face in radians as tuple

property size: float¶: Size of face as percent of image width

property size_pixels: int¶

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

property yaw: float¶: Return yaw angle in radians of the face region

class osxphotos.iPhotoFolderInfo(folder: dict[Any, Any], db: iPhotoDB)[source]¶

Info about a specific folder, contains all the details about the folder including folders, albums, etc

property album_info: list[iPhotoAlbumInfo]¶: Return list of albums (as iPhotoAlbumInfo objects) contained in the folder

asdict() → dict[str, Any][source]¶: Return folder info as a dict

json() → str[source]¶: Return folder info as json

property parent: iPhotoFolderInfo | None¶: Return iPhotoFolderInfo object for parent or None if no parent (e.g. top-level folder)

property subfolders: list[iPhotoFolderInfo]¶: Return list of folders (as FolderInfo objects) contained in the folder

property title: str¶: Title of folder

property uuid: str¶: UUID of folder

class osxphotos.iPhotoPersonInfo(face: dict[str, Any], db: iPhotoDB)[source]¶

PersonInfo implementation for iPhoto

asdict() → dict[str, Any][source]¶: Return person as dict

property facecount: int¶: Count of faces for person

property favorite: bool¶: Returns False for iPhoto

property feature_less: bool¶: Always returns False for iPhoto

json() → str[source]¶: Return person as json

property keyface: iPhotoFaceInfo | None¶: Key face for person

property keyphoto: iPhotoPhotoInfo | None¶: Key photo for person

property name: str¶: Name of person

property photos: list[iPhotoPhotoInfo]¶: List of photos face is contained in

property sort_order: int¶: Always returns 0 for iPhoto

property uuid: str¶: UUID of person

class osxphotos.iPhotoPhotoInfo(uuid: str, db: iPhotoDB)[source]¶

PhotoInfo implementation for iPhoto

property album_info: list[iPhotoAlbumInfo]¶: “Return list of iPhotoAlbumInfo objects for photo

property albums: list[str]¶: List of albums photo is contained in

asdict(shallow: bool = True) → dict[str, Any][source]¶

Return dict representation of iPhotoPhotoInfo object.

Parameters:: shallow – if True, return shallow representation (does not contain folder_info, person_info, etc.)
Returns:: dict representation of iPhotoPhotoInfo object

Note

The shallow representation is used internally by export as it contains only the subset of data needed for export.

property burst: bool¶: Returns True if photo is part of a Burst photo set, otherwise False

property burst_album_info: list[iPhotoAlbumInfo]¶: For iPhoto, returns self.album_info; this is different behavior than Photos

property burst_albums: list[str]¶: For iPhoto, returns self.albums; this is different behavior than Photos

property burst_photos: list[PhotoInfo]¶: If photo is a burst photo, returns list of iPhotoPhotoInfo objects that are part of the same burst photo set; otherwise returns empty list. self is not included in the returned list

property date: datetime¶: Date photo was taken

property date_added: datetime¶: Date added to library

property date_modified: datetime¶: Date modified in library

property description: str¶: Description of photo

property event_info: iPhotoEventInfo | None¶: Return iPhotoEventInfo object for photo or None if photo is not in an event

property exif_info: iPhotoExifInfo¶: Return iPhotoExifInfo object for photo

property exiftool: ExifToolCaching | None¶: 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: str, filename: str | None = None, edited: bool = False, raw_photo: bool = False, export_as_hardlink: bool = False, overwrite: bool = False, increment: bool = True, sidecar_json: bool = False, sidecar_exiftool: bool = False, sidecar_xmp: bool = False, exiftool: bool = False, use_albums_as_keywords: bool = False, use_persons_as_keywords: bool = False, keyword_template: list[str] | None = None, description_template: str | None = None, render_options: RenderOptions | None = None, **kwargs) → list[str][source]¶

Export a photo

Parameters:

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 iPhotoPhotoInfo.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)
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
exiftool – (boolean, default = False); if True, will use exiftool to write metadata to export file
files (returns list of full paths to the exported)
use_albums_as_keywords – (boolean, default = False); if True, will include album names in keywords
sidecar (when exporting metadata with exiftool or)
use_persons_as_keywords – (boolean, default = False); if True, will include person names in keywords
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 paths to photos exported

property face_info: list[iPhotoFaceInfo]¶: List of iPhotoFaceInfo objects for photo

property favorite: bool¶: Returns True if photo is favorite; iPhoto doesn’t have favorite so always returns False

property filename: str¶: Filename of photo

property fingerprint: str | None¶: Returns fingerprint of original photo as a string; returns None if not available. On linux, returns None.

property flagged: bool¶: Returns True if photo is flagged

property hasadjustments: bool¶: True if photo has adjustments

property height: int¶: Height of photo in pixels

property hexdigest: str¶: Returns a unique digest of the photo’s properties and metadata; useful for detecting changes in any property/metadata of the photo

property hidden: bool¶: True if photo is hidden

property intrash: bool¶: True if photo is in the Photos trash

property ismissing: bool¶: Return True if asset is missing

property ismovie: bool¶: Return True if asset is a movie

property isphoto: bool¶: Return True if asset is a photo

property israw: bool¶: Return True if asset is a raw image

property isreference: bool¶: Return True if asset is a referenced file

json(indent: int | None = None, shallow: bool = True) → str[source]¶

Return JSON representation

Parameters:

indent – indent level for JSON, if None, no indent
shallow – if True, return shallow JSON representation (does not contain folder_info, person_info, etc.)

Returns:

JSON string

Note

The shallow representation is used internally by export as it contains only the subset of data needed for export.

property keywords: list[str]¶: Keywords for photo

property latitude: float | None¶: Latitude of photo

property location: tuple[float, float] | tuple[None, None]¶: Location of photo as (latitude, longitude)

property longitude: float | None¶: Longitude of photo

property moment_info: iPhotoMomentInfo | None¶: Return iPhotoMomentInfo object for photo or None if photo is not in a moment; for iPhoto returns event as moment

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

property original_filename: str¶: Original filename of photo

property original_filesize: int¶: Size of original file in bytes

property original_height: int¶: Original height of photo in pixels

property original_width: int¶: Original width of photo in pixels

property path: str | None¶: Path to original photo asset in library

property path_derivatives: list[str]¶: Path to derivatives in library

property path_edited: str | None¶: Path to edited asset in library

property person_info: list[iPhotoPersonInfo]¶: List of iPhotoPersonInfo objects for photo

property persons: list[str]¶: List of persons in photo

property rating: int¶: Rating of photo as int from 0 to 5

property raw_original: bool¶: Return True if asset original is a raw image

render_template(template_str: str, options: RenderOptions | None = None) → tuple[list[str], list[str]][source]¶

Renders a template string for iPhotoPhotoInfo 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 title: str | None¶: Title of photo

property tzoffset: int¶: TZ Offset from GMT in seconds

property uti: str | None¶: UTI of current version of photo (edited if hasadjustments, otherwise original)

property uti_edited: str | None¶: UTI of edited version of photo

property uti_original: str | None¶: UTI of original version of photo

property uti_raw: str | None¶: UTI of raw version of photo

property uuid: str¶: UUID of photo

property visible: bool¶: True if photo is visible in Photos; always returns False for iPhoto

property width: int¶: Width of photo in pixels

osxphotos.is_debug()[source]¶: return debug flag

osxphotos.set_debug(debug: bool)[source]¶: set debug flag