API Reference¶

Component¶

HTTP 요청에 필요한 구성 요소입니다. 구성요소에는 Header, Query, Path, Body 등이 있습니다.

class Component¶

HTTP 구성요소의 기본이 되는 객체입니다.

component_name¶

component 이름을 정의하는 데 사용되는 인수입니다.일반적인 상황에서는 AttributesError 예외를 발생합니다.

Type:: Callable[[str], str]

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

HTTP 구성요소의 이름을 새롭게 정의합니다.구성요소의 키는 메소드의 매개변수 이름을 정의하지만, 다른 이름을 적용하려고 할때 사용합니다.

매개변수:: name (str) – 구성요소의 이름입니다.

예제

>>> @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

경고

Body component와 Path component는 custom_name 메소드를 이용하는 것을 허용하지 않습니다.

classmethod to_camel() → type[Self]¶

HTTP 구성요소(Header, Query, Form, Path)의 키 값이 camel case에 따르도록 하도록 정의합니다.

예제

>>> @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

경고

Body component와 Path component는 to_camel 메소드를 이용하는 것을 허용하지 않습니다.

classmethod to_pascal() → type[Self]¶

HTTP 구성요소(Header, Query, Form, Path)의 키 값이 pascal case에 따르도록 하도록 정의합니다.

예제

>>> @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

경고

Body component와 Path component는 to_pascal 메소드를 이용하는 것을 허용하지 않습니다.

class BodyJson¶

기반 클래스: Component

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

예제

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

class Body¶

기반 클래스: UnsupportedCustomNameComponent

메소드의 매게변수가 HTTP 요청의 Body 값으로 이용되도록 정의할 수 있는 클래스입니다.

예제

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

class Form¶

기반 클래스: Component

메소드의 매게변수가 HTTP 요청의 Body Form 데이터 값으로 이용되도록 정의할 수 있는 클래스입니다.

예제

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

class Header¶

기반 클래스: Component

메소드의 매게변수가 HTTP 요청의 Header 값으로 이용되도록 정의할 수 있는 클래스입니다.

예제

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

class Path¶

기반 클래스: UnsupportedCustomNameComponent

메소드의 매게변수의 값이 URL 주소의 자리표시자 일부분을 대신해서 채울 수 있도록 정의하는 클래스입니다.

예제

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

class Query¶

기반 클래스: Component

메소드의 매게변수가 HTTP 요청의 Query 값으로 이용되도록 정의할 수 있는 클래스입니다.

예제

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

Request Core¶

class RequestCore¶

함수에서 HTTP 요청을 할 수 있도록 구현하는 객체입니다.

name¶

request의 이름입니다.

Type:: str

func¶

request가 호출되어 결과를 받았을 때, 실행할 코루틴 함수입니다.

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

method¶

HTTP 메소드입니다. (예: GET, POST)

Type:: str

path¶

Path 주소입니다. Path는 Sessoin.base_url 와 결합되어 HTTP 호출을 합니다.

Type:: str

directly_response¶

함수의 본문을 실행하지 않고, 반환할 수 있도록 설정합니다. 특별한 설정이 없다면 aiohttp.ClientResponse 를 반환합니다.

Type:: bool

params¶

HTTP 호출에 사용되는 Query(parameter) 입니다.

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

headers¶

HTTP 호출에 사용되는 header 입니다.

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

body¶

HTTP 호출에 사용되는 body 입니다.

Type:: Optional[Any | aiohttp.FormData]

header_parameter¶

HTTP 호출에서 header로 사용할 수 있는 함수의 매게변수입니다.

Type:: dict[str, inspect.Parameter]

query_parameter¶

HTTP 호출에서 query(parameter)로 사용할 수 있는 함수의 매게변수입니다.

Type:: dict[str, inspect.Parameter]

body_json_parameter¶

HTTP 호출에서 json 형태의 body로 사용할 수 있는 함수의 매게변수입니다.

Type:: dict[str, inspect.Parameter]

body_form_parameter¶

HTTP 호출에서 aiohttp.FormData 형태의 body로 사용할 수 있는 함수의 매게변수입니다.

Type:: dict[str, inspect.Parameter]

path_parameter¶

HTTP 호출에서 path로 사용할 수 있는 함수의 매게변수입니다.

Type:: dict[str, inspect.Parameter]

body_parameter¶

HTTP 호출에서 body로 사용할 수 있는 함수의 매게변수입니다.

Type:: Optional[inspect.Parameter]

body_parameter_type¶

body parameter의 유형입니다. 만약 body_parameter 값이 aiohttp.FormData 또는 이외에 유형이라면 body_parameter_type 값은 ‘data’가 됩니다.이외에 body_parameter 값이 Collection 이 될 수 있다면, body_parameter_type 값은 ‘json’이 됩니다.

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

response_parameter¶

HTTP 호출에서 응답받은 결과를 담아낼 함수의 매개변수입니다.

Type:: list[str]

request_kwargs¶

aiohttp.ClientSession.request() 에서 사용되는 HTTP 호출에 사용되는 Keyword Arguments를 정의합니다.

Type:: dict[str, Any]

@before_hook¶

HTTP 호출이 이루어지기 전에 실행되는 함수를 정의하는 데코레이터 메소드입니다.

