doctest — Проверка интерактивных примеров Python

Какие строки документации просматриваются?

Поиск выполняется в строке документации модуля, а также во всех строках документации функций, классов и методов. Объекты, импортированные в модуль, не просматриваются.

Кроме того, бывают случаи, когда тесты должны быть частью модуля, но не частью текста справки, а значит, тесты не следует включать в строку документации. Doctest ищет переменную уровня модуля с именем __test__ и использует её для поиска других тестов. Если M.__test__ существует, она должна быть словарём, и каждая запись в нём сопоставляет строковое имя с объектом-функцией, объектом-классом или строкой. Просматриваются строки документации функций и классов, найденных через M.__test__, а строки обрабатываются как строки документации. В выводе ключ K из M.__test__ отображается под именем M.__test__.K.

Например, поместите этот блок кода в начало example.py:

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

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

Значение example.__test__["numbers"] будет обработано как строка документации, и все содержащиеся в ней тесты будут выполнены. Важно отметить, что значением может быть функция, объект-класс или модуль; в этом случае doctest рекурсивно просматривает их строки документации, в которых затем ищет тесты.

Все найденные классы аналогичным образом просматриваются рекурсивно, чтобы проверить строки документации содержащихся в них методов и вложенных классов.

Как распознаются примеры в строках документации?

В большинстве случаев копирование интерактивного сеанса консоли с последующей вставкой работает без проблем, но doctest не пытается точно эмулировать какую-либо конкретную оболочку Python.

>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
...     print("yes")
... else:
...     print("no")
...     print("NO")
...     print("NO!!!")
...
no
NO
NO!!!
>>>

Ожидаемый вывод должен непосредственно следовать за последней строкой '>>> ' или '... ', содержащей код; ожидаемый вывод (если он есть) продолжается до следующей строки '>>> ' или строки, состоящей только из пробельных символов.

Подробности:

• Ожидаемый вывод не может содержать строку, состоящую только из пробельных символов, поскольку такая строка обозначает конец ожидаемого вывода. Если ожидаемый вывод содержит пустую строку, укажите <BLANKLINE> в примере doctest в каждом месте, где ожидается пустая строка.
• Все символы табуляции преобразуются в пробелы с шагом табуляции в 8 столбцов. Табуляции в выводе проверяемого кода не изменяются. Поскольку все символы табуляции в образце вывода преобразуются, если вывод кода содержит символы табуляции, doctest может пройти только при включённом параметре NORMALIZE_WHITESPACE или директиве. В качестве альтернативы тест можно переписать так, чтобы он перехватывал вывод и сравнивал его с ожидаемым значением. Такой способ обработки табуляций в исходном тексте был выбран методом проб и ошибок и оказался наименее подверженным ошибкам. Для обработки табуляций можно использовать другой алгоритм, написав собственный класс DocTestParser.
• Вывод в stdout перехватывается, но вывод в stderr — нет (трассировки исключений перехватываются другим способом).

• Если в интерактивном сеансе вы продолжаете строку с помощью обратной косой черты или используете её по какой-либо другой причине, следует использовать необработанную строку документации, которая сохранит обратные косые черты именно в том виде, в каком вы их ввели:

  >>> 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, чтобы запуск тестов не изменял настоящие глобальные переменные модуля и чтобы один тест в 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 пройдёт, если будет вызвано исключение ValueError с указанной детализацией list.remove(x): x not in list.

Ожидаемый вывод исключения должен начинаться с заголовка трассировки стека, которым может быть одна из следующих двух строк с отступом, совпадающим с отступом первой строки примера:

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. Многоточие в этом примере можно опустить или заменить тремя (или тремястами) запятыми или цифрами либо строкой с отступом из скетча «Летающего цирка Монти Пайтона».

Некоторые подробности достаточно прочитать один раз — запоминать их не нужно:

• Doctest не может определить, получен ли ожидаемый вывод из трассировки исключения или в результате обычной печати. Поэтому, например, пример, ожидающий ValueError: 42 is prime, пройдёт независимо от того, было ли действительно вызвано исключение ValueError или пример просто вывел этот текст трассировки. На практике обычный вывод редко начинается со строки заголовка трассировки, поэтому это не создаёт реальных проблем.
• Каждая строка стека вызовов (если он есть) должна иметь больший отступ, чем первая строка примера, либо начинаться с не буквенно-цифрового символа. Первая строка после заголовка трассировки, имеющая такой же отступ и начинающаяся с буквенно-цифрового символа, считается началом описания исключения. Для настоящих трассировок это работает правильно.
• Если указан параметр doctest IGNORE_EXCEPTION_DETAIL, всё после первого двоеточия, а также сведения о модуле в имени исключения игнорируются.
• Для некоторых исключений SyntaxError интерактивная оболочка опускает строку заголовка трассировки. Но doctest использует её, чтобы отличать исключения от ситуаций, когда исключения нет. Поэтому в редком случае, когда нужно проверить SyntaxError без заголовка трассировки, заголовок трассировки придётся вручную добавить в пример теста.

