solar-network-sdk 1.0.2

A Python SDK for interacting with the Solar Network API(Not official)

Solar Network Python SDK API 文档

概述

Solar Network Python SDK 提供了与 Solar Network API 交互的完整解决方案。本 SDK 包含认证、账户管理、内容操作等所有核心功能。

安装

pip install solar-network-sdk

快速开始

基本认证

from solar_network_sdk import SolarNetworkClient, WebAuthClient

# 创建客户端
client = SolarNetworkClient()

# 获取认证客户端
web_auth = client.get_web_auth_client()

# 获取认证 URL
auth_url = web_auth.get_authentication_url()
print(f"请在浏览器中打开: {auth_url}")

# 等待用户认证
auth_result = web_auth.wait_for_auth()

if auth_result.status == "challenge":
    # 签名挑战
    signed_challenge = sign_challenge(auth_result.challenge)
    
    # 交换令牌
    token_result = web_auth.exchange_token(signed_challenge)
    
    if token_result.status == "success":
        # 设置令牌
        client.set_token(token_result.token)
        
        # 现在可以进行认证请求
        account = client.get_account()
        print(f"你好, {account.name}!")

核心类

SolarNetworkClient

主客户端类，提供所有 API 操作。

构造函数

SolarNetworkClient(
    server_url: str = "https://api.solian.app",
    token: Optional[str] = None,
    timeout: int = 30
)

参数:

• server_url: Solar Network API 服务器 URL
• token: 可选的认证令牌
• timeout: 请求超时时间（秒）

方法

认证相关

• get_web_auth_client() -> WebAuthClient
  • 获取 Web 认证客户端实例

账户管理

• get_account() -> Account

  • 获取当前账户信息

• update_account(**kwargs) -> Account

  • 更新账户信息

• get_account_profile() -> AccountProfile

  • 获取账户配置文件

• update_account_profile(**kwargs) -> AccountProfile

  • 更新账户配置文件

• get_account_status() -> AccountStatus

  • 获取账户状态

• set_account_status(attitude: int, type: int = 0, label: str = "", symbol: Optional[str] = None, meta: Optional[Dict[str, Any]] = None) -> AccountStatus

  • 设置账户状态

• clear_account_status() -> None

  • 清除账户状态

活动操作

• check_in() -> CheckInResult

  • 执行每日签到

• get_notable_days(start_date: Optional[datetime] = None, end_date: Optional[datetime] = None) -> List[NotableDay]

  • 获取显著日期

• get_timeline_events(limit: int = 20, offset: int = 0, types: Optional[List[str]] = None) -> List[TimelineEvent]

  • 获取时间线事件

聊天操作

• get_chat_rooms(limit: int = 20, offset: int = 0, types: Optional[List[int]] = None) -> List[ChatRoom]

  • 获取聊天室列表

• get_chat_messages(room_id: str, limit: int = 50, before: Optional[str] = None, after: Optional[str] = None) -> List[ChatMessage]

  • 获取聊天室消息

• send_chat_message(room_id: str, content: str, type: str = "text", nonce: Optional[str] = None, meta: Optional[Dict[str, Any]] = None) -> ChatMessage

  • 发送聊天消息

文件操作

• get_file_pools() -> List[FilePool]

  • 获取文件池列表

• get_cloud_files(limit: int = 50, offset: int = 0, pool_id: Optional[str] = None) -> List[CloudFile]

  • 获取云文件列表

• upload_file(file_path: str, pool_id: Optional[str] = None, name: Optional[str] = None, description: Optional[str] = None) -> DriveTask

  • 上传文件

帖子操作

• create_post(content: str, title: Optional[str] = None, visibility: int = 0, type: int = 0, attachments: Optional[List[str]] = None, tags: Optional[List[str]] = None, categories: Optional[List[str]] = None) -> Post

  • 创建帖子

• get_posts(limit: int = 20, offset: int = 0, types: Optional[List[int]] = None, visibility: Optional[List[int]] = None) -> List[Post]

  • 获取帖子列表

钱包操作

• get_wallet() -> Wallet

  • 获取钱包信息

• get_wallet_pockets() -> List[WalletPocket]

  • 获取钱包口袋

