API Reference¶

Component¶

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

class Component¶

요청 매개변수 구성요소(Component)의 기본 클래스입니다.

구성요소는 애너테이션(annotation)을 통해 함수의 매개변수를 header, query string, path placeholder, 요청 본문(request body) 중 하나로 대응시키는 데 사용됩니다.

component_name¶

실제 전송되는 구성요소 키에 적용할 선택적인 변환 함수입니다.

Type:: Callable[[str], str]

classmethod custom_name(name: str) → Self¶

전송되는 이름이 고정된 구성요소 인스턴스를 반환합니다.

매개변수:: name (str) – 파이썬 매개변수 이름 대신 요청에 사용할 이름입니다.
예외 발생:: NotImplementedError – 이름 변경을 지원하지 않는 구성요소(Path, Body 등)인 경우 발생합니다.

classmethod to_camel() → Self¶

키를 camel case로 변환하는 구성요소 인스턴스를 반환합니다.

예외 발생:: NotImplementedError – 이름 변경을 지원하지 않는 구성요소인 경우 발생합니다.

classmethod to_pascal() → Self¶

키를 Pascal case로 변환하는 구성요소 인스턴스를 반환합니다.

예외 발생:: NotImplementedError – 이름 변경을 지원하지 않는 구성요소인 경우 발생합니다.

class Body¶

기반 클래스: _BodyFileComponent, _UnsupportedCustomNameComponent

매개변수를 요청 본문 전체로 지정합니다.

dict, list, tuple 값은 JSON으로 인코딩되며, 그 외의 값(파일과 유사한 값 포함)은 원본(raw) 본문 데이터로 전송됩니다. Body 매개변수는 BodyJson 또는 BodyForm 매개변수와 함께 사용할 수 없습니다. metadata() 는 원본 본문 인코딩을 바꾸지 않고 파일명과 콘텐츠 타입 메타데이터를 추가합니다.

class BodyJson¶

기반 클래스: Component

매개변수를 JSON 요청 본문의 필드로 지정합니다.

값을 다른 이름 또는 중첩된 JSON 키 아래에 두려면 custom_key() 를 사용하세요.

classmethod custom_key(key: str) → Self¶

커스텀 키를 가진 JSON 본문 구성요소를 반환합니다.

점(.)으로 구분된 키는 중첩된 JSON 객체를 생성합니다.

매개변수:: key (str) – JSON 요청 본문에서 사용할 키입니다.

property depth: int¶: 커스텀 JSON 키의 중첩 단계 수를 반환합니다.

property keys: list[str]¶: 커스텀 JSON 키를 중첩된 키 이름들로 나누어 반환합니다.

class BodyForm¶

기반 클래스: _BodyFileComponent

매개변수를 form 요청 본문의 필드로 지정합니다.

파일과 유사한 값이거나 metadata() 설정에 파일명이나 콘텐츠 타입이 지정된 필드는 multipart/form-data 를 사용하며, 그 외의 form 필드는 기본적으로 URL 인코딩됩니다.

class Header¶

기반 클래스: Component

매개변수를 HTTP 요청 헤더로 지정합니다.

default_header() 는 데코레이팅된 요청에 고정된 헤더를 추가합니다.

static default_header(key: str, value: Any) → Callable[[_CallableT], _CallableT]¶

데코레이팅된 요청에 고정된 헤더를 추가합니다.

매개변수:

key (str) – 헤더 이름입니다.
value (Any) – 헤더 값입니다.

class Path¶

기반 클래스: _UnsupportedCustomNameComponent

매개변수를 요청 경로의 플레이스홀더로 지정합니다.

매개변수 이름은 path 안의 str.format 플레이스홀더와 일치해야 합니다.

class Query¶

기반 클래스: Component

매개변수를 HTTP 쿼리 스트링 값으로 지정합니다.

default_query() 는 데코레이팅된 요청에 고정된 쿼리 매개변수를 추가합니다.

static default_query(key: str, value: Any) → Callable[[_CallableT], _CallableT]¶

데코레이팅된 요청에 고정된 쿼리 매개변수를 추가합니다.

매개변수:

key (str) – 쿼리 매개변수 이름입니다.
value (Any) – 쿼리 매개변수 값입니다.

Request Core¶

class RequestCore¶

데코레이팅된 HTTP 요청의 기본 디스크립터입니다.

request core는 세션의 속성으로 접근되는 순간 BaseSession 인스턴스에 바인딩됩니다. 바인딩된 요청은 고정 값과 애너테이션 매개변수로 백엔드에 맞는 요청을 만들고, Response 매개변수를 채운 다음 데코레이팅된 함수를 실행합니다.

name¶

request의 이름입니다.

Type:: str

func¶

응답을 받은 후에 실행되는 동기 또는 비동기 함수입니다.

Type:: Callable[…, Any]

method¶

HTTP 메소드입니다.

Type:: str | Method

path¶

백엔드가 자체적으로 base URL을 관리하지 않는 한, 세션의 base URL을 기준으로 한 상대 경로입니다.

Type:: str

directly_response¶

데코레이팅된 함수를 실행하지 않고 응답 파이프라인의 결과를 반환합니다.

Type:: DirectResponseType | bool

raise_on¶

HTTP 응답 상태가 200 이 아니면 HTTPException 을 발생시킵니다. 4xx와 5xx 상태는 가능한 경우 해당하는 구체적인 예외 클래스를 사용합니다.

Type:: bool

params¶

고정된 쿼리 매개변수입니다.

Type:: dict[str, Any]

headers¶

고정된 요청 헤더입니다.

Type:: dict[str, Any]

body¶

고정된 요청 본문입니다. 인코딩 방식은 body_type 에 의해 결정됩니다.

