API Reference¶

Component¶

A component for HTTP sending. (Header, Query, Path, Body)

class Component¶

Based object on Header, Query, Path, Form and Body

component_name¶

Used to define the name of the component name. In default case, it can cause an AttributesError.

Type:: Callable[[str], str]

classmethod custom_name(name: str) → type[Self]¶

Define the name of the component(Header, Query, Form and Path) Used when the component name must be different from the parameter name.

Parameters:: name (str) – The name of the component (Header, Query, Path and Form)

Examples

>>> @Session.single_session("https://api.yhs.kr")
... @request("GET", "/metro/station")
... async def station_search_with_query(
...     session: Session,
...     response: aiohttp.ClientResponse,
...     station_name: Annotated[str, Query.custom_name('name')]
... ) -> list[...]:
...     # A header called "name" is substituted with the value of station_name parameter.
...     pass

Warning

The body component and path component didn’t allow the custom_name method to be used.

classmethod to_camel() → type[Self]¶

Define the name of the component(Header, Query, Form and Path) to follow camel case.

Examples

>>> @Session.single_session("https://api.yhs.kr")
... @request("GET", "/metro/station")
... async def station_search_with_query(
...     session: Session,
...     response: aiohttp.ClientResponse,
...     station_name: Annotated[str, Query.to_camel()]
... ) -> list[...]:
...     # A header called "stationName" is substituted with the value of station_name parameter.
...     pass

Warning

The body component and path component didn’t allow the to_camel method to be used.

classmethod to_pascal() → type[Self]¶

Define the name of the component(Header, Query, Form and Path) to follow pascal case.

Examples

>>> @Session.single_session("https://api.yhs.kr")
... @request("GET", "/metro/station")
... async def station_search_with_query(
...     session: Session,
...     response: aiohttp.ClientResponse,
...     station_name: Annotated[str, Query.to_pascal()]
... ) -> list[...]:
...     # A header called "StationName" is substituted with the value of station_name parameter.
...     pass

Warning

The body component and path component didn’t allow the to_pascal method to be used.

class BodyJson¶

Bases: Component

This class defines the parameters of a function used in Body of the HTTP request in dictionary format.

Examples

>>> def function(data: typing.Annotated[str, BodyJson]):
...    pass

class Body¶

Bases: UnsupportedCustomNameComponent

This class is used to indicate that a method’s parameter is used in the HTTP Request’s Body.

Examples

>>> def function(body: dict | Body):
...    pass

class Form¶

Bases: Component

This class defines the parameters of a function to be used in the FormData of an HTTP Request.

Examples

>>> def function(data: str | Form):
...    pass

class Header¶

Bases: Component

This class is used when a function’s parameters are used as headers in an HTTP request.

Examples

>>> def function(header: str | Header):
...    pass

class Path¶

Bases: UnsupportedCustomNameComponent

This class is used when a function’s parameters are used as path in an HTTP request. The parameters associated with the Path populate a portion of the HTTP URL.

Examples

>>> def function(path: str | Path):
...    pass

class Query¶

Bases: Component

This class is used when a function’s parameters are used as query in an HTTP request.

Examples

>>> def function(query: str | Query):
...    pass

Request Core¶

class RequestCore¶

A class that implements functions for HTTP requests.

name¶

The name of the request.

Type:: str

func¶

The coroutine function that is executed when the request is called.

Type:: Callable[…, Coroutine[Any, Any, T]]

method¶

HTTP method (example. GET, POST)

Type:: str

path¶

Request path. Path connects to the base url.

Type:: str

directly_response¶

Returns a aiohttp.ClientResponse without executing the function’s body statement.

Type:: bool

params¶

Request parameters.

Type:: Optional[dict[str, Any]]

headers¶

Request headers.

Type:: Optional[dict[str, Any]]

body¶

Request body.

Type:: Optional[Any | aiohttp.FormData]

header_parameter¶

Function parameters used in the header

Type:: dict[str, inspect.Parameter]

query_parameter¶

Function parameters used in the query(parameter)

Type:: dict[str, inspect.Parameter]

body_json_parameter¶

Function parameters used in body json.

Type:: dict[str, inspect.Parameter]

body_form_parameter¶

Function parameters used in body form.

Type:: dict[str, inspect.Parameter]

path_parameter¶

Function parameters used in the path.

Type:: dict[str, inspect.Parameter]

body_parameter¶

Function parameter used in the body. The body parameter must take only Collection, or aiohttp.FormData.

Type:: Optional[inspect.Parameter]

body_parameter_type¶

The type of body parameter. When body_parameter type is aiohttp.FormData, the body_parameter_type is ‘data’. Else body_parameter_type is Collection, the body_parameter_type is ‘json’.

Type:: Literal[‘json’, ‘data’]

response_parameter¶

Function parameter name to store the HTTP result in.

