lexmount 0.3.1__tar.gz

lexmount-0.3.1/.env.example

@@ -0,0 +1,3 @@
+# Lexmount API Configuration
+LEXMOUNT_API_KEY=your-api-key-here
+LEXMOUNT_PROJECT_ID=your-project-id-here

lexmount-0.3.1/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-01-XX
+
+### Added
+- Initial release of Lexmount Python SDK
+- `Lexmount` client for managing browser instances
+- `SessionsResource` for creating and managing browser sessions
+- Support for multiple browser modes (chrome-docker, chrome-light-docker, etc.)
+- Integration with Playwright via CDP WebSocket
+- Environment variable configuration support
+- Basic error handling and timeout management
+- Comprehensive README and API documentation
+
+### Features
+- Create browser sessions with configurable browser modes
+- Retrieve WebSocket URLs for Playwright connection
+- Support for project-level and session-level configuration
+- HTTP client with timeout and error handling
+
+[Unreleased]: https://github.com/yourusername/lexmount-python-sdk/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/yourusername/lexmount-python-sdk/releases/tag/v0.1.0
+

lexmount-0.3.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Lexmount
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

lexmount-0.3.1/MANIFEST.in

@@ -0,0 +1,49 @@
+# 核心文档
+include README.md
+include LICENSE
+include CHANGELOG.md
+
+# 配置文件
+include requirements.txt
+include .env.example
+include pyproject.toml
+
+# 源代码
+recursive-include src *.py
+
+# API 文档
+recursive-include doc *.md
+
+# 示例代码（可选，如果不想包含可以注释掉）
+recursive-include examples *.py
+prune examples/__pycache__
+
+# 排除不需要的文件
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * *.pyd
+recursive-exclude * .DS_Store
+recursive-exclude * *.so
+recursive-exclude * *.dylib
+
+# 排除开发相关文档（用户安装包时不需要）
+prune summary
+
+# 排除开发脚本
+recursive-exclude scripts *
+
+# 排除测试和其他开发文件
+exclude .gitignore
+exclude .env
+exclude screenshot.png
+exclude *.png
+exclude *.jpg
+exclude *.jpeg
+prune tests
+prune .git
+prune .github
+prune build
+prune dist
+prune *.egg-info
+exclude INSTALL_FROM_COS.md
+

lexmount-0.3.1/PKG-INFO

