o-browser 0.1.0__py3-none-any.whl

o_browser/__init__.py

@@ -0,0 +1,4 @@
+from .client import BrowserClient
+from .remote import RemoteBrowser
+
+__all__ = ["BrowserClient", "RemoteBrowser"]

o_browser/_mixin.py

@@ -0,0 +1,183 @@
+"""
+PageMixin — Shared browser page interactions.
+
+All methods depend only on self._page / self._context.
+Inherited by BrowserClient (direct) and RemoteBrowser (CDP).
+"""
+
+import asyncio
+import os
+from typing import Any
+
+
+class PageMixin:
+    """Mixin providing navigation, interactions, scrolling, waiting, selectors, and GIF recording."""
+
+    _page: Any
+    _context: Any
+
+    @property
+    def page(self):
+        if not self._page:
+            raise RuntimeError("Browser not started. Use 'async with' or call start() first.")
+        return self._page
+
+    @property
+    def context(self):
+        if not self._context:
+            raise RuntimeError("Browser not started. Use 'async with' or call start() first.")
+        return self._context
+
+    # === Navigation ===
+
+    async def goto(self, url: str, wait_until: str = "domcontentloaded", timeout: int = 30000) -> bool:
+        """Navigate to URL. Returns True if status 200."""
+        try:
+            response = await self.page.goto(url, wait_until=wait_until, timeout=timeout)
+            return response and response.status == 200
+        except Exception:
+            return False
+
+    async def wait(self, seconds: float):
+        """Wait for specified seconds."""
+        await asyncio.sleep(seconds)
+
+    async def get_text(self) -> str:
+        """Get page text content."""
+        return await self.page.evaluate("() => document.body.innerText")
+
+    async def get_html(self) -> str:
+        """Get page HTML."""
+        return await self.page.content()
+
+    async def screenshot(self, path: str, full_page: bool = True) -> str:
+        """Take screenshot and return path."""
+        await self.page.screenshot(path=path, full_page=full_page)
+        return path
+
+    # === Scrolling ===
+
+    async def scroll_to_bottom(self, times: int = 3, delay: float = 2.0) -> None:
+        """Scroll to bottom multiple times to load dynamic content."""
+        for _ in range(times):
+            await self.page.evaluate("window.scrollTo(0, document.body.scrollHeight)")
+            await asyncio.sleep(delay)
+
+    async def scroll_element(self, selector: str, times: int = 3, delay: float = 2.0) -> None:
+        """Scroll inside a specific element (infinite scroll containers)."""
+        for _ in range(times):
+            await self.page.evaluate(f"""
+                const el = document.querySelector('{selector}');
+                if (el) el.scrollTop = el.scrollHeight;
+            """)
+            await asyncio.sleep(delay)
+
+    async def scroll_by(self, y: int):
+        """Scroll page by Y pixels."""
+        await self.page.evaluate(f"window.scrollBy(0, {y})")
+
+    # === Waiting ===
+
+    async def wait_for_content(self, min_length: int = 500, max_attempts: int = 10, delay: float = 2.0) -> bool:
+        """Wait for page content to load (not showing 'Loading...')."""
+        for _ in range(max_attempts):
+            text = await self.get_text()
+            if "Loading" not in text and len(text) > min_length:
+                return True
+            await asyncio.sleep(delay)
+        return False
+
+    async def wait_for_selector(self, selector: str, timeout: int = 30000):
+        """Wait for element to appear."""
+        return await self.page.wait_for_selector(selector, timeout=timeout)
+
+    # === Interactions ===
+
+    async def click(self, selector: str) -> None:
+        """Click element by selector."""
+        await self.page.click(selector)
+
+    async def fill(self, selector: str, value: str) -> None:
+        """Fill input field."""
+        await self.page.fill(selector, value)
+
+    async def type(self, selector: str, text: str, delay: int = 50) -> None:
+        """Type text with realistic delay between keystrokes."""
+        await self.page.type(selector, text, delay=delay)
+
+    async def press(self, key: str) -> None:
+        """Press a key (e.g., 'Enter', 'Tab')."""
+        await self.page.keyboard.press(key)
+
+    # === Selectors ===
+
+    async def query_selector(self, selector: str):
+        """Query single element."""
+        return await self.page.query_selector(selector)
+
+    async def query_selector_all(self, selector: str):
+        """Query all elements matching selector."""
+        return await self.page.query_selector_all(selector)
+
+    async def evaluate(self, expression: str) -> Any:
+        """Evaluate JavaScript expression."""
+        return await self.page.evaluate(expression)
+
+    # === GIF Recording ===
+
+    def _init_recording(self):
+        """Initialize recording state if needed."""
+        if not hasattr(self, '_frames'):
+            self._frames = []
+            self._rec_dir = None
+
+    async def capture_frame(self, duration: float = 0.5, full_page: bool = False):
+        """Capture a screenshot frame for GIF recording."""
+        self._init_recording()
+        if not self._rec_dir:
+            import tempfile
+            self._rec_dir = tempfile.mkdtemp(prefix="browser_gif_")
+
+        frame_path = os.path.join(self._rec_dir, f"frame_{len(self._frames):03d}.png")
+        await self.page.screenshot(path=frame_path, full_page=full_page)
+        self._frames.append((frame_path, int(duration * 100)))
+
+    async def type_animated(self, selector: str, text: str, frame_every: int = 5,
+                            frame_duration: float = 0.15, type_delay: int = 40):
+        """Type text capturing frames periodically for GIF."""
+        await self.page.click(selector)
+        for i, char in enumerate(text):
+            await self.page.keyboard.type(char, delay=type_delay)
+            if (i + 1) % frame_every == 0 or i == len(text) - 1:
+                await self.capture_frame(duration=frame_duration)
+
+    def save_gif(self, output_path: str, resize: str = None, optimize: bool = True) -> str:
+        """Assemble captured frames into an animated GIF using ImageMagick."""
+        import subprocess
+        import shutil
+
+        self._init_recording()
+        if not self._frames:
+            raise RuntimeError("No frames captured. Use capture_frame() first.")
+
+        if not shutil.which("convert"):
+            raise RuntimeError("ImageMagick 'convert' not found. Install with: apt install imagemagick")
+
+        cmd = ["convert"]
+        for path, delay_cs in self._frames:
+            cmd.extend(["-delay", str(delay_cs), path])
+        cmd.extend(["-loop", "0"])
+        if resize:
+            cmd.extend(["-resize", resize])
+        if optimize:
+            cmd.extend(["-layers", "Optimize"])
+        cmd.append(output_path)
+
+        subprocess.run(cmd, check=True)
+
+        if self._rec_dir:
+            shutil.rmtree(self._rec_dir, ignore_errors=True)
+        self._frames = []
+        self._rec_dir = None
+
+        return output_path

