메뉴 바로가기 검색 및 카테고리 바로가기 본문 바로가기

한빛출판네트워크

IT/모바일

파이썬 문서화 팁과 트릭

한빛미디어

|

2001-06-09

|

by HANBIT

8,750

by 카메론 레어드(Cameron Laird), 역 한빛리포터 1기 이호재 전통적으로 사람들은 계산 언어가 장점을 수학적인 차원에서 보다는 객체 지향적이기 때문에 좋다고 생각한다. 언어는 어떻게 객체지향인가? 그리고 언어의 구조는 독립적인가? 문법은 모호함을 허용하는가? 이런 것들이 추상적인 분석에 적합한 반면, 우리가 일상생활에서 계산 언어를 가지고 일을 하거나 놀 때는, 좀더 인간적인 측면에서 친밀감을 갖게 된다. 파이썬에서 가장 중요하고 훌륭한 부분은 공백을 사용한다는 것도 아니고, 메타프로그래밍 능력도 아니며, 어느 한 가지가 특별히 뛰어난 것도 아니다. 파이썬은 어디에나 잘 어울리기 때문에 사람들이 많이 사용한다. 파이썬은 인간의 필요에 부응하기 위해 엄격함과 유연함을 잘 조화시킨 도구이다. 파이썬은 문서화가 잘 되어 있기도 하다.(레퍼런스나 튜토리얼 등) 어떻게 문서를 볼 것인가 파이썬 프로그래머는 파이썬 라이브러리를 좋아한다. "..를 어떻게 하나요?"의 일반적인 답변은 "...모듈을 사용하세요"이다. 이러한 풍부한 재사용성의 이유 중 하나는 파이썬 모듈이 일반적으로 잘 문서화 되어 있고, 훌륭한 문서화로 인해 새로운 모듈을 만들기가 쉽기 때문이다. 예를 들어서 os 모듈을 살펴보자. os 모듈은 OS의존적인 기능을 이용할 때 OS 의존적인 모듈을 불러오는 것보다 좀더 이식적인 방법을 제공한다. 이는 온라인에 있는 전체 모듈 색인(Global Module Index) 을 보아도 알 수 있다. 색인 페이지에 있는 링크에서는 온라인에서 볼 때와 인쇄할 때 적합하도록 다양한 포맷을 제공한다. 이 사이트에서 프레드 드레이크(Fred L. Drake)가 쓴 "어떻게 파이썬을 문서화하는가"를 볼 수 있다. 이는 파이썬 모듈에서 보통 사용되는 LaTex 예제를 알려주는 문서이다. 파이썬 커뮤니티 덕분에 문서화의 수준이 높다. 이미 등록된 문서들이 훌륭하기 때문에, 파이썬 프로그래머들 역시 새로 문서화 할 때 잘 해야겠다고 생각한다. 소스코드를 문서화하는 프로그래머의 노력은 문서화의 강력함을 증폭시키고 문서를 중요하다고 생각하는 사람들을 끌어들인다. 그리고 이러한 현상은 계속된다. 표준 문서는 다운받아서 개인 컴퓨터에서 이용할 수 있다. 윈도우에 표준으로 설치한 파이썬은 바탕화면에 "파이썬 문서" 바로가기를 만드는데, 이는 위에서 언급한 사용자의 컴퓨터에서 볼 수 있는 문서이 다. __doc__ 마법 파이썬에서 좀더 두드러진 특징은 파이썬 인터프리터 내에서 도움말을 사용할 수 있다는 것이다. 많은 파이썬 프로그래머들은 인터프리터 내에서 바로 작업을 한다. 이 인터프리터 내에서 파이썬 객체(함수,모듈 등)의 __doc__ 값을 요청함으로써 파이썬 객체에 대해 질문할 수 있다. 예를 들어서 어떠한 작업 도중 파일 접근 허가권에 대해서 궁금해 한다고 하자.

>>> import os
>>> os.access__doc__
"access(path, mode) -> 1 if granted, 0 otherwise
Test for access to a file."
>>>
처음으로 __doc__을 접한다면, 이것이 무엇을 의미하는지 궁금할 것이다. 그것은 쓰기 불편한 표준 문서의 축약본이다. 그렇지만 파이썬 전문가들은 항상 __doc__를 이용한다. 간단한 __doc__ 출력은 종종 파라미터 순서 등 필요한 정보를 제공한다. 하지만 이를 전체 문서에서 찾는다면 많은 시간이 소요될 것이다. __doc__는 고유한 순환을 한다. 훌륭한 파이썬 프로그래머라면 __doc__를 매우 자주 사용하기 때문에, 라이브러리 제작자는 고수준의 __doc__ 설명이 높이 평가된다는 것을 알고 있을 것이다. 또한 __doc__의 사용을 급증시키는 간단한 기술적 트릭이 있다. 이는 대부분의 파이썬 속성이 다음과 같은 문장을 통해 적절하게 지정된다는 것이다.

thing.attribute = "This is a description."
__doc__의 특별한 경우를 위해 다음과 같이 축약한다. - 정의(definition)의 첫번째 문장이 문자열일 경우 그 문자열은 정의된 객체의 __doc__이 된다. 그 예는 다음과 같다.

def phase_of_the_moon():
   "This function returns a slightly randomized
   integer that shuffles data around in a way
   convenient for the XYZ class."
   # Working code here.
   return value
