"doctest" --- 대화형 파이썬 예제 테스트
***************************************

**소스 코드:** Lib/doctest.py

======================================================================

"doctest" 모듈은 대화형 파이썬 세션처럼 보이는 텍스트를 검색한 다음,
해당 세션을 실행하여 표시된 대로 정확하게 작동하는지 검증합니다.
doctest를 사용하는 몇 가지 일반적인 방법이 있습니다:

* 모든 대화식 예제가 설명된 대로 작동하는지 확인하여 모듈의 독스트링이
  최신인지 확인합니다.

* 테스트 파일이나 테스트 객체의 대화형 예제가 예상대로 작동하는지 확인
  하여 회귀 테스트를 수행합니다.

* 입/출력 예제를 그대로 보여줌으로써 패키지에 대한 자습서를 작성합니다
  . 예제나 설명문 중 어느 것이 강조되는지에 따라, "문학적 테스트
  (literate testing)"나 "실행 가능한 설명서(executable documentation)"
  의 느낌을 줍니다.

여기에 완전하지만 작은 예제 모듈이 있습니다:

   """
   이것은 "예제" 모듈입니다.

   예제 모듈은 factorial() 함수 하나를 제공합니다. 예를 들어,

   >>> factorial(5)
   120
   """

   def factorial(n):
       """n의 계승을 반환합니다, 정확한 정수 >= 0.

       >>> [factorial(n) for n in range(6)]
       [1, 1, 2, 6, 24, 120]
       >>> factorial(30)
       265252859812191058636308480000000
       >>> factorial(-1)
       Traceback (most recent call last):
           ...
       ValueError: n must be >= 0

       float의 계승도 좋습니다만, float는 정확한 정수여야 합니다:
       >>> factorial(30.1)
       Traceback (most recent call last):
           ...
       ValueError: n must be exact integer
       >>> factorial(30.0)
       265252859812191058636308480000000

       또한 터무니없이 크지 않아야 합니다:
       >>> factorial(1e100)
       Traceback (most recent call last):
           ...
       OverflowError: n too large
       """

       import math
       if not n >= 0:
           raise ValueError("n must be >= 0")
       if math.floor(n) != n:
           raise ValueError("n must be exact integer")
       if n+1 == n:  # 1e300과 같은 값을 잡아냅니다
           raise OverflowError("n too large")
       result = 1
       factor = 2
       while factor <= n:
           result *= factor
           factor += 1
       return result


   if __name__ == "__main__":
       import doctest
       doctest.testmod()

"example.py"를 명령 줄에서 직접 실행하면, "doctest"가 마술을 부리기 시
작합니다:

   $ python example.py
   $

출력이 없습니다! 이것이 정상이며, 모든 예제가 작동했다는 것을 뜻합니다
. "-v"를 스크립트에 전달하면, "doctest"는 시도하고 있는 내용에 대한 자
세한 로그를 출력하고 끝에 요약을 인쇄합니다.:

   $ python example.py -v
   Trying:
       factorial(5)
   Expecting:
       120
   ok
   Trying:
       [factorial(n) for n in range(6)]
   Expecting:
       [1, 1, 2, 6, 24, 120]
   ok

결국, 다음과 같이 끝납니다:

   Trying:
       factorial(1e100)
   Expecting:
       Traceback (most recent call last):
           ...
       OverflowError: n too large
   ok
   2 items passed all tests:
      1 test in __main__
      6 tests in __main__.factorial
   7 tests in 2 items.
   7 passed.
   Test passed.
   $

이것이 "doctest"를 생산적으로 사용하기 위해서 알아야 할 모든 것입니다!
시도해 보세요. 다음 절에서는 자세한 내용을 제공합니다. 표준 파이썬 테
스트 스위트와 라이브러리에는 doctest 예제가 많습니다. 특히 유용한 예제
는 표준 테스트 파일 "Lib/test/test_doctest/test_doctest.py"에서 찾을
수 있습니다.

Added in version 3.13: Output is colorized by default and can be
controlled using environment variables.


간단한 사용법: 독스트링에 있는 예제 확인하기
============================================

doctest를 사용하는 가장 간단한 방법은 (하지만 계속 이렇게 할 필요는 없
습니다) 각 모듈 "M"을 다음과 같이 끝내는 것입니다:

   if __name__ == "__main__":
       import doctest
       doctest.testmod()

그러면 "doctest"는 모듈 "M"의 독스트링을 검사합니다.

모듈을 스크립트로 실행하면 독스트링의 예제가 실행되고 검증됩니다:

   python M.py

예제가 실패하지 않는 한 아무것도 표시되지 않습니다, 실패하면 실패한 예
제와 실패 원인이 stdout으로 출력되고, 마지막 출력 줄은 "***Test
Failed*** N failures."입니다. 여기서 *N*은 실패한 예제의 수입니다.

대신 "-v" 스위치로 실행해 보십시오:

   python M.py -v

그러면 시도한 모든 예제에 대한 자세한 보고서가 표준 출력으로 출력되고,
끝에 정돈된 요약이 붙습니다.

You can force verbose mode by passing "verbose=True" to "testmod()",
or prohibit it by passing "verbose=False".  In either of those cases,
"sys.argv" is not examined by "testmod()" (so passing "-v" or not has
no effect).

"testmod()"를 실행하는 명령줄 바로 가기도 있습니다, 명령줄 사용법 절을
참조하십시오.

"testmod()"에 대한 자세한 내용은, 기본 API 절을 참조하십시오.


간단한 사용법: 텍스트 파일에 있는 예제 확인하기
===============================================

doctest의 또 다른 간단한 활용은 텍스트 파일에 있는 대화형 예제를 테스
트하는 것입니다. 이것은 "testfile()" 함수로 수행할 수 있습니다:

   import doctest
   doctest.testfile("example.txt")

이 짧은 스크립트는 "example.txt" 파일에 들어있는 대화형 파이썬 예제를
실행하고 검증합니다. 파일 내용은 하나의 거대한 독스트링인 것처럼 취급
됩니다; 파일이 파이썬 프로그램일 필요가 없습니다! 예를 들어,
"example.txt"에 다음과 같은 것이 들어있습니다:

   The ``example`` module
   ======================

   Using ``factorial``
   -------------------

   This is an example text file in reStructuredText format.  First import
   ``factorial`` from the ``example`` module:

       >>> from example import factorial

   Now use it:

       >>> factorial(6)
       120

"doctest.testfile("example.txt")"를 실행하면 이 문서에 있는 에러를 찾
습니다:

   File "./example.txt", line 14, in example.txt
   Failed example:
       factorial(6)
   Expected:
       120
   Got:
       720

As with "testmod()", "testfile()" won't display anything unless an
example fails.  If an example does fail, then the failing example(s)
and the cause(s) of the failure(s) are printed to stdout, using the
same format as "testmod()".

기본적으로, "testfile()"은 호출하는 모듈의 디렉터리에서 파일을 찾습니
다. 다른 위치에서 파일을 찾도록 지시하는 데 사용할 수 있는 선택적 인자
에 대한 설명은 기본 API 절을 참조하십시오.

"testmod()"와 마찬가지로, "testfile()"의 상세도는 "-v" 명령 줄 스위치
나 선택적 키워드 인자 *verbose*를 사용하여 설정할 수 있습니다.

"testfile()"을 실행하는 명령줄 바로 가기도 있습니다, 명령줄 사용법 절
을 참조하십시오.

"testfile()"에 대한 자세한 내용은, 기본 API 절을 참조하십시오.


명령줄 사용법
=============

The "doctest" module can be invoked as a script from the command line:

   python -m doctest [-v] [-o OPTION] [-f] file [file ...]

-v, --verbose

   시도한 모든 예제에 대한 자세한 보고서가 표준 출력으로 출력되고, 끝
   에 정돈된 요약이 붙습니다:

      python -m doctest -v example.py

   이렇게 하면 "example.py"를 독립 실행형 모듈로 임포트하고,
   "testmod()"를 실행합니다. 파일이 패키지 일부이고 그 패키지에서 다른
   서브 모듈을 임포트하면, 올바르게 작동하지 않을 수 있음에 유의하십시
   오.

   파일 이름이 ".py"로 끝나지 않으면, "doctest"는 대신 "testfile()"로
   실행되어야 한다고 추론합니다:

      python -m doctest -v example.txt

-o, --option <option>

   Option flags control various aspects of doctest's behavior, see
   section 옵션 플래그.

   Added in version 3.4.

-f, --fail-fast

   "-o FAIL_FAST"의 축약입니다.

   Added in version 3.4.


작동 방법
=========

이 절에서는 doctest가 어떻게 작동하는지 자세히 설명합니다: 어떤 독스트
링을 살피는지, 대화형 예제를 어떻게 찾는지, 사용하는 실행 컨텍스트는
무엇인지, 예외를 어떻게 처리하는지, 어떻게 옵션 플래그를 사용하여 동작
을 제어하는지. 이것은 doctest 예제를 작성하기 위해 알아야 할 정보입니
다; 이러한 예제에 대해 실제로 doctest를 실행하는 방법에 대한 자세한 내
용은 다음 절을 참조하십시오.


어떤 독스트링을 검사합니까?
---------------------------

모듈 독스트링과 모든 함수, 클래스 및 메서드 독스트링이 검색됩니다. 모
듈로 임포트 된 객체는 검색되지 않습니다.

또한, 테스트를 모듈의 일부로 포함시키고 싶지만 도움말 텍스트에는 포함
시키고 싶지 않은 경우가 있습니다. 이 경우 테스트가 독스트링에 포함되지
않도록 해야 합니다. Doctest는 모듈 수준 변수인 "__test__"를 보고 이를
통해 다른 테스트를 찾아냅니다. "M.__test__"가 존재하면, 딕셔너리이어야
하고 각 항목은 (문자열) 이름을 함수 객체, 클래스 객체 또는 문자열에 매
핑합니다. "M.__test__"에서 발견된 함수와 클래스 객체 독스트링이 검색되
고, 문자열은 독스트링인 것처럼 처리됩니다. 출력에서, "M.__test__"의 키
"K"가 이름 "M.__test__.K"로 나타납니다.

