From 28fe66c4a4c0baa89702206bb42e4079d90bc899 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A0=20Arrufat?= Date: Wed, 30 Sep 2026 11:38:13 +0200 Subject: [PATCH] Put the Session conventions in the Session docstring The rules for calling an action -- keyword-only, snake_case after the browser's own names, `selector` winning over `backend_node_id`, `call` as the escape hatch, `ToolError` on failure -- were a fixed paragraph in the docs site's reference generator. They describe this class, so they belong on it: IDE hover and `help()` show them now, and they stay next to the code they describe instead of drifting in another repository. `AsyncSession` points at `Session` rather than repeating them. Part of #6. --- lightpanda/async_browser.py | 4 ++++ lightpanda/browser.py | 14 ++++++++++++++ 2 files changed, 18 insertions(+) diff --git a/lightpanda/async_browser.py b/lightpanda/async_browser.py index 5408e64..34a5b36 100644 --- a/lightpanda/async_browser.py +++ b/lightpanda/async_browser.py @@ -34,6 +34,10 @@ class AsyncSession(AsyncSessionMethods): """One isolated browsing context (own page, cookies, memory), async. Do not construct directly — use :meth:`AsyncBrowser.new_session`. + + Same conventions as :class:`Session` — keyword-only actions in snake_case, + ``selector`` winning over ``backend_node_id``, :meth:`call` as the escape + hatch — with every method a coroutine to await. """ def __init__(self, session: Session, executor: ThreadPoolExecutor): diff --git a/lightpanda/browser.py b/lightpanda/browser.py index a3b0b56..0866ded 100644 --- a/lightpanda/browser.py +++ b/lightpanda/browser.py @@ -80,6 +80,20 @@ class Session(SessionMethods): """One isolated browsing context (own page, cookies, memory). Do not construct directly — use :meth:`Browser.new_session`. + + Browser actions are keyword-only methods, named in snake_case after the + browser's own action names: the ``waitForSelector`` action is + :meth:`wait_for_selector`, and its ``backendNodeId`` argument is + ``backend_node_id``. + + Where a method accepts both ``selector`` and ``backend_node_id``, pass one + of the two. ``selector`` is preferred for reproducibility and wins when + both are given; ``backend_node_id`` takes the values returned by + :meth:`tree`, :meth:`links` or :meth:`find_element`. + + :meth:`call` is the escape hatch that takes the action and argument names + exactly as the browser declares them. A failed action raises + :class:`ToolError`. """ def __init__(self, browser: Browser, session_id: str):