Photos Module Reference

New in version 0.0.2.

Control the macOS Photos application using JXA-like syntax.

Todo

Add support for folders and containers
Add image operations such as rotate, flip
Add ability to add new albums
Add ability to move photos to albums/folders

Classes:

`XAPhotosAlbum`(properties)	An album in Photos.app.
`XAPhotosAlbumList`(properties[, filter])	A wrapper around lists of albums that employs fast enumeration techniques.
`XAPhotosApplication`(properties)	A class for managing and interacting with Photos.app.
`XAPhotosContainer`(properties)	A class for...
`XAPhotosContainerList`(properties[, filter, ...])	A wrapper around lists of containers that employs fast enumeration techniques.
`XAPhotosFolder`(properties)	A folder in Photos.app.
`XAPhotosFolderList`(properties[, filter])	A wrapper around lists of folders that employs fast enumeration techniques.
`XAPhotosMediaItem`(properties)	A photo or video in Photos.app.
`XAPhotosMediaItemList`(properties[, filter])	A wrapper around lists of media items that employs fast enumeration techniques.

class PyXA.apps.PhotosApp.XAPhotosAlbum(properties)[source]

Bases: XAPhotosContainer

An album in Photos.app.

New in version 0.0.2.

Methods:

media_items([filter])

Returns a list of media items, as PyXA objects, matching the given filter.

media_items(filter: dict | None = None) → XAPhotosMediaItemList[source]

Returns a list of media items, as PyXA objects, matching the given filter.

Parameters:: filter (Union[dict, None]) – A dictionary specifying property-value pairs that all returned media items will have, or None
Returns:: The list of media items
Return type:: XAPhotosMediaItemList

New in version 0.0.6.

class PyXA.apps.PhotosApp.XAPhotosAlbumList(properties: dict, filter: dict | None = None)[source]

Bases: XAPhotosContainerList

A wrapper around lists of albums that employs fast enumeration techniques.

All properties of albums can be called as methods on the wrapped list, returning a list containing each album’s value for the property.

New in version 0.0.6.

Methods:

push(container)

Appends the object referenced by the provided PyXA wrapper to the end of the list.

push(container: XAPhotosContainer)[source]: Appends the object referenced by the provided PyXA wrapper to the end of the list.

New in version 0.0.3.

class PyXA.apps.PhotosApp.XAPhotosApplication(properties)[source]

Bases: XASBApplication, XACanOpenPath

A class for managing and interacting with Photos.app.

New in version 0.0.2.

Classes:

ObjectType(value)

Types of objects that can be created using XAPhotosApplication.make().

Methods:

`add`(media_items, album)	Adds the given list of media items to the specified album.
`albums`([filter])	Returns a list of albums, as PyXA objects, matching the given filter.
`containers`([filter])	Returns a list of containers, as PyXA objects, matching the given filter.
`export`(media_items, destination_path[, ...])	Exports a list of media items to the specified folder.
`folders`([filter])	Returns a list of folders, as PyXA objects, matching the given filter.
`import_files`(files[, destination_album, ...])	Imports a list of files into the specified album.
`make`(specifier[, properties, data])	Creates a new element of the given specifier class without adding it to any list.
`media_items`([filter])	Returns a list of media items, as PyXA objects, matching the given filter.
`next_slide`()	Skips to the next slide in the currently playing slideshow.
`open`(path)	Imports the file at the given filepath without adding it to any particular album.
`pause_slideshow`()	Pauses the currently playing slideshow.
`previous_slide`()	Skips to the previous slide in the currently playing slideshow.
`resume_slideshow`()	Resumes the currently playing slideshow (from a paused state).
`search`(query)	Searches for items matching the given search string.
`start_slideshow`(item_list)	Starts an ad-hoc slideshow from the given list of media items, an album, or a folder.
`stop_slideshow`()	Stops the currently playing slideshow.

Attributes:

`favorites_album`	Favorited media items album.
`frontmost`	Whether Photos is the frontmost application.
`library_path`	The path to the Photos library container.
`name`	The name of the application.
`properties`	All properties of the application.
`recently_deleted_album`	The set of recently deleted media items.
`selection`	The currently selected media items in the application.
`slideshow_running`	Returns true if a slideshow is currently running.
`version`	The version of Photos.app.

class ObjectType(value)[source]

Bases: Enum

Types of objects that can be created using XAPhotosApplication.make().

