Mailman 3 September 2004 - Python-checkins

python/dist/src/Lib doctest.py,1.110,1.111
by tim_one＠users.sourceforge.net Sept. 26, 2004

Sept. 26, 2004

Update of /cvsroot/python/python/dist/src/Lib In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv20970/Lib Modified Files: doctest.py Log Message: Removed two undocumented unittest support classes, and one undocumented unittest support function, from the public interface. If they're not documented, they shouldn't be public. Index: doctest.py =================================================================== RCS file: /cvsroot/python/python/dist/src/Lib/doctest.py,v retrieving revision 1.110 retrieving revision 1.111 diff -u -d -r1.110 -r1.111 --- doctest.py 25 Sep 2004 02:41:28 -0000 1.110 +++ doctest.py 26 Sep 2004 01:24:23 -0000 1.111 @@ -83,10 +83,7 @@ # 7. Tester 'Tester', # 8. Unittest Support - 'DocTestCase', 'DocTestSuite', - 'DocFileCase', - 'DocFileTest', 'DocFileSuite', # 9. Debugging Support 'script_from_examples',

1 0

python/dist/src/Doc/lib libdoctest.tex,1.52,1.53
by rhettinger＠users.sourceforge.net Sept. 25, 2004

Sept. 25, 2004

Update of /cvsroot/python/python/dist/src/Doc/lib In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv16722 Modified Files: libdoctest.tex Log Message: Fix double word error. Index: libdoctest.tex =================================================================== RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v retrieving revision 1.52 retrieving revision 1.53 diff -u -d -r1.52 -r1.53 --- libdoctest.tex 25 Sep 2004 03:50:35 -0000 1.52 +++ libdoctest.tex 25 Sep 2004 08:09:23 -0000 1.53 @@ -967,7 +967,7 @@ Options may be provided as keyword arguments: Optional argument \var{module_relative} specifies how - the the filenames in \var{paths} should be interpreted: + the filenames in \var{paths} should be interpreted: \begin{itemize} \item If \var{module_relative} is \code{True} (the default), then

1 0

python/dist/src/Doc/lib libdoctest.tex,1.51,1.52
by tim_one＠users.sourceforge.net Sept. 25, 2004

Sept. 25, 2004

