nexusphp-api 0.1.1

NexusPHP API Client - A Python client for interacting with NexusPHP forum API

NexusPHP API Client

NexusPHP API 客户端，用于与 NexusPHP 论坛 API 进行交互的 Python 库。

项目结构

nexusphp_api/
├── api/                 # API 数据模型
│   ├── bookmark/        # 收藏相关
│   ├── comment/         # 评论相关
│   ├── section/         # 分区相关
│   ├── torrent/         # 种子相关
│   └── user/            # 用户相关
├── api_client/          # API 客户端实现
├── config/              # 配置管理
├── utils/               # 工具库
├── tests/               # 测试代码
├── doc/                 # API 文档
├── pyproject.toml       # PEP 517/518 构建配置
├── setup.cfg            # 包元数据和配置
└── requirements.txt     # 项目依赖

功能模块

1. 收藏管理 (bookmark)

• 添加收藏
• 删除收藏

2. 评论管理 (comment)

• 获取评论列表

3. 分区管理 (section)

• 获取分区信息

4. 种子管理 (torrent)

• 获取种子列表
• 获取种子详情
• 上传种子

5. 用户管理 (user)

• 获取用户资料

安装

从 PyPI 安装（推荐）

pip install nexusphp-api

从源代码安装

git clone https://github.com/nexusphp/nexusphp-api.git
cd nexusphp-api
pip install -e .

安装开发依赖

pip install -r requirements.txt

快速开始

基本使用

from nexusphp_api import NexusAPIClient

# 初始化客户端
client = NexusAPIClient(
    base_url="https://dev.nexusphp.org",
    token="your-api-token"
)

# 获取当前用户资料
profile = client.profile.get_profile()
print(f"用户: {profile.data.data.username}")

# 添加收藏
bookmark = client.bookmark.add_bookmark(torrent_id=123)
print(f"收藏状态: {bookmark.msg}")

# 删除收藏
result = client.bookmark.delete_bookmark(torrent_id=123)
print(f"删除结果: {result.msg}")

动态更新配置

# 更新 token
client.set_token("new-token")

# 更新 base_url
client.set_base_url("https://api.example.com")

配置管理

项目支持通过环境变量进行配置：

环境变量	默认值	说明
API_BASE_URL	https://api.nexusphp.org	API 基础 URL
API_TIMEOUT	30	API 请求超时时间（秒）
API_TOKEN	""	认证 Token
LOG_LEVEL	INFO	日志级别
LOG_FILE	api.log	日志文件
MAX_RETRIES	3	最大重试次数
RETRY_INTERVAL	1.0	重试间隔（秒）

API 参考

NexusAPIClient 主类

from nexusphp_api import NexusAPIClient

# 初始化
client = NexusAPIClient(
    base_url="https://dev.nexusphp.org",  # 可选，默认值
    token="your-token"                    # 可选
)

# 子客户端
client.profile        # 用户资料
client.bookmark       # 收藏管理
client.comment        # 评论管理
client.section        # 分区管理
client.torrent        # 种子管理

可用的客户端方法

ProfileClient（用户资料）

• get_profile(user_id=None, includes=None, include_fields=None)

BookmarkClient（收藏）

• add_bookmark(torrent_id)
• delete_bookmark(torrent_id)

CommentClient（评论）

• 详见代码和文档

SectionClient（分区）

• 详见代码和文档

TorrentClient（种子）

• 详见代码和文档

运行测试

运行所有测试

pytest tests/

运行特定测试

pytest tests/test_api_client.py

运行测试并显示覆盖率

pytest tests/ --cov=nexusphp_api --cov-report=html

使用 unittest 运行

python -m unittest discover tests

代码质量检查

项目配置了以下代码质量工具：

格式化代码

black .
isort .

代码 lint 检查

flake8 .

类型检查

mypy .

响应格式

所有 API 响应都遵循以下格式：

{
  "ret": 0,          // 结果码，0 成功，其他失败
  "msg": "success",  // 文本说明
  "data": {},        // 响应数据
  "rid": "uuid",     // 请求 ID
  "time": 0.123      // 响应耗时（秒）
}

工具库

项目提供了以下工具函数，用于数据转换和处理：

• from_str - 字符串转换
• from_int - 整数转换
• from_int_optional - 可空整数转换
• from_float - 浮点数转换
• from_bool - 布尔值转换
• from_none - None 转换
• from_union - 联合类型转换
• from_list - 列表转换
• from_dict - 字典转换
• to_float - 浮点数输出转换
• to_class - 类实例转换
• to_enum - 枚举转换

开发和贡献

本地开发

1. Fork 项目仓库
2. 克隆到本地
3. 安装开发依赖
4. 创建功能分支
5. 提交变更
6. 推送到分支
7. 创建 Pull Request

构建和发布

# 构建包
python -m build

# 发布到 PyPI
twine upload dist/*

注意事项

1. 使用前请确保已获取有效的 API Token
2. 遵守 API 调用频率限制
3. 处理 API 响应时请检查 ret 字段确认操作是否成功
4. 网络请求失败时会自动重试（默认 3 次）

许可证

MIT License

支持和联系

如有问题或建议，请：

• 提交 Issue: GitHub Issues
• 查看文档: 项目 Wiki