Metadata-Version: 2.4
Name: v123pan
Version: 1.0.0
Summary: 123云盘 API Python SDK，支持 OAuth2 和密钥认证
Author: 123Pan Developer
License: MIT
Project-URL: Homepage, https://github.com/yourusername/v123pan
Project-URL: Documentation, https://github.com/yourusername/v123pan#readme
Project-URL: Repository, https://github.com/yourusername/v123pan.git
Project-URL: Issues, https://github.com/yourusername/v123pan/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"

# v123pan - 123云盘 Python SDK

123云盘 API 的 Python SDK，支持 OAuth2 和密钥认证两种方式。

## 特性

- 🎯 简洁易用的 API 设计
- 🔐 支持 OAuth2 认证（refresh_token 自动刷新）
- 🔑 支持密钥认证
- 📁 完整的文件操作接口
- ⬆️ 文件上传下载支持
- 🔄 离线下载支持
- 📱 异步支持（基于 httpx）

## 安装

```bash
pip install v123pan
```

## 快速开始

### OAuth2 认证（推荐）

```python
import asyncio
from v123pan import V123Pan
from v123pan.const import FILMLY_CLIENT_ID, FILMLY_CLIENT_SECRET

async def main():
    # 创建客户端
    client = V123Pan(
        client_id=FILMLY_CLIENT_ID,
        client_secret=FILMLY_CLIENT_SECRET,
        oauth_file="token.json"
    )
    
    # 交互式授权（首次使用）
    result = await client.auth.authorize_interactive(
        FILMLY_CLIENT_ID,
        FILMLY_CLIENT_SECRET,
        oauth_file="token.json"
    )
    
    # 后续使用会自动加载 token
    user_info = await client.user.info()
    print(f"用户名: {user_info['data']['nickname']}")

asyncio.run(main())
```

### 密钥认证

```python
import asyncio
from v123pan import V123Pan

async def main():
    client = V123Pan(
        client_id="your_client_id",
        client_secret="your_client_secret"
    )
    
    user_info = await client.user.info()
    print(f"用户名: {user_info['data']['nickname']}")

asyncio.run(main())
```

## 使用示例

### 获取文件列表

```python
# 获取根目录文件
files = await client.file.list_files(parent_id=0, limit=50)
for f in files['data']['fileList']:
    print(f"{'📁' if f['type'] == 1 else '📄'} {f['filename']}")
```

### 上传文件

```python
# 上传文件
result = await client.upload.upload_file(
    parent_file_id=0,
    file_path="example.txt"
)
```

### 下载文件

```python
# 获取下载链接
download_url = await client.download.get_download_url(file_id=12345)
print(f"下载地址: {download_url['data']['url']}")
```

## 认证说明

### OAuth2 认证

使用 Filmly 官方 OAuth2 配置：

- `client_id`: `uch86homnvtpukbenxv06whun7oayymz`
- `client_secret`: `qxlth6oludklrutxxz8h4dh6jgicpe28`
- `redirect_uri`: `https://api.filmly.netease.com/a/v1/123pan/callback`
- `scope`: `user:base,file:all:read,file:all:write`

授权后 token 会自动保存到文件，后续使用无需重新授权。

### 密钥认证

需要购买 123云盘开发者权益包获取 `client_id` 和 `client_secret`。

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！
