pymobiledevice3 6.2.0__py3-none-any.whl → 7.0.0__py3-none-any.whl

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())

pymobiledevice3/cli/syslog.py

@@ -2,38 +2,41 @@ import logging
 import os
 import posixpath
 import re
-from typing import Optional, TextIO
-
-import click
-
-from pymobiledevice3.cli.cli_common import Command, get_last_used_terminal_formatting, user_requested_colored_output
-from pymobiledevice3.lockdown import LockdownClient
+from contextlib import nullcontext
+from pathlib import Path
+from typing import Annotated, Optional, TextIO
+
+import typer
+from typer_injector import InjectingTyper
+
+from pymobiledevice3.cli.cli_common import (
+    ServiceProviderDep,
+    get_last_used_terminal_formatting,
+    user_requested_colored_output,
+)
 from pymobiledevice3.lockdown_service_provider import LockdownServiceProvider
-from pymobiledevice3.services.os_trace import OsTraceService, SyslogLogLevel
+from pymobiledevice3.services.os_trace import OsTraceService, SyslogEntry, SyslogLogLevel
 from pymobiledevice3.services.syslog import SyslogService
 
 logger = logging.getLogger(__name__)
 
-
-@click.group()
-def cli() -> None:
-    pass
-
-
-@cli.group()
-def syslog() -> None:
-    """Watch syslog messages"""
-    pass
+cli = InjectingTyper(
+    name="syslog",
+    help="Watch syslog messages",
+    no_args_is_help=True,
+)
 
 
-@syslog.command("live-old", cls=Command)
-def syslog_live_old(service_provider: LockdownClient):
+@cli.command("live-old")
+def syslog_live_old(service_provider: ServiceProviderDep) -> None:
     """view live syslog lines in raw bytes form from old relay"""
     for line in SyslogService(service_provider=service_provider).watch():
         print(line)
 
 
