docstring in python

About_work·2022년 12월 31일

python clean code

목록 보기

3/11

참고 문헌

파이썬 코딩의 기술 책

요약

모듈
- 모듈의 내용과, 사용자가 알아야 하는 중요한 클래스나 함수를 docstring에 소개하라.
클래스
- class 문 뒤에 나오는 docstring에 문서화하라.
- 동작, 중요한 attribute, 하위 클래스의 동작 등을 기술
함수와 메서드
- 모든 인자, 반환 값, 발생하는 예외, 기타 세부적인 동작

기초

파이썬 docstring을 작성할 때 따라야 할 지침은 PEP 257 에서 볼 수 있다.
- https://www.python.org/dev/peps/pep-0257/
파이썬에서는 프로그램을 실행 하는 중에, 프로그램 소스 코드의 문서에 직접 접근할 수 있다.
파이썬 프로그램에서 docstring을 가져오려면 __doc__ magic attribute를 사용하면 된다.

def abc():
""" 독스트링 이란다!"""

print(repr(abc.__doc__)))
>>> '독스트링 이란다!'

또한 명령줄에서 내장 pydoc 모듈을 사용해 local web server을 실행할 수 있다.
이 서버는 작성한 모듈을 비롯해, interpreter에서 찾을 수 있는 모든 파이썬 문서를 제공한다.

$ python3 -m pydoc -p 1234

Server ready at http://localhost:1234/
Server commands: [b]rowser, [q]uit
server> b

