droidrun 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

droidrun/tools/adb.py

@@ -3,29 +3,31 @@ UI Actions - Core UI interaction tools for Android device control.
 """
 
 import os
-import re
 import json
 import time
-import tempfile
 import asyncio
-import aiofiles
-import contextlib
 import logging
-from typing import Optional, Dict, Tuple, List, Any
+from typing import Optional, Dict, Tuple, List, Any, Type, Self
 from droidrun.adb.device import Device
 from droidrun.adb.manager import DeviceManager
 from droidrun.tools.tools import Tools
 
 logger = logging.getLogger("droidrun-adb-tools")
 
+
 class AdbTools(Tools):
     """Core UI interaction tools for Android device control."""
 
-    def __init__(self, serial: str = "emulator-5554") -> None:
+    def __init__(self, serial: str) -> None:
+        """Initialize the AdbTools instance.
+
+        Args:
+            serial: Device serial number
+        """
+        self.device_manager = DeviceManager()
         # Instance‐level cache for clickable elements (index-based tapping)
         self.clickable_elements_cache: List[Dict[str, Any]] = []
         self.serial = serial
-        self.device_manager = DeviceManager()
         self.last_screenshot = None
         self.reason = None
         self.success = None
@@ -35,19 +37,38 @@ class AdbTools(Tools):
         # Store all screenshots with timestamps
         self.screenshots: List[Dict[str, Any]] = []
 
-    def get_device_serial(self) -> str:
+    @classmethod
+    async def create(cls: Type[Self], serial: str = None) -> Self:
+        """Create an AdbTools instance.
+
+        Args:
+            serial: Optional device serial number. If not provided, the first device found will be used.
+
+        Returns:
+            AdbTools instance
+        """
+        if not serial:
+            dvm = DeviceManager()
+            devices = await dvm.list_devices()
+            if not devices or len(devices) < 1:
+                raise ValueError("No devices found")
+            serial = devices[0].serial
+
+        return AdbTools(serial)
+
+    def _get_device_serial(self) -> str:
         """Get the device serial from the instance or environment variable."""
         # First try using the instance's serial
         if self.serial:
             return self.serial
 
-    async def get_device(self) -> Optional[Device]:
+    async def _get_device(self) -> Optional[Device]:
         """Get the device instance using the instance's serial or from environment variable.
 
         Returns:
             Device instance or None if not found
         """
-        serial = self.get_device_serial()
+        serial = self._get_device_serial()
         if not serial:
             raise ValueError("No device serial specified - set device_serial parameter")
 
@@ -57,63 +78,46 @@ class AdbTools(Tools):
 
         return device
 
-    def parse_package_list(self, output: str) -> List[Dict[str, str]]:
-        """Parse the output of 'pm list packages -f' command.
-
-        Args:
-            output: Raw command output from 'pm list packages -f'
-
-        Returns:
-            List of dictionaries containing package info with 'package' and 'path' keys
-        """
-        apps = []
-        for line in output.splitlines():
-            if line.startswith("package:"):
-                # Format is: "package:/path/to/base.apk=com.package.name"
-                path_and_pkg = line[8:]  # Strip "package:"
-                if "=" in path_and_pkg:
-                    path, package = path_and_pkg.rsplit("=", 1)
-                    apps.append({"package": package.strip(), "path": path.strip()})
-        return apps
-
-    def _parse_content_provider_output(self, raw_output: str) -> Optional[Dict[str, Any]]:
+    def _parse_content_provider_output(
+        self, raw_output: str
+    ) -> Optional[Dict[str, Any]]:
         """
         Parse the raw ADB content provider output and extract JSON data.
-        
+
         Args:
             raw_output (str): Raw output from ADB content query command