For example, place this block of code at the top of "example.py":

   __test__ = {
       'numbers': """
   >>> factorial(6)
   720

   >>> [factorial(n) for n in range(6)]
   [1, 1, 2, 6, 24, 120]
   """
   }

The value of "example.__test__["numbers"]" will be treated as a
docstring and all the tests inside it will be run. It is important to
note that the value can be mapped to a function, class object, or
module; if so, "doctest" searches them recursively for docstrings,
which are then scanned for tests.

발견된 모든 클래스는 포함된 메서드와 중첩된 클래스의 독스트링을 테스트
하기 위해 유사하게 재귀적으로 검색됩니다.

참고:

  "doctest" can only automatically discover classes and functions that
  are defined at the module level or inside other classes.Since nested
  classes and functions only exist when an outer function is called,
  they cannot be discovered. Define them outside to make them visible.


독스트링 예제는 어떻게 인식됩니까?
----------------------------------

대부분 대화형 콘솔 세션의 복사하여 붙여넣기가 잘 작동하지만, doctest는
특정 파이썬 셸의 정확한 에뮬레이션을 시도하지 않습니다.

   >>> # 주석은 무시됩니다
   >>> x = 12
   >>> x
   12
   >>> if x == 13:
   ...     print("yes")
   ... else:
   ...     print("no")
   ...     print("NO")
   ...     print("NO!!!")
   ...
   no
   NO
   NO!!!
   >>>

모든 예상 출력은 코드가 포함된 마지막 "'>>> '" 또는 "'... '" 줄 바로
다음에 나와야 하며, (있다면) 예상 출력은 다음 "'>>> '" 나 전체 공백 줄
까지 확장됩니다.

세부 사항:

* 예상 출력은 전체 공백 줄을 포함할 수 없습니다. 그러한 줄은 예상 출력
  의 끝으로 인식되기 때문입니다. 예상 출력이 빈 줄을 포함하면, doctest
  예제에서 빈 줄이 나타나는 곳에 "<BLANKLINE>"을 넣으십시오.

* 모든 하드 탭 문자는 8열 탭 정지를 사용하여 스페이스로 확장됩니다. 테
  스트 된 코드에 의해 생성된 출력의 탭은 수정되지 않습니다. 샘플 출력
  의 모든 하드 탭이 *확장되므로*, 이것은 코드 출력에 하드 탭이 포함될
  때 doctest가 통과할 수 있는 유일한 방법은, "NORMALIZE_WHITESPACE" 옵
  션이나 지시자가 유효한 경우뿐임을 의미합니다. 또는, 출력을 캡처하여
  테스트 일부로 예상값과 비교하도록 테스트를 다시 작성할 수 있습니다.
  이러한 소스의 탭 처리는 시행착오를 거쳐 얻어진 것이며, 가장 에러가
  발생하지 않는 방법으로 입증되었습니다. 사용자 정의 "DocTestParser"
  클래스를 작성하여 탭 처리에 다른 알고리즘을 사용하는 것도 가능합니다
  .

* stdout으로의 출력은 캡처되지만, stderr로의 출력은 그렇지 않습니다 (
  예외 트레이스백은 다른 수단을 통해 캡처됩니다).

* 대화식 세션에서 역 슬래시를 통해 줄을 계속하거나, 다른 이유로 백 슬
  래시를 사용하면, 날 독스트링(raw docstring)을 사용해서 역 슬래시를
  입력한 그대로 유지해야 합니다:

     >>> def f(x):
     ...     r'''Backslashes in a raw docstring: m\n'''
     ...
     >>> print(f.__doc__)
     Backslashes in a raw docstring: m\n

  그렇지 않으면, 백 슬래시가 문자열 일부로 해석됩니다. 예를 들어, 위의
  "\n"은 개행 문자로 해석됩니다. 또는, doctest 버전에서 각 백 슬래시를
  중복시킬 수 있습니다 (그리고 날 문자열은 사용하지 않습니다):

     >>> def f(x):
     ...     '''Backslashes in a raw docstring: m\\n'''
     ...
     >>> print(f.__doc__)
     Backslashes in a raw docstring: m\n

* 시작 열은 중요하지 않습니다:

     >>> assert "Easy!"
           >>> import math
               >>> math.floor(1.9)
               1

  그리고 예제를 시작한 초기 "'>>> '" 줄에 나타나는 것만큼의 선행 공백
  을 예상 출력에서 제거합니다.


실행 컨텍스트란 무엇입니까?
---------------------------

기본적으로, "doctest"가 테스트할 독스트링을 찾을 때마다, "M"의 전역 이
름 공간(globals)의 *앝은 복사*를 사용하므로, 실행 중인 테스트는 모듈의
실제 전역을 변경하지 않고, "M"의 한 테스트가 실수로 다른 테스트가 작동
하도록 만드는 부스러기를 남기지 않습니다. 이는 예제가 "M"에서 최상위
수준에 정의된 이름과 실행 중인 독스트링에서 앞서 정의한 이름을 자유롭
게 사용할 수 있음을 의미합니다. 예제는 다른 독스트링에 정의된 이름을
볼 수 없습니다.

대신 "globs=your_dict"를 "testmod()"나 "testfile()"로 전달하여 실행 컨
텍스트로 여러분 자신의 딕셔너리를 사용하도록 할 수 있습니다.


예외는 어떻게 됩니까?
---------------------

문제없습니다, 트레이스백이 예제에 의해 생성된 유일한 출력이기만 하면
됩니다: 그냥 트레이스백을 붙여넣으십시오. [1] 트레이스백에는 빠르게 변
할 가능성이 있는 세부 사항(예를 들어, 정확한 파일 경로와 줄 번호)이 포
함되어 있으므로, 이것은 doctest가 수락할 내용에 유연하도록 신경 써야
하는 한 가지 사례입니다.

간단한 예:

   >>> [1, 2, 3].remove(42)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ValueError: list.remove(x): x not in list

이 doctest는 "list.remove(x): x not in list" 세부 정보를 포함하는
"ValueError"가 발생하면 성공합니다.

예외의 예상 출력은 다음 두 줄 중 한 가지가 예제의 첫 번째 줄과 같게 들
여쓰기 된 트레이스백 헤더로 시작해야 합니다:

   Traceback (most recent call last):
   Traceback (innermost last):

트레이스백 헤더 다음에는 선택적인 트레이스백 스택이 오며, 그 내용은
doctest가 무시합니다. 보통 트레이스백 스택은 생략되거나, 대화형 세션에
서 그대로 복사됩니다.

트레이스백 스택 다음에는 가장 흥미로운 부분이 옵니다: 예외 형과 세부
사항이 있는 줄. 대개 이것은 트레이스백의 마지막 줄이지만, 예외에 여러
줄로 구성된 세부 사항이 있으면 여러 줄로 확장될 수 있습니다:

   >>> raise ValueError('multi\n    line\ndetail')
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ValueError: multi
       line
   detail

("ValueError"로 시작하는) 마지막 세 줄이 예외의 형 및 세부 사항과 비교
되고, 나머지는 무시됩니다.

모범 사례는 예제에 중요한 설명으로서의 가치를 추가하지 않는 한 트레이
스백 스택을 생략하는 것입니다. 따라서 마지막 예제는 이렇게 하는 것이
더 좋습니다:

   >>> raise ValueError('multi\n    line\ndetail')
   Traceback (most recent call last):
       ...
   ValueError: multi
       line
   detail

트레이스백이 매우 특별하게 취급된다는 점에 유의하십시오. 특히, 다시 작
성된 예제에서, "..."의 사용은 doctest의 "ELLIPSIS" 옵션과 무관합니다.
이 예제의 줄임표는 생략하거나, 3개(혹은 300개)의 쉼표나 숫자 또는 몬티
파이썬 쇼의 들여쓰기 된 대본이어도 똑같이 잘 동작합니다.

한 번쯤 읽어야 할 세부 정보이지만, 기억할 필요는 없습니다:

* Doctest는 예상 출력이 예외 트레이스백에서 온 것인지 일반 인쇄에서 온
  것인지 추측할 수 없습니다. 그래서, 예를 들어, "ValueError: 42 is
  prime"을 예상하는 예제는 "ValueError"가 실제로 발생해도 통과하지만,
  예제가 단지 그 트레이스백 텍스트를 출력해도 통과합니다. 실제로는, 일
  반 출력은 거의 트레이스백 헤더 줄로 시작하지 않으므로, 실제 문제가
  되지는 않습니다.

* (있다면) 트레이스백 스택의 각 줄은 예제의 첫 번째 줄보다 더 들여쓰기
  되거나, *또는* 영숫자(alphanumeric)가 아닌 문자로 시작해야 합니다.
  트레이스백 헤더 뒤에 같은 정도로 들여쓰기 되고, 영숫자로 시작하는 첫
  번째 줄은 예외 세부 사항의 시작으로 간주합니다. 물론 이것은 진짜 트
  레이스백에 잘 들어맞습니다.

* "IGNORE_EXCEPTION_DETAIL" doctest 옵션을 지정하면, 가장 왼쪽 콜론 다
  음에 오는 모든 것과 예외 이름의 모듈 정보가 무시됩니다.

* The interactive shell omits the traceback header line for some
  "SyntaxError"s.  But doctest uses the traceback header line to
  distinguish exceptions from non-exceptions.  So in the rare case
  where you need to test a "SyntaxError" that omits the traceback
  header, you will need to manually add the traceback header line to
  your test example.

* 일부 예외의 경우, 파이썬은 "^" 마커와 물결표를 사용하여 에러의 위치
  를 표시합니다:

     >>> 1 + None
       File "<stdin>", line 1
         1 + None
         ~~^~~~~~
     TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'

  에러의 위치를 나타내는 줄은 예외 형과 세부 사항 앞에 오므로, doctest
  가 점검하지 않습니다. 예를 들어, "^" 마커를 잘못된 위치에 넣어도, 다
  음 테스트가 통과합니다:

     >>> 1 + None
       File "<stdin>", line 1
         1 + None
         ^~~~~~~~
     TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'