o_browser/client.py

@@ -0,0 +1,297 @@
+"""
+BrowserClient — Direct browser automation (launches Chrome locally or connects via CDP).
+
+Usage:
+    # Headless automation
+    async with BrowserClient() as browser:
+        await browser.goto("https://example.com")
+        text = await browser.get_text()
+
+    # Connect to existing Chrome (e.g. launched with --remote-debugging-port=9222)
+    async with BrowserClient(cdp_url="http://127.0.0.1:9222") as browser:
+        await browser.goto("https://example.com")
+        text = await browser.get_text()
+
+    # With recording + proxy
+    async with BrowserClient(record=True, proxy={"server": "http://host:port"}) as browser:
+        await browser.goto("https://example.com")
+    # → recordings/ses_YYYYMMDD_HHMMSS/{network.har, video.webm, state.json}
+
+    # Interactive (human navigates, we record)
+    async with BrowserClient(interactive=True, record=True) as browser:
+        await browser.wait_closed()
+"""
+
+import asyncio
+import os
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, List, Dict, Callable
+
+from ._mixin import PageMixin
+
+
+def _detect_channel() -> str:
+    """Detect best available Chrome channel."""
+    for channel, binary in [
+        ("chrome-beta", "google-chrome-beta"),
+        ("chrome", "google-chrome"),
+    ]:
+        if shutil.which(binary):
+            return channel
+    return "chromium"
+
+
+class BrowserClient(PageMixin):
+    """
+    Async browser client — launches Chrome directly.
+
+    Can be used standalone or inherited by domain-specific clients.
+    """
+
+    def __init__(
+        self,
+        profile_path: Optional[str] = None,
+        headless: bool = True,
+        channel: Optional[str] = None,
+        viewport: tuple[int, int] = (1920, 1080),
+        user_agent: str = None,
+        cookies: List[Dict] = None,
+        locale: str = None,
+        timezone_id: str = None,
+        browser_args: List[str] = None,
+        proxy: Optional[Dict] = None,
+        record: bool = False,
+        record_dir: Optional[str] = None,
+        interactive: bool = False,
+        cdp_url: Optional[str] = None,
+    ):
+        self.cdp_url = cdp_url
+        self.profile_path = Path(profile_path).expanduser() if profile_path else None
+        self.headless = headless if not interactive else False
+        self.channel = channel or os.environ.get("BROWSER_CHANNEL") or _detect_channel()
+        self.viewport = {"width": viewport[0], "height": viewport[1]} if not interactive else None
+        self.user_agent = user_agent
+        self.cookies = cookies or []
+        self.locale = locale
+        self.timezone_id = timezone_id
+        self.browser_args = browser_args or []
+        self.proxy = proxy
+        self.record = record
+        self.record_dir = Path(record_dir) if record_dir else None
+        self.interactive = interactive
+
+        self._playwright = None
+        self._browser = None
+        self._context = None
+        self._page = None
+        self._closed_event: Optional[asyncio.Event] = None
+        self._cdp_owns_browser = False
+
+        self._response_handlers: List[Callable] = []
+
+    async def __aenter__(self):
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+    def _prepare_record_dir(self) -> Path:
+        """Create and return the recording directory."""
+        if self.record_dir:
+            d = self.record_dir
+        else:
+            session_id = f"ses_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+            d = Path("recordings") / session_id
+        d.mkdir(parents=True, exist_ok=True)
+        return d
+
+    def _build_context_options(self) -> dict:
+        """Build shared context options for both persistent and ephemeral modes."""
+        opts = {}
+        if self.viewport:
+            opts["viewport"] = self.viewport
+        if self.user_agent:
+            opts["user_agent"] = self.user_agent
+        if self.locale:
+            opts["locale"] = self.locale
+        if self.timezone_id:
+            opts["timezone_id"] = self.timezone_id
+        if self.proxy:
+            opts["proxy"] = self.proxy
+        if self.record:
+            rec_dir = self._prepare_record_dir()
+            self.record_dir = rec_dir
+            opts["record_har_path"] = str(rec_dir / "network.har")
+            opts["record_har_content"] = "embed"
+            opts["record_video_dir"] = str(rec_dir)
+        return opts
+
+    async def start(self) -> "BrowserClient":
+        """Start browser and return self."""
+        from patchright.async_api import async_playwright
+
+        self._playwright = await async_playwright().start()
+
+        if self.cdp_url:
+            self._browser = await self._playwright.chromium.connect_over_cdp(self.cdp_url)
+            self._cdp_owns_browser = True
+            contexts = self._browser.contexts
+            self._context = contexts[0] if contexts else await self._browser.new_context()
+            self._page = await self._context.new_page()
+        elif self.profile_path:
+            default_args = [
+                "--no-sandbox",
+                "--disable-dev-shm-usage",
+                "--disable-blink-features=AutomationControlled",
+            ]
+            launch_args = list(set(default_args + self.browser_args))
+            ctx_opts = self._build_context_options()
+
+            if not self.profile_path.exists():
+                self.profile_path.mkdir(parents=True, exist_ok=True)
+
+            self._context = await self._playwright.chromium.launch_persistent_context(
+                user_data_dir=str(self.profile_path),
+                headless=self.headless,
+                channel=self.channel,
+                args=launch_args,
+                **ctx_opts,
+            )
+            self._page = self._context.pages[0] if self._context.pages else await self._context.new_page()
+        else:
+            default_args = [
+                "--no-sandbox",
+                "--disable-dev-shm-usage",
+                "--disable-blink-features=AutomationControlled",
+            ]
+            launch_args = list(set(default_args + self.browser_args))
+            ctx_opts = self._build_context_options()
+
+            self._browser = await self._playwright.chromium.launch(
+                headless=self.headless,
+                channel=self.channel,
+                args=launch_args,
+            )
+            self._context = await self._browser.new_context(**ctx_opts)
+            self._page = await self._context.new_page()
+
+        if self.cookies:
+            await self.add_cookies(self.cookies)
+
+        if self._response_handlers:
+            self._page.on("response", self._on_response)
+
+        # Track browser close for interactive mode
+        if self.interactive:
+            self._closed_event = asyncio.Event()
+            self._setup_close_detection()
+
+        return self
+
+    def _setup_close_detection(self):
+        """Detect when user closes browser (all pages closed or browser disconnected)."""
+        def on_page_close():
+            # Check if any pages remain
+            try:
+                if not self._context.pages:
+                    self._closed_event.set()
+            except Exception:
+                self._closed_event.set()
+
+        # Watch existing pages
+        for p in self._context.pages:
+            p.on("close", lambda: on_page_close())
+
+        # Watch new pages too
+        self._context.on("page", lambda page: page.on("close", lambda: on_page_close()))
+
+        # Browser disconnect (persistent context)
+        self._context.on("close", lambda: self._closed_event.set())
+
+        # Browser disconnect (ephemeral)
+        if self._browser:
+            self._browser.on("disconnected", lambda: self._closed_event.set())
+
+    async def wait_closed(self):
+        """Wait for the browser to be closed by the user (interactive mode)."""
+        if not self._closed_event:
+            self._closed_event = asyncio.Event()
+            self._setup_close_detection()
+        await self._closed_event.wait()
+
+    async def close(self):
+        """Close browser and cleanup. Saves recordings if enabled."""
+        if self.record and self._context:
+            try:
+                state_path = self.record_dir / "state.json"
+                await self._context.storage_state(path=str(state_path))
+            except Exception:
+                pass
+
+        if self._cdp_owns_browser:
+            # CDP mode: only close pages we opened, don't kill the browser
+            if self._page:
+                try:
+                    await self._page.close()
+                except Exception:
+                    pass
+        else:
+            if self._context:
+                await self._context.close()
+            if self._browser:
+                await self._browser.close()
+
+        if self._playwright:
+            await self._playwright.stop()
+        if self.record and self.record_dir:
+            print(f"Recordings saved: {self.record_dir}")
+
+    # === Cookie Management ===
+
+    async def add_cookies(self, cookies: List[Dict]):
+        """Add cookies to browser context."""
+        formatted = []
+        for cookie in cookies:
+            c = {
+                "name": cookie["name"],
+                "value": cookie["value"],
+                "domain": cookie.get("domain", ""),
+                "path": cookie.get("path", "/"),
+            }
+            if "httpOnly" in cookie:
+                c["httpOnly"] = cookie["httpOnly"]
+            if "secure" in cookie:
+                c["secure"] = cookie["secure"]
+            if "sameSite" in cookie:
+                c["sameSite"] = cookie["sameSite"]
+            formatted.append(c)
+
+        await self._context.add_cookies(formatted)
+
+    async def get_cookies(self) -> List[Dict]:
+        """Get all cookies from context."""
+        if not self._context:
+            return []
+        return await self._context.cookies()
+
+    # === Response Interception ===
+
+    def on_response(self, handler: Callable):
+        """Register response handler for intercepting network responses."""
+        self._response_handlers.append(handler)
+        if self._page:
+            self._page.on("response", self._on_response)
+
+    async def _on_response(self, response):
+        """Internal response handler dispatcher."""
+        for handler in self._response_handlers:
+            try:
+                if asyncio.iscoroutinefunction(handler):
+                    await handler(response)
+                else:
+                    handler(response)
+            except Exception:
+                pass