-            
+
         Returns:
             dict: Parsed JSON data or None if parsing failed
         """
         # The ADB content query output format is: "Row: 0 result={json_data}"
         # We need to extract the JSON part after "result="
-        lines = raw_output.strip().split('\n')
-        
+        lines = raw_output.strip().split("\n")
+
         for line in lines:
             line = line.strip()
-            
+
             # Look for lines that contain "result=" pattern
             if "result=" in line:
                 # Extract everything after "result="
                 result_start = line.find("result=") + 7
                 json_str = line[result_start:]
-                
+
                 try:
                     # Parse the JSON string
                     json_data = json.loads(json_str)
                     return json_data
                 except json.JSONDecodeError:
                     continue
-            
+
             # Fallback: try to parse lines that start with { or [
-            elif line.startswith('{') or line.startswith('['):
+            elif line.startswith("{") or line.startswith("["):
                 try:
                     json_data = json.loads(line)
                     return json_data
                 except json.JSONDecodeError:
                     continue
-        
+
         # If no valid JSON found in individual lines, try the entire output
         try:
             json_data = json.loads(raw_output.strip())
@@ -199,7 +203,7 @@ class AdbTools(Tools):
                 if not device:
                     return f"Error: Device {serial} not found"
             else:
-                device = await self.get_device()
+                device = await self._get_device()
 
             await device.tap(x, y)
 
@@ -246,7 +250,7 @@ class AdbTools(Tools):
                 if not device:
                     return f"Error: Device {self.serial} not found"
             else:
-                device = await self.get_device()
+                device = await self._get_device()
 
             await device.tap(x, y)
             print(f"Tapped at coordinates ({x}, {y})")
@@ -292,11 +296,13 @@ class AdbTools(Tools):
                 if not device:
                     return f"Error: Device {self.serial} not found"
             else:
-                device = await self.get_device()
+                device = await self._get_device()
 
             await device.swipe(start_x, start_y, end_x, end_y, duration_ms)
             await asyncio.sleep(1)
-            print(f"Swiped from ({start_x}, {start_y}) to ({end_x}, {end_y}) in {duration_ms}ms")
+            print(
+                f"Swiped from ({start_x}, {start_y}) to ({end_x}, {end_y}) in {duration_ms}ms"
+            )
             return True
         except ValueError as e:
             print(f"Error: {str(e)}")
@@ -319,7 +325,7 @@ class AdbTools(Tools):
                 if not device:
                     return f"Error: Device {serial} not found"
             else:
-                device = await self.get_device()
+                device = await self._get_device()
 
             # Save the current keyboard
             original_ime = await device._adb.shell(
@@ -372,7 +378,7 @@ class AdbTools(Tools):
                 if not device:
                     return f"Error: Device {self.serial} not found"
             else:
-                device = await self.get_device()
+                device = await self._get_device()
 
             await device.press_key(3)
             return f"Pressed key BACK"
@@ -398,7 +404,7 @@ class AdbTools(Tools):
                 if not device:
                     return f"Error: Device {self.serial} not found"
             else:
-                device = await self.get_device()
+                device = await self._get_device()
 
             key_names = {
                 66: "ENTER",
@@ -427,7 +433,7 @@ class AdbTools(Tools):
                 if not device:
                     return f"Error: Device {self.serial} not found"
             else:
-                device = await self.get_device()
+                device = await self._get_device()
 
             result = await device.start_app(package, activity)
             return result
@@ -451,7 +457,7 @@ class AdbTools(Tools):
                 if not device:
                     return f"Error: Device {self.serial} not found"
             else:
-                device = await self.get_device()
+                device = await self._get_device()
 
             if not os.path.exists(apk_path):
                 return f"Error: APK file not found at {apk_path}"
@@ -473,7 +479,7 @@ class AdbTools(Tools):
                 if not device:
                     raise ValueError(f"Device {self.serial} not found")
             else:
-                device = await self.get_device()
+                device = await self._get_device()
             screen_tuple = await device.take_screenshot()
             self.last_screenshot = screen_tuple[1]
 
@@ -505,158 +511,12 @@ class AdbTools(Tools):
                 if not device:
                     raise ValueError(f"Device {self.serial} not found")
             else:
-                device = await self.get_device()
-
-            # Use the direct ADB command to get packages with paths
-            cmd = ["pm", "list", "packages", "-f"]
-            if not include_system_apps:
-                cmd.append("-3")
-
-            output = await device._adb.shell(device._serial, " ".join(cmd))
-
-            # Parse the package list using the function
-            packages = self.parse_package_list(output)
-            # Format package list for better readability
-            package_list = [pack["package"] for pack in packages]
-            for package in package_list:
-                print(package)
-            return package_list
+                device = await self._get_device()
+
+            return await device.list_packages(include_system_apps)
         except ValueError as e:
             raise ValueError(f"Error listing packages: {str(e)}")
 
-    async def extract(self, filename: Optional[str] = None) -> str:
-        """Extract and save the current UI state to a JSON file.
-
-        This function captures the current UI state including all UI elements
-        and saves it to a JSON file for later analysis or reference.
-
-        Args:
-            filename: Optional filename to save the UI state (defaults to ui_state_TIMESTAMP.json)
-
-        Returns:
-            Path to the saved JSON file
-        """
-        try:
-            # Generate default filename if not provided
-            if not filename:
-                timestamp = int(time.time())
-                filename = f"ui_state_{timestamp}.json"
-
-            # Ensure the filename ends with .json
-            if not filename.endswith(".json"):
-                filename += ".json"
-
-            # Get the UI elements
-            ui_elements = await self.get_all_elements(self.serial)
-
-            # Save to file
-            save_path = os.path.abspath(filename)
-            async with aiofiles.open(save_path, "w", encoding="utf-8") as f:
-                await f.write(json.dumps(ui_elements, indent=2))
-
-            return f"UI state extracted and saved to {save_path}"
-
-        except Exception as e:
-            return f"Error extracting UI state: {e}"
-
-    async def get_all_elements(self) -> Dict[str, Any]:
-        """
-        Get all UI elements from the device, including non-interactive elements.
-
-        This function interacts with the TopViewService app installed on the device
-        to capture all UI elements, even those that are not interactive. This provides
-        a complete view of the UI hierarchy for analysis or debugging purposes.
-
-        Returns:
-            Dictionary containing all UI elements extracted from the device screen
-        """
-        try:
-            # Get the device
-            device = await self.device_manager.get_device(self.serial)
-            if not device:
-                raise ValueError(f"Device {self.serial} not found")
-
-            # Create a temporary file for the JSON
-            with tempfile.NamedTemporaryFile(suffix=".json") as temp:
-                local_path = temp.name
-
-                try:
-                    # Clear logcat to make it easier to find our output
-                    await device._adb.shell(device._serial, "logcat -c")
-
-                    # Trigger the custom service via broadcast to get ALL elements
-                    await device._adb.shell(
-                        device._serial,
-                        "am broadcast -a com.droidrun.portal.GET_ALL_ELEMENTS",
-                    )
-
-                    # Poll for the JSON file path
-                    start_time = asyncio.get_event_loop().time()
-                    max_wait_time = 10  # Maximum wait time in seconds
-                    poll_interval = 0.2  # Check every 200ms
-
-                    device_path = None
-                    while asyncio.get_event_loop().time() - start_time < max_wait_time:
-                        # Check logcat for the file path
-                        logcat_output = await device._adb.shell(
-                            device._serial,
-                            'logcat -d | grep "DROIDRUN_FILE" | grep "JSON data written to" | tail -1',
-                        )
-
-                        # Parse the file path if present
-                        match = re.search(r"JSON data written to: (.*)", logcat_output)
-                        if match:
-                            device_path = match.group(1).strip()
-                            break
-
-                        # Wait before polling again
-                        await asyncio.sleep(poll_interval)
-
-                    # Check if we found the file path
-                    if not device_path:
-                        raise ValueError(
-                            f"Failed to find the JSON file path in logcat after {max_wait_time} seconds"
-                        )
-
-                    logger.debug(f"Pulling file from {device_path} to {local_path}")
-                    # Pull the JSON file from the device
-                    await device._adb.pull_file(device._serial, device_path, local_path)
-
-                    # Read the JSON file
-                    async with aiofiles.open(local_path, "r", encoding="utf-8") as f:
-                        json_content = await f.read()
-
-                    # Clean up the temporary file
-                    with contextlib.suppress(OSError):
-                        os.unlink(local_path)
-
-                    # Try to parse the JSON
-                    import json
-
-                    try:
-                        ui_data = json.loads(json_content)
-
-                        return {
-                            "all_elements": ui_data,
-                            "count": (
-                                len(ui_data)
-                                if isinstance(ui_data, list)
-                                else sum(1 for _ in ui_data.get("elements", []))
-                            ),
-                            "message": "Retrieved all UI elements from the device screen",
-                        }
-                    except json.JSONDecodeError:
-                        raise ValueError("Failed to parse UI elements JSON data")
-
-                except Exception as e:
-                    # Clean up in case of error
-                    with contextlib.suppress(OSError):
-                        os.unlink(local_path)
-                    raise ValueError(f"Error retrieving all UI elements: {e}")
-
-        except Exception as e:
-            raise ValueError(f"Error getting all UI elements: {e}")
-
     def complete(self, success: bool, reason: str = ""):
         """
         Mark the task as finished.
