phantomwright 0.1.5__tar.gz → 0.2.0__tar.gz

{phantomwright-0.1.5 → phantomwright-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phantomwright
-Version: 0.1.5
+Version: 0.2.0
 Summary: Bridging playwright-core patch + extending playwright API for stealth injection & user simulation
 Project-URL: homepage, https://github.com/ai-microsoft/phantom-wright
 Project-URL: changelog, https://github.com/ai-microsoft/phantom-wright/blob/main/CHANGELOG.md
@@ -9,8 +9,12 @@ License-Expression: MIT
 License-File: LICENSE
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.9
-Requires-Dist: phantomwright-driver==1.57.7
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: markitdown>=0.1.0
+Requires-Dist: phantomwright-driver==1.58.3
 Provides-Extra: black
 Requires-Dist: black>=25.9.0; extra == 'black'
 Provides-Extra: dev

phantomwright-0.2.0/phantomwright/_repo_version.py

@@ -0,0 +1 @@
+version = 'v0.2.0'

phantomwright-0.2.0/phantomwright/cli/__init__.py

@@ -0,0 +1,5 @@
+"""PhantomWright CLI - Browser automation from the command line."""
+
+from .main import cli
+
+__all__ = ["cli"]

phantomwright-0.2.0/phantomwright/cli/client.py

@@ -0,0 +1,201 @@
+"""Client for communicating with the browser session server."""
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+import httpx
+
+from .server import SESSION_FILE, DEFAULT_PORT
+
+
+class SessionClient:
+    """Client for communicating with the browser session server."""
+
+    def __init__(self, port: Optional[int] = None):
+        self._port = port
+        self._base_url: Optional[str] = None
+
+    def _get_base_url(self) -> Optional[str]:
+        """Get the base URL for the server."""
+        if self._base_url:
+            return self._base_url
+
+        # Try to load port from session file
+        port = self._port
+        if port is None:
+            if SESSION_FILE.exists():
+                try:
+                    with open(SESSION_FILE, "r") as f:
+                        session_info = json.load(f)
+                        port = session_info.get("port", DEFAULT_PORT)
+                except (json.JSONDecodeError, IOError):
+                    port = DEFAULT_PORT
+            else:
+                port = DEFAULT_PORT
+
+        self._base_url = f"http://127.0.0.1:{port}"
+        return self._base_url
+
+    def is_server_running(self) -> bool:
+        """Check if the server is running."""
+        base_url = self._get_base_url()
+        if not base_url:
+            return False
+
+        try:
+            with httpx.Client(timeout=2.0) as client:
+                response = client.get(f"{base_url}/status")
+                return response.status_code == 200
+        except httpx.RequestError:
+            return False
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        data: Optional[dict] = None,
+        timeout: float = 60.0,
+    ) -> dict:
+        """Make a request to the server."""
+        base_url = self._get_base_url()
+        if not base_url:
+            return {"error": "NoSession", "message": "No active browser session. Run 'phantomwright start' first."}
+
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                if method == "GET":
+                    response = client.get(f"{base_url}{endpoint}")
+                else:
+                    response = client.post(f"{base_url}{endpoint}", json=data or {})
+
+                return response.json()
+        except httpx.ConnectError:
+            return {"error": "NoSession", "message": "No active browser session. Run 'phantomwright start' first."}
+        except httpx.RequestError as e:
+            return {"error": "ConnectionError", "message": str(e)}
+        except json.JSONDecodeError:
+            return {"error": "InvalidResponse", "message": "Invalid response from server"}
+
+    def get_status(self) -> dict:
+        """Get server status."""
+        return self._request("GET", "/status")
+
+    def stop(self) -> dict:
+        """Stop the server."""
+        return self._request("POST", "/stop")
+
+    def navigate(
+        self,
+        url: str,
+        simulate: bool = True,
+        cool_down: bool = True,
+        wait_for: Optional[str] = None,
+        timeout: int = 30000,
+    ) -> dict:
+        """Navigate to a URL."""
+        return self._request("POST", "/navigate", {
+            "url": url,
+            "simulate": simulate,
+            "cool_down": cool_down,
+            "wait_for": wait_for,
+            "timeout": timeout,
+        }, timeout=timeout / 1000 + 30)
+
+    def scroll(self, duration: int = 2000) -> dict:
+        """Scroll the page."""
+        return self._request("POST", "/scroll", {"duration": duration}, timeout=duration / 1000 + 10)
+
+    def browse(self, duration: int = 2000) -> dict:
+        """Simulate browsing."""
+        return self._request("POST", "/browse", {"duration": duration}, timeout=duration / 1000 + 10)
+
+    def click(self, selector: str, simulate: bool = True) -> dict:
+        """Click an element."""
+        return self._request("POST", "/click", {
+            "selector": selector,
+            "simulate": simulate,
+        })
+
+    def type_text(self, selector: str, text: str, simulate: bool = True, typos: bool = False) -> dict:
+        """Type text into an element."""
+        return self._request("POST", "/type", {
+            "selector": selector,
+            "text": text,
+            "simulate": simulate,
+            "typos": typos,
+        }, timeout=len(text) * 0.5 + 30)
+
+    def screenshot(
+        self,
+        selector: Optional[str] = None,
+        full_page: bool = False,
+    ) -> dict:
+        """Take a screenshot."""
+        return self._request("POST", "/screenshot", {
+            "selector": selector,
+            "full_page": full_page,
+        })
+
+    def get_html(self, selector: Optional[str] = None, outer: bool = True) -> dict:
+        """Get HTML content."""
+        return self._request("POST", "/html", {
+            "selector": selector,
+            "outer": outer,
+        })
+
+    def get_text(self, selector: str) -> dict:
+        """Get text content."""
+        return self._request("POST", "/text", {"selector": selector})
+
+    def get_attr(self, selector: str, attribute: str) -> dict:
+        """Get attribute value."""
+        return self._request("POST", "/attr", {
+            "selector": selector,
+            "attribute": attribute,
+        })
+
+    def query(
+        self,
+        selector: str,
+        limit: Optional[int] = None,
+        attrs: Optional[str] = None,
+    ) -> dict:
+        """Query elements."""
+        return self._request("POST", "/query", {
+            "selector": selector,
+            "limit": limit,
+            "attrs": attrs,
+        })
+
+    def get_url(self) -> dict:
+        """Get current URL."""
+        return self._request("GET", "/url")
+
+    def get_title(self) -> dict:
+        """Get page title."""
+        return self._request("GET", "/title")
+
+    def wait(self, selector: str, timeout: int = 30000, state: str = "visible") -> dict:
+        """Wait for an element."""
+        return self._request("POST", "/wait", {
+            "selector": selector,
+            "timeout": timeout,
+            "state": state,
+        }, timeout=timeout / 1000 + 10)
+
+    def get_markdown(self, selector: Optional[str] = None) -> dict:
+        """Get page content as markdown with selectors."""
+        return self._request("POST", "/markdown", {"selector": selector})
+
+
+# Global client instance
+_client: Optional[SessionClient] = None
+
+
+def get_client() -> SessionClient:
+    """Get the global session client."""
+    global _client
+    if _client is None:
+        _client = SessionClient()
+    return _client

