Metadata-Version: 2.4
Name: antbrowser
Version: 1.0.0
Summary: Python SDK for the Ant Browser daemon
Author: Ant Browser
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/black-ant/Ant-Browser
Project-URL: Repository, https://github.com/black-ant/Ant-Browser
Project-URL: Documentation, https://github.com/black-ant/Ant-Browser/tree/master/packages/ant-browser-py/docs
Project-URL: Issues, https://github.com/black-ant/Ant-Browser/issues
Keywords: browser-automation,chromium,fingerprint-browser,headless-browser,ant-browser,android,termux
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# antbrowser

`antbrowser` 是 Ant Browser 的 Python SDK，配套 `ant-browser-daemon` 使用。

当前交付目标：

- Windows / Linux 可用
- Android / Termux 提供 `Chromium-only` 工作流
- SDK 可自动发现或拉起 daemon
- Python 既能用高层 API，也能直接调 raw HTTP API
- Windows / Linux / Android(arm64-v8a) 的 PyPI wheel 可内嵌 daemon

## Features

- 自动复用 `workspace/runtime/daemon.json`
- 找不到 daemon 时，优先找本地 binary，再回退到 `go run ./cmd/ant-browser-daemon`
- 支持 `profiles / instances / page / inspect / tls / stealth`
- 新增 `cores / proxies` 管理接口
- 支持 Termux 下直接注册 `chromium` 可执行文件
- POSIX/Termux 下会把 wheel 内嵌 daemon materialize 到 `workspace/runtime/bin/` 再启动，避免安装后缺少执行位

## Quick Example

```python
from antbrowser import AntBrowser

with AntBrowser(workspace="C:/tmp/ant-workspace") as browser:
    print(browser.runtime.info())
    print(browser.discover_system_cores())
```

## High-Level Builder Example

```python
from antbrowser import AntBrowser

with AntBrowser(workspace="C:/tmp/ant-workspace") as browser:
    result = (
        browser.new_profile("buyer-random")
        .random_environment(name_prefix="Buyer Random")
        .hardware(hardware_concurrency=8, device_memory=16)
        .anti_detect("strict")
        .create(auto_launch=True, run_mode="headless")
    )
    print(result)
```

## Core Management

```python
with AntBrowser(workspace="C:/tmp/ant-workspace") as browser:
    core = browser.ensure_core(
        "C:/Program Files/Google/Chrome/Application",
        core_name="Local Chrome",
        is_default=True,
    )
    print(core)
```

Linux / Termux 也可以直接传可执行文件路径：

```python
browser.ensure_core("/usr/bin/chromium", core_name="Chromium", is_default=True)
```

## Proxy Management

```python
with AntBrowser(workspace="C:/tmp/ant-workspace") as browser:
    proxy = browser.save_proxy(
        {
            "proxyName": "Local Proxy",
            "proxyConfig": "http://127.0.0.1:7890",
            "groupName": "local",
        }
    )
    print(proxy)
```

## Termux

参考：

- [docs/TERMUX.md](docs/TERMUX.md)
- [scripts/install_termux.sh](scripts/install_termux.sh)
- [examples/termux_chromium.py](examples/termux_chromium.py)

## Docs

- [docs/API.md](docs/API.md)
- [docs/TUTORIAL.md](docs/TUTORIAL.md)
- [docs/TERMUX.md](docs/TERMUX.md)
- [docs/VALIDATION_REPORT.md](docs/VALIDATION_REPORT.md)

## Validation

发布前可运行真实验收：

```powershell
$env:PYTHONPATH="C:\path\to\repo\packages\ant-browser-py\src"
python packages/ant-browser-py/scripts/validate_sdk.py
```

这会生成：

- `packages/ant-browser-py/docs/VALIDATION_REPORT.md`

如果你已经装了 `build` 和 `twine`，也可以直接跑一键发布前检查：

```powershell
python packages/ant-browser-py/scripts/release_prep.py
```

## PyPI Artifacts

现在 `packages/ant-browser-py/dist/` 中的 Windows / Linux / Android wheel 都是内嵌 daemon 的平台 wheel：

- `antbrowser-1.0.0-py3-none-win_amd64.whl`
- `antbrowser-1.0.0-py3-none-linux_x86_64.whl`
- `antbrowser-1.0.0-py3-none-linux_aarch64.whl`
- `antbrowser-1.0.0-py3-none-android_24_arm64_v8a.whl`

这些 wheel 安装后，不需要额外设置 `ANT_BROWSER_DAEMON_BIN` 也可以直接拉起内嵌 daemon。

Android wheel 当前定位为：

- 面向 Termux / Android arm64-v8a
- wheel tag 使用 `android_24_arm64_v8a`
- 默认按 Android 7.0+ / API 24 基线发布

如果你的 Python / pip 环境还没有暴露 Android wheel tag，仍然可以先使用：

- source distribution `antbrowser-1.0.0.tar.gz`
- 或仓库里的 Android bundle / `install_termux.sh`