파이썬이 docstring과 __doc__ attribute 지원을 하는 것의 장점 2가지
- 문서에 항상 접근할 수 있으므로 대화식 개발이 쉬워진다.
  - help 내장 함수를 통해, 내부 문서를 살펴볼 수 있다.
  - 알고리즘을 개발하거나 / API 를 테스트하거나 / 작은 코드를 작성할 때, 파이썬 대화형 interpreter(ex. python 셸)나 IPython 노트북(https://ipython.org) 같은 도구를 즐겁게 사용 가능하다.
- 코드 문서화를 정의하는 표준이 있으므로, 문서를 HTML 등 더 보기 좋은 형태로 바꿔주는 도구를 쉽게 만들 수 있다.
  - 문서 생성 도구: Sphinx(https://www.sphinx-doc.org)
  - 오픈 소스 파이썬 프로젝트들의 보기 좋은 문서들을 무료로 호스팅해주는: readthedocs(https://readthedocs.org)

사용법

""" 내용 """ 형태로 작성하라.
모듈/클래스/함수 문서화는 거의 비슷한 패턴을 보인다.
type annotation 이 제공되었다면, 중복으로 docstring에 정보를 표시하지 말라.

모듈 문서화

각 모듈에는 소스 코드 첫 줄에 위치한 docstring이 있어야 한다.
첫 줄
- 모듈의 목적을 설명하는 한 문장

다음 단락들

모듈의 동작에 대해 알려줘야 하는 세부 사항
- 중요한 클래스와 함수를 강조해도 좋다.
- argument (config)를 소개해도 좋다.
- 모듈이 명령줄 도구라면, 도구를 실행해 사용하는 방법을 모듈 독스트링에 제공하면 좋다.

""" 단어의 언어 패턴을 찾을 때 쓸 수 있는 라이브러리

여러 단어가 서로 어떤 연관 관계에 있는지 검사하는 것이 어려울 떄가 있다!
이 모듈은 단어가 가지는 특별한 특성을 쉽게 결정할 수 있게 해준다.

사용 가능 함수:
_ palindrome: 주어진 단어가 회문인지 결정한다.
_ check_anagram: 주어진 단어가 어구전철(똑같은 글자들로 순서가 바뀐 경우)인지 결정한다. 
"""

클래스 문서화

첫 줄
- 클래스의 목적을 설명하는 한 문장
다음 단락들
- 중요한 공개 attribute와 method를 강조하면 좋다.
- 이 클래스를 상속하는 하위 클래스가, 보호 attribute나 method와 상호작용하는 방법을 인내해야 한다.

class Player:
	"""게임 플레이어를 표현하다.
    
    하위 클래스는 'tick' 메서드를 오버라이드해서, 플레이어의 파워 레벨 등에 맞는 움직임 에니메이션을 제공할 수 있다.
    
    공개 attribute
    - power: 사용하지 않은 파워업들 (0과 1사이 float).
    - coins: 현재 레벨에서 발견한 코인 개수 (integer).
	"""

함수 문서화하기

모든 공개 함수와 method에는 docstring을 포함시켜야 한다.
첫 줄
- 함수가 하는 일을 설명한다.
다음 단락들
- 함수 argument나 함수의 동작에 대해 구체적으로 설명한다.
- 함수의 인터페이스에 속해 있으며, 함수를 호출하는 쪽에서 꼭 처리해야 하는 예외도 설명해야 한다.
함수 독스트링을 작성할 때 지켜야 할 규칙들
- 함수에 argument가 없고 return만 있다면, 설명은 한 줄로도 충분하다.
- 함수가 아무 값도 반환하지 않는다면, 반환 값에 대한 설명을 제외하라.
- 함수 인터페이스에 예외 발생이 포함된다면, 발생하는 예외와 예외가 발생하는 상황에 대한 설명을 반드시 포함시켜야 한다.
- 함수가 가변 인자나 키워드 인자를 받는다면, 문서화한 인자 목록에 *args나 **kwargs 를 사용하고 각각의 목적을 설명하라.
- 함수에 디폴트 값이 있는 argument가 있다면, 디폴트 값을 언급해야 한다.
- 함수가 generator 이라면, 독스트링에는 이 generator을 iteration할 때 어떤 값이 발생하는지 기술해야 한다.
- 함수가 비동기 코루틴이라면, 독스트링에 언제 이 코루틴의 비동기 실행이 중단되는지 설명해야 한다.

def find_anagrams(word: str, dictionary: Container[str]) -> List[str]:
	"""주어진 단어의 모든 어구전철을 찾는다.
    
    이 함수는 '딕셔너리' 컨테이너의 원소 검사만큼 빠른 속도로 실행된다.
    
    Args:
    	word: 대상 단어
        dictionary: 모든 단어가 들어 있는 collections.abc.Container 컬렉션.
    
    Returns:
    	찾은 어구전철들로 이뤄진 리스트. 아무것도 찾지 못한 경우 Empty.
    """
    pass

style 3가지 소개 및 비교

google style

def google_docstrings(num1, num2
                      ) -> int:
    """Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    Args:
        num1 (int) : First number to add.
        num2 (int) : Second number to add.

    Returns:
        The sum of ``num1`` and ``num2``.

    Raises:
        AnyError: If anything bad happens.
    """
    return num1 + num2

Sphinx와 호환되고, autodoc이 인지하게 만드려면, conf.py 파일에 sphinx.ext.napoleon 확장자를 추가해라.
VS Code에서 해당 style을 이용하고 싶다면, https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring 을 써라.

NumPy Docstring

def numpy_docstrings(num1, num2) -> int:
    """
    Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    Parameters
    ----------
    num1 : int
        First number to add.
    num2 : int
        Second number to add.

    Returns
    -------
    int
        The sum of ``num1`` and ``num2``.

    Raises
    ======
     MyException
        if anything bad happens

    See Also
    --------
    subtract : Subtract one integer from another.

    Examples
    --------
    >>> add(2, 2)
    4
    >>> add(25, 0)
    25
    >>> add(10, -10)
    0
    """
    return num1 + num2

google vs numpy 독스트링
- 두 문서 문자열의 출력은 유사하며,
- 두 스타일의 주요 차이점은 구글이 섹션을 구분하기 위해 들여쓰기를 사용하는 반면, NumPy는 밑줄을 사용한다는 것이다.
- NumPy 스타일은 더 많은 수직 공간을 필요로 하는 반면, 구글 스타일은 더 많은 수평 공간을 사용하는 경향이 있다.
- 구글 스타일은 짧고 간단한 문서 문자열을 읽는 것이 더 쉬운 경향이 있는 반면,
- NumPy 스타일은 길고 심층적인 문서 문자열을 읽는 것이 더 쉬운 경향이 있다.

Sphinx docstring

def sphinx_docstrings(num1, num2) -> int:
    """Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    :param int num1: First number to add.
    :param int num2: Second number to add.
    :returns:  The sum of ``num1`` and ``num2``.
    :rtype: int
    :raises AnyError: If anything bad happens.
    """
    return num1 + num2