-def format_line(color, pid, syslog_entry, include_label: bool, image_offset: bool = False) -> Optional[str]:
+def format_line(
+    color: bool, pid: int, syslog_entry: SyslogEntry, include_label: bool, image_offset: bool = False
+) -> Optional[str]:
     log_level_colors = {
         SyslogLogLevel.NOTICE.name: "white",
         SyslogLogLevel.INFO.name: "white",
@@ -60,17 +63,17 @@ def format_line(color, pid, syslog_entry, include_label: bool, image_offset: boo
         label = f"[{syslog_entry.label.subsystem}][{syslog_entry.label.category}]"
 
     if color:
-        timestamp = click.style(str(timestamp), "green")
-        process_name = click.style(process_name, "magenta")
+        timestamp = typer.style(str(timestamp), "green")
+        process_name = typer.style(process_name, "magenta")
         if len(image_name) > 0:
-            image_name = click.style(image_name, "magenta")
+            image_name = typer.style(image_name, "magenta")
         if image_offset:
-            image_offset_str = click.style(image_offset_str, "blue")
-        syslog_pid = click.style(syslog_pid, "cyan")
+            image_offset_str = typer.style(image_offset_str, "blue")
+        syslog_pid = typer.style(syslog_pid, "cyan")
         log_level_color = log_level_colors[level]
-        level = click.style(level, log_level_color)
-        label = click.style(label, "cyan")
-        message = click.style(message, log_level_color)
+        level = typer.style(level, log_level_color)
+        label = typer.style(label, "cyan")
+        message = typer.style(message, log_level_color)
 
     line_format = "{timestamp} {process_name}{{{image_name}{image_offset_str}}}[{pid}] <{level}>: {message}"
 
@@ -93,7 +96,7 @@ def format_line(color, pid, syslog_entry, include_label: bool, image_offset: boo
 def syslog_live(
     service_provider: LockdownServiceProvider,
     out: Optional[TextIO],
-    pid: Optional[int],
+    pid: int,
     process_name: Optional[str],
     match: list[str],
     match_insensitive: list[str],
@@ -106,9 +109,9 @@ def syslog_live(
     match_regex += [re.compile(f".*({r}).*", re.IGNORECASE | re.DOTALL) for r in insensitive_regex]
 
     def replace(m):
-        if len(m.groups()):
-            return line.replace(m.group(1), click.style(m.group(1), bold=True, underline=True))
-        return None
+        if len(m.groups()) and line:
+            return line.replace(m.group(1), typer.style(m.group(1), bold=True, underline=True))
+        return ""
 
     for syslog_entry in OsTraceService(lockdown=service_provider).syslog(pid=pid):
         if process_name and posixpath.basename(syslog_entry.filename) != process_name:
@@ -117,6 +120,9 @@ def syslog_live(
         line_no_style = format_line(False, pid, syslog_entry, include_label, image_offset)
         line = format_line(user_requested_colored_output(), pid, syslog_entry, include_label, image_offset)
 
+        if line_no_style is None or line is None:
+            continue
+
         skip = False
 
         if match is not None:
@@ -127,7 +133,7 @@ def syslog_live(
                     break
                 else:
                     if user_requested_colored_output():
-                        match_line = match_line.replace(m, click.style(m, bold=True, underline=True))
+                        match_line = match_line.replace(m, typer.style(m, bold=True, underline=True))
                         line = match_line
 
         if match_insensitive is not None:
@@ -143,7 +149,7 @@ def syslog_live(
                         last_color_formatting = get_last_used_terminal_formatting(line[:start])
                         line = (
                             line[:start]
-                            + click.style(line[start:end], bold=True, underline=True)
+                            + typer.style(line[start:end], bold=True, underline=True)
                             + last_color_formatting
                             + line[end:]
                         )
@@ -168,50 +174,108 @@ def syslog_live(
                 print(line_no_style, file=out, flush=True)
 
 
-@syslog.command("live", cls=Command)
-@click.option("-o", "--out", type=click.File("wt"), help="log file")
-@click.option("--pid", type=click.INT, default=-1, help="pid to filter. -1 for all")
-@click.option("-pn", "--process-name", help="process name to filter")
-@click.option("-m", "--match", multiple=True, help="match expression")
-@click.option("-mi", "--match-insensitive", multiple=True, help="insensitive match expression")
-@click.option("include_label", "--label", is_flag=True, help="should include label")
-@click.option("-e", "--regex", multiple=True, help="filter only lines matching given regex")
-@click.option("-ei", "--insensitive-regex", multiple=True, help="filter only lines matching given regex (insensitive)")
-@click.option("-io", "--image-offset", is_flag=True, help="Include image offset in log line")
+@cli.command("live")
 def cli_syslog_live(
-    service_provider: LockdownServiceProvider,
-    out: Optional[TextIO],
-    pid: Optional[int],
-    process_name: Optional[str],
-    match: list[str],
-    match_insensitive: list[str],
-    include_label: bool,
-    regex: list[str],
-    insensitive_regex: list[str],
-    image_offset: bool,
+    service_provider: ServiceProviderDep,
+    out: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--out",
+            "-o",
+            help="log file",
+        ),
+    ] = None,
+    pid: Annotated[
+        int,
+        typer.Option(help="pid to filter. -1 for all"),
+    ] = -1,
+    process_name: Annotated[
+        Optional[str],
+        typer.Option(
+            "--process-name",
+            "-pn",
+            help="process name to filter",
+        ),
+    ] = None,
+    match: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "--match",
+            "-m",
+            help="match expression",
+        ),
+    ] = None,
+    match_insensitive: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "--match-insensitive",
+            "-mi",
+            help="case-insensitive match expression",
+        ),
+    ] = None,
+    include_label: Annotated[
+        bool,
+        typer.Option(
+            "--label",
+            help="should include label",
+        ),
+    ] = False,
+    regex: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "--regex",
+            "-e",
+            help="filter only lines matching given regex",
+        ),
+    ] = None,
+    insensitive_regex: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "--insensitive-regex",
+            "-ei",
+            help="filter only lines matching given regex (insensitive)",
+        ),
+    ] = None,
+    image_offset: Annotated[
+        bool,
+        typer.Option(
+            "--image-offset",
+            "-io",
+            help="Include image offset in log line",
+        ),
+    ] = False,
 ) -> None:
     """view live syslog lines"""
 
