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

pymobiledevice3/cli/restore.py

@@ -1,22 +1,23 @@
 import asyncio
 import contextlib
 import logging
-import os
 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 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
@@ -26,107 +27,132 @@ 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'))
 """
+IPSWME_API = "https://api.ipsw.me/v4/device/"
+
+
+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 = 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 '_PYMOBILEDEVICE3_COMPLETE' in os.environ:
-            # 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)
+    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]
+        tmpzip = Path(tmpdir) / url.split("/")[-1]
         file_download(url, tmpzip)
         yield ZipFile(tmpzip)
 
 
 @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)
 
-    @staticmethod
-    def ipsw_ctx(ctx, param, value) -> Generator[ZipFile, None, None]:
-        if value and not value.startswith(('http://', 'https://')):
-            return zipfile_ctx(value)
+    url = ipsw
+    if url is None:
+        url = query_ipswme(device.product_type)
+    return tempzip_download_ctx(url)
 
-        url = value
-        if url is None:
-            url = query_ipswme(ctx.params['device'].product_type)
-        return tempzip_download_ctx(url)
 
-    @staticmethod
-    def tss(ctx, param, value) -> Optional[IO]:
-        if value is None:
-            return
-        return plistlib.load(value)
+IPSWCtxDep = Annotated[
+    contextlib.AbstractContextManager[ZipFile],
+    Depends(ipsw_ctx_dependency),
+]
 
 
-def query_ipswme(identifier: str) -> str:
-    resp = requests.get(IPSWME_API + identifier, headers={'Accept': 'application/json'})
-    firmwares = resp.json()['firmwares']
-    display_list = [f'{entry["version"]}: {entry["buildid"]}' for entry in firmwares if entry['signed']]
-    idx = prompt_selection(display_list, 'Choose version', idx=True)
-    return firmwares[idx]['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)
 
 
-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)
+TSSDep = Annotated[
+    Optional[dict],
+    Depends(tss_dependency),
+]
 
+
+def query_ipswme(identifier: str) -> str:
+    resp = requests.get(IPSWME_API + identifier, headers={"Accept": "application/json"})
+    firmwares = resp.json()["firmwares"]
+    display_list = [f"{entry['version']}: {entry['buildid']}" for entry in firmwares if entry["signed"]]
+    idx = prompt_selection(display_list, "Choose version", idx=True)
+    return firmwares[idx]["url"]
+
+
+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,98 +165,88 @@ 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):
-    """ create an IPython shell for interacting with iBoot """
+@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')),
+        header=highlight(SHELL_USAGE, lexers.PythonLexer(), formatters.Terminal256Formatter(style="native")),
         user_ns={
-            'irecv': device,
-        })
+            "irecv": device,
+        },
+    )
 
 
-@restore.command('enter', cls=Command)
-def restore_enter(device):
-    """ enter Recovery mode """
+@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():
-    """ exit Recovery mode """
+@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):
-    """ restarts device """
-    if isinstance(device, LockdownClient):
-        with DiagnosticsService(device) as diagnostics:
+@cli.command("restart")
+def restore_restart(device: DeviceDep) -> None:
+    """restarts device"""
+    if device.is_lockdown:
+        with DiagnosticsService(device.lockdown) as diagnostics:
             diagnostics.restart()
     else:
-        device.reboot()
+        device.irecv.reboot()
 
 
-@restore.command('tss', cls=IPSWCommand)
-@click.argument('out', type=click.File('wb'), required=False)
-def restore_tss(device: Device, ipsw_ctx: Generator, out):
-    """ query SHSH blobs """
-    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 = Recovery(ipsw, device).fetch_tss_record()
+        tss = await Recovery(ipsw, device).fetch_tss_record()
     if out:
         plistlib.dump(tss, out)
     print_json(tss)
 
 
-@restore.command('ramdisk', cls=IPSWCommand)
-def restore_ramdisk(device: Device, ipsw_ctx: Generator, tss: IO):
-    """
-    don't perform an actual restore. just enter the update ramdisk
+@cli.command("tss")
+def restore_tss(device: DeviceDep, ipsw_ctx: IPSWCtxDep, out: Optional[Path] = None) -> None:
+    """query SHSH blobs"""
+    with out.open("wb") if out else contextlib.nullcontext() as out_file:
+        asyncio.run(restore_tss_task(device, ipsw_ctx, out_file), debug=True)
 
-    ipsw can be either a filename or an url
-    """
-    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:
-        Recovery(ipsw, device, tss=tss).boot_ramdisk()
+        await Recovery(ipsw, device).boot_ramdisk()
 
 
-@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("ramdisk")
+def restore_ramdisk(device: DeviceDep, ipsw_ctx: IPSWCtxDep) -> None:
     """
-    perform an update
-
-    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)
+
+
+@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:
+    """
+    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,80 +1,90 @@
-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.cli.cli_common import ServiceProviderDep, print_json
 from pymobiledevice3.services.springboard import SpringBoardServicesService
 
-SHELL_USAGE = '''
+SHELL_USAGE = """
 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,
         user_ns={
-            'service': service,
-        })
+            "service": service,
+        },
+    )
 
 
-@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())
-
-
-@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')
-def springboard_wallpaper_preview_image(service_provider: LockdownClient, wallpaper_name: str, out: IO,
-                                        reload: bool) -> None:
-    """ get the preview image of either the homescreen or the lockscreen """
+@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())
+
+
+@cli.command("wallpaper-preview-image")
+def springboard_wallpaper_preview_image(
+    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:
+    """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))
+
+
+@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())