diff -r 36b052adf5a7 Doc/extending/newtypes.rst --- a/Doc/extending/newtypes.rst Sun Oct 02 22:00:05 2016 +0300 +++ b/Doc/extending/newtypes.rst Mon Oct 03 20:43:34 2016 +0530 @@ -124,7 +124,7 @@ >>> "" + noddy.new_noddy() Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in TypeError: cannot add type "noddy.Noddy" to string Note that the name is a dotted name that includes both the module name and the diff -r 36b052adf5a7 Doc/howto/functional.rst --- a/Doc/howto/functional.rst Sun Oct 02 22:00:05 2016 +0300 +++ b/Doc/howto/functional.rst Mon Oct 03 20:43:34 2016 +0530 @@ -210,7 +210,7 @@ 3 >>> next(it) Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, StopIteration >>> @@ -474,7 +474,7 @@ 2 >>> next(gen) Traceback (most recent call last): - File "stdin", line 1, in ? + File "stdin", line 1, File "stdin", line 2, in generate_ints StopIteration @@ -577,7 +577,7 @@ 9 >>> next(it) #doctest: +SKIP Traceback (most recent call last): - File "t.py", line 15, in ? + File "t.py", line 15, it.next() StopIteration diff -r 36b052adf5a7 Doc/library/doctest.rst --- a/Doc/library/doctest.rst Sun Oct 02 22:00:05 2016 +0300 +++ b/Doc/library/doctest.rst Mon Oct 03 20:43:34 2016 +0530 @@ -1,597 +1,597 @@ -:keepdoctest: - -:mod:`doctest` --- Test interactive Python examples -=================================================== - -.. module:: doctest - :synopsis: Test pieces of code within docstrings. - -.. moduleauthor:: Tim Peters -.. sectionauthor:: Tim Peters -.. sectionauthor:: Moshe Zadka -.. sectionauthor:: Edward Loper - -**Source code:** :source:`Lib/doctest.py` - --------------- - -The :mod:`doctest` module searches for pieces of text that look like interactive -Python sessions, and then executes those sessions to verify that they work -exactly as shown. There are several common ways to use doctest: - -* To check that a module's docstrings are up-to-date by verifying that all - interactive examples still work as documented. - -* To perform regression testing by verifying that interactive examples from a - test file or a test object work as expected. - -* To write tutorial documentation for a package, liberally illustrated with - input-output examples. Depending on whether the examples or the expository text - are emphasized, this has the flavor of "literate testing" or "executable - documentation". - -Here's a complete but small example module:: - - """ - This is the "example" module. - - The example module supplies one function, factorial(). For example, - - >>> factorial(5) - 120 - """ - - def factorial(n): - """Return the factorial of n, an exact integer >= 0. - - >>> [factorial(n) for n in range(6)] - [1, 1, 2, 6, 24, 120] - >>> factorial(30) - 265252859812191058636308480000000 - >>> factorial(-1) + :keepdoctest: + + :mod:`doctest` --- Test interactive Python examples + =================================================== + + .. module:: doctest + :synopsis: Test pieces of code within docstrings. + + .. moduleauthor:: Tim Peters + .. sectionauthor:: Tim Peters + .. sectionauthor:: Moshe Zadka + .. sectionauthor:: Edward Loper + + **Source code:** :source:`Lib/doctest.py` + + -------------- + + The :mod:`doctest` module searches for pieces of text that look like interactive + Python sessions, and then executes those sessions to verify that they work + exactly as shown. There are several common ways to use doctest: + + * To check that a module's docstrings are up-to-date by verifying that all + interactive examples still work as documented. + + * To perform regression testing by verifying that interactive examples from a + test file or a test object work as expected. + + * To write tutorial documentation for a package, liberally illustrated with + input-output examples. Depending on whether the examples or the expository text + are emphasized, this has the flavor of "literate testing" or "executable + documentation". + + Here's a complete but small example module:: + + """ + This is the "example" module. + + The example module supplies one function, factorial(). For example, + + >>> factorial(5) + 120 + """ + + def factorial(n): + """Return the factorial of n, an exact integer >= 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 + + Factorials of floats are OK, but the float must be an exact integer: + >>> factorial(30.1) + Traceback (most recent call last): + ... + ValueError: n must be exact integer + >>> factorial(30.0) + 265252859812191058636308480000000 + + It must also not be ridiculously large: + >>> 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: # catch a value like 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() + + If you run :file:`example.py` directly from the command line, :mod:`doctest` + works its magic: + + .. code-block:: shell-session + + $ python example.py + $ + + There's no output! That's normal, and it means all the examples worked. Pass + ``-v`` to the script, and :mod:`doctest` prints a detailed log of what + it's trying, and prints a summary at the end: + + .. code-block:: shell-session + + $ 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 + + And so on, eventually ending with: + + .. code-block:: none + + Trying: + factorial(1e100) + Expecting: + Traceback (most recent call last): + ... + OverflowError: n too large + ok + 2 items passed all tests: + 1 tests in __main__ + 8 tests in __main__.factorial + 9 tests in 2 items. + 9 passed and 0 failed. + Test passed. + $ + + That's all you need to know to start making productive use of :mod:`doctest`! + Jump in. The following sections provide full details. Note that there are many + examples of doctests in the standard Python test suite and libraries. + Especially useful examples can be found in the standard test file + :file:`Lib/test/test_doctest.py`. + + + .. _doctest-simple-testmod: + + Simple Usage: Checking Examples in Docstrings + --------------------------------------------- + + The simplest way to start using doctest (but not necessarily the way you'll + continue to do it) is to end each module :mod:`M` with:: + + if __name__ == "__main__": + import doctest + doctest.testmod() + + :mod:`doctest` then examines docstrings in module :mod:`M`. + + Running the module as a script causes the examples in the docstrings to get + executed and verified:: + + python M.py + + This won't display anything unless an example fails, in which case the failing + example(s) and the cause(s) of the failure(s) are printed to stdout, and the + final line of output is ``***Test Failed*** N failures.``, where *N* is the + number of examples that failed. + + Run it with the ``-v`` switch instead:: + + python M.py -v + + and a detailed report of all examples tried is printed to standard output, along + with assorted summaries at the end. + + You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or + prohibit it by passing ``verbose=False``. In either of those cases, + ``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not + has no effect). + + There is also a command line shortcut for running :func:`testmod`. You can + instruct the Python interpreter to run the doctest module directly from the + standard library and pass the module name(s) on the command line:: + + python -m doctest -v example.py + + This will import :file:`example.py` as a standalone module and run + :func:`testmod` on it. Note that this may not work correctly if the file is + part of a package and imports other submodules from that package. + + For more information on :func:`testmod`, see section :ref:`doctest-basic-api`. + + + .. _doctest-simple-testfile: + + Simple Usage: Checking Examples in a Text File + ---------------------------------------------- + + Another simple application of doctest is testing interactive examples in a text + file. This can be done with the :func:`testfile` function:: + + import doctest + doctest.testfile("example.txt") + + That short script executes and verifies any interactive Python examples + contained in the file :file:`example.txt`. The file content is treated as if it + were a single giant docstring; the file doesn't need to contain a Python + program! For example, perhaps :file:`example.txt` contains this: + + .. code-block:: none + + 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 + + Running ``doctest.testfile("example.txt")`` then finds the error in this + documentation:: + + File "./example.txt", line 14, in example.txt + Failed example: + factorial(6) + Expected: + 120 + Got: + 720 + + As with :func:`testmod`, :func:`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 + :func:`testmod`. + + By default, :func:`testfile` looks for files in the calling module's directory. + See section :ref:`doctest-basic-api` for a description of the optional arguments + that can be used to tell it to look for files in other locations. + + Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the + ``-v`` command-line switch or with the optional keyword argument + *verbose*. + + There is also a command line shortcut for running :func:`testfile`. You can + instruct the Python interpreter to run the doctest module directly from the + standard library and pass the file name(s) on the command line:: + + python -m doctest -v example.txt + + Because the file name does not end with :file:`.py`, :mod:`doctest` infers that + it must be run with :func:`testfile`, not :func:`testmod`. + + For more information on :func:`testfile`, see section :ref:`doctest-basic-api`. + + + .. _doctest-how-it-works: + + How It Works + ------------ + + This section examines in detail how doctest works: which docstrings it looks at, + how it finds interactive examples, what execution context it uses, how it + handles exceptions, and how option flags can be used to control its behavior. + This is the information that you need to know to write doctest examples; for + information about actually running doctest on these examples, see the following + sections. + + + .. _doctest-which-docstrings: + + Which Docstrings Are Examined? + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The module docstring, and all function, class and method docstrings are + searched. Objects imported into the module are not searched. + + In addition, if ``M.__test__`` exists and "is true", it must be a dict, and each + entry maps a (string) name to a function object, class object, or string. + Function and class object docstrings found from ``M.__test__`` are searched, and + strings are treated as if they were docstrings. In output, a key ``K`` in + ``M.__test__`` appears with name :: + + .__test__.K + + Any classes found are recursively searched similarly, to test docstrings in + their contained methods and nested classes. + + .. impl-detail:: + Prior to version 3.4, extension modules written in C were not fully + searched by doctest. + + + .. _doctest-finding-examples: + + How are Docstring Examples Recognized? + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + In most cases a copy-and-paste of an interactive console session works fine, + but doctest isn't trying to do an exact emulation of any specific Python shell. + + :: + + >>> # comments are ignored + >>> x = 12 + >>> x + 12 + >>> if x == 13: + ... print("yes") + ... else: + ... print("no") + ... print("NO") + ... print("NO!!!") + ... + no + NO + NO!!! + >>> + + Any expected output must immediately follow the final ``'>>> '`` or ``'... '`` + line containing the code, and the expected output (if any) extends to the next + ``'>>> '`` or all-whitespace line. + + The fine print: + + * Expected output cannot contain an all-whitespace line, since such a line is + taken to signal the end of expected output. If expected output does contain a + blank line, put ```` in your doctest example each place a blank line + is expected. + + * All hard tab characters are expanded to spaces, using 8-column tab stops. + Tabs in output generated by the tested code are not modified. Because any + hard tabs in the sample output *are* expanded, this means that if the code + output includes hard tabs, the only way the doctest can pass is if the + :const:`NORMALIZE_WHITESPACE` option or :ref:`directive ` + is in effect. + Alternatively, the test can be rewritten to capture the output and compare it + to an expected value as part of the test. This handling of tabs in the + source was arrived at through trial and error, and has proven to be the least + error prone way of handling them. It is possible to use a different + algorithm for handling tabs by writing a custom :class:`DocTestParser` class. + + * Output to stdout is captured, but not output to stderr (exception tracebacks + are captured via a different means). + + * If you continue a line via backslashing in an interactive session, or for any + other reason use a backslash, you should use a raw docstring, which will + preserve your backslashes exactly as you type them:: + + >>> def f(x): + ... r'''Backslashes in a raw docstring: m\n''' + >>> print(f.__doc__) + Backslashes in a raw docstring: m\n + + Otherwise, the backslash will be interpreted as part of the string. For example, + the ``\n`` above would be interpreted as a newline character. Alternatively, you + can double each backslash in the doctest version (and not use a raw string):: + + >>> def f(x): + ... '''Backslashes in a raw docstring: m\\n''' + >>> print(f.__doc__) + Backslashes in a raw docstring: m\n + + * The starting column doesn't matter:: + + >>> assert "Easy!" + >>> import math + >>> math.floor(1.9) + 1 + + and as many leading whitespace characters are stripped from the expected output + as appeared in the initial ``'>>> '`` line that started the example. + + + .. _doctest-execution-context: + + What's the Execution Context? + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + By default, each time :mod:`doctest` finds a docstring to test, it uses a + *shallow copy* of :mod:`M`'s globals, so that running tests doesn't change the + module's real globals, and so that one test in :mod:`M` can't leave behind + crumbs that accidentally allow another test to work. This means examples can + freely use any names defined at top-level in :mod:`M`, and names defined earlier + in the docstring being run. Examples cannot see names defined in other + docstrings. + + You can force use of your own dict as the execution context by passing + ``globs=your_dict`` to :func:`testmod` or :func:`testfile` instead. + + + .. _doctest-exceptions: + + What About Exceptions? + ^^^^^^^^^^^^^^^^^^^^^^ + + No problem, provided that the traceback is the only output produced by the + example: just paste in the traceback. [#]_ Since tracebacks contain details + that are likely to change rapidly (for example, exact file paths and line + numbers), this is one case where doctest works hard to be flexible in what it + accepts. + + Simple example:: + + >>> [1, 2, 3].remove(42) + Traceback (most recent call last): + File "", line 1, + ValueError: list.remove(x): x not in list + + That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x): + x not in list`` detail as shown. + + The expected output for an exception must start with a traceback header, which + may be either of the following two lines, indented the same as the first line of + the example:: + + Traceback (most recent call last): + Traceback (innermost last): + + The traceback header is followed by an optional traceback stack, whose contents + are ignored by doctest. The traceback stack is typically omitted, or copied + verbatim from an interactive session. + + The traceback stack is followed by the most interesting part: the line(s) + containing the exception type and detail. This is usually the last line of a + traceback, but can extend across multiple lines if the exception has a + multi-line detail:: + + >>> raise ValueError('multi\n line\ndetail') + Traceback (most recent call last): + File "", line 1, + ValueError: multi + line + detail + + The last three lines (starting with :exc:`ValueError`) are compared against the + exception's type and detail, and the rest are ignored. + + Best practice is to omit the traceback stack, unless it adds significant + documentation value to the example. So the last example is probably better as:: + + >>> raise ValueError('multi\n line\ndetail') + Traceback (most recent call last): + ... + ValueError: multi + line + detail + + Note that tracebacks are treated very specially. In particular, in the + rewritten example, the use of ``...`` is independent of doctest's + :const:`ELLIPSIS` option. The ellipsis in that example could be left out, or + could just as well be three (or three hundred) commas or digits, or an indented + transcript of a Monty Python skit. + + Some details you should read once, but won't need to remember: + + * Doctest can't guess whether your expected output came from an exception + traceback or from ordinary printing. So, e.g., an example that expects + ``ValueError: 42 is prime`` will pass whether :exc:`ValueError` is actually + raised or if the example merely prints that traceback text. In practice, + ordinary output rarely begins with a traceback header line, so this doesn't + create real problems. + + * Each line of the traceback stack (if present) must be indented further than + the first line of the example, *or* start with a non-alphanumeric character. + The first line following the traceback header indented the same and starting + with an alphanumeric is taken to be the start of the exception detail. Of + course this does the right thing for genuine tracebacks. + + * When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified, + everything following the leftmost colon and any module information in the + exception name is ignored. + + * The interactive shell omits the traceback header line for some + :exc:`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 :exc:`SyntaxError` that omits the traceback header, you will need to + manually add the traceback header line to your test example. + + * For some :exc:`SyntaxError`\ s, Python displays the character position of the + syntax error, using a ``^`` marker:: + + >>> 1 1 + File "", line 1 + 1 1 + ^ + SyntaxError: invalid syntax + + Since the lines showing the position of the error come before the exception type + and detail, they are not checked by doctest. For example, the following test + would pass, even though it puts the ``^`` marker in the wrong location:: + + >>> 1 1 Traceback (most recent call last): - ... - ValueError: n must be >= 0 - - Factorials of floats are OK, but the float must be an exact integer: - >>> factorial(30.1) - Traceback (most recent call last): - ... - ValueError: n must be exact integer - >>> factorial(30.0) - 265252859812191058636308480000000 - - It must also not be ridiculously large: - >>> 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: # catch a value like 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() - -If you run :file:`example.py` directly from the command line, :mod:`doctest` -works its magic: - -.. code-block:: shell-session - - $ python example.py - $ - -There's no output! That's normal, and it means all the examples worked. Pass -``-v`` to the script, and :mod:`doctest` prints a detailed log of what -it's trying, and prints a summary at the end: - -.. code-block:: shell-session - - $ 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 - -And so on, eventually ending with: - -.. code-block:: none - - Trying: - factorial(1e100) - Expecting: - Traceback (most recent call last): - ... - OverflowError: n too large - ok - 2 items passed all tests: - 1 tests in __main__ - 8 tests in __main__.factorial - 9 tests in 2 items. - 9 passed and 0 failed. - Test passed. - $ - -That's all you need to know to start making productive use of :mod:`doctest`! -Jump in. The following sections provide full details. Note that there are many -examples of doctests in the standard Python test suite and libraries. -Especially useful examples can be found in the standard test file -:file:`Lib/test/test_doctest.py`. - - -.. _doctest-simple-testmod: - -Simple Usage: Checking Examples in Docstrings ---------------------------------------------- - -The simplest way to start using doctest (but not necessarily the way you'll -continue to do it) is to end each module :mod:`M` with:: - - if __name__ == "__main__": - import doctest - doctest.testmod() - -:mod:`doctest` then examines docstrings in module :mod:`M`. - -Running the module as a script causes the examples in the docstrings to get -executed and verified:: - - python M.py - -This won't display anything unless an example fails, in which case the failing -example(s) and the cause(s) of the failure(s) are printed to stdout, and the -final line of output is ``***Test Failed*** N failures.``, where *N* is the -number of examples that failed. - -Run it with the ``-v`` switch instead:: - - python M.py -v - -and a detailed report of all examples tried is printed to standard output, along -with assorted summaries at the end. - -You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or -prohibit it by passing ``verbose=False``. In either of those cases, -``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not -has no effect). - -There is also a command line shortcut for running :func:`testmod`. You can -instruct the Python interpreter to run the doctest module directly from the -standard library and pass the module name(s) on the command line:: - - python -m doctest -v example.py - -This will import :file:`example.py` as a standalone module and run -:func:`testmod` on it. Note that this may not work correctly if the file is -part of a package and imports other submodules from that package. - -For more information on :func:`testmod`, see section :ref:`doctest-basic-api`. - - -.. _doctest-simple-testfile: - -Simple Usage: Checking Examples in a Text File ----------------------------------------------- - -Another simple application of doctest is testing interactive examples in a text -file. This can be done with the :func:`testfile` function:: - - import doctest - doctest.testfile("example.txt") - -That short script executes and verifies any interactive Python examples -contained in the file :file:`example.txt`. The file content is treated as if it -were a single giant docstring; the file doesn't need to contain a Python -program! For example, perhaps :file:`example.txt` contains this: - -.. code-block:: none - - 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 - -Running ``doctest.testfile("example.txt")`` then finds the error in this -documentation:: - - File "./example.txt", line 14, in example.txt - Failed example: - factorial(6) - Expected: - 120 - Got: - 720 - -As with :func:`testmod`, :func:`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 -:func:`testmod`. - -By default, :func:`testfile` looks for files in the calling module's directory. -See section :ref:`doctest-basic-api` for a description of the optional arguments -that can be used to tell it to look for files in other locations. - -Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the -``-v`` command-line switch or with the optional keyword argument -*verbose*. - -There is also a command line shortcut for running :func:`testfile`. You can -instruct the Python interpreter to run the doctest module directly from the -standard library and pass the file name(s) on the command line:: - - python -m doctest -v example.txt - -Because the file name does not end with :file:`.py`, :mod:`doctest` infers that -it must be run with :func:`testfile`, not :func:`testmod`. - -For more information on :func:`testfile`, see section :ref:`doctest-basic-api`. - - -.. _doctest-how-it-works: - -How It Works ------------- - -This section examines in detail how doctest works: which docstrings it looks at, -how it finds interactive examples, what execution context it uses, how it -handles exceptions, and how option flags can be used to control its behavior. -This is the information that you need to know to write doctest examples; for -information about actually running doctest on these examples, see the following -sections. - - -.. _doctest-which-docstrings: - -Which Docstrings Are Examined? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The module docstring, and all function, class and method docstrings are -searched. Objects imported into the module are not searched. - -In addition, if ``M.__test__`` exists and "is true", it must be a dict, and each -entry maps a (string) name to a function object, class object, or string. -Function and class object docstrings found from ``M.__test__`` are searched, and -strings are treated as if they were docstrings. In output, a key ``K`` in -``M.__test__`` appears with name :: - - .__test__.K - -Any classes found are recursively searched similarly, to test docstrings in -their contained methods and nested classes. - -.. impl-detail:: - Prior to version 3.4, extension modules written in C were not fully - searched by doctest. - - -.. _doctest-finding-examples: - -How are Docstring Examples Recognized? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In most cases a copy-and-paste of an interactive console session works fine, -but doctest isn't trying to do an exact emulation of any specific Python shell. - -:: - - >>> # comments are ignored - >>> x = 12 - >>> x - 12 - >>> if x == 13: - ... print("yes") - ... else: - ... print("no") - ... print("NO") - ... print("NO!!!") - ... - no - NO - NO!!! - >>> - -Any expected output must immediately follow the final ``'>>> '`` or ``'... '`` -line containing the code, and the expected output (if any) extends to the next -``'>>> '`` or all-whitespace line. - -The fine print: - -* Expected output cannot contain an all-whitespace line, since such a line is - taken to signal the end of expected output. If expected output does contain a - blank line, put ```` in your doctest example each place a blank line - is expected. - -* All hard tab characters are expanded to spaces, using 8-column tab stops. - Tabs in output generated by the tested code are not modified. Because any - hard tabs in the sample output *are* expanded, this means that if the code - output includes hard tabs, the only way the doctest can pass is if the - :const:`NORMALIZE_WHITESPACE` option or :ref:`directive ` - is in effect. - Alternatively, the test can be rewritten to capture the output and compare it - to an expected value as part of the test. This handling of tabs in the - source was arrived at through trial and error, and has proven to be the least - error prone way of handling them. It is possible to use a different - algorithm for handling tabs by writing a custom :class:`DocTestParser` class. - -* Output to stdout is captured, but not output to stderr (exception tracebacks - are captured via a different means). - -* If you continue a line via backslashing in an interactive session, or for any - other reason use a backslash, you should use a raw docstring, which will - preserve your backslashes exactly as you type them:: - - >>> def f(x): - ... r'''Backslashes in a raw docstring: m\n''' - >>> print(f.__doc__) - Backslashes in a raw docstring: m\n - - Otherwise, the backslash will be interpreted as part of the string. For example, - the ``\n`` above would be interpreted as a newline character. Alternatively, you - can double each backslash in the doctest version (and not use a raw string):: - - >>> def f(x): - ... '''Backslashes in a raw docstring: m\\n''' - >>> print(f.__doc__) - Backslashes in a raw docstring: m\n - -* The starting column doesn't matter:: - - >>> assert "Easy!" - >>> import math - >>> math.floor(1.9) - 1 - - and as many leading whitespace characters are stripped from the expected output - as appeared in the initial ``'>>> '`` line that started the example. - - -.. _doctest-execution-context: - -What's the Execution Context? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default, each time :mod:`doctest` finds a docstring to test, it uses a -*shallow copy* of :mod:`M`'s globals, so that running tests doesn't change the -module's real globals, and so that one test in :mod:`M` can't leave behind -crumbs that accidentally allow another test to work. This means examples can -freely use any names defined at top-level in :mod:`M`, and names defined earlier -in the docstring being run. Examples cannot see names defined in other -docstrings. - -You can force use of your own dict as the execution context by passing -``globs=your_dict`` to :func:`testmod` or :func:`testfile` instead. - - -.. _doctest-exceptions: - -What About Exceptions? -^^^^^^^^^^^^^^^^^^^^^^ - -No problem, provided that the traceback is the only output produced by the -example: just paste in the traceback. [#]_ Since tracebacks contain details -that are likely to change rapidly (for example, exact file paths and line -numbers), this is one case where doctest works hard to be flexible in what it -accepts. - -Simple example:: - - >>> [1, 2, 3].remove(42) - Traceback (most recent call last): - File "", line 1, in ? - ValueError: list.remove(x): x not in list - -That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x): -x not in list`` detail as shown. - -The expected output for an exception must start with a traceback header, which -may be either of the following two lines, indented the same as the first line of -the example:: - - Traceback (most recent call last): - Traceback (innermost last): - -The traceback header is followed by an optional traceback stack, whose contents -are ignored by doctest. The traceback stack is typically omitted, or copied -verbatim from an interactive session. - -The traceback stack is followed by the most interesting part: the line(s) -containing the exception type and detail. This is usually the last line of a -traceback, but can extend across multiple lines if the exception has a -multi-line detail:: - - >>> raise ValueError('multi\n line\ndetail') - Traceback (most recent call last): - File "", line 1, in ? - ValueError: multi - line - detail - -The last three lines (starting with :exc:`ValueError`) are compared against the -exception's type and detail, and the rest are ignored. - -Best practice is to omit the traceback stack, unless it adds significant -documentation value to the example. So the last example is probably better as:: - - >>> raise ValueError('multi\n line\ndetail') - Traceback (most recent call last): - ... - ValueError: multi - line - detail - -Note that tracebacks are treated very specially. In particular, in the -rewritten example, the use of ``...`` is independent of doctest's -:const:`ELLIPSIS` option. The ellipsis in that example could be left out, or -could just as well be three (or three hundred) commas or digits, or an indented -transcript of a Monty Python skit. - -Some details you should read once, but won't need to remember: - -* Doctest can't guess whether your expected output came from an exception - traceback or from ordinary printing. So, e.g., an example that expects - ``ValueError: 42 is prime`` will pass whether :exc:`ValueError` is actually - raised or if the example merely prints that traceback text. In practice, - ordinary output rarely begins with a traceback header line, so this doesn't - create real problems. - -* Each line of the traceback stack (if present) must be indented further than - the first line of the example, *or* start with a non-alphanumeric character. - The first line following the traceback header indented the same and starting - with an alphanumeric is taken to be the start of the exception detail. Of - course this does the right thing for genuine tracebacks. - -* When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified, - everything following the leftmost colon and any module information in the - exception name is ignored. - -* The interactive shell omits the traceback header line for some - :exc:`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 :exc:`SyntaxError` that omits the traceback header, you will need to - manually add the traceback header line to your test example. - -* For some :exc:`SyntaxError`\ s, Python displays the character position of the - syntax error, using a ``^`` marker:: - - >>> 1 1 - File "", line 1 - 1 1 + File "", line 1 + 1 1 ^ - SyntaxError: invalid syntax - - Since the lines showing the position of the error come before the exception type - and detail, they are not checked by doctest. For example, the following test - would pass, even though it puts the ``^`` marker in the wrong location:: - - >>> 1 1 - Traceback (most recent call last): - File "", line 1 - 1 1 - ^ - SyntaxError: invalid syntax - - -.. _option-flags-and-directives: -.. _doctest-options: - -Option Flags -^^^^^^^^^^^^ - -A number of option flags control various aspects of doctest's behavior. -Symbolic names for the flags are supplied as module constants, which can be -or'ed together and passed to various functions. The names can also be used in -:ref:`doctest directives `, and may be passed to the -doctest command line interface via the ``-o`` option. - -.. versionadded:: 3.4 - The ``-o`` command line option. - -The first group of options define test semantics, controlling aspects of how -doctest decides whether actual output matches an example's expected output: - - -.. data:: DONT_ACCEPT_TRUE_FOR_1 - - By default, if an expected output block contains just ``1``, an actual output - block containing just ``1`` or just ``True`` is considered to be a match, and - similarly for ``0`` versus ``False``. When :const:`DONT_ACCEPT_TRUE_FOR_1` is - specified, neither substitution is allowed. The default behavior caters to that - Python changed the return type of many functions from integer to boolean; - doctests expecting "little integer" output still work in these cases. This - option will probably go away, but not for several years. - - -.. data:: DONT_ACCEPT_BLANKLINE - - By default, if an expected output block contains a line containing only the - string ````, then that line will match a blank line in the actual - output. Because a genuinely blank line delimits the expected output, this is - the only way to communicate that a blank line is expected. When - :const:`DONT_ACCEPT_BLANKLINE` is specified, this substitution is not allowed. - - -.. data:: NORMALIZE_WHITESPACE - - When specified, all sequences of whitespace (blanks and newlines) are treated as - equal. Any sequence of whitespace within the expected output will match any - sequence of whitespace within the actual output. By default, whitespace must - match exactly. :const:`NORMALIZE_WHITESPACE` is especially useful when a line of - expected output is very long, and you want to wrap it across multiple lines in - your source. - - -.. data:: ELLIPSIS - - When specified, an ellipsis marker (``...``) in the expected output can match - any substring in the actual output. This includes substrings that span line - boundaries, and empty substrings, so it's best to keep usage of this simple. - Complicated uses can lead to the same kinds of "oops, it matched too much!" - surprises that ``.*`` is prone to in regular expressions. - - -.. data:: IGNORE_EXCEPTION_DETAIL - - When specified, an example that expects an exception passes if an exception of - the expected type is raised, even if the exception detail does not match. For - example, an example expecting ``ValueError: 42`` will pass if the actual - exception raised is ``ValueError: 3*14``, but will fail, e.g., if - :exc:`TypeError` is raised. - - It will also ignore the module name used in Python 3 doctest reports. Hence - both of these variations will work with the flag specified, regardless of - whether the test is run under Python 2.7 or Python 3.2 (or later versions):: - - >>> raise CustomError('message') - Traceback (most recent call last): - CustomError: message - - >>> raise CustomError('message') - Traceback (most recent call last): - my_module.CustomError: message - - Note that :const:`ELLIPSIS` can also be used to ignore the - details of the exception message, but such a test may still fail based - on whether or not the module details are printed as part of the - exception name. Using :const:`IGNORE_EXCEPTION_DETAIL` and the details - from Python 2.3 is also the only clear way to write a doctest that doesn't - care about the exception detail yet continues to pass under Python 2.3 or - earlier (those releases do not support :ref:`doctest directives - ` and ignore them as irrelevant comments). For example:: - - >>> (1, 2)[3] = 'moo' - Traceback (most recent call last): - File "", line 1, in ? + SyntaxError: invalid syntax + + + .. _option-flags-and-directives: + .. _doctest-options: + + Option Flags + ^^^^^^^^^^^^ + + A number of option flags control various aspects of doctest's behavior. + Symbolic names for the flags are supplied as module constants, which can be + or'ed together and passed to various functions. The names can also be used in + :ref:`doctest directives `, and may be passed to the + doctest command line interface via the ``-o`` option. + + .. versionadded:: 3.4 + The ``-o`` command line option. + + The first group of options define test semantics, controlling aspects of how + doctest decides whether actual output matches an example's expected output: + + + .. data:: DONT_ACCEPT_TRUE_FOR_1 + + By default, if an expected output block contains just ``1``, an actual output + block containing just ``1`` or just ``True`` is considered to be a match, and + similarly for ``0`` versus ``False``. When :const:`DONT_ACCEPT_TRUE_FOR_1` is + specified, neither substitution is allowed. The default behavior caters to that + Python changed the return type of many functions from integer to boolean; + doctests expecting "little integer" output still work in these cases. This + option will probably go away, but not for several years. + + + .. data:: DONT_ACCEPT_BLANKLINE + + By default, if an expected output block contains a line containing only the + string ````, then that line will match a blank line in the actual + output. Because a genuinely blank line delimits the expected output, this is + the only way to communicate that a blank line is expected. When + :const:`DONT_ACCEPT_BLANKLINE` is specified, this substitution is not allowed. + + + .. data:: NORMALIZE_WHITESPACE + + When specified, all sequences of whitespace (blanks and newlines) are treated as + equal. Any sequence of whitespace within the expected output will match any + sequence of whitespace within the actual output. By default, whitespace must + match exactly. :const:`NORMALIZE_WHITESPACE` is especially useful when a line of + expected output is very long, and you want to wrap it across multiple lines in + your source. + + + .. data:: ELLIPSIS + + When specified, an ellipsis marker (``...``) in the expected output can match + any substring in the actual output. This includes substrings that span line + boundaries, and empty substrings, so it's best to keep usage of this simple. + Complicated uses can lead to the same kinds of "oops, it matched too much!" + surprises that ``.*`` is prone to in regular expressions. + + + .. data:: IGNORE_EXCEPTION_DETAIL + + When specified, an example that expects an exception passes if an exception of + the expected type is raised, even if the exception detail does not match. For + example, an example expecting ``ValueError: 42`` will pass if the actual + exception raised is ``ValueError: 3*14``, but will fail, e.g., if + :exc:`TypeError` is raised. + + It will also ignore the module name used in Python 3 doctest reports. Hence + both of these variations will work with the flag specified, regardless of + whether the test is run under Python 2.7 or Python 3.2 (or later versions):: + + >>> raise CustomError('message') + Traceback (most recent call last): + CustomError: message + + >>> raise CustomError('message') + Traceback (most recent call last): + my_module.CustomError: message + + Note that :const:`ELLIPSIS` can also be used to ignore the + details of the exception message, but such a test may still fail based + on whether or not the module details are printed as part of the + exception name. Using :const:`IGNORE_EXCEPTION_DETAIL` and the details + from Python 2.3 is also the only clear way to write a doctest that doesn't + care about the exception detail yet continues to pass under Python 2.3 or + earlier (those releases do not support :ref:`doctest directives + ` and ignore them as irrelevant comments). For example:: + + >>> (1, 2)[3] = 'moo' + Traceback (most recent call last): + File "", line 1, TypeError: object doesn't support item assignment passes under Python 2.3 and later Python versions with the flag specified, diff -r 36b052adf5a7 Doc/library/fpectl.rst --- a/Doc/library/fpectl.rst Sun Oct 02 22:00:05 2016 +0300 +++ b/Doc/library/fpectl.rst Mon Oct 03 20:43:34 2016 +0530 @@ -89,7 +89,7 @@ >>> import math >>> math.exp(1000) Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in FloatingPointError: in math_1 diff -r 36b052adf5a7 Doc/library/pdb.rst --- a/Doc/library/pdb.rst Sun Oct 02 22:00:05 2016 +0300 +++ b/Doc/library/pdb.rst Mon Oct 03 20:43:34 2016 +0530 @@ -76,7 +76,7 @@ >>> import mymodule >>> mymodule.test() Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in File "./mymodule.py", line 4, in test test2() File "./mymodule.py", line 3, in test2 diff -r 36b052adf5a7 Doc/library/unicodedata.rst --- a/Doc/library/unicodedata.rst Sun Oct 02 22:00:05 2016 +0300 +++ b/Doc/library/unicodedata.rst Mon Oct 03 20:43:34 2016 +0530 @@ -158,7 +158,7 @@ 9 >>> unicodedata.decimal('a') Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ValueError: not a decimal >>> unicodedata.category('A') # 'L'etter, 'u'ppercase 'Lu' diff -r 36b052adf5a7 Doc/reference/expressions.rst --- a/Doc/reference/expressions.rst Sun Oct 02 22:00:05 2016 +0300 +++ b/Doc/reference/expressions.rst Mon Oct 03 20:43:34 2016 +0530 @@ -745,7 +745,7 @@ 2 1 >>> f(a=1, *(2,)) Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in TypeError: f() got multiple values for keyword argument 'a' >>> f(1, *(2,)) 1 2 diff -r 36b052adf5a7 Doc/tutorial/classes.rst --- a/Doc/tutorial/classes.rst Sun Oct 02 22:00:05 2016 +0300 +++ b/Doc/tutorial/classes.rst Mon Oct 03 20:43:34 2016 +0530 @@ -833,7 +833,7 @@ 'c' >>> next(it) Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in next(it) StopIteration diff -r 36b052adf5a7 Doc/tutorial/controlflow.rst --- a/Doc/tutorial/controlflow.rst Sun Oct 02 22:00:05 2016 +0300 +++ b/Doc/tutorial/controlflow.rst Mon Oct 03 20:43:34 2016 +0530 @@ -475,7 +475,7 @@ ... >>> function(0, a=0) Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in TypeError: function() got multiple values for keyword argument 'a' When a final formal parameter of the form ``**name`` is present, it receives a diff -r 36b052adf5a7 Doc/tutorial/datastructures.rst --- a/Doc/tutorial/datastructures.rst Sun Oct 02 22:00:05 2016 +0300 +++ b/Doc/tutorial/datastructures.rst Mon Oct 03 20:43:34 2016 +0530 @@ -258,7 +258,7 @@ [(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25)] >>> # the tuple must be parenthesized, otherwise an error is raised >>> [x, x**2 for x in range(6)] - File "", line 1, in ? + File "", line 1, in [x, x**2 for x in range(6)] ^ SyntaxError: invalid syntax diff -r 36b052adf5a7 Doc/tutorial/inputoutput.rst --- a/Doc/tutorial/inputoutput.rst Sun Oct 02 22:00:05 2016 +0300 +++ b/Doc/tutorial/inputoutput.rst Mon Oct 03 20:43:34 2016 +0530 @@ -362,7 +362,7 @@ >>> f.close() >>> f.read() Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ValueError: I/O operation on closed file It is good practice to use the :keyword:`with` keyword when dealing with file