http-noah 0.2.1

基本示例

让我们从一个基本示例开始。假设我们的宠物庇护所API正在运行在http://localhost:8080/api/v1

from pydantic import BaseModel
from http_noah.sync_client import SyncHTTPClient

class Pet(BaseModel):
    name: str

def main():
    with SyncHTTPClient("localhost", 8080) as client:
        pet: Pet = client.get("/pets/1", response_type=Pet)

让我们更仔细地看看这里发生了什么

• 我们只提供了host和port，api_base默认为/api/v1，这样我们就不必在每个URL调用前添加它

• 我们要求http_noah将API响应转换为期望类型的实例（否则抛出异常）

• 我们使用上下文管理器来确保一切都会及时清理。在更复杂的代码中，你可能考虑一种生命周期管理器，例如我在我的演示Hanuka项目中使用的那种（源代码）

异步示例与此类似

from http_noah.async_client import AsyncHTTPClient

async def main():
    async with AsyncHTTPClient("localhost", 8080) as client:
        pet: Pet = await client.get("/pets/1", response_type=Pet)

由于这个库的目的是为同步和异步代码提供类似接口，所以我将专注于异步示例，并在存在差异的情况下留下注释，我会努力将这些差异减少到很少。

客户端支持以下方法，这些方法映射对应的HTTP动词

.get(...)
.post(...)
.put(...)
.delete(...)

发送数据同样简单 - 不论是字典还是Pydantic模型。

对于Pydantic模型，您可以直接将它们传递给例如.post()的body参数

async def create_pet():
    async with AsyncHTTPClient("localhost", 8080) as client:
        pet = Pet(name="Crispy")
        await client.post("/pets", body=pet, response_type=Pet)

如果您只想发送JSON数据，则需要明确指出

from http_noah.common import JSONData

async def create_pet():
    async with AsyncHTTPClient("localhost", 8080) as client:
        pet = {"name": "Crispy"}
        await client.post("/pets", body=JSONData(data=pet), response_type=Pet)

这对于http_noah了解您的意图是要发送JSON还是表单（两者都可以是Python字典）是必要的。有关表单和文件上传的更多信息，请参阅下面的专用部分。

再次，我更喜欢用Pydantic模型来表示我发送和接收的所有内容 - 这使得生活变得如此简单，以至于您会很快上瘾。

嵌套客户端

现在我们已经了解了基本用法，让我们看看如何构建我一开始承诺的美丽嵌套客户端。

让我们从根类开始构建我们的假设宠物庇护所API客户端

from __future__ import annotations

from http_noah.async_client import AsyncAPIClientBase, AsyncHTTPClient

class PetSanctuaryClient(AsyncAPIClientBase):
    @classmethod
    def new(cls, host: str, port: int, scheme: str = "https") -> PetSanctuaryClient:
        client = AsyncHTTPClient(host=host, port=port, scheme=scheme)
        return cls(client=client)

目前，这只是一个样板类，除了有一个构建函数外，没有任何惊人的功能。注意，我使用的是AsyncAPIClientBase而不是AsyncHTTPClient。

现在让我们实现宠物子API

from __future__ import annotations

from dataclasses import dataclass
from http_noah.async_client import AsyncAPIClientBase, AsyncHTTPClient

# Skipped model definitions here - as in the basic example

@dataclass
class PetClient:
    client: AsyncHTTPClient

    class paths:
        prefix: str = "/pets"
        list: str = prefix
        get: str = prefix + "/{id}"
        create: str = prefix

    async def list(self) -> Pets:
        return await self.client.get(self.paths.list, response_type=Pets)

    async def get(self, id: int) -> Pet:
        return await self.client.get(self.paths.get.format(id=id), response_type=Pet)

    async def create(self, pet: Pet) -> Pet:
        return await self.client.post(self.paths.create, body=Pet, response_type=Pet)

@dataclass
class PetSanctuaryClient(AsyncAPIClientBase):
    pets: PetClient

    @classmethod
    def new(cls, host: str, port: int, scheme: str = "https") -> PetSanctuaryClient:
        client = AsyncHTTPClient(host=host, port=port, scheme=scheme)
        pet_client = PetClient(client)
        return cls(client=client, pets=pet_client)

现在我们开始吧！让我们享受这个过程

psc = PetSanctuaryClient("localhost", 8080, scheme="http")
async with psc:
    pets = await psc.pets.list()
    pet = await psc.pets.get(1)

同样，我们可以实现其他子API客户端，并轻松地将它们嵌套。

认真对待

from http_noah.common import ClientOptions, Timeout
from http_noah.async_client import AsyncHTTPClient

options = ClientOptions(Timeout(total=10)
async with AsyncHTTPClient(host="localhost", port=80, options=options) as client:
    await client.get(...)  # Limited to 10 seconds
    await client.post(..., timeout=Timeout(total=20))  # per call override

from http_noah.common import Timeout

async with PetSanctuaryClient("localhost", 8080, scheme="http") as psc:
    pets = await psc.pets.list()
    with psc.client.timeout(Timeout(total=1):
        pet = await psc.pets.get(1)  # Limited to 1 second

from typing import Literal
from pydantic import BaseModel
from http_noah.common import FormData

class TokenResponse(BaseModel):
    access_token: str
    token_type: Literal["bearer"]

async def get_access_token():
    login_form = FormData(data={
        "grant_type": "password",
        "username": "foo",
        "password": "secret",
    })
    async with AsyncHTTPClient("localhost", 8080) as client:
        tr = await client.post("/access_token", body=login_form, response_type=TokenResponse)

from pathlib import Path

from http_noah.common import UploadFile

async with AsyncHTTPClient("localhost", 8080) as client:
    await client.post(
        "/pets/1/photo",
        body=UploadFile(name="thumbnail", path=Path("myphoto.jpg"),
    )

from http_noah.common import ClientOptions
from http_noah.async_client import AsyncHTTPClient

options = ClientOptions(ssl_verify_cert=False)
async with AsyncHTTPClient(host="localhost", port=80, options=options) as client:
    ...

async with AsyncHTTPClient("localhost", 8080) as client:
    # Bearer token
    client.set_auth_token("my-secret-token")
    # Or Basic Auth
    client.set_auth_basic("my-username", "my-password")