diff --git a/.bumpversion.cfg b/.bumpversion.cfg index 25357c3c..9ad11a48 100644 --- a/.bumpversion.cfg +++ b/.bumpversion.cfg @@ -1,5 +1,5 @@ [bumpversion] -current_version = 0.62.0 +current_version = 0.62.1 parse = (?P\d+)\.(?P\d+)\.(?P\d+) serialize = {major}.{minor}.{patch} diff --git a/.github/ISSUE_TEMPLATE/sweep-bugfix.yml b/.github/ISSUE_TEMPLATE/sweep-bugfix.yml deleted file mode 100644 index 25f43c35..00000000 --- a/.github/ISSUE_TEMPLATE/sweep-bugfix.yml +++ /dev/null @@ -1,11 +0,0 @@ -name: Bugfix -title: 'Sweep: ' -description: Write something like "We notice ... behavior when ... happens instead of ..."" -labels: sweep -body: - - type: textarea - id: description - attributes: - label: Details - description: More details about the bug - placeholder: The bug might be in ... file \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/sweep-feature.yml b/.github/ISSUE_TEMPLATE/sweep-feature.yml deleted file mode 100644 index 6b985bc8..00000000 --- a/.github/ISSUE_TEMPLATE/sweep-feature.yml +++ /dev/null @@ -1,11 +0,0 @@ -name: Feature Request -title: 'Sweep: ' -description: Write something like "Write an api endpoint that does "..." in the "..." file" -labels: sweep -body: - - type: textarea - id: description - attributes: - label: Details - description: More details for Sweep - placeholder: The new endpoint should use the ... class from ... file because it contains ... logic \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/sweep-refactor.yml b/.github/ISSUE_TEMPLATE/sweep-refactor.yml deleted file mode 100644 index ed0f8a66..00000000 --- a/.github/ISSUE_TEMPLATE/sweep-refactor.yml +++ /dev/null @@ -1,11 +0,0 @@ -name: Refactor -title: 'Sweep: ' -description: Write something like "Modify the ... api endpoint to use ... version and ... framework" -labels: sweep -body: - - type: textarea - id: description - attributes: - label: Details - description: More details for Sweep - placeholder: We are migrating this function to ... version because ... \ No newline at end of file diff --git a/API_README.md b/API_README.md index 9bcffd33..18501a3c 100644 --- a/API_README.md +++ b/API_README.md @@ -445,7 +445,7 @@ if __name__ == "__main__": ## Package Interface -### PhotosDB +### PhotosDB #### Read a Photos library database @@ -636,11 +636,11 @@ For example, in my library, Photos says I have 19,386 photos and 474 movies. Ho Returns a single PhotoInfo instance for photo with UUID matching `uuid` or None if no photo is found matching `uuid`. If you know the UUID of a photo, `get_photo()` is much faster than `photos`. See also [photos()](#photos). -#### `query(options: QueryOptions) -> List[PhotoInfo]:` +#### `query(options: QueryOptions) -> List[PhotoInfo]:` Returns a list of [PhotoInfo](#photoinfo) objects matching the query options. This is preferred method of querying the photos database. See [QueryOptions](#queryoptions) for details on the options available. -#### `keywords` +#### `keywords` ```python # assumes photosdb is a PhotosDB object (see above) @@ -649,16 +649,16 @@ keywords = photosdb.keywords Returns a list of the keywords found in the Photos library -#### `album_info` +#### `album_info` ```python # assumes photosdb is a PhotosDB object (see above) albums = photosdb.album_info ``` -Returns a list of [AlbumInfo](#albuminfo) objects representing albums in the database or empty list if there are no albums. See also [albums](#albums) and [burst_album_info](#burst_album_info). +Returns a list of [AlbumInfo](#albuminfo) objects representing albums in the database or empty list if there are no albums. See also [albums](#photosdb_albums) and [burst_album_info](#burst_album_info). -#### `albums` +#### `albums` ```python # assumes photosdb is a PhotosDB object (see above) @@ -669,7 +669,7 @@ Returns a list of the album names found in the Photos library. See also [burst_a **Note**: In Photos 5.0 (MacOS 10.15/Catalina), It is possible to have more than one album with the same name in Photos. Albums with duplicate names are treated as a single album and the photos in each are combined. For example, if you have two albums named "Wedding" and each has 2 photos, osxphotos will treat this as a single album named "Wedding" with 4 photos in it. -See also [album_info](#album_info.) +See also [album_info](#photosdb_album_info.) #### `albums_shared` @@ -677,30 +677,30 @@ Returns list of shared album names found in photos database (e.g. albums shared **Note**: *Only valid for Photos 5 / MacOS 10.15*; on Photos <= 4, prints warning and returns empty list. -#### `import_info` +#### `import_info` Returns a list of [ImportInfo](#importinfo) objects representing the import sessions for the database. -#### `project_info` +#### `project_info` Returns a list of [ProjectInfo](#projectinfo) objects representing the projects/creations (cards, calendars, etc.) in the database. -#### `moment_info` +#### `moment_info` Returns the [MomentInfo](#momentinfo) object for the photo or `None` if the photo does not have an associated moment. -#### `folder_info` +#### `folder_info` ```python # assumes photosdb is a PhotosDB object (see above) folders = photosdb.folder_info ``` -Returns a list of [FolderInfo](#folderinfo) objects representing top level folders in the database or empty list if there are no folders. See also [folders](#folders). +Returns a list of [FolderInfo](#folderinfo) objects representing top level folders in the database or empty list if there are no folders. See also [folders](#photosdb_folders). **Note**: Currently folder_info is only implemented for Photos 5 (Catalina); will return empty list and output warning if called on earlier database versions. -#### `folders` +#### `folders` ```python # assumes photosdb is a PhotosDB object (see above) @@ -711,16 +711,16 @@ Returns a list names of top level folder names in the database. **Note**: Currently folders is only implemented for Photos 5 (Catalina); will return empty list and output warning if called on earlier database versions. -#### `persons` +#### `persons` ```python # assumes photosdb is a PhotosDB object (see above) persons = photosdb.persons ``` -Returns a list of the person names (faces) found in the Photos library. **Note**: It is of course possible to have more than one person with the same name, e.g. "Maria Smith", in the database. `persons` assumes these are the same person and will list only one person named "Maria Smith". If you need more information about persons in the database, see [person_info](#dbpersoninfo). +Returns a list of the person names (faces) found in the Photos library. **Note**: It is of course possible to have more than one person with the same name, e.g. "Maria Smith", in the database. `persons` assumes these are the same person and will list only one person named "Maria Smith". If you need more information about persons in the database, see [person_info](#photosdb_personinfo). -#### `person_info` +#### `person_info` ```python # assumes photosdb is a PhotosDB object (see above) @@ -769,17 +769,17 @@ Returns a dictionary of shared albums (e.g. shared via iCloud photo sharing) fou **Note**: *Photos 5 / MacOS 10.15 only*. On earlier versions of Photos, prints warning and returns empty dictionary. -#### `labels` +#### `labels` Returns image categorization labels associated with photos in the library as list of str. -**Note**: Only valid on Photos 5; on earlier versions, returns empty list. In Photos 5, Photos runs machine learning image categorization against photos in the library and automatically assigns labels to photos such as "People", "Dog", "Water", etc. A photo may have zero or more labels associated with it. See also [labels_normalized](#labels_normalized). +**Note**: Only valid on Photos 5; on earlier versions, returns empty list. In Photos 5, Photos runs machine learning image categorization against photos in the library and automatically assigns labels to photos such as "People", "Dog", "Water", etc. A photo may have zero or more labels associated with it. See also [labels_normalized](#photosdb_labels_normalized). -#### `labels_normalized` +#### `labels_normalized` Returns image categorization labels associated with photos in the library as list of str. Labels are normalized (e.g. converted to lower case). Use of normalized strings makes it easier to search if you don't how Apple capitalizes a label. -**Note**: Only valid on Photos 5; on earlier versions, returns empty list. In Photos 5, Photos runs machine learning image categorization against photos in the library and automatically assigns labels to photos such as "People", "Dog", "Water", etc. A photo may have zero or more labels associated with it. See also [labels](#labels). +**Note**: Only valid on Photos 5; on earlier versions, returns empty list. In Photos 5, Photos runs machine learning image categorization against photos in the library and automatically assigns labels to photos such as "People", "Dog", "Water", etc. A photo may have zero or more labels associated with it. See also [labels](#photosdb_labels). #### `labels_as_dict` @@ -952,7 +952,7 @@ if __name__ == "__main__": print(photo.original_filename, photo.date) ``` -### PhotoInfo +### PhotoInfo PhotosDB.photos() returns a list of PhotoInfo objects. Each PhotoInfo object represents a single photo in the Photos library. @@ -1012,11 +1012,11 @@ Returns a list of [ProjectInfo](#projectinfo) objects representing projects/crea Returns a list of the names of the persons in the photo -#### `person_info` +#### `person_info` Returns a list of [PersonInfo](#personinfo) objects representing persons in the photo. Each PersonInfo object is associated with one or more FaceInfo objects. -#### `face_info` +#### `face_info` Returns a list of [FaceInfo](#faceinfo) objects representing faces in the photo. Each face is associated with the a PersonInfo object. @@ -1191,11 +1191,11 @@ Return true if photo was shared via syndication (e.g. via Messages, etc.); these 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. Syndicated photos are photos that appear in "Shared with you" album. Photos 7+ only; returns None if not Photos 7+. -### `shared_moment` +#### `shared_moment` Return True if photo is part of a shared moment, otherwise False. Shared moments are created when multiple photos are shared via iCloud. (e.g. in Messages) -### `shared_library` +#### `shared_library` Return True if photo is included in shared iCloud library, otherwise False. Photos 8+ only; returns False if not Photos 8+. @@ -1329,19 +1329,19 @@ for photo in photosdb.photos(): **Note**: Only valid on Photos 5+; on earlier versions, returns empty list. In Photos 5+, Photos runs machine learning image categorization against photos in the library and automatically assigns labels to photos such as "People", "Dog", "Water", etc. A photo may have zero or more labels associated with it. See also [labels](#labels). -#### `search_info` +#### `search_info` Returns [SearchInfo](#searchinfo) object that represents search metadata for the photo. **Note**: Only valid on Photos 5+; on ealier versions, returns None. -#### `search_info_normalized` +#### `search_info_normalized` Returns [SearchInfo](#searchinfo) object that represents normalized search metadata for the photo. This returns a SearchInfo object just as `search_info` but all the properties of the object return normalized text (converted to lowercase). **Note**: Only valid on Photos 5+; on ealier versions, returns None. -#### `exif_info` +#### `exif_info` Returns an [ExifInfo](#exifinfo) object with EXIF details from the Photos database. See [ExifInfo](#exifinfo) for additional details. @@ -1349,7 +1349,7 @@ Returns an [ExifInfo](#exifinfo) object with EXIF details from the Photos databa See also `exiftool`. -#### `exiftool` +#### `exiftool` Returns an [ExifToolCaching](#exiftoolExifTool) object for the photo which provides an interface to [exiftool](https://exiftool.org/) allowing you to read the actual EXIF data in the image file inside the Photos library. If [exif_info](#exif-info) doesn't give you all the data you need, you can use `exiftool` to read the entire EXIF contents of the image. @@ -1499,7 +1499,7 @@ Some substitutions, notably `album`, `keyword`, and `person` could return multip See [Template System](#template-system) for additional details. -#### `detected_text(confidence_threshold=TEXT_DETECTION_CONFIDENCE_THRESHOLD)` +#### `detected_text(confidence_threshold=TEXT_DETECTION_CONFIDENCE_THRESHOLD)` Detects text in photo and returns lists of results as (detected text, confidence) @@ -1515,7 +1515,7 @@ See also [Text Detection](#textdetection). ### ExifInfo -[PhotosInfo.exif_info](#exif-info) returns an `ExifInfo` object with some EXIF data about the photo (Photos 5 only). `ExifInfo` contains the following properties: +[PhotosInfo.exif_info](#photoinfo_exif_info) returns an `ExifInfo` object with some EXIF data about the photo (Photos 5 only). `ExifInfo` contains the following properties: ```python flash_fired: bool @@ -1553,7 +1553,7 @@ nikon_photos = [ ### AlbumInfo -PhotosDB.album_info and PhotoInfo.album_info return a list of AlbumInfo objects. Each AlbumInfo object represents a single album in the Photos library. +[PhotosDB.album_info](#photosdb_album_info) and [PhotoInfo.album_info](photoinfo_album_info) return a list of AlbumInfo objects. Each AlbumInfo object represents a single album in the Photos library. #### `uuid` @@ -1729,11 +1729,11 @@ Returns the universally unique identifier (uuid) of the folder. This is how Pho Returns the title or name of the folder. -#### `album_info` +#### `album_info` Returns a list of [AlbumInfo](#albuminfo) objects representing each album contained in the folder. -#### `album_info_shared` +#### `album_info_shared` Returns a list of [AlbumInfo](#albuminfo) objects for each shared album in the photos database. @@ -2044,11 +2044,11 @@ Returns a dictionary representation of the PersonInfo instance. [PhotoInfo.face_info](#photofaceinfo) return a list of FaceInfo objects representing detected faces in a photo. The FaceInfo class has the following properties and methods. -#### `uuid` +#### `uuid` UUID of the face. -#### `name` +#### `name` Full name of the person represented by the face or None if person hasn't been given a name in Photos. This is a shortcut for `FaceInfo.person_info.name`. @@ -2056,11 +2056,11 @@ Full name of the person represented by the face or None if person hasn't been gi UUID of the photo this face is associated with. -#### `person_info` +#### `person_info` [PersonInfo](#personinfo) object associated with this face. -#### `photo` +#### `photo` [PhotoInfo](#photoinfo) object representing the photo that contains this face. @@ -2137,11 +2137,11 @@ The following additional properties are also available but are not yet fully doc * `lip_makeup_type`: * `smile_type`: -#### `asdict()` +#### `asdict()` Returns a dictionary representation of the FaceInfo instance. -#### `json()` +#### `json()` Returns a JSON representation of the FaceInfo instance. @@ -2512,7 +2512,7 @@ cog.out("\n"+get_template_field_table()+"\n") |{cr}|A carriage return: '\r'| |{crlf}|A carriage return + line feed: '\r\n'| |{tab}|:A tab: '\t'| -|{osxphotos_version}|The osxphotos version, e.g. '0.62.0'| +|{osxphotos_version}|The osxphotos version, e.g. '0.62.1'| |{osxphotos_cmd_line}|The full command line used to run osxphotos| |{album}|Album(s) photo is contained in| |{folder_album}|Folder path + album photo is contained in. e.g. 'Folder/Subfolder/Album' or just 'Album' if no enclosing folder| @@ -2704,7 +2704,7 @@ Attributes: ### Text Detection -The [PhotoInfo.detected_text()](#detected_text_method) and the `{detected_text}` template will perform text detection on the photos in your library. Text detection is a slow process so to avoid unnecessary re-processing of photos, osxphotos will cache the results of the text detection process as an extended attribute on the photo image file. Extended attributes do not modify the actual file. The extended attribute is named `osxphotos.metadata:detected_text` and can be viewed using the built-in [xattr](https://ss64.com/osx/xattr.html) command or my [osxmetadata](https://github.com/RhetTbull/osxmetadata) tool. If you want to remove the cached attribute, you can do so with `xattr` as follows: +The [PhotoInfo.detected_text()](#photoinfo_detected_text) and the `{detected_text}` template will perform text detection on the photos in your library. Text detection is a slow process so to avoid unnecessary re-processing of photos, osxphotos will cache the results of the text detection process as an extended attribute on the photo image file. Extended attributes do not modify the actual file. The extended attribute is named `osxphotos.metadata:detected_text` and can be viewed using the built-in [xattr](https://ss64.com/osx/xattr.html) command or my [osxmetadata](https://github.com/RhetTbull/osxmetadata) tool. If you want to remove the cached attribute, you can do so with `xattr` as follows: `find ~/Pictures/Photos\ Library.photoslibrary | xargs -I{} xattr -c osxphotos.metadata:detected_text '{}'` diff --git a/README.md b/README.md index b3235912..76054c2f 100644 --- a/README.md +++ b/README.md @@ -2223,7 +2223,7 @@ Substitution Description {cr} A carriage return: '\r' {crlf} A carriage return + line feed: '\r\n' {tab} :A tab: '\t' -{osxphotos_version} The osxphotos version, e.g. '0.62.0' +{osxphotos_version} The osxphotos version, e.g. '0.62.1' {osxphotos_cmd_line} The full command line used to run osxphotos The following substitutions may result in multiple values. Thus if specified @@ -2711,7 +2711,7 @@ The following template field substitutions are availabe for use the templating s |{cr}|A carriage return: '\r'| |{crlf}|A carriage return + line feed: '\r\n'| |{tab}|:A tab: '\t'| -|{osxphotos_version}|The osxphotos version, e.g. '0.62.0'| +|{osxphotos_version}|The osxphotos version, e.g. '0.62.1'| |{osxphotos_cmd_line}|The full command line used to run osxphotos| |{album}|Album(s) photo is contained in| |{folder_album}|Folder path + album photo is contained in. e.g. 'Folder/Subfolder/Album' or just 'Album' if no enclosing folder| diff --git a/docs/.buildinfo b/docs/.buildinfo index 017e70ec..a7b5bce9 100644 --- a/docs/.buildinfo +++ b/docs/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: 72a6d4c94671c4abc454759e142ad2ed +config: 2fc476010affcee784f205bf294f4e73 tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/docs/API_README.html b/docs/API_README.html index 815bd57d..71e62a84 100644 --- a/docs/API_README.html +++ b/docs/API_README.html @@ -6,7 +6,7 @@ - OSXPhotos Python API - osxphotos 0.62.0 documentation + OSXPhotos Python API - osxphotos 0.62.1 documentation @@ -124,7 +124,7 @@
-
osxphotos 0.62.0 documentation
 +