o_browser/remote.py

@@ -0,0 +1,88 @@
+"""
+RemoteBrowser — Connect to a running browser service via CDP.
+
+Usage:
+    async with RemoteBrowser("http://host:8080") as browser:
+        await browser.goto("https://example.com")
+        text = await browser.get_text()
+"""
+
+import re
+from typing import Optional
+
+from ._mixin import PageMixin
+
+
+class RemoteBrowser(PageMixin):
+    """
+    Connects to a remote Chrome instance via CDP WebSocket.
+
+    Does NOT launch or kill the browser — only connects/disconnects.
+    """
+
+    def __init__(self, endpoint: str):
+        """
+        Args:
+            endpoint: HTTP base URL (http://host:8080) or direct WS URL (ws://host:9222/devtools/...)
+        """
+        self.endpoint = endpoint
+        self._playwright = None
+        self._browser = None
+        self._context = None
+        self._page = None
+
+    async def __aenter__(self):
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+    async def _discover_ws_url(self) -> str:
+        """Auto-discover WebSocket URL from HTTP endpoint."""
+        import urllib.request
+        import json
+
+        # Strip trailing slash
+        base = self.endpoint.rstrip("/")
+
+        # Try /api/sessions/current first (o-browser service)
+        try:
+            with urllib.request.urlopen(f"{base}/api/sessions/current", timeout=5) as resp:
+                session = json.loads(resp.read())
+                ws_url = session.get("cdp", {}).get("ws_url")
+                if ws_url:
+                    return ws_url
+        except Exception:
+            pass
+
+        # Fallback: direct CDP /json/version
+        cdp_base = re.sub(r":\d+", ":9222", base)
+        with urllib.request.urlopen(f"{cdp_base}/json/version", timeout=5) as resp:
+            data = json.loads(resp.read())
+            return data["webSocketDebuggerUrl"]
+
+    async def start(self) -> "RemoteBrowser":
+        """Connect to remote browser."""
+        from patchright.async_api import async_playwright
+
+        self._playwright = await async_playwright().start()
+
+        if self.endpoint.startswith("ws://") or self.endpoint.startswith("wss://"):
+            ws_url = self.endpoint
+        else:
+            ws_url = await self._discover_ws_url()
+
+        self._browser = await self._playwright.chromium.connect_over_cdp(ws_url)
+        contexts = self._browser.contexts
+        self._context = contexts[0] if contexts else await self._browser.new_context()
+        self._page = self._context.pages[0] if self._context.pages else await self._context.new_page()
+
+        return self
+
+    async def close(self):
+        """Disconnect (does NOT kill the remote browser)."""
+        if self._browser:
+            await self._browser.close()
+        if self._playwright:
+            await self._playwright.stop()

o_browser-0.1.0.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: o-browser
+Version: 0.1.0
+Summary: Browser automation client — local Chrome via Patchright or remote via CDP
+Author: Alexis Laporte
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: patchright>=0.1.0

o_browser-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+o_browser/__init__.py,sha256=nPx521wxJs0bgIQc4MGXfo0TllBmVDy50wPgAo8bmIE,114
+o_browser/_mixin.py,sha256=1vfVaxfyES4dJvlYO0DTOoAJJPKz88XVDpAOVJckxf8,6695
+o_browser/client.py,sha256=HJcdilnpz7K6B-c17dFO2Olgy45_-K9lRZAfDaXvgB4,10550
+o_browser/remote.py,sha256=s4gdcKOi2tLn3ozfhoZhJoeLMOwOLgXEHbt0mXkioC8,2817
+o_browser-0.1.0.dist-info/METADATA,sha256=qbBKWCF9XU0Hcw4KHb3jYtbETbImpOh4DDJPSWNFNI4,242
+o_browser-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+o_browser-0.1.0.dist-info/RECORD,,

o_browser-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any