• Для некоторых исключений Python показывает положение ошибки с помощью маркеров ^ и тильд:

  >>> 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 в разных аспектах регулируется рядом флагов параметров. Символические имена флагов заданы как константы модуля; их можно объединять с помощью операции побитового ИЛИ и передавать различным функциям. Эти имена также можно использовать в директивах doctest и передавать интерфейсу командной строки doctest с помощью параметра -o.

Первая группа параметров задаёт семантику тестов, управляя тем, как doctest определяет, соответствует ли фактический вывод ожидаемому выводу примера:

doctest.DONT_ACCEPT_TRUE_FOR_1

По умолчанию, если блок ожидаемого вывода содержит только 1, фактический блок вывода, содержащий только 1 или только True, считается совпадением; аналогично для 0 и False. Если указан параметр DONT_ACCEPT_TRUE_FOR_1, обе подстановки запрещены. Такое поведение по умолчанию учитывает, что в Python тип возвращаемого значения многих функций изменился с целого числа на логическое значение; doctest, ожидающие в таких случаях вывод «небольшого целого числа», продолжат работать. Вероятно, этот параметр будет удалён, но не раньше чем через несколько лет.

doctest.DONT_ACCEPT_BLANKLINE

По умолчанию, если блок ожидаемого вывода содержит строку, состоящую только из строки <BLANKLINE>, эта строка соответствует пустой строке в фактическом выводе. Поскольку настоящая пустая строка обозначает конец ожидаемого вывода, это единственный способ указать, что ожидается пустая строка. Если указан параметр DONT_ACCEPT_BLANKLINE, такая подстановка запрещена.

doctest.NORMALIZE_WHITESPACE

Если параметр указан, любые последовательности пробельных символов (пробелов и символов новой строки) считаются равными. Любая последовательность пробельных символов в ожидаемом выводе соответствует любой последовательности пробельных символов в фактическом выводе. По умолчанию пробельные символы должны совпадать точно. Параметр NORMALIZE_WHITESPACE особенно полезен, когда строка ожидаемого вывода очень длинная и её нужно перенести на несколько строк в исходном коде.

doctest.ELLIPSIS

Если параметр указан, маркер многоточия (...) в ожидаемом выводе может соответствовать любой подстроке фактического вывода. Это включает подстроки, пересекающие границы строк, и пустые подстроки, поэтому маркер лучше использовать просто. Сложное использование может привести к тем же неожиданностям в духе «ой, совпало слишком многое!», к которым склонен .* в регулярных выражениях.

doctest.IGNORE_EXCEPTION_DETAIL

Если параметр указан, тесты doctest, ожидающие исключения, проходят, если возникает исключение ожидаемого типа, даже когда его подробности (сообщение и полное имя исключения) не совпадают.

Например, пример, ожидающий ValueError: 42, пройдёт, если фактически возникшее исключение — ValueError: 3*14, но не пройдёт, если вместо него возникнет, например, TypeError. Также будет игнорироваться полное имя, указанное перед классом исключения, поскольку оно может различаться в разных реализациях и версиях Python, а также в используемом коде и библиотеках. Поэтому при включённом флаге будут работать все три следующих варианта:

>>> 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

Обратите внимание, что ELLIPSIS также можно использовать, чтобы игнорировать подробности сообщения исключения, однако такой тест всё ещё может завершиться неудачей, если имя модуля отсутствует или не совпадает в точности.

Изменено в версии 3.2: IGNORE_EXCEPTION_DETAIL теперь также игнорирует любые сведения о модуле, содержащем проверяемое исключение.

doctest.SKIP

Если параметр указан, пример вообще не запускается. Это может быть полезно в случаях, когда примеры doctest служат одновременно документацией и тестами: пример нужно включить в документацию, но проверять его не следует. Например, вывод примера может быть случайным или он может зависеть от ресурсов, недоступных тестовому драйверу.

Флаг SKIP также можно использовать для временного «комментирования» примеров.

doctest.COMPARISON_FLAGS

Битовая маска, объединяющая все перечисленные выше флаги сравнения.

Вторая группа параметров управляет тем, как сообщается о неудачных тестах:

doctest.REPORT_UDIFF

