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

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

doctest.REPORT_CDIFF

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

doctest.REPORT_NDIFF

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

doctest.REPORT_ONLY_FIRST_FAILURE

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

doctest.FAIL_FAST

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

В командной строке doctest параметр -f является сокращённой записью -o FAIL_FAST.

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

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()
{"Hermione", "Harry"}

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

>>> foo() == {"Hermione", "Harry"}
True

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

>>> d = sorted(foo())
>>> d
['Harry', 'Hermione']

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

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

>>> 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 платформы, а качество таких библиотек сильно различается.

>>> 1./7  # risky
0.14285714285714285
>>> print(1./7) # safer
0.142857142857
>>> print(round(1./7, 6)) # much safer
0.142857

Числа вида 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

Ожидаемый результат выполнения исходного кода примера (из stdout или трассировка стека в случае исключения). 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 — это имя, идентифицирующее данную строку; оно используется только в сообщениях об ошибках.

Объекты DocTestRunner

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

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

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

Вывод средства запуска тестов можно контролировать двумя способами. Во-первых, функции вывода можно передать в TestRunner.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 позволяет управлять сравнением ожидаемого и фактического вывода средством запуска тестов, а также отображением сбоев. Дополнительные сведения см. в разделе Флаги параметров.

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.

Примеры выполняются в пространстве имён test.globs. Если clear_globs имеет значение true (по умолчанию), это пространство имён очищается после выполнения теста, что помогает сборщику мусора. Если после завершения теста нужно проверить пространство имён, используйте clear_globs=False.

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

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

summarize(verbose=None)

Выводит сводку по всем тестовым случаям, выполненным этим DocTestRunner, и возвращает TestResults(failed, attempted) — именованный кортеж.

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

Объекты 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.