Skip to content

Commit 892c05d

Browse files
committed
refactor: consolidate helpers and error types across the package
- One `_documented` helper (client.py) replaces `_attach_generated` and the copy in `_serve.py`: it copies members inherited from private modules onto the public classes, which is what both existed for (pdoc hides such members). - `ProcessError` for binary-not-found, port-in-use, startup failure and lost-connection errors, so callers can tell a dead browser from a failed tool call. Usage errors stay on the base class. - Startup readiness polls every 5 ms instead of 50 ms; a refused localhost connect fails instantly, so the coarser cadence only added latency. - Drop the dead "not started" branch in the transport error message, the double-checked locking around uncontended asyncio locks, the `__dir__` overrides (the generated methods always exist), the per-session rebuild of the snake-case name map, `run_script`'s missing-file pre-check (the binary reports it with a real exit code), and browser.py's re-export of the error classes. `args` is typed as `Sequence[str]`.
1 parent 4f890c9 commit 892c05d

9 files changed

Lines changed: 72 additions & 86 deletions

File tree

‎lightpanda/__init__.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
from .bidi import AsyncBiDiServer, BiDiServer
3131
from .browser import Browser, Session, run_script
3232
from .cdp import AsyncCDPServer, CDPServer
33-
from .errors import LightpandaError, ProtocolError, ScriptError, ToolError
33+
from .errors import LightpandaError, ProcessError, ProtocolError, ScriptError, ToolError
3434

