Metadata-Version: 2.4
Name: py-httpx-toolkit
Version: 1.0.3
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
Requires-Dist: jsonpath-ng>=1.5.3
Requires-Dist: jsonschema>=4.21.0
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

[English](README.en.md) | 中文

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

## 功能特点

- 支持同步和异步 HTTP 请求
- 支持预配置客户端参数
- 支持复用已有的客户端实例
- 自动管理客户端生命周期

## 安装

```bash
pip install py-httpx-toolkit
```
或使用 uv：

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

## 快速开始

### 基本使用

```python
from py_httpx_toolkit import Httpx

# 创建 Httpx 实例
httpx_inst = Httpx()

# 同步请求
response = httpx_inst.request(method='GET', url='https://example.com')
print(response.status_code)
print(response.text)

# 异步请求
import asyncio


async def fetch():
    response = await httpx_inst.async_request(method='GET', url='https://example.com')
    print(response.status_code)
    print(response.text)


asyncio.run(fetch())
```

### 预配置客户端

```python
from py_httpx_toolkit import Httpx

# 创建带有默认配置的 Httpx 实例
httpx_inst = Httpx(client_kwargs={
    'headers': {'Authorization': 'Bearer token'},
    'timeout': 30,
    'follow_redirects': True
})

# 使用默认配置发起请求
response = httpx_inst.request(method='GET', url='https://api.example.com/data')
```

### 使用自定义客户端

```python
from py_httpx_toolkit import Httpx
import httpx

httpx_inst = Httpx()

# 创建自定义客户端
client = httpx.Client(headers={'X-Custom': 'value'})

# 使用自定义客户端发起请求
response = httpx_inst.request(client=client, method='GET', url='https://example.com')
```

## API 文档

### Httpx 类

#### 初始化

```python
Httpx(client_kwargs: Optional[dict] = None)
```

创建 Httpx 实例，可传入默认客户端配置。

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

#### client()

```python
client(**kwargs) -> httpx.Client
```

创建同步 HTTP 客户端。

**参数:**
- `**kwargs`: 额外的客户端配置参数，会覆盖默认配置

**返回:**
- `httpx.Client`: 配置好的同步 HTTP 客户端实例

#### async_client()

```python
async_client(**kwargs) -> httpx.AsyncClient
```

创建异步 HTTP 客户端。

**参数:**
- `**kwargs`: 额外的客户端配置参数，会覆盖默认配置

**返回:**
- `httpx.AsyncClient`: 配置好的异步 HTTP 客户端实例

#### request()

```python
request(
    client: Optional[httpx.Client] = None,
    client_kwargs: Optional[dict] = None,
    **kwargs
) -> httpx.Response
```

发起同步 HTTP 请求。

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

**返回:**
- `httpx.Response`: HTTP 响应对象

#### async_request()

```python
async_request(
    client: Optional[httpx.AsyncClient] = None,
    client_kwargs: Optional[dict] = None,
    **kwargs
) -> httpx.Response
```

发起异步 HTTP 请求。

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

**返回:**
- `httpx.Response`: HTTP 响应对象

## 依赖

该项目依赖以下 Python 包：

| 依赖包 | 版本要求        | 说明 |
| :--- |:------------| :--- |
| **httpx** | &ge; 0.27.0 | 高性能 HTTP 客户端库，支持同步和异步请求 |


## 项目主页

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

## 作者

**Author**: 郭磊 

**Email**: 174000902@qq.com

## 许可证

MIT License