@@ -722,26 +582,26 @@ class AdbTools(Tools):
         Returns:
             Dictionary containing both 'a11y_tree' and 'phone_state' data
         """
-        
+
         try:
             if serial:
                 device = await self.device_manager.get_device(serial)
                 if not device:
                     raise ValueError(f"Device {serial} not found")
             else:
-                device = await self.get_device()
+                device = await self._get_device()
 
             adb_output = await device._adb.shell(
                 device._serial,
-                'content query --uri content://com.droidrun.portal/state'
+                "content query --uri content://com.droidrun.portal/state",
             )
 
             state_data = self._parse_content_provider_output(adb_output)
-            
+
             if state_data is None:
                 return {
                     "error": "Parse Error",
-                    "message": "Failed to parse state data from ContentProvider response"
+                    "message": "Failed to parse state data from ContentProvider response",
                 }
 
             if isinstance(state_data, dict) and "data" in state_data:
@@ -751,25 +611,25 @@ class AdbTools(Tools):
                 except json.JSONDecodeError:
                     return {
                         "error": "Parse Error",
-                        "message": "Failed to parse JSON data from ContentProvider data field"
+                        "message": "Failed to parse JSON data from ContentProvider data field",
                     }
             else:
                 return {
                     "error": "Format Error",
-                    "message": f"Unexpected state data format: {type(state_data)}"
+                    "message": f"Unexpected state data format: {type(state_data)}",
                 }
 
             # Validate that both a11y_tree and phone_state are present
             if "a11y_tree" not in combined_data:
                 return {
                     "error": "Missing Data",
-                    "message": "a11y_tree not found in combined state data"
+                    "message": "a11y_tree not found in combined state data",
                 }
-            
+
             if "phone_state" not in combined_data:
                 return {
-                    "error": "Missing Data", 
-                    "message": "phone_state not found in combined state data"
+                    "error": "Missing Data",
+                    "message": "phone_state not found in combined state data",
                 }
 
             # Filter out the "type" attribute from all a11y_tree elements
@@ -777,9 +637,7 @@ class AdbTools(Tools):
             filtered_elements = []
             for element in elements:
                 # Create a copy of the element without the "type" attribute
-                filtered_element = {
-                    k: v for k, v in element.items() if k != "type"
-                }
+                filtered_element = {k: v for k, v in element.items() if k != "type"}
 
                 # Also filter children if present
                 if "children" in filtered_element:
@@ -789,19 +647,25 @@ class AdbTools(Tools):
                     ]
 
                 filtered_elements.append(filtered_element)
-            
+
             self.clickable_elements_cache = filtered_elements
-            
+
             return {
                 "a11y_tree": filtered_elements,
-                "phone_state": combined_data["phone_state"]
+                "phone_state": combined_data["phone_state"],
             }
 
         except Exception as e:
-            return {"error": str(e), "message": f"Error getting combined state: {str(e)}"}
+            return {
+                "error": str(e),
+                "message": f"Error getting combined state: {str(e)}",
+            }
+
 
 if __name__ == "__main__":
+
     async def main():
-        tools = AdbTools()
+        tools = await AdbTools.create()
+        print(tools.serial)
 
-    asyncio.run(main())
+    asyncio.run(main())

droidrun/tools/ios.py

@@ -39,6 +39,12 @@ class IOSTools(Tools):
     """Core UI interaction tools for iOS device control."""
 
     def __init__(self, url: str, bundle_identifiers: List[str] = []) -> None:
+        """Initialize the IOSTools instance.
+
+        Args:
+            url: iOS device URL. This is the URL of the iOS device. It is used to send requests to the iOS device.
+            bundle_identifiers: List of bundle identifiers to include in the list of packages
+        """
         self.clickable_elements_cache: List[Dict[str, Any]] = []
         self.url = url
         self.last_screenshot = None
@@ -536,9 +542,6 @@ class IOSTools(Tools):
             all_packages.update(SYSTEM_BUNDLE_IDENTIFIERS)
         return sorted(list(all_packages))
 
-    async def extract(self, filename: str | None = None) -> str:
-        # TODO
-        return "not implemented"
 
     async def remember(self, information: str) -> str:
         """