Если параметр указан, различия между многострочными ожидаемым и фактическим выводами отображаются в виде унифицированного diff.

doctest.REPORT_CDIFF

Если параметр указан, различия между многострочными ожидаемым и фактическим выводами отображаются в виде контекстного diff.

doctest.REPORT_NDIFF

Если параметр указан, различия вычисляются с помощью difflib.Differ, использующего тот же алгоритм, что и популярная утилита ndiff.py. Это единственный метод, отмечающий различия как между строками, так и внутри них. Например, если в ожидаемом выводе в строке стоит цифра 1, а в фактическом выводе — буква l, вставляется строка с символом-указателем, отмечающим позиции несовпадающих столбцов.

doctest.REPORT_ONLY_FIRST_FAILURE

Если параметр указан, отображается первый неудачный пример в каждом тесте doctest, а вывод для всех остальных примеров подавляется. Это не позволит doctest сообщать о корректных примерах, которые завершаются с ошибкой из-за предыдущих неудач, но может скрыть и некорректные примеры, не связанные с первой ошибкой. Если указан параметр REPORT_ONLY_FIRST_FAILURE, остальные примеры всё равно запускаются и учитываются в общем числе обнаруженных ошибок; подавляется только вывод.

doctest.FAIL_FAST

Если параметр указан, выполнение прекращается после первого неудачного примера, а остальные примеры не запускаются. Таким образом, будет сообщено не более чем об одной ошибке. Этот флаг может быть полезен при отладке, поскольку примеры после первой ошибки даже не выведут отладочную информацию.

doctest.REPORTING_FLAGS

Битовая маска, объединяющая все перечисленные выше флаги отчётности.

Можно также зарегистрировать новые имена флагов параметров, хотя это полезно только в том случае, если вы собираетесь расширять внутренние механизмы doctest с помощью наследования:

doctest.register_optionflag(name)

Создаёт флаг параметра с заданным именем и возвращает его целочисленное значение. register_optionflag() можно использовать при наследовании от OutputChecker или DocTestRunner, чтобы создавать параметры, поддерживаемые вашими подклассами. register_optionflag() всегда следует вызывать следующим образом:

MY_FLAG = register_optionflag('MY_FLAG')

Директивы

Директивы doctest позволяют изменить флаги параметров для отдельного примера. Директивы doctest — это специальные комментарии Python, следующие за исходным кодом примера:

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 требует точного совпадения ожидаемого вывода. Если не совпадает хотя бы один символ, тест завершается неудачей. Это, вероятно, несколько раз вас удивит, пока вы будете разбираться, что именно Python гарантирует и не гарантирует в выводе. Например, при печати множества Python не гарантирует, что его элементы будут выведены в определённом порядке, поэтому такой тест

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

ненадёжен! Один из способов обойти проблему — сделать так:

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

Другой способ — сделать так:

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

Есть и другие варианты, но суть вы поняли.

Ещё одна плохая идея — печатать значения, содержащие адрес объекта, например:

>>> id(1.0)  # certain to fail some of the time
7948648
>>> class C: pass
>>> C()  # the default repr() for instances embeds an address
<C object at 0x00AC18F0>

Директива ELLIPSIS удобно решает проблему в последнем примере:

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

Числа с плавающей точкой также могут немного различаться при выводе на разных платформах, поскольку Python использует системную библиотеку C для некоторых вычислений с плавающей точкой, а качество библиотек C заметно различается.

>>> 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  # utterly safe
0.75

Простые дроби также легче понять, а значит, документация получается лучше.

Объекты DocTest

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

Коллекция примеров doctest, которые следует выполнить в одном пространстве имён. Аргументы конструктора используются для инициализации атрибутов с такими же именами.

DocTest определяет следующие атрибуты. Они инициализируются конструктором, и их не следует изменять напрямую.

examples

Список объектов Example, представляющих отдельные интерактивные примеры Python, которые должен выполнить этот тест.

globs

Пространство имён (то есть глобальные переменные), в котором следует выполнять примеры. Это словарь, сопоставляющий имена значениям. Любые изменения пространства имён, внесённые примерами (например, привязка новых переменных), будут отражены в globs после выполнения теста.

name

Строковое имя, идентифицирующее DocTest. Обычно это имя объекта или файла, из которого был извлечён тест.

filename

Имя файла, из которого был извлечён этот DocTest; или None, если имя файла неизвестно либо если DocTest был извлечён не из файла.

lineno

Номер строки в filename>, с которой начинается этот DocTest, или None, если номер строки недоступен. Нумерация строк начинается с нуля от начала файла.

docstring

Строка, из которой был извлечён тест, или None, если строка недоступна либо если тест был извлечён не из строки.

