browserwright 0.6.2__py3-none-any.whl

browserwright/multitask.py

@@ -0,0 +1,131 @@
+"""Multi-task fan-out (v0.3).
+
+Runs N tasks concurrently. Each one gets its own ``Session`` (and therefore
+its own ws to the daemon, its own sessionId namespace, its own
+``current_target_id``). The daemon v0.3 multi-client mux serialises traffic
+into the single upstream Chrome ws; from Skill's point of view the tasks
+are truly independent — `new_tab()` in task A doesn't yank the tab task B
+is operating on.
+
+This module is intentionally small. The hard work was done in #55 (the
+``ContextVar``-backed ``with_session`` machinery). Here we just iterate.
+
+Concurrency model
+-----------------
+Primitives are sync. The CDP transport is thread-safe (single ``send`` lock).
+So we use a ``ThreadPoolExecutor`` rather than asyncio:
+
+  - Each worker thread enters ``with_session(isolated_session())`` and runs the task.
+  - Sessions are independent ``ContextVar`` slots (#55 covers thread isolation).
+  - Daemon assigns each ws its own client id, so per-thread sessionIds don't
+    collide on the wire either.
+
+Layer 3 (cron / scheduler) shells out to either ``browserwright task ...``
+one-at-a-time or — for bursty work — calls this helper from Python::
+
+    from browserwright.multitask import run_tasks_concurrent
+    rows = run_tasks_concurrent([
+        ("ycombinator.com", "front_page", {"limit": 10}),
+        ("wikipedia.org",         "lookup",     {"title": "Python"}),
+    ], max_workers=4)
+"""
+from __future__ import annotations
+
+import concurrent.futures
+from typing import Any, Callable, Iterable, Optional
+
+from .errors import BrowserwrightError
+from .session import isolated_session, with_session
+from .task_runner import run_task
+
+
+TaskSpec = tuple[str, str, dict]   # (site, name, kwargs)
+
+
+class TaskResult(dict):
+    """Single fan-out result. Acts as a dict for JSON friendliness::
+
+        {"site": "...", "name": "...", "ok": True/False,
+         "value": <return>,             # only when ok
+         "error_type": "ClassName",     # only when not ok
+         "error_msg": "...",            # only when not ok
+         "elapsed_sec": float}
+    """
+
+
+def _run_one(spec: TaskSpec) -> TaskResult:
+    """Worker: build a fresh ``Session``, push it onto the ContextVar, run.
+
+    Each worker owns its CDP transport. We close it on exit so the daemon's
+    client slot is freed promptly. Daemon v0.3 doesn't enforce a single-client
+    cap, but releasing eagerly still helps the daemon's idle policy + uiState
+    accounting stay accurate.
+    """
+    import time
+    site, name, kwargs = spec
+    t0 = time.monotonic()
+    sess = isolated_session()
+    try:
+        with with_session(sess):
+            value = run_task(site, name, **kwargs)
+    except BrowserwrightError as e:
+        return TaskResult(
+            site=site, name=name, ok=False,
+            error_type=type(e).__name__, error_msg=str(e),
+            elapsed_sec=round(time.monotonic() - t0, 3),
+        )
+    except Exception as e:  # noqa: BLE001 — agent-facing catch-all
+        return TaskResult(
+            site=site, name=name, ok=False,
+            error_type=type(e).__name__, error_msg=str(e),
+            elapsed_sec=round(time.monotonic() - t0, 3),
+        )
+    finally:
+        sess.close()
+    return TaskResult(
+        site=site, name=name, ok=True, value=value,
+        elapsed_sec=round(time.monotonic() - t0, 3),
+    )
+
+
+def run_tasks_concurrent(specs: Iterable[TaskSpec], *,
+                         max_workers: int = 4,
+                         warm_upstream: bool = False) -> list[TaskResult]:
+    """Run every (site, name, kwargs) tuple concurrently. Returns one
+    ``TaskResult`` per spec, in input order.
+
+    Exceptions never propagate out — each failure becomes an ``ok=False``
+    result. Layer 3 examines results and decides what to retry/log.
+
+    .. deprecated:: 0.3.0
+       The ``warm_upstream`` keyword is a no-op since the daemon shipped
+       the #76 pre-open buffer fix. The earlier Skill-side workaround
+       (sync probe on the main session before spawning workers) is no
+       longer needed: the daemon now per-client-buffers frames received
+       while ``upstream phase != CONNECTED`` and replays them after the
+       upstream ws opens (``PRE_OPEN_BUFFER_LIMIT=100``; overflow surfaces
+       as JSON-RPC error ``-32603``). The keyword is accepted for source
+       compatibility but has no effect; remove the argument from your
+       call site.
+
+       **Removal target: v0.6** (REVIEW.md F-17). After v0.6 ships the
+       keyword will be removed from the signature and any caller still
+       passing it will hit a ``TypeError``.
+
+    Notes
+    -----
+    * ``max_workers`` defaults to 4. Daemon v0.3 multi-client supports more
+      but Chrome itself gets stressed past ~8 concurrent navigations.
+    * The order of results matches the order of inputs (not completion
+      order) — predictable for the caller's downstream pipeline.
+    """
+    _ = warm_upstream  # accepted-but-ignored; see deprecation note above.
+    specs = list(specs)
+    if not specs:
+        return []
+    with concurrent.futures.ThreadPoolExecutor(
+        max_workers=min(max_workers, len(specs)),
+        thread_name_prefix="bs-task",
+    ) as pool:
+        futures = [pool.submit(_run_one, s) for s in specs]
+        return [f.result() for f in futures]

