libimobiledevice-wrapper 1.1.2

Python wrapper for libimobiledevice with async support and CLI tools

libimobiledevice-wrapper

一个基于 libimobiledevice 的 Python 封装工具，支持 iOS 设备管理和自动化操作。

功能特性

• 🔧 完整的 libimobiledevice 命令封装
• ⚡ 异步支持（asyncio）
• 🛡️ 统一的错误处理机制
• 🖥️ 命令行工具（CLI）
• 🚀 WebDriverAgent 接口支持
• 📱 iOS 设备管理
• 🔍 设备信息获取
• 📦 应用安装和管理

安装

前置要求

1. Python 包依赖（自动安装）

# 自动安装所有 Python 依赖
pip install libimobiledevice-wrapper

# 或手动安装
pip install -r requirements.txt

2. 系统依赖（需要手动安装）

确保系统已安装 libimobiledevice 和 ideviceinstaller：

# macOS
brew install libimobiledevice ideviceinstaller

# Ubuntu/Debian
sudo apt-get install libimobiledevice6 libimobiledevice-utils ideviceinstaller

# CentOS/RHEL
sudo yum install libimobiledevice ideviceinstaller

重要提示：

• libimobiledevice 提供基础的设备连接功能
• ideviceinstaller 是应用管理的核心工具，用于安装、卸载和查看已安装的应用
• 如果缺少 ideviceinstaller，应用管理相关功能（install_app, uninstall_app, list_apps 等）将无法使用

Python 包安装

pip install libimobiledevice-wrapper

或从源码安装：

git clone https://github.com/Huang-Jacky/libimobiledevice-wrapper.git
cd libimobiledevice-wrapper
pip install -e .

快速开始

基本使用

from libimobiledevice_wrapper import LibiMobileDevice

# 同步使用
device = LibiMobileDevice()
devices = device.list_devices()
print(f"连接的设备: {devices}")

# 异步使用
import asyncio

async def main():
    device = LibiMobileDevice()
    devices = await device.list_devices_async()
    print(f"连接的设备: {devices}")

asyncio.run(main())

命令行工具（两种用法）

1. 全局命令（推荐）

安装后会提供可执行命令 libidevice：

# 列出连接的设备
libidevice list-devices

# 获取设备信息
libidevice info --udid <device_udid>

# 安装应用
libidevice install --udid <device_udid> /path/to/app.ipa

# 获取应用信息
libidevice app-info --udid <device_udid> --bundle-id com.example.app

# 截取屏幕截图
libidevice screenshot --udid <device_udid> --output screenshot.png

**注意：截屏功能需要开发者磁盘镜像支持**
- 如果遇到 "Could not start screenshotr service!" 错误
- 系统会自动尝试挂载开发者磁盘镜像
- 如果自动挂载失败，请确保已安装对应版本的 Xcode
- 或手动挂载：`ideviceimagemounter -u <udid> <path_to_DeveloperDiskImage.dmg>`

# 简洁日志捕获
device = LibiMobileDevice()
monitor = device.monitor_device_logs(
    udid="<device_udid>",
    keywords=["error", "exception"],
    log_file_path="logs.txt",
    duration=60  # 60秒后自动停止
)
monitor.start()
time.sleep(30)  # 捕获30秒
monitor.stop()  # 自动保存到文件

# 或使用上下文管理器
with device.monitor_device_logs(udid="<device_udid>", keywords=["error"], log_file_path="logs.txt") as monitor:
    time.sleep(30)
# 自动停止并保存

# 启动应用
libidevice launch --udid <device_udid> --bundle-id com.example.app

注意：启动应用功能需要开发者磁盘镜像支持

• 如果遇到 "Could not start com.apple.debugserver!" 错误
• 需要先挂载开发者磁盘镜像：ideviceimagemounter -u <udid> <path_to_DeveloperDiskImage.dmg>
• 或者手动在设备上启动应用，然后使用日志监控功能

遇到找不到命令时：