옵션 플래그
-----------

많은 옵션 플래그가 doctest의 다양한 동작을 제어합니다. 플래그의 기호
이름은 모듈 상수로 제공되며, 함께 비트별 OR되어 다양한 함수로 전달될
수 있습니다. 이 이름은 doctest 지시자에서도 사용될 수 있으며, "-o" 옵
션을 통해 doctest 명령 줄 인터페이스로 전달될 수 있습니다.

첫 번째 옵션 그룹은 테스트의 의미를 정의하는데, doctest가 실제 출력이
예제의 예상 출력과 일치하는지를 결정하는 측면을 제어합니다:

doctest.DONT_ACCEPT_TRUE_FOR_1

   기본적으로, 예상 출력 블록에 "1" 만 있으면, 단지 "1"이나 "True" 만
   포함된 실제 출력 블록을 일치하는 것으로 간주하며, "0"과 "False"도
   유사하게 다룹니다. "DONT_ACCEPT_TRUE_FOR_1"이 지정되면, 두 치환 모
   두 허용되지 않습니다. 기본 동작은 파이썬이 많은 함수의 반환형을 정
   수에서 논릿값으로 변경했다는 것을 반영합니다; "작은 정수" 출력을 예
   상하는 doctest가 이러한 경우에 여전히 작동합니다. 아마도 이 옵션은
   사라지게 되겠지만, 몇 년 동안은 남아있을 겁니다.

doctest.DONT_ACCEPT_BLANKLINE

   기본적으로, 예상 출력 블록에 "<BLANKLINE>" 문자열만 포함된 줄이 있
   으면, 해당하는 줄은 실제 출력의 빈 줄과 일치합니다. 진짜 빈 줄은 예
   상 출력을 끝내므로, 이것이 빈 줄을 예상하는 유일한 방법입니다.
   "DONT_ACCEPT_BLANKLINE"이 지정되면, 이 치환은 허용되지 않습니다.

doctest.NORMALIZE_WHITESPACE

   지정되면, 모든 공백(빈칸과 개행) 시퀀스는 같게 취급됩니다. 예상 출
   력 내의 모든 공백 시퀀스는 실제 출력 내의 모든 공백 시퀀스와 일치합
   니다. 기본적으로, 공백은 정확히 일치해야 합니다.
   "NORMALIZE_WHITESPACE"는 예상 출력 줄이 매우 길고 소스의 여러 줄에
   걸쳐 줄넘김하려는 경우에 특히 유용합니다.

doctest.ELLIPSIS

   지정되면, 예상 출력의 줄임표("...")가 실제 출력의 모든 부분 문자열
   과 일치 할 수 있습니다. 여기에는 줄 경계를 넘는 부분 문자열과 빈 부
   분 문자열이 포함되므로, 사용을 간단하게 유지하는 것이 가장 좋습니다
   . 복잡한 사용은 정규식에서 ".*"를 쓸 때처럼 "이런, 너무 많이 일치하
   는군!" 과 같은 상황을 만들 수 있습니다.

doctest.IGNORE_EXCEPTION_DETAIL

   When specified, doctests expecting exceptions pass so long as an
   exception of the expected type is raised, even if the details
   (message and fully qualified exception name) don't match.

   For example, an example expecting "ValueError: 42" will pass if the
   actual exception raised is "ValueError: 3*14", but will fail if,
   say, a "TypeError" is raised instead. It will also ignore any fully
   qualified name included before the exception class, which can vary
   between implementations and versions of Python and the
   code/libraries in use. Hence, all three of these variations will
   work with the flag specified:

      >>> raise Exception('message')
      Traceback (most recent call last):
      Exception: message

      >>> raise Exception('message')
      Traceback (most recent call last):
      builtins.Exception: message

      >>> raise Exception('message')
      Traceback (most recent call last):
      __main__.Exception: message

   Note that "ELLIPSIS" can also be used to ignore the details of the
   exception message, but such a test may still fail based on whether
   the module name is present or matches exactly.

   버전 3.2에서 변경: "IGNORE_EXCEPTION_DETAIL"은 이제 테스트 중인 예
   외를 포함하는 모듈과 관련된 정보도 무시합니다.

doctest.SKIP

   지정되면, 예제를 전혀 실행하지 않습니다. 이것은 doctest 예제가 설명
   서와 테스트 케이스의 두 가지 역할을 하는 문맥에서, 설명을 위해 예제
   를 포함해야 하지만 검사하지는 않아야 할 때 유용할 수 있습니다. 예를
   들어, 예제의 출력이 임의적일 수 있습니다; 또는 예제가 테스트 구동기
   에서 사용할 수 없는 자원에 의존할 수 있습니다.

   SKIP 플래그는 임시로 "주석 처리한" 예제를 위해 사용될 수도 있습니다
   .

doctest.COMPARISON_FLAGS

   위의 모든 비교 플래그를 함께 OR 한 비트 마스크.

두 번째 옵션 그룹은 테스트 실패가 보고되는 방식을 제어합니다:

doctest.REPORT_UDIFF

   지정되면, 여러 줄의 예상 및 실제 출력을 수반하는 실패가 통합
   (unified) diff를 사용하여 표시됩니다.

doctest.REPORT_CDIFF

   지정되면, 여러 줄의 예상 및 실제 출력을 수반하는 실패가 문맥
   (context) diff를 사용하여 표시됩니다.

doctest.REPORT_NDIFF

   지정되면, 차이점은 널리 사용되는 "ndiff.py" 유틸리티와 같은 알고리
   즘을 사용하여, "difflib.Differ"로 계산됩니다. 이 방법은 줄 간의 차
   이뿐만 아니라 줄 안에서의 차이점을 표시하는 유일한 방법입니다. 예를
   들어, 예상 출력 줄에 숫자 "1"이 포함된 줄에 실제 출력이 문자 "l"을
   포함하고 있으면, 일치하지 않는 열 위치를 나타내는 캐럿(caret)이 들
   어간 줄이 삽입됩니다.

doctest.REPORT_ONLY_FIRST_FAILURE

   지정되면, 각 doctest에서 실패한 첫 번째 예제를 표시하지만, 나머지
   모든 예제에 대해서는 출력을 억제합니다. 이렇게 하면 doctest가 이전
   의 실패로 인해 망가진 올바른 예제를 보고하지 않게 되지만, 첫 번째
   실패와 무관하게 실패한 잘못된 예제를 숨길 수도 있습니다.
   "REPORT_ONLY_FIRST_FAILURE"가 지정될 때, 나머지 예제는 여전히 실행
   되며, 보고된 총실패 수에 포함됩니다; 출력만 억제됩니다.

doctest.FAIL_FAST

   지정되면, 첫 번째 실패 예제 후에 종료하고, 나머지 예제를 실행하지
   않습니다. 따라서, 보고되는 실패 횟수는 최대 1입니다. 이 플래그는 디
   버깅 중에 유용할 수 있습니다, 첫 번째 실패 이후의 예제는 디버깅 출
   력조차 생성하지 않기 때문입니다.

doctest.REPORTING_FLAGS

   위의 모든 보고(reporting) 플래그를 함께 OR 한 비트 마스크.

새로운 옵션 플래그 이름을 등록하는 방법도 있습니다만, 서브 클래스를 통
해 "doctest" 내부를 확장하려고 하지 않는 한 유용하지는 않습니다:

doctest.register_optionflag(name)

   지정된 이름으로 새로운 옵션 플래그를 만들고, 새로운 플래그의 정숫값
   을 반환합니다. "register_optionflag()"은 "OutputChecker"나
   "DocTestRunner"를 서브 클래싱할 때 서브 클래스가 지원하는 새 옵션을
   만들 때 사용할 수 있습니다. "register_optionflag()"는 항상 다음의
   관용구를 사용하여 호출해야 합니다:

      MY_FLAG = register_optionflag('MY_FLAG')


지시자
------

Doctest 지시자를 사용하면 개별 예제의 옵션 플래그를 수정할 수 있습니다
. Doctest 지시자는 예제의 소스 코드 뒤에 오는 특수한 파이썬 주석입니다
:

   directive:             "#" "doctest:" directive_options
   directive_options:     directive_option ("," directive_option)*
   directive_option:      on_or_off directive_option_name
   on_or_off:             "+" | "-"
   directive_option_name: "DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...

"+"나 "-"와 지시자 옵션 이름 사이의 공백은 허용되지 않습니다. 지시자
옵션 이름은 위에 설명된 옵션 플래그 이름 중 하나일 수 있습니다.

예제의 doctest 지시자는 그 단일 예제에 대한 doctest의 동작을 수정합니
다. 이름 붙인 동작을 활성화하려면 "+"를 사용하고, 비활성화하려면 "-"를
사용하십시오.

예를 들어, 이 테스트는 통과합니다:

   >>> print(list(range(20)))  # doctest: +NORMALIZE_WHITESPACE
   [0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
   10,  11, 12, 13, 14, 15, 16, 17, 18, 19]

지시자가 없으면 실패하는데, 실제 출력에는 한 자리 숫자 리스트 요소 앞
에 두 개의 공백이 없기도 하고, 실제 출력은 한 줄이기 때문입니다. 이 테
스트도 통과하는데, 그러기 위해서 역시 지시자가 필요합니다:

   >>> print(list(range(20)))  # doctest: +ELLIPSIS
   [0, 1, ..., 18, 19]

하나의 물리적 줄에 여러 개의 지시자를 쉼표로 구분하여 사용할 수 있습니
다:

   >>> print(list(range(20)))  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
   [0,    1, ...,   18,    19]

하나의 예제에 여러 개의 지시자 주석이 사용되면, 모두 결합합니다:

   >>> print(list(range(20)))  # doctest: +ELLIPSIS
   ...                         # doctest: +NORMALIZE_WHITESPACE
   [0,    1, ...,   18,    19]

앞의 예가 보여주듯이, 여러분의 예제에 지시자만 포함된 "..." 줄을 추가
할 수 있습니다. 예가 너무 길어서 지시자가 같은 줄에 편안하게 들어갈 수
없을 때 유용할 수 있습니다:

   >>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
   ... # doctest: +ELLIPSIS
   [0, ..., 4, 10, ..., 19, 30, ..., 39]