-    syslog_live(
-        service_provider,
-        out,
-        pid,
-        process_name,
-        match,
-        match_insensitive,
-        include_label,
-        regex,
-        insensitive_regex,
-        image_offset,
-    )
+    with out.open("wt") if out else nullcontext() as out_file:
+        syslog_live(
+            service_provider,
+            out_file,
+            pid,
+            process_name,
+            match or [],
+            match_insensitive or [],
+            include_label,
+            regex or [],
+            insensitive_regex or [],
+        )
 
 
-@syslog.command("collect", cls=Command)
-@click.argument("out", type=click.Path(exists=False, dir_okay=True, file_okay=False))
-@click.option("--size-limit", type=click.INT)
-@click.option("--age-limit", type=click.INT)
-@click.option("--start-time", type=click.INT)
-def syslog_collect(service_provider: LockdownClient, out, size_limit, age_limit, start_time):
+@cli.command("collect")
+def syslog_collect(
+    service_provider: ServiceProviderDep,
+    out: Annotated[
+        Path,
+        typer.Argument(
+            exists=False,
+            dir_okay=True,
+            file_okay=False,
+        ),
+    ],
+    size_limit: int,
+    age_limit: int,
+    start_time: int,
+) -> None:
     """
     Collect the system logs into a .logarchive that can be viewed later with tools such as log or Console.
     If the filename doesn't exist, system_logs.logarchive will be created in the given directory.
@@ -219,12 +283,12 @@ def syslog_collect(service_provider: LockdownClient, out, size_limit, age_limit,
     if not os.path.exists(out):
         os.makedirs(out)
 
-    if not out.endswith(".logarchive"):
+    if out.suffix != ".logarchive":
         logger.warning(
             "given out path doesn't end with a .logarchive - consider renaming to be able to view "
             "the file with the likes of the Console.app and the `log show` utilities"
         )
 
     OsTraceService(lockdown=service_provider).collect(
-        out, size_limit=size_limit, age_limit=age_limit, start_time=start_time
+        str(out), size_limit=size_limit, age_limit=age_limit, start_time=start_time
     )

pymobiledevice3/cli/usbmux.py

@@ -1,35 +1,53 @@
 import logging
 import tempfile
+from typing import Annotated, Optional
 
-import click
+import typer
+from typer_injector import InjectingTyper
 
 from pymobiledevice3 import usbmux
-from pymobiledevice3.cli.cli_common import USBMUX_OPTION_HELP, BaseCommand, print_json
+from pymobiledevice3.cli.cli_common import USBMUX_OPTION_HELP, print_json
 from pymobiledevice3.lockdown import create_using_usbmux
 from pymobiledevice3.tcp_forwarder import UsbmuxTcpForwarder
 
 logger = logging.getLogger(__name__)
 
 
-@click.group()
-def cli() -> None:
-    pass
-
-
-@cli.group("usbmux")
-def usbmux_cli() -> None:
-    """List devices or forward a TCP port"""
-    pass
-
-
-@usbmux_cli.command("forward", cls=BaseCommand)
-@click.option("usbmux_address", "--usbmux", help=USBMUX_OPTION_HELP)
-@click.argument("src_port", type=click.IntRange(1, 0xFFFF))
-@click.argument("dst_port", type=click.IntRange(1, 0xFFFF))
-@click.option("--serial", help="device serial number")
-@click.option("-d", "--daemonize", is_flag=True)
-def usbmux_forward(usbmux_address: str, src_port: int, dst_port: int, serial: str, daemonize: bool):
-    """forward tcp port"""
+cli = InjectingTyper(
+    name="usbmux",
+    help="Inspect usbmuxd-connected devices and forward TCP ports to them.",
+    no_args_is_help=True,
+)
+
+
+@cli.command("forward")
+def usbmux_forward(
+    src_port: Annotated[
+        int,
+        typer.Argument(min=1, max=0xFFFF),
+    ],
+    dst_port: Annotated[
+        int,
+        typer.Argument(min=1, max=0xFFFF),
+    ],
+    *,
+    usbmux_address: Annotated[
+        Optional[str],
+        typer.Option(
+            "--usbmux",
+            help=USBMUX_OPTION_HELP,
+        ),
+    ] = None,
+    serial: Annotated[
+        str,
+        typer.Option(help="Device serial/UDID to forward traffic to."),
+    ],
+    daemonize: Annotated[
+        bool,
+        typer.Option("--daemonize", "-d", help="Run the forwarder in the background."),
+    ] = False,
+) -> None:
+    """Forward a local TCP port to the device via usbmuxd."""
     forwarder = UsbmuxTcpForwarder(serial, dst_port, src_port, usbmux_address=usbmux_address)
 
     if daemonize:
@@ -45,12 +63,33 @@ def usbmux_forward(usbmux_address: str, src_port: int, dst_port: int, serial: st
         forwarder.start()
 
 
-@usbmux_cli.command("list", cls=BaseCommand)
-@click.option("usbmux_address", "--usbmux", help=USBMUX_OPTION_HELP)
-@click.option("-u", "--usb", is_flag=True, help="show only usb devices")
-@click.option("-n", "--network", is_flag=True, help="show only network devices")
-def usbmux_list(usbmux_address: str, usb: bool, network: bool) -> None:
-    """list connected devices"""
+@cli.command("list")
+def usbmux_list(
+    usbmux_address: Annotated[
+        Optional[str],
+        typer.Option(
+            "--usbmux",
+            help=USBMUX_OPTION_HELP,
+        ),
+    ] = None,
+    usb: Annotated[
+        bool,
+        typer.Option(
+            "--usb",
+            "-u",
+            help="show only USB devices",
+        ),
+    ] = False,
+    network: Annotated[
+        bool,
+        typer.Option(
+            "--network",
+            "-n",
+            help="show only network devices",
+        ),
+    ] = False,
+) -> None:
+    """List devices known to usbmuxd (USB and Wi-Fi)."""
     connected_devices = []
     for device in usbmux.list_devices(usbmux_address=usbmux_address):
         udid = device.serial

pymobiledevice3/cli/version.py

@@ -1,9 +1,6 @@
-import click
+from typer import Typer
 
-
-@click.group()
-def cli() -> None:
-    pass
+cli = Typer()
 
 
 @cli.command()