OSXPhotos Python Package Overview#
Example uses of the OSXPhotos python package#
""" Simple usage of the package """
import osxphotos
def main():
photosdb = osxphotos.PhotosDB()
print(photosdb.keywords)
print(photosdb.persons)
print(photosdb.album_names)
print(photosdb.keywords_as_dict)
print(photosdb.persons_as_dict)
print(photosdb.albums_as_dict)
# find all photos with Keyword = Foo and containing John Smith
photos = photosdb.photos(keywords=["Foo"],persons=["John Smith"])
# find all photos that include Alice Smith but do not contain the keyword Bar
photos = [p for p in photosdb.photos(persons=["Alice Smith"])
if p not in photosdb.photos(keywords=["Bar"]) ]
for p in photos:
print(
p.uuid,
p.filename,
p.original_filename,
p.date,
p.description,
p.title,
p.keywords,
p.albums,
p.persons,
p.path,
)
if __name__ == "__main__":
main()
""" Export all photos to specified directory using album names as folders
If file has been edited, also export the edited version,
otherwise, export the original version
This will result in duplicate photos if photo is in more than album """
import os.path
import pathlib
import sys
import click
from pathvalidate import is_valid_filepath, sanitize_filepath
import osxphotos
@click.command()
@click.argument("export_path", type=click.Path(exists=True))
@click.option(
"--default-album",
help="Default folder for photos with no album. Defaults to 'unfiled'",
default="unfiled",
)
@click.option(
"--library-path",
help="Path to Photos library, default to last used library",
default=None,
)
def export(export_path, default_album, library_path):
export_path = os.path.expanduser(export_path)
library_path = os.path.expanduser(library_path) if library_path else None
if library_path is not None:
photosdb = osxphotos.PhotosDB(library_path)
else:
photosdb = osxphotos.PhotosDB()
photos = photosdb.photos()
for p in photos:
if not p.ismissing:
albums = p.albums
if not albums:
albums = [default_album]
for album in albums:
click.echo(f"exporting {p.filename} in album {album}")
# make sure no invalid characters in destination path (could be in album name)
album_name = sanitize_filepath(album, platform="auto")
# create destination folder, if necessary, based on album name
dest_dir = os.path.join(export_path, album_name)
# verify path is a valid path
if not is_valid_filepath(dest_dir, platform="auto"):
sys.exit(f"Invalid filepath {dest_dir}")
# create destination dir if needed
if not os.path.isdir(dest_dir):
os.makedirs(dest_dir)
# export the photo
if p.hasadjustments:
# export edited version
exported = p.export(dest_dir, edited=True)
edited_name = pathlib.Path(p.path_edited).name
click.echo(f"Exported {edited_name} to {exported}")
# export unedited version
exported = p.export(dest_dir)
click.echo(f"Exported {p.filename} to {exported}")
else:
click.echo(f"Skipping missing photo: {p.filename}")
if __name__ == "__main__":
export()
OSXPhotos REPL#
The osxphotos command line interface includes a REPL (Run-Evaluate-Print Loop) for testing and development.
The REPL is started with the command: osxphotos repl:
$ osxphotos repl
python version: 3.10.2 (main, Feb 2 2022, 07:36:01) [Clang 12.0.0 (clang-1200.0.32.29)]
osxphotos version: 0.47.10
Using last opened Photos library: /Users/user/Pictures/Photos Library.photoslibrary
Loading database
Processing database /Users/user/Pictures/Photos Library.photoslibrary/database/photos.db
Processing database /Users/user/Pictures/Photos Library.photoslibrary/database/Photos.sqlite
Database locked, creating temporary copy.
Processing database.
Database version: 6000, 5.
Processing persons in photos.
Processing detected faces in photos.
Processing albums.
Processing keywords.
Processing photo details.
Processing import sessions.
Processing additional photo details.
Processing face details.
Processing photo labels.
Processing EXIF details.
Processing computed aesthetic scores.
Processing comments and likes for shared photos.
Processing moments.
Done processing details from Photos library.
Done: took 18.54 seconds
Getting photos
Found 31581 photos in 0.77 seconds
The following classes have been imported from osxphotos:
- AlbumInfo, ExifTool, PhotoInfo, PhotoExporter, ExportOptions, ExportResults, PhotosDB, PlaceInfo, QueryOptions, MomentInfo, ScoreInfo, SearchInfo
The following variables are defined:
- photosdb: PhotosDB() instance for '/Users/user/Pictures/Photos Library.photoslibrary'
- photos: list of PhotoInfo objects for all photos filtered with any query options passed on command line (len=31581)
- all_photos: list of PhotoInfo objects for all photos in photosdb, including those in the trash (len=31581)
- selected: list of PhotoInfo objects for any photos selected in Photos (len=0)
The following functions may be helpful:
- get_photo(uuid): return a PhotoInfo object for photo with uuid; e.g. get_photo('B13F4485-94E0-41CD-AF71-913095D62E31')
- get_selected(); return list of PhotoInfo objects for photos selected in Photos
- show(photo): open a photo object in the default viewer; e.g. show(selected[0])
- show(path): open a file at path in the default viewer; e.g. show('/path/to/photo.jpg')
- spotlight(photo): open a photo and spotlight it in Photos
- inspect(object): print information about an object; e.g. inspect(PhotoInfo)
- explore(object): interactively explore an object with objexplore; e.g. explore(PhotoInfo)
- q, quit, quit(), exit, exit(): exit this interactive shell
>>>
Using the osxphotos CLI to run python code#
The osxphotos CLI can also be used to run your own python code using the osxphotos run command.
This is useful if you have installed the CLI using pipx but want to use the osxphotos programmatic interface in your own scripts.
If you need to install any additional python packages to use in your own scripts, you can use the osxphotos install command
which installs python packages just as pip does but into the same virtual environment that osxphotos is installed in.
Likewise, you can use osxphotos uninstall to uninstall any installed python packages.
These features are also useful for developing custom functions to use with --query-function and --post-function
as well as {function} templates and function: filters.