cesium-ios 0.1.0__tar.gz

cesium_ios-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: cesium-ios
+Version: 0.1.0
+Summary: Driverless, WDA-Free iOS Test Automation & Telemetry SDK for Linux and Windows
+Author: Cesium Team
+Author-email: Cesium Team <info@cesium-ios.org>
+License: MIT
+Project-URL: Homepage, https://github.com/cesium-ios/cesium-ios
+Project-URL: Repository, https://github.com/cesium-ios/cesium-ios
+Keywords: ios,automation,coredevice,driverless,testing,wda-free,telemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pymobiledevice3>=4.0.0
+Dynamic: author
+Dynamic: requires-python
+
+# cesium-ios Python SDK
+
+**Driverless, 100% WDA-Free iOS Test Automation and Telemetry for Linux & Windows.**
+
+Eliminates WebDriverAgent (WDA), macOS requirements, and Apple Developer accounts. Directly communicates with physical iPhones running iOS 17+ via CoreDevice, `universalhidservice`, and `axAuditDaemon`.
+
+---
+
+## 📦 Installation
+
+### From Local Source (Editable Mode):
+```bash
+cd cesium_sdk
+pip install -e .
+```
+
+### From PyPI (When Published):
+```bash
+pip install cesium-ios
+```
+
+---
+
+## 🚀 Quickstart Example
+
+```python
+import time
+from cesium_ios import IOSDevice
+
+# Automatically connects to the attached device or reads os.environ["UDID"]
+device = IOSDevice()
+
+# 1. Clean slate: Return to Home
+device.home()
+
+# 2. Cold-launch an app or deep-link to a URL in < 25ms
+device.launch_app("com.apple.Preferences")
+time.sleep(2.0)
+
+# 3. Tap on Wi-Fi (using coordinates or by element name)
+device.tap(fx=0.50, fy=0.23)
+
+# 4. Scroll Down & Up
+device.scroll_down()
+time.sleep(1.0)
+device.scroll_up()
+
+# 5. Terminate the app
+device.terminate_app("Preferences")
+device.home()
+```
+
+---
+
+## 🔍 Smart Element Clicking (Zero Guesswork)
+
+```python
+# Automatically finds "Wi-Fi" on screen and taps its center
+device.tap_element("Wi-Fi")
+
+# Dump all elements on screen in ~78ms
+elements = device.get_accessibility_elements()
+for el in elements:
+    print(el.caption, el.bounds)
+```
+
+---
+
+## 🛠️ Publishing to PyPI
+
+```bash
+pip install build twine
+python -m build
+twine check dist/*
+twine upload dist/*
+```

cesium_ios-0.1.0/README.md

@@ -0,0 +1,76 @@
+# cesium-ios Python SDK
+
+**Driverless, 100% WDA-Free iOS Test Automation and Telemetry for Linux & Windows.**
+
+Eliminates WebDriverAgent (WDA), macOS requirements, and Apple Developer accounts. Directly communicates with physical iPhones running iOS 17+ via CoreDevice, `universalhidservice`, and `axAuditDaemon`.
+
+---
+
+## 📦 Installation
+
+### From Local Source (Editable Mode):
+```bash
+cd cesium_sdk
+pip install -e .
+```
+
+### From PyPI (When Published):
+```bash
+pip install cesium-ios
+```
+
+---
+
+## 🚀 Quickstart Example
+
+```python
+import time
+from cesium_ios import IOSDevice
+
+# Automatically connects to the attached device or reads os.environ["UDID"]
+device = IOSDevice()
+
+# 1. Clean slate: Return to Home
+device.home()
+
+# 2. Cold-launch an app or deep-link to a URL in < 25ms
+device.launch_app("com.apple.Preferences")
+time.sleep(2.0)
+
+# 3. Tap on Wi-Fi (using coordinates or by element name)
+device.tap(fx=0.50, fy=0.23)
+
+# 4. Scroll Down & Up
+device.scroll_down()
+time.sleep(1.0)
+device.scroll_up()
+
+# 5. Terminate the app
+device.terminate_app("Preferences")
+device.home()
+```
+
+---
+
+## 🔍 Smart Element Clicking (Zero Guesswork)
+
+```python
+# Automatically finds "Wi-Fi" on screen and taps its center
+device.tap_element("Wi-Fi")
+
+# Dump all elements on screen in ~78ms
+elements = device.get_accessibility_elements()
+for el in elements:
+    print(el.caption, el.bounds)
+```
+
+---
+
+## 🛠️ Publishing to PyPI
+
+```bash
+pip install build twine
+python -m build
+twine check dist/*
+twine upload dist/*
+```

