summaryrefslogtreecommitdiffstats
path: root/Doc/lib
diff options
context:
space:
mode:
authorTim Peters <tim.peters@gmail.com>2004-09-25 01:51:49 (GMT)
committerTim Peters <tim.peters@gmail.com>2004-09-25 01:51:49 (GMT)
commitb2b26aca13119a0ad134342aca9e7a9bb27e7ffa (patch)
treece1ec2410dc59c8200693310872bb199f9d3dd52 /Doc/lib
parent35ae3dd5aad3c2c19393aa0b0b349a211f6d0d7b (diff)
downloadcpython-b2b26aca13119a0ad134342aca9e7a9bb27e7ffa.zip
cpython-b2b26aca13119a0ad134342aca9e7a9bb27e7ffa.tar.gz
cpython-b2b26aca13119a0ad134342aca9e7a9bb27e7ffa.tar.bz2
Repaired mistakes in the descriptions of testmod()/testfile(), and
squashed massive duplication of common argument descriptions.
Diffstat (limited to 'Doc/lib')
-rw-r--r--Doc/lib/libdoctest.tex61
1 files changed, 16 insertions, 45 deletions
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex
index 1dab55f..3fbe884 100644
--- a/Doc/lib/libdoctest.tex
+++ b/Doc/lib/libdoctest.tex
@@ -790,7 +790,7 @@ for better documentation.
The functions \function{testmod()} and \function{testfile()} provide a
simple interface to doctest that should be sufficient for most basic
-uses. For a more informal introduction to these two functions, see
+uses. For a less formal introduction to these two functions, see
sections \ref{doctest-simple-testmod} and
\ref{doctest-simple-testfile}.
@@ -811,15 +811,15 @@ sections \ref{doctest-simple-testmod} and
\begin{itemize}
\item If \var{module_relative} is \code{True} (the default), then
- \var{filename} specifies an os-independent module-relative
+ \var{filename} specifies an OS-independent module-relative
path. By default, this path is relative to the calling
module's directory; but if the \var{package} argument is
specified, then it is relative to that package. To ensure
- os-independence, \var{filename} should use \code{/} characters
+ OS-independence, \var{filename} should use \code{/} characters
to separate path segments, and may not be an absolute path
(i.e., it may not begin with \code{/}).
\item If \var{module_relative} is \code{False}, then \var{filename}
- specifies an os-specific path. The path may be absolute or
+ specifies an OS-specific path. The path may be absolute or
relative; relative paths are resolved with respect to the
current working directory.
\end{itemize}
@@ -835,9 +835,9 @@ sections \ref{doctest-simple-testmod} and
if \var{module_relative} is \code{False}.
Optional argument \var{globs} gives a dict to be used as the globals
- when executing examples; by default, or if \code{None},
- \code{\var{m}.__dict__} is used. A new shallow copy of this dict is
+ when executing examples. A new shallow copy of this dict is
created for the doctest, so its examples start with a clean slate.
+ By default, or if \code{None}, a new empty dict is used.
Optional argument \var{extraglobs} gives a dict merged into the
globals used to execute examples. This works like
@@ -880,8 +880,8 @@ sections \ref{doctest-simple-testmod} and
specified in keyword form.
Test examples in docstrings in functions and classes reachable
- from module \var{m} (or the current module if \var{m} is not supplied
- or is \code{None}), starting with \code{\var{m}.__doc__}.
+ from module \var{m} (or module \module{__main__} if \var{m} is not
+ supplied or is \code{None}), starting with \code{\var{m}.__doc__}.
Also test examples reachable from dict \code{\var{m}.__test__}, if it
exists and is not \code{None}. \code{\var{m}.__test__} maps
@@ -897,40 +897,6 @@ sections \ref{doctest-simple-testmod} and
Optional argument \var{name} gives the name of the module; by default,
or if \code{None}, \code{\var{m}.__name__} is used.
- Optional argument \var{globs} gives a dict to be used as the globals
- when executing examples; by default, or if \code{None},
- \code{\var{m}.__dict__} is used. A new shallow copy of this dict is
- created for each docstring with examples, so that each docstring's
- examples start with a clean slate.
-
- Optional argument \var{extraglobs} gives a dict merged into the
- globals used to execute examples. This works like
- \method{dict.update()}: if \var{globs} and \var{extraglobs} have a
- common key, the associated value in \var{extraglobs} appears in the
- combined dict. By default, or if \code{None}, no extra globals are
- used. This is an advanced feature that allows parameterization of
- doctests. For example, a doctest can be written for a base class, using
- a generic name for the class, then reused to test any number of
- subclasses by passing an \var{extraglobs} dict mapping the generic
- name to the subclass to be tested.
-
- Optional argument \var{verbose} prints lots of stuff if true, and prints
- only failures if false; by default, or if \code{None}, it's true
- if and only if \code{'-v'} is in \code{sys.argv}.
-
- Optional argument \var{report} prints a summary at the end when true,
- else prints nothing at the end. In verbose mode, the summary is
- detailed, else the summary is very brief (in fact, empty if all tests
- passed).
-
- Optional argument \var{optionflags} or's together option flags. See
- see section~\ref{doctest-options}.
-
- Optional argument \var{raise_on_error} defaults to false. If true,
- an exception is raised upon the first failure or unexpected exception
- in an example. This allows failures to be post-mortem debugged.
- Default behavior is to continue running examples.
-
Optional argument \var{exclude_empty} defaults to false. If true,
objects for which no doctests are found are excluded from consideration.
The default is a backward compatibility hack, so that code still
@@ -939,6 +905,11 @@ sections \ref{doctest-simple-testmod} and
The \var{exclude_empty} argument to the newer \class{DocTestFinder}
constructor defaults to true.
+ Optional arguments \var{extraglobs}, \var{verbose}, \var{report},
+ \var{optionflags}, \var{raise_on_error}, and \var{globs} are the same as
+ for function \function{testfile()} above, except that \var{globs}
+ defaults to \code{\var{m}.__dict__}.
+
Optional argument \var{isprivate} specifies a function used to
determine whether a name is private. The default function treats
all names as public. \var{isprivate} can be set to
@@ -988,15 +959,15 @@ suites can then be run using \module{unittest} test runners:
\begin{itemize}
\item If \var{module_relative} is \code{True} (the default), then
- each filename specifies an os-independent module-relative
+ each filename specifies an OS-independent module-relative
path. By default, this path is relative to the calling
module's directory; but if the \var{package} argument is
specified, then it is relative to that package. To ensure
- os-independence, each filename should use \code{/} characters
+ OS-independence, each filename should use \code{/} characters
to separate path segments, and may not be an absolute path
(i.e., it may not begin with \code{/}).
\item If \var{module_relative} is \code{False}, then each filename
- specifies an os-specific path. The path may be absolute or
+ specifies an OS-specific path. The path may be absolute or
relative; relative paths are resolved with respect to the
current working directory.
\end{itemize}