py-httpx-toolkit 1.0.5

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

py_httpx_toolkit

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

功能特性

• 🚀 支持同步和异步 HTTP 客户端
• ⚙️ 支持预配置默认参数
• 🔄 支持复用已有的客户端实例
• 📦 提供 JSONPath 数据提取工具
• ✅ 提供 JSON Schema 数据校验功能
• 📡 支持统一的请求接口，自动管理客户端生命周期

安装方式

使用 pip

pip install py-httpx-toolkit

使用 uv

uv add py-httpx-toolkit

快速开始

同步请求

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())

异步请求

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 类

初始化

http = Httpx(client_kwargs=None)

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

创建同步客户端

client = http.client(**kwargs)

返回 httpx.Client 实例

创建异步客户端

async_client = http.async_client(**kwargs)

返回 httpx.AsyncClient 实例

同步请求

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

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

异步请求

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

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

responses 模块

Base 模型

from py_httpx_toolkit.responses import Base

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

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

utils 模块

JSONPath 工具函数

from py_httpx_toolkit.utils import (
    json_find,
    json_find_values,
    json_find_first,
    json_find_first_value
)
from jsonpath_ng import parse

# 创建 JSONPath 表达式
expression = parse('$.data[*].name')

# 查找所有匹配项
matches = json_find(expression, data)

# 提取所有匹配值
values = json_find_values(expression, data)

# 查找第一个匹配项
first_match = json_find_first(expression, data)

# 提取第一个匹配值
first_value = json_find_first_value(expression, data)

JSON Schema 校验

from py_httpx_toolkit.utils import json_is_valid

schema = {"type": "object", "properties": {"name": {"type": "string"}}}
data = {"name": "test"}

is_valid = json_is_valid(schema, data)
print(is_valid)  # True

响应模型转换

from py_httpx_toolkit.utils import build_base_instance

# 从 httpx.Response 转换
result = build_base_instance(response)

# 从字典转换
result = build_base_instance({"errcode": 0, "errmsg": "ok"})

项目结构

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

依赖

• httpx >= 0.27.0
• pydantic >= 2.0.0
• jsonpath-ng >= 1.5.3
• jsonschema >= 4.20.0
• jsonpath-rw-ext>=1.2.2

项目主页

https://gitee.com/guolei19850528/py_httpx_toolkit

作者

郭磊

[e-mail]

许可证

MIT License