osxphotos 0.62.1 documentation
@@ -147,7 +147,7 @@
- osxphotos 0.62.0 documentation + osxphotos 0.62.1 documentation
-
-

PhotoInfo#

+
+

PhotoInfo#

PhotosDB.photos() returns a list of PhotoInfo objects. Each PhotoInfo object represents a single photo in the Photos library.

uuid#

@@ -1087,8 +1087,8 @@ Python < 3.11.

filename#

Returns the current filename of the photo on disk. See also original_filename

-
-

original_filename#

+
+

original_filename#

Returns the original filename of the photo when it was imported to Photos. Note: Photos 5.0+ renames the photo when it adds the file to the library using UUID. See also filename

@@ -1111,36 +1111,36 @@ Python < 3.11.

title#

Returns the title of the photo

-
-

keywords#

+
+

keywords#

Returns a list of keywords (e.g. tags) applied to the photo

-
-

albums#

+
+

albums#

Returns a list of albums the photo is contained in. See also album_info.

-
-

album_info#

+
+

album_info#

Returns a list of AlbumInfo objects representing the albums the photo is contained in or empty list of the photo is not in any albums. See also albums.

-
-

import_info#

+
+

import_info#

Returns an ImportInfo object representing the import session associated with the photo or None if there is no associated import session.