Attributes:

`ALBUM`
`FOLDER`

ALBUM = 'album'

FOLDER = 'folder'

add(media_items: XAPhotosMediaItemList | list[XAPhotosMediaItem], album: XAPhotosAlbum) → XAPhotosApplication[source]

Adds the given list of media items to the specified album.

Parameters:

media_items (Union[XAPhotosMediaItemList, list[XAPhotosMediaItem]]) – The media items to add
album (XAPhotosAlbum) – The album to add the media items to

Returns:

The Photos application object

Return type:

XAPhotosApplication

New in version 0.0.6.

albums(filter: dict | None = None) → XAPhotosAlbumList[source]

Returns a list of albums, as PyXA objects, matching the given filter.

Parameters:: filter (Union[dict, None]) – A dictionary specifying property-value pairs that all returned albums will have, or None
Returns:: The list of albums
Return type:: XAPhotosAlbumList

New in version 0.0.6.

containers(filter: dict | None = None) → XAPhotosContainerList[source]

Returns a list of containers, as PyXA objects, matching the given filter.

Parameters:: filter (Union[dict, None]) – A dictionary specifying property-value pairs that all returned containers will have, or None
Returns:: The list of containers
Return type:: XAPhotosContainerList

New in version 0.0.6.

export(media_items: XAPhotosMediaItemList | list[XAPhotosMediaItem], destination_path: str | NSURL, use_originals: bool = False) → XAPhotosApplication[source]

Exports a list of media items to the specified folder.

Parameters:

media_items (Union[XAPhotosMediaItemList, list[XAPhotosMediaItem]]) – The media items to export
destination_path (Union[str, NSURL]) – The folder to store the exported files in
use_originals (bool, optional) – Whether to export the original files or rendered jpgs, defaults to False

Returns:

The Photos application object

Return type:

XAPhotosApplication

New in version 0.0.6.

property favorites_album: XAPhotosAlbum: Favorited media items album.

folders(filter: dict | None = None) → XAPhotosFolderList[source]

Returns a list of folders, as PyXA objects, matching the given filter.

Parameters:: filter (Union[dict, None]) – A dictionary specifying property-value pairs that all returned folders will have, or None
Returns:: The list of folders
Return type:: XAPhotosFolderList

New in version 0.0.6.

property frontmost: bool: Whether Photos is the frontmost application.

import_files(files: list[str | NSURL], destination_album: XAPhotosAlbum | None = None, skip_duplicate_checking: bool = False) → XAPhotosMediaItemList[source]

Imports a list of files into the specified album.

Parameters:

files (list[Union[str, NSURL]]) – The files to import
destination_album (Union[XAPhotosAlbum, None], optional) – The album to import items into, defaults to None
skip_duplicate_checking (bool, optional) – Whether the skip checking duplicates and import everything, defaults to False

Returns:

The list of imported media items

Return type:

XAPhotosMediaItemList

New in version 0.0.6.

property library_path: XAPath: The path to the Photos library container.

make(specifier: str | ObjectType, properties: dict | None = None, data: Any | None = None)[source]

Creates a new element of the given specifier class without adding it to any list.

Use XABase.XAList.push() to push the element onto a list.

Parameters:

specifier (Union[str, XAPhotosApplication.ObjectType]) – The classname of the object to create
properties (dict) – The properties to give the object
data (Any, optional) – The data to initialize the object with, defaults to None

Returns:

A PyXA wrapped form of the object

Return type:

XABase.XAObject

Example 1:

Make a new album

>>> import PyXA
>>> app = PyXA.Application("Photos")
>>> new_album = app.make("album", {"name": "PyXA"})
>>> app.albums().push(new_album)

New in version 0.0.6.

media_items(filter: dict | None = None) → XAPhotosMediaItemList[source]

Returns a list of media items, as PyXA objects, matching the given filter.

Parameters:: filter (Union[dict, None]) – A dictionary specifying property-value pairs that all returned media items will have, or None
Returns:: The list of media items
Return type:: XAPhotosMediaItemList

New in version 0.0.6.

property name: str: The name of the application.

next_slide() → XAPhotosApplication[source]

Skips to the next slide in the currently playing slideshow.

Returns:: The Photos application object
Return type:: XAPhotosApplication

New in version 0.0.6.

open(path: str | XAPath | list[str | XAPath]) → XAPhotosApplication[source]

Imports the file at the given filepath without adding it to any particular album.