모든 옵션은 기본적으로 비활성화되고, 지시자가 표시된 예제에만 적용되므
로, (지시자에 "+"를 통해) 옵션을 활성화하는 것이 일반적으로 유일한 의
미 있는 선택입니다. 하지만, doctest를 실행하는 함수에 옵션 플래그를 전
달하여 다른 기본값을 설정할 수도 있습니다. 이럴 때, 지시자에서 "-"를
통해 옵션을 비활성화하는 것이 유용할 수 있습니다.


경고
----

"doctest"는 예상 출력에서 정확한 일치를 요구하는 것에 심각합니다. 단일
문자가 일치하지 않아도 테스트가 실패합니다. 여러분이 출력에 있어서 파
이썬이 정확히 무엇을 보장하고 무엇을 보장하지 않는지 배워감에 따라, 이
것은 아마도 여러분을 몇 번 놀라게 할 것입니다. 예를 들어, 집합을 인쇄
할 때, 파이썬은 원소가 특정 순서로 인쇄되는 것을 보장하지 않으므로, 다
음과 같은 테스트는

   >>> foo()
   {"spam", "eggs"}

취약합니다! 한 가지 해결 방법은 다음과 같습니다

   >>> foo() == {"spam", "eggs"}
   True

대신에. 또 다른 방법은

   >>> d = sorted(foo())
   >>> d
   ['eggs', 'spam']

다른 것들도 있지만, 아마 아이디어를 얻었을 겁니다.

또 다른 나쁜 생각은 객체 주소를 포함하는 것들을 출력하는 것입니다

   >>> id(1.0)  # 때로 실패할 것이 확실합니다
   7948648
   >>> class C: pass
   >>> C()  # 인스턴스에 대한 기본 repr()은 주소를 포함합니다
   <C object at 0x00AC18F0>

"ELLIPSIS" 지시자는 마지막 예제를 다루는 좋은 접근법을 제공합니다:

   >>> C()  # doctest: +ELLIPSIS
   <C object at 0x...>

Floating-point numbers are also subject to small output variations
across platforms, because Python defers to the platform C library for
some floating-point calculations, and C libraries vary widely in
quality here.

   >>> 1000**0.1  # risky
   1.9952623149688797
   >>> round(1000**0.1, 9) # safer
   1.995262315
   >>> print(f'{1000**0.1:.4f}') # much safer
   1.9953

"I/2.**J" 형식의 숫자는 모든 플랫폼에서 안전하며, 저는 종종 이런 형식
의 숫자를 만들도록 doctest 예제를 꾸밉니다:

   >>> 3./4  # 완전히 안전합니다
   0.75

간단한 분수는 또한 사람들이 이해하기가 더 쉬우므로, 더 좋은 설명서가
되도록 합니다.


기본 API
========

"testmod()"와 "testfile()" 함수는 대부분 기본 사용에 충분한 doctest에
대한 간단한 인터페이스를 제공합니다. 이 두 함수에 대한 덜 형식적인 소
개는 섹션 간단한 사용법: 독스트링에 있는 예제 확인하기와 간단한 사용법
: 텍스트 파일에 있는 예제 확인하기를 참조하십시오.

doctest.testfile(filename, module_relative=True, name=None, package=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, parser=DocTestParser(), encoding=None)

   *filename*를 제외한 모든 인자는 선택적이며 키워드 형식으로 지정해야
   합니다.

   *filename* 파일에 있는 예제를 테스트합니다. "(failure_count,
   test_count)"를 반환합니다.

   선택적 인자 *module_relative*는 filename을 해석하는 방법을 지정합니
   다:

   * *module_relative*가 "True"(기본값)이면, *filename*는 OS 독립적 모
     듈 상대 경로를 지정합니다. 기본적으로, 이 경로는 호출하는 모듈의
     디렉터리에 상대적입니다; 그러나 *package* 인자가 지정되면, 해당
     패키지에 상대적입니다. OS 독립성을 보장하기 위해, *filename*은
     "/" 문자를 사용하여 경로 세그먼트를 분리해야 하며, 절대 경로일 수
     없습니다 (즉, "/"로 시작할 수 없습니다).

   * *module_relative*가 "False"이면, *filename*은 OS 특정 경로를 지정
     합니다. 경로는 절대나 상대일 수 있습니다; 상대 경로는 현재 작업
     디렉터리를 기준으로 해석됩니다.

   선택적 인자 *name*은 테스트의 이름을 제공합니다; 기본적으로, 또는
   "None"이면, "os.path.basename(filename)"이 사용됩니다.

   선택적 인자 *package*는 디렉터리가 모듈 상대 filename의 기본 디렉터
   리로 사용될 파이썬 패키지나 파이썬 패키지의 이름입니다. 패키지를 지
   정하지 않으면, 호출하는 모듈의 디렉터리가 모듈 상대 filename의 기본
   디렉터리로 사용됩니다. *module_relative*가 "False"일 때 *package*를
   지정하는 것은 에러입니다.

   선택적 인자 *globs*는 예제를 실행할 때 전역으로 사용될 딕셔너리를
   제공합니다. doctest를 위해 이 딕셔너리의 새 얕은 사본이 만들어지므
   로, 예제는 깨끗한 서판으로 시작합니다. 기본적으로, 또는 "None"이면,
   새 빈 딕셔너리가 사용됩니다.

   선택적 인자 *extraglobs*는 예제를 실행하는 데 사용되는 전역에 병합
   될 딕셔너리를 제공합니다. 이것은 "dict.update()"처럼 작동합니다:
   *globs*와 *extraglobs*에 공통 키가 있으면, *extraglobs*의 연관된 값
   이 병합된 딕셔너리에 나타납니다. 기본적으로, 또는 "None"이면, 추가
   전역은 사용되지 않습니다. doctest의 매개 변수화를 허용하는 고급 기
   능입니다. 예를 들어, doctest는 클래스의 일반 이름을 사용하여 베이스
   클래스용으로 작성할 수 있습니다, 그런 다음 일반 이름을 테스트할 서
   브 클래스에 매핑하는 *extraglobs* 딕셔너리를 전달하여 임의의 수의
   서브 클래스를 테스트하는데 재사용할 수 있습니다.

   Optional argument *verbose* prints lots of stuff if true, and
   prints only failures if false; by default, or if "None", it's true
   if and only if "'-v'" is in "sys.argv".

   선택적 인자 *report*가 참이면 끝에 요약을 인쇄하고, 그렇지 않으면
   끝에 아무것도 인쇄하지 않습니다. verbose 모드에서는 요약 정보가 상
   세히 표시되며, 그렇지 않으면 요약 정보는 매우 간단합니다 (사실, 모
   든 테스트가 통과되면 비어 있습니다).

   Optional argument *optionflags* (default value "0") takes the
   bitwise OR of option flags. See section 옵션 플래그.

   선택적 인자 *raise_on_error*의 기본값은 거짓입니다. 참이면, 예제에
   서 첫 번째 실패나 예기치 않은 예외가 발생할 때 예외가 발생합니다.
   이것은 실패를 사후(post-mortem) 디버깅할 수 있도록 합니다. 기본 동
   작은 예제를 계속 실행하는 것입니다.

   선택적 인자 *parser*는 파일에서 테스트를 추출하는 데 사용할
   "DocTestParser"(또는 서브 클래스)를 지정합니다. 기본값은 일반 파서(
   즉, "DocTestParser()")입니다.

   선택적 인자 *encoding*은 파일을 유니코드로 변환하는 데 사용할 인코
   딩을 지정합니다.

doctest.testmod(m=None, name=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False)

   모든 인자는 선택적이며, *m*을 제외한 모든 인자는 키워드 형식으로 지
   정해야 합니다.

   모듈 *m*(또는 *m*가 제공되지 않았거나 "None"이면 모듈 "__main__")에
   서 도달할 수 있는 함수와 클래스의 독스트링에 있는 예제를 테스트합니
   다. "m.__doc__"으로 시작합니다.

   딕셔너리 "m.__test__"이 존재하면, 여기에서 도달할 수 있는 예제도 테
   스트합니다. "m.__test__"는 이름(문자열)을 함수, 클래스 및 문자열에
   매핑합니다; 함수와 클래스 독스트링에서 예제를 검색합니다; 문자열은
   그것이 독스트링인 것처럼 직접 검색합니다.

   모듈 *m*에 속하는 객체에 연결된 독스트링 만 검색합니다.

   "(failure_count, test_count)"를 반환합니다.

   선택적 인자 *name*은 모듈의 이름을 제공합니다; 기본적으로, 또는
   "None"이면, "m.__name__"이 사용됩니다.

   선택적 인자 *exclude_empty*의 기본값은 거짓입니다. 참이면, doctest
   가 발견되지 않은 객체는 고려 대상에서 제외됩니다. 기본값은 이전 버
   전과의 호환성을 위한 해킹입니다, 여전히 "testmod()"와 함께
   "doctest.master.summarize"를 사용하는 코드는 테스트가 없는 객체에
   대해 계속 출력합니다. 새로운 "DocTestFinder" 생성자에 대한
   *exclude_empty* 인자의 기본값은 참입니다.

   선택적 인자 *extraglobs*, *verbose*, *report*, *optionflags*,
   *raise_on_error* 및 *globs*는 위의 함수 "testfile()"와 같습니다만,
   *globs*의 기본값이 "m.__dict__"인 점이 다릅니다.