-
-

project_info#

+
+

project_info#

Returns a list of ProjectInfo objects representing projects/creations (cards, calendars, etc.) the photo is contained in or empty list if there are no projects associated with the photo.

-
-

persons#

+
+

persons#

Returns a list of the names of the persons in the photo

-
-

`person_info`#

+
+

`person_info`#

Returns a list of PersonInfo objects representing persons in the photo. Each PersonInfo object is associated with one or more FaceInfo objects.

-
-

`face_info`#

+
+

`face_info`#

Returns a list of FaceInfo objects representing faces in the photo. Each face is associated with the a PersonInfo object.

@@ -1197,28 +1197,28 @@ Python < 3.11.

orientation#

Returns EXIF orientation value of the photo as integer. If image has been edited, returns orientation of the edited image, otherwise returns orientation of the original image. See also original_orientation. If orientation cannot be determined, returns 0 (this happens if osxphotos cannot decode the adjustment info for an edited image).

-
-

original_height#

+
+

original_height#

Returns height of the original photo in pixels. See also height.

-
-

original_width#

+
+

original_width#

Returns width of the original photo in pixels. See also width.

-
-

original_orientation#

+
+

original_orientation#

Returns EXIF orientation value of the original photo as integer. See also orientation.

original_filesize#

Returns size of the original photo in bytes as integer.

