allwright 0.0.1__tar.gz

allwright-0.0.1/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: allwright
+Version: 0.0.1
+Summary: High-level Python client for the allwright engine
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: grpcio<2,>=1.74.0
+Requires-Dist: grpcio-tools<2,>=1.74.0
+Requires-Dist: protobuf<7,>=5
+Requires-Dist: PyYAML<7,>=6
+
+# allwright Python client
+
+This folder contains the high-level Python client for the allwright engine.
+
+It loads the shared `proto/engine/v1/engine.proto` contract dynamically at runtime and exposes a browser/page API instead of raw gRPC channel setup.
+
+## Install
+
+```bash
+pip install -e ./python
+```
+
+## Example
+
+```python
+from allwright import firefox
+
+browser = firefox.launch()
+page = browser.page()
+page.goto("https://example.com")
+page.click("h1")
+browser.close()
+```

allwright-0.0.1/README.md

@@ -0,0 +1,23 @@
+# allwright Python client
+
+This folder contains the high-level Python client for the allwright engine.
+
+It loads the shared `proto/engine/v1/engine.proto` contract dynamically at runtime and exposes a browser/page API instead of raw gRPC channel setup.
+
+## Install
+
+```bash
+pip install -e ./python
+```
+
+## Example
+
+```python
+from allwright import firefox
+
+browser = firefox.launch()
+page = browser.page()
+page.goto("https://example.com")
+page.click("h1")
+browser.close()
+```

allwright-0.0.1/allwright/__init__.py

@@ -0,0 +1,69 @@
+from .client import (
+    Browser,
+    BrowserType,
+    ClickResult,
+    CommandOptions,
+    CountResult,
+    ElementResult,
+    FillResult,
+    HighlightOptions,
+    HighlightResult,
+    LaunchOptions,
+    Locator,
+    AllwrightConfig,
+    NavigateResult,
+    Page,
+    PressOptions,
+    PressResult,
+    ResolveConfigOptions,
+    ResolvedConfig,
+    TextResult,
+    WaitForSelectorOptions,
+    WaitForSelectorResult,
+    chromium,
+    find_config_file,
+    firefox,
+    launch_chrome,
+    launch_configured_browser,
+    launch_firefox,
+    load_config_file,
+    ping,
+    resolve_config,
+    set_server_addr,
+    shutdown,
+)
+
+__all__ = [
+    "Browser",
+    "BrowserType",
+    "ClickResult",
+    "CommandOptions",
+    "CountResult",
+    "ElementResult",
+    "FillResult",
+    "HighlightOptions",
+    "HighlightResult",
+    "LaunchOptions",
+    "Locator",
+    "AllwrightConfig",
+    "NavigateResult",
+    "Page",
+    "PressOptions",
+    "PressResult",
+    "ResolveConfigOptions",
+    "ResolvedConfig",
+    "TextResult",
+    "WaitForSelectorOptions",
+    "WaitForSelectorResult",
+    "chromium",
+    "find_config_file",
+    "firefox",
+    "launch_chrome",
+    "launch_configured_browser",
+    "launch_firefox",
+    "load_config_file",
+    "ping",
+    "resolve_config",
+    "set_server_addr",
+    "shutdown",
+]