Update of /cvsroot/python/python/dist/src/Doc/lib In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv9212/Doc/lib Modified Files: libdoctest.tex Log Message: Assorted minor changes, plus a lot more soap. Index: libdoctest.tex =================================================================== RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v retrieving revision 1.51 retrieving revision 1.52 diff -u -d -r1.51 -r1.52 --- libdoctest.tex 25 Sep 2004 03:02:23 -0000 1.51 +++ libdoctest.tex 25 Sep 2004 03:50:35 -0000 1.52 @@ -1090,7 +1090,7 @@ they match. \end{itemize} -The relationship between these processing classes is summarized in the +The relationships among these processing classes are summarized in the following diagram: \begin{verbatim} @@ -1099,7 +1099,7 @@ |module| --DocTestFinder-> | DocTest | --DocTestRunner-> results +------+ | ^ +---------+ | ^ (printed) | | | Example | | | - V | | ... | V | + v | | ... | v | DocTestParser | Example | OutputChecker +---------+ \end{verbatim} @@ -1196,7 +1196,7 @@ \end{memberdesc} \begin{memberdesc}{indent} - The example's indentation in the containing string. I.e., the + The example's indentation in the containing string, i.e., the number of space characters that preceed the example's first prompt. \end{memberdesc} @@ -1206,8 +1206,8 @@ \code{False}, which is used to override default options for this example. Any option flags not contained in this dictionary are left at their default value (as specified by the - \class{DocTestRunner}'s -\member{optionflags}). By default, no options are set. + \class{DocTestRunner}'s \member{optionflags}). + By default, no options are set. \end{memberdesc} \subsubsection{DocTestFinder objects\label{doctest-DocTestFinder}} @@ -1250,7 +1250,7 @@ The optional argument \var{name} specifies the object's name; this name will be used to construct names for the returned \class{DocTest}s. If \var{name} is not specified, then - \code{var.__name__} is used. + \code{\var{obj}.__name__} is used. The optional parameter \var{module} is the module that contains the given object. If the module is not specified or is None, then @@ -1258,7 +1258,7 @@ correct module. The object's module is used: \begin{itemize} - \item As a default namespace, if `globs` is not specified. + \item As a default namespace, if \var{globs} is not specified. \item To prevent the DocTestFinder from extracting DocTests from objects that are imported from other modules. (Contained objects with modules other than \var{module} are ignored.) @@ -1275,7 +1275,7 @@ The globals for each \class{DocTest} is formed by combining \var{globs} and \var{extraglobs} (bindings in \var{extraglobs} - override bindings in \var{globs}). A new copy of the globals + override bindings in \var{globs}). A new shallow copy of the globals dictionary is created for each \class{DocTest}. If \var{globs} is not specified, then it defaults to the module's \var{__dict__}, if specified, or \code{\{\}} otherwise. If \var{extraglobs} is not @@ -1577,15 +1577,16 @@ \subsection{Soapbox\label{doctest-soapbox}} -As mentioned in the introduction, \module{doctest} has two primary -uses: +As mentioned in the introduction, \module{doctest} has grown to have +three primary uses: \begin{enumerate} \item Checking examples in docstrings. \item Regression testing. +\item Executable documentation / literate testing. \end{enumerate} -These two uses have different requirements, and it is important to +These uses have different requirements, and it is important to distinguish them. In particular, filling your docstrings with obscure test cases makes for bad documentation. @@ -1593,39 +1594,44 @@ There's an art to this that needs to be learned---it may not be natural at first. Examples should add genuine value to the documentation. A good example can often be worth many words. -% [edloper] I think this may be excessive for many cases; let's -% just leave it to the user's judgement: -%% If possible, show just a few normal cases, show endcases, show -%% interesting subtle cases, and show an example of each kind of -%% exception that can be raised. You're probably testing for endcases -%% and subtle cases anyway in an interactive shell: -%% \refmodule{doctest} wants to make it as easy as possible to capture -%% those sessions, and will verify they continue to work as designed -%% forever after. If done with care, the examples will be invaluable for your users, and will pay back the time it takes to collect them many times over as the years go by and things change. I'm still amazed at how often one of -my \refmodule{doctest} examples stops working after a ``harmless'' +my \refmodule{doctest} examples stops working after a "harmless" change. -Doctest also makes an excellent tool for writing regression testing. -By interleaving prose and examples, it becomes much easier to keep -track of what's actually being tested, and why. When a test fails, -the prose descriptions makes it much easier to figure out what the -problem is, and how it should be fixed. Regression testing is best -confined to dedicated objects or files. There are several options for -organizing regressions: +Doctest also makes an excellent tool for regression testing, especially if +you don't skimp on explanatory text. By interleaving prose and examples, +it becomes much easier to keep track of what's actually being tested, and +why. When a test fails, good prose can make it much easier to figure out +what the problem is, and how it should be fixed. It's true that you could +write extensive comments in code-based testing, but few programmers do. +Many have found that using doctest approaches instead leads to much clearer +tests. Perhaps this is simply because doctest makes writing prose a little +easier than writing code, while writing comments in code is a little +harder. I think it goes deeper than just that: the natural attitude +when writing a doctest-based test is that you want to explain the fine +points of your software, and illustrate them with examples. This in +turn naturally leads to test files that start with the simplest features, +and logically progress to complications and edge cases. A coherent +narrative is the result, instead of a collection of isolated functions +that test isolated bits of functionality seemingly at random. It's +a different attitude, and produces different results, blurring the +distinction between testing and explaining. + +Regression testing is best confined to dedicated objects or files. There +are several options for organizing tests: \begin{itemize} +\item Write text files containing test cases as interactive examples, + and test the files using \function{testfile()} or + \function{DocFileSuite()}. This is recommended, although is + easiest to do for new projects, designed from the start to use + doctest. \item Define functions named \code{_regrtest_\textit{topic}} that consist of single docstrings, containing test cases for the named topics. These functions can be included in the same file as the module, or separated out into a separate test file. \item Define a \code{__test__} dictionary mapping from regression test topics to docstrings containing test cases. -\item Write a text file containing test cases as interactive examples, - and test that file using \function{testfunc()}. \end{itemize} - - -