-
-

ismissing#

+
+

ismissing#

Returns True if the original image file is missing on disk, otherwise False. This can occur if the file has been uploaded to iCloud but not yet downloaded to the local library or if the file was deleted or imported from a disk that has been unmounted and user hasn’t enabled “Copy items to the Photos library” in Photos preferences. Note: this status is computed based on data in the Photos library and ismissing does not verify if the photo is actually missing. See also path.

-
-

hasadjustments#

+
+

hasadjustments#

Returns True if the picture has been edited, otherwise False

@@ -1233,8 +1233,8 @@ Python < 3.11.

favorite#

Returns True if the picture has been marked as a favorite, otherwise False

-
-

hidden#

+
+

hidden#

Returns True if the picture has been marked as hidden, otherwise False

@@ -1257,25 +1257,25 @@ Python < 3.11.

place#

Returns a PlaceInfo object with reverse geolocation data or None if there is the photo has no reverse geolocation information.

-
-

shared#

+
+

shared#

Returns True if photo is in a shared album, otherwise False.

-

Note: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns None.

+

Note: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns None.

owner#

Returns full name of the photo owner (person who shared the photo) for shared photos or None if photo is not shared. Also returns None if you are the person who shared the photo.

-

Note: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns None.

+

Note: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns None.