allwright-0.0.1/allwright/_browser.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import threading
+
+from ._proto import engine_pb2
+from ._types import AllwrightError, CommandOptions, LaunchOptions
+
+
+class BrowserType:
+    def __init__(self, browser_kind: int = engine_pb2.BROWSER_KIND_CHROMIUM) -> None:
+        self._browser_kind = browser_kind
+
+    def launch(self, options: LaunchOptions | None = None) -> Browser:
+        from .client import launch_browser
+
+        return launch_browser(self._browser_kind, options or LaunchOptions())
+
+
+class Browser:
+    def __init__(
+        self,
+        runtime: RuntimeClient,
+        stream: StreamHandle,
+        session_id: str,
+        browser_name: str,
+        launch_note: str,
+        cdp_websocket_url: str,
+        user_data_dir: str,
+        initial_page: Page,
+    ) -> None:
+        self._runtime = runtime
+        self._stream = stream
+        self._lock = threading.Lock()
+        self._closed = False
+        self._pages: dict[str, Page] = {initial_page.session_id: initial_page}
+        self.session_id = session_id
+        self.browser_name = browser_name
+        self.launch_note = launch_note
+        self.cdp_websocket_url = cdp_websocket_url
+        self.user_data_dir = user_data_dir
+        self._initial_page = initial_page
+
+    def page(self) -> Page:
+        return self._initial_page
+
+    def initial_page(self) -> Page:
+        return self._initial_page
+
+    def initial_tab(self) -> Page:
+        return self._initial_page
+
+    def pages(self) -> list[Page]:
+        return list(self._pages.values())
+
+    def new_page(self, options: CommandOptions | None = None) -> Page:
+        from ._page import Page
+        from ._runtime import retry_options
+
+        with self._lock:
+            self._ensure_open()
+            command_options = options or CommandOptions()
+            self._stream.send(
+                engine_pb2.BrowserSessionCommand(
+                    open_tab=engine_pb2.OpenTabCommand(
+                        retry_options=retry_options(command_options.timeout_ms),
+                    ),
+                )
+            )
+
+            while True:
+                event = self._stream.recv("receive browser session event while opening page")
+                match event.WhichOneof("event"):
+                    case "tab_opened":
+                        page = Page(
+                            runtime=self._runtime,
+                            browser_session_id=self.session_id,
+                            session_id=event.tab_opened.tab_session_id,
+                        )
+                        self._pages[page.session_id] = page
+                        return page
+                    case "error":
+                        raise AllwrightError(
+                            f"browser session error while opening page: {event.error.message}"
+                        )
+
+    def new_tab(self, options: CommandOptions | None = None) -> Page:
+        return self.new_page(options)
+
+    def ping(self, message: str = "ping") -> str:
+        with self._lock:
+            self._ensure_open()
+            self._stream.send(
+                engine_pb2.BrowserSessionCommand(
+                    ping=engine_pb2.SessionPingCommand(message=message),
+                )
+            )
+
+            while True:
+                event = self._stream.recv("receive browser session event while pinging browser")
+                match event.WhichOneof("event"):
+                    case "pong":
+                        return event.pong.message
+                    case "error":
+                        raise AllwrightError(
+                            f"browser session error while pinging: {event.error.message}"
+                        )
+
+    def close(self) -> None:
+        with self._lock:
+            if self._closed:
+                return
+
+            self._stream.send(
+                engine_pb2.BrowserSessionCommand(
+                    close=engine_pb2.CloseBrowserSessionCommand(),
+                )
+            )
+
+            while True:
+                event = self._stream.recv("receive browser session event while closing browser")
+                match event.WhichOneof("event"):
+                    case "closed":
+                        self._closed = True
+                        self._stream.close_send()
+                        return
+                    case "error":
+                        raise AllwrightError(
+                            f"browser session error while closing: {event.error.message}"
+                        )
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise AllwrightError(f"browser session {self.session_id} is closed")
+
+
+from ._page import Page
+from ._transport import RuntimeClient, StreamHandle