1 0

python/dist/src/Doc/lib libdoctest.tex,1.50,1.51
by tim_one＠users.sourceforge.net Sept. 25, 2004

Sept. 25, 2004

Update of /cvsroot/python/python/dist/src/Doc/lib In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv947/Doc/lib Modified Files: libdoctest.tex Log Message: Explain the motivation for the unittest functions, and beef up the example. Squash repeated argument descriptions. Minor rewordings. Index: libdoctest.tex =================================================================== RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v retrieving revision 1.50 retrieving revision 1.51 diff -u -d -r1.50 -r1.51 --- libdoctest.tex 25 Sep 2004 01:51:49 -0000 1.50 +++ libdoctest.tex 25 Sep 2004 03:02:23 -0000 1.51 @@ -860,7 +860,7 @@ passed). Optional argument \var{optionflags} or's together option flags. See - see section~\ref{doctest-options}. + 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 @@ -927,34 +927,46 @@ \subsection{Unittest API\label{doctest-unittest-api}} -Doctest provides several functions that can be used to create -\module{unittest} test suites from doctest examples. These test -suites can then be run using \module{unittest} test runners: +As your collection of doctest'ed modules grows, you'll want a way to run +all their doctests systematically. Prior to Python 2.4, \module{doctest} +had a barely documented \class{Tester} class that supplied a rudimentary +way to combine doctests from multiple modules. \class{Tester} was feeble, +and in practice most serious Python testing frameworks build on the +\module{unittest} module, which supplies many flexible ways to combine +tests from multiple sources. So, in Python 2.4, module{doctest}'s +\class{Tester} class is deprecated, and \module{doctest} provides several +functions that can be used to create \module{unittest} test suites from +modules and text files containing doctests. These test suites can then be +run using \module{unittest} test runners: \begin{verbatim} - import unittest - import doctest - import my_module_with_doctests +import unittest +import doctest +import my_module_with_doctests, and_another - suite = doctest.DocTestSuite(my_module_with_doctests) - runner = unittest.TextTestRunner() - runner.run(suite) +suite = unittest.TestSuite() +for mod in my_module_with_doctests, and_another: + suite.addTest(doctest.DocTestSuite(mod)) +runner = unittest.TextTestRunner() +runner.run(suite) \end{verbatim} \begin{funcdesc}{DocFileSuite}{*paths, **kw} Convert doctest tests from one or more text files to a \class{\refmodule{unittest}.TestSuite}. - The returned \class{TestSuite} is to be run by the unittest + The returned \class{unittest.TestSuite} is to be run by the unittest framework and runs the interactive examples in each file. If an example in any file fails, then the synthesized unit test fails, and a \exception{failureException} exception is raised showing the name of the file containing the test and a (sometimes approximate) line number. - A number of options may be provided as keyword arguments: + Pass one or more paths (as strings) to text files to be examined. - The optional argument \var{module_relative} specifies how + Options may be provided as keyword arguments: + + Optional argument \var{module_relative} specifies how the the filenames in \var{paths} should be interpreted: \begin{itemize} @@ -972,33 +984,33 @@ current working directory. \end{itemize} - The optional argument \var{package} is a Python package or the name + Optional argument \var{package} is a Python package or the name of a Python package whose directory should be used as the base directory for module-relative filenames. If no package is specified, then the calling module's directory is used as the base directory for module-relative filenames. It is an error to specify \var{package} if \var{module_relative} is \code{False}. - The optional argument \var{setUp} specifies a set-up function for + Optional argument \var{setUp} specifies a set-up function for the test suite. This is called before running the tests in each file. The \var{setUp} function will be passed a \class{DocTest} object. The setUp function can access the test globals as the \var{globs} attribute of the test passed. - The optional argument \var{tearDown} specifies a tear-down function + Optional argument \var{tearDown} specifies a tear-down function for the test suite. This is called after running the tests in each file. The \var{tearDown} function will be passed a \class{DocTest} object. The setUp function can access the test globals as the \var{globs} attribute of the test passed. - The optional argument \var{globs} is a dictionary containing the + Optional argument \var{globs} is a dictionary containing the initial global variables for the tests. A new copy of this dictionary is created for each test. By default, \var{globs} is - empty. + a new empty dictionary. - The optional argument \var{optionflags} specifies the default - doctest options for the tests. It is created by or-ing together - individual option flags. + Optional argument \var{optionflags} specifies the default + doctest options for the tests, created by or-ing together + individual option flags. See section~\ref{doctest-options}. \versionadded{2.4} \end{funcdesc} @@ -1010,58 +1022,44 @@ Convert doctest tests for a module to a \class{\refmodule{unittest}.TestSuite}. - The returned \class{TestSuite} is to be run by the unittest framework - and runs each doctest in the module. If any of the doctests fail, - then the synthesized unit test fails, and a \exception{failureException} - exception is raised showing the name of the file containing the test and a - (sometimes approximate) line number. + The returned \class{unittest.TestSuite} is to be run by the unittest + framework and runs each doctest in the module. If any of the doctests + fail, then the synthesized unit test fails, and a + \exception{failureException} exception is raised showing the name of the + file containing the test and a (sometimes approximate) line number. - The optional argument \var{module} provides the module to be tested. It + Optional argument \var{module} provides the module to be tested. It can be a module object or a (possibly dotted) module name. If not specified, the module calling this function is used. - The optional argument \var{globs} is a dictionary containing the + Optional argument \var{globs} is a dictionary containing the initial global variables for the tests. A new copy of this dictionary is created for each test. By default, \var{globs} is - empty. + a new empty dictionary. - The optional argument \var{extraglobs} specifies an extra set of + Optional argument \var{extraglobs} specifies an extra set of global variables, which is merged into \var{globs}. By default, no extra globals are used. - The optional argument \var{test_finder} is the \class{DocTestFinder} + Optional argument \var{test_finder} is the \class{DocTestFinder} object (or a drop-in replacement) that is used to extract doctests from the module. - The optional argument \var{setUp} specifies a set-up function for - the test suite. This is called before running the tests in each - file. The \var{setUp} function will be passed a \class{DocTest} - object. The setUp function can access the test globals as the - \var{globs} attribute of the test passed. - - The optional argument \var{tearDown} specifies a tear-down function - for the test suite. This is called after running the tests in each - file. The \var{tearDown} function will be passed a \class{DocTest} - object. The setUp function can access the test globals as the - \var{globs} attribute of the test passed. - - The optional argument \var{optionflags} specifies the default - doctest options for the tests. It is created by or-ing together - individual option flags. + Optional arguments \var{setUp}, \var{tearDown}, and \var{optionflags} + are the same as for function \function{DocFileSuite()} above. \versionadded{2.3} \versionchanged[The parameters \var{globs}, \var{extraglobs}, \var{test_finder}, \var{setUp}, \var{tearDown}, and - \var{optionflags} were added]{2.4} - \versionchanged[This function now uses the same search technique as - \function{testmod()}.]{2.4} + \var{optionflags} were added; this function now uses the same search + technique as \function{testmod()}]{2.4} \end{funcdesc} \subsection{Advanced API\label{doctest-advanced-api}} The basic API is a simple wrapper that's intended to make doctest easy -to use. It is fairly flexible, and should meet most user's needs; -however, if you require more fine grained control over testing, or +to use. It is fairly flexible, and should meet most users' needs; +however, if you require more fine-grained control over testing, or wish to extend doctest's capabilities, then you should use the advanced API.