주로 HTTP 호출 전에 필수적으로 입력되는 구성요소를 입력하는 함수로 구성합니다.

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¶

HTTP 호출이 이루어진 후에 실행되는 함수를 정의하는 데코레이터 메소드입니다.

주로 응답받은 결과가 올바른지 검증하거나, HTTP 호출에서 받은 원본 데이터를 올바르게 정리합니다.

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¶

이 RequestCore 클래스를 복사합니다.

반환:: 새로운 request 정보가 담긴 인스턴스를 반환합니다.
반환 형식:: RequestCore

get_request_kwargs() → dict[str, Any]¶: aiohttp.ClientSession.request() 에서 사용되는 HTTP 호출에 사용되는 Keyword Arguments를 반환합니다.

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

최종 body 유형을 반환합니다.

반환 형식:: :class:`Literal`[‘json’, ‘data’]

property is_body: bool¶

HTTP request에서 body 요소를 가지고 있는지 반환합니다.

반환 형식:: bool

property is_formal_form: bool¶

HTTP request에서 body가 형식적인 form으로 구성되어 있는지 확인하고 반환합니다.

반환 형식:: bool

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

함수가 HTTP request 과정을 거칠 수 있도록 만드는 데코레이터 메소드입니다.데코레이터로 정의된 메소드가 호출된다면, HTTP 호출도 동시에 이루어집니다.

매개변수:

name (Optional[str]) – Request의 이름입니다.
method (str) – HTTP 메소드입니다. (예: GET, POST)
path (str) – Path 주소입니다. Path는 Sessoin.base_url 와 결합되어 HTTP 호출을 합니다.
params (Optional[dict[str, Any]]) – HTTP 호출에 사용되는 Query(parameter) 입니다.
headers (Optional[dict[str, Any]]) – HTTP 호출에 사용되는 header 입니다.
body (Optional[Any | aiohttp.FormData]) – HTTP 호출에 사용되는 body 입니다.
directly_response (bool) – 함수의 본문을 실행하지 않고, 반환할 수 있도록 설정합니다. 특별한 설정이 없다면 aiohttp.ClientResponse 를 반환합니다.
header_parameter (list[str]) – HTTP 호출에서 header로 사용될 메소드의 매게변수입니다.
query_parameter (list[str]) – HTTP 호출에서 query(parameter)로 사용될 메소드의 매게변수입니다.
form_parameter (list[str]) – HTTP 호출에서 aiohttp.FormData 형태의 body로 사용할 수 있는 함수의 매게변수입니다.
body_json_parameter (list[str]) – HTTP 호출에서 Json 형태의 body로 사용할 수 있는 함수의 매게변수입니다.
path_parameter (list[str]) – HTTP 호출에서 path로 사용할 수 있는 함수의 매게변수입니다.
body_parameter (str) – HTTP 호출에서 body로 사용할 수 있는 함수의 매게변수입니다.
response_parameter (list[str]) – HTTP 호출에서 응답받은 결과를 담아낼 함수의 매개변수입니다.
**request_kwargs

경고

Form 매개변수와 Body 매개변수 중에서는 하나만 정의할 수 있습니다.

@get(path: str)¶

@post(path: str)¶

@options(path: str)¶

@put(path: str)¶

@delete(path: str)¶: ahttp_client.request 와 동일한 기능을 합니다.

Session¶

class Session¶

request decoration으로 정의된 함수를 관리하고, 세션을 관리하는 클래스입니다.

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

하나의 request만 사용하는 경우, 단독 세션을 정의할 수 있습니다.

매개변수:

base_url (str) – API의 기본 주소입니다.
loop (asynico.AbstractEventLoop) – HTTP request 처리 과정에서 사용되는 Event Loop입니다.
session_kwargs – aiohttp.ClientSession 에서 사용되는 keyword argument입니다.

Example

메소드를 데코레이팅하는 방식으로 단독 세션을 정의할 수 있습니다.

@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¶

HTTP 호출 후에 실행되는 함수입니다. RequestCore.after_hook() 와 비슷한 기능을 합니다.

만약 RequestCore.after_hook() 가 정의되어 있다면, RequestCore.after_hook() 이전에 호출됩니다.

매개변수:: response (aiohttp.ClientResponse) – HTTP 요청에서 얻은 결과입니다.
반환:: 정리된 HTTP 결과를 반환하면 됩니다. 만약 RequestCore.after_hook 사용하고 있다면,:meth:RequestCore.after_hook 에도 같은 응답 결과를 따를 것입니다.
반환 형식:: aiohttp.ClientResponse | T

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

HTTP 호출 전에 실행되는 함수입니다. RequestCore.before_hook() 와 비슷한 기능을 합니다.

만약 RequestCore.before_hook() 가 정의되어 있다면, RequestCore.before_hook() 이전에 호출됩니다.

매개변수:

request (RequestCore) – HTTP 요청 정보를 담고 있는 인스턴스 입니다.
path (str) – HTTP 요청에 사용되는 최종 URL 입니다.

반환:

매개변수로 입력받은 유형을 그대로 반환해주면 됩니다.

반환 형식:

Tuple[RequestCore, str]