Type:: Optional[Any]

header_parameter¶

요청 헤더로 사용되는 함수의 매개변수입니다.

Type:: dict[str, inspect.Parameter]

query_parameter¶

쿼리 매개변수로 사용되는 함수의 매개변수입니다.

Type:: dict[str, inspect.Parameter]

body_json_parameter¶

JSON 본문으로 모이는 함수의 매개변수입니다.

Type:: dict[str, inspect.Parameter]

body_form_parameter¶

form 본문으로 모이는 함수의 매개변수입니다.

Type:: dict[str, inspect.Parameter]

path_parameter¶

경로(path)에 대입되는 함수의 매개변수입니다.

Type:: dict[str, inspect.Parameter]

body_parameter¶

요청 본문 전체로 사용되는 함수 매개변수의 메타데이터입니다.

Type:: Optional[BodyEntry]

body_parameter_type¶

매개변수 애너테이션이나 form 설정으로부터 추론된 명시적인 본문 인코딩 방식입니다.

Type:: Optional[BodyType]

response_parameter¶

HTTP 응답을 전달받는 함수 매개변수의 이름입니다.

Type:: list[str]

request_kwargs¶

백엔드의 요청 메소드로 그대로 전달되는 keyword arguments입니다.

Type:: dict[str, Any]

@before_hook¶

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

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

Example

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

    @request("GET", "/users/{user}/repos")
    async def list_repositories(
        self, response: Response, user: Annotated[str, Path]
    ) -> list[dict[str, Any]]:
        return response.json()

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

@after_hook¶

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

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

Example

class GithubService(AsyncSession):
    def __init__(self):
        super().__init__("https://api.github.com", aiohttp.ClientSession)

    @request("GET", "/users/{user}/repos")
    async def list_repositories(
        self, response: Response, user: Annotated[str, Path]
    ) -> list[dict[str, Any]]:
        return response.json()

    @list_repositories.after_hook
    async def validation_status(self, response: Response):
        if response.status != 200:
            raise Exception("ERROR!")
        return response

copy() → Self¶

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

반환:: 고정 헤더와 쿼리 매개변수가 복사된, 독립적인 request 인스턴스입니다.
반환 형식:: RequestCore

validation(parameter_name: str, index: int | None = None) → ValidationDecorator¶

요청 함수 매개변수에 대한 검증기(validator)를 등록합니다.

검증기는 요청을 만들기 전에 (session, value) 형태로 호출되며, 반환값이 요청 구성요소와 데코레이팅된 함수에 쓰이는 인자를 대체합니다.

매개변수:

index
parameter_name (str) – 데코레이팅된 함수 시그니처에 있는 매개변수의 이름입니다.

예외 발생:

ValueError – 매개변수 이름이 비어 있거나 요청 시그니처에 존재하지 않는 경우 발생합니다.

property body_type: BodyType | None¶

이 요청에 선택된 본문 인코딩 방식을 반환합니다.

반환 형식:: Optional[BodyType]

property is_body: bool¶

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

반환 형식:: bool

property is_formal_form: bool¶

이 요청이 form 매개변수를 가지고 있는지 반환합니다.

반환 형식:: bool

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

세션 메소드를 HTTP 요청으로 데코레이팅합니다.

데코레이팅된 메소드는 Session 또는 AsyncSession 에서 접근하는 순간 그 세션에 바인딩됩니다. 호출될 때마다 고정 값과 구성요소 매개변수로 요청을 만들고, 응답 매개변수 자리에 맞는 Response 를 채워 넣습니다.

매개변수:

name (Optional[str]) – 요청의 이름입니다. 기본값은 데코레이팅된 함수의 이름입니다.
method (str | Method) – HTTP 메소드입니다.
path (str) – 세션의 base URL을 기준으로 한 상대 경로입니다.
params (Optional[dict[str, Any]]) – 고정된 쿼리 매개변수입니다.
headers (Optional[dict[str, Any]]) – 고정된 요청 헤더입니다.
body (Optional[Any]) – 고정된 요청 본문입니다.
directly_response (DirectResponseType | bool) – 데코레이팅된 함수를 실행하지 않고 훅을 거친 응답을 반환합니다.
raise_on (bool) – HTTP 응답 상태가 200 이 아니면 HTTPException 을 발생시킵니다. 4xx와 5xx 상태는 가능한 경우 해당하는 구체적인 예외 클래스를 사용합니다.
header_parameter (list[str]) – 헤더로 사용할 매개변수 이름의 레거시 목록입니다.
query_parameter (list[str]) – 쿼리 매개변수로 사용할 매개변수 이름의 레거시 목록입니다.
form_parameter (list[str]) – form 본문에 사용할 매개변수 이름의 레거시 목록입니다.
form_encoding (Optional[BodyFormEncoding]) – form 매개변수에 사용할 인코딩 방식입니다. AUTO 는 파일 필드가 있으면 multipart를, 그렇지 않으면 URL 인코딩을 선택합니다.
body_json_parameter (list[str]) – JSON 본문에 사용할 매개변수 이름의 레거시 목록입니다.
path_parameter (list[str]) – path 에 대입할 매개변수 이름의 레거시 목록입니다.
body_parameter (str) – 본문 전체로 사용할 매개변수 이름의 레거시 값입니다.
response_parameter (list[str]) – 응답을 전달받는 함수 매개변수 이름의 레거시 목록입니다.
**request_kwargs

경고

본문 전체를 나타내는 Body 매개변수는 BodyJson 또는 BodyForm 매개변수와 함께 사용할 수 없습니다.

@get(path: str)¶

GET HTTP 메소드를 위한 요청 데코레이터를 생성합니다.