Parameters:: target (Union[str, XABase.XAPath, list[str, list[XABase.XAPath]]]) – The path to a file to import into photos.
Returns:: The Photos application object
Return type:: XAPhotosApplication

New in version 0.0.1.

pause_slideshow() → XAPhotosApplication[source]

Pauses the currently playing slideshow.

Returns:: The Photos application object
Return type:: XAPhotosApplication

New in version 0.0.6.

previous_slide() → XAPhotosApplication[source]

Skips to the previous slide in the currently playing slideshow.

Returns:: The Photos application object
Return type:: XAPhotosApplication

New in version 0.0.6.

property properties: dict: All properties of the application.

property recently_deleted_album: XAPhotosAlbum: The set of recently deleted media items.

resume_slideshow() → XAPhotosApplication[source]

Resumes the currently playing slideshow (from a paused state).

Returns:: The Photos application object
Return type:: XAPhotosApplication

New in version 0.0.6.

search(query: str) → XAPhotosMediaItemList[source]

Searches for items matching the given search string.

Parameters:: query (str) – The string to search
Returns:: A list of media items matching the search query
Return type:: XAPhotosMediaItemList

New in version 0.0.6.

property selection: XAPhotosMediaItemList: The currently selected media items in the application.

property slideshow_running: bool: Returns true if a slideshow is currently running.

start_slideshow(item_list: XAPhotosMediaItemList | XAPhotosAlbum | XAPhotosFolder) → XAPhotosApplication[source]

Starts an ad-hoc slideshow from the given list of media items, an album, or a folder.

Parameters:: item_list (Union['XAPhotosMediaItemList', 'XAPhotosAlbum', 'XAPhotosFolder']) – The list of media items, an album, or a folder to create a slideshow from
Returns:: The Photos application object
Return type:: XAPhotosApplication

New in version 0.0.6.

stop_slideshow() → XAPhotosApplication[source]

Stops the currently playing slideshow.

Returns:: The Photos application object
Return type:: XAPhotosApplication

New in version 0.0.6.

property version: str: The version of Photos.app.

class PyXA.apps.PhotosApp.XAPhotosContainer(properties)[source]

Bases: XAObject, XAClipboardCodable

A class for…

Methods:

`get_clipboard_representation`()	Gets a clipboard-codable representation of the container.
`spotlight`()	Shows the container in the front window of Photos.app.

Attributes:

`id`	The unique ID of this container.
`name`	The name of this container.
`parent`	This container's parent folder, if any.
`properties`	All properties of the container.

get_clipboard_representation() → str[source]

Gets a clipboard-codable representation of the container.

When the clipboard content is set to a container, the containers’s name is added to the clipboard.

Returns:: The container’s name
Return type:: str

New in version 0.0.8.

property id: str: The unique ID of this container.

property name: str: The name of this container.

property parent: XAPhotosFolder: This container’s parent folder, if any.

property properties: dict: All properties of the container.

spotlight() → XAPhotosContainer[source]

Shows the container in the front window of Photos.app.

Returns:: The container object
Return type:: XAPhotosContainer

New in version 0.0.6.

class PyXA.apps.PhotosApp.XAPhotosContainerList(properties: dict, filter: dict | None = None, obj_class=None)[source]

Bases: XAList, XAClipboardCodable

A wrapper around lists of containers that employs fast enumeration techniques.

All properties of containers can be called as methods on the wrapped list, returning a list containing each container’s value for the property.

New in version 0.0.6.

Methods:

`by_id`(id)
`by_name`(name)
`by_parent`(parent)
`by_properties`(properties)
`get_clipboard_representation`()	Gets a clipboard-codable representation of each container in the list.
`id`()
`name`()
`parent`()
`properties`()

by_id(id: str) → XAPhotosContainer | None[source]

by_name(name: str) → XAPhotosContainer | None[source]

by_parent(parent: XAPhotosFolder) → XAPhotosContainer | None[source]

by_properties(properties: dict) → XAPhotosContainer | None[source]

get_clipboard_representation() → str[source]

Gets a clipboard-codable representation of each container in the list.

When the clipboard content is set to a list of containers, each containers’s name is added to the clipboard.

Returns:: The container’s name
Return type:: str

New in version 0.0.8.

id() → list[str][source]

name() → list[str][source]

parent() → XAPhotosFolderList[source]

properties() → list[dict][source]