comments#

Returns list of CommentInfo objects for comments on shared photos or empty list if no comments.

-

Note: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns empty list.

+

Note: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns empty list.

likes#

Returns list of LikeInfo objects for likes on shared photos or empty list if no likes.

-

Note: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns empty list.

+

Note: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns empty list.

isreference#

@@ -1293,8 +1293,8 @@ Python < 3.11.

iscloudasset#

Returns True if photo is a cloud asset, that is, it is in a library synched to iCloud. See also incloud

-
-

incloud#

+
+

incloud#

Returns True if photo is a cloud asset and is synched to iCloud otherwise False if photo is a cloud asset and not yet synched to iCloud. Returns None if photo is not a cloud asset.

Note: Applies to master (original) photo only. It’s possible for the master to be in iCloud but a local edited version is not yet synched to iCloud. incloud provides status of only the master photo. osxphotos does not yet provide a means to determine if the edited version is in iCloud. If you need this feature, please open an issue.

@@ -1307,14 +1307,14 @@ Python < 3.11.

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. Syndicated photos are photos that appear in “Shared with you” album. Photos 7+ only; returns None if not Photos 7+.

-
-

shared_moment#

+

shared_moment#

Return True if photo is part of a shared moment, otherwise False. Shared moments are created when multiple photos are shared via iCloud. (e.g. in Messages)

-

shared_library#

+

shared_library#

Return True if photo is included in shared iCloud library, otherwise False. Photos 8+ only; returns False if not Photos 8+.

+

uti#

Returns Uniform Type Identifier (UTI) for the current version of the image, for example: ‘public.jpeg’ or ‘com.apple. quicktime-movie’. If the image has been edited, uti will return the UTI for the edited image, otherwise it will return the UTI for the original image.

@@ -1331,8 +1331,8 @@ Syndicated photos are photos that appear in “Shared with you” album. Photos

uti_raw#

Returns Uniform Type Identifier (UTI) for the associated raw image, if there is one; for example, ‘com.canon.cr2-raw-image’. If the image is raw but not part of a RAW+JPEG pair, uti_raw returns None. In this case, use uti, or uti_original. See also has_raw and notes on Raw Photos.

-
-

burst#

+
+

burst#

Returns True if photos is a burst image (e.g. part of a set of burst images), otherwise False. See burst_photos

@@ -1348,8 +1348,8 @@ See burst_photos

burst_default_pick#

Returns True if photo is a burst image and is the photo that Photos selected as the default image for the burst set, otherwise False.

-
-

burst_photos#

+
+

burst_photos#

If photo is a burst image (see burst), returns a list of PhotoInfo objects for all other photos in the same burst set. If not a burst image, returns empty list.

Example below gets list of all photos that are bursts, selects one of of them and prints out the names of the other images in the burst set. PhotosDB.photos() will only return the photos in the burst set that the user selected using “Make a Selection…” in Photos or the key image Photos selected if the user has not yet made a selection. This is similar to how Photos displays and counts burst photos. Using burst_photos you can access the other images in the burst set to export them, etc.

>>> import osxphotos
@@ -1370,21 +1370,21 @@ See burst_photos
-
-

burst_albums#

+
+

burst_albums#

If photo is burst photo, returns list of albums it is contained in as well as any albums the key photo is contained in, otherwise returns PhotoInfo.albums.

If a burst photo which has unselected burst images (e.g. the burst images are in the library but haven’t been selected by the user using the “Make a selection” feature) is placed in a an album, Photos treats only the selected “key” photo as in the album. The unselected burst images, while associated with the photo in the album, are not technically in the album. If you are handling one of these unselected burst photos and want to know which album it would be in based on which albums it’s selected key images are in, use burst_albums. See also burst_album_info and albums.

-
-

burst_album_info#

+
+

burst_album_info#

If photo is non-selected burst photo, teturns a list of AlbumInfo objects representing the albums any other photos in the same burst set are contained in. Otherwise, returns PhotoInfo.album_info. See also burst_albums and album_info.

live_photo#

Returns True if photo is an Apple live photo (ie. it has an associated “live” video component), otherwise returns False. See path_live_photo.

-
-

path_live_photo#

+
+

path_live_photo#

Returns the path to the live video component of a live photo. If photo is not a live photo, returns None.

Note: will also return None if the live video component is missing on disk. It’s possible that the original photo may be on disk (ismissing==False) but the video component is missing, likely because it has not been downloaded from iCloud.

@@ -1418,13 +1418,13 @@ See burst_photos

slow_mo#

Returns True if photo is a slow motion video, otherwise False