droidrun/tools/tools.py

@@ -8,12 +8,23 @@ logger = logging.getLogger(__name__)
 
 
 class Tools(ABC):
+    """
+    Abstract base class for all tools.
+    This class provides a common interface for all tools to implement.
+    """
+
     @abstractmethod
     async def get_state(self) -> Dict[str, Any]:
+        """
+        Get the current state of the tool.
+        """
         pass
 
     @abstractmethod
     async def tap_by_index(self, index: int) -> bool:
+        """
+        Tap the element at the given index.
+        """
         pass
 
     #@abstractmethod
@@ -24,46 +35,72 @@ class Tools(ABC):
     async def swipe(
         self, start_x: int, start_y: int, end_x: int, end_y: int, duration_ms: int = 300
     ) -> bool:
+        """
+        Swipe from the given start coordinates to the given end coordinates.
+        """
         pass
 
     @abstractmethod
     async def input_text(self, text: str) -> bool:
+        """
+        Input the given text into a focused input field.
+        """
         pass
 
     @abstractmethod
     async def back(self) -> bool:
+        """
+        Press the back button.
+        """
         pass
 
     @abstractmethod
     async def press_key(self, keycode: int) -> bool:
+        """
+        Enter the given keycode.
+        """
         pass
 
     @abstractmethod
     async def start_app(self, package: str, activity: str = "") -> bool:
