http-noah 0.2.1

Response type

Specifying response type is mandatory unless you expect your request to respond with HTTP 204 “No Content” which generally makes sense for DELETE operations.

• If response Content-Type heading is set to applicaiton/json then JSON data will be decoded for you and can be further parsed using Pydantic model of your choice.

• Otherwise, you can request back either str or bytes

This results in a limitation where with this library you can’t fetch JSON response back as string. But since this is a high-level REST client I’ve yet bumped into this limitation in practice.

To sum it up, here are your options for the response_type argument:

• bytes when a request returns a binary data, e.g image

• str when a request returns text (technically speaking “when the content type is not application/json”)

• dict, list, int, bool, float, str (i.e. any of the JSON -> Python native types), when your request returns JSON data and you don’t want it parsed further into Pydantic objects.

Error handling

Trying to align between sync and async code I aliased common error base classes under common names ConnectionError, HTTPError, and TimeoutError in both http_noah.sync_client and async_client. This is where it stops though - behind the name these are still requests / aiohttp error classes if you want to dig deeper.

One useful thing that http_noah does for you is making sure to log HTTP body when the error occurs. This is usually a small but vital piece of information to help you understand what’s going on. Sadly enough, it requires quite a bit of tinkering to dig this info out. Just one example is that calling aiohttp’s response object raise_for_status() method will actually return the underlying HTTP connection back to the pool depriving you of reading the error body.

Again, http_noah will log HTTP (error) body when it encounters HTTP errors.

Timeouts

Timeouts can be configured by passing instance of http_noah.common.Timeout class to either .get(), put(), etc. methods or setting it per client instance through ClientOptions:

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

However, if you reflect on the nested client approach as was suggested earlier, you can quickly notice that re-defining timeout argument in all your high-level methods is very onerous. Fortunately, http_noah stands true to its name and provides an easy solution with the help of timeout context manager that both sync and async client implements:

Continuing our PetSanctuaryClient example:

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

As you can see, neither PetClient nor PetSanctuaryClient defined any timeout logic yet we can perfectly apply timeouts.

Forms

Forms are not used much today. However, I still encounter them when I need to login into API to get Bearer token.

To use a form with http_noah simply fill it up as a dict, as you would with aiohttp / requests, and pass it through body argument wrapped with FormData:

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)

Files

http-noah provides simple means to upload a file as a multipart encoded form. Best illustrated by example:

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"),
    )

SSL

SSL/TLS are supported as they are in requests and aiohttp. Sometimes however it’s desirable to disable SSL validation, e.g. in your dev environment. This can be done through ClientOptions:

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:
    ...

Authentication

http-noah support both Basic and Bearer token client authentication. These can be set at any time on the existing 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")

It’s a deliberate design decision to omit auth parameters from constructor because in case of, e.g. bearer token, auth info may not be known in advance because one may need to submit a login form first. Hence it’s required to be able to set auth info at a later stage.