Python pydoc 모듈 활용법: 문서 자동 생성부터 docstring 작성까지

소개

pydoc은 Python 모듈의 문서를 자동으로 생성해 주는 표준 라이브러리 모듈입니다. 이 모듈을 활용하면 콘솔에 텍스트 형태로 문서를 출력하거나, 웹 브라우저에서 바로 확인할 수 있으며, 심지어 HTML 파일로 저장하는 것도 가능합니다.

이 글에서는 다양한 상황에서 pydoc으로 문서를 조회하는 방법과 함께, 여러분의 Python 스크립트에 직접 문서를 만들 수 있게 해주는 docstring(독스트링) 작성법까지 알아보겠습니다.

pydoc 모듈은 Python에 기본적으로 포함되어 있기 때문에 별도로 다운로드하거나 설치할 필요가 없습니다. 다만 사용하기 전에 먼저 임포트(import)해야 합니다.

import pydoc

pydoc의 help 함수를 이용하면 대화형(interactive) 도움말 셸에 접속할 수 있습니다.

먼저 터미널을 열고 Python 인터프리터(대화형 셸)에 진입합니다. 그다음 pydoc을 임포트한 뒤 pydoc.help() 명령어를 입력하면 대화형 헬프 셸이 실행됩니다.

>>> import pydoc
>>> pydoc.help()

대화형 셸이 실행되면 모듈명, 데이터 타입, 함수, 클래스 등 궁금한 항목의 이름을 직접 입력하여 해당 문서를 즉시 확인할 수 있습니다.

pydoc을 사용하면 문서를 웹 브라우저에서 손쉽게 열람할 수도 있습니다.

이번에는 Python 셸 안에서 명령을 실행하는 것이 아니라, 터미널에서 명령줄 인자를 넘겨 직접 실행합니다.

터미널을 열고 아래 명령어를 입력하세요.

python -m pydoc -b

이 명령을 실행하면 로컬 시스템에 설치된 모든 Python 모듈, 함수, 객체에 대한 문서가 브라우저에서 열립니다. 검색 기능을 통해 특정 키워드의 문서만 골라서 찾아볼 수도 있습니다.

C:\Users\vijay>python -m pydoc -b
Server ready at https://localhost:50621/
Server commands: [b]rowser, [q]uit
server> q
Server stopped

명령이 실행되면 로컬 서버가 구동되고, 지정된 포트(위 예제에서는 50621)로 브라우저 접속이 가능해집니다. 종료하려면 프롬프트에 q를 입력하면 됩니다.

pydoc으로 문서를 조회하는 것뿐만 아니라, 직접 문서를 작성할 수도 있습니다. 그 핵심이 바로 docstring입니다. docstring은 함수, 클래스, 모듈 정의 바로 아래에 삼중 따옴표(''')로 감싸서 작성하는 설명 문자열입니다.

작성된 docstring은 객체의 __doc__ 속성에 저장되며, pydoc의 help() 함수를 통해 자동으로 출력됩니다.

def documentation():
    '''Documentation using docstrings'''

print(documentation.__doc__)
help(documentation)

Documentation using docstrings
Help on function documentation in module __main__:

documentation()
    Documentation using docstrings

실행 결과를 보면 __doc__ 속성과 help() 함수 모두 docstring 내용을 정상적으로 출력하는 것을 확인할 수 있습니다. 이처럼 docstring만 잘 작성해 두면 별도의 문서화 작업 없이도 pydoc이 깔끔한 문서를 자동으로 만들어 줍니다.

이제 pydoc을 활용해 Python의 다양한 키워드, 함수, 모듈, 메서드에 대한 문서를 오프라인 환경에서도 조회하고 읽는 방법을 익혔습니다. 나아가 docstring을 작성하여 자신만의 문서를 만드는 방법도 배웠습니다.

규모가 큰 프로젝트를 진행할 때는 좋은 문서를 유지하는 것이 매우 중요합니다. 어떤 코드가 어디에서 어떤 역할을 하는지 명확히 기록해 두면 나중에 혼란을 겪지 않을 수 있고, 예상치 못한 런타임 오류를 사전에 방지하는 데에도 큰 도움이 됩니다.