OSXPhotos Python API 全面解析：高效管理苹果照片库

概述

OSXPhotos 是一个强大的 Python 库，专门用于与苹果 macOS 照片应用（Photos.app）进行交互。它不仅提供了命令行工具，还公开了丰富的 Python API，让开发者能够以编程方式访问和管理照片库中的内容。本文将深入介绍 OSXPhotos Python API 的核心功能和使用方法。

核心功能

基础查询示例

使用 OSXPhotos 只需几行代码即可访问照片库中的基本信息：

import osxphotos

# 初始化照片数据库连接
photosdb = osxphotos.PhotosDB()

# 遍历所有照片并打印基本信息
for photo in photosdb.photos():
    print(photo.original_filename, photo.date, photo.title, photo.keywords)

这段代码展示了如何：

1. 创建 PhotosDB 对象连接照片库
2. 使用 photos() 方法获取所有照片
3. 访问每张照片的文件名、日期、标题和关键词等元数据

构建命令行工具

OSXPhotos 提供了一系列装饰器和工具函数，可以快速构建功能丰富的命令行工具：

简单查询工具

from osxphotos.cli import query_command, verbose

@query_command
def example(photos, **kwargs):
    """示例命令：打印照片文件名和日期"""
    verbose(f"找到 {len(photos)} 张照片")
    for photo in photos:
        print(f"{photo.original_filename} {photo.date}")

if __name__ == "__main__":
    example()

使用 @query_command 装饰器可以：

• 自动添加所有查询选项（如按关键词、日期等过滤）
• 处理命令行参数解析
• 提供详细的帮助信息

高级功能实现

@query_command()
@click.option("--resume", is_flag=True, help="从上次运行处继续")
@click.option("--dry-run", is_flag=True, help="试运行模式")
def advanced_example(resume, dry_run, photos, **kwargs):
    """支持断点续传和试运行的高级示例"""
    kv = kvstore("example")  # 使用键值存储保存状态
    
    for photo in photos:
        if resume and photo.uuid in kv:
            continue  # 跳过已处理照片
        
        kv[photo.uuid] = datetime.now().isoformat()
        if not dry_run:
            # 实际处理逻辑
            process_photo(photo)

这个示例展示了：

• 添加自定义命令行选项
• 使用键值存储(kvstore)保存处理状态
• 实现断点续传功能
• 支持试运行模式

并发处理

OSXPhotos 支持多线程并发导出照片，但需要注意：

1. Python 版本要求：仅支持 Python 3.11 及以上版本
2. 限制：不能使用多进程(由于 PhotosDB 无法被 pickle)
3. 最佳实践：使用 ThreadPoolExecutor 实现并发

with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as executor:
    futures = [
        executor.submit(p.export, export_dir, f"{p.uuid}_{p.filename}")
        for p in photos
    ]
    for future in concurrent.futures.as_completed(futures):
        results.extend(future.result())

API 接口详解

核心类介绍

1. PhotosDB - 照片库入口点

   • photos(): 获取所有照片
   • query(): 执行复杂查询
   • keywords, persons, albums 等属性

2. PhotoInfo - 单张照片的元数据

   • 文件信息：original_filename, path
   • 时间信息：date, date_modified
   • 分类信息：keywords, persons, albums
   • 位置信息：location, place

3. 导出相关类

   • PhotoExporter: 照片导出功能
   • ExifWriter: EXIF 信息写入
   • SidecarWriter: 生成 sidecar 文件

实用功能

1. 模板系统：使用模板字符串动态生成导出路径
2. 文本检测：访问照片中的识别文字
3. 库比较：比较两个照片库的差异
4. 实用函数：各种辅助功能

最佳实践

1. 错误处理：使用提供的 abort() 和错误报告功能
2. 日志记录：利用内置的 verbose() 和 logger
3. 状态管理：使用 kvstore 保存处理进度
4. 性能优化：合理使用并发处理大量照片

总结

OSXPhotos Python API 为开发者提供了全面访问和管理苹果照片库的能力。无论是简单的元数据查询，还是复杂的照片处理流程，都可以通过简洁的 API 实现。本文介绍的核心概念和示例代码，可以帮助开发者快速上手并构建自己的照片管理工具。

对于更高级的用法，建议参考完整的 API 文档，探索更多强大的功能如 RAW 照片处理、人脸识别数据访问等。