sleight 0.1.0a1__py3-none-any.whl

sleight/__init__.py

@@ -0,0 +1,138 @@
+"""sleight —— 通过 CDP 驱动真实浏览器，自带拟人交互与实例池管理。
+
+    >>> from sleight import connect
+    >>> with connect("http://127.0.0.1:9222") as s:
+    ...     s.open("https://example.com")
+    ...     print(s.title())
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _installed_version
+from typing import Any
+
+from ._logging import enable_debug_logging
+from .core import errors
+from .core.element import Element
+from .core.errors import (
+    AuthError,
+    Busy,
+    Crashed,
+    ElementError,
+    InstanceError,
+    LeaseLost,
+    NotFound,
+    NotReady,
+    SessionLost,
+    SleightError,
+)
+from .core.human import CAREFUL, DEFAULT, FAST, HumanProfile
+from .core.session import Selectable, Session
+from .core.transport import Transport
+from .core.types import (
+    Box,
+    Condition,
+    DomReady,
+    Endpoint,
+    Gone,
+    InstanceInfo,
+    InstanceStatus,
+    Load,
+    NetworkIdle,
+    Point,
+    Selector,
+    Text,
+)
+from .pool import InstanceHandle, Pool
+
+try:
+    __version__ = _installed_version("sleight")
+except PackageNotFoundError:      # 从源码目录直接 import，没装进环境
+    __version__ = "0.0.0.dev0"
+
+__all__ = [  # noqa: RUF022 - 按语义分组，不按字母序
+    "__version__",
+    "connect",
+    "Pool",
+    "InstanceHandle",
+    "Session",
+    "Selectable",
+    "Element",
+    "Transport",
+    "enable_debug_logging",
+    # 拟人预设
+    "HumanProfile",
+    "FAST",
+    "DEFAULT",
+    "CAREFUL",
+    # 等待条件
+    "DomReady",
+    "Load",
+    "Text",
+    "Selector",
+    "Gone",
+    "NetworkIdle",
+    "Condition",
+    # 数据类型
+    "Point",
+    "Box",
+    "Endpoint",
+    "InstanceInfo",
+    "InstanceStatus",
+    # 异常
+    "errors",
+    "SleightError",
+    "AuthError",
+    "InstanceError",
+    "NotFound",
+    "NotReady",
+    "Busy",
+    "Crashed",
+    "SessionLost",
+    "LeaseLost",
+    "ElementError",
+]
+
+
+class _Connection:
+    """``connect()`` 的返回：一个 Session，退出时把 transport 也带走。"""
+
+    def __init__(self, transport: Transport, session: Session) -> None:
+        self._t = transport
+        self.session = session
+
+    def __enter__(self) -> Session:
+        return self.session
+
+    def __exit__(self, *exc: object) -> None:
+        try:
+            self.session.close()
+        finally:
+            self._t.close()
+
+
+def connect(url: str, *, headers: dict[str, str] | None = None, **kw: Any) -> _Connection:
+    """连一个裸 CDP 端点，**新建自有 tab**。
+
+    ``url`` 可以是 ``http://host:port``（走 ``/json/version`` 发现）或直接的
+    ``ws://…`` 浏览器级端点。
+
+    自建 tab 而不是接管既有的 —— target 顺序没有业务语义，接管等于随机修改一个
+    别人的页面。
+    """
+    if url.startswith(("ws://", "wss://")):
+        ws_url = url
+    else:
+        from .providers.plain import Plain
+
+        ep: Endpoint = Plain(url, headers=headers).endpoint()
+        ws_url = ep.ws_url
+        headers = dict(ep.headers) or headers
+
+    transport = Transport.connect(ws_url, headers=headers)
+    try:
+        return _Connection(transport, Session.create(transport, **kw))
+    except BaseException:
+        transport.close()
+        raise

sleight/_logging.py

@@ -0,0 +1,53 @@
+"""标准 ``logging``，不引入 loguru。
+
+库不配置根 logger —— 那是应用的事。这里只挂一个 ``NullHandler``，免得用户没配日志时
+Python 打印 "No handlers could be found"。
+
+调试时：
+
+    >>> import sleight
+    >>> sleight.enable_debug_logging()
+
+Logger 层级：``sleight.transport`` / ``sleight.session`` / ``sleight.input`` /
+``sleight.pool`` / ``sleight.lease`` / ``sleight.provider`` / ``sleight.cloakbrowser`` /
+``sleight.http``。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TextIO
+
+__all__ = ["enable_debug_logging"]
+
+ROOT = "sleight"
+_HANDLER_TAG = "sleight-debug"
+
+logging.getLogger(ROOT).addHandler(logging.NullHandler())
+
+
+def enable_debug_logging(level: int = logging.DEBUG, stream: TextIO | None = None) -> None:
+    """给 ``sleight.*`` 挂一个 stderr handler。仅供调试与开发使用。
+
+    **幂等** —— 重复调用只会调整级别，不会再挂一个 handler。挂两个的话每行日志
+    都会打印两遍，而这种事在 notebook 和被重复 import 的模块里太容易发生了。
+
+    凭据由 :mod:`sleight.core._redact` 在生成消息时就已脱敏，但 DEBUG 级别会打印
+    完整的 CDP 流量 —— 不要把它开在生产日志里。
+
+    :param level: 日志级别，默认 ``logging.DEBUG``
+    :param stream: 输出流。``None`` 表示 ``sys.stderr``
+    """
+    logger = logging.getLogger(ROOT)
+    logger.setLevel(level)
+    for existing in logger.handlers:
+        if getattr(existing, "name", None) == _HANDLER_TAG:
+            existing.setLevel(level)
+            return
+    handler = logging.StreamHandler(stream)
+    handler.name = _HANDLER_TAG
+    handler.setLevel(level)
+    handler.setFormatter(
+        logging.Formatter("%(asctime)s %(levelname)-7s %(name)-18s %(message)s", "%H:%M:%S")
+    )
+    logger.addHandler(handler)