class PyXA.apps.PhotosApp.XAPhotosFolder(properties)[source]

Bases: XAPhotosContainer

A folder in Photos.app.

New in version 0.0.2.

Methods:

`albums`([filter])	Returns a list of albums, as PyXA objects, matching the given filter.
`containers`([filter])	Returns a list of containers, as PyXA objects, matching the given filter.
`folders`([filter])	Returns a list of folders, as PyXA objects, matching the given filter.

albums(filter: dict | None = None) → XAPhotosAlbumList[source]

Returns a list of albums, as PyXA objects, matching the given filter.

Parameters:: filter (Union[dict, None]) – A dictionary specifying property-value pairs that all returned albums will have, or None
Returns:: The list of albums
Return type:: XAPhotosAlbumList

New in version 0.0.6.

containers(filter: dict | None = None) → XAPhotosContainerList[source]

Returns a list of containers, as PyXA objects, matching the given filter.

Parameters:: filter (Union[dict, None]) – A dictionary specifying property-value pairs that all returned containers will have, or None
Returns:: The list of containers
Return type:: XAPhotosContainerList

New in version 0.0.6.

folders(filter: dict | None = None) → XAPhotosFolderList[source]

Returns a list of folders, as PyXA objects, matching the given filter.

Parameters:: filter (Union[dict, None]) – A dictionary specifying property-value pairs that all returned folders will have, or None
Returns:: The list of folders
Return type:: XAPhotosFolderList

New in version 0.0.6.

class PyXA.apps.PhotosApp.XAPhotosFolderList(properties: dict, filter: dict | None = None)[source]

Bases: XAPhotosContainerList

A wrapper around lists of folders that employs fast enumeration techniques.

All properties of folders can be called as methods on the wrapped list, returning a list containing each folder’s value for the property.

New in version 0.0.6.

Methods:

push(container)

Appends the object referenced by the provided PyXA wrapper to the end of the list.

push(container: XAPhotosContainer)[source]: Appends the object referenced by the provided PyXA wrapper to the end of the list.

New in version 0.0.3.

class PyXA.apps.PhotosApp.XAPhotosMediaItem(properties)[source]

Bases: XAObject, XAClipboardCodable, XAImageLike

A photo or video in Photos.app.

New in version 0.0.2.

Attributes:

`altitude`	The GPS altitude in meters.
`creation_date`	The creation date of the media item.
`duration`	The duration of the media item.
`favorite`	Whether the media item has been favorited.
`file_path`	The path to the main file for the media item.
`filename`	The name of the file on disk.
`height`	The height of the media item in pixels.
`id`	The unique ID of the media item.
`is_burst`	Whether the media item is a burst photo.
`is_hidden`	Whether the media item is hidden.
`is_photo`	Whether the media item is a photo.
`is_video`	Whether the media item is a video.
`keywords`	A list of keywords to associate with a media item.
`location`	The GPS latitude and longitude, in an ordered list of 2 numbers or missing values.
`modification_date`	The last modification date of the media item.
`name`	The name (title) of the media item.
`object_description`	A description of the media item.
`properties`	All properties of the media item.
`size`	The selected media item file size.
`width`	The width of the media item in pixels.

Methods:

`duplicate`()	Duplicates the media item.
`get_clipboard_representation`()	Gets a clipboard-codable representation of the media item.
`get_image_representation`()	Gets a representation of the object that can be used to initialize an `XAImage` object.
`reveal_in_finder`()	Opens a Finder window or tab focused on the media item's containing folder with the media item selected.
`show_in_preview`()	Opens the media item in Preview.app.
`spotlight`()	Shows the media item in the front window of Photos.app.

property altitude: float: The GPS altitude in meters.

property creation_date: datetime: The creation date of the media item.

duplicate() → XAPhotosMediaItem[source]

Duplicates the media item.

Returns:: The newly created media item object
Return type:: XAPhotosMediaItem

New in version 0.0.2.

property duration: float: The duration of the media item.

property favorite: bool: Whether the media item has been favorited.

property file_path: XAPath: The path to the main file for the media item.

property filename: str: The name of the file on disk.

get_clipboard_representation() → NSURL[source]

Gets a clipboard-codable representation of the media item.

When the clipboard content is set to a media item, the item’s file URL is added to the clipboard.

Returns:: The media item’s file URL
Return type:: NSURL

New in version 0.0.8.