-
-

labels#

+
+

labels#

Returns image categorization labels associated with the photo as list of str.

Note: Only valid on Photos 5; on earlier versions, returns empty list. In Photos 5, Photos runs machine learning image categorization against photos in the library and automatically assigns labels to photos such as “People”, “Dog”, “Water”, etc. A photo may have zero or more labels associated with it. See also labels_normalized.

-
-

labels_normalized#

+
+

labels_normalized#

Returns image categorization labels associated with the photo as list of str. Labels are normalized (e.g. converted to lower case). Use of normalized strings makes it easier to search if you don’t how Apple capitalizes a label. For example:

import osxphotos
 
@@ -1436,24 +1436,24 @@ See burst_photos

Note: Only valid on Photos 5+; on earlier versions, returns empty list. In Photos 5+, Photos runs machine learning image categorization against photos in the library and automatically assigns labels to photos such as “People”, “Dog”, “Water”, etc. A photo may have zero or more labels associated with it. See also labels.

-
-

`search_info`#

+
+

`search_info`#

Returns SearchInfo object that represents search metadata for the photo.

Note: Only valid on Photos 5+; on ealier versions, returns None.

-
-

`search_info_normalized`#

+
+

`search_info_normalized`#

Returns SearchInfo object that represents normalized search metadata for the photo. This returns a SearchInfo object just as search_info but all the properties of the object return normalized text (converted to lowercase).

Note: Only valid on Photos 5+; on ealier versions, returns None.

-
-

exif_info#

+
+

`exif_info`#

Returns an ExifInfo object with EXIF details from the Photos database. See ExifInfo for additional details.

Note: Only valid on Photos 5+; on earlier versions, returns None. The EXIF details returned are a subset of the actual EXIF data in a typical image. At import Photos stores this subset in the database and it’s this stored data that exif_info returns.

See also exiftool.

-
-

exiftool#

+
+

`exiftool`#

Returns an ExifToolCaching object for the photo which provides an interface to exiftool allowing you to read the actual EXIF data in the image file inside the Photos library. If exif_info doesn’t give you all the data you need, you can use exiftool to read the entire EXIF contents of the image.

If the file is missing from the library (e.g. not downloaded from iCloud), returns None.

exiftool must be installed in the path for this to work. If exiftool cannot be found in the path, calling exiftool will log a warning and return None. You can check the exiftool path using osxphotos.exiftool.get_exiftool_path which will raise FileNotFoundError if exiftool cannot be found.

@@ -1587,8 +1587,8 @@ is not intended for general use.

Some substitutions, notably album, keyword, and person could return multiple values, hence a new string will be return for each possible substitution (hence why a list of rendered strings is returned). For example, a photo in 2 albums: ‘Vacation’ and ‘Family’ would result in the following rendered values if template was “{created.year}/{album}” and created.year == 2020: ["2020/Vacation","2020/Family"]

See Template System for additional details.

-
-

`detected_text(confidence_threshold=TEXT_DETECTION_CONFIDENCE_THRESHOLD)`#

+
+

`detected_text(confidence_threshold=TEXT_DETECTION_CONFIDENCE_THRESHOLD)`#

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 osxphotos._constants.TEXT_DETECTION_CONFIDENCE_THRESHOLD

    • @@ -1599,9 +1599,9 @@ is not intended for general use.

    See also Text Detection.

-
-

ExifInfo#

-

PhotosInfo.exif_info returns an ExifInfo object with some EXIF data about the photo (Photos 5 only). ExifInfo contains the following properties:

+
+

ExifInfo#

+

PhotosInfo.exif_info returns an ExifInfo object with some EXIF data about the photo (Photos 5 only). ExifInfo contains the following properties:

flash_fired: bool
 iso: int
 metering_mode: int
@@ -1634,15 +1634,15 @@ is not intended for general use.
-
-

AlbumInfo#

-

PhotosDB.album_info and PhotoInfo.album_info return a list of AlbumInfo objects. Each AlbumInfo object represents a single album in the Photos library.

-
-

uuid#

+
+

AlbumInfo#

+

PhotosDB.album_info and PhotoInfo.album_info return a list of AlbumInfo objects. Each AlbumInfo object represents a single album in the Photos library.

+
+

uuid#

Returns the universally unique identifier (uuid) of the album. This is how Photos keeps track of individual objects within the database.

-
-

title#

+
+

title#

Returns the title or name of the album.

@@ -1687,131 +1687,131 @@ is not intended for general use.

parent#

Returns a FolderInfo object representing the albums parent folder or None if album is not a in a folder.

-
-

owner#

+
+

owner#

Returns full name of the album owner (person who shared the album) for shared albums or None if album is not shared.

-

Note: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns None.

+

Note: *Only valid on Photos 5 / MacOS 10.15+; on Photos <= 4, returns None.

-
-

asdict()#

+
+

asdict()#

Returns a dictionary representation of the AlbumInfo object.

-
-

ImportInfo#

+
+

ImportInfo#

PhotosDB.import_info returns a list of ImportInfo objects. Each ImportInfo object represents an import session in the library. PhotoInfo.import_info returns a single ImportInfo object representing the import session for the photo (or None if no associated import session).

-
-

uuid#

+
+

uuid#

Returns the universally unique identifier (uuid) of the import session. This is how Photos keeps track of individual objects within the database.

`photos`#

