browsix 1.0.0__py3-none-any.whl

browsix/actions/dom.py

@@ -0,0 +1,70 @@
+"""DOM action for element inspection and manipulation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.config import DOMParams
+
+
+class DOMAction(BaseAction[DOMParams, Any]):
+    """Action for DOM operations.
+
+    Supports get (outer/inner HTML), query (single/all), attr get/set/remove,
+    remove, focus, and scroll.
+    """
+
+    async def execute(self, backend: AbstractBackend) -> Any:
+        """Execute the DOM action.
+
+        Args:
+            backend: The browser backend to use.
+
+        Returns:
+            str for "get" and "attr" actions, dict/list for "query",
+            None for set/remove/focus/scroll.
+        """
+        params = self.params
+        if params.url:
+            await backend.navigate(params.url, params.wait)
+
+        if params.action == "get":
+            return await backend.dom_get(params.selector, outer=params.outer)
+
+        if params.action == "query":
+            return await backend.dom_query(params.selector, all=params.all)
+
+        if params.action == "attr":
+            if params.value is not None and params.attribute:
+                await backend.dom_set_attr(
+                    params.selector, params.attribute, params.value
+                )
+                return None
+            if params.attribute:
+                return await backend.dom_get_attr(params.selector, params.attribute)
+            return None
+
+        if params.action == "remove_attr":
+            if params.attribute:
+                await backend.dom_remove_attr(params.selector, params.attribute)
+            return None
+
+        if params.action == "remove":
+            await backend.dom_remove(params.selector)
+            return None
+
+        if params.action == "focus":
+            await backend.dom_focus(params.selector)
+            return None
+
+        if params.action == "scroll":
+            await backend.dom_scroll(
+                selector=params.selector or None,
+                x=int(params.value or 0),
+                y=int(params.attribute or 0) if params.attribute else 0,
+            )
+            return None
+
+        return None

browsix/actions/dom_snapshot.py

@@ -0,0 +1,45 @@
+"""DOM snapshot action for capturing raw DOM snapshots."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.config import BrowserOptions, WaitStrategy
+
+
+@dataclass
+class DOMSnapshotParams:
+    """Parameters for DOM snapshot operations.
+
+    Attributes:
+        url: URL to navigate to before capturing snapshot.
+        wait: Wait strategy after navigation.
+        browser: Browser launch options.
+    """
+
+    url: str = ""
+    wait: WaitStrategy = field(default_factory=WaitStrategy)
+    browser: BrowserOptions = field(default_factory=BrowserOptions)
+
+
+class DOMSnapshotAction(BaseAction[DOMSnapshotParams, dict[str, Any]]):
+    """Action for capturing a DOM snapshot of a web page."""
+
+    async def execute(self, backend: AbstractBackend) -> dict[str, Any]:
+        """Execute the DOM snapshot action on the backend.
+
+        Args:
+            backend: The browser backend to use.
+
+        Returns:
+            Dict containing the raw DOM snapshot.
+        """
+        await backend.launch(self.params.browser)
+        try:
+            await backend.navigate(self.params.url, self.params.wait)
+            return await backend.dom_snapshot()
+        finally:
+            await backend.close()

browsix/actions/download.py

@@ -0,0 +1,38 @@
+"""Download action for intercepting file downloads."""
+
+from __future__ import annotations
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.config import BrowserOptions, WaitStrategy
+
+
+class DownloadAction(BaseAction[str, bytes]):
+    """Action for intercepting file downloads."""
+
+    def __init__(
+        self,
+        params: str,
+        url: str = "",
+        wait: WaitStrategy | None = None,
+    ) -> None:
+        self.params = params
+        self._url = url
+        self._wait = wait or WaitStrategy(strategy="load")
+
+    async def execute(self, backend: AbstractBackend) -> bytes:
+        """Execute the download interception on the backend.
+
+        Args:
+            backend: The browser backend to use.
+
+        Returns:
+            Downloaded file bytes.
+        """
+        await backend.launch(BrowserOptions())
+        try:
+            if self._url:
+                await backend.navigate(self._url, self._wait)
+            return await backend.intercept_download(self.params)
+        finally:
+            await backend.close()

browsix/actions/emulation.py

