pymobiledevice3 6.1.6__tar.gz → 7.0.0__tar.gz

{pymobiledevice3-6.1.6 → pymobiledevice3-7.0.0}/.github/workflows/python-app.yml

@@ -22,7 +22,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: [ 3.9, "3.10", "3.11", "3.12", "3.13", "3.14" ]
+        python-version: [ "3.9", "3.10", "3.11", "3.12", "3.13", "3.14" ]
         os: [ ubuntu-latest, macos-latest, windows-latest ]
 
     steps:

{pymobiledevice3-6.1.6 → pymobiledevice3-7.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymobiledevice3
-Version: 6.1.6
+Version: 7.0.0
 Summary: Pure python3 implementation for working with iDevices (iPhone, etc...)
 Author-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>
 Maintainer-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>
@@ -23,7 +23,6 @@ License-File: LICENSE
 Requires-Dist: construct>=2.9.29
 Requires-Dist: construct-typing>=0.7.0
 Requires-Dist: asn1
-Requires-Dist: click
 Requires-Dist: coloredlogs
 Requires-Dist: IPython
 Requires-Dist: bpylist2>=4.0.1
@@ -61,6 +60,8 @@ Requires-Dist: sslpsk-pmd3>=1.0.3; python_version < "3.13"
 Requires-Dist: python-pcapng>=2.1.1
 Requires-Dist: plumbum
 Requires-Dist: pyimg4>=0.8.8
+Requires-Dist: typer>=0.20.0
+Requires-Dist: typer-injector>=0.2.0
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"

{pymobiledevice3-6.1.6 → pymobiledevice3-7.0.0}/misc/understanding_idevice_protocol_layers.md

@@ -287,14 +287,14 @@ pymobiledevice3 developer dvt launch com.apple.mobilesafari
 
 ## DVT
 
-One of the more interesting developer services, is the one exposed by `DTServiceHub`. It is using DTX protocol messages,
+One of the more interesting developer services is the one exposed by `DTServiceHub`. It is using DTX protocol messages,
 but since it mainly wraps and allows access to stuff in `DVTFoundation.framework` we called it DVT in our
 implementation (probably standing for DeveloperTools).
 
 We don't delve too much into this protocol, but we'll say in general it allows us to invoke a whitelist of ObjC methods
 in different ObjC objects. The terminology used by DVT to each such ObjC object is called "channels".
 
-In order to access this different object use the following APIs:
+To access this different object use the following APIs:
 
 ```python
 from pymobiledevice3.lockdown import create_using_usbmux
@@ -313,17 +313,22 @@ dvt_channel = Screenshot(dvt)
 open('/tmp/screen.png', 'wb').write(dvt_channel.get_screenshot())
 ```
 
-Looking for an unimplemented feature/channel? Feel free to play with it (and submit a PR afterwards 🙏) using the
+Looking for an unimplemented feature/channel? Feel free to play with it (and submit a PR afterward 🙏) using the
 following shell:
 
 ```shell
 pymobiledevice3 developer dvt shell
 ```
 
+> **NOTE:** The full list of the methods that can be invoked on a DVT channel can be found by looking at all ObjC
+> classes in `DVTInstrumentsFoundation.framework` implementing the `DTXAllowedRPC` protocol.
+> There is an existing [Anubis rule](https://github.com/netanelc305/anubis/blob/9da337178ebd7e9f168e9df2d82b192eba4f1b30/example_rules.yaml#L14-L17)
+> I use to diff new methods against the existing ones.
+
 ## RemoteXPC
 
 Starting at iOS 17.0, Apple made a large refactor in the manner we all interact with the developer services. There can
-be multiple reasons for that decision, but in general this refactor main key points are:
+be multiple reasons for that decision, but in general these refactor main key points are:
 
 - Create a single standard for interacting with the new lockdown services (XPC Messages, Apple's proprietary IPC)
 - Optimize the protocol for large file transfers (such as the dyld_shared_cache)
@@ -347,7 +352,7 @@ Since all this communication is IP-based, but without any additional exported TC
 help us here. Instead, starting at iOS 16.0, when connecting an iDevice, it exports another non-standard USB-Ethernet
 adapter (with IPv6 link-local address), placing us in a subnet with the device's `remoted`.
 
-As we've said this communication is non-standard, and requires either:
+As we've said, this communication is non-standard and requires either:
 
 - macOS Monterey or higher
 - Special driver on your linux/Windows machine

{pymobiledevice3-6.1.6 → pymobiledevice3-7.0.0}/pymobiledevice3/__main__.py

@@ -1,5 +1,6 @@
 import asyncio
 import difflib
+import importlib
 import logging
 import os
 import re
@@ -7,13 +8,18 @@ import sys
 import textwrap
 import traceback
 import warnings
-from typing import Union
+from collections.abc import Sequence
+from typing import Annotated, Optional, Union
 
 import click
 import coloredlogs
+import typer
+import typer.core
 from packaging.version import Version
+from typer.core import TyperGroup
+from typer_injector import InjectingTyper
 
-from pymobiledevice3.cli.cli_common import TUNNEL_ENV_VAR, isatty
+from pymobiledevice3.cli.cli_common import TUNNEL_ENV_VAR, isatty, set_color_flag, set_verbosity
 from pymobiledevice3.exceptions import (
     AccessDeniedError,
     CloudConfigurationAlreadyPresentError,
@@ -112,25 +118,26 @@ CLI_GROUPS = {
     "webinspector": "webinspector",
     "idam": "idam",
     "version": "version",
-    "install-completions": "completions",
 }
 
 # Set if used the `--reconnect` option
 RECONNECT = False
 
 
-class Pmd3Cli(click.Group):
-    def list_commands(self, ctx):
-        return CLI_GROUPS.keys()
+class Pmd3TyperGroup(TyperGroup):
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        # Order is preserved by dict insertion; adjust if you want alphabetical
+        return list(CLI_GROUPS.keys())
 
-    def get_command(self, ctx: click.Context, name: str) -> click.Command:
-        if name not in CLI_GROUPS:
-            self.handle_invalid_command(ctx, name)
-        return self.import_and_get_command(ctx, name)
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command:
+        if cmd_name not in CLI_GROUPS:
+            self.handle_invalid_command(ctx, cmd_name)
+        return self.import_and_get_command(ctx, cmd_name)
 
-    def handle_invalid_command(self, ctx: click.Context, name: str) -> None:
+    def handle_invalid_command(self, ctx, name: str) -> None:
         suggested_commands = self.search_commands(name)
         suggestion = self.format_suggestions(suggested_commands)
+        # ctx.fail raises a ClickException underneath, which Typer displays nicely
         ctx.fail(f"No such command {name!r}{suggestion}")
 
     @staticmethod
@@ -138,70 +145,109 @@ class Pmd3Cli(click.Group):
         if not suggestions:
             return ""
         cmds = textwrap.indent("\n".join(suggestions), " " * 4)
-        return f"\nDid you mean this?\n{cmds}"
+        return f"\nDid you mean:\n{cmds}"
 
     @staticmethod
     def import_and_get_command(ctx: click.Context, name: str) -> click.Command:
         module_name = f"pymobiledevice3.cli.{CLI_GROUPS[name]}"
-        mod = __import__(module_name, None, None, ["cli"])
-        command = mod.cli.get_command(ctx, name)
-        if not command:
-            command_name = mod.cli.list_commands(ctx)[0]
-            command = mod.cli.get_command(ctx, command_name)
-        return command
+        mod = importlib.import_module(module_name)
+        # submodules expose a Typer Group named "cli"
+        cli: typer.Typer = mod.cli
+        return typer.main.get_command(cli)
 
     @staticmethod
     def highlight_keyword(text: str, keyword: str) -> str:
-        return re.sub(f"({keyword})", click.style("\\1", bold=True), text, flags=re.IGNORECASE)
+        return re.sub(f"({keyword})", typer.style("\\1", bold=True), text, flags=re.IGNORECASE)
 
     @staticmethod
-    def collect_commands(command: click.Command) -> Union[str, list[str]]:
-        commands = []
-        if isinstance(command, click.Group):
-            for _k, v in command.commands.items():
-                cmd = Pmd3Cli.collect_commands(v)
-                if isinstance(cmd, list):
-                    commands.extend([f"{command.name} {c}" for c in cmd])
+    def collect_commands(command: Union[TyperGroup, click.Command]) -> Union[str, list[str]]:
+        if isinstance(command, TyperGroup):  # group
+            cmds = []
+            for v in command.commands.values():
+                child = Pmd3TyperGroup.collect_commands(v)
+                if isinstance(child, list):
+                    cmds.extend([f"{command.name} {c}" for c in child])
                 else:
-                    commands.append(f"{command.name} {cmd}")
-            return commands
-        return f"{command.name}"
+                    cmds.append(f"{command.name} {child}")
+            return cmds
+        return command.name or ""
 
     @staticmethod
     def search_commands(pattern: str) -> list[str]:
-        all_commands = Pmd3Cli.load_all_commands()
+        all_commands = Pmd3TyperGroup.load_all_commands()
         matched = sorted(filter(lambda cmd: re.search(pattern, cmd), all_commands))
         if not matched:
             matched = difflib.get_close_matches(pattern, all_commands, n=20, cutoff=0.4)
         if isatty():
-            matched = [Pmd3Cli.highlight_keyword(cmd, pattern) for cmd in matched]
+            matched = [Pmd3TyperGroup.highlight_keyword(cmd, pattern) for cmd in matched]
         return matched
 
     @staticmethod
     def load_all_commands() -> list[str]:
-        all_commands = []
+        all_commands: list[str] = []
         for key in CLI_GROUPS:
             module_name = f"pymobiledevice3.cli.{CLI_GROUPS[key]}"
-            mod = __import__(module_name, None, None, ["cli"])
-            cmd = Pmd3Cli.collect_commands(mod.cli.commands[key])
+            mod = importlib.import_module(module_name)
+            if isinstance(mod.cli, typer.Typer):
+                cmd = Pmd3TyperGroup.collect_commands(typer.main.get_group(mod.cli))
+            else:
+                cmd = Pmd3TyperGroup.collect_commands(mod.cli.commands[key])
             if isinstance(cmd, list):
                 all_commands.extend(cmd)
             else:
                 all_commands.append(cmd)
         return all_commands
 
+    def resolve_command(
+        self, ctx: click.Context, args: list[str]
+    ) -> tuple[Optional[str], Optional[click.Command], list[str]]:
+        return super().resolve_command(ctx, args)
+
+
+app = InjectingTyper(
+    cls=Pmd3TyperGroup,
+    context_settings=CONTEXT_SETTINGS,
+    no_args_is_help=True,
+    # add_completion=False,
+    rich_markup_mode="markdown",
+    help=(
+        "Swiss-army CLI for pairing, inspecting, backing up, and automating iOS devices.\n\n"
+        "Docs and examples: https://github.com/doronz88/pymobiledevice3"
+    ),
+)
+
 
-@click.command(cls=Pmd3Cli, context_settings=CONTEXT_SETTINGS)
-@click.option("--reconnect", is_flag=True, default=False, help="Reconnect to device when disconnected.")
-def cli(reconnect: bool) -> None:
+@app.callback()
+def _root(
+    reconnect: Annotated[
+        bool,
+        typer.Option(
+            "--reconnect",
+            help="Automatically reconnect if the device disconnects mid-command.",
+            show_default=False,
+        ),
+    ] = False,
+    verbosity: Annotated[
+        int,
+        typer.Option(
+            "--verbose",
+            "-v",
+            count=True,
+            help="Increase logging verbosity (repeat for more detail).",
+        ),
+    ] = 0,
+    color: Annotated[
+        bool,
+        typer.Option(help="Colorize output; disable with --no-color for plain logs."),
+    ] = True,
+) -> None:
     """
-    \b
-    Interact with a connected iDevice (iPhone, iPad, ...)
-    For more information please look at:
-        https://github.com/doronz88/pymobiledevice3
+    Top-level options for pymobiledevice3.
     """
     global RECONNECT
     RECONNECT = reconnect
+    set_verbosity(verbosity)
+    set_color_flag(color)
 
 
 def device_might_need_tunneld(identifier: str) -> bool:
@@ -221,13 +267,53 @@ def device_might_need_tunneld(identifier: str) -> bool:
         return Version(lockdown.product_version) >= Version("17.0")
 
 
+class PossiblyMisplacedOption(click.NoSuchOption):
+    def __init__(
+        self,
+        option_name: str,
+        message: Optional[str] = None,
+        possibilities: Optional[Sequence[str]] = None,
+        ctx: Optional[click.Context] = None,
+        suggested_ctx: Optional[click.Context] = None,
+    ) -> None:
+        super().__init__(option_name, message, possibilities, ctx)
+        if suggested_ctx is not None:
+            if ctx is not None:
+                self.message += f" for subcommand: {ctx.command_path}"
+
+            suggestion = f"{suggested_ctx.command_path} {option_name}"
+            suggestion += ctx.command_path.removeprefix(suggested_ctx.command_path) if ctx is not None else " ..."
+
+            self.message += f"\nDid you mean: {suggestion}?"
+
+    @staticmethod
+    def from_no_such_option(e: click.NoSuchOption) -> "PossiblyMisplacedOption":
+        ctx = e.ctx
+        while ctx:
+            for param in ctx.command.params:
+                if isinstance(param, typer.core.TyperOption) and (
+                    e.option_name in param.opts or e.option_name in param.secondary_opts
+                ):
+                    break
+            else:
+                ctx = ctx.parent
+                continue
+            break
+
+        return PossiblyMisplacedOption(e.option_name, e.message, e.possibilities, e.ctx, ctx)
+
+
 def invoke_cli_with_error_handling() -> bool:
     """
     Invoke the command line interface and return `True` if the failure reason of the command was that the device was
     disconnected.
     """
     try:
-        cli()
+        # Typer apps are callable; this executes the CLI with current sys.argv
+        try:
+            app(standalone_mode=False)
+        except click.NoSuchOption as e:
+            raise PossiblyMisplacedOption.from_no_such_option(e) from e
     except NoDeviceConnectedError:
         logger.error("Device is not connected")
         return True
@@ -277,9 +363,10 @@ def invoke_cli_with_error_handling() -> bool:
             logger.warning("Got an InvalidServiceError. Trying again over tunneld since it is a developer command")
             should_retry_over_tunneld = True
         if should_retry_over_tunneld:
-            # use a single space because click will ignore envvars of empty strings
+            # use a single space because Typer/Click will ignore envvars of empty strings
             os.environ[TUNNEL_ENV_VAR] = e.identifier or " "
-            return main()
+            main()
+            return False
         logger.error(INVALID_SERVICE_MESSAGE)
     except PasswordRequiredError:
         logger.error("Device is password protected. Please unlock and retry")
@@ -315,6 +402,11 @@ def invoke_cli_with_error_handling() -> bool:
         )
     except QuicProtocolNotSupportedError:
         logger.error("Encountered a QUIC protocol error.")
+    except click.ClickException as e:
+        from typer import rich_utils
+
+        rich_utils.rich_format_error(e)
+        sys.exit(e.exit_code)
 
     return False
 

{pymobiledevice3-6.1.6 → pymobiledevice3-7.0.0}/pymobiledevice3/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '6.1.6'
-__version_tuple__ = version_tuple = (6, 1, 6)
+__version__ = version = '7.0.0'
+__version_tuple__ = version_tuple = (7, 0, 0)
 
-__commit_id__ = commit_id = 'g8900837a9'
+__commit_id__ = commit_id = 'g363ad89c4'

{pymobiledevice3-6.1.6 → pymobiledevice3-7.0.0}/pymobiledevice3/bonjour.py

@@ -300,10 +300,9 @@ async def browse_service(service_type: str, timeout: float = 4.0) -> list[Servic
     adapters = _Adapters()
 
     ptr_targets: set[str] = set()
-    srv_map: dict[str, dict] = {}
+    srv_map: dict[str, list[dict]] = defaultdict(list)  # instance_name -> list of {"target", "port"}
     txt_map: dict[str, dict] = {}
-    # host -> list[(ip, iface)]
-    host_addrs: dict[str, list[Address]] = defaultdict(list)
+    host_addrs: dict[str, list[Address]] = defaultdict(list)  # host -> list[(ip, iface)]
 
     def _record_addr(rr_name: str, ip_str: str, pkt_addr):
         # Determine family and possible scopeid from the packet that delivered this RR
@@ -314,7 +313,7 @@ async def browse_service(service_type: str, timeout: float = 4.0) -> list[Servic
         iface = adapters.pick_iface_for_ip(ip_str, family, scopeid)
         if iface is None:
             return
-        # avoid duplicates for the same host/ip
+        # Avoid duplicates for the same host/ip
         existing = host_addrs[rr_name]
         if not any(a.ip == ip_str for a in existing):
             existing.append(Address(ip=ip_str, iface=iface))
@@ -333,11 +332,10 @@ async def browse_service(service_type: str, timeout: float = 4.0) -> list[Servic
                 if t == QTYPE_PTR and rr.get("name") == service_type:
                     ptr_targets.add(rr.get("ptrdname"))
                 elif t == QTYPE_SRV:
-                    srv_map[rr["name"]] = {
-                        "target": rr.get("target"),
-                        "port": rr.get("port"),
-                    }
+                    srv_map[rr["name"]].append({"target": rr.get("target"), "port": rr.get("port")})
                 elif t == QTYPE_TXT:
+                    # TODO: This could possibly mix the properties of multiple TXT records for the same instance.
+                    #       However, it's currently unused.
                     txt_map[rr["name"]] = rr.get("txt", {})
                 elif (t == QTYPE_A and rr.get("address")) or (t == QTYPE_AAAA and rr.get("address")):
                     _record_addr(rr["name"], rr["address"], pkt_addr)
@@ -348,20 +346,21 @@ async def browse_service(service_type: str, timeout: float = 4.0) -> list[Servic
     # Assemble dataclasses
     results: list[ServiceInstance] = []
     for inst in sorted(ptr_targets):
-        srv = srv_map.get(inst, {})
-        target = srv.get("target")
-        host = (target[:-1] if target and target.endswith(".") else target) or None
-        addrs = host_addrs.get(target, []) if target else []
+        srv_entries = srv_map.get(inst, [])
         props = txt_map.get(inst, {})
-        results.append(
-            ServiceInstance(
-                instance=inst,
-                host=host,
-                port=srv.get("port"),
-                addresses=addrs,
-                properties=props,
+        for srv in srv_entries:
+            target = srv.get("target")
+            host = (target[:-1] if target and target.endswith(".") else target) or None
+            addrs = host_addrs.get(target, []) if target else []
+            results.append(
+                ServiceInstance(
+                    instance=inst,
+                    host=host,
+                    port=srv.get("port"),
+                    addresses=addrs,
+                    properties=props,
+                )
             )
-        )
     return results
 
 

pymobiledevice3-7.0.0/pymobiledevice3/cli/activation.py

@@ -0,0 +1,46 @@
+from typing import Annotated
+
+import typer
+from typer_injector import InjectingTyper
+
+from pymobiledevice3.cli.cli_common import ServiceProviderDep
+from pymobiledevice3.services.mobile_activation import MobileActivationService
+
+cli = InjectingTyper(
+    name="activation",
+    help="Perform iCloud activation/deactivation or query the current state",
+    no_args_is_help=True,
+)
+
+
+@cli.command()
+def state(service_provider: ServiceProviderDep) -> None:
+    """Get current activation state"""
+    print(MobileActivationService(service_provider).state)
+
+
+@cli.command()
+def activate(
+    service_provider: ServiceProviderDep,
+    now: Annotated[
+        bool,
+        typer.Option(help="do not wait for next nonce cycle"),
+    ] = False,
+) -> None:
+    """Activate device"""
+    activation_service = MobileActivationService(service_provider)
+    if not now:
+        activation_service.wait_for_activation_session()
+    activation_service.activate()
+
+
+@cli.command()
+def deactivate(service_provider: ServiceProviderDep) -> None:
+    """Deactivate device"""
+    MobileActivationService(service_provider).deactivate()
+
+
+@cli.command()
+def itunes(service_provider: ServiceProviderDep) -> None:
+    """Tell the device that it has been connected to iTunes (useful for < iOS 4)"""
+    service_provider.set_value(True, key="iTunesHasConnected")

pymobiledevice3-7.0.0/pymobiledevice3/cli/afc.py

@@ -0,0 +1,64 @@
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from typer_injector import InjectingTyper
+
+from pymobiledevice3.cli.cli_common import ServiceProviderDep
+from pymobiledevice3.services.afc import AfcService, AfcShell
+
+cli = InjectingTyper(
+    name="afc",
+    help="Browse, push, and pull files via the AFC service (/var/mobile/Media).",
+    no_args_is_help=True,
+)
+
+
+@cli.command("shell")
+def afc_shell(service_provider: ServiceProviderDep) -> None:
+    """Open an interactive AFC shell rooted at /var/mobile/Media."""
+    AfcShell.create(service_provider)
+
+
+@cli.command("pull")
+def afc_pull(
+    service_provider: ServiceProviderDep,
+    remote_file: Path,
+    local_file: Path,
+    ignore_errors: Annotated[
+        bool,
+        typer.Option(
+            "--ignore-errors",
+            "-i",
+            help="Continue downloading even if some files error (best-effort pull).",
+        ),
+    ],
+) -> None:
+    """Download a remote path under /var/mobile/Media to the local filesystem."""
+    AfcService(lockdown=service_provider).pull(str(remote_file), str(local_file), ignore_errors=ignore_errors)
+
+
+@cli.command("push")
+def afc_push(service_provider: ServiceProviderDep, local_file: Path, remote_file: Path) -> None:
+    """Upload a local file into /var/mobile/Media."""
+    AfcService(lockdown=service_provider).push(str(local_file), str(remote_file))
+
+
+@cli.command("ls")
+def afc_ls(
+    service_provider: ServiceProviderDep,
+    remote_file: Path,
+    recursive: Annotated[
+        bool,
+        typer.Option("--recursive", "-r", help="Recurse into subdirectories when listing."),
+    ] = False,
+) -> None:
+    """List files under /var/mobile/Media (optionally recursively)."""
+    for path in AfcService(lockdown=service_provider).dirlist(str(remote_file), -1 if recursive else 1):
+        print(path)
+
+
+@cli.command("rm")
+def afc_rm(service_provider: ServiceProviderDep, remote_file: Path) -> None:
+    """Delete a file under /var/mobile/Media."""
+    AfcService(lockdown=service_provider).rm(str(remote_file))

pymobiledevice3-7.0.0/pymobiledevice3/cli/amfi.py

@@ -0,0 +1,33 @@
+import logging
+
+from typer_injector import InjectingTyper
+
+from pymobiledevice3.cli.cli_common import ServiceProviderDep, print_json
+from pymobiledevice3.services.amfi import AmfiService
+
+logger = logging.getLogger(__name__)
+
+
+cli = InjectingTyper(
+    name="amfi",
+    help="Enable developer-mode or query its state",
+    no_args_is_help=True,
+)
+
+
+@cli.command()
+def reveal_developer_mode(service_provider: ServiceProviderDep) -> None:
+    """reveal developer mode option in device's UI"""
+    AmfiService(service_provider).reveal_developer_mode_option_in_ui()
+
+
+@cli.command()
+def enable_developer_mode(service_provider: ServiceProviderDep) -> None:
+    """enable developer mode"""
+    AmfiService(service_provider).enable_developer_mode()
+
+
+@cli.command()
+def developer_mode_status(service_provider: ServiceProviderDep) -> None:
+    """query developer mode status"""
+    print_json(service_provider.developer_mode_status)