Returns a list of PhotoInfo objects representing each photo contained in the import session.

-
-

creation_date#

+
+

creation_date#

Returns the creation date as a timezone aware datetime.datetime object of the import session.

-
-

start_date#

+
+

start_date#

Returns the start date as a timezone aware datetime.datetime object for when the import session began.

-
-

end_date#

+
+

end_date#

Returns the end date as a timezone aware datetime.datetime object for when the import session completed.

Note: On Photos <=4, start_date and end_date will be the same as creation_date.

-
-

asdict()#

+
+

asdict()#

Returns a dictionary representation of the import session.

-
-

ProjectInfo#

+
+

ProjectInfo#

PhotosDB.projcet_info returns a list of ProjectInfo objects. Each ProjectInfo object represents a project in the library. PhotoInfo.project_info returns a list of ProjectInfo objects for each project the photo is contained in.

Projects (found under “My Projects” in Photos) are projects or creations such as cards, calendars, and slideshows created in Photos. osxphotos provides only very basic information about projects and projects created with third party plugins may not accessible to osxphotos.

-
-

uuid#

+
+

uuid#

Returns the universally unique identifier (uuid) of the project. This is how Photos keeps track of individual objects within the database.

-
-

title#

+
+

title#

Returns the title or name of the project.

`photos`#

Returns a list of PhotoInfo objects representing each photo contained in the project.

-
-

creation_date#

+
+

creation_date#

Returns the creation date as a timezone aware datetime.datetime object of the project.

-
-

asdict()#

+
+

asdict()#

Returns a dictionary representation of the ProjectInfo object.

-
-

MomentInfo#

+
+

MomentInfo#

PhotoInfo.moment_info return the MomentInfo object for the photo. The MomentInfo object contains information about the photo’s moment as assigned by Photos. The MomentInfo object contains the following properties:

pk#

Returns the primary key of the moment in the Photos database.

-
-

location#

+
+

location#

Returns the location of the moment as a tuple of (latitude, longitude).

-
-

title#

+
+

title#

Returns the title of the moment.

subtitle#

Returns the subtitle of the moment.

-
-

start_date#

+
+

start_date#

Returns the start date of the moment as a timezone aware datetime.datetime object.

-
-

end_date#

+
+

end_date#

Returns the end date of the moment as a timezone aware datetime.datetime object.

-
-

date#

+
+

date#

Returns the date of the moment as a timezone aware datetime.datetime object.

modification_date#

Returns the modification date of the moment as a timezone aware datetime.datetime object.

-
-

photos#

+
+

photos#

Returns a list of [PhotoInfo] objects representing the photos in the moment.

-
-

asdict()#

+
+

asdict()#

Returns a dictionary representation of the moment.

-
-

FolderInfo#

+
+

FolderInfo#

PhotosDB.folder_info returns a list of FolderInfo objects representing the top level folders in the library. Each FolderInfo object represents a single folder in the Photos library.

-
-

uuid#

+
+

uuid#

Returns the universally unique identifier (uuid) of the folder. This is how Photos keeps track of individual objects within the database.

-
-

title#

+
+

title#

Returns the title or name of the folder.

-
-

album_info#

+
+

`album_info`#

Returns a list of AlbumInfo objects representing each album contained in the folder.

-
-

album_info_shared#

+
+

`album_info_shared`#

Returns a list of AlbumInfo objects for each shared album in the photos database.

Note: Only valid for Photos 5+; on Photos <= 4, prints warning and returns empty list.

@@ -1819,8 +1819,8 @@ is not intended for general use.

subfolders#

Returns a list of FolderInfo objects representing the sub-folders of the folder.

-
-

parent#

+
+

parent#

Returns a FolderInfo object representing the folder’s parent folder or None if album is not a in a folder.

@@ -1839,8 +1839,8 @@ is not intended for general use.

photo_index(photo)#

Returns index of photo in album (based on album sort order).

-
-

asdict()#

+
+

asdict()#

Returns a dictionary representation of the FolderInfo object.

Note: FolderInfo and AlbumInfo objects effectively work as a linked list. The children of a folder are contained in subfolders and album_info and the parent object of both AlbumInfo and FolderInfo is represented by parent. For example:

>>> import osxphotos
@@ -1861,8 +1861,8 @@ is not intended for general use.
-
-

PlaceInfo#

+
+

PlaceInfo#

PhotoInfo.place returns a PlaceInfo object if the photo contains valid reverse geolocation information. PlaceInfo has the following properties.

Note For Photos versions <= 4, only name, names, and country_code properties are defined. All others return None. This is because older versions of Photos do not store the more detailed reverse geolocation information.

@@ -1935,8 +1935,8 @@ is not intended for general use.

-
-

ScoreInfo#

+
+

ScoreInfo#

PhotoInfo.score returns a ScoreInfo object that exposes the computed aesthetic scores for each photo (Photos 5+ only). I have not yet reverse engineered the meaning of each score. The overall score seems to the most useful and appears to be a composite of the other scores. The following score properties are currently available:

overall: float
 curation: float
@@ -1974,12 +1974,12 @@ is not intended for general use.
-
-

SearchInfo#

+
+

SearchInfo#

PhotoInfo.search_info and PhotoInfo.search_info_normalized return a SearchInfo object that exposes various metadata that Photos uses when searching for photos such as labels, associated holiday, etc. (Photos 5+ only).