Объекты Example

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

Отдельный интерактивный пример, состоящий из инструкции Python и ожидаемого результата. Аргументы конструктора используются для инициализации атрибутов с такими же именами.

Example определяет следующие атрибуты. Они инициализируются конструктором, и их не следует изменять напрямую.

source

Строка с исходным кодом примера. Этот исходный код состоит из одной инструкции Python и всегда заканчивается символом новой строки; при необходимости конструктор добавляет символ новой строки.

want

Ожидаемый вывод при выполнении исходного кода примера (из стандартного вывода или трассировка стека в случае исключения). want заканчивается символом новой строки, если только вывод не ожидается — в этом случае это пустая строка. При необходимости конструктор добавляет символ новой строки.

exc_msg

Сообщение об исключении, сформированное примером, если ожидается, что пример вызовет исключение; или None, если исключение не ожидается. Это сообщение об исключении сравнивается с возвращаемым значением traceback.format_exception_only(). exc_msg заканчивается символом новой строки, если только это не None. При необходимости конструктор добавляет символ новой строки.

lineno

Номер строки в содержащей пример строке, с которой начинается пример. Нумерация строк начинается с нуля от начала содержащей его строки.

indent

Отступ примера в содержащей его строке, то есть количество пробелов перед первым приглашением ввода примера.

options

Словарь, сопоставляющий флаги параметров значениям True или False; он используется для переопределения параметров по умолчанию для этого примера. Флаги параметров, отсутствующие в этом словаре, сохраняют значения по умолчанию (заданные параметром DocTestRunner optionflags). По умолчанию параметры не заданы.

Объекты DocTestFinder

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

Класс обработки, используемый для извлечения из строки документации заданного объекта и строк документации содержащихся в нём объектов объектов DocTest, относящихся к этому объекту. Объекты DocTest можно извлекать из модулей, классов, функций, методов, статических методов, методов класса и свойств.

Необязательный аргумент verbose позволяет отображать объекты, проверяемые средством поиска. По умолчанию он равен False (вывод отсутствует).

Необязательный аргумент parser задаёт объект DocTestParser (или его полную замену), используемый для извлечения doctest из строк документации.

Если необязательный аргумент recurse имеет значение false, то DocTestFinder.find() проверит только заданный объект, не проверяя содержащиеся в нём объекты.

Если необязательный аргумент exclude_empty имеет значение false, то DocTestFinder.find() включит тесты для объектов с пустыми строками документации.

DocTestFinder определяет следующий метод:

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

Возвращает список объектов DocTest, определённых строкой документации obj или строками документации любых содержащихся в нём объектов.

Необязательный аргумент name задаёт имя объекта; это имя будет использоваться при построении имён возвращаемых объектов DocTest. Если name не задан, используется obj.__name__.

Необязательный параметр module — это модуль, содержащий заданный объект. Если модуль не задан или равен None, средство поиска тестов попытается автоматически определить нужный модуль. Модуль объекта используется:

• Как пространство имён по умолчанию, если globs не задан.
• Для предотвращения извлечения DocTestFinder объектов DocTest из объектов, импортированных из других модулей. (Содержащиеся объекты, модуль которых отличается от module, игнорируются.)
• Для определения имени файла, содержащего объект.
• Для определения номера строки объекта в его файле.

Если module равен False, попытка найти модуль предприниматься не будет. Это редко используемый параметр, полезный главным образом при тестировании самого doctest: если module равен False или равен None, но не может быть найден автоматически, то все объекты считаются принадлежащими несуществующему модулю, поэтому все содержащиеся объекты будут рекурсивно проверены на наличие doctest.

Глобальные переменные для каждого объекта DocTest формируются путём объединения globs и extraglobs (привязки в extraglobs имеют приоритет над привязками в globs). Для каждого DocTest создаётся новая поверхностная копия словаря глобальных переменных. Если globs не задан, по умолчанию используется __dict__ модуля, если он задан, либо {}. Если extraglobs не задан, по умолчанию используется {}.

Объекты DocTestParser

class doctest.DocTestParser

Класс обработки, используемый для извлечения интерактивных примеров из строки и создания на их основе объекта DocTest.

DocTestParser определяет следующие методы:

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

Извлекает все примеры doctest из заданной строки и собирает их в объект DocTest.

globs, name, filename и lineno — это атрибуты нового объекта DocTest. Дополнительные сведения см. в документации для DocTest.

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

Извлекает все примеры doctest из заданной строки и возвращает их в виде списка объектов Example. Нумерация строк начинается с нуля. Необязательный аргумент name — это имя, идентифицирующее данную строку; оно используется только в сообщениях об ошибках.

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

