Metadata-Version: 2.4
Name: profilehub
Version: 3.1.0
Summary: ProfileHub Python SDK — thin HTTP client for ProfileHub browser environment hub
Author: duangbuduang
License: MIT
Project-URL: Homepage, https://github.com/duangbuduang/profilehub
Project-URL: Documentation, https://github.com/duangbuduang/profilehub/blob/main/docs/SDK%E5%8F%82%E8%80%83%E6%89%8B%E5%86%8C.md
Keywords: profilehub,browser-automation,cdp,cookie,multi-profile,chrome,edge
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20
Dynamic: license-file

# ProfileHub Python SDK

> ProfileHub 是本地浏览器环境中枢，管理真实 Chrome/Edge 环境（持久登录态、独立数据目录、固定 CDP 端口、Cookie 访问）。
> 本 SDK 是纯 HTTP 客户端，通过 REST API 和 ProfileHub Server 通信。

## 安装

```bash
pip install profilehub

# 镜像源加速
pip install profilehub -i https://pypi.tuna.tsinghua.edu.cn/simple
```

> SDK 仅依赖 `requests`。需要本地运行 ProfileHub Server 才能连接。

## 快速开始

```python
import profilehub

hub = profilehub.Hub("http://127.0.0.1:5678")

# 列出所有浏览器环境
envs = hub.list_envs()

# 通过别名查找环境
env = hub.env_by_alias("店铺A")

# Context Manager：自动启动 + 自动停止
with hub.env_by_alias("店铺A") as env:
    env.navigate("https://example.com")
    cookies = env.cookies()
    title = env.title()
# 退出 with 块后自动停止
```

## 核心概念

- **Hub** — 连接 ProfileHub Server 的入口，管理所有环境、脚本、项目、计划等
- **ProfileHubEnv** — 单个浏览器环境的操作句柄，封装启动/停止/Cookie/JS 执行/CDP 等

## 环境管理

```python
# 启动/停止
env.launch()
env.stop()

# 状态查询
info = env.info()        # 带缓存
status = env.status()

# Cookie
cookies = env.cookies(url="https://api.example.com")

# 页面操作
env.navigate("https://example.com")
title = env.title()
url = env.current_url()

# JavaScript 执行
result = env.execute_js("document.querySelector('h1').textContent")

# Python 执行（在 ProfileHub 服务端运行）
result = hub.execute_python(code="print('hello')")
```

## 分组操作

```python
# 启动整个分组
hub.launch_group("电商")

# 停止整个分组
hub.stop_group("电商")
```

## 脚本库

```python
# 搜索脚本
scripts = hub.match_scripts(query="登录")

# 运行脚本
hub.run_script("daily_check", profile_id="xxx")

# 匹配最适合的脚本
matched = hub.match_scripts(query="采集订单", group="电商")
```

## 健康检查

```python
if hub.is_alive():
    print("ProfileHub Server 正在运行")
```

## 组合方法（SDK 独有优势）

SDK 封装了多步工作流，比直接调 API 省事：

```python
# 一行找到环境（自动判断传的是 ID 还是别名）
env = hub.find_env("店铺A")       # 等同 hub.env_by_alias("店铺A")
env = hub.find_env("env_xxxx")    # 直接用 ID

# 一行完成：找到环境 → 启动 → 拿 Cookie → 自动还原状态
ck = hub.quick_cookies("店铺A", url="https://api.example.com")

# 一行完成：找到环境 → 启动 → 执行 JS → 自动还原状态
title = hub.quick_js("店铺A", "document.title")

# 一行完成：找到环境 → 启动 → 运行脚本 → 自动还原状态
result = hub.quick_run("店铺A", "daily_check", args={"date": "today"})

# 登录态验证：启动 → 导航 → 抓接口 → 判断有效性 → 还原
check = hub.login_verify("店铺A", check_api="https://api.example.com/user/info")
print(check["valid"])  # True/False

# 批量状态概览
summary = hub.batch_status()
print(summary["running"])  # 正在运行的环境列表
print(summary["stopped"])  # 已停止的环境列表
```

## 分发渠道

| 场景 | 方式 |
|------|------|
| 外部项目 / IDE | `pip install profilehub` |
| ProfileHub 内部执行 | PYTHONPATH 自动注入，`import profilehub` 直接可用 |
| ProfileHub 创建的本地项目 | 自动复制 SDK 到项目目录 |
| 无 pip 环境 | 从 `http://127.0.0.1:5678/api/sdk/download` 下载 |

## 版本兼容

SDK 与 Server 版本独立。旧 SDK + 新 Server = 已有方法始终可用（REST API 是契约层）。

## License

MIT
