FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

gh-80856: doc: reveal doctest directives by sorcio · Pull Request #92318 · python/cpython · GitHub

/ cpython Public

gh-80856: doc: reveal doctest directives #92318

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ezio-melotti merged 2 commits into from
May 8, 2022
Conversation 10 Commits 2 Checks 0 Files changed
Merged

gh-80856: doc: reveal doctest directives #92318

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4935784
Doc: Reveal doctest directives.
JulienPalard Dec 2, 2020
8e10cd7
Fix whitespace.
ezio-melotti May 7, 2022
File filter

Filter by extension

Filter by extension .rst  (1) All 1 file type selected
Viewed files
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Unified
Split
Hide whitespace
Diff view
Unified
Split
Hide whitespace
54 changes: 37 additions & 17 deletions Doc/library/doctest.rst
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -718,36 +718,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:

.. doctest::
:no-trim-doctest-flags:

>>> print(list(range(20))) # doctest: +ELLIPSIS
>>> 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:

.. doctest::
:no-trim-doctest-flags:

>>> print(list(range(20))) # doctest: +ELLIPSIS
... # doctest: +NORMALIZE_WHITESPACE
>>> 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
Expand Down Expand Up @@ -792,18 +807,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

.. doctest::

>>> id(1.0) # certain to fail some of the time
>>> 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::
.. doctest::
:no-trim-doctest-flags:

>>> C() #doctest: +ELLIPSIS
<__main__.C instance at 0x...>
>>> 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,
Expand Down
Back | FazBrowse Home | New Git URL