cookie/cookiecloud_client

CookieCloud Client

一个独立的、可复用的CookieCloud服务器客户端Python模块。

特性

• ✅ 完全独立 - 无外部依赖，仅使用Python标准库
• ✅ 类型安全 - 完整的类型提示支持
• ✅ 异常处理 - 完善的异常体系
• ✅ 易于使用 - 简洁的API设计
• ✅ 可扩展 - 支持自定义配置
• ✅ 文档完善 - 详细的使用文档和示例

安装

将 cookiecloud_client 目录复制到您的项目中即可使用。

快速开始

基本使用

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

# 下载单个域名
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}")

测试连接

success, message = client.test_connection()
if success:
    print("连接成功！")
else:
    print(f"连接失败: {message}")

高级用法

自定义配置

config = CookieConfig(
    server="https://cookiecloud.example.com",
    username="your_username",
    password="your_password",
    timeout=60,  # 超时时间（秒）
    verify_ssl=False,  # 是否验证SSL证书
    ignore_cookies=[  # 忽略的cookie名称
        "CookieAutoDeleteBrowsingDataCleanup",
        "CookieAutoDeleteCleaningDiscarded"
    ]
)

异常处理

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数据对象

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