pymobiledevice3 5.0.4__py3-none-any.whl → 7.0.6__py3-none-any.whl

pymobiledevice3/cli/restore.py

@@ -4,18 +4,20 @@ import logging
 import plistlib
 import tempfile
 import traceback
-from collections.abc import Generator
+from collections.abc import Iterator
 from pathlib import Path
-from typing import IO, Optional, Union
+from typing import IO, Annotated, Optional
 from zipfile import ZipFile
 
 import click
 import IPython
 import requests
+import typer
 from pygments import formatters, highlight, lexers
+from typer_injector import Depends, InjectingTyper
 
 from pymobiledevice3 import usbmux
-from pymobiledevice3.cli.cli_common import is_invoked_for_completion, print_json, prompt_selection, set_verbosity
+from pymobiledevice3.cli.cli_common import is_invoked_for_completion, print_json, prompt_selection
 from pymobiledevice3.exceptions import ConnectionFailedError, ConnectionFailedToUsbmuxdError, IncorrectModeError
 from pymobiledevice3.irecv import IRecv
 from pymobiledevice3.lockdown import LockdownClient, create_using_usbmux
@@ -25,55 +27,66 @@ from pymobiledevice3.restore.restore import Restore
 from pymobiledevice3.services.diagnostics import DiagnosticsService
 from pymobiledevice3.utils import file_download
 
+logger = logging.getLogger(__name__)
+
+
 SHELL_USAGE = """
 # use `irecv` variable to access Restore mode API
 # for example:
 print(irecv.getenv('build-version'))
 """
-
-logger = logging.getLogger(__name__)
 IPSWME_API = "https://api.ipsw.me/v4/device/"
 
 
-class Command(click.Command):
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self.params[:0] = [
-            click.Option(("device", "--ecid"), type=click.INT, callback=self.device),
-            click.Option(("verbosity", "-v", "--verbose"), count=True, callback=set_verbosity, expose_value=False),
-        ]
-
-    @staticmethod
-    def device(ctx, param, value) -> Optional[Union[LockdownClient, IRecv]]:
-        if is_invoked_for_completion():
-            # prevent lockdown connection establishment when in autocomplete mode
-            return
-
-        ecid = value
-        logger.debug("searching among connected devices via lockdownd")
-        devices = [dev for dev in usbmux.list_devices() if dev.connection_type == "USB"]
-        if len(devices) > 1:
-            raise click.ClickException("Multiple device detected")
-        try:
-            for device in devices:
-                try:
-                    lockdown = create_using_usbmux(serial=device.serial, connection_type="USB")
-                except (ConnectionFailedError, IncorrectModeError):
-                    continue
-                if (ecid is None) or (lockdown.ecid == value):
-                    logger.debug("found device")
-                    return lockdown
-                else:
-                    continue
-        except ConnectionFailedToUsbmuxdError:
-            pass
-
-        logger.debug("waiting for device to be available in Recovery mode")
-        return IRecv(ecid=ecid)
+cli = InjectingTyper(
+    name="restore",
+    help="Restore/erase IPSWs, fetch blobs, and manage devices in Recovery/DFU.",
+    no_args_is_help=True,
+)
+
+
+def device_dependency(
+    ecid: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Target device ECID; defaults to the first connected USB device or waits for Recovery/DFU.",
+        ),
+    ] = None,
+) -> Optional[Device]:
+    if is_invoked_for_completion():
+        # prevent lockdown connection establishment when in autocomplete mode
+        return None
+
+    logger.debug("searching among connected devices via lockdownd")
+    devices = [dev for dev in usbmux.list_devices() if dev.connection_type == "USB"]
+    if len(devices) > 1:
+        raise click.ClickException("Multiple device detected")
+    try:
+        for device in devices:
+            try:
+                lockdown = create_using_usbmux(serial=device.serial, connection_type="USB")
+            except (ConnectionFailedError, IncorrectModeError):
+                continue
+            if (ecid is None) or (lockdown.ecid == ecid):
+                logger.debug("found device")
+                return Device(lockdown=lockdown)
+            else:
+                continue
+    except ConnectionFailedToUsbmuxdError:
+        pass
+
+    logger.debug("waiting for device to be available in Recovery mode")
+    return Device(irecv=IRecv(ecid=ecid))
+
+
+DeviceDep = Annotated[
+    Device,
+    Depends(device_dependency),
+]
 
 
 @contextlib.contextmanager
