[Python-checkins] CVS: python/dist/src/Doc/lib libdoctest.tex,1.1,1.2
Fred L. Drake
fdrake@users.sourceforge.net
Sat, 17 Feb 2001 09:32:44 -0800
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv29006/lib
Modified Files:
libdoctest.tex
Log Message:
Make a variety of minor markup adjustments.
Close some environments so that this will actually format.
Index: libdoctest.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -r1.1 -r1.2
*** libdoctest.tex 2001/02/17 05:58:44 1.1
--- libdoctest.tex 2001/02/17 17:32:41 1.2
***************
*** 95,100 ****
There's no output! That's normal, and it means all the examples worked.
! Pass \code{-v} to the script, and doctest prints a detailed log of what it's
! trying, and prints a summary at the end:
\begin{verbatim}
--- 95,100 ----
There's no output! That's normal, and it means all the examples worked.
! Pass \programopt{-v} to the script, and doctest prints a detailed log
! of what it's trying, and prints a summary at the end:
\begin{verbatim}
***************
*** 162,168 ****
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 \code{"Test failed."}.
! Run it with the \code{-v} switch instead:
\begin{verbatim}
--- 162,168 ----
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 \code{'Test failed.'}.
! Run it with the \programopt{-v} switch instead:
\begin{verbatim}
***************
*** 170,183 ****
\end{verbatim}
! and a detailed report of all examples tried is printed to \var{stdout},
along with assorted summaries at the end.
You can force verbose mode by passing \code{verbose=1} to testmod, or
prohibit it by passing \code{verbose=0}. In either of those cases,
! \var{sys.argv} is not examined by testmod.
! In any case, testmod returns a 2-tuple of ints \var{(f, t)}, where \var{f}
! is the number of docstring examples that failed and \var{t} is the total
! number of docstring examples attempted.
\subsection{Which Docstrings Are Examined?}
--- 170,184 ----
\end{verbatim}
! and a detailed report of all examples tried is printed to \code{stdout},
along with assorted summaries at the end.
You can force verbose mode by passing \code{verbose=1} to testmod, or
prohibit it by passing \code{verbose=0}. In either of those cases,
! \code{sys.argv} is not examined by testmod.
! In any case, testmod returns a 2-tuple of ints \code{(\var{f},
! \var{t})}, where \var{f} is the number of docstring examples that
! failed and \var{t} is the total number of docstring examples
! attempted.
\subsection{Which Docstrings Are Examined?}
***************
*** 188,197 ****
names.
! In addition, if \var{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 \var{M.__test__}
! are searched even if the name is private, and strings are searched directly
! as if they were docstrings. In output, a key \var{K} in \var{M.__test__}
! appears with name
\begin{verbatim}
--- 189,198 ----
names.
! In addition, if \code{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
! \code{M.__test__} are searched even if the name is private, and
! strings are searched directly as if they were docstrings. In output,
! a key \code{K} in \code{M.__test__} appears with name
\begin{verbatim}
***************
*** 202,206 ****
their contained methods and nested classes. While private names reached
from \module{M}'s globals are skipped, all names reached from
! \var{M.__test__} are searched.
\subsection{What's the Execution Context?}
--- 203,207 ----
their contained methods and nested classes. While private names reached
from \module{M}'s globals are skipped, all names reached from
! \code{M.__test__} are searched.
\subsection{What's the Execution Context?}
***************
*** 217,221 ****
You can force use of your own dict as the execution context by passing
\code{globs=your_dict} to \function{testmod()} instead. Presumably this
! would be a copy of \var{M.__dict__} merged with the globals from other
imported modules.
--- 218,222 ----
You can force use of your own dict as the execution context by passing
\code{globs=your_dict} to \function{testmod()} instead. Presumably this
! would be a copy of \code{M.__dict__} merged with the globals from other
imported modules.
***************
*** 234,238 ****
Note that only the exception type and value are compared (specifically,
! only the last line in the traceback). The various \code{"File"} lines in
between can be left out (unless they add significantly to the documentation
value of the example).
--- 235,239 ----
Note that only the exception type and value are compared (specifically,
! only the last line in the traceback). The various ``File'' lines in
between can be left out (unless they add significantly to the documentation
value of the example).
***************
*** 241,250 ****
\function{testmod()} actually creates a local instance of class
! \class{doctest.Tester}, runs appropriate methods of that class, and merges
! the results into global \class{Tester} instance \var{doctest.master}.
! You can create your own instances of \class{doctest.Tester}, and so build
! your own policies, or even run methods of \var{doctest.master} directly.
! See \var{doctest.Tester.__doc__} for details.
--- 242,251 ----
\function{testmod()} actually creates a local instance of class
! \class{Tester}, runs appropriate methods of that class, and merges
! the results into global \class{Tester} instance \code{master}.
! You can create your own instances of \class{Tester}, and so build your
! own policies, or even run methods of \code{master} directly. See
! \code{Tester.__doc__} for details.
***************
*** 276,280 ****
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. That's it.
The fine print:
--- 277,281 ----
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.
The fine print:
***************
*** 305,315 ****
\begin{verbatim}
>>> assert "Easy!"
! >>> import math
! >>> math.floor(1.9)
! 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.
\subsection{Warnings}
--- 306,317 ----
\begin{verbatim}
>>> assert "Easy!"
! >>> import math
! >>> math.floor(1.9)
! 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.
+ \end{itemize}
\subsection{Warnings}
***************
*** 323,331 ****
\end{verbatim}
! then \class{XYZclass} is a name in \var{M.__dict__} too, and doctest has no
! way to know that \class{XYZclass} wasn't *defined* in \module{M}. So it may
! try to execute the examples in \class{XYZclass}'s docstring, and those in
! turn may require a different set of globals to work correctly. I prefer to
! do \code{import *}- friendly imports, a la
\begin{verbatim}
--- 325,334 ----
\end{verbatim}
! then \class{XYZclass} is a name in \code{M.__dict__} too, and doctest
! has no way to know that \class{XYZclass} wasn't \emph{defined} in
! \module{M}. So it may try to execute the examples in
! \class{XYZclass}'s docstring, and those in turn may require a
! different set of globals to work correctly. I prefer to do
! ``\code{import *}''-friendly imports, a la
\begin{verbatim}
***************
*** 401,404 ****
--- 404,408 ----
Simple fractions are also easier for people to understand, and that makes
for better documentation.
+ \end{enumerate}
***************
*** 426,428 ****
For exhaustive testing, or testing boring cases that add no value to the
! docs, define a \var{__test__} dict instead. That's what it's for.
--- 430,432 ----
For exhaustive testing, or testing boring cases that add no value to the
! docs, define a \code{__test__} dict instead. That's what it's for.