parsek-cdp 0.1.0__py3-none-any.whl

parsek_cdp/core/frame.py

@@ -0,0 +1,351 @@
+"""A single frame -- the mandatory browser abstraction.
+
+A :class:`Frame` is self-contained: it binds to the CDP session that owns it
+(:attr:`Frame.target` -- a dedicated session of its own for a cross-origin
+OOPIF, the page's session otherwise) and exposes :meth:`Frame.select` /
+:meth:`Frame.evaluate` and the ``wait_for_*`` helpers, all scoped to that frame.
+Everything routes through :attr:`Frame.cdp` so same- and cross-origin frames
+behave identically.
+
+Tracking the *tree* of frames (parent/child links, attach/detach, OOPIF
+discovery) is a separate, optional concern handled by a tree-manager feature --
+a :class:`Frame` never depends on it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from enum import Enum
+from typing import TYPE_CHECKING, List, Optional, Tuple
+
+from ..cdp import DOM, Page
+from .target import ProtocolError, Target
+
+if TYPE_CHECKING:
+    from .element import Element
+
+
+class ElementState(Enum):
+    """Condition awaited by :meth:`Frame.wait_for_selector` / :meth:`Frame.wait_for_xpath`."""
+
+    ATTACHED = "attached"
+    VISIBLE = "visible"
+    HIDDEN = "hidden"
+    DETACHED = "detached"
+
+
+class LoadState(Enum):
+    """A page lifecycle milestone; values are the CDP ``Page.lifecycleEvent`` names."""
+
+    LOAD = "load"
+    DOMCONTENTLOADED = "DOMContentLoaded"
+    NETWORKIDLE = "networkIdle"
+
+
+class Frame:
+    """A single frame, bound to the CDP session that owns it.
+
+    Holds the protocol :class:`~parsek_cdp.cdp.page.types.Frame` fields that
+    matter day to day (``url``, ``name``, ``loader_id``) and offers
+    :meth:`evaluate` / :meth:`select` scoped to it.  A cross-origin frame is
+    bound to its own dedicated CDP session (:attr:`target`); everything routes
+    through :attr:`cdp` so same- and cross-origin frames behave identically.
+
+    ``target`` is the session this frame runs on (the page for same-origin
+    frames; for the main frame the page *is* the frame).  ``parent_id`` is kept
+    as raw protocol data, but resolving it to a parent frame -- and listing
+    children -- is the job of the optional tree-manager feature.
+    """
+
+    _head_elem: Element | None
+
+    def __init__(
+        self,
+        target: "Target",
+        frame_info: Page.Frame,
+        parent: Frame | None = None,
+    ) -> None:
+        self.target = target
+        self._frame = frame_info
+        self._parent = parent
+        self._frames: dict[Page.FrameId, Frame] = {}
+
+        self._dom_generation = 0
+        self._head_elem = None
+
+        self._bind_dom_tracking()
+
+    def _bind_dom_tracking(self) -> None:
+        """Track every event that invalidates this frame's ``nodeId`` map.
+
+        ``DOM.enable``/``DOM.disable`` rebuild (or drop) the whole node-id map and
+        ``DOM.documentUpdated`` fires when the document is replaced -- each leaves
+        previously minted ``nodeId``s stale.  Which one happened doesn't matter,
+        only that the map changed, so all three bump a single monotonic counter;
+        an :class:`Element` whose ``_generation`` lags re-mints its id from the
+        stable ``backendNodeId`` (see :meth:`Element.refresh`).
+        """
+        self.target.on_function(self.target.cdp.DOM.disable, self._bump_dom_generation)
+        self.target.on_function(self.target.cdp.DOM.enable, self._bump_dom_generation)
+        self.target.on(DOM.DocumentUpdated, self._bump_dom_generation)
+
+    def _unbind_dom_tracking(self) -> None:
+        self.target.off_function(self.target.cdp.DOM.disable, self._bump_dom_generation)
+        self.target.off_function(self.target.cdp.DOM.enable, self._bump_dom_generation)
+        self.target.off(DOM.DocumentUpdated, self._bump_dom_generation)
+
+    def _bump_dom_generation(self, _) -> None:
+        self._dom_generation += 1
+
+    def dispose(self) -> None:
+        """Unregister this frame's (and its subtree's) DOM-tracking handlers.
+
+        Same-origin frames share one target, so the handlers bound in
+        :meth:`_bind_dom_tracking` outlive the frame unless removed explicitly.
+        Call this whenever a frame leaves the tree (see :meth:`detach_frame` /
+        :meth:`refresh_frame`) so recreated frames don't pile up dead handlers on
+        the target.
+        """
+        self._unbind_dom_tracking()
+        for child in list(self._frames.values()):
+            child.dispose()
+        self._frames.clear()
+
+    @property
+    def id(self) -> Page.FrameId:
+        return self._frame.id
+
+    @property
+    def url(self) -> str:
+        return self._frame.url
+
+    @property
+    def name(self) -> Optional[str]:
+        return self._frame.name
+
+    @property
+    def loader_id(self) -> str:
+        return self._frame.loader_id
+
+    @property
+    def is_main(self) -> bool:
+        return self._frame.parent_id is None
+
+    @property
+    def is_oopif(self) -> bool:
+        """``True`` when this frame is a cross-origin frame with its own session.
+
+        A frame keeps its own identity (:attr:`id`); this only asks whether the
+        session it is *bound* to is dedicated to it (an out-of-process iframe).
+        """
+        return self.target.id == self._frame.id
+
+    @property
+    def raw_frame(self) -> Page.Frame:
+        return self._frame
+
+    @property
+    def frames(self):
+        return list(self._frames.values())
+
+    @property
+    def cdp(self):
+        """The CDP entry point of the session this frame is bound to."""
+        return self.target.cdp
+
+    async def _get_head_elem(self):
+        if (
+            self._head_elem is None
+            or self._dom_generation != self._head_elem._generation
+        ):
+            from .element import Element
+
+            document = await self.cdp.DOM.get_document(depth=0)
+            self._head_elem = Element._from_node(document.root, frame=self)
+            self._head_elem._generation = self._dom_generation
+        return self._head_elem
+
+    @classmethod
+    def from_frame_tree(cls, origin_frame: Frame, frame_tree: Page.FrameTree):
+        frame_id = frame_tree.frame.id
+        target = origin_frame.target._targets.get(frame_id, origin_frame.target)
+        instance = cls(target, frame_tree.frame, origin_frame)
+        for frame_tree in frame_tree.child_frames or []:
+            child = Frame.from_frame_tree(instance, frame_tree)
+            instance._frames[child.id] = child
+        return instance
+
+    async def refresh_frame(self):
+        tree = await self.cdp.Page.get_frame_tree()
+        self._merge_frame_tree(tree.frame_tree)
+
+    def _merge_frame_tree(self, frame_tree: Page.FrameTree) -> None:
+        """Reconcile this frame's children against a fresh ``Page.getFrameTree``.
+
+        Only frames absent from ``frame_tree`` are disposed; survivors keep their
+        identity (and their bound DOM-tracking handlers), so we neither leak
+        handlers by recreating them nor throw away their per-frame state (DOM
+        generation, cached head element).  New frames are built fresh.
+        """
+        self._frame = frame_tree.frame
+        children = frame_tree.child_frames or []
+        live_ids = {child.frame.id for child in children}
+        for frame_id in list(self._frames):
+            if frame_id not in live_ids:
+                self._frames.pop(frame_id).dispose()
+        for child_tree in children:
+            existing = self._frames.get(child_tree.frame.id)
+            if existing is not None:
+                existing._merge_frame_tree(child_tree)
+            else:
+                child = Frame.from_frame_tree(self, child_tree)
+                self._frames[child.id] = child
+
+    async def select(
+        self, *, selector: Optional[str] = None, xpath: Optional[str] = None
+    ) -> Optional[Element]:
+        """Find the first node matching a CSS ``selector`` or an ``xpath``.
+
+        Returns its :class:`Element`, or ``None`` if nothing matches.  The query
+        runs in this frame's document, so subframes are resolved correctly.
+        """
+        from .element import Element
+
+        if xpath is not None:
+            node_ids = await self._perform_search(xpath)
+            if not node_ids:
+                return None
+            return await Element.describe_node(node_id=node_ids[0], frame=self)
+        if selector is None:
+            raise ValueError("select() needs either selector= or xpath=")
+        head_node = await self._get_head_elem()
+        return await head_node.query_selector(selector=selector)
+
+    async def select_all(self, selector: str) -> List[Element]:
+        """Return an :class:`Element` for every node matching ``selector``."""
+
+        head_node = await self._get_head_elem()
+        res = []
+        async for elem in head_node.query_selector_all(selector=selector):
+            res.append(elem)
+        return res
+
+    async def _perform_search(self, query: str) -> List[int]:
+        """Run a DevTools DOM search (text / attributes / markup / XPath)."""
+        dom = self.cdp.DOM
+        search = await dom.perform_search(
+            query=query, include_user_agent_shadow_dom=True
+        )
+        try:
+            if not search.result_count:
+                return []
+            results = await dom.get_search_results(
+                search_id=search.search_id,
+                from_index=0,
+                to_index=min(search.result_count, 50),
+            )
+            return [n for n in results.node_ids if n]
+        finally:
+            try:
+                await dom.discard_search_results(search_id=search.search_id)
+            except Exception:
+                pass
+
+    async def evaluate(self, expression: str, *, await_promise: bool = False):
+        """Evaluate JavaScript in this frame and return the value.
+
+        Runs in the frame's own execution context, so subframes (including
+        cross-origin ones) are evaluated correctly rather than against the main
+        page.  Raises :class:`RuntimeError` if a non-main frame has no context
+        yet (e.g. before it has loaded).
+        """
+        result = await self.cdp.Runtime.evaluate(
+            expression=expression,
+            await_promise=await_promise,
+            return_by_value=True,
+        )  # TODO: Сделать по контексту
+        return result.result.value if result.result else None
+
+    async def wait_for_selector(
+        self,
+        selector: str,
+        *,
+        state: ElementState = ElementState.VISIBLE,
+        timeout: float = 30,
+        poll_interval: float = 0.1,
+    ) -> Optional[Element]:
+        """Poll until a node matching the CSS ``selector`` reaches ``state``.
+
+        Returns the :class:`Element` for ``ATTACHED`` / ``VISIBLE`` (or ``None``
+        for ``HIDDEN`` / ``DETACHED``).  Raises :class:`asyncio.TimeoutError` if
+        the state is not reached within ``timeout`` seconds.  Each poll
+        re-queries, so a re-mounted node (fresh ``nodeId``) is handled correctly.
+        """
+        return await self._wait_for_query(
+            {"selector": selector}, state, timeout, poll_interval
+        )
+
+    async def wait_for_xpath(
+        self,
+        xpath: str,
+        *,
+        state: ElementState = ElementState.VISIBLE,
+        timeout: float = 30,
+        poll_interval: float = 0.1,
+    ) -> Optional[Element]:
+        """Like :meth:`wait_for_selector` but matching an XPath expression."""
+        return await self._wait_for_query(
+            {"xpath": xpath}, state, timeout, poll_interval
+        )
+
+    async def _wait_for_query(
+        self,
+        query: dict,
+        state: ElementState,
+        timeout: float,
+        poll_interval: float,
+    ) -> Optional[Element]:
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while True:
+            try:
+                element = await self.select(**query)
+            except ProtocolError:
+                element = None
+            done, result = await self._state_satisfied(element, state)
+            if done:
+                return result
+            if loop.time() >= deadline:
+                target = query.get("selector") or query.get("xpath")
+                raise asyncio.TimeoutError(
+                    f"waiting for {target!r} to be {state.value} timed out after {timeout}s"
+                )
+            await asyncio.sleep(poll_interval)
+
+    @staticmethod
+    async def _state_satisfied(
+        element: Optional[Element], state: ElementState
+    ) -> Tuple[bool, Optional[Element]]:
+        """Whether ``element`` meets ``state`` (and what to return on success)."""
+        if state is ElementState.ATTACHED:
+            return element is not None, element
+        if state is ElementState.DETACHED:
+            return element is None, None
+        visible = element is not None and await element.is_visible()
+        if state is ElementState.VISIBLE:
+            return visible, element
+        return not visible, element
+
+    def attach_frame(self, frame: Frame):
+        self._frames[frame.id] = frame
+
+    def detach_frame(self, frame: Frame):
+        detached = self._frames.pop(frame.id)
+        detached.dispose()
+        return detached
+
+    def __str__(self) -> str:
+        kind = "oopif" if self.is_oopif else ("main" if self.is_main else "child")
+        return f"<Frame {kind} {self.target.url!r}>"
+
+    __repr__ = __str__

parsek_cdp/core/pagable.py

@@ -0,0 +1,175 @@
+"""``PagableTarget`` -- shared management of pages (the page/tab handling).
+
+Both :class:`Browser` (all pages) and :class:`BrowserContext` (pages of one
+context) manage a collection of pages with identical bookkeeping, so the whole
+page/tab lifecycle -- *including reacting to the ``Target.*`` discovery events*
+-- lives here:
+
+* :meth:`watch` registers the discovery handlers on the connection that delivers
+  them (the browser's own websocket);
+* :meth:`_on_target_created` / :meth:`_on_target_destroyed` /
+  :meth:`_on_target_info_changed` react to the protocol events;
+* :meth:`new_page` issues ``Target.createTarget`` and waits for the matching
+  target to be discovered;
+* :meth:`_ensure_page` builds a :class:`Page` (via ``self.page_class``), connects
+  its own websocket, binds it and registers it.
+
+Pages are keyed by their **target id** (each target has its own websocket, so
+there is no multiplexing ``sessionId``).  A page registered in a scope *bubbles*
+to its :attr:`_parent` (a context's parent is its browser), so a page created in
+a context also lands in the browser's global registry -- one :class:`Page`
+instance shared by both.  The only browser-specific bit is resolving which
+context owns a target, exposed through :meth:`_context_for` (defaults to
+``self``; the browser overrides it).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+from typing import TYPE_CHECKING, Callable, Dict, List, Optional, cast
+
+from ..cdp import Target as TargetDomain
+
+if TYPE_CHECKING:
+    from ..cdp import CDP
+    from .browser import Browser
+    from .page import Page
+    from .target import Target
+
+PageCallback = Callable[["Page"], None]
+
+
+class PagableTarget[T: Page]:
+    """Mixin managing a collection of pages within a scope."""
+
+    _cdp: CDP
+    page_class: type[T]
+    _parent: PagableTarget[T] | None = None
+
+    def __init__(self) -> None:
+        self._pages: Dict[TargetDomain.TargetID, T] = {}
+        self._page_callbacks: List[PageCallback] = []
+        self._page_waiters: List[list] = []
+
+    @property
+    def pages(self):
+        return list(self._pages.values())
+
+    @property
+    def _scope_context_id(self) -> Optional[str]:
+        """Browser-context id new pages are created in (``None`` = default)."""
+        raise NotImplementedError
+
+    def _bind_page(self, page: T) -> None:
+        """Set ``page.browser`` / ``page.browser_context``. Overridden per scope."""
+
+    def _context_for(self, context_id: Optional[str]) -> "PagableTarget[T]":
+        """Resolve the scope that owns a target. Browser overrides; else self."""
+        return self
+
+    def watch(self, connection: "Target") -> None:
+        """Register the page-discovery handlers on ``connection``'s websocket.
+
+        Only the browser calls this (its websocket is where ``Target.*`` events
+        arrive); contexts are driven by the browser routing through
+        :meth:`_context_for`.
+        """
+        connection.on(TargetDomain.TargetCreated, self.__on_target_created)
+        connection.on(TargetDomain.TargetDestroyed, self.__on_target_destroyed)
+        connection.on(TargetDomain.TargetInfoChanged, self.__on_target_info_changed)
+
+    def __on_target_created(self, event: TargetDomain.TargetCreated) -> None:
+        info = event.target_info
+        if info.type_ in ("page", "tab"):
+            scope = self._context_for(info.browser_context_id)
+            asyncio.ensure_future(scope._ensure_page(info))
+
+    def __on_target_destroyed(self, event: TargetDomain.TargetDestroyed) -> None:
+        self._drop_page(event.target_id)
+
+    def __on_target_info_changed(self, event: TargetDomain.TargetInfoChanged) -> None:
+        page = self.get_page(target_id=event.target_info.target_id)
+        if page is not None:
+            page._target = event.target_info
+
+    def on_page(self, callback: PageCallback) -> PageCallback:
+        """Register a callback invoked for every page added to this scope."""
+        self._page_callbacks.append(callback)
+
+        @functools.wraps(callback)
+        def wrapper(page: Page):
+            callback(page)
+
+        return wrapper
+
+    @property
+    def page_list(self) -> List[T]:
+        return list(self._pages.values())
+
+    def get_page(self, *, target_id: Optional[str] = None) -> Optional[T]:
+        """Look a page up by target id."""
+        if target_id is not None:
+            return self._pages.get(target_id)
+        return None
+
+    async def new_page(self, url: str = "about:blank", *, timeout: float = 30) -> T:
+        """Create a new page/tab in this scope and return it once connected.
+
+        Relies on target discovery to deliver the new target, build the page and
+        open its own websocket.
+        """
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future = loop.create_future()
+        waiter: list = [None, future]
+        self._page_waiters.append(waiter)
+        try:
+            created = await self._cdp.Target.create_target(
+                url=url,
+                browser_context_id=self._scope_context_id,
+            )
+            waiter[0] = created.target_id
+            existing = self.get_page(target_id=created.target_id)
+            if existing is not None and not future.done():
+                future.set_result(existing)
+            page: T = await asyncio.wait_for(future, timeout)
+            await page.wait_features_ready()
+            return page
+        finally:
+            if waiter in self._page_waiters:
+                self._page_waiters.remove(waiter)
+
+    async def _ensure_page(self, target_info: TargetDomain.TargetInfo) -> T:
+        """Build, connect + register a page in this scope (once per target)."""
+        page = self._pages.get(target_info.target_id)
+        if page is None:
+            owner = cast("Browser[T]", self._parent or self)
+            page = self.page_class(owner, target_info)
+            self._bind_page(page)
+            await page.connect()
+            await page.wait_features_ready()
+            self._add_page(page)
+        return page
+
+    def _add_page(self, page: T) -> None:
+        if page.id is not None:
+            self._pages[page.id] = page
+        for callback in list(self._page_callbacks):
+            callback(page)
+        for waiter in list(self._page_waiters):
+            target_id, future = waiter
+            if target_id == page.id and not future.done():
+                future.set_result(page)
+        if self._parent is not None:
+            self._parent._add_page(page)  # bubble to the global registry
+
+    def _drop_page(self, target_id: Optional[str]) -> None:
+        page = self._pages.pop(target_id or "", None)
+        if page is None:
+            return
+        context = getattr(page, "browser_context", None)
+        if context is not None and context is not self:
+            context._remove_page(page.id)
+
+    def _remove_page(self, target_id: Optional[str]) -> None:
+        self._pages.pop(target_id or "", None)

parsek_cdp/core/page.py

@@ -0,0 +1,163 @@
+"""A page target: a CDP session attached to a page/tab.
+
+``Page`` is a bare host -- it attaches **no** features by default; every feature
+(frame-tree tracking, request listening, ...) is optional and opted into:
+
+* declaratively -- ``Page[Frames]`` / ``Page[Frames, RequestListener]`` (or
+  chained ``Page[A][B]``); each is attached on construction;
+* imperatively + type-safely -- ``page.get_feature(Frames)`` returns the feature
+  typed as ``Frames`` (attaching it on first use).
+
+A page *is its own main frame*: it subclasses :class:`Frame` (the main frame's id
+equals the page's target id), so ``page.select(...)`` / ``page.evaluate(...)``
+work on the top frame without any feature.  The frame *tree* (subframes, OOPIFs)
+lives in the optional :class:`Frames` feature.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, AsyncIterator
+
+from ..cdp import Target as TargetDomain
+from .feature import Feature, FeatureHost
+from .frame import Frame
+from .target import Target
+
+if TYPE_CHECKING:
+    from .browser import Browser
+    from .browser_context import BrowserContext
+
+
+class NavigationError(Exception):
+    """Raised by :meth:`Page.no_navigation` when the guarded block was cut short
+    by a main-frame navigation (only when ``raise_=True``)."""
+
+
+class _NavGuard:
+    """Handle yielded by :meth:`Page.no_navigation`; ``navigated`` flips on nav."""
+
+    navigated: bool = False
+
+
+class Page[T: Feature](Target, FeatureHost[T], Frame):
+    """A page (tab) target exposing every CDP domain through :attr:`cdp`.
+
+    A page *is its own main frame*: it subclasses :class:`Frame` (in CDP the
+    main frame's id equals the page's target id), so ``page.url`` and
+    ``page.evaluate(...)`` operate on the top frame, while the full frame tree
+    (and navigation like ``page.frames.children_of(page)``) lives in
+    :attr:`frames`.
+
+    Generic over the feature type so ``Page[RequestListener]`` is accepted by
+    type checkers (the runtime composition is handled by ``FeatureHost``).
+    """
+
+    browser: "Browser"
+    browser_context: "BrowserContext"
+
+    def __init__(
+        self,
+        browser: Browser,
+        target_info: TargetDomain.TargetInfo,
+    ):
+        Target.__init__(self, target_info, browser)
+        self._init_features()
+        self.browser = browser
+        self.browser._targets[self.id] = self
+
+    async def connect(self) -> "Page[T]":
+        """Open the page's own websocket, learn its main frame, start features."""
+        await super().connect()
+        tree = await self.cdp.Page.get_frame_tree()
+        Frame.__init__(self, self, tree.frame_tree.frame, None)
+        await self.wait_features_ready()
+        return self
+
+    async def navigate(self, url: str, *, wait_load: bool = False, timeout: float = 30):
+        """Navigate to ``url``; optionally wait for the load event.
+
+        ``Page.loadEventFired`` only arrives while the ``Page`` domain is enabled,
+        so ``wait_load`` enables it for the duration here.  The waiter is armed
+        *before* navigating, so a fast load that fires before the command returns
+        is not missed.
+        """
+        from ..cdp.page.events import LoadEventFired
+
+        if not wait_load:
+            return await self.cdp.Page.navigate(url=url)
+
+        async with self.domain_enabled(self.cdp.Page):
+            loop = asyncio.get_running_loop()
+            loaded: asyncio.Future = loop.create_future()
+
+            def _on_load(_event: object) -> None:
+                if not loaded.done():
+                    loaded.set_result(None)
+
+            self.on(LoadEventFired, _on_load)
+            try:
+                data = await self.cdp.Page.navigate(url=url)
+                await asyncio.wait_for(loaded, timeout)
+            finally:
+                self.off(LoadEventFired, _on_load)
+        return data
+
+    @asynccontextmanager
+    async def with_same_navigation(
+        self, *, raise_: bool = True
+    ) -> AsyncIterator[_NavGuard]:
+        """Run the block only while the document stays the same.
+
+        Guards a block of work against a main-frame navigation: if the page
+        navigates (the main frame commits a new ``loaderId``) while the body
+        runs, the body is cancelled at its next ``await`` -- so logic never keeps
+        operating on a document that has been replaced underneath it::
+
+            async with page.with_same_navigation():
+                el = await page.select(selector="#row")
+                await el.click()          # cut short if navigation happens here
+
+        With ``raise_=True`` (default) a :class:`NavigationError` is raised when
+        the block is cut short; with ``raise_=False`` it is swallowed and the
+        yielded guard's ``navigated`` flag lets the caller decide (e.g. retry)::
+
+            async with page.with_same_navigation(raise_=False) as guard:
+                ...
+            if guard.navigated:
+                ...  # the block was interrupted by a navigation
+        """
+        from ..cdp.page.events import FrameNavigated
+
+        guard = _NavGuard()
+        baseline = self.loader_id
+        task = asyncio.current_task()
+
+        def _on(e: "FrameNavigated") -> None:
+            if (
+                e.frame.parent_id is None
+                and e.frame.loader_id != baseline
+                and not guard.navigated
+            ):
+                guard.navigated = True
+                if task is not None:
+                    task.cancel()
+
+        self.on(FrameNavigated, _on)
+        try:
+            async with self.domain_enabled(self.cdp.Page):
+                yield guard
+                if guard.navigated and raise_:
+                    raise NavigationError(
+                        f"navigation away from {self.url!r} cut the block short"
+                    )
+        except asyncio.CancelledError:
+            if not guard.navigated:
+                raise  # a genuine external cancellation -- propagate untouched
+            if raise_:
+                raise NavigationError(
+                    f"navigation away from {self.url!r} cut the block short"
+                ) from None
+        finally:
+            self.off(FrameNavigated, _on)