doctest.run_docstring_examples(f, globs, verbose=False, name='NoName', compileflags=None, optionflags=0)

   객체 *f*와 관련된 예제를 테스트합니다. 여기서, *f*는 문자열, 모듈,
   함수 또는 클래스 객체일 수 있습니다.

   딕셔너리 인자 *globs*의 얕은 사본이 실행 컨텍스트에 사용됩니다.

   선택적 인자 *name*은 실패 메시지에서 사용되며, 기본값은 ""NoName""
   입니다.

   선택적 인자 *verbose*가 참이면, 실패가 없어도 출력이 생성됩니다. 기
   본적으로, 출력은 예제가 실패할 때만 생성됩니다.

   선택적 인자 *compileflags*는 예제를 실행할 때 파이썬 컴파일러에서
   사용해야 하는 플래그 집합을 제공합니다. 기본적으로, 또는 "None"이면
   , *globs*에서 발견되는 퓨처 기능 집합에 해당하는 플래그가 추론됩니
   다.

   선택적 인자 *optionflags*는 위의 함수 "testfile()"에서 처럼 작동합
   니다.


Unittest API
============

doctest된 모듈 모음이 늘어남에 따라, 모든 doctest를 체계적으로 실행하
는 방법이 필요합니다. "doctest"는 doctest가 포함된 모듈과 텍스트 파일
로부터 "unittest" 테스트 스위트를 만드는 데 사용할 수 있는 두 가지 함
수를 제공합니다. "unittest" 테스트 탐색과 통합하려면, 테스트 모듈에
load_tests 함수를 포함하십시오:

   import unittest
   import doctest
   import my_module_with_doctests

   def load_tests(loader, tests, ignore):
       tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
       return tests

Doctest가 있는 텍스트 파일과 모듈로부터 "unittest.TestSuite" 인스턴스
를 만드는 두 가지 주요 함수가 있습니다:

doctest.DocFileSuite(*paths, module_relative=True, package=None, setUp=None, tearDown=None, globs=None, optionflags=0, parser=DocTestParser(), encoding=None)

   하나 이상의 텍스트 파일로부터 doctest 테스트를 "unittest.TestSuite"
   로 변환합니다.

   The returned "unittest.TestSuite" is to be run by the unittest
   framework and runs the interactive examples in each file.  If an
   example in any file fails, then the synthesized unit test fails,
   and a "failureException" exception is raised showing the name of
   the file containing the test and a (sometimes approximate) line
   number.  If all the examples in a file are skipped, then the
   synthesized unit test is also marked as skipped.

   검사할 텍스트 파일을 하나 이상의 paths(문자열)로 전달합니다.

   옵션은 키워드 인자로 제공될 수 있습니다:

   선택적 인자 *module_relative*는 *paths*에 있는 파일명을 해석하는 방
   법을 지정합니다:

   * *module_relative*가 "True"(기본값)이면, *paths*의 각 파일명은 OS
     독립적 모듈 상대 경로를 지정합니다. 기본적으로, 이 경로는 호출하
     는 모듈의 디렉터리에 상대적입니다; 그러나 *package* 인자가 지정되
     면, 해당 패키지에 상대적입니다. OS 독립성을 보장하기 위해, 각 파
     일명은 "/" 문자를 사용하여 경로 세그먼트를 분리해야 하며, 절대 경
     로일 수 없습니다 (즉, "/"로 시작할 수 없습니다).

   * *module_relative*가 "False"이면, *paths*의 각 파일명은 OS 특정 경
     로를 지정합니다. 경로는 절대나 상대일 수 있습니다; 상대 경로는 현
     재 작업 디렉터리를 기준으로 해석됩니다.

   선택적 인자 *package*는 디렉터리가 *paths*의 모듈 상대 파일명의 기
   본 디렉터리로 사용될 파이썬 패키지나 파이썬 패키지의 이름입니다. 패
   키지를 지정하지 않으면, 호출하는 모듈의 디렉터리가 모듈 상대 파일명
   의 기본 디렉터리로 사용됩니다. *module_relative*가 "False"일 때
   *package*를 지정하는 것은 에러입니다.

   Optional argument *setUp* specifies a set-up function for the test
   suite. This is called before running the tests in each file.  The
   *setUp* function will be passed a "DocTest" object.  The *setUp*
   function can access the test globals as the "globs" attribute of
   the test passed.

   Optional argument *tearDown* specifies a tear-down function for the
   test suite.  This is called after running the tests in each file.
   The *tearDown* function will be passed a "DocTest" object.  The
   *tearDown* function can access the test globals as the "globs"
   attribute of the test passed.

   선택적 인자 *globs*는 테스트의 초기 전역 변수를 포함하는 딕셔너리입
   니다. 이 딕셔너리의 새 사본이 테스트마다 만들어집니다. 기본적으로,
   *globs*는 새로운 빈 딕셔너리입니다.

   선택적 인자 *optionflags*는 테스트에 대한 기본 doctest 옵션을 지정
   하는데, 개별 옵션 플래그를 함께 OR 해서 만들어집니다. 옵션 플래그
   절을 참조하십시오. 보고(reporting) 옵션을 설정하는 더 좋은 방법은
   아래 함수 "set_unittest_reportflags()"를 참조하십시오.

   선택적 인자 *parser*는 파일에서 테스트를 추출하는 데 사용할
   "DocTestParser"(또는 서브 클래스)를 지정합니다. 기본값은 일반 파서(
   즉, "DocTestParser()")입니다.

   선택적 인자 *encoding*은 파일을 유니코드로 변환하는 데 사용할 인코
   딩을 지정합니다.

   전역 "__file__"이 "DocFileSuite()"를 사용하여 텍스트 파일에서 로드
   된 doctest에 제공된 전역에 추가됩니다.

doctest.DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, setUp=None, tearDown=None, optionflags=0, checker=None)

   모듈에 대한 doctest 테스트를 "unittest.TestSuite"로 변환합니다.

   The returned "unittest.TestSuite" is to be run by the unittest
   framework and runs each doctest in the module. Each docstring is
   run as a separate unit test. If any of the doctests fail, then the
   synthesized unit test fails, and a
   "unittest.TestCase.failureException" exception is raised showing
   the name of the file containing the test and a (sometimes
   approximate) line number.  If all the examples in a docstring are
   skipped, then the

   선택적 인자 *module*은 테스트할 모듈을 제공합니다. 모듈 객체나 (점
   으로 구분될 수 있는) 모듈 이름일 수 있습니다. 지정하지 않으면, 이
   함수를 호출하는 모듈이 사용됩니다.

   Optional argument *globs* is a dictionary containing the initial
   global variables for the tests.  A new copy of this dictionary is
   created for each test.  By default, *globs* is the module's
   "__dict__".

   선택적 인자 *extraglobs*는 *globs*에 병합되는 전역 변수의 추가 집합
   을 지정합니다. 기본적으로, 추가 전역 변수는 사용되지 않습니다.

   선택적 인자 *test_finder*는 모듈에서 doctest를 추출하는 데 사용되는
   "DocTestFinder" 객체(또는 드롭 인 대체)입니다.

   Optional arguments *setUp*, *tearDown*, and *optionflags* are the
   same as for function "DocFileSuite()" above, but they are called
   for each docstring.

   이 함수는 "testmod()"와 같은 검색 기법을 사용합니다.

   버전 3.5에서 변경: *module*에 독스트링이 없으면 "DocTestSuite()"는
   "ValueError"를 발생시키는 대신 빈 "unittest.TestSuite"를 반환합니다
   .

수면 아래에서, "DocTestSuite()"는 "doctest.DocTestCase" 인스턴스에서
"unittest.TestSuite"를 만들고, "DocTestCase"는 "unittest.TestCase"의
서브 클래스입니다. "DocTestCase"는 여기에서 설명되지는 않지만 (내부 세
부 사항입니다), 그것의 코드를 살펴보면 "unittest" 통합의 정확한 세부
사항에 대한 질문에 대한 답을 얻을 수 있습니다.

마찬가지로, "DocFileSuite()"는 "doctest.DocFileCase" 인스턴스에서
"unittest.TestSuite"를 만들고, "DocFileCase"는 "DocTestCase"의 서브 클
래스입니다.

So both ways of creating a "unittest.TestSuite" run instances of
"DocTestCase".  This is important for a subtle reason: when you run
"doctest" functions yourself, you can control the "doctest" options in
use directly, by passing option flags to "doctest" functions.
However, if you're writing a "unittest" framework, "unittest"
ultimately controls when and how tests get run.  The framework author
typically wants to control "doctest" reporting options (perhaps, e.g.,
specified by command line options), but there's no way to pass options
through "unittest" to "doctest" test runners.

For this reason, "doctest" also supports a notion of "doctest"
reporting flags specific to "unittest" support, via this function:

doctest.set_unittest_reportflags(flags)

   사용할 "doctest" 보고 플래그를 설정합니다.

   인자 *flags*는 옵션 플래그의 비트별 OR를 취합니다. 옵션 플래그 절을
   참조하십시오. "보고 플래그"만 사용할 수 있습니다.

   This is a module-global setting, and affects all future doctests
   run by module "unittest":  the "runTest()" method of "DocTestCase"
   looks at the option flags specified for the test case when the
   "DocTestCase" instance was constructed.  If no reporting flags were
   specified (which is the typical and expected case), "doctest"'s
   "unittest" reporting flags are bitwise ORed into the option flags,
   and the option flags so augmented are passed to the "DocTestRunner"
   instance created to run the doctest.  If any reporting flags were
   specified when the "DocTestCase" instance was constructed,
   "doctest"'s "unittest" reporting flags are ignored.

   함수가 호출되기 전에 유효했던 "unittest" 보고 플래그의 값이 함수에
   의해 반환됩니다.


고급 API
========

기본 API는 doctest를 사용하기 쉽게 하기 위한 간단한 래퍼입니다. 그것은
매우 유연하며, 대부분 사용자의 요구를 충족시켜야 합니다; 그러나, 테스
팅에 대한 세밀한 제어가 필요하거나, doctest의 기능을 확장하려면, 고급
API를 사용해야 합니다.

고급 API는 doctest 케이스에서 추출한 대화식 예제를 저장하는 데 사용되
는 두 개의 컨테이너 클래스를 중심으로 돌아갑니다:

* "Example": 예상 출력과 쌍을 이루는 단일 파이썬 *문장*.

* "DocTest": 일반적으로 단일 독스트링이나 텍스트 파일에서 추출된
  "Example"의 모음.

doctest 예제를 찾고, 구문 분석하고, 실행하고, 검사하기 위해 추가 처리
클래스가 정의됩니다:

* "DocTestFinder": 주어진 모듈에서 모든 독스트링을 찾고,
  "DocTestParser"를 사용하여 대화식 예제가 들어있는 모든 독스트링에서
  "DocTest"를 만듭니다.

* "DocTestParser": 문자열(가령 객체의 독스트링)에서 "DocTest" 객체를
  만듭니다.

* "DocTestRunner": "DocTest"에 있는 예제를 실행하고, "OutputChecker"를
  사용하여 출력을 확인합니다.

* "OutputChecker": doctest 예제의 실제 출력을 예상 출력과 비교하고, 그
  들이 일치하는지 결정합니다.

이러한 처리 클래스 간의 관계는 다음 도표에 요약되어 있습니다:

   list of:
   +------+                   +---------+
   |module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
   +------+    |        ^     +---------+     |       ^    (printed)
               |        |     | Example |     |       |
               v        |     |   ...   |     v       |
              DocTestParser   | Example |   OutputChecker
                              +---------+


DocTest 객체
------------

class doctest.DocTest(examples, globs, name, filename, lineno, docstring)

   단일 이름 공간에서 실행되어야 하는 doctest 예제의 모음. 생성자 인자
   는 같은 이름의 어트리뷰트를 초기화하는 데 사용됩니다.

   "DocTest"는 다음 어트리뷰트를 정의합니다. 이들은 생성자에 의해 초기
   화되며, 직접 수정하면 안 됩니다.

   examples

      이 테스트가 실행해야 하는 개별 대화형 파이썬 예제를 인코딩하는
      "Example" 객체의 리스트.

   globs

      예제가 실행되어야 하는 이름 공간 (일명 전역). 이름을 값에 매핑하
      는 딕셔너리입니다. 예제가 만든 이름 공간의 모든 변경 사항(가령
      새 변수 바인딩)은 테스트가 실행된 후 "globs"에 반영됩니다.

   name

      "DocTest"를 식별하는 문자열 이름. 일반적으로, 테스트가 추출된 객
      체나 파일의 이름입니다.

   filename

      The name of the file that this "DocTest" was extracted from; or
      "None" if the filename is unknown, or if the "DocTest" was not
      extracted from a file.

   lineno

      이 "DocTest"가 시작되는 "filename" 내의 줄 번호, 또는 줄 번호가
      없으면 "None". 이 줄 번호는 파일의 시작 부분을 기준으로 0에서 시
      작합니다.

   docstring

      테스트가 추출된 문자열, 또는 문자열이 없거나 테스트가 문자열에서
      추출되지 않았으면 "None".


Example 객체
------------

class doctest.Example(source, want, exc_msg=None, lineno=0, indent=0, options=None)

   파이썬 문장과 예상 출력으로 구성된 단일 대화형 예제. 생성자 인자는
   같은 이름의 어트리뷰트를 초기화하는 데 사용됩니다.

   "Example"는 다음 어트리뷰트를 정의합니다. 이들은 생성자에 의해 초기
   화되며, 직접 수정하면 안 됩니다.

   source

      예제의 소스 코드가 포함된 문자열. 이 소스 코드는 단일 파이썬 문
      으로 구성되며 항상 개행으로 끝납니다; 생성자는 필요하면 개행 문
      자를 추가합니다.

   want

      예제의 소스 코드를 실행할 때 (stdout이나 예외 발생 시 트레이스백
      으로부터) 예상되는 출력. "want"는 출력이 예상되지 않으면 빈 문자
      열이고, 그렇지 않으면 개행으로 끝납니다. 생성자는 필요하면 개행
      을 추가합니다.

   exc_msg

      예제가 예외를 생성할 것으로 예상되면, 예제에서 생성된 예외 메시
      지; 또는 예외를 생성할 것으로 예상되지 않으면 "None". 이 예외 메
      시지는 "traceback.format_exception_only()"의 반환 값과 비교됩니
      다. "exc_msg"는 "None"이 아니면 개행으로 끝납니다. 생성자는 필요
      하면 개행을 추가합니다.

   lineno

      이 예제가 시작하는 이 예제를 포함하는 문자열 내의 줄 번호. 이 줄
      번호는 포함하는 문자열의 시작 부분을 기준으로 0에서 시작합니다.

   indent

      포함하는 문자열 내에서의 이 예제의 들여쓰기, 즉 예제의 첫 번째
      프롬프트 앞에 오는 스페이스 문자의 수.

   options

      옵션 플래그에서 "True"나 "False" 로 매핑하는 딕셔너리, 이 예제의
      기본 옵션을 재정의하는 데 사용됩니다. 이 딕셔너리에 포함되지 않
      은 옵션 플래그는 ("DocTestRunner"의 optionflags에 지정된 대로)
      기본값으로 남습니다. 기본적으로, 아무런 옵션도 설정되지 않습니다
      .


DocTestFinder 객체
------------------

class doctest.DocTestFinder(verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True)

   주어진 객체에 관련된 "DocTest"를 그것의 독스트링과 그것이 포함하는
   객체의 독스트링으로부터 추출하기 위해서 사용되는 처리 클래스.
   "DocTest"는 모듈, 클래스, 함수, 메서드, 정적 메서드, 클래스 메서드
   및 프로퍼티에서 추출할 수 있습니다.

   선택적 인자 *verbose*는 파인더가 검색한 객체를 표시하는 데 사용될
   수 있습니다. 기본값은 "False" (출력 없음)입니다.

   선택적 인자 *parser*는 독스트링에서 doctest를 추출하는 데 사용되는
   "DocTestParser" 객체 (또는 드롭 인 대체)를 지정합니다.

   선택적 인자 *recurse*가 거짓이면, "DocTestFinder.find()"는 오직 주
   어진 객체만을 검사 할 뿐, 포함된 객체는 검사하지 않습니다.

   선택적 인자 *exclude_empty*가 거짓이면, "DocTestFinder.find()"는 빈
   독스트링을 가진 객체에 대한 테스트를 포함합니다.

   "DocTestFinder"는 다음 메서드를 정의합니다:

   find(obj[, name][, module][, globs][, extraglobs])

      *obj*의 독스트링이나 포함된 객체의 독스트링으로 정의된 "DocTest"
      의 리스트를 반환합니다.

      선택적 인자 *name*은 객체의 이름을 지정합니다. 이 이름은 반환된
      "DocTest"의 이름을 구성하는 데 사용됩니다. *name*이 지정되지 않
      으면, "obj.__name__"이 사용됩니다.

      선택적 매개 변수 *module*은 주어진 객체를 포함하는 모듈입니다.
      모듈이 지정되지 않거나 "None"이면, 테스트 파인더는 자동으로 올바
      른 모듈을 판별하려고 시도합니다. 객체의 모듈은 다음과 같이 사용
      됩니다:

      * *globs*가 지정되지 않으면, 기본 이름 공간으로.

      * DocTestFinder가 다른 모듈에서 임포트 된 객체에서 DocTest를 추
        출하지 못하도록 하려고. (*module*이 아닌 다른 모듈을 가진 포함
        된 객체는 무시됩니다.)

      * 객체를 포함하는 파일의 이름을 찾으려고.

      * 해당 파일 내에서 객체의 줄 번호를 찾는 데 도움이 됩니다.

      *module*이 "False"면, 모듈을 찾으려고 시도하지 않습니다. 이것은
      눈에 띄지 않는데, 대부분 doctest 자체를 테스트할 때 사용합니다:
      *module*이 "False"이거나, "None"이지만 자동으로 찾을 수 없으면,
      모든 객체는 (존재하지 않는) 모듈에 속한 것으로 간주하므로, 포함
      된 모든 객체에서 (재귀적으로) doctest를 검색합니다.

      The globals for each "DocTest" is formed by combining *globs*
      and *extraglobs* (bindings in *extraglobs* override bindings in
      *globs*).  A new shallow copy of the globals dictionary is
      created for each "DocTest". If *globs* is not specified, then it
      defaults to the module's "__dict__", if specified, or "{}"
      otherwise. If *extraglobs* is not specified, then it defaults to
      "{}".


DocTestParser 객체
------------------

class doctest.DocTestParser

   문자열에서 대화형 예제를 추출하고, 이를 사용하여 "DocTest" 객체를
   만드는 데 사용되는 처리 클래스.

   "DocTestParser"는 다음 메서드를 정의합니다:

   get_doctest(string, globs, name, filename, lineno)

      주어진 문자열에서 모든 doctest 예제를 추출하고, 이를 "DocTest"
      객체로 모읍니다.

      *globs*, *name*, *filename*, and *lineno* are attributes for the
      new "DocTest" object.  See the documentation for "DocTest" for
      more information.

   get_examples(string, name='<string>')

      주어진 문자열에서 모든 doctest 예제를 추출하고, 이를 "Example"
      객체의 리스트로 반환합니다. 줄 번호는 0부터 시작합니다. 선택적
      인자 *name*은, 이 문자열을 식별하는 이름이며, 에러 메시지에만 사
      용됩니다.

   parse(string, name='<string>')

      Divide the given string into examples and intervening text, and
      return them as a list of alternating "Example"s and strings.
      Line numbers for the "Example"s are 0-based.  The optional
      argument *name* is a name identifying this string, and is only
      used for error messages.


TestResults 객체
----------------

class doctest.TestResults(failed, attempted)

   failed

      Number of failed tests.

   attempted

      Number of attempted tests.

   skipped

      Number of skipped tests.

      Added in version 3.13.


DocTestRunner 객체
------------------