1 0

python/dist/src/Lib doctest.py,1.109,1.110
by tim_one＠users.sourceforge.net Sept. 25, 2004

Sept. 25, 2004

Update of /cvsroot/python/python/dist/src/Lib In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv30047/lib Modified Files: doctest.py Log Message: Removed most of the module docstring. There's too much to explain now, and the LaTeX docs are in increasingly good shape. Index: doctest.py =================================================================== RCS file: /cvsroot/python/python/dist/src/Lib/doctest.py,v retrieving revision 1.109 retrieving revision 1.110 diff -u -d -r1.109 -r1.110 --- doctest.py 21 Sep 2004 03:24:24 -0000 1.109 +++ doctest.py 25 Sep 2004 02:41:28 -0000 1.110 @@ -8,13 +8,11 @@ r"""Module doctest -- a framework for running examples in docstrings. -NORMAL USAGE - In simplest use, end each module M to be tested with: def _test(): import doctest - return doctest.testmod() + doctest.testmod() if __name__ == "__main__": _test() @@ -40,133 +38,13 @@ it by passing "verbose=False". In either of those cases, sys.argv is not examined by testmod. -In any case, testmod returns a 2-tuple of ints (f, t), where f is the -number of docstring examples that failed and t is the total number of -docstring examples attempted. - There are a variety of other ways to run doctests, including integration with the unittest framework, and support for running non-Python text files containing doctests. There are also many ways to override parts of doctest's default behaviors. See the Library Reference Manual for details. - - -WHICH DOCSTRINGS ARE EXAMINED? - -+ M.__doc__. - -+ f.__doc__ for all functions f in M.__dict__.values(), except those - defined in other modules. - -+ C.__doc__ for all classes C in M.__dict__.values(), except those - defined in other modules. - -+ If 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 M.__test__ - are searched, and strings are searched directly as if they were docstrings. - In output, a key K in M.__test__ appears with name - <name of M>.__test__.K - -Any classes found are recursively searched similarly, to test docstrings in -their contained methods and nested classes. - - -WHAT'S THE EXECUTION CONTEXT? - -By default, each time testmod finds a docstring to test, it uses a *copy* -of M's globals (so that running tests on a module doesn't change the -module's real globals, and so that one test in M can't leave behind crumbs -that accidentally allow another test to work). This means examples can -freely use any names defined at top-level in M. It also means that sloppy -imports (see above) can cause examples in external docstrings to use -globals inappropriate for them. - -You can force use of your own dict as the execution context by passing -"globs=your_dict" to testmod instead. Presumably this would be a copy of -M.__dict__ merged with the globals from other imported modules. - - -WHAT ABOUT EXCEPTIONS? - -No problem, as long as the only output generated by the example is the -traceback itself. For example: - - >>> [1, 2, 3].remove(42) - Traceback (most recent call last): - File "<stdin>", line 1, in ? - ValueError: list.remove(x): x not in list - >>> - -Note that only the exception type and value are compared. - - -SO WHAT DOES A DOCTEST EXAMPLE LOOK LIKE ALREADY!? - -Oh ya. It's easy! In most cases a copy-and-paste of an interactive -console session works fine -- just make sure the leading whitespace is -rigidly consistent (you can mix 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). - - >>> # comments are ignored - >>> x = 12 - >>> x - 12 - >>> if x == 13: - ... print "yes" - ... else: - ... print "no" - ... print "NO" - ... print "NO!!!" - ... - no - NO - NO!!! - >>> - -Any expected output must immediately follow the final ">>>" or "..." line -containing the code, and the expected output (if any) extends to the next -">>>" or all-whitespace line. That's it. - -Bummers: - -+ Output to stdout is captured, but not output to stderr (exception - tracebacks are captured via a different means). - -+ If you continue a line via backslashing in an interactive session, - or for any other reason use a backslash, you should use a raw - docstring, which will preserve your backslahses exactly as you type - them: - - >>> def f(x): - ... r'''Backslashes in a raw docstring: m\n''' - >>> print f.__doc__ - Backslashes in a raw docstring: m\n - - Otherwise, the backslash will be interpreted as part of the string. - E.g., the "\n" above would be interpreted as a newline character. - Alternatively, you can double each backslash in the doctest version - (and not use a raw string): - - >>> def f(x): - ... '''Backslashes in a raw docstring: m\\n''' - >>> print f.__doc__ - Backslashes in a raw docstring: m\n - -The starting column doesn't matter: - ->>> assert "Easy!" - >>> import math - >>> math.floor(1.9) - 1.0 - -and as many leading whitespace characters are stripped from the expected -output as appeared in the initial ">>>" line that triggered it. - -If you execute this very file, the examples above will be found and -executed. """ + __docformat__ = 'reStructuredText en' __all__ = [

1 0

python/dist/src/Doc/lib libdoctest.tex,1.49,1.50
by tim_one＠users.sourceforge.net Sept. 25, 2004

Sept. 25, 2004

Update of /cvsroot/python/python/dist/src/Doc/lib In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv22822/Doc/lib Modified Files: libdoctest.tex Log Message: Repaired mistakes in the descriptions of testmod()/testfile(), and squashed massive duplication of common argument descriptions. Index: libdoctest.tex =================================================================== RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v retrieving revision 1.49 retrieving revision 1.50 diff -u -d -r1.49 -r1.50 --- libdoctest.tex 25 Sep 2004 01:30:16 -0000 1.49 +++ libdoctest.tex 25 Sep 2004 01:51:49 -0000 1.50 @@ -790,7 +790,7 @@ 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 @@ \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 @@ 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 @@ 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 @@ 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 @@ 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 @@ \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}