@@ -0,0 +1,45 @@
+"""Emulation action for device, viewport, geolocation, timezone, and dark mode."""
+
+from __future__ import annotations
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.config import EmulationParams
+
+
+class EmulationAction(BaseAction[EmulationParams, None]):
+    """Action for browser emulation operations.
+
+    Supports device emulation, viewport override, geolocation override,
+    timezone override, and dark mode emulation.
+    """
+
+    async def execute(self, backend: AbstractBackend) -> None:
+        """Execute the emulation action on the backend.
+
+        Args:
+            backend: The backend to execute the action on.
+        """
+        params = self.params
+        if params.action == "device":
+            if params.device is None:
+                raise ValueError("device is required for 'device' action")
+            await backend.emulate_device(params.device)
+        elif params.action == "viewport":
+            await backend.set_viewport(
+                params.width,
+                params.height,
+                params.device_scale_factor,
+            )
+        elif params.action == "geolocation":
+            await backend.set_geolocation(
+                params.latitude,
+                params.longitude,
+                params.accuracy,
+            )
+        elif params.action == "timezone":
+            await backend.set_timezone(params.timezone)
+        elif params.action == "dark_mode":
+            await backend.set_dark_mode(params.dark_mode)
+        else:
+            raise ValueError(f"Unknown emulation action: {params.action}")

browsix/actions/eval.py

@@ -0,0 +1,36 @@
+"""Eval action for executing JavaScript expressions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.config import EvalParams
+
+
+class EvalAction(BaseAction[EvalParams, Any]):
+    """Action for evaluating a JavaScript expression on a web page.
+
+    Navigates to the URL in params, then evaluates the expression.
+    Supports @file syntax to read expression from a file.
+    """
+
+    async def execute(self, backend: AbstractBackend) -> Any:
+        """Execute the eval action.
+
+        Args:
+            backend: The browser backend to use.
+
+        Returns:
+            The JavaScript evaluation result.
+        """
+        params = self.params
+        await backend.navigate(params.url, params.wait)
+
+        expression = params.expression
+        if params.file:
+            expression = Path(params.file).read_text(encoding="utf-8")  # noqa: ASYNC240
+
+        return await backend.eval(expression, await_promise=params.await_promise)

browsix/actions/har.py

@@ -0,0 +1,27 @@
+"""HAR action for capturing network traffic as HAR 1.2."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.config import HarParams
+
+
+class HARAction(BaseAction[HarParams, dict[str, Any]]):
+    """Action for capturing HAR data.
+
+    Navigates to a URL, captures network traffic, and returns a HAR 1.2 dict.
+    """
+
+    async def execute(self, backend: AbstractBackend) -> dict[str, Any]:
+        """Execute the HAR capture action.
+
+        Args:
+            backend: The browser backend to use.
+
+        Returns:
+            HAR 1.2 compliant dict with log.entries.
+        """
+        return await backend.capture_har(self.params)

browsix/actions/input.py

@@ -0,0 +1,62 @@
+"""Input action for browser interactions (click, type, fill, select, hover, key, drag, tap)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.config import InputParams
+
+
+class InputAction(BaseAction[InputParams, Any]):
+    """Action for performing input interactions on a web page."""
+
+    async def execute(self, backend: AbstractBackend) -> Any:
+        """Execute the input action on the backend.
+
+        Args:
+            backend: The browser backend to use.
+
+        Returns:
+            None for most actions; the result of the interaction.
+        """
+        await backend.launch(self.params.browser)
+        try:
+            await backend.navigate(self.params.url, self.params.wait)
+            action = self.params.action
+            if action == "click":
+                await backend.click(
+                    self.params.selector,
+                    button=self.params.button,
+                    click_count=self.params.click_count,
+                )
+            elif action == "type":
+                await backend.type_text(
+                    self.params.selector,
+                    self.params.text or "",
+                    delay=self.params.delay,
+                )
+            elif action == "fill":
+                await backend.fill(
+                    self.params.selector, self.params.value or ""
+                )
+            elif action == "select":
+                await backend.select_option(
+                    self.params.selector, self.params.value or ""
+                )
+            elif action == "hover":
+                await backend.hover(self.params.selector)
+            elif action == "key":
+                await backend.key_press(self.params.key or "Enter")
+            elif action == "drag":
+                await backend.drag(
+                    self.params.source or "", self.params.target or ""
+                )
+            elif action == "tap":
+                await backend.tap(self.params.selector)
+            else:
+                raise ValueError(f"Unknown input action: {action}")
+        finally:
+            await backend.close()
+        return None

browsix/actions/media.py

@@ -0,0 +1,62 @@
+"""Media action for listing media players and messages (experimental)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.config import BrowserOptions, WaitStrategy
+
+
+@dataclass
+class MediaParams:
+    """Parameters for Media operations.
+
+    Attributes:
+        url: URL to navigate to before Media operations.
+        action: Media action — "list", "messages".
+        player_id: Media player ID for "messages" action.
+        wait: Wait strategy after navigation.
+        browser: Browser launch options.
+    """
+
+    url: str = ""
+    action: str = "list"
+    player_id: str | None = None
+    wait: WaitStrategy = field(default_factory=WaitStrategy)
+    browser: BrowserOptions = field(default_factory=BrowserOptions)
+
+
+class MediaAction(BaseAction[MediaParams, Any]):
+    """Action for Media operations (experimental)."""
+
+    async def execute(self, backend: AbstractBackend) -> Any:
+        """Execute the Media action on the backend.
+
+        Args:
+            backend: An AbstractBackend instance.
+
+        Returns:
+            Result of the Media operation.
+        """
+        try:
+            await backend.launch(self.params.browser)
+            if self.params.url:
+                await backend.navigate(self.params.url, self.params.wait)
+
+            action = self.params.action
+
+            if action == "list":
+                return await backend.media_get_players()
+
+            if action == "messages":
+                if not self.params.player_id:
+                    raise ValueError("player_id is required for messages action")
+                return await backend.media_get_messages(self.params.player_id)
+
+            raise ValueError(f"Unknown Media action: {action}")
+
+        finally:
+            await backend.close()

