HTTP Component

A component used in ahttp_client are Query, Header, Path, and Body. In the HTTP request process in ahttp_client, a component defines as typing.Annotated.

When a list_repository_activites method is called, the request is called as shown below.

 1@AsyncSession.single_session("https://api.github.com/", aiohttp.ClientSession)
 2@request("GET", "/repos/{owner}/{repo}/activity")
 3async def list_repository_activites(
 4    session: AsyncSession,
 5    response: Response,
 6    owner: Annotated[str, Path],
 7    repo: Annotated[str, Path],
 8    activity_type: Annotated[str, Query],
 9    authorization: Annotated[str, Header]
10) -> dict[str, Any]:
11    return response.json()
12
13await list_repository_activites(
14    owner="gunyu1019",
15    repo="ahttp_client",
16    activity_type="push",
17    authorization="Bearer <GITHUB TOKEN>"
18)
19
20# curl https://api.github.com/repos/gunyu1019/ahttp_client/activity?activity_type=push \
21#    -H "authorization: Bearer <GITHUB TOKEN>"

Note

An HTTP Component can be defined as typing.Union instead of typing.Annotated.

@AsyncSession.single_session("https://api.github.com/", aiohttp.ClientSession)
@request("GET", "/repos/{owner}/{repo}/activity")
async def list_repository_activites(
    session: AsyncSession,
    response: Response,
    owner:str | Path,
    repo: str | Path,
    activity_type: str | Query,
    authorization: str | Header  # or, authorization: typing.Union[str, Header]
) -> dict[str, Any]:
    return response.json()

However, using typing.Annotated is recommended to follow correct Python syntax.

Usage by Component

  • Header - Configure the header for the HTTP component.

  • Query - Insert a value inside the URL parameter.

  • Path - Insert the specified value(s) inside the path placeholder. The path placeholder is using curly brackets: {}

  • Body - Send the whole request body as one value. dict, list, and tuple are encoded as JSON. Anything else, including a file-like object, is sent as raw body data.

  • BodyJson - Send one field of a JSON request body. Several BodyJson parameters on the same method are merged into a single JSON object. Use custom_key for a nested (dot-separated) key.

  • BodyForm - Send one field of a form request body. Adding file metadata (see metadata) or passing a file-like value switches the request to multipart/form-data automatically; otherwise all BodyForm fields are sent URL-encoded.

Warning

A request can only use one of Body, BodyJson, or BodyForm for its body. Mixing Body with BodyJson or BodyForm on the same method can raise a TypeError.

Custom Component Name

According to PEP 8 rules, the parameter names of method must be lowercase, with words separated by underscores. (reference)

The queries or headers in an API can be named in Camel Case, or Pascal Case.

To follow the PEP 8 rules as described, an ahttp_client package provides a custom component name.

 1@AsyncSession.single_session("https://api.github.com/", aiohttp.ClientSession)
 2@request("GET", "/repos/{owner}/{repo}/activity")
 3async def list_repository_activites(
 4    session: AsyncSession,
 5    response: Response,
 6    owner: Annotated[str, Path],
 7    repo: Annotated[str, Path],
 8    activity_type: Annotated[str, Query],
 9    token: Annotated[str, Header.custom_name("Authorization")]
10) -> dict[str, Any]:
11    return response.json()
12
13await list_repository_activites(
14    owner="gunyu1019",
15    repo="ahttp_client",
16    activity_type="push",
17    token="Bearer <GITHUB TOKEN>"
18)
19
20# curl https://api.github.com/repos/gunyu1019/ahttp_client/activity?activity_type=push \
21#    -H "Authorization: Bearer <GITHUB TOKEN>"

As in the example above, insert the GITHUB API TOKEN in token argument of list_repository_activites method. During the calling process, the key of Header has been overridden to “Authorization”.

Warning

Custom component names only work on Header, Query, BodyJson, and BodyForm. Path values have to match a placeholder in the request path, and Body has no field key to rename in the first place, so calling custom_name on either one raises NotImplementedError.