mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-24 11:44:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

gh-80856: doc: reveal doctest directives (#92318)

Browse source 
* Doc: Reveal doctest directives.

* Fix whitespace.

Co-authored-by: Julien Palard <julien@palard.fr>
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
This commit is contained in:
Davide Rizzo 2022-05-08 18:14:55 +02:00 • committed by GitHub
parent 5c3ecddad7
commit 7b024e3a3f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 37 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

54
Doc/library/doctest.rst
View file

@ -714,36 +714,51 @@ above.
An example's doctest directives modify doctest's behavior for that single
example. Use ``+`` to enable the named behavior, or ``-`` to disable it.
For example, this test passes::
For example, this test passes:
>>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE
.. doctest::
:no-trim-doctest-flags:
>>> 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]
Without the directive it would fail, both because the actual output doesn't have
two blanks before the single-digit list elements, and because the actual output
is on a single line. This test also passes, and also requires a directive to do
so::
so:
>>> print(list(range(20))) # doctest: +ELLIPSIS
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(20))) # doctest: +ELLIPSIS
[0, 1, ..., 18, 19]
Multiple directives can be used on a single physical line, separated by
commas::
commas:
>>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
[0, 1, ..., 18, 19]
If multiple directive comments are used for a single example, then they are
combined::
combined:
>>> print(list(range(20))) # doctest: +ELLIPSIS
... # doctest: +NORMALIZE_WHITESPACE
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(20))) # doctest: +ELLIPSIS
... # doctest: +NORMALIZE_WHITESPACE
[0, 1, ..., 18, 19]
As the previous example shows, you can add ``...`` lines to your example
containing only directives. This can be useful when an example is too long for
a directive to comfortably fit on the same line::
a directive to comfortably fit on the same line:
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
... # doctest: +ELLIPSIS
@ -783,18 +798,23 @@ instead. Another is to do ::
There are others, but you get the idea.
Another bad idea is to print things that embed an object address, like ::
Another bad idea is to print things that embed an object address, like
>>> id(1.0) # certain to fail some of the time
.. doctest::
>>> id(1.0) # certain to fail some of the time # doctest: +SKIP
7948648
>>> class C: pass
>>> C() # the default repr() for instances embeds an address
<__main__.C instance at 0x00AC18F0>
>>> C() # the default repr() for instances embeds an address # doctest: +SKIP
<C object at 0x00AC18F0>
The :const:`ELLIPSIS` directive gives a nice approach for the last example::
The :const:`ELLIPSIS` directive gives a nice approach for the last example:
>>> C() #doctest: +ELLIPSIS
<__main__.C instance at 0x...>
.. doctest::
:no-trim-doctest-flags:
>>> C() # doctest: +ELLIPSIS
<C object at 0x...>
Floating-point numbers are also subject to small output variations across
platforms, because Python defers to the platform C library for float formatting,