Metadata-Version: 2.4
Name: guangyapan
Version: 0.0.0
Summary: Python guangyapan client.
License: MIT
License-File: LICENSE
Keywords: 115,guangyapan,client
Author: ChenyangGao
Author-email: wosiwujm@gmail.com
Requires-Python: >=3.12,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: errno2 (>=0.0.5)
Requires-Dist: http_response (>=0.0.9)
Requires-Dist: integer_tool (>=0.0.6.1)
Requires-Dist: orjson
Requires-Dist: python-asynctools (>=0.1.3.4)
Requires-Dist: python-dicttools (>=0.0.5)
Requires-Dist: python-filewrap (>=0.3.0)
Requires-Dist: python-hashtools (>=0.0.6)
Requires-Dist: python-http_request (>=0.1.7.1)
Requires-Dist: python-httpfile (>=0.0.6)
Requires-Dist: python-iterutils (>=0.2.10.2)
Requires-Dist: python-property (>=0.0.3)
Requires-Dist: qrcode
Requires-Dist: urllib3_future_request (>=0.0.2)
Requires-Dist: yarl
Project-URL: Documentation, https://guangyapan.readthedocs.io
Project-URL: Homepage, https://github.com/ChenyangGao/guangyapan
Project-URL: Repository, https://github.com/ChenyangGao/guangyapan
Description-Content-Type: text/markdown

![license](https://img.shields.io/github/license/ChenyangGao/guangyapan)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/guangyapan)
![PyPI - Version](https://img.shields.io/pypi/v/guangyapan)
![PyPI - Downloads](https://img.shields.io/pypi/dm/guangyapan)
![PyPI - Format](https://img.shields.io/pypi/format/guangyapan)
![PyPI - Status](https://img.shields.io/pypi/status/guangyapan)

# guangyapan client

[guangyapan](https://github.com/ChenyangGao/guangyapan) 是一个 [光鸭网盘](https://guangyapan.com) 的 [Python](https://python.org) 客户端模块，不过仅提供最直接的接口包装。

支持同步和异步操作，全面封装了各种接口。

## 安装

你可以从 [pypi](https://pypi.org/project/guangyapan/) 安装最新版本

```console
pip install -U guangyapan
```

或者从 [github](https://github.com/ChenyangGao/guangyapan) 安装最新版本

```console
pip install -U git+https://github.com/ChenyangGao/guangyapan@main
```

## 入门介绍

### 1. 导入模块

导入模块

```python
from guangyapan import GuangyaPanClient
```

### 2. 创建实例

创建客户端对象，可以传入 ``access_token`` 和 ``refresh_token``，如果不传，就自己调用 ``GuangyaPanClient.login()`` 方法登录

#### 1. 用 refresh_token 创建实例

```python
refresh_token = "..."
client = GuangyaPanClient(refresh_token)
# NOTE: 立即刷新一个访问令牌出来
client.refresh_access_token()
```

#### 2. 用 access_token 创建实例

```python
access_token = "..."
client = GuangyaPanClient(access_token)
# NOTE: 底层会在检测到 refresh_token 缺失，然后用这个 access_token 授权登录然后获取新的 access_token 和 refresh_token
client.refresh_access_token()
```

#### 3. 手动登录

```python
client = GuangyaPanClient()
# NOTE: 命令行等待扫码登录
client.login()

# 或者提供手机号，则会发送验证码登录
mobile = "+86 xxxxxxxxxxx"
client.login(mobile)
```

### 3. 接口调用

> 我推荐你选择 [`ipython`](https://ipython.readthedocs.io/en/latest/) 作为执行环境，可以交互式地执行代码和分析结果

所有需要直接或间接执行 HTTP 请求的接口，都有同步和异步的调用方式

```python
# 同步调用
client.method(payload)
client.method(payload, async_=False)

# 异步调用
await client.method(payload, async_=True)
```

它们都能接受一个参数 `request`，具体要求可以查看 [`guangyapan.request`](https://guangyapan.readthedocs.io/en/latest/reference/module/client.html#guangyapan.client.guangyapan.request) 的文档。我也封装了一些模块, 它们都能提供一个符合要求的 `request` 函数。更一般的实现，可以参考 [`python-http_request`](https://pypi.org/project/python-http_request/)。

1. [aiohttp_client_request](https://pypi.org/project/aiohttp_client_request/)
1. [aiosonic_request](https://pypi.org/project/aiosonic_request/)
1. [asks_request](https://pypi.org/project/asks_request/)
1. [blacksheep_client_request](https://pypi.org/project/blacksheep_client_request/)
1. [curl_cffi_request](https://pypi.org/project/curl_cffi_request/)
1. [http_client_request](https://pypi.org/project/http_client_request/)
1. [httpcore_request](https://pypi.org/project/httpcore_request/)
1. [httpx_request](https://pypi.org/project/httpx_request/)
1. [niquests_request](https://pypi.org/project/niquests_request/)
1. [pycurl_request](https://pypi.org/project/pycurl_request/)
1. [python-urlopen](https://pypi.org/project/python-urlopen/)
1. [requests_request](https://pypi.org/project/requests_request/)
1. [tornado_client_request](https://pypi.org/project/tornado_client_request/)
1. [urllib3_request](https://pypi.org/project/urllib3_request/)
1. [urllib3_future_request](https://pypi.org/project/urllib3_future_request/)

**注意**：从根本上讲，所有接口的封装，最终都会调用 `GuangyaPanClient.request`

### 4. 检查响应

接口被调用后，如果返回的是 [dict](https://docs.python.org/3/library/stdtypes.html#mapping-types-dict) 类型的数据（说明原本是 [JSON](https://www.json.org)），则可以用 `guangyapan.check_response` 执行检查。首先会查看其中名为 "state" 的键的对应值，如果为  True、1 或不存在，则原样返回被检查的数据；否则，"state" 的对应值大概是 False 或 0，说明有问题出现，会根据实际情况抛出一个异常，但都是 `guangyapan.P115OSError` 的实例。

```python
from guangyapan import check_response

# 检查同步调用
data = check_response(client.method(payload))

# 检查异步调用
data = check_response(await client.method(payload, async_=True))
# 或者
data = await check_response(client.method(payload, async_=True))
```

### 5. 辅助工具

一些简单的封装工具可能是必要的，特别是那种实现起来代码量比较少，可以封装成单个函数的。我把平常使用过程中，积累的一些经验具体化为一组工具函数。这些工具函数分别有着不同的功能，如果组合起来使用，或许能解决很多问题。

```python
from guangyapan import tool
```