1 0

python/dist/src/Misc vimrc,1.2,1.3
by bcannon＠users.sourceforge.net Sept. 25, 2004

Sept. 25, 2004

Update of /cvsroot/python/python/dist/src/Misc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv20650/Misc Modified Files: vimrc Log Message: Add warning notation about using 'bomb' setting. Index: vimrc =================================================================== RCS file: /cvsroot/python/python/dist/src/Misc/vimrc,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- vimrc 20 Sep 2004 22:33:21 -0000 1.2 +++ vimrc 25 Sep 2004 01:39:56 -0000 1.3 @@ -67,7 +67,9 @@ " Set the default file encoding to UTF-8: ``set encoding=utf-8`` " Put a marker at the beginning of the file to differentiate between UTF and -" UCS encoding: ``set bomb`` +" UCS encoding (warning: always done when reasonable, which can mess up shells +" into thinking a text file is actually a binary file when executing the text +" file): ``set bomb`` " For full syntax highlighting: "``let python_highlight_all=1``

1 0

python/dist/src/Objects object.c,2.223,2.224
by bcannon＠users.sourceforge.net Sept. 25, 2004

Sept. 25, 2004

Update of /cvsroot/python/python/dist/src/Objects In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv20010/Objects Modified Files: object.c Log Message: Remove 'extern' declaration for _Py_SwappedOp. Index: object.c =================================================================== RCS file: /cvsroot/python/python/dist/src/Objects/object.c,v retrieving revision 2.223 retrieving revision 2.224 diff -u -d -r2.223 -r2.224 --- object.c 23 Sep 2004 02:39:37 -0000 2.223 +++ object.c 25 Sep 2004 01:37:24 -0000 2.224 @@ -476,7 +476,7 @@ ? (t)->tp_richcompare : NULL) /* Map rich comparison operators to their swapped version, e.g. LT --> GT */ -extern int _Py_SwappedOp[] = {Py_GT, Py_GE, Py_EQ, Py_NE, Py_LT, Py_LE}; +int _Py_SwappedOp[] = {Py_GT, Py_GE, Py_EQ, Py_NE, Py_LT, Py_LE}; /* Try a genuine rich comparison, returning an object. Return: NULL for exception;

1 0

python/dist/src/Doc/lib libdoctest.tex,1.48,1.49
by tim_one＠users.sourceforge.net Sept. 25, 2004

Sept. 25, 2004

Update of /cvsroot/python/python/dist/src/Doc/lib In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19010/Doc/lib Modified Files: libdoctest.tex Log Message: Since the doctest warnings section was reduced to one bullet point, get rid of the itemize structure. Index: libdoctest.tex =================================================================== RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v retrieving revision 1.48 retrieving revision 1.49 diff -u -d -r1.48 -r1.49 --- libdoctest.tex 25 Sep 2004 01:22:29 -0000 1.48 +++ libdoctest.tex 25 Sep 2004 01:30:16 -0000 1.49 @@ -712,14 +712,12 @@ \subsubsection{Warnings\label{doctest-warnings}} -\begin{itemize} - -\item \module{doctest} is serious about requiring exact matches in expected - output. If even a single character doesn't match, the test fails. This - will probably surprise you a few times, as you learn exactly what Python - does and doesn't guarantee about output. For example, when printing a - dict, Python doesn't guarantee that the key-value pairs will be printed - in any particular order, so a test like +\module{doctest} is serious about requiring exact matches in expected +output. If even a single character doesn't match, the test fails. This +will probably surprise you a few times, as you learn exactly what Python +does and doesn't guarantee about output. For example, when printing a +dict, Python doesn't guarantee that the key-value pairs will be printed +in any particular order, so a test like % Hey! What happened to Monty Python examples? % Tim: ask Guido -- it's his example! @@ -788,8 +786,6 @@ Simple fractions are also easier for people to understand, and that makes for better documentation. -\end{itemize} - \subsection{Basic API\label{doctest-basic-api}} The functions \function{testmod()} and \function{testfile()} provide a

1 0

python/dist/src/Doc/lib libdoctest.tex,1.47,1.48
by tim_one＠users.sourceforge.net Sept. 25, 2004

Sept. 25, 2004

Update of /cvsroot/python/python/dist/src/Doc/lib In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv17874/Doc/lib Modified Files: libdoctest.tex Log Message: In the "doctest warnings" section, removed obsolete info, and noted that ELLIPSIS can be used to deal with examples that embed object addresses. Index: libdoctest.tex =================================================================== RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v retrieving revision 1.47 retrieving revision 1.48 diff -u -d -r1.47 -r1.48 --- libdoctest.tex 25 Sep 2004 00:49:53 -0000 1.47 +++ libdoctest.tex 25 Sep 2004 01:22:29 -0000 1.48 @@ -365,8 +365,8 @@ \end{verbatim} Otherwise, the backslash will be interpreted as part of the string. - E.g., the "{\textbackslash}" above would be interpreted as a newline - character. Alternatively, you can double each backslash in the + For example, the "{\textbackslash}" above would be interpreted as a + newline character. Alternatively, you can double each backslash in the doctest version (and not use a raw string): \begin{verbatim} @@ -497,8 +497,9 @@ \end{itemize} -\versionchanged[The ability to handle a multi-line exception detail - was added]{2.4} +\versionchanged[The ability to handle a multi-line exception detail, + and the \constant{IGNORE_EXCEPTION_DETAIL} doctest option, + were added]{2.4} \subsubsection{Option Flags and Directives\label{doctest-options}} @@ -750,6 +751,17 @@ \begin{verbatim} >>> id(1.0) # certain to fail some of the time 7948648 +>>> class C: pass +>>> C() # the default repr() for instances embeds an address +<__main__.C instance at 0x00AC18F0> +\end{verbatim} + +The \constant{ELLIPSIS} directive gives a nice approach for the last +example: + +\begin{verbatim} +>>> C() #doctest: +ELLIPSIS +<__main__.C instance at 0x...> \end{verbatim} Floating-point numbers are also subject to small output variations across @@ -776,34 +788,6 @@ Simple fractions are also easier for people to understand, and that makes for better documentation. -\item Be careful if you have code that must only execute once. - -If you have module-level code that must only execute once, a more foolproof -definition of \function{_test()} is - -% [XX] How is this safer?? The only difference I see is that this -% imports (but doesn't use) sys. -edloper -\begin{verbatim} -def _test(): - import doctest, sys - doctest.testmod() -\end{verbatim} - -\item WYSIWYG isn't always the case, starting in Python 2.3. The - string form of boolean results changed from \code{'0'} and - \code{'1'} to \code{'False'} and \code{'True'} in Python 2.3. - This makes it clumsy to write a doctest showing boolean results that - passes under multiple versions of Python. In Python 2.3, by default, - and as a special case, if an expected output block consists solely - of \code{'0'} and the actual output block consists solely of - \code{'False'}, that's accepted as an exact match, and similarly for - \code{'1'} versus \code{'True'}. This behavior can be turned off by - passing the new (in 2.3) module constant - \constant{DONT_ACCEPT_TRUE_FOR_1} as the value of \function{testmod()}'s - new (in 2.3) optional \var{optionflags} argument. Some years after - the integer spellings of booleans are history, this hack will - probably be removed again. - \end{itemize} \subsection{Basic API\label{doctest-basic-api}}

1 0