-def tempzip_download_ctx(url: str) -> Generator[ZipFile, None, None]:
+def tempzip_download_ctx(url: str) -> Iterator[ZipFile]:
     with tempfile.TemporaryDirectory() as tmpdir:
         tmpzip = Path(tmpdir) / url.split("/")[-1]
         file_download(url, tmpzip)
@@ -81,33 +94,52 @@ def tempzip_download_ctx(url: str) -> Generator[ZipFile, None, None]:
 
 
 @contextlib.contextmanager
-def zipfile_ctx(path: str) -> Generator[ZipFile, None, None]:
+def zipfile_ctx(path: str) -> Iterator[ZipFile]:
     yield ZipFile(path)
 
 
-class IPSWCommand(Command):
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self.params.extend([
-            click.Option(("ipsw_ctx", "-i", "--ipsw"), required=False, callback=self.ipsw_ctx, help="local IPSW file"),
-            click.Option(("tss", "--tss"), type=click.File("rb"), callback=self.tss),
-        ])
+def ipsw_ctx_dependency(
+    device: DeviceDep,
+    ipsw: Annotated[
+        Optional[str],
+        typer.Option(
+            "--ipsw",
+            "-i",
+            help="Path or URL to an IPSW. If omitted, choose a signed build interactively.",
+        ),
+    ] = None,
+) -> contextlib.AbstractContextManager[ZipFile]:
+    if ipsw and not ipsw.startswith(("http://", "https://")):
+        return zipfile_ctx(ipsw)
+
+    url = ipsw
+    if url is None:
+        url = query_ipswme(device.product_type)
+    return tempzip_download_ctx(url)
+
+
+IPSWCtxDep = Annotated[
+    contextlib.AbstractContextManager[ZipFile],
+    Depends(ipsw_ctx_dependency),
+]
 
-    @staticmethod
-    def ipsw_ctx(ctx, param, value) -> Generator[ZipFile, None, None]:
-        if value and not value.startswith(("http://", "https://")):
-            return zipfile_ctx(value)
 
-        url = value
-        if url is None:
-            url = query_ipswme(ctx.params["device"].product_type)
-        return tempzip_download_ctx(url)
+def tss_dependency(
+    tss: Annotated[
+        Optional[Path],
+        typer.Option(help="Path to SHSH blob plist to use for signing requests."),
+    ] = None,
+) -> None:
+    if tss is None:
+        return
+    with tss.open("rb") as tss_file:
+        return plistlib.load(tss_file)
 
-    @staticmethod
-    def tss(ctx, param, value) -> Optional[IO]:
-        if value is None:
-            return
-        return plistlib.load(value)
+
+TSSDep = Annotated[
+    Optional[dict],
+    Depends(tss_dependency),
+]
 
 
 def query_ipswme(identifier: str) -> str:
@@ -118,15 +150,9 @@ def query_ipswme(identifier: str) -> str:
     return firmwares[idx]["url"]
 
 
-async def restore_update_task(device: Device, ipsw: ZipFile, tss: Optional[IO], erase: bool, ignore_fdr: bool) -> None:
-    lockdown = None
-    irecv = None
-    if isinstance(device, LockdownClient):
-        lockdown = device
-    elif isinstance(device, IRecv):
-        irecv = device
-    device = Device(lockdown=lockdown, irecv=irecv)
-
+async def restore_update_task(
+    device: Device, ipsw: ZipFile, tss: Optional[dict], erase: bool, ignore_fdr: bool
+) -> None:
     behavior = Behavior.Update
     if erase:
         behavior = Behavior.Erase