sleight/core/__init__.py

@@ -0,0 +1 @@
+"""核心：协议、传输、会话、类型。不依赖任何 provider、不依赖 lease。"""

sleight/core/_http.py

@@ -0,0 +1,169 @@
+"""标准库 HTTP 客户端。
+
+为什么不用 httpx / niquests：Provider 只在 launch/status/list 时发 HTTP，频率极低，
+不需要连接池、不需要 HTTP/2。实测依赖代价 —— urllib 0 个包、httpx 6 个、niquests 7 个
+（含两个 Rust 编译扩展）。
+
+证书：httpx 并不"管理证书"，它只是捆一份 certifi 的 CA bundle。标准库的
+``ssl.create_default_context()`` 在 Windows 走系统证书存储、Linux 走 OpenSSL 默认路径，
+对公网 CA 一样能验。只有连自签证书的远程 Manager 才需要 ``ca_bundle``。
+"""
+
+from __future__ import annotations
+
+import builtins
+import http.client
+import json
+import logging
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any
+
+from ._redact import redact_url
+from .errors import AuthError, ConnectionError
+
+log = logging.getLogger("sleight.http")
+
+__all__ = ["HttpClient", "HttpResponse"]
+
+DEFAULT_TIMEOUT = 15.0
+
+
+@dataclass(frozen=True, slots=True)
+class HttpResponse:
+    status: int
+    body: Any
+    url: str = field(repr=False, default="")
+
+    @property
+    def ok(self) -> bool:
+        return 200 <= self.status < 300
+
+    @property
+    def detail(self) -> str:
+        """FastAPI 风格的 ``{"detail": "..."}``。
+
+        CloakBrowser 的 stop 对「已停止」和「id 不存在」都返回 404，**必须靠 detail
+        或 status() 才能区分**。
+        """
+        if isinstance(self.body, dict):
+            d = self.body.get("detail")
+            if isinstance(d, str):
+                return d
+        return ""
+
+
+class HttpClient:
+    """极简 JSON over HTTP 客户端。
+
+    非 2xx **不抛异常**（401/403 除外）—— provider 需要自己解读 409/404，
+    生命周期语义无法从状态码通用推导。
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        ca_bundle: str | None = None,
+        verify: bool = True,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.headers = dict(headers or {})
+        self.timeout = timeout
+        self._ctx = self._build_ssl_context(ca_bundle, verify)
+
+    @staticmethod
+    def _build_ssl_context(ca_bundle: str | None, verify: bool) -> ssl.SSLContext | None:
+        if not verify:
+            ctx = ssl.create_default_context()
+            ctx.check_hostname = False
+            ctx.verify_mode = ssl.CERT_NONE
+            return ctx
+        if ca_bundle:
+            return ssl.create_default_context(cafile=ca_bundle)
+        return None  # urllib 用默认上下文
+
+    # ------------------------------------------------------------------ #
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        params: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> HttpResponse:
+        """发一个请求。**所有出站 HTTP 都从这里走** —— 打桩只需要盯这一个入口。
+
+        :param method: HTTP 方法，大小写不敏感
+        :param path: 相对 :attr:`base_url` 的路径，要带前导 ``/``
+        :param json_body: 给了就序列化成 JSON body 并加 ``Content-Type``
+        :param params: query 参数
+        :param timeout: 覆盖本次请求的超时，秒。``None`` 用构造时的默认值
+        :returns: :class:`HttpResponse`。**非 2xx 不抛异常**（401/403 除外）
+        :raises AuthError: 401 / 403
+        :raises ConnectionError: 连不上、超时、传输中断
+        """
+        url = self.base_url + path
+        if params:
+            url = f"{url}?{urllib.parse.urlencode(params)}"
+
+        data: bytes | None = None
+        headers = dict(self.headers)
+        if json_body is not None:
+            data = json.dumps(json_body).encode()
+            headers["Content-Type"] = "application/json"
+        headers.setdefault("Accept", "application/json")
+
+        req = urllib.request.Request(url, data=data, headers=headers, method=method.upper())
+        try:
+            with urllib.request.urlopen(
+                req, timeout=timeout or self.timeout, context=self._ctx
+            ) as resp:
+                return HttpResponse(resp.status, _parse(resp.read(), resp.headers), url)
+        except urllib.error.HTTPError as exc:
+            resp = HttpResponse(exc.code, _parse(exc.read(), exc.headers), url)
+            if exc.code in (401, 403):
+                suffix = f": {resp.detail}" if resp.detail else ""
+                raise AuthError(f"{exc.code} from {redact_url(url)}{suffix}") from exc
+            return resp
+        except urllib.error.URLError as exc:
+            raise ConnectionError(f"cannot reach {redact_url(url)}: {exc.reason}") from exc
+        except builtins.TimeoutError as exc:  # socket timeout（注意不是本包的 TimeoutError）
+            raise ConnectionError(f"timed out talking to {redact_url(url)}") from exc
+        except (http.client.HTTPException, OSError) as exc:
+            # urllib 只在它自己的内层 try 里包 URLError；`h.getresponse()` 期间断连会原样
+            # 逃逸成 http.client.RemoteDisconnected / ConnectionResetError，绕过整个
+            # SleightError 体系，调用方的 except 一个都接不住。
+            raise ConnectionError(f"lost connection to {redact_url(url)}: {exc}") from exc
+
+    def get(self, path: str, **kw: Any) -> HttpResponse:
+        return self.request("GET", path, **kw)
+
+    def post(self, path: str, **kw: Any) -> HttpResponse:
+        return self.request("POST", path, **kw)
+
+    def put(self, path: str, **kw: Any) -> HttpResponse:
+        return self.request("PUT", path, **kw)
+
+    def delete(self, path: str, **kw: Any) -> HttpResponse:
+        return self.request("DELETE", path, **kw)
+
+
+def _parse(raw: bytes, headers: Any) -> Any:
+    if not raw:
+        return None
+    ctype = (headers.get("Content-Type") or "").lower() if headers else ""
+    text = raw.decode("utf-8", errors="replace")
+    if "json" in ctype:
+        try:
+            return json.loads(text)
+        except ValueError:
+            return text
+    return text

sleight/core/_redact.py

@@ -0,0 +1,44 @@
+"""日志与异常里的凭据脱敏。
+
+dataclass 的默认 repr 会把 ``Authorization: Bearer ...`` 原样打进 traceback，
+所有携带凭据的字段必须 ``repr=False``，所有对外可见的字符串走这里过一遍。
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = ["redact", "redact_url"]
+
+_SENSITIVE_QUERY = re.compile(r"([?&](?:token|api_?key|access_token|auth|password|secret)=)([^&#]+)", re.I)
+_BEARER = re.compile(r"(Bearer\s+)([A-Za-z0-9._\-]{8,})", re.I)
+
+
+def _mask(value: str) -> str:
+    """保留头尾各 3 个字符，够人肉比对，不够复用。"""
+    if len(value) <= 8:
+        return "***"
+    return f"{value[:3]}…{value[-3:]}"
+
+
+def redact(text: str) -> str:
+    """对任意字符串做尽力脱敏（Bearer token + URL query 里的凭据）。
+
+    :param text: 任意文本，通常是即将进日志或异常消息的字符串
+    :returns: 敏感片段替换成 ``头3…尾3``（长度 ≤ 8 的整个换成 ``***``）
+    """
+    text = _BEARER.sub(lambda m: m.group(1) + _mask(m.group(2)), text)
+    return _SENSITIVE_QUERY.sub(lambda m: m.group(1) + _mask(m.group(2)), text)
+
+
+def redact_url(url: str) -> str:
+    """URL 专用：去掉 userinfo，遮蔽 query 里的凭据。
+
+    异常消息里不出现完整 WS URL —— 它可能整条就是凭据。
+
+    :param url: 完整 URL
+    :returns: userinfo 段换成 ``***``，query 里的 token/api_key 等遮蔽掉
+    """
+    url = re.sub(r"://([^/@]+)@", "://***@", url)
+    return _SENSITIVE_QUERY.sub(lambda m: m.group(1) + _mask(m.group(2)), url)
+