@@ -0,0 +1,534 @@
+Metadata-Version: 2.4
+Name: lexmount
+Version: 0.3.1
+Summary: Python SDK for Lexmount browser automation service
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/lexmount-python-sdk
+Project-URL: Documentation, https://github.com/yourusername/lexmount-python-sdk/blob/main/doc/api.md
+Project-URL: Repository, https://github.com/yourusername/lexmount-python-sdk
+Project-URL: Bug Tracker, https://github.com/yourusername/lexmount-python-sdk/issues
+Keywords: browser,automation,playwright,selenium,cloud,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+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: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.23.0
+Requires-Dist: python-dotenv>=0.19.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: respx>=0.20.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=0.950; extra == "dev"
+Dynamic: license-file
+
+# Lexmount Python SDK
+
+[English](#english) | [中文](#中文)
+
+---
+
+## English
+
+Python SDK for Lexmount browser automation service.
+
+### ✨ Features
+
+- 🚀 **Easy to Use**: Simple and intuitive API design
+- 🔒 **Type-Safe**: Complete type hints for better IDE support
+- 📝 **Well Documented**: Comprehensive docstrings and examples
+- 🛡️ **Production Ready**: Error handling, logging, and retry support
+- 📊 **Session Management**: Create, list, and delete browser sessions
+- 🔍 **Advanced Querying**: Pagination support and status filtering
+
+### 📦 Installation
+
+```bash
+pip install lexmount
+```
+
+**Requirements:**
+- Python 3.8+
+- httpx >= 0.23.0
+- python-dotenv >= 0.19.0
+- playwright (optional, for browser automation)
+
+### 🚀 Quick Start
+
+#### Basic Usage
+
+```python
+from lexmount import Lexmount
+
+# Initialize client (credentials from environment variables)
+client = Lexmount(
+    api_key="your-api-key",
+    project_id="your-project-id"
+)
+
+# Create a browser session
+session = client.sessions.create()
+print(f"Session ID: {session.id}")
+print(f"Connect URL: {session.connect_url}")
+
+# Close session when done
+session.close()
+```
+
+#### Using Context Managers (Recommended)
+
+Context managers provide automatic resource cleanup:
+
+```python
+from lexmount import Lexmount
+
+# Client and session will be automatically closed
+with Lexmount(api_key="key", project_id="proj") as client:
+    with client.sessions.create() as session:
+        print(f"Using session: {session.id}")
+        # Use session...
+        # Automatically closed on exit
+```
+
+#### Integration with Playwright
+
+```python
+from lexmount import Lexmount
+from playwright.sync_api import sync_playwright
+
+# Create session
+client = Lexmount(api_key="key", project_id="proj")
+session = client.sessions.create()
+
+# Connect with Playwright
+with sync_playwright() as p:
+    browser = p.chromium.connect_over_cdp(session.connect_url)
+    page = browser.new_page()
+
+    page.goto("https://example.com")
+    print(page.title())
+
+    browser.close()
+
+session.close()
+```
+
+### 📚 Core Features
+
+#### Session Management
+
+**Create Session**
+
+```python
+# Basic creation
+session = client.sessions.create()
+
+# With specific browser mode
+session = client.sessions.create(browser_mode="normal")
+
+# Available browser modes:
+# - "normal": Chrome in Docker container
+# - "light": Lightweight Chrome in Docker
+```
+
+**List Sessions**
+
+```python
+# List all sessions with pagination
+result = client.sessions.list()
+print(f"Total: {result.pagination.total_count}")
+print(f"Active: {result.pagination.active_count}")
+
+for session in result.sessions:
+    print(f"{session.id}: {session.status}")
+
+# Filter by status (server-side filtering)
+active_sessions = client.sessions.list(status="active")
+print(f"Found {len(active_sessions)} active sessions")
+```
+
+**Delete Session**
+
+```python
+# Delete by session ID
+client.sessions.delete(session_id="session-id")
+
+# Or use session object
+session.close()
+```
+
+#### Error Handling
+
+```python
+from lexmount import (
+    Lexmount,
+    AuthenticationError,
+    SessionNotFoundError,
+    TimeoutError,
+    NetworkError,
+    APIError
+)
+
+try:
+    client = Lexmount(api_key="key", project_id="proj")
+    session = client.sessions.create()
+except AuthenticationError:
+    print("Invalid credentials")
+except TimeoutError:
+    print("Request timed out")
+except NetworkError:
+    print("Network connection failed")
+except APIError as e:
+    print(f"API error: {e.status_code}")
+```
+
+#### Logging
+
+```python
+from lexmount import set_log_level
+
+# Enable debug logging
+set_log_level("DEBUG")
+
+# Available levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
+client = Lexmount(api_key="key", project_id="proj")
+session = client.sessions.create()  # Will log detailed info
+```
+
+### 📖 API Reference
+
+#### Lexmount Client
+
+```python
+Lexmount(
+    api_key: str = None,           # API key (or LEXMOUNT_API_KEY env var)
+    project_id: str = None,        # Project ID (or LEXMOUNT_PROJECT_ID env var)
+    base_url: str = None,          # API URL (or LEXMOUNT_BASE_URL env var)
+    timeout: float = 60.0          # Request timeout in seconds
+)
+```
+
+#### Sessions Resource
+
+**`sessions.create()`** - Create a new browser session
+
+- **Parameters:**
+  - `project_id` (str, optional): Override default project ID
+  - `browser_mode` (str, optional): Browser mode (default: "normal")
+- **Returns:** `SessionInfo` object
+- **Raises:** `AuthenticationError`, `ValidationError`, `APIError`, `NetworkError`, `TimeoutError`
+
+**`sessions.list()`** - List browser sessions with pagination
+
+- **Parameters:**
+  - `project_id` (str, optional): Override default project ID
+  - `status` (str, optional): Filter by status ("active", "closed", or None for all)
+- **Returns:** `SessionListResponse` with sessions and pagination info
+- **Raises:** `AuthenticationError`, `APIError`, `NetworkError`, `TimeoutError`
+
+**`sessions.delete()`** - Delete a browser session
+
+- **Parameters:**
+  - `session_id` (str, required): Session ID to delete
+  - `project_id` (str, optional): Override default project ID
+- **Returns:** None
+- **Raises:** `AuthenticationError`, `SessionNotFoundError`, `APIError`
+
+#### SessionInfo Object
+
+**Attributes:**
+- `id` (str): Session identifier
+- `session_id` (str): Alias for id
+- `status` (str): Session status ("active", "closed")
+- `browser_type` (str): Browser mode used
+- `created_at` (str): ISO 8601 timestamp
+- `connect_url` (str): WebSocket URL for Playwright
+- `ws` (str): Alias for connect_url
+- `container_id` (str): Docker container ID (if applicable)
+- `inspect_url` (str): Chrome DevTools inspection URL
+
+**Methods:**
+- `close()`: Close the session and release resources
+- `__enter__()`, `__exit__()`: Context manager support
+
+### 🔧 Configuration
+
+#### Environment Variables
+
+```bash
+export LEXMOUNT_API_KEY="your-api-key"
+export LEXMOUNT_PROJECT_ID="your-project-id"
+export LEXMOUNT_BASE_URL="https://api.lexmount.com"  # Optional
+```
+
+Or use a `.env` file:
+
+```bash
+LEXMOUNT_API_KEY=your-api-key
+LEXMOUNT_PROJECT_ID=your-project-id
+```
+
+### 📄 License
+
+MIT License
+
+---
+
+## 中文
+
+Lexmount 浏览器自动化服务的 Python SDK。
+
+### ✨ 特性
+
+- 🚀 **简单易用**：直观的 API 设计
+- 🔒 **类型安全**：完整的类型提示，IDE 支持友好
+- 📝 **文档完善**：详细的文档和示例
+- 🛡️ **生产就绪**：错误处理、日志记录、重试支持
+- 📊 **会话管理**：创建、列表、删除浏览器会话
+- 🔍 **高级查询**：支持分页和状态过滤
+
+### 📦 安装
+
+```bash
+pip install lexmount
+```
+
+**依赖要求：**
+- Python 3.8+
+- httpx >= 0.23.0
+- python-dotenv >= 0.19.0
+- playwright（可选，用于浏览器自动化）
+
+### 🚀 快速开始
+
+#### 基础用法
+
+```python
+from lexmount import Lexmount
+
+# 初始化客户端（从环境变量读取凭据）
+client = Lexmount(
+    api_key="your-api-key",
+    project_id="your-project-id"
+)
+
+# 创建浏览器会话
+session = client.sessions.create()
+print(f"会话 ID: {session.id}")
+print(f"连接 URL: {session.connect_url}")
+
+# 使用完毕后关闭会话
+session.close()
+```
+
+#### 使用上下文管理器（推荐）
+
+上下文管理器提供自动资源清理：
+
+```python
+from lexmount import Lexmount
+
+# 客户端和会话会自动关闭
+with Lexmount(api_key="key", project_id="proj") as client:
+    with client.sessions.create() as session:
+        print(f"使用会话: {session.id}")
+        # 使用会话...
+        # 退出时自动关闭
+```
+
+#### 与 Playwright 集成
+
+```python
+from lexmount import Lexmount
+from playwright.sync_api import sync_playwright
+
+# 创建会话
+client = Lexmount(api_key="key", project_id="proj")
+session = client.sessions.create()
+
+# 使用 Playwright 连接
+with sync_playwright() as p:
+    browser = p.chromium.connect_over_cdp(session.connect_url)
+    page = browser.new_page()
+
+    page.goto("https://example.com")
+    print(page.title())
+
+    browser.close()
+
+session.close()
+```
+
+### 📚 核心功能
+
+#### 会话管理
+
+**创建会话**
+
+```python
+# 基础创建
+session = client.sessions.create()
+
+# 指定浏览器模式
+session = client.sessions.create(browser_mode="normal")
+
+# 可用的浏览器模式：
+# - "normal": Docker 中的 Chrome
+# - "light": Docker 中的轻量级 Chrome
+```
+
+**列出会话**
+
+```python
+# 列出所有会话（带分页信息）
+result = client.sessions.list()
+print(f"总计: {result.pagination.total_count}")
+print(f"活跃: {result.pagination.active_count}")
+
+for session in result.sessions:
+    print(f"{session.id}: {session.status}")
+
+# 按状态过滤（服务端过滤）
+active_sessions = client.sessions.list(status="active")
+print(f"找到 {len(active_sessions)} 个活跃会话")
+```
+
+**删除会话**
+
+```python
+# 通过会话 ID 删除
+client.sessions.delete(session_id="session-id")
+
+# 或使用会话对象
+session.close()
+```
+
+#### 错误处理
+
+```python
+from lexmount import (
+    Lexmount,
+    AuthenticationError,
+    SessionNotFoundError,
+    TimeoutError,
+    NetworkError,
+    APIError
+)
+
+try:
+    client = Lexmount(api_key="key", project_id="proj")
+    session = client.sessions.create()
+except AuthenticationError:
+    print("认证失败")
+except TimeoutError:
+    print("请求超时")
+except NetworkError:
+    print("网络连接失败")
+except APIError as e:
+    print(f"API 错误: {e.status_code}")
+```
+
+#### 日志配置
+
+```python
+from lexmount import set_log_level
+
+# 启用调试日志
+set_log_level("DEBUG")
+
+# 可用级别：DEBUG, INFO, WARNING, ERROR, CRITICAL
+client = Lexmount(api_key="key", project_id="proj")
+session = client.sessions.create()  # 会输出详细日志
+```
+
+### 📖 API 参考
+
+#### Lexmount 客户端
+
+```python
+Lexmount(
+    api_key: str = None,           # API 密钥（或 LEXMOUNT_API_KEY 环境变量）
+    project_id: str = None,        # 项目 ID（或 LEXMOUNT_PROJECT_ID 环境变量）
+    base_url: str = None,          # API 地址（或 LEXMOUNT_BASE_URL 环境变量）
+    timeout: float = 60.0          # 请求超时时间（秒）
+)
+```
+
+#### Sessions 资源
+
+**`sessions.create()`** - 创建新的浏览器会话
+
+- **参数：**
+  - `project_id` (str, 可选): 覆盖默认项目 ID
+  - `browser_mode` (str, 可选): 浏览器模式（默认: "normal"）
+- **返回：** `SessionInfo` 对象
+- **异常：** `AuthenticationError`, `ValidationError`, `APIError`, `NetworkError`, `TimeoutError`
+
+**`sessions.list()`** - 列出浏览器会话（带分页）
+
+- **参数：**
+  - `project_id` (str, 可选): 覆盖默认项目 ID
+  - `status` (str, 可选): 按状态过滤（"active"、"closed" 或 None 表示全部）
+- **返回：** `SessionListResponse`，包含会话列表和分页信息
+- **异常：** `AuthenticationError`, `APIError`, `NetworkError`, `TimeoutError`
+
+**`sessions.delete()`** - 删除浏览器会话
+
+- **参数：**
+  - `session_id` (str, 必需): 要删除的会话 ID
+  - `project_id` (str, 可选): 覆盖默认项目 ID
+- **返回：** None
+- **异常：** `AuthenticationError`, `SessionNotFoundError`, `APIError`
+
+#### SessionInfo 对象
+
+**属性：**
+- `id` (str): 会话标识符
+- `session_id` (str): id 的别名
+- `status` (str): 会话状态（"active", "closed"）
+- `browser_type` (str): 使用的浏览器模式
+- `created_at` (str): ISO 8601 时间戳
+- `connect_url` (str): Playwright 的 WebSocket URL
+- `ws` (str): connect_url 的别名
+- `container_id` (str): Docker 容器 ID（如适用）
+- `inspect_url` (str): Chrome DevTools 检查 URL
+
+**方法：**
+- `close()`: 关闭会话并释放资源
+- `__enter__()`, `__exit__()`: 上下文管理器支持
+
+### 🔧 配置
+
+#### 环境变量
+
+```bash
+export LEXMOUNT_API_KEY="your-api-key"
+export LEXMOUNT_PROJECT_ID="your-project-id"
+export LEXMOUNT_BASE_URL="https://api.lexmount.com"  # 可选
+```
+
+或使用 `.env` 文件：
+
+```bash
+LEXMOUNT_API_KEY=your-api-key
+LEXMOUNT_PROJECT_ID=your-project-id
+```
+
+### 📄 许可证
+
+MIT License