browsix/actions/multi.py

@@ -0,0 +1,29 @@
+"""Multi-action: parse YAML and execute multiple actions on a single backend."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.multi import execute_actions, parse_yaml
+
+
+class MultiAction(BaseAction[Path, list[Any]]):
+    """Action that parses a YAML config and executes multiple actions sequentially.
+
+    Reuses a single backend instance for all actions.
+    """
+
+    async def execute(self, backend: AbstractBackend) -> list[Any]:
+        """Parse the YAML config and execute all actions on the backend.
+
+        Args:
+            backend: An already-launched AbstractBackend instance.
+
+        Returns:
+            List of results from each action.
+        """
+        actions = parse_yaml(self.params)
+        return await execute_actions(actions, backend)

browsix/actions/navigate.py

@@ -0,0 +1,98 @@
+"""Navigation actions for back, forward, reload, stop, and wait."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.config import WaitStrategy
+
+
+@dataclass
+class NavigateParams:
+    """Parameters for navigation actions.
+
+    Attributes:
+        url: URL to navigate to (for navigate action).
+        wait: Wait strategy after navigation.
+    """
+
+    url: str = ""
+    wait: WaitStrategy | None = None
+
+
+class NavigateAction(BaseAction[NavigateParams, None]):
+    """Action for navigating to a URL."""
+
+    async def execute(self, backend: AbstractBackend) -> None:
+        """Execute the navigate action.
+
+        Args:
+            backend: The browser backend to use.
+        """
+        params = self.params
+        await backend.navigate(params.url, params.wait)
+
+
+class BackAction(BaseAction[None, None]):
+    """Action for navigating back in history."""
+
+    async def execute(self, backend: AbstractBackend) -> None:
+        """Execute the back action.
+
+        Args:
+            backend: The browser backend to use.
+        """
+        await backend.go_back()
+
+
+class ForwardAction(BaseAction[None, None]):
+    """Action for navigating forward in history."""
+
+    async def execute(self, backend: AbstractBackend) -> None:
+        """Execute the forward action.
+
+        Args:
+            backend: The browser backend to use.
+        """
+        await backend.go_forward()
+
+
+class ReloadAction(BaseAction[bool, None]):
+    """Action for reloading the current page.
+
+    Params is a bool indicating whether to ignore cache.
+    """
+
+    async def execute(self, backend: AbstractBackend) -> None:
+        """Execute the reload action.
+
+        Args:
+            backend: The browser backend to use.
+        """
+        await backend.reload(ignore_cache=self.params)
+
+
+class StopAction(BaseAction[None, None]):
+    """Action for stopping all pending navigations."""
+
+    async def execute(self, backend: AbstractBackend) -> None:
+        """Execute the stop action.
+
+        Args:
+            backend: The browser backend to use.
+        """
+        await backend.stop_loading()
+
+
+class WaitAction(BaseAction[WaitStrategy, None]):
+    """Action for waiting for a condition."""
+
+    async def execute(self, backend: AbstractBackend) -> None:
+        """Execute the wait action.
+
+        Args:
+            backend: The browser backend to use.
+        """
+        await backend.wait_for(self.params)

browsix/actions/network.py

