Metadata-Version: 2.4
Name: py-httpx-toolkit
Version: 1.0.6
Summary: 一个对 httpx 库的轻量级封装，简化了 HTTP 客户端的创建和使用，支持同步和异步两种请求模式。
Author-email: Guolei <174000902@qq.com>
Maintainer-email: Guolei <174000902@qq.com>
License: MIT License
Project-URL: Homepage, https://gitee.com/guolei19850528/py_httpx_toolkit
Project-URL: Repository, https://gitee.com/guolei19850528/py_httpx_toolkit
Project-URL: Documentation, https://gitee.com/guolei19850528/py_httpx_toolkit#readme
Keywords: httpx,http,client,async,sync,api
Classifier: Development Status :: 3 - Alpha
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.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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.10.6
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: setuptools>=61.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# py_httpx_toolkit

一个对 httpx 库的轻量级封装工具包，简化了 HTTP 客户端的创建和使用，支持同步和异步两种请求模式。

## 功能特性

- 🚀 支持同步和异步 HTTP 客户端
- ⚙️ 支持预配置默认参数
- 🔄 支持复用已有的客户端实例
- 📡 支持统一的请求接口，自动管理客户端生命周期

## 安装方式

### 使用 pip

```bash
pip install py-httpx-toolkit
```

### 使用 uv

```bash
uv add py-httpx-toolkit
```

## 快速开始

### 同步请求

```python
from py_httpx_toolkit import Httpx

# 创建 HTTP 客户端实例
http = Httpx(client_kwargs={"timeout": 30})

# 发起同步请求
response = http.request(method='GET', url='https://api.example.com/data')
print(response.status_code)
print(response.json())
```

### 异步请求

```python
import asyncio
from py_httpx_toolkit import Httpx

async def main():
    http = Httpx()
    
    # 发起异步请求
    response = await http.async_request(method='GET', url='https://api.example.com/data')
    print(response.status_code)
    print(response.json())

asyncio.run(main())
```

## API 文档

### Httpx 类

#### 初始化

```python
http = Httpx(client_kwargs=None)
```

- `client_kwargs`: 客户端的默认配置参数，如 headers、timeout 等

#### 创建同步客户端

```python
client = http.client(**kwargs)
```

返回 `httpx.Client` 实例

#### 创建异步客户端

```python
async_client = http.async_client(**kwargs)
```

返回 `httpx.AsyncClient` 实例

#### 同步请求

```python
response = http.request(client=None, client_kwargs=None, **kwargs)
```

- `client`: 已有的同步客户端实例（可选）
- `client_kwargs`: 创建新客户端时的配置参数（可选）
- `**kwargs`: 请求参数，如 method、url、headers、data、json 等

#### 异步请求

```python
response = await http.async_request(client=None, client_kwargs=None, **kwargs)
```

- `client`: 已有的异步客户端实例（可选）
- `client_kwargs`: 创建新客户端时的配置参数（可选）
- `**kwargs`: 请求参数，如 method、url、headers、data、json 等

### responses 模块

#### Base 模型

```python
from py_httpx_toolkit.responses import Base

# 创建响应模型实例
result = Base(**response.json())
```

用于将 HTTP 响应转换为 Pydantic 模型，支持额外字段。

## 项目结构

```
py_httpx_toolkit/
├── src/
│   └── py_httpx_toolkit/
│       ├── __init__.py      # Httpx 客户端封装
│       └── responses.py     # 响应模型定义
├── .venv/                   # 虚拟环境
├── .gitignore              # Git 忽略配置
└── README.md               # 项目文档
```

## 依赖

- httpx >= 0.27.0
- pydantic >= 2.0.0

## 项目主页

[https://gitee.com/guolei19850528/py_httpx_toolkit](https://gitee.com/guolei19850528/py_httpx_toolkit)

## 作者

**郭磊**

**174000902@qq.com** 

## 许可证

MIT License