• 使用 PyPI 安装：python3 -m pip install libimobiledevice-wrapper（然后执行 pyenv rehash 如使用 pyenv）
• 或使用完整路径（示例）：~/.pyenv/versions/3.10.6/bin/libidevice list-devices
• 或参考第 2 种用法（模块方式）

2. 模块方式（备用）

# 列出连接的设备
python3 -m libimobiledevice_wrapper.cli list-devices

# 获取设备信息
python3 -m libimobiledevice_wrapper.cli info --udid <device_udid>

# 安装应用
python3 -m libimobiledevice_wrapper.cli install --udid <device_udid> /path/to/app.ipa

# 获取应用信息
python3 -m libimobiledevice_wrapper.cli app-info --udid <device_udid> --bundle-id com.example.app

# 获取设备日志
python3 -m libimobiledevice_wrapper.cli device-logs --udid <device_udid> --duration 60 --keywords "error,exception"

# 实时监控设备日志
python3 -m libimobiledevice_wrapper.cli device-logs --udid <device_udid> --keywords "error"

# 截取屏幕截图
python3 -m libimobiledevice_wrapper.cli screenshot --udid <device_udid> --output screenshot.png

# 启动应用
python3 -m libimobiledevice_wrapper.cli launch --udid <device_udid> --bundle-id com.example.app

注意：截屏和启动应用功能需要开发者磁盘镜像支持

• 截屏功能：如果遇到 "Could not start screenshotr service!" 错误，系统会自动尝试挂载开发者磁盘镜像
• 启动应用功能：如果遇到 "Could not start com.apple.debugserver!" 错误，需要先挂载开发者磁盘镜像
• 手动挂载：ideviceimagemounter -u <udid> <path_to_DeveloperDiskImage.dmg>
• 确保已安装对应版本的 Xcode 以获得正确的开发者磁盘镜像

API 文档

LibiMobileDevice 类

主要的设备管理类，提供所有 libimobiledevice 功能的封装。

设备管理

• list_devices() - 列出连接的设备
• get_device_info(udid) - 获取设备信息
• get_device_props(udid) - 获取设备属性

应用管理

• install_app(udid, app_path) - 安装应用
• uninstall_app(udid, bundle_id) - 卸载应用
• list_apps(udid) - 列出已安装应用
• get_app_info(udid, bundle_id) - 获取指定应用的详细信息
• launch_app(udid, bundle_id) - 启动应用（需要开发者磁盘镜像支持）

文件操作

• pull_file(udid, remote_path, local_path) - 从设备拉取文件
• push_file(udid, local_path, remote_path) - 推送文件到设备

系统操作

• reboot_device(udid) - 重启设备
• shutdown_device(udid) - 关机设备

截屏

• take_screenshot(udid, output_path) - 截取设备屏幕截图（需要开发者磁盘镜像支持）
• take_screenshot_async(udid, output_path) - 异步截取设备屏幕截图（需要开发者磁盘镜像支持）

日志管理

• get_device_logs(udid, duration, keywords) - 获取设备日志
• monitor_device_logs(udid, keywords, callback, log_file_path, duration) - 实时监控设备日志
  • 自动保存到文件，无需手动调用 save_logs
  • 支持关键字过滤
  • 支持指定时长自动停止
  • 支持上下文管理器

错误处理

所有方法都包含统一的错误处理：

from libimobiledevice_wrapper import LibiMobileDeviceError

try:
    device = LibiMobileDevice()
    devices = device.list_devices()
except LibiMobileDeviceError as e:
    print(f"设备操作失败: {e}")

异步支持

所有方法都提供异步版本：

import asyncio
from libimobiledevice_wrapper import LibiMobileDevice

async def main():
    device = LibiMobileDevice()
    
    # 异步方法以 _async 结尾
    devices = await device.list_devices_async()
    info = await device.get_device_info_async(devices[0])
    
asyncio.run(main())

WebDriverAgent 支持

from libimobiledevice_wrapper import WebDriverAgent

wda = WebDriverAgent(device_udid="<device_udid>")
await wda.start()
session = await wda.create_session()

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！