photos — 访问iOS上的相册

photos模块允许你访问存储在iOS照片库中的媒体。

你还可以将新图像添加到库中，就地修改现有内容并删除项目。

注意: 首次使用任何访问照片的功能时，都会显示系统提供的权限对话框。如果你拒绝访问，则大多数函数运行结果都将像你的照片库为空时一样。如果你以后改变主意，则可以从应用“设置”中的“隐私”部分允许访问你的照片。应用中的权限对话框将仅显示一次。

入门

要开始使用照片库中的媒体，通常需要至少一个Asset对象。你可以使用get_assets()函数从库中获取所有资产，如下所示：

# 获取最近的一张照片，并将它显示在控制台中

import photos
all_assets = photos.get_assets()
last_asset = all_assets[-1]
img = last_asset.get_image()
img.show()

资产仅包含元数据，因此要获得实际的图像，你将必须使用该Asset.get_image()函数，如上面的示例所示。图像作为PIL.Image对象返回。如果你要使用ui.Image，请使用Asset.get_ui_image()。

资产以集合的形式进行组织，这些集合表示为AssetCollection对象。集合可以是常规相册或智能相册，它们会自动包含具有某些属性的资产。

这些智能相册之一就是“屏幕快照”相册，你可以使用get_screenshots_album()功能轻松地将其检索。以下代码段显示了如何检索最早的屏幕截图并将其从库中删除（显示确认对话框之后）：

# 检索最早的屏幕截图并将其从库中删除

import photos
album = photos.get_screenshots_album()
screenshots = album.assets
if not screenshots:
    print('You have no screenshots in your library.')
else:
    oldest = screenshots[0]
    if oldest.can_delete:
        # 这将会自动显示一个确认对话框：
        oldest.delete()
    else:
        print('Oldest screenshot is not deletable')

你也可以通过将照片替换为编辑过的图像来修改照片库中的内容。

以下代码段获取“最近添加”相册中的最后一个资产，将其转换为灰度，然后替换图像。可以在“照片”应用中或使用Asset.revert()方法来还原编辑：

# 获取最近的一张照片，将其和转换为灰度图，然后就地保存

import photos
album = photos.get_recently_added_album()
last = album.assets[-1]
if last.can_edit_content:
    img = last.get_image()
    grayscale_img = img.convert('L')
    grayscale_img.save('.edit.jpg', quality=90)
    last.edit_content('.edit.jpg')
else:
    print('The asset is not editable')

前面的示例均按索引获取了资产，但是你也可以仅显示一个对话框，让用户从缩略图网格中选择资产。pick_asset()函数获取资产列表（或AssetCollection），然后返回所选资产。它还允许多项选择。如果不带参数调用它，则会显示“最近添加”专辑。：

# 显示一个图片选择器对话框 (允许多选) 然后打印结果

import photos
assets = photos.pick_asset(title='Pick some assets', multi=True)
print(assets)

函数

photos.capture_image(camera=’rear’)
显示标准的相机界面并返回捕获的图像（PIL.Image对象）。

如果设备没有摄像头或取消了摄像头接口，则不返回任何内容。

您可以将’front‘作为相机参数传递，以启动自拍相机（用户始终可以手动切换相机）。

photos.get_assets(media_type=’image’, include_hidden=False)
获取并返回具有给定媒体类型（’image‘或’video‘）的库中所有资产的列表。默认情况下，排除标记为隐藏的资产。

photos.get_asset_with_local_id(local_id)
Asset.local_id从库中获取并返回具有给定本地标识符（属性）的资产。如果不存在具有此标识符的资产，则会引发IOError。

photos.get_albums()
返回照片库中所有普通相册的列表。返回值是AssetCollection对象列表。

photos.get_smart_albums()
返回照片库中所有智能相册的列表。返回值是AssetCollection对象列表。

photos.get_moments()
返回照片库中所有“时刻”的列表。时刻是按日期/位置自动分组的资产集合。返回值是AssetCollection对象列表。

photos.get_favorites_album()
返回包含所有标记为收藏夹的资产的智能相册。返回值是一个AssetCollection对象。

photos.get_recently_added_album()
返回包含最近添加到库中的所有资产的智能相册。返回值是一个AssetCollection对象。

photos.get_selfies_album()
返回包含使用前置摄像头拍摄的所有资产的智能相册。返回值是一个AssetCollection对象。

photos.get_screenshots_album()
返回包含使用截图功能创建的所有资产的智能相册。返回值是一个AssetCollection对象。