sleight/core/element.py

@@ -0,0 +1,219 @@
+"""Element：几何 + 命中校验。
+
+作用域限制（有意为之）：**只支持主 frame 的普通 DOM**。不支持 iframe、OOPIF，
+不穿透 Shadow DOM。需要这些就用 Playwright。
+
+定位方式是 selector + index 而不是 CDP 的 ``nodeId``/``objectId``：省掉一整套节点
+生命周期管理，代价是 DOM 变动后同一个 Element 可能指向不同节点。对驱动层够用；
+每次取几何都会重新解析，所以拿到的 box 一定是当下的。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from .errors import ElementError
+from .types import Box
+
+if TYPE_CHECKING:
+    from .session import Session
+
+__all__ = ["Element"]
+
+
+class Element:
+    __slots__ = ("_session", "index", "selector")
+
+    def __init__(self, session: Session, selector: str, index: int = 0) -> None:
+        self._session = session
+        self.selector = selector
+        self.index = index
+
+    def __repr__(self) -> str:
+        at = f"[{self.index}]" if self.index else ""
+        return f"<Element {self.selector!r}{at}>"
+
+    # ------------------------------------------------------------------ #
+    # JS 侧的元素引用
+    # ------------------------------------------------------------------ #
+
+    @property
+    def js_ref(self) -> str:
+        """解析到该元素的 JS 表达式。
+
+        用 ``json.dumps`` 而不是 Python 的 ``repr`` —— repr 走 Python 的引号与转义
+        规则，遇到反斜杠、引号、非 ASCII 会产出不合法或语义不同的 JS 字面量。
+        ``json.dumps`` 产出的恰好是合法 JS 字符串字面量。
+        """
+        return f"document.querySelectorAll({json.dumps(self.selector)})[{self.index}]"
+
+    def _eval(self, body: str) -> Any:
+        """在 ``el`` 绑定到本元素的作用域里求值。元素不存在时 body 不执行。"""
+        return self._session.eval(
+            f"(() => {{ const el = {self.js_ref}; if (!el) return null; {body} }})()"
+        )
+
+    # ------------------------------------------------------------------ #
+    # 查询
+    # ------------------------------------------------------------------ #
+
+    def exists(self) -> bool:
+        """选择器现在还能命中这个元素吗？"""
+        return bool(self._eval("return true;"))
+
+    def box(self) -> Box | None:
+        """``getBoundingClientRect()`` 的原值，viewport CSS 像素。
+
+        不乘 devicePixelRatio，不加 scroll 偏移 —— CDP Input 用的就是这个坐标系。
+
+        :returns: 元素几何；元素已经不在了返回 ``None``
+        """
+        raw = self._eval(
+            "const r = el.getBoundingClientRect();"
+            " return {x: r.x, y: r.y, w: r.width, h: r.height};"
+        )
+        return Box(**raw) if raw else None
+
+    def require_box(self) -> Box:
+        """同 :meth:`box`，但拿不到就抛。
+
+        :raises ElementError: 元素不存在，或宽高为 0（多半是被 CSS 隐藏了）
+        """
+        box = self.box()
+        if box is None:
+            raise ElementError(f"no element matches {self.selector!r}[{self.index}]")
+        if box.empty:
+            raise ElementError(f"{self!r} has zero size ({box.w}x{box.h}); is it hidden?")
+        return box
+
+    def text(self) -> str:
+        """元素的 ``innerText``。元素不在了返回空串。"""
+        return self._eval("return el.innerText;") or ""
+
+    def attr(self, name: str) -> str | None:
+        """读一个 HTML 属性。
+
+        :param name: 属性名，会经 ``json.dumps`` 转义后拼进 JS
+        :returns: 属性值；属性不存在或元素不在了返回 ``None``
+        """
+        return self._eval(f"return el.getAttribute({json.dumps(name)});")
+
+    def object_id(self) -> str:
+        """拿一个 CDP ``Runtime.RemoteObject`` 句柄，给 ``DOM.*`` 命令用。
+
+        **调用方负责 ``Runtime.releaseObject``** —— 不释放会把节点钉在内存里。
+        平时不需要它：读几何走 ``Runtime.evaluate`` 更简单，也不用维护 nodeId 生命周期。
+
+        :returns: 可传给 ``DOM.*`` 命令的 ``objectId``
+        :raises ElementError: 元素不存在
+        """
+        result = self._session.call(
+            "Runtime.evaluate", {"expression": self.js_ref, "returnByValue": False}
+        )
+        remote = result.get("result") or {}
+        if not (object_id := remote.get("objectId")):
+            raise ElementError(f"no element matches {self.selector!r}[{self.index}]")
+        return object_id
+
+    def in_viewport(self) -> bool:
+        """元素当前是否有一部分落在视口内，且宽高都不为 0。
+
+        滚动是否到位的判据就是它 —— 不能用"垂直偏移为 0"，那对横向出界的元素
+        会误判成成功。
+        """
+        return bool(
+            self._eval(
+                "const r = el.getBoundingClientRect();"
+                " return r.bottom > 0 && r.right > 0"
+                " && r.top < innerHeight && r.left < innerWidth"
+                " && r.width > 0 && r.height > 0;"
+            )
+        )
+
+    def scroll_metrics(self) -> dict[str, float]:
+        """``{top, bottom, height}``，供 :class:`~sleight.core.input.InputDriver`
+        计算还要滚多远。``height`` 是视口高度，不是元素高度。
+
+        :raises ElementError: 元素不存在
+        """
+        raw = self._eval(
+            "const r = el.getBoundingClientRect();"
+            " return {top: r.top, bottom: r.bottom, height: innerHeight};"
+        )
+        if raw is None:
+            raise ElementError(f"{self!r} no longer exists")
+        return raw
+
+    # ------------------------------------------------------------------ #
+    # 命中校验 —— 每次点击前后各做一次
+    # ------------------------------------------------------------------ #
+
+    def hit_test(self, x: int, y: int) -> bool:
+        """(x, y) 处最上层的元素是不是本元素或其后代。
+
+        false 说明被遮挡（cookie 弹窗、fixed 头部、遮罩层）。不做这步的症状是
+        "点了但没反应"，排查极费时间。
+
+        :param x: viewport CSS 像素
+        :param y: viewport CSS 像素
+        """
+        return bool(
+            self._eval(
+                f"const hit = document.elementFromPoint({x}, {y});"
+                " return !!hit && (hit === el || el.contains(hit));"
+            )
+        )
+
+    def has_focus(self) -> bool:
+        """本元素或其后代是不是 ``document.activeElement``。"""
+        return bool(
+            self._eval(
+                "return document.activeElement === el"
+                " || el.contains(document.activeElement);"
+            )
+        )
+
+    def require_focus(self, *, after: str) -> None:
+        """确认焦点真的落在本元素上。
+
+        点击只保证**几何命中**（``elementFromPoint``），不保证元素可聚焦：点一个
+        ``<div>`` 会让焦点留在原处，随后的键盘事件全打给上一个焦点元素。这在
+        ``type(clear=True)`` 下尤其危险 —— Ctrl+A + Backspace 会清空**别的**输入框。
+
+        :param after: 出现在报错消息里的一句话，说明是在哪一步之后检查的，
+            例如 ``"the focusing click"``
+        :raises ElementError: 焦点不在本元素上；消息里会带上真正的 activeElement
+        """
+        if self.has_focus():
+            return
+        active = self._session.eval(
+            "(() => { const a = document.activeElement;"
+            " return a ? a.tagName.toLowerCase() + (a.id ? '#' + a.id : '') : null; })()"
+        )
+        raise ElementError(
+            f"{self!r} does not have focus {after}"
+            f"{f'; document.activeElement is <{active}>' if active else ''}"
+            " — is it focusable?"
+        )
+
+    def require_hit(self, x: int, y: int, *, when: str) -> None:
+        """同 :meth:`hit_test`，但没命中就抛，并在消息里点名挡住它的元素。
+
+        :param x: 要探的 viewport 坐标
+        :param y: 要探的 viewport 坐标
+        :param when: 出现在报错消息里的时机描述，例如 ``"before moving there"``
+        :raises ElementError: 该点最上层的不是本元素
+        """
+        if not self.hit_test(x, y):
+            blocker = self._session.eval(
+                f"(() => {{ const h = document.elementFromPoint({x}, {y});"
+                " return h ? (h.tagName.toLowerCase()"
+                " + (h.id ? '#' + h.id : '')"
+                " + (h.className && typeof h.className === 'string'"
+                "    ? '.' + h.className.trim().split(/\\s+/).join('.') : '')) : null; })()"
+            )
+            raise ElementError(
+                f"{self!r} is covered at ({x}, {y}) {when}"
+                f"{f'; topmost element is <{blocker}>' if blocker else ''}"
+            )