profilehub 3.1.0

ProfileHub Python SDK — thin HTTP client for ProfileHub browser environment hub

ProfileHub Python SDK

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

安装

pip install profilehub

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

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

快速开始

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 等

环境管理

# 启动/停止
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')")

分组操作

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

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

脚本库

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

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

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

健康检查

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

组合方法（SDK 独有优势）

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

# 一行找到环境（自动判断传的是 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