Skip to content

readme.md

Latest commit

 

History

History
339 lines (227 loc) · 8.11 KB

readme.md

File metadata and controls

339 lines (227 loc) · 8.11 KB

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 文件。