"This function ..." 이라는 설명은 이 함수의 docstring인 phase_of_the_moon.__doc__이다. __doc__의 기초를 넘어 대부분의 파이썬 프로그래머들이 최소한의 docstring을 작성하기 때문에, 몇 가지 유용한 툴을 사용하면 이러한 정보를 잘 활용할 수 있다. Pytext는 설명을 DOM 트리로 변환한다. - DOM 트리는 인덱스를 위한 XML에 관련된 데이터 구조이다. Docutils는 다양한 문서 형식으로 변환하기 위해 좀더 많은 정보를 모은다. 그리고 PyDoc을 사용하면 문서, 특히 docstring을 다양한 형식으로 바꿀 수 있다. 이 모든 툴 중에서 doctest가 가장 간결하고 성능이 훌륭하다. Doctest는 docstring에 간단한 자체 테스트 예제를 포함시키기 위한 것이다. doctest 자신의 설명은 다음과 같다. "doctest 모듈은 파이썬의 인터랙티브한 세션과 같은 텍스트를 위해 모듈의 docstring을 찾는다. 그리고 그것들이 보이는 것처럼 정확하게 작동하는 것을 검증하기 위해 그러한 모든 세션들을 실행한다." 다음 팩토리얼 함수 정 의의 예를 보자. docstring이 다음과 같이 인터랙티브한 예제를 포함한다.

>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
>>> factorial(30)
265252859812191058636308480000000L
물론 팩토리얼의 정의는 다른 파이썬 코드에서 재사용될 수 있도록 디자인 되었다. 동시에 doctest 포맷을 따르기 때문에, 이 정의는 내용을 검증하기 위해 혼자서도 실행될 수 있다. 이러한 종류의 내적 관찰 때문에 파이썬이라는 훌륭한 언어는 인터프리터가 생산적으로 될 수 있다. Doctest는 파이썬 커뮤티니의 또 다른 사회적 관습에 기반하여 생성된다. C와 같은 언어에서 계속되는 도전의 하나는 유닛테스트를 어떻게 디자인하고 구현하는가 이다. 이것은 일반적으로 상급 프로그래머에 게 곤란한 문제이다. 하지만 파이썬에서는 전통적으로 각 정의에 유닛테스트가 있어야 한다. 파이썬 소스 파일은 종종 다음과 같이 끝난다.

if __name__ == "__main__":
  # Self-testing code goes here.
else:
  # This will be executed in case the
  #   source has been imported as a
  #   module.
† 역자주: 파이썬 모듈이 직접 실행될때는 __name__이라는 변수가 "__main__"이라는 값을 갖게된다. 모듈로 임포트될 경우에는 __name__에 그 모듈의 이름이 들어간다. 이러한 문장은 소스가 다른 애플리케이션에서 모듈로서 재사용될 수 있고 즉각적인 자체 테스팅으로도 사용될 수 있다는 것을 의미한다. doctest 예제의 경우에서처럼, 자체 테스팅 코드는 doctest를 불러들이고 자신의 소스파일에 적용시킨다. 이러한 일련의 작업은 매우 간결하다.

def _test():
  import doctest, example
  return doctest.testmod(example)

if __name__ == "__main__":
  _test()
파이썬을 사용하는데 있어 이러한 강력한 전통을 따름으로써, 몇 줄 안되는 소스코드로 자체 검증을 한다는 강력한 결과를 이루어낼 수 있다. 문서 관리의 또 다른 이점 문서화에 있어서 이러한 자동화와 강력한 사회적 기대가 파이썬 프로그래밍이 널리 퍼지는 요인이 되고 있다. 다른 언어와 비교할 때 문서화가 잘 되어 있고, 기술적으로도 우월한 점이 있다. 그럼에도 불구하고 파이썬은 프로그래머가 툴의 약속을 지킨다는 점에서 본질적으로 독특하다. Pythondoc은 Javadoc과 비슷한 툴이다. - 이것은 소스코드 주석으로부터 문서를 생성하는데 Python styleguide에 의존한다. 파이썬의 문서화는 계속 발전하고 있다. 여기서 언급했던 모든 툴과 레퍼런스는 계속해서 활발히 개발되고 있다. 지금 꽃이 피는 영역은 "structured text(ST)"이다. 이는 docstring 등의 문서 재료들을 변환시키는 것을 가리킨다. ST를 처리하는 것이 발전되면, 초보 프로그래머나 프로그래머가 아닌 사람들도 파이썬을 사용할 수 있다. 왜 ST인가? 간단하게 말하면, "일반 사람"은 구조적인 글을 읽고 쓸 수 있기 때문이다. 예를 들자면 대부분의 사람에게 있어 구조적인 글은 XML보다 덜 엄격하고 훨씬 읽기 쉽다. 또다른 예로 구조적인 글은 문단을 암시적으로 인지한다.

def something():
  "This is a first paragraph.

  This is a second paragraph.  The intervening
  blank line means this must be a new paragraph."
  #  ... 
하지만 HTML에는 이와 반대로 문단을 나타내는

라는 태그가 있어야 한다. 요약 파이썬에는 문법과 레퍼런스 매뉴얼 이상의 것이 있다. 파이썬에서 많은 것을 얻으려면 파이썬의 방식으로 문서화하는 법을 배워야 한다. 다른 프로그래머가 작성한 docstring을 찾아라. 이는 많은 고기를 갖는 것과 같다. docstring을 포함해서 훌륭한 방법으로 당신의 소스에 주석을 달아라. 소스코드와 훌륭한 문서를 전통적인 파이썬 스타일로 어떻게 제공하든지 간에, 다른 사람들이 당신의 코드를 빨리 이해하는데 도움을 줄 것이다. 이호재님은 한빛 리포터 1기로 활동 중입니다. 카드 코리아 개발 실장으로 근무한 경험이 있으며, 지금은 서울대 지구환경시스템공학부(컴퓨터 공학)에 다니고 있습니다. 컴퓨터에 관련된 모든 분야에 두루 관심이 많으며, 요즈음엔 파이썬, MPI, PHP 등에 관심이 많다고 합니다.

TAG :
댓글 입력
자료실