@@ -139,19 +165,8 @@ async def restore_update_task(device: Device, ipsw: ZipFile, tss: Optional[IO],
         raise
 
 
-@click.group()
-def cli() -> None:
-    pass
-
-
-@cli.group()
-def restore() -> None:
-    """Restore an IPSW or access device in recovery mode"""
-    pass
-
-
-@restore.command("shell", cls=Command)
-def restore_shell(device):
+@cli.command("shell")
+def restore_shell(device: DeviceDep) -> None:
     """create an IPython shell for interacting with iBoot"""
     IPython.embed(
         header=highlight(SHELL_USAGE, lexers.PythonLexer(), formatters.Terminal256Formatter(style="native")),
@@ -161,40 +176,34 @@ def restore_shell(device):
     )
 
 
-@restore.command("enter", cls=Command)
-def restore_enter(device):
+@cli.command("enter")
+def restore_enter(device: DeviceDep) -> None:
     """enter Recovery mode"""
     if isinstance(device, LockdownClient):
         device.enter_recovery()
 
 
-@restore.command("exit")
-def restore_exit():
+@cli.command("exit")
+def restore_exit() -> None:
     """exit Recovery mode"""
     irecv = IRecv()
     irecv.set_autoboot(True)
     irecv.reboot()
 
 
-@restore.command("restart", cls=Command)
-def restore_restart(device):
+@cli.command("restart")
+def restore_restart(device: DeviceDep) -> None:
     """restarts device"""
-    if isinstance(device, LockdownClient):
-        with DiagnosticsService(device) as diagnostics:
+    if device.is_lockdown:
+        with DiagnosticsService(device.lockdown) as diagnostics:
             diagnostics.restart()
     else:
-        device.reboot()
+        device.irecv.reboot()
 
 
-async def restore_tss_task(device: Device, ipsw_ctx: Generator, tss: IO, out: Optional[IO]) -> None:
-    lockdown = None
-    irecv = None
-    if isinstance(device, LockdownClient):
-        lockdown = device
-    elif isinstance(device, IRecv):
-        irecv = device
-
-    device = Device(lockdown=lockdown, irecv=irecv)
+async def restore_tss_task(
+    device: Device, ipsw_ctx: contextlib.AbstractContextManager[ZipFile], out: Optional[IO]
+) -> None:
     with ipsw_ctx as ipsw:
         tss = await Recovery(ipsw, device).fetch_tss_record()
     if out:
@@ -202,46 +211,42 @@ async def restore_tss_task(device: Device, ipsw_ctx: Generator, tss: IO, out: Op
     print_json(tss)
 
 
-@restore.command("tss", cls=IPSWCommand)
-@click.argument("out", type=click.File("wb"), required=False)
-def restore_tss(device: Device, ipsw_ctx: Generator, tss: IO, out: Optional[IO]) -> None:
+@cli.command("tss")
+def restore_tss(device: DeviceDep, ipsw_ctx: IPSWCtxDep, out: Optional[Path] = None) -> None:
     """query SHSH blobs"""
-    asyncio.run(restore_tss_task(device, ipsw_ctx, tss, out), debug=True)
+    with out.open("wb") if out else contextlib.nullcontext() as out_file:
+        asyncio.run(restore_tss_task(device, ipsw_ctx, out_file), debug=True)
 
 
-async def restore_ramdisk_task(device: Device, ipsw_ctx: Generator) -> None:
-    lockdown = None
-    irecv = None
-    if isinstance(device, LockdownClient):
-        lockdown = device
-    elif isinstance(device, IRecv):
-        irecv = device
-    device = Device(lockdown=lockdown, irecv=irecv)
-
+async def restore_ramdisk_task(device: Device, ipsw_ctx: contextlib.AbstractContextManager[ZipFile]) -> None:
     with ipsw_ctx as ipsw:
         await Recovery(ipsw, device).boot_ramdisk()
 
 
-@restore.command("ramdisk", cls=IPSWCommand)
-def restore_ramdisk(device: Device, ipsw_ctx: Generator, tss: IO) -> None:
+@cli.command("ramdisk")
+def restore_ramdisk(device: DeviceDep, ipsw_ctx: IPSWCtxDep) -> None:
     """
-    don't perform an actual restore. just enter the update ramdisk
-
-    ipsw can be either a filename or an url
+    Boot only the update ramdisk without performing a restore (IPSW path or URL accepted).
     """
     asyncio.run(restore_ramdisk_task(device, ipsw_ctx), debug=True)
 
 
-@restore.command("update", cls=IPSWCommand)
-@click.option("--erase", is_flag=True, help="use the Erase BuildIdentity (full factory-reset)")
-@click.option(
-    "--ignore-fdr", is_flag=True, help="only establish an FDR service connection, but don't proxy any traffic"
-)
-def restore_update(device: Device, ipsw_ctx: Generator, tss: IO, erase: bool, ignore_fdr: bool) -> None:
+@cli.command("update")
+def restore_update(
+    device: DeviceDep,
+    ipsw_ctx: IPSWCtxDep,
+    tss: TSSDep,
+    erase: Annotated[
+        bool,
+        typer.Option(help="Erase and restore (factory reset) instead of updating in place."),
+    ] = False,
+    ignore_fdr: Annotated[
+        bool,
+        typer.Option(help="Connect to the FDR service only (debug mode; no traffic proxying)."),
+    ] = False,
+) -> None:
     """
-    perform an update
-
-    ipsw can be either a filename or an url
+    Update or restore the device using an IPSW (local path or URL).
     """
     with ipsw_ctx as ipsw:
         asyncio.run(restore_update_task(device, ipsw, tss, erase, ignore_fdr), debug=True)

pymobiledevice3/cli/springboard.py

@@ -1,11 +1,11 @@
-from typing import IO
+from pathlib import Path
+from typing import Annotated, Literal
 
-import click
 import IPython
+import typer
+from typer_injector import InjectingTyper
 
-from pymobiledevice3.cli.cli_common import Command, print_json
-from pymobiledevice3.lockdown import LockdownClient
-from pymobiledevice3.lockdown_service_provider import LockdownServiceProvider
+from pymobiledevice3.cli.cli_common import ServiceProviderDep, print_json
 from pymobiledevice3.services.springboard import SpringBoardServicesService
 
 SHELL_USAGE = """
@@ -13,32 +13,28 @@ Use `service` to access the service features
 """
 
 
-@click.group()
-def cli():
-    pass
+cli = InjectingTyper(
+    name="springboard",
+    help="Interact with SpringBoard UI (icons, wallpapers, orientation, shell).",
+    no_args_is_help=True,
+)
+state_cli = InjectingTyper(
+    name="state",
+    help="Icon state operations.",
+    no_args_is_help=True,
+)
+cli.add_typer(state_cli)
 
 
-@cli.group()
-def springboard():
-    """Access device UI"""
-    pass
-
-
-@springboard.group()
-def state():
-    """icons state options"""
-    pass
-
-
-@state.command("get", cls=Command)
-def state_get(service_provider: LockdownClient):
-    """get icon state"""
+@state_cli.command("get")
+def state_get(service_provider: ServiceProviderDep) -> None:
+    """Fetch the current icon layout/state."""
     print_json(SpringBoardServicesService(lockdown=service_provider).get_icon_state())
 
 
-@springboard.command("shell", cls=Command)
-def springboard_shell(service_provider: LockdownClient):
-    """open a shell to communicate with SpringBoardServicesService"""
+@cli.command("shell")
+def springboard_shell(service_provider: ServiceProviderDep) -> None:
+    """Open an IPython shell bound to SpringBoardServicesService."""
     service = SpringBoardServicesService(lockdown=service_provider)
     IPython.embed(
         header=SHELL_USAGE,
@@ -48,43 +44,47 @@ def springboard_shell(service_provider: LockdownClient):
     )
 
 
-@springboard.command("icon", cls=Command)
-@click.argument("bundle_id")
-@click.argument("out", type=click.File("wb"))
-def springboard_icon(service_provider: LockdownClient, bundle_id, out):
-    """get application's icon"""
-    out.write(SpringBoardServicesService(lockdown=service_provider).get_icon_pngdata(bundle_id))
+@cli.command("icon")
+def springboard_icon(service_provider: ServiceProviderDep, bundle_id: str, out: Path) -> None:
+    """Save an app's icon PNG to the given path."""
+    out.write_bytes(SpringBoardServicesService(lockdown=service_provider).get_icon_pngdata(bundle_id))
 
 
-@springboard.command("orientation", cls=Command)
-def springboard_orientation(service_provider: LockdownClient):
-    """get screen orientation"""
+@cli.command("orientation")
+def springboard_orientation(service_provider: ServiceProviderDep) -> None:
+    """Print current screen orientation."""
     print(SpringBoardServicesService(lockdown=service_provider).get_interface_orientation())
 
 
-@springboard.command("wallpaper-home-screen", cls=Command)
-@click.argument("out", type=click.File("wb"))
-def springboard_wallpaper_home_screen(service_provider: LockdownClient, out: IO) -> None:
-    """get homescreen wallpaper"""
-    out.write(SpringBoardServicesService(lockdown=service_provider).get_wallpaper_pngdata())
+@cli.command("wallpaper-home-screen")
+def springboard_wallpaper_home_screen(service_provider: ServiceProviderDep, out: Path) -> None:
+    """Save the homescreen wallpaper PNG to the given path."""
+    out.write_bytes(SpringBoardServicesService(lockdown=service_provider).get_wallpaper_pngdata())
 
 
-@springboard.command("wallpaper-preview-image", cls=Command)
-@click.argument("wallpaper-name", type=click.Choice(["homescreen", "lockscreen"]))
-@click.argument("out", type=click.File("wb"))
-@click.option("-r", "--reload", is_flag=True, help="reload icon state before fetching image")
+@cli.command("wallpaper-preview-image")
 def springboard_wallpaper_preview_image(
-    service_provider: LockdownClient, wallpaper_name: str, out: IO, reload: bool
+    service_provider: ServiceProviderDep,
+    wallpaper_name: Literal["homescreen", "lockscreen"],
+    out: Path,
+    reload: Annotated[
+        bool,
+        typer.Option(
+            "--reload",
+            "-r",
+            help="reload icon state before fetching image",
+        ),
+    ] = False,
 ) -> None:
-    """get the preview image of either the homescreen or the lockscreen"""
+    """Save the preview image for the homescreen or lockscreen wallpaper (optionally reload state first)."""
     with SpringBoardServicesService(lockdown=service_provider) as springboard_service:
         if reload:
             springboard_service.reload_icon_state()
-        out.write(springboard_service.get_wallpaper_preview_image(wallpaper_name))
+        out.write_bytes(springboard_service.get_wallpaper_preview_image(wallpaper_name))
 
 
-@springboard.command("homescreen-icon-metrics", cls=Command)
-def springboard_homescreen_icon_metrics(service_provider: LockdownServiceProvider) -> None:
-    """Get homescreen icon metrics"""
+@cli.command("homescreen-icon-metrics")
+def springboard_homescreen_icon_metrics(service_provider: ServiceProviderDep) -> None:
+    """Print homescreen icon spacing/metrics."""
     with SpringBoardServicesService(lockdown=service_provider) as springboard_service:
         print_json(springboard_service.get_homescreen_icon_metrics())