[PEP] 함수 Docstring과 Type Hint 작성 방법

파이썬에서 유명한 라이브러리 코드를 보게 되면 무언가 많이 작성되어 있는 것을 볼 수가 있다. 

def generate_identified_filename(filename: Path, identifier: str) -> Path:
    """
    Append a string-identifier at the end (before the extension, if any) to the provided filepath

    Args:
        filename: pathlib.Path The actual path object we would like to add an identifier suffix
        identifier: The suffix to add

    Returns: String with concatenated identifier at the end of the filename
    """
    return filename.parent.joinpath(filename.stem + identifier).with_suffix(filename.suffix)

* transformers 의 코드 중 하나

 

이런 식으로 함수 아래에  """ 따옴표를 이용하여 무언가가 많이 적혀 있는데 이것을 Docstring이라고 하는데 이것에 대해 알아보려고 한다. 

Docstring이란?

---

쉽게 말해서 소스 코드에 포함된 문서라고 말할 수 있다. docstring은 문자열이며, fucntion logic을 문서화하기 위해 작성한다. Docstring은 주석과는 다르게 Python의 첫 번째 실행 가능한 문장으로 작성되며, Python 인터프리터에 의해 처리되어 해당 객체의 __doc__ 특수 속성에 저장됩니다. 이를 통해 프로그램 실행 중에도 해당 정보에 접근할 수 있다.

 

Docstring 작성 방법

---

1. 함수 정의와 타입 힌트 적용: 함수 정의에서 매개변수와 반환 값에 타입 힌트를 적용
2. 문자열 시작: 함수 정의 바로 아래에 삼중 따옴표 (""")를 사용해 docstring을 시작
3. 요약 설명: 함수가 수행하는 작업에 대한 간결하고 명확한 한 줄 요약을 포함
4. 상세 설명 (선택 사항): 요약 설명 다음에 빈 줄을 두고 필요한 경우 함수의 동작을 보다 상세히 설명
5. 매개변수 설명: Parameters 섹션에서 각 매개변수의 이름, 타입, 그리고 설명을 제공
6. 반환 값 설명: Returns 섹션에서 함수가 반환하는 값의 타입과 그 의미를 설명
7. 예외 설명: Raises 섹션에서 함수 실행 중 발생할 수 있는 예외와 그 상황을 나열하고 설명
8. 예시 설명: Examples 섹션에서 함수의 실행 예시와 결과 값에 대해 나열하고 설명

 

타입 힌트 작성

---

타입 힌트는 typing 모듈과 pydantic 모듈을 사용합니다. typing은 3.5 버전부터 일반적으로 사용하고 3.10 버전부터는 pydantic 모듈을 사용한다. 특히 pydantic은 FastAPI와 같은 API에서 많이 사용하고 그 외에는 거의 typing 모듈을 사용한다고 보면 된다. 

 

예시

---

typing 모듈을 사용하지 않았을 때

def add(a: int, b: int) -> int:
    """
    두 정수의 합을 계산하여 반환합니다.

    Parameters:
    a (int): 첫 번째 정수. 정수가 아닐 경우 TypeError 발생.
    b (int): 두 번째 정수. 정수가 아닐 경우 TypeError 발생.

    Returns:
    int: 두 수의 합

    Raises:
    TypeError: `a` 또는 `b`가 정수가 아닐 때 발생

    Examples:
    >>> add(10, 20)
    30

    >>> add("ten", 20)
    TypeError: Both arguments must be integers
    """
    if not isinstance(a, int) or not isinstance(b, int):
        raise TypeError("Both arguments must be integers")
    return a + b

 

typing 모듈을 사용했을 때

from typing import Union

def add_numbers(x: Union[int, float], y: Union[int, float]) -> float:
    """
    두 숫자의 합을 계산하여 반환합니다.

    Parameters:
    x (Union[int, float]): 첫 번째 숫자. 정수 또는 부동소수점 수가 될 수 있습니다.
    y (Union[int, float]): 두 번째 숫자. 정수 또는 부동소수점 수가 될 수 있습니다.

    Returns:
    float: `x`와 `y`의 합.

    Examples:
    >>> add_numbers(1, 2)
    3
    >>> add_numbers(1.5, 2.3)
    3.8

    Notes:
    이 함수는 `int` 또는 `float` 타입의 두 입력값을 받아 그 합을 `float`로 반환합니다.
    """
    return x + y