@@ -0,0 +1,70 @@
+"""Network action for cookies, headers, and user-agent management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.config import NetworkParams
+
+
+class NetworkAction(BaseAction[NetworkParams, Any]):
+    """Action for network operations.
+
+    Supports cookies get/set/delete/clear, headers, and user-agent override.
+    """
+
+    async def execute(self, backend: AbstractBackend) -> Any:
+        """Execute the network action.
+
+        Args:
+            backend: The browser backend to use.
+
+        Returns:
+            List of cookies for "cookies_get", None for other actions.
+        """
+        params = self.params
+
+        if params.action == "cookies_get":
+            return await backend.get_cookies()
+
+        if params.action == "cookies_set":
+            if params.cookie:
+                await backend.set_cookie(params.cookie)
+            elif params.cookies:
+                from browsix.config import CookieParams
+
+                for cookie_dict in params.cookies:
+                    cookie = CookieParams(
+                        name=str(cookie_dict.get("name", "")),
+                        value=str(cookie_dict.get("value", "")),
+                        domain=str(cookie_dict.get("domain", "")),
+                        path=str(cookie_dict.get("path", "/")),
+                        secure=bool(cookie_dict.get("secure", True)),
+                        http_only=bool(cookie_dict.get("http_only", False)),
+                        same_site=str(cookie_dict.get("same_site", "Lax")),
+                    )
+                    await backend.set_cookie(cookie)
+            return None
+
+        if params.action == "cookies_delete":
+            if params.name and params.domain:
+                await backend.delete_cookie(params.name, params.domain)
+            return None
+
+        if params.action == "cookies_clear":
+            await backend.clear_cookies()
+            return None
+
+        if params.action == "headers":
+            if params.headers:
+                await backend.set_headers(params.headers)
+            return None
+
+        if params.action == "user_agent":
+            if params.user_agent:
+                await backend.set_user_agent(params.user_agent)
+            return None
+
+        return None

browsix/actions/overlay.py

@@ -0,0 +1,61 @@
+"""Overlay action for highlighting elements and clearing highlights."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.config import BrowserOptions, WaitStrategy
+
+
+@dataclass
+class OverlayParams:
+    """Parameters for overlay operations.
+
+    Attributes:
+        url: URL to navigate to before overlay.
+        selector: CSS selector for the element to highlight.
+        color: RGBA color string for the highlight overlay.
+        action: Overlay action — "highlight" or "clear".
+        wait: Wait strategy after navigation.
+        browser: Browser launch options.
+    """
+
+    url: str = ""
+    selector: str | None = None
+    color: str = "rgba(255,0,0,0.5)"
+    action: str = "highlight"
+    wait: WaitStrategy = field(default_factory=WaitStrategy)
+    browser: BrowserOptions = field(default_factory=BrowserOptions)
+
+
+class OverlayAction(BaseAction[OverlayParams, None]):
+    """Action for overlay highlight and clear operations."""
+
+    async def execute(self, backend: AbstractBackend) -> None:
+        """Execute the overlay action on the backend.
+
+        Args:
+            backend: The browser backend to use.
+
+        Raises:
+            ValueError: If the action is not recognized or selector is missing.
+        """
+        await backend.launch(self.params.browser)
+        try:
+            await backend.navigate(self.params.url, self.params.wait)
+            await self._run_action(backend)
+        finally:
+            await backend.close()
+
+    async def _run_action(self, backend: AbstractBackend) -> None:
+        action = self.params.action
+        if action == "highlight":
+            if not self.params.selector:
+                raise ValueError("selector is required for highlight action")
+            await backend.overlay_highlight(self.params.selector, self.params.color)
+        elif action == "clear":
+            await backend.overlay_clear()
+        else:
+            raise ValueError(f"Unknown overlay action: {action}")

browsix/actions/pdf.py

@@ -0,0 +1,32 @@
+"""PDF action for generating page PDFs."""
+
+from __future__ import annotations
+
+from browsix.actions.base import BaseAction
+from browsix.backend.base import AbstractBackend
+from browsix.config import PDFParams
+
+
+class PDFAction(BaseAction[PDFParams, bytes]):
+    """Action for generating a PDF of a web page.
+
+    Navigates to the URL in params, optionally executes JS, and generates
+    a PDF.
+    """
+
+    async def execute(self, backend: AbstractBackend) -> bytes:
+        """Execute the PDF action.
+
+        Args:
+            backend: The browser backend to use.
+
+        Returns:
+            PDF bytes.
+        """
+        params = self.params
+        await backend.navigate(params.url, params.wait)
+
+        if params.js:
+            await backend.eval(params.js, await_promise=True)
+
+        return await backend.pdf(params)