allwright-0.0.1/allwright/_config.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ._types import (
+    AllwrightConfig,
+    AllwrightError,
+    LaunchOptions,
+    ResolveConfigOptions,
+    ResolvedConfig,
+    RetryConfig,
+)
+
+CONFIG_FILENAMES = (
+    "allwright.config.yaml",
+    "allwright.config.yml",
+    "allwright.config.json",
+    ".allwright/config.yaml",
+    ".allwright/config.yml",
+    ".allwright/config.json",
+)
+
+
+def find_config_file(start_dir: str | Path | None = None) -> Path | None:
+    current_dir = Path(start_dir or Path.cwd()).resolve()
+
+    while True:
+        for filename in CONFIG_FILENAMES:
+            candidate = current_dir / filename
+            if candidate.is_file():
+                return candidate
+
+        if current_dir.parent == current_dir:
+            return None
+        current_dir = current_dir.parent
+
+
+def load_config_file(config_file: str | Path) -> AllwrightConfig:
+    resolved = Path(config_file).resolve()
+    raw = resolved.read_text(encoding="utf-8")
+
+    if resolved.suffix.lower() == ".json":
+        parsed = json.loads(raw)
+    elif resolved.suffix.lower() in {".yaml", ".yml"}:
+        parsed = yaml.safe_load(raw) or {}
+    else:
+        raise AllwrightError(
+            f"unsupported allwright config file extension {resolved.suffix or '<none>'} for {resolved}"
+        )
+
+    if not isinstance(parsed, dict):
+        raise AllwrightError(f"allwright config {resolved} must contain a top-level object")
+
+    validate_config_shape(parsed, resolved)
+    return AllwrightConfig(
+        schema_version=parsed.get("schemaVersion"),
+        server=parsed.get("server"),
+        browser=parsed.get("browser"),
+        expect=retry_config_from_mapping(parsed.get("expect")),
+        suites=parsed.get("suites"),
+    )
+
+
+def resolve_config(options: ResolveConfigOptions | None = None) -> ResolvedConfig:
+    resolved_options = options or ResolveConfigOptions()
+    config_file_path = (
+        Path(resolved_options.config_file).resolve()
+        if resolved_options.config_file
+        else find_config_file(resolved_options.cwd)
+    )
+    file_config = load_config_file(config_file_path) if config_file_path else AllwrightConfig()
+    suite_name = (resolved_options.suite or "").strip() or None
+    suite_config = None
+
+    if suite_name:
+        suite_config = (file_config.suites or {}).get(suite_name)
+        if suite_config is None:
+            source = str(config_file_path) if config_file_path else "the resolved config file"
+            raise AllwrightError(
+                f'allwright config suite "{suite_name}" was not found in {source}'
+            )
+
+    server_addr = first_non_empty(
+        server_addr_from_mapping(suite_config.get("server") if suite_config else None),
+        server_addr_from_mapping(file_config.server),
+    )
+    browser_name = first_non_empty(
+        browser_name_from_mapping(suite_config.get("browser") if suite_config else None),
+        browser_name_from_mapping(file_config.browser),
+    ) or "chromium"
+    browser_binary = first_non_empty(
+        browser_binary_from_mapping(suite_config.get("browser") if suite_config else None),
+        browser_binary_from_mapping(file_config.browser),
+    )
+    launch_options = merge_launch_options(
+        launch_options_from_mapping(file_config.browser),
+        launch_options_from_mapping(suite_config.get("browser") if suite_config else None),
+    )
+    if browser_binary:
+        launch_options.browser_binary = browser_binary
+    expect = merge_retry_config(
+        file_config.expect,
+        retry_config_from_mapping(suite_config.get("expect") if suite_config else None),
+    )
+
+    return ResolvedConfig(
+        config_file_path=config_file_path,
+        suite_name=suite_name,
+        server_addr=server_addr,
+        browser_name=browser_name,
+        browser_binary=browser_binary,
+        launch_options=launch_options,
+        expect=expect,
+    )
+
+
+def validate_config_shape(config: dict[str, Any], source: Path) -> None:
+    schema_version = config.get("schemaVersion")
+    if schema_version is not None and schema_version != 1:
+        raise AllwrightError(
+            f"allwright config {source} has unsupported schemaVersion {schema_version}; expected 1"
+        )
+
+    browser_name = browser_name_from_mapping(config.get("browser"))
+    if browser_name and browser_name not in {"chromium", "firefox"}:
+        raise AllwrightError(
+            f'allwright config {source} has unsupported browser.name "{browser_name}"; use "chromium" or "firefox"'
+        )
+
+
+def browser_name_from_mapping(browser: dict[str, Any] | None) -> str | None:
+    if not isinstance(browser, dict):
+        return None
+    value = browser.get("name")
+    return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+def browser_binary_from_mapping(browser: dict[str, Any] | None) -> str | None:
+    if not isinstance(browser, dict):
+        return None
+    value = browser.get("binary")
+    return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+def server_addr_from_mapping(server: dict[str, Any] | None) -> str | None:
+    if not isinstance(server, dict):
+        return None
+    value = server.get("addr")
+    return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+def launch_options_from_mapping(browser: dict[str, Any] | None) -> LaunchOptions:
+    if not isinstance(browser, dict):
+        return LaunchOptions()
+    launch_options = browser.get("launchOptions")
+    if not isinstance(launch_options, dict):
+        return LaunchOptions()
+    return LaunchOptions(
+        browser_binary=launch_options.get("browserBinary"),
+        timeout_ms=launch_options.get("timeoutMs"),
+    )
+
+
+def retry_config_from_mapping(value: dict[str, Any] | None) -> RetryConfig | None:
+    if not isinstance(value, dict):
+        return None
+    return RetryConfig(
+        timeout_ms=value.get("timeoutMs"),
+        interval_ms=value.get("intervalMs"),
+    )
+
+
+def merge_launch_options(base: LaunchOptions, override: LaunchOptions) -> LaunchOptions:
+    return LaunchOptions(
+        browser_binary=override.browser_binary or base.browser_binary,
+        timeout_ms=override.timeout_ms if override.timeout_ms is not None else base.timeout_ms,
+    )
+
+
+def merge_retry_config(base: RetryConfig | None, override: RetryConfig | None) -> RetryConfig:
+    return RetryConfig(
+        timeout_ms=(
+            override.timeout_ms
+            if override and override.timeout_ms is not None
+            else (base.timeout_ms if base else None)
+        ),
+        interval_ms=(
+            override.interval_ms
+            if override and override.interval_ms is not None
+            else (base.interval_ms if base else None)
+        ),
+    )
+
+
+def first_non_empty(*values: str | None) -> str | None:
+    for value in values:
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None