photos.batch_delete(assets)
从照片库中删除多个资产。资产必须是一系列Asset对象。如果不可删除一个或多个资产，则会引发IOError，并且不会删除任何资产。您可以使用Asset.can_delete属性检查是否可以删除资产。

photos.batch_revert(assets)
将多个资产恢复到其原始状态（删除所有编辑）。如果一个或多个资产不可编辑，则会引发IOError，并且不会还原任何资产。您可以使用Asset.can_edit_content属性检查资产是否可编辑。

photos.create_album(title)
使用给定的标题在照片库中创建并返回一个新相册。返回值是AssetCollection代表新专辑的对象。

photos.create_image_asset(image_path)
使用给定的图像文件（例如JPEG或PNG图像）创建并返回新的图像资产。返回值是Asset代表添加图像的对象。

photos.pick_asset(assets=None, title=’’, multi=False)
显示对话框，其中包含给定资产的缩略图网格。资产可以是Asset对象的序列/列表，也可以是一个AssetCollection。

如果multi为True，则用户可以选择多个资产。否则，选择一项资产后，对话框将关闭。返回值可以是单个Asset对象（如果multi为False），也可以是Asset对象列表（如果multi为True）。如果取消了资产选择器，则返回None。

资产类

class photos.Asset
Asset类表示在照片库中的一个媒体项目，即图像或视频。Asset无法直接初始化对象–您必须使用get_assets()或通过访问AssetCollection.assets相册或智能相册的属性从库中获取它们。

一个Asset对象仅包含元数据。要获取实际的图像数据，请使用Asset.get_image()和get_image_data()方法。

要将新的图像资产添加到照片库，请使用create_image_asset()函数，提供您之前保存到磁盘的图像文件的路径。

资产类的方法

Asset.get_image(original=False)
获取资产的图像数据，并将其作为PIL.Image对象返回。

默认情况下，返回图像的最新版本。通过original = True获得无任何调整/编辑的图像。

Asset.get_image_data(original=False)
获取资产的图像数据，并将其作为io.BytesIO对象返回。您可以通过io.BytesIO.getvalue()来获取图像数据作为字节字符串。

默认情况下，返回图像的最新版本。通过original = True获得无任何调整/编辑的图像。

如果只需要将图像保存为文件，则比Asset.get_image()效率更高。返回的io.BytesIO值具有附加的uti属性，该属性可用于确定图像数据的文件类型。

Asset.get_ui_image(size=None, crop=False)
获取资产的图像数据，然后将其作为ui.Image对象返回，例如在用户界面中显示。通过传递尺寸（一对宽度/高度），可以请求图像的较小版本（传递None则请求最大可用版本）。

crop参数确进行定尺寸调整行为时图像的纵横比不匹配size参数。传递True以获取具有给定大小的图像–例如，这对于生成缩略图图像很有用。

Asset.edit_content(jpeg_path)
用给定的JPEG文件替换资产的图像内容。

如果资产不可编辑，则会引发IOError。您可以使用Asset.can_edit_content属性检查资产是否可编辑。

请注意，图像文件必须为JPEG格式。不支持其他图像格式来编辑内容（尽管您可以使用来从PNG / GIF文件中创建新资源create_image_asset()）。

系统将显示一个对话框以确认编辑。

Asset.delete()
从照片库中删除资产。

如果资产不可删除，将引发IOError。您可以使用Asset.can_delete属性检查资产是否可删除。

系统将显示一个对话框以确认删除。

如果要删除多个资产而不显示每个资产的确认对话框，请使用此batch_delete()功能。

Asset.revert()
将资产还原为其原始状态。

如果资产不可编辑，则会引发IOError。您可以使用Asset.can_edit_content属性检查资产是否可编辑。

系统将显示一个对话框以确认编辑。

如果要还原多个资产而不显示每个资产的确认对话框，请使用此batch_revert()功能。

资产类的属性

Asset.local_id
（只读，字符串）此资产在当前设备上的唯一标识符。

Asset.pixel_width
（只读，数字）资产的宽度，以像素为单位。

Asset.pixel_height
（只读，数字）资产的高度，以像素为单位。

Asset.media_type
（只读，字符串）资产的媒体类型（’image‘或’video‘）。

Asset.media_subtypes
（只读，字符串列表）资产的媒体子类型（例如’photo_screenshot‘，’photo_hdr‘…）。

Asset.creation_date
（读写，日期时间）资产的创建日期。仅当Asset.can_edit_properties为True时才可写。

Asset.modification_date
（读写，日期时间）资产的修改日期。

