From b2b26aca13119a0ad134342aca9e7a9bb27e7ffa Mon Sep 17 00:00:00 2001 From: Tim Peters Date: Sat, 25 Sep 2004 01:51:49 +0000 Subject: [PATCH] Repaired mistakes in the descriptions of testmod()/testfile(), and squashed massive duplication of common argument descriptions. --- Doc/lib/libdoctest.tex | 61 +++++++++++------------------------------- 1 file changed, 16 insertions(+), 45 deletions(-) diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex index 1dab55f437d..3fbe8841788 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}