Metadata-Version: 2.4
Name: lBrowser
Version: 0.1.0
Summary: 轻量级、易用的Python浏览器自动化操作库
Author: lBrowser Team
License: MIT
Project-URL: Homepage, https://github.com/example/lBrowser
Project-URL: Repository, https://github.com/example/lBrowser
Keywords: browser,automation,playwright,testing,web-scraping
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Testing
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright>=1.40.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Dynamic: license-file

# lBrowser

轻量级、易用的 Python 浏览器自动化操作库，基于 Playwright 构建。

## 特性

- **简洁 API**：直观的链式调用，学习成本低
- **同步/异步双模式**：`Browser`（同步）和 `AsyncBrowser`（异步）两种接口
- **跨浏览器支持**：Chromium、Firefox、WebKit 三引擎
- **自动等待**：内置显式/隐式等待机制
- **完整截图能力**：整页截图、元素截图、Data URL 格式
- **类型安全**：完整的类型注解，支持 IDE 智能提示
- **上下文管理器**：支持 `with` / `async with` 自动管理资源
- **错误处理**：层次化的异常体系，清晰的错误信息

## 安装

```bash
# 安装 lBrowser
pip install lbrowser

# 安装 Playwright 浏览器（首次使用）
playwright install chromium
```

### 从源码安装

```bash
git clone https://github.com/example/lBrowser.git
cd lBrowser
pip install -e .
playwright install chromium
```

## 快速开始

```python
from lBrowser import Browser

# 使用上下文管理器（推荐）
with Browser(headless=True) as browser:
    browser.load("https://www.example.com")

    # 获取页面信息
    print(f"标题: {browser.get_title()}")
    print(f"URL: {browser.get_url()}")

    # 元素操作
    browser.click("#submit-btn")
    browser.type("#search-input", "keyword")

    # 截图
    browser.screenshot(save_path="page.png")
    data_url = browser.screenshot(format="data_url")
```

## API 概览

| 操作 | 方法 | 说明 |
|------|------|------|
| 启动浏览器 | `Browser.start()` | 启动浏览器实例 |
| 加载页面 | `browser.load(url)` | 加载指定 URL |
| 点击元素 | `browser.click(selector)` | 点击匹配的元素 |
| 输入文本 | `browser.type(selector, text)` | 在元素中输入文本 |
| 获取文本 | `browser.get_text(selector)` | 获取元素文本内容 |
| 获取属性 | `browser.get_attribute(selector, name)` | 获取元素属性值 |
| 查找元素 | `browser.find(selector)` | 返回 Element 对象 |
| 页面截图 | `browser.screenshot()` | 页面/元素截图 |
| 执行 JS | `browser.execute_script(js)` | 执行 JavaScript |
| 等待元素 | `browser.wait_for_selector(selector)` | 等待元素出现 |
| 获取标题 | `browser.get_title()` | 获取页面标题 |
| 获取 URL | `browser.get_url()` | 获取当前 URL |
| 关闭浏览器 | `browser.close()` | 释放资源 |

## 文档

详细示例请参考：

- [基础使用示例](examples/basic_usage.py) — 核心功能演示
- [进阶使用示例](examples/advanced_usage.py) — 异步、并发、数据采集、页面监控等

## 错误处理

lBrowser 提供层次化的异常体系：

| 异常类 | 说明 |
|--------|------|
| `BrowserException` | 所有异常的基类 |
| `BrowserLaunchError` | 浏览器启动失败 |
| `NavigationError` | 页面导航失败 |
| `ElementNotFoundError` | 元素未找到 |
| `ElementNotInteractableError` | 元素不可交互 |
| `TimeoutError` | 操作超时 |
| `ScreenshotError` | 截图失败 |
| `JavaScriptError` | JS 执行失败 |

## 常见使用场景

- **自动化测试**：页面功能验证、表单提交测试
- **数据采集**：动态网页内容抓取
- **页面监控**：定时截图对比、内容变更检测
- **截图服务**：生成页面快照、元素截图
- **RPA 流程自动化**：重复性网页操作

## 许可证

MIT
