Metadata-Version: 2.4
Name: nexusphp-api
Version: 0.1.0
Summary: NexusPHP API Client - A Python client for interacting with NexusPHP forum API
Home-page: https://github.com/nexusphp/nexusphp_api
Author: NexusPHP Team
Author-email: contact@nexusphp.org
License: MIT License
Project-URL: Bug Tracker, https://github.com/nexusphp/nexusphp_api/issues
Project-URL: Documentation, https://github.com/nexusphp/nexusphp_api#readme
Project-URL: Source Code, https://github.com/nexusphp/nexusphp_api
Keywords: nexusphp,api,client,torrent,forum
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: typing_extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# NexusPHP API Client

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

[![PyPI Version](https://img.shields.io/pypi/v/nexusphp-api.svg)](https://pypi.org/project/nexusphp-api/)
[![Python Versions](https://img.shields.io/pypi/pyversions/nexusphp-api.svg)](https://pypi.org/project/nexusphp-api/)
[![License](https://img.shields.io/pypi/l/nexusphp-api.svg)](https://github.com/nexusphp/nexusphp-api/blob/main/LICENSE)

## 项目结构

```
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 安装（推荐）

```bash
pip install nexusphp-api
```

### 从源代码安装

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

### 安装开发依赖

```bash
pip install -r requirements.txt
```

## 快速开始

### 基本使用

```python
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}")
```

### 动态更新配置

```python
# 更新 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 主类

```python
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（种子）
- 详见代码和文档

## 运行测试

### 运行所有测试

```bash
pytest tests/
```

### 运行特定测试

```bash
pytest tests/test_api_client.py
```

### 运行测试并显示覆盖率

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

### 使用 unittest 运行

```bash
python -m unittest discover tests
```

## 代码质量检查

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

### 格式化代码

```bash
black .
isort .
```

### 代码 lint 检查

```bash
flake8 .
```

### 类型检查

```bash
mypy .
```

## 响应格式

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

```json
{
  "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

### 构建和发布

```bash
# 构建包
python -m build

# 发布到 PyPI
twine upload dist/*
```

## 注意事项

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

## 许可证

MIT License

## 支持和联系

如有问题或建议，请：
- 提交 Issue: [GitHub Issues](https://github.com/nexusphp/nexusphp-api/issues)
- 查看文档: [项目 Wiki](https://github.com/nexusphp/nexusphp-api/wiki)

