Lines Matching +full:runner +full:- +full:before +full:- +full:script
1 :mod:`doctest` --- Test interactive Python examples
14 --------------
20 * To check that a module's docstrings are up-to-date by verifying that all
27 input-output examples. Depending on whether the examples or the expository text
49 >>> factorial(-1)
91 .. code-block:: shell-session
97 ``-v`` to the script, and :mod:`doctest` prints a detailed log of what
100 .. code-block:: shell-session
102 $ python example.py -v
116 .. code-block:: none
140 .. _doctest-simple-testmod:
143 ---------------------------------------------
154 Running the module as a script causes the examples in the docstrings to get
164 Run it with the ``-v`` switch instead::
166 python M.py -v
173 ``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not
180 python -m doctest -v example.py
186 For more information on :func:`testmod`, see section :ref:`doctest-basic-api`.
189 .. _doctest-simple-testfile:
192 ----------------------------------------------
200 That short script executes and verifies any interactive Python examples
205 .. code-block:: none
211 -------------------
240 See section :ref:`doctest-basic-api` for a description of the optional arguments
244 ``-v`` command-line switch or with the optional keyword argument
251 python -m doctest -v example.txt
256 For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
259 .. _doctest-how-it-works:
262 ------------
272 .. _doctest-which-docstrings:
291 .. impl-detail::
296 .. _doctest-finding-examples:
301 In most cases a copy-and-paste of an interactive console session works fine,
328 ``'>>> '`` or all-whitespace line.
332 * Expected output cannot contain an all-whitespace line, since such a line is
337 * All hard tab characters are expanded to spaces, using 8-column tab stops.
341 :const:`NORMALIZE_WHITESPACE` option or :ref:`directive <doctest-directives>`
381 .. _doctest-execution-context:
390 freely use any names defined at top-level in :mod:`M`, and names defined earlier
398 .. _doctest-exceptions:
433 multi-line detail::
471 the first line of the example, *or* start with a non-alphanumeric character.
482 distinguish exceptions from non-exceptions. So in the rare case where you need
497 Since the lines showing the position of the error come before the exception type
509 .. _option-flags-and-directives:
510 .. _doctest-options:
518 The names can also be used in :ref:`doctest directives <doctest-directives>`,
519 and may be passed to the doctest command line interface via the ``-o`` option.
522 The ``-o`` command line option.
596 <doctest-directives>` and ignore them as irrelevant comments). For example::
632 When specified, failures that involve multi-line expected and actual outputs are
638 When specified, failures that involve multi-line expected and actual outputs
669 The doctest command line accepts the option ``-f`` as a shorthand for ``-o
698 single: - (minus); in doctests
699 .. _doctest-directives:
705 <doctest-options>` for an individual example. Doctest directives are
712 on_or_off: "+" \| "-"
715 Whitespace is not allowed between the ``+`` or ``-`` and the directive option
720 example. Use ``+`` to enable the named behavior, or ``-`` to disable it.
729 two blanks before the single-digit list elements, and because the actual output
761 disabling an option via ``-`` in a directive can be useful.
764 .. _doctest-warnings:
791 Before Python 3.6, when printing a dict, Python did not guarantee that
792 the key-value pairs was printed in any particular order.
809 Floating-point numbers are also subject to small output variations across
830 .. _doctest-basic-api:
833 ---------
837 introduction to these two functions, see sections :ref:`doctest-simple-testmod`
838 and :ref:`doctest-simple-testfile`.
853 OS-independent module-relative path. By default, this path is relative to the
855 is relative to that package. To ensure OS-independence, *filename* should use
859 * If *module_relative* is ``False``, then *filename* specifies an OS-specific
867 whose directory should be used as the base directory for a module-relative
869 used as the base directory for module-relative filenames. It is an error to
887 failures if false; by default, or if ``None``, it's true if and only if ``'-v'``
896 See section :ref:`doctest-options`.
900 allows failures to be post-mortem debugged. Default behavior is to continue
964 .. _doctest-unittest-api:
967 ------------
1006 *paths* specifies an OS-independent module-relative path. By default, this
1009 OS-independence, each filename should use ``/`` characters to separate path
1014 an OS-specific path. The path may be absolute or relative; relative paths
1019 module-relative filenames in *paths*. If no package is specified, then the
1020 calling module's directory is used as the base directory for module-relative
1024 Optional argument *setUp* specifies a set-up function for the test suite.
1025 This is called before running the tests in each file. The *setUp* function
1029 Optional argument *tearDown* specifies a tear-down function for the test
1039 tests, created by or-ing together individual option flags. See section
1040 :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below
1076 drop-in replacement) that is used to extract doctests from the module.
1117 section :ref:`doctest-options`. Only "reporting flags" can be used.
1119 This is a module-global setting, and affects all future doctests run by module
1130 The value of the :mod:`unittest` reporting flags in effect before the function
1134 .. _doctest-advanced-api:
1137 ------------
1141 require more fine-grained control over testing, or wish to extend doctest's
1173 +------+ +---------+
1174 |module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
1175 +------+ | ^ +---------+ | ^ (printed)
1179 +---------+
1182 .. _doctest-doctest:
1228 ``None`` if the line number is unavailable. This line number is zero-based
1238 .. _doctest-example:
1282 begins. This line number is zero-based with respect to the beginning of the
1300 .. _doctest-doctestfinder:
1317 drop-in replacement) that is used to extract doctests from docstrings.
1355 to belong to the (non-existent) module, so all contained objects will
1366 .. _doctest-doctestparser:
1394 of :class:`Example` objects. Line numbers are 0-based. The optional argument
1402 :class:`Example`\ s are 0-based. The optional argument *name* is a name
1406 .. _doctest-doctestrunner:
1419 option flags; see section :ref:`doctest-options` for more information. If the
1423 The test runner's display output can be controlled in two ways. First, an output
1432 object (or drop-in replacement) that should be used to compare the expected
1439 iff the command-line switch ``-v`` is used.
1442 runner compares expected output to actual output, and how it displays failures.
1443 For more information, see section :ref:`doctest-options`.
1451 Report that the test runner is about to process the given example. This method
1506 the set of future-import flags that apply to *globs*.
1522 .. _doctest-outputchecker:
1543 they are identical; but depending on what option flags the test runner is
1544 using, several non-exact match types are also possible. See section
1545 :ref:`doctest-options` for more information about option flags.
1555 .. _doctest-debugging:
1558 ---------
1567 that example. This information can be used to perform post-mortem debugging on
1592 --Return--
1593 > <doctest a[1]>(3)g()->None
1594 -> import pdb; pdb.set_trace()
1598 3 -> import pdb; pdb.set_trace()
1603 --Return--
1604 > <doctest a[0]>(2)f()->None
1605 -> g(x*2)
1608 2 -> g(x*2)
1613 --Return--
1614 > <doctest a[2]>(1)?()->None
1615 -> f(3)
1627 Convert text with examples to a script.
1630 to a Python script, where doctest examples in *s* are converted to regular code,
1631 and everything else is converted to Python comments. The generated script is
1656 script.
1661 Convert the doctest for an object to a script.
1666 containing the object's docstring converted to a Python script, as described for
1668 contains a top-level function :func:`f`, then ::
1673 prints a script version of function :func:`f`'s docstring, with doctests
1682 :func:`testsource` above. The synthesized Python script for the named object's
1689 Optional argument *pm* controls whether post-mortem debugging is used. If *pm*
1690 has a true value, the script file is run directly, and the debugger gets
1691 involved only if the script terminates via raising an unhandled exception. If
1692 it does, then post-mortem debugging is invoked, via :func:`pdb.post_mortem`,
1694 specified, or is false, the script is run under the debugger from the start, via
1728 documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`.
1782 .. _doctest-soapbox:
1785 -------
1801 this that needs to be learned---it may not be natural at first. Examples should
1813 code-based testing, but few programmers do. Many have found that using doctest
1817 the natural attitude when writing a doctest-based test is that you want to
1842 runner. When a test fails, you can arrange for your test runner to re-run only
1844 such a test runner::
1865 Trying to guess where one ends and the other begins is too error-prone, and that