phantomwright-0.2.0/phantomwright/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""PhantomWright CLI commands."""

phantomwright-0.2.0/phantomwright/cli/commands/extraction.py

@@ -0,0 +1,137 @@
+"""Extraction commands: screenshot, html, text, attr, query."""
+
+import base64
+import os
+import click
+
+from ..client import get_client
+from ..output import output_success, output_error
+
+
+@click.command()
+@click.option("--path", default=None, help="File path to save screenshot")
+@click.option("--selector", default=None, help="CSS selector for element screenshot")
+@click.option("--full-page/--no-full-page", default=False, help="Capture full scrollable page")
+def screenshot(path: str, selector: str, full_page: bool):
+    """Take a screenshot of the page or element."""
+    client = get_client()
+    result = client.screenshot(selector=selector, full_page=full_page)
+
+    if "error" in result:
+        output_error("screenshot", result["error"], result["message"], selector=selector)
+        return
+
+    screenshot_bytes = base64.b64decode(result["base64"])
+
+    if path:
+        # Ensure directory exists
+        dir_path = os.path.dirname(path)
+        if dir_path:
+            os.makedirs(dir_path, exist_ok=True)
+        with open(path, "wb") as f:
+            f.write(screenshot_bytes)
+        output_success("screenshot", {
+            "path": os.path.abspath(path),
+            "size_bytes": result["size_bytes"],
+            "selector": selector,
+            "full_page": full_page,
+        })
+    else:
+        # Return base64 encoded image
+        output_success("screenshot", {
+            "base64": result["base64"],
+            "size_bytes": result["size_bytes"],
+            "selector": selector,
+            "full_page": full_page,
+        })
+
+
+@click.command()
+@click.option("--selector", default=None, help="CSS selector to get HTML from")
+@click.option("--outer/--inner", default=True, help="Get outer HTML (default) or inner HTML")
+def html(selector: str, outer: bool):
+    """Get page or element HTML content."""
+    client = get_client()
+    result = client.get_html(selector=selector, outer=outer)
+
+    if "error" in result:
+        output_error("html", result["error"], result["message"], selector=selector)
+    else:
+        output_success("html", {
+            "html": result["html"],
+            "length": result["length"],
+            "selector": selector,
+            "type": result["type"],
+        })
+
+
+@click.command()
+@click.argument("selector")
+def text(selector: str):
+    """Get text content of an element."""
+    client = get_client()
+    result = client.get_text(selector=selector)
+
+    if "error" in result:
+        output_error("text", result["error"], result["message"], selector=selector)
+    else:
+        output_success("text", {
+            "text": result["text"],
+            "length": result["length"],
+            "selector": selector,
+        })
+
+
+@click.command()
+@click.argument("selector")
+@click.argument("attribute")
+def attr(selector: str, attribute: str):
+    """Get an attribute value from an element."""
+    client = get_client()
+    result = client.get_attr(selector=selector, attribute=attribute)
+
+    if "error" in result:
+        output_error("attr", result["error"], result["message"], selector=selector)
+    else:
+        output_success("attr", {
+            "attribute": result["attribute"],
+            "value": result["value"],
+            "selector": selector,
+        })
+
+
+@click.command()
+@click.argument("selector")
+@click.option("--limit", default=None, type=int, help="Maximum number of elements to return")
+@click.option("--attrs", default=None, help="Comma-separated list of attributes to extract")
+def query(selector: str, limit: int, attrs: str):
+    """Query all elements matching a selector."""
+    client = get_client()
+    result = client.query(selector=selector, limit=limit, attrs=attrs)
+
+    if "error" in result:
+        output_error("query", result["error"], result["message"], selector=selector)
+    else:
+        output_success("query", {
+            "elements": result["elements"],
+            "count": result["count"],
+            "total_matches": result.get("total_matches", result["count"]),
+            "selector": selector,
+        })
+
+
+@click.command()
+@click.option("--selector", default=None, help="CSS selector to convert (default: entire page)")
+def markdown(selector: str):
+    """Get page content as markdown with embedded selectors for agent interaction."""
+    client = get_client()
+    result = client.get_markdown(selector=selector)
+
+    if "error" in result:
+        output_error("markdown", result["error"], result["message"], selector=selector)
+    else:
+        output_success("markdown", {
+            "markdown": result["markdown"],
+            "url": result["url"],
+            "title": result["title"],
+        })

phantomwright-0.2.0/phantomwright/cli/commands/info.py

@@ -0,0 +1,169 @@
+"""Info commands: url, title, wait, status, start, stop."""
+
+import asyncio
+import subprocess
+import sys
+import click
+
+from ..session import load_session, clear_session, is_session_active
+from ..client import get_client
+from ..output import output_success, output_error
+
+
+@click.command()
+def url():
+    """Get the current page URL."""
+    client = get_client()
+    result = client.get_url()
+
+    if "error" in result:
+        output_error("url", result["error"], result["message"])
+    else:
+        output_success("url", {"url": result["url"]})
+
+
+@click.command()
+def title():
+    """Get the current page title."""
+    client = get_client()
+    result = client.get_title()
+
+    if "error" in result:
+        output_error("title", result["error"], result["message"])
+    else:
+        output_success("title", {
+            "title": result["title"],
+            "url": result["url"],
+        })
+
+
+@click.command()
+@click.argument("selector")
+@click.option("--timeout", default=30000, help="Timeout in milliseconds")
+@click.option("--state", default="visible", type=click.Choice(["attached", "detached", "visible", "hidden"]), help="Element state to wait for")
+def wait(selector: str, timeout: int, state: str):
+    """Wait for an element to appear."""
+    client = get_client()
+    result = client.wait(selector, timeout=timeout, state=state)
+
+    if "error" in result:
+        output_error("wait", result["error"], result["message"], selector=selector, timeout=timeout)
+    else:
+        output_success("wait", {
+            "selector": selector,
+            "state": state,
+            "found": result["found"],
+            "count": result["count"],
+        })
+
+
+@click.command()
+def status():
+    """Get the current session status."""
+    client = get_client()
+    result = client.get_status()
+    output_success("status", result)
+
+
+@click.command()
+@click.option("--browser", default="chrome", type=click.Choice(["chrome", "msedge"]), help="Browser to use (default: chrome)")
+@click.option("--headless/--no-headless", default=False, help="Run browser in headless mode")
+@click.option("--stealth/--no-stealth", default=True, help="Enable stealth mode")
+@click.option("--cloudflare-solver/--no-cloudflare-solver", default=True, help="Enable Cloudflare solver")
+@click.option("--visualize-mouse/--no-visualize-mouse", default=None, help="Show visual cursor (default: on when not headless)")
+@click.option("--port", default=9323, help="Server port (default: 9323)")
+@click.option("--foreground/--no-foreground", default=False, help="Run server in foreground (default: background)")
+@click.option("--user-data-dir", default=None, help="Browser user data directory for persistent sessions (preserves logins)")
+def start(browser: str, headless: bool, stealth: bool, cloudflare_solver: bool, visualize_mouse: bool, port: int, foreground: bool, user_data_dir: str):
+    """Start a new browser session."""
+    # Check if already running
+    if is_session_active():
+        output_error("start", "SessionExists", "A browser session is already active. Run 'phantomwright stop' first.")
+        return
+
+    if not foreground:
+        # Start server in background subprocess
+        args = [
+            sys.executable, "-m", "phantomwright.cli.server",
+            "--port", str(port),
+            "--browser", browser,
+        ]
+        if headless:
+            args.append("--headless")
+        if not stealth:
+            args.append("--no-stealth")
+        if not cloudflare_solver:
+            args.append("--no-cloudflare-solver")
+        if visualize_mouse is not None:
+            args.append("--visualize-mouse" if visualize_mouse else "--no-visualize-mouse")
+        if user_data_dir:
+            args.extend(["--user-data-dir", user_data_dir])
+
+        # Use CREATE_NEW_PROCESS_GROUP on Windows, start_new_session on Unix
+        if sys.platform == "win32":
+            subprocess.Popen(
+                args,
+                creationflags=subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.DETACHED_PROCESS,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        else:
+            subprocess.Popen(
+                args,
+                start_new_session=True,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+
+        # Wait for server to start
+        import time
+        from ..client import SessionClient
+        client = SessionClient(port=port)
+        for _ in range(300):  # Wait up to 30 seconds
+            time.sleep(0.1)
+            if client.is_server_running():
+                result = client.get_status()
+                output_success("start", result)
+                return
+
+        output_error("start", "StartupTimeout", "Server did not start within timeout.")
+    else:
+        # Run server in foreground
+        asyncio.run(_start_foreground(browser, headless, stealth, cloudflare_solver, visualize_mouse, port, user_data_dir))
+
+
+async def _start_foreground(browser: str, headless: bool, stealth: bool, cloudflare_solver: bool, visualize_mouse: bool, port: int, user_data_dir: str):
+    """Start server in foreground."""
+    from ..server import run_server
+    await run_server(
+        port=port,
+        browser=browser,
+        headless=headless,
+        stealth=stealth,
+        cloudflare_solver=cloudflare_solver,
+        visualize_mouse=visualize_mouse,
+        user_data_dir=user_data_dir,
+    )
+
+
+@click.command()
+def stop():
+    """Stop the current browser session."""
+    client = get_client()
+
+    if not client.is_server_running():
+        # Check if there's a stale session file
+        stored_session = load_session()
+        if stored_session:
+            clear_session()
+            output_success("stop", {"message": "Cleaned up stale session file."})
+        else:
+            output_error("stop", "NoSession", "No active browser session to stop.")
+        return
+
+    result = client.stop()
+
+    if "error" in result:
+        output_error("stop", result["error"], result["message"])
+    else:
+        output_success("stop", {"message": "Browser session stopped."})

phantomwright-0.2.0/phantomwright/cli/commands/interaction.py

@@ -0,0 +1,46 @@
+"""Interaction commands: click, type."""
+
+import click
+
+from ..client import get_client
+from ..output import output_success, output_error
+
+
+@click.command("click")
+@click.argument("selector")
+@click.option("--simulate/--no-simulate", default=True, help="Use human-like mouse movement (default: on)")
+def click_cmd(selector: str, simulate: bool):
+    """Click an element with human-like behavior."""
+    client = get_client()
+    result = client.click(selector=selector, simulate=simulate)
+
+    if "error" in result:
+        output_error("click", result["error"], result["message"], selector=selector)
+    else:
+        output_success("click", {
+            "selector": selector,
+            "element_count": result["element_count"],
+            "simulated": result["simulated"],
+            "clicked_at": result["clicked_at"],
+        })
+
+
+@click.command("type")
+@click.argument("selector")
+@click.argument("text")
+@click.option("--simulate/--no-simulate", default=True, help="Use human-like typing (default: on)")
+@click.option("--typos/--no-typos", default=False, help="Simulate typing mistakes")
+def type_cmd(selector: str, text: str, simulate: bool, typos: bool):
+    """Type text into an element with human-like timing."""
+    client = get_client()
+    result = client.type_text(selector=selector, text=text, simulate=simulate, typos=typos)
+
+    if "error" in result:
+        output_error("type", result["error"], result["message"], selector=selector)
+    else:
+        output_success("type", {
+            "selector": selector,
+            "text_length": result["text_length"],
+            "simulated": result["simulated"],
+            "typos_enabled": result["typos_enabled"],
+        })

phantomwright-0.2.0/phantomwright/cli/commands/navigation.py

@@ -0,0 +1,70 @@
+"""Navigation commands: navigate, scroll, browse."""
+
+import time
+import click
+
+from ..client import get_client
+from ..output import output_success, output_error
+
+
+@click.command()
+@click.argument("url")
+@click.option("--simulate/--no-simulate", default=True, help="Use human-like navigation behavior (default: on)")
+@click.option("--cool-down/--no-cool-down", default=True, help="Simulate browsing after navigation")
+@click.option("--wait-for", default=None, help="CSS selector to wait for after navigation")
+@click.option("--timeout", default=30000, help="Navigation timeout in milliseconds")
+def navigate(url: str, simulate: bool, cool_down: bool, wait_for: str, timeout: int):
+    """Navigate to a URL with human-like behavior."""
+    client = get_client()
+    start_time = time.time()
+
+    result = client.navigate(
+        url=url,
+        simulate=simulate,
+        cool_down=cool_down,
+        wait_for=wait_for,
+        timeout=timeout,
+    )
+
+    if "error" in result:
+        output_error("navigate", result["error"], result["message"], url=url)
+    else:
+        load_time = int((time.time() - start_time) * 1000)
+        output_success("navigate", {
+            "url": result["url"],
+            "title": result["title"],
+            "simulated": result["simulated"],
+            "load_time_ms": load_time,
+        })
+
+
+@click.command()
+@click.option("--duration", default=2000, help="Scroll duration in milliseconds")
+def scroll(duration: int):
+    """Simulate reading behavior with scrolling."""
+    client = get_client()
+    result = client.scroll(duration=duration)
+
+    if "error" in result:
+        output_error("scroll", result["error"], result["message"])
+    else:
+        output_success("scroll", {
+            "duration_ms": result["duration_ms"],
+            "current_url": result["current_url"],
+        })
+
+
+@click.command()
+@click.option("--duration", default=2000, help="Browse duration in milliseconds")
+def browse(duration: int):
+    """Simulate general browsing behavior."""
+    client = get_client()
+    result = client.browse(duration=duration)
+
+    if "error" in result:
+        output_error("browse", result["error"], result["message"])
+    else:
+        output_success("browse", {
+            "duration_ms": result["duration_ms"],
+            "current_url": result["current_url"],
+        })