The following properties are available:

-
-

labels#

+
+

labels#

Returns list of labels applied to photo by Photos image categorization algorithms.

@@ -2054,24 +2054,24 @@ is not intended for general use.

all#

Returns all search_info properties as a single list of strings.

-
-

asdict()#

+
+

asdict()#

Returns all associated search_info metadata as a dict.

-
-

PersonInfo#

+
+

PersonInfo#

PhotosDB.person_info and PhotoInfo.person_info return a list of PersonInfo objects represents persons in the database and in a photo, respectively. The PersonInfo class has the following properties and methods.

-
-

name#

+
+

name#

Returns the full name of the person represented in the photo. For example, “Maria Smith”.

display_name#

Returns the display name of the person represented in the photo. For example, “Maria”.

-
-

uuid#

+
+

uuid#

Returns the UUID of the person as stored in the Photos library database.

@@ -2098,36 +2098,36 @@ is not intended for general use.

`sort_order`#

Returns the sort order for the person in the Photos People view. Available on Photos 5+ only; on Photos <= 4, returns None.

-
-

json()#

+
+

json()#

Returns a json string representation of the PersonInfo instance.

-
-

asdict()#

+
+

asdict()#

Returns a dictionary representation of the PersonInfo instance.

-
-

FaceInfo#

+
+

FaceInfo#

PhotoInfo.face_info return a list of FaceInfo objects representing detected faces in a photo. The FaceInfo class has the following properties and methods.

-
-

uuid#

+
+

`uuid`#

UUID of the face.

-
-

name#

+
+

`name`#

Full name of the person represented by the face or None if person hasn’t been given a name in Photos. This is a shortcut for FaceInfo.person_info.name.

asset_uuid#

UUID of the photo this face is associated with.

-
-

person_info#

+
+

`person_info`#

PersonInfo object associated with this face.

-
-

photo#

+
+

`photo`#

PhotoInfo object representing the photo that contains this face.

@@ -2204,17 +2204,17 @@ is not intended for general use.

  • smile_type:

    • -
    -

    asdict()#

    +
    +

    `asdict()`#

    Returns a dictionary representation of the FaceInfo instance.

    -
    -

    json()#

    +
    +

    `json()`#

    Returns a JSON representation of the FaceInfo instance.

    -
    -

    CommentInfo#

    +
    +

    CommentInfo#

    PhotoInfo.comments returns a list of CommentInfo objects for comments on shared photos. (Photos 5/MacOS 10.15+ only). The list of CommentInfo objects will be sorted in ascending order by date comment was made. CommentInfo contains the following fields:

    • datetime: datetime.datetime, date/time comment was made

      • @@ -2223,8 +2223,8 @@ is not intended for general use.

    • text: str, text of the actual comment

    -
    -

    LikeInfo#

    +
    +

    LikeInfo#

    PhotoInfo.likes returns a list of LikeInfo objects for “likes” on shared photos. (Photos 5/MacOS 10.15+ only). The list of LikeInfo objects will be sorted in ascending order by date like was made. LikeInfo contains the following fields:

    • datetime: datetime.datetime, date/time like was made

      • @@ -2232,8 +2232,8 @@ is not intended for general use.

    • ismine: bool, True if like was made by person who owns the Photos library being operated on

    -
    -

    AdjustmentsInfo#

    +
    +

    AdjustmentsInfo#

    PhotoInfo.adjustments returns an AdjustmentsInfo object, if the photo has adjustments, or None if the photo does not have adjusments. AdjustmentsInfo has the following properties and methods:

    • plist: The adjustments plist file maintained by Photos as a dict.

      • @@ -2251,8 +2251,8 @@ is not intended for general use.

    • asdict(): dict representation of the AdjustmentsInfo object; contains all properties with exception of plist.

    -
    -

    PhotoTables#

    +
    +

    PhotoTables#

    PhotoInfo.tables returns a PhotoTables object that contains information about the tables in the Photos database that contain information about the photo. The following properties are available:

      @@ -2277,8 +2277,8 @@ and a rows_dict()
    -
    -

    Raw Photos#

    +
    +

    Raw Photos#

    Handling raw photos in osxphotos requires a bit of extra work. Raw photos in Photos can be imported in two different ways: 1) a single raw photo with no associated JPEG image is imported 2) a raw+JPEG pair is imported – two separate images with same file stem (e.g. IMG_0001.CR2 and IMG_001.JPG) are imported.

    The latter are treated by Photos as a single image. By default, Photos will treat these as a JPEG image. They are denoted in the Photos interface with a “J” icon superimposed on the image. In Photos, the user can select “Use RAW as original” in which case the “J” icon changes to an “R” icon and all subsequent edits will use the raw image as the original. To further complicate this, different versions of Photos handle these differently in their internal logic.

    osxphotos attempts to simplify the handling of these raw+JPEG pairs by providing a set of attributes for accessing both the JPEG and the raw version. For example, PhotoInfo.has_raw will be True if the photo has an associated raw image but False otherwise and PhotoInfo.path_raw provides the path to the associated raw image. Reference the following table for the various attributes useful for dealing with raw images. Given the different ways Photos deals with raw images I’ve struggled with how to represent these in a logical and consistent manner. If you have suggestions for a better interface, please open an issue!

    @@ -2347,8 +2347,8 @@ and a rows_dict()
    -
    -

    Template System#

    +
    +

    Template System#