pydoc — 설명서 생성과 온라인 도움말 시스템¶
소스 코드: Lib/pydoc.py
pydoc 모듈은 파이썬 모듈로부터 자동으로 설명서를 생성합니다. 설명서는 콘솔에 텍스트 페이지로 표시하거나, 웹 브라우저로 제공하거나, HTML 파일에 저장할 수 있습니다.
모듈, 클래스, 함수 및 메서드의 경우, 표시된 설명서는 객체와 재귀적으로 그것의 설명 가능한 멤버들의 독스트링(즉, __doc__ 어트리뷰트)에서 파생됩니다. 독스트링이 없으면, pydoc은 소스 파일의 클래스, 함수 또는 메서드의 정의 바로 위나 모듈의 맨 위에 있는 주석 줄 블록에서 설명을 얻으려고 합니다 (inspect.getcomments()를 참조하십시오).
내장 함수 help()는 대화형 인터프리터에서 온라인 도움말 시스템을 호출합니다. 이 시스템은 pydoc을 사용하여 설명서를 콘솔에 텍스트로 생성합니다. 같은 텍스트 설명서는 운영 체제의 명령 프롬프트에서 pydoc을 스크립트로 실행하여 파이썬 인터프리터 외부에서도 볼 수 있습니다. 예를 들어,
pydoc sys
를 셸 프롬프트에서 실행하면, sys 모듈의 설명서를 유닉스 man 명령으로 표시되는 매뉴얼 페이지와 비슷한 스타일로 표시합니다. pydoc의 인자는 함수, 모듈 또는 패키지의 이름이거나 모듈이나 패키지의 모듈 내의 클래스, 메서드 또는 함수에 대한 점으로 구분된 참조일 수 있습니다. pydoc에 대한 인자가 경로처럼 보이고 (즉, 유닉스의 슬래시와 같이 운영 체제의 경로 구분 기호가 포함되어 있으면), 기존 파이썬 소스 파일을 가리키면, 해당 파일에 대한 설명서가 생성됩니다.
참고
객체와 그들의 설명을 찾기 위해, pydoc은 설명할 모듈을 임포트 합니다. 따라서, 모듈 수준의 모든 코드는 이때 실행됩니다. 파일이 임포트될 때가 아니라 스크립트로 호출할 때만 실행되도록 코드를 보호하려면 if __name__ == '__main__':를 사용하십시오.
출력을 콘솔에 인쇄할 때, pydoc은 읽기 쉽도록 출력을 페이지로 나누려고 합니다. PAGER 환경 변수가 설정되면, pydoc은 그 값을 페이지 매김 프로그램으로 사용합니다.
인자 앞에 -w 플래그를 지정하면 콘솔에 텍스트를 표시하는 대신, HTML 설명서가 현재 디렉터리에 파일로 기록됩니다.
인자 앞에 -k 플래그를 지정하면 인자로 주어진 키워드에 대해 사용 가능한 모든 모듈의 개요 행을 검색할 수 있습니다. 역시 유닉스 man 명령과 유사한 방식입니다. 모듈의 개요 행은 설명서 문자열의 첫 행입니다.
pydoc을 사용하여 방문하는 웹 브라우저에 설명서를 제공하는 HTTP 서버를 로컬 시스템에서 시작할 수도 있습니다. pydoc -p 1234는 포트 1234에서 HTTP 서버를 시작해서, 여러분이 선호하는 웹 브라우저에서 http://localhost:1234/의 설명서를 볼 수 있도록 합니다. 포트 번호로 0을 지정하면 사용되지 않는 임의의 포트가 선택됩니다.
pydoc -n <hostname>은 주어진 호스트 이름에서 리스닝하는 서버를 시작합니다. 기본적으로 호스트 이름은 ‘localhost’ 이지만 다른 컴퓨터에서 서버에 도달하도록 하고 싶으면 서버가 응답하는 호스트 이름을 변경해야 할 수 있습니다. 개발 중에 컨테이너 내에서 pydoc을 실행하려는 경우 특히 유용합니다.
pydoc -b는 서버를 시작하고 모듈 색인 페이지로 웹 브라우저를 추가로 엽니다. 제공되는 각 페이지에는 상단에 탐색 바가 있어, 개별 항목에 대한 도움말을 조회(Get)하고, 개요 행에 키워드가 있는 모든 모듈을 검색(Search)하고, 모듈 색인(Module index), 주제(Topics) 및 키워드(Keywords) 페이지로 이동할 수 있습니다.
pydoc이 설명서를 생성할 때, 현재 환경과 경로를 사용하여 모듈을 찾습니다. 따라서, pydoc spam을 호출하면 정확히 파이썬 인터프리터를 시작하고 import spam을 입력할 때 얻는 모듈의 버전을 설명합니다.
코어 모듈에 대한 모듈 설명은 https://docs.python.org/X.Y/library/에 있다고 가정합니다. 여기서 X와 Y는 파이썬 인터프리터의 주 버전 번호와 부 버전 번호입니다. 이는 PYTHONDOCS 환경 변수를 다른 URL로 설정하거나 라이브러리 레퍼런스 매뉴얼 페이지가 있는 로컬 디렉터리로 설정하여 재정의할 수 있습니다.
버전 3.2에서 변경: -b 옵션이 추가되었습니다.
버전 3.3에서 변경: -g 명령 줄 옵션이 제거되었습니다.
버전 3.4에서 변경: 이제 pydoc은 inspect.getfullargspec() 대신 inspect.signature()를 사용하여 콜러블에서 서명 정보를 추출합니다.
버전 3.7에서 변경: -n 옵션이 추가되었습니다.