249 lines
5.6 KiB
Markdown
249 lines
5.6 KiB
Markdown
# CookieCloud Client
|
|
|
|
一个独立的、可复用的CookieCloud服务器客户端Python模块。
|
|
|
|
## 特性
|
|
|
|
- ✅ **完全独立** - 无外部依赖，仅使用Python标准库
|
|
- ✅ **类型安全** - 完整的类型提示支持
|
|
- ✅ **异常处理** - 完善的异常体系
|
|
- ✅ **易于使用** - 简洁的API设计
|
|
- ✅ **可扩展** - 支持自定义配置
|
|
- ✅ **文档完善** - 详细的使用文档和示例
|
|
|
|
## 安装
|
|
|
|
将 `cookiecloud_client` 目录复制到您的项目中即可使用。
|
|
|
|
## 快速开始
|
|
|
|
### 基本使用
|
|
|
|
```python
|
|
from cookiecloud_client import CookieCloudClient, CookieConfig
|
|
|
|
# 创建配置
|
|
config = CookieConfig(
|
|
server="https://cookiecloud.example.com",
|
|
username="your_username",
|
|
password="your_password"
|
|
)
|
|
|
|
# 创建客户端
|
|
client = CookieCloudClient(config)
|
|
|
|
# 下载所有cookies
|
|
result = client.download()
|
|
|
|
if result.success:
|
|
print(f"下载成功！")
|
|
print(f"总域名数: {result.total_domains}")
|
|
print(f"总Cookie数: {result.total_cookies}")
|
|
print(f"下载耗时: {result.download_time:.2f}秒")
|
|
|
|
# 获取指定域名的cookie
|
|
cookie_str = result.get_cookie_string("example.com")
|
|
print(f"example.com的cookie: {cookie_str}")
|
|
else:
|
|
print(f"下载失败: {result.error_message}")
|
|
```
|
|
|
|
### 下载指定域名的Cookie
|
|
|
|
```python
|
|
# 下载单个域名
|
|
cookie_str = client.download_for_domain("baidu.com")
|
|
if cookie_str:
|
|
print(f"baidu.com的cookie: {cookie_str}")
|
|
|
|
# 批量下载多个域名
|
|
domains = ["baidu.com", "google.com", "github.com"]
|
|
cookies = client.download_for_domains(domains)
|
|
for domain, cookie in cookies.items():
|
|
print(f"{domain}: {cookie}")
|
|
```
|
|
|
|
### 测试连接
|
|
|
|
```python
|
|
success, message = client.test_connection()
|
|
if success:
|
|
print("连接成功！")
|
|
else:
|
|
print(f"连接失败: {message}")
|
|
```
|
|
|
|
## 高级用法
|
|
|
|
### 自定义配置
|
|
|
|
```python
|
|
config = CookieConfig(
|
|
server="https://cookiecloud.example.com",
|
|
username="your_username",
|
|
password="your_password",
|
|
timeout=60, # 超时时间（秒）
|
|
verify_ssl=False, # 是否验证SSL证书
|
|
ignore_cookies=[ # 忽略的cookie名称
|
|
"CookieAutoDeleteBrowsingDataCleanup",
|
|
"CookieAutoDeleteCleaningDiscarded"
|
|
]
|
|
)
|
|
```
|
|
|
|
### 异常处理
|
|
|
|
```python
|
|
from cookiecloud_client import (
|
|
CookieCloudClient,
|
|
CookieConfig,
|
|
CookieCloudError,
|
|
ConnectionError,
|
|
AuthenticationError,
|
|
DataParseError,
|
|
NetworkError
|
|
)
|
|
|
|
try:
|
|
client = CookieCloudClient(config)
|
|
result = client.download()
|
|
|
|
except AuthenticationError as e:
|
|
print(f"认证失败: {e.message}")
|
|
print(f"用户名: {e.details.get('username')}")
|
|
|
|
except ConnectionError as e:
|
|
print(f"连接失败: {e.message}")
|
|
print(f"服务器: {e.details.get('server')}")
|
|
print(f"状态码: {e.details.get('status_code')}")
|
|
|
|
except DataParseError as e:
|
|
print(f"数据解析失败: {e.message}")
|
|
|
|
except NetworkError as e:
|
|
print(f"网络错误: {e.message}")
|
|
print(f"原始错误: {e.details.get('original_error')}")
|
|
|
|
except CookieCloudError as e:
|
|
print(f"CookieCloud错误: {e.message}")
|
|
```
|
|
|
|
### 使用Cookie数据对象
|
|
|
|
```python
|
|
result = client.download()
|
|
|
|
# 获取所有域名
|
|
domains = result.get_domains()
|
|
print(f"所有域名: {domains}")
|
|
|
|
# 遍历所有cookie
|
|
for domain, collection in result.cookies.items():
|
|
print(f"\n域名: {domain}")
|
|
for cookie in collection.cookies:
|
|
print(f" - {cookie.name}={cookie.value[:20]}...")
|
|
print(f" 路径: {cookie.path}")
|
|
print(f" 安全: {cookie.secure}")
|
|
print(f" HttpOnly: {cookie.http_only}")
|
|
```
|
|
|
|
## API文档
|
|
|
|
### CookieConfig
|
|
|
|
配置类，用于存储CookieCloud服务器配置。
|
|
|
|
**参数:**
|
|
- `server` (str): CookieCloud服务器地址
|
|
- `username` (str): 用户名
|
|
- `password` (str): 密码
|
|
- `timeout` (int): 请求超时时间（秒），默认30
|
|
- `verify_ssl` (bool): 是否验证SSL证书，默认True
|
|
- `ignore_cookies` (List[str]): 忽略的cookie名称列表
|
|
|
|
### CookieCloudClient
|
|
|
|
客户端类，用于与CookieCloud服务器交互。
|
|
|
|
**方法:**
|
|
|
|
#### `download() -> DownloadResult`
|
|
下载所有cookies
|
|
|
|
**返回:** DownloadResult对象
|
|
|
|
#### `download_for_domain(domain: str) -> Optional[str]`
|
|
下载指定域名的cookie字符串
|
|
|
|
**参数:**
|
|
- `domain` (str): 目标域名
|
|
|
|
**返回:** cookie字符串或None
|
|
|
|
#### `download_for_domains(domains: List[str]) -> Dict[str, Optional[str]]`
|
|
批量下载多个域名的cookie字符串
|
|
|
|
**参数:**
|
|
- `domains` (List[str]): 目标域名列表
|
|
|
|
**返回:** {domain: cookie_string}字典
|
|
|
|
#### `test_connection() -> Tuple[bool, str]`
|
|
测试与CookieCloud服务器的连接
|
|
|
|
**返回:** (是否成功, 消息)元组
|
|
|
|
### DownloadResult
|
|
|
|
下载结果类。
|
|
|
|
**属性:**
|
|
- `success` (bool): 是否成功
|
|
- `cookies` (Dict[str, CookieCollection]): cookie集合字典
|
|
- `error_message` (str): 错误信息
|
|
- `total_domains` (int): 总域名数
|
|
- `total_cookies` (int): 总cookie数
|
|
- `download_time` (float): 下载耗时（秒）
|
|
|
|
**方法:**
|
|
- `get_cookie_string(domain: str) -> Optional[str]`: 获取指定域名的cookie字符串
|
|
- `get_domains() -> List[str]`: 获取所有域名列表
|
|
|
|
## 异常类
|
|
|
|
### CookieCloudError
|
|
基础异常类，所有其他异常都继承自此类。
|
|
|
|
### ConfigurationError
|
|
配置错误异常
|
|
|
|
### ConnectionError
|
|
连接错误异常
|
|
|
|
### AuthenticationError
|
|
认证错误异常
|
|
|
|
### DataParseError
|
|
数据解析错误异常
|
|
|
|
### NetworkError
|
|
网络错误异常
|
|
|
|
## 依赖
|
|
|
|
- Python 3.7+
|
|
- 仅使用Python标准库
|
|
|
|
## 许可证
|
|
|
|
MIT License
|
|
|
|
## 更新日志
|
|
|
|
### v1.0.0 (2026-03-02)
|
|
- 初始版本发布
|
|
- 完整的CookieCloud客户端功能
|
|
- 独立模块，无外部依赖
|
|
- 完善的异常处理
|
|
- 详细的文档和示例
|