class doctest.DocTestRunner(checker=None, verbose=None, optionflags=0)

   "DocTest"에 있는 대화형 예제를 실행하고 검증하는 데 사용되는 처리
   클래스.

   The comparison between expected outputs and actual outputs is done
   by an "OutputChecker".  This comparison may be customized with a
   number of option flags; see section 옵션 플래그 for more
   information.  If the option flags are insufficient, then the
   comparison may also be customized by passing a subclass of
   "OutputChecker" to the constructor.

   테스트 실행기의 디스플레이 출력은 두 가지 방법으로 제어할 수 있습니
   다. 첫째, 출력 함수를 "run()"로 전달할 수 있습니다; 이 함수는 표시
   되어야 하는 문자열로 호출됩니다. 기본값은 "sys.stdout.write"입니다.
   출력을 캡처하는 것으로 충분하지 않으면, DocTestRunner를 서브 클래싱
   하고 "report_start()", "report_success()",
   "report_unexpected_exception()" 및 "report_failure()" 메서드를 재정
   의하여 디스플레이 출력을 사용자 정의할 수 있습니다.

   선택적 키워드 인자 *checker*는 예상 출력을 doctest 예제의 실제 출력
   과 비교하는 데 사용되는 "OutputChecker" 객체(또는 드롭 인 대체)를
   지정합니다.

   선택적 키워드 인자 *verbose*는 "DocTestRunner"의 상세도를 제어합니
   다. *verbose*가 "True"이면, 실행될 때 각 예제에 대한 정보가 인쇄됩
   니다. *verbose*가 "False"이면, 실패만 인쇄됩니다. *verbose*가 지정
   되지 않거나 "None"이면, 명령 줄 스위치 "-v"가 사용될 때만 상세 출력
   이 사용됩니다.

   선택적 키워드 인자 *optionflags*는 테스트 실행기가 예상 출력을 실제
   출력과 비교하는 방법과 실패를 표시하는 방법을 제어하는 데 사용할 수
   있습니다. 자세한 내용은 옵션 플래그 절을 참조하십시오.

   The test runner accumulates statistics. The aggregated number of
   attempted, failed and skipped examples is also available via the
   "tries", "failures" and "skips" attributes. The "run()" and
   "summarize()" methods return a "TestResults" instance.

   "DocTestRunner"는 다음 메서드를 정의합니다:

   report_start(out, test, example)

      테스트 러너가 주어진 예제를 처리하려고 한다고 보고합니다. 이 메
      서드는 "DocTestRunner"의 서브 클래스가 출력을 사용자 정의할 수
      있도록 제공됩니다; 직접 호출해서는 안 됩니다.

      *example* is the example about to be processed.  *test* is the
      test containing *example*.  *out* is the output function that
      was passed to "DocTestRunner.run()".

   report_success(out, test, example, got)

      주어진 예제가 성공적으로 실행되었음을 보고합니다. 이 메서드는
      "DocTestRunner"의 서브 클래스가 출력을 사용자 정의할 수 있도록
      제공됩니다; 직접 호출해서는 안 됩니다.

      *example*은 처리될 예제입니다. *got*은 예제의 실제 출력입니다.
      *test*는 *example*을 포함하는 테스트입니다. *out*은
      "DocTestRunner.run()"에 전달된 출력 함수입니다.

   report_failure(out, test, example, got)

      주어진 예제가 실패했음을 보고합니다. 이 메서드는 "DocTestRunner"
      의 서브 클래스가 출력을 사용자 정의할 수 있도록 제공됩니다; 직접
      호출해서는 안 됩니다.

      *example*은 처리될 예제입니다. *got*은 예제의 실제 출력입니다.
      *test*는 *example*을 포함하는 테스트입니다. *out*은
      "DocTestRunner.run()"에 전달된 출력 함수입니다.

   report_unexpected_exception(out, test, example, exc_info)

      주어진 예제가 예기치 않은 예외를 발생시켰다고 보고합니다. 이 메
      서드는 "DocTestRunner"의 서브 클래스가 출력을 사용자 정의할 수
      있도록 제공됩니다; 직접 호출해서는 안 됩니다.

      *example*은 처리될 예제입니다. *exc_info*는 예기치 않은 예외에
      대한 정보를 포함하는 튜플입니다 ("sys.exc_info()"에 의해 반환되
      는 것). *test*는 *example*을 포함하는 테스트입니다. *out*은
      "DocTestRunner.run()"에 전달된 출력 함수입니다.

   run(test, compileflags=None, out=None, clear_globs=True)

      *test*("DocTest" 객체)에 있는 예제를 실행하고, 출력 함수 *out*을
      사용하여 결과를 표시합니다. "TestResults" 인스턴스를 반환합니다.

      예제는 이름 공간 "test.globs"에서 실행됩니다. *clear_globs*가 참
      (기본값)이면, 가비지 수집을 돕기 위해 테스트가 실행된 후 이 이름
      공간이 지워집니다. 테스트가 완료된 후에 이름 공간을 검사하려면
      *clear_globs=False*를 사용하십시오.

      *compileflags*는 예제를 실행할 때 파이썬 컴파일러에서 사용해야
      하는 플래그 집합을 제공합니다. 지정되지 않으면, *globs*에 적용되
      는 퓨처-임포트 플래그 집합이 기본값이 됩니다.

      각 예제의 출력은 "DocTestRunner"의 출력 검사기를 사용하여 검사되
      며, 결과는 "DocTestRunner.report_*()" 메서드로 포맷됩니다.

   summarize(verbose=None)

      이 DocTestRunner가 실행 한 모든 테스트 케이스의 요약을 인쇄하고,
      "TestResults" 인스턴스를 반환합니다.

      선택적 *verbose* 인자는 요약이 얼마나 상세할지를 제어합니다. 상
      세도가 지정되지 않으면, "DocTestRunner"의 상세도가 사용됩니다.

   "DocTestParser"는 다음과 같은 어트리뷰트를 갖습니다:

   tries

      Number of attempted examples.

   failures

      Number of failed examples.

   skips

      Number of skipped examples.

      Added in version 3.13.


OutputChecker 객체
------------------

class doctest.OutputChecker

   doctest 예제의 실제 출력이 예상 출력과 일치하는지를 확인하는 데 사
   용되는 클래스. "OutputChecker"는 두 가지 메서드를 정의합니다:
   "check_output()"은 주어진 출력 쌍을 비교하고 일치하면 "True"를 반환
   합니다; "output_difference()"는 두 출력 간의 차이를 설명하는 문자열
   을 반환합니다.

   "OutputChecker"는 다음 메서드를 정의합니다:

   check_output(want, got, optionflags)

      예제의 실제 출력(*got*)이 예상 출력(*want*)과 일치할 때만 "True"
      를 반환합니다. 이 문자열은 같으면 항상 일치하는 것으로 간주합니
      다; 그러나 테스트 실행기가 사용하는 옵션 플래그에 따라 몇 가지
      정확하지 않은 일치 유형도 가능합니다. 옵션 플래그에 대한 자세한
      정보는 옵션 플래그 절을 참조하십시오.

   output_difference(example, got, optionflags)

      주어진 예제(*example*)에 대한 예상 출력과 실제 출력(*got*)의 차
      이를 설명하는 문자열을 반환합니다. *optionflags*는 *want*와
      *got*을 비교하는 데 사용되는 옵션 플래그 집합입니다.


디버깅
======

Doctest는 doctest 예제를 디버깅하기 위한 몇 가지 메커니즘을 제공합니다
:

* 몇몇 함수는 doctest를 파이썬 디버거 "pdb"에서 실행할 수 있는 실행 가
  능한 파이썬 프로그램으로 변환합니다.

* "DebugRunner" 클래스는 첫 번째 실패한 예제에 대한 예외를 발생시키는
  "DocTestRunner"의 서브 클래스이며 해당 예제에 대한 정보가 들어 있습
  니다. 이 정보는 예제에서 사후 디버깅을 수행하는 데 사용될 수 있습니
  다.

* "DocTestSuite()"에 의해 생성된 "unittest" 케이스는
  "unittest.TestCase"에 의해 정의된 "debug()" 메서드를 지원합니다.

* doctest 예제에 "pdb.set_trace()"에 대한 호출을 추가 할 수 있습니다.
  그러면 해당하는 줄이 실행될 때 파이썬 디버거로 들어갑니다. 그런 다음
  변수의 현재 값을 검사하는 등의 일을 할 수 있습니다. 예를 들어,
  "a.py"가 다음과 같은 모듈 독스트링을 포함한다고 가정합시다:

     """
     >>> def f(x):
     ...     g(x*2)
     >>> def g(x):
     ...     print(x+3)
     ...     import pdb; pdb.set_trace()
     >>> f(3)
     9
     """

  그러면 대화형 파이썬 세션은 이런 식이 됩니다:

     >>> import a, doctest
     >>> doctest.testmod(a)
     --Return--
     > <doctest a[1]>(3)g()->None
     -> import pdb; pdb.set_trace()
     (Pdb) list
       1     def g(x):
       2         print(x+3)
       3  ->     import pdb; pdb.set_trace()
     [EOF]
     (Pdb) p x
     6
     (Pdb) step
     --Return--
     > <doctest a[0]>(2)f()->None
     -> g(x*2)
     (Pdb) list
       1     def f(x):
       2  ->     g(x*2)
     [EOF]
     (Pdb) p x
     3
     (Pdb) step
     --Return--
     > <doctest a[2]>(1)?()->None
     -> f(3)
     (Pdb) cont
     (0, 3)
     >>>

Doctest를 파이썬 코드로 변환하고, 디버거에서 합성 코드를 실행할 수 있
는 함수들:

doctest.script_from_examples(s)

   예제가 있는 텍스트를 스크립트로 변환합니다.

   인자 *s*는 doctest 예제를 포함하는 문자열입니다. 문자열은 파이썬 스
   크립트로 변환됩니다. 여기서 *s*의 doctest 예제는 일반 코드로 변환되
   고, 나머지는 파이썬 주석으로 변환됩니다. 생성된 스크립트는 문자열로
   반환됩니다. 예를 들어,

      import doctest
      print(doctest.script_from_examples(r"""
          Set x and y to 1 and 2.
          >>> x, y = 1, 2

          Print their sum:
          >>> print(x+y)
          3
      """))

   는 다음과 같이 출력합니다:

      # Set x and y to 1 and 2.
      x, y = 1, 2
      #
      # Print their sum:
      print(x+y)
      # Expected:
      ## 3

   이 함수는 다른 함수(아래 참조)에서 내부적으로 사용되지만, 대화형 파
   이썬 세션을 파이썬 스크립트로 변환하려고 할 때도 유용합니다.

