Annotation

코드 사용자에게 함수 인자로 어떤 값이 와야 하는지 알려주는 역할. 어노테이션을 사용하여 변수의 예상 타입을 표시할 수 있다.

class Point:
    def __init__(self, lat, long):
        self.lat = lat
        self.long = long
 
def locate(latitude: float, longitude: float) -> Point:
    """맵에서 좌표에 해당하는 객체를 검색"""

어노테이션을 사용함으로써 locate 함수의 파라미터와 반환값을 알 수 있다. 파이썬은 타입을 검사하거나 어노테이션을 강제하지는 않는다.

파이썬 3.6부터는 함수 파라미터와 리턴 타입뿐만 아니라 변수에 직접 주석을 달 수 있다.

class Point:
    lat: float
    long: float

어노테이션은 Docstring을 대체하는가?

docstring의 대부분을 어노테이션으로 대체할 수 있지만. docstring은 여전히 필요하다. docstring과 어노테이션은 서로 보완적인 개념이기 때문이다.

어노테이션으로 대체 가능한 정보 또한 더 나은 문서화를 위해 docstring에 남겨두어야 한다. 특히 동적 데이터 타입과 중첩 데이터 타입의 경우 예상 데이터의 예제를 제공하는 것이 좋다.

def data_from_response(response: dict) -> dict:
    if response['status'] != 200:
        raise ValueError
    return {'data': response['payload']}

위 함수는 어노테이션을 통해 파라미터와 return 값의 type을 표시한다. 하지만 response 객체의 올바른 인스턴스 형태, 결과 인스턴스의 형태 등의 상세한 내용은 알 수 없다. 위 두 가지 문제를 해결하려면 파라미터와 함수 반환 값의 예상 형태를 docstring으로 문서화하는 것이 좋다.

def data_from_response(response: dict) -> dict:
    """response에 문제가 없다면 response의 payload를 반환
    
    - response 사전의 예제::
    {
        "status": 200, # <int>
        "timestamp": "....", # 현재 시간의 ISO 포맷 문자열
        "payload": {...} # 반환하려는 사전 데이터
    }
    
    - 반환 사전 값의 예제::
    {"data": {..}}
    
    - 발생 가능한 예외:
    - HTTP status가 200이 아닌 경우 ValueError 발생
    """
    if response['status'] != 200:
        raise ValueError
    return {"data": response['payload']}