Type:: list[str]

request_kwargs¶

Keyword Arguments are passed directly request method.

Type:: dict[str, Any]

@before_hook¶

A decorator that registers a coroutine as a pre-invoke hook. A pre-invoke hook is called directly before the HTTP request is called.

This makes it a useful function to set up authorizations or any type of set up required.

Example

class GithubService(Session):
    def __init__(self, token: str):
        self.token = token
        super().__init__("https://api.github.com")

    @request("GET", "/users/{user}/repos")
    def list_repositories(user: Annotated[str, Path]) -> dict[str, Any]:
        pass

    @list_repoisitories.before_hook
    async def authorization(self, req_obj: RequestCore, path: str):
        req_obj.header["Authorization"] = f"Bearer: {self.token}"
        return req_obj, path

@after_hook¶

A decorator that registers a coroutine as a post-invoke hook. A post-invoke hook is called directly after the returned HTTP response.

This makes it a useful function to check correct response or any type of clean up response data.

Example

class GithubService(Session):
    def __init__(self):
        super().__init__("https://api.github.com")

    @request("GET", "/users/{user}/repos")
    def list_repositories(user: Annotated[str, Path]) -> dict[str, Any]:
        pass

    @list_repoisitories.after_hook
    async def validation_status(self, response: aiohttp.ClientResponse):
        if response.status_code != 200:
            raise Exception("ERROR!")
        return await response.json()

copy() → Self¶

Creates a copy of this request.

Returns:: A new istnace of this request.
Return type:: RequestCore

get_request_kwargs() → dict[str, Any]¶: Get keyword arguments to call request method

property body_type: Literal['json', 'data'] | None¶

Returns the final body type

Return type:: :class:`Literal`[‘json’, ‘data’]

property is_body: bool¶

Returns whether the HTTP request has a body element.

Return type:: bool

property is_formal_form: bool¶

Returns whether the body element in the HTTP request is of type Form.

Return type:: bool

@request(method: str, path: str)¶

A decoration for making request. Create an HTTP client-request, when decorated function is called.

Parameters:

name (Optional[str]) – The name of the Request
method (str) – HTTP method (example. GET, POST)
path (str) – Request path. Path connects to the base url.
params (Optional[dict[str, Any]]) – Request parameters.
headers (Optional[dict[str, Any]]) – Request headers.
body (Optional[Any | aiohttp.FormData]) – Request body.
directly_response (bool) – Returns a aiohttp.ClientResponse without executing the function’s body statement.
header_parameter (list[str]) – Function parameter names used in the header
query_parameter (list[str]) – Function parameter names used in the query(parameter)
form_parameter (list[str]) – Function parameter names used in body form.
body_json_parameter (list[str]) – Function parameter names used in body json.
path_parameter (list[str]) – Function parameter names used in the path.
body_parameter (str) – Function parameter name used in the body. The body parameter must take only Collection, or aiohttp.FormData.
response_parameter (list[str]) – Function parameter name to store the HTTP result in.
**request_kwargs

Warning

Form_parameter and Body Parameter can only be used with one or the other.

@get(path: str)¶

@post(path: str)¶

@options(path: str)¶

@put(path: str)¶

@delete(path: str)¶: Same feature as ahttp_client.request.

Session¶

class Session¶

A class to manage session for managing decoration functions.

@single_session(base_url: str, loop: asyncio.AbstractEventLoop | None, **session_kwargs)¶

A single session for one request.

Parameters:

base_url (str) – base url of the API.
loop (asynico.AbstractEventLoop) – event loop used for processing HTTP requests.
session_kwargs – Keyword argument used in aiohttp.ClientSession

Example

The session is defined through the function’s decoration.

@Session.single_session("https://api.yhs.kr")
@request("GET", "/bus/station")
async def station_query(session: Session, name: Query | str) -> aiohttp.ClientResponse:
    pass

async after_request(response: ClientResponse) → ClientResponse | T¶

A special method that acts as a session local post-invoke. This is similar to RequestCore.after_request().

When RequestCore.after_request() exists, this method is called before RequestCore.after_request() called.

Parameters:: response (aiohttp.ClientResponse) – The result of HTTP request.
Returns:: Cleanup response HTTP results. If RequestCore.after_request exists, the response type of RequestCore.after_request() will follow the type of this method.
Return type:: aiohttp.ClientResponse | T

async before_request(request: RequestCore, path: str) → tuple[RequestCore, str]¶

A special method that acts as a session local pre-invoke hook. This is similar to RequestCore.before_request().

When RequestCore.before_request() exists, this method is called after RequestCore.before_request() called.

Parameters:

request (RequestCore) – The instance of RequestCore.
path (str) – The final string of the request url.

Returns:

The return type must be the same as the parameter.

Return type:

Tuple[RequestCore, str]