doctest.testsource(module, name)

   객체에 대한 doctest를 스크립트로 변환합니다.

   인자 *module*은 doctest가 관심 대상인 객체를 포함하는 모듈 객체나
   모듈의 점으로 구분된 이름입니다. 인자 *name*은 doctest가 관심 대상
   인 객체의 (모듈 내에서의) 이름입니다. 결과는 위의
   "script_from_examples()"에서 설명한 대로 파이썬 스크립트로 변환된
   객체의 독스트링을 포함하는 문자열입니다. 예를 들어, 모듈 "a.py"에
   최상위 함수 "f()"가 포함되었다면,

      import a, doctest
      print(doctest.testsource(a, "a.f"))

   는 doctest가 코드로 변환되고 나머지는 주석으로 배치된, 함수 "f()"의
   독스트링의 스크립트 버전을 인쇄합니다.

doctest.debug(module, name, pm=False)

   객체의 doctest를 디버그합니다.

   *module*과 *name* 인자는 위의 함수 "testsource()"와 같습니다. 명명
   된 객체의 독스트링에 대한 합성된 파이썬 스크립트가 임시 파일에 기록
   되고, 그 파일을 파이썬 디버거 "pdb"의 제어하에 실행합니다.

   "module.__dict__"의 얕은 사본이 지역과 전역 실행 컨텍스트 모두에 사
   용됩니다.

   선택적 인자 *pm*은 사후 디버깅이 사용되는지를 제어합니다. *pm*이 참
   값이면, 스크립트 파일은 직접 실행되고, 처리되지 않은 예외를 발생시
   켜 스크립트가 종료될 때만 디버거가 개입합니다. 그럴 때, 사후 디버깅
   이 "pdb.post_mortem()"를 통해 호출되어, 처리되지 않은 예외로부터 온
   트레이스백 객체를 전달합니다. *pm*이 지정되지 않았거나 거짓이면, 스
   크립트는 적절한 "exec()" 호출을 "pdb.run()"에 전달하여 시작부터 디
   버거에서 실행됩니다.

doctest.debug_src(src, pm=False, globs=None)

   문자열에 있는 doctest를 디버그합니다.

   doctest 예제를 포함하는 문자열이 *src* 인자를 통해 직접 지정된다는
   점을 제외하면, 위의 함수 "debug()"과 같습니다.

   선택적 인자 *pm*은 위의 함수 "debug()"에서와 같은 의미를 가집니다.

   선택적 인자 *globs*는 지역과 전역 실행 컨텍스트 모두에 사용할 딕셔
   너리를 제공합니다. 지정되지 않거나 "None"이면, 빈 딕셔너리가 사용됩
   니다. 지정되면, 딕셔너리의 얕은 사본이 사용됩니다.

"DebugRunner" 클래스와 이 클래스가 발생시킬 수 있는 특별한 예외는 주로
테스트 프레임워크 작성자가 관심을 가지며, 여기에서는 대략적으로만 다룰
예정입니다. 자세한 내용은 소스 코드, 특히 "DebugRunner"의 독스트링
(doctest입니다!)을 참조하십시오:

class doctest.DebugRunner(checker=None, verbose=None, optionflags=0)

   실패를 만나자마자 예외를 발생시키는 "DocTestRunner"의 서브 클래스.
   예기치 않은 예외가 발생하면, 테스트, 예제 및 원래 예외가 포함된
   "UnexpectedException" 예외가 발생합니다. 출력이 일치하지 않으면, 테
   스트, 예제 및 실제 출력을 포함하는 "DocTestFailure" 예외가 발생합니
   다.

   생성자 매개 변수와 메서드에 대한 자세한 내용은 고급 API 절의
   "DocTestRunner" 설명서를 참조하십시오.

"DebugRunner" 인스턴스가 발생시킬 수 있는 두 가지 예외가 있습니다:

exception doctest.DocTestFailure(test, example, got)

   doctest 예제의 실제 출력이 예상 출력과 일치하지 않는다는 것을 알리
   기 위해 "DocTestRunner"가 발생시키는 예외. 생성자 인자는 같은 이름
   의 어트리뷰트를 초기화하는 데 사용됩니다.

"DocTestFailure"는 다음 어트리뷰트를 정의합니다:

DocTestFailure.test

   예제가 실패했을 때 실행 중이던 "DocTest" 객체.

DocTestFailure.example

   실패한 "Example".

DocTestFailure.got

   예제의 실제 출력.

exception doctest.UnexpectedException(test, example, exc_info)

   doctest 예제가 예기치 않은 예외를 발생시켰음을 알리기 위해
   "DocTestRunner"가 발생시키는 예외. 생성자 인자는 같은 이름의 어트리
   뷰트를 초기화하는 데 사용됩니다.

"UnexpectedException"는 다음 어트리뷰트를 정의합니다:

UnexpectedException.test

   예제가 실패했을 때 실행 중이던 "DocTest" 객체.

UnexpectedException.example

   실패한 "Example".

UnexpectedException.exc_info

   "sys.exc_info()"에 의해 반환되는 것과 같은, 예기치 않은 예외에 대한
   정보가 포함된 튜플.


맺음말
======

소개에서 언급했듯이, "doctest"는 다음 세 가지 주요 용도로 성장했습니다
:

1. 독스트링에 있는 예제 검사.

2. 회귀 테스트.

3. 실행 가능한 문서/문학적(literate) 테스트.

이러한 용도들은 다른 요구 사항을 가지며, 이를 구별하는 것이 중요합니다
. 특히, 모호한 테스트 케이스로 독스트링을 채우는 것은 나쁜 설명서를 만
듭니다.

독스트링을 작성할 때, 독스트링 예제를 주의해서 선택하십시오. 여기에는
배울 필요가 있는 기술이 있습니다---처음에는 자연스럽지 않을 수도 있습
니다. 예제는 설명서에 진짜 가치를 부여해야 합니다. 좋은 예제는 종종 많
은 단어의 가치가 있습니다. 주의 깊게 작업 된다면, 예제는 사용자에게 매
우 가치 있을 것이며, 몇 년이 지나고 변함에 따라 여러 번 수집하는 데 드
는 시간을 갚을 것입니다. 제 "doctest" 예제 중 하나가 "해가 없는" 변경
후에 얼마나 자주 작동을 멈추는지 지금도 놀라울 뿐입니다.

Doctest는 회귀 테스트를 위한 훌륭한 도구도 제공합니다. 특히 설명 텍스
트를 생략하지 않는다면 더욱더 그렇습니다. 설명과 예제를 번갈아 보여줌
으로써, 실제로 무엇이 왜 테스트 되는지를 추적하기가 훨씬 쉬워집니다.
테스트가 실패할 때, 좋은 설명은 문제가 무엇인지, 어떻게 고쳐야 하는지
를 쉽게 파악할 수 있게 해줍니다. 코드 기반 테스트에 광범위한 주석을 쓸
수는 있는 것은 사실이지만, 그렇게 하는 프로그래머는 거의 없습니다. 많
은 사람이 doctest 접근법을 사용하는 것이 훨씬 더 명확한 테스트를 유도
한다는 것을 발견했습니다. 어쩌면 단순히 doctest가 설명을 작성하는 것을
코드를 작성하는 것보다 조금 더 쉽게 만들고, 코드에 주석을 쓰는 것이 조
금 더 어렵기 때문일 것입니다. 저는 단지 그것보다는 더 깊이 들어간다고
생각합니다: doctest 기반 테스트를 작성할 때의 자연스러운 태도는 소프트
웨어의 미세한 포인트를 설명하고 그것을 예제로 보여주는 것입니다. 이것
은 자연스럽게 가장 간단한 기능으로 시작하고, 복잡하고 지엽적인 경우까
지 논리적으로 진행되는 테스트 파일로 이어집니다. 무작위로 보이는 격리
된 기능 조각을 테스트하는 격리된 함수들의 모음 대신에, 일관된 내러티브
가 얻어집니다. 이것은 다른 태도이며, 테스트와 설명의 구별을 모호하게
하면서 다른 결과를 낳습니다.

회귀 테스트는 전용 객체나 파일로 제한하는 것이 가장 좋습니다. 테스트
구성을 위한 몇 가지 옵션이 있습니다.:

* 대화형 예제로 테스트 케이스가 들어있는 텍스트 파일을 작성하고,
  "testfile()"이나 "DocFileSuite()"를 사용하여 파일을 테스트하십시오.
  doctest를 처음부터 사용하도록 고안된 새로운 프로젝트에서 가장 쉬운
  방법이지만, 이 방법을 권장합니다.

* 명명된 주제에 대한 테스트 케이스를 포함하는 단일 독스트링으로 구성된
  "_regrtest_topic"이라는 함수를 정의하십시오. 이 함수들은 모듈과 같은
  파일에 포함되거나 별도의 테스트 파일로 분리될 수 있습니다.

* Define a "__test__" dictionary mapping from regression test topics
  to docstrings containing test cases.

테스트를 모듈에 배치할 때, 모듈 자체가 테스트 실행기가 될 수 있습니다.
테스트가 실패할 때, 문제를 디버깅하는 동안 실패한 doctest 만 다시 실행
하도록 테스트 실행기를 조정할 수 있습니다. 다음은 그러한 테스트 실행기
의 최소 예입니다:

   if __name__ == '__main__':
       import doctest
       flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST
       if len(sys.argv) > 1:
           name = sys.argv[1]
           if name in globals():
               obj = globals()[name]
           else:
               obj = __test__[name]
           doctest.run_docstring_examples(obj, globals(), name=name,
                                          optionflags=flags)
       else:
           fail, total = doctest.testmod(optionflags=flags)
           print(f"{fail} failures out of {total} tests")

-[ 각주 ]-

[1] 예상 출력과 예외를 모두 포함하는 예제는 지원되지 않습니다. 어디에
    서 하나가 끝나고 다른 하나가 시작되는지 추측하는 것은 너무 에러가
    발생하기 쉽고, 이것은 또한 혼란스러운 테스트를 만들게 됩니다.