allwright-0.0.1/allwright/_locator.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ._selectors import chain_selector_for_transport
+from ._types import (
+    ClickResult,
+    CommandOptions,
+    CountResult,
+    ElementResult,
+    FillResult,
+    HighlightOptions,
+    HighlightResult,
+    PressOptions,
+    PressResult,
+    TextResult,
+    WaitForSelectorOptions,
+    WaitForSelectorResult,
+)
+
+if TYPE_CHECKING:
+    from ._page import Page
+
+
+@dataclass(slots=True)
+class Locator:
+    page: Page
+    selector: str
+
+    def locator(self, selector: str) -> Locator:
+        return Locator(page=self.page, selector=chain_selector_for_transport(self.selector, selector))
+
+    def click(self, options: CommandOptions | None = None) -> ClickResult:
+        return self.page.click(self.selector, options)
+
+    def count(self, options: CommandOptions | None = None) -> CountResult:
+        return self.page.count(self.selector, options)
+
+    def highlight(self, options: HighlightOptions | None = None) -> HighlightResult:
+        return self.page.highlight(self.selector, options)
+
+    def focus(self, options: CommandOptions | None = None) -> ElementResult:
+        return self.page.focus(self.selector, options)
+
+    def fill(self, value: str, options: CommandOptions | None = None) -> FillResult:
+        return self.page.fill(self.selector, value, options)
+
+    def hover(self, options: CommandOptions | None = None) -> ElementResult:
+        return self.page.hover(self.selector, options)
+
+    def press(self, key: str, options: PressOptions | None = None) -> PressResult:
+        return self.page.press(self.selector, key, options)
+
+    def text_content(self, options: CommandOptions | None = None) -> TextResult:
+        return self.page.text_content(self.selector, options)
+
+    def inner_text(self, options: CommandOptions | None = None) -> TextResult:
+        return self.page.inner_text(self.selector, options)
+
+    def wait_for(self, options: WaitForSelectorOptions | None = None) -> WaitForSelectorResult:
+        return self.page.wait_for_selector(self.selector, options)