browserwright/output_schema.py

@@ -0,0 +1,99 @@
+"""Minimal JSON-Schema-subset validator for task ``OUTPUT_SCHEMA`` (v0.2).
+
+We don't pull in ``jsonschema`` — task schemas in practice cover one of
+five shapes: list-of-dicts, dict, scalar, optional/nullable, and unions.
+The validator handles those plus enough
+plumbing for nested ``items`` / ``properties``. If a task needs a richer
+schema it can ``pip install jsonschema`` and write its own ``validate()``;
+we don't paint into a corner.
+
+Supported keywords:
+  - ``type``: ``"object" | "array" | "string" | "integer" | "number" |
+              "boolean" | "null"`` (or a list for union types)
+  - ``properties``: object → property-name → sub-schema
+  - ``required``: list of required property names
+  - ``additionalProperties``: bool (default True). When False, extra keys
+    cause a validation error.
+  - ``items``: array → sub-schema applied to each element
+  - ``enum``: list of allowed scalar values
+  - ``nullable``: bool — convenience, equivalent to ``type: [..., "null"]``
+
+Failures raise ``BrowserwrightError`` with a path-qualified message so the
+agent can tell the user *which* field failed.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .errors import BrowserwrightError
+
+
+_TYPE_MAP = {
+    "object": dict,
+    "array": list,
+    "string": str,
+    "integer": int,
+    "number": (int, float),
+    "boolean": bool,
+    "null": type(None),
+}
+
+
+class OutputSchemaError(BrowserwrightError):
+    exit_code = 3
+
+    def __init__(self, site: str, task: str, path: str, msg: str):
+        self.site, self.task, self.path, self.msg_short = site, task, path, msg
+        super().__init__(f"OUTPUT_SCHEMA mismatch in {site}/{task} at {path}: {msg}")
+
+
+def validate(value: Any, schema: dict, *, site: str = "", task: str = "") -> None:
+    """Raise ``OutputSchemaError`` on shape mismatch. Returns None on success."""
+    _check(value, schema, path="$", site=site, task=task)
+
+
+def _types_for(schema: dict) -> list:
+    t = schema.get("type")
+    if isinstance(t, list):
+        out = [_TYPE_MAP[k] for k in t if k in _TYPE_MAP]
+    elif isinstance(t, str):
+        out = [_TYPE_MAP[t]] if t in _TYPE_MAP else []
+    else:
+        out = []
+    if schema.get("nullable"):
+        out.append(type(None))
+    return out
+
+
+def _check(value, schema, *, path, site, task):
+    if not isinstance(schema, dict):
+        return
+    types = _types_for(schema)
+    if types:
+        # bool is a subclass of int in Python; treat them as distinct.
+        if int in types and bool not in types and isinstance(value, bool):
+            raise OutputSchemaError(site, task, path, f"expected {types}, got bool")
+        if not isinstance(value, tuple(types)):
+            raise OutputSchemaError(
+                site, task, path,
+                f"expected one of {[t.__name__ if isinstance(t, type) else t for t in types]}, "
+                f"got {type(value).__name__}",
+            )
+    if "enum" in schema and value not in schema["enum"]:
+        raise OutputSchemaError(site, task, path,
+                                f"value {value!r} not in enum {schema['enum']!r}")
+    if isinstance(value, dict) and "properties" in schema:
+        props = schema.get("properties", {})
+        for key in schema.get("required", []):
+            if key not in value:
+                raise OutputSchemaError(site, task, f"{path}.{key}", "missing required key")
+        for k, v in value.items():
+            sub = props.get(k)
+            if sub is not None:
+                _check(v, sub, path=f"{path}.{k}", site=site, task=task)
+            elif schema.get("additionalProperties") is False:
+                raise OutputSchemaError(site, task, f"{path}.{k}", "unexpected key")
+    if isinstance(value, list) and "items" in schema:
+        items_schema = schema["items"]
+        for i, item in enumerate(value):
+            _check(item, items_schema, path=f"{path}[{i}]", site=site, task=task)

browserwright/primitives/__init__.py

@@ -0,0 +1,67 @@
+"""v0.5.1 primitive surface (spec §A.2).
+
+This module is what the REPL / inline / task entry points pull into
+their exec globals. Keep it boring — no decorators, no metaprogramming —
+so the agent gets stable, greppable names.
+
+v0.5.1 (F-4 catch-up) added 13 primitives previously documented but not
+re-exported: type_text / press_key / scroll / fill_input / dispatch_key
+/ upload_file / wait_for_element / wait_for_network_idle / drain_events
+/ ensure_real_tab / iframe_target / http_get plus three Layer-3 helpers
+(list_site_skills / load_site_skill / run_task). Three primitives remain
+deferred to v0.6 with explicit footnotes in design.md §A.2:
+handle_dialog, try_recover_from_drift, plus the broader Layer-3 drift
+recovery scaffold.
+"""
+from .discovery_api import (  # noqa: F401
+    list_site_skills,
+    load_site_skill,
+    run_task,
+)
+from .http import http_get  # noqa: F401
+from .inspect import (  # noqa: F401
+    capture_screenshot,
+    cdp,
+    describe_page,
+    diff_snapshot,
+    page_info,
+    snapshot,
+)
+from .interact import (  # noqa: F401
+    click_at_xy,
+    dispatch_key,
+    drain_events,
+    fill_input,
+    js,
+    press_key,
+    scroll,
+    type_text,
+    upload_file,
+    wait_for_element,
+    wait_for_network_idle,
+)
+from .page import (  # noqa: F401
+    attach_active,
+    attach_readonly,
+    close_tab,
+    current_page,
+    current_tab,
+    ensure_real_tab,
+    goto_url,
+    iframe_target,
+    list_tabs,
+    new_tab,
+    open,
+    open_background,
+    reload,
+    switch_tab,
+    wait,
+    wait_for_load,
+)
+from .site import (  # noqa: F401
+    bootstrap_site,
+    memory_read,
+    remember,
+    remember_global,
+    remember_preference,
+)

browserwright/primitives/discovery_api.py

@@ -0,0 +1,79 @@
+"""Discovery / Layer-3 task primitives surfaced into the REPL namespace.
+
+These are thin re-exports + tiny convenience wrappers around
+``browserwright.discovery`` and ``browserwright.task_runner`` so an agent
+typing ``list_site_skills()`` / ``run_task("github.com/list_issues")`` /
+``load_site_skill("github.com")`` from the REPL or inline execution
+doesn't get a NameError. Spec §A.2 v0.5.1 (F-4 catch-up).
+"""
+from __future__ import annotations
+
+import importlib.util
+from typing import Any, Optional
+
+from ..discovery import find_task_path, list_tasks
+from ..memory.site_mem import host_stem
+from ..task_runner import run_task as _run_task
+
+
+def list_site_skills(*, site: Optional[str] = None,
+                     query: Optional[str] = None) -> list[dict]:
+    """List bundled + user-installed tasks (alias of CLI ``list-tasks``).
+
+    Returns dicts with ``site``, ``name``, ``desc``, ``path`` and the
+    discovery scoring fields. ``site`` filters by stem (eTLD+1 or
+    legacy alias); ``query`` does substring scoring against task
+    metadata.
+    """
+    return list_tasks(site=site, query=query)
+
+
+def load_site_skill(site: str, name: Optional[str] = None) -> Any:
+    """Import a site-skill task module so its ``run()``, ``ARGS``,
+    ``OUTPUT_SCHEMA``, etc. are reachable as attributes.
+
+    Two shapes:
+      - ``load_site_skill("github.com/list_issues")`` (slash form) →
+        load that specific task.
+      - ``load_site_skill("github.com", "list_issues")`` → same, split.
+
+    Pure module import; no ``run()`` invocation. Use ``run_task()`` to
+    actually execute. Path is resolved via ``find_task_path`` so the
+    eTLD+1 stem fallback applies (Bug 1 v0.3.1).
+    """
+    if name is None and "/" in site:
+        site, name = site.split("/", 1)
+    if name is None:
+        raise ValueError(
+            "load_site_skill: missing task name. Pass "
+            "'<site>/<name>' or two positional args."
+        )
+    path = find_task_path(host_stem(site), name)
+    mod_name = f"browserwright_task_{host_stem(site).replace('.', '_')}_{name}"
+    spec = importlib.util.spec_from_file_location(mod_name, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"could not build importlib spec for {path}")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def run_task(site: str, name: Optional[str] = None, **kwargs) -> Any:
+    """Execute a site-skill's ``run(args, ctx=None)`` and return its
+    value. Two argument shapes:
+
+      - ``run_task("github.com/list_issues", state="open")`` (slash form)
+      - ``run_task("github.com", "list_issues", state="open")`` (split)
+
+    Re-exports ``browserwright.task_runner.run_task`` so agents calling
+    this through the REPL namespace get the same isolation semantics as
+    the CLI ``task`` subcommand.
+    """
+    if name is None and "/" in site:
+        site, name = site.split("/", 1)
+    if name is None:
+        raise ValueError(
+            "run_task: missing task name. Pass '<site>/<name>' or two "
+            "positional args."
+        )
+    return _run_task(site, name, **kwargs)

browserwright/primitives/http.py

@@ -0,0 +1,42 @@
+"""Pure-HTTP helpers — no browser required.
+
+``http_get`` is the canonical "I just want the bytes of a page" escape
+hatch. Spec §A.2 / browser-harness pattern: pair with
+``ThreadPoolExecutor`` for bulk static-page scraping (e.g. paginated
+list pages) — opening a browser for every page is wasteful.
+"""
+from __future__ import annotations
+
+import gzip
+import os
+import urllib.request
+from typing import Optional
+
+
+def http_get(url: str, *, headers: Optional[dict] = None,
+             timeout: float = 20.0) -> str:
+    """Plain HTTP GET. Decodes gzip automatically; returns text.
+
+    When ``BROWSER_USE_API_KEY`` is set, prefers the optional ``fetch_use``
+    proxy (handles bot detection / residential proxies / retries) if
+    installed; otherwise falls back to stdlib ``urllib`` with a vanilla
+    Mozilla UA + gzip Accept-Encoding header.
+    """
+    if os.environ.get("BROWSER_USE_API_KEY"):
+        try:
+            from fetch_use import fetch_sync  # type: ignore[import-not-found]
+            return fetch_sync(
+                url, headers=headers, timeout_ms=int(timeout * 1000),
+            ).text
+        except ImportError:
+            pass
+
+    h = {"User-Agent": "Mozilla/5.0", "Accept-Encoding": "gzip"}
+    if headers:
+        h.update(headers)
+    req = urllib.request.Request(url, headers=h)
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        data = r.read()
+        if r.headers.get("Content-Encoding") == "gzip":
+            data = gzip.decompress(data)
+        return data.decode()