get_image_representation() → XAPath[source]

Gets a representation of the object that can be used to initialize an XAImage object.

Returns:: The XAImage-compatible form of this object
Return type:: XABase.XAPath

property height: int: The height of the media item in pixels.

property id: str: The unique ID of the media item.

property is_burst: bool: Whether the media item is a burst photo.

property is_hidden: bool: Whether the media item is hidden.

property is_photo: bool: Whether the media item is a photo.

property is_video: bool: Whether the media item is a video.

property keywords: list[str]: A list of keywords to associate with a media item.

property location: XALocation: The GPS latitude and longitude, in an ordered list of 2 numbers or missing values. Latitude in range -90.0 to 90.0, longitude in range -180.0 to 180.0.

property modification_date: datetime: The last modification date of the media item.

property name: str: The name (title) of the media item.

property object_description: str: A description of the media item.

property properties: dict: All properties of the media item.

reveal_in_finder()[source]: Opens a Finder window or tab focused on the media item’s containing folder with the media item selected.

New in version 0.0.2.

show_in_preview()[source]: Opens the media item in Preview.app.

New in version 0.0.2.

property size: int: The selected media item file size.

spotlight() → XAPhotosMediaItem[source]

Shows the media item in the front window of Photos.app.

Returns:: The media item object
Return type:: XAPhotosMediaItem

New in version 0.0.6.

property width: int: The width of the media item in pixels.

class PyXA.apps.PhotosApp.XAPhotosMediaItemList(properties: dict, filter: dict | None = None)[source]

Bases: XAList, XAClipboardCodable

A wrapper around lists of media items that employs fast enumeration techniques.

All properties of media items can be called as methods on the wrapped list, returning a list containing each media item’s value for the property.

New in version 0.0.6.

Methods:

`altitude`()
`by_altitude`(altitude)
`by_date`(date)
`by_favorite`(favorite)
`by_filename`(filename)
`by_height`(height)
`by_id`(id)
`by_keywords`(keywords)
`by_location`(location)
`by_object_description`(object_description)
`by_properties`(properties)
`by_size`(size)
`by_title`(title)
`by_width`(width)
`creation_date`()
`duration`()
`favorite`()
`file_path`()
`filename`()
`get_clipboard_representation`()	Gets a clipboard-codable representation of each media item in the list.
`height`()
`id`()
`is_burst`()
`is_hidden`()
`is_photo`()
`is_video`()
`keywords`()
`location`()
`modification_date`()
`object_description`()
`properties`()
`size`()
`title`()
`width`()

altitude() → list[float][source]

by_altitude(altitude: float) → XAPhotosMediaItem | None[source]

by_date(date: datetime) → XAPhotosMediaItem | None[source]

by_favorite(favorite: bool) → XAPhotosMediaItem | None[source]

by_filename(filename: str) → XAPhotosMediaItem | None[source]

by_height(height: int) → XAPhotosMediaItem | None[source]

by_id(id: str) → XAPhotosMediaItem | None[source]

by_keywords(keywords: list[str]) → XAPhotosMediaItem | None[source]

by_location(location: XALocation) → XAPhotosMediaItem | None[source]

by_object_description(object_description: str) → XAPhotosMediaItem | None[source]

by_properties(properties: dict) → XAPhotosMediaItem | None[source]

by_size(size: int) → XAPhotosMediaItem | None[source]

by_title(title: str) → XAPhotosMediaItem | None[source]

by_width(width: int) → XAPhotosMediaItem | None[source]

creation_date() → list[datetime][source]

duration() → list[float][source]

favorite() → list[bool][source]

file_path() → list[XAPath][source]

filename() → list[str][source]

get_clipboard_representation() → list[NSURL][source]

Gets a clipboard-codable representation of each media item in the list.

When the clipboard content is set to a list of media items, each item’s file URL is added to the clipboard.

Returns:: A list of media item file URLs
Return type:: list[NSURL]

New in version 0.0.8.

height() → list[int][source]

id() → list[str][source]

is_burst() → list[bool][source]

is_hidden() → list[bool][source]

is_photo() → list[bool][source]

is_video() → list[bool][source]

keywords() → list[list[str]][source]

location() → list[list[float | None]][source]

modification_date() → list[datetime][source]

object_description() → list[str][source]

properties() → list[dict][source]

size() → list[tuple[float, float]][source]

title() → list[str][source]

width() → list[int][source]