mirror of
https://github.com/python/cpython.git
synced 2024-11-25 19:03:49 +08:00
Work around the broken formatting of sys.ps1 prompts in running text.
Move sample sessions to the left margin of the file for consistency; formatting can adjust the margin if needed. This closes SF bug #133213.
This commit is contained in:
parent
2f55b11bf7
commit
19f3c52347
@ -226,11 +226,11 @@ No problem, as long as the only output generated by the example is the
|
||||
traceback itself. For example:
|
||||
|
||||
\begin{verbatim}
|
||||
>>> [1, 2, 3].remove(42)
|
||||
Traceback (most recent call last):
|
||||
File "<stdin>", line 1, in ?
|
||||
ValueError: list.remove(x): x not in list
|
||||
>>>
|
||||
>>> [1, 2, 3].remove(42)
|
||||
Traceback (most recent call last):
|
||||
File "<stdin>", line 1, in ?
|
||||
ValueError: list.remove(x): x not in list
|
||||
>>>
|
||||
\end{verbatim}
|
||||
|
||||
Note that only the exception type and value are compared (specifically,
|
||||
@ -257,26 +257,27 @@ tabs and spaces if you're too lazy to do it right, but doctest is not in
|
||||
the business of guessing what you think a tab means).
|
||||
|
||||
\begin{verbatim}
|
||||
>>> # comments are ignored
|
||||
>>> x = 12
|
||||
>>> x
|
||||
12
|
||||
>>> if x == 13:
|
||||
... print "yes"
|
||||
... else:
|
||||
... print "no"
|
||||
... print "NO"
|
||||
... print "NO!!!"
|
||||
...
|
||||
no
|
||||
NO
|
||||
NO!!!
|
||||
>>>
|
||||
>>> # comments are ignored
|
||||
>>> x = 12
|
||||
>>> x
|
||||
12
|
||||
>>> if x == 13:
|
||||
... print "yes"
|
||||
... else:
|
||||
... print "no"
|
||||
... print "NO"
|
||||
... print "NO!!!"
|
||||
...
|
||||
no
|
||||
NO
|
||||
NO!!!
|
||||
>>>
|
||||
\end{verbatim}
|
||||
|
||||
Any expected output must immediately follow the final \code{">>>"} or
|
||||
\code{"..."} line containing the code, and the expected output (if any)
|
||||
extends to the next \code{">>>"} or all-whitespace line.
|
||||
Any expected output must immediately follow the final
|
||||
\code{'>\code{>}>~'} or \code{'...~'} line containing the code, and
|
||||
the expected output (if any) extends to the next \code{'>\code{>}>~'}
|
||||
or all-whitespace line.
|
||||
|
||||
The fine print:
|
||||
|
||||
@ -310,8 +311,9 @@ yes
|
||||
1.0
|
||||
\end{verbatim}
|
||||
|
||||
and as many leading whitespace characters are stripped from the expected
|
||||
output as appeared in the initial ">>>" line that triggered it.
|
||||
and as many leading whitespace characters are stripped from the
|
||||
expected output as appeared in the initial \code{'>\code{>}>~'} line
|
||||
that triggered it.
|
||||
\end{itemize}
|
||||
|
||||
\subsection{Warnings}
|
||||
@ -349,26 +351,26 @@ testmod skips it by default. Other approaches are described in
|
||||
% Hey! What happened to Monty Python examples?
|
||||
% Tim: ask Guido -- it's his example!
|
||||
\begin{verbatim}
|
||||
>>> foo()
|
||||
{"Hermione": "hippogryph", "Harry": "broomstick"}
|
||||
>>>
|
||||
>>> foo()
|
||||
{"Hermione": "hippogryph", "Harry": "broomstick"}
|
||||
>>>
|
||||
\end{verbatim}
|
||||
|
||||
is vulnerable! One workaround is to do
|
||||
|
||||
\begin{verbatim}
|
||||
>>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
|
||||
1
|
||||
>>>
|
||||
>>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
|
||||
1
|
||||
>>>
|
||||
\end{verbatim}
|
||||
|
||||
instead. Another is to do
|
||||
|
||||
\begin{verbatim}
|
||||
>>> d = foo().items()
|
||||
>>> d.sort()
|
||||
>>> d
|
||||
[('Harry', 'broomstick'), ('Hermione', 'hippogryph')]
|
||||
>>> d = foo().items()
|
||||
>>> d.sort()
|
||||
>>> d
|
||||
[('Harry', 'broomstick'), ('Hermione', 'hippogryph')]
|
||||
\end{verbatim}
|
||||
|
||||
There are others, but you get the idea.
|
||||
@ -376,9 +378,9 @@ There are others, but you get the idea.
|
||||
Another bad idea is to print things that embed an object address, like
|
||||
|
||||
\begin{verbatim}
|
||||
>>> id(1.0) # certain to fail some of the time
|
||||
7948648
|
||||
>>>
|
||||
>>> id(1.0) # certain to fail some of the time
|
||||
7948648
|
||||
>>>
|
||||
\end{verbatim}
|
||||
|
||||
Floating-point numbers are also subject to small output variations across
|
||||
@ -386,20 +388,20 @@ platforms, because Python defers to the platform C library for float
|
||||
formatting, and C libraries vary widely in quality here.
|
||||
|
||||
\begin{verbatim}
|
||||
>>> 1./7 # risky
|
||||
0.14285714285714285
|
||||
>>> print 1./7 # safer
|
||||
0.142857142857
|
||||
>>> print round(1./7, 6) # much safer
|
||||
0.142857
|
||||
>>> 1./7 # risky
|
||||
0.14285714285714285
|
||||
>>> print 1./7 # safer
|
||||
0.142857142857
|
||||
>>> print round(1./7, 6) # much safer
|
||||
0.142857
|
||||
\end{verbatim}
|
||||
|
||||
Numbers of the form \code{I/2.**J} are safe across all platforms, and I
|
||||
often contrive doctest examples to produce numbers of that form:
|
||||
|
||||
\begin{verbatim}
|
||||
>>> 3./4 # utterly safe
|
||||
0.75
|
||||
>>> 3./4 # utterly safe
|
||||
0.75
|
||||
\end{verbatim}
|
||||
|
||||
Simple fractions are also easier for people to understand, and that makes
|
||||
|
Loading…
Reference in New Issue
Block a user