# 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客户端功能
- 独立模块，无外部依赖
- 完善的异常处理
- 详细的文档和示例