Metadata-Version: 2.4
Name: nb_aiohttp
Version: 1.0
Summary: 更好用的 aiohttp 客户端，支持同步和异步使用。 性能碾压 httpx 和 requests 400%
Author-email: ydf0509 <ydf0509@xxx.com>
License: MIT
Project-URL: Homepage, https://github.com/ydf0509/nb_aiohttp
Project-URL: Repository, https://github.com/ydf0509/nb_aiohttp
Project-URL: Issues, https://github.com/ydf0509/nb_aiohttp/issues
Keywords: asyncio,aiohttp,httpx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: typing_extensions>=3.7; python_version < "3.8"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.14; extra == "test"
Provides-Extra: dev
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.812; extra == "dev"

# nb_aiohttp

`nb_aiohttp` 是一个基于 `aiohttp` 的Python HTTP客户端库，旨在提供更易于使用的API和更强大的功能。它通过懒加载机制解决了 `aiohttp.ClientSession` 无法在模块级别实例化的问题，并同时提供了同步和异步两种请求方式。

## 核心特性

*   **极致性能**: 底层使用 `aiohttp`，异步性能远超 `httpx`，同步性能数倍于 `requests`。
*   **懒加载实例化**: 允许在模块的全局作用域直接创建客户端实例，无需在异步函数内部进行。
*   **同步/异步双支持**: 同时提供 `NbAioHttpClient` (异步) 和 `NbSyncHttpClient` (同步) 两种客户端，满足不同场景的需求。
*   **简洁的API**: 提供了类似 `requests` 的 `get`, `post` 等方法，调用更直观、更简单。
*   **自动重试**: 内置请求失败后的自动重试机制，增加了应用的健壮性。
*   **统一的响应对象**: 封装了 `NbHttpResp` 对象，可以方便地获取响应状态、文本内容，并能通过 `.dict` 属性直接将JSON响应转换为Python字典。
*   **集成日志**: 与 `nb_log` 无缝集成，自动记录请求错误和慢速请求，便于调试和监控。

## 安装

```bash
pip install nb_aiohttp
```

## 快速上手

### 异步用法 (`NbAioHttpClient`)

`NbAioHttpClient` 封装了 `aiohttp.ClientSession`，但允许你在任何地方实例化它，包括全局作用域。默认配置下，如果HTTP响应状态码表示失败（如4xx, 5xx），将会直接抛出异常。

```python
import asyncio
from nb_aiohttp import NbAioHttpClient

# 在模块顶层直接实例化，无需在 async 函数内
http = NbAioHttpClient(timeout=10, connector_limit=100)

async def main():
    # 发起 GET 请求
    resp = await http.get('https://api.github.com/events')

    # 直接处理成功的响应
    print(f"Response Text (first 100 chars): {resp.text[:100]}")
    
    # 发起 POST 请求
    post_data = {'key': 'value'}
    resp_post = await http.post('https://httpbin.org/post', json=post_data)
    print(f"POST Response: {resp_post.dict}")

    # 使用完毕后关闭 session
    await http.close()

if __name__ == '__main__':
    asyncio.run(main())
```

### 同步用法 (`NbSyncHttpClient`)

`NbSyncHttpClient` 让你可以在同步代码中享受 `aiohttp` 的高性能，而无需关心 `asyncio` 事件循环的管理。

```python
from nb_aiohttp import NbSyncHttpClient

# 实例化同步客户端
sync_http = NbSyncHttpClient(timeout=10)

# 在后台启动事件循环线程
sync_http.run_forever()

def main():
    # 发起 GET 请求，用法和 requests 库非常相似
    resp = sync_http.get('https://api.github.com/events')

    # 直接处理响应
    print(f"Response Text (first 100 chars): {resp.text[:100]}")

    # 发起 POST 请求
    post_data = {'key': 'value'}
    resp_post = sync_http.post('https://httpbin.org/post', json=post_data)
    print(f"POST Response: {resp_post.dict}")

if __name__ == '__main__':
    main()
```

## 与其他库的对比

### 性能和易用性

| 库 (Library)         | 性能 (Performance)                    | 易用性 (Ease of Use)                                       |
| -------------------- |-------------------------------------| ---------------------------------------------------------- |
| **`NbAioHttpClient`**  | **极高** (基于`aiohttp`)，约是 `httpx` 的5倍 | **非常简单**。支持全局实例化，仅需1次`await`。             |
| **`NbSyncHttpClient`** | **高**，约是 `requests` 的4倍             | **非常简单**。API类似`requests`，无需管理事件循环。        |
| `aiohttp` (原生)     | 极高                                  | 复杂。不能全局实例化，需要`async with`和多次`await`。      |
| `httpx` (异步)       | 较低                                  | 简单。支持全局实例化。                                     |
| `requests`           | 较低 (同步阻塞)                           | 非常简单。                                                 |

<p align="right">(*性能数据基于在特定场景下的压测结果，仅供参考*)</p>

### 代码简洁性对比

**原生 `aiohttp` 的繁琐**

需要手动管理 `ClientSession` 的生命周期，不能在全局实例化，导致代码冗长。

```python
import aiohttp
import asyncio

# 必须在 async 函数内创建 session
async def fetch_with_aiohttp():
    async with aiohttp.ClientSession() as session:
        async with session.get('https://api.github.com/events') as response:
            # 2次 async with, 3次 await (包括 response.json())
            if response.status == 200:
                text = await response.text()
                print(text[:100])
```

**`NbAioHttpClient` 的简洁**

实现了懒加载，可以在全局实例化，API设计极大简化了调用过程。

```python
from nb_aiohttp import NbAioHttpClient
import asyncio

# 可以在全局实例化
http = NbAioHttpClient()

async def fetch_with_nb_aiohttp():
    # 仅需 1次 await
    resp = await http.get('https://api.github.com/events')
    print(resp.text[:100])
```

## API 参考

### `NbAioHttpClient`

异步客户端。

*   `__init__(self, *, timeout: int | float = 30, connector_limit: int = 100, max_retries: int = 3, is_raise_for_status: bool = True, **kwargs)`
    *   `timeout`: 默认请求超时时间。
    *   `connector_limit`: TCP连接池的大小。
    *   `max_retries`: 请求失败时的最大重试次数。
    *   `is_raise_for_status`: 当响应状态码为4xx或5xx时，是否记录错误日志。异常总是会抛出。
    *   其他 `aiohttp.ClientSession` 支持的参数。

*   `async def request(self, method, url, **kwargs)`: 发起一个HTTP请求。
*   `async def get(self, url, **kwargs)`: 发起GET请求。
*   `async def post(self, url, **kwargs)`: 发起POST请求。
*   `async def close(self)`: 关闭客户端会话。

### `NbSyncHttpClient`

同步客户端。

*   `__init__(self, **kwargs)`: 参数与 `NbAioHttpClient` 相同。
*   `run_forever(self)`: 启动后台事件循环线程。**在使用任何请求方法前必须调用此方法**。
*   `request(self, method, url, **kwargs)`: 发起一个同步的HTTP请求。
*   `get(self, url, **kwargs)`: 发起同步GET请求。
*   `post(self, url, **kwargs)`: 发起同步POST请求。

---

*This README was generated by an AI assistant.*