cesium_ios-0.1.0/cesium_ios/__init__.py

@@ -0,0 +1,25 @@
+"""
+Cesium iOS Python SDK
+=====================
+Driverless, 100% WDA-Free iOS Test Automation and Telemetry for Linux and Windows.
+"""
+
+from .client import EngineClient
+from .device import AccessibilityElement, IOSDevice
+from .exceptions import (
+    CesiumConnectionError,
+    CesiumError,
+    DeviceNotFoundError,
+    ElementNotFoundError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "IOSDevice",
+    "EngineClient",
+    "AccessibilityElement",
+    "CesiumError",
+    "CesiumConnectionError",
+    "DeviceNotFoundError",
+    "ElementNotFoundError",
+]

cesium_ios-0.1.0/cesium_ios/client.py

@@ -0,0 +1,81 @@
+"""
+Low-level JSON-RPC client for the Cesium Native CoreDevice Engine.
+"""
+
+import json
+import logging
+import socket
+import time
+from typing import Any, Dict, Optional
+
+from .exceptions import CesiumConnectionError, CesiumError
+
+logger = logging.getLogger("cesium_ios.client")
+
+
+class EngineClient:
+    """
+    Direct low-latency JSON-RPC 2.0 client talking to the C cesium-engine daemon (port 9876).
+    """
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 9876, timeout: float = 6.0):
+        self.host = host
+        self.port = port
+        self.timeout = timeout
+        self._seq = 0
+
+    def call(self, method: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Executes an RPC method synchronously over a short-lived TCP socket.
+        """
+        self._seq += 1
+        req_id = self._seq
+        payload = {
+            "jsonrpc": "2.0",
+            "method": method,
+            "params": params or {},
+            "id": req_id,
+        }
+
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.settimeout(self.timeout)
+        try:
+            s.connect((self.host, self.port))
+            data = json.dumps(payload).encode("utf-8") + b"\n"
+            s.sendall(data)
+
+            raw_resp = b""
+            while True:
+                chunk = s.recv(4096)
+                if not chunk:
+                    break
+                raw_resp += chunk
+                if b"\n" in chunk:
+                    break
+
+            if not raw_resp:
+                raise CesiumConnectionError(f"Empty response from engine at {self.host}:{self.port}")
+
+            parsed = json.loads(raw_resp.decode("utf-8"))
+            if not parsed.get("ok", True) or "error" in parsed:
+                err_msg = parsed.get("error", "Unknown engine error")
+                raise CesiumError(f"Engine method '{method}' failed: {err_msg}")
+
+            return parsed.get("result", {})
+
+        except socket.timeout:
+            raise CesiumConnectionError(f"Socket timed out while calling '{method}' on {self.host}:{self.port}")
+        except ConnectionRefusedError:
+            raise CesiumConnectionError(
+                f"Could not connect to cesium-engine at {self.host}:{self.port}. "
+                "Ensure cesium-engine is running."
+            )
+        except Exception as e:
+            if isinstance(e, CesiumError):
+                raise
+            raise CesiumConnectionError(f"Network error communicating with cesium-engine: {e}") from e
+        finally:
+            try:
+                s.close()
+            except Exception:
+                pass

cesium_ios-0.1.0/cesium_ios/device.py

@@ -0,0 +1,238 @@
+"""
+High-level Pythonic interface for physical iOS device automation.
+"""
+
+import asyncio
+import os
+import re
+import time
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from .client import EngineClient
+from .exceptions import DeviceNotFoundError, ElementNotFoundError
+
+
+class AccessibilityElement:
+    """Represents an on-screen UIKit element returned by axAuditDaemon."""
+
+    def __init__(
+        self,
+        caption: str = "",
+        label: str = "",
+        identifier: str = "",
+        element_type: str = "",
+        bounds: Optional[Dict[str, int]] = None,
+        screen_w: int = 390,
+        screen_h: int = 844,
+    ):
+        self.caption = caption
+        self.label = label
+        self.identifier = identifier
+        self.element_type = element_type
+        self.bounds = bounds or {"x": 0, "y": 0, "width": 0, "height": 0}
+        self.screen_w = screen_w
+        self.screen_h = screen_h
+
+    @property
+    def center_fraction(self) -> tuple[float, float]:
+        """Calculates normalized (fx, fy) center fractions for tap injection."""
+        x = self.bounds.get("x", 0)
+        y = self.bounds.get("y", 0)
+        w = self.bounds.get("width", 0)
+        h = self.bounds.get("height", 0)
+        sw = max(self.screen_w, 1)
+        sh = max(self.screen_h, 1)
+        fx = (x + w / 2.0) / float(sw)
+        fy = (y + h / 2.0) / float(sh)
+        return (max(0.0, min(1.0, fx)), max(0.0, min(1.0, fy)))
+
+    def __repr__(self):
+        return f"<AccessibilityElement type='{self.element_type}' caption='{self.caption}' bounds={self.bounds}>"
+
+
+class IOSDevice:
+    """
+    Primary interface for automating physical iOS devices (iOS 17+) driverless.
+    """
+
+    def __init__(
+        self,
+        udid: Optional[str] = None,
+        host: str = "127.0.0.1",
+        port: int = 9876,
+    ):
+        self.host = host
+        self.port = port
+        self.udid = udid or os.environ.get("UDID") or self._auto_detect_udid()
+        self.client = EngineClient(host=host, port=port)
+        self.screen_width = 390
+        self.screen_height = 844
+
+    @staticmethod
+    def _auto_detect_udid() -> str:
+        """Attempts to auto-detect the connected device UDID via usbmuxd."""
+        try:
+            from pymobiledevice3.usbmux import list_devices
+            devs = asyncio.run(list_devices())
+            if devs:
+                return devs[0].serial
+        except Exception:
+            pass
+        return "default"
+
+    # =========================================================================
+    # APP LIFECYCLE & PROCESS MANAGEMENT
+    # =========================================================================
+    def launch_app(self, bundle_id: str, url: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Launches an application cold via CoreDevice.
+        If `url` is provided, opens deep link directly in under 25ms.
+        """
+        params = {"bundle_id": bundle_id}
+        if url:
+            params["url"] = url
+        return self.client.call("launch_app", params)
+
+    def list_processes(self) -> List[Dict[str, Any]]:
+        """Returns all running processes on the device with PIDs and executable paths."""
+        res = self.client.call("list_processes")
+        return res.get("processTokens", [])
+
+    def terminate_process(self, pid: int, signal: int = 9) -> Dict[str, Any]:
+        """Terminates a process by its PID."""
+        return self.client.call("terminate_app", {"pid": pid, "signal": signal})
+
+    def terminate_app(self, name_or_bundle_id: str) -> int:
+        """
+        Finds any running processes matching the name or bundle ID and terminates them.
+        Returns the number of terminated processes.
+        """
+        target = name_or_bundle_id.lower()
+        tokens = self.list_processes()
+        killed = 0
+        for tok in tokens:
+            exe = tok.get("executableURL", {}).get("relative", "")
+            if target in exe.lower():
+                pid = tok.get("processIdentifier")
+                if pid:
+                    self.terminate_process(pid)
+                    killed += 1
+        return killed
+
+    # =========================================================================
+    # HARDWARE GESTURES & BUTTONS
+    # =========================================================================
+    def home(self) -> Dict[str, Any]:
+        """Simulates native Home gesture (returns to SpringBoard)."""
+        return self.client.call("home")
+
+    def app_switcher(self) -> Dict[str, Any]:
+        """Simulates native App Switcher gesture."""
+        return self.client.call("app_switcher")
+
+    # =========================================================================
+    # TOUCH & GESTURE CONTROL (HARDWARE DIGITIZER)
+    # =========================================================================
+    def tap(self, fx: float, fy: float, dwell_ms: int = 80) -> Dict[str, Any]:
+        """
+        Injects a physical hardware digitizer tap at normalized fractions (0.0 to 1.0).
+        """
+        return self.client.call("swipe", {
+            "fx0": fx, "fy0": fy,
+            "fx1": fx, "fy1": fy,
+            "duration_ms": dwell_ms
+        })
+
+    def swipe(
+        self,
+        fx0: float,
+        fy0: float,
+        fx1: float,
+        fy1: float,
+        duration_ms: int = 300,
+    ) -> Dict[str, Any]:
+        """
+        Injects a physical hardware digitizer swipe between two normalized points.
+        """
+        return self.client.call("swipe", {
+            "x0": fx0, "y0": fy0,
+            "x1": fx1, "y1": fy1,
+            "duration_ms": duration_ms
+        })
+
+    def scroll_down(self, duration_ms: int = 300) -> Dict[str, Any]:
+        """Performs a standard vertical scroll down gesture."""
+        return self.swipe(0.50, 0.70, 0.50, 0.30, duration_ms=duration_ms)
+
+    def scroll_up(self, duration_ms: int = 300) -> Dict[str, Any]:
+        """Performs a standard vertical scroll up gesture."""
+        return self.swipe(0.50, 0.30, 0.50, 0.70, duration_ms=duration_ms)
+
+    # =========================================================================
+    # ACCESSIBILITY INSPECTION & SMART CLICKING
+    # =========================================================================
+    def get_accessibility_elements(self) -> List[AccessibilityElement]:
+        """
+        Queries Apple's native axAuditDaemon to dump all current on-screen UIKit elements.
+        """
+        elements = []
+        try:
+            from pymobiledevice3.lockdown import create_using_usbmux
+            from pymobiledevice3.services.accessibilityaudit import AccessibilityAudit
+
+            async def _dump():
+                nonlocal elements
+                lockdown = await create_using_usbmux(self.udid)
+                audit = AccessibilityAudit(lockdown)
+                try:
+                    first_pid = None
+                    async for el in audit.iter_elements():
+                        pid = getattr(el, 'platform_identifier', '')
+                        if first_pid is None:
+                            first_pid = pid
+                        elif pid == first_pid:
+                            break
+                        caption = el.caption or ""
+                        elements.append(AccessibilityElement(
+                            caption=caption,
+                            label=getattr(el, 'label', caption),
+                            identifier=getattr(el, 'identifier', ''),
+                            element_type=getattr(el, 'type', 'Element'),
+                            bounds=getattr(el, 'bounds', None),
+                            screen_w=self.screen_width,
+                            screen_h=self.screen_height,
+                        ))
+                finally:
+                    await audit.close()
+
+            asyncio.run(_dump())
+        except Exception:
+            pass
+        return elements
+
+    def find_element(self, text_or_predicate: Union[str, Callable[[AccessibilityElement], bool]]) -> AccessibilityElement:
+        """
+        Finds the first on-screen element matching the text caption or custom predicate.
+        """
+        elements = self.get_accessibility_elements()
+        if isinstance(text_or_predicate, str):
+            needle = text_or_predicate.lower()
+            predicate = lambda el: needle in el.caption.lower() or needle in el.label.lower() or needle in el.identifier.lower()
+        else:
+            predicate = text_or_predicate
+
+        for el in elements:
+            if predicate(el):
+                return el
+        raise ElementNotFoundError(f"No accessibility element matched '{text_or_predicate}'")
+
+    def tap_element(self, text_or_element: Union[str, AccessibilityElement]) -> Dict[str, Any]:
+        """
+        Finds an element by text/caption and taps its geometric center automatically!
+        """
+        if isinstance(text_or_element, str):
+            el = self.find_element(text_or_element)
+        else:
+            el = text_or_element
+        fx, fy = el.center_fraction
+        return self.tap(fx, fy)

cesium_ios-0.1.0/cesium_ios/exceptions.py

@@ -0,0 +1,22 @@
+"""
+Exceptions for the Cesium iOS SDK.
+"""
+
+class CesiumError(Exception):
+    """Base exception for all Cesium SDK errors."""
+    pass
+
+
+class CesiumConnectionError(CesiumError):
+    """Raised when communication with cesium-engine fails or times out."""
+    pass
+
+
+class DeviceNotFoundError(CesiumError):
+    """Raised when a requested device UDID cannot be found or attached."""
+    pass
+
+
+class ElementNotFoundError(CesiumError):
+    """Raised when an accessibility element matching the query cannot be located."""
+    pass

cesium_ios-0.1.0/cesium_ios.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: cesium-ios
+Version: 0.1.0
+Summary: Driverless, WDA-Free iOS Test Automation & Telemetry SDK for Linux and Windows
+Author: Cesium Team
+Author-email: Cesium Team <info@cesium-ios.org>
+License: MIT
+Project-URL: Homepage, https://github.com/cesium-ios/cesium-ios
+Project-URL: Repository, https://github.com/cesium-ios/cesium-ios
+Keywords: ios,automation,coredevice,driverless,testing,wda-free,telemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pymobiledevice3>=4.0.0
+Dynamic: author
+Dynamic: requires-python
+
+# cesium-ios Python SDK
+
+**Driverless, 100% WDA-Free iOS Test Automation and Telemetry for Linux & Windows.**
+
+Eliminates WebDriverAgent (WDA), macOS requirements, and Apple Developer accounts. Directly communicates with physical iPhones running iOS 17+ via CoreDevice, `universalhidservice`, and `axAuditDaemon`.
+
+---
+
+## 📦 Installation
+
+### From Local Source (Editable Mode):
+```bash
+cd cesium_sdk
+pip install -e .
+```
+
+### From PyPI (When Published):
+```bash
+pip install cesium-ios
+```
+
+---
+
+## 🚀 Quickstart Example
+
+```python
+import time
+from cesium_ios import IOSDevice
+
+# Automatically connects to the attached device or reads os.environ["UDID"]
+device = IOSDevice()
+
+# 1. Clean slate: Return to Home
+device.home()
+
+# 2. Cold-launch an app or deep-link to a URL in < 25ms
+device.launch_app("com.apple.Preferences")
+time.sleep(2.0)
+
+# 3. Tap on Wi-Fi (using coordinates or by element name)
+device.tap(fx=0.50, fy=0.23)
+
+# 4. Scroll Down & Up
+device.scroll_down()
+time.sleep(1.0)
+device.scroll_up()
+
+# 5. Terminate the app
+device.terminate_app("Preferences")
+device.home()
+```
+
+---
+
+## 🔍 Smart Element Clicking (Zero Guesswork)
+
+```python
+# Automatically finds "Wi-Fi" on screen and taps its center
+device.tap_element("Wi-Fi")
+
+# Dump all elements on screen in ~78ms
+elements = device.get_accessibility_elements()
+for el in elements:
+    print(el.caption, el.bounds)
+```
+
+---
+
+## 🛠️ Publishing to PyPI
+
+```bash
+pip install build twine
+python -m build
+twine check dist/*
+twine upload dist/*
+```

cesium_ios-0.1.0/cesium_ios.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+setup.py
+cesium_ios/__init__.py
+cesium_ios/client.py
+cesium_ios/device.py
+cesium_ios/exceptions.py
+cesium_ios.egg-info/PKG-INFO
+cesium_ios.egg-info/SOURCES.txt
+cesium_ios.egg-info/dependency_links.txt
+cesium_ios.egg-info/requires.txt
+cesium_ios.egg-info/top_level.txt

cesium_ios-0.1.0/cesium_ios.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cesium_ios-0.1.0/cesium_ios.egg-info/requires.txt

@@ -0,0 +1 @@
+pymobiledevice3>=4.0.0

cesium_ios-0.1.0/cesium_ios.egg-info/top_level.txt

@@ -0,0 +1 @@
+cesium_ios

cesium_ios-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cesium-ios"
+version = "0.1.0"
+description = "Driverless, WDA-Free iOS Test Automation & Telemetry SDK for Linux and Windows"
+readme = "README.md"
+authors = [
+    { name = "Cesium Team", email = "info@cesium-ios.org" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = [
+    "pymobiledevice3>=4.0.0",
+]
+keywords = ["ios", "automation", "coredevice", "driverless", "testing", "wda-free", "telemetry"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Testing",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/cesium-ios/cesium-ios"
+Repository = "https://github.com/cesium-ios/cesium-ios"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["cesium_ios*"]

cesium_ios-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cesium_ios-0.1.0/setup.py

@@ -0,0 +1,22 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="cesium-ios",
+    version="0.1.0",
+    description="Driverless, WDA-Free iOS Test Automation & Telemetry SDK",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    author="Cesium Team",
+    packages=find_packages(),
+    python_requires=">=3.9",
+    install_requires=[
+        "pymobiledevice3>=4.0.0",
+    ],
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "Topic :: Software Development :: Testing",
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+    ],
+)