Разделяет заданную строку на примеры и промежуточный текст и возвращает их в виде списка, в котором чередуются объекты Example и строки. Нумерация строк для объектов Example начинается с нуля. Необязательный аргумент name — это имя, идентифицирующее данную строку; оно используется только в сообщениях об ошибках.

Объекты TestResults

class doctest.TestResults(failed, attempted)

failed

Количество неудачных тестов.

attempted

Количество запущенных тестов.

skipped

Количество пропущенных тестов.

Добавлено в версии 3.13.

Объекты DocTestRunner

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

Класс обработки, используемый для выполнения и проверки интерактивных примеров в объекте DocTest.

Сравнение ожидаемого и фактического вывода выполняется объектом OutputChecker. Это сравнение можно настроить с помощью нескольких флагов параметров; дополнительные сведения см. в разделе Флаги параметров. Если флагов параметров недостаточно, сравнение также можно настроить, передав конструктору подкласс OutputChecker.

Отображаемый тестовым средством вывода можно контролировать двумя способами. Во-первых, функции вывода можно передать в run(); эта функция будет вызвана со строками, которые следует отобразить. По умолчанию используется sys.stdout.write. Если перехвата вывода недостаточно, вывод также можно настроить, создав подкласс DocTestRunner и переопределив методы report_start(), report_success(), report_unexpected_exception() и report_failure().

Необязательный именованный аргумент checker задаёт объект OutputChecker (или его полную замену), используемый для сравнения ожидаемого вывода с фактическим выводом примеров doctest.

Необязательный именованный аргумент verbose управляет подробностью вывода DocTestRunner. Если verbose равен True, при выполнении выводится информация о каждом примере. Если verbose равен False, выводятся только сведения о сбоях. Если verbose не задан или равен None, подробный вывод используется только при наличии переключателя командной строки -v.

Необязательный именованный аргумент optionflags позволяет управлять тем, как средство запуска тестов сравнивает ожидаемый вывод с фактическим и как отображает сведения о сбоях. Дополнительные сведения см. в разделе Флаги параметров.

Средство запуска тестов собирает статистику. Общее число запущенных, неудачных и пропущенных примеров также доступно через атрибуты tries, failures и skips. Методы run() и summarize() возвращают экземпляр TestResults.

DocTestRunner определяет следующие методы:

report_start(out, test, example)

Сообщает, что средство запуска тестов собирается обработать заданный пример. Этот метод предоставлен для того, чтобы подклассы DocTestRunner могли настраивать вывод; его не следует вызывать напрямую.

example — пример, который будет обработан. test — тест, содержащий example. out — функция вывода, переданная в 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 имеет значение true (по умолчанию), это пространство имён будет очищено после выполнения теста, чтобы облегчить сборку мусора. Если после завершения теста вам нужно проверить пространство имён, используйте clear_globs=False.

compileflags задаёт набор флагов, которые компилятор Python должен использовать при выполнении примеров. Если параметр не задан, по умолчанию используется набор флагов импортов future, применимых к globs.

Вывод каждого примера проверяется средством проверки вывода DocTestRunner, а результаты форматируются методами DocTestRunner.report_*().

summarize(verbose=None)

Выводит сводку по всем тестовым случаям, запущенным этим DocTestRunner, и возвращает экземпляр TestResults.

Необязательный аргумент verbose управляет подробностью сводки. Если уровень подробности не задан, используется уровень подробности DocTestRunner.

DocTestParser имеет следующие атрибуты:

tries

Количество запущенных примеров.

failures

Количество неудачных примеров.

skips

Количество пропущенных примеров.

Добавлено в версии 3.13.

Объекты OutputChecker

class doctest.OutputChecker

Класс для проверки того, соответствует ли фактический вывод примера doctest ожидаемому. OutputChecker определяет два метода: check_output(), который сравнивает заданную пару выводов и возвращает True, если они совпадают; и output_difference(), который возвращает строку с описанием различий между двумя выводами.

OutputChecker определяет следующие методы:

check_output(want, got, optionflags)

Возвращает True тогда и только тогда, когда фактический вывод примера (got) совпадает с ожидаемым выводом (want). Эти строки всегда считаются совпадающими, если они идентичны; однако в зависимости от флагов параметров, используемых средством запуска тестов, возможны и некоторые виды неточного совпадения. Дополнительные сведения о флагах параметров см. в разделе Флаги параметров.

output_difference(example, got, optionflags)

Возвращает строку с описанием различий между ожидаемым выводом заданного примера (example) и фактическим выводом (got). optionflags — набор флагов параметров, использованных для сравнения want и got.