3535
__all__ = [
3636
"Browser",
@@ -44,6 +44,7 @@
4444
"BiDiServer",
4545
"AsyncBiDiServer",
4646
"LightpandaError",
47+
"ProcessError",
4748
"ProtocolError",
4849
"ScriptError",
4950
"ToolError",

‎lightpanda/_serve.py‎

Lines changed: 6 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
import json
1212
import os
1313
import urllib.request
14+
from collections.abc import Sequence
1415
from typing import Generic, TypeVar
1516

1617
from .client import _HOST, _spawn, _terminate, find_binary
@@ -27,7 +28,7 @@ def __init__(
2728
binary: str | os.PathLike | None = None,
2829
env: dict[str, str] | None = None,
2930
verbose: bool = False,
30-
args: tuple[str, ...] | list[str] = (),
31+
args: Sequence[str] = (),
3132
port: int | None = None,
3233
):
3334
"""``port`` pins the listening port (default: a free one). ``args``
@@ -93,7 +94,7 @@ def __init__(
9394
binary: str | os.PathLike | None = None,
9495
env: dict[str, str] | None = None,
9596
verbose: bool = False,
96-
args: tuple[str, ...] | list[str] = (),
97+
args: Sequence[str] = (),
9798
port: int | None = None,
9899
):
99100
"""Arguments are forwarded to the sync class."""
@@ -103,10 +104,9 @@ def __init__(
103104

104105
async def start(self):
105106
"""Spawn the server process. Idempotent."""
106-
if self._server is None:
107-
async with self._start_lock:
108-
if self._server is None:
109-
self._server = await asyncio.to_thread(self._sync_cls, **self._kwargs)
107+
async with self._start_lock:
108+
if self._server is None:
109+
self._server = await asyncio.to_thread(self._sync_cls, **self._kwargs)
110110
return self
111111

112112
def _started(self) -> _S:
@@ -134,16 +134,3 @@ async def __aenter__(self):
134134
async def __aexit__(self, *exc):
135135
await self.close()
136136

137-
138-
def _documented(cls: type) -> type:
139-
"""Copy the public members (and ``__init__``) this module's bases give
140-
``cls`` onto ``cls`` itself, so pdoc and IDEs document them as its own:
141-
pdoc hides what is inherited from a private module. Same trick as
142-
``_attach_generated`` in browser.py."""
143-
for base in cls.__mro__[1:]:
144-
if base.__module__ != __name__:
145-
continue
146-
for name, member in vars(base).items():
147-
if (name == "__init__" or not name.startswith("_")) and name not in vars(cls):
148-
setattr(cls, name, member)
149-
return cls

‎lightpanda/async_browser.py‎

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,11 @@
1414
import contextlib
1515
import functools
1616
import os
17+
from collections.abc import Sequence
1718
from concurrent.futures import ThreadPoolExecutor
1819

19-
from .browser import Browser, Session, _attach_generated, _generated, run_script
20+
from .browser import Browser, Session, _generated, run_script
21+
from .client import _documented
2022
from .errors import LightpandaError
2123

2224
AsyncSessionMethods = _generated("AsyncSessionMethods")
@@ -27,6 +29,7 @@ async def _run(executor: ThreadPoolExecutor, fn, *args, **kwargs):
2729
return await loop.run_in_executor(executor, functools.partial(fn, *args, **kwargs))
2830

2931

32+
@_documented
3033
class AsyncSession(AsyncSessionMethods):
3134
"""One isolated browsing context (own page, cookies, memory), async.
3235
@@ -51,12 +54,8 @@ def __getattr__(self, attr: str):
5154
return functools.partial(self.call, attr)
5255
raise AttributeError(f"{type(self).__name__!r} object has no attribute {attr!r}")
5356

54-
def __dir__(self):
55-
return sorted(set(super().__dir__()) | self._session._tool_attrs())
56-
5757
async def close(self) -> None:
58-
if not self._session._closed:
59-
await _run(self._executor, self._session.close)
58+
await _run(self._executor, self._session.close)
6059

6160
async def __aenter__(self):
6261
return self
@@ -65,8 +64,6 @@ async def __aexit__(self, *exc):
6564
await self.close()
6665

6766

68-
_attach_generated(AsyncSession, AsyncSessionMethods)
69-
7067

7168
class AsyncBrowser:
7269
"""A lightpanda browser process, driven from asyncio.
@@ -82,7 +79,7 @@ def __init__(
8279
env: dict[str, str] | None = None,
8380
timeout: float = 300.0,
8481
verbose: bool = False,
85-
args: tuple[str, ...] | list[str] = (),
82+
args: Sequence[str] = (),
8683
max_concurrency: int = 32,
8784
):
8885
"""``binary``/``env``/``timeout``/``verbose``/``args`` are forwarded
@@ -107,10 +104,9 @@ def wrap(cls, browser: Browser, max_concurrency: int = 32) -> AsyncBrowser:
107104

108105
async def start(self) -> AsyncBrowser:
109106
"""Spawn the browser process and fetch its tool list. Idempotent."""
110-
if self._browser is None:
111-
async with self._start_lock:
112-
if self._browser is None:
113-
self._browser = await _run(self._executor, Browser, **self._kwargs)
107+
async with self._start_lock:
108+
if self._browser is None:
109+
self._browser = await _run(self._executor, Browser, **self._kwargs)
114110
return self
115111

116112
@property

‎lightpanda/bidi.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@
99

1010
import asyncio
1111

12-
from ._serve import _AsyncServeProcess, _ServeProcess, _documented
13-
from .client import _HOST
12+
from ._serve import _AsyncServeProcess, _ServeProcess
13+
from .client import _HOST, _documented
1414

1515

1616
@_documented

‎lightpanda/browser.py‎

Lines changed: 12 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,12 @@
1616
import os
1717
import re
1818
import subprocess
19+
from collections.abc import Sequence
1920
from importlib.metadata import PackageNotFoundError, version
2021
from pathlib import Path
2122

22-
from .client import Client, find_binary
23-
from .errors import ProtocolError, ScriptError, ToolError
23+
from .client import Client, _documented, find_binary
24+
from .errors import ScriptError, ToolError
2425

2526
_SESSION_TOOLS = {"save", "session_new", "session_list", "session_close"}
2627

@@ -39,29 +40,21 @@ def _generated(name: str) -> type:
3940
return type(name, (), {})
4041

4142

42-
def _attach_generated(cls: type, methods: type) -> None:
43-
"""pdoc hides members inherited from a private module; re-attach the
44-
generated tool methods as the class's own so they document (and
45-
introspect) directly."""
46-
for name, member in vars(methods).items():
47-
if not name.startswith("_") and name != "call":
48-
setattr(cls, name, member)
49-
50-
5143
SessionMethods = _generated("SessionMethods")
5244

5345

46+
@_documented
5447
class Session(SessionMethods):
5548
"""One isolated browsing context (own page, cookies, memory).
5649
5750
Do not construct directly — use :meth:`Browser.new_session`.
5851
"""
5952

60-
def __init__(self, client: Client, session_id: str, tools: dict[str, dict]):
61-
self._client = client
53+
def __init__(self, browser: Browser, session_id: str):
54+
self._client = browser._client
55+
self._tools = browser._tools
56+
self._snake_map = browser._snake_map
6257
self._id = session_id
63-
self._tools = tools
64-
self._snake_map = {_snake(name): name for name in tools}
6558
self._closed = False
6659

6760
self._client.request(
@@ -121,21 +114,11 @@ def _resolve(self, attr: str) -> str | None:
121114
name = self._snake_map.get(attr, attr)
122115
return name if name in self._tools and name not in _SESSION_TOOLS else None
123116

124-
def _tool_attrs(self) -> set[str]:
125-
names = set()
126-
for snake, name in self._snake_map.items():
127-
if name not in _SESSION_TOOLS:
128-
names.update((snake, name))
129-
return names
130-
131117
def __getattr__(self, attr: str):
132118
if self.__dict__.get("_tools") and (name := self._resolve(attr)):
133119
return functools.partial(self.call, name)
134120
raise AttributeError(f"{type(self).__name__!r} object has no attribute {attr!r}")
135121

136-
def __dir__(self):
137-
return sorted(set(super().__dir__()) | self._tool_attrs())
138-
139122
def close(self) -> None:
140123
if not self._closed:
141124
self._closed = True
@@ -148,8 +131,6 @@ def __exit__(self, *exc):
148131
self.close()
149132

150133

151-
_attach_generated(Session, SessionMethods)
152-
153134

154135
class Browser:
155136
"""A lightpanda browser process. Spawns the bundled binary on first use.
@@ -164,7 +145,7 @@ def __init__(
164145
env: dict[str, str] | None = None,
165146
timeout: float = 300.0,
166147
verbose: bool = False,
167-
args: tuple[str, ...] | list[str] = (),
148+
args: Sequence[str] = (),
168149
):
169150
"""``args`` are extra CLI flags for the spawned browser process
170151
(e.g. ``["--http-cache-dir", path]`` or cookie flags)."""
@@ -178,6 +159,7 @@ def __init__(
178159
}
179160
for tool in listed.get("tools", [])
180161
}
162+
self._snake_map = {_snake(name): name for name in self._tools}
181163

182164
@property
183165
def tools(self) -> dict[str, dict]:
@@ -187,7 +169,7 @@ def tools(self) -> dict[str, dict]:
187169
def new_session(self) -> Session:
188170
# itertools.count is atomic, so concurrent callers (the async facade's
189171
# worker threads) can't mint duplicate session ids.
190-
return Session(self._client, f"py{next(self._seq)}", self._tools)
172+
return Session(self, f"py{next(self._seq)}")
191173

192174
def close(self) -> None:
193175
self._client.close()
@@ -211,8 +193,6 @@ def run_script(
211193
child's environment. Raises :class:`ScriptError` on a non-zero exit.
212194
"""
213195
path = Path(script)
214-
if not path.is_file():
215-
raise ScriptError(f"script not found: {path}", returncode=-1)
216196
proc = subprocess.run(
217197
[str(find_binary(binary)), "run", str(path)],
218198
env=os.environ | (env or {}),
@@ -239,4 +219,4 @@ def _version() -> str:
239219
return "0.0.0.dev0"
240220

241221

242-
__all__ = ["Browser", "Session", "run_script", "ProtocolError", "ScriptError", "ToolError"]
222+
__all__ = ["Browser", "Session", "run_script"]

‎lightpanda/cdp.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@
1616

1717
import asyncio
1818

19-
from ._serve import _AsyncServeProcess, _ServeProcess, _documented
20-
from .client import _HOST
19+
from ._serve import _AsyncServeProcess, _ServeProcess
20+
from .client import _HOST, _documented
2121

2222

2323
@_documented

0 commit comments

Comments
 (0)