dp-cli 0.3.2__tar.gz → 0.4.0__tar.gz

{dp_cli-0.3.2 → dp_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dp-cli
-Version: 0.3.2
+Version: 0.4.0
 Summary: A powerful CLI for DrissionPage — browser automation, structured data extraction, network listening and more.
 License: BSD-3-Clause
 Project-URL: Homepage, https://github.com/mofanx/dp-cli
@@ -31,7 +31,8 @@ A powerful CLI for [DrissionPage](https://github.com/g1879/DrissionPage) — bro
   and custom menu items the a11y tree misses; every element gets an `[N]` ref with
   confidence markers (`⚡` medium, `?` low)
 - **`dp scan`** — fast Vimium-style listing of interactive elements (viewport-only mode available)
-- **Powerful locator syntax** — descriptive strings stable across navigation
+- **Powerful locator syntax** — descriptive strings stable across navigation, plus
+  Playwright-style `pw:role=button[name="Submit"] >> nth=2` chains
 - **Structured data extraction** — `extract` + `query` + `snapshot` for scraping list pages
 - **Network listening** — capture XHR/Fetch requests and response bodies
 - **Stealth patches** — `dp stealth` bypasses common automation detections
@@ -150,6 +151,53 @@ dp scan --confidence high       # only the sure-thing clickables
 Both `snapshot` and `scan` share the same `[N]` ref numbering per session, so
 `dp click "ref:N"` works regardless of which one produced the snapshot.
 
+## Playwright-style locators (`pw:` prefix)
+
+Need semantic, role-based targeting on a fresh page (no snapshot required)?
+Use the `pw:` prefix. Syntax mirrors Playwright, and chains with `>>`:
+
+```bash
+# By ARIA role (with accessible name — exact / substring / regex)
+dp click 'pw:role=button[name="Submit"]'
+dp click 'pw:role=button[name=/^Sign/i]'
+dp click 'pw:role=link[name=More]'         # substring
+
+# By visible text (exact / substring / regex)
+dp click 'pw:text="Login"'                 # exact
+dp click 'pw:text=Login'                   # substring (case-insensitive)
+dp click 'pw:text=/^log/i'                 # regex
+
+# By form affordances
+dp fill  'pw:placeholder=Search…' "chatgpt"
+dp fill  'pw:label="Email"' "a@b.com"
+dp click 'pw:alt="Logo"'
+dp click 'pw:title="Close"'
+dp click 'pw:testid=submit-btn'            # data-testid / data-test-id / data-test
+
+# Chain with >> (each step narrows the scope)
+dp click 'pw:css=.sidebar >> role=listitem[name="Chat"] >> nth=2'
+dp click 'pw:css=li >> has-text="Python"'
+dp click 'pw:role=list >> nth=-1'          # negative index = from end
+
+# Raw css/xpath chunks mix freely
+dp click 'pw:xpath=//nav >> role=link[name=Docs]'
+```
+
+**Matchers**: `role` / `text` / `label` / `placeholder` / `alt` / `title` /
+`testid` / `css` / `xpath` / `nth` / `has-text` / `visible`
+
+**Value forms**: `bare` = substring, `"quoted"` = exact, `/pattern/flags` = regex
+
+**Visibility**: `role` / `text` / `has-text` automatically skip elements hidden
+via `display:none`, `visibility:hidden`, `hidden` attribute, or
+`aria-hidden="true"` (matches Playwright semantics).
+
+**Shadow DOM**: open shadow roots are traversed automatically.
+
+Under the hood the matcher chain is evaluated in-page as JS, the target element
+is tagged with a one-shot `data-dp-ref` attribute, and DrissionPage resolves it
+by that attribute — bypassing stale classes / CSS Modules / dynamic XPath.
+
 ## Anti-Detection (stealth)
 
 Bypass `navigator.webdriver`, `HeadlessChrome` UA, empty `plugins`, SwiftShader WebGL,

{dp_cli-0.3.2 → dp_cli-0.4.0}/README.md

@@ -10,7 +10,8 @@ A powerful CLI for [DrissionPage](https://github.com/g1879/DrissionPage) — bro
   and custom menu items the a11y tree misses; every element gets an `[N]` ref with
   confidence markers (`⚡` medium, `?` low)
 - **`dp scan`** — fast Vimium-style listing of interactive elements (viewport-only mode available)
-- **Powerful locator syntax** — descriptive strings stable across navigation
+- **Powerful locator syntax** — descriptive strings stable across navigation, plus
+  Playwright-style `pw:role=button[name="Submit"] >> nth=2` chains
 - **Structured data extraction** — `extract` + `query` + `snapshot` for scraping list pages
 - **Network listening** — capture XHR/Fetch requests and response bodies
 - **Stealth patches** — `dp stealth` bypasses common automation detections
@@ -129,6 +130,53 @@ dp scan --confidence high       # only the sure-thing clickables
 Both `snapshot` and `scan` share the same `[N]` ref numbering per session, so
 `dp click "ref:N"` works regardless of which one produced the snapshot.
 
+## Playwright-style locators (`pw:` prefix)
+
+Need semantic, role-based targeting on a fresh page (no snapshot required)?
+Use the `pw:` prefix. Syntax mirrors Playwright, and chains with `>>`:
+
+```bash
+# By ARIA role (with accessible name — exact / substring / regex)
+dp click 'pw:role=button[name="Submit"]'
+dp click 'pw:role=button[name=/^Sign/i]'
+dp click 'pw:role=link[name=More]'         # substring
+
+# By visible text (exact / substring / regex)
+dp click 'pw:text="Login"'                 # exact
+dp click 'pw:text=Login'                   # substring (case-insensitive)
+dp click 'pw:text=/^log/i'                 # regex
+
+# By form affordances
+dp fill  'pw:placeholder=Search…' "chatgpt"
+dp fill  'pw:label="Email"' "a@b.com"
+dp click 'pw:alt="Logo"'
+dp click 'pw:title="Close"'
+dp click 'pw:testid=submit-btn'            # data-testid / data-test-id / data-test
+
+# Chain with >> (each step narrows the scope)
+dp click 'pw:css=.sidebar >> role=listitem[name="Chat"] >> nth=2'
+dp click 'pw:css=li >> has-text="Python"'
+dp click 'pw:role=list >> nth=-1'          # negative index = from end
+
+# Raw css/xpath chunks mix freely
+dp click 'pw:xpath=//nav >> role=link[name=Docs]'
+```
+
+**Matchers**: `role` / `text` / `label` / `placeholder` / `alt` / `title` /
+`testid` / `css` / `xpath` / `nth` / `has-text` / `visible`
+
+**Value forms**: `bare` = substring, `"quoted"` = exact, `/pattern/flags` = regex
+
+**Visibility**: `role` / `text` / `has-text` automatically skip elements hidden
+via `display:none`, `visibility:hidden`, `hidden` attribute, or
+`aria-hidden="true"` (matches Playwright semantics).
+
+**Shadow DOM**: open shadow roots are traversed automatically.
+
+Under the hood the matcher chain is evaluated in-page as JS, the target element
+is tagged with a one-shot `data-dp-ref` attribute, and DrissionPage resolves it
+by that attribute — bypassing stale classes / CSS Modules / dynamic XPath.
+
 ## Anti-Detection (stealth)
 
 Bypass `navigator.webdriver`, `HeadlessChrome` UA, empty `plugins`, SwiftShader WebGL,

{dp_cli-0.3.2 → dp_cli-0.4.0}/dp_cli/commands/_utils.py

@@ -75,7 +75,7 @@ def _get_page(session: str, raw: bool = False):
 
 
 _KNOWN_PREFIX = re.compile(
-    r'^(css[:=]|xpath[:=]|text[:=^$]|tag[:=^$]|@@?[\w]|ref:)', re.IGNORECASE)
+    r'^(css[:=]|xpath[:=]|text[:=^$]|tag[:=^$]|@@?[\w]|ref:|pw:)', re.IGNORECASE)
 _CSS_ID_CLASS = re.compile(r'^[#.][\w-]')           # #id  .class
 _CSS_TAG_SEL = re.compile(r'^[\w-]+[.#\[][\w-]')   # div.class  a[href]  h1#title
 _CSS_COMBINATOR = re.compile(r'[\[>+~]|::|:(?:nth|first|last|not|has)')  # [attr] > + ~ ::pseudo :nth-child
@@ -145,17 +145,58 @@ def _mark_element_by_backend_id(page, backend_node_id: int) -> str:
     return marker
 
 
-def resolve_locator(locator: str, session: str = 'default', page=None) -> str:
-    """解析定位器：ref:N 展开 + 智能前缀补全。
+def _resolve_pw(expr: str, session: str, page) -> str:
+    """解析 pw: 表达式 → 在页面上打标 → 返回 @data-dp-ref=<marker>。
+
+    失败（语法错 / 未匹配 / 浏览器不可用）会调用 error 并退出。
+    """
+    from dp_cli.locators import parse_pw, build_pw_js, PwParseError
+    try:
+        matchers = parse_pw(expr)
+    except PwParseError as e:
+        error(f'pw 定位器语法错误: {e}', code='PW_SYNTAX')
+        raise SystemExit(1)
 
-    如果 locator 以 'ref:' 开头，从 session 的 refs 映射中查找。
-      - 有 backendNodeId 时：通过 CDP 现场打临时属性，返回 @data-dp-ref=<marker>
-        （最鲁棒，绕开 CSS Modules / 动态 class / xpath 变化）
-      - 无 backendNodeId 或打标失败时：回落到保存的 locator 字符串
-      - 再失败，用 name 作 text 定位器
+    if page is None:
+        try:
+            page = _get_page(session)
+        except SystemExit:
+            raise
+        except Exception as e:
+            error('无法连接浏览器会话', code='SESSION_NOT_FOUND', detail=str(e))
+            raise SystemExit(1)
+
+    js = build_pw_js(matchers)
+    try:
+        marker = page.run_js(js)
+    except Exception as e:
+        error(f'pw 定位器求值失败', code='PW_EVAL_FAILED', detail=str(e))
+        raise SystemExit(1)
+
+    if not marker:
+        error(f'pw 定位器未匹配到元素: pw:{expr}', code='PW_NOT_FOUND')
+        raise SystemExit(1)
+
+    return f'@data-dp-ref={marker}'
+
+
+def resolve_locator(locator: str, session: str = 'default', page=None) -> str:
+    """解析定位器：ref:N 展开 + pw: 表达式求值 + 智能前缀补全。
+
+    - pw:<expr>：Playwright 风格（role/text/label/placeholder/alt/title/
+      testid/css/xpath/nth/has-text/visible），支持 >> 链式。通过 JS 求值
+      + 打标，返回 @data-dp-ref=<marker>。
+    - ref:N：从 session 的 refs 映射中查找。
+        · 有 backendNodeId 时：通过 CDP 现场打临时属性，返回 @data-dp-ref=
+          （最鲁棒，绕开 CSS Modules / 动态 class / xpath 变化）
+        · 无 backendNodeId 或打标失败时：回落到保存的 locator 字符串
+        · 再失败，用 name 作 text 定位器
+    - 其它：智能补全 css:/xpath: 前缀。
 
     :param page: 可选，传入避免内部再调用 _get_page；为 None 时按需懒加载。
     """
+    if locator.startswith('pw:'):
+        return _resolve_pw(locator[3:], session, page)
     if not locator.startswith('ref:'):
         return normalize_locator(locator)
 

dp_cli-0.4.0/dp_cli/locators/__init__.py

@@ -0,0 +1,9 @@
+# -*- coding:utf-8 -*-
+"""Playwright 风格定位器（pw: 前缀）。
+
+模块入口只暴露最常用的 API：
+  - parse_pw(expr): 解析 'css=.btn >> role=button[name="OK"]' → matcher 列表
+  - build_pw_js(matchers): 把 matcher 列表转成可执行的 JS 脚本
+"""
+from .playwright import parse_pw, PwParseError  # noqa: F401
+from .pw_js import build_pw_js  # noqa: F401

dp_cli-0.4.0/dp_cli/locators/playwright.py

@@ -0,0 +1,236 @@
+# -*- coding:utf-8 -*-
+"""Playwright 风格定位器解析器（纯 Python，不依赖浏览器）。
+
+输入：去掉 'pw:' 前缀的表达式字符串，例如
+  css=.sidebar >> role=listitem[name="Chat"] >> nth=2
+  role=button[name=/^Sign/i]
+  text="Login" >> has-text="今天"
+
+输出：matcher 列表（list[dict]），交给 JS 逐段求值。
+
+matcher dict 结构示例：
+  {'type': 'role', 'role': 'button',
+   'name': {'kind': 'exact', 'value': 'Submit'}}     # 或 None
+  {'type': 'text',  'value': {'kind': 'substr', 'value': 'Login'}}
+  {'type': 'label', 'value': {'kind': 'exact', 'value': 'Email'}}
+  {'type': 'placeholder', 'value': {'kind': 'substr', 'value': 'search'}}
+  {'type': 'alt' | 'title' | 'testid', 'value': {...}}
+  {'type': 'css',   'value': '.btn'}
+  {'type': 'xpath', 'value': '//div[@id="foo"]'}
+  {'type': 'nth',   'index': 2}
+  {'type': 'has-text', 'value': {'kind': 'substr', 'value': 'Price'}}
+  {'type': 'visible', 'value': True}
+
+值规格（value spec）：
+  {'kind': 'exact',  'value': 'Submit'}                 # "Submit" / 'Submit'
+  {'kind': 'substr', 'value': 'Sub'}                    # Submit（裸值）
+  {'kind': 'regex',  'value': '^Sign', 'flags': 'i'}    # /^Sign/i
+"""
+import re
+
+
+class PwParseError(ValueError):
+    """pw: 表达式语法错误。"""
+
+
+# 允许的顶层 chunk 类型（不含 >> 分段符）
+_VALUE_TYPES = (
+    'text', 'label', 'placeholder', 'alt', 'title', 'testid', 'has-text'
+)
+_RAW_TYPES = ('css', 'xpath')  # 保留原值，不再解析
+_ALL_TYPES = _VALUE_TYPES + _RAW_TYPES + ('role', 'nth', 'visible')
+
+
+def parse_pw(expr: str) -> list:
+    """把 pw: 表达式解析为 matcher 列表。
+
+    :raises PwParseError: 语法非法
+    """
+    if not expr or not expr.strip():
+        raise PwParseError('空的 pw 表达式')
+    chunks = _split_chunks(expr)
+    if not chunks:
+        raise PwParseError(f'未找到有效的 chunk: {expr!r}')
+    return [_parse_chunk(c) for c in chunks]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# chunk 切分：按 ' >> ' 分段，尊重引号和正则字面量
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _split_chunks(expr: str) -> list:
+    """把表达式按 >> 切成若干 chunk。
+
+    规则：
+      - 引号（' / "）内的 >> 不切
+      - 正则字面量 /.../[flags] 内的 >> 不切
+      - >> 前后可以有空格，也可以没有（但建议有）
+    """
+    parts = []
+    buf = []
+    i = 0
+    n = len(expr)
+    in_quote = None  # None | '"' | "'"
+    in_regex = False
+    while i < n:
+        c = expr[i]
+        if in_quote:
+            buf.append(c)
+            # 处理反斜杠转义
+            if c == '\\' and i + 1 < n:
+                buf.append(expr[i + 1])
+                i += 2
+                continue
+            if c == in_quote:
+                in_quote = None
+            i += 1
+            continue
+        if in_regex:
+            buf.append(c)
+            if c == '\\' and i + 1 < n:
+                buf.append(expr[i + 1])
+                i += 2
+                continue
+            if c == '/':
+                # 结束正则，继续吃 flags
+                j = i + 1
+                while j < n and expr[j].isalpha():
+                    buf.append(expr[j])
+                    j += 1
+                in_regex = False
+                i = j
+                continue
+            i += 1
+            continue
+        # 非引号、非正则态
+        if c in ('"', "'"):
+            in_quote = c
+            buf.append(c)
+            i += 1
+            continue
+        # 识别正则起始：=/.../ 这种，简化判断为前一个非空字符是 =
+        if c == '/':
+            # 往前看非空格字符
+            k = len(buf) - 1
+            while k >= 0 and buf[k] == ' ':
+                k -= 1
+            if k >= 0 and buf[k] == '=':
+                in_regex = True
+                buf.append(c)
+                i += 1
+                continue
+        if c == '>' and i + 1 < n and expr[i + 1] == '>':
+            parts.append(''.join(buf).strip())
+            buf = []
+            i += 2
+            continue
+        buf.append(c)
+        i += 1
+
+    if in_quote:
+        raise PwParseError(f'引号未闭合: {expr!r}')
+    if in_regex:
+        raise PwParseError(f'正则字面量未闭合: {expr!r}')
+
+    tail = ''.join(buf).strip()
+    if tail:
+        parts.append(tail)
+    return [p for p in parts if p]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 单个 chunk 解析
+# ─────────────────────────────────────────────────────────────────────────────
+
+_ROLE_RE = re.compile(r'^role=([a-zA-Z][\w-]*)(.*)$')
+_ROLE_NAME_RE = re.compile(r'^\[name=(.+)\]$')
+_NTH_RE = re.compile(r'^nth=(-?\d+)$')
+
+
+def _parse_chunk(chunk: str) -> dict:
+    s = chunk.strip()
+    if not s:
+        raise PwParseError('空 chunk')
+
+    # visible / visible=true / visible=false
+    if s == 'visible' or s == 'visible=true':
+        return {'type': 'visible', 'value': True}
+    if s == 'visible=false':
+        return {'type': 'visible', 'value': False}
+
+    # nth=N
+    m = _NTH_RE.match(s)
+    if m:
+        return {'type': 'nth', 'index': int(m.group(1))}
+
+    # role=X 或 role=X[name=...]
+    m = _ROLE_RE.match(s)
+    if m:
+        role = m.group(1)
+        rest = m.group(2).strip()
+        if not rest:
+            return {'type': 'role', 'role': role, 'name': None}
+        nm = _ROLE_NAME_RE.match(rest)
+        if not nm:
+            raise PwParseError(
+                f'role= 后只支持 [name=...] 过滤: {chunk!r}')
+        name_spec = _parse_value(nm.group(1))
+        return {'type': 'role', 'role': role, 'name': name_spec}
+
+    # 文本类过滤：text= / label= / placeholder= / alt= / title= / testid= / has-text=
+    for t in _VALUE_TYPES:
+        prefix = t + '='
+        if s.startswith(prefix):
+            spec = _parse_value(s[len(prefix):])
+            return {'type': t, 'value': spec}
+
+    # css= / xpath=：原样保留
+    for t in _RAW_TYPES:
+        prefix = t + '='
+        if s.startswith(prefix):
+            raw = s[len(prefix):].strip()
+            if not raw:
+                raise PwParseError(f'{t}= 后面不能为空: {chunk!r}')
+            return {'type': t, 'value': raw}
+
+    raise PwParseError(
+        f'无法识别的 pw chunk: {chunk!r}；'
+        f'合法类型: {", ".join(_ALL_TYPES)}')
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 值规格解析（value spec）
+# ─────────────────────────────────────────────────────────────────────────────
+
+_REGEX_RE = re.compile(r'^/(.+)/([a-z]*)$', re.DOTALL)
+
+
+def _parse_value(raw: str) -> dict:
+    """解析值字符串。
+
+    规则（按优先级）：
+      "..." 或 '...'     → exact 精确匹配，支持 \\ 转义引号
+      /pattern/[flags]   → regex 正则（Playwright 风格）
+      其它（裸值）        → substr 子串匹配
+    """
+    s = raw.strip()
+    if not s:
+        raise PwParseError('值不能为空')
+    # 引号包裹 → exact
+    if len(s) >= 2 and s[0] == s[-1] and s[0] in ('"', "'"):
+        inner = s[1:-1]
+        # 去反斜杠转义
+        inner = inner.replace('\\' + s[0], s[0]).replace('\\\\', '\\')
+        return {'kind': 'exact', 'value': inner}
+    # /re/flags → regex
+    m = _REGEX_RE.match(s)
+    if m:
+        pattern = m.group(1)
+        flags = m.group(2) or ''
+        # 校验 flags（JS 允许的）
+        for f in flags:
+            if f not in 'gimsuy':
+                raise PwParseError(f'非法的正则 flag: {f!r} in {raw!r}')
+        return {'kind': 'regex', 'value': pattern, 'flags': flags}
+    # 裸值 → substr
+    return {'kind': 'substr', 'value': s}