+        """
+        Start the given app.
+        """
         pass
 
     @abstractmethod
     async def take_screenshot(self) -> Tuple[str, bytes]:
+        """
+        Take a screenshot of the device.
+        """
         pass
 
     @abstractmethod
     async def list_packages(self, include_system_apps: bool = False) -> List[str]:
+        """
+        List all packages on the device.
+        """
         pass
 
     @abstractmethod
     async def remember(self, information: str) -> str:
+        """
+        Remember the given information. This is used to store information in the tool's memory.
+        """
         pass
 
     @abstractmethod
     async def get_memory(self) -> List[str]:
-        pass
-
-    @abstractmethod
-    async def extract(self, filename: Optional[str] = None) -> str:
+        """
+        Get the memory of the tool.
+        """
         pass
 
     @abstractmethod
     def complete(self, success: bool, reason: str = "") -> bool:
+        """
+        Complete the tool. This is used to indicate that the tool has completed its task.
+        """
         pass
 
 
@@ -84,12 +121,10 @@ def describe_tools(tools: Tools) -> Dict[str, Callable[..., Any]]:
         "input_text": tools.input_text,
         "press_key": tools.press_key,
         "tap_by_index": tools.tap_by_index,
-        # "tap_by_coordinates": tools_instance.tap_by_coordinates,
         # App management
         "start_app": tools.start_app,
         "list_packages": tools.list_packages,
         # state management
-        "extract": tools.extract,
         "remember": tools.remember,
         "complete": tools.complete,
     }