Asset.hidden
（读写，布尔值）资产是否隐藏在库中。仅当can_edit_properties为True时才可写。

Asset.favorite
（读写，布尔值）资产是否标记为收藏。仅当can_edit_properties为True时才可写。

Asset.duration
（只读，数字）视频资产的持续时间（以秒为单位）（对于静止图像，始终为零）。

Asset.location
（读写，字典）拍摄照片/视频的地理位置，至少包含’latitude‘和’longitude‘键（以及可选的’altitude‘）作为字典。仅当can_edit_properties为True时才可写。

Asset.can_edit_content
（只读，布尔值）是否可以修改资产的内容（例如使用Asset.revert()或Asset.edit_content()）。

Asset.can_edit_properties
（只读，布尔值）是否资产的元数据可以被修改（Asset.favorite，Asset.hidden，Asset.creation_date，Asset.location）。

Asset.can_delete
（只读，布尔值）是否可以使用Asset.delete()删除资产。

资产集合类

class photos.AssetCollection
AssetCollection对象代表照片库中的集合，即相册或智能相册。“时刻”（按日期/位置自动分组的照片）也表示为AssetCollection对象。

您不能直接初始化AssetCollection。使用get_albums()，get_smart_albums()和get_moments()函数从照片库中抓取整个集合。您也可以通过方便的访问某些特殊的智能相册，例如get_screenshots_album()，get_recently_added_album()或get_selfies_album()。

要在照片库中创建新相册，请使用该create_album()功能。然后，您可以使用添加资产AssetCollection.add_assets()（或使用删除资产AssetCollection.remove_assets()）。

资产集合类的方法

AssetCollection.delete()
从照片库中删除资产集合。所包含的资产不会被删除。

如果资产集合不可删除，则将引发IOError。您可以使用AssetCollection.can_delete属性检查资产集合是否可删除。

AssetCollection.add_assets(assets)
将Asset对象列表添加到该对象表示的相册中。

并非所有资产集合都允许添加资产。您可以使用AssetCollection.can_add_assets属性进行检查。

AssetCollection.add_assets(assets)
从Asset对象代表的相册中删除对象列表。

并非所有资产集合都允许删除资产。您可以使用AssetCollection.can_remove_assets属性进行检查。

资产集合类的属性

AssetCollection.assets
（只读，Asset对象列表）集合包含的资产。请注意，直接修改列表对照片库中的照片集没有影响。使用AssetCollection.add_assets()和AssetCollection.remove_assets()添加或删除资产。

AssetCollection.local_id
（只读，字符串）当前设备上此资产集合的唯一标识符。

AssetCollection.title
（读写，字符串）资产集合的标题（可能已本地化）。仅当AssetCollection.can_rename为True时才可写。

AssetCollection.type
（只读，字符串）的类型的资产集合（的’album‘，’smart_album‘或’moment‘）。

AssetCollection.subtype
（只读，字符串）资产集合的子类型（例如’favorites‘，’recently_added‘…）。

AssetCollection.start_date
（只读，日期时间）资产集合中所有资产中最早的创建日期。

AssetCollection.end_date
（只读，日期时间）资产集合中所有资产中的最新创建日期。

AssetCollection.can_delete
（只读，布尔值）是否可以删除资产集合。

AssetCollection.can_add_assets
（只读，布尔值）资产集合是否允许使用AssetCollection.add_assets()来添加资产。

AssetCollection.can_remove_assets
（只读，布尔值）资产集合是否允许使用AssetCollection.remove_assets()来添加资产。

AssetCollection.can_rename
（只读，布尔值）资产集合的title属性是否可以更改。

已废弃的函数

为了向后兼容，仍然可以使用以下功能，但是不建议在新代码中使用它们。

get_count() – 返回相册中的图像数量。
get_image(image_index=-1, original=True, raw_data=False) – 返回相册中的图像之一。使用get_assets()代替。
get_metadata(image_index=-1) – 将相册中图像的EXIF和其他元数据作为字典返回。请改用Asset的元数据属性。
get_thumbnail(image_index=-1) – 返回相册中图像的缩略图。无论原始图像的纵横比如何，缩略图的宽度和高度均相等。使用Asset.get_ui_image()代替。
pick_image(show_albums=False, include_metadata=False, original=True, raw_data=False, multi=False) – 显示标准的图像选择器UI，并返回选择的图像。使用pick_asset()代替。
save_image(image) – 保存PIL图像或ui.Image到相册。使用create_image_asset()代替。