Metadata-Version: 2.5
Name: ysbrowser-sdk
Version: 0.11.2
Summary: Versioned sync and async Python SDK for YSbrowser context configuration, diagnostics and mouse trajectories
Project-URL: Documentation, https://selfshore.github.io/YSbrowser/sdk/0.11.2/README.html
Project-URL: Homepage, https://github.com/selfshore/YSbrowser
Project-URL: Issues, https://github.com/selfshore/YSbrowser/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy<3,>=1.26
Requires-Dist: onnxruntime<2,>=1.17
Requires-Dist: patchright==1.64.2
Requires-Dist: py7zr<2,>=1.1
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: psutil<8,>=6; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: twine<8,>=7; extra == 'dev'
Description-Content-Type: text/markdown

# Windows / Linux compatibility in 0.11.2

One `py3-none-any` wheel supports Windows and Linux with the same sync and async API.
Omit `server_gpu_backend` for host defaults: WARP on Windows, Mesa llvmpipe on Linux.
Explicit backends are validated before launch. Windows supports warp/swiftshader;
Linux supports llvmpipe/native/software/swiftshader. Paths refer to the host running Python.

Install a native custom YSBrowser and pass its executable_path, or register one with
the SDK archive installer. Windows keeps its built-in release URL. Linux requires
an explicit native .zip/.7z URL or YSBROWSER_LINUX_BROWSER_URL; an absent Linux URL
never falls back to downloading Windows Chrome. The Python wheel does not bundle Chromium.
Linux deployments need the native Chromium shared-library, font and sandbox runtime
dependencies. WSLg supplies Windows desktop display/audio for a Linux process.

```python
from ysbrowser_sdk.sync_api import YSBrowser
# Windows: executable_path="./browser/chrome.exe"
# Linux: executable_path="./browser/chrome"
with YSBrowser(headless=True) as browser:
    context = browser.new_context()
    page = context.new_page()
    page.set_content("<h1>YSBrowser</h1>")
```

The remaining reference below also contains Windows-specific path examples.

# YSbrowser SDK 0.11.2

配套 YSbrowser 定制浏览器的 Windows / Linux Python SDK，支持同步/异步调用、Context 配置、代理、状态保存和模型鼠标操作。

- [完整使用手册（含代码高亮与全文搜索）](https://selfshore.github.io/YSbrowser/sdk/0.11.2/README.html)
- [drag_element 每个参数和返回结构](https://selfshore.github.io/YSbrowser/sdk/0.11.2/drag-element.html)

## 安装

```powershell
pip install ysbrowser-sdk
python -m ysbrowser_sdk install
```

Python >= 3.10；依赖 Patchright 1.64.2、NumPy 和 ONNX Runtime。默认下载内置的 [YSBrowser 6.2](https://github.com/selfshore/YSbrowser/releases/download/6.2/chrome.7z)；需要其他版本时，可用 `--url` 显式指定压缩包直链。浏览器默认安装到当前目录的 ./browsers，下载压缩包在解压完成后删除。推理不需要 PyTorch。

## 使用

```python
from ysbrowser_sdk.sync_api import YSBrowser

with YSBrowser(headless=False) as browser:
    context = browser.new_context()
    page = context.new_page()
    page.set_content('<button style="position:absolute;left:700px;top:300px">目标</button>')
    mouse = context.mouse(page)
    result = mouse.move_between(100, 200, 500, 300)
    result = mouse.click_element(page.get_by_role("button", name="目标"))
    print(result.plan.model_id, result.plan.data_source)
```

异步代码从 `ysbrowser_sdk.async_api` 导入，在浏览器操作前加 await。

- [鼠标完整 API](https://selfshore.github.io/YSbrowser/sdk/0.11.2/mouse.html)
- [Context 与代理](https://selfshore.github.io/YSbrowser/sdk/0.11.2/proxy.html)
- [Context 参数及诊断](https://selfshore.github.io/YSbrowser/sdk/0.11.2/context-options.html)
- [代理切换](https://selfshore.github.io/YSbrowser/sdk/0.11.2/proxy.html)
- [A 点到 B 点的可运行示例](https://selfshore.github.io/YSbrowser/sdk/0.11.2/examples/mouse_between.py)
- [拖动示例](https://selfshore.github.io/YSbrowser/sdk/0.11.2/examples/mouse_drag.py)

鼠标使用随包条件 Flow Matching Transformer。`move()`、`move_to()` 为绝对坐标，`move_by()` 为相对距离，`move_between()` 指定起终点。省略 duration_s 自动预测运动时长。原生 page.mouse 和 Locator 保持原生调用方式，模型操作通过 context.mouse(page) 使用。