• get_wallet_transactions(limit: int = 50, offset: int = 0, types: Optional[List[int]] = None) -> List[Transaction]

  • 获取钱包交易

工具方法

• set_token(token: str) -> None

  • 设置认证令牌

• clear_token() -> None

  • 清除认证令牌

WebAuthClient

Web 认证客户端，用于与 Solar Network 桌面应用进行认证交互。

构造函数

WebAuthClient(
    base_url: str = "http://127.0.0.1",
    default_port: int = 40000,
    web_url: str = "https://app.solian.fr"
)

参数:

• base_url: 本地服务器基础 URL
• default_port: 默认连接端口
• web_url: Solar Network Web URL

属性

• port: int
  • 获取/设置当前端口

方法

URL 生成

• get_authentication_url() -> str

  • 获取认证 URL

• get_protocol_challenge_url(app_slug: str, redirect_uri: str, state: Optional[str] = None) -> str

  • 获取协议挑战 URL

• get_protocol_exchange_url(signed_challenge: str, redirect_uri: str, secret_id: Optional[str] = None, state: Optional[str] = None) -> str

  • 获取协议交换 URL

认证流程

• wait_for_auth(port: Optional[int] = None, app_name: str = "PythonApp") -> WebAuthResult

  • 等待用户认证响应

• exchange_token(signed_challenge: str, port: Optional[int] = None, device_info: Optional[Dict[str, Any]] = None, secret_id: Optional[str] = None) -> WebAuthResult

  • 交换认证令牌

• fetch_account_info(port: Optional[int] = None, token: str = "") -> Dict[str, Union[bool, Optional[Dict[str, Any]], Optional[str]]]

  • 获取账户信息

• authenticate(app_name: str = "PythonApp", sign_challenge: Optional[callable] = None) -> WebAuthResult

  • 完整认证流程

数据模型

Account

账户信息模型。

字段:

• id: str - 账户 ID
• name: str - 账户名称
• email: str - 邮箱地址
• status: int - 账户状态
• created_at: datetime - 创建时间

AccountProfile

账户配置文件模型。

字段:

• nick: str - 昵称
• birthday: Optional[datetime] - 生日
• gender: int - 性别
• bio: str - 个人简介

ChatRoom

聊天室模型。

字段:

• id: str - 聊天室 ID
• name: str - 聊天室名称
• type: int - 聊天室类型
• is_public: bool - 是否公开

CloudFile

云文件模型。

字段:

• id: str - 文件 ID
• name: str - 文件名
• size: int - 文件大小
• mime_type: str - MIME 类型
• url: str - 文件 URL

Post

帖子模型。

字段:

• id: str - 帖子 ID
• title: str - 帖子标题
• content: str - 帖子内容
• visibility: int - 可见性
• created_at: datetime - 创建时间

Wallet

钱包模型。

字段:

• id: str - 钱包 ID
• pockets: List[WalletPocket] - 钱包口袋列表

WalletPocket

钱包口袋模型。

字段:

• currency: str - 货币类型
• amount: float - 金额

错误处理

所有 API 方法都可能抛出异常。建议使用 try-catch 块进行错误处理：

try:
    account = client.get_account()
    print(f"账户信息: {account.name}")
except Exception as e:
    print(f"获取账户信息失败: {e}")

分页

大多数列表方法都支持分页参数：

• limit: 返回项目数量
• offset: 偏移量
• before/after: 时间戳分页

示例：

# 获取前 20 个项目
items = client.get_posts(limit=20, offset=0)

# 获取下一页
next_items = client.get_posts(limit=20, offset=20)

异步支持

分页控制器支持异步操作：

from solar_network_sdk.pagination import AsyncPaginationController

async def fetch_data():
    controller = AsyncPaginationController(fetch_func)
    await controller.refresh()
    await controller.fetch_further()

最佳实践

1. 认证安全: 始终使用安全的方式存储和传输认证令牌
2. 错误处理: 为所有 API 调用添加适当的错误处理
3. 分页: 处理大量数据时使用分页
4. 超时: 根据需要调整请求超时时间
5. 类型检查: 利用类型注解提高代码质量

贡献

欢迎贡献代码！请阅读 CONTRIBUTING.md 了解详细信息。

许可证

MIT License - 详见 LICENSE 文件。