doronz88/pymobiledevice3 v11.1.4

on GitHub

Highlights

🐛 A device the native tunnel can't find now raises DeviceNotFoundError

Asking the macOS native transport for a UDID no device answers to used to fail with an internal _RemotePairingError — a subclass of UserspaceTunnelUnavailableError, not of DeviceNotFoundError. Every other transport raises DeviceNotFoundError for the same situation, so code that caught it (yours, or the CLI's own --reconnect retry loop) simply missed the native case.

It is now both: DeviceNotFoundError for callers, and still a native-path failure internally, so the automatic native → userspace → tunneld routing is unchanged. The practical consequence for the CLI is that a device that vanished mid-session is treated as reconnectable on the native transport too, exactly as it already was over usbmux and tunneld.

from pymobiledevice3.exceptions import DeviceNotFoundError
from pymobiledevice3.remote.native_tunnel import NativeRemotedTunnel

try:
    async with NativeRemotedTunnel(serial=udid) as rsd:
        ...
except DeviceNotFoundError as e:
    print(e.udid, e)   # the target, and why the lookup failed

✨ DeviceNotFoundError says which lookup failed

The exception carried only the UDID — str(exc) was empty, and every consumer had to re-render it. It now takes a message as well, while udid stays a dedicated member, and each raise site names the transport that came up empty:

Device not found: usbmux has no device matching udid <UDID> over USB
Device not found: tunneld (127.0.0.1:49151) serves no tunnel for udid <UDID>
Device not found: remotepairingd reported no device matching udid <UDID>

A raise site that passes only the UDID still yields the familiar Device not found: <UDID>, so existing callers are unaffected.

📚 Every environment variable in one place

PYMOBILEDEVICE3_DEFAULT_FALLBACK and its siblings were only mentioned in passing inside the tunnel guides, with nowhere to look them up. Environment variables now lists all of them — device selection, transport selection, the advanced/debug ones — plus the variables your shell or OS sets that change behaviour anyway (SUDO_USER, ALLUSERSPROFILE, ...).

# opt back out of the macOS native default for this shell
export PYMOBILEDEVICE3_DEFAULT_FALLBACK=userspace

What's Changed

• 8281194 remote: raise DeviceNotFoundError when the native tunnel finds no device (#1883) (@doronz88)
• 2956768 exceptions: give DeviceNotFoundError a message naming the failed lookup (#1883) (@doronz88)
• 82bd7cc docs: add an environment-variables reference (#1883) (@doronz88)

Full Changelog: v11.1.3...v11.1.4