Skip to main content

Python wrapper around Apple Photos applescript interface

Project description

PhotoScript

Code style: black License: MIT

All Contributors

What is PhotoScript

PhotoScript provides a python wrapper around Apple Photos applescript interface. With PhotoScript you can interact with Photos using python. Runs only on MacOS. Tested on MacOS Catalina.

PhotosScript is limited by Photos' very limited AppleScript dictionary.

Compatibility

Designed for MacOS Catalina/Photos 5. Preliminary testing on Big Sur/Photos 6 beta shows this should work on Big Sur as well. Photos' AppleScript interface has changed very little since Photos 2 (the earliest version I have access to). This package should work with most versions of Photos but some methods may not function correctly on versions earlier than Photos 5. If you find compatibility issues, open an issue or send a PR.

Installation

You can install via pip:

python3 -m pip install photoscript

To install via the source code:

  • Install uv if not already installed
  • Clone the repo: git clone git@github.com:RhetTbull/PhotoScript.git
  • Change to the directory: cd PhotoScript
  • Run uv pip install -r pyproject.toml.

If you want to develop code for PhotoScript, see README_DEV.md.

Example

""" Simple example showing use of photoscript """

import photoscript

photoslib = photoscript.PhotosLibrary()

photoslib.activate()
print(f"Running Photos version: {photoslib.version}")

album = photoslib.album("Album1")
photos = album.photos()

for photo in photos:
    photo.keywords = ["travel", "vacation"]
    print(f"{photo.title}, {photo.description}, {photo.keywords}")

new_album = photoslib.create_album("New Album")
photoslib.import_photos(["/Users/rhet/Downloads/test.jpeg"], album=new_album)

photoslib.quit()

Documentation

Full documentation here.

Additional documentation about Photos and AppleScript available on the wiki.

Testing

Tested on MacOS Catalina, Photos 5 with 100% coverage.

Limitations

Photos' AppleScript interface is very limited. For example, it cannot access information on faces in photos nor can it delete a photo. PhotoScript is thus limited. PhotoScript works by executing AppleScript through an Objective-C bridge from python. Every method call has to do a python->Objective C->AppleScript round trip; this makes the interface much slower than native python code. This is particularly noticeable when dealing with Folders which requires significant work arounds.

Where possible, PhotoScript attempts to provide work-arounds to Photos' limitations. For example, Photos does not provide a way to remove a photo from an album. PhotoScript does provide a Album.remove() method but in order to do this, it creates a new album with the same name as the original, copies all but the removed photos to the new album then deletes the original album. This simulates removing photos and produces the desired effect but is not the same thing as removing a photo from an album.

Related Projects

  • osxphotos: Python package that provides read-only access to the Photos library including all associated metadata.

Dependencies

Contributors ✨

Thanks goes to these wonderful people (emoji key):

David Haberthür
David Haberthür

📖
André Anjos
André Anjos

🤔 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

See Also

For a more comprehensive python interface for Mac automation, see PyXA which provides a python interface to Photos and many other Mac applications.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

photoscript-0.4.0.tar.gz (26.3 kB view details)

Uploaded Source

Built Distribution

photoscript-0.4.0-py3-none-any.whl (24.3 kB view details)

Uploaded Python 3

File details

Details for the file photoscript-0.4.0.tar.gz.

File metadata

  • Download URL: photoscript-0.4.0.tar.gz
  • Upload date:
  • Size: 26.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.5.1

File hashes

Hashes for photoscript-0.4.0.tar.gz
Algorithm Hash digest
SHA256 5b00d663b7b2c2450d54fbba8a9d4864be5beb9396eac47e1dd3aeaecdc34366
MD5 4e8574fb09b90a2ea3f0a74f9931ece2
BLAKE2b-256 cbcb39b1db76fdfa4439de0c5e90fc20ffdeb9dedd01e62b0dce56ee954caf81

See more details on using hashes here.

File details

Details for the file photoscript-0.4.0-py3-none-any.whl.

File metadata

File hashes

Hashes for photoscript-0.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 051a9fb96e948e0ca6f195b7fdc631f80e02d2864ba2acff70d5bee706a44d75
MD5 60e05db4203364bc0130a411f1296ca0
BLAKE2b-256 9af12d9e5f687a88b025bc88b945ed290989343906d509740f2bf8627319534b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page